AIV 视频生产线:九个环节、唯一契约与入库边界


 TL;DR
这条线要解决的问题只有一个:
难度 中等

入库的是事实,不入库的是产物。

规范、契约、台账、口播稿、渲染代码与测试进仓库;
图像、音频、时间轴、片段与成片只留在本机。

这条线要解决的问题只有一个:

怎么把已经写过的技术文章,变成一条能持续产出、还能被复现的成片流水线。

「可复现」是这条线的验收标准:换个人、换台机器、半年后重跑,出来的片子必须一样。
这比「做出一条片子」难得多,因为后者只需要一次成功。


一、一条视频的九个环节

flowchart TD A["1 选题 选题库"] --> B["2 讲解底稿 源码与出处"] B --> C["3 口播稿 短句加锚点"] C --> D["4 视觉契约 画面文案与数字"] C --> E["5 旁白 合成与音色定标"] D --> F["6 时间轴 align 按旁白对齐"] E --> F F --> G["7 渲染 cairo 逐帧绘制"] G --> H["8 成片 compose 拼接混音烧字幕"] H --> I["9 品牌片头片尾 配乐首尾相接"]
# 环节 产物 入库
1 选题 一句话钩子 + 关联文档 + 出处 ✅ 选题库
2 讲解底稿 源码路径、函数名、行号、异常分支 ✅ 原文就在仓库里
3 口播稿 每行一个意群、每 15~20 秒一个锚 ✅ 字幕-<主题>.md
4 视觉契约 画面上写什么:标题、副标题、标签、数字、枚举 ✅ contracts/<期>.json
5 旁白 定稿音色合成,句长与语速对齐口播稿 ❌ 音频是产物
6 时间轴 旁白对齐算出的时间码、字幕断行、场景序列 ❌ 跟着旁白走
7 渲染 各场景片段(cairo 逐帧绘制 + ffmpeg 编码) ❌ 片段可重出
8 成片 拼接 + 混音 + 烧字幕 ❌ 产物
9 品牌片头片尾 2.833 秒的两支片,配乐首尾相接成闭环 ⚠️ 配乐窗口决策入库,音轨不入库

关键设计只有一条:把「文案」和「契约」从「产物」里拆出来。

前四步是人写的内容——体积小、可评审、可版本化,所以入库;
后五步是机器生成的产物——体积大、不可读、不可评审,所以不入库。
这条界线划在 §4。


二、技术画面为什么不用模型生成

这条线最早的做法是整片交给视频模型生成。核算下来,
H3 2K 实测 120 积分/秒,35 秒就是 4200 积分——
而技术讲解片的主体恰恰是技术图示:reader 到 worker 的数据流、
32 核、三层线程拓扑。这些东西:

  • 用规则描述最准确,用模型生成最容易出错
  • 文字和数字一旦生成错,没法撤回
  • 改一句话要重生成整段,成本按秒计

于是改成「技术图示全代码绘制,模型只出静态底板」:

项 原方案(整片视频生成) 现方案(代码渲染)
积分消耗 4200(按秒计) 视频生成为 0
画面准确性 文字、数字由模型生成 文字、数字、机制图示零模型生成
改一处 重生成整段 只重渲一个场景
返修粒度 整片 单场景(build/<期>/s03.mp4 单独重出)

连 3 秒的品牌片头也不用视频生成:H3 视频生成最短 4 秒,做不出 3 秒以内的片头。
所以品牌片改成「AI 出背景底板(静态图)+ 代码合成角色与文字」。

实现落在 pipeline/pyv/:draw.py 是 cairo 绘制封装,
scenes/s*.py 一个场景一个模块,场景是纯函数 render(ctx, t, w, h),
t ∈ [0,1],无全局状态——所以它可单测、可重放、可并发。

视觉规格是 palette.py 里的常量,启动时校验字体可加载,
缺失即报错退出,不静默降级(避免跨机渲染结果不一致):

项 值
画布 1920×1080 / 24fps / 时间基 1/24000 / H.264 (yuv420p) / AAC 48kHz 立体声
背景 / 主色 #FFFFFF / #2B4C7E
强调 / 次强调 #F5A623 / #4FD1C5
字体 跨平台解析(启动即校验):macOS PingFang SC,Linux Noto Sans CJK SC
字幕 底部居中,深蓝字 #1B2A47 + 白描边,每行 ≤ 14 字,无底板

三、唯一契约:画面上写什么,写在契约里

一条视频的画面文案与数字(标题、副标题、标签、核数、顺序号、性能倍数……)
全部写在 contracts/<期>.json 里,不写在场景代码里。

放哪 谁定
文案、数字、标签、枚举 contracts/<期>.json 每一期
位置、尺寸、配色、动效 pipeline/pyv/scenes/*.py 模板

这么分是为了让「换一期」不再等于「改一遍代码」:新一期只写契约,
场景渲染器一行都不用动。两条硬规矩:

  • 参数缺失当场报错。契约少给一个参数,渲染前就抛 MissingParam,
    绝不悄悄退回硬编码的旧文案——那会让契约与画面的不一致变得无声无息。
  • 文案不许回流到代码。tests/test_contract.py 会解析场景源码,
    只要契约里的文案还以字符串字面量的形式出现在场景里,测试就红。

契约还规定「哪几句旁白配哪张图」,句子必须恰好被覆盖一次:
漏了、重了都会在 align 之前就报错。

时间轴不是契约。 storyboard_<期>.json 是 align 按旁白算出来的产物,
跟着本机旁白走,不入库。入库的契约决定「画面上写什么」,
时间轴只决定「什么时候出现」——两者解耦,换稿时只重跑 align。


四、为什么音视频不入库

仓库根的 .gitignore 和 aiv/.gitignore 都把媒体挡在仓库外。
这不是洁癖,是算过账的:

理由 说明
体积 单条成片 15~35 MB,一期含旁白、片段、成片约 60 MB。100 期就是 6 GB
不可读 二进制在 diff 里永远是 “Binary files differ”,评审和回溯都失效
CI 成本 每次部署都要 checkout 整个仓库,媒体会让 clone 时间线性膨胀
不可重建 成片是产物,不是事实来源。真正的事实来源是契约 + 口播稿 + 规范 + 引擎代码
归属风险 媒体里带着品牌色、吉祥物与形象原图,把它们塞进公开仓库,是把别人的物料放到个人名下

所以规则很简单:

入库的是「事实」,不入库的是「产物」。

入库 不入库(留本机)
contracts/<期>.json 视觉分镜契约 storyboard_<期>.json 时间轴
字幕-<主题>.md 口播稿与字幕表 build/<期>/*.mp4 片段
pipeline/pyv/scenes/*.py 场景代码 out/<期>.mp4 成片
三份规范(人格 / 形象音色 / 背景音乐) 发布包
music/library.json 曲库台账
brand/brand_windows.json 片头片尾的配乐窗口

(成片、片段、时间轴是产物;旁白、曲库、立绘、品牌片是输入——
它们也入库,理由见下一节。)

需要成片时,本机跑 make all 重新生成即可——这才是「可复现」的真正含义。

但「输入」和「产物」不是一回事

上面那条规则后来被追了一条例外,因为它把两件事混在了一起:

旁白 mp3 / 曲库 wav / 立绘 png 成片 mp4 / 片段 mp4
是什么 输入:没有它就算不出成片 产物:由输入算出来
能不能重建 旁白要联网调 TTS,曲库要从 archive.org 下载,立绘要调图像生成——三步都可能失败 跑一遍流水线就有
换台机器 缺了就出不了片 缺了重跑就有了

「产物」不入库是对的:体积大、不可读、且能重建。
但「输入」不入库,等于每次换机器都要重新走一遍「从这台机器搬文件 →
重新下载 → 重新合成」,每一步都可能失败,而且没人能保证复现出同一个文件
(TTS 的输出未必逐字节相同)。

于是规则被改成:

入库的是「事实」与「出片必需的输入」,不入库的是「产物」。

最小必需集入库(约 105 MB):六期旁白 + 音色定标参照稿 + 形象原型与立绘 +
品牌片头片尾与成品音轨 + 曲库两首(授权 CC0-1.0,指纹已核对)。
aiv/pipeline/tests/test_assets_are_tracked.py 盯着这件事——
必需素材一旦被 .gitignore 拦掉,测试立刻变红。

「可复现」的第二道考题:换台机器

上面这些都还只是同一台机器上的可复现。真正的考题是:
换一台机器、换一个操作系统,还能不能出片?

原来不能。原因是三件事被默认了:

  1. 字体——渲染用 macOS 自带的 PingFang SC。它是 Apple 的授权字体,
    不能随仓库分发,Linux 上根本没有,于是渲染直接抛错拒绝开工;
  2. 素材——见上一节,全部要现搬;
  3. 依赖——没有依赖清单,也没有自检,换机器只能靠试错。

现在补齐了:

  • 字体族名由 pipeline/pyv/fonts.py 统一解析:macOS 用 PingFang SC,
    Linux 退到开源的 Noto Sans CJK SC;找不到就报错并给出 apt-get 命令,
    不再静默画成豆腐块。
  • make doctor 一次报清「缺什么、怎么补」:Python 版本、四个第三方库、
    ffmpeg 的 libx264 与原生 aac、中文字体、每一期的旁白、曲库、立绘、品牌片。
  • .github/workflows/aiv-pipeline.yml 在 ubuntu 上真跑一遍测试——
    而且不只是单元测试:它用入库的真实旁白与 BGM 合成出一段成片,
    再按规格核对(1920×1080 / 24fps / h264 yuv420p / aac 48kHz 立体声 /
    video_track_timescale=24000),并检查画面里真的有字幕、且中文字形
    不是豆腐块。
    合成这一步在 Linux 上以前从没执行过:真实的 storyboard_*.json
    是产物、不入库,于是那条集成测试在新克隆上一直 skip——CI 只证明了
    零件能用,没证明整条能走通。

代价只有一条,但必须说清楚:字体不同,所以像素不同。
Linux 上出的片子与 macOS 上的不是逐像素一致——文案、字幕、版式规则完全一致,
视觉上仍是同一套系统。逐像素基准那条守卫因此在 Linux 上跳过并说明原因
(基准绑在字体上,在那里它测不出任何东西),而不是红、也不是假装绿。

这正是「可复现」这个词的真实含义:不是每个字节都一样,
而是在明确的边界内能重新长出来
。


五、名字要能三个月后还认得出来

成片文件名里必须带期号 slug。这条不是审美问题,是三个月后你自己都认不出来的问题:

✅ 好 ❌ 坏
pg-parallel-decode.mp4 最终成片.mp4
csn-total-ordering.mp4 最终成片-修复音频.mp4
narration_csn-total-ordering.mp3 9-16-提高+logo尾版.mp4

规则:

  1. 英文小写连字符做 slug,不用中文、不用空格
  2. 期号贯穿全链路:契约、旁白、时间轴、片段目录、成片都按同一个 slug 命名
  3. 版本号写进文件名(v2),不要靠「最新」这种词
  4. 片段目录按期分开(build/<期号>/):各期的段 id 会重名(s01…),共用一个目录会互相覆盖

流水线也按期号切,忘了换稿会当场报错,而不是静悄悄地拿上一期的稿子出片:

cd aiv/pipeline
make EP=csn-total-ordering align      # 按这一期的旁白对齐出时间轴
make EP=csn-total-ordering all         # validate → brand → render → compose

六、口径:独立开发者视角,以及可机检的那几条

成片里的口径不靠记性,靠可机检的规则。三份规范一共 35 条硬/倾向规则,
每条都有编号,编号与代码里的规则表一一对应,由测试盯着:

规范 规则数 守什么
《人格规范》 9 营销腔禁词、机构自称、绝对化断言、能力域边界、量化依据、边界表达、方法论表达、句子宽度与长度
《选题库》 8 结构完整、关联文档真实存在、标题与钩子不命中禁词、能力域合法、实测类数字必须带作者本人归因、句数与字数硬指标
《背景音乐规范》 18 曲库技术规格、授权白名单、指纹、角色、混音 duck 深度与电平差、真峰值、片头片尾的窗口闭环
cd aiv/pipeline
make persona     # 按《人格规范》检查口播稿
make topics      # 按《选题库》的规则检查选题
make bgm         # 按《背景音乐规范》检查曲库台账
make mix-verify  # 成片级混音验收

口径上有一条不能碰的红线:内容只讲公开可验证的机制,
不站在任何产品或厂商的立场,也不把别的项目的物料说成自己的。

具体到已出的两期:

  • EP01(openGauss 的并行逻辑解码)讲的是 openGauss 的实现,
    不是 PostgreSQL 18 的能力;里面的性能倍数必须标注是作者本人在 openGauss 上
    本地压测
    的,不是厂商结论;
  • EP02(CSN 全序)讲的是 openGauss 的实现,
    不是 PostgreSQL 18 的能力——这句话收在口播稿的最后一句。

EP01 在 2026-11-12 整期重做过一次:原来它把并行解码说成 PostgreSQL 18 的功能,
还把「按事务结束顺序输出」写进了本期。归属改成 openGauss,
顺序整段留给 EP02(那才是 openGauss 真正解决顺序的方式)。


七、片头片尾:一段音乐,两个窗口

系列感靠同一首曲子反复出现。但「同一首」不等于「同一段」——
早先片头片尾各挑各的窗口:片头取「起音明显」的位置,片尾取「尾部衰减」的位置。
实测片头落在 115.15 秒、片尾落在 31.80 秒,两段互不相干,
听上去基本是两首不同的音乐——这就是「结尾和片头对不上」的真正原因。

现在的口径是片尾接回片头:片头取 s 到 s+D 这一段,片尾取 s-D 到 s 这一段,
于是 outro_start + D == intro_start——两段在原曲里紧挨着,
拼起来是同一段连续音乐,形成闭环。

选窗的判据是起音比:窗口开头 50 ms 的能量 ÷ 紧邻之前 200 ms 的能量,
比值大 = 那里有个清楚的起音,片头才「起」得起来。阈值 4.0。
旧的两个窗口起音比只有 1.60 / 1.19,新窗口 13.71。

别用相关系数判断两段是否相接。 有瞬态的音乐上这个指标没有意义
(旧口径 +0.0543、新口径 -0.0655,两个数都说明不了任何问题)。
真判据是两段在原曲里紧挨着:逐样本验证原曲里从 outro_start
到 intro_start+D 这一段,前半等于片尾窗口、后半等于片头窗口。

窗口是决策,所以入库(brand/brand_windows.json);音频是产物,所以不入库。
换曲子时重挑一次即可,不用改任何脚本。

还有一个容易踩的坑:成品音轨必须真的接进成片。
品牌片 mp4 里也烘焙了一份音轨,但那是渲染那一刻的版本——
换了配乐又没重渲 3D 形象的话,成片就会用回旧音乐。
所以品牌片的音轨以 brand/audio/*_mix.wav 为正本,mp4 里的只作兜底。


八、现在到哪了

第一季主线是机制族——同一个机制往下挖,观众跟着一条链路走完五期;
EP06 是第二季第一期,回到内核机制:

期 标题 主线位置 状态
EP01 openGauss 的并行逻辑解码 入口 已出片(正文 32.436 秒)
EP02 一个 64 位计数器,决定所有事务的提交顺序 提交顺序怎么定 已出片(正文 35.316 秒)
EP03 WAL 里的顺序,不等于事务的顺序 提交顺序怎么保 已出片(正文 34.596 秒)
EP04 并行接收之后,谁先应用 订阅端怎么落 已出片(正文 35.424 秒)
EP05 为什么 DDL 同步不能直接把 SQL 文本发过去 链路怎么扩 已出片(正文 34.128 秒)
EP06 两个事务改同一行,谁先谁后 第二季入口(内核机制) 已出片(正文 35.208 秒)

六期成片都是 1920×1080 / 24fps / H.264 yuv420p / AAC 48kHz 立体声,
外加 2.833 秒品牌片头与片尾(EP01 共 38.125 秒,EP02 共 41.000 秒,
EP03 共 40.262 秒,EP04 共 41.090 秒,EP05 共 39.833 秒,EP06 共 40.875 秒)。

另有一版无品牌导流版(横版,去掉品牌片头片尾)与一版竖版 9:16(1080×1920,
竖版那一档同时就是无品牌版——竖版不要品牌片,落版也去品牌名):
抖音那一档发的是竖版(规格 §6.6.4、§6.6.5、§6.6.6)。

成片的验收也不靠耳朵:混音要量稳态 duck 深度(6.98 ~ 6.99 dB)、
旁白与 BGM 的电平差(23.08 ~ 23.56 dB)、真峰值(-3.50 ~ -1.90 dBTP)、
旁白增益偏差(-0.03 ~ -0.02 dB),超阈值直接不合格。六期全部合格。


九、相关阅读


文章作者: growdu
版权声明: 本博客所有文章除特別声明外,均采用 CC BY 4.0 许可协议。转载请注明来源 growdu !
这篇还发到了
今日头条 drafted
  目录