OPEN SOURCE · MIT

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 · Claude Code plugin · Headless · Keyless dry-run · Audio-first sync by construction.

View on GitHub Watch the video it made of itself

Watch agent-demo-video in action

Reused agent-demo-video v0.3.0 self-demo. A sample app and edited replay of the real render. Synthetic narration uses Dan’s own voice clone.

Watch the original on YouTube

Read the transcript

This is a release checklist for a small web app. Watch it get filled in, one step at a time. First we name the release, then tick off the tests and the docs. The camera follows each click, and the captions keep pace with the voice. The last box fills the progress bar, and one click ships it. None of that was recorded by hand. It came from this script: each shot is a heading, one line of narration, and the clicks to perform. One command turned the script into the video. The voice comes first, and its timing sets the pace for the recording and the captions. Then the tool checks its own work. It listens back to the narration, confirms the first frame carries the hook, verifies the video file, and lays out a contact sheet of every shot. To make one for your own app, add it to Claude Code as a plugin, or run it from a terminal. The video you just watched made itself.

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 generated first, and its timing becomes the clock that paces the browser recording and the captions, so audio, video, and captions are in sync by construction. Narrate with ElevenLabs or with any text-to-speech you run yourself. It can drive an authenticated SaaS app behind its real login, or splice in a prebaked clip for surfaces you would rather not automate, and it checks its own output before you ship it. Run it keyless with FAKE_TTS to iterate on the script for free.

Demo

Author a DEMO_SCRIPT.md, prove it keyless, then add a voice. Before any narration is generated, the pipeline checks the selectors it can against the app and reports the ones it cannot prove; then it synthesises narration, records the browser, builds word-timed captions, muxes, and verifies the delivered video file, failing if anything is out of spec.

terminal

# 1. Author a DEMO_SCRIPT.md: shots + browser actions + narration
# 2. Keyless dry run, no API key (silent audio, real capture + captions)
$ FAKE_TTS=1 npx -y agent-demo-video@0.3.0 demo.config.json
preflight → tts(fake) → capture → captions → mux → verify
 
# 3. Add a voice (ElevenLabs or your own text-to-speech), render for real
$ npx -y agent-demo-video@0.3.0 demo.config.json
✓ wrote out/final.mp4 (60.3s, 9 segments)

Quickstart

Install it as a Claude Code plugin, or run it with npx. 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+ (22.12+ for motion cards) and ffmpeg 5.1+ on PATH.

Claude Code pluginadds a demo-video skill and a read-only render-reviewer agent

/plugin marketplace add OrionArchitekton/agent-demo-video
/plugin install agent-demo-video@agent-demo-video

Capture browser (one time)the Playwright build this CLI uses

npx -y -p agent-demo-video@0.3.0 playwright install chromium

Script and configstart from the sample config, then point it at your DEMO_SCRIPT.md and running app (in Windows PowerShell, type curl.exe)

curl -fsSLo demo.config.json https://raw.githubusercontent.com/OrionArchitekton/agent-demo-video/v0.3.0/demo.config.sample.json

Keyless dry run (silent audio, no API key)real capture + real captions

FAKE_TTS=1 npx -y agent-demo-video@0.3.0 demo.config.json

Your own voice (a block in demo.config.json)any text-to-speech you can run from a shell; the aligner gives word-timed captions

"voice": {
  "provider": "command",
  "command": ["my-tts", "--text-file", "{text}", "--out", "{out}"],
  "aligner": ["/path/to/venv/bin/python", "/path/to/agent-demo-video/tools/align_whisper.py", "{audio}", "{text}", "{out}"]
}

Or ElevenLabsreplace your-api-key with your own key

ELEVENLABS_API_KEY=your-api-key npx -y agent-demo-video@0.3.0 demo.config.json

Authenticated SaaS (optional)log in once in your own terminal, then render headlessly

npx -y agent-demo-video@0.3.0 login demo.config.json
npx -y agent-demo-video@0.3.0 demo.config.json

Manifest actions

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.
scroll: Smoothly scroll an element into view, or to a pixel offset.
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 generated first; its timing becomes the clock that paces both the screen recording and the captions. Audio, video, and captions are in sync by construction, not nudged into alignment afterwards.

Checks its own work

Every render verifies the delivered video file, tiles a contact sheet of every segment, and records the run in a render report. With an aligner configured, a transcript check listens back to the narration and names any phrase it did not hear.

Your voice, or none

Narrate with ElevenLabs, or with any text-to-speech you run yourself, with word timings from your program or an aligner. FAKE_TTS renders silent drafts with real capture and real captions, so you can iterate on the script for free.

Built for Claude Code

Install it as a plugin and ask Claude for a demo video. A skill walks Claude through the script, preflight, a silent pass, a pre-render review by a read-only agent, and the narrated render.

Authenticated SaaS, captured safely

Drive a login-walled app behind its real session. Operator-confirmed 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.

Headless and reproducible

Playwright drives a headless Chromium with an injected 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.