manim-craft

name	manim-craft
description	Craft standards for Manim CE animations that teach. Mandatory storyboard → render → look → revise loop, a library of named cinematographic moves, layout and 3D camera recipes, and annotated 3Blue1Brown exemplars. Use whenever writing or reviewing Manim code.

manim-craft

You are writing an animation, not a slideshow. The failure mode this skill exists to prevent: flat shapes plus labels that fade in and out, no camera, no continuity, motion that decorates instead of explains.

You are making the visual half of a narrated piece. A person speaks over this video. That single fact governs two things people get wrong constantly: the narration is spoken, so it must not be printed on screen (hard rule 13); and the visuals must be slow enough for a human to talk over them (hard rule 14). A video that reads like a slideshow with subtitles, racing at 0.2 s per animation, has failed before anyone judges its composition.

Base directory of this skill: the directory containing this file. All relative paths below are relative to it.

The loop (non-negotiable)

0. Know what you are animating before you animate. This skill decides HOW something is shown; it never decides WHAT is worth showing. If you were handed a beat-by-beat script (by a human, or by a pedagogy skill such as professor), execute it: its stage directions say what is visible, its events are what you animate, its narration becomes subcaptions, and its scene split, per-scene space (2D/3D), and persistent anchor visual are given — never rebuild an anchor, morph it. If you were handed only a topic, write that beat list yourself before touching code. A weak explanation animated beautifully is still a weak explanation, and nothing in this skill can fix that.

1. Storyboard first, in words. Before any code, list the beats. One idea per beat. For each beat write down: what is on screen, the single focal point, which Move (see below) carries the transition into it, and why the viewer should care at that moment.

2. Choose the space. If the concept has natural spatial structure — surfaces, terrain, trees, vector fields, gradients, anything with depth — you MUST sketch a 3D treatment and explicitly justify 2D if you reject it. "2D is easier to code" is not a justification.

3. Render keyframes before animating. For each beat, build its final composition with self.add(...) and render a still: manim -s -ql file.py SceneName. Read the PNG with your image-reading tool. Score it against the rubric. Fix layout problems now, before any motion exists.

4. Animate, then look. Render with -ql, then run scripts/contact_sheet.sh <video.mp4> and read the sheet image. Check the motion arc across tiles: does each transition read? Is anything popping in/out that should morph? Is the pacing monotone? Three or more near-identical consecutive tiles need judging against the .srt: if narration is playing over them, that is a hold — correct and necessary, the viewer is listening while looking at the finished picture. If nothing is being said, it is dead air — cut it or give the beat something to do. A tile showing scenery without its beat's focal point is a dead beat either way. For dark or atmospheric scenes, also run scripts/frame_lint.py <video.mp4> — it flags sustained unreadable-dark stretches that per-frame eyeballing misses. Contact-sheet tiles are too small to certify caption-band integrity: spot-check full-resolution frames at the swap timestamps (scripts/keyframes.sh or ffmpeg -ss). And if a render disagrees with what the code can possibly produce, suspect the segment cache before your code — re-render with --disable_caching (landmines §14).

5. Lint every beat. Add the skill's scripts/ dir to sys.path and call from craft import lint; lint(self, "beat name") at the end of each beat inside construct(). Fix every warning or write down why it is intentional.

6. Check the pacing against the narration. Run python3 scripts/pace_lint.py <SceneName>.srt <SceneName>.mp4. RUSHED means the narrator cannot say that line in the time you left; TOO-DENSE means they never get to breathe. Fix by adding self.wait() and lengthening run_time — never by shortening the narration.

7. Iterate 3–6 until the rubric passes. Never deliver a scene whose rendered frames you have not personally looked at.

The Moves

Named patterns. Refer to them by name in your storyboard.

Move	When	How
Morph-Don't-Fade	A thing becomes another thing	ReplacementTransform, TransformMatchingShapes, FadeTransform — never FadeOut+FadeIn. Identity continuity is how viewers track meaning.
Grid-Warp	A function/transform acts on space itself	NumberPlane → prepare_for_nonlinear_transform() → animate.apply_function(f), generous run_time (3–6 s). See examples/01-grid-warp/.
Establish-Push-In	Start with context, then commit to a subject	MovingCameraScene; self.camera.frame.animate.scale(0.5).move_to(target). Camera motion is narrative intent, never decoration.
Orbit-Reveal	Expose depth / 3D structure	ThreeDScene; sweep theta/phi via move_camera(...) or begin_ambient_camera_rotation(rate=0.1). See examples/03-surface-camera/.
Collapse-Dimension	Connect 3D intuition to 2D formalism	Introduce the concept in 3D, move_camera to an axis-aligned view, crossfade to the flat diagram where the math happens. The single most powerful move for "intuition → formula". Recipe in references/camera-3d.md.
Rack-Focus	Scene is busy, one thing matters now	Dim everything else to 0.2–0.3 opacity (VGroup(*rest).animate.set_opacity(0.25)). Do not remove context — dim it.
Ticker	A quantity changes over time	ValueTracker + one number mobject with an updater (DecimalNumber needs LaTeX; Text-become variant in ce-cheatsheet.md). Never a chain of Transforms of new Text. See examples/02-updaters-continuity/.
Trace-Build	A process unfolds along a path	TracedPath, or Create along the path, with a moving dot as the focal point.

Hard rules

1. Every scene has a title — a short Text (≤ 5 words, a chapter marker not a sentence), top edge, readable throughout the scene (in 3D scenes: fixed-in-frame).

2. One focal point per beat. If you cannot say what it is, the beat is not designed yet.

3. Nothing pops. Everything Creates, Grows, Morphs, or slides with purpose. self.add() mid-scene is for backgrounds only.

4. Contrast: dark background needs bright fills (*_A/*_B color variants, not *_E). Labels ≥ font_size=24. Judge readability on the rendered frame, never in your head.

5. Timing: see hard rule 14 — narration sets the clock. Floors: nothing under 0.4 s except micro-adjustments; every beat ends with a wait; big reveals get 1.5–2.5 s plus a pause. Vary the pace — uniform timing reads as monotone.

6. rate_func with intent: smooth by default, rush_into for falling/dropping, there_and_back for pulses, linear only for ambient motion.

7. Never trust LaTeX. Probe MathTex with a tiny -s render before relying on it; if the pipeline is broken, use Text (see references/landmines.md §4).

8. Read references/landmines.md before writing code. Every item in it is a real bug that actually happened.

9. Study the example matching your scene type (examples/*/NOTES.md + their keyframe PNGs) before writing your own scene. Look at the keyframes — that is what "good" looks like.

10. Caption bands cut, they never crossfade. Swapping title/footer text with simultaneous FadeOut+FadeIn, Transform, or FadeTransform renders garbled double-text (landmines §12). Use the sequential swap or scripts/caption_slot.py. Morph-Don't-Fade is for subjects; caption bands are narration, and narration cuts.

11. Justified 2D is not a static camera. If a beat's STAGE implies a close-up, a scale change, or a reveal, use MovingCameraScene and pin the HUD with scripts/pin_to_frame.py (unpinned HUD vanishes on push-in — landmines §13). Do not downgrade a scripted camera move to opacity dimming.

12. Atmosphere never beats legibility. Fog and darkness must keep the focal point readable at 480p — verify with scripts/frame_lint.py, and never leave a beat on stage without its focal point. Rule of thumb: a deliberately dim beat still needs ≥1% of pixels genuinely bright; a lone title plus one small glow is borderline.

13. Narration is spoken, never printed. The script's narration lines go to self.add_subcaption(text, duration=...), which writes a SceneName.srt sidecar for the voice artist — they must NEVER become Text mobjects on stage. There is no subtitle band. Burning the script into the frame is the single most common way an LLM-made animation announces itself: it forces the viewer to read and listen at once, duplicates the narrator, and eats the frame.

    On-screen text is allowed for exactly four things: the scene title (≤5 words), labels on objects and axes, a named term at the moment it is defined (that's the payoff of picture→name→symbol), and live numbers (tickers, counters, readouts). Everything else is the narrator's job.

    Practical test: if a string is a sentence — has a verb and reads like speech — it is narration; move it to add_subcaption. craft.lint flags any on-screen Text over 6 words as WORDY-TEXT. A caption that survives that test is a label, not a subtitle.

14. Narration sets the clock — the video waits for the speaker. Time every beat by how long its narration takes to say, at 2.5 words/second maximum (150 wpm; slower is usually better for teaching):

    beat seconds ≳ (words in its narration) / 2.5  +  ~1 s of silence to breathe
    

    A 20-word line needs ≥8 s of screen time before pauses — not the 2 s of animation it takes to draw. Make up the difference with real self.wait() calls and longer run_times, not by cramming. Every beat ends with self.wait(); a reveal the viewer must absorb gets self.wait(1.5) or more, held on the finished picture in silence. Aim for ≥15% of each scene unnarrated.

    Verify, don't estimate: python3 scripts/pace_lint.py SceneName.srt SceneName.mp4 reports RUSHED cues, NO-BREATH gaps and TOO-DENSE scenes against the real rendered timings. It must pass before you deliver.

Rubric

Score every keyframe / contact sheet 1–5 on each axis. Any axis ≤ 3 → revise before proceeding. Deliver only when everything is ≥ 4.

• Focal clarity — is it instantly obvious where to look?
• Readability — contrast, sizes, nothing clipped, nothing overlapping.
• Motion meaning — does every animation communicate something, or is it decoration?
• Speakability — could a narrator talk over this at a human pace without rushing, and is the frame free of printed narration?
• Continuity — do objects persist and transform, or do they pop in and out?
• Spatial truth — does the representation live in the space the concept naturally lives in (including 3D when the concept has depth)?

Map

• references/ce-cheatsheet.md — the blessed Manim CE subset: scene types, positioning, animation families, updaters, graphs, timing.
• references/landmines.md — verified failure modes and their fixes. Read first.
• references/camera-3d.md — ThreeDScene recipes: orientation, orbit, ambient rotation, fixed-frame HUD, surfaces, Collapse-Dimension.
• references/layout.md — frame geometry, named regions, spacing standards, text measurement, lint usage.
• examples/01-grid-warp/ — 3b1b OpeningManimExample ported to CE. Moves: Grid-Warp, Morph-Don't-Fade.
• examples/02-updaters-continuity/ — 3b1b UpdatersExample ported to CE. Moves: Ticker; continuity via updaters.
• examples/03-surface-camera/ — 3b1b SurfaceExample ported to CE. Moves: Orbit-Reveal; 3D camera choreography; fixed-frame text.
• scripts/craft.py — layout linter (lint(scene)).
• scripts/contact_sheet.sh — one-image filmstrip of a video.
• scripts/keyframes.sh — N evenly spaced stills from a video.
• scripts/caption_slot.py — flicker-free caption band swaps (CaptionSlot); hard rule 10.
• scripts/pin_to_frame.py — HUD pinning for MovingCameraScene camera moves; hard rule 11.
• scripts/frame_lint.py — rendered-frame readability check (sustained-dark-stretch detector); hard rule 12.
• scripts/pace_lint.py — narration-pacing check against the rendered .srt (RUSHED / NO-BREATH / TOO-DENSE); hard rule 14.