视频录制

使用 record 将浏览器自动化过程录制为 WebM 或 MP4 视频，用于调试、CI 证据、产品演示或问题复现报告。

要求¶

录制功能会将帧通过管道送入 ffmpeg，ffmpeg 必须位于 PATH 中，并带有 libvpx 和 libx264 编码器（Homebrew 和 Debian/Ubuntu 的默认构建均包含这两者）：

brew install ffmpeg        # macOS
sudo apt install ffmpeg    # Debian/Ubuntu
agent-browser doctor       # reports ffmpeg and its encoders under "Recording"

支持的格式为 .webm（通过 libvpx 编码的 VP8）和 .mp4（通过 libx264 编码的 H.264）。任何其他扩展名都会原样交给 ffmpeg，视频采用 H.264 编码，因此只要 ffmpeg 认识该容器，.mkv 或 .mov 也能正常工作。没有扩展名的路径会在录制开始前被拒绝，因为 ffmpeg 将无从选择容器。agent-browser 中的其他任何功能都不需要 ffmpeg。

基本工作流程¶

agent-browser open https://example.com
agent-browser record start ./demo.webm
agent-browser snapshot -i
agent-browser click @e1

agent-browser record stop

启动会话后，record start 也可以立即导航：

agent-browser open
agent-browser record start ./demo.webm https://example.com

record start 按原样录制当前活动页面。如果不提供 URL，则不会导航或替换任何内容：录制器会附加到你已打开的标签页上，因此捕获从已水合（hydrated）的页面开始，而不是在冷导航的 load 事件时开始。如果提供 URL，活动标签页会先导航到该地址，页面加载完成后录制开始。不会创建额外的标签页或浏览器上下文。

要在单独的标签页中录制，请先打开一个：

agent-browser tab new https://example.com
agent-browser record start ./demo.webm

可见光标¶

Chrome 录制通常不包含原生指针。添加 --cursor 可渲染一个随页面显示的动画指针和点击波纹，并保持拖拽在每一捕获帧中同步。临时叠加层是惰性的，对无障碍快照不可见，并在录制停止时被移除。录制期间拍摄的截图会包含它：

agent-browser record start ./walkthrough.webm --cursor

联系表¶

添加 --contact-sheet 可生成带时间戳的 PNG 联系表，其中会高亮显示变化区域。

agent-browser record start ./checkout.webm --contact-sheet

# Select a frame when at least 2% of pixels change
agent-browser record start ./checkout.webm --contact-sheet-threshold 0.02

阈值接受 0 到 1 之间的值，默认值为 0.05，并隐含启用 --contact-sheet。联系表最多包含 100 帧。

Example contact sheet with timestamps and highlighted change regions

帧率¶

录制默认每秒捕获 30 帧，足以让滚动、悬停状态和 CSS 过渡呈现为运动感而不是幻灯片效果。使用 --fps 可更改帧率：

# 60 fps for a short, motion-heavy take
agent-browser record start ./scroll.webm --fps 60

# 10 fps for a long soak run where file size matters more than motion
agent-browser record start ./soak.webm --fps 10

帧率	适用场景
60	拖拽交互、动画和滚动效果打磨，任何需要以单帧作为证据的场景。最适合短视频。
30（默认）	其他所有场景：流程、CI 证据、产品演示。
1 到 15	长时间会话，视频更像是一条时间线而非运动研究。

有效帧率为 1 到 60。在重绘间隔期间会保持 Chrome 的最新帧，因此文件时长与实际经过的时间一致。

record stop 会报告写入文件的 frames 数量，以及从 Chrome 接收到的去重后的 capturedFrames 数量。

命令¶

命令	描述
`record start <path.webm\|path.mp4> [url] [--fps <n>] [--cursor] [--contact-sheet]`	开始录制活动页面；提供 URL 时先导航活动标签页
`record stop`	停止当前录制并保存文件
`record restart <path.webm\|path.mp4> [url] [--fps <n>] [--cursor] [--contact-sheet]`	停止当前录制并立即开始新的录制

CI 证据¶

#!/bin/bash
set -e

cleanup() {
  agent-browser record stop 2>/dev/null || true
  agent-browser close 2>/dev/null || true
}
trap cleanup EXIT

agent-browser open https://app.example.com/login
agent-browser record start "./artifacts/login-flow.webm"
agent-browser snapshot -i
agent-browser fill @e1 "demo@example.com"
agent-browser fill @e2 "password"
agent-browser click @e3
agent-browser wait --url "**/dashboard"

当浏览器故障难以仅凭文本输出诊断时，请将录制文件保留为 CI 制品。

供人观看的演示¶

当视频是供人观看时，请添加短暂的等待：

agent-browser open https://shop.example.com
agent-browser record start ./checkout.webm
agent-browser wait 500
agent-browser click @e4
agent-browser wait 500
agent-browser screenshot ./screenshots/cart.png
agent-browser record stop

截图和视频搭配使用效果很好：截图捕获精确的静态状态，而视频展示时序、过渡和意外出现的叠加层。

输出格式¶

属性	值
容器	WebM（`.webm`，通过 libvpx 编码的 VP8）或 MP4（`.mp4`，通过 libx264 编码的 H.264），由扩展名决定；其他扩展名使用 H.264 编码，放入 ffmpeg 映射到的任意容器中
编码器	`PATH` 上的 ffmpeg
帧率	默认 30 fps，使用 `--fps` 可设为 1 到 60
视口	使用活动浏览器的视口设置
状态	按原样录制活动页面，包括其会话和页面内状态

限制¶

录制会给自动化带来额外开销，帧率越高，开销越大。
长时间录制可能占用大量磁盘空间；60 fps 的比特率大约是 30 fps 的两倍。
每秒的实际帧数受页面重绘频率的限制，因此页面渲染低于 60 fps 时，录制的帧率也会低于 60 fps。
如果需要将文件刷新写入磁盘，请在关闭会话前使用 record stop。
某些受限的无头环境可能存在编解码器或 GPU 限制。未包含 libvpx 或 libx264 构建的 ffmpeg 无法写入相应的格式；agent-browser doctor 会报告当前存在哪些编码器。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 agen/agent-browser