实战工具:用 ffmpeg-skill 在本地给编码 Agent 装上视频编辑器

给编码 Agent 交代一段视频剪辑,常见别扭并不在「它知不知道 FFmpeg」,而在执行过程里的猜测:帧率按文件名估、容器里塞不进所选编码、本来只需流复制却整段重编码,以及报告「已经完成」时并没有打开写出来的文件。另外一类工具则把剪辑放到云端,还要先准备密钥。本地已经有 FFmpeg 时,真正缺的往往是一套带类型参数、先测量再动手、做完再核对的固定流程。

ffmpeg-skill 是 kajisho5 开源的 Agent Skill,用来给 Claude Code、Cursor、Codex 以及任何能读 SKILL.md 的宿主,在本地接上一组由 FFmpeg / ffprobe 执行的视频编辑工具。许可证为 MIT (Copyright © 2026 kajisho5)。官方说明里写得很清楚:No cloud, no API keys;工具脚本只依赖 Python 标准库。需要同时分清另一条边界:本机实际调用的 FFmpeg 是 Debian 提供的 7.1.5-0+deb13u1 ,构建配置含 --enable-gpl 和 libx264,doctor 把它的构建许可证记为 GPL-2.0-or-later。ffmpeg-skill 是 MIT,FFmpeg 本体不是。

这个仓库并不是今天才出现的。GitHub 记录它创建于 2026-09-03T14:33:38.000Z,合 2026-09-03 22:33:38 Asia/Shanghai。查询日凌晨刚发布正式版 v3.15.1 。不要把「2026-09 创建的项目」和「近日才发布的 3.15.1」混为一谈。查询当下 main 恰好停在同一提交,本文仍按 Git 标签和 npm 正式版钉死,不跟踪 main 的后续改动。

相关入口(查询日:2026-11-20,Asia/Shanghai):

  • 仓库:kajisho5/ffmpeg-skill(仓库页 HTML 于 2026-11-20 09:36:09--09:36:12 Asia/Shanghai 返回 8,373 stars、776 forks,许可证 MIT,未归档。仓库创建于 2026-09-03T14:33:38.000Z,合 2026-09-03 22:33:38 Asia/Shanghai。同日 GitHub API 的仓库接口返回 403 限流,星标与创建时间以 HTML 为准。查询时官方 GitHub Trending · This week 将该仓库列在第 13,页面显示 2,998 stars this week;周榜页面于 2026-11-20 09:36:40--09:36:43 Asia/Shanghai 核对)
  • 官网:kajisho5.github.io/ffmpeg-skill
  • npm 包:ffmpeg-skill(本次实测 3.15.1 ,registry 记录发布于 2026-11-19T17:47:42.802Z,合 2026-11-20 01:47:42 Asia/Shanghai;license 为 MIT,gitHead 为 364f2d5210870987dacddfea887787038a6f54ac)
  • 正式版:v3.15.1(GitHub Release 发布于 2026-11-19T17:41:17Z,合 2026-11-20 01:41:17 Asia/Shanghai;tag 指向提交 364f2d5210870987dacddfea887787038a6f54ac)
  • 许可证:MIT License
  • README:README.md @ v3.15.1

本文只记录本地 Linux x86_64 上,按 Git 标签 v3.15.1 对一条核心剪辑链路的有边界实测:用 FFmpeg 测试源生成 8 秒短片,再依次跑 probe.py、cut.py --accurate、fit.py 的 9:16 裁切、export.py --preset reels 和 check.py --platform reels。第一次检查因响度未达标退出码为 1,随后按工具自己给出的修复命令跑了 loudness.py,再检查时退出码为 0。没有下载语音模型,没有启动 MCP 守护进程,也没有把技能安装进用户主目录下的全局 skills 目录。

一、原理与流程

官方 README 把这个项目写成一套给 Agent 用的本地 FFmpeg 引擎:先用 probe.py 读取真实文件的时长、帧率、分辨率和音频布局,再用带类型参数的脚本做剪辑,最后检查写出的文件,而不是相信一段自己拼出来的 FFmpeg 命令行。调用方不能传入原始 filter_complex 或任意 -vf 字符串。每个工具的输入模式由脚本自己的 argparse 在运行时派生,官方称之为 SPEC(Self-Producing Execution Contract);contract --json 是这份合约的机读入口,MCP 工具列表也从这里来。默认 MCP 的 tools/list 只公布核心 12 个工具,以免撑爆客户端上下文,42 个工具仍可按名字调用。

它做的是「手」这一侧:裁切、测量、导出,并给出结构化 JSON。它不决定该不该留下某一段、字幕文案写什么、成片能不能过审。官方也写明:用户提供的字幕文本会按原样烧录,工具不会为了贴合画面去改写。

可以把官方推荐的作业顺序看成四步:探测真实文件;能流复制时就不重编码;按目标平台检查;再看写出的结果。本次实测覆盖的是其中可本地立刻验证的一段:钉死 v3.15.1,先跑 doctor 和精简后的 contract --json,再用自生成测试片走 probe → cut → fit → export → check,并在检查失败后补做官方提示的响度校正。语音转写、字幕烧录、工程级 render.py 和长跑 MCP 服务都不在这次范围内。

二、安装配置

环境:Linux x86_64,Python 3.13.5,Node v24.22.1。本机 /usr/bin/ffmpeg 与 ffprobe 均为 7.1.5-0+deb13u1,满足官方要求的 FFmpeg 6.1+ 与 Python 3.10+。没有 Docker,也没有安装 faster-whisper 或其他语音引擎。--hw 在这份项目里指向 Apple Silicon 上的 VideoToolbox,本机 doctor --json 里 hw.platform_ok 为 false,因此没有尝试 GPU 编码。

官方给宿主的安装口令是 npx ffmpeg-skill,默认写入 ~/.claude/skills/ffmpeg-skill;--cursor、--codex、--all 和 setup 会落到其他全局技能目录,或尝试用系统包管理器补装 FFmpeg。为了不改这台机器的全局技能目录,本次按标签检出源码,直接调用 scripts/ 里的 Python 工具:

bash 复制代码
git clone --depth 1 --branch v3.15.1 https://github.com/kajisho5/ffmpeg-skill.git
cd ffmpeg-skill
python3 scripts/_contract.py doctor
python3 scripts/_contract.py doctor --json
python3 scripts/_contract.py --json --tool probe --tool cut --tool fit --tool export --tool check

实际检出的提交是 364f2d5210870987dacddfea887787038a6f54ac,package.json 的 version 为 3.15.1,与 Release 和 npm latest 一致。scripts/ 下不以 _ 开头的工具脚本正好 42 个。

doctor 人可读输出耗时 1.825 秒,退出码 0,摘要如下:

text 复制代码
ffmpeg-skill 3.15.1
python 3.13.5; ffmpeg 7.1.5-0+deb13u1; ffprobe 7.1.5-0+deb13u1
FFmpeg build license GPL-2.0-or-later
ok: 86 capabilities available, 0 required missing, 2 optional missing
missing required: none
missing optional: external:parakeet, external:whisper

doctor --json 耗时 1.862 秒,退出码 0,ok 为 true,42 个工具的 usable 均为 yes。官方特别提醒:doctor 的总体 ok 和单个工具的 usable 不是一回事------缺一个被某个工具依赖的滤镜,总体 ok 就会变成 false,但多数工具仍可能能跑。这次是两类信号都通过。缺少的两项是可选语音引擎,所以后面没有跑 --transcribe。

stderr 里还有一条安全提示:doctor 在 2026-10-22 对照 FFmpeg 安全页 检查时,认为 7.1.5-0+deb13u1 早于上游修复 CVE-2026-8461(MagicYUV 解码器堆溢出,CVSS 8.8)的首个发行版 8.0.3。它同时写明,发行版包可能已经单独打过补丁,因而不能据此断定本机构建一定脆弱。本文只原样记录这条提示,没有对这条 CVE 做额外验证。

精简后的 contract --json 耗时 2.023 秒,退出码 0。帮助文本写明完整合约大约 950 KB,所以这里只用 --tool 取出 probe、cut、fit、export、check 五份说明。合约版本是 2.0,技能版本仍是 3.15.1。cut 的验证策略写的是:结果必须再经 probe 核对;画面内容本身列在未验证项里。

另外用官方安装器做了一次限定目录的演示,没有写到主目录:

bash 复制代码
npx -y ffmpeg-skill@3.15.1 --help
npx -y ffmpeg-skill@3.15.1 --dir /workspace/csdn-ffmpeg-skill/runtime-skills

--help 耗时 0.726 秒,退出码 0。--dir 耗时 0.447 秒,退出码 0,工作区里出现 runtime-skills/ffmpeg-skill/,其中 package.json 同样是 3.15.1。安装前后 ~/.claude/skills、~/.cursor/skills、~/.agents/skills 和 ~/.codex/skills 都不存在。npx -y ffmpeg-skill@3.15.1 mcp --help 也会退出 0,但输出和安装器 --help 完全相同------安装器在分派 mcp 子命令之前就处理了全局 --help。MCP 服务器源码 mcp/server.py 存在,注释写明它是 stdio JSON-RPC 传输;这次没有把它当作守护进程启动。

三、完整代码与实跑输出

测试片用 FFmpeg 自带的 testsrc2 和 sine 生成,片长 8 秒,画面正中烧录「本地测试片」,没有下载任何成片。字体是本机的 Noto Sans CJK。

bash 复制代码
ffmpeg -y \
  -f lavfi -i testsrc2=size=1280x720:rate=30:duration=8 \
  -f lavfi -i sine=frequency=440:sample_rate=48000:duration=8 \
  -vf "drawtext=fontfile=/home/box/.fonts/NotoSansCJK-Regular.ttc:textfile=/workspace/csdn-ffmpeg-skill/smoke/drawtext.txt:fontsize=72:fontcolor=white:x=(w-text_w)/2:y=(h-text_h)/2:box=1:boxcolor=black@0.55:boxborderw=16" \
  -c:v libx264 -preset veryfast -pix_fmt yuv420p -r 30 \
  -c:a aac -b:a 128k -ar 48000 -ac 2 \
  -movflags +faststart -shortest \
  /workspace/csdn-ffmpeg-skill/smoke/source.mp4

生成耗时 0.730 秒,退出码 0,文件 2,946,451 字节。ffprobe 看到的是 8.000 秒、1280×720、30 fps、H.264、yuv420p,音频为 AAC、2 声道、48 kHz。抽帧后可以清楚读到「本地测试片」。

随后在 v3.15.1 的检出目录里调用 scripts/ 下的工具。工作目录是仓库根,输入输出使用工作区绝对路径。终端示意图里写成 smoke/...,只是为了方便阅读。

bash 复制代码
python3 scripts/probe.py /workspace/csdn-ffmpeg-skill/smoke/source.mp4 --compact
python3 scripts/cut.py /workspace/csdn-ffmpeg-skill/smoke/source.mp4 --start 1 --end 5 --accurate -o /workspace/csdn-ffmpeg-skill/smoke/cut.mp4 --json
python3 scripts/fit.py /workspace/csdn-ffmpeg-skill/smoke/cut.mp4 --aspect 9:16 --fit crop --width 1080 -o /workspace/csdn-ffmpeg-skill/smoke/fit-9x16.mp4 --json
python3 scripts/export.py /workspace/csdn-ffmpeg-skill/smoke/fit-9x16.mp4 --preset reels -o /workspace/csdn-ffmpeg-skill/smoke/export-reels.mp4 --json
python3 scripts/check.py /workspace/csdn-ffmpeg-skill/smoke/export-reels.mp4 --platform reels --json

probe.py --compact 耗时 0.181 秒,退出码 0,一行就能读完源片:

text 复制代码
.../smoke/source.mp4: 8.000s | 1280x720 @ 30.0fps h264 yuv420p | audio aac 2ch 48000Hz

cut.py 使用 --accurate,要求按帧重编码,而不是默认的流复制(流复制会对齐到关键帧)。耗时 1.549 秒,退出码 0。JSON 里 status 为 completed,verified 为 true,mode 为 accurate,precision 为 frame,requested_start / requested_end 为 1.0 / 5.0,输出时长正好 4.000 秒,duration_delta_seconds 为 0.0,分辨率仍是 1280×720,30 fps,120 帧。stderr 也写了同样的结论:wrote .../cut.mp4 (4.000s, expected ~4.000s, re-encoded, frame precision)。画面内容本身仍列在 unverified 里,工具没有声称「看起来是对的」。

fit.py --aspect 9:16 --fit crop --width 1080 耗时 3.131 秒,退出码 0,verified 为 true。输出是 1080×1920,左右各裁掉 438 像素。容器时长变成 4.01 秒:视频流仍是 4.0 秒、120 帧,音频流是 4.01 秒。这是重编码后音视频时长的微小偏差,不是又一次裁切。因为测试源是运动彩条而不是人物,工具给出一条建议性警告 crop_content_off_centre:按亮度运动代理,约 58% 的采样落在被裁掉的 68% 宽度里,建议 --crop-x 0.34,或改用 --fit pad / --fit blur 以免裁掉内容。警告不改变退出码,也不是主体检测。

export.py --preset reels 耗时 2.485 秒,退出码 0,画面已是 1080×1920、30 fps、H.264。但 JSON 里 verified 为 false:测到的响度是 -21.85 LUFS / -20.62 dBTP ,达不到 Reels 预设的 -14 LUFS / -1 dBTP 。工具给出的下一步是对这个文件跑 loudness.py -I -14 --tp -1,或在导出时加 --normalize。

check.py --platform reels 把这件事写成了正式检查结果,耗时 0.351 秒,退出码 1 ,ok 为 false,failed 为 1,warnings 为 1。分项里,时长 4.01 秒、画面 9:16、1080×1920、30 fps、恒定帧率、H.264、yuv420p、bt709、AAC 2ch 48 kHz 和文件大小都是 PASS;loudness 为 FAIL,显示 -21.9 LUFS,期望 -14 ± 2 LUFS;字幕一项是 WARN(没有带语言标签的字幕轨)。也就是说,导出命令自己成功了,平台检查并没有把「文件已经写出来」当成交付通过。

按检查结果里的修复命令补跑:

bash 复制代码
python3 scripts/loudness.py /workspace/csdn-ffmpeg-skill/smoke/export-reels.mp4 -I -14 --tp -1 -o /workspace/csdn-ffmpeg-skill/smoke/export-reels-loudnorm.mp4 --json
python3 scripts/check.py /workspace/csdn-ffmpeg-skill/smoke/export-reels-loudnorm.mp4 --platform reels --json

loudness.py 耗时 1.251 秒,退出码 0,verified 为 true。它先测到 -21.9 LUFS / -20.6 dBTP,再把音频归一化到目标;视频走流复制。写完后再次测量,结果是 -14.02 LUFS / -12.61 dBTP ,时长仍是 4.01 秒,分辨率仍是 1080×1920。第二次 check.py 耗时 0.369 秒,退出码 0,ok 为 true,failed 为 0,warnings 仍为 1(还是无字幕的 WARN)。响度显示 -14.0 LUFS,为 PASS;真峰值 -12.6 dBTP,低于 -1 dBTP 上限,为 PASS。这份 JSON 里 verified 字段是 false,且 verification 为空;对 check.py 来说,更合适的判据是文档写明的分项结果、ok 和退出码,不要把它理解成另一次 verified=true 的剪辑工具输出。

第二次检查的分项可以概括成:时长 4.01 秒(上限 90 秒)、9:16、1080×1920、30 fps、H.264、yuv420p、bt709、AAC 立体声 48 kHz、1.3 MB,均已通过;缺字幕仍是警告,不是失败。

四、适用与限制

这次实测说明,ffmpeg-skill 适合已经装好 FFmpeg 6.1+ 和 Python 3.10+、希望让编码 Agent 走「先探测、再剪辑、再核对」而不是手写滤镜图的本地工作。42 个工具覆盖裁切、拼接、画幅、字幕、响度、平台导出和检查等;本次只实跑了其中与这条交付链路直接相关的几个,外加作为修复步骤的 loudness.py。它不需要云端账户,也不需要模型密钥。

限制也同样具体:

  • 许可要分开看。技能仓库是 MIT;本机 FFmpeg 是带 --enable-gpl 的 GPL-2.0-or-later 构建。发布或分发衍生视频工具时,不能把整条链路都写成 MIT。
  • 可选语音引擎这次是缺的。doctor 列出 external:parakeet 和 external:whisper 为 missing optional。没有安装 faster-whisper,也没有下载模型,因此没有跑 --transcribe,不能把「可加字幕」写成这次已经验证过的能力。
  • check.py 会按平台规格失败。本次第一次导出在命令层面是成功的,但响度未达标,退出码为 1。这是工具按设计在工作,不应当改写成「导出即通过」。
  • 无字幕会留下 WARN。官方把它视为可选但值得做的可访问性项;本次没有烧录或封装字幕。
  • --hw 不是通用 GPU 编码开关。本机即使列出了 16 个 GPU 相关编码器,项目文档和 doctor 也只把 --hw 落到 Apple Silicon 的 VideoToolbox。
  • 完整 MCP 服务没有作为守护进程启动。只确认了安装器文档中的 npx ffmpeg-skill mcp 入口和源码里的 stdio 服务器文件;mcp --help 会被安装器的全局帮助拦截。
  • doctor 的 CVE 提示只说明上游版本对照结果,不能单独当成「这台 Debian 包一定有洞」或「一定没洞」的结论。
  • 测试片是合成彩条加正弦波,不是真实访谈或成片。fit.py 的构图警告在这种画面上会出现,不能推广成对真实主体的检测结论。
  • 默认安装会写入用户主目录下的技能文件夹。若只想试用脚本,应检出指定标签,或把 npx 的 --dir 指到项目目录。

五、小结

ffmpeg-skill v3.15.1 是一套给编码 Agent 用的本地视频编辑技能:MIT 许可,不依赖云端和 API Key,用本机 FFmpeg 完成探测、剪辑和核对。仓库创建于 2026 年 9 月,正式版 3.15.1 在查询日凌晨发布,二者不是同一件事。

在 Linux 上按标签检出后,doctor 确认 86 项能力齐备、42 个工具可用,缺的是两个可选语音引擎。对自生成的 8 秒测试片,probe.py 读到 1280×720 的 8.000 秒源;cut.py --accurate 得到精确的 4.000 秒;fit.py 输出 1080×1920 的 9:16 画面;export.py --preset reels 写出平台尺寸后,check.py 因 -21.9 LUFS 失败。按官方提示跑完 loudness.py,响度回到 -14.0 LUFS,第二次检查退出码为 0,仍保留无字幕警告。

它能减少「命令跑完了就算剪好了」的误报,但不会替你决定剪哪里,也不会在没有语音引擎时凭空生成字幕。本机 FFmpeg 的 GPL 构建许可证,需要和技能仓库的 MIT 分开写清。

相关推荐
JonaHu1 天前
博客转视频总返工?用章节清单、样片和 FFmpeg 搭一条可控流水线
ffmpeg·ai视频·内容创作·acedatacloud
StarsGreen6 天前
ffmpeg中常用结构体以及函数简介以及版本变化情况
ffmpeg
大飞哥软件自习室7 天前
视频批量截图并自动拼图是怎么做的:从四步向导、三种截帧模式到等距抽样与日志兜底的实现拆解,附 FFmpeg 调用与线程模型说明
ffmpeg·音视频·批量截图
todoitbo8 天前
把 K-Lite「什么都能播」搬上鸿蒙 PC:影匣播放器的 FFmpeg + libass 原生移植实录
华为·ffmpeg·harmonyos·鸿蒙
FlightYe9 天前
音视频修炼之容器与协议(四):RTSP详解
android·linux·ffmpeg·音视频·dash
架构师伯子明10 天前
ffmpeg学习4:opencv在音视频领域常用指令
opencv·学习·ffmpeg
Android系统攻城狮11 天前
Linux FFmpeg深度解析之avio_open调用流程与实战(三十八)
linux·运维·服务器·ffmpeg·音视频进阶·ffmpeg音视频
Android系统攻城狮12 天前
Linux FFmpeg深度解析之av_guess_format调用流程与实战(三十六)
linux·运维·服务器·ffmpeg·ffmpeg音视频进阶
Android系统攻城狮13 天前
Linux FFmpeg深度解析之av_write_frame调用流程与实战(三十三)
linux·运维·服务器·ffmpeg·音视频进阶·ffmpeg音视频