demo-dev

Generate polished product demo videos with one command.

Give a URL and a prompt. Get a narrated, Screen Studio-style video.

npx demo-dev demo --base-url https://your-app.com --prompt "Show the dashboard and create a new project" --frame

---

What it does

demo-dev opens your web app in a headless browser, navigates it like a human, records everything, adds AI narration, and renders a polished mp4.

• AI plans the demo from a natural language prompt
• Ghost-cursor moves the mouse with human-like Bezier curves
• Playwright screencast records continuously at 60fps
• CSS zoom animates smoothly into click targets (Screen Studio style)
• ElevenLabs / OpenAI / local TTS generates narration per scene
• FFmpeg composes the final video with speed ramps, browser frame, and audio

---

Quick start

npm install -g demo-dev
npx playwright install chromium

Generate a demo:

demo-dev demo \
  --base-url https://your-app.com \
  --prompt "Show the onboarding flow and invite a teammate" \
  --frame

Authenticated apps

demo-dev auth --base-url https://your-app.com --email you@example.com --password 'your-password'
demo-dev demo --base-url https://your-app.com --prompt "..." --frame

---

Commands

demo-dev demo        # Full pipeline: prompt -> capture -> voice -> render
demo-dev auth        # Login and save browser session
demo-dev capture     # Record only (no voice/render)
demo-dev voice       # Generate TTS narration only
demo-dev render      # Capture + voice + compose video
demo-dev plan        # Generate demo plan from git diff
demo-dev probe       # Plan + probe pages for element discovery
demo-dev init        # Create config file in your project
demo-dev doctor      # Check environment (ffmpeg, playwright, etc.)
demo-dev config      # Show resolved config
demo-dev providers   # List available AI/TTS providers
demo-dev comment     # Post demo as a PR comment

Run demo-dev <command> --help for detailed options.

---

Key flags

Flag	Description
--prompt "..."	Natural language description of the demo to create
--frame	Wrap video in a browser window with gradient background
--quality draft|standard|high	Video quality preset
--base-url	URL of the app to demo
--base-ref	Git base ref for diff-based planning (default: origin/main)
--output-dir	Where to write artifacts (default: artifacts)

---

AI & voice providers

Set via environment variables:

# AI planning (pick one)
DEMO_AI_PROVIDER=claude          # Uses local Claude CLI
DEMO_AI_PROVIDER=openai          # Uses OpenAI API
DEMO_OPENAI_API_KEY=sk-...

# Voice narration (pick one)
DEMO_TTS_PROVIDER=elevenlabs     # Best quality
DEMO_ELEVENLABS_API_KEY=sk_...
DEMO_ELEVENLABS_VOICE_ID=...

DEMO_TTS_PROVIDER=openai         # Good quality
DEMO_OPENAI_API_KEY=sk-...

DEMO_TTS_PROVIDER=local          # Free, uses macOS `say` command

---

Config file

Create a demo.dev.config.json in your project:

{
  "projectName": "My App",
  "baseUrl": "http://localhost:3000",
  "baseRef": "origin/main",
  "outputDir": "artifacts",
  "preferredRoutes": ["/", "/dashboard"],
  "featureHints": ["dashboard", "settings"],
  "auth": {
    "loginPath": "/login",
    "emailTarget": { "strategy": "css", "value": "#email" },
    "passwordTarget": { "strategy": "css", "value": "#password" },
    "submitTarget": { "strategy": "role", "role": "button", "name": "Login" }
  }
}

---

How it works

prompt + URL
     |
     v
Playwright explores the site (screenshots + interactive elements)
     |
     v
AI generates a demo plan (scenes, actions, narration text)
     |
     v
ghost-cursor executes actions with human-like mouse movement
     |
     v
page.screencast records continuous video + CSS zoom on interactions
     |
     v
ElevenLabs/OpenAI generates narration audio per scene
     |
     v
FFmpeg composes: speed ramps + browser frame + audio sync
     |
     v
polished mp4

---

Requirements

• Node.js >= 20
• FFmpeg (install via brew install ffmpeg or equivalent)
• Chromium (installed via npx playwright install chromium)

---

License

MIT