ffmpeg-skill：让智能体先探测素材，能不重编码就不重编码

npx skills add kajisho5/ffmpeg-skill --skill ffmpeg-skill

让智能体剪视频，最常见的翻车是：它「懂 FFmpeg」，却凭感觉猜帧率，只需要拷贝流的剪切也重新编码，最后不打开结果就报告「完成」。ffmpeg-skill 是 kajisho5 的开源仓库（MIT 协议，截至 2026-10-08 约 1.9k 星，最新版本 v2.5.1，2026 年 10 月 5 日发布），用一份 SKILL.md 加 42 个 Python 脚本，把剪辑音视频这件事排成固定流程，全部在本地调用 ffmpeg 和 ffprobe，不需要云服务和 API Key。

它让智能体按什么顺序做事

SKILL.md 给一次任务排了固定步骤，核心是「先量、再改、后核」：

1. 先探测：对要规划的输入跑 probe.py，读时长、帧率、分辨率、编码和声道，不凭文件名假设。
2. 无损优先：能不重编码就不重编码。cut.py 和 loudness.py 默认直接拷贝视频流。
3. 先干跑再执行：所有写文件的脚本都支持 --dry-run --json，先看计划。
4. 按顺序串联：色彩、剪切、拼接、静音、画幅、字幕和叠加、同步、音频、响度、导出；三步以上就写一份 project.json，交给 render.py 一次跑完。
5. 核对交付物：用 check.py --platform 对着目标平台检查，再用 look.py 生成接触印样，亲自看画面。

上图是 README 的演示之一：左半是输入，右半是 fit.py --aspect 9:16 --fit crop 的输出。项目说所有演示都用合成画面生成，可以用 python3 demos/build.py 重建。

它约束什么

• 不让智能体写原始 ffmpeg 命令：每个操作都是带类型参数的脚本，不经过 shell，也不接受调用方给的滤镜图。需求超出 42 个脚本，它要求如实说明，不许退回手写命令。
• 原片不动：输出路径已存在就拒绝，只有明确要替换时才加 --overwrite。
• 报告必须有数字：结果按 Done / Steps / Check / Look / Notes 五行汇报，时长、分辨率、帧率来自探测，不是记忆；脚本非零退出或输出文件为空，都按失败汇报。
• 判断归人：它只执行剪辑，不决定「哪里该剪」。scenes.py --highlights 按响度或时长排序，只给候选；字幕文字按用户写的原样烧录，哪怕太长也不改写，只缩字号或限制行数。
• 画面改了必须看图：加字幕、叠加、裁切、色彩转换之后，要查看接触印样才算完成；没有视觉能力的智能体必须写明「像素未检查」。

42 个脚本覆盖剪切拼接、静音和口头禅移除、9:16 或方图改画幅、字幕和卡拉 OK 高亮、LUT 与 HDR 转 SDR、多机位和外接麦克风同步、响度归一、各平台导出和合规检查。TikTok、Reels、Shorts、YouTube、X、LinkedIn、Facebook 和播客都有现成的交付模板，render.py --template tiktok 素材.mp4 一条命令出片。

适合谁

适合要让 Claude Code、Cursor 或 Codex 批量处理本地素材的人：口播切静音、横屏转竖屏、给一批文件统一响度、按平台规格导出。它处理的是已有素材；想用代码从零合成动画，可以看 hyperframes 或 remotion-best-practices 这类走 HTML 或 React 渲染的 skill。

要知道几个门槛。需要 FFmpeg 5.0 以上和 Python 3.9 以上；macOS 上 README 要求装 brew install ffmpeg-full，因为普通的 ffmpeg 公式缺 subtitles、drawtext 和 zscale 滤镜，字幕类脚本跑不了。自动转写需要本地装有 whisper，没装就让你提供文字或带时间轴的文件。它也不会替你判断好不好看：高光选段、构图和调色风格都留给调用它的智能体或你自己。SKILL.md 本身约 30 KB，加载后占用上下文，这是它换来稳定流程的代价。