math_explainer_video v1.0.0

name: "math_explainer_video" description: "Making animated math explainer videos that are actually correct: break one problem into visual steps for algebra, geometry, or a word problem, storyboard the reveal in Polya order (understand, plan, solve, answer, check), write narration that tracks the visuals and says equations in words, animate with any tool, and run a two-pass accuracy check before delivery. Ships a solution verifier and a storyboard checker plus three fully worked examples. Use when asked to make a math explainer, animate a solution, teach an equation or a geometry problem on video, or fix a math video that confuses viewers."

Math Explainer Video

Purpose

Turn one math problem into a short animated video a viewer can follow step by step and trust. The work that decides quality happens before animation: the step design, a storyboard where narration and visuals land together, and a check scene that proves the answer on screen. Animation is the last and most replaceable part, so this skill is tool-neutral. Manim, Remotion, Motion Canvas, After Effects, or a slide renderer all qualify if they take the same board in and pass the same checks out.

Scope boundary: for a chart driven by a dataset, use the data animation skill. For writing a proof as text, use the proof writing skill. This skill is for a single worked problem taught on video, or a series of them, one problem per video.

Workflow

1. Pick one problem and solve it cold. One problem per video. Solve it on paper first, without designing any visuals. If the problem needs more than about six solve steps at this audience level, pick a smaller problem or split the set. Record the givens, the unknown, and the answer.
2. Design the steps by problem type. Read references/step-design.md and follow the pattern for algebra, geometry, or word problems. Every design uses the same five phases from Polya, How to Solve It (1945): understand, plan, solve, answer, check. One operation or one construction per solve step. The check step substitutes back into the original problem, never into a simplified later step.
3. Verify the math before storyboarding. Encode the solution as JSON and run python3 scripts/verify_solution.py assets/<problem>-solution.json (copy an asset file and edit it). It covers single-variable equations with their step lists, arithmetic chains, Pythagoras, triangle angle sums, and sum checks. Every step must hold at the claimed value. For types it does not cover, design an on-screen check by substitution or a second method and write that check into the board. No designable check, no video.
4. Storyboard the reveal. Write the board in the JSON shape of the asset storyboards: scenes with id, phase, visual, narration, on_screen, hold_after_seconds, in phase order. Follow references/narration-and-boards.md: narration says each equation in words the first time it appears, labels sit next to the parts they name, one highlight color means the thing changing now, no paragraph of text sits under narration. Budget narration at 130 words per minute plus holds.
5. Check the board. Run python3 scripts/plan_check.py assets/<problem>-storyboard.json. It fails boards with missing or out-of-order phases, duplicate ids, and solve scenes with no visible step, and warns on scenes over 45 narration words, heavy on-screen text, and powers or roots the narration never says in words. Fix fails. Fix warnings or note why they stand.
6. Animate from the board, scene by scene. Any renderer. In Manim terms that means one Scene class per video, all animation inside construct(), steps revealed with play() and held with wait() for the board's hold times. In other tools the mapping is the same: one timeline segment per board scene, reveal, hold, next. Keep a manifest or a render log that maps each scene id to its time range in the output, so pass 2 of the accuracy check can find each step.
7. Record and sync the narration. Record from the board's narration text, not from memory of it. Place each line so the named change happens as it is spoken. Master the audio with ffmpeg loudnorm, two-pass where the tooling allows, targeting about -14 LUFS integrated and true peak at or below -1 dBTP for YouTube delivery, and pin the output sample rate to 48000.
8. Run the rendered-video accuracy pass. Follow references/accuracy-check.md pass 2: pause on every solve scene and compare the frame character by character against the board, confirm each step sits still for its hold, listen once without watching, watch once muted with captions, and inspect the final frame as a still.
9. Finish the accessibility set. Human-correct the captions (auto captions corrupt numbers and math terms), confirm the narration states every visual given the lesson depends on, and export the transcript with equations in plain text plus a still of the final board.

Output Contract

• One MP4 per problem: H.264, yuv420p, even dimensions, with the title stating the problem type and the exact problem.
• The storyboard JSON and the solution JSON that produced it, with plan_check and verify_solution both ending in PASS.
• Five phases present in order: understand, plan, solve, answer, check. The check scene verifies against the original problem on screen.
• Narration that says every equation in words on first appearance, estimated at 130 words per minute plus stated holds, and captions that are human-corrected.
• A final frame that works as a still: the solved problem, the answer with its unit where it has one, and the check result.
• A transcript with equations in plain text, delivered next to the video.

Operating Rules

1. Accuracy before motion. Every number, sign, and symbol on screen traces to the verified solution JSON. Unverifiable means cut, never smoothed over with confident narration.
2. One change per reveal. Two operations in one cut is where viewers get lost and where sign errors hide. Split the scene instead.
3. The check is part of the video, not an optional extra. A video that ends on the answer teaches answer-getting. The check scene teaches whether an answer is right, and it is the public receipt that this one was verified.
4. Narration and visuals land together. If the voice names a term before it appears or after it leaves, fix the timing or the line. Never leave the viewer reading a step the voice has already moved past.
5. Tool neutrality is real. Do not rebuild a working pipeline around a new renderer mid-series. Change tools between series, and only if the new tool still emits scene timings for the accuracy pass.
6. Sample problems in assets/ are worked test problems with known answers: 2x + 6 = 20 gives x = 7, a 6-8 right triangle gives hypotenuse 10, two consecutive integers summing to 23 are 11 and 12. Use them to test the pipeline, never present them as anything else.
7. Test before shipping. Verified 2026-10-21 in this environment: both scripts compile under Python 3.12, all three asset solutions pass verify_solution (5/5, 2/2, and 6/6 checks), all three asset storyboards pass plan_check with no warnings after one narration fix, a wrong claimed value of 6 for the algebra problem fails verify_solution with residuals named, and a board missing four phases fails plan_check.