# aidemo

> aidemo is built for coding agents to autonomously record product demos — the
> hero video on a landing page, a walkthrough in a GitHub README, a
> what-shipped video attached to release notes for customers. It turns an
> agent-authored `storyboard.json` into a polished, narrated, captioned
> product-demo video (MP4). It is an open-source (MIT) alternative to Screen
> Studio, Clueso, or Demosmith for when you'd rather your coding agent make
> the demo: the agent writes the storyboard (script + per-scene voice/music
> plan + declarative browser action-spec), then a deterministic player drives a
> real Chrome — no LLM in the loop during capture — records it, generates a
> realistic voiceover (OpenAI TTS), aligns word-level captions (Whisper), trims
> dead time, auto-zooms on interactions, and exports a shareable MP4. Runs
> locally — fully offline if voice/captions point at an OpenAI-compatible local
> server — and works against localhost and auth-walled apps using your own
> Chrome profile.

Key facts:
- Works with Claude Code today via the bundled `record-demo` skill; Codex CLI /
  Gemini CLI planned via an agent-neutral authoring doc + MCP server. Any human
  or agent that can write a `storyboard.json` and run `aidemo render` can use it.
- Deterministic replay: recording runs a fixed action-spec at full speed; the
  agent only authors, it never drives the capture. Same input → same video.
- Tweak loop without re-recording: per-scene TTS hash cache means editing one
  narration line re-voices only that scene; zoom choreography is compose-time,
  so a bad zoom is a recompose, never a re-record.
- Private by design: the pipeline's only network calls are TTS narration and
  caption transcription, sent with your own OpenAI key — or to any
  OpenAI-compatible local server (speaches, Kokoro-FastAPI, LocalAI) via
  OPENAI_BASE_URL, in which case no API key is needed and the whole render is
  offline. `aidemo captions --offline` needs no speech-to-text at all
  (approximate script-based timing). No telemetry or analytics; music is
  synthesized locally from math, captions/cards are rasterized locally, and
  the output MP4 never leaves disk. Verified end-to-end both against a bundled
  mock OpenAI-compatible server and against real local models (speaches:
  Kokoro TTS + faster-whisper captions, no API key).
- Use cases: autoplaying GIFs for GitHub READMEs (`aidemo render
  demos/onboarding --headless && aidemo gif demos/onboarding` writes
  `output/final-demo.gif` next to the MP4); muted-autoplay hero videos for
  landing pages (the hero video on aidemo.top is aidemo output); release /
  what-shipped demos attached to a release (`gh release upload v1.4.0
  demos/whats-new/output/final-demo.mp4`); personalized customer & prospect
  demos against localhost or auth-walled apps in your own logged-in Chrome,
  nothing uploaded anywhere; end-of-sprint progress demos — one prompt, the
  agent authors and renders in the background while you keep working.
- Integrations: authoring by Claude (Claude Code) today, Codex CLI / Gemini CLI
  planned; narration voice by OpenAI TTS (gpt-4o-mini-tts) behind a swappable
  VoiceProvider interface; captions by OpenAI Whisper (word-level timestamps) —
  voice and captions both also work against any OpenAI-compatible local server
  (speaches, Kokoro-FastAPI, LocalAI) via OPENAI_BASE_URL; recording via
  Playwright + system Chrome; final compose via ffmpeg. All rendering is local.
- Requirements: Node 20+, Google Chrome, ffmpeg/ffprobe, and an OpenAI API key
  — or an OpenAI-compatible local server via OPENAI_BASE_URL (no key needed,
  render is fully offline). Developed on macOS; Linux expected to work (default
  capture path).
- Made with aidemo (first customers, real-world examples): a 51-second
  self-narrated demo of the engine driving Wikipedia (the hero video on the
  landing page and README); aidemo's first customers are MaxFit (maxfit.ee) —
  a 75-second narrated shopping demo inside its ChatGPT app, an auth-walled
  widget in nested iframes through to a live checkout — and turg.fitness.ee, a
  production fitness-gear marketplace whose walkthrough (same record-demo
  skill, pointed at the live site) is next.

## Docs

- [README](https://github.com/tandryukha/aidemo#readme): positioning, design
  decisions, quickstart, CLI reference, cinematic-polish options
- [record-demo skill](https://github.com/tandryukha/aidemo/blob/main/.claude/skills/record-demo/SKILL.md):
  how the agent authors a storyboard and renders a demo
- [Releases](https://github.com/tandryukha/aidemo/releases): versioned releases
  with real rendered MP4s as assets
- [Example output (51s, narrated)](https://github.com/tandryukha/aidemo/releases/download/v0.3.0/wikipedia-showcase-demo.mp4):
  aidemo demoing itself on Wikipedia, authored by Claude
- [Example output (75s, narrated)](https://github.com/tandryukha/aidemo/releases/download/v0.3.0/maxfit-chatgpt-demo.mp4):
  a shopping flow inside a ChatGPT app, authored by Claude
- [CONTRIBUTING](https://github.com/tandryukha/aidemo/blob/main/CONTRIBUTING.md)

## Install

- Clone + run: `git clone https://github.com/tandryukha/aidemo && npm install`,
  then `node bin/aidemo.mjs render <demo-dir>`
- Or via npx from a product repo: `npx -y github:tandryukha/aidemo#stable <cmd>`