browser-video-recording

浏览器视频录制

依赖模型

将工作流分为三个层次：

1. 浏览器控制和源帧：通过 Browser skill/MCP 使用 Codex 内置浏览器。用户要求使用 Codex 浏览器，或项目明确要求不要使用 Chrome 时，不要使用 Chrome。浏览器层提供真实截图，以及真实的点击、滚动和导航状态。
2. 本地视频渲染器：使用随附的 Python 脚本，将截图渲染为 MP4，并添加自然的 macOS 光标、轻微的点击缩放效果和舒缓的缩放跟随取景。此过程不需要屏幕录制 MCP。
3. 可选的原生录制器集成：仅当原生录制 MCP 可调用，且明确适用于启动／停止实际应用录制或打开生成的项目时，才使用它。如果不可用、受到阻止，或无法捕获 Codex 浏览器界面，则改用截图转视频渲染器，并说明回退方案。

独立执行

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

所需的本地工具：

• python3
• Python 包 Pillow
• ffmpeg 和 ffprobe

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

如需获取新的 Codex 内置浏览器截图，仍需使用 Browser skill/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 或等效值。
• 时长符合要求。
• 光标清晰可见、自然且位置准确。
• 视频仅裁剪浏览器内容，不包含桌面。
• 浏览器视口覆盖设置已重置。