manim-storyboard

See every animation in a Manim scene as one labelled contact sheet, and check it against a storyboard you wrote.

^{The first 18 steps of a 97 step scene. Cyan is what rendered, amber is what you said it should do.}

Why

Manim tells you a scene rendered. It does not tell you the chapter title ran off the right edge, or that a banner landed on top of the text underneath it. Those are only visible by looking, and looking means scrubbing an mp4 or guessing timestamps to pull stills from.

Guessing wastes a lot of samples. A fade between two sections is a black frame, and roughly a quarter of hand picked timestamps land in one.

There is a better source. Manim writes one clip per self.play() call into partial_movie_files/ and lists them in order. Take the last frame of each and you get one settled frame per animation, in order, with nothing wasted. That is the whole idea here.

Install

pip install manim-storyboard

Needs ffmpeg on PATH, or FFMPEG_EXECUTABLE and FFPROBE_EXECUTABLE pointing at the binaries. That is the same convention manim-mcp-server uses, so an existing setup already works.

Use

One sheet for a whole scene:

manim-storyboard sheet scene.py MyScene

97 panels -> storyboard_MyScene.png

Each panel carries the index, its start time in the final video, its duration, and the animation classes that actually ran:

#012   0:08.5   1.33s
LaggedStart[Write, FadeIn x2]

Groups get expanded one level, so you can see what is inside a LaggedStart without opening the file. self.wait() gets its own panel, because manim renders it as its own clip.

Big scenes page:

manim-storyboard sheet scene.py MyScene --range 1-40 --columns 6

Already rendered through the manim CLI and just want the sheet:

manim-storyboard sheet scene.py --from-media media/videos/scene/480p15/partial_movie_files/MyScene

Try it

examples/ has a small scene with no LaTeX and no assets, plus a finished storyboard for it:

manim-storyboard sheet examples/demo_scene.py DemoScene -s examples/storyboard.yaml
manim-storyboard check examples/demo_scene.py DemoScene -s examples/storyboard.yaml

Storyboarding

A storyboard is a YAML file saying what each step is supposed to do. Write it by hand before the scene exists, or scaffold it from a render:

manim-storyboard plan scene.py MyScene            # scaffold from what rendered
manim-storyboard plan scene.py MyScene --blank 40 # 40 empty steps to fill in

scene: LarpGuide
steps:
  - at: 1
    section: cold open
    intent: the overheard question fades up on an empty frame
    expect: [FadeIn]
  - at: 7
    intent: the title writes on, RENT-A-GIRLFRIEND FAN
    expect: [Write]
  - at: 9
    intent: pink flash pops on the word FAN
    expect: [Flash]
  - at: 11
    intent: clear everything before chapter one
    expect: [FadeOut]

intent is prose for you. expect is the animation type you mean to use at that step, and it is what gets verified:

manim-storyboard check scene.py MyScene -s storyboard.yaml

step 7: [drift] expected FadeIn but rendered Write
step 9: [drift] expected Circumscribe but rendered Flash
step 400: [missing] plan has step 400 but the render stopped at 97

Feed the storyboard back into sheet and every panel gets its intent printed underneath, with drifted steps outlined in red:

manim-storyboard sheet scene.py MyScene -s storyboard.yaml

Rules worth knowing

Counts are opt-in. expect: [FadeOut] means "this step fades things out" and passes for any number of them. A helper that clears the stage fades however many mobjects happen to be on it, and you should not have to update the plan every time you add one. When the exact count is the point, write expect: [FadeOut x6] and the comparison becomes strict and order sensitive.

Partial plans are fine. Only steps declaring expect are checked. A plan can cover the opening and say nothing about the rest. Pass --strict to also flag rendered steps the plan never mentions.

Prose-only plans never fail. Steps with intent and no expect are labels for the sheet, not assertions.

Group contents are ignored. expect: [LaggedStart] is satisfied by LaggedStart[Write, FadeIn x2]. Match the wrapper, not its children.

MCP

The same three tools over MCP, so an agent writing Manim can look at its own output:

pip install "manim-storyboard[mcp]"
python -m manim_storyboard.mcp_server

{
  "mcpServers": {
    "manim-storyboard": {
      "command": "python",
      "args": ["-m", "manim_storyboard.mcp_server"],
      "env": {
        "FFMPEG_EXECUTABLE": "C:\\ffmpeg\\bin\\ffmpeg.exe",
        "FFPROBE_EXECUTABLE": "C:\\ffmpeg\\bin\\ffprobe.exe"
      }
    }
  }
}

Exposes storyboard_sheet, storyboard_plan, storyboard_check and storyboard_from_media. To bolt them onto a manim MCP server you already run:

from manim_storyboard.mcp_server import register
register(my_fastmcp_instance)

Python

from pathlib import Path
from manim_storyboard import record, build, load, check

take = record(Path("scene.py"), "MyScene", quality="low_quality")
plan = load(Path("storyboard.yaml"))

for issue in check(plan, take.steps):
    print(issue.index, issue.kind, issue.message)

build(take.steps, Path("sheet.png"), columns=6, plan=plan)

record() wraps Scene.play for the duration of one render, so the manifest lines up with the clips on disk exactly. It restores the original method afterwards, including when the render raises.

Development

pip install -e ".[dev]"
pytest

The plan matching tests need neither manim nor ffmpeg.

License

MIT