让编程 Agent 在本地完成视频剪辑
ffmpeg-skill 将 42 个 FFmpeg 工具封装为 Agent Skill 和 MCP 服务,支持剪切、字幕、画面适配、响度调整及平台导出。可接入 Claude Code、Cursor、Codex 等客户端,在本地处理并检查输出,无需云服务或 API 密钥。
AI 深度解读
让 Claude Code、Cursor 或 Codex 剪视频,难点不只是生成一条 FFmpeg 命令,还包括识别素材、选择处理方式,以及确认成品真的符合要求。ffmpeg-skill 的做法是把这些步骤固定下来:先测量,再编辑,最后检查文件和画面。
它提供 42 个本地工具,也暴露为 MCP 工具。对程序员来说,更值得看的不是功能数量,而是它如何约束 Agent:参数从哪里来,执行前检查什么,执行后凭什么说「完成」。
会写 FFmpeg 命令,为什么还需要工具层
作者指出,Agent 即使知道 FFmpeg,也可能猜错帧率、选用容器不支持的编码,或者把只需复制码流的文件重新编码。更麻烦的是,命令执行成功后,它可能直接报告完成。
ffmpeg-skill 把工作流固定为 probe → edit → check → verify。第一步必须运行 probe.py,测量时长、帧率、分辨率、旋转、色彩和音轨,还包括可变帧率、位深与 Dolby Vision 等信息。后续决策以文件实测结果为依据。
编辑阶段尽量避免重编码。cut.py 和 loudness.py 会复制无需修改的流;join.py 默认重编码,以便处理转场和规格不同的片段,素材已经匹配时可以用 --copy --transition none 直接拼接。精确到帧的裁剪、滤镜和格式变化仍可能要求重编码。
命令退出成功,只能证明执行结束,不能证明交付合格。
原文给出的例子是:保留采访中的两段内容,再生成 60 秒竖屏视频。Agent 依次调用 probe.py、cut.py --segments 0:45-3:10,5:00-6:30、fit.py --duration 60 --aspect 9:16 --fit crop、export.py --preset reels、check.py --platform reels 和 look.py,最终报告实测为 59.98 秒、1080×1920、30 fps、AAC 双声道。
这里也有一个小问号:请求是「恰好 60 秒」,示例交付是 59.98 秒。原文没有在这一例里解释容差,接入自动验收时需要自行明确标准。

42 个工具,怎样避免接口和实现各说各话
这些操作被封装成带类型参数的 Python 脚本,不经过 shell,也不接受调用方传入任意滤镜图。调用方选择操作并填写参数,工具负责构造 FFmpeg 调用。
更有借鉴意义的是作者命名的 SPEC,即 Self-Producing Execution Contract:工具的 input_schema 直接从运行时的 argparse 解析器生成。CLI 已经定义过的类型、默认值、枚举和互斥关系,不再维护第二份。
这个自动生成有明确边界。工具角色、能力需求、输入输出说明和 output_schema 仍来自手写的 TOOL_META。CI 检查它们是否漂移,不能替人修正描述。
下面的命令用于读取契约,第三条可以只取某个工具,减少送给 Agent 的内容:
npx ffmpeg-skill contract --json # or: python3 scripts/_contract.py --json
npx ffmpeg-skill contract --json --static # without environment detection
npx ffmpeg-skill contract --json --tool cut # one tool's entry under `tools` (repeatable): ~60 KB, not ~950 KB
重点看第三行的 --tool cut:完整契约约 950 KB,单工具条目约 60 KB,机器可读不等于适合每轮全部塞进上下文。
MCP 也复用这份契约。mcp/server.py 通过 stdio JSON-RPC 提供服务,tools/list 默认只公布核心 12 个工具;设置 FFMPEG_SKILL_MCP_FULL=1 才列出全部 42 个。不过,两种情况下都能通过 tools/call 按名称调用全部工具。
这套设计值得做 Node 工具服务的团队参考:参数定义尽量只有一个来源,再派生 CLI 和 Agent 接口。它减少的是重复维护,不会自动证明业务实现正确。
本地执行和自动检查,分别保证了什么
运行基础是 PATH 中的 ffmpeg、ffprobe 和 Python 3.10+,核心工具只用 Python 标准库。原文声称 CI 测试了 FFmpeg 6.1、7.1、8 和 9;3.0.0 已移除 Python 3.9 与 FFmpeg 5.x 支持。
安装入口是 npx ffmpeg-skill,默认面向 Claude Code,也支持 --cursor、--codex 和 --all。安装副本不会自动更新,需要重新运行安装命令。
下面这组命令分别用于探测素材、预览处理计划和获取结构化导出结果:
S=~/.claude/skills/ffmpeg-skill/scripts
python3 $S/probe.py input.mp4 --compact
python3 $S/fit.py input.mp4 --duration 60 --aspect 9:16 --dry-run # print the plan, run nothing
python3 $S/export.py input.mp4 --preset reels --json # structured result with a probe of the output
第三行的 --dry-run 用来查看计划;第四行的 --json 会返回包含输出探测信息的结构化结果。--plan FILE 还能保存带输入指纹的计划,交给 render.py FILE 执行,输入改变时拒绝继续。工具不覆盖输入文件,替换已有输出需要 --overwrite。
环境检查同样有层次。doctor 会检查编码器、解码器、滤镜和位流过滤器,但整体 ok: false 不代表全部工具不可用。比如缺少 libass 或 libvidstab,可能只影响部分功能,应查看 doctor --json 的 tools 字段。检测失败则标为 unknown,不会伪装成已安装或缺失。
画面检查的边界尤其需要理解。look.py 只生成联系表,也就是把多帧排在一张 PNG 上;识别人脸、确认裁剪是否保住主体,需要调用它的多模态 Agent 或人来判断。默认裁剪仍是居中裁剪。scenes.py --highlights 也只是按 --rank-by audio 或 --rank-by duration 排候选片段,不理解内容是否精彩。
「本地」也有范围。FFmpeg 处理在本机完成,不要求云端 API;可选转写需要另装 Parakeet 或 whisper 系列引擎,部分引擎首次运行会下载模型。至于调用方 Agent 如何处理提示词或检查图片,原文没有说明,不能据此断言整条链路完全离线。
我的判断
我认同它把测量、执行和验收分开的思路。相较于让 Agent 临时拼命令,结构化参数、能力检测和稳定错误码更适合自动化;相较于传统固定脚本,它又保留了自然语言组织任务的灵活性。
但它更适合规格明确的剪辑任务:截取区间、改比例、处理音量、添加字幕、按平台导出。判断哪里值得剪、字幕该写什么,仍由上游决定。它在作者的生态里定位为执行引擎,也不反向调用分析、转写或质检等其他仓库。
效果证据需要分开看。原文描述了契约一致性、原文件哈希、dry-run 行为等测试,这些能支持工程约束;演示素材多数来自 FFmpeg 测试源,只有 reframe_talk、filler_en 和 pauses_en 使用两段 AI 生成人物素材,演示可通过 python3 demos/build.py 重建。
作者没有给出与直接生成 FFmpeg 命令相比的成功率、耗时或画质对照。因此,「减少猜测」有设计依据,能提高多少交付成功率仍缺数据。作者引用的立场论文甚至把项目自身评为仅部分符合其验证纪律,这个保留应当一起读进去。
能拿来做什么
- 为产品演示、录屏或课程片段生成多个平台版本时,可以先用
render.py --list-templates检查模板,再通过--dry-run审阅计划;批量导出后仍要检查字幕位置和主体裁剪。 - 在 Node 自动化任务里,可以消费
--json的状态、输出路径和探测结果,并明确时长、尺寸、音量等验收条件。失败处理应读取error.kind和稳定的error.reason,避免只匹配终端文字。 - 给现有 AI 编程工具补上验证步骤时,可以借鉴它的契约设计:参数定义统一维护,每项操作写清后置检查,把执行结果和验收证据一起返回。
- 处理采访或播客时,可以先从区间裁剪、响度检查这类确定任务入手;需要自动转写再安装本地引擎,并提前验证模型下载和识别效果。