### Install puppeteer-capture and puppeteer Source: https://github.com/alexey-pelykh/puppeteer-capture/blob/main/README.md Install the puppeteer-capture plugin and its peer dependency puppeteer via npm. ```bash npm install puppeteer-capture puppeteer ``` -------------------------------- ### Build Commands Source: https://github.com/alexey-pelykh/puppeteer-capture/blob/main/CLAUDE.md Commands to install dependencies, build, test, and lint the project. Use npm ci for clean installs, npm run build to compile TypeScript, npm run test to run tests, and npm run lint for ts-standard linting. ```bash # Install dependencies npm ci # Build (compile TypeScript) npm run build # Run tests npm run test # Lint (ts-standard) npm run lint ``` -------------------------------- ### Build the project with npm run build Source: https://github.com/alexey-pelykh/puppeteer-capture/blob/main/CONTRIBUTING.md Build the project. Run after installing dependencies. ```bash npm run build ``` -------------------------------- ### Install dependencies with npm ci Source: https://github.com/alexey-pelykh/puppeteer-capture/blob/main/CONTRIBUTING.md Install project dependencies using npm ci. Requires Node.js >=20.18. ```bash npm ci ``` -------------------------------- ### Capture page as video with puppeteer-capture Source: https://github.com/alexey-pelykh/puppeteer-capture/blob/main/README.md Launch a browser, create a page, attach a capture recorder, navigate to a URL, start recording to a file, wait, stop, detach, and close the browser. ```javascript 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() ``` -------------------------------- ### Default workaround for viewport freeze Source: https://github.com/alexey-pelykh/puppeteer-capture/blob/main/KNOWN_ISSUES.md A friendlier workaround enabled by default: recorder.start() automatically waits for the first frame, which bypasses the race condition when setting the viewport after starting capture. ```javascript const recorder = await capture(page, { size: `${viewportWidth}x${viewportHeight}`, }) await recorder.start('capture.mp4') await page.setViewport({ width: viewportWidth, height: viewportHeight, deviceScaleFactor: 1.0, }) ``` -------------------------------- ### PuppeteerCaptureStartOptions Source: https://github.com/alexey-pelykh/puppeteer-capture/blob/main/README.md Options passed to recorder.start(). ```APIDOC ## PuppeteerCaptureStartOptions ### Description Options passed to `recorder.start()`. ### Fields - **waitForFirstFrame** (boolean, default: `true`) - Whether `start()` waits for the first frame before resolving. - **dropCapturedFrames** (boolean, default: `false`) - When `true`, frames are emitted via events but not written to the output. ``` -------------------------------- ### launch(options?) Source: https://github.com/alexey-pelykh/puppeteer-capture/blob/main/README.md Launches a browser configured for deterministic capture. Returns a Promise resolving to a PuppeteerBrowser instance. ```APIDOC ## launch(options?) ### Description Launches a browser configured for deterministic capture. Returns a Promise resolving to a PuppeteerBrowser instance. ### Parameters - **options** (PuppeteerLaunchOptions) - Optional - Puppeteer launch options. The `headless` option is overridden to `'shell'` and required Chrome arguments are appended to `args` automatically. ### Returns `Promise` ### Example ```ts import { launch } from 'puppeteer-capture' const browser = await launch() ``` ``` -------------------------------- ### Run tests with npm run test Source: https://github.com/alexey-pelykh/puppeteer-capture/blob/main/CONTRIBUTING.md Run the test suite. Tests involve browser launch and are slow (~30s threshold). ```bash npm run test ``` -------------------------------- ### Release Notes Format (Markdown) Source: https://github.com/alexey-pelykh/puppeteer-capture/blob/main/CLAUDE.md Use this markdown template for GitHub release notes, following the 'Generate release notes' style. Replace placeholders like @author, pull request number, and tag names. ```markdown ## What's Changed * (type) description by @author in https://github.com/alexey-pelykh/puppeteer-capture/pull/N **Full Changelog**: https://github.com/alexey-pelykh/puppeteer-capture/compare/PREV_TAG...NEW_TAG ``` -------------------------------- ### Launch browser with launch() Source: https://github.com/alexey-pelykh/puppeteer-capture/blob/main/README.md Launches a browser configured for deterministic capture. The headless option is overridden to 'shell' and required Chrome arguments are appended automatically. ```TypeScript import { launch } from 'puppeteer-capture' const browser = await launch() ``` -------------------------------- ### capture(page, options?) Source: https://github.com/alexey-pelykh/puppeteer-capture/blob/main/README.md Creates a PuppeteerCapture instance for the given page. Returns a Promise resolving to a PuppeteerCapture instance. ```APIDOC ## capture(page, options?) ### Description Creates a PuppeteerCapture instance for the given page. Returns a Promise resolving to a PuppeteerCapture instance. ### Parameters - **page** (PuppeteerPage) - Required - The page to capture. - **options** (PuppeteerCaptureOptions) - Optional - Extended with `attach` option. - **attach** (boolean, default: `true`) - When `false`, the recorder is created without attaching to the page. Call `recorder.attach(page)` later. ### Returns `Promise` ### Example ```ts import { capture } from 'puppeteer-capture' const recorder = await capture(page) ``` ``` -------------------------------- ### PuppeteerCaptureOptions Source: https://github.com/alexey-pelykh/puppeteer-capture/blob/main/README.md Options passed to capture(). ```APIDOC ## PuppeteerCaptureOptions ### Description Options passed to `capture()`. ### Fields - **fps** (number, default: `60`) - Frames per second. - **size** (string) - Output size in ffmpeg notation (e.g. `'1280x720'`). - **format** ((ffmpeg: FfmpegCommand) => Promise, default: `PuppeteerCaptureFormat.MP4()`) - Output format configurator. - **ffmpeg** (string) - Path to the ffmpeg binary (overrides auto-detection). - **customFfmpegConfig** ((ffmpeg: FfmpegCommand) => Promise) - Additional ffmpeg configuration callback applied after `format`. ``` -------------------------------- ### Create capture instance with capture() Source: https://github.com/alexey-pelykh/puppeteer-capture/blob/main/README.md Creates a PuppeteerCapture instance for the given page. The page must be a PuppeteerPage. Optional options can include attach: false to defer attachment. ```TypeScript import { capture } from 'puppeteer-capture' const recorder = await capture(page) ``` -------------------------------- ### PuppeteerCapture Methods Source: https://github.com/alexey-pelykh/puppeteer-capture/blob/main/README.md Methods available on the PuppeteerCapture instance returned by capture(). ```APIDOC ## PuppeteerCapture 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** (string | Writable) - A file path or a Writable stream. When a file path, parent directories are created automatically. - **options** (PuppeteerCaptureStartOptions) - Optional. ### 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. ### on(event, listener) Subscribes to a capture event. - **event** (string) - Event name. - **listener** (function) - Listener function. ``` -------------------------------- ### Check code style with npm run lint Source: https://github.com/alexey-pelykh/puppeteer-capture/blob/main/CONTRIBUTING.md Run the linter (ts-standard) to check code style. ```bash npm run lint ``` -------------------------------- ### PuppeteerCaptureFormat.MP4(preset?, videoCodec?) Source: https://github.com/alexey-pelykh/puppeteer-capture/blob/main/README.md Creates a format configurator for MP4 video capture. Accepts an optional x264 encoding preset and video codec, returning a function to configure the capture format. ```APIDOC ## PuppeteerCaptureFormat.MP4(preset?, videoCodec?) ### Description Creates a format configurator for MP4 video capture. Accepts an optional x264 encoding preset and video codec, returning a function to configure the capture format. ### Parameters - **preset** (string) - Optional - x264 encoding preset. Default: `'ultrafast'`. One of: `'ultrafast'`, `'superfast'`, `'veryfast'`, `'faster'`, `'fast'`, `'medium'`, `'slow'`, `'slower'`, `'veryslow'`. - **videoCodec** (string) - Optional - Video codec. Default: `'libx264'`. ### Returns - A format configurator function. ### Example ```ts import { capture, PuppeteerCaptureFormat } from 'puppeteer-capture' const recorder = await capture(page, { format: PuppeteerCaptureFormat.MP4('medium', 'libx264') }) ``` ``` -------------------------------- ### MP4 format configurator usage Source: https://github.com/alexey-pelykh/puppeteer-capture/blob/main/README.md Use PuppeteerCaptureFormat.MP4 to set the output format for capture. The preset and videoCodec parameters are optional, with defaults 'ultrafast' and 'libx264' respectively. ```TypeScript import { capture, PuppeteerCaptureFormat } from 'puppeteer-capture' const recorder = await capture(page, { format: PuppeteerCaptureFormat.MP4('medium', 'libx264') }) ``` -------------------------------- ### PuppeteerCapture Events Source: https://github.com/alexey-pelykh/puppeteer-capture/blob/main/README.md Events emitted by PuppeteerCapture. ```APIDOC ## PuppeteerCapture Events ### captureStarted - **Listener**: `() => void` - **Description**: Capture was started. ### frameCaptured - **Listener**: `(index: number, timestamp: number, data: Buffer) => void` - **Description**: A frame was captured. ### frameCaptureFailed - **Listener**: `(reason?: any) => void` - **Description**: Frame capture failed. ### frameRecorded - **Listener**: `(index: number, timestamp: number, data: Buffer) => void` - **Description**: A frame was written to the output. ### captureStopped - **Listener**: `() => void` - **Description**: Capture was stopped. ``` -------------------------------- ### Workaround for viewport freeze with waitForFirstFrame: false Source: https://github.com/alexey-pelykh/puppeteer-capture/blob/main/KNOWN_ISSUES.md When setting defaultViewport causes rendering to freeze, specify the frame size and use waitForFirstFrame: false, then wait 100ms before setting the viewport to work around the race condition. ```javascript 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, }) ``` -------------------------------- ### Wait for timeout in deterministic mode Source: https://github.com/alexey-pelykh/puppeteer-capture/blob/main/README.md Use PuppeteerCapture.waitForTimeout() to wait for a specified amount of time within the page's timeline when the browser runs in deterministic mode. The argument is in milliseconds. ```javascript await recorder.waitForTimeout(1000) ``` -------------------------------- ### Seek and Canvas Pattern for Approximate Video Capture Source: https://github.com/alexey-pelykh/puppeteer-capture/blob/main/KNOWN_ISSUES.md Use this JavaScript pattern inside a requestAnimationFrame callback to approximate video frame capture by seeking and drawing to a canvas. It is not frame-perfect; seek accuracy depends on codec keyframe placement, audio is not captured, and native video controls are not visible on the canvas. ```javascript // On each frame (inside requestAnimationFrame callback): video.currentTime = desiredTimeInSeconds video.addEventListener('seeked', () => { ctx.drawImage(video, 0, 0) }, { once: true }) ``` -------------------------------- ### Inject time-related function overrides before page load Source: https://github.com/alexey-pelykh/puppeteer-capture/blob/main/KNOWN_ISSUES.md Time-related functions (setTimeout, setInterval, requestAnimationFrame, Date, performance.now) must be overridden with injected versions before page content loads. The injection happens during capture() attach(), so call it before page.goto(). ```javascript 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 ```