Capture Pipeline · 技术选型手册

recordVideo 与 CDP
两条画面采集链路的工作原理

它们不是两套技术,而是同一个 Chromium 供帧管道的两个下游出口。这份文档把安装链路、源码机制、 实测帧率和选型判断拆成可核对的步骤 —— 每一步都标注了证据来源:是实测出来的、读源码读出来的,还是推断。 最后还落到一个更实际的问题:怎么让整条链路在用户看不见的窗口里跑完。

Playwright 1.64.1 Chromium 1248 · CFT 156.0.8078.4 ffmpeg 1013 · n7.0.1 采集 1920×1080 11 张 手绘 SVG

00三十秒结论

如果你的问题是「这两个该怎么选」,答案往往被包装成性能对比。但读完 Playwright 的实现会发现: 两者调用的是同一个 CDP 命令,连 quality 默认值都一样(90)。 真正的差别只有一个 —— 帧拿到手之后,谁来把它变成文件。

CDP 直采
97.85 帧/秒
recordVideo @90
58.8 唯一帧/秒
默认录制尺寸
800×450
默认帧率
25 fps
判断依据证据
采集端同源 recordVideo 内部就是 ScreencastClient 的一个客户端,调用 Page.startScreencast;format: "jpeg"、quality ?? 90。 源码
fps 只是配额 传 fps 只改两处:maxFramesInFlight(5 或 10)和 ffmpeg 的 -r。声明 90 时,90 帧里有 31 帧是 ffmpeg 复制出来的。 源码 实测
不抢主线程 注入 rAF 探针测真实渲染帧率:不录制 116.85 / 录 60fps 116.45 / 录 90fps 116.67 / CDP 116.80,差异 < 0.5%。 实测
无窗口也能录 默认 headless: true 会换成 chrome-headless-shell,WebGL 落到 SwiftShader:实测 7.4 fps;加 channel:"chromium" 走 Metal:60.0 fps。 实测 源码
按镜头分工 1× 常规镜头用 fps:60(唯一 47.8,降到 30fps 交付够用);2× 以上慢放用 CDP(慢放后 27.8 vs 25.0)。 实测
为什么先讲结论

因为选型的成本差在「工程」而不在「性能」:recordVideo 是 20 行配置换一个 webm,CDP 是 20 行协议换 900 张 JPEG + 一份 meta.json。 性能上 CDP 全面占优,但它要求你自己管帧号、时间戳和后续编码 —— 这部分的代价,只有在你真的需要慢放或逐帧对齐时才值得付。

01同源,在第四步分叉

把两条链路画在一起,交叉点非常清楚:上半和下半在 Chromium 出帧 之前完全重叠。 这个结构决定了后面所有结论 —— 既然是同一个水源,那产能上限就由水源决定,下游只能决定「怎么装瓶」。

① 采集端 · 两条链路共用 ② 下游 · 在这里分叉 Chromium 合成器 每合成一帧就推一次 Page.startScreencast jpeg · quality 90 maxFramesInFlight 5 / 10 recordVideo 内置客户端 Playwright 自己写盘 + 编码 Matroska 封装 EBML 头 + JPEG 帧 ffmpeg VP9 实时编码 app.webm(VP9) 自建 CDP 客户端 你写 onFrame + ack JPEG 序列 000123.jpg ffmpeg 离线编码 成片 mp4(H.264) 边录边压 · 实时 先落盘 · 录完再压 上游代码完全相同,差别只在第 4 步之后 —— 谁负责把帧变成文件。
图 1 · 链路全景。上半(橙)是 recordVideo:帧一进 Node 就被封进 Matroska 管道喂给 ffmpeg,边录边编码。 下半(绿)是 CDP 直采:Node 只负责把 JPEG 写进磁盘,编码推迟到录制结束后。同一台机器、同一场景,上半实测 58.8 唯一帧/秒,下半 77.9。

这个分叉在源码里只有一个入口可以确认 —— ScreencastClient.addClient()。 Playwright 的 VideoRecorder 把 onFrame 回调注册进去,从此每一帧都被同步转交给 ffmpeg 的 stdin。 也就是说,recordVideo 并不是「另一个采集实现」,它是 CDP 采集的一个消费者。

// playwright-core/src/server/videoRecorder.ts(1.64.1,压缩后变量名已还原)
const ffmpegPath = registry.findExecutable("ffmpeg").executablePathOrDie();
this._client = {
  onFrame: (frame) => this._videoRecorder.writeFrame(frame.buffer, frame.frameSwapWallTime),
  size: options.size,
  fps: options.fps            // ← 只被用于 maxFramesInFlight 与 ffmpeg 的 -r
};
const { size } = this._screencast.addClient(this._client);
this._videoRecorder = new FfmpegVideoRecorder(ffmpegPath, videoSize, options.fps ?? kDefaultFps, outputFile);
// kDefaultFps = 25 —— 这就是那个「不报错、只是默默给你 25fps」的默认值

02安装:三个二进制,一个被钉死的版本

这一步最容易出问题的原因,是它不由你决定。你在 package.json 里写的是 playwright@1.64.1,但这个版本要配哪个 Chromium、哪个 ffmpeg,是 playwright-core/browsers.json 里钉死的 revision。升级 Playwright 而没重跑安装, 就会出现「代码是新的、二进制是旧的」—— 报错信息还只说文件不存在,不说版本不匹配。

package.json playwright@1.64.1 playwright-core/browsers.json 钉死每个二进制的 revision 不由你决定 ↑ chromium-1248 headed 采集用它 366 MB chromium_headless_shell-1248 headless 默认用它 203 MB ffmpeg-1013 recordVideo 的编码器 2.9 MB 缓存根目录(macOS): ~/Library/Caches/ms-playwright PLAYWRIGHT_BROWSERS_PATH=0 → 改装到 node_modules/.local-browsers 每个目录里的 INSTALLATION_COMPLETE 是「真的装完」的唯一凭据 默认清单 = 5 项 chromium + shell + firefox + webkit + ffmpeg (dry-run 可原样打印这份清单)
图 2 · 安装链路。revision 由 browsers.json 决定;三个二进制各自独立下载、独立打完成标记。 注意 ffmpeg 只有 2.9 MB —— 它不是完整版 ffmpeg,只带 image2pipe → VP9 这条最窄的能力。

·三条命令,差别在「装了哪些」

命令实际下载够不够录
npm i -D playwright@1.64.1 只有 JS 包。不下载任何浏览器(1.64.1 的 package.json 已无 install 脚本)。 不能
npx playwright install chromium Chromium 1248 + headless shell + ffmpeg 1013(实测 dry-run:这个组合里 ffmpeg 是连带项)。 能
npx playwright install 5 项全装:chromium、shell、firefox、webkit、ffmpeg。约 1.2 GB。 能
npx playwright install ffmpeg 只补 ffmpeg(2.9 MB)。已有 Chromium 时最省的一刀。 仅补齐
一个真实的踩坑,结论与直觉相反

我一度以为原因是「install chromium 不含 ffmpeg」。实测 --dry-run 后否掉了这个假设: 1.64.1 里 ffmpeg 是 chromium 安装组的连带项,会一起下。
真正的失败原因是:升级 Playwright 时只跑完了 Chromium 那一段,ffmpeg 的下载被中断, 目录存在但没有 INSTALLATION_COMPLETE,于是 recordVideo 在启动 ffmpeg 时才炸。 教训不是「记得装 ffmpeg」,而是「装完必须对账」。

·装完的对账三件事

对账# 1. 这个版本到底要哪些二进制、装在哪
npx playwright install --dry-run

# 2. 每个目录是否真的装完了(缺这个文件 = 半成品)
ls ~/Library/Caches/ms-playwright/*/INSTALLATION_COMPLETE

# 3. ffmpeg 能否执行(它是 recordVideo 的硬依赖)
~/Library/Caches/ms-playwright/ffmpeg-1013/ffmpeg-mac -version
# → ffmpeg version n7.0.1-playwright-build-1013

第 3 步有个容易忽略的细节:这个 ffmpeg 是 Playwright 自己编译的裁剪版, 只保留 VP9 编码这一条链路,所以其他机器上 which ffmpeg 找到的系统版不能替代它。 反过来说,走 CDP 路线时采集端完全不需要它 —— 这是两个方案在部署上的实质差异。

磁盘会悄悄长大

这次检查发现缓存里同时躺着 7 代 Chromium(1055 到 1248,单代 330–366 MB), 而当前版本只需要 1248 —— 升级过程并没有顺手清掉旧代际。 只跑 install chromium 时,其他代际也不在它的处理范围里,于是越攒越多。 回收空间:npx playwright uninstall(清掉本安装用到的)或加 --all(清所有版本), 也可以手工删掉带旧 revision 的目录。

03recordVideo 的工作原理

它做的事可以一句话说完:把一个内置的 screencast 客户端接上,把每帧 JPEG 连同自己写的时间戳封进 Matroska 管道,喂给一个常驻的 ffmpeg 进程实时压成 VP9。 下面按时序拆开,编号与图 3 对应。

Node / Playwright VideoRecorder Chromium 合成器 + JPEG 编码 ffmpeg 子进程 常驻,等 stdin 磁盘 循环 · 每帧执行一次 1 startScreencast {quality:90, in-flight:10} 2 spawn ffmpeg -f matroska -i pipe:0 3 screencastFrame(JPEG base64) 4 EBML 集群头 + JPEG 字节 → stdin 5 VP9 → app.webm 6 screencastFrameAck(回执) 7 ctx.close() → stdin.end() → 编码收尾 8 video.saveAs(path) 录制起点 = context 创建时刻,早于 goto:成片开头必然含加载期,必须裁掉。
图 3 · recordVideo 时序。① 启动 screencast;② 拉起常驻 ffmpeg;③–⑥ 每帧走一遍 「收帧 → 封 Matroska → 回执」;⑦ 关闭时才结束管道;⑧ 才把临时文件交给你。 注意 编码是串在录制过程中的,这是它和 CDP 的根本区别。
  1. 建 context 就开始录

    newContext({ recordVideo }) 一返回,VideoRecorder.start() 就已经 addClient 并 startScreencast 了。所以录制起点早于 goto, 片头一定带着加载画面 —— 实测两次相同操作,成片时长分别是 1.68s 和 1.96s,差的就是这段。

  2. 拉起一个常驻 ffmpeg

    输入是 pipe:0(stdin),容器声明为 matroska,输出 libvpx-vp9。 它不是「录完再压」,而是页面动一下它就收到一帧。

  3. 收帧:base64 解码后的原始 JPEG

    CDP 事件里的 data 是 base64,Playwright 解成 Buffer 后不做任何转码, 原样往下传。所以 quality 90 的 JPEG 压缩痕迹会一路留到 VP9 里。

  4. 自己封 Matroska:先写集群头,再写 JPEG

    这一步很反直觉 —— ffmpeg 的输入不是裸 JPEG 流,而是 Playwright 手工拼的 EBML 结构。 writeClusterHeader(timestamp, length) 写入时间戳和长度,紧跟原始 JPEG 字节。 用绝对时间戳(不是等间隔)意味着容器里保留了真实的采集节奏,后面才有「重采样」的空间。

  5. 实时 VP9 编码,参数全为「快」让路

    -deadline realtime、-cpu-used 8、-lag-in-frames 0: 不做前瞻缓存、用最快的预设。代价是压缩效率,收益是不堵管道。

  6. 回执,释放一个在途名额

    Chromium 只有在收到 screencastFrameAck 之后才会继续推后续帧, 在途上限是 maxFramesInFlight。这是整条链路真正的限速器(见 §5)。

  7. ctx.close() 才收尾

    关闭 context 会触发 stdin.end(),ffmpeg 才会 flush 出完整的 WebM 索引(Cues)。 先 saveAs 再关 context,会拿到半截文件或报 Target closed。

  8. 交付一个 webm

    VP9 + WebM,没有音轨(参数里写死了 -an)。要 mp4 得自己转封装。

·那串 ffmpeg 参数,逐行看

1.64.1 实际下发的参数-loglevel error
-f matroska            # 输入容器:Playwright 手工拼的 EBML
-fpsprobesize 0 -probesize 32 -analyzeduration 0
                       # 放弃探测:这三行是「别浪费时间分析流」
-i pipe:0 -y -an
-r {fps}               # 输出时间基 —— 关键:不足就复制帧补齐
-c:v libvpx-vp9 -qmin 0 -qmax 50 -crf 8
-deadline realtime -cpu-used 8 -lag-in-frames 0
                       # 实时优先:无前瞻、最快预设
-b:v {bitrate}k -threads {threads} -tile-columns {tile}
-row-mt 1
-vf pad={w}:{h}:0:0:gray,crop={w}:{h}:0:0
                       # 补到偶数尺寸(yuv420 要求)
-metadata creation_time=...
{output}.webm

其中 -r 是理解后面一切的钥匙:它声明「输出必须是这个帧率」。 当实际进来的帧少于这个数,ffmpeg 的默认行为是重复上一帧,而不是丢时间。 所以文件看起来是 90fps,画面信息量却只有 59fps —— 这就是 §5 要展开的核心。

·位率、线程、切片:三个自动算出来的数

你没法直接传码率,只能传 fps 和 size,剩下三个值由公式推导 (w·h·fps / (800·450·25) 得到一个「像素率倍数」):

1920×1080像素率倍数码率threadstile-columns
fps 255.7605.76 Mbps21
fps 6013.82413.82 Mbps42
fps 9020.73620.74 Mbps63

这个设计很聪明也很坑:码率随 fps 同比放大,每帧分到的比特数恒定。 所以提高 fps 不会让画面更清楚,只会让文件更大、编码更吃力,而你多拿到的那些帧里有一半是重复的。 实测体积也吻合:同样 22 秒,25fps 10 MB、60fps 23 MB、90fps 34 MB。

两个默认值,都会静默毁掉素材

① 不传 size → 录出来是 800×450。 源码里 screencast 尺寸在缺省时按「最长边不超过 800」等比缩小(1920×1080 → 800×450)。 实测对照:不传 size 得 800×450 / 20 KB,传 size:{1920,1080} 得 1920×1080 / 85 KB。
② 不传 fps → 恒定 25fps。 两次实测都稳定输出 r_frame_rate=25/1,不报错、不警告。

可用的最小配置const browser = await chromium.launch();
const ctx = await browser.newContext({
  viewport: { width: 1920, height: 1080 },
  deviceScaleFactor: 1,
  recordVideo: {
    dir: "raw",
    size: { width: 1920, height: 1080 },  // 不传 = 800×450
    fps: 60                                     // 不传 = 25
  },
});
const page = await ctx.newPage();
// ... 操作 ...

const video = page.video();
await ctx.close();                  // 必须先关,录制才收尾
await video.saveAs("raw/shot-b.webm");
await browser.close();

04CDP 的工作原理

把 Playwright 那层客户端拆掉,直接对着协议说话,就得到 CDP 路线: 发一条命令开始,每来一帧存一张 JPEG,存完回执,循环到你说停。 没有任何编码,没有任何容器,因此也没有任何隐藏的帧率换算。

你的采集脚本 onFrame + 回执 Chromium 合成器 + JPEG 编码 磁盘 闭环 · 每帧打一个来回 1 startScreencast(jpeg / q92 / 1:1) 2 screencastFrame {data, sessionId, timestamp} 3 writeFileSync(000123.jpg) 4 screencastFrameAck {sessionId} 5 录制结束 → ffmpeg 离线编码(可选) 你控制三个旋钮:quality(画质/带宽)、maxWidth·maxHeight(尺寸)、回执节奏(供帧速度)。
图 4 · CDP 时序。① 一条命令启动;② 帧事件带着 base64 JPEG 抵达;③ 你决定怎么落盘; ④ 回执才允许下一帧;⑤ 录制结束后另行编码。采集与编码彻底解耦,这是它能跑满 97.85 帧/秒的原因。
最小可用采集器const cdp = await ctx.newCDPSession(page);
let n = 0;

cdp.on("Page.screencastFrame", async ({ data, sessionId, timestamp }) => {
  writeFileSync(`${dir}/${String(n++).padStart(6, "0")}.jpg`, Buffer.from(data, "base64"));
  await cdp.send("Page.screencastFrameAck", { sessionId });   // 不回执 = 停在 maxFramesInFlight
});

await cdp.send("Page.startScreencast", {
  format: "jpeg", quality: 92,
  maxWidth: 1920, maxHeight: 1080,
  everyNthFrame: 1,
});
// ... 操作 ...
await cdp.send("Page.stopScreencast");
// 帧数 / 耗时 → 写进 meta.json,后面裁剪靠它换算

这段最小实现是「先落盘、再回执」,为的是让代码顺序和上图一一对应,能跑通。 但它每帧都要多等一次磁盘 I/O;真要跑满帧率,得把回执提前到写盘之前 —— 这一处调整连同实测数据在 §7 的第二点。

·三个必须自己兜住的细节

一、base64 有 33% 的体积税。 协议传的是 base64 字符串,解回来才是 JPEG。1080p / quality 92 下,903 帧实测占了 165 MB (平均 183 KB/帧),而同样 9 秒的 recordVideo 成片是 23 MB —— 约 7 倍的磁盘差。 长时间录制要盯着磁盘,或者边录边转。

二、timestamp 是唯一可信的时间基准。 帧不是等间隔到达的(合成器忙就慢),所以「第 N 帧 = 第 N/fps 秒」这个假设在 CDP 路线上完全不成立。 每场采完必须存一份 meta.json,记录总帧数、总耗时、实测 fps —— 本次各场 fps 在 60–98 之间波动, 没有这份元数据就没法把帧号映射回时间。

三、没有 ffmpeg 也能采。 CDP 采集端不依赖任何二进制,JPEG 落盘就结束了。编码是之后的事, 所以内网、CI、装不上 Playwright ffmpeg 的环境里,这条路线仍然可用。

05fps 是配额,不是产能

这是整份文档最值得记住的一节。把 fps 当成「我要每秒 90 张不同画面」是错的 —— 它实际的含义是「我要求输出流每秒有 90 个时间槽」。槽位空着怎么办?ffmpeg 复制上一帧填进去。

而真正决定槽位能不能填满的,是两处限制:一处写在源码里,一处来自 Chromium 本身。

  • maxFramesInFlight:fps > 30 ? 10 : 5。在途帧满了,Chromium 就暂停推。
  • Chromium 自己的 JPEG 编码:1080p 一帧要几毫秒,它跟合成器抢同一个进程的时间片。

注意 fps 参数在这两处只影响第一处,而且只是把窗口从 5 放到 10。 它没有任何办法让 Chromium 更快地产生画面 —— 于是第二个限制成了真正的天花板。

maxFramesInFlight:同时在途的帧数上限 图示:10 个槽位里,3 个已发出、正等回执 在途 在途 在途 空闲 fps ≤ 30 → 只有 5 个槽 fps > 30 → 放宽到 10 个槽 帧到 → 占一个槽 回执 → 释放一个槽 槽满 → 停止推帧 这是唯一的限速阀, 也是 fps 参数唯一碰到的地方。 放宽窗口只能减少「等回执」的空转,不能让 Chromium 更快合成 —— 产能上限在编码侧,不在槽位数。
图 5 · 在途窗口。槽位是「已发出但未确认」的帧。窗口越大,流水线越不容易空转; 但它不能突破上游产帧速度,所以把 fps 从 30 提到 90,只是把窗口从 5 放到 10 而已。
声明 fps:90 → 一秒有 90 个时间槽 Chromium 实际交付 59 帧 (每个蓝格 = 一个不同的画面) ffmpeg 输出 90 帧 (-r 90 把空槽填满:31 帧是复制品) 唯一画面 复制帧(信息量为零) 未交付的槽位 同一秒,同一场景:声明 90,得到 59 种画面,文件里写着 90fps。
图 6 · 一秒的解剖。上排是 Chromium 真实交付的帧,下排是 ffmpeg 按 -r 90 输出的流。 橙色那 31 格不是「补间动画」,而是把第 59 帧原样重复了 31 次 —— 播放器会如实显示,观感就是卡顿。

·三档实测:提高标称只增加重复

同一 9 秒动作段 · 1920×1080 · mpdecimate 去重 标称 fps(配额) 唯一帧率(产能) 30 交付线 60 慢放门槛 recordVideo 25 22.1 recordVideo 60 47.8 recordVideo 90 58.8 CDP 直采 77.9 0 20 40 60 80 fps 虚线是标称值、实条是真实产能:两者的落差就是「被复制出来的帧」。
图 7 · 配额 vs 产能。虚线是声明的标称帧率,蓝条是实际不同的画面数。 25 → 60 有明显改善(22.1 → 47.8),但 60 → 90 只从 47.8 涨到 58.8 —— 说明天花板已经不在参数上了。
方案标称9s 输出帧唯一帧唯一帧率重复率
recordVideo2522519922.111.6%
recordVideo6054043047.820.4%
recordVideo9081052958.834.7%
CDP 直采—90371977.920.4%

最后一行还有一个值得注意的细节:CDP 的采集侧是 97.85 帧/秒,去重后 77.9。 这条链路根本没有编码环节,所以差的这 20 帧不可能是「编码丢帧」,而是场景里变化较慢的部分被去重算法判成了重复。 不同场景的数字不能直接横比,同一台机器上的相对关系才有意义。

recordVideo 这一侧的趋势更明确:标称值从 60 提到 90,重复率从 20% 涨到 35%。 多出来的帧全是填充物 —— 文件更大、编码更慢、画面并不会更顺。

·慢放把这个问题放大

慢放的本质是「用更少的时间采样换更长的时间展示」。2 倍慢放意味着每个源帧要撑 2 个输出帧, 所以源唯一帧率至少要翻倍。目标 30fps 交付时,2× 慢放需要 ≥ 60 唯一帧/秒的源:

2× 慢放 → 输出 30fps 后的有效帧率 30 recordVideo 60 25.0 recordVideo 90 22.0 CDP 直采 27.8 0 10 20 30 fps 判据:源唯一帧率 ≥ 慢放倍率 × 30。2× 需要 ≥ 60 —— 只有 CDP(77.9)满足,fps:90 反而比 fps:60 更差。
图 8 · 慢放的预算。为什么 fps:90 反而比 60 差?因为它多出的帧本来就是重复的, 慢放后重复帧被拉长成两帧完全一样的画面,去重统计自然更低。这条反直觉的结论,是选型时最容易踩的坑。
一句话判据

要判断「这个方案够不够」,别看标称 fps,算这个:源唯一帧率 ÷ 慢放倍率 ≥ 输出帧率。 本次实测:recordVideo@60 是 47.8 ÷ 2 = 23.9,不够 30;CDP 是 77.9 ÷ 2 = 39,够。

06选型决策

前面的数据可以压缩成一棵三岔树。注意分支依据不是「哪个更快」,而是这批镜头要怎么用 —— 慢放和逐帧对齐是 CDP 唯一不可替代的两个场景。

这批镜头怎么用? 先问用途,再问参数 常规 1× 播放 动作不需要放慢细看 2× 及以上慢放 要看清每一帧的姿态 逐帧对齐 / 超长时段 时间码要精确到帧 recordVideo fps:60 唯一 47.8 → 交付 30fps 够用 时间码直接用 -ss 裁 CDP 直采 唯一 77.9,慢放后 27.8 fps:90 也救不了 → 见 §5 CDP 直采 JPEG 序列 + 每帧时间戳 帧号可精确映射回时刻 两条链路的上游完全相同,切换成本 = 换一个采集函数,不用改页面驱动逻辑。 但下游成本不同:CDP 要自己管 meta.json、磁盘和批量编码,这是它的「税」。
图 9 · 决策树。三岔树里只有两个叶子指向 CDP,判断依据都是「对单帧信息量的需求」, 与录多久、分辨率多高无关。

·成本对照:性能之外的那一半

维度recordVideoCDP 直采
产物 1 个 webm(VP9,无音轨) N 张 JPEG + meta.json,编码另行
磁盘(9 秒 1080p) 23 MB(fps:60) 165 MB(903 张,均 183 KB)
时间码 直接可用:-ss 12.4 就够 需 帧号 ÷ 实测fps;各场 fps 在 60–98 漂移
分段录制 每个 page 一个文件,同一页不能中途分段 天然按场次起停,帧号从 0 开始
依赖 需要 Playwright 专用 ffmpeg 二进制 采集端零依赖(writeFileSync 而已)
最大唯一帧率 实测 58.8 实测 77.9(采集 97.85)
混合使用才是常态

本次成片 22 个镜头里,常规动作走 recordVideo,三处 2× 慢放走 CDP —— 两条链路同时存在不冲突, 因为它们只是同一个 page 上的两个消费者。真正的成本是「维护两套采集脚本」,代价约 40 行。

07无人值守:把窗口从等式里拿掉

前六节讨论的都是「帧拿到手之后谁负责编码」。还有一个与编码完全无关的维度: 窗口要不要出现在用户的屏幕上。它决定的是能不能批量跑、能不能不打扰人, 与画面质量、帧率上限是三件不同的事。这一节把三者拆开。

·一、窗口可见性本来就不该影响采集

原因在采集层的位置:CDP 的 Page.screencastFrame 交付的是 renderer 合成后的 surface 帧(GPU 进程里贴好的一块位图), 而系统录屏抓的是显示器的 framebuffer。前者与窗口是否被遮挡、是否最小化、 是否在前台完全无关 —— 它根本不知道「屏幕」长什么样。

运行状态CDP 抓帧 recordVideo 唯一帧合成按键是否仍生效
窗口在前台98.8 fps45.2 fps是
最小化到 Dock98.8 fps44.2 fps是(P1 血量 100→53)
8 个进程占满 CPU98.4 fps—是
最小化 + 满载99.0 fps—是
headless(无窗口)60.0 fps—是

最后一行和其他行不是一个量级,这是本节唯一真正的坑,下面单独讲。 先看一个反直觉的细节:页面在最小化时 rAF 仍然跑满 120fps。 不是因为游戏勤快,而是 screencast 在持续请求帧 —— 没有采集时,Chrome 会把最小化页面的 渲染节奏降到几乎停摆。是采集让页面保持活跃,而不是反过来。 实测

·二、真正的门槛不在窗口,在内核

headless: true 看起来只是「不显示窗口」的一个布尔值,但 Playwright 1.64 会据此选一个不同的浏览器二进制。两个二进制版本号一模一样, 能力却差一个数量级。

chromium.launch({ headless: true }) 一个布尔值,却决定了用哪个二进制 没有 channel channel: "chromium" chrome-headless-shell 独立下载 · 203 MB · 没有 .app 外壳 libEGL.dylib / libGLESv2.dylib = 736 B(占位) Google Chrome for Testing 与 headed 同一个二进制 · 366 MB 完整 ANGLE + Metal 后端 WebGL 渲染器返回 ANGLE (Google, Vulkan 1.3.0 (SwiftShader Device (LLVM 10.0.0)), SwiftShader driver) WebGL 渲染器返回 ANGLE (Apple, ANGLE Metal Renderer: Apple M2 Max, Unspecified Version) CPU 光栅化 → 实测 7.4 fps 不报错、不警告,只是变慢 GPU 光栅化 → 实测 60.0 fps 受虚拟 vsync 限制,见下一节 两者的 browser.version() 都是 156.0.8078.4 —— 版本号分辨不出来,只能读 WebGL 的 renderer 字符串。 这就是问题最隐蔽的地方:代码没变、API 没变、日志干净,只有帧率悄悄掉到七分之一。
图 10 · headless 的启动分叉。左右两侧的差异不在「显示不显示窗口」, 而在被选中的那个二进制里有没有真正的 GL 实现。左侧的 EGL/GLES 库是 736 字节的占位文件, GL 一路退到随包附带的 SwiftShader。
这个坑不会报错,只会变慢

第一次写采集器时用的是默认 headless: true,跑出来 4.6 fps。 我先后怀疑过三件事:写盘阻塞回调、JPEG 编码太重、页面没进战斗。 做了三组隔离实验(只计数不写盘、同步写、异步写)才发现三组都是 6–7 fps —— 问题在启动那一刻就已经定了,与采集循环无关。 实测

·三、60fps 是虚拟 vsync,不是性能极限

换成完整内核后,headless 稳定在 60.0fps,而 headed 是 98.8。这个差距不是性能差: headless 挂的是一块虚拟显示器,合成器按它 60Hz 的刷新率出帧;headed 用的是这块 120Hz 的屏幕, 所以能给到近百帧。换句话说,60 是节拍器,不是天花板。

验证这个判断的办法是解掉 vsync 看会不会更快。结果是更慢:加上 --disable-frame-rate-limit + --disable-gpu-vsync 后, rAF 失去节拍,合成器满载而 screencast 的在途窗口被打满(回到 §5 的 maxFramesInFlight),有效帧率反而崩到 13fps。 实测 这从反面印证了「配额 ≠ 产能」:限速器从来不在 fps 参数上,而在合成器真正能产出多少帧。

同一游戏场景 · 1920×1080 · CDP 采集 9 秒动作段 运行形态 / 内核 用户是否看得见 headless 默认 7.4 完全看不见 ✓ 但帧率不可用 headless + channel 60.0 ← 2× 慢放的安全边界 完全看不见 ✓ 2× 慢放刚够 30fps 窗口最小化 98.8 Dock 多一个图标 启动瞬间还会闪一下 窗口在前台 98.8 占满屏幕 等于把电脑借出去 0 25 50 75 fps 第二行留了 2:1 的余量:60 ÷ 2 = 30,正好是 2× 慢放后要交付的帧率 —— 实测 266 个唯一帧 / 8.87 秒 = 30.0fps,无重复帧。 红色的 7.4 不是抖动,是软件光栅化的稳定产能 —— 同一配置多次运行落在 4.6–7.4 之间。
图 11 · 四种形态的取舍。帧率最高的一列恰恰是最打扰人的一列。 真正的可用区间是第二行:用户零感知,同时守住 60fps —— 它需要的只是一个参数。

·四、两条「把窗口藏起来」的路,被系统堵死了

在想到 headless 之前,我先试了两个更省事的办法,都被操作系统挡回来了:

  • 把窗口移到屏幕外:--window-position=-4000,-4000 在 macOS 上被忽略, 回读窗口 bounds 是 left=0 top=33,被夹回了主屏左上角。 实测
  • 最小化窗口:帧率不掉(98.8),但 Dock 会多出一个图标,启动瞬间还会闪一下。 用户明确要求「无感知」,这就不算。

结论是:只有 headless 是真正的零窗口。而且它顺带解决了一个原本很别扭的约束 —— 有窗口时「不能去点那个浏览器窗口」,因为合成事件和真实事件走同一条输入管线; headless 没有窗口可点,这条约束自动消失。

·五、落地实现:四个关键点

这些都已经收进 promo/capture/record.mjs,一条命令从头到成片。四个地方值得单独说明:

  1. channel 优先,失败自动回退

    先按 channel: "chromium" 启动;如果本机没装完整内核再退回默认值, 并打印警告告诉使用者帧率会崩。宁可吵,也不要静默降级。

    // 关键:headless 默认会落到 chromium-headless-shell(SwiftShader,实测 7 fps)
    // channel:"chromium" 才是完整 Chrome,headless 下仍走 Metal,实测 60 fps
    try {
      browser = await chromium.launch({ ...launchArgs, channel: "chromium" });
    } catch {
      browser = await chromium.launch(launchArgs);
      console.warn("警告:回退到默认 headless 内核,GPU 可能不可用,帧率会大幅下降");
    }
  2. 先 ack,再异步写盘

    screencast 有在途窗口(§5),浏览器等你的 ack 才发下一帧。 同步写一张 1080p JPEG 会让回调阻塞约 40ms,直接压低采集节奏。 正确顺序是:ack 立刻发,写盘丢给 promise。

    cdp.on("Page.screencastFrame", (e) => {
      const seq = ++index;
      // 先 ack 再写盘:同步写 1080p 帧会让回调阻塞 40ms,直接压掉采集帧率
      cdp.send("Page.screencastFrameAck", { sessionId: e.sessionId }).catch(() => {});
      writes.push(writeFile(`${dir}/${seq}.jpg`, Buffer.from(e.data, "base64")));
    });
  3. 内置静态服务器,随机端口

    不再依赖一个常驻的 npm run preview:脚本自己起一个只监听 127.0.0.1 的服务,端口交给系统分配,跑完就关。 这消掉了「预览服务被回收导致 502」这类与采集无关的失败。

  4. 开录前断言真的进了战斗

    这次踩过:脚本按了键、K 线一样跑完,但页面停在标题界面,录出来是一段静止画面。 现在开录前读一次 __velvetDebug(),phase 不是 fight 就直接抛错, 而不是等剪辑时才发现素材废了。

    const d = await page.evaluate(() => window.__velvetDebug());
    if (d?.phase !== "fight") throw new Error(`未能进入对战,phase=${d?.phase}`);
一条命令,默认零窗口node promo/capture/record.mjs --out promo/clips/demo.mp4 --seconds 10 --demo

# 实测输出:1920×1080 · 59.98fps · 531 帧 · 8.87s · 7.6MB
# --mode window  退回到有窗口的高帧率模式(98.8fps)

·六、无感的边界:还有三件事会打断你

  • 休眠 / 锁屏 / 合盖:进程被杀,采集中断。无人值守≠可以不插电。
  • 改分辨率或屏幕缩放:viewport 一变,前后片段尺寸不一致,拼接会跳。
  • 本机必须有 GPU:这条是硬前提。如果以后把它搬到 GitHub Actions 之类的无 GPU 环境,会退化成 SwiftShader 的 7fps —— 对 3D 场景来说这条路不成立。
一句话

无感的代价不是帧率,而是一个参数:把 channel: "chromium" 写上去, headless 就从 7.4fps 变成 60fps。忘记写它,你会得到一段又慢又看不出来哪里错的素材。

08工程约束:五条会咬人的规则

这些都不是「最佳实践」,而是踩过之后总结的硬约束 —— 违反任何一条,产物就是废的。

·一、关闭顺序决定文件是否完整

ctx.close() → video.saveAs() → browser.close()。 顺序颠倒会报 Target closed,或者拿到一个没有索引的 webm(能播,但时长显示为 0)。

·二、一个 page 只出一个文件

recordVideo 配在 context 上,但产物是每个 page 一个 webm(文件名取 page 的 guid)。 公开 API 没有分段录制;内部虽有重启录制的私有方法,但不要依赖。 正确做法是一次录一整场,后期按 marks 裁切:脚本记录每段动作的起止时刻,剪辑时按时间码切。 这样反而比中途起停更稳,因为不用担心文件碎片。

·三、尺寸会被强制取偶

源码里 width & ~1、height & ~1 —— yuv420 要求偶数边长。 传 1919 会静默变成 1918。不要用奇数分辨率设计分镜。

·四、录制从 context 创建开始,不是从 goto 结束开始

所以每段成片开头都带着页面加载期(本次约 7–9 秒,因为要等 10 MB 的 GLB 模型)。 两个处理方式:剪辑时按 marks 裁掉;或者干脆录前先静置到画面稳定,把「加载期」压到最短。

·五、headless 能录,但不是「开了就行」

不需要虚拟显示器、不需要 headed 模式,CDP screencast 走的是合成器输出,与窗口是否可见无关。 但默认 headless: true 启动的不是完整 Chrome:它会换成 chrome-headless-shell,WebGL 退到 SwiftShader,实测只剩 7.4fps 且不报错。 必须显式写 channel: "chromium" 才拿回 60fps —— 详见 §7 无人值守。 顺带一提,--mute-audio 要自己加,音频不会进 webm(-an)。

09故障对照表

按「症状 → 先查什么 → 根因 → 修法」排列。这些症状的共同点是:都不报错,或者报错信息指向错误的方向。

症状先查什么根因与修法
Executable doesn't exist at …/ffmpeg-1013/ffmpeg-mac ls ~/Library/Caches/ms-playwright/ffmpeg-1013/ 有没有 INSTALLATION_COMPLETE 组件下载中断。跑 npx playwright install ffmpeg(2.9 MB,最快)。
Executable doesn't exist at …/chromium-1248/… npx playwright --version 与 install --dry-run 对比 revision 升级了 JS 包但没重装浏览器(缓存里还是旧 revision)。npx playwright install chromium。
成片糊、只有 800×450 ffprobe -show_entries stream=width,height 没传 recordVideo.size,被按 800 上限缩放。显式传 1920×1080。
帧率恒定 25,怎么调都不变 ffprobe -show_entries stream=r_frame_rate 没传 fps,落到 kDefaultFps=25。传 fps: 60。
设了 90fps 还是很卡 去重:mpdecimate 后数唯一帧 标称是配额不是产能。要么接受 60,要么换 CDP。
headless 下只有 5–7fps,不报错 读 WebGL 的 UNMASKED_RENDERER_WEBGL,看有没有 SwiftShader 默认 headless: true 落到 chrome-headless-shell,无 GPU 合成。加 channel: "chromium" → 60fps(见 §7)。
Target closed 三个关闭调用的顺序 先 ctx.close(),再 saveAs,最后 browser.close()。
录到一半画面冻结 采集回调里是否 await 了耗时操作 没回执 = 在途窗口塞满 = Chromium 停止推帧。回执要早于重活,或把重活挪到队列。
CDP 采集成片时间对不上 有没有存 meta.json 帧间隔不均匀,不能用固定 fps 换算。每场记录总帧数/总耗时。

·验证「帧率是否真实」的标准动作

两个数都要看:容器声明的帧率(r_frame_rate)和去重后的唯一帧数。 只看前者会被骗,只看后者不知道时间轴对不对。

去重检测# 声明帧率 + 总帧数
ffprobe -v error -count_frames -select_streams v:0 \
  -show_entries stream=r_frame_rate,nb_read_frames -of csv=p=0 app.webm

# 唯一帧:mpdecimate 丢掉近似重复帧,剩下的才是真信息量
ffmpeg -i app.webm -vf "mpdecimate=hi=768:lo=320:frac=0.33" \
  -vsync 0 -f null - 2>&1 | tail -1
# frame= 529  ← 与声明的 810 相差 281,就是重复帧

10速查与复跑

本节是可以直接抄走的部分。所有数字都来自 promo/recordvideo-benchmark.json, 换了机器想重新对比,改路径重跑即可。

·两套采集器,外加一条命令

A · recordVideoconst ctx = await browser.newContext({
  viewport: { width: 1920, height: 1080 },
  recordVideo: { dir: "raw", size: { width: 1920, height: 1080 }, fps: 60 },
});
// 一场一录;动作起止用 marks 记录,剪辑按 marks 裁
const v = page.video();
await ctx.close();
await v.saveAs("raw/scene-b.webm");
B · CDP 直采const cdp = await ctx.newCDPSession(page);
let n = 0, t0 = Date.now();
cdp.on("Page.screencastFrame", ({ data, sessionId }) => {
  // 回执先发(不 await),写盘丢给 promise —— 顺序反了会压掉采集帧率
  cdp.send("Page.screencastFrameAck", { sessionId }).catch(() => {});
  writeFile(`${dir}/${String(n++).padStart(6,"0")}.jpg`, Buffer.from(data, "base64"));
});
await cdp.send("Page.startScreencast", {
  format: "jpeg", quality: 92, maxWidth: 1920, maxHeight: 1080,
});
// ... 动作 ...
await cdp.send("Page.stopScreencast");
writeFileSync(`${dir}/meta.json`, JSON.stringify({ frames: n, ms: Date.now() - t0 }));
C · 无窗口跑批// 关键是 channel:不加它,headless 会掉到 SwiftShader 的 7fps
const browser = await chromium.launch({ headless: true, channel: "chromium" });

// 现成脚本:自带静态服务器,跑完直接出 mp4
// node promo/capture/record.mjs --out clips/demo.mp4 --seconds 10 --demo

·参数怎么定:从交付目标倒推

  1. 先定输出帧率

    平台通常 30fps 足够。定 30,别再往上加。

  2. 再定慢放倍率

    有 2× 慢放就要源 ≥ 60 唯一帧/秒;没有就只需 ≥ 30。

  3. 反查方案产能

    recordVideo@60 是 47.8,@90 是 58.8;CDP 是 77.9。都不够就降倍率,不要提 fps。

  4. 最后才选方案

    1× 且 ≥30 唯一帧 → recordVideo;需要 ≥60 → CDP。

  5. 录完必须验证

    mpdecimate 去重数唯一帧,与预期对账。

这次真正学到的

「参数能不能调」和「调了有没有用」是两件事。1.64.1 确实支持 recordVideo.fps, 但它的作用被两处硬限制夹住了 —— 只查文档会以为 90 就是 90,只有去数唯一帧才知道不是。 以后遇到任何「帧率/采样率」类参数,默认它描述的是配额,然后用去重验证产能。