ffmpeg-skill 是给编程智能体装的本地剪辑师:Claude Code、Cursor、Codex 直接指挥你电脑上的 FFmpeg 剪片——先量后剪、剪完自检,全程不上云、不要 API key、不用花钱。MIT 许可证,GitHub 实时 7,762 星(本站核对:2026-11-18),过去一周日均新增从约 109 星涨到约 490 星,是本周增速最快的新秀之一。本站验证:全程实机跑通——npx 安装、doctor 体检、probe 量片、cut 剪片、check 验收,数字见正文;语音转字幕未实测(未装 faster-whisper)。

能干什么

  • 42 个工具,一套固定流程:先 probe 量出片子的时长、帧率、分辨率与音频底细,再剪辑,最后 check 按平台规范验收、look 看接触表确认画面。剪、接、去静音、按时长与比例适配、字幕与卡拉 OK、叠加与动效、HDR 转 SDR、音频清理、响度、多机位、交付检查、批量处理都在内。
  • 一句话出多平台版本:对智能体说“把这段做成 60 秒竖屏 Reels”,它自己跑 probe、cut、fit、export、check、look 全套;模板覆盖 TikTok、Reels、Shorts、YouTube、X、LinkedIn、Facebook、播客与音频图,--template all 一次出七个视频版本。
  • 不用学 FFmpeg 命令:每个操作都是带类型参数的脚本,不拼 shell 字符串;每一步的输入要求由机器可读的 contract 写死,改了代码没同步改说明,CI 会直接报错。
  • 本地离线:只要 ffmpeg 与 python3 在 PATH 里就能跑;Python 只用标准库,不装任何依赖;字幕转录用的语音引擎也在本地跑,音频不上传。

优缺点

优点:免费、离线、无账号;结果自带校验——check 按平台规范逐项验收,look 把成片摊成接触表给你看,不靠嘴说“好了”;文档极细,每个工具的输入格式与验证方式都写清,改错了会直接拒绝而不是悄悄出废片;本站实测:10 秒测试片从量片到剪片再到验收全程无报错。

缺点与边界:FFmpeg 本身要自己装,macOS 得装带全套滤镜的 ffmpeg-full,普通版缺东西;语音转字幕要另装 faster-whisper,首次运行还要下载模型;重编码大文件耗时看机器;它只是“手”不是“脑”——剪哪几段、留什么内容,要你自己说清楚,它不替你做判断;去不掉已经烧进画面的字幕与 Logo,也不会自动追踪人脸重构图。

下载与安装(官方文档口径,本站实测)

  1. 先装 FFmpeg 本体:Ubuntu / Debian 用 sudo apt install ffmpeg;macOS 用 brew install ffmpeg-full(注意:它是 keg-only,不会自动进 PATH,装完要按官方说明把它的 bin 目录放到 PATH 最前面或链接过去);Windows 用 winget install Gyan.FFmpeg。本站这台机器是 FFmpeg 8.1.2,官方要求 6.1 以上,5.x 会直接拒绝。
  2. 装技能:npx ffmpeg-skill(装给 Claude Code;Cursor 加 --cursor,Codex 加 --codex,三个全装加 --all,只装给当前项目加 --project)。本站实测:npx ffmpeg-skill --dir /tmp/ffskill-test 一次成功,装完提示“Done. Ask your agent things like …”。
  3. 验机:npx ffmpeg-skill doctor。本站实测结果:Python 3.12.3、FFmpeg 8.1.2,86 项能力全可用、0 项必需缺失,只缺两个可选的语音引擎(parakeet、whisper)——不影响剪片,只影响语音转字幕。
  4. 插件路线(不用 npx):Claude Code 2.1.275 以上用 /plugin install ffmpeg-skill --marketplace kajisho5/ffmpeg-skill;Codex 与 Gemini CLI 各有官方给出的两条插件命令;没有 Node 的机器可以克隆仓库后手动复制 SKILL.md、scripts、templates 等文件到智能体的技能目录。
  5. 国内网络:npx 默认走官方注册表,下载慢可换 npm 国内镜像源(npm config set registry https://registry.npmmirror.com),装好之后剪片全程离线。

调用与使用

  1. 对智能体说一句话就行,例如:“把 interview.mp4 里 0:45–3:10 和 5:00–6:30 留下来,做成正好 60 秒的 Reels。”它会自己跑 probe、cut、fit、export、check、look,最后报一句“final.mp4:59.98 秒、1080×1920、30 fps、AAC 立体声”,附上它检查过的接触表。
  2. 也可以直接在 shell 里用脚本:python3 $S/probe.py input.mp4 --compact 量片,python3 $S/cut.py input.mp4 --segments 2-5 剪片,python3 $S/fit.py input.mp4 --duration 60 --aspect 9:16 --dry-run 先看方案再动手。
  3. 本站实测(10 秒 1280×720 测试片):probe 量出“10.000 秒、1280×720 @ 30.0fps、h264、AAC 单声道”;cut 取 2–5 秒得到 3.100 秒成片;check 逐项验收,时长一项 PASS;fit 干跑时如实拒绝了不合理要求——10 秒片子拉到 60 秒要 0.17 倍速,超过 4 倍速上限,工具直接报错而不是硬做。
  4. 按平台出片:python3 $S/render.py talk.mp4 --template tiktok --cues cues.txt,字幕位置、响度(-14 LUFS)、导出预设与验收一次配齐;--template all 从同一份剪辑一次出七个视频平台的版本。

调教成自己的

  • 改模板,别每次重说:templates 目录里是各平台的成片规范(字幕放哪、多大、响度多少),按自己账号的风格改一份,以后每次出片自动按你的规范来;--brand 可以定字幕尺寸。
  • 把常用组合固定下来:比如“去静音 → 剪成 60 秒 → 上字幕 → 响度归一 → 出七个平台包”,写成一条固定流程,每次只换输入文件。
  • MCP 模式:没有 shell 的客户端用 npx -y ffmpeg-skill mcp 起 MCP 服务;默认只露出 12 个核心工具省上下文,设 FFMPEG_SKILL_MCP_FULL=1 全开 42 个。
  • 先看 doctor 再动手:doctor 的 ok 为 false 不代表全坏,看 doctor --json 里每个工具的 usable——缺一个滤镜只影响用到它的那一两个工具。

玩法:自媒体创作者的一条长视频,变出全平台素材包

模拟一位每周发一条口播的自媒体创作者:长视频录完 20 分钟,要发公众号视频号、抖音、视频号、B站与小红书,过去是打开剪辑软件一段段切。他的打法:

  1. 长视频丢给智能体,一句话:“去掉静音段,留精华 3 分钟,再做一条 60 秒竖屏版。”
  2. 竖屏版用模板一次出 TikTok、Reels、Shorts 七个版本:字幕自动避开各平台的点赞栏与简介栏,响度统一 -14 LUFS。
  3. check 逐项验收:时长、比例、帧率、音频有一项不对就当场指出,不用你自己逐个打开看。
  4. 每周固定这一套流程,只换输入文件;剪点判断仍在人——哪段是精华、哪句是钩子,开口之前自己先定好。

避坑指南

  • 先跑 doctor,别直接剪:缺滤镜、缺编码器都会在 doctor 里列出来;ok 为 false 时看每个工具的 usable,不要只看总开关。
  • macOS 必须装 ffmpeg-full:普通 ffmpeg 公式缺 subtitles、drawtext、zscale 等滤镜,字幕与动效类工具会直接不可用;装完记得处理 keg-only 的 PATH 问题。
  • FFmpeg 版本别太旧:要 6.1 以上,5.x 会被直接拒绝;Ubuntu 一行 sudo apt install ffmpeg 装到的通常都够新。
  • 语音转字幕要另装引擎:caption.py --transcribe 需要 faster-whisper 这类本地语音引擎(pip install faster-whisper,首次运行下载模型);没装时它会直接拒绝并给出安装行,不会瞎猜。
  • 它不替你选剪点:剪哪段、留哪句,你开口前要自己定;只说“剪好看点”它没法执行。
  • 改模板前先备份:templates 目录改乱了没有一键恢复,先复制一份再改。

档案

  • 仓库:github.com/kajisho5/ffmpeg-skill;许可证 MIT(干净可商用,可二开、可改、可分发,须保留许可证与版权声明);官网 kajisho5.github.io/ffmpeg-skill;npm 包 ffmpeg-skill,最新版 3.10.1(注册表核对)。
  • 星数 7,762(2026-11-18 实时核对);过去一周日均新增从约 109 星涨到约 490 星(whatstrending.ai 2026-11-18 报告);FFmpeg 6.1 / 7.1 / 8 / 9 均经 CI 测试。
  • 本站验证:npx 安装、doctor(86 项能力全可用、0 必需缺失)、probe、cut、check 全程实机跑通——10 秒测试片量出 1280×720 @ 30fps,cut 2–5 秒得到 3.100 秒成片,check 时长项 PASS;语音转字幕未实测(未装 faster-whisper)。

常见问题

和直接让 AI 写 ffmpeg 命令有什么区别?直接写命令靠模型现编,容易猜错帧率、选错编码、把不用重编码的文件重编码一遍,还不检查结果;这个技能是先量片、再用带类型参数的脚本执行、最后按平台规范验收并看接触表,错了会直接拒绝而不是悄悄出废片。

它会上传我的视频吗?不会。全程本地,音频与画面都不出本机;语音转录也在本地跑。

能剪 4K 或一小时长片吗?能,工具本身不限制时长与分辨率,耗时看机器;官方文档有在真实长素材上测试的记录。超长重编码可在 FFMPEG_SKILL_TIMEOUT 里放宽时限。

支持 GPU 加速吗?支持,但只在显式要求时用(--hw 或 FFMPEG_SKILL_HW=1),默认走 CPU;本站实测的这台机器检出 16 个 GPU 编码器,未实际调用。

剪片卡住了搞不定怎么办?先跑 npx ffmpeg-skill doctor --json 看是哪个工具缺什么;实在跑不通,可以看本站的部署与配置跑通服务,把跑通这一步交出去。

站内往下读:AI视频栏目、AI智能体栏目、录音转文字工具推荐:云端、本地软件、代做,三条路线手把手走一遍。