paulirish/chrome-capture

项目介绍

chrome-capture 把 Chrome 标签页录制成 AV1 .mp4，最高 2160p、60–120fps，可同时录制标签页音频，无需额外调用 ffmpeg。它依赖新增的 Page.startScreenRecording CDP 命令：视频帧从合成器经共享内存直接送入进程外编码器，Chrome 在录制过程中就把 AV1 写入 MP4，因此停止录制几乎瞬间完成 Page.startScreenRecording。相比之下，Playwright recordVideo 和 Puppeteer page.screencast() 使用的旧接口 Page.startScreencast 需要把 JPEG 帧经 CDP 传输，再交给 ffmpeg 处理 Page.startScreencast。

项目适合需要自动化录制浏览器操作流程、追求高帧率或高分辨率的开发者，包括为 Playwright/Puppeteer 测试生成录像、或直接通过 CDP 控制录制的场景。提供 CLI 和 TypeScript 库两种用法。

快速使用

前提：Chrome 153+ 以使用原生 MP4 标签页录制器，以及带 npm 的 Node.js 环境来运行 CLI。

录制 4 秒页面（默认 720p/60fps，含标签页音频）：

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

更高帧率需要匹配的显示器和有头 Chrome，例如在 120Hz 显示器上录制 1080p@120fps：

npx chrome-capture https://paulirish.github.io/chrome-capture/ 120fps.mp4 5s --fps=120 --width=1920 --height=1080 --headful

在 Playwright、Puppeteer 或 CDP 会话中以代码方式使用时，startRecording() 返回一个支持 await using 的录制器，代码块退出时写出 MP4：

import {startRecording} from 'chrome-capture';

{
  await using rec = await startRecording(page, {
    outputPath: 'flow.mp4',
    frameRate: 60,
    maxWidth: 1280,
    maxHeight: 720,
    audio: false,
  });
  await page.goto('https://paulirish.github.io/chrome-capture/');
}

包内还提供 @playwright/test fixture 和裸 CDP 的 CdpScreenRecorder。完整示例见 README。

使用约束

• 需要 Chrome 153+ 才能使用 Page.startScreenRecording。
• CLI 在帧率不超过 60fps 时以无头模式运行；在 macOS 上 --fps 超过 60 时自动切换为有头模式，以便 Chrome 锁定 ProMotion 的 120Hz 显示。
• 120fps 需要 120Hz 显示器和有头 Chrome。
• 目前无法手动设置码率和画质：Chrome 使用 libaom AV1 实时单遍 VBR 编码，目标码率随像素率线性增长。文档给出的高画质甜点是 1080p60 及以上；如果需要无损的 1px 文字保真且只关心约 10–15fps，仍可退回 Page.startScreencast({format: 'png'}) + ffmpeg 的离线方案。
• 在 GPU 加速的 macOS 上不要传 --disable-frame-rate-limit --disable-gpu-vsync，否则 Metal 命令队列会被淹没，2160p@60 录制可能降到 0.3fps。
• Windows 或带独立 GPU 的 Linux 上的实测分辨率/帧率上限尚未记录。

基准测试

在 M4 Max 上，以 1280×800 回放 6.4 秒的操作，chrome-capture 默认 60fps 全程耗时 11s，Playwright recordVideo 为 21s；停止并收尾分别耗时 17ms 和 3,800ms。WebSocket 流量 450KB 对 10.5MB，最终文件 330KB 对 480KB。相对无损截图的 PSNR 为 34dB 对 32dB。方法见 benchmarks/README.md。

HotRepo 点评

chrome-capture 在 2026-11-10 的 HotRepo TypeScript 新项目榜有记录：在 02:45–03:45 UTC 的一小时窗口内新增 7 Star，总计 108 Star；没有全语言日榜名次或 HN 讨论记录。项目的技术前提具体且可检验：走合成器到编码器的直通路径后，JPEG 经 CDP 和 ffmpeg 的环节被去掉，文档所述停止耗时 17ms 与 ffmpeg 收尾的 3.8s 形成鲜明对比。项目规模不大，README 建议读者直接看 src/index.ts 复用实现；文档列出的兼容性限制意味着最高设置在特定硬件上才得到确认。