aidemo

The core goal of aidemo is to enable coding agents to produce demo videos. You only need to describe your requirements to an MCP-enabled agent (such as Claude Code, Codex CLI, Gemini CLI), for example "record a 45-second checkout flow demo," and the agent will write a storyboard.json. Then, a headless engine drives a real Chrome browser, records a deterministic replay, and adds narration, synchronized subtitles, and automatically trims dead time. Because the replay is deterministic, when the product changes, the demo video can be re-rendered in CI without re-recording and without API keys, at a cost of about $0 per render.

Main capabilities:

• Generate demo videos from natural language descriptions, with the agent automatically writing an editable storyboard.json.
• Deterministic replay: record a fixed action specification to ensure smooth video without relying on real-time LLM decisions.
• Automatic narration (TTS) and synchronized subtitles (Whisper).
• Cinematic polish such as auto-zoom, scroll easing, and music ducking, completed during the compositing stage without re-recording.
• Output MP4, GIF, and static screenshots, convenient for READMEs, landing pages, release notes, and more.
• Support local offline rendering, using the built-in voice model (Kokoro) and script-timed subtitles, without API keys.
• Automatically maintainable in CI: re-render committed storyboards via GitHub Action to keep demo media in sync.
• Suitable for localhost and apps requiring authentication, using your local Chrome session, with data never leaving your machine.

How to use:

• Use from a coding agent (fastest path): in Claude Code, run /plugin marketplace add tandryukha/aidemo, then /plugin install record-demo@aidemo. In Codex / Gemini / other MCP agents, run npx -y github:tandryukha/aidemo#stable repo-init. Then tell the agent "record a 45-second demo of <flow>" and you're done.
• Local free offline rendering: set AIDEMO_TTS_PROVIDER=local, run aidemo render <目录> --headless.
• Use in CI: add uses: tandryukha/aidemo@stable to the workflow.
• Command-line interface: npx -y @tandryukha/aidemo or install via Homebrew with brew install tandryukha/aidemo/aidemo.
• MCP server: aidemo mcp runs a stdio MCP server for use by any MCP client.

When to use it:

• GitHub README demos: use aidemo gif to generate an autoplaying GIF.
• Landing page hero video: a rendered silent autoplaying MP4.
• Release/feature demos: describe new features for release notes and upload a video.
• Customer and prospect demos: personalized walkthroughs against real apps (including localhost and auth walls).
• Self-maintaining demos in CI: after committing a storyboard, the GitHub Action generates a new MP4 and GIF with narration and subtitles on every relevant change.

Limitations and requirements:

• Requires Node 20+, Google Chrome, ffmpeg, and ffprobe in PATH.
• Voice and subtitles require OPENAI_API_KEY in .env, or use a local TTS provider (no key, offline), or set OPENAI_BASE_URL to point to a local server.
• No need to download Playwright browsers; the engine uses system Chrome (channel: "chrome").
• Development and testing are mainly done on macOS; Linux supports default capture and --capture obs.
• Network requests are only user-initiated: api.openai.com (voice/subtitles only, your key), api.elevenlabs.io (optional), huggingface.co (downloaded once only, for local TTS), github.com (for feedback). Recording and compositing are fully local. The MCP server uses stdio only, with no network listening.
• No telemetry, analytics, or install scripts. The codebase is small and easy to audit (about 20 source files, 7 runtime dependencies, MIT license).

More docs: docs/AUTHORING.md (storyboard spec), docs/LOCAL_MODELS.md (keyless rendering), docs/POLISH.md (polish options), docs/CI.md (CI rendering), docs/CHATGPT_APPS.md (recording ChatGPT app components).