explainer-video

---
name: explainer-video
description: >-
  Produces animated explainer videos (MP4, landscape 1920×1080 or portrait 1080×1920) for a feature,
  algorithm, architecture or mechanism: narration script → Doubao TTS 2.0 voice with word timestamps (or a
  no-voice version paced for reading, when there is no TTS key) →
  Revideo scenes (responsive layout, hand-drawn Excalidraw-style sketches, Gruvbox palette) → MP4 with
  burned-in + soft subtitles, a QA report and a contact sheet. Use when the user asks for an explainer /
  讲解视频 / 科普动画 / 3b1b 风格视频 / 竖屏短视频 / 分镜脚本, or iterates on such a video's script,
  voice, pacing, subtitles/字幕, visuals or layout.
---

# 讲解视频

流程：**写旁白脚本（用户确认）→ 生成配音和时间轴 → 为这支片子设计画面、写 Revideo 场景 → 截一段看效果 → 后台全量渲染 → 看 QA 和接触表 →（用户要配乐时）铺背景音乐 → 按反馈迭代**。

## 硬约束

- **TTS key 不写进任何文件、提交或输出**，用户在对话里贴了 key，提醒其轮换。key 的存放和读取见 [setup.md](setup.md)。
- **没有豆包 key 时不卡住**：先问用户要不要配置 key；用户没有或不想配，就做无配音版本（见「3. 配音和时间轴」的「无配音模式」），不要因为缺 key 停下。
- 每支片子一个独立目录：用户指定了位置就用用户的，否则用当前工作目录下的 `videos/<slug>/`。产物（mp4、png、build/）不放进任何代码仓库。
- **片子之间互相隔离**：只读写当前片子的目录。不要打开、引用或改动 `videos/` 下别的片子；新片子一律从 `$SKILL/template/` 起步，不从旧片子复制。迭代已有片子时沿用原目录，递增版本号。
- 成片、接触表、封面、`.srt` 都输出到当前片子的 `renders/`，不要写到父目录。
- 长渲染放后台并把输出重定向到日志。
- 未经用户听过，不宣称"音画同步 / 发音正确"已验证。QA 只能证明动画按时间轴触发、布局没有撞车。
- **脚本先给用户确认再配音**：跑 `narrate.mjs` 之前，把旁白（含 2–3 个备选 hook 和 2–3 个备选封面标题）发给用户，等用户确认。迭代时改了旁白也一样。
- **用图形讲，不做 PPT**：每一幕的主角是一张会动的图，不是一个装着句子的框。见「画面：用图形讲，不做 PPT」。
- **默认带字幕**：烧进画面的硬字幕 + MP4 软字幕轨 + 同名 `.srt`。只有用户明确不要硬字幕时才加 `--no-burn-subs`。

## 搭工作目录

按 [setup.md](setup.md) 从 `$SKILL/template/` 建好片子目录。模板自带一个二分查找的演示（`script.json` + `src/scenes.tsx`），**只用来演示机制**：时间锚点、手绘图形、响应式布局。新片子先把它整个替换掉，不要沿用它的版式。

## 1. 先问清楚

用 AskQuestion 一次问完：讲哪个机制（宁窄勿宽）、给谁看、多长、**横屏还是竖屏**、产品对外叫法。

## 2. 旁白脚本 `script.json`

```json
{ "size": "1080x1920", "voice": "zh_female_xiaohe_uranus_bigtts", "rate": 20,
  "scenes": [{ "id": "hook", "beats": [{ "id": "ask", "say": "旁白", "sub": "字幕（可选）", "pause": 0.1 }] }] }
```

- 一个 beat 是一句旁白，`id` 全片唯一。`silent: 秒数` 表示无旁白的停顿。
- **配音语气**：`narrate.mjs` 里的 `BASE_CONTEXT` 是默认的配音风格（科技博主给朋友讲、节奏紧凑、语速适中、吐字清楚、中英文连贯、句间停顿短），每次请求都会带上。用户没要求换风格时**不要删改或替换**；用户想要别的风格时，先出 A/B 样本让他听，定了再改 `BASE_CONTEXT`。`script.json` 的 `context` 可选，只用来为这支片子补充一句（比如「讲到两边的差距时加重语气」），会接在 `BASE_CONTEXT` 后面。
- 技术名词保留英文。容易读错的数字写成汉字，再用 `sub` 让字幕显示阿拉伯数字。
- 写好后按「硬约束」发给用户确认：2–3 个备选 hook、2–3 个备选封面标题（见「封面」）、完整旁白、每幕一句画面构想（说清楚画的是什么图，而不是屏幕上写什么字）。

写法上的建议，按主题取舍，不是固定结构：

- 屏幕上只放名词、数字和图；整句交给旁白。
- 能在同一张画布上演变就不要翻页：变暗旧内容、圈出重点、把东西移到新位置。
- 颜色语义在一支片子内保持一致（见 `src/theme.ts` 的角色）。
- 封面（第一幕）和片尾品牌卡每支片子都要有，见「封面」「开场」「结尾」「频道品牌和水印」；梗之类的看片子气质决定。

## 3. 配音和时间轴

```bash
node narrate.mjs                    # 用 script.json 的 size
node narrate.mjs --size 1920x1080   # 临时换画幅（字幕换行宽度跟着变）
```

产出 `src/timeline.json`（每个 beat 的起止和逐字时间戳、字幕）、`build/narration.wav`、`build/captions.srt`。原理和常量见 [reference.md](reference.md#配音细节)。

- 整篇旁白**一次请求**合成、整段播放，幕和句子都只是这段音频里的时间标记，句间、幕间停顿由模型决定（用 `context` 控制）。接口嫌文本太长时自动在幕边界切成 2 段、再不行切成 3 段，终端打印 `tts: N request(s)`；不要改回每幕一次。`silent` beat 会打断语调，尽量少用。
- 终端出现 `AUDIO QA:` 说明自动重试后仍有卡顿或截断，请用户听那一幕。用户听出某句卡而检测没报：`node narrate.mjs --redo <beatId>`。口误、读错字只能靠用户听。
- 字幕断得别扭时，改写那句旁白，或用 `sub` 手动调整。
- 有缓存：只改画面不会重新合成；改了任何一句旁白，整篇会重新合成（同一个请求），整片的语气和停顿都会和上一版不同，交付时提醒用户整片重听。`--redo <beatId>` 同理会重做它所在的整个请求。
- 挑音色：`node $SKILL/tts/server.mjs`（http://127.0.0.1:8765 试听），或 `RATE=20 node $SKILL/tts/batch.mjs <speaker>` 批量出样本。加速一律用 `rate`（不变调）。

### 无配音模式（没有豆包 key）

```bash
node narrate.mjs --no-voice          # 或在 script.json 里写 "voice": "none"
```

不调用 TTS，也不需要 key。每句按阅读速度排时间（默认每秒 5.5 个字，`script.json` 的 `"readRate"` 可改；逗号、句号处略停，每句至少 1.2 秒），逐字时间按同样的速度推出来，所以 `cue.on('beatId', '某个字')` 照常可用。`build/narration.wav` 是一段等长的静音，后面的 `render.mjs`、`bgm.mjs` 不用改。

- 这时**字幕就是旁白**：必须烧硬字幕，不要加 `--no-burn-subs`。旁白照常写成完整的句子，但要更短、更好读；`sub` 仍可用来把数字写成阿拉伯数字。
- 画面更要「用图形讲」：观众要一边读字幕一边看图，图不能再塞文字。
- 建议配上背景音乐，否则整片无声。`bgm.mjs` 发现视频里没有人声时，把音乐当主音轨放到 `--level`（默认 -20 LUFS）。
- 交付时说明这是无配音版本；以后有了 key，只需去掉 `--no-voice` 重跑 `narrate.mjs` 和 `render.mjs`，场景代码不用改（动画会自动对齐到真实配音的时间）。

## 4. 设计画面，写 `src/scenes.tsx`

**每支片子先想它自己的视觉点子**：这个机制最适合用什么图来讲？是一排格子、一条流水线、一棵树、一张坐标图，还是一段代码在变？再决定构图。不要套用上一支片子的版式。

### 画面：用图形讲，不做 PPT

一图胜千言。观众关掉声音、不看字幕，也应该能从画面看懂这一幕在讲什么。所以每一幕先问：**这句话画出来是什么样子？**

- 数量画成长度、面积或个数：「翻倍」是一根柱子长到两倍，「一百万」是一大堆，「砍掉一半」是那堆东西真的少了一半。
- 过程画成东西在动：请求沿箭头流过一条流水线，文件从一边飞到另一边，格子一个个被划掉。
- 对比画成并排的两张图，差别一眼可见（长短、多少、快慢），不要写成两段文字。
- 结构画成图：树、层、网、时间线、坐标图；角色画成小图标（文件是一页带横线的纸，人是小人，模型是一个方块大脑），不要写成名字框。
- 文字只做标签，点出图里的东西是什么；整句交给旁白。
- **不要**：标题加要点列表；一排框，每个框里一句话；满屏的问题气泡；一张「文字卡」飞进来再飞出去。这些都是 PPT，不是动画。
- 实在要出现一句原话（论文里的一句定义、用户原话）时，让它成为画面里的一个物件（一页纸、一个对话框）配合图形出现，而不是整幕的主角。

`render.mjs` 会在 `QA style` 下提示框里只装了一句话、没有任何图形的地方（`text in a box`）。看到就改成图；确实需要（比如引用原文）时在交付时说明。

机制（细节见 [reference.md](reference.md)）：

- `const cue = cues('sceneId')`，`cue.at(cue.on('beatId', '某个字'), () => 动画, 'label')`：在旁白念到那个字前 0.25s 触发。只在动画和字无关时才写秒数。最后 `yield* cue.run(view)`，它负责字幕、QA 探针、手绘抖动，并让场景正好持续到旁白结束。
- `frame(view)` 给出 `w / h / portrait / u / safe`。尺寸一律写成 `n * u`（短边 1080 时 u=1），用 flex 布局并按 `portrait` 切换方向，横竖屏共用一套代码。内容默认放在 `safe` 区内（竖屏约为上留 15%、下留 26%，内容落在画面中部）。这是建议的排版区，不是硬限制：需要时可以超出。竖屏字幕在画面约 76% 高度处（避开短视频平台底部的标题、简介和按钮），底色半透明，可以轻微压住图的下沿，但别让字幕盖住主要文字。
- 装文字的框不要写死 `width`：让 `<Sketch layout padding>` 按文字撑开；需要等宽对齐时用 `minWidth`，或把宽度设得比最长的标签宽。否则文字会冲出框（QA 的 `overflows box` 会让渲染失败）。
- 手绘风格：`<Sketch>` 是可以带 `layout` 和子节点的手绘框或椭圆，`<Ink points>` 是手绘线和箭头，`draw(node)` 一笔一笔画出来。地图、坐标区这类「东西必须画在里面」的框写成 `<Sketch contain>`，QA 会报出越过它边框的图形和文字。字体是 Excalifont（拉丁字母）和小赖（中文）。等宽代码用 `MONO`。
- 默认调色板是 Gruvbox Dark，按角色命名（`C.primary / highlight / good / bad …`）。用户要别的风格时改 `theme.ts`；不想要手绘效果就把 `ROUGH.roughness` 设为 0、`BOIL_FPS` 设为 0。

## 频道品牌和水印

模板自带一套**示例品牌**：账号名 `403-error`，头像是手绘的奥本海默（圆框、平顶帽、帽带、烟斗和一缕烟）。这是本 skill 作者自己的频道，只用来演示。

- **第一次为一个用户做片子时，先问他的账号名和片尾 CTA**，在 `src/theme.ts` 的 `BRAND` 里改掉示例品牌再渲染。之后同一个用户的片子沿用他的设置，不用每次都问。
- 用户不需要品牌时，把 `BRAND.name` 设为空字符串：水印自动关掉，`script.json` 和 `project.ts` 里也不加 `brand` 幕。
- 头像：用户有想要的形象时，按描述改 `src/brand.tsx` 的 `STROKES`（以半径为单位的几笔手绘线）；没有就把 `STROKES` 清空，只留一个圆框。

品牌用在三个地方：

- **全程水印**：`cues()` 默认在左上角放半透明的「头像 + 账号名」（竖屏下移 100u，避开状态栏）。只有本身已经展示品牌的场景（封面、片尾品牌卡）才用 `cues(id, { watermark: false })` 关掉。
- **封面（第一幕结尾）**：一行小的 `<Avatar>` + 账号名（或保留角落水印），放在封面窗口内、标题之外，见「封面」。
- **片尾品牌卡**：`script.json` 最后加 `{ "id": "brand", "beats": [{ "id": "cta", "say": "关注我，看更多。" }] }`，`project.ts` 末尾加 `brandOutro('论文：…，arXiv …')`（来自 `src/outro.tsx`）。见「结尾」。

定制点都在这几处，场景代码不写死品牌：

- `src/theme.ts` 的 `BRAND`：账号名 `name`、片尾文案 `cta`。
- `src/brand.tsx` 的 `STROKES`：头像笔画；`Watermark` 的大小和透明度。
- 片尾配音那句 CTA 在 `script.json` 的 `brand` 幕里。

品牌定下来以后，用户没明确要求时不改账号名、头像和水印位置。

## 封面

封面决定观众点不点进来。它是第一幕的最后一帧（`render.mjs` 存成 `-cover.png`，此时字幕会自动撤掉），所以第一幕要收在一个完整的封面构图上。

- **内容集中在画面中部**：信息流常把竖屏封面裁成 3:4，只露出中间部分。标题和主图都放在 `frame(view).cover` 窗口里（竖屏是画面正中的 1080×1440 再留 60u 边，横屏是四周留 5%）。标题放在窗口中央略偏上，不要贴着顶部或底部。
- **大字、少字**：主标题短、字号大，是整张封面最显眼的东西，关键词用 `C.highlight` 或 `C.bad` 着色。其余文字越少越好。
- **一张图**：标题之外只放一个主图（一个对比柱、一个数字、一个关键物件），不放第二段说明、出处、日期、要点列表。出处放进片尾品牌卡和视频简介。
- **让人想点**：标题直接给出最有收获的结论或最醒目的数字（例如「100 万个数只看 20 次」「加一个 skill，成绩翻倍」），让人一眼知道看完能得到什么。说法要在原始资料里找得到依据；措辞完整、不过分口语；屏幕上不用「·」做分隔符（用「，」「、」「：」）。
- 写脚本时就给 2–3 个备选封面标题，和 hook 一起让用户挑。

`render.mjs` 会在 `QA cover` 下报告封面帧上跑出中部窗口的文字。

## 开场

观众在头几秒决定要不要看下去，所以开头就要让人觉得「有收获」。

- **第一句就把最重要的内容说出来**：可以长一些，直接讲清这支片子最核心的结论或发现（是什么、为什么重要、差别有多大），让观众听完第一句就已经学到东西。不打招呼，不念标题，不讲背景，不说「今天我们来聊聊」。
- **不用提问做钩子**：不要用「怎么做到的？」「你知道吗？」这类问题开场或吊胃口，问题本身不给观众任何收获。第一句讲完结论，接着直接进入演示或展开。
- 外行要听得懂：开场不出现观众可能不认识的名字和缩写（比如「JEV」），先用大白话说，名字等正文需要时再介绍。
- 不标题党：说法要能在原始资料里找到依据。
- **画面第一帧就有主角**：第一帧不是空白或一个小标题，主图从一开始就在，并且马上开始动。hook 的画面也遵守「用图形讲」：把第一句的结论画出来。
- 第一幕同时是封面：封面上的其他信息在这一幕里陆续出现，最后一帧是完整封面（见「封面」）。

模板自带的例子：「二分查找每次把范围砍掉一半，所以一百万个数里找一个，最多只要看二十次。」第一帧就是一根代表一百万个数的长条，每看一次缩短一半，次数从 0 跳到 20 并被圈出来；接着「用七个数演示一遍」直接进入演示。最后一帧是封面：「100 万个数 / 只看 20 次」加那根缩没了的长条。

`render.mjs` 会在 `QA hook` 下报告第一帧是空的、开场迟迟不动。另外看 `-hook.png`（0–5 秒的画面条）：画面应该在变化，第一格就有主角。

## 节奏

- 停顿整体控制在 0.1–0.2s：`narrate.mjs` 会把句间、幕间超过 0.2s 的静音压到 0.2s。整篇一次合成，`pause` 只在整片最后一句（或 `silent` beat 前）生效，其余位置的停顿交给模型和 `context`，不用写 `pause`。
- 不让观众等：不写「想三秒」「暂停一下」这类句子；要观众参与，就提问后马上演示。
- 删掉不改变理解的句子，背景压缩成一句放在需要它的地方。

## 结尾

观众一感觉到「要结束了」就会划走，所以结尾越快越好。

- **最后一幕收在结论上**：讲完最后一个要点（或回答开头的问题）就结束，最多两句。不写「总结一下」「以上就是」「希望对你有帮助」，不把前面的内容再列一遍。最后一句不加 `pause`。
- **品牌卡配一句短 CTA，要快**：`brand` 幕只念一句短话（例如「关注我，看更多。」）。头像、账号名、出处一开场就全部出现，CTA 文字跟着念到的字出现，念完 0.15 秒就结束，不留空镜。品牌卡不显示字幕（卡上已经有 CTA 文字）。

`render.mjs` 会在 `QA outro` 下报告超过 2 秒的品牌卡。

## 5. 看效果，再全量渲染

```bash
npx tsc                                         # 类型检查（秒级）
node render.mjs --range 4,12 --out renders/try.mp4   # 只渲染一段，快速看
node render.mjs --out renders/<slug>-v1.mp4 > build/render.log 2>&1   # 全量，后台运行
```

`render.mjs` 每次都会输出：

- `<out>-sheet.png`：每句旁白结束时的画面拼成的接触表。**用 Read 逐张看**：标签是否贴对、该出现的有没有出现、构图是否拥挤。几何检查抓不到这些问题。
- 终端和 `build/qa.json` 里的 QA：
  - `overrun`：动画结束时已进入下一句，或场景结束时被截断；
  - `layout`：文字出界、重叠、字号过小、被字幕挡住、**超出所在的手绘框**（`overflows box`，出现即 `render.mjs` 以退出码 2 失败，必须修掉再交付）；手绘框、椭圆、圆点跑出屏幕；图形或文字越过 `<Sketch contain>` 框的边线（`crosses frame`）。线和箭头不查，它们常常故意穿过框线。
  - `cover` / `hook` / `style` / `outro`：对照「封面」「开场」「画面：用图形讲」「结尾」的规则给出的提示，不会让渲染失败。能改就改；不改时交付时说明原因。
- `<out>-hook.png`：前 5 秒的画面排成一条，用来看开场是否抓人。
- `<out>.srt` 和 `<out>-cover.png`（第一幕结尾的画面）。

渲染出错（场景代码抛异常、控制台 error）时脚本会以非零退出，并打印错误。Revideo 遇到这类错误时可能仍会产出视频，只是画面空白，所以别只看有没有生成文件。

## 6. 交付

交付时内嵌开场画面条（`-hook.png`）、接触表或封面，说明时长、画幅、路径、相比上一版改了什么，以及**待用户确认的项**（音画同步、发音、画面风格）。每轮迭代递增版本号，保留旧版。交付前的格式和响度检查见 [setup.md](setup.md#交付前检查)。

## 7. 背景音乐（用户要配乐时）

成片渲染完、画面和配音都定了以后再铺，`bgm.mjs` 只动音轨，视频和字幕轨原样复制，所以改音乐不用重新渲染。

```bash
node bgm.mjs renders/<slug>-v1.mp4 $SKILL/music/horizons-scott-buckley.mp3 --out renders/<slug>-v1-bgm-horizons.mp4 \
  --credit '"Horizons" by Scott Buckley, licensed under CC BY 4.0, www.scottbuckley.com.au'
```

- **音量**：默认让音乐在有人声时比人声低 30 dB（人声 -16 LUFS 时，音乐约 -46 LUFS），整片同一个音量，开头和片尾不单独抬高。低 22 dB 时音乐就容易抢人声；用户想让音乐更明显时，再用 `--under` 调小差值（比如 24 或 20）。脚本会实测人声响度来校准音乐增益，并打印实际差值，交付时如实报告。
- **处理**：音乐先在 2.5 kHz 附近削 4 dB、150 Hz 附近加 1.5 dB，让开人声频段；有人声时再轻压一点（sidechain，ratio 2.5）；开头 1.2 秒淡入、结尾 2.5 秒淡出；曲子比视频短时用 4 秒交叉淡化接起来，脚本会打印接点时间，交付时请用户留意那里有没有接缝。
- **选曲**：讲解视频适合钢琴、弦乐、暖色播客风这类安静的配乐，像知名科普频道那样；厚重的电子乐、合成器贝斯容易和人声打架。`$SKILL/music/` 自带两首 CC BY 4.0 的曲子：Horizons（钢琴 + 弦乐）和 Let That Sink In（播客风），署名文案见 [music/README.md](music/README.md)。换新曲子时，先做一段「人声 + 音乐」的试听让用户挑，不要只发纯音乐。
- **授权**：只用可商用的授权（CC BY、CC0、Pixabay 这类）。CC BY 的曲子要署名：用 `--credit` 写进 `<out>-credits.txt`，交付时提醒用户把这行放进视频简介。
- 想让用户对比几首时，每首各出一版，文件名带上曲名。

## 迭代要点

- 用户说开场不够抓人时，重新写几个不同角度的 hook 给用户挑，不要只微调措辞。
- 用户说封面不吸引人时，同样重新给 2–3 个不同角度的封面标题和主图，不要只调字号。
- 用户说某一幕「像 PPT」时，先想这一幕能画成什么图，再动手，不要只是把框换个样式。
- 用户说发音怪、中英夹杂不连贯时，先在 `build/` 下出 A/B 样本（换写法、换音色、在 `context` 里补充说明）让用户听，样本也要带上 `BASE_CONTEXT`，再改脚本。
- 反馈涉及多处时，先复述方案，确认后再改。
- 改了 `script.json` 必须先跑 `narrate.mjs`；`render.mjs` 发现脚本和时间轴对不上会直接报错。

• SKILL.md 21 KB
• reference.md 17 KB
• setup.md 2 KB
• music/README.md 1 KB
• template/bgm.mjs 5 KB
• template/narrate.mjs 21 KB
• template/package.json 1 KB
• template/render.mjs 12 KB
• template/script.json 2 KB
• template/setup.mjs 2 KB
• template/tsconfig.json 1 KB
• template/src/brand.tsx 2 KB
• template/src/lib.tsx 17 KB
• template/src/outro.tsx 2 KB
• template/src/project.ts 1 KB
• template/src/scenes.tsx 11 KB
• template/src/sketch.tsx 6 KB
• template/src/theme.ts 1 KB
• tts/batch.mjs 2 KB
• tts/index.html 10 KB
• tts/server.mjs 3 KB

Pominięte w paczce: 2 (zbyt duże albo wykonywalne), są w repozytorium.