demo-machine

Demo as code — turn YAML specs into polished product demo videos.

Write a simple YAML file describing what to click, type, and navigate. demo-machine launches your app, drives a real browser with human-like interactions, records everything, and renders a production-ready MP4.

Quick Start • Spec Format • CLI Reference • Contributing

Demo

A task manager app demo with voice narration — generated entirely from a YAML spec.

https://github.com/45ck/demo-machine/raw/master/examples/todo-app-demo.mp4

Notice the smooth cursor movement to each target, character-by-character typing, voice narration that leads into each action, and polished overlays with fades. This is not a screen recording — it's generated from code.

meta:
  title: "TaskFlow - Task Manager Demo"
  resolution:
    width: 1920
    height: 1080

runner:
  command: "node examples/todo-app/serve.mjs"
  url: "http://localhost:4567"
  timeout: 10000

chapters:
  - title: "Welcome to TaskFlow"
    steps:
      - action: navigate
        url: "http://localhost:4567"
        narration: "Welcome to TaskFlow, a simple and elegant task manager."
      - action: wait
        timeout: 1000

  - title: "Getting Started"
    steps:
      - action: click
        selector: "#get-started"
        narration: "Let's click Get Started to begin managing our tasks."
      - action: wait
        timeout: 800

  - title: "Adding Tasks"
    steps:
      - action: click
        selector: "#task-input"
      - action: type
        selector: "#task-input"
        text: "Design new landing page"
        narration: "We'll type in our first task — designing a new landing page."
      - action: click
        selector: "#add-btn"
      - action: wait
        timeout: 500
      - action: type
        selector: "#task-input"
        text: "Review pull requests"
        narration: "Next, let's add a task to review pull requests."
      - action: click
        selector: "#add-btn"
      - action: wait
        timeout: 500
      - action: type
        selector: "#task-input"
        text: "Write unit tests"
        narration: "And one more — writing unit tests."
      - action: click
        selector: "#add-btn"
      - action: wait
        timeout: 500

  - title: "Completing a Task"
    steps:
      - action: click
        selector: ".task-checkbox"
        narration: "To mark a task as done, just click the checkbox."
      - action: wait
        timeout: 800

  - title: "Filtering Tasks"
    steps:
      - action: click
        selector: "[data-filter='completed']"
        narration: "We can filter to see only completed tasks."
      - action: wait
        timeout: 800
      - action: click
        selector: "[data-filter='all']"
        narration: "Or switch back to view all tasks at once."
      - action: wait
        timeout: 500

Why demo-machine?

Tools like Screen Studio and Arcade require manual recording sessions. Every time your UI changes, you re-record. demo-machine takes a different approach:

• Reproducible — same YAML, same video, every time
• Version-controlled — specs live in your repo, reviewable in PRs
• CI-friendly — generate demo videos in your pipeline on every release
• No manual work — no clicking through your app, no editing in a video tool

Features

| Feature | Description | | ------------------------- | --------------------------------------------------------------------------- | | Smooth cursor | Cubic-bezier eased movement with click pulse feedback | | Natural typing | Character-by-character keystroke simulation | | Configurable pacing | Global + per-step delays for clicks, typing, navigation | | Polished overlays | Intro/outro cards, chapter titles with fades and backgrounds | | Auto app lifecycle | Spawns your dev server, healthchecks, tears down after | | Redaction | Blur sensitive selectors, scan for secret patterns | | Narration | Local TTS via Kokoro, or cloud via OpenAI/ElevenLabs with VTT/SRT subtitles | | Dead-time compression | Long pauses automatically sped up | | Callout zoom | Click targets highlighted with zoom regions |

Quick Start

Prerequisites

• Node.js >= 22
• pnpm
• FFmpeg on your PATH
• Playwright browsers: pnpm exec playwright install chromium

Install

git clone https://github.com/45ck/demo-machine.git
cd demo-machine
pnpm install
pnpm build

Run the Example

node dist/cli.js run examples/todo-app.demo.yaml \
  --output ./output \
  --no-headless

This will:

1. Start the included todo-app dev server
2. Launch a browser with smooth cursor and natural typing
3. Record the session via Playwright
4. Render a polished MP4 with overlays to ./output/output.mp4

Usage

CLI Commands

# Full pipeline: capture + edit + render
demo-machine run <spec.yaml>

# Validate a spec file without running
demo-machine validate <spec.yaml>

# Capture only (raw video, no post-processing)
demo-machine capture <spec.yaml>

# Re-render from an existing event log
demo-machine edit <events.json>

Options

| Flag | Default | Description | | ----------------------- | ---------- | ---------------------------------------------- | | -o, --output <dir> | ./output | Output directory | | --no-narration | — | Skip TTS narration | | --no-edit | — | Raw capture only, skip rendering | | --no-headless | — | Show the browser window | | --renderer <name> | ffmpeg | Video renderer | | --tts-provider <name> | kokoro | TTS: kokoro (local), openai, elevenlabs, piper | | --verbose | — | Debug logging |

Spec Format

Minimal Spec

meta:
  title: "My Demo"

runner:
  url: "http://localhost:3000"

chapters:
  - title: "Getting Started"
    steps:
      - action: navigate
        url: "/"
      - action: click
        selector: "#btn"

Action Types

| Action | Required Fields | Description | | ------------ | ------------------ | ----------------------------------------------- | | navigate | url | Go to a URL | | click | selector | Click an element | | type | selector, text | Type text character-by-character | | hover | selector | Hover over an element | | scroll | — | Scroll the page (selector, x, y optional) | | wait | timeout | Pause for milliseconds | | press | key | Press a keyboard key | | assert | selector | Assert visibility or text content | | screenshot | — | Take a screenshot (name optional) |

Every action supports an optional narration field for TTS and most support delay to override the default post-action pause.

Pacing

Control the feel of the demo globally. All fields are optional with sensible defaults:

pacing:
  cursorDurationMs: 600 # cursor travel time
  typeDelayMs: 50 # ms between keystrokes
  postClickDelayMs: 500 # pause after clicks
  postTypeDelayMs: 300 # pause after typing
  postNavigateDelayMs: 1000 # pause after navigation
  settleDelayMs: 200 # micro-pause after every action

Redaction

Blur sensitive content and scan for secret patterns:

redaction:
  selectors:
    - ".user-email"
    - "[data-sensitive]"
  secrets:
    - "\\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Z]{2,}\\b"

Branding

meta:
  branding:
    logo: "./assets/logo.png"
    colors:
      primary: "#3B82F6"
      background: "#000000"

Architecture

                    ┌──────────────┐
                    │  YAML Spec   │
                    └──────┬───────┘
                           │
                    ┌──────▼───────┐
                    │ Spec Loader  │  Zod validation + defaults
                    └──────┬───────┘
                           │
                    ┌──────▼───────┐
                    │   Runner     │  Spawn dev server, healthcheck
                    └──────┬───────┘
                           │
                    ┌──────▼───────┐
                    │   Playback   │  Cursor animation, typing, pacing
                    │   Engine     │  Playwright browser automation
                    └──────┬───────┘
                           │
                    ┌──────▼───────┐
                    │   Capture    │  Video recording + event log
                    └──────┬───────┘
                           │
                    ┌──────▼───────┐
                    │  Timeline    │  Intro/outro, chapters, callouts
                    │  Builder     │  Dead-time compression
                    └──────┬───────┘
                           │
                    ┌──────▼───────┐
                    │   FFmpeg     │  Overlays, fades, final MP4
                    │  Renderer    │
                    └──────┬───────┘
                           │
                    ┌──────▼───────┐
                    │  Narration   │  TTS + VTT/SRT subtitles
                    │  (optional)  │
                    └──────────────┘

Project Structure

src/
  cli.ts              # CLI entry point
  index.ts            # Public API exports
  spec/               # YAML parsing + Zod validation
  runner/             # Dev server lifecycle
  playback/           # Cursor, typing, pacing engine
  capture/            # Playwright video recording
  editor/             # Timeline + ffmpeg renderer
  narration/          # TTS providers + subtitles
  redaction/          # Blur + secret scanning
  utils/              # Logger, process helpers
tests/                # 172 tests across 13 suites
examples/             # Example specs + demo apps

Development

pnpm build          # Compile TypeScript
pnpm test           # Run 172 tests
pnpm lint           # ESLint
pnpm format         # Prettier check
pnpm typecheck      # tsc --noEmit
pnpm validate       # Run everything

See CONTRIBUTING.md for setup instructions and development workflow.

License

MIT — use it however you want.