vhs-video

name	vhs-video
description	VHS tape syntax and ffmpeg video handling in readme2demo — how the demo video is generated, the hard-won gotchas, and the duration gate. Use when touching templates/demo.tape.j2, render.py, distill.tape_from_guide, or when a video is short, blank, mis-paced, or fails to render.

VHS tapes & video

The demo video is built from the FINAL step_by_step.md (render stage, after tutorial finalizes the guide) so the video follows the published guide step-for-step. distill.tape_from_guide parses the guide's fenced bash blocks into TapeCommands; templates/demo.tape.j2 renders the tape; render.py runs VHS in the base image.

Non-negotiable tape rules (each is a scar)

• Never use Wait+Screen on output text. It matches only the VISIBLE buffer; any pattern in longer-than-one-screen output scrolls off and times the render out. Pace with Wait (blocks until the shell prompt returns, so the command — build included — has finished) then a short Sleep to read.
• VHS string literals have NO backslash escapes. vhs_quote picks a delimiter the text doesn't contain: " → ` → '. A string with all three can't be typed (rare; that step is skipped).
• Type is single-line. Multi-line commands (heredocs) are typed LINE-BY-LINE via TapeCommand.lines (Type/Enter per line) so file creation plays on camera — a real shell reads a heredoc until its terminator.
• Framerate 24, Output demo.mp4 only. A GIF per-frame render of a multi-minute tape once filled the Docker VM disk. demo.gif is a short downscaled ffmpeg preview cut from the mp4 afterwards (best-effort, never gates the stage).
• Hidden preamble cd /work && clear so the guide's own git clone ... . starts from the empty workspace.

Duration gate (render.validate_outputs)

expected_min_duration_s sums the tape's Sleeps + typing time; real command execution (the Waits) only adds on top. A video shorter than ~0.8× that bound means steps didn't play (stale image, aborted tape) → HARD error, never a silently short clip. Bounds: 5s..1500s.

Coverage

render writes tape_coverage.json (guide_steps / tape_steps / dropped) and prints any dropped step. With heredocs now on camera, a dropped step means a genuinely ungrounded guide command — investigate, don't ignore.

ffmpeg

Used for the gif preview (fps=10,scale=800) and, on the host, ffprobe for the duration check. Both run inside the base image for the preview; the host ffprobe check is skipped when ffprobe isn't on PATH.