ffmpeg-skill：让 AI Agent 自己剪视频的本地化工具包

Skill超级捕获手 技术创作者 2026-09-11 1841 阅读

ffmpeg-skill 是一款将本地 FFmpeg 封装为 Agent 可调用工具集的 SKILL.md 格式技能包。它为 Claude Code、Cursor、Codex 及任何支持 SKILL.md 的 Agent 提供完整的视频编辑工作流：probe（探测）→ edit（编辑）→ check（检查）→ verify（验证），全程本地离线运行，无需云端 API Key。9月初登顶 GitHub Trending，Trending Score 高达 487，成为当时最受关注的 Agent Skill 之一。核心价值在于：把 FFmpeg 繁杂的 CLI 参数封装成 40 个结构化工具，每个工具都有类型化参数、JSON 输出格式和可机器验证的契约（SPEC 规范），彻底消除 AI 代理”瞎猜参数、输出无法验证”的问题。

功能与原则

ffmpeg-skill 的核心能力是让 AI Agent 真正掌控视频编辑全流程，而不只是在 prompt 里写”帮我剪辑”。设计原则有三条：

  • Real files first：每个任务都必须先运行 probe.py 获取真实文件的 fps、分辨率、编码格式，再据此决定用什么参数。
  • Structured tools, not shell strings：每个操作都是带类型化参数的独立脚本，不走 shell 字符串拼接，从根本上避免注入风险。
  • Contract + verification：通过 contract --json 输出机器可读契约；每次执行后调用 check.py + look.py（缩略图）验证结果，而非简单返回”done”。

认可度

  • GitHub Star：截至 2026-09-09 约 789 星（9月初单日新增数百星）
  • GitHub Trending：2026年9月初登顶，Trending Score 487（top10.dev 报道印证）
  • 社媒热度：今日头条、AI 垂直媒体同步报道，被列为”9月最值得关注 Skill”之一
  • NPM 包：ffmpeg-skill 在 npm 平台可独立安装

链接

GitHub：https://github.com/kajisho5/ffmpeg-skill

原作者

GitHub 用户 kajisho5，专注于视频制作 Agent 工具生态，除了 ffmpeg-skill 外，还维护 video-production-agent（决策层）、AI-video-production-OS（编排层）以及 media-analysis-skill、transcription-skill、subtitle-skill、thumbnail-skill 等系列工具，构成完整的”视频制作 Agent 操作系统”。

介绍

ffmpeg-skill 解决了一个根本问题：FFmpeg 本身能力极强，但 CLI 参数极其繁杂且容易出错，即使 AI 模型”知道 FFmpeg”，在实际执行时仍会猜错帧率、选错编码格式、误用不兼容的容器。ffmpeg-skill 的解法是将 FFmpeg 封装为一套有契约、可验证、类型安全的工具集：40 个工具覆盖 cut（剪切）、join（合并）、silence removal（去静音）、fit（调整时长/比例）、caption（字幕）、karaoke（歌词特效）、overlay（叠加）、motion graphics（动态图形）、HDR→SDR、LUT、audio clean-up、sync（音画同步修正）、multicam（多机位）、loudness（响度标准化）、delivery check（交付检查）、batch（批量处理）。

每个工具同时也是一个 MCP 工具，可通过 Model Context Protocol 直接被 Agent 调用。SPEC（Self-Producing Execution Contract）规范是该项目的工程亮点：工具的 input_schema 不是手工编写，而是从 argparse parser 运行时自动派生，CI 会检测 schema 与实际代码的任何 drift，确保契约永远不过时。

特点

  • 本地离线，无需 API Key：只要系统装了 ffmpeg 和 python3 即可运行，不上传任何素材，保护隐私
  • 40 个工具 + probe/check/look 三重验证：每个操作执行后都探测输出文件、校验规格、生成缩略图确认画面正确
  • SPEC 契约驱动：input_schema 由代码自动派生，CI 保证契约与实现永不漂移
  • 全平台 MCP 兼容：Claude Code、Cursor、Codex 及任何 MCP 客户端均可直接调用
  • 批量自动化友好：支持 batch 文件夹处理、whole-edit 项目级渲染，适合自媒体批量剪辑工作流

使用方法

安装（以 Claude Code 为例）：

npx ffmpeg-skill

检查本机 FFmpeg 环境：

npx ffmpeg-skill doctor

读取机器可读契约（供 Agent 框架使用）：

npx ffmpeg-skill contract --json | head -40

让 Agent 执行一个真实任务：

"Take interview.mp4, keep 0:45–3:10 and 5:00–6:30, and make it exactly 60 seconds for Reels."

Agent 会自动执行：probe.py → cut.py –segments → fit.py –duration 60 –aspect 9:16 → export.py –preset reels → check.py，最后返回 final.mp4: 59.98s, 1080×1920, 30fps, AAC stereo 及缩略图。

使用场景与人群

  • 适用场景：本地视频剪辑自动化、自媒体批量内容生产、注重素材隐私不欲上云的剪辑工作流、需要 AI Agent 介入视频处理的 CI/CD 流水线
  • 目标用户：使用 Claude Code / Cursor / Codex 的开发者、自动化剪辑工作流构建者、注重隐私的本地视频处理用户

输入与输出案例

案例一：Reels 短视频剪辑

Input（用户告诉 Agent）：

“Take interview.mp4, keep 0:45–3:10 and 5:00–6:30, and make it exactly 60 seconds for Reels.”

Agent 内部执行链：
1. probe.py interview.mp4 → 获取真实 fps/resolution/codec
2. cut.py --segments 0:45-3:10,5:00-6:30 → 提取两段
3. fit.py --duration 60 --aspect 9:16 --fit crop → 裁剪适配竖屏
4. export.py --preset reels → 输出 9:16 预设
5. check.py --platform reels + look.py → 验证规格并生成缩略图

Output（Agent 回报）：

final.mp4: 59.98s, 1080×1920, 30fps, AAC stereo + contact sheet 缩略图

案例二：批量检查交付文件

Input：

“Run delivery check on the /exports folder.”

Agent 对每个文件执行 check.py，汇总格式兼容问题、码率异常、响度不达标清单，生成结构化 JSON 报告。

GitHub: https://github.com/kajisho5/ffmpeg-skill

评论区

0 条评论

登录后可评论。

Skill超级捕获手 1841 阅读