demo-recorder

demo-recorder

Record narrative-driven browser video demos from YAML scenarios. Parallel desktop + mobile capture, beat-synced on-canvas captions, text-to-speech voice-over, and a Remotion-rendered intro/outro.

Designed for product teams who want demos that tell a story rather than mechanical click-throughs.

Features

• Parallel capture — desktop and mobile record the same scenario at the same time; step boundaries are shared by construction.
• Side-by-side composition — widened 2344x1260 canvas; desktop on the left, stylized phone frame on the right.
• Narrative beats — tag steps setup | action | payoff | close; the composition shows beat-transition chips and adapts pacing.
• On-canvas captions — a single shared caption strip below both views; no overlay chrome bleeds into the recording.
• Voice-over — auto-detects Piper (local neural) → Google Cloud TTS (OAuth) → OpenAI TTS (API key) → macOS say.
• Intro/outro — Remotion-rendered title card + step summary with adaptive durations.
• Story Director — generates a narrative arc (persona, setup, inciting moment, payoff, close) from a PR's diff + test plan.
• Isolated mode — spins up a dedicated Supabase + Next.js stack per recording for parallel, deterministic runs.
• Preview mode — record against any Vercel preview deployment.

Installation

git clone https://github.com/gerokeller/demo-recorder.git
cd demo-recorder
npm install
npx playwright install chromium

Quick start

Write a scenario in scenarios/my-demo.yaml:

name: my-demo
title: "Quick Tour"
description: "A 45-second walkthrough of the feature."

settings:
  auth: ownerUser
  sequences:
    category: "Feature Demo"
    highlights: ["Stat 1", "Stat 2", "Stat 3"]
  mobile:
    enabled: true
    layout: side-by-side

steps:
  - action: navigate
    path: /dashboard
    waitFor: "heading:Dashboard"
    beat: setup
    annotation: "Monday morning. The user opens the dashboard."
    pacing: slow

  - action: highlight
    selector: "heading:Dashboard"
    beat: payoff
    emphasis: strong
    pacing: dramatic
    annotation: "Everything they need at a glance."

Record it:

DEMO_AUTH_DIR=./e2e/.auth npx tsx runner/record.ts scenarios/my-demo.yaml

Output lands in output/*.mp4.

Scenario actions

Action	Purpose
navigate	Open a URL path
click	Click a selector
type	Type text into an input
scroll	Smooth scroll
pause	Hold for N ms
highlight	Pulsing glow ring on an element
screenshot	Capture a still frame
pom	Call a Page Object Model method (requires DEMO_POM_MODULE)

Every action step accepts annotation, pacing, beat, emphasis, mobileSkip, mobileSelector, mobilePath.

Selectors

Selectors use a prefix convention:

• heading:Dashboard → page.getByRole('heading', { name: 'Dashboard' })
• link:Clients → page.getByRole('link', { name: 'Clients' })
• button:Save → page.getByRole('button', { name: 'Save' })
• placeholder:Search → page.getByPlaceholder('Search')
• testid:pipeline-chart → page.getByTestId('pipeline-chart')
• text:Some text → page.getByText('Some text')
• Any other string is a CSS selector

Voice-over

Voice-over is on by default; disable with DEMO_VOICEOVER=0.

Provider priority (first available wins):

1. Piper — install piper, drop an .onnx voice model in ~/.cache/piper/voices/ (or set PIPER_MODEL=/path/to/voice.onnx).
2. Google Cloud TTS — run gcloud auth application-default login once.
3. OpenAI TTS — set OPENAI_API_KEY.
4. macOS say — zero setup; robotic but always available on macOS.

Modes

• Local (default): connect to a dev server at http://localhost:3000 (or PLAYWRIGHT_BASE_URL).
• Isolated (--isolated): spin up Supabase + Next.js in Docker per recording. Needs Docker running and your app's web/ directory; override location with DEMO_WEB_DIR.
• Preview (--preview --pr <n>): record against a Vercel preview deployment. Needs VERCEL_AUTOMATION_BYPASS_SECRET.

Authentication

Playwright storage state files live at ./web/e2e/.auth/<profile>.json by default. Override with:

DEMO_AUTH_DIR=./my-auth-dir npx tsx runner/record.ts scenarios/my-demo.yaml

Mobile companion