FFmpeg-Skill 是一个为 AI 编程智能体（如 Claude Code、Cursor、Codex）设计的本地视频编辑技能包。它通过结构化的工具集和固定工作流，让智能体能像专业剪辑师一样使用 FFmpeg 进行视频处理，且完全本地运行，无需云服务或 API 密钥。

本教程将指导您在智能体环境中完整部署和使用 FFmpeg-Skill。

1. 项目概览与核心价值

FFmpeg-Skill 不是一个独立的应用程序，而是一个为智能体提供的“技能包”。它从根本上解决了 AI 直接调用 FFmpeg 时的常见问题：猜测参数、错误使用编解码器、不必要地重新编码、以及缺乏结果验证。

核心设计原则

  • 探测优先 (Probe First)：所有操作前必须先使用 probe.py 获取文件的真实参数（时长、帧率、分辨率、色彩等），杜绝依据文件名猜测。
  • 无损优先 (Lossless When Possible)：剪辑、拼接等操作优先使用流拷贝（-c copy），仅在必要时才重新编码，保证速度与画质。
  • 计划后渲染 (Plan Before Render)：所有工具都支持 --dry-run 模式，可预览命令而不实际执行，便于审核。
  • 结果验证 (Verify the Result)：每次操作后自动对输出文件进行探测 (probe)、合规检查 (check)，并在画面变动时生成缩略图联系表 (look.py) 供智能体“查看”。
  • 机器可读契约 (Contract)：通过 contract --json 提供所有工具的详细输入输出模式，使智能体能够精确调用。

2. 环境准备

2.1 基础依赖

  • 操作系统：Windows、macOS 或 Linux。
  • FFmpeg：版本 5.0 或更高。请务必安装包含所需滤镜的完整版本。
    • macOS：推荐 brew install ffmpeg-full（注意：普通 ffmpeg 公式可能缺少 libass、zscale 等关键滤镜）。
    • Ubuntu/Debian：sudo apt install ffmpeg。
    • Windows：winget install Gyan.FFmpeg 或从 gyandev 下载完整构建版。
  • Python：Python 3.9 或更高版本（仅使用标准库）。
  • Node.js：Node 16 或更高版本（仅用于运行 npx 安装器，运行技能本身无需 Node）。

2.2 验证 FFmpeg 安装

安装 FFmpeg 后，打开终端，确保以下命令可正常执行并返回版本信息：

1
2
ffmpeg -version
ffprobe -version

3. 安装 FFmpeg-Skill

方式一：使用 npx 一键安装（推荐）

此方式会将技能包自动安装到智能体对应的技能目录下。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 为 Claude Code 安装 (默认)
npx ffmpeg-skill

# 为 Cursor 安装
npx ffmpeg-skill --cursor

# 为 Codex 安装
npx ffmpeg-skill --codex

# 为所有三个智能体安装
npx ffmpeg-skill --all

# 安装到当前项目的 .claude/skills 目录
npx ffmpeg-skill --project

方式二：手动克隆安装

如果您没有 Node.js 环境，或希望自定义安装路径，可直接克隆仓库并复制文件。

1
2
git clone https://github.com/kajisho5/ffmpeg-skill.git
# 将 SKILL.md、scripts/、references/ 和 mcp/ 文件夹复制到您智能体的技能目录中。

安装后检查

安装完成后，运行内置的 doctor 命令，检查当前系统中的 FFmpeg 是否满足所有工具的需求。

1
npx ffmpeg-skill doctor

该命令会列出所有必需和可选的 FFmpeg 组件（编码器、滤镜等）的状态：available (可用)、missing (缺失) 或 unknown (未知)。请确保所有必需组件均为 available。

4. 核心工具概览

FFmpeg-Skill 提供了 21 个 结构化 Python 脚本工具，全部位于 scripts/ 目录下。您可以直接从命令行调用它们，但更常见的是由智能体按需调用。

类别 工具 功能描述
分析与检测 probe.py 获取媒体文件的全面技术参数（时长、帧率、色彩空间、HDR 类型、音频流等）。
scenes.py 检测场景变化、音频峰值，生成剪辑建议点。
look.py 生成视频联系表（缩略图网格）、单帧截图或并排对比图，供智能体“视觉验证”。
基础剪辑 cut.py 执行单个或多个片段的剪切，优先无损拷贝，支持帧精确剪切。
join.py 拼接多个视频/音频片段，支持交叉过渡 (xfade)，并统一规格。
silence.py 检测并移除静音片段（跳剪），可保留语音周围的安全边距。
fit.py 调整视频时长（变速）和/或宽高比（裁剪或填充），以适配特定平台（如 Reels）。
音频处理 audio.py 语音降噪、动态压缩/限制/门限、侧链闪避、淡入淡出、多声道下混、音轨替换等。
sync.py 通过音频互相关分析，计算两个录制文件之间的时间偏移（最高精度 1ms），并可校正时钟漂移。
loudness.py 执行 EBU R128 标准的响度标准化（如 -14 LUFS），适用于播客、视频平台。
画面与效果 caption.py 烧录 SRT/ASS 字幕，支持卡拉 OK 动画效果，并可调用本地 Whisper 进行语音转录。
overlay.py 叠加图片（Logo、水印）或文本标题，可控制位置、时间范围和透明度。
graphics.py 使用 FFmpeg 绘制动态图形元素，如标题卡、章节徽章、进度条、倒计时等。
color.py HDR（HLG/PQ/Dolby Vision）到 SDR 的色调映射、应用 3D LUT 文件、基础色彩校正（曝光、对比度、饱和度、白平衡）。
交付与报告 export.py 针对 YouTube、Reels、ProRes、GIF 等常用场景的预设导出，自动添加正确元数据。
check.py 检查视频是否符合目标平台（YouTube、TikTok、播客等）的规范，并给出修复建议。
report.py 生成一个 HTML 格式的完整交付报告，包含前后对比、文件信息、响度和合规性检查结果。
工作流编排 render.py 从声明式的 project.json 文件渲染整个剪辑项目（包含片段、转场、字幕、音轨等）。
batch.py 将某个操作（或整个项目）批量应用于文件夹内的所有文件，并支持内容哈希缓存以跳过重复处理。
multicam.py 通过音频对齐多机位素材，并根据切换列表（switch list）自动剪辑。
verify.py 在实际设备文件上运行整个工具链，并报告每一步的通过/失败状态，用于验证系统完整性。

5. 智能体集成与使用

5.1 MCP (模型上下文协议) 集成

这是将技能与智能体连接的标准方式。将以下配置添加到您的智能体客户端（如 Claude Desktop）的 MCP 配置文件中，即可将 FFmpeg-Skill 的所有工具作为 MCP 工具暴露给智能体。

1
2
3
4
5
6
7
8
{
  "mcpServers": {
    "ffmpeg-skill": {
      "command": "python3",
      "args": ["路径/到/你的/skills/ffmpeg-skill/mcp/server.py"]
    }
  }
}

5.2 工作流示例

安装并集成后，您可以直接用自然语言向智能体发出视频编辑指令，例如：

“请处理这段 interview.mp4：保留 0:45 到 3:10 和 5:00 到 6:30 这两个片段，然后将它们拼接成一个恰好 60 秒、宽高比为 9:16 的短视频。”

智能体会遵循 SKILL.md 中定义的工作流，自动地、依次调用工具：

  1. probe.py：分析输入文件 interview.mp4，获取准确参数。
  2. cut.py：根据您的时间点无损剪切出两个片段。
  3. join.py：将两个片段拼接在一起。
  4. fit.py：调整拼接后视频的时长至 60 秒，并裁剪至 9:16 宽高比。
  5. export.py：使用 --preset reels 导出最终视频。
  6. check.py：检查导出视频是否符合 Reels 的交付标准。
  7. look.py：生成最终视频的联系表截图，并附在最终报告中。
    智能体会在任务完成时给出详细的处理报告。

5.3 直接命令行使用

您也可以不通过智能体，直接在终端使用这些工具进行测试或手工处理：

1
2
3
4
5
6
7
8
# 获取文件信息
python3 ~/.claude/skills/ffmpeg-skill/scripts/probe.py my_video.mp4 --compact

# 预览剪辑计划（不实际执行）
python3 ~/.claude/skills/ffmpeg-skill/scripts/cut.py my_video.mp4 --start 00:01:00 --end 00:02:00 --dry-run

# 执行音频标准化
python3 ~/.claude/skills/ffmpeg-skill/scripts/loudness.py audio.wav -I -16 -o audio_normalized.m4a

6. 配置与优化

6.1 查看机器可读契约

高级用户或智能体框架可以通过契约来动态了解所有工具能力。

1
npx ffmpeg-skill contract --json

这会输出一个完整的 JSON 文档，描述了每个工具的输入参数（从 argparse 自动生成）、输出模式、所需 FFmpeg 能力、验证策略等。

6.2 调试与测试

项目提供了完整的测试套件，用于验证环境。

1
2
3
4
5
# 运行所有测试 (需要约1.4GB测试素材下载)
python3 tests/corpus.py --fetch --verify

# 单独测试场景检测
python3 tests/bench_scenes.py

7. 常见问题与排查

问题 可能原因与解决方案
doctor 报告 libass 或 zscale 缺失 FFmpeg 安装不完整。macOS 需使用 ffmpeg-full；Linux 可安装 libavfilter-extra 包；Windows 请从 Gyan 下载完整版。
智能体无法调用工具 MCP 配置文件中 server.py 的路径不正确。请使用绝对路径，并确认 Python 环境可执行。
cut.py 剪切不精确 若未使用 --accurate 标志，为保持性能会采用关键帧剪切（误差在 GOP 内）。如需帧精确，请添加 --accurate，但会触发重新编码。
处理 HDR 视频时颜色异常 确保使用 color.py 配合正确的色调映射参数（如 --tonemap hable）将 HDR 转换为 SDR，并在导出时指定合适的色彩标签。
音频同步问题 尝试使用 sync.py 工具，它可以通过音频波形互相关自动计算并校正两个音视频文件之间的偏移和时钟漂移。

通过以上步骤，您已经成功为您的 AI 编程助手部署了专业级视频编辑能力。现在，您可以直接用自然语言指令，让智能体可靠地完成从简单剪辑到复杂色彩校正的各种任务。