ffmpeg-skill 交付闭环实战:YouTube 模板渲染、-14 LUFS 归一化与 faststart 字节级校验

原创2026-11-17 13:50:481,415 阅读
文章标签:音视频视频处理音频处理AI 技能MCP 服务CLI

ffmpeg-skill 交付闭环实战:YouTube 模板渲染、-14 LUFS 归一化与 faststart 字节级校验

本文以仓库内一份真实评测记录 evals/results/iteration-23b/ff1/with_skill/outputs/run.md 为主线,拆解 ffmpeg-skill 如何用一条 render.py --template youtube 命令完成「适配画幅 → 响度归一化 → 平台导出 → 交付检查」的完整链条,并解释记录中那次 moov(offset 36)先于 mdat(offset 14396)的字节级验证为什么是这条路径上最值得盯住的回归点。读完后你能独立复现这次交付、读懂 check.py 的每一行判定,并自己动手做一次 faststart 校验。

一、这份运行记录到底证明了什么

评测记录本身非常短,但信息密度很高。它给出的是一次端到端交付的可复现命令与结果:

Prompt: I need OUTDIR/source.mp4 ready to upload to YouTube -- normal loudness, all the delivery
checks passing. Save to OUTDIR.

$ python3 scripts/render.py --template youtube OUTDIR/source.mp4 --output OUTDIR/ff1_delivery.mp4 --json
loudness.py OUTDIR/ff1_delivery_work_841/fit.mp4 -o OUTDIR/ff1_delivery_work_841/loudnorm.mp4 -I -14 --tp -1.0 --timeout 1800
check: loudness PASS -14.0 LUFS (expected -14 +/- 2 LUFS); true peak PASS -4.4 dBTP (expected <= -1 dBTP); failed 0, warnings 1, ok true

随后是结论:OUTDIR/ff1_delivery.mp4 是 YouTube 模板交付,响度归一化到 -14.0 LUFS、真峰值 -4.4 dBTP,faststart 存在且经过字节校验(moov 在 mdat 之前);步骤为 render.py --template youtube(fit → loudness → export)加 check.py;检查结果里只有一条“没有字幕轨”的警告,而原始请求并没有要求字幕;因为这条链上没有任何影响画面的步骤,所以没有做视觉检查。

这段记录对应评测集里的 ff1 用例,见 evals/agent_prompts_24.json:expect 要求出现 render|loudness 与 check,grader_expect 是 (?i)(faststart|moov),备注写明它是“faststart 修复(#275、#279)的回归探针:响度归一化后的模板交付输出必须仍然快速启动(moov 在 mdat 之前),并且 check.py 的 loudness / true-peak 行必须 PASS”。这说明该记录不是随手跑一次的日志,而是针对一个已知易回归路径的定点验证。

二、一条命令背后的真实调用链

--template 并不是一个独立的渲染器,而是把随仓库发布的模板 JSON 填充成一份普通 project,再走 render.py 原有的阶段流水线。相关实现见 scripts/render.py:

  • template_project() 读取 templates/<name>.json,把 $INPUT、$OUTPUT、$CUES、$SRT、$LOGO、$BRAND、$CHAPTERS、$TITLE、$IMAGE 等占位符替换成绝对路径或参数值;占位符没有值的模板块会被整体丢弃,而不是渲染成一个空图层。
  • 模板的 caption 尺寸与安全边距来自平台表而不写死在 JSON 里:caption_defaults(dest) 会把该目的地的默认字号、位置、描边写进填充后的 project(scripts/_platforms.py)。
  • 阶段执行顺序固定为 clips → audiogram → join → silence → fit → captions → graphics → overlays → audio → loudness → export → chapters → check,常量 STAGE_ORDER 在 scripts/render.py,主流程中“缺哪个阶段就跳过哪个”的写法从第 1871 行起依次展开。

本次运行实际命中的是三个阶段加一个校验阶段,正好与记录里的 Steps: render.py --template youtube (fit -> loudness -> export), check.py 对应:

阶段 命令 输入 → 输出
fit fit.py(aspect/fit 来自模板 frame) OUTDIR/source.mp4 → OUTDIR/ff1_delivery_work_841/fit.mp4
loudness loudness.py -I -14 --tp -1.0 fit.mp4 → OUTDIR/ff1_delivery_work_841/loudnorm.mp4
export export.py --preset youtube --normalize loudnorm.mp4 → OUTDIR/ff1_delivery.mp4
check check.py --platform youtube 读取 ff1_delivery.mp4

工作目录命名也在源码里写明:默认用 tempfile.mkdtemp(prefix=f"{<output stem>}_work_{os.getpid()}_", dir=<output 的目录>) 创建,所以记录中的 ff1_delivery_work_841 就是“输出名 + 进程号”的组合(scripts/render.py)。这个目录默认在运行结束时删除;只有显式给出 --work 或 --keep 才会保留,而 --stop-after 预览未到 export 时也会被保留,因为结果文件就在里面。

模板 JSON 里到底定义了什么

youtube 模板的内容可以在 templates/youtube.json 中逐项核对,它是理解整条链的骨架:

{
  "template": "youtube",
  "output": "$OUTPUT",
  "clips": [{"src": "$INPUT"}],
  "frame": {"aspect": "16:9", "fit": "pad"},
  "brand": "$BRAND",
  "captions": {"text": "$CUES", "animate": "none", "karaoke": false, "size": 20, "position": "bottom", "margin": 14},
  "graphics": [{"template": "lower-third", "name": "$TITLE", "start": 1, "end": 6}],
  "overlays": [{"image": "$LOGO", "position": "top-left"}],
  "loudness": {"lufs": -14, "tp": -1.0},
  "export": {"preset": "youtube", "normalize": true},
  "check": {"platform": "youtube"}
}

几个容易被忽略但影响结果的细节:

  1. 画幅用 pad 而不是 crop:16:9 目标下不裁掉画面内容,竖屏素材会得到左右黑边,而不是丢掉 70% 的内容。
  2. captions 块在缺少 --cues / --srt 时会整体消失:fill_template() 发现 $CUES 没有值就丢弃整个块,因此本次运行不含字幕阶段,最终 check.py 的 subtitles 行给出 WARN —— 这正是记录里“唯一警告”的来源。
  3. graphics 与 overlays 同样依赖 $TITLE / $LOGO:不传 --title、--logo 时下三分之一与角标都不会出现,交付物就是纯净的画面 + 归一化音频。
  4. export.normalize: true 是显式写进模板的:即便项目里已经有 loudness 阶段,导出阶段仍会按平台预设做一次兜底检查。源码里另有一条默认规则:平台预设若没有 normalize 键且 project 没有 loudness 段,会自动打开并给出 normalize_on_by_default 警告(scripts/render.py)。

平台侧的规格全部来自唯一一张表 scripts/_platforms.py:YouTube 目标帧 1920×1080 / 16:9,编码接受 h264/hevc/prores/av1/vp9,最短边不低于 720,帧率上限 60,响度 -14 LUFS(容差 ±2),真峰值 -1 dBTP,上传长度与体积上限带 basis: guidance 标记(UPLOAD_LIMITS_AS_OF = "2026-10-30")。同一张表同时被 check.py 的 SPECS、export.py 的预设和 render.py 的模板读取,所以“目标画幅”“合规行”“导出参数”不会三处漂移。

三、响度归一化:为什么输出是 -14.0 LUFS

记录里最关键的一行是 loudness.py ... -I -14 --tp -1.0 --timeout 1800。loudness.py 用的是两遍法,而不是单遍 loudnorm,实现见 scripts/loudness.py:

  • 第一遍只测量:ffmpeg -i INPUT -map 0:<audio> -vn -af loudnorm=I=-14:TP=-1:LRA=11:print_format=json -f null -,从 stderr 中解析 input_i、input_tp、input_lra、input_thresh、target_offset。显式 -map 是为了避免 FFmpeg 选到“声道最多”的那条轨,导致增益被施加到别的音轨上。
  • 第二遍带测量值做线性归一化:滤镜串里追加 measured_I/measured_TP/measured_LRA/measured_thresh/offset 与 linear=true,再用 atrim=duration=<输入音频长度> 把 loudnorm 多吐出的尾部裁掉 —— 源码注释里点明了 AAC 编码后会多出约 0.1 秒,足以让 90 秒的 Reels 交付卡在长度检查上。
  • 视频流拷贝:视频走 -c:v copy,只重编音频(AAC,视频容器默认 192k),并在 mp4/mov/m4v 上追加 -movflags +faststart。
  • 编码器过冲的二次修正:真峰值是编码后重新测的,如果超过目标 +0.1 dB 容差,会先尝试把码率提到 256k、320k(量化噪声随码率下降),必要时再下调 loudnorm 的 ceiling 重编;最多 5 轮,最后仍超标就以 kind: verification 失败退出,而不是悄悄交付。
  • linear 与 dynamic 的判定:loudnorm_mode() 复刻 FFmpeg af_loudnorm.c 的规则 —— 只有当测量的 TP 加上增益仍不越过 ceiling、且 LRA 不超过 --lra 时才用线性增益,否则回落到 dynamic 模式压缩动态范围。若因此偏离目标,结果里会带 note 说明“差了几 LU、原因是什么”,不会把它当成达标。

本次输出 -14.0 LUFS 落在目标值上,真峰值 -4.4 dBTP 远低于 -1 dBTP 上限,属于“线性增益足够、无需压动态范围”的理想情形。注意真峰值的判定统一使用 TP_TOLERANCE_DB = 0.1(scripts/_platforms.py),源码注释解释了统一容差的原因:此前 loudness.py 允许 +0.1、check.py 允许 +0.05、export.py 允许 0,导致“同一个文件在不同工具里结论不同”。

四、check.py 的行级判定与退出码语义

check.py 不是“跑一下 ffmpeg 看有没有报错”,而是按平台表逐行打分,输出 PASS/WARN/FAIL 表格,并在任何一行 FAIL 时以退出码 1 结束(scripts/check.py)。与本次记录直接相关的实现要点:

  • 默认平台:不传 --platform 时按 youtube 规格检查,但 duration/aspect/loudness/true peak/fps/resolution/first frame/flashes 这些“判断类”行降级为 WARN,不计数到 failed;只有显式命名平台才会真正 FAIL。本次 render.py 的 check 阶段传了 --platform youtube,所以响度行是硬判定。
  • 响度测量:measure_loudness() 用 loudnorm=I=-14:TP=-1:LRA=11:print_format=json 对第一条音轨做一次分析,得到 input_i / input_tp / input_lra;解析失败时不会静默丢行(那会造成“假 PASS”),而是给出 could not measure 的 WARN。
  • 两行分别判定:loudness 行比较 |measured - spec| 与 lufs_tol(YouTube 为 2.0 LU),true peak 行比较 measured <= spec.tp + 0.1。记录的 PASS -14.0 LUFS (expected -14 +/- 2 LUFS) 与 PASS -4.4 dBTP (expected <= -1 dBTP) 就是这两行的文本形态。
  • 警告不计入失败:failed = [r for r in rows if r["status"] == "FAIL"],WARN 只计入 warnings。因此 failed 0, warnings 1, ok true 精确地表示“零个硬失败、一个提示”。本次那一条 WARN 来自 subtitles 行:WARN none (expected >= 1 language-tagged subtitle track),源码注释明确写着“任何平台都不会因为缺字幕而拒收”,且提示语是“字幕是交付里最廉价的无障碍收益”。
  • --json 文档形态:成功时是 {platform, checks, failed, warnings, ok: true, notes, input_identity?};失败时通过 die(..., kind="verification", checks=rows, failed=..., ok=False) 输出错误文档。render.py 的 check 阶段直接复用它(run_check()),并且镜像其退出码:check FAIL 时 render.py 也以 1 退出,产物仍然落地,check 字段仍带完整的逐行结果(scripts/render.py)。

顺带一提,short/短音频有个专门分支:如果音频短于一个 400 ms 的响度门限块,integrated loudness 会是 -inf,此时 check.py 报“could not measure (shorter than one 400 ms loudness block)”的 WARN 而不是 FAIL —— 因为那不是静音,也不该被要求替换音轨。

五、faststart:为什么要盯 moov 与 mdat 的偏移

MP4 的索引(moov)默认写在文件末尾,播放器要读完整个文件才能开始解码;-movflags +faststart 会把索引前移,使文件“边下边播”。对平台上传与预览来说,这不是优化项而是交付质量项,因此它成了最容易在重构中悄悄丢失的东西。

记录里的验证方法是直接读文件头部:moov 在 offset 36,mdat 在 14396,索引在前 —— 一个 1920×1080 的 mp4 头部结构里 ftyp 之后紧跟 moov,这个偏移量完全符合预期。

这条链上有三处写文件的环节,任何一处漏掉 +faststart 都会前功尽弃:

  1. loudness.py 的流拷贝分支:-c:v copy 时仍需显式追加 -movflags +faststart(scripts/loudness.py)。CHANGELOG 的 1.24.1 条目正是 fix(loudness): stream-copy branch was dropping -movflags +faststart (#277),而本文记录的运行发生在包含该修复之后的版本上。
  2. export.py 的写出:预设编码分支统一追加 +faststart(scripts/export.py);同时 --normalize 会在导出后对文件再跑一次 loudness.py,用临时文件替换原文件,因此“二次写入是否仍带 faststart”必须单独成立。
  3. metadata.py 的流拷贝:早期用流拷贝写 MPEG-4 家族时索引会落到媒体之后,导致“faststart 的输入、非 faststart 的输出”,CHANGELOG 中 #415 与源码注释都记录了这一点(scripts/metadata.py);1.25.0 的 Add -movflags +faststart to remaining mp4 stream-copy paths (#279) 则补齐了其余拷贝路径。

也就是说,ff1 这条用例之所以被设计成“模板交付 + 响度归一化”,是因为它同时穿过 1、2 两处写入:先经 loudness.py 做流拷贝重编音频,再由 export.py 重编视频并在需要时再归一化一次。只要其中任一环节回退,moov 就会跑到 mdat 后面。

自己动手做一次字节级校验

不依赖任何外部工具,用 Python 顺序读 box 头即可:

python3 - <<'PY'
import struct, sys
path = "OUTDIR/ff1_delivery.mp4"
order = []
with open(path, "rb") as f:
    while True:
        head = f.read(8)
        if len(head) < 8:
            break
        size, kind = struct.unpack(">I4s", head)
        order.append((kind.decode("latin-1"), f.tell() - 8))
        if size == 1:            # 64 位 largesize
            size = struct.unpack(">Q", f.read(8))[0]
            f.seek(f.tell() - 16 + size)
        elif size == 0:          # 直到文件末尾
            break
        else:
            f.seek(f.tell() - 8 + size)
        if len(order) > 8:
            break
for kind, off in order:
    print(f"{kind} @ {off}")
PY

判据很简单:moov 的偏移必须小于 mdat。本次记录中即 moov @ 36、mdat @ 14396。若顺序相反,说明某个写入环节丢了 -movflags +faststart,应顺着上面的三处写入逐一排查,而不是只在最后一步重新封装。

六、复现这次交付的完整步骤

结合 render.py 的参数定义(scripts/render.py),最贴近记录的最小复现路径是:

# 0) 先看模板清单:画幅、fit 策略、时长上限、响度目标、安全区
python3 scripts/render.py --list-templates

# 1) 只出计划,不写文件:把每个阶段的真实命令打印出来
python3 scripts/render.py OUTDIR/source.mp4 --template youtube \
  --output OUTDIR/ff1_delivery.mp4 --dry-run --json

# 2) 正式渲染(记录中的命令)
python3 scripts/render.py OUTDIR/source.mp4 --template youtube \
  --output OUTDIR/ff1_delivery.mp4 --json

# 3) 独立再验一次交付合规
python3 scripts/check.py OUTDIR/ff1_delivery.mp4 --platform youtube --json

# 4) 字节级确认 faststart
#    即上一节的 box 遍历脚本,观察 moov 与 mdat 的先后

几个在实战中很有价值的配套参数:

参数 作用 适用场景
--dry-run --json 只规划:列出 commands,不编码、不校验 先确认阶段与中间文件名
--write-project FILE 把填充后的 project.json 落盘并停止 想手动改 caption 尺寸、加 overlays、换 fit 策略
--stop-after STAGE 停在某个阶段(clips/join/silence/fit/captions/graphics/overlays/audio/loudness/export) 迭代字幕或构图时避免重跑全链
--cache DIR + --from STAGE 复用相同阶段的产物,只重跑后续阶段 改了文案但画面阶段不变
--intermediate-preset 预导出阶段的 x264/x265 预设,默认 superfast 中间文件只服务最终重编码,medium 可恢复各阶段默认
--cues/--srt/--logo/--title/--brand/--chapters/--image 填模板占位符 需要字幕、角标、下三分之一、品牌、章节、音频波形图
--template all 一次投放到 tiktok/reels/shorts/youtube/x/linkedin/facebook 并生成 *_pack.md 结果表 一稿多发

需要提醒两点约束:--template 一次只能配合一个模板使用 --stop-after、--cache、--work、--export-timeline 这些“单次渲染”参数,传多个模板(pack)时会被明确拒绝;--write-project 也要求单个模板。另外 render.py --template 里的位置参数是素材,而 render.py project.json 里的位置参数是工程文件,两种调用形式不要混用。

七、结果解读:哪些是已验证,哪些没有

记录的价值不只在“跑通了”,更在于它标清了证据边界:

  • 已验证(有数值或字节证据):响度 -14.0 LUFS 落在 -14 ± 2 内;真峰值 -4.4 dBTP 低于 -1 dBTP;check.py 0 个 FAIL、1 个 WARN、ok: true;moov 偏移 36 小于 mdat 偏移 14396。
  • 已知但未处理:唯一警告是缺字幕轨。因为 prompt 未要求字幕,这属于“可选能力缺席”,不是缺陷;源码中该行本来就不会计入 failed。
  • 明确未做:视觉检查。run.md 给出的理由是“这条链没有影响画面的步骤”——只做了 fit(画幅适配)与音频归一化,导出重编码不改变构图。按仓库的报告规范 references/report.md,这类情形应显式写 Look: not needed 而不是留空,记录也正是这么做的。
  • 不该被过度解读的:这次 -4.4 dBTP 说明该素材余量充足,并不代表任何素材都能轻松达标;遇到瞬态强的素材,loudness.py 的码率提升与 ceiling 下调机制才真正派上用场。

八、一条记录串起来的仓库结构

把这份运行记录当作索引,可以顺着它读到整个交付子系统的骨架:

关注点 文件 读什么
模板定义 templates/youtube.json 画幅、字幕、图层、响度、导出、校验六段
模板引擎与阶段编排 scripts/render.py template_project()、fill_template()、STAGE_ORDER、sh()、run_check()
平台规格单一真源 scripts/_platforms.py 帧、fps、合规行、安全区、字幕默认值、上传上限的 guidance 语义
两遍响度归一化 scripts/loudness.py 测量、linear/dynamic 判定、atrim 截尾、过冲重编、verification 步
交付合规检查 scripts/check.py 行级 PASS/WARN/FAIL、判断类与格式类区分、--content/--levels 扩展
平台导出预设 scripts/export.py 预设表、+faststart、--normalize 的二次归一化
元数据与章节写入 scripts/metadata.py 流拷贝写 MP4 时的 faststart 处理
报告格式规范 references/report.md Done/Steps/Check/Look/Notes 五行的语义与失败写法
用例定义 evals/agent_prompts_24.json ff1 的期望、禁止项与回归意图
版本变更 CHANGELOG.md #277、#279、#415 与 1.24.1 / 1.25.0 的对应关系

九、结语:可交付性是被测量的,不是被声明的

这份 run.md 之所以值得作为技术样本,是因为它把“我做好了”拆成了三类可核对的证据:数值(-14.0 LUFS / -4.4 dBTP 与目标区间)、行级判定(0 FAIL、1 WARN、ok: true 的语义)、字节(moov 在 mdat 之前)。三者分别由 loudness.py 的测量、check.py 的合规表、以及文件头部的 box 顺序提供,任何一环都可以脱离这次会话被独立复现。

更实用的启示是:当交付链路里存在“重编码 → 归一化 → 再重编码”这类多次写文件的环节时,最脆弱的往往不是画质或响度,而是像 +faststart 这种「不会报错、只会悄悄变差」的容器属性。把它纳入自动化校验(哪怕只是比较两个整数偏移),成本极低,却能拦住一整类静默回归。

登录后查看全文
ffmpeg-skill