ffmpeg-skill Skill 技能

技能简介

ffmpeg-skill 是一款专为 AI 编程智能体打造的本地视频处理技能包。它把 FFmpeg 与 ffprobe 的强大媒体处理能力，封装成 42 个结构化工具，让 Claude Code、Cursor、Codex 等主流编程智能体直接"获得一个视频剪辑器"。你只需用自然语言描述需求，智能体便会调用 probe、cut、fit、caption、export 等工具完成裁剪、拼接、转码、加字幕、适配平台比例等操作。

该技能完全本地运行，无需云服务、无需 API Key、不依赖任何第三方 Python 库，只要机器上装了 ffmpeg 和 python3 即可工作，天然适合处理不宜上传的私密素材。项目在 GitHub 已获 1214 星，月下载量超过 1.2 万次，处于活跃维护状态。

核心能力

• 结构化工具集：提供 42 个独立脚本工具，覆盖剪辑（cut/join）、静音去除（silence）、时长与比例适配（fit）、字幕与卡拉 OK（caption）、叠加层与动态图形、HDR 转 SDR 与 LUT 调色、音频清理与动态处理、多机位、响度归一化、交付检查、整片项目渲染、批量文件夹处理等。
• 先探测后编辑：每个任务都从 probe.py 开始，智能体依据实测的时长、帧率、分辨率、色彩与音频布局做决策，而不是靠文件名猜测。
• 无损优先：cut、join、loudness 在无需改动时会直接做流复制（stream copy），仅在必须时才重新编码，最大限度保留画质。
• 执行后验证：结果会被再次探测，并与目标平台规格比对；画面发生变化时还会生成联系表（contact sheet）供智能体"亲眼确认"。
• MCP 原生支持：所有工具同时可作为 MCP 工具调用，默认向客户端暴露 12 个核心工具以控制上下文占用，设置 FFMPEG_SKILL_MCP_FULL=1 可列出全部 42 个。
• 平台模板：内置 tiktok、reels、shorts、youtube、linkedin、facebook、podcast 等交付模板，一键适配各平台比例、字幕安全区与响度标准。

安装配置

1. 安装技能：运行 npx ffmpeg-skill 即可为 Claude Code 安装（Cursor 加 --cursor，Codex 加 --codex，三者都要则加 --all）。
2. 环境自检：运行 npx ffmpeg-skill doctor 检查机器上的 ffmpeg、ffprobe 以及各工具所需组件是否齐全。
3. 读取契约：运行 npx ffmpeg-skill contract --json 获取机器可读的工具契约，agent 框架可据此自动对接。
4. 前置要求：需本机已安装 ffmpeg 与 python3；无需 API Key、无需联网、无需额外 Python 依赖。

使用步骤

1. 在终端运行 npx ffmpeg-skill 完成技能安装，并执行 doctor 确认环境可用。
2. 直接用自然语言向智能体下达剪辑指令，例如"把 interview.mp4 保留 0:45–3:10 和 5:00–6:30，做成正好 60 秒的 Reels 视频"。
3. 智能体会自动依次调用 probe.py → cut.py → fit.py → export.py → check.py → look.py，完成探测、裁剪、适配、导出、检查与目视核验。
4. 智能体回报最终结果，例如"final.mp4：59.98 秒，1080×1920，30fps，AAC 立体声"，并附上它检查过的联系表。
5. 如需交付特定平台，可执行 python3 render.py talk.mp4 --template tiktok --cues cues.txt，一次性生成符合该平台规格的成品。

适用场景

• 短视频批量制作：将长视频快速裁剪、转比例并加字幕，批量产出适配抖音、Reels、Shorts 的竖版内容。
• 播客与访谈精剪：自动去除静音段、统一响度、生成带卡拉 OK 高亮的动态字幕。
• 多平台一键分发：用同一份剪辑通过 --template all 渲染出各平台版本，并生成产出对照表。
• 私密素材处理：素材不出本机、不经过云端，适合涉密或版权敏感的视频加工。

适用人群

视频创作者、播客主播、社媒运营者，以及任何希望在 AI 编程助手内直接完成视频后期、不想被复杂 FFmpeg 命令困扰的开发者。

工作原理

技能通过 SKILL.md 向智能体灌输固定工作流（探测 → 尽量无损编辑 → 检查 → 验证），并附带 42 个带类型化参数的 Python 脚本执行实际工作。每个工具的输入 schema（即需与 CLI 参数一一对应的契约部分）并非手写，而是在运行时从定义 CLI 的同一个 argparse 解析器自动派生，CI 会在契约漂移时使构建失败，从而保证 MCP 工具定义与 CLI 始终一致。

官方链接

• GitHub：https://github.com/kajisho5/ffmpeg-skill
• npm：https://www.npmjs.com/package/ffmpeg-skill