用 ffmpeg-skill 的 42 个 agent 工具在本地剪视频

一个"懂 FFmpeg"的 agent 仍然在猜——它假定一个帧率，挑一个容器装不下的编解码器，把只需要流拷贝的文件重新编码一遍，然后不打开结果就报告"完成"。ffmpeg-skill 是 kajisho5 的一个 2k 星、MIT 许可的项目，它用 42 个带类型参数的工具和一套先测量、最后验证的工作流取代了这种猜测。

为什么这个 Skill 重要

skill 文件给 agent 一套固定的工作流——探测、尽可能无损地编辑、检查、验证——而工具用本地的 ffmpeg 与 ffprobe 干活。每个任务都从 probe.py 开始，所以决策依据是量出来的时长、帧率、分辨率、色彩与音频布局，而不是文件名。没有任何东西经由 shell 运行，也不接受调用方给的 filter graph；每个操作都是一个带类型参数的脚本。contract --json 为每个工具说明它接收什么、写出什么、需要哪些 FFmpeg 组件、结果如何验证，MCP 接口就是从这份契约派生的。执行之后，输出会被探测、对照目标平台的规格检查，而且只要画面变了，就用 look.py 渲染一张联系表给 agent 看。

42 个工具分为分析类（probe、scenes、look），从 cut、join 到 silence、fit、stabilize、broll、grid 的 24 个编辑类工具，音频类（audio、sync、loudness），画面类（caption、overlay、graphics、color），交付类（export、proxy、check、report）与编排类（render、batch、multicam、verify）。全部只用 Python 3.9 标准库，全部支持 --help、--dry-run、--json 与 --plan FILE。

安装

npx ffmpeg-skill
npx ffmpeg-skill doctor
npx ffmpeg-skill contract --json | head -40

第一行会为 Claude Code 安装到 ~/.claude/skills/ffmpeg-skill；--cursor、--codex 与 --all 面向其他 agent，--project 装进 ./.claude/skills/。作为 Claude Code 插件，claude plugin install kajisho5/ffmpeg-skill 不需要 Node，并通过 claude plugin update 更新。没有 Node 的话，克隆仓库，把 SKILL.md、scripts/、references/ 与 mcp/ 复制进你 agent 的 skills 目录。重新运行 npx ffmpeg-skill 即可刷新——副本不会自动更新。

doctor 检查 ffmpeg、ffprobe 以及工具需要的每一个 FFmpeg 组件是否就位。要仔细读它的输出：整体 ok 只表示"每个工具都需要的东西"没有缺失，但 macOS 上 Homebrew 的普通 ffmpeg 可以是 ok，而 caption.py 偏偏跑不了，因为那个 formula 缺少 subtitles 滤镜——doctor --json 的 tools 字段给出每个工具各自的答案。README 的安装表是：macOS 用 brew install ffmpeg-full（它是 keg-only 的，所以要把 $(brew --prefix ffmpeg-full)/bin 放到 PATH 最前面），Ubuntu 与 Debian 用 sudo apt install ffmpeg，Windows 用 winget install Gyan.FFmpeg。要求 FFmpeg 5.0+。

实战：把一段访谈剪成 60 秒的 Reel

1. 安装、运行 doctor，然后用平实的语言和 agent 说话——这是 README 自己的例子：

Take interview.mp4, keep 0:45–3:10 and 5:00–6:30, and make it exactly 60 seconds for Reels.

2. 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。
3. 它报告 "final.mp4: 59.98 s, 1080×1920, 30 fps, AAC stereo"，并附上它检视过的联系表。报告只带一个标签——Done: 或 Failed:——部分完成的结果是 Done: 加上在 Notes: 下点名的缺口。
4. 这些工具也可以在任何 shell 里单独运行：

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

5. 面向有自家 UI 的平台，一条命令就能填好一份自带的模板：

python3 $S/render.py talk.mp4 --template tiktok --cues cues.txt

这意味着：9:16 裁切、字幕逐词弹出，位于 TikTok 描述栏之上并避开点赞栏，−14 LUFS，tiktok 导出预设，再对写出的文件跑一次 check.py --platform tiktok。模板覆盖 tiktok、reels、shorts、youtube-shorts、youtube、x、linkedin、facebook 与 podcast；--template all 用同一份剪辑渲染所有平台，并写出一张 <name>_pack.md 表格记录每个平台产出了什么。

技巧

• 无损剪切会吸附到关键帧：流拷贝的剪切点可能比你要求的早最多一个 GOP，所以当偏移超过 0.5 秒时 cut.py 会改为重新编码（--tolerance 调整上限；--tolerance -1——在可变帧率的源上再加 --vfr-guard off——保持文件严格无损，并把剪切点落在最近的前一个关键帧上）。
• 可变帧率——手机录像和屏幕录制——会被 probe.py 标出，cut.py 遇到它会切换到帧精确模式，因为在 VFR 上做拷贝剪切会落到错误的帧。
• 先重新取景，再加字幕：在裁切或缩放之前烧进去的文字会跑出画面。把 16:9 裁成 9:16 会丢掉 70% 的宽度；fit.py --fit crop 默认居中，所以要用 --crop-x/--crop-y 朝主体偏移，或者用 --fit pad --pad-fill blur 填充，决定之前先看联系表。
• HDR 保持 HDR。在输出 H.264 成品或做 LUT 之前，用 color.py --to-sdr 有意识地转换；平台导出预设都是 SDR，遇到 HDR 输入会给出警告。
• 响度目标：YouTube 与社交平台 −14 LUFS / −1 dBTP（loudness.py 的默认值），播客 -I -16 --tp -1.5，广播 -I -23。check.py file --platform podcast 同时测量 LUFS 和真峰值。
• 没有任何工具会覆盖输入，也不会悄悄替换已有的输出。除非另有指定，输出是名为 <input>_<operation>.<ext> 的新文件，已存在的路径会被拒绝，直到你传入 --overwrite。
• 音频是一等输入：WAV、FLAC、MP3、M4A/AAC、OGG 与 Opus 用和视频相同的命令走 probe、cut、join、silence、loudness、audio、sync 与 check --platform podcast。
• 可选的本地转写——装了 Parakeet 或某个 whisper 时——为 caption.py --transcribe 与 silence.py --filler --transcribe 提供支持；两者也都能接收你已有的文字稿，而且在缺失时都会带着安装命令拒绝执行，而不是猜。

何时不用这个 Skill

按 README 的说法，ffmpeg-skill 是手，不是脑。它不决定剪哪里、成品是否可以通过、什么才算精彩片段，以及字幕该写什么——cue 文本会原样烧录。仓库里没有任何东西能检测人脸、商品或主体：redact.py 模糊或插值的是你给出的矩形，cropdetect.py --motion-centre 报告运动集中在哪里但不选裁切，决定画面里保留什么是调用方的事。调用方提供的 filter graph、-vf 字符串或其他 ffmpeg 选项，没有任何脚本会接受。工具唯一会走的 GPU 编码路径是 Apple Silicon 上的 Apple VideoToolbox，通常通过 --hw 选择启用；nvenc、QSV、VAAPI 与 AMF 会出现在 doctor --json 的报告里，但没有工具用它们编码。至于从 React 组件渲染视频，README 指向 Remotion 作为互补——Remotion 写出的文件在这里只是一个普通输入。

查看 排行榜 了解更多 skill。