ffmpeg-skill 把本地 FFmpeg 包装成 Coding Agent 可发现、可校验、可调用的 42 个工具。Agent 读取机器可读契约,经 MCP 服务调用本地 FFmpeg,再读取生成的文件;它补充的是 Agent 的工具调用层,而不是重新实现一套视频引擎。
这套方案适合裁切、拼接、字幕、转码等参数明确且经常重复的任务。它与“完全本地、不上传”并非同义:FFmpeg 处理发生在本机,但自然语言请求、字幕识别后端是否发送数据,仍取决于 Agent 和相关服务的配置。
42 个工具:补齐 Agent 的工具调用层
FFmpeg 本身提供录制、转码、滤镜和流化能力,配套的 ffprobe 可检查媒体信息。它的命令行以选项和滤镜组合表达任务,直接使用最灵活,但要求人或 Agent 准确掌握输入输出顺序、-map、编码器和滤镜参数。
ffmpeg-skill 在这之上补充了四个环节:机器可读契约负责描述工具名称、参数和输入输出;MCP 服务负责校验调用并启动 FFmpeg;Agent 根据契约选择工具;最终再通过 ffprobe 或文件信息确认结果。所谓“42 个工具”大多是常用 FFmpeg 操作组合,而不是 42 种全新的编解码算法。
| 使用路径 | Agent 面对的接口 | 更适合 | 主要限制 |
|---|---|---|---|
| 直接调用 FFmpeg | 命令行和选项 | 已知参数的一次性处理、精细控制 | 参数组合复杂,容易误选流或编码器 |
| Python-FFmpeg | 同步、异步 Python API | 开发转码服务、录制或批处理应用 | 仍需自行封装 Agent 的工具协议 |
| GitHub URL 生成 Coze Skill | 仓库地址加自然语言提示 | 快速生成 Coze Skill | 与具体客户端的集成程度取决于生成结果 |
| ffmpeg-skill | 42 个结构化工具和 MCP 服务 | Claude Code、Cursor、Codex 中执行本地视频任务 | 能力受 FFmpeg 构建版本和契约约束 |
当前项目明确面向 Claude Code、Cursor 和 Codex,因此不宜把它描述为原生支持 Coze。通过 GitHub URL 自动生成 Coze Skill 是另一条工作流;即使生成成功,也不能据此推断 ffmpeg-skill 的 MCP 服务可以直接接入 Coze。
42 个工具按任务查,先覆盖剪辑、字幕和画幅
这份清单以仓库 main 分支 README 标注的 42 项工具为准;实际调用时,应以同一 Commit 的机器可读契约为准。下表列出各工具的用途、关键参数、输入输出和最短调用指令。
| 工具名 | 用途与关键参数 | 输入 → 输出 | Agent 指令示例 |
|---|---|---|---|
get_media_info |
探测格式、时长、分辨率、流 | 媒体 → JSON | 探测 input.mp4 |
trim_video |
保留区间;start,end |
视频 → 视频 | 裁 5–15 秒 |
cut_video |
删除指定区间;segments |
视频 → 视频 | 删除 10–20 秒 |
split_video |
等长或指定分段 | 视频 → 视频组 | 每 5 秒切分 |
concat_videos |
按列表顺序拼接 | 多视频 → 视频 | 拼接 a、b |
add_transition |
添加转场;类型、时长 | 多视频 → 视频 | 加 1 秒淡化 |
change_speed |
倍速;factor |
视频 → 视频 | 加速到 2 倍 |
reverse_video |
视频倒放 | 视频 → 视频 | 倒放 input.mp4 |
loop_video |
循环;count |
视频 → 视频 | 循环 3 次 |
generate_subtitles |
识别语音;语言、模型 | 音视频 → SRT | 生成中文字幕 |
add_subtitles |
封装字幕轨;字幕文件、语言 | 视频+字幕 → 视频 | 把 srt 封装进视频 |
burn_subtitles |
渲染字幕;字幕、样式 | 视频+字幕 → 视频 | 烧录 srt |
extract_subtitles |
提取内嵌字幕 | 视频 → SRT/VTT | 提取视频字幕 |
crop_video |
裁剪画面;x,y,w,h |
视频 → 视频 | 居中裁成 1080×1920 |
scale_video |
缩放;宽、高 | 视频 → 视频 | 缩放到 1280×720 |
pad_video |
补边;画布、位置、颜色 | 视频 → 视频 | 补边成 1920×1080 |
rotate_video |
旋转;角度、方向 | 视频 → 视频 | 旋转 90 度 |
reframe_video |
目标画幅;比例、布局 | 视频 → 视频 | 重构为 9:16 |
set_fps |
修改帧率;fps |
视频 → 视频 | 改为 30 fps |
denoise_video |
降噪;强度 | 视频 → 视频 | 轻度降噪 |
adjust_color |
亮度、对比度、饱和度 | 视频 → 视频 | 提高对比度 |
transcode_video |
转码;编码器、CRF | 视频 → 视频 | 转成 H.264/AAC |
remux_video |
换封装、不重编码 | 视频 → 视频 | 无损封装为 MKV |
compress_video |
压缩;码率、CRF | 视频 → 视频 | 压到 2 Mbps |
convert_format |
容器与编码转换 | 媒体 → 媒体 | 转成 WebM |
extract_audio |
提取音轨;编码、采样率 | 视频 → 音频 | 提取 MP3 |
replace_audio |
替换原声;音频、偏移 | 视频+音频 → 视频 | 用 audio.wav 换原声 |
mix_audio |
混合多轨;音量权重 | 多音频 → 音频 | 混合两段音频 |
adjust_volume |
调整音量;倍数或 dB | 音频 → 音频 | 音量降至 -6 dB |
fade_audio |
淡入淡出;起止、时长 | 音频 → 音频 | 做 1 秒淡入淡出 |
normalize_audio |
响度标准化;目标 LUFS | 音频 → 音频 | 标准化到 -14 LUFS |
remove_silence |
删除静音;阈值、时长 | 音频 → 音频 | 删除静音段 |
overlay_video |
叠加图层;位置、透明度 | 基础视频+图层 → 视频 | 把 logo 放右上角 |
add_watermark |
图片或文字水印 | 视频+素材 → 视频 | 添加半透明水印 |
picture_in_picture |
画中画;窗口、位置 | 主视频+小窗 → 视频 | 小窗放右下角 |
extract_frames |
抽帧;时间点或帧率 | 视频 → 图片组 | 每秒抽一帧 |
create_thumbnail |
封面;时间点、宽度 | 视频 → 图片 | 截取第 10 秒封面 |
image_to_video |
图片转视频;时长、帧率 | 图片 → 视频 | 让图片动 5 秒 |
images_to_video |
图片序列转视频 | 图片组 → 视频 | 合成图片序列 |
video_to_gif |
GIF;帧率、宽度 | 视频 → GIF | 转成 10 fps GIF |
gif_to_video |
GIF 转视频;帧率、时长 | GIF → 视频 | 把 GIF 转成 MP4 |
video_to_images |
视频拆成图片序列 | 视频 → 图片组 | 拆分视频帧 |
优先学习 trim_video、cut_video、split_video、concat_videos,再学习字幕和 reframe_video,基本能覆盖日常剪辑。字幕必须区分三件事:generate_subtitles 依赖语音识别后端生成字幕文件;add_subtitles 只封装字幕轨,不改变画面像素;burn_subtitles 会把字幕渲染进视频,之后无法直接恢复为独立字幕轨。FFmpeg 本身不能从语音中推断字幕,因此“生成”环节还需要对应的识别模型或服务。
画幅重构也应先做取舍:以主体为中心时使用裁剪,以完整保留原画面为优先时使用补边。转码、压缩和换封装不是同一件事;能直接换容器时使用 remux_video,需要改变编码或码率时才使用 transcode_video 或 compress_video。
接入三个 Coding Agent,跑通两条视频链路
先区分 Skill 与 MCP:Skill 提供说明、工作流和机器可读契约,MCP 服务才是实际执行工具的进程。只安装 Skill,Agent 可能知道该做什么,却无法调用工具。
先确认系统中同时存在 ffmpeg 和 ffprobe:
ffmpeg -version
ffprobe -version
再安装 Agent Skill,并按仓库说明用 Node.js 构建 MCP 服务:
npx skills add kajisho5/ffmpeg-skill
git clone https://github.com/kajisho5/ffmpeg-skill.git
cd ffmpeg-skill
npm install
npm run build
Claude Code 可以通过命令注册 MCP:
claude mcp add ffmpeg -- node /absolute/path/to/ffmpeg-skill/dist/index.js
Cursor 在项目的 .cursor/mcp.json 中配置:
{
"mcpServers": {
"ffmpeg": {
"command": "node",
"args": ["/absolute/path/to/ffmpeg-skill/dist/index.js"]
}
}
}
Codex 在 ~/.codex/config.toml 中配置:
[mcp_servers.ffmpeg]
command = "node"
args = ["/absolute/path/to/ffmpeg-skill/dist/index.js"]
配置中的路径应使用绝对路径。配置完成后,重启客户端或开启新会话。随后检查 MCP 面板或列表,确认 ffmpeg 已连接且能够列出工具:
claude mcp list
codex mcp list
第一次调用可以先让 Agent 探测媒体,再执行裁切:
请先探测 ./input.mp4,再把 00:00:05 到 00:00:15 裁成 ./output/trim.mp4,并核对输出时长。
裁切与拼接通常对应 get_media_info → trim_video → concat_videos。如果片段的编码、分辨率、帧率或音频参数不一致,直接拼接可能失败,此时应先用 transcode_video 统一参数,而不是反复修改拼接参数。
字幕与画幅链路可以这样描述:
请为 ./talk.mp4 生成中文字幕,先把画面重构为 9:16,再把字幕作为独立字幕轨封装到成片中;主体优先,字幕样式保持默认。
合理顺序是先生成字幕,再重构画面,最后封装或烧录。若同时要求画幅重构和字幕烧录,应先重构、后烧录,否则裁切可能截断已经渲染进画面的字幕。中间的 add_subtitles 产物仍可继续调整字幕轨;burn_subtitles 应留给最终交付版本。
常见故障集中在几个位置:ffmpeg 不在 MCP 进程的 PATH 中会导致启动或执行失败;相对路径会随 Agent 的工作目录变化,因此输入输出应使用绝对路径;MCP 已连接但工具未出现时,应检查 Skill 契约是否安装、客户端是否允许该工具;时间格式、枚举值和文件不存在会在参数校验阶段报错;H.264、VP9、AV1 或某项滤镜是否可用,则取决于本机 FFmpeg 构建,可通过 ffmpeg -encoders、ffmpeg -filters 和 ffmpeg -formats 核对。
成片完成后,用 ffprobe 核对时长、分辨率和流结构:
ffprobe -v error -show_entries format=duration:stream=index,codec_type,codec_name,width,height,r_frame_rate -of json ./output/final.mp4
输出中的 format.duration 应接近预期时长,视频流应显示目标分辨率;如果要求保留声音或独立字幕,streams 中还应分别出现音频流和字幕流。
[email protected]
。
我们承诺在核实信息后,将第一时间删除相关内容或断开链接。























暂无评论内容