# manim-storyboard

See every animation in a [Manim](https://www.manim.community/) scene as one labelled contact sheet, and check it against a storyboard you wrote.

![Contact sheet with intents](examples/storyboard_with_plan.png)

<sup>The first 18 steps of a 97 step scene. Cyan is what rendered, amber is what you said it should do.</sup>

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

```bash
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](https://github.com/abhiemj/manim-mcp-server) uses, so an existing setup already works.

## Use

One sheet for a whole scene:

```bash
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:

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

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

```bash
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:

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

![Demo contact sheet](examples/demo_sheet.png)

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

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

```yaml
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:

```bash
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:

```bash
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](https://modelcontextprotocol.io), so an agent writing Manim can look at its own output:

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

```json
{
  "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:

```python
from manim_storyboard.mcp_server import register
register(my_fastmcp_instance)
```

## Python

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

```bash
pip install -e ".[dev]"
pytest
```

The plan matching tests need neither manim nor ffmpeg.

## License

MIT