Manim teaching animations

Use Manim when motion exposes a relationship the learner needs to inspect. A still diagram, runnable example, or source excerpt is the better representation when nothing meaningful changes.

Choose Manim during lesson design when motion teaches a change the learner needs to follow. Give it an animation or voice-animation lesson block with a clear purpose and production brief. Before building it, read skills/lesson-design/references/representation-choices.md for when motion helps and when a still or explanation is clearer.

Start with GNOS context

Treat the animation as a teaching artifact, not a generic explainer. Before writing scene code:

1. Identify the learner's target action (derive, predict, implement, or explain) and the last step supported by evidence. Do not invent a learner record.
2. Load the selected subject reference and one lead teacher. Read the active course only when it sets notation, sequence, or assessment; read the learner snapshot only when an identity and relevant evidence are established. A supporting subject supplies a named bridge, not a second narrator.
3. State the concept ID, prerequisite assumption, and one observable success check in the storyboard notes or adjacent design file. Keep course notation and the teacher's voice consistent with the lesson.
4. Choose one change the learner needs to see: for example, a secant tending to a tangent, a basis transforming, a force changing motion, or an algorithm changing state. Predict → show → explain → vary is useful when it serves the target, but is not a universal script.

Write the storyboard before scene code. Each scene needs a concept target, exact narration, visible objects, and the change each cue reveals. Use templates/storyboard_schema.json; validate IDs and cues before spending time on narration. Its duration is authored timing for a silent preview. Spoken durations come from measured clips or local recordings.

Narration and timing

Read references/02_voiceover_synchronization.md. scripts/cue_player.py is the timeline boundary: construct it with the scene, manifest path, and scene ID; call play(cue_id, *animations, run_time=...) once per cue; call finish(output_prefix) after all cues. It attaches each local clip at the current scene time, fills unused cue duration with a wait, applies pause_after, and exports actual cue starts to SRT, WebVTT, and timing JSON. Do not reuse a cue or leave one unplayed. An animation must fit inside its cue.

Use the project's .venv/bin/python for the commands below when that environment is present. Check it before assuming packages missing from the system Python are unavailable. For a fresh environment, install this skill's requirements.txt there. Check dependencies without network calls:

python3 skills/manim-voice-animation/scripts/setup_env.py

Narration generation uses an external provider only when explicitly requested:

python3 skills/manim-voice-animation/scripts/voice_synthesizer.py \
  --storyboard path/to/storyboard.json --out output/topic/audio

--silent creates an honest preview manifest with authored durations and no speech. --audio-dir <folder> uses measured local files named SceneID_cue-id.mp3. Never call silence generated speech, send learner records to a voice provider, or hide a provider failure. Do not mux again after cue-timed audio is already in the scene.

Render and review the artifact

python3 skills/manim-voice-animation/scripts/linter.py scene.py
python3 skills/manim-voice-animation/scripts/render_pipeline.py \
  render scene.py MyScene -q l -o output/preview.mp4

Review the first frame, every conceptual transition, and the ending at actual playback size. Check that each spoken term points to the corresponding object, numbers agree with displayed equations and simulation state, labels stay in frame, and no updater remains attached after its section. For the final render, listen from beginning to end and check that every narration cue is present, audible, and aligned with its visual action. A silent render verifies choreography only; keep it draft, even if the video itself renders correctly. Use a higher quality only after the low-quality preview is correct.

Register the artifact

The viewer page shows the topic's manim chip as ready only after the video is registered. First render with real recorded or synthesized narration attached to the scene timeline, or mux a whole track made for the exact visual sequence. Review the resulting MP4 with sound. Copy that voiced render into the course workspace, then register it. In the example, output/voiced.mp4 means your actual final render; the preview command above does not create that filename automatically:

cp output/voiced.mp4 learners/<learner>/courses/<course-id>/artifacts/videos/<slug>.mp4
python3 skills/course-design/scripts/manage_artifact.py --learners-root learners \
  register <learner-id> <course-id> --file artifact.json

Register the exported .vtt as a ready text/vtt companion artifact and the transcript as a separate ready text artifact. Set the video's metadata.captions and metadata.transcript to their registered artifact IDs. Check captions in the native player and open the transcript after rendering.

The artifact file uses type: voice-animation, mime_type: video/mp4, the topic's lesson_id, and status: ready. Registration checks that a ready voice-animation or animation is a local MP4 with a video stream and a decodable audio stream; a silent preview or invalid file is rejected. This mechanical check cannot establish that the audio is narration, so the listening review above is still required. Keep silent previews and unfinished renders as draft or failed with an honest note. Then re-render the page:

python3 skills/course-viewer/scripts/render_viewer.py learners/<learner>/courses/<course-id>

Visual judgment

Keep the compared quantity visible and use a stable camera unless movement reveals structure. Prefer ValueTracker, DecimalNumber, and lightweight updaters over rebuilding MathTex or other expensive objects every frame. Tie displayed values to the same state as the geometry. Grids, halos, particles, and camera motion are optional signals; remove them when they compete with the concept. Check bounds against the chosen aspect ratio and clear updaters when objects leave the scene.

Read only the reference for the chosen scene:

• Storyboard
• Proofs and calculus
• Linear algebra
• Mechanics and fields
• Algorithms
• 3D camera
• Common failures
• Optional visual components

The five subject templates are starting points, not verified lessons for every input. Start from the subject templates in templates/.