--- name: manim-voice-animation description: Make Manim teaching animations with narration and subtitles when motion helps a concept. --- # 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](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 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: ```bash python3 skills/manim-voice-animation/scripts/setup_env.py ``` Narration generation uses an external provider only when explicitly requested: ```bash 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 ` 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 ```bash 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: ```bash cp output/voiced.mp4 learners//courses//artifacts/videos/.mp4 python3 skills/course-design/scripts/manage_artifact.py --learners-root learners \ register --file artifact.json ``` 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: ```bash python3 skills/course-viewer/scripts/render_viewer.py learners//courses/ ``` ## 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](references/01_pedagogical_storyboard.md) - [Proofs and calculus](references/03_math_proofs_calculus.md) - [Linear algebra](references/04_linear_algebra_matrices.md) - [Mechanics and fields](references/05_physics_mechanics_fields.md) - [Algorithms](references/06_cs_algorithms_graphs.md) - [3D camera](references/07_3d_surfaces_camera.md) - [Common failures](references/08_anti_patterns_curated_fixes.md) - [Optional visual components](references/09_cinematic_depth_and_illustrations.md) The five subject templates are starting points, not verified lessons for every input. Start from the subject templates in `templates/`.