gold-noir-video-creator

---
name: gold-noir-video-creator
description: 制作暗金、黑金电影感的科普与知识讲解视频（dark-gold explainer videos）。使用 Remotion + Three.js 输出带 3D 物体或 2D 线描小剧场（具象人物、章节印、年份里程表）、金色衬线标题、刻度表盘、数据面板、逐字字幕、程序合成配乐和可选 AI 旁白配音（edge-tts，音画逐句对齐）的 MP4。用户要求制作这种风格的视频、复用 gold-noir-video-creator 模板，或提供相同风格的视频参考时使用。附 1920×1080 太阳系示例；不适用于未指定此风格的普通视频需求、明亮卡通或真人实拍。
---

# 暗金风格视频制作（gold-noir-video-creator）

用同级 `template/` 中的 Remotion + Three.js 项目制作视频。默认示例为 60 秒太阳系科普，1920×1080、30fps，Composition id 为 `Main`。默认输出字幕和程序合成配乐，不含旁白；需要配音时按下文“配音”一节开启，旁白与字幕、画面逐句对齐。

模板支持本地渲染，无需购买素材或调用付费生成 API；Remotion 的适用许可条件见 [官方说明](https://www.remotion.dev/docs/license/pricing)。环境与字体安装见 [README.md](README.md)。

## 何时使用

- 用户明确要暗金、黑金、深色电影感的科普或知识讲解视频。
- 用户要求使用 gold-noir-video-creator，或复用这个视频模板。
- 用户提供这种风格的参考视频；先查看参考，确认视觉风格与需求一致。

只说“做个科普视频”但未指定风格时，不默认套用此模板。尊重用户指定的内容、片长和交付方式。

## 起步

先找到**本次实际加载的 SKILL.md 所在目录**，由此定位同级 `template/`，不要假设安装在某个固定的用户目录。需要 Node.js 22.x（至少 22.18.0）或 24+，建议 24 LTS。

下面的两个变量须替换为实际路径；将模板复制到一个新的项目目录，并保留隐藏文件和锁文件：

```bash
SKILL_DIR="/absolute/path/to/gold-noir-video-creator"
PROJECT_DIR="/absolute/path/to/new-video-project"
mkdir "$PROJECT_DIR"
cp -R "$SKILL_DIR/template/." "$PROJECT_DIR/"
cd "$PROJECT_DIR"
npm ci
npm run check
npm run still -- --frame=470
npm run render
```

Windows 可使用文件管理器复制完整模板，然后在 PowerShell 进入项目目录运行 npm 命令。不要覆盖已有项目文件。

- `npm run voice` 按 `narration.json` 生成旁白和配音时间轴；`npm run voice:samples` 生成多种声音的试听对比；`npm run voice:off` 关闭配音。详见“配音”。
- `npm run master` 对 `out/video.mp4` 做响度标准化（默认 -16 LUFS），可加 `-- --speed=1.25` 整体提速。详见“交付检查”。
- `npm run dev` 启动 Studio，自动生成配乐。Studio 里另有 `Linework` 演示（6 秒），展示线描人物、章节卡、年份里程表等组件。
- `npm run still` 和 `npm run render` 都会重新生成配乐、打包，再输出 `out/still.png` 或 `out/video.mp4`。
- 批量抽帧：先 `npm run bundle`，再 `npm run stills -- 0 300 470`，一次打开浏览器连续输出 `out/stills/Main-<帧号>.png`（默认半分辨率，`SCALE=1` 出全分辨率，`COMP=Linework` 换 Composition）。改完一处要看十几帧时，比反复 `npm run still` 快得多。修改内容后重新打包。
- 首次渲染会下载浏览器。遇到字体、WebGL 或浏览器启动问题时，先检查实际运行环境。

## 文件分工

| 文件（相对项目目录） | 负责什么 |
|---|---|
| `src/cinematic/data.ts` | 内容数组、时长常量 `FPS / HOOK / TITLE / SEG / CLOSE`、字体及配色 |
| `src/cinematic/timeline.ts` | 共用时间线、帧数校验、按内容数量生成收尾布局 |
| `src/cinematic/SolarCinematic.tsx` | 场景编排、开场问题、片名与收尾文案 |
| `src/cinematic/Overlay.tsx` | 字幕、标题卡、表盘、通用信息面板 |
| `src/cinematic/Space3D.tsx` | 相机、灯光、物体、轨道和 3D 到 2D 的投影 |
| `src/cinematic/textures.ts` | 带种子噪声的程序化纹理 |
| `scripts/bgm.mjs` | 读取共用时间线，合成 PCM 配乐、钟声与转场声 |
| `narration.json` | 旁白稿：每个场景的字幕文本、朗读文本、声音、语速和停顿 |
| `scripts/tts.py` | 逐句生成旁白：原始语音存 `public/vo/raw/`，后期处理并裁静音后存 `public/vo/`，实测时长，写出 `voice.ts`；`--samples` 生成试听对比 |
| `scripts/master.mjs` | 交付母带：响度标准化，可选整体变速（画面补帧、声音保调） |
| `src/cinematic/voice.ts` | 生成的配音时间轴；为 `null` 时不配音，使用固定时长 |
| `src/linework/kit.tsx` | 线描叙事基础件：深蓝夜空 `Sky`、红色章节印 `Seal`、章节卡 `ChapterCard`、左上章节标识 `ChapterHUD`、年份里程表 `Odometer` / `YearTag`、标签 `Tag`、逐笔画线 `drawn()`；版式件 `PaperGrid`（网格底板）、`ChartFrame`（图表框）、`BoxLabel`（方框注释）、`Annot`（引线标注）、`Counter`（角落计数器）、`TitleCard`（片名卡，支持 `instant` 做封面） |
| `src/linework/People.tsx` | 具象线描人物：`SeatedPerson`（坐姿，手铐搭在桌上）、`StandingPerson`（`outfit`: 警察 / 嫌疑人 / 西装礼帽，`reach` 伸手，`step` 走路）、侧脸 `Head` |
| `src/linework/Demo.tsx` | `Linework` 演示 Composition，正片不依赖它 |
| `scripts/stills.mjs` | 按句子批量抽帧（`npm run stills`） |
| `scripts/demo-stills.mjs` | 抽线描演示的指定帧，用来检查组件改动 |

## 叙事与动画感（动手前先过一遍）

模板的表盘、面板、矩阵是**信息的容器**，不是故事。只把信息摆上画面，成片会像一块仪表盘：观众读得懂字幕，却没有"在看一段动画"的感觉。动手写代码前，先按下面几条把稿子过一遍。

1. **每句字幕都要有一个画面动作。** 给稿子每一句写下"这句话时画面里什么在动"：门打开、刻痕一笔笔刻上墙、砝码落进秤盘、一根线被扯断。答不出来的句子，要么补一个动作，要么并进上一句。字幕说的和画面演的必须是同一件事，而且在同一帧发生。
2. **用故事世界里的东西，不用比喻物。** 讲审讯就画审讯室、警察、桌上的条件；讲冷战就画核弹头库存。棋子、发光几何体、抽象图表只在没有更具体的东西时才用。
3. **抽象量要换成看得见的东西。** 常用对应：

   | 抽象概念 | 具象画法 |
   |---|---|
   | 时长、刑期、次数 | 墙上刻"正"字，一笔一声 |
   | 比较两个选项 | 天平：数量变成砝码，轻的一边升起来就是更好的选择 |
   | 承诺、约定、关系 | 两人之间一根金线；违约就是线断 |
   | 释放、出局、得到 | 门打开、光照进来、人走出去 |
   | 规模（几万、几亿） | 小图标一个个堆起来 + 环形计数器滚动 |
   | 年代推进 | 年份里程表逐位滚动 |
   | 同一个结构反复出现 | 同一张表换标签再用一次（翻转动画） |

4. **人物要具象，不要火柴人。** 线条小人（一个圆加几根线）会显得廉价。用 `src/linework/People.tsx`：侧脸带鼻、耳、头发，外套有领口和门襟，警察有帽徽、领带、腰带和裤线，手、鞋、手铐都画出来。做法是"填深蓝 + 金色描边"的闭合形状画躯干和衣服，四肢用"先粗金线、再细深蓝线"叠出带轮廓的肢体。人物统一朝右画，朝左用 `scale(-1 1)` 镜像；**文字和"正"字不要放进镜像组**，单独按镜像后的坐标画，否则会反过来。
5. **给故事装一台引擎：**
   - **冷开场先给代价**：一个具体的数字、年份或后果（"1986 年，全世界约 7 万枚核弹头"），再抛出问题，最后才是标题卡。
   - **分章**：每章开头一张约 1.5 秒的章节卡（红色印章 壹 / 贰 / 叁 + 章名 + 一句引子），之后缩到左上角常驻。
   - **章尾留一个问题**把观众推进下一章（"那事先约好呢？"）。
   - **结尾回扣开场**：开场那个数字或画面在结尾再出现一次，用片中讲的道理解释它。
6. **一个主场景贯穿全片。** 例如两间审讯室的剖面图：规则、推理、结局都在里面演，镜头推近、拉远、压暗其中一间。表格和面板只在需要"总结"的那一两句出现，用完就收。
7. **2D 线描往往比 3D 更合适。** 讲人物和事件的故事，SVG 线描（逐笔画出、灯光锥、门后的光）比 3D 物体更可控，渲染也快。3D 留给需要体积感的单个物体。
8. **配色两套可选**：默认暖黑底 + 金（下节）；线描叙事可换深蓝夜空（`#18234d → #0c1434 → #05081a`，带闪烁星点）+ 暖金线条 + 暖色灯光锥。两套都只把红色留给印章和"盖章"式的结论。

## 信息密度与版式（第二遍过稿）

同上一条并列：画面动作解决了"像不像动画"，这一条解决"够不够耐看"。只有一层信息的画面——一个图形 + 一行字幕——即使动作对，也会显得单薄。做完上一节，再按这几条检查一遍。

1. **每一帧都要有四到七层信息同时在场。** 一层的画面看起来像 PPT。分层建议：

   | 层 | 内容 | 例 |
   |---|---|---|
   | ① 底 | 星空 / 背景渐变 | `Sky` |
   | ② 承托 | 淡网格纸，让线描图形像画在图纸上 | `PaperGrid` |
   | ③ 主图形 | 线描主体 + 逐笔画出 | 飞机、牢房、战壕 |
   | ④ 辅助网格 | 坐标轴、标尺、虚线基准线 | `ChartFrame` |
   | ⑤ 引线标注 | 圆点 + 折线 + 方框文字 | `Annot` |
   | ⑥ 角落标记 | 计数器、年份里程表、章节印、方框注释 | `Counter` / `YearTag` / `BoxLabel` |
   | ⑦ 字幕 | 中文主行 + 英文斜体小注 | `Subtitle`（传 `en`） |

2. **给主图形一条承托面。** 悬在空背景里的线描图形会显得没着落。一条地平线、一张网格纸、一个图表框都行。`PaperGrid` 是全局底，`ChartFrame` 是单个图表的外框（带角标和横向网格）。

3. **标签一律走引线，不压在图形上。** 这是最常犯的排版事故：柱状图的名称、数值直接叠在柱体上，或几个短标签横向挤在一起。规则：
   - 用 `Annot`（圆点 + 折线 + 方框）或把标签统一提到图表上沿，再用虚线引到对应柱体；
   - 同类标签之间至少留一个字宽的空隙，宁可错行、竖排，也不要让它们挨着；
   - 长英文名配短中文名时，中文在上、英文在下，字号分别固定，不要让它们竞争同一行宽。

4. **关键数字要单独放大。** "14 个程序""4 行代码""132 只猫"这类信息，用 150–190px 金色粗衬线单独占一块版面，配一个可视化图形，而不是挤在 20px 的小字里。参考版式：左侧大字数字 + 右侧图形 + 底部字幕。

5. **角落常驻一个会变的数字。** 一个计数器能同时提供信息密度和"时间在走"的感觉。`Counter` 复用 `Odometer`，让它跟着旁白滚动（例：讲"重复两百轮"就从头滚到尾）。选一个片中最有意义的量，别放装饰性的数字。

6. **字幕加一行英文字幕。** `Subtitle` 传 `en` 后在中文下方加一行斜体小注（字号自动为主行的 36%），两侧带细横线。密度提升明显，且不占额外时间。

7. **角标要让位。** 镜头推近（放大到 1.5 倍以上）时，左上角的章名和计数器会压在主体上（例：满墙"正"字）。做法是推镜时把章名淡出、计数器移到画面下方的空白带，拉远时再回来。别让角标固定在一个坐标上不管镜头。

8. **别忘了标题卡。** 按句组织的时间轴容易漏掉片名 —— 如果稿子里有一句"（标题卡）"，它必须真的有一张画面：红色大印章 + 章名 + 系列名 + 一行英文副题。见 `kit.tsx` 的 `TitleCard`。空屏三秒是全片最显眼的失误。

## 视觉规范

- **底色**：径向渐变 `#2c1f13 → #150e08 → #070504`，叠加暗角和颗粒。
- **金色**：主金 `#d9a54a`、亮金 `#f3d590`；`goldText` 提供金色文字渐变。
- **字体**：中文优先 Songti SC，回退 Noto Serif CJK SC、思源宋体、宋体；拉丁标题优先 Baskerville，斜体副题优先 Didot。其他平台先确认中文字体可用，字体回退可能改变字宽。
- **字幕**：底部居中，默认 62px 衬线粗体；逐字模糊上浮淡入，`【】` 内文字标金。
- **背景大字**：主题英文或拉丁名，230px，透明度约 0.065，缓慢横移，两侧渐隐。
- **表盘**：3D 物体外画 300° 刻度弧、细圆、环形文字和发光标记。
- **信息面板**：左上编号与标题，右上副题与注释，右侧 0–3 行数据配圆形徽章和 12 段进度条。

## 时长与内容数量

默认结构：封面（`HOOK = 120` + `TITLE = 120` 帧，合并为一个场景）→ `PLANETS.length` 个段落，每段 `SEG = 168` 帧 → 收尾 `CLOSE = 216` 帧。

按"一组同类事物"组织的主题直接套用这个结构。按推理一步步展开的主题（例如博弈论、某个机制的原理）更适合"按句组织的时间轴"：每句字幕是一个时间锚点，画面动作都挂在句子上，见 [examples.md](examples.md)。

在 `data.ts` 修改数组及帧数，视频总时长、段落起点、面板总数、收尾布局和配乐时长会同步更新；不需要手工改配乐的秒数。场景内部的入场、退场效果按对应段落时长缩放。随后运行 `npm run still` 或 `npm run render`。

至少保留一个内容项；帧率、各段帧数须为正整数。每项 `id` 唯一，`texture` 独立选择内置纹理，允许多个段落复用同一种纹理。很多项目或很短的段落需要额外检查标签布局与字幕可读性。

## 首帧即封面

**片名卡放第一拍，不要放中间。** 把标题卡放在冷开场之后（第 7 秒左右）会有两个代价：一是它必须做完整的淡入，二是视频未播放时的预览图取第 0 帧，于是封面变成一张空背景或半成品。正确做法是把片名卡作为整片第一拍（约 2.6 秒），并且**第 0 帧已是完成状态**：

- `TitleCard` 传 `instant`：印章已盖下、章名已清晰、分隔线和英文副题都已就位，只保留结尾的淡出，不要淡入。
- 冷开场（真正的问题或代价）放在片名卡之后，用一句字幕把观众带进去。
- 相机表的第一段必须是整屏（`FULL`），第二段才推到第一个主场景。
- 章名 HUD 和角落计数器等角标要等片名卡淡出之后再出现，否则会和标题卡上的印章、章名重复。

第 0 帧必须是完整、可辨认的画面：标题已经显现、主体物体已经点亮，不从黑场淡入。视频未播放时的预览图和平台封面都取首帧，黑首帧会让观众看不出内容。

- 模板的 `CoverScene` 把标题卡放在左侧、主体放在右侧；`TitleCard` 传入 `f={frame + 96}`，入场动画在第 0 帧已经完成。
- 开场提问以字幕（或旁白）形式放在封面上。
- 换主题时同步替换封面的标题、副题和主体物体。交付前抽 `--frame=0` 确认。

## 配音（可选）

旁白用 [edge-tts](https://github.com/rany2/edge-tts) 调用微软在线神经网络语音：免费、音质接近真人，需要联网，另需 `uv`（提供 `uvx`）和 `ffprobe`。它使用的是微软 Edge 朗读服务，并非官方付费 API；商用前请让用户自行确认条款。

### 核心原则：时间轴跟着旁白走

**不要**把一整段旁白铺在固定时长的画面上，也不要在渲染后再混音。那样字幕和画面切换点与语音无关，必然不同步。正确流程：

1. 旁白稿按句写进 `narration.json`，每句对应一条字幕。
2. `npm run voice` 逐句生成 `public/vo/<场景>-<序号>.mp3`（先存原始语音，再做后期处理并裁掉首尾静音），用 `ffprobe` 实测时长，按停顿规则排出每个场景的长度和每句的起始帧，写出 `src/cinematic/voice.ts`。
3. 合成读取 `voice.ts`：场景长度、段落起点、配乐钟声都由它决定；每句的 `<Audio>` 与字幕挂在**同一帧**；画面里的关键事件（爆发、高亮、物体变化）也以某句旁白的起始帧为锚点。
4. `npm run render` 在 Remotion 中一次性渲染画面与全部音频。

### narration.json

- `scenes` 顺序固定：`cover` → 与内容数组同序的各段落 `id` → `closing`。不一致时 `createVoicedTimeline` 会报错并给出期望顺序。
- 每句 `text` 是字幕（`【】` 标金）；`speak` 是朗读文本，省略时朗读去掉 `【】` 的 `text`。
- 朗读文本的写法：数字写成汉字（`46 亿` → `四十六亿`），`-260℃` → `零下二百六十摄氏度`，`≈ > ·` 等符号改写成文字或删掉，单位写全称。字幕保留阿拉伯数字。
- 每段 1–2 句，每句约 12–25 字（3–6 秒）。句子过长会拖长场景，字幕也可能超出一行。
- `pitch` 调音调（如 `-4Hz`），默认 `+0Hz`；`polish` 控制人声后期处理，默认 `true`。
- `pacing`（单位：帧）：默认句前 `lead 20`、句间 `gap 20`、句后 `tail 30`；封面 `lead 12 / gap 14 / tail 24 / min 150`；收尾 `tail 96` 留给片名卡。需要更多停顿的场景（如爆发前的静默）可单独加大 `gap`。

### 声音与混音

- **先试听，再定声音。** 运行 `npm run voice:samples`：用旁白稿前 3 句，按 5 个候选声音（晓晓、晓伊、晓臻〔台湾腔〕、云希、云扬）各读一遍，拼成 `out/voice-samples.mp3`，每个声音前有一声提示音。你无法亲耳判断音色，把文件交给用户挑，再把选中的声音写进 `narration.json` 的 `voice`。
- **AI 味**：晓晓（`zh-CN-XiaoxiaoNeural`）是短视频里最常见的 AI 配音，很多观众一听就能认出来。用户要求"不要太 AI 味的女声"时，提供试听对比；一位真实用户最终选了晓伊（`zh-CN-XiaoyiNeural`，`rate -8%`、`pitch -4Hz`）。其他可选：`zh-CN-YunxiNeural`（男声，轻快）、`zh-CN-YunyangNeural`（男声，新闻播报）、`zh-CN-YunjianNeural`（男声，激昂）。完整列表：`uvx edge-tts --list-voices`。
- **后期处理**（`polish`，默认开启，需要 ffmpeg）：去掉 70Hz 以下低频，180Hz 加一点胸腔暖度，3.2kHz 略提清晰度，7.5kHz 压齿音和电子味，2.5:1 轻压缩，再加两次很短的反射制造一点空间感；同时裁掉每句首尾静音，句间停顿统一交给 `pacing`。没有 ffmpeg 时自动退回原始语音。
- **语速与节奏**：短视频观众偏好比"朗读"更快的节奏。实测：`rate -8%`、每句留足阅读停顿的版本被用户评价"有点慢"，整体提速 1.25 倍后才满意。**新项目直接按快节奏设计，不要事后加速**：`rate +15%` 左右；按句组织的时间轴里，开口前 3 帧、说完后 8 帧再进下一句，`hold` 只留给画面动作本身需要的时间（门打开、刻十笔）。清晰仍然优先，每一步推理都要讲到，收紧的是语速和停顿，不是内容；总时长由稿子决定，不预设 60 秒。已渲染的成片可用 `npm run master -- --speed=1.25` 整体提速（声音不变调）作为补救。
- **配乐闪避**：开启配音后，配乐在说话时压到 0.32，句间回到 0.6，进出各渐变 8 帧（`timeline.ts` 的 `speechWindows` / `musicVolume`）；实测人声比配乐高约 9–10 dB。旁白音量为 1。
- 修改旁白稿、声音、语速或音调后重新运行 `npm run voice`；内容没变的句子会复用已生成的音频。在线服务偶尔断连时，脚本会自动重试。

### 配音交付检查

- `npm run check` 通过，`voice.ts` 中各场景时长合理。
- 抽首帧确认封面；抽每个场景中段的帧，确认字幕不超出一行。
- 渲染后用 `ffprobe` 确认存在音轨、总时长等于 `voice.ts` 的总帧数。用 `volumedetect` 比较几句的“说话区间”和“句前空隙”：说话区间应明显更响（实测高 8–15 dB）。句前若有设计好的音效，空隙也会响，属于正常。
- 无法试听时如实说明，请用户确认语速、音色和音量比例。不要声称已经听过，也不要凭推测宣称“已同步”。可以说明同步的依据：每句音频与字幕挂在同一帧。

## 更换主题

1. **内容**：替换 `PLANETS` 和开场、片名、收尾文案。当前 `Planet` 类型、行星纹理与数值单位属于太阳系示例，新主题需要相应修改类型和模型。
2. **信息面板**：使用通用 `<InfoHUD rows={...}>`。每行 `frac` 为 0–1；跨度大的数据使用开方或对数映射，并保持可比较项目的映射一致。
3. **标题卡**：使用 `<TitleCard f dur title latin subtitle motto />`。
4. **物体**：替换 `PlanetBody`，保留适合主题的主光和金色逆光。没有合适模型时可用几何体（`LatheGeometry` 旋转出棋子、奖杯、瓶子）、程序化纹理或 2D SVG。金属材质（`metalness` 较高）必须在 `<Stage>` 里放 `<Environment />`（`Space3D.tsx`），否则背光的一半会直接发黑。
5. **对位**：`project(camPos, target, point)` 返回屏幕位置和像素缩放系数；表盘半径可设为物体半径乘以系数再加 30。
6. **事实**：为数字和关键事实保存可靠来源。近似值写明“约”；未经核实的数字先核实或删除。太阳系示例的参考入口见 [sources.md](sources.md)，不要把风格化纹理、轨道和尺寸当成真实测绘数据。

更多主题示例见 [examples.md](examples.md)。

## 组件速查（Overlay.tsx）

| 组件 | 关键参数 |
|---|---|
| `Background` | `glowY`：光晕纵向位置（百分比） |
| `Vignette` / `Grain` | `Grain` 接收 `frame` |
| `Fade` | `f`、`dur`、`inF`、`outF` |
| `Dust` | `frame`、`count`、`seed` |
| `LatinBG` | `text`、`frame`、`top` |
| `Dial` | 唯一 `id`、`cx`、`cy`、`r`、`progress`、`rot`、`ring` |
| `Subtitle` | `text`（支持【】）、`en`（英文斜体小注，可选）、`f`、`start`、`end`、`bottom`、`size` |
| `InfoHUD` | `f`、`index`、`total`、`title`、`en`、`italic`、`note`、`rows: {badge,label,value,unit,frac}[]` |
| `TitleCard` | `f`、`dur`、`title`、`latin`、`subtitle`、`motto` |

## 组件速查（linework/kit.tsx）

做线描叙事时用这一套（`src/linework/`）。演示见 Studio 里的 `Linework` 组合。

| 组件 | 关键参数 | 用途 |
|---|---|---|
| `Sky` | `f`、`warm` | 深蓝夜空 + 星点 + 地平线微光 |
| `Seal` | `ch`、`size`、`stamp` | 红色印章（壹/贰/叁…） |
| `ChapterCard` / `ChapterHUD` | `f`、`s`、`d`、`ch` | 章节卡与常驻章名 |
| `Odometer` / `YearTag` | `value`、`size` | 年份里程表（逐位滚动） |
| `Tag` | `x`、`y`、`op`、`anchor`、`boxed` | 画面内的小标签 |
| `drawn` | `p`（0–1） | 逐笔画出：配合 `pathLength=1` 与 dashoffset |
| **`PaperGrid`** | `op`、`size` | 全局网格底板，给线描图形一个承托面 |
| **`ChartFrame`** | `x`、`y`、`w`、`h`、`grid`、`gridStep`、`corner` | 图表外框：基线、角标、横向网格 |
| **`BoxLabel`** | `x`、`y`、`anchor` | 方框注释（口径说明、来源） |
| **`Annot`** | `x`、`y`、`to`、`side`、`num`、`label`、`sub` | 引线标注：圆点 + 折线 + 方框文字 |
| **`Counter`** | `x`、`y`、`value`、`label`、`sub` | 角落计数器，内部复用 `Odometer` |
| **`TitleCard`** | `f`、`s`、`d`、`seal`、`name`、`series`、`en`、`instant` | 片名卡；`instant` 让第 0 帧即完成态（做封面用） |

## 渲染约束

- 使用 `@remotion/three` 的 `ThreeCanvas`；渲染脚本已配置 `--gl=angle`。
- 画面必须由帧号确定。随机数使用 `remotion` 的 `random(seed)` 或纹理中的种子噪声；不要使用 `Math.random()`、`Date.now()` 或 CSS 动画驱动画面。
- 透明画布上的 AdditiveBlending 自定义辉光着色器应输出带强度的 alpha，避免固定 alpha 为 1 产生黑环。
- 温度使用 `℃`，减少宋体中 `°C` 的字形间距问题。
- 3D 内容与标签避开底部约 180px 的字幕区域；收尾全景可下调相机 `target.y` 让主体上移。
- 打勾、箭头、标签不要压在数字或文字上：放在格子的角上或格子之间的空隙里，较长的说明移到旁边的图例。
- 吊灯、灯罩这类贴近画面上沿的物体，镜头推近后会被切掉一半、或压到左上角标题，这时把它隐藏，只保留光。
- `interpolate` 的输入区间必须严格递增，`[a, a]` 会直接报错让渲染中断；按句子算出的起止帧可能相等，用 `linework/kit.tsx` 里的 `k()`（区间相等时退化成阶跃）。
- JSX 里展开公共样式时注意顺序：`<path fill="#0b1230" {...line} />` 会被 `line` 里的 `fill: 'none'` 覆盖，要写成 `{...line} fill="#0b1230"`。`tsc` 会对此报 TS2783，别忽略。
- 东西"消失"用透明度淡出，不要把计数倒着减回去（刻痕会一笔笔倒退）。
- Remotion 各包保持同一精确版本，保留锁文件；升级依赖后重新检查与抽帧。

## 渲染约束（补充）

- **相机查找表的边界。** `CAMS` 这类"时间 → 机位"的数组，插值时要显式向前找当前段，并且**首段必须直接返回、不参与跨段插值**；否则 `CAMS[i-1]` 在开头几帧是 `undefined`，渲染到第 3 帧就报 `Cannot read properties of undefined`。
- **改稿子别忘同步测试。** 测试文件里的 import 路径是与剧集目录绑定的，复制模板做第二集时容易漏改（症状：`Cannot find module '../src/ep01/script.ts'`）。复制后先跑一次 `npm test`。
- **容器尺寸变了要重看标签。** 柱状图、榜单这类"数据 + 标签"的组件，行高、间距、字号是耦合一体的；只调其中一个（例如把行高从 44 调到 40）就要重新抽帧确认底行没有压到字幕。

## 交付检查

1. 执行 `npm run check`。每个场景抽取代表帧，检查字幕、中文字体、物体与表盘对位和黑边。按句组织的片子，用 `npm run stills` 抽每句 80% 处的帧，拼成总览图逐句对照：这一句的动作有没有演出来、标签有没有互相压住、表格文字有没有折行。不要抽在句尾（字幕和画面正在淡出）。
2. 渲染完整视频后，使用 ffmpeg 以 0.5fps 抽帧检查全过程；核对总时长和音轨是否存在。抽帧图里偶尔有一帧偏暗或数字只滚了一半，先确认是不是截在淡入淡出或滚动中途，再决定要不要改。
3. 抽 `--frame=0` 确认首帧是完整封面。
4. **响度**：`npm run master` 把成片标准化到 -16 LUFS，输出 `out/video-master.mp4`，交付这个文件。手机平台常见响度在 -14 到 -16 LUFS 之间。实测：模板直出的示例不配音约 -19 LUFS，开启配音后约 -25 LUFS；换了更安静的配乐后，一集只有 -29 LUFS，外放几乎听不清。用 `--lufs=-14` 可以更响。
5. 使用可用音频工具试听。无法实际试听时如实说明，并请用户检查配乐音量、转场钟声和旁白，不能声称已听过。