用途
Motion Explainer 把「上网查资料 → 写脚本 → 中文旁白 → 一格一格做动画 → 字幕 → 配色 → 自我审查 → 输出 MP4」串成一条固定流程，目标是产出一支可直接上课投影或上传 YouTube 的原理解说动画（explainer video / motion graphics）。
流程建立在三部分之上：
- HyperFrames（HeyGen 开源，用 HTML + GSAP 输出 MP4）及其官方 skills，特别是 /hyperframes 入口和 /faceless-explainer 工作流，做法以官方为准。
- 本仓库的 motion-design（品味规则：缓动、节奏、停留、中文排版）与 review-loop（contact sheet 自我审查），好不好看以这两个为准。
- 本文件夹 scripts/ 的工具：补足官方流程对中文旁白、字幕、字型一致性和三色主题处理不足的地方；references/lessons.md 记录实战踩过的坑，动工前必读。
主要能力
环境检查
首次使用先运行 python <me>/scripts/hw_check.py --project <项目>，检测 CPU、内存、GPU 和硬盘，并建议旁白引擎、--workers 数量与 sub-agent 是否分批派发。建议均为推估，不是跑分。所需环境：Node.js 22+、ffmpeg/ffprobe、Python 3 + Pillow + fonttools（pip install pillow fonttools；装了 brotli 字型会输出 woff2，否则输出 ttf）；HyperFrames CLI 用 npm install -g hyperframes，再跑 hyperframes doctor（Docker、Whisper、Kokoro、MusicGen 均为选配）；官方 skills 用 hyperframes skills update，做这类片还要 hyperframes skills update faceless-explainer。匿名使用统计默认开启，可询问用户是否 hyperframes telemetry disable。
TTS 二选一（需询问用户）：edge-tts（默认，pip install edge-tts，不需 GPU，生成时需联网，台湾口音有 zh-TW-HsiaoChenNeural 女、zh-TW-HsiaoYuNeural 女、zh-TW-YunJheNeural 男）；Breeze TTS 2（进阶，需本机 NVIDIA GPU，约 7.7 GB VRAM，建议 12 GB 以上，模型档约 7 GB，可用文字描述设计声音再做声音复制）。其他引擎只要能为每句输出 assets/voice/raw/NN.wav 也可。
研究与需求确认
有网络搜索时，查主题最新资料，至少两个独立来源；数字对不上要记录，取来源一致的那个。每个数字分三类并在画面上标注：官方宣称／实测或报道／自己的估算。自己做的物理或数学估算须与现实比对。不用品牌照片和 logo，主角用自绘示意图并标注「示意图」。需求访谈按 /hyperframes 的 intent layer 一次问完，必确认播放平台（上课／YouTube → 16:9）、长度（建议 60–90 秒）、要不要旁白、要不要先审分镜、自动化还是边做边调；另加问背景色、主色、强调色三种颜色，无偏好则推荐黑底 #121212、白字 #F2F0EA、橘色强调 #FF7A1A；全片统一一种字型，默认源石黑体粗体（GenSeki Gothic Bold，OFL 授权），确认后写入项目的 theme.json。
建项目与分镜
用 hyperframes init videos/<kebab-name> --non-interactive --example=blank --skill=faceless-explainer 建项目，写 BRIEF.md，照 /faceless-explainer 的 Step 0–2 做，选线稿清楚的 preset（如 cobalt-grid），在 frame.md 加繁体中文覆写，并跑 bash <me>/scripts/fetch_fonts.sh <project> 把字型放进 assets/fonts/，不依赖 Google Fonts 线上载入。写 STORYBOARD.md 和 SCRIPT.md，旁白按「子句」切（每个逗号是一个画面揭示时间点），数字写成国字以免 TTS 念错。
旁白制作
按分镜格号生成每句一个 WAV。edge-tts 用 python <me>/scripts/edge_tts_voice.py --project <p> --voice zh-TW-HsiaoChenNeural [--rate=-5%]，全片同一 voice 保证一致；Breeze 先用 --only-ref 设计参考声音让用户试听，确认后再产生全部句子。先让用户试听前一两句，口音与情绪由耳朵决定。若整片完成后发现某字念错，不整句重录（会打乱该格动画时间），而是同声音同句生成 4–6 个候选，用 fix_voice.py audition 串成试听档让用户选，再 apply --line N --take NN_X 把新句等比伸缩回原长度、对齐音量并重算该句字幕时间，然后重建字幕 → patch_captions.py → theme.py → 重新输出。之后跑 voice_meta.py 量出子句时间，再用官方 audio.mjs sync-durations 同步。成片响度目标约 −14 LUFS、true peak ≤ −1 dBFS，按实测差值统一调整各句旁白音量。
镜头设计与平行制作
在 shots.json 用「第几个子句 → 画面上出现什么」写每格，跑 apply_shots.py 换算真实秒数写回 STORYBOARD.md。blueprint 只能是 <id> (Adapt)、<id> (Reproduce) 或 compose。先用 hyperframes catalog --query 找现成元件。多格重复出现的主角先画成共用 SVG 并固定坐标，所有 worker 照抄。用 frame-packets.mjs 产生每格 packet，复制 dispatch_context 填好项目值，每格派一个 sub-agent 平行做；没有 sub-agent 时按格号顺序逐格做。相邻格接续同一画面时，先完成那格回报的精确几何要立刻转给还在做的那格。全部回来后跑 unify_frames.py 统一字型和发丝线位置。
组装、字幕与配色
依次执行 captions.mjs build、assemble-index.mjs（须在字幕之后，输出要看到 captions 为 yes）、patch_captions.py（中文字幕字型与粗细，默认粗体 700）、theme.py（套用 theme.json 三色与字型）、transitions.mjs inject 与 verify，最后 hyperframes lint && hyperframes check。字幕每次重建后都要重跑 patch_captions.py 再跑 theme.py；transitions.mjs inject 会延长每格长度，每次跑完 theme.py 都要再 inject 一次，但不要连续 inject 两次。最后才跑 subset_fonts.py 瘦身字型（CJK 字型从 12–17 MB 降到几百 KB）；任何改动文字、字幕或配色的动作之后都要重跑 theme.py。
审查与交付
先 hyperframes check，再用 draft 品质输出整片，在每个子句结束前 0.15 秒截一格拼成 contact sheet，用 sheet.py 逐张亲眼看，对照 lessons.md 检查表逐项修，直到一轮无问题。最后用 hyperframes render --skill=faceless-explainer --quality high 输出最终版并再量一次响度。交付时给出 MP4 路径、片长、总览 contact sheet，并列出用了哪些来源、哪些数字是宣称或估算、哪些地方与需求不同、哪些没做。
适用场景与限制
适用于解说动画、科普动画、原理动画、教学动画、explainer video、motion graphics 等。流程对 agent 能力有要求：部分 Codex、Gemini 设定没有 sub-agent，也能跑完整流程，第 6 节改为自己按顺序逐格做，每格读的档案和顺序不变。资料未提供收费、价格与效果保证；硬件建议为推估；旁白口音与情绪需用户试听决定，ASR 只能筛掉明显错误，声调对错 ASR 听不出来。