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

整套工具一共42个,默认MCP只对外暴露12个高频核心工具避免占满上下文,开启环境变量FFMPEG_SKILL_MCP_FULL=1才会加载全部。它最特别的设计是自生成执行契约(SPEC):每个工具的入参Schema不是手工维护,而是直接从 argparse 解析器动态导出;一旦代码参数和MCP定义不同步,CI会直接报错,杜绝文档和实现漂移。
核心工作流:探测 → 编辑 → 校验 → 复核
这也是交给AI智能体强制遵守的流程:
- 探测优先(probe):先读取真实媒体文件,拿到时长、VFR帧率、分辨率、色彩空间、Dolby Vision/HDR信息、音频流,一切决策基于实测数据,不靠文件名猜。
- 优先无损:剪切、音频响度标准化优先流复制,只有帧精准剪辑、滤镜、格式转换等场景才触发重编码。
- 支持预演规划:所有工具都带
--dry-run预览命令、--plan保存执行计划,输入文件改动后计划会拒绝执行,防止素材变动渲染出错。 - 结果强制验证:输出文件二次探测;涉及画面改动(字幕、叠加、调色、裁切),自动生成联系表PNG交给智能体视觉复核;纯音频任务跳过图像检查。
- 永不覆盖原文件:输出生成新文件,自动命名,保留原始素材。
快速上手
# 安装,适配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报告,包含截图、媒体参数、响度、合规检查记录
相关导航


Academic Forge

MengTo/Agent Skills

Hindsight

NaturePanelForge

talk-normal

huashu-excel






