📌 项目地址:kajisho5/ffmpeg-skill | ⭐ 6,439 颗星 | 🔧 Python

剪视频这件事,人和 AI 的痛点一样:知道要什么效果,但记不住 FFmpeg 那几十个参数。ffmpeg-skill 干的事,就是把这层摩擦去掉。它是一个 Agent Skill(仓库里带 SKILL.md),Claude Code、Cursor、Codex 或者任何能读 SKILL.md 的代理拿到它之后,就学会了一套固定流程:先探测素材(probe),再尽量无损地剪辑,然后自己检查输出(check → verify)。
本地运行,不上云,不用 API key,只用 Python 标准库。只要 ffmpeg 和 python3 在 PATH 上就能跑。想剪又不想上传到在线服务的素材,正好用它。
一条命令装好
npx ffmpeg-skill
这是 README 给出的完整安装步骤,没有第二步。装完之后,代理可以调用的工具有 42 个,都靠 ffmpeg / ffprobe 干活,覆盖这些事:剪切拼接、去静音、适配时长和画幅、字幕和卡拉OK、叠加与动效、HDR 转 SDR、LUT、音频清理、带漂移校正的同步、多机位、响度处理、交付检查、整个剪辑项目的渲染、批量处理文件夹。
几个 README 里的实际命令,感受一下粒度:
caption.py --animate pop --karaoke
fit.py --aspect 9:16 --fit crop
silence.py --threshold -35
loudness.py -I -14 --tp -1
caption.py 加字幕,带弹出动画和逐字高亮;fit.py 把画面裁成 9:16 竖屏;silence.py 按阈值(比如 -35dB)剪掉静音段;loudness.py 归一响度,-14 LUFS 整合响度、-1 dBTP 真峰值,这是平台交付的标准参数。
仓库的 docs/demos.md 里每个效果都有左右对比图(左边输入,右边输出),每张图下面标着对应命令。所有演示由 python3 demos/build.py 生成,你可以自己重建每一帧。素材基本是 FFmpeg 自带的测试源,只有三个 demo 用了 AI 生成的、真人不存在的两段视频。
schema 不是手写的,这点最值得学
工具开发里有个老毛病:代码改了参数,文档和工具定义忘了改,用户照着文档调用就报错。ffmpeg-skill 的解法叫 SPEC(Self-Producing Execution Contract):每个工具的 input_schema 从来不在代码旁边手写,而是在运行时从定义 CLI 的那个 argparse parser 派生出来。CLI 和 schema 永远来自同一份定义,如果出现漂移,CI 直接挂掉。
这个思路不限于视频工具,任何”CLI 和 MCP 工具定义要逐 flag 对应”的项目都能抄。
MCP 上下文的省法
42 个工具全部能通过 MCP 调用,但默认 tools/list 只列出核心的 12 个,避免把客户端上下文撑爆。设 FFMPEG_SKILL_MCP_FULL=1 就能列出全部 42 个。不管哪种模式,任何工具都可以通过 tools/call 按名字直接调用,功能没有损失。
定位:它是手,不是脑
仓库可以完全独立用,就是一个本地 FFmpeg 引擎,不依赖作者的其他仓库。但在 kajisho5 的整个视频生产生态里,它扮演执行者的角色:负责剪、测、导出文件,用结构化 JSON 汇报结果。它不决定该剪哪一段、成片算不算合格、哪里算精彩片段,这些判断留给上游。
用之前知道这几件事
- 剪辑策略是”尽量无损”(losslessly where possible),加字幕动效这类操作还是要重编码。
- 它只管执行,不替你做创意决策,自动化”选什么”的逻辑得靠生态里别的组件或你自己写。
- README 没标许可证,商用前先去仓库确认 LICENSE。
- 走 MCP 的话,默认只见 12 个工具,记得
FFMPEG_SKILL_MCP_FULL=1开全量。