puppeteer-capture

!node-current
!GitHub Workflow Status
!Codecov
!Code Climate maintainability

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

This project is brought to you by Alexey Pelykh.

Under The Hood

HeadlessExperimental is used to
capture frames in a deterministic way. This approach allows to achieve better quality than using screencast.

Getting Started

``js
const { capture, launch } = require('puppeteer-capture')

(async () => {
const browser = await launch()
const page = await browser.newPage()
const recorder = await capture(page)
await page.goto('https://google.com', {
waitUntil: 'networkidle0',
})
await recorder.start('capture.mp4')
await recorder.waitForTimeout(1000)
await recorder.stop()
await recorder.detach()
await browser.close()
})()
`

Time flow

The browser is running in a deterministic mode, thus the time flow is not real time. To wait for a certain amount of
time within the page's timeline, PuppeteerCapture.waitForTimeout() must be used:

`js
await recorder.waitForTimeout(1000)
`

Known Issues

$3

Sadly, it is so. For Puppeteer v23+, the plugin enforces use
of the chrome-headless-shell binary.

$3

- 117.0.5938.88 (default for puppeteer version(s) 21.3.0 ): reacts with targetCrashed
- 117.0.5938.92 (default for puppeteer version(s) 21.3.2…21.3.6): reacts with targetCrashed
- 117.0.5938.149 (default for puppeteer version(s) 21.3.7…21.3.8): reacts with targetCrashed
- 118.0.5993.70 (default for puppeteer version(s) 21.4.0…21.4.1): reacts with targetCrashed
- 119.0.6045.105 (default for puppeteer version(s) 21.5.0…21.7.0): reacts with targetCrashed
- 120.0.6099.109 (default for puppeteer version(s) 21.8.0): reacts with targetCrashed

$3

Unfortunately, it is so.

$3

This relates to timers, animations, clicks, etc. To process interaction with the page, frame requests have to be
submitted and thus capturing have to be active.

$3

The exact origin of the issue is not yet known, yet it's likely to be related to the deterministic mode.

Calling page.setViewport() before starting the capture behaves the same, yet calling it _after_ starting the capture
works yet not always. Thus it's safe to assume that there's some sort of race condition, since adding
recorder.waitForTimeout(100) just before setting the viewport workarounds the issue.

Also it should be taken into account that since frame size is going to change over the time of the recording, frame size
autodetection will fail. To workaround this issue, frame size have to be specified:

`js
const recorder = await capture(page, {
size: ${viewportWidth}x${viewportHeight},
})
await recorder.start('capture.mp4', { waitForFirstFrame: false })
await recorder.waitForTimeout(100)
await page.setViewport({
width: viewportWidth,
height: viewportHeight,
deviceScaleFactor: 1.0,
})
`

A friendlier workaround is enabled by default: recorder.start() automatically waits for the first frame to be
captured. This approach seems to allow bypassing the alleged race condition:

`js
const recorder = await capture(page, {
size: ${viewportWidth}x${viewportHeight},
})
await recorder.start('capture.mp4')
await page.setViewport({
width: viewportWidth,
height: viewportHeight,
deviceScaleFactor: 1.0,
})
`

$3

It's unclear why, yet after disabling and re-enabling the capture, callbacks from browser stop arriving.

$3

The following functions have to be overriden with injected versions:

- setTimeout & clearTimeout
- setInterval & clearInterval
- requestAnimationFrame & cancelAnimationFrame
- Date() & Date.now()
- performance.now()

The injection should happen before page content loads:

`js
const recorder = await capture(page) // Injection happens here during attach()
await page.goto('https://google.com') // Possible capture would happen here, thus injected versions would be captured
`

Events

PuppeteerCapture supports following events:

- captureStarted: capture was successfully started
- frameCaptured: frame was captured
- frameCaptureFailed: frame capture failed
- frameRecorded: frame has been submitted to ffmpeg
- captureStopped: capture was stopped

Dependencies

$3

It is resolved in the following order:

1. FFMPEG environment variable, should point to the executable
2. The executable that's available via the PATH environment variable
3. Via @ffmpeg-installer/ffmpeg`, if it's installed as dependency