Puppeteer Record Video: page.screencast() vs puppeteer-screen-recorder

Quick answer

If you want to record video with Puppeteer today, start with the native page.screencast() API.

It is now good enough for many common cases and supports useful options such as format, crop, fps, quality, scale, and speed through ScreencastOptions.

Use puppeteer-screen-recorder when you need a package wrapper around recording, want a stream-based workflow, or prefer its API over the native Puppeteer recorder.

Record video with Puppeteer using page.screencast()

This is the simplest way to record a video in Puppeteer:

1
import puppeteer from "puppeteer";
2

3
const browser = await puppeteer.launch();
4

5
try {
6
    const page = await browser.newPage();
7

8
    await page.setViewport({
9
        width: 1280,
10
        height: 720,
11
        deviceScaleFactor: 1,
12
    });
13

14
    await page.goto("https://screenshotone.com", {
15
        waitUntil: "networkidle2",
16
    });
17

18
    const recorder = await page.screencast({
19
        path: "recording.mp4",
20
        format: "mp4",
21
        fps: 30,
22
    });
23

24
    await page.evaluate(() => {
25
        window.scrollBy({ top: 900, left: 0, behavior: "smooth" });
26
    });
27

28
    await new Promise((resolve) => setTimeout(resolve, 1500));
29

30
    await recorder.stop();
31
} finally {
32
    await browser.close();
33
}

This method requires FFmpeg to be installed locally.

For most “Puppeteer record video” use cases, this should be your default starting point.

Puppeteer screencast options

The native API is no longer as limited as many older tutorials suggest.

According to the official Puppeteer docs, page.screencast() supports:

That means native Puppeteer is already a strong option for:

• short product demos;
• automated test recordings;
• scroll-based captures;
• debugging browser automation flows;
• generating MP4, WebM, or GIF output from a script.

Record part of the page with Puppeteer crop

If you only need to record a specific region, use crop:

1
import puppeteer from "puppeteer";
2

3
const browser = await puppeteer.launch();
4

5
try {
6
    const page = await browser.newPage();
7

8
    await page.setViewport({
9
        width: 1440,
10
        height: 900,
11
        deviceScaleFactor: 1,
12
    });
13

14
    await page.goto("https://tailwindcss.com", {
15
        waitUntil: "networkidle2",
16
    });
17

18
    const recorder = await page.screencast({
19
        path: "hero-section.webm",
20
        format: "webm",
21
        crop: {
22
            x: 0,
23
            y: 0,
24
            width: 1440,
25
            height: 520,
26
        },
27
    });
28

29
    await new Promise((resolve) => setTimeout(resolve, 2000));
30

31
    await recorder.stop();
32
} finally {
33
    await browser.close();
34
}

This is useful when you want a cleaner recording for a landing page hero, dashboard widget, or a single component in a test report.

Puppeteer screen recorder with puppeteer-screen-recorder

If you specifically want the puppeteer-screen-recorder package, install it like this:

1
npm i puppeteer-screen-recorder

And then use it like this:

1
"use strict";
2

3
const puppeteer = require("puppeteer");
4
const { PuppeteerScreenRecorder } = require("puppeteer-screen-recorder");
5

6
(async () => {
7
    const browser = await puppeteer.launch();
8

9
    try {
10
        const page = await browser.newPage();
11

12
        await page.setViewport({
13
            width: 1920,
14
            height: 1080,
15
            deviceScaleFactor: 1,
16
        });
17

18
        await page.goto("https://tailwindcss.com/", {
19
            waitUntil: "networkidle2",
20
        });
21

22
        const recorder = new PuppeteerScreenRecorder(page);
23

24
        await recorder.start("video.mp4");
25
        await animate(page);
26
        await recorder.stop();
27
    } catch (error) {
28
        console.error(error);
29
    } finally {
30
        await browser.close();
31
    }
32
})();
33

34
async function animate(page) {
35
    await wait(500);
36
    await page.evaluate(() => {
37
        window.scrollBy({ top: 500, left: 0, behavior: "smooth" });
38
    });
39
    await wait(500);
40
    await page.evaluate(() => {
41
        window.scrollBy({ top: 1000, left: 0, behavior: "smooth" });
42
    });
43
    await wait(1000);
44
}
45

46
function wait(ms) {
47
    return new Promise((resolve) => setTimeout(resolve, ms));
48
}

You can still convert the resulting MP4 to GIF with FFmpeg:

1
const util = require("util");
2
const exec = util.promisify(require("child_process").exec);
3

4
await exec("ffmpeg -i video.mp4 -qscale 0 animated.gif");

page.screencast() vs puppeteer-screen-recorder

Here is the practical difference:

If your goal is simply “record video with Puppeteer”, use the native API first.

If your team is already built around puppeteer-screen-recorder, or you want the library’s approach to stream handling and page lifecycle behavior, keep using the package.

How to stream Puppeteer recording instead of saving to disk

One reason to use puppeteer-screen-recorder is stream-oriented workflows.

That can matter if you want to:

• send video directly to object storage;
• process chunks without keeping large local files;
• integrate recording into a queue or worker pipeline.

The native page.screencast() path is ideal when writing a file directly is acceptable. If direct streaming is central to your architecture, evaluate the library approach first.

Can Puppeteer record audio?

At the time of writing, the official ScreencastOptions documentation lists video-oriented options such as format, crop, fps, quality, scale, and speed, but does not list audio settings.

So the safe assumption is: use Puppeteer for visual recording, and use a separate browser-media or system-level capture solution if tab audio is a hard requirement.

Use cases

Marketing with animated screenshots

You can generate animated page recordings for:

• personalized outbound emails;
• product walkthroughs;
• changelog videos;
• blog post demos;
• landing page previews.

Debug browser automation

In production scraping or automation flows, a recording can show exactly what happened before a failure.

That is especially useful when the issue is timing-related, environment-specific, or difficult to reproduce locally.

Test reports

Recording end-to-end flows can make failed test reports much easier to review.

Instead of reading logs alone, developers can watch the interaction and identify where the state diverged.

Interactive mockups and programmatic demos

If you can script the interaction in JavaScript, you can turn it into a repeatable recording.

That is useful for design handoff, launch announcements, and documentation videos.

Use ScreenshotOne API if you need hosted rendering

If you do not want to maintain browser automation, FFmpeg, storage, and media processing yourself, you can use ScreenshotOne API.

It supports animated screenshots and lets you generate recordings in one request:

1
https://api.screenshotone.com/animate?url=https://tailwindcss.com&access_key=<your access key>

That can be a better fit when your actual goal is marketing automation or media generation at scale, not maintaining a Puppeteer recording stack.

Frequently Asked Questions

What is the best way to record video with Puppeteer?

Start with the native page.screencast() API. It is the official Puppeteer solution and already supports useful recording controls such as output format, cropping, fps, quality, scale, and speed.

Should I use page.screencast() or puppeteer-screen-recorder?

Use page.screencast() first for most projects. Use puppeteer-screen-recorder if your workflow benefits from that package’s abstraction or stream-based handling.

Can Puppeteer save recordings as MP4?

Yes. Current Puppeteer documentation lists mp4 as one of the supported video formats for screencast output.

Can Puppeteer create GIF files?

Yes. Current Puppeteer documentation lists gif as a supported screencast format, and FFmpeg-based conversion is still another option if you prefer to convert after recording.

Can Puppeteer record only part of the page?

Yes. Use the crop option in page.screencast() to record a specific region.

Summary

Native Puppeteer is now the right default for recording video from a page.

Use page.screencast() when you want the official API and straightforward MP4, WebM, or GIF output. Use puppeteer-screen-recorder when you specifically want that package’s workflow.