Narrate

Overview

Narrate produces narrated walkthrough videos of a web app. You describe what should be demonstrated; it scripts the walkthrough, drives a headless browser through it, speaks each step with a text-to-speech voice, and muxes the result into a single MP4.

It runs both as a Claude Code plugin (/narrate-video <prompt>) and as a standalone CLI and library (@narrate/core).

Key Features

• Prompt to video: Describe the flow to demo; the walkthrough is scripted, recorded and narrated end to end
• Automatic audio sync: The browser is recorded in one continuous headless pass, paced to the narration, so each beat is held on screen for exactly the length of its spoken line, so there is no manual syncing step
• Works with no API key: Narration falls back to the operating system voice out of the box; Gemini and ElevenLabs are optional upgrades
• Presenter overlays: A synthetic cursor glides to each interaction, and highlights pulse on whatever the narration is describing
• Scene format: Walkthroughs are JSON scenes with a documented step vocabulary (navigation, forms, scrolling, waits, highlights), so a render is reproducible
• Authenticated flows: Captures a browser session once and reuses it, so login-gated pages can be demoed without credentials in the scene file

Technical Stack

• Language: TypeScript
• Browser automation: Playwright, auto-provisioning Chromium on first render
• Video: ffmpeg for muxing narration onto the recording
• TTS: Pluggable providers: OS voice, Gemini, or ElevenLabs
• Distribution: Claude Code plugin marketplace, plus a standalone CLI

Architecture

The design decision that matters is recording the browser in a single continuous pass rather than stitching per-step clips together.

• Scene compiler: A JSON scene describes beats, each with narration and an ordered list of browser steps
• Narration first: Speech is synthesised up front, so the exact duration of every line is known before recording starts
• Paced recording: Each beat is held on screen for its narration's measured length, which makes audio and video line up by construction instead of by editing
• Mux stage: ffmpeg trims the recording lead-in and overlays the combined narration track

Challenges & Solutions

• Audio drift: Solved structurally: synthesising narration before recording means the video is paced to the audio, rather than the audio being fitted to the video afterwards
• Zero-setup requirement: The OS voice provider means the tool works immediately with no account or key, with cloud voices as an opt-in quality upgrade
• Credentials in demos: A captured session file keeps logins out of scene files entirely, and environment placeholders cover the case where the login itself is the thing being demonstrated
• Dependency footprint: Playwright and Chromium are provisioned automatically on first use, leaving ffmpeg as the only manual prerequisite

Impact & Results

• Documentation that stays current: A walkthrough is a text scene, so re-rendering after a UI change is a single command rather than a re-recording session
• No editing step: One command produces a finished, narrated MP4
• Dual distribution: Usable conversationally inside Claude Code, or scripted in CI as a CLI
• Open source: MIT licensed