ffmpeg-skill

让 AI 代理本地剪视频，42 个 FFmpeg 工具开箱即用

开源 free 自动化工作流

访问官网 ↗ GitHub ↗ 文档 ↗

GitHub 星标 ★ 2014

维护状态活跃

是否开源是

定价模式 free

项目预览

项目数据

分类自动化工作流

开发团队kajisho5

所属国家

官网地址

GitHubhttps://github.com/kajisho5/ffmpeg-skill

定价模式free

价格说明开源免费，本地运行无需API密钥

访问状态

是否开源是

开源协议MIT

主要语言Python

技术栈/模型agent-skills,ai-agents,audio-processing,captions,claude-code,codex,coding-agent,cursor,ffmpeg,loudness-normalization,mcp,mcp-server,model-context-protocol,python,subtitles,transcoding,video,video-editing,video-processing,whisper

GitHub 星标★ 2014

30天Star增速

HF 下载量

上线时间2026-09-03 00:00:00

代码更新—

仓库体积—

本站数据更新—

维护状态活跃

中文支持

访问方式

移动端支持

综合评分

收录时间2026-10-20

浏览次数0

项目介绍

ffmpeg-skill 是一个面向编码智能体（Claude Code、Cursor、Codex 等）的本地视频编辑工具集，把 FFmpeg 的常用能力封装成 42 个带机器可读契约的工具，并通过 MCP 服务器暴露给 AI 代理调用。它解决的问题是：AI 代理虽然能写代码，但直接操作 FFmpeg 命令行容易参数出错、输出不可控，且缺少统一接口。项目提供结构化工具定义，让代理能可靠地完成剪辑、加字幕、画面重构图（横竖屏适配）、响度归一化和各平台导出等任务。核心能力包括：42 个工具覆盖剪切拼接、字幕烧录、音频处理、平台规格导出；机器可读契约让代理知道每个工具的参数与返回；MCP 服务器即插即用；全程本地运行，无需云服务、无需 API Key，视频不出本机。适合需要让 AI 代理批量处理视频的开发者与内容团队。

Star 增长趋势

本站每日记录该项目 GitHub 星标变化，观测越久曲线越完整

正在加载星标数据…

技术标签

使用教程

—

难度：入门约 10 分钟部署方式：本地安装 7 步

环境要求

Node.js/npm 环境（npx 安装方式需要；也可改用插件或手动复制）
本机已安装 FFmpeg：macOS 用 ffmpeg-full，Ubuntu/Debian 与 Windows 用常规包
一个支持 skill 或 MCP 的编码智能体（Claude Code、Cursor、Codex 等）
无需云服务、无需 API key，纯本地运行

安装与启动步骤

1装 FFmpeg(macOS)

必须装 ffmpeg-full，普通 ffmpeg 公式缺少 subtitles、drawtext、zscale 滤镜。
```
brew install ffmpeg-full
```
2装 FFmpeg(Linux/Win)

Ubuntu/Debian 执行此命令；Windows 改用 winget install Gyan.FFmpeg。
```
sudo apt install ffmpeg
```
3安装 skill

默认装给 Claude Code；Cursor 加 --cursor，Codex 加 --codex，全部装用 --all。
```
npx ffmpeg-skill
```
4插件方式安装

Claude Code 插件安装，无需 Node，后续用 claude plugin update 更新。
```
claude plugin install kajisho5/ffmpeg-skill
```
5手动复制安装

无 Node 时克隆仓库，把 SKILL.md、scripts/、references/、mcp/ 复制到智能体 skills 目录。
```
git clone https://github.com/kajisho5/ffmpeg-skill
```
6检查 FFmpeg 组件

确认 FFmpeg 必需组件齐全；加 --json 可看 ffmpeg_path 与 ffmpeg_source。
```
npx ffmpeg-skill doctor
```
7查看工具契约

打印智能体框架将看到的工具定义，即 42 个工具的参数与返回。
```
npx ffmpeg-skill contract --json
```

关键配置

配置项	必填	说明	示例
`PATH`	否	macOS 上让 ffmpeg-full 优先于精简版 ffmpeg 生效	`export PATH="$(brew --prefix ffmpeg-full)/bin:$PATH"`
`--dir`	否	自定义 skill 的安装目录	`npx ffmpeg-skill --dir ./my-skills`
`--project`	否	把 skill 装到当前项目而非用户目录	`npx ffmpeg-skill --project`
`--all`	否	一次装给 Claude Code、Cursor、Codex 三者	`npx ffmpeg-skill --all`
`--uninstall`	否	从已选目标中卸载 skill	`npx ffmpeg-skill --uninstall`

如何确认成功

运行 npx ffmpeg-skill doctor，输出显示所有必需 FFmpeg 组件齐全即安装成功。

常见问题

Q：安装时找不到 Node 怎么办？

A：npx 方式需要 Node；可改用 claude plugin install kajisho5/ffmpeg-skill，或克隆仓库手动复制 SKILL.md、scripts/、references/、mcp/。

Q：macOS 装了 ffmpeg-full，ffmpeg 还是精简版？

A：ffmpeg-full 是 keg-only 不会自动链接。可把它的 bin 加到 PATH，或执行 brew unlink ffmpeg 2>/dev/null; brew link --overwrite --force ffmpeg-full。

Q：Cursor 和 Codex 的 skill 装到哪里？

A：Cursor 装到 ~/.cursor/skills/ffmpeg-skill，Codex 装到 ~/.agents/skills/ffmpeg-skill（Cursor 也会读该位置）。

Q：需要联网或 API key 吗？

A：不需要。项目完全使用本地 FFmpeg，无云服务、无 API key，仅 Python 标准库实现。

Q：怎么卸载？

A：执行 npx ffmpeg-skill --uninstall，会从已选目标中移除；--codex 还会清理旧的 ~/.codex/skills 位置。

注意事项

macOS 普通 ffmpeg 公式缺少 subtitles、drawtext、zscale 滤镜，务必安装 ffmpeg-full。
用 brew link 方式链接 keg-only 公式会被 brew doctor 警告，且升级精简版 ffmpeg 后可能被覆盖，升级后需复查 command -v ffmpeg。
CI 已测试 FFmpeg 5.1、6.1、7.1、8、9 版本兼容性。
安装后可用 npx ffmpeg-skill doctor --json 查看实际使用的 ffmpeg 路径与来源。

核心亮点

42 个工具带机器可读契约，代理调用参数明确、结果可预期，减少命令行试错
通过 MCP 服务器接入 Claude Code、Cursor、Codex，配置简单即插即用
全程本地运行、无需 API Key 和云服务，视频素材不外传，隐私友好

不足之处

依赖本机安装 FFmpeg，环境配置对非技术用户仍有门槛
工具数量多但缺少端到端示例工作流，新手需自行组合
项目处于成长阶段，文档与社区生态待观察

适用场景

内容创作者让 Claude Code 批量把长视频切成短视频并加字幕导出
开发者用 Cursor 代理自动将横屏素材重构图适配竖屏平台
团队在本地对播客音频做响度归一化并生成多平台版本

替代项目

ffmpeg-python、moviepy

上一篇：doit

下一篇：没有了！