Video Recording#

Use record to capture browser automation as a WebM video for debugging, CI evidence, product walkthroughs, or repro reports.

Basic workflow#

agent-browser open https://example.com
agent-browser record start ./demo.webm
agent-browser snapshot -i
agent-browser click @e1

agent-browser record stop

After launching a session, record start can also navigate immediately:

agent-browser open
agent-browser record start ./demo.webm https://example.com

If no URL is provided, recording starts from the current page. The recording context copies cookies from the active session.

Frame rate#

Recording captures 30 frames per second by default, which is enough for scrolling, hover states, and CSS transitions to read as motion rather than as a slideshow. Use --fps to change it:

# 60 fps for a short, motion-heavy take
agent-browser record start ./scroll.webm --fps 60

# 10 fps for a long soak run where file size matters more than motion
agent-browser record start ./soak.webm --fps 10

Rate	When to use it
60	Drag interactions, animation and scroll polish work, anything where a single frame is the evidence. Best on short clips.
30 (default)	Everything else: flows, CI evidence, walkthroughs.
1 to 15	Long sessions where the video is a timeline rather than a motion study.

Valid rates are 1 to 60. Frames come from Chrome's screencast, so every repaint up to the display rate is captured and a 60 fps take of a scroll holds 60 distinct pictures per second. While the page is static the last frame is held, so the file's duration matches wall clock; a gap longer than five seconds is held for five and the rest left out.

record stop reports frames (written to the file) and capturedFrames (distinct frames the page produced). A static page shows a small capturedFrames against a full frames count; that is the hold working.

Commands#

Command	Description
`record start <path.webm> [url] [--fps <n>]`	Start recording to a WebM file
`record stop`	Stop the active recording and save the file
`record restart <path.webm> [url] [--fps <n>]`	Stop the current recording and immediately start another

CI evidence#

#!/bin/bash
set -e

cleanup() {
  agent-browser record stop 2>/dev/null || true
  agent-browser close 2>/dev/null || true
}
trap cleanup EXIT

agent-browser open https://app.example.com/login
agent-browser record start "./artifacts/login-flow.webm"
agent-browser snapshot -i
agent-browser fill @e1 "demo@example.com"
agent-browser fill @e2 "password"
agent-browser click @e3
agent-browser wait --url "**/dashboard"

Keep recordings as CI artifacts when browser failures are hard to diagnose from text output alone.

Human-readable demos#

Add small waits when the video is meant for a person to watch:

agent-browser open https://shop.example.com
agent-browser record start ./checkout.webm
agent-browser wait 500
agent-browser click @e4
agent-browser wait 500
agent-browser screenshot ./screenshots/cart.png
agent-browser record stop

Screenshots and videos work well together: screenshots capture precise still states, while the video shows timing, transitions, and unexpected overlays.

Output format#

Property	Value
Container	WebM
Common extension	`.webm`
Frame rate	30 fps by default, 1 to 60 with `--fps`
Viewport	Uses the active browser viewport settings
State	Copies cookies from the active session

Limitations#

Recording adds overhead to automation, and higher frame rates add more.
Long recordings can use significant disk space; 60 fps roughly doubles the bitrate of 30 fps.
Distinct frames per second are bounded by how often the page repaints, so a page that renders below 60 fps records below it too.
Use record stop before closing a session if you need the file flushed.
Some constrained headless environments may have codec or GPU limitations.