Narrated walkthrough: in-page play mode + opt-in MP4 export

[russ]

What & why

Turns a PatchStory walkthrough into a narrated screencast that breaks down the code being reviewed — inspired by this AI-video-generation pipeline, but built to fit PatchStory's local-first, zero-dependency model. The walkthrough's chapters already are the script (intent, risk, the referenced diff hunks), so this mostly adds a player and an exporter over data that already exists.

Two layers:

1. In-page "play" mode (the default — stays zero-dependency)

A ▶ Play button turns the static .html into a self-playing screencast: each chapter becomes a scene that pans the actual diff and spotlights the lines it references, while the browser's built-in speech synthesis reads a short narration (captions included, so it works muted). No ffmpeg, no API key, no network — the same single .html, just playing itself.

• New optional Chapter.narration field (falls back to intent → summary, so existing walkthroughs still play).
• Player overlay: requestAnimationFrame scene clock, speech + auto-advance, transport controls, diff spotlight/dim, keyboard (space/←/→/m/Esc), header Play button and p shortcut.
• Themed via the existing light/dark CSS vars; prefers-reduced-motion fallback.

2. patchstory video (opt-in MP4 export)

For when you need a real shareable file. Same scene model, rendered to an .mp4 using system tools (no npm runtime deps; only touched when you ask for a video):

patchstory video pr-walkthrough.json --diff pr.diff --redact -o walkthrough.mp4

Per scene: deterministic scene HTML (fixed header/caption bands) → headless-Chromium screenshot → TTS → ffmpeg slices the screenshot into a fixed header, a vertically-panning code region, and a fixed caption, then muxes audio. Clips are concatenated to the final MP4.

• ffmpeg/ffprobe resolved by actually running candidates (PATH → /usr/bin → PATCHSTORY_FFMPEG/FFPROBE), so a broken/shadowing PATH entry is skipped.
• Chromium via --chrome, PATCHSTORY_CHROME, or a flatpak Chromium.
• TTS via --tts: elevenlabs (ELEVENLABS_API_KEY), or local espeak-ng/flite/say, or none (silent; captions still shown).

Verification

• typecheck clean · build clean · 23/23 tests pass.
• Play mode driven in headless Chromium (overlay mounts, scenes render/advance, end card). That run caught and fixed a real bug: a TTS onerror was instantly skipping scenes instead of falling back to the timed clock.
• patchstory video produces a valid 1920×1080 H.264 + AAC, ~133s MP4 from a 5-chapter walkthrough; sampled frames confirm the title card, panning syntax-highlighted diff with spotlit lines, and burned-in captions.

Notes

• Web Speech API voice quality varies by OS/browser — the tradeoff for keeping play mode zero-dependency.
• The MP4 path is heavier/slower by design; the HTML play mode is the local-first default.

🤖 Generated with Claude Code