Demo Recording with VHS — replay-first pipeline

Record CLI demos using charmbracelet/vhs. Each demo lives in its own dated-slug folder docs/demos/YYYYMMDD-<slug>/. The pipeline is replay-first: captured stdouts are saved once on a live host, then a YAML spec drives tape generation, recording, and narration. Iteration is fast and timing is deterministic.

Pipeline

              (one-time, slow)
   scenes.yaml + live host  -->  outputs/*.txt       [capture phase]
                                          |
              (instant)                   v
   scenes.yaml  +  outputs/*.txt  -->  compile.py  -->  tape.tape + helpers.sh + compiled.json
                                          |
              (~2 min)                    v
                                       vhs tape.tape  -->  recording.mp4
                                          |
              (~30s, cached per text)     v
                                       narrate.py compiled.json  -->  voice/*.mp3 + recording-narrated.mp4
                                          |
              (manual)                    v
                                       upload to YouTube

compile.py, vhs, and narrate.py are all idempotent and fast. The slow step is the initial capture; everything downstream re-runs in seconds.

Output Layout

All .mp4 files under docs/demos/ are gitignored; voice/ directories under any demo are gitignored.

Arguments

• <scenario-name>: Slug for the demo (e.g. agent-lifecycle). Must match ^[a-zA-Z0-9_-]+$. The skill prefixes today's date in YYYYMMDD form to produce docs/demos/YYYYMMDD-<scenario-name>/.
• --description: Optional one-liner of what the demo should show.

Required Up-Front Questions

MANDATORY: Before scaffolding any file, ask the user the following via AskUserQuestion. Do not assume defaults.

1. Output format
   • MP4 (.mp4) — recommended; YouTube uploads, social, video containers.
   • GIF (.gif) — README/docs embeds. Smaller, no audio.
2. Scene plan — ordered list of scene titles + commands. Scene 1 is fixed as clawctl --version; ask only for Scene 2 onward.
3. Long-output handling per scene — for any scene whose command produces tens or hundreds of lines (Ansible installs, etc.), confirm whether to head N + tail M elide the middle. The narration covers the gap.
4. Any other unclear input — never invent prerequisites.

Universal Flow

Step 1 — Run the prereq validator

bash "$(git rev-parse --show-toplevel)/.claude/skills/create-vhs/scripts/check-prereqs.sh"

Checks vhs, ttyd, ffmpeg, clawctl. Stop immediately if any are missing.

Step 2 — Author scenes.yaml

Copy .claude/skills/create-vhs/templates/scenes.yaml.template to docs/demos/YYYYMMDD-<scenario-name>/scenes.yaml and fill in title, subtitle, intro/outro narration, and the scene list.

Fixed Scene 1: clawctl --version. Leave it in place. It anchors the recording to a known release.

For long scenes use head: and tail: to elide the middle on screen — narration covers the elision.

Get explicit user approval on scenes.yaml before capturing outputs.

Step 3 — Capture stdouts (one-time, on a live host)

For each scene with mode: replay (default), run the real command once and save its stdout into the demo's outputs/ folder:

NAME=YYYYMMDD-<scenario-name>
mkdir -p docs/demos/$NAME/outputs

clawctl --version                 | tee docs/demos/$NAME/outputs/01-version.txt
clawctl service init              | tee docs/demos/$NAME/outputs/02-service-init.txt
# ... one per scene ...

Mask non-deterministic values (timestamps, UUIDs, IPs, private hostnames) before committing the capture files. A scripted sed pass is fine:

sed -i -E 's/[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9:.+-]+/2026-01-01T00:00:00Z/g' docs/demos/$NAME/outputs/*.txt

Re-capture cadence: per release tag, after Rich table changes, or whenever the CLI's output shape shifts.

Step 4 — Compile

uv run docs/demos/lib/compile.py docs/demos/YYYYMMDD-<scenario-name>

uv resolves the PEP 723 deps (pyyaml) on first run. Outputs:

• tape.tape — replay-first VHS source. Header banner says "GENERATED — DO NOT EDIT".
• helpers.sh — per-demo _SCENES/_TITLE/... + sources lib/cards.sh.
• compiled.json — flat list of every narration beat with its absolute timestamp in the rendered recording.

The script prints the recording duration estimate and a per-beat timeline. Verify these match what you expect before recording.

Step 5 — Record

export PATH="${GOPATH:-$HOME/go}/bin:$PATH"
vhs docs/demos/YYYYMMDD-<scenario-name>/tape.tape

Output lands at docs/demos/YYYYMMDD-<scenario-name>/recording.<ext> — .mp4 by default, .gif if tape.output_format: gif is set in scenes.yaml. Replay-first tapes run in roughly their on-screen duration (no live waits), so recording time ≈ recording duration.

Step 6 — Layer narration (ElevenLabs)

Skip this step for GIF demos. GIF has no audio container, so the narration beats in scenes.yaml are unused at render time. They still drive hold_seconds extension during compile so on-screen pacing matches the spoken cadence — keep them written.

One-time setup per machine:

cp docs/demos/lib/.env.example docs/demos/lib/.env
# Edit and fill in ELEVENLABS_API_KEY + ELEVENLABS_VOICE_ID.

narrate.py declares its Python deps via PEP 723. uv resolves on first invocation; no pip step.

Run:

uv run docs/demos/lib/narrate.py docs/demos/YYYYMMDD-<scenario-name>
  [--force]              # regenerate ALL clips even if cached
  [--skip-mux]           # generate audio only; skip ffmpeg
  [--input recording.mp4 --output recording-narrated.mp4]

• Reads compiled.json (not scenes.yaml — narrate.py only consumes derived artifacts).
• TTS-synthesizes each beat; clips are cached at voice/<scene>-<beat>-<sha1>.mp3. Editing a beat's text changes the sha and auto-invalidates the cache — no --regen flag needed.
• Muxes onto recording.mp4 via ffmpeg adelay + amix. Video is -c:v copy (no re-encode).

Step 7 — Iterate

Step 8 — Upload (out of skill scope)

You upload recording-narrated.mp4 (or recording.mp4 if going voiceless) to YouTube. The skill does not push.

Configuration

narrate.py honors these env vars from docs/demos/lib/.env:

Shell env vars override .env values.

VHS Commands Reference (for generated tapes)

The compile.py output is hand-readable. Commands you'll see in generated tapes:

⚠️ Never use Env with real credentials. VHS bakes the literal value into the committed tape.

Production Quality (research-backed)

• Pre-roll & post-roll: Sleep 1s (pre-roll) is auto-emitted by compile.py. Outro card has a 5s hold.
• Vary typing speed: default Set TypingSpeed 50ms is in the YAML tape.typing_speed_ms.
• Mask non-deterministic output in captured replay files. Done at capture time (Step 3).
• Long Ansible logs: use head: + tail: in scenes.yaml. Narration covers the elision.
• One demo = one fleet state. Don't combine create and remove in one tape — second half would need a different captured starting state.

Troubleshooting

File Organization

docs/demos/
├── lib/                              # committed — shared, all demos
│   ├── cards.sh                      # titlecard / outrocard / headline / progress
│   ├── compile.py                    # scenes.yaml -> tape.tape + helpers.sh + compiled.json (PEP 723; run via `uv run`)
│   ├── narrate.py                    # compiled.json -> voice/*.mp3 + recording-narrated.mp4 (PEP 723; run via `uv run`)
│   ├── .env.example                  # ElevenLabs credentials template
│   └── .env                          # GITIGNORED — real ELEVENLABS_API_KEY etc.
└── YYYYMMDD-<slug>/                  # one folder per demo
    ├── scenes.yaml                   # committed — SOURCE OF TRUTH
    ├── outputs/                      # committed — per-scene captures
    │   ├── 01-version.txt
    │   └── 02-….txt
    ├── tape.tape                     # committed (generated) — VHS source
    ├── helpers.sh                    # committed (generated) — per-demo vars + source lib/cards.sh
    ├── compiled.json                 # committed (generated) — narration timeline
    ├── voice/                        # GITIGNORED — per-beat TTS clips
    │   └── scene-NN-beat-MM-<sha8>.mp3
    ├── recording.mp4                 # GITIGNORED — output of `vhs tape.tape`
    └── recording-narrated.mp4        # GITIGNORED — recording with voiceover

References

External best-practice sources consulted for this skill:

• charmbracelet/vhs README
• VHS canonical demo.tape
• Tips and tricks from VHS tapes (gist)
• ElevenLabs Python SDK
• Automated YouTube dubbing with ElevenLabs + ffmpeg
• PEP 723 — inline script metadata

Prompt Logging

REQUIRED: Append prompt log to .itx/<N>/03_DEMO.md if recording as part of an issue.

See AGENTS.md for format specification.