Skip to main content

agent-demo-video

Turn a script and a running web app into a finished, narrated, captioned demo video. Automated, headless, zero-drift.

Open source (MIT) · On npm · Headless · Keyless dry-run · Audio-first sync by construction.

The problem

Demo videos are made by hand: screen-record, write a script, record a voiceover, edit, then re-sync captions, and redo the whole thing every time the UI changes. Narration, screen, and captions drift apart, and nothing about it is reproducible or CI-friendly.

A headless pipeline that turns a Markdown DEMO_SCRIPT (shots, browser actions, and narration) plus a running web app into a finished MP4. It is audio-first: narration is synthesised first, and its exact per-character timing becomes the clock that paces the browser recording and the captions, so audio, video, and captions are in sync by construction with zero drift. It can drive an authenticated SaaS app behind its real login (Slack, Notion, Linear, Stripe, any Google-SSO app), or splice in a prebaked clip for surfaces you would rather not automate. Run it keyless with FAKE_TTS to iterate on the script before spending any API quota.

Quickstart

Install from npm, prove your script keyless in one dry run, then add a voice. Everything runs on your machine: there is no hosted service. Needs Node 18+ and ffmpeg on PATH.

Install (Node 18+, plus ffmpeg on PATH):

npm install -g agent-demo-video
npx playwright install chromium

Command surface

  • goto: Navigate the recording browser to a URL (relative to the dashboard base, or absolute).
  • click: Move the on-screen cursor to a selector and click it, with a visible click ripple.
  • type: Type text into a field character-by-character, like a real user.
  • hover: Hover a selector to reveal hover-only states before capturing them.
  • highlight: Draw an attention box around an element to direct the viewer’s eye.
  • chapter: Show a lower-third chapter banner to title a section of the walkthrough.
  • wait: Dwell for N milliseconds, e.g. while an async backend action finishes on screen.

Why it is different

  • Audio-first, zero-drift: Narration is synthesised first; its exact per-character timing becomes the clock that paces both the screen recording and the caption file. Audio, video, and captions are in sync by construction, not nudged into alignment afterwards.
  • Authenticated SaaS, captured safely: Drive a login-walled app (Slack, Notion, Linear, Stripe, any Google-SSO app) behind its real session. Operator-confirm login absorbs MFA and SSO, and a record-time guard fails closed rather than silently recording a logged-out screen. The saved browser profile holds secrets at rest, so it lives outside the repo and is never committed.
  • Keyless dry run: FAKE_TTS swaps the TTS step for a silent track of estimated duration, so you can iterate on the script and action sequence, with real browser capture and real captions, without spending a cent of API quota.
  • Headless and reproducible: Playwright drives a headless Chromium with an injected fake cursor and overlays; ffmpeg does the rest. The whole render is one command, so it runs the same on your laptop and in CI: re-render on every UI change instead of re-recording by hand. A parity check fails the render if shot count, segment count, or audio/video duration disagree.

Links