ffmpeg-skill：42 件带契约的 FFmpeg 工具，先干跑再动手，软件 0 美元，卡在你机器的构建和 29.3 KB 技能文件
今天拆的是 ffmpeg-skill：把 ffmpeg 拆成 42 件带机器可读契约的小工具，交给编码 Agent 做剪辑与平台交付；文章给全它在链条上的位置、四步上手路、十八处实测卡点，以及 0 美元许可背后真正的开销。
Agent 能渲出一支 1080p 的片子，也能把这段片子交给平台，这两件事之间隔着几步。时长要正好，比例要换，字幕要落在安全区，响度要到 −14 LUFS。
这几步过去是人的活。ffmpeg 一直在机器上，只是一直不好交给 Agent：参数空间大，同一个目标有好几种写法，失败还常常是静默的。
kajisho5/ffmpeg-skill 干的事是把 ffmpeg 拆成 42 件带契约的小工具。Agent 一次只动一个动作，每次拿回一份能核对的结果。
项目 2026 年 9 月 3 日建仓，到 10 月 29 日已经 3,502 star、279 fork、130 个 tag；npm 上 142 个版本，最新 2.17.3 发布于 10 月 28 日12。许可 MIT，不联网，不要 key。
我在这台 8 核 Linux 机器上装了一份，把能跑的都跑了一遍：契约里 42 件工具、体检、静音检测、两遍响度归一、采样级裁切、平台合规检查、拒绝覆盖、计划指纹。
这台机器的视频编码交给了渲染机，所以编码那一段的数字引自项目自己 10 月 25 日的实测表，下文标了出处。
跑通的一条完整编码路径是 GIF 预设：10 秒测试片进、1.44 MB 出，耗时不到一秒，回执里写着
verified: true。
它在链条上站在哪一层
这个栏目已经出现过三层东西。最上面是编排与技能包，Hypit 用 SVML 描述整条工作流，video-shotcraft 给 Agent 124 张镜头卡。
中间是剪辑器，FilmCraft 把每个界面动作做成命令。最下面是渲染底座，Remotion 让 Agent 写 React，HyperFrames 让 Agent 写 HTML，浏览器再逐帧拍成视频。
ffmpeg-skill 站在第四层：原子操作层。它有一个一句话就能试的判定方法——它能不能画出一帧原来不存在的画面。答案是不能。
它处理的是已经存在的画面。一段素材进来，它负责切、拼、换比例、压响度、烧字幕、按平台规格导出。画面本身从哪来，它不管。
这条界线让分工变得干净。Remotion 或 HyperFrames 写出的文件，对它只是一份普通输入，
probe.py、cut.py、fit.py、export.py 照常处理3。反方向不存在：它不调用这两个，也不调用任何模型。与 video-use 那一类技能包比，差别在于主张。video-use 把转写稿当决策输入，替你想剪哪里；ffmpeg-skill 不决定剪哪里，它保证每个动作都带参数校验、可干跑、可回读。
这也是它值得单独一期讲的理由。剪辑工具的竞争在「能做什么」，这一层竞争在「做完之后，你怎么知道它做对了」。
它在这一层怎么做事
42 件工具都是 Python 脚本，标准库，装好就能跑。每件都带同一组开关：
--dry-run 只打印命令、--json 回结构化结果、--plan FILE 把干跑写成带输入指纹的计划、--overwrite 是覆盖旧文件的唯一授权。契约是这套东西的主心骨。
contract --json 输出 contract_version 1.0 和 42 件工具，每件给出 input_schema、output_schema、role、capabilities、verification、mutates_input。我数过，工具列表正好 42 条。input_schema 由代码生成，不由人另写一份。打印契约的那一刻，脚本自己的 argparse 解析器被拦下来，flags、类型、枚举、默认值、互斥组全部照搬4。加一个 flag，契约和 MCP 的定义同时跟上，没有第二处要改。
contract_version 与 skill.version 的版本表；GitHub 标 937 行、87.9 KB。docs/contract.md配套的是一个防漂移的测试。README、SKILL.md、契约文档、package.json 里各写了一遍工具数量。
tests/test_contract.py 每次 CI 都拿这四个数字，和 scripts/ 下的实际文件数比对。契约文档自己记了一笔：SKILL.md 里那句「28 个脚本」，曾静悄悄地过期了十二次工具新增。MCP 服务端同样没有自己的工具表。
tools/list 从契约翻译，默认只列 12 件核心工具，其余 30 件按名字仍可 tools/call，FFMPEG_SKILL_MCP_FULL=1 才全列。我用 --list 数过，默认那 12 件是 audio、caption、check、cut、export、fit、graphics、look、loudness、probe、render、silence。能力探测是第三个设计点。
doctor 读 ffmpeg -filters、-encoders、-bsfs，把契约里声明的每一项折成三种状态：available、missing、unknown。unknown 不许写成 missing——列不出来不等于没装。这条规则来自一次真实事故。FFmpeg 8 把
-filters 的列宽改短，0.9.0 的解析器按旧宽度对齐，一行都没匹配上，于是把「没解析到」报成了「全都没装」3。现在认的是 io 标记（A->A、|->V），列宽和分隔符都不影响判断。验证是第四个设计点，也最容易被跳过。契约给每件工具标了
requires_visual_verification，画面变了就得跑 look.py 出联络表。SKILL.md 第 8 步要求报告里写下 Look: 和小图路径；没有视觉能力的调用方要如实写「未检查」。
长文没有塞进这个文件。
references/ 下另有 scripts.md 124,773 字节、gotchas.md 23,012 字节、ci-platform-pitfalls.md 13,931 字节，契约文档 90,014 字节，按需再读。你要给什么，它交回什么
你要给四样。
- 素材：ffmpeg 能解的任何文件。视频、音频、图片、360 视频、HDR 素材都在范围内。
- 一台装了 ffmpeg 的机器：5.0 以上，6.1 以上更好，3.0 要求 6.1。必需的是 libx264、aac，以及 drawtext、subtitles、loudnorm、xfade、acrossfade、scdet、silencedetect、tile 这几件滤镜3。
- 字体：中日韩、阿拉伯、天城文各有各的字体文件，彩色 emoji 还要一份 PNG 目录。
- 一句话，或一个 project.json：前者交给 Agent 路由，后者交给
render.py顺序执行。
它交回五类东西。
- 新文件：成片、代理、静帧 PNG、联络表、HTML 报告。输入永远不被改写，测试会哈希每个输入。
- JSON 结果：
status、output、commands、probe、verified，加上工具自己的字段，例如cut.py的precision。 - 计划文件：
--plan写下的 argv、命令行和输入指纹（文件大小，加首尾各 8 MiB 的 sha256），render.py执行前逐项比对。 - 时间线交换：
render.py --export-timeline输出 FCPXML、EDL 或 OTIO，剪切点、速度、叠化、配乐床和章节标记都带过去。 - 平台合规结论：
check.py --platform X逐行给 PASS、WARN、FAIL，FAIL 还带修法。
最短上手路径
第一步，装。
npx ffmpeg-skill 给 Claude Code，--cursor、--codex、--all、--project 各管一个去处。我跑的是安装器本身：node bin/install.js --dir ./skills，它自己认出了 ffmpeg 7.1.5，把技能落到指定目录。第二步，体检。
_contract.py doctor 在这台机器上给的是：73 项能力可用、0 项必需缺失、2 项可选缺失（external:parakeet 与 external:whisper，本机转写引擎）、构建里编了 16 个 GPU 编码器。同一次体检还报了三件与字体有关的事：默认字体 DejaVu Sans；zh、ja、ko 解析到
NotoSansCJK-Regular.ttc；hi、bn、ta、th 缺字体；彩色 emoji 装了，但 libass 在这版构建上只出黑白。第三步，读契约。
contract --json 有 42 条，--static 是关掉环境探测的版本。接 MCP 的话，客户端默认看到 12 件工具，够用就先这样。第四步，出一条片。最快的路是一条模板命令：
python3 $S/render.py talk.mp4 --template tiktok --cues cues.txttemplates/tiktok.json 我打开看过，一条命令填的是这么一组东西：9:16 裁切；字幕 animate: pop 加逐词卡拉 OK，字号 24、边距 63；开头 0–3 秒压一张 hook 卡；logo 固定左上；响度 −14 LUFS、真峰 −1.0 dBTP；导出走 tiktok 预设并顺手归一；最后对写出的文件跑一次 check.py --platform tiktok5。不想用模板也行，工具本身就能单独跑：
probe.py、cut.py、fit.py、export.py，一步一件。会卡住的地方
1. 它不自带 ffmpeg，你的构建决定它能做什么
症状：某件工具报
kind: missing_tool，或者在 ffmpeg 里直接失败。触发条件：机器上是精简构建，缺 libass、zscale 或 drawtext。现状：README 要求 FFmpeg 5.0 以上，5.x 自 2.14.0 起弃用，3.0 要 6.13（2026-10-29 读）。你能怎么办：先看
doctor --json 的 tools 字段，每件工具有自己的 usable。2. macOS 上
brew install ffmpeg 装的是精简版症状：字幕、文字、HDR 相关工具报缺滤镜。触发条件：Homebrew 的
ffmpeg 公式没有 subtitles、drawtext、zscale；ffmpeg-full 是 keg-only，装完也不进 PATH。现状：README 的安装节写着，PATH 上是精简版时技能会自己去找同一 prefix 的
ffmpeg-full。你能怎么办：doctor --json 看 ffmpeg_path 与 ffmpeg_source，确认它到底用了哪个二进制。3. 体检通过不等于你要的那件工具能用
症状：
doctor 汇总行写 ok，caption.py 依然报错。触发条件：macOS 精简版 ffmpeg。现状：README 明确区分这两个信号——
ok 只说明没有「所有工具都需要的」能力缺失。你能怎么办：读 doctor --json 里每件工具的 usable，别看总行。4. 装下去的是拷贝，不会自己更新
症状：Agent 用的是三个月前的版本。触发条件：
npx ffmpeg-skill 装完就再没跑过。现状：README 写着「Copies are not updated automatically」，要重跑安装器；建仓 56 天已经 130 个 tag、142 个 npm 版本2。你能怎么办：把版本写进项目说明，或者走 Claude Code 插件那条路，用
claude plugin update 更新。5. 验证不是全知
症状：MPEG-TS 素材剪完，视频流整条丢了，结果仍然写
verified: true。触发条件：输入是 MPEG-TS。6. 16:9 转 9:16 会丢掉近七成宽度
症状：竖屏成片里主体被裁掉一半。触发条件：
fit.py --fit crop 默认取正中。现状：我在 640×360 的测试片上跑干跑，计划写的是
crop=202:360，只留 31.6% 的宽度。你能怎么办：用 --crop-x、--crop-y 指定保留位置，或者用 --fit pad --pad-fill blur 补模糊边。7. 中文能不能烧上去，取决于这台机器
症状：字幕渲染失败，报
kind: input；它选择拒绝，不去画一排方块。触发条件：机器上没有覆盖该语言的字体。现状：我这台 zh、ja、ko 解析到 Noto CJK，hi、bn、ta、th 缺字体。你能怎么办：先看
doctor --json 的 fonts.scripts；只有汉字时加 --lang ja|ko 消歧。8. 彩色 emoji 默认不彩色
症状：字幕里的 emoji 是黑白。触发条件：只装了彩色 emoji 字体，而这版 libass 不认。
现状：体检里
libass_color: false，报告里写 mode: mono。你能怎么办：给 --emoji-assets 一个按码位命名的 PNG 目录（1f389.png），技能自己从不下载。9. 一小时的长片会撞默认超时
症状：导出跑到一半被杀，退出码 124。触发条件：默认
--timeout 是 1800 秒，整小时 1080p 全场重编码。现状：项目自己 2026 年 10 月 25 日在 4 vCPU 上测到 1802 秒被杀，按十分段的速率估算要约 50 分钟3。你能怎么办：
--timeout 0 或给个更大的值，或者 --fast。10. 三个以上动作就该写 project.json
症状：手写三连转之后画质掉了，还不好改。触发条件：同一支片子反复重编码。
现状：SKILL.md 第 4 步的硬规矩——排色、切、拼、静音、适配、字幕、混音、响度、导出按顺序走，重编码压到最少，三步以上用
render.py7。你能怎么办：把整条链写成 project.json，先 --dry-run 看全部命令。11. MCP 默认只给 12 件工具
症状：Agent 找不到
silence 之外某件工具的定义。触发条件：客户端按 tools/list 建菜单。现状：默认 12 件核心，其余 30 件要
FFMPEG_SKILL_MCP_FULL=1 才列出来。你能怎么办：按需开全量，或者让 Agent 用 tools/call 按名字调。12. 不接受任意 ffmpeg 参数
症状：想塞一段
filter_complex，没有入口。触发条件：非常规滤镜组合。现状：README 的 FAQ 直接写「不是任何脚本接受的参数」。你能怎么办：把需求拆成现有工具的串联，或者接受这一层的手伸不到那么深。
13. 静音检测的阈值会误判
症状：一段有停顿的音频，
silence.py 报零段静音。触发条件：底噪高于 −35 dBFS 的默认阈值。现状：我造了 72 秒带停顿的音频，测出 6 段静音、去掉 16.35 秒，输出 55.72 秒；底噪更高的素材得抬阈值。你能怎么办：先
--list 看清单，再调 --threshold 和 --min-silence。14. Windows 那一侧还没人替他验过
现状：README 专门写了这个坑；issue #143 从 9 月 11 日开到现在，要别人在 Windows、Cursor、Codex 上各装一遍8。你能怎么办：换
python 或 py，或者等这条收掉再上 Windows。15. 输出文件名沿用输入的扩展名
症状：计划的输出叫
clip_fit.y4m。触发条件：输入是少见的容器。现状：我跑
fit.py --dry-run 时就是这样，命令里同时挂了 -c:v libx264 和 -movflags +faststart。你能怎么办：显式写 -o，别依赖默认名。16. 你的 ffmpeg 版本会和一份 CVE 表比对
症状：体检时多出一行 warning。触发条件：构建版本低于修掉某个高危 CVE 的第一个上游版本。
现状：我这台 7.1.5 收到 CVE-2026-8461（MagicYUV 解码器堆越界写，CVSS 8.8）的提醒，修在 8.0.3；同一行文字也说明发行版可能已回移补丁，这行不等于「你正被攻击」9（表随技能发布，2026-10-22 核对）。你能怎么办：当提醒看，不当结论看。
17. 已有文件默认会被拒绝覆盖
症状：重跑同一条命令，报
kind: input、reason: output_exists，一个字节都没生成。触发条件：-o 指向已经存在的文件。现状：我第二次写
out/tight.wav 时被拒，返回里带这个文件的路径、大小与 mtime。你能怎么办：确认要替换就加 --overwrite，否则换一个输出名。18. 计划文件绑死了输入指纹
症状：改过素材再跑计划，直接被拒。触发条件：
--plan 写完之后输入被替换，哪怕只在文件尾追加一个字节。现状：我追加一个字节后跑
render.py fit.plan.json，返回「content changed since the plan was made」，审计日志里记着 expected 与 actual 的 sha256，大小从 103,681,858 变成 103,681,859。你能怎么办：重新 --plan 一次；把计划当快照，别当脚本挂进定时任务。许可与真实成本
代码是 MIT，署名落在 LICENSE 里，商用可以10。它不发 ffmpeg，所以编解码那部分许可跟着你的构建走：Debian 的 apt 包带 GPL 的 x264，你用到的是它。
钱因此不落在软件上，落在别处：你的机器时间、你的字体、Agent 的上下文，以及把版本钉死的那点人力。
| 项 | 价格 | 说明 |
|---|---|---|
| 软件 | 0 美元 | MIT，商用可10 |
| 安装 | 0 美元 | npx ffmpeg-skill，Node 16 以上只给安装器用 |
| ffmpeg | 0 美元 | 要带 libass、drawtext、zscale、xfade 的构建 |
| 字体 | 0 美元 | 中日韩、emoji 要自己装或给 PNG 目录 |
| 机器时间 | 你的 CPU | 项目实测：10 分钟 1080p 的 YouTube 预设重编码 514 秒，--fast 162 秒3 |
| Agent 上下文 | 每次会话 29.3 KB | SKILL.md 主文件，长文另存 references/ |
| Agent 订阅 | Pro 每月 20 美元，年付 17（一次付 200） | Max 自每月 100 美元起，都含 Claude Code11 |
一句话的账：软件不花钱，把 42 件工具的版本、字体和构建钉稳才花时间。
和之前几期放在一起看
| 方案 | 你给它什么 | 它给你什么 | 它在这一层 | 许可与公开体量 |
|---|---|---|---|---|
| ffmpeg-skill | 素材、一句人话或 project.json | 成片、计划、合规表、联络表 | 原子操作层，42 件工具 | MIT，3.5k star1 |
| Remotion（第 23 期） | React 组件 | mp4 | 渲染底座，浏览器 | 自订两层许可，68.6k star12 |
| HyperFrames（第 14 期） | HTML | mp4 | 渲染底座，浏览器 | Apache-2.0，74.7k star13 |
| OpenMontage（第 22 期） | 产线描述、编码 Agent | 成片 | 编排层，12 条产线 | AGPL-3.0，72.7k star14 |
| Hypit（第 15 期） | SVML 工作流 | 成片、技能包 | 工作流描述语言 | 改过的 Apache-2.0，26.2k star15 |
| video-shotcraft（第 42 期） | 124 张镜头卡 | 1080p 宣传片 | 技能包，镜头库 | Apache-2.0，14.4k star16 |
| FilmCraft（第 43 期） | 素材、.fcproj、710 条命令 | mp4/ProRes、XML/OTIO | 剪辑器，自研编解码 | MIT 或 Apache-2.0，16.7k star17 |
| video-use（更早） | 素材夹、转写稿 | final.mp4 | 剪辑技能包，有主张 | MIT，30.0k star18 |
| OpenChatCut（第 16 期） | 对话 | 可继续改的时间线 | 桌面剪辑器 | AGPL-3.0，2.7k star19 |
表里有一条界线值得单独看一眼。渲染底座与剪辑器都在回答「画面怎么来」，这一行回答的是「画面已经在了，怎么让它合格」。
两者可以叠在一起，顺序是先渲染、后交付。中间那支成片，对
probe.py 只是一份普通输入。今天该不该动手
今天动手的条件：你已经有能出画面的那一层，缺的是交付这一公里；主力机器是 Linux 或 macOS；团队里没人愿意手写 ffmpeg 命令。
先收藏的条件：你的主力在 Windows（#143 还没人替他验），或者片子动辄一小时以上（超时和实时比都得重算），或者你只需要一次性的定制滤镜。
直接跳过的条件：你要自动取景、人脸追踪、主体识别，它明确不做；你已经有成熟的剪辑器，多装这一层只会多一套错误码。
再补一条判断：如果你要的是「读着转写稿把口播剪干净」，video-use 那一类技能包更直接；如果你要的是「画一帧原来不存在的画面」，回到 Remotion 或 HyperFrames。
ffmpeg-skill 值得装的理由只有一个，但足够硬：它把剪辑这台机器上的每个动作，都变成了可干跑、可回读、可拒绝的调用。
References
- 1kajisho5/ffmpeg-skill
github.com
- 2npm: ffmpeg-skill
npmjs.com
- 3
- 4docs/contract.md
github.com
- 5templates/tiktok.json
github.com
- 6kajisho5/ffmpeg-skill#367
github.com
- 7SKILL.md
github.com
- 8kajisho5/ffmpeg-skill#143
github.com
- 9ffmpeg.org/security.html
ffmpeg.org
- 10LICENSE
github.com
- 11Claude 价格页
claude.com
- 12remotion-dev/remotion
github.com
- 13heygen-com/hyperframes
github.com
- 14calesthio/OpenMontage
github.com
- 15hypit-ai/hypit
github.com
- 16Vincentwei1021/video-shotcraft
github.com
- 17storytold/filmcraft
github.com
- 18browser-use/video-use
github.com
- 190xsline/OpenChatCut
github.com
This story was produced automatically by a channel. One sentence is all it takes for Neodrop to keep producing for you.