Narrated, captioned product-demo MP4 from a storyboard.json; re-renders itself in CI at ~$0.
io.github.tandryukha/aidemo MCP Server
This MCP server generates narrated, captioned product-demo videos. It takes a storyboard.json produced by an MCP-capable coding agent and drives a headless Chrome session to produce a deterministic replay, then renders an MP4 with voiceover, synced captions, and auto-zoom.
π οΈ Key Features
Narrated product-demo MP4 output
Voiceover and synced captions
Auto-zoom during the recording
Deterministic replay via headless Chrome
Accepts storyboard.json written by an MCP-capable agent
Tell your coding agent "record a 45s demo of the checkout flow" β get back a
polished MP4 with voiceover, synced captions, and auto-zoom. Any MCP-capable
agent (Claude Code, Codex CLI, Gemini CLI) writes one storyboard.json; the
headless engine drives a real Chrome, records a deterministic replay, voices
it, captions it, and trims the dead time. Because the replay is deterministic,
the demo re-renders itself in CI when the product changes β no re-recording,
no API key, about $0 a render. An open-source (MIT) alternative to Screen
Studio, Clueso, or Demosmith for when you'd rather your coding agent make the
demo.
Install: Claude Code /plugin marketplace add tandryukha/aidemo Β· any agent npx skills add tandryukha/aidemo (skill only; add the MCP server with repo-init) Β· CI uses: tandryukha/aidemo@stable Β· CLI npx -y @tandryukha/aidemo Β· Homebrew brew install tandryukha/aidemo/aidemo Published on the GitHub Marketplace, npm, a Homebrew tap, and the MCP Registry.
Real output β a ~51 s self-narrated tour of Wikipedia (portal search β
Ada Lovelace β focus-zoom β click through to the Analytical Engine β glide
scroll), authored by Claude from one storyboard.json and recorded as a
deterministic replay. The preview GIF is silent;
watch the full version with narration βΆ.
Three ways to use it
From your coding agent β the fastest path. In Claude Code:
/plugin marketplace add tandryukha/aidemo then
/plugin install record-demo@aidemo (bundles the skill and the MCP
server). In Codex / Gemini / any MCP agent:
npx -y github:tandryukha/aidemo#stable repo-init. Then just say
"record a 45s demo of <flow>" and the agent authors + renders it.
Locally, free & offline β
AIDEMO_TTS_PROVIDER=local aidemo render <dir> --headless. An in-process
voice model + script-timed captions mean no API key, ~$0, fully offline.
See docs/LOCAL_MODELS.md.
In CI, self-maintaining β drop uses: tandryukha/aidemo@stable into a
workflow. When the product changes, it replays the committed storyboard and
commits fresh media β no key, no LLM tokens, ~$0 on free runner minutes.
See docs/CI.md.
Free & open source. MIT-licensed. Runs on GitHub's free Actions tier, or
fully local at $0 with the in-process voice β no API key, no cloud upload, no
telemetry. Works against localhost and auth-walled apps (your own Chrome).
From one sentence to a narrated MP4
You type a sentence, the agent writes an artifact you can read and edit, the
engine records and cuts it:
1 Β· What you type β one line to any MCP-capable agent (Claude Code here):
code
claude "record a 45s demo touring Wikipedia: search for Ada Lovelace,
open the Analytical Engine, then glide down the article"
2 Β· What the agent authors β a plain, editable storyboard.json (excerpt:
narration + a fixed browser action-spec, side by side β no generated code):
jsonc
{"title":"A quick tour of Wikipedia","zoom":{},// Screen-Studio-style auto-zoom"scenes":[{"id":"search","narration":"Start at the Wikipedia portal and search for Ada Lovelace.","actions":[{"op":"goto","url":"https://www.wikipedia.org/"},{"op":"type","target":{"selector":"#searchInput"},"text":"Ada Lovelace"},{"op":"click","target":{"selector":"button[type=submit]"}}]},{"id":"engine","narration":"Her notes on Babbage's Analytical Engine hold the first computer program.","actions":[{"op":"focus","target":{"selector":"#firstHeading"}},{"op":"click","target":{"selector":"a[href*='Analytical_Engine']"}},{"op":"scrollBy","dy":900,"easing":"glide"}]}]}
3 Β· How it's recorded + cut β aidemo render drives a real Chrome (smooth
animated cursor, human-cadence typing, auto-zoom), then trims the dead time and
syncs to the narration:
4 Β· What you get β output/final-demo.mp4 with final-demo.srt/.vtt
captions beside it (timed to the video; captions.track also embeds them as a
subtitle track viewers can toggle), plus a README-ready GIF (aidemo gif) and
named stills (aidemo stills) from the same take. UI changed?
Re-run against the same storyboard β no re-recording by hand.
The design goal: demos that look human-made and snappy, not like an AI
clicking around and waiting between screenshots β by separating authoring
(slow, one-time β figure out the flow) from recording (a fast deterministic
replay with a smooth animated cursor).
What teams render with it
GitHub README demos β aidemo gif demos/onboarding, drop the autoplaying
GIF into the readme (the GIFs on this page are exactly that).
Landing-page hero videos β the muted-autoplay MP4 on
aidemo.top is a rendered demo, poster frame and all.
Release / what-shipped demos β narrate the new feature, then
gh release upload v1.4.0 demos/whats-new/output/final-demo.mp4.
Customer & prospect demos β personalized flows against your real app:
localhost, auth walls, your own logged-in Chrome; nothing leaves the machine.
For a native iOS or Android app, aidemo records the iOS Simulator
(simctl recordVideo) or the Android emulator (adb screenrecord) while your
own Maestro flows drive it, then edits the clips into store-ready media:
App Store App Preview (886Γ1920, 15β30 s, 30 fps H.264 + stereo AAC,
poster frame + its ASC timecode) and Google Play promo (1080Γ1920 or
1920Γ1080, YouTube-ready) β validated against the store spec; a file that
would be rejected fails the run.
Made for muted autoplay: burned-in captions rendered from text (a new
language is a text swap: --lang ru), speed ramps on labelled dead time
(typing, waiting), no still frame over ~0.7 s unless you mark it a hold,
an end card with icon, name and one line. No voiceover needed.
Screenshot sets: iOS 6.9" (1320Γ2868), Play phone (1080Γ1920), Play
feature graphic (1024Γ500) β headline + zoomed device frame that bleeds off the
edge so UI text is readable at search-thumbnail size; brand fonts and colours.
bash
aidemo store-check demos/store # generated/store.json: scenes β Maestro flows, captions, shots
aidemo native-record demos/store # one clip per scene on the booted simulator/emulator (--boot to start one)
aidemo store-video demos/store # β output/store/app-store-preview.mp4 (+ poster, report)
aidemo store-screenshots demos/store # β output/store/screenshots/ios-6.9/01-β¦.png
aidemo store-validate some.mp4 --preset app-store-preview # check any file
Commit a storyboard and the aidemo GitHub Action keeps its
demo media in sync β a fresh narrated, captioned MP4 (and GIF) on every relevant
change. Deterministic replay + a local voice mean no API key, no LLM tokens,
about $0 (just free runner minutes). It's the loop a screen recorder can't
run: your demo maintains itself.
yaml
# .github/workflows/demo.yml-uses:actions/checkout@v4-run:sudoapt-getupdate&&sudoapt-getinstall-yffmpeg# ubuntu ships Chrome, not ffmpeg-uses:tandryukha/aidemo@stablewith:demos:demos/*tts:local# in-process voice β no keys, no tokensgif:"true"
A bundled fixture store (search β results β cart β checkout) that renders a
finished demo with zero external dependencies:
bash
npm install # Node 22.12+, system Chrome, ffmpeg on PATH
node examples/local-demo/serve.mjs # terminal 1: fixture on :8787
node bin/aidemo.mjs render examples/local-demo --headless # terminal 2
open examples/local-demo/output/final-demo.mp4 # xdg-open on Linux, start on Windows
Voice/captions need OPENAI_API_KEY in .env β orAIDEMO_TTS_PROVIDER=local
(no key, offline), orOPENAI_BASE_URL at a local server. See
docs/LOCAL_MODELS.md. No Playwright browser download is
needed β the engine uses your system Chrome (channel: "chrome"; see
Setup to use a different browser). The one Playwright download is
its ~2 MB ffmpeg helper, which encodes the take: the first take installs it
automatically (AIDEMO_NO_AUTO_INSTALL=1 to manage it yourself with
npx playwright install ffmpeg).
The bundled fixture rendered end-to-end β narrated, captioned, auto-trimmed.
Silent preview; full version βΆ.
CLI
Each step is independently runnable and re-runnable β regenerate voice without
re-recording, recompose without re-transcribing, etc.
bash
aidemo init <name> # scaffold demos/<name>/ with a starter storyboard
aidemo init <name> --from-url <url> # β¦drafted from the live page's headings + real selectors
aidemo import-trace trace.zip --name <name> # β¦or from a Playwright trace / *.spec.ts (actions + selectors β scenes)
aidemo voice <dir> # per-scene TTS β narration.mp3 + voice.json
aidemo record <dir> # drive Chrome β raw video + timeline.json
aidemo probe <dir> # record-only dry run (verify selectors), no key needed
aidemo validate <dir> # schema-check the storyboard, no browser (non-zero exit on issues)
aidemo lint <dir> # predict freezes/cuts + selector pitfalls before spending a take
aidemo captions <dir> # Whisper β captions.{srt,vtt,cues.json} (--offline for no network)
aidemo compose <dir> # trim + sync + zoom + cards + caption + mux β final-demo.mp4
aidemo gif <dir> # final-demo.mp4 β README-ready GIF (autoplays on GitHub)
aidemo frames <dir> # evenly spaced PNGs from the video for review (--source raw)
aidemo render <dir> # voice β record β captions β compose
aidemo native-record <dir> # iOS Simulator / Android emulator take, one clip per scene (Maestro)
aidemo store-video <dir> # β App Store App Preview / Play promo, spec-validated
aidemo store-screenshots <dir> # β store screenshot sets + Play feature graphic
aidemo guide # print the canonical authoring guide
aidemo doctor # check Node, ffmpeg, Chrome, voice endpoint
Add --headless for CI/fixtures; omit it for real sites that need your
logged-in session. --profile <dir> picks the Chrome user-data dir; --fresh
records on a wiped one; --storage-state <file> / --cookie "name=value;domain=host"
seed a cookie-gated site before the first action (or declare setup in the
storyboard, which can also run a preflight script before every take);
--capture native|obs switches to high-fidelity screen capture. voice/renderskip TTS for unchanged scenes, and recordsalvages a failed take (keeps
the footage + drops a screenshot/frame-dump in logs/).
Agent interface (MCP)
aidemo mcp runs a stdio MCP server (no network listener) exposing the engine
to any MCP client. The Claude Code plugin bundles it; aidemo repo-init registers
it agent-neutrally (.mcp.json for Claude Code, .gemini/settings.json for
Gemini; codex mcp add aidemo -- npx -y github:tandryukha/aidemo#stable mcp for
Codex).
Authoring tools β get_authoring_guide serves
docs/AUTHORING.md version-matched from the engine (can't go
stale); get_storyboard_schema, validate_storyboard, init_demo, doctor.
Pipeline tools run as jobs β probe/record/render/voice/captions/
compose/gif (and native_record/store_video/store_screenshots) return a jobId immediately; job_status reports stage,
per-scene progress, and (on failure) the screenshot/frame-dump paths.
.env works like the CLI β the server loads its cwd's and the engine's
.env at startup, and since MCP clients often start it outside your repo, each
tool given a demo dir also applies that repo's .env (nearest one walking up
from the demo dir to the repo root). doctor {dir} shows the result.
Why it's built this way
Deterministic replay, not an LLM in the loop. The recording runs a fixed
action-spec at full speed, so the video is smooth. The agent only authors the
storyboard (and confirms selectors once), never during capture.
Declarative action-spec + fixed player (not generated spec.ts). Safer,
editable, and it emits a timeline for free β compose fits each scene's video
to its narration by trimming/speeding only the idle parts, freeze-holding a
static page for any remainder instead of ugly slow-motion.
Captions via overlaid PNGs, not libass. Many ffmpeg builds lack
subtitles/drawtext; aidemo rasterizes each caption with headless Chrome and
overlays it with time-gated enable β works on any ffmpeg with overlay.
Cinematic polish is compose-time, not record-time β a bad zoom is a
recompose, never a re-record. See docs/POLISH.md.
Deeper docs
docs/AUTHORING.md β the canonical storyboard schema,
action vocabulary, and demo-director principles (served by the engine).
Prereqs: Node 22.12+, Google Chrome, ffmpeg + ffprobe on PATH. The
first take also fetches Playwright's ~2 MB ffmpeg helper, which encodes the
recording (once per Playwright version; AIDEMO_NO_AUTO_INSTALL=1 opts out).
Developed and tested on macOS; Linux works for the default (Playwright) capture
and --capture obs. Run aidemo doctor to check your setup.
bash
npm install
cp .env.example .env# add OPENAI_API_KEY, or use AIDEMO_TTS_PROVIDER=local (no key)
Choosing the browser. Every launch (recording, inspect, caption/card
rasterizing) uses system Google Chrome by default. Two env vars (shell or
.env) override that, highest precedence first:
AIDEMO_CHROME_EXECUTABLE=/path/to/chrome β an explicit Chromium-based binary.
AIDEMO_CHROME_CHANNEL=<channel> β a Playwright channel: chrome (default),
chrome-beta, chrome-dev, chrome-canary, msedge, msedge-beta,
msedge-dev, msedge-canary, or chromium. chromium (Chrome for Testing)
is the fix when an enterprise-managed Chrome closes automated sessions after
a few seconds ("Target page, context or browser has been closed"); it needs a
one-time npx playwright install chromium.
aidemo doctor reports which browser will be used and whether it was found.
aidemo login opens the same browser, so the profile you log into matches the
one you record with.
Project layout (per demo)
code
demos/<name>/ β your working area (untracked; scaffold with `aidemo init`)
input/ brief.md
generated/ storyboard.json timeline.json captions.{srt,vtt,cues.json}
recordings/ raw.webm (or raw.mp4 for native/OBS capture)
audio/ scene-*.mp3 narration.mp3 voice.json
output/ final-demo.mp4 final-demo.{srt,vtt} (captions timed to the video)
logs/ <command>.log fail-<scene>-<n>.{png,json} (on a failed action)
Security & trust
No telemetry, no analytics, no install-time scripts (package.json has no
postinstall/preinstall).
Network is user-initiated only:api.openai.com (only voice/captions,
your key β or a local server via OPENAI_BASE_URL), api.elevenlabs.io (opt-in),
huggingface.co (download-only, once, for AIDEMO_TTS_PROVIDER=local),
cdn.playwright.dev (download-only, once per Playwright version: the ~2 MB
ffmpeg helper that encodes the take; off with AIDEMO_NO_AUTO_INSTALL=1), and
github.com (your own gh, for aidemo feedback). Recording/composing are
otherwise fully local. The MCP server is stdio-only β no listener.
Small, auditable surface: ~50 source files, 7 runtime deps (11 packages
installed in all), MIT. Pin an immutable ref if you're wary of the moving
#stable tag: npx -y github:tandryukha/aidemo#v0.20.1 (any released tag).
Comments on the video (pause & comment) and in-place transcript editing:
captions map to scenes, so editing a line marks that scene dirty and
aidemo voice --scene <id> + compose regenerates only the delta.
Web UI, project history, brand kits, changelog integrations.
Shipped: the GitHub Action (CI re-render), cinematic polish (auto-zoom,
scroll easing, music ducking, intro/outro cards, motion blur, post-hoc cursor
control), native/OBS capture, iOS Simulator / Android emulator capture with
App Store / Google Play exports, the agent-neutral MCP server + authoring guide,
ElevenLabs and in-process local voice providers, and the Claude Code plugin.
Contributing
Issues and PRs welcome β see CONTRIBUTING.md for dev setup, the
smoke test, and the DCO sign-off requirement. Recording-session feedback has a fast
path: aidemo feedback demos/<name> pre-fills a structured issue. Blocked in the
meantime? aidemo guide --topic troubleshooting covers the local workarounds
(per-stage re-runs, pinning a release, running a patched checkout).