Video Recording#

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

Requirements#

Recording pipes frames into ffmpeg, which must be on PATH with the libvpx and libx264 encoders (the default builds from Homebrew and Debian/Ubuntu include both):

brew install ffmpeg        # macOS
sudo apt install ffmpeg    # Debian/Ubuntu
agent-browser doctor       # reports ffmpeg and its encoders under "Recording"

The supported formats are .webm (VP8 via libvpx) and .mp4 (H.264 via libx264). Any other extension is handed to ffmpeg as-is with H.264 video, so .mkv or .mov work if ffmpeg knows the container. A path with no extension is rejected before recording starts, since ffmpeg would have nothing to pick a container from. Nothing else in agent-browser needs ffmpeg.

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

record start records the current active page as-is. With no URL, nothing is navigated or replaced: the recorder attaches to the tab you already have open, so capture begins on a hydrated page rather than at load on a cold navigation. With a URL, the active tab navigates there first and recording starts once the page has loaded. No extra tab or browser context is created.

To record in a separate tab, open one first:

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

Visible cursor#

Chrome recordings do not normally include the native pointer. Add --cursor for an animated pointer and click ripple rendered with the page, keeping drags synchronized in every captured frame. The temporary overlay is inert, hidden from accessibility snapshots, and removed when recording stops. Screenshots taken during the recording include it:

agent-browser record start ./walkthrough.webm --cursor

Contact sheets#

Add --contact-sheet for a timestamped PNG with highlighted changes.

agent-browser record start ./checkout.webm --contact-sheet

# Select a frame when at least 2% of pixels change
agent-browser record start ./checkout.webm --contact-sheet-threshold 0.02

The threshold accepts 0 to 1, defaults to 0.05, and implies --contact-sheet. Contact sheets contain at most 100 frames.

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

Valid rates are 1 to 60. The latest Chrome frame is held between repaints so the file duration matches wall clock.

record stop reports frames written to the file and distinct capturedFrames received from Chrome.

Commands#

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#

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. An ffmpeg built without libvpx or libx264 cannot write the matching format; agent-browser doctor reports which encoders are present.