Version: v2

Screencast API

info

Screencasting (Screen Recording) is only available on paid plans.

The Screencast API enables on-demand generation of WebM video files from your Puppeteer or Playwright automation scripts. The API supports both video and audio recording, making it ideal for creating comprehensive session recordings, debugging automation workflows, and capturing user interactions. This feature is not to be confused with the Session Replay feature, which captures DOM events and is viewable in your dashboard with automatic recording.

Key Features

The Screencast API provides high-quality WebM output with efficient compression, audio recording support automatically captured with video, flexible video dimensions inherited from browser viewport settings, CDP-based control for precise recording start/stop timing, and cross-library compatibility with Puppeteer, Playwright, and other CDP-supporting tools.

Connection Requirements

You must add record=true to your connection string to enable the Screencast API. This parameter loads the screencast extension that handles video capture.

Video Dimensions Configuration

The resulting WebM dimensions are inherited from the page viewport size at the moment recording starts. For example, if you run await page.setViewport({ width: 2048, height: 720 }); before Browserless.startRecording, the resulting video will be 2048x720 px.

You can customize viewport dimensions in several ways:

Puppeteer: Use page.setViewport({ width: 1280, height: 720 })
URL Parameters: Add --window-size=1280,720 and headless=false to your connection string
Launch Arguments: Configure viewport in browser launch options

CDP Fallback for Viewport Sizing

If your automation library does not expose a page.setViewport or page.setViewportSize method, you can set dimensions directly with the CDP Emulation.setDeviceMetricsOverride method. Most libraries use this CDP command under the hood when updating viewport size. See the DevTools Protocol reference: https://chromedevtools.github.io/devtools-protocol/tot/Emulation/#method-setDeviceMetricsOverride.

Avoid Resizing During Recording

Avoid changing the viewport size while recording is in progress. Mid-recording viewport changes can distort rendered content and produce a visibly stretched or otherwise unusual recording.

Basic Usage

This API works over CDP, thus you can use it with Puppeteer, Playwright, ChromeCDP or any other library that support CDP connections.

The following examples demonstrate how to implement screencasting across different automation libraries. Each example shows the complete workflow: connecting to Browserless, starting a recording session, performing automation tasks, stopping the recording, and saving the resulting WebM video file to disk.

Puppeteer
Playwright

import fs from "fs";
import puppeteer from "puppeteer-core";

const sleep = (ms) => new Promise((res) => setTimeout(res, ms));
const token = "YOUR_API_TOKEN_HERE";

const wsEndpoint = `wss://production-sfo.browserless.io?token=${token}&headless=false&stealth&record=true`;
const browser = await puppeteer.connect({ browserWSEndpoint: wsEndpoint });
const page = await browser.newPage();

// Set custom viewport for recording dimensions
await page.setViewport({ width: 1280, height: 720 });
await page.goto("https://browserless.io");

// Start recording session
const cdp = await page.createCDPSession();
await cdp.send("Browserless.startRecording");

// Perform your automation actions here
await sleep(15000);

// Stop recording and save
const response = await cdp.send("Browserless.stopRecording");
const file = Buffer.from(response.value, "binary");
await fs.promises.writeFile("./recording.webm", file);

await browser.close();

Javascript
Python
Java
C#

warning

On Playwright, you must use the already existing context and page and avoid creating new ones.

import playwright from "playwright-core";
import fs from "fs/promises";

const sleep = (ms) => new Promise((res) => setTimeout(res, ms));
const token = "YOUR_API_TOKEN_HERE";

const wsEndpoint = `wss://production-sfo.browserless.io?token=${token}&headless=false&stealth&record=true`;

(async () => {
  // Connect to the remote browser
  const browser = await playwright.chromium.connectOverCDP(wsEndpoint);

  // Reuse the context and page
  const context = browser.contexts()[0];
  const page = context.pages()[0];
  await page.setViewportSize({ width: 1280, height: 720 });
  await page.goto("https://browserless.io");

  // Start recording
  const cdpSession = await page.context().newCDPSession(page);
  await cdpSession.send("Browserless.startRecording");
  
  // Wait for some time while recording
  await sleep(15000);
  
  // Stop recording and get the response
  const response = await cdpSession.send("Browserless.stopRecording");
  const file = Buffer.from(response.value, "binary");

  // Save the recording as a webm file
  await fs.writeFile("./recording.webm", file);

  await browser.close();
})();

warning

On Playwright, you must use the already existing context and page and avoid creating new ones.

from playwright.sync_api import sync_playwright
import time

TOKEN = "YOUR_API_TOKEN_HERE"
WS_ENDPOINT = (
    f"wss://production-sfo.browserless.io?token={TOKEN}&headless=false&stealth&record=true"
)

with sync_playwright() as playwright:
    # Connect to the remote browser
    browser = playwright.chromium.connect_over_cdp(WS_ENDPOINT)

    # Reuse the context and page
    context = browser.contexts[0]
    page = context.pages[0]
    page.set_viewport_size({"width": 1280, "height": 720})
    page.goto("https://browserless.io")

    # Start recording
    cdp_session = context.new_cdp_session(page)
    cdp_session.send("Browserless.startRecording")

    # Wait for some time while recording
    time.sleep(15)

    # Stop recording and get the response
    response = cdp_session.send("Browserless.stopRecording")
    recording_data = response["value"]

    # Write binary data to a file
    with open("recording.webm", "wb") as file:
        file.write(recording_data.encode("latin1"))

    browser.close()

warning

On Playwright, you must use the already existing context and page and avoid creating new ones.

import com.microsoft.playwright.*;
import java.nio.file.*;

public class App {
  public static void main(String[] args) {
    String TOKEN = "YOUR_API_TOKEN_HERE";
    String WS_ENDPOINT = String.format("wss://production-sfo.browserless.io?token=%s&headless=false&stealth&record=true",
        TOKEN);

    try (Playwright playwright = Playwright.create()) {
      // Connect to the remote browser
      Browser browser = playwright.chromium().connectOverCDP(WS_ENDPOINT);

      // Reuse the context and page
      Page page = browser.contexts().get(0).pages().get(0);
      page.setViewportSize(1280, 720);
      page.navigate("https://browserless.io");

      // Start recording
      CDPSession cdpSession = browser.contexts().get(0).newCDPSession(page);
      cdpSession.send("Browserless.startRecording", null);

      // Wait for 15 seconds
      Thread.sleep(15000);

      // Stop recording
      var response = cdpSession.send("Browserless.stopRecording", null);
      String recordingData = response.get("value").getAsString();

      // Write binary data to a file
      byte[] fileData = recordingData.getBytes("ISO-8859-1");
      Files.write(Paths.get("recording.webm"), fileData);

      System.out.println("Recording saved as 'recording.webm'");
      browser.close();
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}

warning

On Playwright, you must use the already existing context and page and avoid creating new ones.

using Microsoft.Playwright;
using System;
using System.IO;
using System.Text;

class BrowserlessRecording
{
    public static async Task Main(string[] args)
    {
        string TOKEN = "YOUR_API_TOKEN_HERE";
        string WS_ENDPOINT = $"wss://production-sfo.browserless.io?token={TOKEN}&headless=false&stealth&record=true";

        using var playwright = await Playwright.CreateAsync();
        var browser = await playwright.Chromium.ConnectOverCDPAsync(WS_ENDPOINT);

        // Reuse the context and page
        var context = browser.Contexts[0];
        var page = context.Pages[0];

        await page.SetViewportSizeAsync(1280, 720);
        await page.GotoAsync("https://browserless.io");

        // Start recording
        var cdpSession = await context.NewCDPSessionAsync(page);
        await cdpSession.SendAsync("Browserless.startRecording");

        // Wait for 15 seconds
        await Task.Delay(15000);

        // Stop recording
        var response = await cdpSession.SendAsync("Browserless.stopRecording");
        string recordingData = response.Value<string>("value");

        // Write binary data to a file
        byte[] fileData = Encoding.GetEncoding("ISO-8859-1").GetBytes(recordingData);
        await File.WriteAllBytesAsync("recording.webm", fileData);

        Console.WriteLine("Recording saved as 'recording.webm'");
        await browser.CloseAsync();
    }
}

Next Steps

Ready to explore more BaaS features? Continue your journey with these essential capabilities:

Multi-Session Recording

Record multiple browser sessions simultaneously for comprehensive testing and automation workflows

Conditional Recording with Error Handling

Implement robust recording with proper error handling and conditional triggers for production workflows

Proxies

Learn how to use residential and datacenter proxies for enhanced anonymity and geo-targeting

Key Features​

Connection Requirements​

Video Dimensions Configuration​

Basic Usage​

Next Steps​

Multi-Session Recording

Conditional Recording with Error Handling

Proxies

Key Features

Connection Requirements

Video Dimensions Configuration

Basic Usage

Next Steps