Browser Demo Recording with Playwright — replay-first pipeline

Record browser demos using Playwright Python. Each demo lives in its own dated-slug folder docs/demos/YYYYMMDD-<slug>/ — the same parent as CLI demos produced by /create-vhs. The pipeline is replay-first: network responses are captured once via HAR on a live app, then a YAML spec drives driver generation, recording, and narration. Iteration is fast and timing is deterministic.

Pipeline

              (one-time, slow)
   scenes.yaml + live app  -->  outputs/*.har       [HAR capture phase]
                                        |
              (instant)                 v
   scenes.yaml  +  outputs/*.har  -->  pw_compile.py  -->  driver.py + cards/*.html + compiled.json
                                        |
              (~recording length)       v
                                     uv run driver.py  -->  recording.webm
                                        |
              (~5s, codec swap)         v
                                     ffmpeg -c:v libx264 ...  -->  recording.mp4
                                        |
              (~30s, cached per text)   v
                                     narrate.py compiled.json  -->  voice/*.mp3 + recording-narrated.mp4
                                        |
              (manual)                  v
                                     upload to YouTube

pw_compile.py, the driver, and narrate.py are all idempotent. The slow step is the initial HAR capture; everything downstream re-runs in seconds.

Output Layout

storage_state.json MUST be gitignored — it can contain bearer tokens.

Arguments

• <scenario-name>: Slug for the demo (e.g. gui-agent-create). Must match ^[a-zA-Z0-9_-]+$. The skill prefixes today's date as YYYYMMDD → docs/demos/YYYYMMDD-<scenario-name>/.
• --description: Optional one-liner of what the demo should show.

Required Up-Front Questions

MANDATORY: Before scaffolding any file, ask the user via AskUserQuestion. Do not assume defaults.

1. Target app & base URL — the URL the demo opens against (base_url).
2. Auth model
   • Anonymous — no login needed (most landing/marketing demos).
   • Pre-authenticated session — operator runs playwright codegen --save-storage outputs/storage_state.json <base_url> once; the driver loads it before scenes.
   • Live login flow — login is itself a scene (avoid for committed demos; secrets leak into HAR).
3. Scene plan — ordered list of scene titles + actions. There is no fixed Scene 1 (unlike /create-vhs which anchors on clawctl --version); choose what anchors the recording.
4. HAR strategy per scene — for each scene whose network responses you want frozen, confirm a HAR file path. Scenes without har: execute live.
5. Long-flow handling — for any scene whose interaction takes more than ~15 seconds on screen, confirm whether to split into sub-scenes or use the speed_up: multiplier (post-record ffmpeg pass).
6. Any other unclear input — never invent prerequisites.

Universal Flow

Step 1 — Run the prereq validator

bash "$(git rev-parse --show-toplevel)/.claude/skills/create-playwright/scripts/check-prereqs.sh"

Checks python3, uv, system ffmpeg, jq, a system Chrome binary (google-chrome / chromium), and that Playwright (>=1.40) can resolve plus its bundled ffmpeg is present at ~/.cache/ms-playwright/ffmpeg-*/. Stop immediately if any are missing.

Installation hints surfaced by the check:

• playwright install ffmpeg downloads the bundled video-encoder ffmpeg (separate from system ffmpeg — Playwright needs its own for record_video_dir).
• Ubuntu 26.04 isn't on Playwright's supported-OS matrix yet. Prepend PLAYWRIGHT_HOST_PLATFORM_OVERRIDE=ubuntu24.04-x64 to the install command; the 24.04 binaries run fine on 26.04. The prereq check detects this OS and emits the override automatically.
• The driver intentionally launches system Chrome via chromium.launch(channel="chrome") rather than Playwright's bundled Chromium. This sidesteps the OS-matrix problem for the browser binary itself and produces identical recordings. The only Playwright-bundled binary you still need is ffmpeg.

Step 2 — Author scenes.yaml

Copy .claude/skills/create-playwright/templates/scenes.yaml.template to docs/demos/YYYYMMDD-<scenario-name>/scenes.yaml and fill in title, subtitle, base_url, intro/outro narration, and the scene list.

Action verbs supported by the driver (mapped 1:1 to Playwright Page methods):

Avoid wait: (raw sleeps) — Playwright's auto-wait via wait_for: is deterministic and faster.

Get explicit user approval on scenes.yaml before capturing HARs.

Step 3 — Capture HARs (one-time, on a live app)

For each scene that declares har:, run the capture pass. pw_compile.py --capture generates a stripped-down capture-only driver that emits HARs without recording video:

NAME=YYYYMMDD-<scenario-name>
mkdir -p docs/demos/$NAME/outputs

uv run docs/demos/lib/pw_compile.py docs/demos/$NAME --capture
uv run docs/demos/$NAME/driver_capture.py

The capture pass opens a real Chromium window (headed by default), executes every scene's actions, and writes one HAR per scene to outputs/NN-<slug>.har.

Scrub secrets from HARs before committing:

• Bearer tokens in Authorization headers
• Session cookies
• PII in request/response bodies

A scripted jq pass works:

jq '(.log.entries[].request.headers[] | select(.name | ascii_downcase == "authorization")).value = "Bearer REDACTED"' \
  docs/demos/$NAME/outputs/02-foo.har > /tmp/scrubbed.har && mv /tmp/scrubbed.har docs/demos/$NAME/outputs/02-foo.har

Re-capture cadence: when the app's API shape or UI structure changes, when selectors used in scenes.yaml no longer resolve, or per release tag.

Step 4 — Compile

uv run docs/demos/lib/pw_compile.py docs/demos/YYYYMMDD-<scenario-name>

uv resolves PEP 723 deps (pyyaml, jinja2) on first run. Outputs:

• driver.py — self-contained Playwright Python script. Header banner says "GENERATED — DO NOT EDIT".
• cards/title.html, cards/outro.html — rendered from the YAML title/subtitle/outro.
• compiled.json — flat list of every narration beat with its absolute timestamp in the rendered recording.

The script prints the recording duration estimate and a per-beat timeline. Verify these match what you expect before recording.

Step 5 — Record

uv run docs/demos/YYYYMMDD-<scenario-name>/driver.py

The driver:

1. Opens Chromium at the configured viewport (tape.width × tape.height).
2. Optionally loads outputs/storage_state.json for auth.
3. Plays the title card HTML for intro.title_card.hold_seconds.
4. For each scene: applies route_from_har (if har: set), executes actions, holds for screen_seconds.
5. Plays the outro card.
6. Closes the context; Playwright finalizes recording.webm.

Then transcode to MP4:

ffmpeg -y -i docs/demos/YYYYMMDD-<scenario-name>/recording.webm \
       -c:v libx264 -pix_fmt yuv420p -crf 20 -preset slow \
       docs/demos/YYYYMMDD-<scenario-name>/recording.mp4

The driver runs this transcode automatically at the end of its run; the standalone command above is for manual re-runs.

Step 6 — Layer narration (ElevenLabs)

Identical to /create-vhs — narrate.py is reused unchanged:

uv run docs/demos/lib/narrate.py docs/demos/YYYYMMDD-<scenario-name>
  [--force]              # regenerate ALL clips even if cached
  [--skip-mux]           # generate audio only; skip ffmpeg
  [--input recording.mp4 --output recording-narrated.mp4]

The cache key (sha1(voice_id + text)) and timeline contract (compiled.json) are unchanged.

Step 7 — Iterate

Step 8 — Upload (out of skill scope)

You upload recording-narrated.mp4 to YouTube. The skill does not push.

Configuration

narrate.py configuration is unchanged from /create-vhs (.env-based, ElevenLabs).

scenes.yaml tape: block:

Cards as HTML

Title and outro cards are full-screen HTML rendered in the same Playwright context. The Jinja templates at docs/demos/lib/cards/{title,outro}.html.j2 receive:

• title (string)
• subtitle (string)
• outro.line_1, outro.line_2 (strings, outro only)
• theme — currently fixed to "dark"; matches Catppuccin Mocha palette used in CLI demos for brand parity.

You can hand-edit the rendered cards/*.html for one-off visual tweaks, but a recompile overwrites them. Prefer editing the .j2 template or YAML fields.

Production Quality

• reduced_motion: reduce kills CSS transitions/animations the browser would render non-deterministically.
• HAR replay catches 99% of HTTP traffic but does NOT capture WebSocket frames (Playwright limitation as of writing). Apps with WS-heavy UI (live dashboards, chat) should record live or mock WS via page.route + custom handler — call this out at scene authoring time.
• Custom webfonts may fall back to default fonts in headless mode. Run headed if pixel-perfect type matters, or pre-load fonts via page.add_style_tag().
• Cookie/auth secrets: NEVER commit storage_state.json. NEVER let live-login HAR ship — the Authorization header will be in the captured response chain.
• One demo = one app state. Don't try to demo "create then delete" in one HAR — the HAR captured at create-time doesn't have the delete responses. Split into two scenes with separate HARs, or run that scene live.
• Viewport ≥ 1400×900 for desktop apps; smaller viewports require scenes designed for them (tape.width: 1024 etc.).

Troubleshooting

File Organization

docs/demos/
├── lib/                              # committed — shared, all demos
│   ├── cards.sh                      # used by create-vhs CLI demos
│   ├── cards/                        # used by create-playwright (this skill)
│   │   ├── title.html.j2
│   │   └── outro.html.j2
│   ├── compile.py                    # create-vhs compiler
│   ├── pw_compile.py                 # THIS skill — scenes.yaml -> driver.py + cards/*.html + compiled.json (PEP 723; uv run)
│   ├── pw_driver.py.j2               # THIS skill — Jinja template for the generated driver
│   ├── narrate.py                    # REUSED — compiled.json -> voice/*.mp3 + recording-narrated.mp4
│   ├── .env.example                  # REUSED — ElevenLabs credentials template
│   └── .env                          # GITIGNORED — real ELEVENLABS_API_KEY etc.
└── YYYYMMDD-<slug>/                  # one folder per demo (CLI or browser)
    ├── scenes.yaml                   # committed — SOURCE OF TRUTH
    ├── outputs/                      # committed except storage_state.json
    │   ├── 01-landing.har
    │   ├── 02-create-agent.har
    │   └── storage_state.json        # GITIGNORED — contains auth tokens
    ├── driver.py                     # committed (generated) — Playwright script
    ├── cards/
    │   ├── title.html                # committed (generated)
    │   └── outro.html                # committed (generated)
    ├── compiled.json                 # committed (generated) — narration timeline
    ├── voice/                        # GITIGNORED — per-beat TTS clips
    │   └── scene-NN-beat-MM-<sha8>.mp3
    ├── recording.webm                # GITIGNORED — Playwright direct output
    ├── recording.mp4                 # GITIGNORED — ffmpeg-transcoded H.264
    └── recording-narrated.mp4        # GITIGNORED — final with voiceover

Symmetry with /create-vhs

References

External best-practice sources consulted:

• Playwright Python docs — video recording
• Playwright Python docs — network replay via route_from_har
• Playwright Python docs — codegen + storage state
• HAR 1.2 spec
• ElevenLabs Python SDK
• PEP 723 — inline script metadata

Prompt Logging

REQUIRED: Append prompt log to .itx/<N>/03_DEMO.md if recording as part of an issue.

See AGENTS.md for format specification.