Video Recording

Video Recording

Set record = true on a flow to record the entire flow as a .webm video alongside its screenshots:

[[flows]]
name = "signup-demo"
record        = true
record_width  = 1280   # optional, default 1280
record_height = 720    # optional, default 720
record_mp4    = true   # optional — also convert to mp4 (requires ffmpeg on PATH)

  [[flows.steps]]
  action = "navigate"
  url    = "/signup"

  # ...fill, click, wait, capture steps as usual

Why recording is flow-scoped, not step-scoped

Playwright ties video capture to a BrowserContext, not a page or a step — the .webm file only finalizes once that context closes. It can't be paused or resumed mid-flow. If you only want part of a sequence recorded, split it into multiple flows.

mp4 conversion

record_mp4 shells out to ffmpeg (brew install ffmpeg on macOS) to transcode the .webm to H.264 .mp4 after recording finishes — the same approach shot-scraper's --mp4 flag uses. Without ffmpeg on PATH (or if the conversion itself fails), this reports a clear mp4 conversion failed: ... message on the flow's result rather than shipping a half-converted file — the .webm and every screenshot the flow already captured are still written and returned, not lost. The conversion is also bounded to 5 minutes — a hung/runaway ffmpeg process (a malformed .webm, a pathological codec edge case) is killed rather than left running, reported as ... timed out after 300.0s and was killed. In the ordinary case this never matters; it only shows up as a real limit if a single recording is unusually long or large.

.webm vs .mp4: .webm alone is fine for GitHub READMEs and most embeds, and it's what Playwright gives you with zero extra dependency. Turn on record_mp4 specifically when you need a file for platforms that don't reliably support webm — e.g. direct upload to LinkedIn/YouTube.

Output

docs/screenshots/{flow_name}/{flow_name}.webm
docs/screenshots/{flow_name}/{flow_name}.mp4   # when record_mp4 = true

Linked automatically from the flow's index.md.