puntorigen/avatar-skills / cuento-reel
cuento-reel
VerifiedProduce a "cuento" (story) reel where each avatar is a CHARACTER in a narrated tale (Narnia-style), not a single presenter talking to camera. An unseen storyteller NARRATOR (voice-only, older "cuentacuentos"/grandfatherly cloned voice) carries the story in third person, while invented character avatars ACT: silent animated action beats (broll-story / seedance image-to-video) under the narrator's voice-over, and key lines delivered as real lip-synced p-video-avatar clips (avatar-talking-video) woven in as guest scenes. Orchestrates avatar-invent, broll-story, audio-theater, avatar-talking-video and avatar-reel-composer (assemble_narration + compose_reel). Use when the user wants a story/cuento reel, to "contar una historia / cuento" with characters and a narrator, to adapt a tale (fairy tale, public-domain classic, etc.) into a narrated multi-character reel, or to make another episode in a cuento series like narnia/.
| File | Kind | Size |
|---|---|---|
| REFERENCE.md | markdown | 4.8 KB |
| SKILL.md | skill md | 9.9 KB |
| templates/dialog.script.json | config | 939 B |
| templates/episodio.script.md | markdown | 1.2 KB |
| templates/narrador.voice_brief.json | config | 1.3 KB |
| templates/plan.example.json | config | 1.6 KB |
| templates/serie.pauta.md | markdown | 2.8 KB |
| templates/storyboard.example.json | config | 1.9 KB |
REFERENCE.md
View on GitHub# Cuento Reel — reference
Detailed schemas, the A/V-sync QA check, and troubleshooting. The plan and
storyboard schemas are owned by `avatar-reel-composer` — see its `SKILL.md`
(sections *Storyboard schema* and *Guest / cameo scenes*). This file only adds
the cuento-specific conventions and the lessons baked into the hard rules.
## Why the hard rules exist
### Boundaries pin to assemble offsets (frame-exact A/V)
`compute_boundaries` in `compose_reel.py` snaps cuts to whisper word timings,
which is only approximate. For a multi-segment narration that drift inflates the
narration-scene slots and runs the PICTURE ahead of the AUDIO (≈1s by mid-reel) —
the dialogue then looks out of lip-sync. Fix (already in the composer): when the
master narration came from `assemble_narration` with a **1:1 scene↔segment**
correspondence, it pins EVERY scene boundary to the exact recorded segment
offsets (`assemble_narration.out.json`). So:
- keep `storyboard.scenes` in the SAME order as `plan.segments`, one-to-one;
- use `gap: 0` so each scene's clip equals its audio segment exactly.
### gap = 0
With `gap>0` the audio slot of a guest = `audio_dur + gap`, but the lip-sync clip
is only `audio_dur` long → it falls short by `gap` and everything after drifts.
`compose_reel` prints a warning if it pins offsets while the plan used `gap>0`.
### motion = none (no Ken Burns)
A static frame with a push/zoom reads as fake. Animate the still into real motion
(seedance image-to-video) instead, and set `motion:"none"`. Never put `emphasis`
on a `guest` scene — emphasis bumps motion and would re-introduce a push-in.
### Lip-sync clip A/V (avoid cumulative drift)
A talking clip whose AUDIO stream is slightly longer than its VIDEO stream makes
the composer trim the video short → cumulative drift. If you hand-build clips,
re-mux so audio ≤ video:
```bash
ffmpeg -i in.mp4 -map 0:v:0 -map 0:a:0 -c:v copy -c:a aac -shortest out.mp4
```
## A/V-sync QA check (do this after compose)
Confirm a character cut lands where its line ends (not before/after):
```bash
# read the exact segment end from assemble (e.g. d_eus_5 end = 54.96)
# extract frames around it and compare picture vs the burned subtitle/audio
cd <libro>/<NN_slug>
for t in 54.6 54.8 55.0 55.2; do ffmpeg -y -ss $t -i final.mp4 -frames:v 1 _qa_$t.png -loglevel error; done
```
The frame just BEFORE the boundary should still show the speaking character on
their last word; the frame just AFTER should be the next scene. If the next scene
appears EARLY (while the subtitle is still on the previous line), the picture is
running ahead — re-check `gap:0` and the 1:1 scene/segment order.
Optional: detect big visual cuts and compare to expected boundaries:
```bash
ffmpeg -i final.mp4 -vf "select='gt(scene,0.4)',showinfo" -an -f null - 2>&1 \
| grep -oE "pts_time:[0-9.]+"
```
## Dialogue clip paths (two options)
- **Own MiniMax voice** → plan `kind:"guest"` (composer auto-generates the clip
to `<char>/generated-videos/guest_<slug>.mp4`).
- **Specific non-MiniMax voice** (youthful/child voices ElevenLabs blocks):
`audio-theater` → line `.wav`; lip-sync with `avatar-talking-video --audio`
onto the character face → clip `.mp4`. Reference that clip as plan
`kind:"audio"` (`file` = .mp4) AND a storyboard `guest` scene (`broll_clip` =
same .mp4). Re-mux audio≤video (above) if you see drift.
## Troubleshooting
- **`ip_detected` / blocked in seedance** with photoreal faces → push wording to
"cinematic realism" (not a clone of a real person); keep invented side-characters
stylized to match; re-run. Wide shots / silhouettes / body language pass more
often than distressed child close-ups.
- **Mouth moving on a narration beat** (the character is silent under VO) → in the
seedance prompt demand the mouth stays SHUT the entire time ("lips pressed
gently together; never opens the mouth; no jaw/lip movement"); add a downward or
away gaze so only eyes/head/hair move.
- **Narrator sounds flat** → set `voice.emotion` and drop sparse MiniMax
interjections (`(sighs)`) / pauses `<#0.6#>` into the narrator text (ignored by
captions/alignment).
- **Face drifts between clips** → anchor `refs/<char>_hero_master.png` and repeat
the character DNA verbatim in every broll sheet.
- **higgsfield `Session expired` / out of credits** → `higgsfield auth login` /
top up; the broll sheet is cached (pass `--sheet` to skip image gen).
## Copyright
Copyright protects expression, not ideas. For a copyrighted source, write 100%
original narration + dialogue inspired by the plot — never reproduce or closely
paraphrase the prose, structure or distinctive wording. Public-domain tales are
free, but modern translations may carry their own copyright; adapt in your own
words. Keep an internal rights note in the series pauta and treat published output
as needing a rights review.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |