wizz-method 1.0.3 → 1.2.0

package/src/skills-lib/huashu-design/references/video-export.md

@@ -0,0 +1,232 @@
+# Video Export：HTML 动画导出为 MP4/GIF
+
+动画 HTML 完成后，用户常想「能导出视频吗」。这份指南给出完整流程。
+
+## 何时导出
+
+**导出时机**：
+- 动画完整跑通、视觉验证过（Playwright 截图确认各时间点状态正确）
+- 用户在浏览器里看过至少一次，表示效果 OK
+- **不要**在动画 bug 没修完的阶段导出——导出到视频后改起来更贵
+
+**用户可能说的触发语**：
+- 「能导出成视频吗」
+- 「转成 MP4」
+- 「做成 GIF」
+- 「60fps」
+
+## 产出规格
+
+默认一次给三种格式，让用户选：
+
+| 格式 | 规格 | 适合场景 | 典型大小（30s） |
+|---|---|---|---|
+| MP4 25fps | 1920×1080 · H.264 · CRF 18 | 公众号嵌入、视频号、YouTube | 1-2 MB |
+| MP4 60fps | 1920×1080 · minterpolate 插帧 · H.264 · CRF 18 | 高帧率展示、B站、作品集 | 1.5-3 MB |
+| GIF | 960×540 · 15fps · palette 优化 | Twitter/X、README、Slack 预览 | 2-4 MB |
+
+## 工具链
+
+两个脚本在 `scripts/`：
+
+### 1. `render-video.js` — HTML → MP4
+
+录一个 25fps 的 MP4 基础版本。依赖全局 playwright。
+
+```bash
+NODE_PATH=$(npm root -g) node /path/to/claude-design/scripts/render-video.js <html文件>
+```
+
+可选参数：
+- `--duration=30` 动画时长（秒）
+- `--width=1920 --height=1080` 分辨率
+- `--trim=2.2` 从视频开头裁掉的秒数（去掉 reload + 字体加载时间）
+- `--fontwait=1.5` 字体加载等待时间（秒），字体多时调高
+
+输出：与 HTML 同目录，同名 `.mp4`。
+
+### 2. `add-music.sh` — MP4 + BGM → MP4
+
+给无声 MP4 混入背景音乐，按场景（mood）从内置 BGM 库里选，也可自带音频。自动匹配时长、加淡入淡出。
+
+```bash
+bash add-music.sh <input.mp4> [--mood=<name>] [--music=<path>] [--out=<path>]
+```
+
+**内置 BGM 库**（在 `assets/bgm-<mood>.mp3`）：
+
+| `--mood=` | 风格 | 适配场景 |
+|-----------|------|---------|
+| `tech`（默认） | Apple Silicon / 苹果发布会，极简合成器+钢琴 | 产品发布、AI工具、Skill 宣传 |
+| `ad` | upbeat 现代电子，有 build + drop | 社交媒体广告、产品预告、促销片 |
+| `educational` | 温暖明亮、轻吉他/电钢琴，inviting | 科普、教程介绍、课程预告 |
+| `educational-alt` | 同类备选，换一首试试 | 同上 |
+| `tutorial` | lo-fi 环境音，几乎无存在感 | 软件演示、编程教程、长演示 |
+| `tutorial-alt` | 同类备选 | 同上 |
+
+**行为**：
+- 音乐按视频时长裁剪
+- 0.3s 淡入 + 1s 淡出（避免硬切）
+- 视频流 `-c:v copy` 不重编码，音频 AAC 192k
+- `--music=<path>` 优先级高于 `--mood`，可以直接指定任意外部音频
+- 传错 mood 名会列出所有可用选项，不会静默失败
+
+**典型流水线**（动画导出三件套 + 配乐）：
+```bash
+node render-video.js animation.html                        # 录屏
+bash convert-formats.sh animation.mp4                      # 派生 60fps + GIF
+bash add-music.sh animation-60fps.mp4                      # 加默认 tech BGM
+# 或针对不同场景：
+bash add-music.sh tutorial-demo.mp4 --mood=tutorial
+bash add-music.sh product-promo.mp4 --mood=ad --out=promo-final.mp4
+```
+
+### 3. `convert-formats.sh` — MP4 → 60fps MP4 + GIF
+
+从已有 MP4 生成 60fps 版本和 GIF。
+
+```bash
+bash /path/to/claude-design/scripts/convert-formats.sh <input.mp4> [gif_width] [--minterpolate]
+```
+
+输出（与输入同目录）：
+- `<name>-60fps.mp4` — 默认用 `fps=60` 帧复制（兼容性广）；加 `--minterpolate` 启用高质量插帧
+- `<name>.gif` — palette 优化的 GIF（默认 960 宽，可改）
+
+**60fps 模式选择**：
+
+| 模式 | 命令 | 兼容性 | 使用场景 |
+|---|---|---|---|
+| 帧复制（默认）| `convert-formats.sh in.mp4` | QuickTime/Safari/Chrome/VLC 全通 | 通用交付、上传平台、社交媒体 |
+| minterpolate 插帧 | `convert-formats.sh in.mp4 --minterpolate` | macOS QuickTime/Safari 可能拒打 | B站等需要真插帧的展示场景，**交付前必须本地测**目标播放器 |
+
+为什么默认改成帧复制？minterpolate 输出的 H.264 elementary stream 有 known compat bug——之前默认 minterpolate 时多次踩到「macOS QuickTime 打不开」的问题。详见 `animation-pitfalls.md` §14。
+
+`gif_width` 参数：
+- 960（默认）—— 社交平台通用
+- 1280 —— 更清晰但文件更大
+- 600 —— Twitter/X 优先加载
+
+### 4. `render-video-seek.js` — 真 60fps / 确定性渲染（推荐高质量交付）
+
+`render-video.js` 的 recordVideo 路径有三个固有限制：帧率被 Chromium compositor 锁死 25fps、开头有加载黑帧需 trim、60fps 只能靠事后 minterpolate 插帧（有 ghosting + macOS QuickTime 兼容 bug，见 `animation-pitfalls.md §14`）。需要**真 60fps、确定性输出、或交付 B站/作品集**时，改用 seek 渲染。
+
+它逐帧 seek 到时间戳截图、再用 ffmpeg 把 PNG 序列编码成 MP4。技术内核借鉴 HeyGen HyperFrames（Apache 2.0）的「冻结时钟 + seek 截图」思路，但不引入任何第三方包——只用本 skill 已有的 playwright + ffmpeg，runtime 中立。
+
+```bash
+NODE_PATH=$(npm root -g) node /path/to/claude-design/scripts/render-video-seek.js <html文件> --fps=60
+```
+
+参数：`--duration` · `--fps`（默认 60）· `--width` · `--height` · `--concurrency`（默认 4 个 worker 并行）· `--settle`（seek 后等几个 rAF 再截图，默认 2，重 layout 动画可调高）· `--keep-chrome`。输出与 HTML 同目录、同名 `.mp4`。
+
+正面解决 recordVideo 三死结：
+- **真原生任意帧率**：`--fps=60` 出真 60fps（每帧都是真实 seek 画面），不再经 `convert-formats.sh` 的 minterpolate 插帧，绕开 ghosting + macOS 兼容 bug
+- **无开头黑帧**：不录屏，根本没有加载期黑帧，不需要 `--trim` / `--fontwait`
+- **确定性**：seek 到时间戳截图，同输入同输出，不受机器负载/丢帧影响
+
+**适用边界（重要）**：只支持走 Stage 时钟的动画——`assets/animations.jsx` 的 `<Stage>` 或 `narration_stage.jsx` 的 `<NarrationStage>`，它们会响应 `window.__seekRender` 冻结自驱时钟并暴露 `window.__seek(t)`。纯 CSS `@keyframes` / Lottie / 手写非 Stage 动画不吃 `__seek`，这类继续用 `render-video.js`（脚本检测不到 `__seek` 会报错并提示）。
+
+**代价**：逐帧截图，长视频总耗时可能比 recordVideo 实时录更久（靠 `--concurrency` 多 worker 缓解）；大量临时 PNG 占盘，渲染前建议关其他大内存 App。
+
+**二选一策略**：默认仍用 `render-video.js`（零风险、覆盖所有动画类型）；需要真 60fps / 确定性 / 高质量交付、且动画走 Stage 时钟时，用 `render-video-seek.js`。带解说的长动画用 `render-narration.sh --seek` 一键走 seek 渲染 + 混音。
+
+## 完整流程（标准推荐）
+
+用户说「导出视频」后：
+
+```bash
+cd <项目目录>
+
+# 假设 $SKILL 指向本 skill 的根目录（自行按安装位置替换）
+
+# 1. 录 25fps 基础 MP4
+NODE_PATH=$(npm root -g) node "$SKILL/scripts/render-video.js" my-animation.html
+
+# 2. 派生 60fps MP4 和 GIF
+bash "$SKILL/scripts/convert-formats.sh" my-animation.mp4
+
+# 产出清单：
+# my-animation.mp4         (25fps · 1-2 MB)
+# my-animation-60fps.mp4   (60fps · 1.5-3 MB)
+# my-animation.gif         (15fps · 2-4 MB)
+```
+
+## 技术细节（排错用）
+
+### Playwright recordVideo 的坑
+
+- 帧率固定 25fps，无法直接录 60fps（Chromium headless 的 compositor 上限）
+- 从 context 创建就开始录，必须用 `trim` 裁掉前面的加载时间
+- 默认 webm 格式，需要 ffmpeg 转 H.264 MP4 才能通用播放
+
+`render-video.js` 已处理以上问题。
+
+### ffmpeg minterpolate 参数
+
+当前配置：`minterpolate=fps=60:mi_mode=mci:mc_mode=aobmc:me_mode=bidir:vsbmc=1`
+
+- `mi_mode=mci` — motion compensation interpolation（运动补偿）
+- `mc_mode=aobmc` — adaptive overlapped block motion compensation
+- `me_mode=bidir` — 双向运动估计
+- `vsbmc=1` — 可变 size block motion compensation
+
+对 CSS **transform 动画**（translate/scale/rotate）效果好。
+对**纯 fade** 可能产生轻微 ghosting——如果用户嫌弃，退化为简单帧复制：
+
+```bash
+ffmpeg -i input.mp4 -r 60 -c:v libx264 ... output.mp4
+```
+
+### GIF palette 为何要两阶段
+
+GIF 只能 256 色。一次 pass 的 GIF 会把全动画色彩压到 256 色通用 palette，对米色底+橙色这种细腻配色会糊。
+
+两阶段：
+1. `palettegen=stats_mode=diff` —— 先扫描全片，生成**针对此动画的 optimal palette**
+2. `paletteuse=dither=bayer:bayer_scale=5:diff_mode=rectangle` —— 用这个 palette 编码，rectangle diff 只更新变化区域，大幅减小文件
+
+对 fade 过渡用 `dither=bayer` 比 `none` 更平滑，但文件大一点。
+
+## Pre-flight check（导出前）
+
+导出前 30 秒自检：
+
+- [ ] HTML 在浏览器里完整跑过一遍，无控制台错误
+- [ ] 动画第 0 帧是完整初始状态（不是空白加载中）
+- [ ] 动画最后一帧是稳定的收尾状态（不是半截）
+- [ ] 字体/图片/emoji 全部正常渲染（参考 `animation-pitfalls.md`）
+- [ ] Duration 参数与 HTML 里的实际动画时长匹配
+- [ ] HTML 中 Stage 检测 `window.__recording` 强制 loop=false（手写 Stage 必查；用 `assets/animations.jsx` 自带）
+- [ ] 结尾 Sprite 的 `fadeOut={0}`（视频末帧不淡出）
+- [ ] 含「Created by Huashu-Design」水印（仅动画场景必加；第三方品牌作品加「非官方出品 · 」前缀。详见 SKILL.md §「Skill 推广水印」）
+
+## 交付时附带的说明
+
+导出完成后给用户的标准说明格式：
+
+```
+**完整交付**
+
+| 文件 | 格式 | 规格 | 大小 |
+|---|---|---|---|
+| foo.mp4 | MP4 | 1920×1080 · 25fps · H.264 | X MB |
+| foo-60fps.mp4 | MP4 | 1920×1080 · 60fps（运动插帧）· H.264 | X MB |
+| foo.gif | GIF | 960×540 · 15fps · palette 优化 | X MB |
+
+**说明**
+- 60fps 用 minterpolate 做运动估计插帧，transform 动画效果好
+- GIF 用 palette 优化，30s 动画可压到 3MB 左右
+
+要换尺寸或帧率说一声。
+```
+
+## 常见用户追加需求
+
+| 用户说 | 应对 |
+|---|---|
+| 「太大了」 | MP4：提高 CRF 到 23-28；GIF：降分辨率到 600 或 fps 到 10 |
+| 「GIF 太糊」 | 提高 `gif_width` 到 1280；或者建议用 MP4 代替（微信朋友圈也支持） |
+| 「要竖屏 9:16」 | 改 HTML 源的 `--width=1080 --height=1920`，重新录 |
+| 「加水印」 | ffmpeg 加 `-vf "drawtext=..."` 或 `overlay=` 一个 PNG |
+| 「要透明背景」 | MP4 不支持 alpha；用 WebM VP9 + alpha 或 APNG |
+| 「要无损」 | CRF 改 0 + preset veryslow（文件会大 10 倍） |

package/src/skills-lib/huashu-design/references/voiceover-pipeline.md

@@ -0,0 +1,397 @@
+# Voiceover Pipeline · 解说驱动动画
+
+> 把动画从「无声画面 + 后期配音」升级为「**先有解说词，再按音频实测时长驱动画面**」的工作流。
+> 适用：5-20 分钟概念解说视频、教程视频、长篇知识科普。
+>
+> 配套 `references/animation-best-practices.md` 使用——本文件管 **怎么把解说和画面对上**，
+> animation-best-practices 管 **每一帧画面怎么动**。
+
+---
+
+## 🛑 铁律 · 在写一行代码之前必读
+
+> **强调多少遍都不够：解说动画的失败模式 #1 是做成了带配音的 PowerPoint。**
+
+### 第一条 · 整片是一个连续的运动叙事，不是一组独立场景
+
+PowerPoint 是 7 张幻灯片。我们做的是 **1 段持续 X 分钟的电影**。
+
+**身份切换**：
+- ❌ 你不是「在做 7 个 scene 的内容」
+- ✅ 你是「在屏幕上让一个或几个 hero element 演 X 分钟的戏」
+
+**视觉骨架 = 一个或几个贯穿全片的 hero element**：
+- 它从 t=0 出现，到结束才离场
+- 每个 cue 是它的**状态变化**（位置 / 大小 / 颜色 / 透视 / 形态），不是「换一个新元素」
+- scene 边界在剧本里有，**在画面里不应该有**——观众看不出"这是第 3 个 scene"，只看到一段连续的运动
+
+**反例（本 skill v1 实战踩坑 · 2026-05-10）**：
+- 7 个 `<Scene>` 各自独立 layout，scene 切换 = 整页 opacity 1→0 切到下一页
+- 每个 cue = `opacity: p, transform: translateY((1-p)*30px)`（fade-up 单调使用）
+- 结果：观众看完第一反应「像一页页 keynote」，整片质感归零
+
+**正确模式**：
+- 选定 1-2 个 hero element（如本文章 demo 应选「md」「html」两个字符作为骨架）
+- 这两个字符**从片头到片尾**一直在屏幕上
+- 每段「scene」实际是 hero element 的一次状态变化
+  - opening：两字符在屏幕中央对峙
+  - md-side：md 变大变粗占据画面，html 退到角落小字；数据围绕 md 涌入
+  - html-side：html 反转为主角；md 退到角落
+  - the-real-question：两字符回到中央，但中间出现「≠」分隔
+  - the-split：两字符向两侧推开，中间空白展开
+  - activity-proof：两字符在 timeline 上交替闪烁
+  - closing：两字符落地为最终答案位置
+- 这样整片是「md 和 html 在屏幕上演了 X 分钟」，不是 7 张独立 PPT
+
+**最小实现骨架**（直接抄改）：
+
+```jsx
+// ── Step 1: 定义 hero 在每个 scene 的目标状态（位置/大小/不透明度）──
+const HERO_KEYS = {
+  opening:    { md: { x: 50, y: 35, scale: 1.0, opacity: 1 }, html: { x: 50, y: 65, scale: 1.0, opacity: 1 } },
+  'md-side':  { md: { x: 78, y: 50, scale: 1.6, opacity: 1 }, html: { x: 92, y: 8,  scale: 0.25, opacity: 0.4 } },
+  'html-side':{ md: { x: 8,  y: 8,  scale: 0.25, opacity: 0.4 }, html: { x: 22, y: 50, scale: 1.6, opacity: 1 } },
+  // ... 每段一个 entry，连贯的运动从前一段的 final → 本段的 from
+};
+
+// ── Step 2: easing + lerp 工具 ──
+const expoOut = t => t === 1 ? 1 : 1 - Math.pow(2, -10 * t);
+const lerp = (a, b, t) => a + (b - a) * t;
+const lerpPos = (from, to, t) => ({
+  x: lerp(from.x, to.x, t), y: lerp(from.y, to.y, t),
+  scale: lerp(from.scale, to.scale, t),
+  opacity: lerp(from.opacity ?? 1, to.opacity ?? 1, t),
+});
+
+// ── Step 3: HeroAnchor 组件 —— 直接挂在 <NarrationStage> 子级，不放进 <Scene> ──
+const HeroAnchor = () => {
+  const { time, scene, timeline } = useNarration();
+  if (!scene) return null;
+  const idx = timeline.scenes.findIndex(s => s.id === scene.id);
+  const prevId = idx > 0 ? timeline.scenes[idx - 1].id : scene.id;
+  const from = HERO_KEYS[prevId];
+  const to   = HERO_KEYS[scene.id];
+
+  // 段内前 ~45% 时间用于从 prev 状态 morph 到本段状态，剩余 hold
+  const transitionDur = Math.min(2.0, scene.duration * 0.45);
+  const t = expoOut(Math.min(1, (time - scene.start) / transitionDur));
+  const md   = lerpPos(from.md,   to.md,   t);
+  const html = lerpPos(from.html, to.html, t);
+
+  // 加 subtle breathing 让任意一帧都有运动（对应铁律第三条）
+  const breath = 1 + Math.sin(time * 0.6) * 0.012;
+
+  const renderHero = (label, pos, color) => (
+    <div style={{
+      position: 'absolute', left: `${pos.x}%`, top: `${pos.y}%`,
+      transform: `translate(-50%, -50%) scale(${pos.scale * breath})`,
+      opacity: pos.opacity, color, fontSize: 360, fontWeight: 800,
+      lineHeight: 1, willChange: 'transform, opacity', pointerEvents: 'none',
+    }}>{label}</div>
+  );
+  return <>
+    {renderHero('md',   md,   '#1B4965')}
+    {renderHero('html', html, '#C04A1A')}
+  </>;
+};
+
+// ── Step 4: 主组件 —— hero 在 NarrationStage 子级，scene 内辅助元素另外管 ──
+const App = () => (
+  <NarrationStage timeline={TIMELINE} audioSrc="_narration/voiceover.mp3" width={1920} height={1080}>
+    <HeroAnchor />  {/* ← 跨 scene 持续存在，整片视觉骨架 */}
+    {/* scene 内辅助元素用 useSceneFade 控制软淡入淡出，不要硬切 */}
+    <MdSideAux />
+    <HtmlSideAux />
+    {/* ... */}
+  </NarrationStage>
+);
+```
+
+**完整可运行参考**：`demos/md-html-narration/md-html-demo.html`（3 分 21 秒，7 段，21 cue，已实战验证）
+
+### 第二条 · 场景之间不能「硬切」
+
+| 错误模式（PowerPoint slop） | 正确模式（电影感） |
+|---|---|
+| scene A 整体 `opacity 1→0` 同时 scene B `opacity 0→1` | scene A 的核心元素 **morph 进** B（位置/大小/颜色平滑变换） |
+| 每个 scene 独立 layout，元素出现/消失 | 元素在屏幕上**持续存在**，只是位置和形态在变 |
+| `keepMounted=false`，scene 切换瞬间组件被卸载 | hero 用 `keepMounted=true`，跨 scene 共享 DOM 节点 |
+| 字幕条/数据卡片各自 fade in fade out | 字幕条作为画面唯一的"非 hero" 入场，hold 后**配合 hero 的运动一起退出** |
+
+实现层面：
+- **共享元素跨 scene** → 把 hero 提到 `<NarrationStage>` 直接子级，**不放在任何 `<Scene>` 里**
+- 用 `useNarration()` hook 在 hero 里读 `time`、`scene`、`isCueTriggered`，自己根据当前时间决定形态
+- `<Scene>` 只用来管那些只在该段出现的辅助元素（数据卡、引用块等），并且**这些辅助元素也不要硬切**——出场用 expoOut + stagger，退场用 fade overlap 跟下一段叠
+
+### 第三条 · 每一帧画面都必须有运动
+
+**自检方法**：在录制中**任意截一帧**（不是 cue 触发那一秒）。
+- 如果画面看起来「**完全静止**」→ 错。回去加底层运动（background drift / hero subtle scale / camera pan / parallax）
+- 永远有一个**底层运动**在跑（即使不是焦点）：
+  - hero element 的 `scale: 1 ↔ 1.02` 5 秒呼吸循环
+  - 背景 `translateX: 0 ↔ -20px` 缓慢漂移
+  - 数据卡片入场后保留 `translateY` 微抖（Perlin noise）
+- 一个完全静止的画面 = PowerPoint slop
+
+### 第四条 · Easing / Stagger / Hold 是底线
+
+| 项 | 必须 | 禁止 |
+|---|---|---|
+| Easing | `expoOut` 主轴（`cubic-bezier(0.16, 1, 0.3, 1)`），`overshoot` 强调，`spring` 落位 | `linear`、`ease`、CSS 默认 |
+| 多元素入场 | 30ms stagger（每个晚 30ms 进） | 一刀切全部出现 |
+| 关键 cue 前 | hold 0.3-0.5s 让观众"看见"（前一段元素先静止 0.3s，再触发 cue） | 一段说完无缝切下一段 |
+| 收尾 | 戛然而止，最后一帧 hold 1s | fade to black |
+
+详细规则参考 `animation-best-practices.md` 的 §1-§4。
+
+### 自检 · 第一观众反应
+
+做完拿给一个没看过的人看（或自己 24 小时后再看），**他们的第一反应**是什么？
+
+| 反应 | 评级 | 行动 |
+|---|---|---|
+| 「这是带配音的 PPT」 | 失败 | 回去重做 |
+| 「画面跟着声音在切换」 | 不及格 | 缺连续叙事，hero element 不存在或没贯穿 |
+| 「这个东西在动」 | 合格 | 但没记忆点 |
+| 「我想看完」 | 良 | 节奏对了 |
+| 「这一段我想截图」 | great | 你做到了 |
+
+---
+
+## 工作流（高层）
+
+```
+                ┌──────────────────────────┐
+                │  解说稿 .md（## scene + │
+                │  [[cue:xx]] 标关键句）   │
+                └──────────────┬───────────┘
+                               │
+                  narrate-pipeline.mjs
+                               │
+                               ▼
+            ┌──────────────────────────────┐
+            │ voiceover.mp3 (拼接的整段)  │
+            │ timeline.json (实测时长)    │
+            └──────────────┬───────────────┘
+                           │
+              ┌────────────┴────────────┐
+              ▼                         ▼
+    ┌─────────────────┐      ┌──────────────────┐
+    │ HTML 动画       │      │ 录制 MP4 + 混音  │
+    │ (NarrationStage)│      │ render-narration │
+    │ 实播带 audio 同步│      │ → 最终发布 MP4   │
+    └─────────────────┘      └──────────────────┘
+       交付形态 1                交付形态 2
+```
+
+## 解说稿格式
+
+放在项目目录下任意位置，文件名建议 `script.md`：
+
+```markdown
+---
+title: 什么是 LLM
+voice: S_JSdgdWk22   # 可选，覆盖 .env 默认音色
+speed: 1.0           # 可选，0.5-2.0
+gap: 0.4             # 段间静音秒数，默认 0.3
+---
+
+## intro
+大家好，今天我们 5 分钟讲清楚 LLM 是什么。
+
+## what-is
+LLM 全称 Large Language Model，[[cue:bigmodel]]它是一个有几千亿参数的神经网络。
+本质是一个文字接龙的预测器。
+
+## demo
+比如你输入「今天天气」，[[cue:input]]模型会预测下一个字最可能是什么。
+[[cue:predict]]也许是「真好」，也许是「不错」。
+```
+
+**规则**：
+- 段标题 `## scene-id` 是英文/数字 + 连字符（如 `## what-is`、`## scene-1`）
+- `[[cue:xx]]` 标在**关键句中间**——脚本运行时会在该位置切割文本，cue 之后那一刻就是画面的触发点
+- cue id 在动画 HTML 里用 `<Cue id="xx">` 监听
+- 写解说时**关注节奏 + 短句**，长句 TTS 出来会平淡
+
+## timeline.json schema
+
+```ts
+{
+  title: string,
+  voice: string | null,
+  speed: number,
+  gap: number,
+  totalDuration: number,        // 整段 voiceover.mp3 的实测秒数
+  voiceover: 'voiceover.mp3',   // 相对 timeline.json 的路径
+  scenes: [
+    {
+      id: string,
+      start: number,            // 该段在整段音频里的开始时间
+      end: number,
+      duration: number,
+      audio: 'audio/<id>.mp3',  // 该段单独音频（合并前的子段已 concat）
+      text: string,             // 已剥离 [[cue:xx]] 标记的整段文本
+      // chunks 是字幕显示的源——每个 chunk 是被 cue 切开的子段，含 TTS 实测时间窗
+      chunks: [
+        {
+          text: string,            // 子段文本
+          start: number,           // 段内相对时间
+          end: number,
+          absoluteStart: number,   // 整轨绝对时间（对齐 voiceover.mp3）
+          absoluteEnd: number,
+        }
+      ],
+      cues: [
+        {
+          id: string,
+          offset: number,       // 段内相对时间
+          absoluteTime: number, // 整段时间轴上的绝对时间
+        }
+      ]
+    }
+  ]
+}
+```
+
+`absoluteTime` 和 `absoluteStart/End` 都是**真实测出来的**——pipeline 把段内文本按 cue 切成子段分别 TTS，时间 = 累加前面子段的实测时长。**不是按字符数线性估算的近似值**。
+
+## 字幕（Subtitles）
+
+> **字幕是默认带的**——长解说视频没字幕，留存率会显著下降。NarrationStage 提供 `<Subtitles />` 开箱即用。
+
+### 用法（一行）
+
+```jsx
+const { NarrationStage, Subtitles } = NarrationStageLib;
+<NarrationStage timeline={TIMELINE} audioSrc="...">
+  {/* 你的 hero / scene 内容 */}
+  <Subtitles />  {/* ← 自动从 timeline.scenes[].chunks 取活动文本 */}
+</NarrationStage>
+```
+
+### 视觉规则（B 站风 · 反 PowerPoint）
+
+| 项 | 规则 | 反例 |
+|---|---|---|
+| 背景 | **无背景**（不要黑色横条不要 backdrop-blur）| 半透明黑底 + blur = 字幕条压住画面 = PPT 感 |
+| 字色 | **浅底用深墨 `#1a1a1a` + 白光晕**；深底用白字 + 黑光晕 | 浅底白字+黑描边 = 字糊 |
+| 字号 | 32px（1080p 视频）| <24px 看不清，>40px 抢主视觉 |
+| 字体 | `PingFang SC` / `Noto Sans SC`（无衬线，B 站标准）| 衬线字体 = 像电影字幕 |
+| 位置 | bottom: 90px（不贴边）| 贴底边显得廉价 |
+| 单行长度 | **≤ 12-13 字**（中英混合时英文按 0.5 字算）| >15 字一行手机端读不完 |
+| 切句规则 | **绝不跨句号截断**：先按 `。！？` 切句，每句再按 `，、；：` 合并到 ≤maxLen | 按字数硬切，把「这是好的」切成「这是好」+「的」 |
+
+`<Subtitles />` 默认按以上规则跑，不需要传 props。深底场景：`<Subtitles color="#fff" haloColor="rgba(0,0,0,0.85)" />`。
+
+### 切句算法（已在 narration_stage.jsx 内置）
+
+```js
+splitChunkToLines(text, maxLen = 13)
+// 1. 强标点切句（。！？\n）
+// 2. 每句 ≤ maxLen 直接保留
+// 3. 否则按弱标点（，、；：）切片，合并到 ≤ maxLen
+// 4. 兜底硬切（罕见）
+// 中英混合：英文/数字按 0.5 字算视觉宽度
+```
+
+如果 chunk 切完后某行明显太长或太短，**改解说稿里 cue 位置**（cue 把段切得更细），不要在前端调切句逻辑。
+
+## NarrationStage API
+
+```jsx
+import 'assets/narration_stage.jsx';
+const { NarrationStage, Scene, Cue, useNarration } = NarrationStageLib;
+
+<NarrationStage
+  timeline={TIMELINE}                  // timeline.json 内容
+  audioSrc="_narration/voiceover.mp3"  // 相对当前 HTML 的路径
+  width={1920} height={1080}
+  background="#f5f1e8"
+  controls={true}                      // 实播时显示底部播放条
+>
+  {/* hero element：跨 scene 持续存在 —— 直接放在 NarrationStage 子级 */}
+  <HeroAnchor />
+
+  {/* scene 内辅助元素：只在该段出现 */}
+  <Scene id="intro">
+    <Cue id="bigmodel">{(triggered, progress) => (
+      <SomeElement style={{ opacity: progress }} />
+    )}</Cue>
+  </Scene>
+</NarrationStage>
+```
+
+**Hooks**：
+- `useNarration()` 返回 `{ time, scene, sceneTime, isCueTriggered, cueProgress }`
+- 在自定义组件里直接读，不需要传 props
+
+**Scene 组件**：
+- 默认只在 `scene.id === id` 时挂载
+- 加 `keepMounted` 持续挂载（跨 scene 动画连续时用）
+
+**Cue 组件**：
+- children 必须是 `(triggered, progress) => ReactNode`
+- progress 是 cue 触发后 0→1 的渐进值（默认 0.6s ramp）
+
+## 时间源（双轨）
+
+NarrationStage 自动检测 `window.__recording`：
+- **实播模式**（默认）：跟随 audio 元素的 currentTime，用户暂停/拖动 seek 都能同步
+- **录视频模式**（render-video.js 设置 `window.__recording = true`）：rAF wall-clock 自驱动从 0 开始，暴露 `window.__seek(t)` 给 render-video.js 复位
+
+## 三个脚本
+
+| 脚本 | 输入 | 输出 |
+|---|---|---|
+| `scripts/tts-doubao.mjs` | 单段文本 | 单个 mp3 + 实测时长 |
+| `scripts/narrate-pipeline.mjs` | 解说稿 .md | voiceover.mp3 + timeline.json |
+| `scripts/mix-voiceover.sh` | 视频 + voiceover.mp3 [+ BGM] | 带音频的 MP4 |
+| `scripts/render-narration.sh` | 解说 HTML + timeline.json | 最终 MP4（录制 + 混音一条龙）|
+
+## .env 配置
+
+skill 根目录下 `.env`（已 gitignore）：
+
+```
+DOUBAO_TTS_API_KEY=<your_key>
+DOUBAO_TTS_VOICE_ID=<your_clone_voice_id>
+DOUBAO_TTS_CLUSTER=volcano_icl
+DOUBAO_TTS_ENDPOINT=https://openspeech.bytedance.com/api/v1/tts
+```
+
+参考 `.env.example` 模板。豆包语音克隆音色 ID 在火山引擎控制台获取。
+
+## 标准工作流（10 步）
+
+1. **写解说稿**：解说稿是源代码。先把整段口播写完整，标段标题 `## scene-id`，关键句前加 `[[cue:xx]]`
+2. **跑 narrate-pipeline**：`node scripts/narrate-pipeline.mjs --script script.md --out-dir _narration`
+3. **听整段 voiceover.mp3**：节奏不对回去改稿。**这一步决定整片质量上限**
+4. **🛑 设计前先回答铁律**：hero element 是什么？它在每段是什么状态？跨场景怎么 morph？答不上不要写代码
+5. **写动画 HTML**：用 NarrationStage + 一个或几个 hero element 跨 scene 演戏
+6. **实播预览**：浏览器打开 HTML，点 ▶ Play，听画面+解说同步
+7. **第一观众自检**：用上面「自检 · 第一观众反应」表打分。失败回到 Step 4 重做
+8. **录视频**：`bash scripts/render-narration.sh demo.html --timeline=_narration/timeline.json`（自动录无声 MP4 + 混入 voiceover）
+9. **可选 BGM**：在 render-narration 加 `--bgm-mood=educational`（或 tech / tutorial 等）
+10. **交付**：浏览器 HTML（实时演示用）+ 最终 MP4（发布用）
+
+## 异常处理
+
+| 问题 | 解决 |
+|---|---|
+| TTS API 报错 | 检查 .env 里 `DOUBAO_TTS_API_KEY` 是否正确 |
+| 某段音频明显比脚本长/短 | 该段文本里有奇怪标点或 emoji，TTS 解析异常 → 改稿 |
+| cue absoluteTime 不准 | 段内子段拼接时 ffmpeg 有问题 → 检查 mp3 编码一致性 |
+| 录视频结果有黑屏 | render-video.js 没拿到 `window.__ready` 信号 → 检查 NarrationStage 是否正常挂载 |
+| 录视频画面卡顿 | 动画里有重 layout（大量 box-shadow / blur）→ 简化或预合成 |
+| 实播音画不同步 | audio 元素加载延迟 → 加 `preload="auto"` 或本地预加载 |
+
+## 何时不用这套 pipeline
+
+- **<60s 短动画**：直接做无声动画 + 后期配音（add-music.sh + 一段单独 TTS）即可，不需要 timeline 驱动
+- **纯 BGM 视频**：用 `add-music.sh` 加预设 BGM
+- **真人录音替换 TTS**：把 `voiceover.mp3` 替换成真人录音，timeline 自己手写或用 ffprobe 测段时长 + 工具脚本生成 → 流程其余部分通用
+
+---
+
+**最后一次提醒**：写代码前回到铁律。**别做带配音的 PowerPoint**。