Claude Code 剪视频,不上传、不要 API Key

Agent 剪完视频,会先量一遍、再看一眼成品。

摘要

ffmpeg-skill 把 42 个本地 FFmpeg 工具打包成一个 Agent Skill,Claude Code、Cursor、Codex 都能直接调用。剪辑、字幕、竖屏改版、响度、平台导出全在本机完成,不用云端,也不用 API Key。

核心优势

让 AI 剪视频,常见翻车点是"以为自己会 FFmpeg":臆测帧率、选了容器装不下的编码、只需要流拷贝却整段重编码,最后没打开成品就说"完成"。这个项目把这些猜测一项项拿掉:

  • 先测量再动手 :每个任务从 probe.py 开始,时长、帧率、分辨率、色彩、音轨布局都按实测值决策,而不是看文件名。
  • 结构化工具,不是 shell 拼接:每个操作是一个带类型参数的脚本,不经过 shell,也不接受调用方传入的滤镜图。
  • 机器可读的契约 :contract --json 说明每个工具的输入、输出、所需 FFmpeg 组件和验证方式,MCP 接口就是从它派生的,参数不会和脚本脱节。
  • 做完要验收 :成品会被再次 probe,对照目标平台规格检查,画面有变化时还会用 look.py 生成联系表,让 Agent 亲眼看一遍。
  • 能无损就无损 :cut.py、loudness.py 对不需要改动的流直接拷贝,不重编码;所有工具都不覆盖原文件。

整个项目只依赖 Python 3.10+ 标准库,没有第三方 Python 依赖,视频也不用离开你的电脑。

面向人群

  • 已经在用 Claude Code、Cursor 或 Codex,想让 Agent 直接处理本地素材的开发者
  • 要批量把长视频切成竖屏短视频、统一响度的内容创作者
  • 不想把访谈、会议录像上传到云端剪辑服务的人
  • 在搭 Agent 工作流,需要一套"参数可读、结果可验"的剪辑工具层的工程师

快速上手

先装 FFmpeg(项目要求 6.1 及以上),再一行命令安装 Skill(npx 安装器需要 Node 16+):

bash 复制代码
# 0. 装 FFmpeg(Ubuntu/Debian 示例)
sudo apt install ffmpeg
# macOS 要装 ffmpeg-full:普通的 ffmpeg 缺 subtitles、drawtext 滤镜,烧字幕会用不了
# brew install ffmpeg-full

# 1. 为 Claude Code 安装(Cursor 加 --cursor,Codex 加 --codex)
npx ffmpeg-skill

# 2. 体检:ffmpeg、ffprobe 以及各工具需要的组件是否齐全
npx ffmpeg-skill doctor

# 3. 读取机器可读契约
npx ffmpeg-skill contract --json | head -40

装好之后,直接对 Agent 说人话:

把 interview.mp4 里 0:45--3:10 和 5:00--6:30 留下,剪成正好 60 秒的竖屏版。

Agent 会依次跑 probe.py、cut.py --segments 0:45-3:10,5:00-6:30、fit.py --duration 60 --aspect 9:16 --fit crop、export.py --preset reels 和 check.py --platform reels,画面有改动时再用 look.py 看一眼,最后汇报实测结果:59.98 秒、1080×1920、30 fps。

这些工具也能脱离 Agent,在命令行里单独用:

bash 复制代码
S=~/.claude/skills/ffmpeg-skill/scripts
python3 $S/probe.py input.mp4 --compact
python3 $S/fit.py input.mp4 --duration 60 --aspect 9:16 --dry-run   # 只打印计划,不执行
python3 $S/export.py input.mp4 --preset reels --json                # 输出带成品 probe 的结构化结果

每个工具都支持 --dry-run(只打印 ffmpeg 命令,不写文件)和 --json,失败时以非零退出码加原因退出。

进阶用法

一条命令交付到平台。 render.py 配合模板,把裁切、字幕、响度、导出预设和最终检查串成一步:

bash 复制代码
python3 $S/render.py talk.mp4 --template tiktok --cues cues.txt

模板会做 9:16 裁切,把逐字弹出的字幕放在平台描述栏之上、避开点赞栏,同时按预设响度处理,并对写出的文件跑一次平台检查。

字幕与去静音。 caption.py 能烧录 SRT/ASS,也能封装成软字幕轨,字号按平台安全区自动适配,并选用覆盖中日韩等文字的字体;需要语音转写时,装一个本地引擎即可,最简单的是 pip install faster-whisper,音频不出本机。silence.py 负责剪掉冷场,两侧默认各留 0.2 秒余量。项目在 20 个已知静音段的测试文件上做过验证:没有漏检,残留静音最多 1 毫秒。

接入 MCP。 在 MCP 客户端里加一段配置,指向 mcp/server.py,工具列表在启动时从契约派生。默认只列出核心的 12 个工具(省上下文),其余 30 个仍可按名字直接调用,设 FFMPEG_SKILL_MCP_FULL=1 则全部列出;另外还提供 reel、podcast、multicam、delivery_check、hdr 五个现成的工作流提示。

边界要心里有数。 验证只覆盖"能测量的部分":画面内容、主体构图、字幕的实际位置和可读性,工具会在 unverified 里明说没测,所以动过画面之后一定要看联系表。它也没法真正"抹掉"移动的水印或位置会变的烧录字幕(只能用 redact.py 处理位置固定的矩形区域),不做人脸或主体自动追踪,GPU 编码目前只支持 Apple Silicon 的 VideoToolbox,而且要加 --hw 手动开启。

项目地址:github.com/kajisho5/ffmpeg-skill

收藏清单

  • 先装 FFmpeg 6.1+(macOS 用 ffmpeg-full)、Python 3.10+ 和 Node 16+,再 npx ffmpeg-skill
  • 装完先跑 npx ffmpeg-skill doctor,缺哪个组件一目了然
  • 让 Agent 先 --dry-run 看计划,再真正执行
  • 动过画面的成品,必看 look.py 的联系表
  • 报告里 unverified 列出的项,要自己亲眼确认
相关推荐
stormzhangV23 分钟前
Coding Agent,通往 AGI 的重要一环
人工智能·agent·ai编程
伯奥克客服1 小时前
2026年视频综合一体机架构选型:从接口协议到流媒体底层的深度技术解析
架构·音视频
Bowen_J2 小时前
Apple Foundation Models:Apple AI核心框架
人工智能·ai编程·apple
如夏倾城2 小时前
VRRP(虚拟路由器冗余协议Virtual Router Redundancy Protocol)
网络·python·网络协议·安全·智能路由器·负载均衡·信息与通信
IT_陈寒2 小时前
Redis那个过期删除策略,差点让我线上崩了
前端·人工智能·后端
IvanCodes2 小时前
LangChain(04):Runnable 与 LCEL 的执行与组合机制
python·langchain·agent
阿里云大数据AI技术2 小时前
AI 原生大数据服务 ADA 快速入门:完成首次对话式数据分析
大数据·人工智能
特创数字科技2 小时前
纯本地离线运行的文档脱敏工具(技术分享)
前端·驱动开发·python
字节跳动开源2 小时前
小红书/抖音图文排版利器——一个杂志风skill
人工智能·开源·设计