ffmpeg-skill – 给 AI 编程助手装上视频剪辑能力的开源技能

ffmpeg-skill是一款由开发者 kajisho5 于 2026 年 9 月开源的AI 编程助手视频剪辑技能，把粗剪、字幕、画幅与响度处理交给智能体在本机完成，采用无损优先的剪辑路径与出错即回执，适用于成片粗剪、口播去停顿与竖屏改版。

ffmpeg-skill 的核心能力

它解决的不是「能不能剪」，而是「智能体敢不敢自己剪」：工具有固定输入输出契约，出错回原因，成片回读验证，剪辑才能无人值守。

42 个工具：把剪辑动作拆成可调用单元

从 cut、join、silence、fit、caption 到 loudness、metadata、grid，官方把常见动作逐个拆成独立脚本，每个都带 --help、--dry-run、--json 与 --plan；助手不必写对整条 filter 链。

契约先于代码：参数表由解析器现算，CI 防漂移

官方把这套机制叫 SPEC：input_schema 不手写，而是运行时从定义命令行参数的同一份 argparse 解析器推导。CI 把参数名钉在快照上，漂移即构建失败。

自检闭环：先探测，再无损剪，最后回读验证

官方给助手定的工作流是 probe、无损剪、回读三步：先看时长、帧率、可变帧率、HDR 与每条音轨，cut.py 先试 -c copy，需帧级精确才用 --accurate 重编码。

MCP 双通道：默认只暴露 12 个核心工具

工具同时是 MCP tool。默认 tools/list 只广播 12 个核心动作以控制上下文占用，设 FFMPEG_SKILL_MCP_FULL=1 才列出全部 42 个，任何模式下都能经 tools/call 调到。要让助手把整条任务链放本机跑，视频侧做法可对照 Hypit。

本地闭环：素材不出机器，也不需要 API Key

全部处理走本机 ffmpeg 与 ffprobe，不经过云端。合同、医疗、内部培训这类不便外传的片子可整条留在本机，代价是吃自己的 CPU。

按平台交付：安全区、画幅与响度一次对齐

look.py 的 --safe 遮出目标平台 UI 覆盖区，fit.py 做 9:16、1:1 画幅重构与补边，loudness.py 按 -14 LUFS 做响度归一，三者串成多平台发布的最小流水线。

ffmpeg-skill 与 FFmpeg、Shotstack、剪映专业版的对比

下表把它与三款具体产品并列：FFmpeg 本体、云端剪辑接口 Shotstack、桌面端剪映专业版。第一列取自仓库文档，后三列取自各自官网。

差别在智能体可用性、失败反馈与精细控制三处：它把动作做成带契约的工具，另三款要么由人再包一层，要么面向人手操作；报错它回非零退出码加原因，助手可据此重试；精细控制它给固定参数集，写任意 filter_complex 仍得回到 FFmpeg。流水线省事选第一列，精调选 FFmpeg。

站内写过 DeepSeek Harness，同样把智能体的执行环节放在本机，一个管编码与任务编排，一个管视频处理。

ffmpeg-skill 的应用场景与适用人群

它对应「剪辑动作重复、每次都靠人点」的情形，常见场景包括：

• 口播长视频去停顿：silence.py 按句边界切静音，--speech-aware 只在句末下手。
• 一次成片多平台发布：fit.py 按 9:16、1:1 重构画幅，--safe 避开 UI 遮挡区，不必逐平台导出。
• 批量课程与访谈：先用 --plan 写出剪辑计划，确认后整套参数复用到整批素材；批量编排交给终端智能体时可用 Step Code。
• 字幕与卡拉 OK：caption.py 支持 pop 动画与逐词高亮，字幕烧进画面。
• 素材脱敏：redact.py 对给定矩形做模糊、马赛克或 delogo 插值。

适用人群：用 Claude Code、Cursor、Codex 批量处理视频的开发者与内容团队，以及要把剪辑步骤固化成流水线的运营岗。注意 redact.py 只处理给定矩形，不做人脸或车牌识别，脱敏范围仍要人工划定。

ffmpeg-skill 的使用方法

官方给了三条路径：npx 装进技能目录、插件安装、MCP 服务接入。

npx 安装：装进助手技能目录

1. 装技能：按 ffmpeg-skill 官方仓库 的说明执行 npx ffmpeg-skill，默认装到 Claude Code 的 ~/.claude/skills/ffmpeg-skill；Cursor 加 --cursor，Codex 加 --codex，一起加 --all。
2. 装 FFmpeg：macOS 用 brew install ffmpeg-full（普通版缺 libass 等滤镜）；Ubuntu 用 sudo apt install ffmpeg；Windows 用 winget install Gyan.FFmpeg。
3. 体检：执行 npx ffmpeg-skill doctor，确认 libx264、subtitles、loudnorm 等组件在位。

插件安装：不走 npm 的方式

1. 不想用 npm 的可以走插件：claude plugin install kajisho5/ffmpeg-skill。
2. 完全没有 Node 的环境，克隆仓库后把 SKILL.md、scripts、references 与 mcp 复制进技能目录即可。

MCP 服务接入：先对齐契约再派活

1. 对齐契约：执行 npx ffmpeg-skill contract --json，看工具清单与参数 schema。
2. 让它干活：用自然语言说清目标，例如「把 20 分钟访谈去停顿、加中文字幕、输出 9:16」；助手先调 probe，再按序执行。
3. 复核产出：工具都会回读结果并给 verified 字段，失败为非零退出并写明原因；批量先用 --dry-run 或 --plan。

不同装法装到的是同一套工具，助手看到的工具清单一致；更多同类工具可以在 AI 工具箱 里按类别翻。

ffmpeg-skill 的项目地址

• GitHub 主仓库（源码、文档与 issue）：https://github.com/kajisho5/ffmpeg-skill
• npm 包页面（版本与安装命令）：https://www.npmjs.com/package/ffmpeg-skill

ffmpeg-skill 的价格方案

免费。代码与 npm 包同为 MIT，安装、修改与商用都不产生许可费用，也没有按调用量计费的接口。

成本落在算力与时间上：编码吃 CPU，长素材的 --accurate 重编码更慢；单个工具默认超时 1800 秒，超时会杀进程，可用 FFMPEG_SKILL_TIMEOUT 调高。

无订阅与额度限制。素材不上传对合同、医疗、内部培训一类片子更实际；本机性能差时等待要自己承担。

ffmpeg-skill 的常见问题