ffmpeg-skill:为 Agent 补齐本地 FFmpeg 工具层

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 中还应分别出现音频流和字幕流。

© 版权声明
THE END
喜欢就支持一下吧
点赞0 分享
评论 抢沙发

请登录后发表评论

    暂无评论内容