Skip to main content
Version: v2

Screencast API

info

Screencasting is only available on paid plans.

The screencasting 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.

Key Features

  • 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
  • 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 recording API.

Video Dimensions Configuration

The resulting video dimensions are inherited from the browser's width and height. You can customize these in several ways:

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

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.

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();

Next Steps

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