ffmpeg-skill

3周前发布 41 00

ffmpeg-skill 是一款专为 AI 编程智能体(如 Claude Code、Cursor、Codex 及任何支持 MCP 协议的客户端)设计的本地化视频处理工具集。它赋予智能体直接操作本地 FFmpeg 的能力,使其能够自主完成素材剪辑、拼接、音频清理、字幕烧录及多平台交付等复杂任务。

所在地:
kajisho5
收录时间:
2026-10-28
ffmpeg-skillffmpeg-skill

ffmpeg-skill 是面向 Claude Code、Cursor、Codex 以及所有兼容 MCP 客户端的 Agent Skill,本质是一套标准化封装的FFmpeg工具链。它解决一个老大难问题:AI智能体直接手写ffmpeg命令很容易踩坑——乱假设帧率、选错编解码器、不必要重编码,渲染完直接告诉你“完成”,根本不会校验输出文件是否符合预期。这个项目把探测、编辑、校验、复核做成固定闭环,全程本地离线运行,无云端、无需API密钥,仅依赖Python标准库 + FFmpeg。

ffmpeg-skill

整套工具一共42个,默认MCP只对外暴露12个高频核心工具避免占满上下文,开启环境变量FFMPEG_SKILL_MCP_FULL=1才会加载全部。它最特别的设计是自生成执行契约(SPEC):每个工具的入参Schema不是手工维护,而是直接从 argparse 解析器动态导出;一旦代码参数和MCP定义不同步,CI会直接报错,杜绝文档和实现漂移。

核心工作流:探测 → 编辑 → 校验 → 复核

这也是交给AI智能体强制遵守的流程:

  1. 探测优先(probe):先读取真实媒体文件,拿到时长、VFR帧率、分辨率、色彩空间、Dolby Vision/HDR信息、音频流,一切决策基于实测数据,不靠文件名猜。
  2. 优先无损:剪切、音频响度标准化优先流复制,只有帧精准剪辑、滤镜、格式转换等场景才触发重编码。
  3. 支持预演规划:所有工具都带--dry-run预览命令、--plan保存执行计划,输入文件改动后计划会拒绝执行,防止素材变动渲染出错。
  4. 结果强制验证:输出文件二次探测;涉及画面改动(字幕、叠加、调色、裁切),自动生成联系表PNG交给智能体视觉复核;纯音频任务跳过图像检查。
  5. 永不覆盖原文件:输出生成新文件,自动命名,保留原始素材。

快速上手

# 安装,适配Cursor / Claude Code / Codex / 全部
npx ffmpeg-skill

# 环境预检,检查FFmpeg编码器、滤镜、字体能力
npx ffmpeg-skill doctor

# 导出机器可读契约,给MCP客户端读取
npx ffmpeg-skill contract --json

MCP服务配置示例:

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

Windows注意:Microsoft Store版Python命令是python3,官网安装包一般是python,配置里需要对应修改。

四大类工具能力概览

1. 分析检测类

probe.py媒体全量探测;scenes.py检测镜头切换、音频峰值、节拍、运动类型;look.py生成联系表、对比帧,供AI看图复核。

2. 音视频编辑类

覆盖剪切拼接、静音剔除、时长比例适配、黑边裁剪、去隔行、降噪、画面打码、360球面视频提取、画面稳定、变速、循环、B-roll插入、章节标记;音频侧支持语音降噪压缩、侧链闪避、多机位音频漂移对齐、EBU R128响度归一化。

3. 字幕、图形、调色交付类

caption.py烧录字幕,支持平台安全区、短语自动换行;overlay.py水印、画中画、绿幕抠像;graphics.py生成下三分之一字幕、倒计时、社交贴纸;color.pyHDR/DV转SDR、LUT加载、基础调色;export.py内置TikTok、Reels、YouTube、播客等交付预设;check.py自动校验是否符合平台规格,输出PASS/WARN/FAIL。

4. 编排批量

render.py读取项目JSON,一键完成整套剪辑,支持多平台同时打包导出,还能导出FCP/PR/达芬奇兼容的EDL/FCFXML时间线;batch.py批量处理文件夹、监听目录;multicam.py多机位音频对齐、自动切镜。

生态定位

ffmpeg-skill 在这套视频生产体系里是执行手,只负责执行剪辑、测量、渲染、校验;不负责写脚本、定剪辑点、判断镜头好不好看。上层还有配套仓库:

  • video-production-agent:负责剪辑方案、审核交付
  • video-editing-skill / audio-production-skill:可视化编辑图抽象
  • remotion-ffmpeg-skill:动态字幕、动画图形合成
  • media-analysis / transcription / subtitle / color-grading 等技能:单向依赖ffmpeg-skill的输出,互相不反向调用

附加特性

  • 音频是一等公民:wav/flac/m4a/opus可以单独走整套探测、剪辑、响度校验流程
  • ASR可选:接入faster-whisper / Parakeet做语音转写、填充词检测,模型本地跑,不上传音频
  • 硬件编码:Apple Silicon可选VideoToolbox加速,其他平台复用FFmpeg自带NVENC/QSV/VAAPI
  • 完整交付报表:report.py输出HTML报告,包含截图、媒体参数、响度、合规检查记录

相关导航