Feature Request: Built-in session video recording via Page.startScreencast

[crayment]

Feature Request: Built-in session video recording via Page.startScreencast

Summary

Add a high-level recording abstraction to cdp_use that uses the CDP Page.startScreencast / Page.screencastFrame / Page.stopScreencast protocol to capture a browser session as a video file.

Motivation

CDP has native support for streaming browser frames via Page.startScreencast. This makes it possible to record headless browser sessions without needing external tools like ffmpeg screen capture (which doesn't work in headless mode) or Playwright's recording feature (which is not available in cdp_use).

Use cases:

• Debugging automated browser sessions after the fact
• Generating video artifacts from CI/test runs
• Recording user flow walk-throughs driven by agents (e.g. first-time UX testing)

What CDP supports today

The protocol already has everything needed:

# Start streaming frames
await cdp.send("Page.startScreencast", {
    "format": "jpeg",
    "quality": 80,
    "maxWidth": 1280,
    "maxHeight": 800,
    "everyNthFrame": 1
})

# Each frame arrives as an event
@cdp.on("Page.screencastFrame")
async def on_frame(event):
    frame_data = event["data"]  # base64-encoded JPEG
    session_id = event["sessionId"]
    # acknowledge receipt
    await cdp.send("Page.screencastFrameAck", {"sessionId": session_id})

# Stop when done
await cdp.send("Page.stopScreencast")

Frames can then be encoded to .webm or .mp4 using ffmpeg or a pure-Python encoder like imageio.

Proposed API

A simple, ergonomic recording context manager on the CDP client or page:

async with cdp.record_video("/tmp/session.webm", fps=10, width=1280, height=800):
    await cdp.send("Page.navigate", {"url": "https://example.com"})
    # ... do stuff
# video saved to /tmp/session.webm when context exits

Or a lower-level start/stop pair:

recorder = await cdp.start_recording("/tmp/session.webm")
# ... do stuff
await recorder.stop()  # saves the file

Alternatives considered

• ffmpeg screen capture: doesn't work in headless mode
• Playwright record_video_dir: requires Playwright, not available in cdp_use
• Screenshot stitching: produces a slideshow, not a real recording; frame timing is lost
• Laminar / external observability platforms: too heavyweight for simple local use

Notes

• Page.startScreencast works in headless Chromium — this is how Cypress and other tools implement their video recording
• Frame encoding to video could be an optional dependency (e.g. pip install cdp-use[video]) to keep the base install lightweight
• Quality and frame rate should be configurable

[Adarsh-Raj-Jaiswal]

Hi @crayment

I'd like to take a shot at implementing this if it’s not already being worked on.

I also noticed there's a related feature request in browser-use to add CLI-level recording commands. My plan would be to first implement the recording abstraction here (using Page.startScreencast / Page.screencastFrame), and then build the CLI integration on top of it.

For the initial version, I’m thinking of:

• Starting with a simple start/stop recording API
• Capturing frames via Page.screencastFrame
• Encoding to .webm (possibly via a simple approach first, then improving)

Happy to iterate on the API design if there are preferences around abstraction (context manager vs start/stop).

[crayment]

Thanks @Adarsh-Raj-Jaiswal — great to see this picked up so quickly!

A few thoughts on the API design:

Prefer context manager as the primary API — it makes the common case (record a session, save on exit) clean and safe:

async with cdp.record_video("/tmp/session.webm", fps=10):
    await cdp.send("Page.navigate", {"url": "https://example.com"})
    # ... do stuff
# file is saved and closed automatically

The start/stop pair is still useful for cases where the recording spans multiple scopes, but the context manager should be the happy path.

On encoding — if keeping it simple to start, even writing raw JPEG frames with timestamps to a directory (like Playwright does internally) would be a fine v1. That avoids a hard dependency on a video encoder and lets users run ffmpeg themselves if needed. You could add direct .webm output as a follow-up once the frame capture side is solid.

One thing worth checking — does Page.startScreencast work reliably in headless mode? Our use case is headless (agent-driven automation), so that's the critical path. I believe Cypress uses this same mechanism headlessly, but worth a quick validation early.

[crayment]

Quick follow-up on the API design — I want to clarify my earlier comment. I suggested context manager as the "happy path" but that was based on Python usage patterns. For the CLI use case (which is actually our primary driver here), start/stop is the only option that works — recording needs to persist across many separate CLI invocations against the daemon.

So to reframe:

• Context manager — great API for Python scripts that drive the browser in one block
• Start/stop — essential for CLI users where commands come in one at a time

Both are worth supporting, but start/stop is arguably more critical for this feature to be useful from the CLI.

[Adarsh-Raj-Jaiswal]

Thanks, this is super helpful — especially the clarification around start/stop being the priority for CLI use.

I’ll start with a minimal start/stop implementation and focus on frame capture first (saving JPEG frames with timestamps), and validate headless support early.

Once that’s solid, I can iterate on encoding and add the context manager as a higher-level API.

Will share a first pass soon.

[Adarsh-Raj-Jaiswal]

Quick update — I validated that CDP screencast works in headless mode.

I tested Page.startScreencast with headless Chrome and confirmed that frames are being emitted consistently (tested on dynamic pages like YouTube as well). Frame acknowledgment is working as expected.

Based on this, the recording approach should work for the headless agent-driven use case.

I’ll proceed with implementing a minimal start/stop recording API next, starting with saving raw JPEG frames.

[crayment]

That's great news! Thank you for working on this!!