---
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 <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

```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/<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
```

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/<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](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/`.