ffmpeg-skill 实测：42 个脚本让 Agent 剪完先自检

让编程 Agent 直接拼 ffmpeg 命令剪视频，常见的问题是帧率靠猜、编码乱选，最后不打开成品就说做完了。ffmpeg-skill 把剪辑拆成 42 个带固定参数的 Python 脚本，配一份 SKILL.md 规定「先探测、再剪、最后自检」，同一套工具还能当 MCP 服务器用。我们 10 月 23 日在服务器上装了 2.10.11，用一段 20 秒的合成素材走完了去静音、转竖屏、烧字幕、响度标准化、平台自检。

它是什么

一个给 Claude Code、Cursor、Codex 等读 SKILL.md 的 Agent 用的本地视频剪辑工具包，附带一个 stdio MCP 服务器。

解决什么问题

Agent 记得 ffmpeg 的参数，交出来的视频照样可能不合格：没看源文件就假设 30 帧，往容器里塞不支持的编码，本来流拷贝就行的却全片重编码，渲染完也不看结果。ffmpeg-skill 把能做的事收窄了：每个操作是一个脚本，参数由 argparse 定死，不接受调用方传进来的滤镜串，也不走 shell；每个脚本都有 --dry-run 打印将要执行的 ffmpeg 命令，--json 返回结构化结果。

仓库里还有一份 contract --json，描述每个工具的输入、输出、依赖哪些 ffmpeg 组件、做完该用什么方式校验。MCP 的工具列表就从这份契约实时生成，所以命令行和 MCP 两边的参数不会对不上。

怎么用

# 装进 Claude Code（Cursor 用 --cursor，Codex 用 --codex，三个都装用 --all）
npx ffmpeg-skill
npx ffmpeg-skill doctor          # 检查 ffmpeg 版本和各工具需要的组件

# 不经过 Agent，直接在终端用
S=~/.claude/skills/ffmpeg-skill/scripts
python3 $S/probe.py talk.mp4 --compact
python3 $S/silence.py talk.mp4 --threshold -35
python3 $S/fit.py talk_tight.mp4 --aspect 9:16 --fit blur --width 720 -o v916.mp4
python3 $S/caption.py v916.mp4 --text cues.txt --animate pop --karaoke --platform reels -o cap.mp4
python3 $S/loudness.py cap.mp4 -I -14 --tp -1 -o final.mp4
python3 $S/check.py final.mp4 --platform reels
python3 $S/look.py final.mp4 -o look.png

# 接 MCP 客户端
{"mcpServers": {"ffmpeg-skill": {"command": "python3", "args": ["/home/you/.claude/skills/ffmpeg-skill/mcp/server.py"]}}}

实测

环境：2026-10-23，Debian 13，Python 3.13.5，ffmpeg 7.1.5-0+deb13u1，Node.js 20.19.2，npm 包 2.10.11（仓库提交 7646489）。素材是用 ffmpeg 生成的 20 秒 1280×720 测试画面加 440 Hz 正弦音，4–8 秒和 12–15 秒静音。

• 去静音：silence.py 用时约 2 秒，输出 13.581 秒（原片 20 秒），切点在静音两端各留了约 0.15 秒。
• 帧率：剪完的文件被 probe 标成「VFR?」，帧率 30.074；fit.py 自动提示「conforming to constant fps」并转成恒定帧率，但成品仍是 30.074 帧，不是 30。fit.py 有 --fps 参数可以指定，我们没再跑一遍。
• 字幕：4 条中文字幕全部烧进画面，cues_outside: 0，逐字高亮正常。
• 自检：check.py 的两条提醒都合理：720×1280 低于 Reels 建议的短边 1080；没有可开关的字幕轨（我们是烧录字幕）。
• 不覆盖原文件：2.0 起输出文件已存在时直接拒绝，要加 --overwrite，第二次跑 loudness.py 时我们碰到了。
• MCP：initialize 返回 ffmpeg-skill 2.10.11，tools/list 默认 12 个；server.py --call probe 0.18 秒返回。
• 安全提示：安装时 doctor 提醒本机 ffmpeg 7.1.5 低于上游修复 CVE-2026-8461 的版本，同时说明发行版可能已回补补丁。我们在脚本里没找到联网和遥测代码，只有提示文字里的网址。
• 坑：在克隆下来的仓库目录里跑 npx ffmpeg-skill 会报 ffmpeg-skill: not found，换到别的目录就好。仓库自带的完整测试我们跑了 11 分钟没跑完，结果未记录。
• 未实测：真实 Agent 按 SKILL.md 自己挑工具、看缩略图（要接付费模型）；--transcribe 自动听写（本机没装 Parakeet 或 whisper）；HDR 转 SDR、硬件编码。

它把 Agent 能做的事限制在 42 个有固定参数的脚本里，每一步都留下能检查的结果。批量剪辑没人盯着的时候，靠的就是这些结果。

适合谁，不适合谁

适合：经常剪访谈、口播、短视频，想让 Agent 去静音、转竖屏、加字幕、按平台规格导出的人；素材不方便上传云端的团队；想给自家 Agent 框架接一个本地视频 MCP 的开发者。不适合：要精细调色、多轨时间线的正片剪辑；本机 ffmpeg 版本很老或缺 libass 的环境（先看 doctor --json 里每个工具的 usable）。

替代方案：直接让 Agent 写 ffmpeg 命令（灵活，但没有校验）；要用 HTML 做动态图形再渲染成视频，可以看本栏的 lemo-opuscar 实测。

最后

先跑一次 npx ffmpeg-skill doctor，再拿一条自己的口播素材试 silence.py --dry-run，看它打算怎么切。