ffmpeg-skill

ffmpeg-skill是什么

ffmpeg-skill 是一个面向编程 Agent 的开源 Agent Skill，它让 Claude Code、Cursor、Codex 这类 AI 编程工具能够像专业剪辑师一样调用本地 FFmpeg 处理视频。它本身不是一个大模型，也不是一个带时间轴的图形界面剪辑软件，而是一份”工作剧本”加一组可执行脚本：SKILL.md 负责告诉 Agent 应该按什么流程走，脚本负责真正调用 ffmpeg 与 ffprobe 把活干完。

整个工具内置 28 个结构化工具，覆盖探测、剪切、拼接、字幕、调色、响度、多机位、批量导出等完整链路，并遵循”探测 → 编辑 → 检查 → 验证”的固定工作流。由于全部依赖都落在本地，它不需要任何云端服务、不需要 API Key，Python 部分只依赖标准库，素材也无需上传到任何服务器。

ffmpeg-skill 开源项目主页

ffmpeg-skill的主要功能

这 28 个工具可以按职能分成六大类，基本对应一条完整的视频生产流水线：

1. 探测与诊断：读取视频的真实元数据——时长、帧率（含可变帧率 VFR）、分辨率、旋转、色彩空间、HDR 格式与全部音轨，作为后续所有决策的依据；同时支持场景切换点检测、能力自检与机器可读契约输出。
2. 编辑处理：支持无损剪切、多段拼接、静音与气口剔除、按时长与画幅自动适配、精确裁剪与片段插入，特效同样在覆盖范围内。
3. 音频处理：提供人声清洗、音画同步（含漂移校正）与响度标准化，其中响度处理遵循 EBU R128 标准，适合播客与口播类内容统一听感。
4. 字幕与叠加：支持 SRT/ASS 字幕烧录，可调字体、描边与位置，还能做逐词动画与卡拉 OK 效果；另提供 Logo 水印、画中画、下三栏与进度条等动态图形渲染。
5. 调色与色彩管理：支持 HDR 到 SDR 的转换、LUT 套用与绿幕合成，处理不同来源素材的色彩一致性问题。
6. 交付与编排：内置主流社交媒体平台的导出预设，提供自动化质检与 HTML 交付报告生成，并通过工程渲染与批量处理支撑大规模素材的流水线作业。
7. 视觉审计：生成联络表（contact sheet）截图，让 Agent 能”亲眼”核对字幕有没有盖脸、Logo 位置对不对，把自动剪辑从”盲操作”变成”可复核”。
8. 契约化接口：所有工具均以 JSON 契约描述，且每个工具同时是一个 MCP 工具，与 MCP 生态兼容性良好，避免接口漂移。

ffmpeg-skill的设计原则

ffmpeg-skill 与普通”FFmpeg 命令速查表”最大的区别，在于几条规定得很死的工程原则：

1. 先探测，再动手：每个任务都从探测开始，Agent 必须基于实测的帧率、分辨率、色彩与音频布局做决策，而不是靠文件名猜测参数。
2. 能无损就不重编码：简单剪切与拼接优先走流复制，只在需要帧精确、或滤镜时才重新编码，并如实回报精度情况。
3. 不做 shell 拼接：每个操作都是有类型化参数的脚本，不接受调用方传入的滤镜字符串，规避命令注入与参数漂移。
4. 执行后必须验证：输出文件会被重新探测、按目标平台规格检查；画面发生变化时还会生成联络表截图供人工或 Agent 复核。
5. 纯本地、零费用：数据不离机，不产生任何 API 调用费用，也不引入第三方依赖。

如何使用ffmpeg-skill

ffmpeg-skill 仓库中的安装与使用说明

部署过程被压缩到了极致，一条命令即可完成安装：

1. 安装 Skill：在终端执行 npx ffmpeg-skill，默认安装到 Claude Code 的技能目录；Cursor 使用 npx ffmpeg-skill –cursor，Codex 使用 npx ffmpeg-skill –codex，三个都装可用 npx ffmpeg-skill –all；只想给当前项目安装则用 npx ffmpeg-skill –project。
2. 环境自检：首次使用建议先跑 npx ffmpeg-skill doctor，检查本机 ffmpeg、ffprobe 以及各工具所需的编码器与滤镜是否齐全，按提示补齐缺失组件。
3. 确认运行环境：需要 FFmpeg 5.0 以上、Python 3.9 以上，Node 仅用于安装器本身。若本机没有 Node，也可以直接克隆仓库，把 SKILL.md、scripts、references 与 mcp 目录复制到 Agent 的技能目录。
4. 用自然语言下指令：安装后直接在对话里描述需求，例如”把这段采访的 0:45–3:10 和 5:00–6:30 剪出来，做成 60 秒的 9:16 竖版”，Agent 会自行走完探测、剪切、画幅适配、字幕、导出与验证的完整链路。
5. 查看机器可读契约：需要与其他 Agent 框架对接时，可执行 npx ffmpeg-skill contract –json 查看每个工具的输入、输出、依赖与验证方式。
6. 脱离 Agent 单独使用：脚本本身也可直接调用，配合 –dry-run（只打印将执行的命令不碰文件）与 –json（输出结构化结果）进行调试与集成。

ffmpeg-skill的使用场景

只要你的工作流里存在”重复、规则明确、需要可复现”的视频处理环节，ffmpeg-skill 就能派上用场：

1. 播客与访谈精剪：自动检测并剔除静音与气口，把响度统一到 EBU R128 标准，将数小时素材快速压缩为节奏紧凑的精华片段。
2. 短视频多平台分发：把长视频拆解为符合 TikTok、Reels 等规格的短片，自动完成字幕烧录与竖屏适配，一次处理多处投放。
3. 多机位后制：处理会议录像或教学录制，实现多机位切换、音画对齐与动态字幕添加；若素材需要进一步压缩分发，可与 视频压缩工具 配合使用。
4. Vlog 与日常出片：依据素材参数自动执行防抖、高光选取与配乐，把原始素材到成片的过程尽量自动化。
5. 批量素材处理：对整个文件夹执行统一的静音去除、响度归一与导出预设，配合内容哈希缓存，第二轮只处理新增文件，非常适合活动、课程这类成批素材。若你的诉求更偏向体积压缩，也可以对比 rotato视频压缩。
6. AI 视频链路的后处理：当视频由生成式工具产出、还需要加字幕、统一响度或转码交付时，可以用它做自动化收尾，与 免费AI生成视频 这类工具形成前后工序。

ffmpeg-skill与其他方案的差异

同样是”让 AI 用上 FFmpeg”，不同实现的工程化程度差别明显：

ffmpeg-skill的常见问题解答

ffmpeg-skill 需要付费或申请 API Key 吗？

不需要。它完全在本地运行，不调用任何云端接口，也不要求注册账号，只要本机装有 FFmpeg 与 Python 即可使用，处理过程中素材不会离开你的电脑。

为什么安装后第一步要跑 doctor？

因为不同渠道安装的 FFmpeg 编译选项差异很大，部分精简版本并不包含字幕、绘制文字或色彩转换等滤镜。doctor 会逐项检查各工具所需组件是否齐备并明确报告缺失项，提前跑一遍能避免任务执行到一半才报错。

ffmpeg-skill 能自动决定”剪哪里””挑哪段高光”吗？

不能，它明确定位为执行引擎而非创意大脑。它负责把已经明确的参数准确执行、并在完成后给出可核验的结果；至于剪辑点选择、成片审美判断，仍由使用者或上层的 AI 编排逻辑决定。

ffmpeg-skill官网网址

ffmpeg-skill 已在 npm 与 GitHub 公开发布，可通过以下入口获取：

• npm 包主页：https://www.npmjs.com/package/ffmpeg-skill
• 源码仓库：https://github.com/kajisho5/ffmpeg-skill
• 安装命令：npx ffmpeg-skill
• 环境自检命令：npx ffmpeg-skill doctor

OpenI AI时代点评

ffmpeg-skill 真正解决的不是”FFmpeg 能不能做”的问题，而是”AI 能不能稳定地让 FFmpeg 做对”。它把度很高的命令生成，收敛成一组受约束、带类型、可验证的脚本调用：先探测再决策，能流复制就不重编码，做完必须复测并留下联络表截图。对于需要把视频处理嵌进自动化管线、又对素材隐私和成本敏感的团队，这种”工程化护栏”比多几个花哨功能更有价值。

选型时也要认清边界：它不会替你做创意判断，适合的是规则明确、需要可复现结果的批量任务。如果你的场景更偏向从零生成视频内容，可以看看 即梦 AI（Seedance 视频）、阶跃视频 或 绘蛙AI生图/视频；若要安装使用 ffmpeg-skill，请访问 ffmpeg-skill 仓库 获取最新版本与完整文档。