html-to-video-pipeline

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:

• Mode A — real-time recordVideo (the phases below). Simple, wall-clock = clip length. But the screencast is best-effort variable frame rate (~25fps) and competes with the animation for CPU. Good enough for previews and ≤30fps deliverables on an idle machine.
• Mode B — deterministic frame stepping (pause everything, seek to i / fps, screenshot, encode the PNG sequence). Exact fps, every frame rendered, no lead-in trim, immune to machine load. Required when the output must be genuinely smooth ≥30fps or renders run on loaded CI. See "Deterministic frame stepping" below.