README 的 Why 章节写明每个任务从 probe.py 开始,并依据时长、fps、分辨率、色彩和音频布局决策。
ffmpeg-skill:给编码代理的本地42工具视频编辑器
给 Claude Code、Cursor 和 Codex 用的本地视频编辑器,靠42个结构化FFmpeg工具替代代理手写命令。
🧭 决策指南
为什么现在热: 无法从材料判断
适合,如果你
-
你在 Claude Code、Cursor 或 Codex 中处理本地视频,并希望代理先读取真实媒体属性。
-
你的 MCP 客户端需要从 argparse 自动同步工具参数,而不是维护第二份 schema。README 的 What is SPEC? 章节说明 input_schema 从运行时的 argparse parser 生成,tests/test_contract.py 会检查漂移。
-
你需要字幕、静音移除、响度或平台导出等现成视频操作,而不是直接拼接 shell 字符串。README 正文列出 caption.py、silence.py、loudness.py、export.py 和42个工具,并说明操作使用 typed arguments。
-
你需要默认较小的 MCP 工具列表,但仍能按名称调用完整工具集。README FAQ 说明 tools/list 默认列出核心12个,其他30个可通过 tools/call 按名称调用,FFMPEG_SKILL_MCP_FULL=1 可列出全部42个。
不适合,如果你
-
你的流程必须使用云端视频处理或上传音频进行转写。README 的 Local first 明确写明 No cloud、No API keys,且转写引擎在本机运行、音频不会上传。
-
你需要向调用者直接传入任意 filter_complex 或原始 FFmpeg shell 字符串。README 的 Why 章节写明工具不通过 shell 执行,也不接受调用者传入 filter graph。
-
你的部署环境没有 ffmpeg 或 python3 在 PATH 中。README 正文写明“If ffmpeg and python3 are on your PATH, it works”。
-
你要求代理自动追踪人脸或主体进行重构。README 将“Does it auto-track faces or subjects for reframing?”列为FAQ,但提供材料没有给出支持该能力的说明。
前置条件
- README Quick start 要求先安装 FFmpeg,例如 Ubuntu/Debian 使用 sudo apt install ffmpeg。
- README 正文要求 ffmpeg 和 python3 在 PATH 中。
- 安装入口是 npx ffmpeg-skill;README Quick start 还提供 npx ffmpeg-skill doctor。
- 本地转写不是必需项;使用 caption.py --transcribe 或 silence.py --transcribe 时,需要安装 Parakeet 或 whisper 引擎。
- parakeet-mlx、faster-whisper 和 openai-whisper 首次运行会下载模型权重;README 示例提到 whisper.cpp 的 large-v3-turbo。
第一步命令(README 原文)
npx ffmpeg-skill
要注意
-
运行 stabilize.py 时不能遗漏第一遍生成的transforms文件,否则第二遍缺少输入。README FAQ 说明 stabilize.py 使用两遍处理,第二遍需要第一遍的 transforms file。
-
处理 HDR→SDR 时要注意色彩标签;color.py 即使错误配置也可能退出成功。README FAQ 说明错误 colour tag 可能让运行完成,但画面会 washed out。
-
join.py 处理尺寸、帧率或音频布局不同的片段时需要先标准化,否则 xfade 会失败。README FAQ 说明 join.py 的不同媒体属性需要先 normalise。
-
启用本地转写时,parakeet-mlx、faster-whisper 和 openai-whisper 会在首次运行下载模型权重。README 的 Local first 章节明确列出首次下载模型权重的引擎。
-
MCP 客户端若只读取 tools/list,默认只能看到核心12个工具。README FAQ 说明默认 tools/list 暴露12个工具,FFMPEG_SKILL_MCP_FULL=1 才列出全部42个。
替代方案
-
Remotion:当你的决策重点是与Remotion的方案比较时,应直接查看两者在视频生成或编辑工作流上的差异;提供材料没有给出具体结论。README FAQ:How does ffmpeg-skill compare with Remotion?
材料未说明
- 提供材料没有给出各操作的性能、处理速度或硬件要求。
- 提供材料没有说明支持的具体操作系统版本和 FFmpeg 版本范围。
- 提供材料没有给出 GPU 编码是否支持;README 仅列出“Does it encode on the GPU?”这一FAQ标题。
- 提供材料没有给出 HDR→SDR、字幕和静音移除在真实素材上的成功率或质量指标。
- 提供材料没有说明 npx 安装路径所需的 Node.js 或 npm 版本。
- 提供材料没有给出42个工具的完整参数、输出格式和每项FFmpeg组件依赖。
- 提供材料没有给出与 Remotion 的具体功能、性能或维护对比。
- 提供材料没有说明最近新增367颗星与版本v3.10.1、最近10次提交之间的因果关系。
💡 深度解析
6
适合
我用 Python 和 argparse 维护 FFmpeg 工具,担心 CLI 参数、MCP schema、contract 和文档发生漂移;这个项目的 SPEC 模式是否值得采用?
适合读者: 熟悉 FFmpeg、但想减少复杂参数维护并接入编码代理的 Python 工具开发者
适合,尤其是你要同时维护 CLI、MCP 和机器可读契约,而不是只写一次性 FFmpeg 脚本。
- 项目的
input_schema在运行时直接从工具自身的 argparse parser 生成,覆盖 flags、类型、choices、默认值、必选参数和互斥组。 - MCP server 不单独维护 schema,而是从 contract 转换得到;新增 argparse flag 后,CLI 的参数和 MCP tool definition 可以同步更新。
TOOL_META仍由人工维护 role、capabilities、inputs、outputs 和验证信息,因为这些语义不能由 parser 表达。tests/test_contract.py在 CI 中检查代码、contract、文档和元数据是否漂移;它会发现不一致,但不会自动修复。
因此,SPEC 很适合减少重复定义和接口漂移;但它不是完整的元数据生成方案,扩展者仍需维护 TOOL_META、验证逻辑和文档。
- README「What is SPEC?」:"input_schema ... is derived ... from the live parser directly"
- README「What is SPEC?」:"The MCP server ... carries no schema of its own"
- README「What is SPEC?」:"TOOL_META" 提供 parser 无法表达的语义
- README「What is SPEC?」:"tests/test_contract.py ... fails the build if ... drift"
适合
我使用 Claude Code、Cursor 或 Codex,希望代理处理本地视频,但不想让它生成任意 FFmpeg shell 命令;这个项目能否提供可控的 MCP 工具接口?
适合读者: 使用 Claude Code、Cursor 或 Codex,并希望让编码代理通过 MCP 处理本地视频的开发者
适合,因为它把 FFmpeg 封装成结构化工具,并通过 MCP 暴露,而不是让代理直接拼接 shell 字符串。
- 项目提供 42 个任务级工具,覆盖剪切、字幕、响度、重构、交付检查和项目渲染。
- 每个工具使用 typed arguments;调用方不能传入任意原始 shell 字符串或
filter_complex,降低命令注入和参数误用风险。 - MCP 默认只在
tools/list中展示核心 12 个工具,以减少上下文负担;设置FFMPEG_SKILL_MCP_FULL=1后可列出全部工具,42 个工具仍可按名称调用。 - MCP schema 直接由 argparse 和机器可读 contract 生成,CLI 参数与接口定义不需要分别维护。
因此,它适合需要代理规划和调用固定媒体操作的场景;如果任务必须使用尚未封装的任意 FFmpeg filter graph,则不适合。
- README「Built for agents」:"ships 42 tools"
- README「Why」:"Structured tools, not shell strings"
- README「MCP」相关原句:"tools/list advertises a core 12 by default"
- README「What is SPEC?」:"input_schema ... is derived ... from the same argparse parser"
npx ffmpeg-skill
适合
我们的素材不能上传云端,也不想申请 API key;如果还要用本地 Parakeet、faster-whisper、openai-whisper 或 whisper.cpp 做字幕,这个项目是否适合?
适合读者: 素材不能上传云端、使用本地 FFmpeg 和 Python 标准库处理视频的隐私敏感媒体团队
适合,前提是你们能承担本地 FFmpeg、转写引擎和模型权重的计算与存储成本。
- README 明确声明 No cloud、No API keys,并说明核心运行依赖是 PATH 中的
ffmpeg和python3,不需要额外 Python 依赖。 - 可选本地转写支持 Parakeet、faster-whisper、openai-whisper 或 whisper.cpp;引擎在本机运行,音频不会上传。
caption.py --transcribe和silence.py --transcribe支持--engine、--model,也可用FFMPEG_SKILL_ASR_ENGINE与FFMPEG_SKILL_ASR_MODEL设置默认值。- 代价是部分引擎首次运行会下载模型权重,且 README 明确提示本地 ASR 可能增加首次耗时、磁盘占用和硬件需求。
因此,隐私和离线是硬约束时它很匹配;如果团队不能接受本地模型下载或没有足够计算资源,则需要另选方案。
- README 开头:"No cloud · No API keys · Python standard library"
- README「Why」:"Optional local transcription",列出 Parakeet 和 whisper 引擎
- README「Why」:"The engine runs on your machine and the audio is never uploaded"
- 项目洞察 user_experience.common_pitfalls:本地 ASR 可能需要较大模型权重、首次运行耗时和额外硬件
npx ffmpeg-skill
适合
我使用 Cursor 作为 MCP 客户端,既想保持默认上下文较小,又需要偶尔调用 multicam、批量文件夹处理和完整项目渲染;应该如何判断这个项目是否满足?
适合读者: 需要在默认 MCP 上下文较小的前提下按需调用全部 42 个视频工具的 Cursor 或其他 MCP 客户端用户
适合,因为项目把“默认少暴露”和“按名称访问全部工具”分开设计,正好覆盖你既要控制上下文、又要保留完整能力的约束。
- MCP 的
tools/list默认只广告核心 12 个工具,避免 42 个 schema 同时进入 Cursor 的上下文。 - 全部 42 个工具仍可通过工具名称调用;如果客户端需要完整列表,可设置
FFMPEG_SKILL_MCP_FULL=1。 - 工具范围不只包括基础剪切,还包括 multicam、batch folders、whole-edit project rendering、delivery checks 和平台导出。
- 这套设计并不意味着代理会自动理解复杂时间线;项目洞察指出,多轨关系、过渡、字幕定位和多机位编辑仍可能被错误拆解。
因此,它适合功能按需发现、工具按名调用的 MCP 集成;如果你要求客户端始终把全部 42 个 schema 自动展示且不做任何配置,则需要启用 full 模式。
- README「Built for agents」:"tools/list advertises a core 12 by default"
- README「Built for agents」:"FFMPEG_SKILL_MCP_FULL=1 listing all 42"
- README「Built for agents」:列出 multicam、batch folders、whole-edit project rendering
- 项目洞察 user_experience.common_pitfalls:复杂编辑意图可能被错误拆解
npx ffmpeg-skill
视情况
我需要先尽量无损剪切,再处理字幕、重构或 HDR 转 SDR,并确认输出画面真的正确;这个项目是否比直接调用 FFmpeg 更可靠?
适合读者: 需要无损优先剪切、关键帧偏移报告和字幕/画面结果核验的内容创作者或媒体工程师
视情况:它比只检查 FFmpeg 退出码更可靠,但不能把主观画质判断或复杂编辑决策完全自动化。
- 项目固定推广“probe → edit losslessly where possible → check → verify”,先读取真实媒体属性,再决定是否可以流复制。
cut.py会报告切点因关键帧产生的偏移,因此能显式暴露无损剪切与精确帧级剪切之间的差异。- 画面发生变化时,流程会重新探测、按目标规格检查,并在需要时生成 contact sheet;这对字幕、重构和 HDR → SDR 比单看进程成功更有价值。
- 但项目洞察明确指出,验证不能完全判断审美质量、叙事连贯性、字幕语义准确性或肤色;自动重构也不等同于持续主体或人脸跟踪。
所以它适合可验证的剪切和转码流程;若目标是专业调色、复杂时间线或精细审片,它不是完整非线性编辑器。
- README 开头:"fixed workflow (probe → edit losslessly where possible → check → verify)"
- README FAQ「Why 42 tools?」:"cut.py reports how far a cut snapped to a keyframe"
- README「Why」:"Verification after execution",并提到 picture changed 时使用 contact sheet
- 项目洞察 user_experience.usage_limitations:不是完整的非线性编辑器,不能完全判断主观效果
视情况
我需要把视频批量处理成平台版本,并检查最大时长、响度、true peak、画幅和编码规格;这个项目能否作为自动化媒体流水线的一层?
适合读者: 需要批量文件夹处理、平台导出和交付检查的媒体自动化工程师
视情况:它适合作为可脚本化、可验证的媒体执行层,但不能替代目标平台的实际播放测试或完整广播级质控。
- 42 个工具包含 platform exports、delivery checks、batch folders 和 whole-edit project rendering,覆盖自动化流水线常见的处理与交付环节。
export.py会检查预设的最大时长;loudness.py会重新测量 integrated loudness 和 true peak;工具还会在输出后重新 probe 并按目标规格检查。- 项目采用“probe → edit → check → verify”流程,依据真实时长、帧率、分辨率、色彩和音频布局,而不是仅检查 FFmpeg 退出码。
- 限制在于不同平台和播放器对编码器、像素格式、音频采样率及色彩元数据的支持不同,项目的交付检查不能完全替代真实播放验证。
如果流水线目标是标准化导出和机器可读检查,它合适;如果要求专业调色、精细混音或严格广播级质控,则不应单独依赖它。
- README「Built for agents」:列出 platform exports、delivery checks、batch folders
- README FAQ「Why 42 tools?」:"loudness.py re-measures integrated loudness and true peak"
- README FAQ「Why 42 tools?」:"export.py checks the preset's maximum length"
- README「Why」:"Verification after execution"
✨ 核心亮点
-
42 个 FFmpeg 工具覆盖剪辑、字幕、HDR→SDR与导出
-
probe.py 先读取时长、fps、分辨率与音频布局
-
SPEC 从 argparse 运行时生成 input_schema
-
MCP 默认暴露12个工具,可用变量列出全部42个
🔧 工程化
-
用 cut.py、caption.py 和 loudness.py 执行剪辑、字幕与响度处理
-
contract --json 描述工具输入、输出、FFmpeg组件与验证方式
-
MCP tools/call 可按名称调用42个工具,tools/list默认仅列12个
⚠️ 风险
-
parakeet-mlx、faster-whisper和openai-whisper首次运行会下载模型权重
-
MCP默认只列12个工具,未设置FFMPEG_SKILL_MCP_FULL不会显示全部42个
-
color.py错误色彩标签仍可能完成运行,但画面会发灰或发白
-
stabilize.py两遍运行依赖第一遍生成的transforms文件
👥 适合谁?
-
使用Claude Code、Cursor或Codex处理本地视频的开发者
-
需要MCP工具契约和typed arguments的代理框架集成者
-
希望用FFmpeg与ffprobe离线处理、避免上传素材的团队