Playhead

Getting started

One command installs the CLI and wires your coding agent. Two more take you from a URL to a verified MP4.

Install#

Playhead is a single npm package with a CLI. Node 20 or newer, on macOS, Linux or Windows.

npx playhead init

With no path argument, init does the whole first-run setup: it registers an MCP server and skills for Cursor, Claude Code and Codex (writing .cursor/mcp.json, .mcp.json, .codex/config.toml and a Playhead section in AGENTS.md), installs Chromium, and downloads the offline narration voice.

FlagWhat it does
--no-ttsSkip the Kokoro voice (~400MB one-time). Narration then needs macOS `say`, or nothing at all.
--no-browserSkip the Chromium download — for images that already ship it, like the Playwright base image.
--forceOverwrite the managed skills and the Playhead section of AGENTS.md.
--url <url>Only with a spec path: explore that running app and scaffold the spec from real locators.

Or install it globally#

npm install -g playhead-cli
npx playwright install chromium

Check the machine#

Rendering needs ffmpeg, a browser, and fonts. doctor reports all three plus the optional pieces — narration providers, the local vision reviewer, signing prerequisites — and tells you the exact command to fix anything missing.

playhead doctor          # or --ci to also check container prerequisites
  ✓ tts (kokoro): kokoro-js installed — the natural offline voice is available
  ✓ ffmpeg: ffmpeg version 6.1.1
  ✓ chromium: …/chrome-win64/chrome.exe
  ✓ fonts: Inter registered
  ✓ vision: Ollama reachable — render --vision stays on-machine
ffmpeg and ffprobe ship with the package. You do not need them on your PATH — the binaries come from ffmpeg-static and ffprobe-static. If doctor reports a problem there, it is a broken install rather than a missing system dependency.

Render something, right now#

The fastest honest path is to record yourself using your own app. A browser opens; you drive the flow like a user; every interaction becomes a validated step.

playhead record http://localhost:3000 -o demo.yaml
playhead validate demo.yaml
playhead render demo.yaml -o out

Behind a login wall, save a session first. Playhead never sees the password — you type it into a real browser, and only the resulting cookies are written to disk.

playhead login https://app.example.com
playhead record https://app.example.com --storage-state playhead-session.json -o demo.yaml

What you get#

PathWhat it is
out/out.mp4The finished 1080p walkthrough: title card, planned camera moves, rendered cursor, numbered captions, narration.
out/capture/The re-renderable capture bundle — frames, events.json, manifest. The only artifact that ever touched your app.
out/compose-manifest.jsonEverything the compositor rendered, and the contract verification checks against.
out/verify/verdict.jsonpublishable or not-publishable, with per-check reasons, coverage and hashes.
out/verify/contact-sheet.pngKey moments as an annotated grid, so you can trust the output without watching it end to end.
out/evidence/index.htmlA relocatable page with the video, the steps and the verdict — the thing you paste into a ticket.
out/bug-report.mdWritten for kind: bug-repro: URL, steps with timecodes, and the captured console — a ticket body, not just a clip.

render exits 0 only when the verdict is publishable, which is what lets it double as an end-to-end test. See what each check asserts →

Try it against the bundled demo app#

Cloning the repository gets you a deliberately awkward demo app — a modal that paints in the browser top layer, network latency, a toast, masked fields, a long scroll — so you can watch the pipeline handle the hard parts.

git clone https://github.com/Cypher-aman/playhead && cd playhead
npm install && npx playwright install chromium
npm run demo &                 # http://localhost:4173
npm run playhead -- render specs/examples/add-user.yaml -o out

Where to go next#