Communitygithub.com

demo-narrator

Turn a silent product demo or screen recording into a narrated video with a natural human-sounding voiceover, clean UI sound effects (whooshes, pops, clicks, dings), optional background music, and subtitles (burned in or .srt). Includes a script approval step before any audio is generated. 100% local and free — FFmpeg, Kokoro-82M TTS (Piper fallback), numpy/scipy for SFX and music; no API keys or paid services. Use when the user wants to add narration, voiceover, captions/subtitles, or sound effects to a demo video, screen recording, walkthrough, or product clip (.mp4/.mov/.webm/.mkv).

What is demo-narrator?

demo-narrator is a Claude Code agent skill that turn a silent product demo or screen recording into a narrated video with a natural human-sounding voiceover, clean UI sound effects (whooshes, pops, clicks, dings), optional background music, and subtitles (burned in or .srt). Includes a script approval step before any audio is generated. 100% local and free — FFmpeg, Kokoro-82M TTS (Piper fallback), numpy/scipy for SFX and music; no API keys or paid services. Use when the user wants to add narration, voiceover, captions/subtitles, or sound effects to a demo video, screen recording, walkthrough, or product clip (.mp4/.mov/.webm/.mkv).

Works with✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/GarvitSolanki/audio-generator/tree/main/skills/demo-narrator

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

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

  1. If $PY does 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, run bash "$SKILL/setup.sh" (takes a few minutes; run it in the background).
  2. Pick a work dir next to the video: WORK="<video dir>/demo-narrator-work/<video stem>". Never write into the skill dir.
  3. 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-duration to override; use --interval 4 for long videos).
  • Review $WORK/sheets/*.jpg first (each labelled with timestamps). Open individual $WORK/frames/*.jpg only 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.5 words (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 start to 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.

  • whoosh on page/screen transitions (use scene_changes), whoosh_soft for panels/modals sliding, pop for elements/toasts appearing, click for key button presses, ding for 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.

  1. Present the script as a table and stop:

    #TimeWords / budgetNarrationSFX
    10:00.4–0:04.611 / 10 ⚠Meet Relay, …—

    Flag segments over budget with ⚠. Mention voice + total narration length. End with: "Approve this script, or tell me what to change."

  2. End your turn and wait. Silence, "looks fine?", or approval of an earlier draft is not approval of this one.

  3. On edits: update script.json, re-present the changed rows, wait again.

  4. 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" --approve
    

    The stamp is a digest of the narration text. generate_tts.py and render_video.py refuse to run on an unstamped script or if any text changed after stamping — you must go back through this gate. Never set approved/approved_digest by hand. Timing (start/end) and sfx edits 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 piper to 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 moving start/end or 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-preserving atempo squeeze (≤ 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.mp4 and subtitles.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 N for a variation). Make 30–40 s previews with --duration 40 and let the user pick by ear before rendering everything, then render with --bgm "$WORK/bgm.wav". --bgm also 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 writes subtitles.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

  1. Check the render printout: drift column ~0, no hold-frame warning (or explain it).
  2. 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-scale or tell the user.
  3. 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

SymptomFix
kokoro unavailable … trying fallbackRun setup.sh again; check Python is 3.10–3.12 in .venv. Piper output is fine but less natural.
Mispronounced word / nameRespell phonetically in text (e.g. "Kubernetes" → "koo-ber-net-eez"), get approval, regenerate that segment with --only.
Voice feels rushedLower speed to 0.95, widen segment windows, or trim words.
Subtitles too small/large--font-scale 0.035–0.06.
Wrong colors / VFR stutterAdd --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.

Related Skills