edu-physics-video

物理题讲解视频 (edu-physics-video)

把一道物理题做成 16:9、1920×1080、带中文配音 + 中英双语字幕 + 蓝图风格动画的 MP4。流水线与 edu-math-video 相同，区别在解题方法和画面：先按物理解题流程（建模 → 分段 → 受力 → 选规律 → 求解 → 验算）解对，再让画面把物理过程真实地演出来——力箭头按比例从作用点长出、物体按解析解运动、v-t 图同步生长、摩擦力随运动反向而转向。

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

核心原则：画面跟着旁白走，物理过程在图上真的发生。 每句旁白都有一个动作把这句物理演出来；每个动画用"第 k 句旁白开始的时刻"S.at(k, f) 定时，绝不写死秒数；物体的位置只来自解析解 x(t)，用 simT() 线性映射时间（可以慢放，不能缓动）。

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

• template/：可直接运行的完整示例项目（斜面往返：受力分析 + 牛顿第二定律 + 两段运动 + v-t 图）。engine.js 是通用引擎（蓝图主题，不改），phys.js 是物理道具库（力、斜面、物块、弹簧、光线、图像、场），anim.js / script.json / episode.json / storyboard.md / problem.png 是每道题都要重写的。
• examples/laser-curvature/：几何光学竞赛题完整示例（anim.js + script.json + storyboard.md + problem.png）：光线传播、平行玻璃砖侧移、折射定律小角近似、屏幕正视图分解位移、切线/圆心角。光学、几何味重、或题目截图带装置图时先读它。
• shared/pron.py + shared/pron.json：读音控制（GLM-TTS 没有 SSML/拼音输入），已收录物理常见多音词。
• 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）。

必须遵守的规则

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

1. 严格按下面 11 步顺序做，每步的"通过标准"满足了才能进入下一步。
2. 先按物理方法解对题。 第 1 步必须写出解题卡（研究对象、过程分段、每段受力、所用规律、答案、验算），见 reference/physics-solving.md。多段过程、符号答案用 sympy 验算。
3. 先讲清楚题目。 第一幕展示原题图片，旁白逐条读条件，每读一条就在图上框出那一条。
4. tts 字段只能是能念出来的中文。 不能有阿拉伯数字、= + − × ÷ / ^ √ ° ( ) 等符号，单位要读出来：v₀ = 10 m/s 写成 v零等于十米每秒，2 m/s² 写成 二米每二次方秒；sin/cos 写成 正弦/余弦；希腊字母按 pronunciation.md 的表写（θ 西塔、φ 菲）。字幕 zh 保留正常物理写法（v_0、d_A、m/s^2）。
5. 读音必须固定。 调 TTS 之前 --check 必须显示 未固定读音的生僻字/多音字: 0 且 script errors: 0。多音字的标注写在该字后面：长[cháng]、调[tiáo]节。
6. API Key 只能由用户提供。 缺 GLM_API_KEY 时先问用户：配置 key（音质最好，推荐），还是用兜底引擎（edge-tts / macOS say，见 reference/glm-tts-setup.md）。不要编造 key、模型名或接口地址，不要把 key 打印出来或写进项目文件夹。
7. 物理画面必须正确。 力的方向（摩擦力与相对运动相反、弹力垂直接触面）、力箭头按同一比例 FS、物体位置来自解析解、特殊角用课本近似值（sin37° = 0.6）与答案一致；小角度放大画时注明 notToScale()。
8. 所有画面内容在 y ≤ 860 以内（y≈9141044 是字幕框）。图形放左半边 x 60900，推导写在右边 board() 上，用 bm()（支持 v_0^2 上下标）。
9. 先写分镜，再写动画。 storyboard.md 顶部写解题卡 + 图形清单，再给每句旁白规划"指/动/留"，按 reference/visual-design.md 的物理动作表选动作；node render.mjs motion 必须通过。
10. 先预览再花钱（--preview + stills auto），看图验证（每次都打开 build/sheet*.png，汇报你实际看到了什么）。
11. 不要修改 engine.js；通用物理道具加在 phys.js，只属于这道题的图形写在 anim.js。不要把 node_modules、package*.json 复制进视频文件夹。

11 个步骤

第 1 步：按物理方法解题，写解题卡

读 reference/physics-solving.md。拿到题目（有截图先读图），写下：

• 研究对象与模型；过程分段（每段的起止条件与分段判据：速度为零、共速、能否滑回、是否脱离……）；每段受力（大小、方向）；每段所用规律及理由；符号解 → 数值答案（带单位）；验算（量纲、极限、能量/动量另算一遍）。
• 多段过程或符号答案：用 sympy 写脚本算一遍。答案不确定或题目看不清时问用户，不要猜。
• 通过标准： 解题卡完整；能用 4~7 个"幕"讲完（一般一段过程一幕）；答案已验算。

第 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。
• 缺 GLM_API_KEY：停下，按 reference/glm-tts-setup.md 引导用户配置（~/.config/math-problem-video/.env，与数学视频技能共用）。用户没有 key：TTS_ENGINE=auto 自动改用兜底引擎；装 edge-tts 前先征得用户同意。
• 通过标准： setup_check.sh 输出 ALL OK。

第 3 步：测试 TTS

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

• 成功打印 WROTE build/say_xxxx.wav。401/403 = key 错或没余额，告诉用户，不要反复重试。第一次给这个用户做视频时，把 wav 路径给用户试听确认音色。
• 通过标准： 生成了 wav。

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

二选一（细节见 reference/animation.md）：

• 只有文字：PY SKILL/scripts/make_problem_png.py --text "完整题目" --mark "条件1" ... --out PROJ/problem.png。问题 (1)(2)(3) 前用换行 \n 分行。
• 有截图（物理题常带装置图）：复制到 PROJ/，必要时 problem_boxes.py crop；problem_boxes.py grid 读坐标；problem_boxes.py check 确认。截图很高时在 anim.js 里 Object.assign(FRAME, { y0: 110, y1: 880 }) 放大卡片。
• 把尺寸和框填进 anim.js 顶部的 PROBLEM。
• 通过标准： 打开了 *.preview.png 或 *.check.png，文字完整（没有 ☒/□），每个框恰好罩住对应文字。

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

按 reference/script-writing.md 写（含物理式子、单位、希腊字母的口语对照表）。

• 幕的顺序照解题流程：intro 读题 → 受力/建模 → 每段过程 → 分段判断/临界 → （验算）→ outro 回顾 + 报答案。
• 每句 ≤ 36 个汉字宽，一句只讲一件事；数值与解题卡完全一致，带单位。
• 通过标准： JSON 合法；每一幕的 id 都有计划好的画面。

第 6 步：写分镜 storyboard.md

先读 reference/visual-design.md，按 template/storyboard.md 的格式：顶部写解题卡和图形清单（所有物体、接触面、力、已知量、所求量、图像），再每句一行 | 幕id 句号 | 旁白要点 | 指 | 动 | 留 | 板书 |。

• "动"从物理动作表选：力从作用点长出、分解、复制品叠放比较大小、摩擦力转向、物体按解真实运动、v-t 曲线生长、面积着色、光线传播……不能只写"出现/显示/高亮"。每幕至少一个连续运动。
• 通过标准： 每句都有一行；图形清单完整；你能说出每一幕里"最能让人看懂物理"的那个动作。

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

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

• ERROR 行按提示改；⚠ 多音/生僻 按 reference/pronunciation.md 处理（物理常见多音字、希腊字母表都在里面）。
• 通过标准： 未固定读音的生僻字/多音字: 0 且 script errors: 0，退出码 0。

第 8 步：写 anim.js

先通读 template/anim.js，API 见 reference/animation.md（engine.js + phys.js 速查）。结构保持一致：

• PROBLEM、TAGS；物理解常量区（课本近似值、分段解析解 sPos(t)、vel(t)）；几何（incline / block 等用 p: 0 只算几何）；比例常量 FS（px/N）、VS（px per m/s）；SC.<id> 每幕一个。
• 每句：glow(..., bump(lt, at(k))) 指 → 动作 → 留下标记；右侧 board() + bm(...) 逐行写推导（与图同色），答案用 bbox + stamp。
• 通过标准： PY build_audio.py --check 无 ERROR。

第 9 步：免费预览：动作检查 + 版面检查

cd PROJ && PY build_audio.py --preview && node render.mjs motion && node render.mjs stills auto && PY SKILL/scripts/contact_sheet.py .

• motion：STATIC 必须修，每幕至少一句 MOVE。
• 打开 build/sheet_*.png 逐张检查（审查清单）：不重叠、不出界、不压字幕、同步；物理正确：力的方向与比例、物体停下/反向的位置与时刻、图像与运动一致。需要中间帧：node render.mjs stills 12.5,13。
• 通过标准： motion check passed；截图检查通过（在回复里逐幕说明你看到了什么）。

第 10 步：生成配音，自动听写核对，再检查一次画面

cd PROJ && PY build_audio.py && PY build_audio.py --asr && node render.mjs stills auto && PY SKILL/scripts/contact_sheet.py .

• --asr 字母序列对不上的句子标 ✗（退出码 1）：按 pronunciation.md 的"字母"一节修改后重跑。
• 真实时长与预览不同，重新看一遍 sheet（慢放倍率也会变）。
• 通过标准： mix + srt written；字母读错的句子: 0（无 GLM key 时 ASR SKIPPED，交付时列出含字母的句子请用户重点听）；截图检查通过。

第 11 步：渲染视频并交付

cd PROJ && node render.mjs video 6      # 6 = 并行浏览器页数（不是帧率！帧率固定 30）

• 输出 WS/<output_name>.mp4 和 .srt。交付时告诉用户：路径、时长、各幕内容、答案；说明你无法听音频，请用户试听读音，列出你标注过读音的字和希腊字母。

常见错误

错误做法	正确做法
直接列公式算答案，不讲研究对象和过程分段	解题卡先行；幕结构 = 解题流程，分段判据单独一幕讲
摩擦力按"速度方向的反方向"画，物体反向后忘了改	按相对运动（趋势）方向；运动反向时让 f 箭头绕作用点转 180°
物体位置用 lerp(a, b, eio(...)) 滑过去	sPos(simT(lt, t0, dur, T))：解析解 + 线性时间，屏幕注明"慢放 ×k"
力箭头长度随手画，8 N 比 12 N 还长	一幕一个比例 FS，长度 = 大小 × FS
Math.sin(37 * PI / 180)	课本近似 SIN = 0.6, COS = 0.8，与答案一致
tts 写 mg sinθ、sin i、μ = 0.5	重力沿斜面的分力 / m g乘正弦西塔、正弦i、动摩擦因数零点五
tts 里的单位省略或写 m/s	十米每秒、二米每二次方秒，单位一定要读
希腊字母写 斐、伽马	菲、嘎马（见 pronunciation.md 希腊字母表）
板书用 bl('v0^2 ...')	bm('v_0^2 / 2a_1 ...') 渲染上下标
装置图画到右边板子上	缩小比例，或该幕 ctx.translate 左移（board/bm 在 translate 外）
从别的视频文件夹复制代码	用 new_video.sh 从本技能 template/ 建项目
编造 GLM_MODEL、接口地址	模型只有 glm-tts，地址已写在 build_audio.py；只需用户提供 GLM_API_KEY
node render.mjs video 24 以为是 24fps	参数是并行数；预览版面用 stills auto
--check 还有 ⚠ 就调 TTS	修到 0
渲染完不看画面就交付	每次都看 build/sheet*.png

参考文件

• reference/physics-solving.md：物理解题方法：六步流程、分段判据、sympy 验算、把解变成动画的要求、常见题型的幕结构。第 1 步必读。
• reference/visual-design.md：讲解动画设计：指→动→留→连、物理配色、物理→动画动作表、真实运动写法。写分镜前必读。
• reference/animation.md：engine.js + phys.js API、场景写法、版面坐标、题目图片与高亮框、审查清单。
• reference/script-writing.md：script.json 格式、幕的设计、物理式子/单位的口语写法对照表。
• reference/pronunciation.md：读音控制、物理常见多音字、希腊字母读法。
• reference/glm-tts-setup.md：智谱 GLM-TTS 注册、API Key、.env、音色、兜底引擎。
• reference/troubleshooting.md：报错与处理。