puppeteer-capture

A Puppeteer plugin for capturing page as a video with ultimate quality.

Standard screencast approaches capture frames in real time, producing inconsistent frame timing and non-reproducible output. puppeteer-capture uses Chrome's HeadlessExperimental CDP domain to capture each frame deterministically. If you need frame-perfect, reproducible video output from Puppeteer, this is the only option.

Quick Start

npm install puppeteer-capture puppeteer

import { capture, launch } from 'puppeteer-capture'

const browser = await launch()
const page = await browser.newPage()
const recorder = await capture(page)

await page.goto('https://example.com', { waitUntil: 'networkidle0' })
await recorder.start('capture.mp4')
await recorder.waitForTimeout(1000)
await recorder.stop()
await recorder.detach()
await browser.close()

Key Features

• Deterministic frame timing — frames are captured on demand via CDP, not in real time
• Frame-perfect reproducible output — the same page produces the same video, every time
• CDP-powered — uses HeadlessExperimental.beginFrame for precise frame control
• Virtual time control — waitForTimeout() advances the page's own timeline
• Works with any Puppeteer workflow — drop-in alongside existing Puppeteer scripts

Comparison

| | puppeteer-capture | puppeteer-screen-recorder | Playwright built-in | |---|---|---|---| | Approach | CDP HeadlessExperimental | Screencast | Screencast | | Frame timing | Deterministic | Real-time | Real-time | | Reproducibility | Frame-perfect | Varies | Varies | | Time control | Full (virtual clock) | None | None | | Platform | Linux, Windows | All | All |

API Reference

launch(options?)

Launches a browser configured for deterministic capture.

import { launch } from 'puppeteer-capture'

const browser = await launch()

• options — Optional PuppeteerLaunchOptions from puppeteer-core. The headless option is overridden to 'shell' and the required Chrome arguments are appended to args automatically.
• Returns Promise<PuppeteerBrowser>

capture(page, options?)

Creates a PuppeteerCapture instance for the given page.

import { capture } from 'puppeteer-capture'

const recorder = await capture(page)

• page — A PuppeteerPage to capture.
• options — Optional PuppeteerCaptureOptions extended with:
  • attach (boolean, default: true) — When false, the recorder is created without attaching to the page. Call recorder.attach(page) later.
• Returns Promise<PuppeteerCapture>

PuppeteerCaptureOptions

Options passed to capture().

| Option | Type | Default | Description | |--------|------|---------|-------------| | fps | number | 60 | Frames per second | | size | string | — | Output size in ffmpeg notation (e.g. '1280x720') | | format | (ffmpeg: FfmpegCommand) => Promise<void> | PuppeteerCaptureFormat.MP4() | Output format configurator | | ffmpeg | string | — | Path to the ffmpeg binary (overrides auto-detection) | | customFfmpegConfig | (ffmpeg: FfmpegCommand) => Promise<void> | — | Additional ffmpeg configuration callback applied after format |

PuppeteerCaptureStartOptions

Options passed to recorder.start().

| Option | Type | Default | Description | |--------|------|---------|-------------| | waitForFirstFrame | boolean | true | Whether start() waits for the first frame before resolving | | dropCapturedFrames | boolean | false | When true, frames are emitted via events but not written to the output |

PuppeteerCapture

The main interface returned by capture().

Properties

| Property | Type | Description | |----------|------|-------------| | page | Page \| null | The attached page, or null if detached | | isCapturing | boolean | Whether capture is in progress | | captureTimestamp | number | Current virtual timestamp (ms) since capture start | | capturedFrames | number | Total frames captured since last start() | | dropCapturedFrames | boolean | Whether captured frames are dropped (read/write) | | recordedFrames | number | Total frames written to the output |

Methods

attach(page) — Attaches the recorder to a page. Required only when capture() was called with { attach: false }. Throws if already attached.

detach() — Detaches from the current page. Throws if not attached.

start(target, options?) — Starts capturing frames.

• target — A file path (string) or a Writable stream.
• options — Optional PuppeteerCaptureStartOptions.

When target is a file path, parent directories are created automatically.

stop() — Stops capture and waits for ffmpeg to finalize the output.

waitForTimeout(milliseconds) — Advances the page's virtual timeline by the given number of milliseconds. Can only be called while capturing. See Time Flow.

on(event, listener) — Subscribes to a capture event.

Events

| Event | Listener Signature | Description | |-------|--------------------|-------------| | captureStarted | () => void | Capture was started | | frameCaptured | (index: number, timestamp: number, data: Buffer) => void | A frame was captured | | frameCaptureFailed | (reason?: any) => void | Frame capture failed | | frameRecorded | (index: number, timestamp: number, data: Buffer) => void | A frame was written to the output | | captureStopped | () => void | Capture was stopped |

PuppeteerCaptureFormat

Format configurators for PuppeteerCaptureOptions.format.

PuppeteerCaptureFormat.MP4(preset?, videoCodec?)

• preset — x264 encoding preset (default: 'ultrafast'). One of: 'ultrafast', 'superfast', 'veryfast', 'faster', 'fast', 'medium', 'slow', 'slower', 'veryslow'.
• videoCodec — Video codec (default: 'libx264').
• Returns a format configurator function.

import { capture, PuppeteerCaptureFormat } from 'puppeteer-capture'

const recorder = await capture(page, {
  format: PuppeteerCaptureFormat.MP4('medium', 'libx264')
})

Error Classes

NotChromeHeadlessShell — Thrown when the browser is not chrome-headless-shell. Use launch() to ensure the correct binary.

MissingRequiredArgs — Thrown when the browser is missing one or more required Chrome arguments. Use launch() to add them automatically.

Required Chrome Arguments

The following arguments are required and are added automatically by launch():

• --deterministic-mode
• --enable-begin-frame-control
• --disable-new-content-rendering-timeout
• --run-all-compositor-stages-before-draw
• --disable-threaded-animation
• --disable-threaded-scrolling
• --disable-checker-imaging
• --disable-image-animation-resync
• --enable-surface-synchronization

Platform Risk: HeadlessExperimental Dependency

This library depends entirely on Chrome's HeadlessExperimental CDP domain — specifically the beginFrame method — for deterministic frame capture. This is the only mechanism in Chrome that provides compositor-level frame scheduling, which is what enables frame-perfect, reproducible video output.

Current status

• beginFrame is not deprecated and remains actively implemented in the Chromium source.
• enable/disable are marked deprecated in the protocol definition (they are no-ops and have no functional impact).
• The domain is labeled Experimental, meaning it can change without notice.
• beginFrame is exclusive to chrome-headless-shell (the old headless architecture). It is not available in --headless=new.

Risk assessment

| Timeframe | Risk | Rationale | |-----------|------|-----------| | Near-term (0–12 months) | Low | beginFrame is not deprecated; implementation receives maintenance commits; chrome-headless-shell ships with every Chrome release. | | Medium-term (1–3 years) | Moderate | The "Experimental" label has persisted since inception without graduating to stable. No public commitment to long-term chrome-headless-shell maintenance exists. | | Long-term (3+ years) | Moderate–High | Chrome's strategic direction favors --headless=new. If chrome-headless-shell is eventually discontinued, beginFrame goes with it. |

Why there is no drop-in alternative

HeadlessExperimental.beginFrame is unique because it controls when the compositor renders each frame. The alternatives — Page.startScreencast, Page.captureScreenshot, tab capture — all capture frames produced by Chrome's own compositor timing, which means:

• Frame timing depends on wall-clock time and system load (non-deterministic).
• CSS animations, transitions, and compositor-driven effects cannot be synchronized to a virtual timeline.
• Two runs of the same page may produce different frame counts and visual output.

A partial fallback using Page.captureScreenshot with JavaScript time virtualization can achieve determinism for JS-driven content but not for CSS animations or compositor-driven effects.

Mitigating factors

• Remotion and other ecosystem projects also depend on chrome-headless-shell for deterministic rendering, creating broader pressure to maintain the binary.
• Active Chromium issues (e.g., #40550372 — making BeginFrameControl work with Viz) indicate ongoing investment, not abandonment.
• Chromium's deprecation process typically involves long warning periods and migration paths.

Monitoring

To track changes to this dependency:

• Chromium HeadlessExperimental.pdl — protocol definition (watch for deprecation annotations on beginFrame)
• Chromium headless_handler.cc — implementation (watch for removal or functional changes)
• Chrome DevTools Protocol changelog
• headless-dev mailing list — discussions on headless mode future

Time Flow

The browser runs in deterministic mode, so the time flow is not real time. To wait for a certain amount of time within the page's timeline, use PuppeteerCapture.waitForTimeout():

await recorder.waitForTimeout(1000)

Dependencies

ffmpeg

ffmpeg is resolved in the following order:

1. FFMPEG environment variable pointing to the executable
2. The executable available via PATH
3. Via ffmpeg-static, if installed as a dependency

Known Issues

See Known Issues for platform constraints and workarounds.

Contributing

See Contributing for development setup and guidelines.

License

MIT