ffmpeg-skill [1] 是一个专门为 Claude Code、Cursor、Codex 等 AI 编程助手设计的 Agent Skill 。
它的核心想法很简单：
不让 Agent 自己拼 FFmpeg 命令，而是给它 28 个经过严格工程化的工具脚本，每个工具都有明确的输入输出契约，执行前先探测文件、执行后自动验证结果。
而且 全在本地跑 。不需要云服务，不需要 API Key，不需要 Python 依赖——只用 Python 3.9+ 标准库和你已经装在机器上的 FFmpeg 5.0+。
这个项目 9 月 3 日才推上 GitHub，而且作者 kajisho5 自己有一整套视频制作 Agent 生态，后面会提到。
它到底解决了什么问题？
ffmpeg-skill 的 README 里有一段话我特别有共鸣：
"An agent that 'knows FFmpeg' still guesses: it assumes a frame rate, picks a codec the container cannot hold, re-encodes a file that only needed a stream copy, and reports 'done' without opening the result."
翻译一下就是： 一个懂 FFmpeg 的 Agent 还是会瞎猜 ——假设帧率、选容器不支持的编码、把只需流复制的文件重编码一遍、不看结果就说搞定。
ffmpeg-skill 就是专门治这些问题的。它给 Agent 立了几条铁规矩：
规矩一：先探测，再动手
任何操作之前，必须先跑 probe.py 。这个脚本会测出真实的帧率（还能检测可变帧率 VFR）、分辨率、旋转方向、色深、HDR 格式（包括 Dolby Vision）、色彩标签、所有音轨……Agent 从这些真实数据出发，而不是从文件名猜。
规矩二：能无损就不重编码
cut.py 和 loudness.py 默认优先用 -c copy 流复制。只有在必须帧精准剪切、或者需要用滤镜、或者容器/编码不兼容时才重编码，而且会报告一个 precision 字段告诉你精确到什么程度。
规矩三：先 dry-run，再执行
每个工具都支持 --dry-run 。跑一下看看会执行什么 FFmpeg 命令，不会真的动文件。还有 --json 输出结构化结果，里面包含输出文件的 probe 信息； --fast 出个预览质量的快速版本先看看效果。
规矩四：执行完必须验证
跑完了不是直接说"好了"。而是要重新 probe 输出文件，确认时长、分辨率、帧率、音轨都对得上。如果画面变了（加了字幕、叠加了水印、裁了画面），还要跑 look.py 生成一张联系表（contact sheet）让 Agent 自己看——字幕有没有盖在脸上、logo 位置对不对、裁剪有没有切到主体。
规矩五：原文件永远不覆盖
输出文件都是新的 _.扩展名 。有测试会对输入文件做 hash，跑完之后再 hash 一遍，确保没被改过。
28 个工具
让我把这些工具分分类，你就知道有多全了。
🔍 分析检测类
| 工具 | 干啥用 |
|---|---|
| probe.py | 全方面体检：时长、帧率（含 VFR 检测）、分辨率、编码、HDR 格式、色彩标签、所有音轨 |
| scenes.py | 场景切换检测、音频峰值检测、高光片段候选（按音频响度或时长排名），可以直接生成 cut list 喂给 cut.py |
| look.py | 从视频里截帧生成联系表 PNG，让 Agent"看到"自己做了什么doctor能力检测：列出你这台机器上的 FFmpeg 有哪些编码器、滤镜、封装器，提前告诉你哪个工具能用、哪个缺组件 |
| contract | 输出机器可读的完整工具契约（JSON 格式），每个工具的输入、输出、依赖、验证策略都在这里 |
✂️ 编辑类（真正干活的）
| 工具 | 干啥用 |
|---|---|
| cut.py | 单段/多段剪切，默认流复制无损，需要帧精确时才重编码join.py拼接多段视频，还能加 xfae 转场，自动统一尺寸/帧率/音轨silence.py自动检测静音/空白然后跳切，口语视频必备 |
| fit.py | 调整时长（变速或裁剪）、适配纵横比（填充或裁剪，还能指定保留画面哪个位置的主体）、旋转、翻转 |
| crop.py | 精确按像素裁剪矩形区域 |
| insert.py | 把一张静图变成带 Ken Burns 推拉效果的视频片段 |
| background.py | 生成纯色/渐变背景视频（连输入文件都不需要） |
| reverse.py | 倒放 |
| stabilize.py | 两轴防抖 |
| sequence.py | 把编号的帧序列合成视频 |
🎵 音频类
| 工具 | 干啥用 |
|---|---|
| audio.py | 人声清洗链路、FFT 降噪、压缩器/限制器/门限器、背景音乐+sidechain ducking（人声时自动压低背景音乐）、淡入淡出、5.1 转立体声 |
| sync.py | 两路录音对齐（音频互相关，精度 1ms）、时钟漂移校正、支持把外置麦克风替换掉相机原声 |
| loudness.py | EBU R128 响度标准化到 -14 LUFS / -1 dBTP 或你指定的目标 |
🖼️ 画面叠加类
| 工具 | 干啥用 |
|---|---|
| caption.py | 烧录 SRT/ASS 字幕，支持字体/大小/颜色/描边/位置，还能做逐词动画和卡拉 OK 效果，可选本地 Whisper 自动转写 |
| overlay.py | Logo/水印/标题叠加（位置、时间、透明度、淡入淡出），画中画，绿幕抠像 |
| graphics.py | 下三分之一字幕条、章节标签、进度条、倒计时——纯 FFmpeg 滤镜画出来的，不用图形文件 |
| color.py | HDR10/HLG/Dolby Vision → SDR BT.709 色调映射，3D LUT（.cube），色彩标签重写 |
📤 导出与交付类
| 工具 | 干啥用 |
|---|---|
| export.py | 预设导出：YouTube / Reels / TikTok / X，ProRes 母版，HEVC，GIF 预览 |
| check.py | 交付前合规检查：格式/编码/像素格式/尺寸/响度/色彩标签/VFR，标记 PASS / WARN /FAIL |
| FAILverify.py | 对输出文件做最终验证render.py项目级渲染——把多个步骤写进 project.json，一次性跑完所有操作 |
| proxy.py | 生成低分辨率代理文件（快速预览用，不是交付用） |
| batch.py | 批量处理文件夹 |
快速入手
一行命令：
# 为 Claude Code 安装
npx ffmpeg-skill
# 为 Cursor 安装
npx ffmpeg-skill --cursor
# 为 Codex 安装
npx ffmpeg-skill --codex
# 三个都装
npx ffmpeg-skill --all装完先跑一下 doctor 检查环境：
npx ffmpeg-skill doctor它会告诉你 FFmpeg 有哪些能力、哪些工具能用、哪些滤镜缺。
而且这套工具 脱离 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 # 只看命令，不动文件
python3 $S/export.py input.mp4 --preset reels --json # 输出结构化结果SPEC 契约驱动 + 自动 MCP
这个项目有个挺有原创性的设计，作者叫它 SPEC（Self-Producing Execution Contract） 。
普通的 Agent Skill 就是一堆提示词 + 一些脚本，Agent 能不能用对全靠运气。
但 ffmpeg-skill 把每个工具的输入输出都变成了 机器可读的 JSON Schema ，而且这个 Schema 不是手写的——它直接从每个脚本的 argparse 解析器里自动生成。
就是说你给脚本加了一个新参数 --foo ， contract --json 里会自动出现这个参数的定义，MCP 服务端的 tools/list 里也会自动更新，完全不需要手动同步。
有测试保证这两边 byte-identical，改了一边没改另一边 CI 直接挂。
MCP 支持也是自带的 。跑 mcp/server.py 就是一个标准 MCP stdio 服务端，Claude Desktop、Cursor、任何 MCP client 都能直接连上，所有 28 个工具自动变成 MCP tools。
视频制作 Agent 生态
作者挺有意思的，ffmpeg-skill 不是孤立的项目。他的 GitHub 上有一整套视频制作 Agent 相关的仓库：
| 仓库 | 定位 |
|---|---|
| ffmpeg-skill （就是本文的主角） | 执行层——裁剪、测量、导出文件，报告 JSON |
| video-production-agent | 决策层——决定剪哪里、审批成片、规划整个编辑 |
| AI-video-production-OS | 编排层——跨仓库的 Capability 调度 |
| video-editing-skill / audio-production-skill | 编辑层——在 workspace 上构建类型化的编辑图 |
| media-analysis-skill / transcription-skill / subtitle-skill / thumbnail-skill / color-grading-skill / motion-graphics-skill / qc-skill | 各司其职的专业模块 |
ffmpeg-skill 在这个生态里是"手"——它不会决定"这个高光够不够精彩"、"字幕盖在脸上面应该往上挪"，那些是其他 skill 或上层 Agent 的事。
它只做一件事： 给我明确的参数，我就严格执行，然后把结果告诉你。
这个定位挺清晰的：ffmpeg-skill 不抢其他组件的活，但它干的活最扎实——因为有契约、有验证、有不猜的规矩。
写在最后
说实话，FFmpeg 本身已经很强了，网上也不缺各种"FFmpeg 速查表"、"FFmpeg 常用命令"。
但这个把 FFmpeg 工程化成一套 给 AI Agent 用的、可验证的、不会猜的工具集 ，ffmpeg-skill 是做得比较完整的。
你手里有素材、又懒得背 FFmpeg 参数的话，装上它。
跟 Agent 说一声就行，它会自己探测、自己规划、自己验证。执行完了还给你报确切的时长分辨率和一张缩略图。
项目地址： https://github.com/kajisho5/ffmpeg-skill
