揭秘ProofShot视频剪辑:ffmpeg如何自动剪除Agent思考的"死时间"
揭秘ProofShot视频剪辑:ffmpeg如何自动剪除Agent思考的"死时间"
ProofShot 是一款给 AI 编程 Agent"装上眼睛"的开源可视验证工具:它录制浏览器操作视频、截图关键步骤、收集错误,并用 ffmpeg 自动剪除视频中 Agent 思考产生的"死时间",交付一段紧凑有力的证明视频。本文带你揭秘这个视频剪辑功能背后的完整设计与实现。
为什么证明视频会有一段段"死时间"
ProofShot 的录制在 proofshot start 执行的瞬间就开始。但 AI Agent 通常要先"思考"20~30 秒,才会真正动手操作浏览器——这意味着视频开头是 30 秒纹丝不动的静止画面;动作做完后、proofshot stop 执行前,又可能堆出一段空白。
看视频的人体验到的就是:空白 → 十几秒真实操作 → 又空白。证明力被死时间严重稀释。
这个痛点在提案 issues/01-video-dead-time-trimming.md 中被完整描述,方案方向是:在 proofshot stop 时做视频后处理,只保留"有动作"的区间。
上图中是验证完成后生成的产物文件夹,三个关键文件正好构成剪辑的"时间坐标系":session.webm(完整录屏)、session-log.json(每次操作的时间戳)、step-*.png(关键时刻截图)。
如何定位视频的有效区间:双数据源时间戳
剪辑逻辑的核心是 src/commands/stop.ts 中的 trimVideo 函数,它取"第一动作"和"最后一动作"的时间,策略是双数据源:
- 首选:操作时间日志。 每次
proofshot exec执行点击、截图等动作时,都会把相对会话开始的秒数写入session-log.json(结构见 SessionLogEntry)。日志首尾两条记录,就是精确的有效区间。 - 兜底:截图创建时间。 若 Agent 没走
proofshot exec而没留下日志,则改用所有.png截图的文件创建时间(birthtime)来推断首尾动作时刻。
拿到两个边界后,还要各留一段"呼吸空间":
- 第一个动作前 5 秒——让观者看到操作前的准备;
- 最后一个动作后 3 秒——让结果完整呈现。
trimStart = max(0, 首个动作时间 - 5s)
trimEnd = 最后动作时间 + 3s
边界情况也被照顾到:没有任何截图或日志 → 不剪;有效区间不足 5 秒的极短视频 → 不剪。
ffmpeg 自动剪除死时间:一行命令无损裁剪
算出裁剪点后,ProofShot 调用 ffmpeg 完成切割(src/commands/stop.ts):
ffmpeg -i session-raw.webm -ss 5.00 -to 12.30 -c copy session.webm
三个工程细节值得玩味:
-c copy流拷贝,不重编码:直接按关键帧切流,秒级完成且画质零损失,2MB 的视频几乎瞬间剪完;- 先改名再剪,失败可还原:原视频先被改名成
session-raw.webm,一旦 ffmpeg 失败就自动还原回原文件——剪辑永远"毁不掉"你唯一的视频; - 没有 ffmpeg 就静默降级:流程不会中断,只提示一句
Tip: Install ffmpeg to auto-trim dead time from videos.——剪辑是增强项,而非硬依赖。
这正是 架构文档 中强调的设计哲学:优雅降级无处不在(graceful degradation everywhere),非关键失败永不中止会话。
剪掉开头后,时间线如何保持精准同步
视频开头被剪掉 N 秒,viewer 里的"动作标记"岂不是全部错位?ProofShot 的办法是整体平移时间戳:session-log.json 中每条记录的 relativeTimeSec 统一减去裁剪偏移量 trimOffsetSec,Console 日志和 Server 日志的时间戳也同步调整(src/commands/stop.ts)。
于是交互式 viewer 中,进度条上的操作标记、右侧时间轴、视频实际内容三者依旧严丝合缝:
点击时间轴任意一步直接跳转到视频对应时刻;剪完后的产物里,session.webm 只有有效操作那十几秒,观者无需快进跳过任何空白。
不只是裁剪:ffmpeg 的第二用途——上传 PR 前的格式转换
ffmpeg 在 proofshot pr(把验证产物发到 PR 评论)中还有一处暗线:部分平台对 .webm 播放不友好,于是若检测到 ffmpeg,会自动转成 MP4(src/commands/pr.ts):
ffmpeg -i session.webm -c:v libx264 -preset fast -crf 23 -an session.mp4
-preset fast -crf 23 是"编码快 + 质量好"的实用组合;ffmpeg 不在场时则原样上传 .webm,流程照走。
如何验证 ffmpeg 已生效:自检步骤
- 跑一次体检。 执行
proofshot doctor,它会直接列出 ffmpeg 的查找路径与版本号(src/commands/doctor.ts)。若显示not found,装好 ffmpeg 再跑一次即可。 - 在示例 App 里亲手试。 仓库内置了开箱即用的样例项目 test/fixtures/sample-app,启动验证会话后故意停顿几秒(模拟 Agent 思考),截两张图,再
proofshot stop——终端会打印Trimmed video to Xs (removed dead time),视频时长应是十几秒而非几十秒。 - 回看 viewer 验证同步。 打开
viewer.html的 Console 标签页,日志时间戳应与剪辑后的视频严格对齐,没有偏移:
常见问题
Q:没装 ffmpeg 会怎样? A:完全不影响主流程。完整视频原样保留,截图、日志、viewer 照常生成,只是跳过自动裁剪。
Q:为什么录屏是 .webm 而不是 .mp4?
A:浏览器录屏走 Playwright screencast 通道,原生输出 .webm,录制阶段零 ffmpeg 依赖;ffmpeg 只承担剪辑与 PR 上传转换这类后处理工作。
Q:5 秒 / 3 秒的 buffer 能改吗?
A:可以。调整 src/commands/stop.ts 中的 BUFFER_BEFORE / BUFFER_AFTER 两个常量即可。
总结
ProofShot 的视频剪辑能力,本质是一套三步走设计:
| 环节 | 用什么 | 目的 |
|---|---|---|
| 定位时间锚点 | session-log.json / 截图创建时间 |
找出 Agent "真正动手"的区间 |
| 无损剪辑 | ffmpeg -ss / -to + -c copy |
秒级剪掉前后死时间,画质零损失 |
| 时间戳平移 | 全体日志统一减去偏移量 | viewer 时间轴与视频永远同步 |
下次 AI Agent 帮你写完功能,你不再需要快进跳过证明视频头尾各 30 秒的静止画面——ffmpeg 已经替你做好了。


