企业官网建设流程全解析

你是否好奇，prehistoric-animal-museum 里那些温柔连贯的中文、英文讲解旁白到底从何而来？这个免费开源的双语 3D 恐龙博物馆，为 24 种史前动物制作了"开场—靠近—抵达"三段式连续旁白。全部音频由 Qwen3-TTS 大模型在本地离线生成：把三段文案拼成一次输入，合成一条不间断的主音频（master），统一归一化后再从自然停顿处精确切回三个 MP3 片段。本文带你完整看懂这套"生成 → 归一化 → 切分"的旁白流水线。

三段式旁白：一次探险的三个瞬间

在"尺度遭遇"（scale-encounter）体验中，孩子和大人会跟随旁白走近一只史前动物，整个旅程被拆成三个阶段：

每个阶段的一句话文案都写在 narration-scripts.json 中，按"动物 × 语言（zh-CN / en）"组织。以剑龙中文开场为例：

小朋友，准备好了吗？背上小背包，我们穿过树林，去寻访一只剑龙。它从头到尾有八米，你猜自己能到它身体的哪里？

为什么三段文案要"一次说完"

最直观的偷懒做法是：三句话分别调用 TTS，得到三个 MP3。但这样做有三个问题：

• 语气割裂：三次独立生成的停顿节奏、气息和音调各不一致，拼起来像三个人在说话；
• 响度不一：每个片段单独归一化，衔接处会忽大忽小；
• 衔接点生硬：句末的停顿没有"呼吸感"，听起来像被剪断的录音。

ANIMAL_AUTHORING_GUIDE.md 中明确写入了这条连续性规则：intro、transition、arrival 被视为同一条旁白，必须一次输入、一次归一化、之后再切分，绝不允许三段各自独立生成。

生成流水线：一条命令完成四步

核心脚本是 generate-scale-encounter-continuous-narration.py，用项目共享的 Qwen 虚拟环境执行即可：

../../../../../.runtime/qwen3-tts/venv/bin/python \ scripts/generate-scale-encounter-continuous-narration.py

整条流水线分为四步：

1. 拼接文案：把三种阶段的文案用换行符连接成continuousScript，作为一次 TTS 输入（脚本内注释说"换行能强化两个剪辑点，又不破坏单次输入、单次 master 的约定"）。
2. 调用 Qwen3-TTS：加载Qwen/Qwen3-TTS-12Hz-0.6B-CustomVoice模型，使用内置的Serena音色（与静态展馆旁白同一声线），在 CPU 上以float32 + sdpa推理，并固定随机种子20260823保证可复现。
3. 归一化一次：用 FFmpeg 裁掉首尾静音，整条 master 提速 1.04 倍（只改速度、不改音调），再经两遍loudnorm（集成响度 I=-18 LUFS、真峰 -1 dBTP、LRA 7）输出 48 kHz 单声道 24-bit 无损 WAV 主音频。
4. 按样本切分：在自然停顿处把 master 切成三段，逐段编码为 80 kbps MP3，覆盖到 src/scale-encounter/audio/ 目录。

一个细节很讲究：脚本会为同一批任务生成两次（--runs 2），要求两次的原始 WAV 逐字节一致，否则直接报错——这是在用"重复运行哈希比对"来守护生成结果的可复现性。

切分点怎么选：让机器找"自然停顿"

切分不是机械地对半分，而是一个带约束的搜索问题：

• 先估期望位置：按每段文案的字数（中文按汉字/字母计，英文按音节近似）和句末停顿数量，估算每段应占的时长，得到两个"期望分界点"（见 expected_boundary_seconds）。
• 再搜自然停顿：用 FFmpeg 的silencedetect（阈值 -50 dB、最短 20 ms）扫出所有静默区间，只保留足够长且不在首尾的候选。
• 最后打分择优：枚举候选停顿组合，以"偏离期望位置的距离"为主、"停顿时长对数"为奖励，选总分最优的切点。若切点偏离期望超过 2.75 秒，脚本会拒绝并提示"先听完再人工覆盖切点"。

切分以精确样本索引（48 kHz 下的采样点）为准，而不是秒数，保证三个片段首尾严格相邻、无缝可拼接（见 encode_slice）。

结果如何被浏览器消费

切分完成后，每个动物每种语言得到三个 MP3，命名稳定，例如stegosaurus-intro.zh-CN.mp3、stegosaurus-transition.zh-CN.mp3、stegosaurus-arrival.zh-CN.mp3，全部位于 src/scale-encounter/audio/。

两个 JSON 文件是"旁白账本"：

• transition-durations.json：记录每种动物 transition 段的实际毫秒数，运行时用它精确对齐旁白与镜头推进；
• narration-candidates.json：候选清单，记录模型版本与修订号、种子、目标响度、每条切片的 SHA-256、所属 master 的哈希与精确采样区间（startSample/endSample），以及人工试听审批状态。

运行时，content.ts 把三个文件路径注册进每种动物的audio配置，intro → transition → arrival依序播放，配合 transition-durations.json 的时长驱动场景过渡。

证据链与人工试听

所有中间产物——原始运行 WAV、归一化 master、听审预览、检测到的停顿、精确切点——都保存在被 git 忽略的 handoff 证据目录里，并生成一份manifest.json；入库的候选清单与它一一对应，任何人都可以拿哈希复核"这三段 MP3 确实切自同一条 master"。

值得注意的是，脚本跑完只把状态置为pending：旁白从不自动放行。文案、多音字发音（比如"重爪龙"的 zhòng 音通过 pronunciation overrides 处理）、节奏、切点都要经过人工完整试听，记录审批人、日期与证据后才算approved，才能进入正式发布。

小结

• 三段文案一次输入 Qwen3-TTS（Serena 音色、固定种子、CPU 推理），保证语气与音色连贯；
• 整条 master 只做一次 1.04x 提速与 loudnorm 归一化，避免逐段处理的响度割裂；
• 切分点由"期望位置估计 + 静默检测 + 打分择优"决定，并以精确样本对齐，偏差超阈即拒绝；
• 每次运行留下完整证据链（哈希、采样区间、模型修订号），人工试听审批后才可发布。

这套"连续生成、一次归一化、自然停顿切分"的做法，是低成本获得电台级连贯旁白的实用方案，也值得任何需要多段语音导览的互动项目借鉴。