别只拿 AI 写文案了:剪视频、加字幕,这个开源工具也能做

344次阅读
没有评论

共计 6292 个字符,预计需要花费 16 分钟才能阅读完成。

ffmpeg-skill 是一套给编程助手用的本地视频剪辑工具,仓库在 kajisho5/ffmpeg-skill,许可证是 MIT。它要做的事情很具体:你可以把素材交给 Claude Code、Cursor 或 Codex,让助手在你自己的电脑上剪切、改画幅、烧字幕、调响度,再按短视频平台的规格检查一遍。文件不用传到云上,也不用申请 API 密钥。

2026 年 11 月 18 日早上 7 点 52 分(北京时间),我看 GitHub 的 Python 日榜,它排在第 8,页面写着当天加了 1,376 星。同一时间用 GitHub 接口读到总星数 7,732。最新正式版是 3.10.1,GitHub Release 的时间换算过来是 11 月 16 日 07:32,npm 上的 latest 也是这个版本。

有人问我,能不能让 Cursor 在本地把一条横屏口播剪成竖屏。今早我在 Linux 测试机上装了 3.10.1,用一条自己生成的 18 秒演示片走了一遍。裁成 9:16 的时候,我选了裁切来填满画面,原片正中间那行标题左右被切掉了;后来另外烧进去的字幕是完整的。下面按我当时做的选择写。

🍎 实测环境:Linux 测试机,ffmpeg 和 ffprobe 都是 7.1.5-0+deb13u1,Python 3.13.5,Node.js 24.22.1(只用它跑安装器)。工具装在一个项目目录里,没有写入默认的技能文件夹。演示片是 ffmpeg 生成的色块加正弦音,不是真人出镜。自动听写要用的 whisper 或 Parakeet,这台机器上没有装。Windows 和 macOS 的安装命令来自官方文档,我没在这两个系统上跑过。

先探测真实参数 → 按片段剪切 → 改画幅 → 烧字幕 → 调响度 → 按平台自检

别只拿 AI 写文案了:剪视频、加字幕,这个开源工具也能做

▲ 这次走过的顺序:探测 → 剪切 → 画幅 → 字幕 → 响度 → 自检

PART 01

它到底替助手做哪些事

让编程助手直接拼 ffmpeg 命令,常见的结果是:没看源文件就按 30 帧去猜,能拷贝的流也整段重编码,渲染完也不打开看一眼。ffmpeg-skill 把能做的事收窄了。每个操作是一个参数固定的 Python 脚本,不接受你塞进来的滤镜串,也不把命令交给 shell 去执行。

官方 README 里写的工作顺序是:先用 probe.py 读真实时长、帧率、分辨率和音频布局,能不重编码就先走流拷贝,改之前可以用 --dry-run --json 先看计划,改完再用 check.py 对照平台规格、用 look.py 导出一页分镜图检查画面。仓库里还有一份 contract --json,把每个工具的输入、输出和校验方式写清楚;MCP 的工具列表就是从这份契约生成的。

3.10.1 这一份里,公开工具是 42 个。MCP 默认只列出 12 个常用的,免得一次把整份说明书塞进上下文;其余的仍可以按名字调用,把环境变量 FFMPEG_SKILL_MCP_FULL=1 打开才会在列表里显示全部。

它也不是剪辑软件的替代品。时间线调色、多机位的精细切换、自动追着人脸构图,这些它都不做。fit.py 的结果里会留下 unverified: subject_framing,意思很直白:画幅改完了,主体有没有被切到,它不负责判断,得你自己看那张分镜图。

PART 02

安装:我没写进默认目录

官方给的最快路径是这条:

# 0. 本机先有 ffmpeg(Ubuntu / Debian)
sudo apt install ffmpeg
# 1. 默认装进 Claude Code 的技能目录 ~/.claude/skills/ffmpeg-skill
npx ffmpeg-skill
# Cursor 用 --cursor,Codex 用 --codex,三个都装用 --all
npx ffmpeg-skill --cursor

我这台机器上已经有 ffmpeg 7.1.5,这一步跳过了。为了测完能整目录删掉,我没有用默认位置,而是把 3.10.1 装到了项目目录:

npx ffmpeg-skill@3.10.1 --dir ./skills

安装器打印的是 installed custom: ./skills/ffmpeg-skill,并确认找到了本机的 ffmpeg 7.1.5。整个过程大约半秒。装好以后,脚本在 ./skills/ffmpeg-skill/scripts 下面,模板在 templates 里,一共 10 份,包括 shorts、reels、tiktok、youtube、x 等。后面的命令里,我把脚本目录写成 $S。

🍎 macOS 上官方要求装 brew install ffmpeg-full。普通的 ffmpeg 公式会缺 subtitles、drawtext、zscale 这些滤镜,字幕和部分画幅工具会跑不起来。Windows 官方写的是 winget install Gyan.FFmpeg。这两条我都没实测。

不想用 Node 的话,官方也允许克隆仓库,只拷 SKILL.md、scripts/、templates/、mcp/ 等技能运行需要的那几项。不要把 docs/ 里那些演示 GIF 一起拷走,README 说那大约有 14 MB,工具运行时不会读。

PART 03

先让 doctor 看这台机器

安装器自己不会保证每个工具都能跑。官方的下一步是:

npx ffmpeg-skill doctor

我这边的输出是:ffmpeg-skill 3.10.1,Python 3.13.5,ffmpeg 和 ffprobe 都是 7.1.5-0+deb13u1。总结果 ok: 86 capabilities available, 0 required missing, 2 optional missing。缺的两项可选能力是 external:parakeet 和 external:whisper,也就是本地语音转写。42 个工具的 usable 全部是 yes。

别只拿 AI 写文案了:剪视频、加字幕,这个开源工具也能做

▲ 2026 年 11 月 18 日 07:54(北京时间)在 Linux 测试机上跑 npx ffmpeg-skill doctor 的结果。路径已隐去。

doctor 还提了一句安全提示:本机的 7.1.5-0+deb13u1,比上游第一份修复 CVE-2026-8461 的发行版要旧。这条漏洞在 MagicYUV 解码器,CVSS 8.8;提示里写明,7.1 分支没有列出带修复的版本,最早写明修好的是 8.0.3,并特别说明发行版有可能已经回补补丁,所以这不能证明当前这个包一定有漏洞。来源是 FFmpeg 安全页,skill 里标注的核对日期是 2026-10-22。我没有据此升级系统里的 ffmpeg。

中文字体方面,doctor 确认本机可以渲染汉字,后面烧字幕时指定 Noto Sans CJK SC,实际解析到了 /usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc,没有被换字体。

硬件编码这边,hw.platform_ok 是 false。README 写得很清楚:--hw 目前是 Apple Silicon 上的 VideoToolbox,这台 Linux 机器就算编出器列表里出现了名字,默认也不会走 GPU。我没有加 --hw。

PART 04

一条 18 秒演示片,我决定留下哪几段

我没有拿现成的口播去试,免得版权和隐私说不清。用 ffmpeg 做了一条 18 秒、1920×1080、30 帧的横屏演示片:五段色块,中间叠一行中文,有声音的段落用正弦音,两段废镜头是静音。

probe.py 读到的数字是:时长 18.021 秒,画面 1920×1080,30 fps,编码 H.264 + AAC 立体声 48 kHz,文件 319,295 字节。视频流自己的时长是 18.0 秒,540 帧。

别只拿 AI 写文案了:剪视频、加字幕,这个开源工具也能做

▲ 原片时间线。红框是准备丢掉的两段静音废镜头,保留 0–5 秒、8–14 秒、16–18 秒。

接下来是一次选择。cut.py 默认优先流拷贝,切点会靠到关键帧;要更准,就加 --accurate,代价是重编码。我要的是整秒切点,选了 --accurate:

python3 $S/cut.py source.mp4 --segments 0-5,8-14,16-18 --accurate --json -o cut.mp4

先 --dry-run,计划里的预期时长是 13.0 秒,reencode_reason 写的是 requested,也就是我自己要求的精确模式,不是它判断拷贝不了。真正跑完用了 2.819 秒,输出 13.04 秒(画面 13.0 秒、390 帧,音频 13.04 秒),和预期差 0.04 秒。校验结果是 verified: true,允许误差是 0.25 秒,这次远小于这个值。

PART 05

裁成 9:16 时,我选了 crop,原片上的字被切掉了

shorts 模板的默认画幅是 1080×1920,拟合方式是 crop。fit.py 自己也提供 pad(留边)和 blur(模糊填充)。我按模板的默认走了裁切,想看看一口填满竖屏会怎样:

python3 $S/fit.py cut.mp4 --aspect 9:16 --fit crop --width 1080 --json -o fit.mp4

2.593 秒后得到 1080×1920、13.056 秒、390 帧的竖屏文件。JSON 里写得很清楚:左右各裁掉 656 像素,再放大 1.7792 倍。verified 是 true,但 unverified 里留着 subject_framing。

打开成品才看见后果。原片正中间那行「开场:先说今天做哪三步」是按 16:9 居中排的,左右一裁,变成了「场:先说今天做哪三」。两边的字没了。

别只拿 AI 写文案了:剪视频、加字幕,这个开源工具也能做

▲ 同一时刻的画面。① 原片标题完整;② 裁切后左右缺字;③ 后来烧进去的字幕是完整的。

别只拿 AI 写文案了:剪视频、加字幕,这个开源工具也能做

▲ 三种拟合方式。这次成品走的是 crop,左右各裁了 656 像素。

如果重要信息写在画面两侧,或者像我这样把一行标题拉得很宽,crop 就会切到字。pad 能保住完整画面,但上下或左右会留边;blur 是把裁掉的边缘做模糊背景,主体仍按竖屏放大,四周不会空,字会不会被切,还是要看主体本身有多宽。这三种我只把 crop 跑到了成品,另外两种没有做对照导出。

look.py 可以把视频抽成一页分镜,并按平台安全区涂暗。我让它按 shorts 的安全区来画:

python3 $S/look.py final.mp4 --tiles 3x3 --safe shorts -o look-final.png

输出是一张 1286×2282 的 PNG,九宫格上有时间码。涂暗的是 shorts 界面可能挡住的上下左右,中间被裁断的原片标题,和下方两行完整字幕,都看得很清楚。SKILL.md 要求助手改过画面之后必须看这张图再汇报;我没有把工具接到某个已登录的 Cursor 或 Claude Code 里自动跑,是自己在终端里看的。

别只拿 AI 写文案了:剪视频、加字幕,这个开源工具也能做

▲ look.py --tiles 3x3 --safe shorts 的输出。安全区是工具画的,不是我后加的。

PART 06

字幕、响度,以及对着 shorts 做自检

本机没有 whisper 或 Parakeet,--transcribe 这条路我没走。官方的办法是自己准备时间轴文本。我按剪完之后的时间写了三行:

0:00-0:05 开场:先说今天做哪三步
0:05-0:11 中间:打开软件看这一步
0:11-0:13 收尾:导出之前先自检

然后:

python3 $S/caption.py fit.mp4 --text cues.txt --animate pop --platform shorts --font "Noto Sans CJK SC" --json -o caption.mp4

2.042 秒完成。结果里 cues_burned 是 3,cues_outside 是 0,字体按我指定的名字解析成功,没有替换。字号我请它按 24 来,实际用了 22,JSON 写的是为了在画面里放下而缩小了 2。unverified 里仍有 rendered_placement 和 legibility:位置好不好看、好不好认,还是要看分镜图,工具不替你打分。

响度这一步把目标定在 -14 LUFS、真峰值不超过 -1 dBTP,和 shorts 模板一致:

python3 $S/loudness.py caption.mp4 -I -14 --tp -1 --json -o final.mp4

输入测到的是 -21.63 LUFS、真峰值 -20.17 dBTP,偏安静,这是正弦测试音的实际情况。1.655 秒后,成品是 -14.02 LUFS、真峰值 -12.53 dBTP,时长仍是 13.056 秒。这一步的视频编码器写的是 copy,只重编码了音频。文件 645,880 字节。

检查这一步,我对着 YouTube Shorts 的规格表跑:

python3 $S/check.py final.mp4 --platform shorts --json

结果是 ok: true,失败 0 条,提醒 1 条。时长、画幅 9:16、分辨率 1080×1920、30 帧、H.264、响度 -14.0 LUFS、真峰值 -12.5 dBTP 都是 PASS。那条 WARN 是 subtitles: none:规格表希望有一条可开关的字幕轨,而我把字幕烧进画面了,自然没有软字幕轨。提醒里给的修法是再用 caption.py --mode mux 加一条软字幕。对我这次的目标来说,烧进去就可以,我没有再做一条可开关的轨。

别只拿 AI 写文案了:剪视频、加字幕,这个开源工具也能做

▲ check.py --platform shorts 的结果摘录。数字来自这次实测的 JSON。

另外还有一条没真正跑完的路。render.py --template shorts --cues cues.txt 可以把剪切之后的拟合、字幕、响度、导出和检查串成一次。我只加了 --dry-run,计划里会出现 clips、fit、captions、loudness、export 这些阶段,命令共 10 条,大约 1.4 秒给出计划。因为我想看清每一步的 JSON,成品是按上面的脚本逐步跑出来的,模板这一条没有真正写出文件。

MCP 我在终端里试了两下,没有接到桌面里的助手。python3 mcp/server.py --list 列出 12 个核心工具:audio、caption、check、cut、export、fit、graphics、look、loudness、probe、render、silence。用 --call probe,并传入 {"inputs":["source.mp4"]},返回的时长是 18.021333 秒,和直接跑 probe.py 一致。我第一次把参数写成 input,被拒绝了,提示里没有这个参数名,改成 inputs 才通过。

我没跑过的,以及用完怎么收

没做的事情需要说清楚。我没有把 skill 接到已登录的 Cursor、Claude Code 或 Codex 里,让助手自己读 SKILL.md 再挑选工具;所以「对助手说一句话,它就能剪完」这件事,我不能写成已经验证。--transcribe 自动听写没测。pad 和 blur 只在文档里对照过,没有导出对照文件。HDR 转 SDR、多机位、--hw 硬件编码,都没有跑。完整的仓库测试套件我也没有跑。

如果只是试用,装到项目目录的那份可以直接删掉整个文件夹。默认装进 ~/.claude/skills/ffmpeg-skill 或 ~/.cursor/skills/ffmpeg-skill 的,官方提供:

npx ffmpeg-skill --uninstall
npx ffmpeg-skill --cursor --uninstall

这次没有往这两个默认目录里写文件,也没有启动后台服务,没有把端口绑到本机以外。

相关阅读:如果想给编程助手接上浏览器里的开发者工具,可以看站内这篇 Chrome DevTools MCP 实测;如果想在没有显卡的电脑上本地跑小模型,可以看 llama.cpp 1.0 实测。

参考来源(官方):kajisho5/ffmpeg-skill、npm 上的 ffmpeg-skill 3.10.1、v3.10.1 Release。

正文完
 0

版权声明:除特殊说明外本站文章皆由CC-4.0协议发布,转载请注明出处。

科技喵仔
版权声明:本站原创文章,由 科技喵仔 于2026-11-18发表,共计6292字。
转载说明:除特殊说明外本站文章皆由CC-4.0协议发布,转载请注明出处。
评论(没有评论)
验证码
    中文English