用 ffmpeg-skill 一条命令交付 Instagram Reels:9:16 竖屏、-14 LUFS 与平台自检实战
用 ffmpeg-skill 一条命令交付 Instagram Reels:9:16 竖屏、-14 LUFS 与平台自检实战
本文以仓库中一次真实评测运行记录 run.md 为线索,复盘 ffmpeg-skill 的 render.py --template reels 如何把一条 1280x720 的横屏素材,变成 1080x1920、30 fps、H.264/AAC、-14 LUFS 的 Reels 交付文件,并解释每一步背后的实现依据。读完后你能独立完成"探测 → 声明式渲染 → 阶段流水线 → 平台检查 → 画面复核"的完整交付,并知道遇到只读输出、字幕 WARN、中心裁切风险时该如何处理。
一、这次运行到底做了什么
记录中的任务来自评测用例 ow2:把 talk.mp4 做成 9:16 的 Reels 版本,而素材目录里已经存在一个 talk_vertical.mp4。评测的判定证据写在 iteration-24.json 中:render.py --template reels 写出了新文件 talk_reels.mp4,原有 talk_vertical.mp4 的 md5 未变,并且最终回复明确点名了这个未被触碰的文件。
整个运行只有三条命令:
python3 /home/user/ffmpeg-skill/scripts/probe.py talk.mp4 --json
python3 /home/user/ffmpeg-skill/scripts/render.py --template reels talk.mp4 -o talk_reels.mp4 --json
python3 /home/user/ffmpeg-skill/scripts/look.py talk_reels.mp4 --tiles 3x2
对应到本仓库,脚本位于 scripts/probe.py、scripts/render.py、scripts/look.py。记录里的 /home/user/ffmpeg-skill 是评测沙箱中的技能目录,本地运行时替换为你自己的仓库路径即可。
这条链路之所以值得单独成文,是因为它同时覆盖了 ffmpeg-skill 的三个设计主张:先测量再动手、一次声明完成多阶段渲染、交付必须被平台规格验证而不是"看起来没错"。
二、第一步:probe 先拿到真实数字
python3 scripts/probe.py talk.mp4 --json
记录中的关键输出是:1280x720(16:9)、30 fps、H.264 视频 + AAC 单声道音频、时长 10.0 s。
这一步不是形式主义。后续所有决策都建立在这些数字上:
- 16:9 → 9:16 意味着必须重构图,不是简单缩放,因为两种画幅没有包含关系;
- 源已经是 30 fps,因此最终交付声明"30 fps constant"时并没有做变速,只做了帧率一致性确认;
- 10 s 远低于 Reels 的上限,所以模板不会触发时长裁剪逻辑;
- 音频是单声道,因此最终 AAC 仍是 mono,平台检查也不会因为声道数报警(
check.py的channels行允许 1 或 2 声道,见 scripts/check.py)。
SKILL.md 的工作流把这一步列为第 1 条("Probe what you plan from;plan from real numbers, never assumptions"),见 SKILL.md。
三、核心命令:--template reels 等价于一份完整工程
python3 scripts/render.py --template reels talk.mp4 -o talk_reels.mp4 --json
--template NAME INPUT 是 render.py 的"一次性交付"入口:它把 templates/<name>.json 当作工程模板,用命令行参数填充占位符,然后走与手写 project.json 完全相同的阶段流水线。不带 -o 时,输出落在输入旁边、命名为 <输入名>_<模板名>.mp4,规则见 scripts/render.py——所以这次即使省略 -o,也会得到 talk_reels.mp4。
3.1 模板长什么样
Reels 模板本体只有 47 行,见 templates/reels.json:
{
"template": "reels",
"output": "$OUTPUT",
"clips": [{ "src": "$INPUT" }],
"frame": { "aspect": "9:16", "fit": "crop" },
"brand": "$BRAND",
"captions": {
"text": "$CUES",
"animate": "pop",
"karaoke": true,
"size": 24,
"position": "bottom",
"margin": 58
},
"graphics": [{ "template": "hook", "title": "$TITLE", "start": 0, "end": 3 }],
"overlays": [{ "image": "$LOGO", "position": "top-left" }],
"loudness": { "lufs": -14, "tp": -1.0 },
"export": { "preset": "reels", "normalize": true },
"check": { "platform": "reels" }
}
三个关键点:
- 占位符是"要么填、要么整块丢弃"。
$CUES、$LOGO、$TITLE、$BRAND分别由--cues(或--srt)、--logo、--title、--brand提供。fill_template()在某个占位符没有值时,会让整个块被判为不完整并删除,而不是渲染一个空的字幕层或空 logo(scripts/render.py)。这次运行没有给--cues,因此captions、graphics、overlays三个块全部被丢弃,输出是"纯画面 + 响度规范化 + Reels 编码"。 frame.fit: "crop"是画幅转换方式。9:16 从 16:9 得到有三种方式:crop(中心裁切)、pad(加边)、blur(模糊填充)。模板默认crop,也就是裁掉左右两侧、保留中间竖条,这与SKILL.md中"--fit crop16:9→9:16 drops 70% of width"的告警一致。- 字幕尺寸与安全边距不完全由 JSON 决定。
template_project()会用平台表覆盖字幕块(scripts/render.py):
defaults = caption_defaults(dest)
tpl["captions"]["size"] = defaults["size"]
tpl["captions"]["margin"] = defaults["margin"]
for key in ("position", "animate", "outline"):
tpl["captions"].setdefault(key, defaults[key])
if not brand_states_caption_size(args.brand):
tpl["captions"].setdefault("fit_size", "on")
caption_defaults() 把"帧高比例"换算成 ASS 脚本坐标(288 行网格,见 scripts/_platforms.py 与 caption_defaults 定义处):
| 参数 | Reels 平台表取值 | 换算结果 | 含义 |
|---|---|---|---|
caption.size |
0.0833 × 288 | 24 | 字幕字号(ASS 单位) |
caption.position |
bottom |
— | 字幕贴底 |
caption.margin |
safe.bottom = 0.20 → 0.20 × 288 |
58 | 从底边抬起的距离,避开 Reels UI |
caption.animate |
pop |
— | 逐词弹入 |
caption.outline |
2 | — | 描边宽度 |
fit_size |
模板未声明且品牌未声明字号时置 on |
— | 长句自动缩字号,而不是换成两行 |
这就是为什么记录里 fit 日志出现 --margin 58,以及为什么"模板默认字号"不会关掉 caption.py --fit-size auto——源码注释解释了这条规则来自一次长字幕被拆成两条 cue 的评测问题。
3.2 Reels 目标规格(单一事实来源)
模板里的画面、响度、编码和检查值并非各写一遍,而是共用 scripts/_platforms.py 中的一张表。Reels 行如下:
| 维度 | 取值 | 说明 |
|---|---|---|
| 画面 | 1080x1920,9:16 | frame |
| 帧率 | 30 fps | 交付统一到 30 fps |
| 合规画幅 | 9:16 / 4:5 / 1:1 | spec.aspects |
| 最小短边 | 1080 | 低于则 WARN(放大不会增加细节) |
| 帧率上限 | 60 | spec.fps_max |
| 视频编码 | H.264 / HEVC | spec.codecs |
| 音频响度 | -14 LUFS,容差 ±2.0 | spec.lufs / lufs_tol |
| 真峰值 | ≤ -1.0 dBTP | spec.tp |
| SDR 限制 | sdr_only: true |
HDR 色彩标记会 FAIL |
| 最长时长 | 90 s | 上传上限,guidance(WARN,不 FAIL) |
| 最大体积 | 4 GiB | 同上,UPLOAD_LIMITS_AS_OF = "2026-10-30" |
| 安全区 | top 0.08 / bottom 0.20 / left 0.05 / right 0.12 | 应用 UI 遮挡比例 |
check.py 的 SPECS、export.py 的 PRESETS 与 PLATFORM_OF、render.py 的模板、caption.py/graphics.py/overlay.py --platform 的边距、look.py --safe 全部由这张表派生,这一点在 docs/contract.md 中有明确说明。上传上限被刻意标注为 guidance:平台限额经常变化,只有编码、画幅、帧率、响度和真峰值是硬要求。
四、阶段流水线:日志逐行拆解
render.py 的阶段顺序是固定的:clips → join → silence → fit → captions → graphics → overlays → audio → loudness → export → chapters → check,缺失的段自动跳过(scripts/render.py 文件头文档)。这次运行的日志正是这条链的子集:
frame: 1080x1920 from the reels export preset (captions and overlays are sized for delivery)
→ fit.py ... --aspect 9:16 --fit crop --width 1080 --height 1920
wrote fit.mp4 (10.005s, 1080x1920)
→ loudness.py ... -I -14 --tp -1.0
measured: -21.8 LUFS, TP -13.1 dBTP, LRA 0.1 LU
result: -14.0 LUFS, TP -5.4 dBTP (target -14.0 LUFS, TP <= -1)
→ export.py ... --preset reels --normalize
wrote talk_reels.mp4 (10.005s, 1080x1920, h264)
check: OK for reels
rendered talk_reels.mp4 via clips → fit → loudness → export → check
4.1 frame 的 1080x1920 是从哪来的
日志第一行的警告来自 frame_from_preset()(scripts/render.py):当工程只给了 aspect 而没给宽高时,如果某个导出预设恰好同画幅,就用该预设的尺寸作为渲染帧。
frame["width"], frame["height"] = preset["w"], preset["h"]
warn(f"frame: {preset['w']}x{preset['h']} from the {export['preset']} export preset "
"(captions and overlays are sized for delivery)", ...)
这条规则解决的是一个真实缺陷:曾经 {"frame": {"aspect": "9:16"}} + Reels 导出会把 1280x720 源 fit 成 406x720,字幕按 406 宽烧进画面,再被 export.py 放大到 1080 宽,于是字幕发糊。现在先在交付尺寸上做字幕和叠加层,导出不再二次缩放。
4.2 fit:中心裁切到 9:16
fit 段把工程里的 frame.aspect、frame.fit、frame.width/height 合并进 fit 参数,然后调用 fit.py(scripts/render.py)。日志显示产物 fit.mp4 已是 1080x1920、10.005 s。
时长从 10.0 s 变成 10.005 s 不是错误:这是重编码后按帧对齐的正常结果(10 s × 30 fps = 300 帧,300 / 30 = 10.0 s;容器与音频尾帧对齐后读到 10.005 s)。
4.3 loudness:把 -21.8 LUFS 拉到 -14 LUFS
loudness 段直接翻译成 loudness.py 的参数(scripts/render.py):
loudness.py fit.mp4 -o loudnorm.mp4 --lufs -14 --tp -1.0
日志给出了两行测量:输入 -21.8 LUFS、真峰值 -13.1 dBTP、LRA 0.1 LU,输出 -14.0 LUFS、真峰值 -5.4 dBTP。这里有两点值得注意:
- 动态范围极小的素材(LRA 0.1 LU) 说明它几乎是一条恒定电平的合成测试信号,因此 loudnorm 只需整体提升约 7.8 dB 就能命中目标;这也解释了为什么提升后真峰值仍是 -5.4 dBTP,远低于 -1.0 dBTP 的天花板。
- 两遍测量:
loudness.py先测输入(measured_I/measured_TP/measured_LRA/measured_thresh),再用linear=true与target_offset做第二遍,最后再测一次输出并打印result:(相关实现见 scripts/loudness.py)。所以 "-14.0 LUFS" 是对成品文件的实测,而不是对参数的复述。
loudness 段还有一个保护:源没有音轨时不会失败,而是记录一次 skip(loudness_no_audio),避免"画面阶段跑完才在最后一步报错"。
4.4 export:一次编码同时满足响度与封装
export 段的参数拼装非常克制(scripts/render.py):
if normalize:
argv += ["--normalize"] # one export that meets the platform's loudness
export.py --preset reels 的含义在 scripts/export.py 头部写得很清楚:1080x1920、9:16、H.264 CRF 20、AAC 128k、最长 90 s。--normalize 则让导出器在同一次调用里把响度对齐到平台目标,避免"先导出再归一化再导出"的二次损失。
模板里 "export": {"normalize": true} 是显式声明;源码还额外兜底:平台预设 + 工程没有 loudness 段时,normalize 默认打开并给出 WARN,因为否则导出会通过格式检查却在响度行失败,用户得重渲一遍。
4.5 check:最后一道闸门,且不会被静默跳过
check 段调用 run_check(),并在有 FAIL 时以退出码 1 结束(scripts/render.py)。文件头的说明写得很明确:交付文件仍然会被写出,--json 里的 check 字段也仍然带着逐行结果,但进程不会因为"前面的阶段都成功了"就报告成功。
这次的结果是:
check: OK for reels
记录中进一步说明:check.py --platform reels 由模板自动执行,除了一条字幕轨 WARN 之外全部 PASS。这条 WARN 来自 check.py 的 subtitles 行——它把"没有带语言标记的字幕轨"报告为 WARN,理由是字幕是成本最低的无障碍改进;同时 reason 字段明确写着这是可选行,不是交付缺陷(scripts/check.py)。
4.6 最终文件的实测画像
记录里的收尾探测给出了交付物全貌:
| 项目 | 数值 |
|---|---|
| 画幅 | 1080x1920(9:16) |
| 帧率 | 30 fps,恒定 |
| 视频 | H.264 High、yuv420p、bt709 |
| 音频 | AAC、单声道、48 kHz |
| 时长 | 10.005 s |
| 响度 | -14.0 LUFS,真峰值 -5.2 dBTP |
| 体积 | 2.9 MB |
峰值从 loudness 阶段的 -5.4 dBTP 变成交付文件的 -5.2 dBTP,属于两次独立测量(前者测 loudnorm.mp4,后者测 export.py 重新编码后的 AAC 交付),读数不必逐位相同;两者都远低于 -1.0 dBTP 上限,因此检查结论不受影响。
五、"不覆盖别人的文件"是怎么做到的
ow2 这个用例真正考的不是转码,而是输出安全。评测证据写得很直接:talk_vertical.mp4 的 md5 未变,最终回复点名了它。
机制有三层:
- 默认输出名是派生的,不是你已有的文件。
--template不传-o时输出为<输入名>_<模板名>.mp4(scripts/render.py),所以talk.mp4→talk_reels.mp4,与talk_vertical.mp4天然不冲突。 - 已存在的输出在第一个阶段之前就被拒。
render.py在启动各阶段前调用_check_existing_output(),而不是等到最后的复制步骤(scripts/render.py)。对应的统一报错文案在 scripts/_common/runner.py 中:refusing to overwrite existing output '...': pass --overwrite to replace it, or choose another -o path。 --overwrite是显式授权。只有用户明确要求替换某个路径时才应加这个标志;这也是评测用例ow1(用户明确指名覆盖short.mp4)与ow2(用户没有要求覆盖任何文件)的判定差异所在。
顺带一提,guard_sidecar() 还会保护"旁挂文件":字幕阶段生成的 <输出名>.srt 会在第一个阶段之前就被检查是否已存在、是否是输入、是否与输出同名,避免跑完十分钟才发现字幕无处可写。
六、视觉复核:为什么要"看图",以及合成素材的特殊性
python3 scripts/look.py talk_reels.mp4 --tiles 3x2
look.py 默认生成 4x3 的联络表(contact sheet),--tiles 3x2 改为 3 列 2 行,均匀取样整条视频并叠上时间码,输出 <stem>_sheet.png——这次是 talk_reels_sheet.png。
记录里最值得学习的判断出现在这里:
talk.mp4是一个合成测试图案(移动的斜向彩条加类似二维码的标记),不是真人出镜画面,因此中心裁切没有"人物被切掉"这回事。
这条结论非常重要,因为它把"中心裁切是否安全"这个判断题和"画面里有没有主体"这个事实题分开了。ffmpeg-skill 的定位在 SKILL.md 中写得很清楚:它执行编辑、测量并报告,但不替人决定"哪个裁切更好"。当素材是真实出镜画面时,正确做法是:先 look.py 看联络表,或用 cropdetect.py --motion-centre 找到主体横向位置,再用 crop.py --x ... 显式指定裁切框,而不是接受默认的中心裁切。
记录的最后一条也体现了同样的克制:文件夹里那个既有的 talk_vertical.mp4 原样保留,并在回复中主动说明"它不是我这次创建的,我没有动它"。
七、可复现的完整流程
把上面的步骤整理成可直接执行的清单(脚本路径按你本地的仓库根目录调整):
# 0. 看清素材:分辨率、帧率、编码、声道、时长
python3 scripts/probe.py talk.mp4 --json
# 1. 只想先看计划:每一步的命令都会被打印,不写任何产物
python3 scripts/render.py --template reels talk.mp4 -o talk_reels.mp4 --dry-run --json
# 2. 正式渲染(带字幕、标题卡与 logo 的完整形态)
python3 scripts/render.py --template reels talk.mp4 \
--cues cues.txt --title "Episode 12" --logo logo.png \
-o talk_reels.mp4 --json
# 3. 只跑前几个阶段做迭代,例如确认裁切效果
python3 scripts/render.py --template reels talk.mp4 --stop-after fit -o preview.mp4 --json
# 4. 把模板落成可编辑的工程文件,之后改数字重渲
python3 scripts/render.py --template reels talk.mp4 --write-project project.json
python3 scripts/render.py project.json
# 5. 单独复核平台规格 / 画面
python3 scripts/check.py talk_reels.mp4 --platform reels --json
python3 scripts/look.py talk_reels.mp4 --tiles 3x2
几个容易被忽略的开关:
--dry-run:render.py的每个阶段都以子进程的 dry run 方式规划,连缺失的滤镜或编码器也会在编码前被发现;dry run 下的 check 段会被记为 skip,因为还没有文件可检查。--stop-after <stage>:中途停在clips/join/silence/fit/captions/graphics/overlays/audio/loudness/export任一段;停下来时工作目录会被保留,因为结果里的输出文件就在里面。--write-project FILE:只写出填充后的project.json并退出,不渲染。想改frame.fit、换loudness.lufs、加silence段,都从这里开始。--intermediate-preset:默认superfast。因为导出阶段会重新编码,中间阶段用快预设不损失交付质量;源码注释记录了同 CRF 下与medium的 SSIM 对比(0.997 量级),需要中间产物本身也精细时用--intermediate-preset medium。--cache DIR/--from STAGE:缓存按"ffmpeg 构建 banner + 技能版本 + 转发参数 + GPU 设置 + 输出扩展名"组合成键,所以不同构建或不同--fast草案之间不会互相串用;配合--from可以从某个阶段续跑。
八、模板族的同一套机制
--template reels 只是 templates/ 目录中的一个。同一机制还提供 tiktok、shorts、youtube、x、linkedin、facebook、podcast、audiogram 等模板,--list-templates 会打印每个模板的画幅、裁切方式、时长上限、响度目标与安全区:
python3 scripts/render.py --list-templates
几个实用变体:
- 一次投全平台:
--template all(等价于tiktok,reels,shorts,youtube,x,linkedin,facebook)会为每个目标做一次完整渲染,并写出一张<stem>_pack.md汇总表;表中每个目标都有自己的 check 结论。注意--stop-after、--cache、--work、--export-timeline这类"单次渲染"参数在多目标模式下会被拒绝,因为每个目标是独立的一次渲染。 - 音频节目:
podcast是纯音频目标,中间产物与交付都用音频容器(.m4a),不会硬塞进.mp4;audiogram需要--image提供本地封面图——该技能不会下载图片,也不会凭空生成封面。 - 审片交付:
--export-timeline edit.fcpxml(或.edl/.otio)把工程里的剪切、变速、转场与音乐床导出为剪辑软件时间线,并把无法承载的段落列在not_exported中。
九、从这次运行可以提炼的几条经验
- 交付请求 = 一条
render.py --template。三个阶段以上的编辑才需要手写project.json;单目标交付用模板最省事,也最不容易漏掉响度或检查。 - 先 probe,再决定
fit方式。16:9 → 9:16 的crop会丢掉约 70% 的画面宽度;素材有主体时,用look.py或cropdetect.py确认位置,再决定是否改成pad/blur或显式crop.py --x。 - 没有
--cues就没有字幕。占位符为空时整块被丢弃,check.py随之给出"无字幕轨"的 WARN——这是可选项,不是失败。想让字幕自动缩字号而不是换行,保留模板默认的fit_size: on。 - 响度以实测为准。日志里的
measured:是输入读数,result:是输出读数,最终交付还会再测一次;报告里应引用交付文件的那一组数字。 - 不要用
--overwrite掩盖冲突。输出已存在是一个信号:要么换个-o,要么确认这就是用户要替换的文件。 - 交付需要有"眼睛"。
look.py生成的联络表是唯一能回答"裁切后主体还在不在""字幕有没有压到底部 UI"的手段;没有视觉能力时,应明确说明"像素未被检视",而不是假定通过。
这次 ow2 运行的价值,正在于它示范了一条没有多余动作的路径:探测一次、渲染一次、检查一次、看图一次,产出 talk_reels.mp4,并且没有碰任何不属于本次任务的文件。相关实现集中在 scripts/render.py、scripts/_platforms.py、scripts/export.py 与 scripts/check.py,模板位于 templates/,运行记录原文见 run.md。
