揭秘ProofShot视频剪辑:ffmpeg如何自动剪除Agent思考的"死时间"

原创2026-10-25 13:59:201,646 阅读

揭秘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 时做视频后处理,只保留"有动作"的区间。

ProofShot验证产物文件夹:session.webm证明视频与session-log.json操作时间日志是死时间剪辑的数据来源

上图中是验证完成后生成的产物文件夹,三个关键文件正好构成剪辑的"时间坐标系":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 中,进度条上的操作标记、右侧时间轴、视频实际内容三者依旧严丝合缝:

ProofShot交互式验证viewer:时间轴动作标记在ffmpeg剪除死时间后仍与证明视频精准同步

点击时间轴任意一步直接跳转到视频对应时刻;剪完后的产物里,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 已生效:自检步骤

  1. 跑一次体检。 执行 proofshot doctor,它会直接列出 ffmpeg 的查找路径与版本号(src/commands/doctor.ts)。若显示 not found,装好 ffmpeg 再跑一次即可。
  2. 在示例 App 里亲手试。 仓库内置了开箱即用的样例项目 test/fixtures/sample-app,启动验证会话后故意停顿几秒(模拟 Agent 思考),截两张图,再 proofshot stop——终端会打印 Trimmed video to Xs (removed dead time),视频时长应是十几秒而非几十秒。
  3. 回看 viewer 验证同步。 打开 viewer.html 的 Console 标签页,日志时间戳应与剪辑后的视频严格对齐,没有偏移:

ProofShot viewer控制台日志页:日志时间戳与ffmpeg剪辑后的视频时间同步对齐

常见问题

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 已经替你做好了。

登录后查看全文
proofshot