Math Problem Explainer Video (edu-math-video)

Turn a math problem into a 16:9, 1920×1080 MP4 with Chinese voice-over, bilingual Chinese-English subtitles, and hand-drawn notebook-style animation.

Pipeline (one folder per video):

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

Core principle: the visuals follow the voice-over, and the graphics themselves “explain the problem.” For every narration line, an on-screen action performs the reasoning expressed by that line (a segment slides over until it overlaps, a triangle is overlaid, the camera rotates to a top-down view, a moving point travels, and so on); it is not enough to merely add one more line or label. Every animation is scheduled using “the moment narration line k begins,”

S.at(k, f)

, and never uses hard-coded seconds.

This skill includes all the code; do not copy files from another project:

```
template/
```
: a complete, directly runnable example project for the problem about the median to the hypotenuse of a right triangle.
```
engine.js
```
is the general-purpose engine and must remain unchanged, while
```
anim.js
```
,
```
script.json
```
,
```
episode.json
```
, and
```
problem.png
```
must be rewritten for every problem.
```
shared/pron.py
```
+
```
shared/pron.json
```
: pronunciation control, because GLM-TTS does not accept SSML or pinyin input.
```
examples/cone-parallel/
```
: a complete solid-geometry example containing
```
anim.js
```
,
```
storyboard.md
```
, and
```
script.json
```
: an angled camera view transitioning to a top-down view, a side unfolding into a sector, rotation to illustrate alternate interior angles, and translation across a plane. Read this first when working on solid geometry, circles, or multiple problems.
```
scripts/
```
:
```
new_video.sh
```
(create a project),
```
setup_check.sh
```
(check the environment),
```
make_problem_png.py
```
(convert a text problem into an image with highlighted boxes),
```
problem_boxes.py
```
(extract highlighted-box coordinates from a screenshot), and
```
contact_sheet.py
```
(create a contact sheet for screenshot review).

Below,

SKILL

= the directory containing this file, and

WS

= the user's current directory (your working directory,
$PWD
). The video folder is created here, and the MP4 and SRT files are also output here. Do not switch to a different directory merely because another directory, including the project containing this skill, already has
.env
,
node_modules
, or
pron.json
. Fill any gaps with

new_video.sh

and Step 2.

PROJ

= the folder for this video, and

PY

= the Python executable reported by

setup_check.sh

(on macOS this is generally

/usr/bin/python3

; the

python3

in PATH may not have numpy).

Mandatory Rules

An exit code other than 0 means the task is incomplete. A

--check

exit code of 1, even if only one ⚠ polyphonic-character warning remains, a

motion

exit code of 1, or any problem visible in the screenshots means the work is not finished. Do not claim that an issue is merely a warning and does not affect the result. Fix it before continuing.

Strictly follow the 10 steps below in order. Each step's acceptance criteria must be satisfied before proceeding to the next step. Do not skip steps or defer all checks until the end.
Explain the problem clearly first. The first scene of the video must display the original problem image, whether it is a screenshot or generated by
```
make_problem_png.py
```
. The voice-over must read each condition one at a time, and the corresponding condition must be boxed on the image as it is read.
The
tts
field may contain only Chinese text that can actually be spoken. It must not contain Arabic numerals or symbols such as
```
= + − × ÷ / ^ √ ∠ △ ∥ ° ( )
```
. Write
```
AC=3
```
as
```
AC等于三
```
, and
```
x²
```
as
```
x的平方
```
. The subtitle's
```
zh
```
field retains normal mathematical notation.
```
--check
```
will report an error and block the workflow.
Pronunciation must be deterministic. Before invoking TTS,
```
--check
```
must show
```
未固定读音的生僻字/多音字: 0
```
and
```
script errors: 0
```
. A polyphonic-character annotation must appear immediately after the relevant character:
```
长[cháng]
```
,
```
要[yào]求
```
. Do not write
```
中点[zhōng]
```
, because that causes 点 to be pronounced as zhōng.
Only the user may provide the API key. If
```
GLM_API_KEY
```
is missing, first ask the user whether they want to configure a key for the best audio quality, which is recommended, or use a fallback engine such as edge-tts or macOS
```
say
```
; see reference/glm-tts-setup.md. Do not invent a key, model name, or endpoint. Do not print the key or write it into the project folder.
All visual content must remain within y ≤ 860. The area around y ≈ 914–1044 is reserved for subtitles. Place graphics in the left half at x 60–900, and write derivations on the ruled board on the right using
```
board()
```
.
Create the storyboard before the animation. In
```
storyboard.md
```
, plan a “point/move/retain” action for every narration line and select actions from the table in reference/visual-design.md.
```
node render.mjs motion
```
must pass.
Preview before spending money. Use
```
--preview
```
together with
```
stills auto
```
to check the layout, and run the real TTS only after the preview is correct.
Verify the rendered images visually. After every rendering pass, open
```
build/sheet.png
```
and inspect it with an image-reading tool. Do not rely only on whether the command reported an error. When reporting the results, describe what you actually saw rather than marking every item as passed based on assumptions.
Do not modify
engine.js
unless the user requests a different visual style. Implement new graphics as functions in
```
anim.js
```
.
Do not copy
node_modules
or
package*.json
into the video folder. Install dependencies once at the
```
WS
```
root and share them across videos.

The 11 Steps

Step 1: Understand the Problem and Solve It Correctly First

Obtain the problem text; if a screenshot is provided, read it first. Solve the entire problem yourself and verify the result, then record the list of given conditions, the target, the key idea or ideas (1–2), every calculation, the final answer, and the verification method.
If the answer is uncertain or the problem is unreadable, ask the user rather than guessing.
Acceptance criteria: You can explain the problem in 3–6 “scenes,” with one sentence per scene explaining its purpose, and the answer has been verified.

Step 2: Create the Project and Check the Environment

bash

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

```
new_video.sh
```
links
```
pron.py
```
and
```
pron.json
```
to the skill's shared pronunciation dictionary and links to an existing
```
node_modules
```
installation when one can be found instead of copying it. Run
```
npm install
```
under
```
WS
```
only if no suitable installation is found. Install the Python packages with
```
PY -m pip install --user numpy requests pypinyin pillow
```
.
If
```
new_video.sh
```
reports
```
ERROR: ... is where the skill is installed
```
, it means WS was set to the skill's own project. Use the current directory instead.
The default voice is
```
chuichui
```
(Chuichui). Users can change it with
```
GLM_VOICE
```
in
```
.env
```
.
If
```
GLM_API_KEY
```
is missing, stop and guide the user through the configuration described in reference/glm-tts-setup.md. The recommended location is
```
~/.config/math-problem-video/.env
```
, which works across all directories. Then continue. Do not look for a
.env
file in another project, and do not change the working directory because the key is missing. If the user has no key or does not want to configure one,
```
TTS_ENGINE=auto
```
, which is the default, automatically switches to a fallback engine, and
```
setup_check.sh
```
reports which engine is in use. Ask for permission before installing edge-tts.
Acceptance criteria:
```
setup_check.sh
```
prints
```
ALL OK
```
.

Step 3: Test TTS and Verify the Key and Voice

bash

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

Success prints
```
WROTE build/say_xxxx.wav
```
and
```
voice: ...
```
. A voice beginning with
```
edge:
```
or
```
say:
```
indicates a fallback engine. A 401/403 response means the key is invalid or has no remaining balance. Tell the user rather than retrying ten times.
When creating the first video for a user, provide the WAV path so the user can audition the voice. The voice list is available in glm-tts-setup.md.
Acceptance criteria: A WAV file is generated.

Step 4: Prepare

problem.png

and the Highlighted Boxes

Choose one of the following methods; see reference/animation.md for details:

Text only:

PY SKILL/scripts/make_problem_png.py --text "完整题目" --mark "条件1" "条件2" ... "所求" --out PROJ/problem.png

. The script directly outputs

srcW

srcH

, and

boxes

Screenshot provided: Copy it into
```
PROJ/
```
. If necessary, use
```
problem_boxes.py crop
```
to remove irrelevant content and save the result as
```
problem.png
```
. Then use
```
problem_boxes.py grid
```
to generate a coordinate-grid image and read the pixel box for each condition. Finally, use
```
problem_boxes.py check
```
to draw and verify the boxes.
Enter the dimensions and boxes at the top of
```
anim.js
```
in the
```
PROBLEM
```
object.
Acceptance criteria: You have opened the
```
*.preview.png
```
or
```
*.check.png
```
file, the text is complete with no ☒ or □ placeholder glyphs, and every box covers exactly the corresponding text.

Step 5: Write

episode.json

and

script.json

Follow reference/script-writing.md. Key points:

```
episode.json
```
:
```
title
```
(video title),
```
output_name
```
(output filename, such as
```
斜边中线_Median_to_Hypotenuse
```
), and
```
pop_scenes
```
(scenes that should include the “pop” sound effect).
```
script.json
```
: an array of scenes, where each scene has the form
```
{"scene": "English ID", "lines": [{"zh","tts","en"}, ...]}
```
. The first scene,
```
intro
```
, reads the problem, and the final scene,
```
outro
```
, reviews the solution and states the answer.
Each narration line must be no more than 36 Chinese-character widths wide; otherwise the subtitle wraps onto two lines. Each line should communicate only one idea.
Acceptance criteria: The JSON is valid, and every scene ID has a planned visual composition.

Step 6: Write the Storyboard

storyboard.md

Read reference/visual-design.md first, then follow the format in

template/storyboard.md

and write one row per narration line:

| scene ID line number | narration point | point | move | retain | board notes |

“Point” describes how the element mentioned by the line is highlighted. “Move” describes one on-screen action that demonstrates the reasoning, selected from the action table (equal → copy and slide until it overlaps, congruent → overlay the triangles, solid ↔ planar → rotate the camera, find a length → count units, and so on). “Retain” describes the mark left after the action.
Except for the first and final scenes, “Move” must not be empty and must not merely say “appears” or “is displayed.” Every scene must contain at least one continuous motion.
First determine whether a viewer can understand why the step is valid by looking only at the graphics, without reading the board. If not, replace the action with a clearer one.
At the top of
```
storyboard.md
```
, write the graphics inventory: every point, segment, parallel/perpendicular/midpoint relationship, and given length in the problem must be drawn, with positions calculated from the data.
Acceptance criteria: Every narration line has a row, the graphics inventory is complete, and you can identify the action in each scene that makes that step easiest to understand.

Step 7: Check Pronunciation and the Script Until All Errors Are Resolved

bash

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

For an
```
ERROR
```
line, follow the instructions to fix
```
script.json
```
. This is usually caused by digits or symbols in
```
tts
```
, or by a missing
```
SC.<id>
```
in
```
anim.js
```
. The latter is expected before Step 8 and is not an error at that point.
For a
```
⚠ 多音/生僻
```
line, follow reference/pronunciation.md. Add
```
[pinyin]
```
after the character, or add recurring words to the
```
words
```
list in
```
pron.json
```
. Add words whose default pronunciation is already correct to
```
ok
```
.

Acceptance criteria:

未固定读音的生僻字/多音字: 0

script errors: 0

, and the exit code is 0.

Step 8: Write

anim.js

Implement the storyboard line by line, using the API in reference/animation.md. Read the complete example in

template/anim.js

before starting, and preserve the same structure:

```
PROBLEM
```
(the data from Step 4),
```
TAGS
```
(the tag in the upper-left corner of each scene), graphics functions such as
```
fig(st)
```
, and
```
SC.<id> = (lt, S) => {...}
```
for each scene.
Each element's appearance time must match the moment the narration mentions it:
```
S.P(S.at(k, f), duration)
```
.
For every line: use
```
glow(..., bump(lt, at(k)))
```
to highlight the mentioned element, then perform the storyboard action, such as
```
slideSeg
```
,
```
movePoly
```
,
```
camTween
```
, moving a point, or
```
countTo
```
, and finally leave the resulting mark.
On the right, use
```
board()
```
and
```
bl(line number, text, S.at(k, f), lt)
```
to write the derivation line by line in the same color as the corresponding graphic. Finally, use
```
stamp()
```
to stamp the answer.
Acceptance criteria:
```
PY build_audio.py --check
```
reports no errors.

Step 9: Perform a Free Preview and Check Motion and Layout

bash

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

```
motion
```
takes six frames from every narration line and compares changes in the graphics area on the left. Every
```
STATIC
```
result, meaning no visual change, must be fixed. Every scene must contain at least one
```
MOVE
```
. If the check fails, return to the storyboard and choose a better action; do not add a meaningless shake merely to pass the check.
```
stills auto
```
captures a frame near the end of each narration line, by which time everything introduced by that line should be visible. A
```
FAILED: page error
```
message indicates a JavaScript error in
```
anim.js
```
and must be fixed.
Open
```
build/sheet.png
```
and inspect it image by image. If there are more than 12 images, the files are named
```
sheet_1.png
```
,
```
sheet_2.png
```
, and so on. Check each image against the reference/animation.md review checklist: there must be no overlaps, no out-of-bounds content, nothing blocking the subtitles, every mentioned element must be drawn, and all values must match the solution.
If there is a problem, edit
```
anim.js
```
and rerun this step.
Acceptance criteria: The output includes
```
motion check passed
```
, and every screenshot passes review. In the response, describe what was actually observed in each scene.

Step 10: Generate the Real Voice-over, Verify It with ASR, and Recheck the Visuals

bash

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

TTS output is cached in
```
build/tts/
```
, so only modified lines are synthesized again.
```
--asr
```
uses Zhipu speech recognition to transcribe each narration line back into text and writes the results to
```
build/asr_report.txt
```
; results are cached. A sentence whose letter sequence does not match is marked with ✗ and produces exit code 1. Modify that sentence according to the “letters” section of pronunciation.md, then rerun these two commands. Also review the Chinese characters in the report. If an obviously mispronounced character is found, and it is not merely a homophone or an ASR result such as converting 三 to 3, correct it according to Step 7.
The real duration may differ from the preview. Review the contact sheet again.
Acceptance criteria: The command prints
```
mix + srt written
```
;
```
--asr
```
reports
```
字母读错的句子: 0
```
. Without a GLM key, it displays
```
ASR SKIPPED
```
; in that case, tell the user during delivery that the letter pronunciation was not machine-verified and list the sentences containing names or other potentially ambiguous terms so the user can listen to them carefully.

Step 11: Render and Deliver the Video

bash

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

This outputs
```
WS/<output_name>.mp4
```
and
```
WS/<output_name>.srt
```
, where
```
WS
```
is the user's current directory. A two- to three-minute video generally takes a few minutes to render.
During delivery, provide the MP4 and SRT paths, the duration, and a summary of every scene. Explain that you cannot listen to the audio and ask the user to audition the pronunciation. In particular, list every character whose pronunciation was manually annotated. If the user reports a mispronunciation, add it to
```
pron.json
```
or use an inline annotation, then rerun Steps 10 and 11. Only the modified lines will be synthesized again.

Common Mistakes That Have Actually Occurred

Incorrect approach	Correct approach
Create the project in another directory that already has `.env` or `node_modules` , such as the project containing the skill, simply because the current directory lacks them	WS is always the user's current directory. Use `new_video.sh` to link dependencies and ask the user to configure `~/.config/math-problem-video/.env` when a key is required
Copy code from another video folder, such as a chemistry project	Create the project from this skill's `template/` with `new_video.sh`
Invent settings such as `GLM_MODEL=glm-4-voice` or `api.zhipuai.cn`	The only model is `glm-tts` , and the endpoint is already defined in build_audio.py. The user only needs to provide `GLM_API_KEY` ; `GLM_VOICE` is optional
Assume `node render.mjs video 24` means 24 fps	The argument is the number of parallel processes. Use `stills auto` for layout previews, and do not repeatedly render the entire video
Write `中点[zhōng]`	An annotation applies only to the immediately preceding character: `中[zhōng]点` . In fact, 中点 does not require an annotation
Write expressions such as `AC=3` , `60 − 7t` , or `x²` in `tts`	Write `AC等于三` , `六十减七t` , and `x的平方`
Place an arbitrary problem screenshot at (50,50) with a size of 400×400	Use `PROBLEM` and `problemCard()` to fit it automatically into the card below the title
Schedule animation with an absolute timestamp such as `if (lt > 12.5)`	Use `S.at(k, f)` , where `f` is a proportion of the time since narration line `k` began
Deliver the video without inspecting the rendered images	Inspect `build/sheet.png` after every rendering pass
Manually write `C、O` or `C,O` in `tts` to separate letters	This is unnecessary: pron.py automatically splits adjacent letters into `C O` . In testing, commas and enumeration commas introduce extra pauses
Invoke TTS while `--check` still contains a ⚠	Resolve it to zero; otherwise, the system may spend money synthesizing incorrect pronunciation
Add common words to `pron.json` or annotate them inline “just to be safe”	Annotate only characters that may be mispronounced. Replacing words with homophones damages phrasing, such as `直搅三搅形` ; pron.py already replaces text only when the context would otherwise produce an incorrect pronunciation
Put more than about 20 characters in a clause without punctuation	Add commas at natural breathing points and keep clauses at 18 characters or fewer. `--check` will warn otherwise, and TTS may otherwise pause in the middle of a phrase
Fail to notice that `x²` in a problem image has become `x☒`	Zoom in on the text during review. make_problem_png.py automatically switches fonts
Introduce curly quotation marks such as `“` into JSON after editing it, causing parsing to fail	JSON syntax requires straight English quotation marks ( `"` ); see troubleshooting.md
Draw everything at once and then add only one line or label per narration line, leaving all reasoning on the board	Every line must contain point → move → retain. Slide equal elements until they overlap, use `camTween` for solid-to-top-view transitions, and ensure `render.mjs motion` passes
Draw a separate top-view diagram beside the original when a top view is needed	Rotate the same 3D model with `camTween` until pitch = π/2
Put three or four knowledge points into one narration line	Use one point per line and introduce one element in sync with the visuals

Reference Files

reference/glm-tts-setup.md: Zhipu GLM-TTS registration, API key,
```
.env
```
, voices, speaking rate, and error handling. Read this when guiding the user through configuration.
reference/script-writing.md:
```
script.json
```
format, scene design, and a comparison table for converting mathematical notation into spoken language.
reference/pronunciation.md: pronunciation-control principles, annotation syntax,
```
pron.json
```
, and common mathematical polyphonic characters.
reference/visual-design.md: How to design instructional animation, including point → move → retain → connect, a table mapping reasoning to animation actions, solid-to-top-view transitions, cone unfolding, and the storyboard format. This file is required before creating a storyboard.
reference/animation.md: engine.js API, scene implementation, layout coordinates, drawing methods for geometry, functions, solid geometry, and motion/distance problems, and the review checklist.
reference/troubleshooting.md: errors and solutions.

edu-math-video

NPX Install

Tags

SKILL.md Content (Chinese)

Math Problem Explainer Video (edu-math-video)

Mandatory Rules

The 11 Steps

Step 1: Understand the Problem and Solve It Correctly First

Step 2: Create the Project and Check the Environment

Step 3: Test TTS and Verify the Key and Voice

Step 4: Prepare
`problem.png`
and the Highlighted Boxes

Step 5: Write
`episode.json`
and
`script.json`

Step 6: Write the Storyboard
`storyboard.md`

Step 7: Check Pronunciation and the Script Until All Errors Are Resolved

Step 8: Write
`anim.js`

Step 9: Perform a Free Preview and Check Motion and Layout

Step 10: Generate the Real Voice-over, Verify It with ASR, and Recheck the Visuals

Step 11: Render and Deliver the Video

Common Mistakes That Have Actually Occurred

Reference Files