读书视频工厂：文稿 → 竖版成片
从一篇 Markdown 读书文稿出发，五步产出可发布的竖版视频（1080×1920，h264+aac）。
内置的每一条规则都来自 46+ 期真实生产的战损，不是理论。
五步流水线
文稿 → ①转换(契约闸门) → ②配音(四档) → ③时间轴回写 → ④渲染 → ⑤交付检查
① 文稿转换（渲染前闸门）
python scripts/script_to_data.py 文稿.md --book 书名 --author 作者 -o episode.json
- 转换器内置数据契约：标题 4-30 字、封面词 2-12 字、钩子 ≤25 字、段数 3-8、单段 10-220 字
- 校验失败必须停下修数据，绝不允许放宽契约让它通过
- 输出里的
_diagnostics字段：复核截断和估算用，下游忽略 - exit code 2 = 有致命问题，此时渲染出来的片必是坏的（末尾硬切/Outro 消失）
② 配音（四档 provider，默认零 key）
python scripts/make_voice.py episode.json --audio-dir audio/ --provider edge --sync
| provider | key 要求 | 音色 | 适用 |
|---|---|---|---|
edge（默认） |
无 | zh-CN-XiaoxiaoNeural 等 | 开箱即用，秒级合成 |
mmx |
mmx 账号 | mmx speech voices 查看 26+ 音色 |
进阶音质 |
minimax |
自备 key | speech-2.6-hd | 最高音质 |
voice-studio |
本地服务 | 自定义/克隆音色 | 离线/品牌声音（CPU 每句 40-50s，慢） |
- voice-studio 需先启动本地服务（默认
http://127.0.0.1:3900），合成慢但全离线 - 断点续跑：已存在的段自动跳过，中断重跑即可续传
- 音频时长必须 ffprobe 实测，估算值只配出现在
_diagnostics
③ 时间轴回写（音画对齐真值）
--sync 参数用实测音频时长回写 episode.json（段间 0.4s 呼吸）。
脚本里的时间标注只是意图，实测时长才是渲染依据。 漂移门禁从这里起算。
④ 渲染
cd assets/starter
npm install # 首次
npx remotion render src/index.ts BookVideo out/video.mp4 --props <episode.json 绝对路径>
配音文件放 assets/starter/public/audio/section_XX.mp3（--sync 后按 timeline 命名）。
durationInFrames 由 calculateMetadata 从数据推导，绝不写死——写死 = 数据一超就静默截尾。
⑤ 交付检查（全过才许交付）
- 契约校验 exit code 0
- 成片 ffprobe：时长 ≈ 实测音频总长 + 2.5s 收尾（±1s）
- 抽 3 帧（封面/正文/金句）人眼查排版—— Remotion 截断不报错，渲染成功 ≠ 内容正确
- 音画漂移抽查：任一段落画面切换点与配音起点偏差 ≤ 250ms
npm install用--cache <D盘路径>，别把缓存写进 C 盘
已知战损（遇到同类症状直接对症）
| 症状 | 根因 | 修法 |
|---|---|---|
| 成片末尾被硬切、Outro 不出现 | durationInFrames 写死 | calculateMetadata 由数据推导（starter 已内置） |
| 首句配音念两遍 | hook 拼进 TTS 正文 | 转换器已做前缀互斥；自写拼接时判 startsWith |
| 动画元素几秒后消失 | interpolate 只 clamp 左侧 | 右侧必须 extrapolateRight: 'clamp'（starter 已内置） |
| 中文生成非法文件名 id | id 未经归一化 | 转换器 ASCII 化 + 哈希兜底 |
| 时间轴估算离谱 | 区间/时长两种标注混用 | 转换器双模式真解析，无法解析才估算并标记 |
依赖与环境
- Node 18+（渲染）；Python 3.10+（转换/配音）
pip install edge-tts（默认配音）- ffprobe/ffmpeg（时长实测与拼轨，缺 ffprobe 时配音层拒绝工作——这是故意的）
- 首次渲染 Remotion 需下载 headless shell，国内网络慢可设
REMOTION_DOWNLOAD_HEADLESS_SHELL=false并用系统 Chrome
边界（NOT for）
- 真人出镜、实拍素材剪辑
- 横屏长视频（本产线是竖版 1080×1920）
- 想要不同视觉风格：改
assets/starter/src/BookVideo.tsx的设计 token（配色/字号/卡片），数据契约不变
