ffmpeg-skill 怎么用？一条命令装上视频剪辑

一条 npx ffmpeg-skill，加上本机装好的 ffmpeg 和 Python，你的 AI 编程助手就能自己剪片、转码、去空话、加字幕了。这个项目在 GitHub 上 kajisho5/ffmpeg-skill 目前约 1.1k star、80 个 fork，README 里说得很直白：给编码 Agent 配一个「视频编辑器」。

ffmpeg-skill 是什么：不是命令合集，是一套工作流

很多 Agent「知道 ffmpeg」，但实际干活时全靠猜：假设帧率、选容器装不下的编码器、把只需要复制流的文件重新编码，最后报告「完成」却没打开看过结果。ffmpeg-skill 解决的就是这个问题，它教给 Agent 一套固定工作流：

1. 先探测：每个任务从 probe.py 开始，量出真实时长、帧率、分辨率、音轨，不看文件名瞎猜。
2. 能无损就无损：剪辑、拼接优先流复制，只在必要时重新编码。
3. 干完必校验：输出文件会被再次探测，画面有改动还会生成联检图（contact sheet）让 Agent 亲眼看一遍。

它带 39 个工具，全部用 Python 标准库写的本地脚本，不联网、不要 API Key、素材不出本机，MIT 协议，要求 ffmpeg 5.0+ 和 Python 3.9+。每个工具同时是 MCP 工具，所以 Claude Desktop 也能调。安装思路和站内其他 Skill 教程一致，可以对照 Dashi PPT Skill 完全教程 和 diagram-design 中文教程。

装之前先看一眼版本节奏

这个项目发版很勤，你遇到的大多数「报错」其实是被修掉的旧版本问题，所以先对齐版本：

对你意味着两件事：第一，技能不会自动更新，感觉行为奇怪时先重跑一次安装命令刷到最新版；第二，公开 issue 数量少不代表没问题，更可能说明作者修复速度快、讨论集中在 Discussions 区，遇到问题先去那里的 Discussions 搜一遍。

开跑前要备齐的三样东西

1. Node 环境（用 npx 跑安装器）。
2. ffmpeg.org 下载的 ffmpeg 5.0 以上版本，含 ffprobe；macOS 用 Homebrew 装，Windows 可下 gyan.dev 构建。注意这里是硬要求：低于 5.0 的版本会缺这套工具依赖的滤镜与能力。
3. Python 3.9 以上，只需要标准库，不用装任何第三方包。

三样缺一样，后面都会以「命令找不到」或「滤镜不存在」的形式报出来，所以先花两分钟确认版本号再往下走。

安装：一条 npx 命令

在终端里执行：

npx ffmpeg-skill

默认装给 Claude Code（写入 ~/.claude/skills/ffmpeg-skill）；给 Cursor 用加 --cursor，给 Codex 用加 --codex，三家都装加 --all。已经装过的，重跑同一条命令即可刷新，技能不会自动更新。npm 包地址见 npmjs.com/package/ffmpeg-skill。

装完没生效时，先按这个顺序排：一是确认安装目标选对了（默认只写 Claude Code 的技能目录，其他编辑器要显式加参数）；二是重启一次编辑器会话，让技能清单重新加载；三是确认脚本目录真的存在（默认在 ~/.claude/skills/ffmpeg-skill/scripts）。

体检：doctor 逐工具看结论

安装完先别急着派活，跑：

npx ffmpeg-skill doctor

doctor 会检查 ffmpeg、ffprobe，以及每个工具需要的组件（libx264、libass、loudnorm、xfade 等）在不在。这里有个很容易踩的坑：doctor 总体显示 ok，不代表所有工具都能用。比如 macOS 上 Homebrew 默认装的 ffmpeg 可能缺少 subtitles 滤镜，总体 ok，但字幕工具 caption.py 就是跑不了。要看 doctor --json 输出里 tools 字段的逐工具结论，别只看总开关。

契约：contract --json 看能力边界

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

这个命令输出全部 39 个工具的机器可读契约：每个工具要什么参数、写什么文件、需要哪些 ffmpeg 组件、怎么校验结果。Agent 就是靠这份契约挑工具的，你扫一眼也能知道能力边界。

实际用法：怎么指挥 Agent 剪片

装好后直接用自然语言下需求，比如让 Agent 处理一段访谈视频：

把 interview.mp4 保留 0:45 到 3:10 和 5:00 到 6:30 两段，压成正好 60 秒、9:16 竖版，发 Reels 用。

Agent 会按顺序调 probe.py 探测、cut.py --segments 剪段、fit.py --duration 60 --aspect 9:16 调比例、export.py --preset reels 导出、check.py --platform reels 做平台合规检查、look.py 出联检图，最后给你一份结构化报告：成片 59.98 秒、1080x1920、30fps、AAC 立体声，附它检查过的画面拼图。

工具也能脱离 Agent 单独跑：

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

--dry-run 只打印计划不动文件，--json 返回带输出探测的结构化结果，先预览再执行是好习惯。

39 个工具怎么挑：按任务速查

完整清单跑 contract --json 看，或读仓库 README 的 Tools 表。想继续扩充 Agent 的技能库，可以再看 frontend-design skill 实测教程。

边界与前提：哪些事别指望它

知道它不做什么，比知道它能做什么更重要：

1. 它只动手，不做决定。这套工具负责剪、量、导出并返回结构化 JSON；选题、节奏、审片这类判断属于同一作者的视频生产系列工具，依赖是单向的。
2. 没有云端兜底。全程本地执行意味着不联网、不传素材，但也意味着本机环境不达标就完全跑不起来，没有「换台服务器试试」这条路。
3. 速度由你的机器决定。本地转码的耗时取决于 CPU 和硬解支持，大文件批量处理前先用一个短片跑通流程再排队。
4. 不覆盖专业特效。多轨时间线、复杂合成、精细调色这类活，专业剪辑软件里拖两下就完成，指挥 Agent 反而绕路。
5. 转写是可选依赖。只有用到本地转写功能才需要本机装 whisper，不需要的话可以完全不装。

适合谁用，不适合谁

适合日常要批量处理视频的人：剪播客、去冷场、统一竖版尺寸、加字幕这些重复劳动交给 Agent 最划算；不适合追求精细特效和复杂时间线的专业剪辑师，专业剪辑软件里拖两下的活，指挥 Agent 反而绕路。另外素材敏感的团队可以放心：全程本地处理，不联网。

常见报错速查