/screencast API

The screencast API is still under beta, and isn't recommended yet for production usage.

The screencast API allows for generating video files, on demand, of your puppteer scripts. This simple REST API allows for POSTing of a application/json or application/javascript body of your code you'd like to record. The resulting response is a webm file with the video attached. Audio is now supported in our screencast API as of docker version 1.8.0.

The resulting video's dimensions are inherited by the width and height of the browser. You can change this very easily by calling page.setViewport with your dimensions in your scripts as well as setting --window-size in the URL.

Using application/javascript content-type

When using this API you'll need to specify an appropriate content-type for the body of the request. When the type is application/json the /screencast API follows a similar semantic of the /function API, where you'll apply both a code property and a context property. This makes your request more re-usable as you can specify arguments in the context property that your code can reference:

Example code body

module.exports = async ({ page, context }) => {
  const { url, wait, width, height } = context;
  await page.setViewport({ width, height });
  await page.goto(url);
  await page.waitFor(wait);
};

Full Eample JSON body

// JSON body
// Code is minifed here!
{
  "code": "module.exports = async function main({ page, context }) { await page.setViewport({ width: context.width, height: context.height, deviceScaleFactor: 2 }); await page.goto(context.url); await page.waitFor(context.wait);}",
  "context": {
    "url": "https://www.youtube.com/watch?v=GnEmD17kYsE",
    "wait": 1000,
    "width": 1920,
    "height": 1080
  }
}

Full cURL (with an API token)

curl -X POST \
  https://chrome.browserless.io/screencast?token=YOUR-API-TOKEN&--window-size=1920,1080 \
  -o video.webm \
  -H 'Content-Type: application/json' \
  -d '{
  "code": "module.exports = async function main({ page, context }) { await page.setViewport({ width: context.width, height: context.height, deviceScaleFactor: 2 }); await page.goto(context.url); await page.waitFor(context.wait);}",
  "context": {
    "url": "https://www.youtube.com/watch?v=GnEmD17kYsE",
    "wait": 5000,
    "width": 1920,
    "height": 1080
  }
}'

Using application/javascript content-type

The application/javascript content-type is great for testing quick scripts and seeing their output, and works with many tools like postman for faster feedback. The only limitation is that you cannot post any arguments into your script via context, and all parameters will need to be hard-coded.

Example body

module.exports = async ({ page }) => {
  await page.setViewport({ width: 1920, height: 1080 });
  await page.goto('https://www.youtube.com/watch?v=GnEmD17kYsE');
  await page.waitFor(10000);
};

And the resulting cURL call:

Full cURL (with an API token)

curl -X POST \
  https://chrome.browserless.io/screencast?token=MY-API-TOKEN&--window-size=1920,1080 \
  -o video.webm \
  -H 'Content-Type: application/javascript' \
  -d '
    module.exports = async ({ page }) => {
      await page.setViewport({ width: 1920, height: 1080 });
      await page.goto(`https://www.youtube.com/watch?v=GnEmD17kYsE`);
      await page.waitFor(10000);
    };
  '

Programmatic control

By default, browserless will start recording the session immediately, and will stop once your function completes execution. You can change this behavior by using to functions in your code: startScreencast and stopScreencast:

Starting the screencast after load

module.exports = async ({ page, startScreencast, stopScreencast }) => {
    await page.goto('https://vclock.com/stopwatch');
    await page.click('#btn-resume');
    startScreencast();
    await page.waitFor(5000);
    stopScreencast();
}

Full request with cURL

curl -X POST \
  https://chrome.browserless.io/screencast?token=YOUR-API-TOKEN \
  -H 'Content-Type: application/javascript' \
  -d 'module.exports = async ({ page, startScreencast, stopScreencast }) => {
    await page.goto('\''https://vclock.com/stopwatch'\'');
    await page.click('\''#btn-resume'\'');
    await page.waitFor(1000);
    startScreencast();
    await page.waitFor(5000);
    stopScreencast();
}'
← /pdf/screenshot →