
Agent 剪完视频,会先量一遍、再看一眼成品。
摘要
ffmpeg-skill 把 42 个本地 FFmpeg 工具打包成一个 Agent Skill,Claude Code、Cursor、Codex 都能直接调用。剪辑、字幕、竖屏改版、响度、平台导出全在本机完成,不用云端,也不用 API Key。
核心优势
让 AI 剪视频,常见翻车点是"以为自己会 FFmpeg":臆测帧率、选了容器装不下的编码、只需要流拷贝却整段重编码,最后没打开成品就说"完成"。这个项目把这些猜测一项项拿掉:
- 先测量再动手 :每个任务从
probe.py开始,时长、帧率、分辨率、色彩、音轨布局都按实测值决策,而不是看文件名。 - 结构化工具,不是 shell 拼接:每个操作是一个带类型参数的脚本,不经过 shell,也不接受调用方传入的滤镜图。
- 机器可读的契约 :
contract --json说明每个工具的输入、输出、所需 FFmpeg 组件和验证方式,MCP 接口就是从它派生的,参数不会和脚本脱节。 - 做完要验收 :成品会被再次 probe,对照目标平台规格检查,画面有变化时还会用
look.py生成联系表,让 Agent 亲眼看一遍。 - 能无损就无损 :
cut.py、loudness.py对不需要改动的流直接拷贝,不重编码;所有工具都不覆盖原文件。
整个项目只依赖 Python 3.10+ 标准库,没有第三方 Python 依赖,视频也不用离开你的电脑。
面向人群
- 已经在用 Claude Code、Cursor 或 Codex,想让 Agent 直接处理本地素材的开发者
- 要批量把长视频切成竖屏短视频、统一响度的内容创作者
- 不想把访谈、会议录像上传到云端剪辑服务的人
- 在搭 Agent 工作流,需要一套"参数可读、结果可验"的剪辑工具层的工程师
快速上手
先装 FFmpeg(项目要求 6.1 及以上),再一行命令安装 Skill(npx 安装器需要 Node 16+):
bash
# 0. 装 FFmpeg(Ubuntu/Debian 示例)
sudo apt install ffmpeg
# macOS 要装 ffmpeg-full:普通的 ffmpeg 缺 subtitles、drawtext 滤镜,烧字幕会用不了
# brew install ffmpeg-full
# 1. 为 Claude Code 安装(Cursor 加 --cursor,Codex 加 --codex)
npx ffmpeg-skill
# 2. 体检:ffmpeg、ffprobe 以及各工具需要的组件是否齐全
npx ffmpeg-skill doctor
# 3. 读取机器可读契约
npx ffmpeg-skill contract --json | head -40
装好之后,直接对 Agent 说人话:
把 interview.mp4 里 0:45--3:10 和 5:00--6:30 留下,剪成正好 60 秒的竖屏版。
Agent 会依次跑 probe.py、cut.py --segments 0:45-3:10,5:00-6:30、fit.py --duration 60 --aspect 9:16 --fit crop、export.py --preset reels 和 check.py --platform reels,画面有改动时再用 look.py 看一眼,最后汇报实测结果:59.98 秒、1080×1920、30 fps。
这些工具也能脱离 Agent,在命令行里单独用:
bash
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 # 输出带成品 probe 的结构化结果
每个工具都支持 --dry-run(只打印 ffmpeg 命令,不写文件)和 --json,失败时以非零退出码加原因退出。
进阶用法
一条命令交付到平台。 render.py 配合模板,把裁切、字幕、响度、导出预设和最终检查串成一步:
bash
python3 $S/render.py talk.mp4 --template tiktok --cues cues.txt
模板会做 9:16 裁切,把逐字弹出的字幕放在平台描述栏之上、避开点赞栏,同时按预设响度处理,并对写出的文件跑一次平台检查。
字幕与去静音。 caption.py 能烧录 SRT/ASS,也能封装成软字幕轨,字号按平台安全区自动适配,并选用覆盖中日韩等文字的字体;需要语音转写时,装一个本地引擎即可,最简单的是 pip install faster-whisper,音频不出本机。silence.py 负责剪掉冷场,两侧默认各留 0.2 秒余量。项目在 20 个已知静音段的测试文件上做过验证:没有漏检,残留静音最多 1 毫秒。
接入 MCP。 在 MCP 客户端里加一段配置,指向 mcp/server.py,工具列表在启动时从契约派生。默认只列出核心的 12 个工具(省上下文),其余 30 个仍可按名字直接调用,设 FFMPEG_SKILL_MCP_FULL=1 则全部列出;另外还提供 reel、podcast、multicam、delivery_check、hdr 五个现成的工作流提示。
边界要心里有数。 验证只覆盖"能测量的部分":画面内容、主体构图、字幕的实际位置和可读性,工具会在 unverified 里明说没测,所以动过画面之后一定要看联系表。它也没法真正"抹掉"移动的水印或位置会变的烧录字幕(只能用 redact.py 处理位置固定的矩形区域),不做人脸或主体自动追踪,GPU 编码目前只支持 Apple Silicon 的 VideoToolbox,而且要加 --hw 手动开启。
项目地址:github.com/kajisho5/ffmpeg-skill
收藏清单
- 先装 FFmpeg 6.1+(macOS 用
ffmpeg-full)、Python 3.10+ 和 Node 16+,再npx ffmpeg-skill - 装完先跑
npx ffmpeg-skill doctor,缺哪个组件一目了然 - 让 Agent 先
--dry-run看计划,再真正执行 - 动过画面的成品,必看
look.py的联系表 - 报告里
unverified列出的项,要自己亲眼确认