Transform Playwright traces into stunning demo videos — automatically.

Your Playwright tests already capture everything — traces, screenshots, network activity, cursor positions. playwright-recast turns those artifacts into polished, narrated product videos with a single fluent pipeline.

Recording product demos is painful. Every UI change means re-recording. Manual voiceover and subtitling takes hours. Timing is always off.

playwright-recast flips this:** your Playwright tests become your video source.** Write tests once, regenerate polished videos on every deploy.

import { Recast, ElevenLabsProvider } from 'playwright-recast'

await Recast
  .from('./test-results/trace.zip')
  .parse()
  .speedUp({ duringIdle: 3.0, duringUserAction: 1.0 })
  .subtitlesFromSrt('./narration.srt')
  .voiceover(ElevenLabsProvider({ voice: 'daniel' }), { normalize: true })
  .render({ format: 'mp4', resolution: '1080p' })
  .toFile('demo.mp4')

That's it. Trace in, polished video out.

• Fluent pipeline API — Chainable, immutable, lazy-evaluated. Build complex pipelines that read like English.
• Trace-based processing — Parses Playwright trace.zip (actions, screenshots, network, cursor positions). No manual recording needed.
• Smart speed control — Automatically speeds up idle time, network waits, and navigation while keeping user actions at normal speed.
• TTS voiceover — Generate narration with OpenAI TTS, ElevenLabs, or Amazon Polly. Properly timed with silence padding.
• Subtitle generation — SRT, WebVTT, and ASS output. Import external SRT or generate from trace BDD step titles.
• Styled subtitle burn-in — Configurable font, size, color, background box with opacity, padding, position. Smart punctuation-based chunking for single-line display.
• playwright-bdd support — First-class integration with playwright-bdd Gherkin steps. Doc strings become voiceover narration.
• Click highlighting — Animated ripple effect at click positions with optional click sound. Configurable color, opacity, radius, duration.
• Cursor overlay — Animated cursor appears before each click, moves to the click position with ease-out animation, then disappears. Bundled arrow cursor or custom image.
• Animated zoom with easing — Auto-zoom uses customizable easing functions (ease-in-out, ease-out, cubic-bezier, or custom JS functions) with smooth zoom-to-zoom panning.
• Frame interpolation — Smooth out choppy browser recordings with ffmpeg minterpolate. Blend, duplicate, or motion-compensated modes with multi-pass support.
• Step helpers — narrate(), zoom(), pace() — importable helpers for Playwright step definitions.
• Background music — Add background music with auto-ducking during voiceover, looping, and fade-out. Covers intro/outro.
• Intro/outro — Prepend/append branded video clips with smooth crossfade transitions. Audio preserved.
• MCP server — AI-assisted video creation via Model Context Protocol. Record, analyze, and render through any MCP-compatible client (Claude Code, etc.).
• recast-studio — Record browser sessions via Playwright Codegen, then generate videos with a Claude Code skill. No code required.
• CLI included — npx playwright-recast -i trace.zip -o demo.mp4 — no code needed.
• Zero lock-in — Every stage is optional. Use just the trace parser, just the subtitle generator, or the full pipeline.

npm install playwright-recast
# or
bun add playwright-recast

System requirement: ffmpeg and ffprobe must be on your PATH.

# macOS
brew install ffmpeg

# Ubuntu
sudo apt install ffmpeg

Trace inputs. Two layouts work:

• Test-results directory (preferred): pass a folder or trace.zip whose sibling is a .webm recorded by Playwright's recordVideo (use: { video: 'on' }). Native frame rate, best quality.
• Standalone trace.zip: pass the zip alone — the pipeline assembles the source video from screencast JPEG frames stored inside the trace. Variable cadence (~capture rate), but works out of the box on traces from the Playwright trace viewer or test runs without recordVideo.

# Basic — trace to video
npx playwright-recast -i ./test-results/trace.zip -o demo.mp4

# With speed processing
npx playwright-recast -i ./traces --speed-idle 4.0 --speed-action 1.0

# With external SRT subtitles
npx playwright-recast -i ./traces --srt narration.srt --burn-subs

# With TTS voiceover (OpenAI)
npx playwright-recast -i ./traces --srt narration.srt --provider openai --voice nova

# With TTS voiceover (ElevenLabs)
npx playwright-recast -i ./traces --srt narration.srt --provider elevenlabs --voice onwK4e9ZLuTAKqWW03F9

import { Recast, OpenAIProvider } from 'playwright-recast'

// Minimal — just trace to video
await Recast.from('./traces').parse().render().toFile('output.mp4')

// Full pipeline
await Recast
  .from('./test-results/')
  .parse()
  .hideSteps(s => s.keyword === 'Given' && s.text?.includes('logged in'))
  .speedUp({
    duringIdle: 4.0,
    duringUserAction: 1.0,
    duringNetworkWait: 2.0,
    minSegmentDuration: 500,
  })
  .subtitlesFromSrt('./narration.srt')
  .voiceover(OpenAIProvider({
    voice: 'nova',
    speed: 1.2,
    instructions: 'Professional product demo narration.',
  }))
  .render({
    format: 'mp4',
    resolution: '1080p',
    fps: 60,
    burnSubtitles: true,
    subtitleStyle: {
      fontSize: 48,
      primaryColor: '#1a1a1a',
      backgroundColor: '#FFFFFF',
      backgroundOpacity: 0.75,
      padding: 20,
      bold: true,
      chunkOptions: { maxCharsPerLine: 55 },
    },
  })
  .toFile('demo.mp4')

Use narrate() and pace() in your BDD step definitions:

// steps/fixtures.ts
import { test } from 'playwright-bdd'
import { setupRecast, narrate, pace } from 'playwright-recast'

setupRecast(test)
export { narrate, pace }

// steps/my-steps.ts
import { Given, When, Then } from './fixtures'
import { narrate, pace } from 'playwright-recast'

Given('the user opens the dashboard', async ({ page }, docString?: string) => {
  narrate(docString)
  await page.goto('/dashboard')
  await pace(page, 4000)
})

Feature: Dashboard demo

  Scenario: View analytics
    Given the user opens the dashboard
      """
      Let's open the analytics dashboard to see real-time metrics.
      """
    When the user clicks the revenue chart
      """
      Clicking on the revenue chart reveals detailed breakdown.
      """

Every stage is optional and composable:

Burn styled subtitles into the video with full control over appearance:

.render({
  burnSubtitles: true,
  subtitleStyle: {
    fontFamily: 'Arial',          // Any system font
    fontSize: 48,                 // Pixels (relative to 1080p)
    primaryColor: '#1a1a1a',      // Text color (hex)
    backgroundColor: '#FFFFFF',   // Box background (hex)
    backgroundOpacity: 0.75,      // 0.0 transparent — 1.0 opaque
    padding: 20,                  // Box padding in px
    bold: true,
    position: 'bottom',           // 'bottom' or 'top'
    marginVertical: 50,           // Distance from edge
    marginHorizontal: 100,        // Side margins (text wraps within)
    wrapStyle: 'smart',           // 'smart', 'endOfLine', 'none'
    chunkOptions: {               // Split long text into single-line chunks
      maxCharsPerLine: 55,        // Split at punctuation when text exceeds this
      minCharsPerChunk: 15,       // Merge tiny fragments
    },
  },
})

Punctuation-based chunking splits long subtitle text into shorter single-line entries. Time is distributed proportionally by character count. Splits at sentence boundaries (. ! ?) first, then clause boundaries (, ; :) if still too long.

Without subtitleStyle, burnSubtitles: true falls back to default ffmpeg SRT rendering.

Clean subtitle text before sending to TTS providers. Removes typographic characters that cause artifacts in voice synthesis while keeping the original text for visual subtitles.

// Built-in sanitization (strips smart quotes, normalizes dashes, etc.)
.textProcessing({ builtins: true })

// Custom regex rules
.textProcessing({
  builtins: true,
  rules: [
    { pattern: '\\bNSS\\b', flags: 'g', replacement: 'Nejvyšší správní soud' },
  ],
})

// Programmatic transform
.textProcessing({
  transform: (text) => text.replace(/\[.*?\]/g, ''),
})

Built-in rules (when builtins: true):

• Remove double quotes: „ " " " « » "
• Remove single quotes: ' ' ‚ ‛ ‹ ›
• Dashes → comma: – — → ,
• Ellipsis: … → ...
• Normalize: NBSP → space, collapse whitespace, trim

Text processing writes to ttsText — the voiceover uses cleaned text while burnt-in subtitles and SRT/VTT output keep the original text.

CLI:

npx playwright-recast -i ./traces --text-processing --provider openai
npx playwright-recast -i ./traces --text-processing-config ./rules.json --provider elevenlabs

import { OpenAIProvider } from 'playwright-recast/providers/openai'

OpenAIProvider({
  voice: 'nova',          // alloy, echo, fable, onyx, nova, shimmer
  model: 'gpt-4o-mini-tts',
  speed: 1.2,
  instructions: 'Calm, professional demo narration.',
})

Requires OPENAI_API_KEY environment variable or apiKey option.

import { ElevenLabsProvider } from 'playwright-recast/providers/elevenlabs'

ElevenLabsProvider({
  voice: 'onwK4e9ZLuTAKqWW03F9',  // Daniel
  model: 'eleven_multilingual_v2',
  languageCode: 'cs',              // Force Czech (ISO 639-1)
  voiceSettings: {
    stability: 0.75,               // Higher = more consistent delivery (less drift)
    similarityBoost: 0.75,
  },
})

Requires ELEVENLABS_API_KEY environment variable or apiKey option.

import { PollyProvider } from 'playwright-recast/providers/polly'

PollyProvider({
  region: 'us-east-1',
  voice: 'Joanna',          // Matthew, Ruth, Stephen, Ivy, Joey, …
  engine: 'neural',         // standard | neural | long-form | generative
  sampleRate: '24000',
  // Credentials are optional — the AWS SDK default chain is used
  // (env vars, ~/.aws/credentials, IAM role on EC2/ECS/Lambda, SSO).
})

Install the SDK alongside this package:

npm install @aws-sdk/client-polly

Resolves credentials from AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY (and optional AWS_SESSION_TOKEN), shared config, or — preferred on AWS — an attached IAM role.

TTS providers (especially ElevenLabs on eleven_multilingual_v2 + non-English languages) can deliver segments at wildly different levels — one line at −16 LUFS, the next at −32 LUFS. Enable opt-in per-segment normalization to fix it:

.voiceover(ElevenLabsProvider({ voice: 'daniel' }), { normalize: true })

This runs each synthesized segment through two-pass EBU R128 loudnorm before concat. Defaults: −16 LUFS integrated, −1 dBFS true peak, 11 LU range, linear mode (preserves dynamics). Override any of them:

.voiceover(provider, {
  normalize: {
    targetLufs: -18,
    truePeakDb: -1.5,
    lra: 11,
    linear: true,
  },
})

Also exported standalone for external use:

import { normalizeLoudness } from 'playwright-recast'
await normalizeLoudness('input.mp3', 'output.mp3', { targetLufs: -16 })

Zoom into specific areas of the video during steps — focus the viewer's attention on the relevant UI element.

Automatically zoom into input elements (fill/type actions) detected from the Playwright trace. Zoom window follows the actual action duration — zooms in when the user starts typing, zooms out when they move on. Smooth fade transitions between zoom states.

await Recast
  .from('./traces')
  .parse()
  .subtitlesFromSrt('./narration.srt')
  .autoZoom({
    inputLevel: 1.4,    // zoom level for fill/type actions
    clickLevel: 1.0,    // 1.0 = no zoom on clicks (default)
    centerBias: 0.3,    // blend coordinates toward center (0–1)
  })
  .render({ format: 'mp4' })
  .toFile('demo.mp4')

autoZoom() finds click/fill/type actions in the trace, extracts their cursor coordinates, and applies crop-and-scale zoom during the matching subtitle's time window.

Apply zoom coordinates from an external source (e.g., a demo report with per-step zoom data):

const reportSteps = [
  { zoom: null },                            // Step 1: no zoom
  { zoom: { x: 0.5, y: 0.8, level: 1.4 } }, // Step 2: zoom to input area
  { zoom: null },                            // Step 3: no zoom
  { zoom: { x: 0.78, y: 0.45, level: 1.3 }}, // Step 4: zoom to sidebar
]

await Recast
  .from('./traces')
  .parse()
  .subtitlesFromSrt('./narration.srt')
  .enrichZoomFromReport(reportSteps)
  .render({ format: 'mp4' })
  .toFile('demo.mp4')

Capture zoom coordinates during Playwright test execution using the zoom() helper:

import { zoom } from 'playwright-recast'

When('the user opens the sidebar', async ({ page }) => {
  const sidebar = page.locator('.sidebar-panel')
  await zoom(sidebar, 1.3) // Record zoom target for this step
  await sidebar.click()
})

The helper captures the element's bounding box as a Playwright annotation. Use enrichZoomFromReport() to apply these coordinates during video generation.

All zoom coordinates use viewport-relative fractions (0.0–1.0):

The renderer applies zoom by cropping the video to (width/level × height/level) centered at (x, y), then scaling back to the output resolution.

Highlight click actions with animated ripple effects and optional click sounds.

await Recast
  .from('./traces')
  .parse()
  .clickEffect({
    color: '#3B82F6',    // Ripple color (hex, default: blue)
    opacity: 0.5,        // Ripple opacity 0.0–1.0
    radius: 30,          // Max radius in px (relative to 1080p)
    duration: 400,       // Animation duration in ms
    sound: true,         // true = bundled default, or path to custom audio
    soundVolume: 0.8,    // Sound volume 0.0–1.0
  })
  .render({ format: 'mp4' })
  .toFile('demo.mp4')

The click effect stage automatically detects click and selectOption actions from the Playwright trace. Timestamps are remapped through speed processing so ripples appear at the correct video time.

Filtering clicks:

.clickEffect({
  filter: (action) => action.method === 'click', // Only clicks, not selectOption
})

CLI:

npx playwright-recast -i ./traces --click-effect
npx playwright-recast -i ./traces --click-effect --click-sound click.mp3
npx playwright-recast -i ./traces --click-effect-config config.json

Generate smooth intermediate frames from choppy browser recordings using ffmpeg's minterpolate filter.

await Recast
  .from('./traces')
  .parse()
  .interpolate({
    fps: 60,              // Target FPS (default: 60)
    mode: 'blend',        // 'dup' | 'blend' | 'mci' (default: 'mci')
    quality: 'balanced',  // 'fast' | 'balanced' | 'quality' (default: 'balanced')
    passes: 1,            // Multi-pass for smoother results (default: 1)
  })
  .render({ format: 'mp4' })
  .toFile('demo.mp4')

With passes: 2, FPS is distributed geometrically across passes (e.g., 25fps -> 39fps -> 60fps). Each pass interpolates already-smoothed frames for a cleaner result.

CLI:

npx playwright-recast -i ./traces --interpolate
npx playwright-recast -i ./traces --interpolate --interpolate-fps 30
npx playwright-recast -i ./traces --interpolate --interpolate-mode blend --interpolate-passes 2

The speed processor classifies every moment of the trace:

.speedUp({
  duringIdle: 4.0,
  duringUserAction: 1.0,
  duringNetworkWait: 2.0,
  duringNavigation: 2.0,
  minSegmentDuration: 500,  // Avoid jarring speed changes
  maxSpeed: 8.0,            // Safety cap
})

Trace.zip → ParsedTrace → FilteredTrace → SpeedMappedTrace → SubtitledTrace → VoiceoveredTrace → MP4
               ↑               ↑                ↑                  ↑       ↑          ↑              ↑
            parse()       hideSteps()        speedUp()         subtitles() textProcessing() voiceover()  render()

The pipeline is lazy — calling chain methods builds a pipeline description. Nothing executes until .toFile() or .toBuffer() is called.

Each pipeline instance is immutable — every method returns a new pipeline, so you can branch:

const base = Recast.from('./traces').parse().speedUp({ duringIdle: 3.0 })

// Branch A: with voiceover
await base.subtitlesFromSrt('./en.srt').voiceover(openai).render().toFile('demo-en.mp4')

// Branch B: subtitles only
await base.subtitlesFromSrt('./cs.srt').render({ burnSubtitles: true }).toFile('demo-cs.mp4')

playwright-recast includes an MCP (Model Context Protocol) server for AI-assisted video creation. Any MCP-compatible client (Claude Code, Cursor, etc.) can record browser sessions, analyze traces, and render polished videos through a conversational workflow.

Typical workflow: record_session --> analyze_trace --> (edit voiceover text) --> render_video

Add to your project's .mcp.json:

{
  "mcpServers": {
    "recast": {
      "command": "npx",
      "args": [
        "-y",
        "-p", "playwright-recast",
        "-p", "@playwright/test",
        "-p", "openai",
        "-p", "@elevenlabs/elevenlabs-js",
        "recast-mcp"
      ],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "RECAST_RESOLUTION": "1080p",
        "RECAST_WORK_DIR": "."
      }
    }
  }
}

Environment variables:

TTS provider is auto-detected from available API keys when RECAST_TTS_PROVIDER is not set.

Contributions welcome! Please check the issues for open tasks.

git clone https://github.com/ThePatriczek/playwright-recast.git
cd playwright-recast
npm install
npm test

MIT