kajisho5/ffmpeg-skill

Local video editor for coding agents: 42 FFmpeg tools with a machine-readable contract and an MCP server, for Claude Code, Cursor and Codex. Cut, captions, reframe, loudness, platform exports. No cloud, no API keys.

什么是 ffmpeg‑skill？

ffmpeg‑skill 是一个本地、对 AI 代理友好且基于 FFmpeg 的封装工具，它允许 AI 编码代理（如 Claude Code、Cursor、Codex 或任何 MCP 客户端）在不将媒体发送到云端的情况下编辑视频和音频文件。它包含 42 个小型 Python 工具（例如 cut.py、fit.py、loudness.py、caption.py），每个工具都提供类型化的命令行接口以及描述其输入、输出和所需 FFmpeg 功能的机器可读契约。

该技能遵循严格的工作流：

探测 (Probe)：使用 probe.py 获取源文件的精确元数据（时长、帧率、分辨率、色彩空间、音频布局、HDR 等）。
编辑 (Edit)：尽可能进行无损编辑（流拷贝），仅在需要滤镜或精确剪辑时进行重编码。
验证 (Verify)：通过再次探测结果并可选地生成 PNG 联系表（look.py）来验证结果。
报告 (Report)：返回一个可供调用代理解析的结构化 JSON 报告。

所有这些操作均在离线状态下运行，仅需 FFmpeg、ffprobe 和 Python 3（仅标准库）。无需 API 密钥，无需外部服务，语音转文字功能仅在安装了本地 ASR 引擎时才有效。

核心功能

功能	重要性
代理就绪契约 (`contract --json`)	代理可以读取 JSON 模式，确保其传递的标志与底层的 `argparse` 定义匹配——文档与代码之间不会产生偏差。
42 个专注工具	每个操作（剪辑、合并、静音移除、字幕、HDR→SDR、响度标准化等）都是一个带有类型化参数的独立脚本，方便 LLM 调用正确的工具。
无损优先工作流	当编辑不需要重编码时，工具会尝试流拷贝 (`-c copy`)，从而保持质量并节省时间。
干运行与规划 (`--dry-run`, `--plan FILE`)	代理可以在写入任何文件之前预览精确的 FFmpeg 命令行，或生成可稍后执行的可重现计划。
验证步骤 (`look.py`, `check.py`)	每次编辑后都会再次探测输出；如果视觉内容发生变化，会生成 PNG 表格，以便代理能够“看到”发生了什么。
功能检测 (`doctor`)	在运行作业之前，该技能会检查本地 FFmpeg 构建是否包含所需的编码器/滤镜（例如 `libass`、`zscale`、`loudnorm`）。
无外部依赖	纯 Python 3.9+ 标准库；可选的本地 ASR 引擎（Parakeet‑mlx, faster‑whisper, openai‑whisper）仅在存在时使用。
模板驱动交付 (`render.py --template tiktok`)	针对 TikTok、Reels、Shorts 等平台的预构建 JSON 模板，自动设置宽高比、字幕样式、响度目标和导出预设。
跨仓库生态系统	设计为大型 AI 视频生产 OS 的“手”；其他技能（媒体分析、转录、字幕、调色）可以调用其契约，但反之则不行。

如何开始

# 安装技能（将其添加到 Claude 的技能目录）
npx ffmpeg-skill

# 验证您的机器是否具备所需的 FFmpeg 组件
npx ffmpeg-skill doctor

# 检查 JSON 契约（对代理或自定义工具很有用）
npx ffmpeg-skill contract --json | head -40

从命令行，您也可以直接运行任何工具，例如：

python3 ~/.claude/skills/ffmpeg-skill/scripts/cut.py input.mp4 \
    --segments 0:45-3:10,5:00-6:30 --dry-run

或者渲染一个完整的特定平台包：

python3 $HOME/.claude/skills/ffmpeg-skill/scripts/render.py talk.mp4 \
    --template tiktok --cues cues.txt

AI 代理的典型用例流程

用户请求 – “使用最佳片段从 interview.mp4 制作一个 60 秒的 Reel。”
代理读取 SKILL.md 以了解工作流。
探测 – probe.py 返回精确的元数据。
决定剪辑 – 代理可能会调用 scenes.py 获取高光建议，然后使用选定的片段调用 cut.py。
适配与格式化 – 使用 fit.py 强制执行 9:16 宽高比，使用 export.py --preset reels 获取正确的编解码器/比特率。
检查 – check.py --platform reels 验证时长、响度等。
查看 – look.py 生成联系表；代理检查 PNG 以确认视觉结果。
报告 – 该技能返回一个包含状态、输出路径、探测摘要以及指向 PNG 的 Look: 行的 JSON 对象。

谁会使用它？

构建 AI 驱动视频编辑器的开发者，需要一个可靠、离线的 FFmpeg 后端。
提示词工程师，希望他们的 LLM 代理在不编写原始 shell 字符串的情况下操作媒体。
内容创作者，偏好本地、隐私优先的工作流来进行快速的平台特定剪辑。
研究人员，正在试验需要“看到”视频编辑结果的多模态代理。

限制

该技能不决定剪辑什么、写什么字幕或哪个高光是“有趣的”——这些逻辑属于调用它的 AI 大脑。
它依赖于本地 FFmpeg 构建；缺失的滤镜将导致相应的工具无法使用（由 doctor 报告）。
音频转录是可选的，仅在安装了受支持的本地 ASR 引擎时才有效。

许可证

MIT – 可自由使用、修改并嵌入到其他项目中。