browser-video-recording

浏览器视频录制

何时使用此技能

• 当用户要求录制或重新录制浏览器操作（点击、滚动、导航）并制作精致的演示视频时使用。
• 当制作 Dribbble/UI 灵感视频或产品演示录屏，且需要自然的 macOS 光标、精心设计的点击节奏和平稳的缩放跟随画面时使用。
• 当用户询问 Codex、Playwright 或 MCP 是否能制作自然的浏览器演示视频时使用，因为此技能定义了三层依赖模型（Codex 应用内浏览器捕获、本地 ffmpeg/Pillow 渲染器、可选的原生录制器）。
• 当需要通过 scripts/render_browser_demo.py，将 Codex 应用内浏览器截图渲染为确定性的 60 fps、4:3、4K MP4 输出时使用。
• 当需要使用 ffprobe 和视频中段缩略图检查，验证成片的分辨率、帧率、时长和光标准确性时使用。
• 不适用于与 Codex 应用内浏览器无关的一般桌面录屏，也不适用于超出光标/缩放演示渲染范围的视频编辑——这些任务需要其他录制或编辑工具。

依赖模型

将工作流分为三层：

1. 浏览器控制与源帧：通过 Browser 技能/MCP 使用 Codex 应用内浏览器。用户要求使用 Codex 浏览器或项目明确禁止使用 Chrome 时，不要使用 Chrome。浏览器层提供真实截图，以及真实的点击、滚动和导航状态。
2. 本地视频渲染器：使用捆绑的 Python 脚本，将截图渲染为 MP4，并添加自然的 macOS 光标、细微的点击缩放效果和平稳的缩放跟随画面。此步骤不需要屏幕录制 MCP。
3. 可选的原生录制器集成：仅在原生录制 MCP 可调用且确实有用时使用，例如启动/停止实际应用录制或打开生成的项目。如果不可用、受到阻止或无法捕获 Codex 浏览器画面，则改用截图转视频渲染器，并说明此回退方案。

自包含执行

只要安装了完整的技能文件夹（包括 scripts/render_browser_demo.py），其他 Codex 实例就可以使用此技能执行 Python 渲染。Codex 应运行捆绑的脚本，而不是重新创建渲染器。

所需的本地工具：

• python3
• Python 包 Pillow
• ffmpeg 和 ffprobe

可选的 macOS 光标提取需要 swift 和 /usr/sbin/screencapture。如果无法使用这些工具，请通过 cursor_asset 提供透明 PNG，并在配置中设置 cursor_hotspot。

如需获取新的 Codex 应用内浏览器截图，仍需 Browser 技能/MCP。如果不可用，请使用现有的最佳浏览器自动化截图来源，并说明所采用的回退方案。

可选的原生录制器支持

对于原生应用录制，请确认 MCP 支持：

• 使用 frameRate: 60。
• 使用 resolutionRawValue: "4K"。
• 区域录制时使用 ratioPresetRawValue: "4:3"。
• 裁剪嵌入式浏览器视口时，使用明确的 selectedRegionOnScreen。

对于本地渲染器，4K 4:3 即 3840x2880。如果原生录制器提供 4K 枚举值，请将其视为应用侧分辨率预设，并在通过该 MCP 录制时搭配 4:3 区域选择。

捕获工作流

首先使用 browser:control-in-app-browser。查看其文档后，使用 Node/browser API 操控内置浏览器：

• 将视口设为 1920x1440，以输出 4:3 4K，然后在结束前重置视口。
• 前往指定页面，并实际执行点击、返回、搜索和滚动操作。
• 每次重要状态变化后保存仅来自浏览器的截图。使用类似 01-results-top.png、02-after-card-click.png、03-back-results.png 的名称。
• 记录每个点击或滚动目标的视口坐标。最终光标路径应落在这些点上，暂停、点击，然后移至下一个有意义的位置。

除非用户明确需要操作系统界面，否则避免使用桌面坐标自动化。Codex 的浏览器可见性可能无法呈现可捕获的 macOS 画面；浏览器 API 截图是可靠的来源。

动效规则

让光标移动显得有目的性：

• 使用稀疏、以直线为主的光标路径。
• 点击前在目标上短暂停留。
• 不要在无关的界面上游移。
• 点击后再让页面发生转换，而不是提前转换。
• 仅使用微妙的点击反馈：缩放后回弹；除非用户要求，否则不要使用装饰性圆环。
• 缩放跟随应比光标移动更平缓。镜头应框选被点击的内容，而不是追逐每次细小的鼠标移动。

默认视觉目标：

• 使用从合成器中提取的真实 macOS 指针，或现有的透明光标素材。
• 光标缩放比例设为 3.0，与编辑演示录制中常见的大光标样式一致。
• 点击动画强度设为 15，产生微妙的点击缩放效果。
• 旋转强度最高为 8deg，且仅由水平速度触发。

渲染脚本

使用 scripts/render_browser_demo.py 生成确定性的 60 fps、4:3 4K 输出：

python3 /path/to/browser-video-recording/scripts/render_browser_demo.py \
  --config /tmp/browser-demo-config.json \
  --output /tmp/browser-demo-4x3-4k-60fps.mp4

生成初始配置：

python3 /path/to/browser-video-recording/scripts/render_browser_demo.py --write-template

配置包含：

• shots：状态名称到截图 PNG 路径的映射。
• scene_starts：[time, shotName, transition] 条目。
• cursor_keys：视口坐标条目 [time, x, y]。
• camera_keys：[time, x, y, zoom] 条目。
• click_times：点击时间戳。
• duration、fps、output_size、source_size、cursor_scale。

推荐的默认值：

{
  "fps": 60,
  "output_size": [3840, 2880],
  "source_size": [1920, 1440]
}

如果省略 cursor_asset，脚本会短暂显示纯色叠加层，并使用 screencapture 将当前 macOS 光标提取为透明 PNG。这是本地渲染辅助功能，不是 MCP 依赖项。

验证

始终验证交付的视频：

ffprobe -v error \
  -show_entries stream=codec_name,width,height,r_frame_rate \
  -show_entries format=duration,size \
  -of json /path/to/output.mp4

提取至少一张视频中段的缩略图并检查：

ffmpeg -y -ss 8 -i /path/to/output.mp4 -frames:v 1 -update 1 /tmp/browser-demo-thumb.png

确认：

• 分辨率为指定的输出分辨率，通常 4:3 4K 为 3840x2880。
• 帧率为 60/1 或等效值。
• 时长符合要求。
• 光标清晰可见、自然且位于目标位置。
• 视频裁剪的是浏览器内容，而不是桌面。
• 浏览器视口覆盖设置已重置。

参考资料

• 上游来源：MengTo/Skills — browser-video-recording
• scripts/render_browser_demo.py — “渲染脚本”部分中使用的确定性 60 fps、4:3 4K 渲染器