ffmpeg-skill 快速入门:让编码智能体自己剪视频并自查结果

给 Claude Code、Cursor、Codex 等宿主用的视频剪辑 Agent Skill:42 个类型化工具 + MCP 服务 + 机器可读契约;媒体处理在本机 FFmpeg 完成、工具自身无 API key(宿主模型调用另计),执行后会重新探测输出交给 agent 自查。

📊 评分明细

📦 打包完整度
2 2 / 2.5
🎯 实用性
2 2 / 2.5
📖 文档清晰度
1.6 1.6 / 2
👥 社区影响力
1.2 1.2 / 1.5
🔗 集成度
1.2 1.2 / 1.5

🎯 适用场景

视频处理FFmpegAgent Skills本地运行

ffmpeg-skill 快速入门:让编码智能体自己剪视频并自查结果

ffmpeg-skill 是一个 Agent Skill:它不替代 FFmpeg,而是把 FFmpeg 操作包成 42 个带类型参数的工具,教宿主里的智能体按「探测 → 无损剪辑 → 检查 → 复验」的固定流程干活。作者的定位句很直接——Give your coding agent a video editor。

它和「让模型自由拼 FFmpeg 命令」的差别在于把可测项写进结构化结果:每个工具跑完会重新探测输出文件的时长、帧率、分辨率与音频,把测量结果写进 JSON,测不到的项写进 unverified。这里要分清四个轴——执行状态(status: completed、退出码 0)、可测项验证(verified 覆盖哪些属性)、未测量或主观项(unverified)、视觉质量(谁看了联系表)。README 明确写「It cannot tell you whether the result looks or sounds right」:进程跑完不等于画面合格,画面要人(或多模态宿主)看。

核验日期:2026-11-20。 本文基于官方文档和公开资料整理,AI辅助生成,MagicNetWorld 尚未完成独立实测。 我们读了 README 全文(约 770 行)、npm 包元数据、GitHub REST 元数据与发布信息;没有安装这个技能、没有在 Claude Code / Cursor / Codex 里触发它、没有跑过任何一个工具脚本、也没有用真实素材验证过任何剪辑结果。README 里引用的评测数字均为作者自述。

这是什么?适合谁?

  • 适合:已经在 Claude Code、Cursor、Codex 或任意 MCP 客户端里工作,想让智能体直接处理手头视频文件的人。
  • 适合:希望媒体处理留在本机的人。官方写明这批工具 No cloud · No API keys,42 个工具只依赖 Python 标准库,FFmpeg 在你自己的机器上执行。注意这个承诺覆盖的是技能自身:宿主(Claude Code / Cursor / Codex 等)是独立一层,可能把提示词、文件路径与命令日志、字幕文本,乃至它自己读的联系表图像发给它的模型 API——素材是否出网取决于宿主与模型配置,不是技能能保证的。
  • 适合:被「agent 说剪好了,其实没剪」坑过的人。它的做法是写出文件后重新探测并核对可测属性(时长、尺寸、帧率、音频),把这些写进报告;但画面对不对它自己判断不了——completed + verified: true 只说明测过的项对得上,Look: 一节才是给人看画面留的位置。
  • 适合:要批量做竖版短视频、字幕、响度归一、平台规格检查的流水线场景。
  • 不适合:想要文生视频、图生视频这类生成模型的人。它不提供生成模型,做的是对已有素材的加工;graphics / background / sequence 能在图形、背景与拼接层面做合成,但不会由提示词生成新画面。
  • 不适合:想自动找人脸、自动决定裁哪里的人。README 反复强调:仓库里没有任何人脸、主体或「精彩片段」检测,look.py 只负责生成一张联系表 PNG,看的人是不带眼睛的脚本时,裁切锚点得你自己给。
  • 重要边界:仓库 2026-09-03 才创建,提交集中在单一账号(kajisho5 351 次),另有自动化账号(github-actions[bot] 209 次、claude[bot] 53 次)与 1 个匿名贡献者,属于「热但嫩」——建仓约 11 周的数据只说明关注度,不说明生态成熟,是否适合生产要自己压测。

前置准备

  1. FFmpeg 6.1 或更高。3.0.0 起明确移除 FFmpeg 5.x:版本低于 6.1 会被工具直接拒绝(kind: missing_tool,error.reason: ffmpeg_unsupported)。git 快照那种读不出版本号的构建不会被拒。
  2. Python 3.10+,且只需要标准库。3.0.0 同时移除了 Python 3.9。
  3. Node 16+,只有走 npx 安装器时才需要。
  4. 一份能合法使用的素材:官方评测用的是 GoPro、DJI、iPhone(含 Dolby Vision)、安卓录屏、HDR10、24p 与 Tears of Steel 这类公开测试素材。
  5. 知道你机器的 ffmpeg 是哪个构建。官方明确点名:macOS 上 brew install ffmpeg 的普通 formula 缺少 subtitles、drawtext、zscale 三个滤镜,字幕与 HDR 转 SDR 会直接不可用。
  6. 本地语音引擎(可选):只有 caption.py --transcribe 这类「从语音生成字幕」的功能需要,支持 parakeet / whisper 引擎,首次运行可能下载模型权重(这一步会联网)。语音识别在本机进程里跑,音频不交给厂商;但宿主模型是否收到字幕文本或路径,仍由宿主决定。

安装:四条路,选一条

路径 A:一条命令装完并自检

npx ffmpeg-skill setup

官方说明这条命令做三件事:给它在这台机器上找到的所有宿主装技能(~/.claude、~/.cursor、~/.codex 或 ~/.agents,一个都没找到时装给 Claude Code);如果 ffmpeg 跑不起来就装 FFmpeg(打印出 brew install ffmpeg-full、winget install --id Gyan.FFmpeg -e 或 sudo apt-get install -y ffmpeg 之后才执行,--no-ffmpeg 则完全不碰包管理器);最后跑 doctor 并返回它的退出码。三种包管理器都没有的机器上,它会装技能、告诉你 FFmpeg 仍缺失、并以非零退出。

路径 B:分步装给指定宿主

npx ffmpeg-skill              # Claude Code  → ~/.claude/skills/ffmpeg-skill
npx ffmpeg-skill --cursor     # Cursor       → ~/.cursor/skills/ffmpeg-skill
npx ffmpeg-skill --codex      # Codex        → ~/.agents/skills/ffmpeg-skill
npx ffmpeg-skill --all        # 三个都装
npx ffmpeg-skill --project    # 只装到当前项目 ./.claude/skills/ffmpeg-skill

装完想更新要重跑一次 npx ffmpeg-skill——README 明说复制出来的副本不会自动更新。卸载用 --uninstall。

路径 C:作为宿主插件安装

Claude Code 2.1.275 或更高:

/plugin install ffmpeg-skill --marketplace kajisho5/ffmpeg-skill

2.1.69 到 2.1.274 要分两步:先 claude plugin marketplace add kajisho5/ffmpeg-skill --sparse .claude-plugin,再 claude plugin install ffmpeg-skill@ffmpeg-skill。插件路径不需要 Node,更新走 claude plugin update。

Codex CLI 与 Gemini CLI 也在官方支持列表里:

codex plugin marketplace add kajisho5/ffmpeg-skill --sparse .claude-plugin
codex plugin add ffmpeg-skill@ffmpeg-skill
gemini extensions install https://github.com/kajisho5/ffmpeg-skill

注意 Gemini 那条会克隆整个默认分支(约 28 MB,含测试、评测与演示素材),是唯一「装得比技能本身大」的路径。

路径 D:只接 MCP,不装技能

npx -y ffmpeg-skill mcp

MCP 注册表里的条目是 io.github.kajisho5/ffmpeg-skill。客户端配置形如:

{"mcpServers": {"ffmpeg-skill": {"command": "python3", "args": ["/Users/you/.claude/skills/ffmpeg-skill/mcp/server.py"]}}}

Windows 上如果客户端报 MCP server 启动失败,把 command 从 python3 换成 python 或 where python 给出的完整路径——README 专门写了这条。

装完必做:读 doctor,而不是读「ok」

npx ffmpeg-skill doctor
npx ffmpeg-skill doctor --json

doctor 读 ffmpeg -encoders / -decoders / -filters / -bsfs,把契约里声明的每个能力解析成本机三态:available、missing、unknown。退出码 0 表示必需项齐备,1 表示缺必需项,2 表示没证明缺、但有必需项状态未知。它还会报告字体(按语言区分 ja / zh / ko / ar / he / hi / bn / ta / th / lo / ru / el / latin 各有 available/missing/unknown)、GPU 编码器是否编进了这个 ffmpeg 构建,以及一张内置的 FFmpeg 高危 CVE 对照表。

最关键的一点,README 自己点出来了:doctor 的整体 ok 与单个工具的 usable 是两个信号。一个缺 subtitles 滤镜的构建会让 ok 变 false,但大多数工具其实还能跑;所以排障要看 doctor --json 里的 tools 字段,逐个工具问「我这台机器能不能跑 caption」。

第一个完整任务:把一段采访剪成竖版

目标:输入一个横版视频,输出一条 60 秒、9:16、响度达标的竖版成片,并且能用数字证明它确实是这样。字幕不在首任务里——官方 Quick start 的 Reel 链本身不产出字幕,加字幕要另备一份 cues/SRT,放到后面的可选任务。

  1. 先探测。让智能体跑 probe.py,拿到真实时长、帧率(含可变帧率检测)、分辨率、色彩与音频流。不要从文件名猜。
  2. 再问它要什么。比如:「取 0:45–1:20 与 5:00–5:25,做成 60 秒的 Reel」。
  3. 看它怎么调用。README 给的标准链路是:probe.py → cut.py --segments 0:45-1:20,5:00-5:25 --accurate → fit.py --aspect 9:16 --fit crop → export.py --preset reels → check.py --platform reels → look.py。
  4. 要它报数字。合格的报告会长这样:final.mp4: 60.00 s, 1080×1920, 30 fps, AAC stereo,并附上它看过的联系表图片。
  5. 自己抽验。用播放器打开成片,确认裁切没有把主体切掉——这正是仓库声明「不自动识别人脸/主体」的地方,锚点是你或智能体看联系表后给的。

也可以直接用交付模板一条命令走完:

S=~/.claude/skills/ffmpeg-skill/scripts
python3 $S/render.py talk.mp4 --template tiktok

--template 会填一份随包模板:9:16 裁切、−14 LUFS、tiktok 导出预设,并对写出的文件跑一次 check.py --platform tiktok。模板同时带了逐词弹出字幕(避开 TikTok 自己的说明栏与点赞列)的位置,但那需要一个 cues 文件才会生效,见下一节。官方随包模板覆盖 tiktok、reels、shorts、youtube-shorts、youtube、x、linkedin、facebook、podcast、audiogram;--template all 会从同一次剪辑渲出七个视频目的地,并写一张 <name>_pack.md 汇总表。

成功判据

  • probe.py 报的输入参数与你的素材一致(时长、分辨率、帧率、音频流数量)。
  • 输出文件被重新探测过,时长与你要求的差在工具的容差内,帧尺寸正好是目标尺寸。
  • check.py --platform <目标> 通过,或明确告诉你哪几行是 WARN、哪几行是 FAIL 及修法。
  • 画面变化时它跑了 look.py 并看了那张 PNG;纯音频任务则应报告 Look: not needed。
  • 报告只有三种标签:成功 Done:、失败 Failed:、部分完成 Done: 加 Notes: 说明差在哪——没有第四种模糊说法。
  • 读报告时先看 status 与 verified,再看 unverified 里列了哪些没测的项,最后看 Look: 有没有交代像素是否被看过;没看过就必须写 pixels were not inspected。

可选:再给成片加字幕

字幕是另一条配置,不属于上面那条 60 秒链路:官方 Quick start 的 Reel 链不产出字幕,模板里的字幕位也不会自己长出文本。字幕源有两条路:让 caption.py 用本机已装的语音引擎把音轨转成 SRT(--transcribe;没装引擎时它只打印安装提示,技能自身代码不下载、音频不出机器,引擎可能自行下载模型权重),或者自己准备一份 SRT。下面的顺序是先剪再转写,并把 SRT 落到显式路径,后面的烧字与模板两条路才读得到同一个文件:

# 1) 在剪后成片上转写,SRT 显式存成 cut.srt(本机需已装 parakeet-mlx / parakeet.cpp / whisper-cli / faster-whisper / whisper 之一)
python3 $S/caption.py cut.mp4 --transcribe --write-srt cut.srt
#    → 一条命令同时产出 cut.srt 与烧字成片 cut_captioned.mp4
# 2) 想再烧一遍这份 SRT 时,另给一条输出名,否则会与第 1 条的默认成片撞名而被拒
python3 $S/caption.py cut.mp4 --srt cut.srt -o cut_subbed.mp4
# 3) 或者让模板链路自己吃这份字幕文件(模板输出 cut_tiktok.mp4)
python3 $S/render.py cut.mp4 --template tiktok --srt cut.srt

三点提醒:① caption.py 的字幕输入只有三类——--srt / --ass / --text(--text 是纯文本 cues,转成 SRT),转写用 --transcribe,另存路径用 --write-srt / --write-ass;它没有 --cues 这个参数,--cues 是 render.py 的输入选项。--write-srt 只决定那份 SRT 存到哪,不改变「同时写 SRT 与烧字成片」这件事;不给它时 SRT 默认与成片同名,落在 <stem>_captioned.srt(cut.mp4 就是 cut_captioned.srt,不是 cut.srt)。② 时间轴跟着被转写的那条视频走:拿原片转写、再把 SRT 套到剪后成片上,时间会整体错位(原片被剪掉的开头仍留在字幕里),所以先剪再转写。③ 手写 cues 文本的格式以 npx ffmpeg-skill contract --json --tool caption(--text)或 --tool render(--cues)的 input_schema 为准,本文不提供样例内容;逐词弹出、避开说明栏这类行为来自模板参数,不是「自动识别字幕」。本节的预期输出同样没有在本文运行验证。

初级用法(三条)

1. 用 --dry-run 先看命令

写文件的工具普遍支持 --dry-run:打印它将要执行的 ffmpeg 命令行,不写输出文件。支持情况要以契约和 references/scripts.md 为准,因为例外不少:render.py 与 verify.py 直接拒绝 --plan;verify.py 接受 --dry-run 但完全忽略它(按 dry_run: false 执行);测量类工具(probe、check、silence、loudness)本来只读,也就无所谓 dry-run;可选的 ASR 与编排层的 dry-run 另有单独例外。dry-run 的意思是「不写输出」,不是隔离沙箱。

2. 用 --json 拿结构化结果

python3 $S/probe.py input.mp4 --compact
python3 $S/export.py input.mp4 --preset reels --json

--json 返回 status、output、commands、输出文件的 probe、output_identity(写出文件的 size 与 mtime),以及工具自己的字段(比如 cut.py 的 precision)。要给上层程序消费时用 --json-brief,字节数约为三分之一。

3. 先 doctor,再干活

doctor 的价值在于把「跑一半才失败」提前成「开跑前就知道」。特别是字幕(subtitles)、drawtext、zscale 三者,在 macOS 普通 brew 构建里就是缺的。

高级玩法(三条)

1. 用「计划」把长链条固定下来

python3 $S/cut.py input.mp4 --start 0:10 --end 0:40 --plan cut.json --dry-run
python3 $S/render.py cut.json

--plan FILE 会把这次调用的参数写成一份计划 JSON(不是渲染,也不是只打印),之后由 render.py 执行;render.py 与 verify.py 自己拒绝 --plan。计划里记录每个输入的 size 与 sha256_head_tail,执行时若检测到所记录的指纹变化就拒绝(plan_inputs_changed)——注意这是采样指纹,不是全文件完整性校验:文件中间被改而大小与头尾都没变时不会发现;没有指纹的输入会另列为 unbound。它让「先审后跑」可行,但不等于内容完整性证明。

2. 用 render.py 的 project.json 承载整条剪辑

render.py 从一份声明式 project.json 渲染整条剪辑:片段、转场、字幕、叠加(含社交贴纸/开头钩子/梗图、画中画或抠像视频层)、音乐与分轨电平、响度、导出、章节标记、检查。它支持 --init 初始化、--stop-after 只跑到某阶段、--cache DIR 复用没变的阶段。--export-timeline edit.fcpxml|.edl|.otio 还能把剪辑导出成 Final Cut、DaVinci Resolve 或 Premiere 的时间线,而不是渲染成片。

3. 用 MCP 的瘦身清单控制上下文成本

MCP 默认只广告 12 个核心工具(render、look、caption、export、check、fit、cut、audio、loudness、graphics、silence、probe),全部 42 个用 FFMPEG_SKILL_MCP_FULL=1 打开。README 给了作者自己测量的 schema 体积:默认 12 个约 71.0 kB(≈1.8 万 token),全部 42 个约 190.9 kB(≈4.8 万 token),自定义五工具清单约 24.0 kB(≈6000 token)。这些数字不是本站测量的,你的客户端的实际 token 开销也会随实现不同。

{"mcpServers": {"ffmpeg-skill": {"command": "python3", "args": [".../mcp/server.py"], "env": {"FFMPEG_SKILL_MCP_TOOLS": "probe,cut,fit,export,check"}}}}

未列出的工具仍然可以按名字通过 tools/call 调用——瘦身的是 schema 广告,不是能力。

4. 用 batch.py 与 --jobs 做批量

batch.py 支持按步骤配方或 project 处理整个文件夹,带内容哈希缓存与 --watch;--jobs N 并发跑多个文件,上限是 min(N, cpu_count, 8),并且共用一个 --timeout 预算而不是每个文件各一份。

六个具体踩坑

1. macOS 上字幕/HDR 功能直接不可用

  • 症状:caption.py 报缺 subtitles 滤镜,color.py --to-sdr 报缺 zscale。
  • 原因:Homebrew 的普通 ffmpeg formula 不含 subtitles、drawtext、zscale。
  • 解决:装 ffmpeg-full 并让它先上 PATH(export PATH="$(brew --prefix ffmpeg-full)/bin:$PATH"),或用 brew link --overwrite --force ffmpeg-full(brew doctor 会警告)。技能本身在检测到 PATH 上是 Homebrew 的瘦身版时,会自己去找同一前缀的 ffmpeg-full,doctor --json 会给出 ffmpeg_path 与 ffmpeg_source。来源:README「Install」/「Requirements」。

2. 一小时的片子导出被超时杀掉

  • 症状:长片导出跑到一半退出,kind: timeout,退出码 124,什么都没写出来。
  • 原因:每次 ffmpeg 调用默认 --timeout 1800 秒。作者的实测样本是一次全长 1802 秒的导出被默认超时杀掉——也就是这条基准没有跑完。README 里的「约 50 分钟」与 --fast 的「约 16 分钟」不是实测完成时间,而是从 10 分钟片段(514 秒;--fast 162 秒)的速率外推到一小时的结果。
  • 解决:长片加 --timeout 0 或更大值,再用自己的素材测一次真实耗时(4 vCPU / Linux / FFmpeg 6.1.1 是作者的测试环境,不是你的)。来源:README「A one-hour recording」。

3. 以为 doctor 说 ok 就什么都能跑

  • 症状:doctor 退出码 0,结果 caption.py 还是失败。
  • 原因:ok 只表示「所有工具需要的组件都不缺」,缺一个只被个别工具用到的滤镜就会把它变 false;反过来,ok 为真也不代表每个工具在你的素材上都合适。
  • 解决:看 doctor --json 的 tools.<name>.usable 与 missing,按具体工具判断。来源:README「Capability detection」。

4. 想让 agent 自动找人脸、自动裁到主体

  • 症状:让智能体「把人物放中间」,结果裁到了画面中央的桌面。
  • 原因:仓库不做人脸/主体识别。fit.py --fit crop 默认居中裁切;cropdetect.py --motion-centre 只报告每秒的运动质心,不选裁切框。
  • 解决:跑 look.py 出联系表,由多模态宿主看 PNG 后传 --crop-x / --crop-y;没有视觉能力的调用方必须自己决定锚点。来源:README「Design principles」第 8 条与 FAQ「Does it auto-track faces」。

5. VFR 素材的无损剪切切错帧

  • 症状:手机或录屏素材按 -c copy 切出来,起止点对不上。
  • 原因:可变帧率素材用流复制切会落到错误的帧。cut.py 会先采样帧时序,判定为可变帧率或样本太短时自动切到帧精确模式。
  • 解决:不要强行关掉保护;需要严格无损就接受落点吸附到关键帧(--tolerance -1 配合 --vfr-guard off),并读 JSON 里的 nearest_keyframes 确认落点。来源:README「Gotchas」第 1 条。

6. Windows 上 python3 找不到

  • 症状:Git Bash 里照抄示例,报 command not found。
  • 原因:Windows 上 python3 只有从 Microsoft Store 装的 Python 才有;python.org 的安装暴露的是 python 或 py。
  • 解决:把示例里的 python3 换成 python;bin/install.js、doctor、contract 已经替你处理了这件事。另外官方明说整套真实素材语料还没在 Windows 上跑完(issue #143),Windows 属于「测试覆盖中」而非「已验证」。来源:README「Quick start」/「Tested on real footage」。

7. 以为 MIT 就等于整条链路都能随便分发

  • 症状:把带编码器的成品流水线打包分发,被 GPL 条款卡住。
  • 原因:仓库本身是 MIT,但它调用的 FFmpeg 构建有自己的许可:带 libx264、libx265、libvidstab 的构建适用 GPL 条款,--enable-nonfree 的构建被标为不可再分发。
  • 解决:分发前确认目标机器上的 FFmpeg 构建授权;doctor 会显示所选可执行文件的许可。来源:README「License」。

五个实用技巧

  1. 装完先跑 doctor --json,把 tools 里 unusable 的项列出来,比事后一个个撞墙快。
  2. 任何写文件的操作先用 --dry-run 看命令,尤其是带滤镜链的 color、graphics、overlay。
  3. 长片统一加 --timeout 0(或显式大值),并把 --fast 留给预览;跑之前先用自己的素材量一次真实耗时,别照抄作者的 10 分钟样本外推。
  4. 交付前固定加一次 check.py --platform <目标>;平台限制会变,官方把超限行标成 basis: guidance。
  5. 把「画面对不上」当作第一嫌疑:先 look.py 看联系表,再怀疑参数。

具体进阶路径

  1. 先跑通单文件链路:probe → cut → fit → export → check,目标是拿到一份带数字的报告。
  2. 读契约:npx ffmpeg-skill contract --json --tool cut,看单个工具的 input_schema、capabilities、verification 是怎么描述它的承诺的。
  3. 用交付模板替代手工参数:render.py --list-templates 看每个模板的帧尺寸、时长限制与安全区,再 --template 一次成型。
  4. 进 project.json:把多段剪辑、字幕、叠加与响度写进一份工程文件,用 --cache 反复试错而不重跑全流程。
  5. 接 MCP:用瘦身清单把工具数量压到 5–12 个,让客户端少付 schema 成本;需要时再按名字调未列出的工具。
  6. 读评测与限制:evals/results/ 里按版本记录的评测(含失败项)比 README 的亮点更能说明它的边界。

常见问题 FAQ

1. 它会不会把我的原片覆盖掉?

正常路径下不会。官方设计原则第 10 条是「保留原件」:工具不覆盖输入,输出默认命名为 <input>_<operation>.<ext>,并且有测试在跑完后对每个输入做哈希;目标路径与已声明的输入相同会被拒绝,要替换已有输出必须显式 --overwrite。有一个官方写明的例外:batch.py --watch 在后续 pass 里可以替换它自己在更早一轮交付、且源文件未变的输出。所以「原件安全」是设计承诺,不是覆盖所有脚本、所有模式的绝对保证,具体以 contract 为准。

2. 能不能直接传原始 ffmpeg 参数或 filter_complex?

不能。每个操作都是一个脚本,它的参数就是它的 argparse 解析器,契约与 MCP 的 inputSchema 都由这个解析器生成,CI 会在两者漂移时让构建失败。MCP 接受 argv 数组,但那仍然是该脚本自己的 CLI 参数,不是 ffmpeg 命令行,也不经过 shell。

3. 它是「agent skill」还是「MCP server」?

两者都是同一套工具的两个入口。作为 Agent Skill,宿主读 SKILL.md 拿到工作流与「请求→脚本」映射;作为 MCP server,tools/list 在启动时从契约翻译出工具表。MCP 服务本身没有自己的工具表,所以不存在两份定义漂移的问题。

4. 需要联网或 API key 吗?

技能自身不需要。官方写明 offline、No cloud、No API keys,媒体处理、测量与复验都在本机用 FFmpeg 与 Python 标准库完成。会联网的是另外几层,必须分开看:① npx 安装器与它调用的系统包管理器;② 可选本地语音引擎首次运行时下载模型权重;③ 宿主模型——Claude Code / Cursor / Codex 这类宿主为了决定怎么裁、怎么读报告,通常会把提示词、命令输出与日志、必要时还有联系表图像发给自己的模型 API,云宿主不能承诺素材或截图不出网。要在保密环境使用,得同时审宿主与模型配置、遥测开关和工具权限。

5. Windows 能用吗?

部分可用且官方自己标注未完全验证:CI 在 Windows(gyan.dev 的 FFmpeg 9.x)上跑契约与部分测试,但真实设备语料尚未在 Windows 上跑完(issue #143),作者也承认没有第二位维护者复现过 Windows 安装。商务场景建议先在隔离机器上跑一遍你要用的那几条链路。

6. 它的评测数字可信吗?

那些数字(如 100 条提示词的一轮评测、92 个验证步骤、silence 20 例 0 missed)都是作者自报,评测脚本与结果文件在 evals/、tests/bench_*.py 里可复跑,但 MagicNetWorld 没有复现。而且「100 条提示词」是那轮评测的运行规模,不是所有指标都拿到 100%——README 同时写了 routing 95%、honest 22/25、report 98/100 这类分项。README 也主动写了评测里的失败项(例如 1.17.0 的 --fit-size 在模板路径不可达),这种「自曝短板」比纯亮点更值得参考,但仍不等于第三方验证。

7. 为什么代码是 MIT,还说要小心许可?

MIT 只覆盖这个仓库的代码。技能调用的 FFmpeg 由你的系统提供,构建里若含 libx264、libx265、libvidstab 等 GPL 组件,那部分按 GPL 处理;--enable-nonfree 的构建不可再分发。

成本、权限、平台与安全限制

  • 许可:仓库 MIT;FFmpeg 构建另按自身许可(GPL / LGPL / nonfree),分发前要分别确认。
  • 成本:软件零费用、无 API key。真实成本是宿主模型调用与本机算力。时间基准要看清口径:作者用 10 分钟片段测得 514 秒(--fast 162 秒,4 vCPU / Linux / FFmpeg 6.1.1),据此外推「一小时约 50 分钟 / --fast 约 16 分钟」;而默认 1800 秒超时下,一次全长 1802 秒的导出实际是被杀掉的,并没有跑完。
  • 平台:FFmpeg 6.1+、Python 3.10+(仅标准库)、Node 16+(仅 npx 安装器)。宿主覆盖 Claude Code、Cursor、Codex、Gemini CLI 与任意 MCP 客户端。
  • 权限:工具会在你给的文件系统路径上读写文件、执行 ffmpeg/ffprobe。官方声明的是核心媒体路径不经过 shell、只执行脚本与 ffmpeg/ffprobe;但权限面不止这三个可执行文件——安装器会 spawn 系统包管理器(brew / winget / apt 之一),caption.py --transcribe 会启动本地语音引擎子进程,宿主本身还持有你的工作目录读写权与网络出口。所以「不跑 shell」是设计约束,不是安全边界,也不是沙箱;要隔离就在容器或独立账号里跑。
  • 安全:
    • 不自动改输入、拒绝覆盖已有输出(batch.py --watch 替换自己上轮交付是官方写明的例外),是它给出的最小保护,但不构成安全边界;
    • redact.py --mode delogo 只是 1 像素边界混合,不是修复式涂抹,也不负责找位置;
    • doctor 内置 FFmpeg 高危 CVE 对照表(截至核验日含 CVE-2026-8461,修复版本 8.0.3 / 8.1.2 / 9.0),但只给建议、不改退出码;发行版可能以回移植形式带修复,所以它说的是「构建版本旧于修复版本」,不是「一定存在漏洞」。
  • 稳定性承诺:3.x 期间不删除、不改名任何工具名、CLI 参数、JSON 输出键与退出码,也不把可选变必需,直到 4.0;有测试用快照钉住每个工具的参数名。官方建议钉住 tag,而不是跟 main。
  • 未实测声明:以上所有行为描述都来自 README 与包元数据,MagicNetWorld 未安装、未执行任何工具。

参考链接

  1. 仓库与 README:github.com/kajisho5/ffmpeg-skill
  2. npm 包(核验时 latest 为 3.15.1):npmjs.com/package/ffmpeg-skill
  3. 仓库元数据(stars / forks / pushed_at):api.github.com/repos/kajisho5/ffmpeg-skill
  4. 契约字段逐项说明:docs/contract.md
  5. 每个工具的参数与判据阈值:references/scripts.md
  6. 演示与前后对比(含确切命令):docs/demos.md
  7. 设计取舍(哪些看起来像 bug 其实是决定):docs/design-decisions.md
  8. Windows 语料验证进展:issue #143
  9. FFmpeg 安全公告(doctor CVE 表来源):ffmpeg.org/security.html
  10. FFmpeg 许可与分发说明:ffmpeg.org/legal.html

📊 评分与标签

核验口径:已按现行口径通过,待按新证据契约复核 · 证据状态:仅公开资料 · 核验日期:

评分说明

总分 7.9/10 · S_入选

核验日期:2026-11-20。评分依据可追溯至仓库 README 全文(约 770 行,含安装、工具表、MCP、doctor、兼容性、评测与许可各章)、docs/contract.md 与 references/scripts.md 的正文(含 --plan / --dry-run 的例外与输入指纹字段)、npm registry 的包元数据,以及 GitHub REST 元数据与贡献者列表;关键命令与版本门槛逐条对回原文。 这是资料核验判断:我们没有安装这个技能、没有在 Claude Code / Cursor / Codex / Gemini CLI 中触发它、没有运行任何工具脚本,也没有用自己的素材验证过任何剪辑或导出结果。 分数为独立的文档与工程质量评估,不沿用仓库自述的 star 热度;README 引用的评测数字(如 100 条提示词的一轮评测、92 个验证步骤)均为作者自报,本站未复现,也不把「100 条提示词」读成所有指标满分。

可观测社区指标

采集日期:2026-11-20(当日 05:36 北京时间快照)。GitHub REST 返回 stars 8,302、forks 773、open issues 53(含 PR),pushed_at 为 2026-11-19T20:28:04Z(北京时间 11-20 04:28),created_at 为 2026-09-03T14:33:38Z,未归档,默认分支 main,语言 Python,许可 MIT,homepage 指向 npm 包页。这些是会变的单日快照,随提交自然增长,正文与 JSON 统一用这一快照口径。 贡献者接口带 anon=1 返回 11 条(其中 1 条为 Anonymous,不带 anon=1 只有 10 条),提交数前三为 kajisho5 351 次、github-actions[bot] 209 次、claude[bot] 53 次,另有 dependabot[bot] 11 次与 claude 4 次。需要说清接口能证明什么:它给的是账号与计数,claude 是 User 类型账号、claude[bot] 是 Bot 类型账号,接口不证明某个 User 类型提交由真实人类完成,也不证明背后有几位维护者。最新提交时间为 2026-11-19T17:41:13Z,作者标注为 github-actions[bot](发布流水线)。 npm registry 显示包 ffmpeg-skill 创建于 2026-09-03T15:19:14Z,核验时 latest 为 3.15.1,许可 MIT,最新发布时间 2026-11-19。 判断:这是一条**「热但嫩」**的记录——建仓约 11 周即 8,302 stars,提交高度集中在单一账号,另有多个自动化账号;仓库年龄、账号结构、53 个 open issues 与「Windows 全量语料尚未跑完(issue #143)」都说明它仍处早期。本文没有同类项目的抽样分母,因此不作「增速高于同类常态」这类比较。本站不把 star 当质量分,也不因 star 高就假设生态成熟。

📦 可安装性 2.2/2.5

  • 证据:一条命令即可装完并自检——npx ffmpeg-skill setup 会为机器上找到的所有宿主安装技能、按需安装 FFmpeg(--no-ffmpeg 可禁用)、最后跑 doctor 并返回其退出码。另有按宿主分装(--cursor / --codex / --all / --project / --dir / --uninstall)、宿主插件(Claude Code 插件市场、Codex plugin、Gemini CLI extension)、MCP 注册表条目 io.github.kajisho5/ffmpeg-skill,以及无 Node 时的手工复制清单。来源:README「Install」。
  • 竞品对比 1(Remotion):Remotion 的安装单位是一个 React 工程(npx create-video@latest,官方也写 npm create video),产物是项目代码与依赖;ffmpeg-skill 的安装单位是技能目录(用户级 ~/.claude/skills,或 --project 装到项目内 .claude/skills)或一条 MCP 服务条目。两者交付形态不同:一个给你工程,一个给宿主加工具。
  • 竞品对比 2(MoviePy):MoviePy 是 Python 库,pip install moviepy 后在代码里调用剪辑、合成与特效 API;ffmpeg-skill 是宿主技能或 MCP 服务,装完由宿主按 schema 调起脚本。调用形式不同:一边是你写 Python,一边是宿主发起工具调用(前提是宿主支持技能或 MCP)。
  • 扣分:技能副本不会自动更新,必须重跑安装命令(README 明写「Copies are not updated automatically」);Gemini CLI 那条路径会克隆整个默认分支(约 28 MB);尚未进入 Claude 插件目录(官方说明因为需要 Anthropic Verified 组织身份,提交处于搁置)。

🎯 实用性 2.1/2.5

  • 证据:42 个工具覆盖分析(probe / scenes / look)、剪辑(cut / join / silence / fit / crop / insert / broll / metadata …)、音频(audio / sync / loudness)、画面(caption / overlay / graphics / color)、交付(export / check / report)与编排(render / batch / multicam / verify)。每个脚本都有 --help 与 --json;--dry-run 在写文件的工具上普遍可用,--plan 只在部分脚本上可用(render.py、verify.py 明确拒绝,verify.py 还会忽略 --dry-run),细节以 references/scripts.md 为准。失败返回非零并给原因;执行后重新探测输出,把测不到的属性写进 unverified——completed 与 verified 是两个轴,画面质量另由人看联系表。来源:README「Tools」「What does verified check」。
  • 竞品对比 1(Remotion):Remotion 用 React 组件渲染视频,路线是「用代码生成画面」,官方定位含 programmatic / interactive video。ffmpeg-skill 编辑的是已存在的素材(切、裁、字幕、响度、叠加),它有自己的 graphics / background / sequence 工具能做图形与拼接层面的合成,但不提供文生视频、图生视频这类生成模型。两者在「生成新画面」这件事上分工不同;在「处理已有素材」上本文只比两者的入口形态(一边是工程代码,一边是宿主技能/MCP 工具),不做易用性或效果优劣的排名。
  • 竞品对比 2(MoviePy):MoviePy 的公开形态是 Python 库,README 列的是 cuts、concatenations、title insertions、compositing、processing 与 custom effects 等 Python API,pip install moviepy 之后在代码里调用;ffmpeg-skill 把这些检查做进了工具(重新探测输出、check --platform 规格检查、look 生成联系表),未测项写进 unverified。本文只对比两者的公开调用形态与 ffmpeg-skill 自己的检查步骤,没有核到 MoviePy 的验证流程,因此不说谁检查得更充分,也不说谁更容易用——易用性本文没有做用户测试。
  • 扣分:不做生成式视频、不自动找人脸或主体、不自动判定「哪个片段精彩」——README 把这些边界写得很直白,也意味着宣传里容易被误读为「AI 自动剪辑」;长片重编码受默认 1800 秒超时限制,需手动放宽。

📚 文档质量 1.9/2.0

  • 证据:README 近 770 行(直连读取 123,519 字节),分安装、工具表(42 条逐项说明)、音频、面向 agent 的设计、MCP、doctor、踩坑、FAQ(十余问)、FFmpeg 兼容性、真实素材测试、安装、要求、开发与文档索引;另有 docs/contract.md(契约逐字段)、references/scripts.md(每工具参数与判据阈值)、docs/design-decisions.md(哪些行为看起来像 bug 其实是决定)、references/ci-platform-pitfalls.md 与 references/process-pitfalls.md。文档本身由 CI 与契约绑定,漂移会让构建失败。来源:README「Docs」。
  • 竞品对比 1(Remotion):Remotion 的文档是独立文档站(含模板与示例入口),面向「学一个框架」;ffmpeg-skill 的文档在仓库内:README(约 770 行)+ docs/contract.md + references/scripts.md + docs/design-decisions.md + docs/demos.md + SKILL.md。前者是产品站形态,后者是随仓库发布的 Markdown;本文不评价教程体系是否完备。
  • 竞品对比 2(MoviePy):MoviePy 的入口是 API 参考与示例页,安装页还写明 ImageIO 首次使用会下载 FFmpeg、可用 FFMPEG_BINARY 指定路径;ffmpeg-skill 在 README 之外另有 docs/design-decisions.md(哪些行为看起来像 bug 其实是决定)与 references/process-pitfalls.md。两边文档侧重不同,本文不比较示例长度或罕见程度。
  • 扣分:文档语言为英文,无中文版;体量极大(README 约 123 KB),新读者需要靠目录跳转;未发布的平台兼容矩阵(Cursor Marketplace、Gemini 扩展库、Glama 均在等待审核)只能靠 README 表格推断。

👥 社区活跃 0.8/1.5

  • 证据:stars 8,302、forks 773、open issues 53,pushed_at 为 2026-11-19T20:28:04Z(距核验不足一天);CI 在 Linux、macOS、Windows 三个平台跑契约与测试,评测结果按迭代版本落在 evals/results/,CHANGELOG 由发布流水线生成。来源:GitHub REST、README「Tested on real footage」「Development」。
  • 竞品对比 1(Remotion):Remotion 由公司运营,提供商业许可与支持入口;ffmpeg-skill 是个人项目加 GitHub Sponsors。支持渠道的形态不同(商业支持 vs 赞助/issue),本文不据此推断响应速度或插件数量。
  • 竞品对比 2(MoviePy):MoviePy 建立时间更早,文档、示例与维护者招募入口都在官方页面列出;ffmpeg-skill 建仓于 2026-09-03,可见的支持入口是 README 的 FAQs 与 GitHub issues。本文没有统计两边的教程数量或问答存量。
  • 扣分:贡献者接口带 anon=1 只有 11 条,其中 1 条匿名,除 kajisho5 外主要是自动化账号(github-actions[bot]、claude[bot]、dependabot[bot]),存在单点维护风险;53 个 open issues 只作单日计数记录,本文没有同类项目的基线,不判断这个比例偏高还是偏低;发布由自动化流水线驱动,说明流程规范,不等于外部协作活跃。

🔗 兼容性 0.9/1.5

  • 证据:宿主侧覆盖 Claude Code、Cursor、Codex、Gemini CLI 与任意 MCP 客户端;运行侧要求 FFmpeg 6.1+、Python 3.10+(仅标准库)、Node 16+(仅安装器)。doctor 把每个能力解析成 available / missing / unknown 三态,并给出按语言区分的字体可用性与 GPU 编码器清单。来源:README「Requirements」「Capability detection」。
  • 竞品对比 1(Remotion):Remotion 的渲染依赖浏览器,可用框架自带的下载流程,也可用 browserExecutable 指定自己的浏览器路径;ffmpeg-skill 依赖系统 FFmpeg 构建,缺 subtitles、drawtext、zscale 会直接变成功能缺失。两边都要指定运行时,只是一个管浏览器、一个管 FFmpeg 构建。
  • 竞品对比 2(MoviePy):MoviePy 通过 ImageIO 取 FFmpeg,首次使用会下载,也可用 FFMPEG_BINARY 指向系统或自定义二进制(ffplay 另配);ffmpeg-skill 明确不捆绑 FFmpeg,用哪个构建由你的 PATH 决定。两边都把二进制的选择权留给用户,只是默认路径不同。
  • 扣分:macOS 普通 brew 构建缺三个关键滤镜,需要 ffmpeg-full 并处理 keg-only 的 PATH 问题;Windows 上真实设备语料尚未跑完(issue #143),且 python3 在 Git Bash 里常不可用;FFmpeg 9.x 与 6.1 的滤镜列表列宽不同,曾导致 0.9.0 在 macOS/Windows 上误判「全部滤镜缺失」。

维度求和核对

2.2 + 2.1 + 1.9 + 0.8 + 0.9 = 7.9,与总分 7.9/10 一致;各维度均未超过满分(2.5 / 2.5 / 2.0 / 1.5 / 1.5)。

局限与未实测

  • 未安装、未触发:所有「装上之后 agent 会怎么做」的描述来自 README 与 SKILL.md 的结构,不是实测。
  • 未运行任何工具:42 个工具的实际行为、失败模式与输出精度均未验证。
  • 未复现评测:README 里的 100 条提示词评测、92 个验证步骤、F1 0.97、silence 0 missed 等数字为作者自述,脚本虽在仓库内可复跑,本文未跑;MCP schema 体积(71.0 / 190.9 / 24.0 kB)同样是 README 作者的测量值。
  • 未做跨平台验证:macOS keg-only、Windows python3、FFmpeg 6.1/8.x/9.x 的差异均按文档转述。Windows 上「python3 常不可用」是文档经验,不是所有安装方式下的普遍结论。
  • 未评估真实素材上的画面质量:裁切、字幕可读性、HDR 转 SDR 的主观效果需要人眼看,本文只核对了「工具有能力做」与「工具有复验步骤」。
  • stars / forks / open issues / 贡献者为 2026-11-20 05:36(北京时间)单日快照,会随后续提交变动;npm 版本 3.15.1 为采集时 latest。

来源核实

  • ✅ 直连已验证:README — 安装命令、42 工具表、MCP 默认 12 工具与体积、doctor 三态语义、1800 秒超时与一小时导出被杀、macOS 滤镜缺失、Windows python3 说明、issue #143、许可与 FFmpeg 构建授权段落。
  • ✅ 直连已验证:GitHub REST — stars 8,302、forks 773、open issues 53、pushed_at、created_at、默认分支 main、MIT、语言 Python(2026-11-20 05:36 北京时间快照)。
  • ✅ 直连已验证:贡献者与最新提交接口(带 anon=1)— 11 条,含 1 条 Anonymous;kajisho5 351 次、github-actions[bot] 209 次、claude[bot] 53 次;最新提交 2026-11-19T17:41:13Z。接口只给账号类型与计数。
  • ✅ 直连已验证:npm registry — 包创建 2026-09-03T15:19:14Z,latest = 3.15.1,许可 MIT,最近发布 2026-11-19。
  • ✅ 直连已验证:docs/contract.md 与 references/scripts.md — 输入指纹字段(size、sha256_head_tail、unbound_inputs)与 --plan / --dry-run 的例外原文。
  • ⚠️ 未逐页核对:evals/results/* 只核到 README 中的引用与目录结构,未读全文。
  • ⚠️ 未独立实测:未安装、未执行任何脚本、未在真实素材上验证任何结果;作者自述的评测数字不代表本站结论。

标签说明

  • 视频处理: 42 个工具围绕剪辑、音频、字幕、转码与交付检查,README 定位为 locally editing your footage。来源:README。
  • FFmpeg: 所有媒体操作交给系统的 ffmpeg / ffprobe 执行,技能本身不捆绑也不重写 FFmpeg。来源:README「Requirements」「License」。
  • Agent Skills: 以 SKILL.md 交付,供 Claude Code、Cursor、Codex 等宿主读取;同一套工具同时以 MCP 暴露。来源:README 首段与「MCP」。
  • 本地运行: 官方明确 no cloud、no API keys,工具只用 Python 标准库,媒体处理在本机 FFmpeg 上完成。这个标签描述的是技能层:npx 安装器与包管理器、可选本地语音引擎首次下载权重会联网,宿主模型(Claude Code / Cursor / Codex 等)也可能收到提示词、日志与联系表图像。不能把它读成「整个使用链路离线」。来源:README「Why」。