用 ffmpeg-skill 一条命令交付 Instagram Reels:9:16 竖屏、-14 LUFS 与平台自检实战

原创2026-11-18 05:01:462,187 阅读
文章标签:音视频视频处理音频处理AI 技能MCP 服务CLI

用 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、中心裁切风险时该如何处理。

Reels 导出预设与平台合规检查的演示

一、这次运行到底做了什么

记录中的任务来自评测用例 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" }
}

三个关键点:

  1. 占位符是"要么填、要么整块丢弃"。$CUES、$LOGO、$TITLE、$BRAND 分别由 --cues(或 --srt)、--logo、--title、--brand 提供。fill_template() 在某个占位符没有值时,会让整个块被判为不完整并删除,而不是渲染一个空的字幕层或空 logo(scripts/render.py)。这次运行没有给 --cues,因此 captions、graphics、overlays 三个块全部被丢弃,输出是"纯画面 + 响度规范化 + Reels 编码"。
  2. frame.fit: "crop" 是画幅转换方式。9:16 从 16:9 得到有三种方式:crop(中心裁切)、pad(加边)、blur(模糊填充)。模板默认 crop,也就是裁掉左右两侧、保留中间竖条,这与 SKILL.md 中"--fit crop 16:9→9:16 drops 70% of width"的告警一致。
  3. 字幕尺寸与安全边距不完全由 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 未变,最终回复点名了它。

机制有三层:

  1. 默认输出名是派生的,不是你已有的文件。--template 不传 -o 时输出为 <输入名>_<模板名>.mp4(scripts/render.py),所以 talk.mp4 → talk_reels.mp4,与 talk_vertical.mp4 天然不冲突。
  2. 已存在的输出在第一个阶段之前就被拒。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。
  3. --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 中。

九、从这次运行可以提炼的几条经验

  1. 交付请求 = 一条 render.py --template。三个阶段以上的编辑才需要手写 project.json;单目标交付用模板最省事,也最不容易漏掉响度或检查。
  2. 先 probe,再决定 fit 方式。16:9 → 9:16 的 crop 会丢掉约 70% 的画面宽度;素材有主体时,用 look.py 或 cropdetect.py 确认位置,再决定是否改成 pad/blur 或显式 crop.py --x。
  3. 没有 --cues 就没有字幕。占位符为空时整块被丢弃,check.py 随之给出"无字幕轨"的 WARN——这是可选项,不是失败。想让字幕自动缩字号而不是换行,保留模板默认的 fit_size: on。
  4. 响度以实测为准。日志里的 measured: 是输入读数,result: 是输出读数,最终交付还会再测一次;报告里应引用交付文件的那一组数字。
  5. 不要用 --overwrite 掩盖冲突。输出已存在是一个信号:要么换个 -o,要么确认这就是用户要替换的文件。
  6. 交付需要有"眼睛"。look.py 生成的联络表是唯一能回答"裁切后主体还在不在""字幕有没有压到底部 UI"的手段;没有视觉能力时,应明确说明"像素未被检视",而不是假定通过。

这次 ow2 运行的价值,正在于它示范了一条没有多余动作的路径:探测一次、渲染一次、检查一次、看图一次,产出 talk_reels.mp4,并且没有碰任何不属于本次任务的文件。相关实现集中在 scripts/render.py、scripts/_platforms.py、scripts/export.py 与 scripts/check.py,模板位于 templates/,运行记录原文见 run.md。

登录后查看全文
ffmpeg-skill