chrome-capture README

项目的 README,来自 github.com/paulirish/chrome-capture。合并为一个 markdown 文件:README.md。

chrome-capture

Record a Chrome tab at 60-120fps (up to 2160p) straight to a AV1 .mp4. Tab audio too. No ffmpeg.

npx chrome-capture https://paulirish.github.io/chrome-capture/ demo.mp4 4s

Chrome 153+ has a native MP4 tab recorder! 😻

For the past ~decade, Page.startScreencast was the only way to get video frames out of CDP. That API is from ~2013, built so DevTools could show a live preview of a USB-tethered Android. (So good!) Both Playwright (recordVideo) and Puppeteer (page.screencast()) built their video capture on top of it: Chrome JPEG-encodes each frame, base64s it into JSON over CDP, waits for an ack, and the library pipes those JPEGs into ffmpeg. It's served us well.

In Sept 2026… the new Page.startScreenRecording landed (thx alex rudenko!). Frames go straight from the compositor to an out-of-process encoder over shared memory, and Chrome writes AV1 into the mp4 as it goes (plus optional tab audio). 💅 Stopping is ~instant because the encoding is already done (no multi-second ffmpeg flush at the end). And you can start/stop recording whenever you want: log in, warm up the page, then record just the interaction.

In short: It's hot. It's good. really good.

https://github.com/user-attachments/assets/e17ffe7e-e868-40d5-adc9-df85eeb3dae8

(Thx github.com/Sam1983Aing/senna-800kg for this Gemini Argon generation.)

Puppeteer v25.10+ wraps this in an experimental page.record() (deprecating page.screencast()). (Update: Nov 10th... Playwright now has an open PR (#43999) bringing Page.startScreenRecording to Chromium! :fingers_crossed:)

Feel free to install this from npm.. or tbh just point your agent at src/index.ts and steal the implementation. It's tiny.

CLI

# 720p @ 60fps for 4s, with tab audio
npx chrome-capture https://paulirish.github.io/chrome-capture/ demo.mp4 4s

# 1080p @ 120fps (needs a 120Hz display and headful Chrome, e.g. a ProMotion MacBook)
npx chrome-capture https://paulirish.github.io/chrome-capture/ 120fps.mp4 5s --fps=120 --width=1920 --height=1080 --headful

# Record the page with DevTools open next to it
npx chrome-capture https://paulirish.github.io/chrome-capture/ devtools.mp4 5s --with-devtools

The CLI records audio by default and runs headless (--headless=new) for <= 60fps, automatically switching to --headful on macOS when --fps > 60 so Chrome can lock onto ProMotion's 120Hz CVDisplayLink. --help for the rest.

Playwright, Puppeteer, or raw CDP

startRecording() takes a Playwright Page, a Puppeteer Page, or a CDP session. It defaults to 60fps and works with await using, so the mp4 is written when the block exits:

import {startRecording} from 'chrome-capture';

// `page` can be a Playwright Page, a Puppeteer Page, or a CDP session!!
{
  await using rec = await startRecording(page, {
    outputPath: 'flow.mp4',   // optional: omit to get a Buffer from rec.stop()
    frameRate: 60,            // default: 60 (up to 120 on a 120Hz display)
    maxWidth: 1280,           // default: 1280
    maxHeight: 720,           // default: 720
    captureArea: 'target',    // 'target' (viewport) or 'browserWindow'
    audio: false,             // 48kHz stereo Opus tab audio
  });
  await page.goto('https://paulirish.github.io/chrome-capture/');
  await page.click('a');
}

@playwright/test fixture

Records every test and attaches the mp4 to the report:

import {test as base} from '@playwright/test';
import {screenRecordingFixture} from 'chrome-capture/playwright';

export const test = base.extend({
  recordVideo60fps: screenRecordingFixture({auto: true, audio: true}),
});

(Drop auto: true if you'd rather call recordVideo60fps.start() yourself, mid-test.)

Raw CDP

import {CdpScreenRecorder, connectCdpSession} from 'chrome-capture';

const session = await connectCdpSession(pageWebSocketDebuggerUrl);
const recorder = new CdpScreenRecorder(session);

await recorder.start({maxWidth: 1920, maxHeight: 1080});
// ... do stuff
const mp4 = await recorder.stop();
session.close();

Visible cursor

With Playwright, await page.screencast.showActions() draws its cursor, element highlights, and click badges right into the DOM (without starting Page.startScreencast), so startRecording(page) captures them natively. To restyle the cursor SVG and click ring yourself, inject a custom DOM overlay instead: see examples/custom-cursor/ (pointermove/pointerdown tracking for Playwright or manual sessions) and examples/raw-cdp-cursor/ (raw CDP Bezier choreography).

Benchmarks

Same 6.4s UI replay (typing, clicks, drag-and-drop, scroll) at 1280x800, comparing the Page.startScreencast + ffmpeg pipeline (recordVideo) against Page.startScreenRecording (chrome-capture at its default 60fps) on an M4 Max. Methodology and the full numbers are in benchmarks/README.md.

recordVideo (startScreencast) chrome-capture (startScreenRecording)
Output fps 25 (up to 60) 60 (up to 120)
Total wall-clock 21s 11s
Stop + finalize 3,800ms 17ms
WebSocket traffic 10.5 MB 450 KB
Final file size 480 KB 330 KB
PSNR vs. lossless screenshot 32 dB 34 dB
Audio none optional

Because Chrome encodes the video in-flight instead of piping JPEGs to ffmpeg, stopping takes 17ms instead of 3.8s (or 91ms vs 20.5s at 2160p), and the whole test finishes ~10s quicker.

What about bitrate and visual quality? There's no bitrate/CRF knob (yet). Under the hood, Chrome encodes on the fly with libaom AV1 in realtime 1-pass VBR and scales target bitrate linearly with pixel rate (2 Mbps at 720p30 -> 9 Mbps at 1080p60 -> 18 Mbps at 1080p120 -> 72 Mbps at 2160p120).

The high bitrate sweet spot is 1080p60 (9 Mbps) and up (bumping resolution or frameRate doubles as a backdoor bitrate multiplier). If you ever need lossless 1px text fidelity and only care about ~10-15fps, an offline Page.startScreencast({format: 'png'}) -> ffmpeg pipeline still has a place.

How high can it go?

Video files can lie about fps. So the stress test (demo) draws a binary frame counter on every requestAnimationFrame, then decodes it back out of the mp4 to count unique frames:

https://github.com/user-attachments/assets/67734ccb-b986-4d66-a7d4-84bf05f7af87

One macOS gotcha: don't pass --disable-frame-rate-limit --disable-gpu-vsync on a GPU-accelerated Mac. rAF spins at 1,600-9,800fps, floods the Metal command queue, and starves the capture readback (dropping 2160p@60 to 0.3fps). Leave native vsync alone; it's what gets you to 120.


npm version

chrome-capture (paulirish/chrome-capture)

正在搜索数据库…

这是什么?一个可以把 Chrome 标签页以 60-120 fps(最高 2160p)直接录制成 AV1 .mp4 的工具,可选录制标签页声音,且不需要 ffmpeg。它使用 Chrome 原生的 Page.startScreenRecording,由 Chrome 自己编码画面。
它是 CLI、库,还是两者都是?两者都是。它提供一个可以驱动 Chrome 的 CLI,也提供 startRecording() 函数,可接收 Playwright 的 Page、Puppeteer 的 Page,或原始的 CDP 会话。
我该怎么让它运行起来?可以从 npm 安装,也可以直接复制 src/index.ts(README 称其实现非常精简)。快速录制可以使用 CLI(默认录制声音),也可以在测试或脚本中调用 startRecording(page)。
我首先需要准备什么?你需要 Chrome 153 或更高版本,因为 Page.startScreenRecording 只在这些版本中存在。不需要 ffmpeg,因为 Chrome 会直接把 AV1 写入 mp4 文件。
有没有什么需要注意的地方?有。目前还没有码率或 CRF 设置。在启用 GPU 加速的 Mac 上,同时传入 --disable-frame-rate-limit 和 --disable-gpu-vsync 会让 60 fps 的 2160p 降到约 0.3 fps,因此请保持原生 vsync 开启。
它在哪些操作系统上测试过?基准测试在搭载 M4 Max 的 macOS 和无头 Linux 上运行。README 将 Windows 以及配备独立显卡的 Linux 标记为未知。
帧率是否取决于我的 GPU?基本是的。在 macOS 上,无头 Chrome 仍然使用 Metal,因此 1080p、1440p 和 2160p 都能达到 60 fps。没有 GPU 的无头 Linux 在标准 60Hz 垂直同步下,1080p 大约能达到 60 fps。
为什么它比 recordVideo 更快、更精确?Chrome 在浏览器内部编码画面,而不是通过 CDP 发送 base64 JPEG 再交给 ffmpeg 处理。README 测得在 1280x800 下,停止和完成处理耗时为 17 毫秒,而 recordVideo 为 3800 毫秒。
我能在会话中途开始和停止录制吗?可以。你可以先登录、预热页面,然后只录制你关心的操作,因为 startRecording() 随时都可以调用。
如何在视频中显示光标和点击高亮?使用 Playwright 时,await page.screencast.showActions() 会把光标、元素高亮和点击标记绘制到 DOM 中,因此它们会被录制下来。如需自定义光标,请参考 examples/custom-cursor 文件夹。
输出使用多大的码率?Chrome 使用 libaom AV1 的实时单遍 VBR 编码,并根据像素速率调整码率,例如 1080p60 为 9 Mbps,2160p120 为 72 Mbps。目前还没有可修改的设置。
作者
paulirish
大小
0.3 MB
星标
490
更新
提交Nov 17
时长
10天
提交 · 90 天