Playhead

Product video as a build artifact, not a performance.

Give Playhead a small spec and a URL. It drives your real app, films clean footage, composes the video, and reviews its own output before handing you a publishable MP4.

npm install -g playhead-cli
00:00.0spec.yamlsmall, reviewable, lives in your repo
00:02.4captureyour real app, real input, event log
00:09.8composecamera, cursor, captions — re-renderable
00:31.5verifyten checks against the delivered pixels
00:31.9out.mp4plus verdict.json — publishable, or told why not
00:47.2

Capture once, compose forever.

The capture bundle is the only artifact that touches your app. Presentation — camera, captions, voice — is applied at compose time, so changing words or voices never means re-recording.

V1
Film the real app

Playwright-driven capture with grounded locators — by role, label, and text, straight through shadow DOM. No mockups, no drift from the product.

V2
Compose, and re-compose

Planned camera moves, a synthesized cursor, auto-written captions. Edit the spec and re-render in seconds — the app is never touched again.

A1
Voice at compose time

Narration is spoken per step — macOS voices or the natural Kokoro model, offline. Audition a line with playhead say before committing.

It reviews its own output

Ten deterministic checks on the delivered pixels: targets framed, clicks landed and effective, no frozen footage, narration audible. Exit 0 only when the verdict is publishable.

01:12.6

Exit codes are a contract.

A video you can trust in an automated pipeline, without a human watching it end to end. Verification writes a signed verdict and a contact sheet of key moments.

passtarget-in-frame — 8/8 targets fully framed
passcursor-on-target — 3/3 clicks land, sprite on film
passaction-effect — every click visibly changed the UI
passfrozen-blank — footage live, content regions painted
passaudio — 6 lines audible, −16 LUFS
✓ verdict: publishable
0publishable — ship it
1the app broke the flow — failure clip rendered
2rendered, but failed verification
3infrastructure problem
4bad spec or arguments
01:38.0

You never hand-write a locator.

rec
playhead record — author by doing

A browser opens. Click through your flow like a user; every interaction becomes a validated step. Press Enter, get a spec.

cmd
playhead demo — one command to video

URL in, verified MP4 out. Works with no API key at all — it explores your app and grounds the spec itself.

yaml
playhead explore — write it yourself, grounded

Every addressable element on the page as a ready-to-paste locator, grouped by toolbar, with camera focus targets included.