/edu-math-video

name: edu-math-video
description: Use when asked to make an explainer / walkthrough video (讲解视频、解题视频、例题精讲、微课) for a math problem (数学题, geometry, algebra, functions, motion/行程 problems), from a problem screenshot or text, with Chinese voice-over (GLM-TTS / 智谱 TTS), bilingual zh+en subtitles and hand-drawn canvas animation rendered to MP4.

数学题讲解视频 (edu-math-video)

把一道数学题做成 16:9、1920×1080、带中文配音 + 中英双语字幕 + 手绘笔记本风格动画的 MP4。

流水线（每个视频一个文件夹）：

script.json ──build_audio.py──► build/timeline.json + build/mix.wav + ../<name>.srt
     (旁白)     (GLM-TTS + 合成音乐)          │
anim.js + engine.js ◄─────────────────────────┘ (按旁白时间点驱动动画)
     └──node render.mjs video──► ../<name>.mp4

**核心原则：画面跟着旁白走，而且图会"讲题"。** 每句旁白，图上都有一个动作把这句推理演出来（线段滑过去重合、三角形叠上去、相机转到俯视、动点移动……），不是只多出一条线、一个标签。每个动画都用"第 k 句旁白开始的时刻"`S.at(k, f)` 定时，绝不写死秒数。

**本技能自带全部代码**，不要从别的项目复制文件：

• `template/`：可直接运行的完整示例项目（直角三角形斜边中线题）。`engine.js` 是通用引擎（不改），`anim.js` / `script.json` / `episode.json` / `problem.png` 是每道题都要重写的。
• `shared/pron.py` + `shared/pron.json`：读音控制（GLM-TTS 没有 SSML/拼音输入）。
• `examples/cone-parallel/`：立体几何完整示例（anim.js + storyboard.md + script.json）：相机斜视↔俯视、侧面展开成扇形、内错角旋转、平面平移。做立体几何、圆、多问题时先读它。
• `scripts/`：`new_video.sh`（建项目）、`setup_check.sh`（查环境）、`make_problem_png.py`（文字题→图片+高亮框）、`problem_boxes.py`（截图→高亮框坐标）、`contact_sheet.py`（截图拼图审查）。

下文 `SKILL` = 本文件所在目录，`WS` = **用户当前所在的目录（你的工作目录，`$PWD`）**：视频文件夹建在这里，mp4/srt 也输出到这里。**不要因为别的目录（包括本技能所在的项目）已经有 `.env`、`node_modules`、`pron.json` 就把 WS 换过去**，缺什么由 `new_video.sh` 和第 2 步补齐。`PROJ` = 本视频文件夹，`PY` = `setup_check.sh` 报告的 python（macOS 上一般是 `/usr/bin/python3`；PATH 里的 `python3` 可能没有 numpy）。

必须遵守的规则

**退出码不是 0 就是没完成。** `--check` 退出码 1（哪怕只剩一个 ⚠ 多音字）、`motion` 退出码 1、截图里有问题，都不能写"只是警告、不影响"然后继续。修好再往下走。

1. **严格按下面 10 步顺序做，每步的"通过标准"满足了才能进入下一步。** 不要跳步，不要"最后一起检查"。 2. **先讲清楚题目。** 视频第一幕必须展示原题图片（截图或 `make_problem_png.py` 生成的图），旁白逐条读条件，每读一条就在图上框出那一条。 3. **`tts` 字段只能是能念出来的中文。** 不能有阿拉伯数字、`= + − × ÷ / ^ √ ∠ △ ∥ ° ( )` 等符号：`AC=3` 写成 `AC等于三`，`x²` 写成 `x的平方`。字幕 `zh` 字段保留正常数学写法。`--check` 会报错拦住。 4. **读音必须固定。** 调 TTS 之前 `--check` 必须显示 `未固定读音的生僻字/多音字: 0` 且 `script errors: 0`。多音字的标注写在该字**后面**：`长[cháng]`、`要[yào]求`。**不能**写成 `中点[zhōng]`（那会把"点"读成 zhōng）。 5. **API Key 只能由用户提供。** 缺 `GLM_API_KEY` 时先问用户：配置 key（音质最好，推荐），还是用兜底引擎（edge-tts / macOS `say`，见 [reference/glm-tts-setup.md](reference/glm-tts-setup.md#没有-glm-key-时兜底引擎)）。不要编造 key、模型名或接口地址，不要把 key 打印出来或写进项目文件夹。 6. **所有画面内容在 y ≤ 860 以内**（y≈914~1044 是字幕框）。图形放左半边 x 60~900，推导文字写在右边的横线板 `board()` 上。 7. **先写分镜，再写动画。** `storyboard.md` 给每句旁白规划"指/动/留"，按 [reference/visual-design.md](reference/visual-design.md) 的动作表选动作；`node render.mjs motion` 必须通过。 8. **先预览再花钱。** 用 `--preview` + `stills auto` 检查版面，没问题再跑真正的 TTS。 9. **看图验证。** 每次渲染截图后都要打开 `build/sheet.png` 亲眼检查（用读图工具），不能只看命令有没有报错。汇报时写你实际看到了什么，不要凭印象全部打勾。 10. **不要修改 `engine.js`**，除非用户要求换风格；需要新图形就在 `anim.js` 里写函数。 11. **不要把 `node_modules`、`package*.json` 复制进视频文件夹**，依赖在 `WS` 根目录装一次，所有视频共享。

11 个步骤

第 1 步：弄清题目，自己先把题解对

• 拿到题目文字（有截图就先读图）。**先自己完整解一遍并验算**，写下：已知条件清单、所求、关键思路（1~2 个）、每一步计算、最终答案、验算方法。
• 答案不确定或题目看不清时，问用户，不要猜。
• **通过标准：** 你能用 3~6 个"幕"讲完，每一幕一句话说清目的；答案已验算。

第 2 步：建项目、查环境

bash SKILL/scripts/new_video.sh "$PWD" <ascii_folder_name>     # WS 就是当前目录
bash SKILL/scripts/setup_check.sh WS/<ascii_folder_name>

• `new_video.sh` 会把 `pron.py`/`pron.json` 链接到技能自带的共享词表，并在找得到时把 `node_modules` 链接到已有安装（不复制）；找不到才需要在 `WS` 下 `npm install`。python 包用 `PY -m pip install --user numpy requests pypinyin pillow`。
• `new_video.sh` 报 `ERROR: ... is where the skill is installed` 说明你把 WS 设成了技能所在的项目，改用当前目录。
• 默认音色是 `chuichui`（锤锤），用户可以在 `.env` 里用 `GLM_VOICE` 换。
• 缺 `GLM_API_KEY`：**停下，按 [reference/glm-tts-setup.md](reference/glm-tts-setup.md) 引导用户**配置（推荐放 `~/.config/math-problem-video/.env`，所有目录通用），然后继续。**不要去别的项目里找 `.env` 用，也不要因此换工作目录。** 用户没有 key 或不想配：`TTS_ENGINE=auto`（默认）会自动改用兜底引擎，`setup_check.sh` 会显示用的是哪个；装 edge-tts 前先征得用户同意。
• **通过标准：** `setup_check.sh` 输出 `ALL OK`。

第 3 步：测试 TTS（验证 key 和音色）

cd PROJ && PY build_audio.py --say "你好，我们来看一道数学题。"

• 成功会打印 `WROTE build/say_xxxx.wav` 和 `voice: ...`（`edge:` / `say:` 开头 = 兜底引擎）。401/403 = key 错或没余额，告诉用户，不要重试 10 次。
• 第一次给这个用户做视频时，把这个 wav 路径告诉用户试听，确认音色（音色表见 glm-tts-setup.md）。
• **通过标准：** 生成了 wav。

第 4 步：准备题目图片 `problem.png` 和高亮框

二选一（细节见 [reference/animation.md](reference/animation.md#题目图片与高亮框)）：

• **只有文字**：`PY SKILL/scripts/make_problem_png.py --text "完整题目" --mark "条件1" "条件2" ... "所求" --out PROJ/problem.png`，它直接输出 `srcW/srcH/boxes`。
• **有截图**：复制到 `PROJ/`，必要时 `problem_boxes.py crop` 裁掉无关部分并存为 `problem.png`；然后 `problem_boxes.py grid` 出坐标网格图，读出每个条件的像素框；再 `problem_boxes.py check` 画框确认。
• 把尺寸和框填进 `anim.js` 顶部的 `PROBLEM`。
• **通过标准：** 你打开了 `*.preview.png` 或 `*.check.png`，文字完整（没有 ☒/□ 方框），每个框都恰好罩住对应文字。

第 5 步：写 `episode.json` 和 `script.json`

按 [reference/script-writing.md](reference/script-writing.md) 写。要点：

• `episode.json`：`title`（视频标题）、`output_name`（输出文件名，如 `斜边中线_Median_to_Hypotenuse`）、`pop_scenes`（要加"啵"音效的幕）。
• `script.json`：幕的数组，每幕 `{"scene": "英文id", "lines": [{"zh","tts","en"}, ...]}`。第一幕 `intro` 读题，最后一幕 `outro` 回顾 + 报答案。
• 每句旁白 ≤ 36 个汉字宽（否则字幕折两行），一句只讲一件事。
• **通过标准：** JSON 合法；每一幕的 id 都有计划好的画面。

第 6 步：写分镜 `storyboard.md`

**先读 [reference/visual-design.md](reference/visual-design.md)**，再按 `template/storyboard.md` 的格式给每句旁白写一行：`| 幕id 句号 | 旁白要点 | 指 | 动 | 留 | 板书 |`。

• "指"：这句提到的元素怎么点亮。"动"：图上**一个**体现推理的动作，从动作表里选（相等→复制滑过去重合，全等→三角形叠上去，立体↔平面→相机转动，求长度→数字计数……）。"留"：动作后留下的标记。
• 除第一幕和最后一幕外，"动"不能空，也不能只写"出现/显示"。每幕至少一个连续运动。
• 先想清楚：只看图、不看板子，观众能不能看懂这一步为什么成立？不能就换动作。
• 先在 storyboard.md 顶部写**图形清单**：题目里所有的点、线段、平行/垂直/中点关系、已知长度，全部要画出来，位置按数据计算。
• **通过标准：** 每句都有一行；图形清单完整；你能说出每一幕里"最能让人看懂"的那个动作。

第 7 步：读音与脚本检查，修到 0

cd PROJ && PY build_audio.py --check ; cat build/pron_report.txt

• `ERROR` 行：按提示改 `script.json`（通常是 tts 里有数字/符号，或 anim.js 缺 `SC.<id>`；第 8 步写完 anim.js 前后者会报错，属正常）。
• `⚠ 多音/生僻` 行：按 [reference/pronunciation.md](reference/pronunciation.md) 处理：该字后面加 `[拼音]`，或反复出现的词加进 `pron.json` 的 `words`，确认默认读音正确的词加进 `ok`。
• **通过标准：** `未固定读音的生僻字/多音字: 0` 且 `script errors: 0`，退出码 0。

第 8 步：写 `anim