kajisho5/ffmpeg-skill

项目介绍

ffmpeg-skill 是一个本地视频与音频剪辑引擎，供 Claude Code、Cursor、Codex 或任意 MCP 客户端中的编码智能体调用。它不让智能体直接拼 FFmpeg 命令，而是提供 42 个带类型化 argparse 参数的 Python 脚本：每个任务先探测素材，再执行编辑，最后测量输出文件。常见流程由 probe.py、cut.py、fit.py、export.py、check.py 和 look.py（生成联系表）组成，覆盖裁剪、拼接、字幕烧录、重构图、响度归一化、平台导出和静音移除等操作。

这些工具的定义同时以机器可读契约和 MCP 服务发布。契约中的 input_schema 直接从脚本运行时的 argparse 解析器生成，因此 CLI、契约与 MCP 的 tools/list 不会各自漂移，并有测试验证这一点。通过 MCP 使用时，默认只列出核心 12 个工具以节省上下文，其余工具仍可通过 tools/call 按名称调用。

快速使用

前置条件是 FFmpeg 6.1+ 和 Python 3.10+，只有用 npx 安装器时才需要 Node 16+。以 Ubuntu/Debian 为例：

sudo apt install ffmpeg
npx ffmpeg-skill            # 安装给 Claude Code；其他客户端用 --cursor、--codex 或 --all
npx ffmpeg-skill doctor     # 检查 ffmpeg、ffprobe 及所需组件

安装器会把技能复制到对应智能体的 skills 目录。之后可直接用自然语言向智能体提出剪辑需求，例如保留某段素材的两个区间并适配成 9:16 的 Reels 时长；智能体会依次调用探测、裁剪、适配、导出和检查工具，并报告测量结果。工具也可以在 shell 中直接运行：

S=~/.claude/skills/ffmpeg-skill/scripts
python3 $S/probe.py input.mp4 --compact
python3 $S/fit.py input.mp4 --duration 60 --aspect 9:16 --dry-run
python3 $S/export.py input.mp4 --preset reels --json

平台模板通过 render.py 渲染，例如 python3 $S/render.py talk.mp4 --template tiktok --cues cues.txt，内置模板包括 TikTok、Reels、Shorts、YouTube、X、LinkedIn、Facebook、podcast 和 audiogram。已安装的副本不会自动更新，需要再次运行 npx ffmpeg-skill 刷新；Claude Code 插件和手动复制等其他安装方式见安装说明。

使用约束

• FFmpeg 构建差异会影响可用性。doctor 会检查 libx264、aac、drawtext、subtitles（libass）、loudnorm 等必需组件；总体 ok 为 false 时多数工具仍可能可用，应查看 doctor --json 中每个工具的 usable 字段。部分 Homebrew 构建缺少 libass、libfreetype 或 libzimg。
• 语音转字幕需要另行安装本地引擎，例如 pip install faster-whisper，首次运行可能下载模型；没有引擎时其他工具仍可使用，--transcribe 会拒绝执行并给出安装提示。
• verified 只覆盖可测量的文件属性，无法判断画面或声音听起来是否正确。字幕位置、可读性、构图、调色观感和混音平衡会被列为未验证。
• 已知限制：不做自动人脸或主体跟踪重构；不能移除移动的烧录台标或字幕；除 Apple Silicon 上的 VideoToolbox 外不做 GPU 编码（nvenc、QSV、VAAPI、AMF 可被检出但工具不使用）；不接受任意 FFmpeg 参数或调用方提供的 filter graph。
• 一小时基准是在 Linux 上测得的，完整的真实设备媒体语料尚未在 Windows 上跑过；README 指出完整语料测试和非维护者的 Windows 安装仍需覆盖（issue #143）。
• 许可证为 MIT。

HotRepo 点评

在 2026-11-03 记录的 Python 周榜中，该项目以新增 1,352 Star、总计 4,443 Star、350 Fork 排到第 6 名。这只是单次周榜快照，能说明该周获得了明显关注，不能据此判断长期采用情况。技术上更值得看的是契约驱动的设计：CLI 解析器同时作为 JSON 契约和 MCP schema 的唯一来源，每个工具执行后再测量自己的输出，把验证当作工具承诺的一部分，而不是事后补丁。这种结构让 42 个工具对智能体真正可用，也是评估该项目时最应关注的部分。