agent-demo-video

Optional prepared opening scenes and external scene renderers are documented in Optional opening scene. They are off by default, preserve narration and timing, and require no Blender or private scene library.

Turn a DEMO_SCRIPT.md and a running web app into a finished, narrated, captioned MP4, headless and repeatable. Narration is generated first and becomes the clock for the screen recording and the captions, so audio, video and captions stay in sync by construction. Length is capped by maxDurationSec (default 300).

Watch the self-demo on YouTube (one minute): the tool rendered it of a sample app and of its own script, run and checks, from demos/self/. The video file is also on the v0.3.0 release.

Install

All three ways need Node 18 or newer and ffmpeg 5.1 or newer plus ffprobe on PATH (apt install ffmpeg or brew install ffmpeg; check with ffmpeg -version).

Claude Code plugin. Adds a demo-video skill that walks Claude through a video, and a read-only render-reviewer agent that checks the contact sheet before narration is spent:

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

Then ask Claude for a demo video of your app. The skill runs the CLI through npx.

npx or a global install:

npx -y -p [email protected] playwright install chromium   # one time: the browser build this CLI uses
npx -y [email protected] demo.config.json
# or: npm install -g agent-demo-video, then: demo-video demo.config.json

From source:

git clone https://github.com/OrionArchitekton/agent-demo-video.git
cd agent-demo-video
pnpm install
pnpm exec playwright install chromium

Quickstart

From a source checkout, render the bundled smoke demo with silent narration. It needs no API key and no running app:

FAKE_TTS=1 pnpm demo demos/smoke/demo.config.json

Output lands in demos/smoke/out/: final.mp4, captions.srt, contact-sheet.png and render-report.json.

For your own app:

1. Write a DEMO_SCRIPT.md: one ### SHOT <id> per shot, with narration and browser actions (script format).
2. Write a demo.config.json that points at the script and your running app (config; sample: demo.config.sample.json).
3. Render with FAKE_TTS=1 first and look at contact-sheet.png.
4. Choose a voice and render for real.

### SHOT intro
- target: dashboard
- narration: This is the dashboard. Every active workflow, at a glance.
- action: goto url="/"
- action: highlight selector="#workflows"
- action: wait ms=800

Voice

• ElevenLabs. Set ELEVENLABS_API_KEY. Without a key the run stops rather than shipping a silent video.
• Your own text-to-speech. voice.provider: "command" runs any program you can call from a shell, with an optional aligner for word-timed captions (voice).
• Silent. FAKE_TTS=1 renders placeholder narration of estimated length, for drafts.

Features

• Screencast capture with an animated cursor, highlights, chapter cards, zoom on action, a slowly drifting camera, a framed scene and light sound design (how the pipeline works).
• Fail-closed preflight. Selectors are checked against the running app before any narration is generated. Shots behind a login, and selectors that follow a click or type in the same shot, are reported rather than proven (preflight).
• Apps behind a login. target: live drives a saved browser profile kept outside the repo; demo-video login <config.json> creates it (authenticated capture).
• Prebaked clips and third-party tabs for surfaces you cannot or prefer not to automate (third-party tabs).
• Shorts. "platform": "shorts" renders 9:16, and brand.hook puts large text on the first frame (config).
• Quality checks. When voice.aligner is configured, a transcript check compares what the video says with the script, and Shorts without a hook are flagged (quality checks).
• Motion cards. brand.motion: true animates the title and end cards with HyperFrames, an optional add-on (motion cards).
• Verified output. Every render probes the delivered final.mp4 against the configured format, writes a contact-sheet.png with one still per segment (title and end cards included), and records everything in .

CLI

demo-video <config.json> [--no-preflight] [--out <new-directory>] [--script <absolute-file>]
                         [--clips-dir <absolute-directory>] [--render-host <host>]
demo-video login <config.json>

Documentation

• How the pipeline works
• Script format
• Config
• Preflight selector gate
• Authenticated capture
• Third-party tabs
• Voice
• Quality checks
• Motion cards
• Changelog

Replicability

Pin voice.seed in your config and lock your ffmpeg and Chromium versions to get byte-stable reruns from the same script. The only inputs that change between demo iterations are DEMO_SCRIPT.md and demo.config.json; everything else is deterministic given the same narration audio.

License

MIT