HTML → Video: the pipeline that actually works

Turning a live HTML page into an MP4 sounds like a one-liner ("Playwright records, ffmpeg encodes") and the first draft always looks fine, until you play back the export and notice text flashing in a fallback font, three dead seconds at the start, or a "10-second" clip that clocks in at 35s. This skill captures the specific ordering, waits, and encoder flags that make the output trustworthy.

Think of the pipeline as five phases with a single invariant between them:

launch  →  hold @ frame 0  →  align capture start with animation start  →  record  →  trim & encode

The invariant: no pixel of the animation should render before capture is ready, AND capture must not start before every asset that affects layout has loaded. Every gotcha below is a violation of that invariant.

Quick checklist (each item is expanded below):

1. viewport must exactly equal recordVideo.size, mismatch silently rescales the output soft/blurry.
2. Freeze CSS animations via addInitScript before goto().
3. goto with domcontentloaded, never load.
4. Pre-inline data-composition-src sub-scenes, file:// blocks client-side fetch.
5. Font wait = stylesheet <link> load → face.load() per face → fonts.ready → 2 rAFs.
6. Probe duration with infinite-iteration / repeat: -1 guards.
7. Unfreeze = t=0; trim leadInMs − 120ms with -ss before -i.
8. Concat: same engine → demuxer -c copy; mixed engines → concat filter + re-encode.
9. Verify with ffprobe duration + full decode + sampled frames. Always.

There are two capture modes, and picking the wrong one wastes a day: