demo-studio

Polished product demos — recorded by your AI agent.

Tag a skill in Cursor or Claude Code, describe what to show, and get back a zoom-composited .mp4 with optional voiceover and burned-in captions.

Launch demo (~60s, narrated + captioned) — recorded end-to-end with produce-video. The in-session app preview uses film-demo:

Why not just screen-record?

Works on any web app — Vite, Next.js, your own stack. One install, five skills.

Requirements

npx skills add only copies the skill files — it does not install ffmpeg, Playwright, Python packages, or browser binaries. @demo-setup writes demo.config.json, vendors the recording engine, and runs sanity checks — it does not install system tools for you. Install the rows below once per machine (or per project for Playwright / npm deps).

Every demo (silent or narrated)

Cloning this repo for the hello fixture: npm install (Playwright is already in package.json), then npx playwright install chromium.

Narrated demos only (narrate / sync-narration / produce-video)

Silent mode (narration.provider: "none") needs no Python packages and no API key.

Recording your own app (not the hello fixture)

Your dev server must be reachable at demo.config.json → app.baseUrl (e.g. npm run dev on port 5173). @demo-setup infers the command but does not start the server for you.

Verify before the first recording

After @demo-setup (or once demo.config.json exists):

node skills/demo-setup/scripts/check-setup.mjs    # node, ffmpeg, ffprobe, python, config
node skills/film-demo/scripts/test-engine.mjs     # full capture → compose smoke test (no app)

Both must exit 0. If ffmpeg or ffprobe is missing, nothing downstream works.

Quick start

1. Install skills (in your project, or clone this repo to try the hello fixture):

npx skills add AlexAnsart/demo-studio --all --agent cursor --copy -y

Install the requirements above if you have not already (ffmpeg, Playwright, and Python deps for narrated runs).

2. Set up once — in Cursor chat:

@demo-setup Set up demo-studio for this project.

This creates demo.config.json at your project root (from demo.config.example.json).

3. Record — silent demo:

@film-demo Record a silent demo of the signup flow. Save to demos/signup/demo.mp4.

Or full narrated pipeline (needs ELEVENLABS_API_KEY in .env):

@produce-video Produce a narrated demo of creating a task — voiceover and captions — save to demos/create-task/demo.mp4.

The agent writes the beat script, records the browser, composes zooms, runs quality checks, and delivers the file. You don't run ffmpeg or Playwright commands yourself.

Skills

How it works

Your prompt  →  script.md (Say + Show beats)
                    ↓
              narrate (optional)  →  narration.mp3
                    ↓
              film-demo           →  silent .mp4 (smart zooms, guardrails)
                    ↓
              sync-narration      →  final .mp4 + captions

Voice comes first when narrated: the video adapts to the voice, not the other way around.

Try the hello fixture

No dev server required — clone or open this repo, then install deps once:

npm install
npx playwright install chromium

Or install skills into another project:

npx skills add AlexAnsart/demo-studio --all --agent cursor --copy -y

Then in Cursor:

@demo-setup Set up demo-studio. Use the hello fixture in examples/hello-demo/app.

@film-demo Record a silent demo: type "Ship the v1 release", click Add, show the new task. Save to examples/hello-demo/output/demo.mp4.

Configuration

All tunables live in demo.config.json at your project root. The demo-setup skill generates it; you can also copy demo.config.example.json and edit by hand.

Field-by-field reference: docs/CONFIG.md

Every field has a safe default in skills/film-demo/scripts/config.mjs — a partial or empty file still works.

Where settings apply

Config sections at a glance

Minimal config example

{
  "app": { "baseUrl": "http://localhost:5173", "devCommand": "npm run dev" },
  "frame": { "preset": "macos-dark", "wallpaper": "photo-beach-tropical" },
  "narration": { "provider": "elevenlabs" }
}

Only the fields you set override defaults; everything else falls back to config.mjs.

Window design (styled frame)

The styled frame is the border around your recording: background (solid color or wallpaper), optional rounded corners, drop shadow, and an optional macOS-style title bar with red / amber / green traffic-light dots.

Light variant: docs/assets/window-chrome-macos-light.png

Frame presets

Set frame.preset in demo.config.json, or pass --preset to compose.mjs.

Built-in macOS presets ship with these defaults (skills/film-demo/scripts/presets.mjs):

Swap the wallpaper to any bundled name or your own image — the preset only sets the starting point.

Frame fields in demo.config.json

Example — aerial beach behind a dark macOS window:

"frame": {
  "preset": "macos-dark",
  "wallpaper": "photo-beach-tropical"
}

Example — rounded corners only, no wallpaper:

"frame": {
  "preset": "rounded-dark"
}

Compose CLI (per-render overrides)

After recording, film-demo runs compose.mjs on the render folder (raw.mp4, camera plan, etc.). You can re-run compose manually with extra flags:

node skills/film-demo/scripts/compose.mjs <renderDir> --preset macos-dark

# Swap wallpaper
node skills/film-demo/scripts/compose.mjs <renderDir> \
  --preset macos-dark --wallpaper photo-beach-tropical

# Build chrome piecemeal from a plain preset
node skills/film-demo/scripts/compose.mjs <renderDir> \
  --preset studio-dark \
  --wallpaper ribbon-indigo --wallpaper-dim 0.5 --radius 28

# Title bar + custom dot colors, no wallpaper
node skills/film-demo/scripts/compose.mjs <renderDir> \
  --preset studio-dark \
  --radius 18 --titlebar \
  --titlebar-color "rgba(30,30,36,0.95)" \
  --traffic-light-colors "#ff5f57,#febc2e,#28c840"

Finer options (dim, blur, title bar color) are not in demo.config.json yet — use CLI flags or edit presets.mjs. See docs/CONFIG.md § Window chrome.

Title bar note: the bar sits inside the top padding — it does not shrink your recorded content. If titlebarHeight exceeds internal padding, it is clamped with a console warning.

Wallpapers

47 bundled PNGs in skills/film-demo/assets/wallpapers/. Use any name with frame.wallpaper or --wallpaper (no .png extension). Pass a file path to use your own image.

Full gallery + licenses: skills/film-demo/assets/wallpapers/ATTRIBUTION.md
Machine-readable list: skills/film-demo/assets/wallpapers/manifest.json

Picking a wallpaper

List every bundled name:

ls skills/film-demo/assets/wallpapers/*.png

Preview wallpapers before committing

Renders a 10-second macos-dark sample for each wallpaper (requires an existing render dir with raw.mp4 or preview-zoomed.mp4, e.g. from hello-demo):

# All wallpapers
node skills/film-demo/scripts/render-wallpaper-samples.mjs examples/hello-demo/renders/006 --sec 10

# Subset only
node skills/film-demo/scripts/render-wallpaper-samples.mjs examples/hello-demo/renders/006 \
  --sec 10 --only photo-beach-tropical,photo-aurora,photo-city-neon

Output: examples/hello-demo/wallpaper-samples/<name>.mp4 — open a few, pick a name, set it in config.

Download / refresh Unsplash photos

Bundled photos are already in the repo. To re-fetch or add subsets:

node skills/film-demo/scripts/download-wallpapers.mjs
node skills/film-demo/scripts/download-wallpapers.mjs --only photo-beach-tropical,photo-beach-aerial

Unsplash License — free commercial use. Synthetic wallpapers need no attribution.

Regenerate procedural ribbons/mesh: node skills/film-demo/scripts/generate-wallpaper.mjs

Environment variables

Never commit .env. See .env.example.

Project layout (after setup)

your-project/
├── demo.config.json          ← all defaults (frame, camera, voice, …)
├── .env                      ← API keys (gitignored)
├── demos/                    ← output dir (configurable)
│   └── my-feature/
│       ├── script.md         ← Say + Show beats
│       ├── run.mjs           ← Playwright recording script
│       └── demo.mp4          ← final deliverable
└── skills/                   ← copied by npx skills add
    └── film-demo/
        └── assets/wallpapers/  ← bundled PNGs

Further reading

License

MIT · AlexAnsart/demo-studio