Demo Narrator
Pipeline: frames → understand → draft script → USER APPROVAL GATE → SFX + TTS → render → verify.
Output: output_final.mp4 (H.264/AAC, −16 LUFS, subtitles burned in) + subtitles.srt.
SKILL="<absolute path of the directory containing this SKILL.md>" # e.g. ~/.claude/skills/demo-narrator or ./.claude/skills/demo-narrator
PY="$SKILL/.venv/bin/python"
Resolve SKILL once at the start (it depends on where the skill was installed) and use absolute paths from then on.
0. Preflight
- If
$PYdoes not exist, tell the user setup installs ffmpeg + espeak-ng (Homebrew/apt), a Python 3.12 venv, PyTorch, and ~400 MB of free model weights; on a yes, runbash "$SKILL/setup.sh"(takes a few minutes; run it in the background). - Pick a work dir next to the video:
WORK="<video dir>/demo-narrator-work/<video stem>". Never write into the skill dir. - Ask (one message, only what is unknown): product name + what it does, audience, tone (default: friendly, confident, concise), voice preference (default
af_heart), and anything that must be said (CTA, URL). Don't block on this if the user already said "just do it" — infer from the frames.
1. Extract frames + check duration
"$PY" "$SKILL/scripts/extract_frames.py" "<video>" --out "$WORK"
- Prints duration/resolution, samples 1 frame / 2 s, detects scene changes, builds 3×3 contact sheets.
- Refuses videos < 3 s or > 15 min (
--force/--max-durationto override; use--interval 4for long videos). - Review
$WORK/sheets/*.jpgfirst (each labelled with timestamps). Open individual$WORK/frames/*.jpgonly where you need detail (small UI text, exact moment a click lands). $WORK/frames.json→duration,scene_changes(best places for whooshes), frame list.
Build a beat list: what is on screen at each moment, which actions happen (click, type, page change, success state), and what the viewer should take away.
2. Draft $WORK/script.json
{
"video": "/abs/path/to/demo.mp4",
"voice": "af_heart",
"speed": 1.0,
"approved": false,
"segments": [
{"id": 1, "start": 0.4, "end": 4.6, "text": "Meet Relay, the fastest way to turn customer calls into tickets."},
{"id": 2, "start": 5.0, "end": 10.8, "text": "Drop in a recording, and Relay pulls out every bug, request, and follow-up for you."}
],
"sfx": [
{"name": "whoosh", "at": 4.8},
{"name": "pop", "at": 7.2, "gain_db": -12},
{"name": "ding", "at": 10.4}
]
}
Timing rules
- Word budget per segment ≈
(end − start) × 2.5words (Kokoro ≈ 150 wpm at speed 1.0). Stay under it. - Leave ≥ 0.3 s between segments; start first line at ~0.3–0.8 s; let the video breathe after big moments.
- Anchor
startto when the thing being described appears, not before. Narration can lead an action by ~0.3 s. - Segments must not exceed the video; final segment should end ≥ 1 s before the video ends.
Writing for the ear
- Conversational, second person ("you"), contractions, active verbs. One idea per segment.
- Describe the benefit of what's happening, not the pixels. Never "Here we see…" / "As you can see…".
- Spell things as they should be spoken: "two-x faster", "A-P-I" only if it should be spelled out, "dot com". Avoid symbols, emoji, URLs with slashes, and parentheses.
- Short sentences. End with a clear CTA if the user gave one.
SFX (whoosh, whoosh_soft, pop, click, ding) — at is absolute video time.
whooshon page/screen transitions (usescene_changes),whoosh_softfor panels/modals sliding,popfor elements/toasts appearing,clickfor key button presses,dingfor success/completion.- Restraint: ~1 cue per 4–6 s max. Don't stack cues within 0.3 s. Default level −9 dB under voice; set
gain_db(e.g. −14) for subtle ones.
Voices (Kokoro): af_heart (warm US female, default), af_bella, am_michael / am_fenrir (US male), bf_emma (UK female), bm_george (UK male). Other voices download once on first use.
3. ⛔ SCRIPT APPROVAL GATE — mandatory
Do not generate any audio until the user explicitly approves the script.
-
Present the script as a table and stop:
# Time Words / budget Narration SFX 1 0:00.4–0:04.6 11 / 10 ⚠ Meet Relay, … — Flag segments over budget with ⚠. Mention voice + total narration length. End with: "Approve this script, or tell me what to change."
-
End your turn and wait. Silence, "looks fine?", or approval of an earlier draft is not approval of this one.
-
On edits: update
script.json, re-present the changed rows, wait again. -
Only after an explicit yes ("approve", "yes", "go", "ship it") for the current text, stamp it:
"$PY" "$SKILL/scripts/generate_tts.py" "$WORK/script.json" --approveThe stamp is a digest of the narration text.
generate_tts.pyandrender_video.pyrefuse to run on an unstamped script or if any text changed after stamping — you must go back through this gate. Never setapproved/approved_digestby hand. Timing (start/end) andsfxedits do not need re-approval.
4. Generate SFX + voiceover
"$PY" "$SKILL/scripts/generate_sfx.py" --out "$WORK/sfx"
"$PY" "$SKILL/scripts/generate_tts.py" "$WORK/script.json"
- TTS writes
$WORK/audio/seg_###.wav+tts.json. Engine: Kokoro, auto-falling back to Piper (--engine piperto force). - Each clip is fitted to its slot (until next segment start); overruns are re-synthesized faster up to
--max-speed 1.25. - If the table still shows
OVER, prefer movingstart/endor later segments (no re-approval needed). If text must get shorter, that's a text change → back to the gate. - Re-do single segments:
--only 3 5. Different variation of SFX:--seed 7.
5. Render
"$PY" "$SKILL/scripts/render_video.py" "$WORK/script.json"
- Places clips at their
start, never overlapping; small overruns get a pitch-preservingatemposqueeze (≤ 1.12×), remainder shifts later clips (printed as drift). Holds the last frame if narration outlasts the video. - Mixes voice + SFX, loudness-normalizes to −16 LUFS, burns in subtitles (Pillow-rendered cards + FFmpeg
overlay, so no libass needed), writes$WORK/output_final.mp4andsubtitles.srt. - Optional background music (original, synthesized locally, no licensing):
"$PY" "$SKILL/scripts/generate_bgm.py" --duration <video seconds> --out "$WORK/bgm.wav"(styles:positive(default) = acoustic-guitar 16th picking with ringing open strings, warm chord stab on every beat, four-on-the-floor kick, syncopated rim/claps, off-beat bass, soft pluck lead, 111 BPM, break mid-track, modelled on a B2B demo reference;demo-bright/demo-dorian= SaaS-demo groove modelled on stock product-demo tracks: 110 BPM, warm chords pulsing on 8ths and pumping with a soft kick, claps on 2 and 4, 8th hats, bass on chord roots, a held top line, a light plucked melody, intro → groove → 8-bar break mid-track → groove → clean end;uke,marimba,pluck,kalimba= bright software-demo beds, one plucked/mallet motif over a simple soft-kick + snap/clap + shaker beat and a little bass, 100–112 BPM, major key;lofi(default) = chill swung beat with drums;keys= electric piano;upbeat= four-on-the-floor + arpeggio;ambient= pad only.--bpm,--key(bright styles),--mood(others),--seed Nfor a variation). Make 30–40 s previews with--duration 40and let the user pick by ear before rendering everything, then render with--bgm "$WORK/bgm.wav".--bgmalso takes a user-supplied track (mp3/m4a/wav): it is auto-levelled to the same reference, looped with a 2.5 s crossfade if shorter than the video, and faded out at the end. Ask the user to confirm they have the rights to any track they supply. Music auto-ducks under the voice; adjust with--bgm-db(default −2.5) and--duck-db(default −5). - Useful flags:
--out <path>,--orig-volume 0.15(keep original audio quietly),--sfx-gain-db -12,--no-subs(still writessubtitles.srt; use when the video already has on-screen captions near the bottom),--font <ttf>,--font-scale 0.05,--crf 20.
6. Verify before reporting
- Check the render printout: drift column ~0, no hold-frame warning (or explain it).
- Spot-check subtitles:
ffmpeg -ss <t> -i "$WORK/output_final.mp4" -frames:v 1 "$WORK/check_<t>.jpg"at 2–3 segment midpoints, then view the images — captions readable, not covering key UI. If they cover something important, consider--font-scaleor tell the user. - Report: output path, duration, engine/voice used, segments that were sped up or shifted, and how to tweak (edit
script.json→ re-run steps 4–5; text edits go through the gate again).
Troubleshooting
| Symptom | Fix |
|---|---|
kokoro unavailable … trying fallback | Run setup.sh again; check Python is 3.10–3.12 in .venv. Piper output is fine but less natural. |
| Mispronounced word / name | Respell phonetically in text (e.g. "Kubernetes" → "koo-ber-net-eez"), get approval, regenerate that segment with --only. |
| Voice feels rushed | Lower speed to 0.95, widen segment windows, or trim words. |
| Subtitles too small/large | --font-scale 0.035–0.06. |
| Wrong colors / VFR stutter | Add --fps 30. |
| Video has music you want to keep | --orig-volume 0.12–0.2. |
Everything runs offline after the one-time model download. Licences: Kokoro-82M Apache-2.0, Piper GPL-3.0 (piper-tts ≥1.3), voices per model card, FFmpeg LGPL/GPL.