Demo Reel

Create professional demo videos from web apps. Code your demos in TypeScript, with automatic voiceover and subtitles.

Quick Start

pnpm add -D demo-reel

// demos/my-feature.demo.ts
import { generate } from "demo-reel";

await generate(
  {
    name: "signup",
    outputDir: "./output",
    video: { resolution: "FHD" },
    cursor: "dot",
    motion: "smooth",
    typing: "humanlike",
    timing: "normal",
    outputFormat: "mp4",

    voice: {
      provider: "piper", // "piper" | "chatterbox" | "chatterbox-multilingual" (local/free) | "openai" | "elevenlabs"
      voice: "en_US-amy-medium", // auto-downloaded on first use
    },

    auth: {
      loginSteps: [
        { action: "goto", url: "https://myapp.com/login" },
        { action: "type", selector: { strategy: "id", value: "email" }, text: "[email protected]" },
        { action: "type", selector: { strategy: "id", value: "password" }, text: "password" },
        { action: "click", selector: { strategy: "class", value: "btn-primary" } },
      ],
      validate: {
        protectedUrl: "https://myapp.com/dashboard",
        successIndicator: { strategy: "custom", value: "h1:has-text('Dashboard')" },
      },
      storage: { name: "demo-session", types: ["cookies"] },
    },

    setup: [
      // Runs before recording (off-screen) — create test data, navigate
      { action: "goto", url: "https://myapp.com/dashboard" },
    ],

    cleanup: [
      // Runs after recording — delete test data
    ],

    scenes: [
      {
        narration: "Welcome to our app. Let's create a new project.",
        isIntro: true,
        steps: [
          {
            action: "hover",
            selector: { strategy: "testId", value: "new-project" },
            delayAfterMs: 800,
          },
          {
            action: "click",
            selector: { strategy: "testId", value: "new-project" },
            delayAfterMs: 1500,
          },
        ],
      },
      {
        narration: "Fill in the details and click Create.",
        steps: [
          {
            action: "type",
            selector: { strategy: "id", value: "name" },
            text: "My Project",
            delayAfterMs: 500,
          },
          {
            action: "hover",
            selector: { strategy: "custom", value: "button[type='submit']" },
            delayAfterMs: 600,
          },
          {
            action: "click",
            selector: { strategy: "custom", value: "button[type='submit']" },
            delayAfterMs: 2000,
          },
        ],
      },
    ],
  },
  { verbose: true },
);

pnpm build && pnpm demo-reel demos/my-feature

Output: output/signup.mp4 + .srt + .vtt + .meta.json

How It Works

1. You write a .demo.ts — TypeScript config with steps, scenes, and narration
2. generate() handles everything — compiles config, generates voiceover, records the video, outputs subtitles and metadata

Requirements

• Node.js 18+ — for running your demo scripts
• Playwright — pnpm exec playwright install chromium (peer dependency)
• FFmpeg — for video/audio processing (installed via ffmpeg-static or system package)
• Piper (optional) — for local TTS voiceover (auto-downloaded on first use, no setup needed)
• Chatterbox (optional) — highest-quality local TTS, English or 23 languages; needs a one-time Python env (see Provider Details)
• API keys (optional) — ELEVENLABS_KEY or OPENAI_API_KEY for cloud TTS

Claude Code Integration

Build demo scripts interactively with Claude Code:

pnpm demo-reel setup   # shows how to install the /demo-script plugin

Then use /demo-script in Claude Code:

/demo-script https://myapp.com show the signup flow

Claude crawls your app, builds the script with you scene by scene, and generates the .demo.ts.

Track CLI

Use track when you already know the flow you want to capture and want AI to start from your real interactions instead of re-exploring the app.

demo-reel track --name=create-template
demo-reel track --name=create-template --url=app.example.com/templates
demo-reel track --name=create-template --session=my-app --url=app.example.com/templates

That opens a headed Playwright browser, optionally navigates to the provided URL first, and writes create-template.track.json in the current directory when you close the browser or press q in the terminal.

If --url does not include a scheme, track prepends https:// automatically.

track also supports pause/resume controls in the terminal:

• r resumes recording
• p pauses recording
• q stops and writes the track file

For login-heavy flows, use --session <name>. That starts track paused, restores any previously saved auth state, and enables:

• s to save the current browser session into .demo-reel-sessions/<name>.json

Recommended auth-safe flow:

1. Run demo-reel track --name=create-template --session=my-app --url=app.example.com/templates
2. Log in while recording is paused
3. Press s to save the session
4. Press r to start recording the real demo flow

The written .track.json is normalized for AI consumption before it is saved.

It still reflects your real flow, but it now collapses noisy low-level browser activity:

• scroll bursts become a small number of meaningful scroll events
• typing bursts become final field values instead of one event per keystroke
• duplicate navigation bursts are reduced
• obvious weak selectors like generic buttons are upgraded when possible

See TRACKING.md for the raw file format and guidance for AI tools that consume .track.json files.

Configuration

Voice / TTS

voice: {
  provider: "piper",             // "piper" | "chatterbox" | "chatterbox-multilingual" | "openai" | "elevenlabs"
  voice: "en_US-amy-medium",      // any voice name or ID supported by the provider
  speed: 1.0,
  pronunciation: {                // word replacements before TTS
    "template": "template",       // prevent Dutch pronunciation of English words
  },
},

Voiceover is auto-generated when scenes have narration text and voice is configured. Cached by content hash — only regenerates when narration changes.

Provider Details

Piper (local, free) — voice is a model name like en_US-amy-medium. Auto-downloaded from HuggingFace on first use. Models are cached in $PIPER_VOICE_DIR (defaults to ~/.local/share/piper-voices). For custom models, use voicePath instead of voice:

voice: {
  provider: "piper",
  voicePath: "/path/to/custom-voice.onnx",
  speed: 1.0,
}

Chatterbox (local, free, highest quality)

Resemble AI's Chatterbox ships as two separate checkpoints, exposed here as two providers. They are different models with different sampling defaults, not one model with a language switch — so picking between them is an explicit choice rather than something inferred from your config:

| Provider | Model | Languages | Use when | | ------------------------- | ----------------------- | ------------ | ---------------------------------------------------- | | chatterbox | Chatterbox Turbo | English only | You want the English-tuned checkpoint | | chatterbox-multilingual | Chatterbox Multilingual | 23 | Anything non-English, or one provider for everything |

Both do zero-shot voice cloning: point voicePath at a 7-15s reference clip, or omit it for the built-in voice.

voice: {
  provider: "chatterbox-multilingual",
  language: "nl",                         // required for multilingual; defaults to "en"
  voicePath: "./voices/brand-voice.wav",  // omit to use the built-in voice
  speed: 1.0,
}

Supported language values: ar da de el en es fi fr he hi it ja ko ms nl no pl pt ru sv sw tr zh. Anything else is rejected at config-validation time.

Cached audio is keyed on the language too, so switching languages regenerates rather than serving stale audio.

Trade-offs versus Piper: ~3x slower than realtime on CPU (a 3-minute narration takes ~9 minutes to generate, once — results are cached by content hash), a multi-GB one-time model download per checkpoint, and output carries an inaudible Resemble watermark. speed is applied with FFmpeg atempo since Chatterbox has no native pace control.

Setup (shared by both providers):

uv venv --python 3.12 ~/.local/share/demo-reel-tts/venv
VIRTUAL_ENV=~/.local/share/demo-reel-tts/venv uv pip install \
  --index-url https://download.pytorch.org/whl/cpu torch==2.6.0 torchaudio==2.6.0
VIRTUAL_ENV=~/.local/share/demo-reel-tts/venv uv pip install chatterbox-tts

Both providers look for ~/.local/share/demo-reel-tts/venv/bin/python, then fall back to python3. Override with DEMO_REEL_CHATTERBOX_PYTHON. Model weights download on first use and are cached under ~/.cache/huggingface.

OpenAI — voice is an OpenAI TTS voice name (e.g. alloy, nova, shimmer). Requires OPENAI_API_KEY env var.

ElevenLabs — voice is an ElevenLabs voice ID string. Requires ELEVENLABS_KEY or ELEVENLABS_API_KEY env var.

Setup & Cleanup

setup: [
  // Runs in a separate browser BEFORE recording (not visible in video)
  { action: "goto", url: "https://myapp.com/" },
  { action: "click", selector: { strategy: "id", value: "create-workspace" } },
],

cleanup: [
  // Runs AFTER recording (even on failure) — delete test data
  { action: "goto", url: "https://myapp.com/admin" },
  { action: "click", selector: { strategy: "custom", value: "button.delete" } },
],

Setup and cleanup run in tolerant mode — failed steps are skipped.

Scenes & Subtitles

scenes: [
  {
    narration: "Welcome to our app.",
    isIntro: true,
    steps: [
      { action: "goto", url: "https://myapp.com" },
      { action: "wait", ms: 1500 },
    ],
  },
  {
    narration: "Let's create something.",
    steps: [
      { action: "click", selector: { strategy: "id", value: "create" } },
    ],
  },
],

• narration — voiceover text (also used for subtitles)
• steps — steps that belong to this scene
• isIntro — marks the intro scene (used by presentation systems to skip context)

Generates .srt, .vtt (subtitles) and .meta.json (scene timestamps for interactive players).

Legacy compatibility: You can also use the older format with a single top-level steps array and scenes referencing stepIndex. The two formats cannot be mixed.

Steps

| Action | Description | | --------- | -------------------------------------------------------------------- | | goto | Navigate to URL | | click | Click an element | | hover | Hover over element | | type | Type text into input | | press | Press a key | | scroll | Scroll element | | select | Select dropdown option(s) | | check | Check/uncheck checkbox | | upload | Upload files | | drag | Drag and drop | | wait | Wait for duration | | waitFor | Wait for condition (selector, URL, load state, network, JS function) |

Selectors

{ strategy: "testId", value: "submit-button" }     // data-testid
{ strategy: "id", value: "username" }               // id (no #)
{ strategy: "class", value: "btn-primary" }         // class (no .)
{ strategy: "href", value: "/dashboard" }           // link href
{ strategy: "custom", value: "button:has-text('Save')" }  // any CSS selector
{ strategy: "class", value: "card", index: 2 }      // nth match

Presets

cursor: "dot" | "arrow" | "none";
motion: "smooth" | "snappy" | "instant";
typing: "humanlike" | "fast" | "instant";
timing: "normal" | "fast" | "instant";
video: {
  resolution: "HD" | "FHD" | "2K" | "4K";
}

Modular Video Series

Demo videos are designed as standalone segments that also work as a series:

demos/
├── the-internet-login.demo.ts               # login flow (goto, type, click, hover)
├── the-internet-dynamic-controls.demo.ts    # async UI changes (waitFor)
├── the-internet-checkboxes-dropdown.demo.ts # form controls (check, select)
├── the-internet-file-upload.demo.ts         # file input (upload)
├── the-internet-hovers.demo.ts              # hover reveals (hover)
└── the-internet-drag-drop.demo.ts           # column swap (drag)

Each video is independently recordable. For apps requiring login, use the auth + setup blocks to recreate state from scratch.

CI/CD

name: Generate Demo Videos
on: push

jobs:
  demos:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm
      - run: pnpm ci
      - run: pnpm exec playwright install chromium
      - run: pnpm build
      - run: pnpm demo-reel demos/the-internet-login
      - uses: actions/upload-artifact@v4
        with:
          name: demo-videos
          path: ./output/*.mp4

Piper binary and voice models download automatically on first run — no secrets needed for the built-in demos. For cloud TTS, add secrets in your repo settings and pass them as env:

- run: pnpm demo-reel demos/my-demo
  env:
    ELEVENLABS_KEY: ${{ secrets.ELEVENLABS_KEY }}
    OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

License

MIT