agent-browser Video Recording FPS

Pick the frame rate from the review question

Start at 30 fps. It is the new default because ordinary clicks, hover states, scrolling, CSS transitions, and walkthroughs remain readable without taking on the extra load of 60 fps.

The valid --fps range is 1 through 60. A higher number is not automatically stronger evidence. If the page repaints less often than the requested rate, asking for 60 fps cannot create 60 genuinely different page states.

What changed in v0.37.0

The recorder now treats video as a timed view of the page you are actually using. record start and record restart capture the current active page at 30 fps by default, accept --fps 1-60, and use Chrome's Page.startScreencast. That is Chrome's own feed of repainted page frames, like wiring a camera directly to the browser's display pipeline instead of taking occasional screenshots.

The v0.37.0 release also tightened failure behavior. Missing ffmpeg, an output path with no extension, or an invalid recording option fails before the browser or recording state changes. If a replacement take fails to start, the active take is preserved. Navigation while recording now clears stale element references and frame state in the same way normal navigation does.

This matters in a real QA loop. A bad video path should not silently change the page under test, and starting a second take should not destroy the first one before the replacement is known to work.

The five-step recording workflow

The reliable sequence is check, open, record, assert, stop. The final command is part of the evidence contract because it flushes and saves the file.

agent-browser doctor
agent-browser open https://app.example.com/login
agent-browser record start ./login-flow.mp4 --fps 30
agent-browser snapshot -i
agent-browser click @e1
agent-browser wait --url "**/dashboard"
agent-browser record stop

1. Check the encoder first. agent-browser doctor reports ffmpeg and its recording encoders. MP4 needs libx264; WebM needs libvpx. A standard Homebrew or Debian/Ubuntu ffmpeg build normally includes both.

2. Put the right page in the active tab. With no URL on record start, the recorder attaches to the active page exactly as it is. It does not reload it, open a new tab, or create a clean browser context. That is useful when the bug depends on a hydrated app, an authenticated session, or in-page state. If you include a URL, the active tab navigates first and recording begins after the page loads.

3. Choose the container by extension. .mp4 selects H.264 through libx264; .webm selects VP8 through libvpx. Other extensions go to ffmpeg with H.264 and only work if ffmpeg knows the container. A filename with no extension is rejected.

4. Keep the pass/fail check in the automation. In the example, wait --url checks whether the browser reached the dashboard. The clip helps a person understand what happened. It does not turn pixels into a test assertion.

5. Stop before closing. record stop saves and flushes the take. Closing the session first can leave you without the file you meant to keep. Use record restart when you want to close one take and immediately begin the next on the active page.

capturedFrames and frames answer different questions

Read the two counters as source material and finished footage. capturedFrames counts distinct frames the page produced. frames counts the frames written into the video file. A static page can produce very few distinct pictures while ffmpeg writes repeated frames to keep the take watchable.

There is one important timing caveat. When the page stops changing, the last frame is held. A single static gap is held for up to five seconds, then the rest of that unchanged stretch is omitted. In practice, the video preserves short pauses but compresses long idle gaps. Do not use the playback duration as a stopwatch for a soak test.

This is why a low capturedFrames count is not automatically a recording failure. It can mean the page was simply still. It is also why 60 fps should be reserved for motion that deserves inspection: the recording guide says 60 fps roughly doubles the bitrate of 30 fps, while the number of distinct frames still depends on page repaints.

The budget line that changes

If your team already runs agent-browser, basic video evidence no longer has to begin with another recorder seat. The v0.37.0 package declares an Apache-2.0 license, so the recorder itself has no per-user software license. The incremental costs are the things you operate: ffmpeg setup, CI time, artifact storage, and the minutes a person spends reviewing the result.

That is meaningfully different from buying a full feedback or testing platform. Jam Team lists $14 per creator per month on annual billing. BugHerd Standard lists $50 per month for five members on monthly billing and includes video feedback. BrowserStack Automate lists one Chrome Desktop parallel at $59 per month billed annually and includes video recordings among its debugging tools.

Those products sell more than recording, so replacing them is the wrong conclusion. BrowserStack sells managed browser coverage. BugHerd and Jam sell collaboration, issue capture, and integrations. The useful cost decision is narrower: do not buy a second capture layer when agent-browser already runs the flow and the missing artifact is simply a readable video.

Seven use cases, ranked by who gains most

1. Product teams diagnosing failed CI flows

A product team with a flaky login or checkout test can start a 30 fps recording immediately before the risky path, keep its URL or element assertions in place, and retain the MP4 as a CI artifact when the run fails. The engineer sees the consent banner, late overlay, focus jump, or transition that a text log may miss. The payoff is fewer paid engineering minutes spent trying to recreate an intermittent state.

2. Front-end teams reviewing drag, scroll, and animation behavior

A front-end engineer can isolate one short interaction and capture it at 60 fps, then pair the clip with screenshots of the start and end states. The video answers whether the motion between those states was clean; the screenshots preserve exact pixels. This pays when the defect lives between two screenshots, such as a dropped frame or a drag target crossed at the wrong moment.

3. AI product teams auditing browser-agent behavior

An AI product team can record the active authenticated page at 30 fps while its agent follows a task, then attach the video beside the agent's command trace and assertions. A reviewer can distinguish a bad plan from a page that changed under the agent. That turns an opaque run into evidence a product manager and engineer can discuss together.

4. QA engineers reproducing state-dependent bugs

A QA engineer can prepare the session until the bug's preconditions exist, then run record start without a URL. Because recording attaches in place, the page is not replaced by a cold navigation. This pays when a bug depends on accumulated cart state, a modal, an authenticated route, or another condition that disappears on reload.

5. Agencies handing a release to a client

A web agency can record a 30 fps acceptance path, add short waits at decision points, and give the client a clip that is paced for a person rather than an automation engine. The client can review the exact path without getting access to the test runner. The agency spends less meeting time narrating a flow that the artifact already shows.

6. Reliability teams keeping long-run timelines

A reliability engineer can record a long soak at 10 fps when sequence matters more than motion. The lower rate reduces recording overhead and file growth compared with 30 or 60 fps. The take remains useful for locating the visible moment of failure, but its compressed static gaps mean timestamps must come from logs, not playback length.

7. Support engineers escalating a hard browser issue

A support engineer can reproduce a customer path in a controlled account, record it at 30 fps, stop the take, and attach it to the escalation. The development team receives the timing and unexpected overlays that a written ticket often loses. This only pays if the workflow also prevents secrets and customer data from entering the recording.

Three products worth building

Best opportunity: an agent-run evidence pack

Build a small service that turns one browser-agent run into a single review packet: assertion result, command trace, final screenshot, MP4, frame counters, and a link posted to Jira or Linear. Product and engineering teams would pay because the output fits the issue workflow they already use.

The demand is concrete. U.S. keyword data shows about 590 searches a month for “bug reporting tool”, with a $43.80 CPC. Existing spend is visible too: Jam Team is $14 per creator per month on annual billing, while BugHerd Standard is $50 per month on monthly billing. The smallest sellable version needs one agent-browser wrapper, artifact storage, one issue-tracker integration, and a redaction checklist.

This is the strongest opportunity because it sells the handoff, not the codec. The catch is a shallow technical moat. Jira posting and video storage are easy to copy, so the product must get unusually good at assembling trustworthy context and keeping sensitive data out.

An agency QA handoff portal

Build a client-facing review page where an agency chooses a flow, runs it against staging, and publishes the assertion, screenshots, and paced video under one approval link. Agencies and fractional QA teams are the buyer because client sign-off is where technical evidence often becomes a meeting.

U.S. keyword data shows 110 searches a month for “website qa testing”, up 55% year over year, with a $23.91 CPC. An MVP could support a few reusable flows, 30 fps capture, comments, and approve or reject. The catch is incumbent depth: BugHerd already bundles unlimited projects, client users, screenshots, metadata, and video feedback on its Standard plan. The new product has to win on agent-produced evidence, not another comment pin.

A motion-test preset layer

Build a thin CI tool that labels tests as timeline, default, or motion, maps them to 10, 30, or 60 fps, and flags surprising gaps between captured and written frames. Front-end platform teams would pay for consistent evidence across animation and interaction regressions.

U.S. keyword data shows 110 searches a month for “automated browser testing” with a $14.96 CPC. The narrower commercial phrase “automated browser testing tools” has only 20 monthly searches but a $63.21 CPC, a sign that the small buyer pool is expensive to reach. The MVP is a test manifest, an agent-browser command wrapper, retained clips only on failure, and a compact artifact index.

The catch is weaker momentum: the broader keyword is down 18% year over year, and 60 fps adds overhead while still being limited by page repaint rate. This should begin as a feature inside an evidence product, not a standalone company.

What the recording does not prove

Video is observability, not correctness. It cannot tell you that the right database row was written, that an API response was valid, or that every browser and device behaves the same way. Keep assertions, logs, and screenshots beside it.

It also does not remove environment risk. Recording needs ffmpeg on PATH and the matching encoder. Higher frame rates add overhead, long recordings consume disk, and constrained headless machines can have codec or GPU limits. A page that repaints slowly cannot supply 60 distinct frames every second.

Treat privacy as a product requirement. The recorder captures the active viewport and in-page state, which is precisely why it is useful and why test accounts, secret masking, artifact retention, and access control need deliberate rules. That is operational judgment, not a built-in redaction promise.

Finally, agent-browser records the evidence but does not interpret it. If you want a model to inspect the footage after the run, that is a separate system, closer to agentic video understanding. Keep that layer separate from the deterministic pass/fail check.

The Monday move

Pick one failure-prone login, checkout, or publishing path next week. Run doctor, record the existing active page at 30 fps, keep the current assertion, call record stop, and attach the MP4 to the test result. Move to 60 fps only if the reviewer cannot judge a motion defect; move to 10 fps when a long run is mainly a sequence. The pilot succeeds when a reviewer can diagnose the failure without rerunning it, not when the video merely looks smooth.

If you want a browser agent that produces review-ready evidence for your team, I can build it around your real QA workflow.