42 个 FFmpeg 工具交给编程助手,本地剪片不用 API key,只是别指望它懂审美
ffmpeg-skill 把 FFmpeg 拆成 42 个结构化工具给 Claude Code、Cursor、Codex 调用,本地跑,素材不出门。它花力气解决 agent 瞎猜 FFmpeg 参数的问题,也明说自己检查的是文件不是画面。
在 Claude Code 或 Cursor 里说一句“把 interview.mp4 的 0:45 到 3:10 和 5:00 到 6:30 剪出来,做成 60 秒的竖版 Reels”,agent 会按 SKILL.md 里的流程跑 probe、cut、fit、export、check、look,最后回报:final.mp4,59.98 秒,1080×1920,30fps,AAC 立体声,附上它看过的 contact sheet。
这是 ffmpeg-skill 想做到的事。项目在 github.com/kajisho5/ffmpeg-skill,MIT 协议,本地跑 FFmpeg,不需要 API key,素材不出门。安装一行 npx ffmpeg-skill。

agent 知道 FFmpeg 仍然会猜
一个读过 FFmpeg 文档的 agent 会干这些事:假设一个帧率,挑一个容器装不下的编解码器,对一个只需 stream copy 的文件重新编码,然后不打开结果就报完成。README 的 Why 一段就在说这个。
ffmpeg-skill 的对策是四条规则:每个任务从 probe.py 开始,用测出来的时长、fps、分辨率、色彩和音频布局做决定;每个操作是有类型参数的脚本,不走 shell,不接受调用方传 filter graph;contract --json 写清每个工具吃什么、写什么、依赖哪个 FFmpeg 组件、结果怎么验;写完之后 probe 输出,画面变了就生成 contact sheet 让 agent 看。
42 个工具拆开看
分析检查类(probe、scenes、look)先跑,剪辑类(cut、join、silence、fit)在中间,音频类(audio、sync、loudness)单独一组,画面类(caption、overlay、graphics、color)处理字幕、水印、调色,最后交付类(export、check、report)按平台规格导出和打分。编排类里 render.py 从一份 project.json 跑整条流水线,batch.py 处理一整个文件夹,multicam.py 靠音频互相关对齐多机位。
有几个具体行为值得说:
cut.py --smart只重编码 H.264 切点附近的那几个 GOP,中间的 stream copy,然后把结果跟源比对帧。比全量重编码快,也比纯 stream copy 精确。silence.py默认阈值 -35 dBFS,切点前后各留 0.2 秒气口。--speech-aware只切句子之间的停顿,保留句子内的呼吸。切到呼吸或词尾会在报告里 warning。caption.py --fit-size的字号往下走到每条字幕塞进平台安全区,而不是把一句话切成四条。文字本身不改写,换行点有自己的规则,不会在词中间断。render.py --template tiktok一条命令出成片:9:16 裁切,逐词 karaoke 字幕放在 TikTok 描述栏上方、让开点赞列,-14 LUFS,导出后用check.py按平台规格再验一遍。




上面每组都是左半边输入、右半边输出,命令行写在 gif 下面。这些 demo 由仓库里的 demos/build.py 逐帧重建,可以自己跑。
它检查文件,不检查画面
每个写出文件的工具跑完都会再 probe 一次,用工具自己的承诺做检查。loudness 二次测量 LUFS 和真峰值,cut 报告切点偏了多久,export 检查预设的最长时长,值读不出来记 not_measured,不算通过。
但好看吗这件事不在检查范围里。look.py 只生成一张 PNG contact sheet,真正看的是 agent 自己的多模态能力。人脸、产品、主体检测,这个仓库一个都没有。fit.py --fit crop 默认中心裁,要偏向主体就自己给 --crop-x/-y。cropdetect.py --motion-centre 报告每秒运动质心,但只报告,不剪。README 把 picture_content、subject_framing、grade_look、lip_sync 都列在 unverified 里。
作者 Kajiyama 自己的论文里写,ffmpeg-skill 只部分符合他定义的验证驱动纪律。这句话就放在 README 的 Paper 一节,没藏起来。
几个被问到的问题
有人问 filter_complex 拼错一步整片黑屏怎么办。这个 skill 不接受调用方传 filter graph,每个操作是脚本,参数是类型化的,不存在手拼滤镜链这回事。
有人问剪完会不会自己回看。会看文件属性,会生成 contact sheet,但画面内容得靠调用它的 agent 有视觉能力,仓库不提供这个判断。
有人问只把第二个镜头缩短半秒,其他剪辑决定会不会跟着重来。整条剪辑描述在 project.json 里,剪点、转场、字幕、音乐电平都在,改一个参数重渲染时 --cache 让没变的阶段直接复用。这不是撤销,是改一处重新算。
边界
FFmpeg 6.1 以上,Python 3.10 以上,标准库。macOS 上 Homebrew 的 ffmpeg 缺 subtitles、drawtext、zscale,得装 ffmpeg-full,脚本会自己在同一个 prefix 里找。
去不掉移动的 logo。redact.py --mode delogo 只处理固定矩形,做的是 1 像素边框混合,不是 inpainting,HDR 和 10-bit 源会直接被拒。
HDR 到 SDR 靠 zscale 加 tonemap,--peak 要自己按源的峰值亮度给,给高了画面暗,给低了高光切。这部分也算人工判断。
怎么用
npx ffmpeg-skill
npx ffmpeg-skill doctor
装完对着 agent 说人话就行,比如“把这段访谈的废话剪掉,压到 60 秒,加中文字幕导出成竖版”。它会自己拆成几条命令去跑。
值得知道的一点:它把剪辑拆成 42 个可测量的小任务,每一步都有东西可核对。批量切片、补字幕、多机位对齐、平台合规,这些重复活交给它确实省事。但哪一秒是高潮、字幕断在哪儿、裁切保住哪张脸,仓库明说不是它的事。
工具只负责执行和测量,判断还是人的。
发布时间: 2026-11-15 18:30