HyperFrames 音频进阶：修好 TTS 旁白，重构无旁白视频节奏

HyperFrames 视频的音频生产应该分成两条独立工作流：旁白视频先完成发音词典、可朗读脚本、TTS 和词级时间，再按真实音频时长制作画面；无旁白视频则用短句动效、视觉聚焦、BGM/SFX 节拍和进度提示替代口述。两种模式都应把音频冻结为本地资产，并由 HyperFrames 统一管理播放和 Seek。

先说结论：不要把两种视频混成一条工作流

制作程序化视频时，两个最常见、也最容易被低估的问题是：

1. TTS 能发声，但读错、停顿生硬、语气不像真人。
2. 去掉旁白后，视频虽然更快生成，却变成了会动的 PPT。

这两个问题不能只靠“换一个更贵的语音模型”或“再多加几个动画”解决。真正有效的方法，是在项目开始时就选择一条明确的生产线：

旁白视频应该遵循：

先修脚本和发音
→ 再生成语音
→ 再得到真实时长
→ 最后制作画面

无旁白视频应该遵循：

先拆成视觉动作
→ 再确定阅读时长
→ 再设计 BGM / SFX 落点
→ 最后编排动画

不要先做完 30 秒动画，再把一段 37 秒的配音硬塞进去；也不要删除旁白后，只把原字幕原封不动地放在画面中央。

为什么 Raw Text 直接进 TTS 一定容易出问题

LLM 生成的文案首先是“给人阅读的文本”，不是“给语音引擎执行的脚本”。二者至少有四个差异。

1. 书面句子不等于口语句子

下面这句话适合文章，不一定适合配音：

HyperFrames 通过 HTML、CSS、GSAP 与浏览器渲染管线完成确定性视频生成。

直接朗读时，信息密度过高，英文缩写连续出现，也没有自然呼吸点。更适合语音的版本是：

HyperFrames 用 HTML 和 CSS 构建画面。停一下，再由 G S A P 控制动画，最后交给浏览器逐帧渲染。

它未必更适合做正文，但更适合说出来。

2. 中文多音字需要上下文或显式纠正

“行业”“银行”“重新”“重量”“角色”等词，对人没有难度，但 TTS 引擎可能因为上下文不足而误判。

尤其在技术教程中，短标题、代码片段和中英混排会进一步减少可供模型判断的上下文。

3. 缩写的显示方式和朗读方式不同

屏幕上应该显示：

GSAP + JSON 驱动动画

语音里可能需要说成：

G S A P，加上 J S O N，驱动动画。

因此，屏幕文案和配音文案不应该共用同一个字符串。

4. 标点只能粗略控制节奏

逗号、句号、省略号可以影响部分 TTS 引擎，但它们不是稳定、精确的音频时间轴。不同引擎、不同音色，甚至同一引擎的不同模型，对标点的处理都可能不同。

所以标点可以用来初步塑造语气，但最终仍要以生成音频的真实时长和试听结果为准。

建立三层脚本，而不是维护一份文案

一个可靠的 HyperFrames 旁白项目，建议同时维护三层文本。

SCRIPT.md                  内容与分镜的事实来源
narration.display.json     屏幕显示文案
narration.tts.txt           实际送入 TTS 的可朗读文本
pronunciation.json         专有名词、多音字和替换规则

显示文案

显示文案追求短、准、易扫读：

{
  "scene_02_title": "JSON 驱动时间轴",
  "scene_02_label": "STEP 02"
}

可朗读文案

可朗读文案追求自然发音和呼吸：

第二步，用 J S O N 驱动时间轴。
这样，内容和动画逻辑就能分开维护。

发音词典

把项目中会反复出现的词统一维护，不要每次临时修改：

{
  "aliases": {
    "GSAP": "G S A P",
    "JSON": "J S O N",
    "CLI": "C L I",
    "API": "A P I",
    "HyperFrames": "Hyper Frames"
  },
  "polyphones": {
    "行业": "hang2 ye4",
    "重新": "chong2 xin1"
  },
  "pauses": {
    "short": "220ms",
    "normal": "320ms",
    "section": "520ms"
  }
}

这份词典有三个价值：

• 同一个品牌名在全片中的读法一致；
• 更换 TTS 供应商时可以批量转换；
• Agent 下次生成脚本时能自动复用，而不是重新猜测。

SSML 很有用，但不要把它当成通用标准答案

SSML 可以描述停顿、别名、重音、语速和音素，是修正 TTS 的重要工具。例如：

<speak>
  还在手写代码？
  <break time="300ms"/>
  AI 智能体时代已经来了。

  使用 <sub alias="G S A P">GSAP</sub>，
  配合 <sub alias="J S O N">JSON</sub> 数据驱动。
</speak>

多音字也可以通过 <phoneme> 一类的标签处理，但这里有一个经常被忽略的问题：

不同 TTS 引擎支持的 SSML 标签、拼音字母表、音素格式和扩展属性并不完全相同。

因此，工业化工作流不应该只有一份写死厂商语法的 SSML，而应该采用：

中立脚本 + 发音词典
  ↓
Provider Adapter
  ↓
对应引擎可接受的 SSML 或纯文本

如果引擎不支持某个 SSML 标签，就退化为：

• 用空格实现缩写分读；
• 用同音替换或完整词组增加上下文；
• 用分句生成控制停顿；
• 生成后通过试听和转写做二次校验。

换句话说，SSML 是适配层，不应该成为内容层。

一条可靠的 TTS 生产线

第一步：先把脚本切成可独立重做的语音片段

不要把整条 60 秒旁白一次生成成一个文件。更稳妥的粒度通常是一句或一个分镜一段：

voice/
  s01-hook.wav
  s02-install.wav
  s03-compare.wav
  s04-result.wav

这样做的好处是：

• 某个多音字读错时，只重做一个片段；
• 可以单独调整某一句的语速；
• 场景时长可以直接绑定对应语音；
• 中途修改文案时不必重新生成整条视频的旁白。

但也不要切得太碎。每两个词生成一次，会破坏语气连续性。通常以“一次完整表达”为最小片段更合适。

第二步：为 Agent 增加文本预处理

让 Agent 在调用 TTS 前完成以下检查：

1. 扫描全大写英文缩写
2. 扫描中英混排边界
3. 匹配 pronunciation.json
4. 把长句拆成可呼吸短句
5. 在重点句前后加入停顿
6. 输出显示版与朗读版差异
7. 标记无法确定的专有名词

可以使用下面这段提示词：

你正在准备 HyperFrames 视频的中文旁白。

请基于原始脚本输出：
1. display_text：用于屏幕显示，短而清晰；
2. spoken_text：用于 TTS，改成自然口语；
3. pronunciation_map：列出英文缩写、品牌名、多音字的建议读法；
4. pause_plan：标出 200ms、300ms、500ms 三档停顿；
5. uncertain_terms：无法确认读法的词，不要自行猜测。

规则：
- 英文缩写默认按字母分读，但常用单词不要强行拆开；
- 每个口语句只表达一个主要意思；
- 不改变技术事实；
- 不在 display_text 中显示 SSML；
- 输出结构化 JSON，方便后续适配不同 TTS 引擎。

第三步：选择语音路线

在当前 HyperFrames 工作流中，可以把选择简化为三类：

本地生成前先查看当前可用音色：

npx hyperframes tts --list

然后把可朗读脚本生成到项目中：

npx hyperframes tts ./narration.tts.txt \
  --voice zf_xiaobei \
  --lang zh \
  --speed 0.92 \
  -o assets/audio/voice.wav

音色 ID 和语言依赖应以本机 --list 与实际环境为准，不要把某个旧教程里的音色名称永久写进流水线。

如果使用 HeyGen、ElevenLabs、火山引擎或其他外部 TTS，HyperFrames 侧真正关心的不是供应商名称，而是最终能否稳定得到：

assets/audio/voice.wav
assets/audio/voice.words.json

其中词级时间可以采用统一结构：

[
  { "id": "w0", "text": "现在", "start": 0.00, "end": 0.31 },
  { "id": "w1", "text": "打开", "start": 0.33, "end": 0.62 },
  { "id": "w2", "text": "终端", "start": 0.64, "end": 1.05 }
]

如果 TTS 不直接返回词级时间，可以在语音确定后再执行转写，得到字幕时间。

第四步：不要只听，要做“发音 QA”

一次高质量 TTS 检查至少包含四项：

转写校验不能完全替代人工试听，因为转写模型可能把错误发音“猜回”正确文字。但它很适合发现漏词、吞词和句子被截断。

第五步：音频先冻结，再做画面

音频确认后，把文件放进项目资产目录，不要在渲染时临时调用远程 TTS：

assets/audio/
  voice.wav
  voice.words.json
  bgm.wav
  sfx/
    typing.wav
    whoosh.wav
    click.wav

这样才能保证：

• 本地预览和最终渲染使用同一份声音；
• 重跑项目不会生成不同语气；
• 远程接口波动不会影响逐帧渲染；
• 音频时长、字幕和画面可以稳定复现。

在 HyperFrames 中正确挂载 Voice、BGM 和 SFX

HyperFrames 应该拥有媒体播放和 Seek 控制权。不要在 Composition 脚本中手动调用 audio.play()、pause() 或修改 currentTime。

一个基础音频层可以这样组织：

<audio
  id="voice"
  src="assets/audio/voice.wav"
  data-start="0.6"
  data-duration="18.4"
  data-track-index="20"
  data-volume="1"
></audio>

<audio
  id="bgm"
  src="assets/audio/bgm.wav"
  data-start="0"
  data-duration="22"
  data-track-index="10"
  data-volume="0.18"
></audio>

<audio
  id="sfx-confirm"
  src="assets/audio/sfx/click.wav"
  data-start="14.2"
  data-duration="0.5"
  data-track-index="30"
  data-volume="0.75"
></audio>

这里的分层逻辑是：

Voice：主信息
BGM：节奏与情绪
SFX：关键动作的确认信号

当语音进入时，可以在主 Timeline 上对 BGM 做 Ducking：

const tl = gsap.timeline({ paused: true });

// 旁白开始前降低音乐，结束后恢复。
tl.to("#bgm", {
  volume: 0.10,
  duration: 0.35,
  ease: "power2.out"
}, 0.35);

tl.to("#bgm", {
  volume: 0.18,
  duration: 0.7,
  ease: "power2.inOut"
}, 19.0);

window.__timelines["hf-audio-demo"] = tl;

data-volume 是基础音量，淡入、淡出和 Ducking 应放在可 Seek 的 Timeline 上，这样预览与渲染才能得到一致结果。

字幕不应该只是旁白的全文复制

有旁白时，屏幕上通常同时存在三种文字：

1. 字幕：帮助静音观看和理解语音；
2. 画面标题：说明这一幕的结论；
3. 界面或代码文字：作为演示对象存在。

如果三种文字都重复同一句话，观众会同时面对三份相同信息。

更好的分工是：

字幕可以跟随词级时间做 Karaoke 高亮，但不要让每个词都剧烈跳动。高亮用于建立同步感，重点词再使用更强的颜色、缩放或标记动效。

“无旁白”不是“无声音”

很多教程把 Silent Video 理解成完全静音。更准确的说法应该是：

No Voice-over：没有人声旁白，但仍然可以有 BGM 和 SFX。

真正完全静音的视频，只适合非常短、信息极简单或平台自动静音播放的特殊场景。对于 15 秒以上的技术教程，BGM 和 SFX 往往承担着原本由人声负责的节奏提示。

无旁白视频的关键不是删掉 Voice Track，而是把旁白的功能重新分配给四套视觉与听觉信号：

动效文字：告诉观众“发生了什么”
视觉聚焦：告诉观众“看哪里”
BGM / SFX：告诉观众“什么时候发生”
进度提示：告诉观众“还剩多少”

无旁白教程的四维视觉框架

第一维：Kinetic Text 代替口述

无旁白视频中，文字是主叙事元素，但文字不能变成文章截图。

可以使用三个约束：

• 每个画面只表达一个主要结论；
• 主标题尽量控制在 5～12 个汉字；
• 一次只强调一个关键词或一个命令片段。

例如，不要显示：

接下来我们需要在终端中运行安装命令，然后等待所有依赖安装完成。

改成连续三个视觉动作：

STEP 01 / 打开终端
        ↓
粘贴安装命令
        ↓
安装完成 ✓

适合使用的文字动作包括：

• 逐字输入：命令、搜索词、Prompt；
• Scramble / Decode：章节标题、系统状态；
• Kinetic Slam：重要结论；
• Highlight Sweep：参数、数字、关键词；
• 数字递增：时间、成本、性能差异。

但不要在同一幕同时使用五种文字效果。一个场景选择 2～4 条一致的动作规则，通常已经足够。

第二维：Zoom、Spotlight 和 Cursor 负责指路

没有旁白时，观众不知道当前应该看按钮、代码还是结果区域。

可以建立一条固定的视觉聚焦顺序：

全局建立画面
→ 非目标区域轻微变暗
→ 目标区域放大 1.08～1.20 倍
→ 光标或箭头移动到目标
→ 点击或高亮确认
→ 恢复全局视图

“变暗”不应该把其他信息完全抹掉。背景仍然要保留足够上下文，让观众知道目标位于哪个界面区域。

对于代码场景，优先高亮一行或一个参数，而不是整块代码一起发光。

第三维：SFX 与 BGM 建立节拍

无旁白视频的音效不是装饰，而是时间结构。

一个常见错误是：画面里每动一下就播放一次音效。结果会像系统通知连续弹出。

更好的原则是：

SFX 只服务动作落点，不服务所有动作过程。

例如一段终端输入可以只包含：

开始输入：一次轻键盘起音
命令完成：一次清晰 Tick
回车执行：一次 Click
成功结果：一次 Confirm

BGM 则负责更长周期的结构：开场建立能量、步骤之间维持节奏、结尾形成释放。尽量把大转场、数字落点和结论出现安排在明显拍点附近。

第四维：进度提示建立完成预期

无旁白教程容易让观众失去“还要看多久”的判断。可以使用：

• 顶部 Progress Line；
• STEP 1 / 3；
• 三段式章节圆点；
• 当前步骤高亮；
• 剩余步骤淡化。

在 HyperFrames 中，可以让顶部进度条由同一条可 Seek Timeline 驱动：

<div class="progress-shell" aria-hidden="true">
  <div id="progress-line"></div>
</div>

.progress-shell {
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
  height: 8px;
  background: rgba(255,255,255,.12);
}

#progress-line {
  width: 100%;
  height: 100%;
  background: #f7e34d;
  transform: scaleX(0);
  transform-origin: left center;
}

const duration = 24;
const tl = gsap.timeline({ paused: true });

tl.to("#progress-line", {
  scaleX: 1,
  duration,
  ease: "none"
}, 0);

window.__timelines["hf-silent-tutorial"] = tl;

这里不要读取系统时间，也不要通过 setInterval 更新进度。进度必须由 Composition 的确定性时间轴驱动，才能正确响应 Snapshot、Seek 和逐帧渲染。

把有旁白分镜改造成无旁白分镜

原始有旁白场景通常以“说了什么”为中心，无旁白场景则必须改成“观众看见了什么动作”。

示例一：终端安装

示例二：方案对比

这个转换过程不是删除旁白，而是把每一句话改写为：

建立动作 + 聚焦动作 + 结果动作 + 停留时间

无旁白视频的阅读时间怎么算

无旁白视频最容易出现的问题，是 Agent 按动画速度排场景，却没有按人的阅读速度排场景。

可以使用一个保守估算：

短标签：0.6～1.0 秒
5～8 个字的结论：1.2～2.0 秒
一行命令：2.0～3.5 秒
两组对比数据：2.5～4.0 秒
需要理解的代码差异：至少 4～6 秒

这不是固定标准，而是制作初稿时的安全区间。真正检查时，应在正常播放速度下确认：

• 文字是否来得及读完；
• 观众是否知道先看哪里；
• 结论是否有停留；
• 下一幕是否在理解完成前就切走。

不要通过把所有动画减速来解决可读性。更有效的方法通常是减少同屏文字、减少并行动作，并增加关键结论的 Dwell。

两条生产线如何落到 HyperFrames 项目结构

建议在项目中显式声明模式：

# BRIEF.md
mode: voiceover   # voiceover | no-voiceover
language: zh-CN
duration_target: 30s

然后分别使用不同的产物依赖。

旁白驱动项目

BRIEF.md
SCRIPT.md
pronunciation.json
narration.tts.txt
assets/audio/voice.wav
assets/audio/voice.words.json
assets/audio/bgm.wav
STORYBOARD.md
index.html

依赖顺序：

SCRIPT
→ pronunciation + spoken text
→ voice.wav + words.json
→ STORYBOARD 场景时长
→ Composition
→ captions

无旁白驱动项目

BRIEF.md
STORYBOARD.md
beat-map.json
assets/audio/bgm.wav
assets/audio/sfx/
index.html

依赖顺序：

STORYBOARD
→ 阅读时长
→ BGM 与 beat map
→ SFX 落点
→ Composition
→ 进度与聚焦动效

两种模式共享的资产包括：

frame.md
品牌 token
字体
图标
图片与视频素材
可复用 Block
验证脚本

Registry 可以提效，但先查 Catalog

终端、代码、字幕、转场和进度类场景适合优先从 Registry 复用。不过不要在 Prompt 里假设 terminal-block、bento-grid 或某个描述性名字一定存在。

先查询当前 Catalog：

npx hyperframes catalog --json

然后让 Agent 根据用途筛选：

terminal / code / caption / progress / transition / lower-third

安装后再根据它是 Block 还是 Component，选择独立挂载或合并进现有 Composition。Registry 名称会演进，工作流应该依赖实时 Catalog，而不是依赖文章中写死的旧名字。

验证音频视频时，不要只看最终 MP4

音频项目同样应该使用从便宜到昂贵的检查梯度：

脚本与发音词典审查
  ↓
单段 TTS 试听
  ↓
语音转写差异检查
  ↓
音频时长与场景时长检查
  ↓
lint
  ↓
check
  ↓
关键时间点 snapshot
  ↓
preview
  ↓
草稿 render
  ↓
最终 render

旁白模式重点检查

• Voice 是否在场景进入后才开始；
• 字幕高亮是否和词级时间一致；
• BGM 是否压住辅音和句尾；
• 场景是否在旁白结束前切走；
• 旁白结束后是否保留了适当停留时间；
• 同一个缩写在不同场景中是否读法一致。

无旁白模式重点检查

• 静音播放时是否仍能完全理解；
• 有声音播放时 SFX 是否强化了关键落点；
• 任何 2～3 秒内是否同时出现过多焦点；
• 进度是否与真实时长同步；
• 命令和代码是否有足够阅读时间；
• BGM 节拍是否和重要转场明显错开。

推荐的关键时间点

每一幕至少检查：

进入后 0.1 秒：是否闪现、是否抢跑
建立阶段中点：构图和阅读顺序是否清楚
动作落点：SFX、缩放、高亮是否同步
高潮停留：结果是否完整可读
离场前 0.1 秒：是否提前消失或残留

常见错误与修复方法

一份可以直接交给 Agent 的进阶指令

请为这个 HyperFrames 教程项目建立音频与节奏生产线。

第一步，读取 BRIEF.md，明确 mode 是 voiceover 还是 no-voiceover。

如果是 voiceover：
1. 从 SCRIPT.md 生成 display_text 与 spoken_text；
2. 建立 pronunciation.json，覆盖英文缩写、品牌名和中文多音字；
3. 长句改成自然口语短句，保留技术事实；
4. 先分段生成 TTS，再试听并做转写校验；
5. 将确认后的语音和词级时间冻结到 assets/audio；
6. 根据真实语音时长更新 STORYBOARD；
7. 为字幕、标题和界面文字分配不同的信息职责；
8. BGM 在旁白期间做 Ducking，SFX 只强化关键动作。

如果是 no-voiceover：
1. 不要直接删除旁白后保留原画面；
2. 把每一句解释改成建立、聚焦、结果、停留四阶段；
3. 每幕只保留一个主要结论；
4. 使用 Kinetic Text、Zoom/Spotlight、SFX 和 Progress Indicator；
5. 按阅读时间决定场景长度；
6. 将转场、点击、完成和数字落点对齐到 BGM 节拍；
7. 即使完全静音播放，也必须能理解完整流程。

共同规则：
- 所有媒体下载并冻结到本地；
- 不在 Composition 中调用 audio.play、pause 或手动 seek；
- 使用一个 paused、可 Seek 的主 Timeline；
- 不使用 Date.now、setInterval 或不可复现随机数驱动画面；
- Registry Item 必须先通过 catalog --json 查询真实名称；
- 依次执行 lint、check、snapshot 和 preview；
- 最终预览确认前不要直接渲染高质量 MP4。

最终选择：什么时候用旁白，什么时候不用

可以使用下面的判断表：

还可以采用混合模式：开头 3 秒用旁白建立问题，中间操作步骤改用短文字与 SFX，结尾再用一句旁白收束。这样既保留人声温度，又减少整片语音对齐成本。

总结

高质量 TTS 的关键，不是把 Raw Text 直接交给一个更贵的模型，而是建立：

显示文案
+ 可朗读文案
+ 发音词典
+ Provider Adapter
+ 试听与转写 QA
+ 真实音频时间轴

高质量无旁白视频的关键，也不是简单删除 Voice Track，而是用：

Kinetic Text
+ Visual Focus
+ BGM / SFX Sync
+ Progress Indicator

重新承担旁白原本负责的信息、注意力、节奏和完成预期。

对 HyperFrames 来说，两条路线最后会汇合到同一个工程原则：媒体必须本地化，时间轴必须可 Seek，播放必须由框架管理，所有关键画面都必须能够在任意时间点稳定复现。

系列导航

• HyperFrames 原理详解：AI Agent 如何把 HTML 渲染成视频
• HyperFrames Skills 实战：从 Brief 到 MP4 生成第一条视频
• HyperFrames 进阶：提高画面质量与生产效率
• 玩转 HyperFrames：从 AI Coder 到 AI Layout Driver
• HyperFrames 官方 Registry：Agent 自动查、拉、挂、验
• HyperFrames Registry：Block + JSON Schema 视频流水线