manim-storyboard

Sehen Sie jede Animation in einer Manim-Szene als ein beschriftetes Kontaktblatt und vergleichen Sie es mit einem von Ihnen geschriebenen Storyboard.

Die ersten 18 Schritte einer 97-Schritte-Szene. Cyan zeigt, was gerendert wurde, Bernstein zeigt, was es tun sollte.

Warum

Manim sagt Ihnen, dass eine Szene gerendert wurde. Es sagt Ihnen nicht, dass der Kapiteltitel über den rechten Rand hinausläuft oder dass ein Banner auf dem darunterliegenden Text gelandet ist. Das ist nur durch Hinsehen sichtbar, und Hinsehen bedeutet, ein mp4 zu durchsuchen oder Zeitstempel zu erraten, um Standbilder zu extrahieren.

Raten verschwendet viele Stichproben. Ein Überblendung zwischen zwei Abschnitten ist ein schwarzer Frame, und etwa ein Viertel der manuell ausgewählten Zeitstempel landet in einem.

Es gibt eine bessere Quelle. Manim schreibt einen Clip pro self.play()-Aufruf in partial_movie_files/ und listet sie in der Reihenfolge auf. Nimmt man den letzten Frame von jedem, erhält man einen stabilen Frame pro Animation, in der Reihenfolge, ohne Verschwendung. Das ist die ganze Idee hier.

Installation

pip install manim-storyboard

Benötigt ffmpeg im PATH, oder FFMPEG_EXECUTABLE und FFPROBE_EXECUTABLE, die auf die Binärdateien verweisen. Das ist die gleiche Konvention, die manim-mcp-server verwendet, also funktioniert eine bestehende Einrichtung bereits.

Verwendung

Ein Blatt für eine ganze Szene:

manim-storyboard sheet scene.py MyScene

97 panels -> storyboard_MyScene.png

Jedes Panel trägt den Index, seine Startzeit im endgültigen Video, seine Dauer und die tatsächlich ausgeführten Animationsklassen:

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

Gruppen werden eine Ebene erweitert, sodass Sie sehen können, was sich in einem LaggedStart befindet, ohne die Datei öffnen zu müssen. self.wait() erhält ein eigenes Panel, da manim es als eigenen Clip rendert.

Große Szenen seitenweise:

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

Bereits über die manim CLI gerendert und möchten nur das Blatt:

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

Ausprobieren

examples/ enthält eine kleine Szene ohne LaTeX und ohne Assets, plus ein fertiges Storyboard dafür:

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

Storyboard-Erstellung

Ein Storyboard ist eine YAML-Datei, die angibt, was jeder Schritt tun soll. Schreiben Sie es von Hand, bevor die Szene existiert, oder erstellen Sie es aus einem 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 ist Prosa für Sie. expect ist der Animationstyp, den Sie in diesem Schritt verwenden möchten, und das wird überprüft:

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

Füttern Sie das Storyboard zurück in sheet und jedes Panel erhält seine Absicht darunter gedruckt, mit abweichenden Schritten rot umrandet:

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

Wissenswerte Regeln

Anzahlen sind optional. expect: [FadeOut] bedeutet "dieser Schritt blendet Dinge aus" und gilt für jede Anzahl. Ein Helfer, der die Bühne räumt, blendet so viele Mobjects aus, wie gerade darauf sind, und Sie sollten den Plan nicht jedes Mal aktualisieren müssen, wenn Sie eines hinzufügen. Wenn die genaue Anzahl entscheidend ist, schreiben Sie expect: [FadeOut x6] und der Vergleich wird streng und reihenfolgeabhängig.

Teilpläne sind in Ordnung. Nur Schritte, die expect deklarieren, werden überprüft. Ein Plan kann die Eröffnung abdecken und nichts über den Rest sagen. Übergeben Sie --strict, um auch gerenderte Schritte zu markieren, die der Plan nie erwähnt.

Nur-Prosa-Pläne schlagen nie fehl. Schritte mit intent und ohne expect sind Beschriftungen für das Blatt, keine Behauptungen.

Gruppeninhalte werden ignoriert. expect: [LaggedStart] wird durch LaggedStart[Write, FadeIn x2] erfüllt. Passen Sie den Wrapper an, nicht seine Kinder.

MCP

Die gleichen drei Werkzeuge über MCP, damit ein Agent, der Manim schreibt, seine eigene Ausgabe betrachten kann:

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

Stellt storyboard_sheet, storyboard_plan, storyboard_check und storyboard_from_media bereit. Um sie an einen bereits laufenden manim MCP Server anzuhängen:

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() umschließt Scene.play für die Dauer eines Renderings, sodass das Manifest genau mit den Clips auf der Festplatte übereinstimmt. Es stellt die ursprüngliche Methode danach wieder her, auch wenn das Rendering einen Fehler auslöst.

Entwicklung

pip install -e ".[dev]"
pytest

Die Planabgleichstests benötigen weder manim noch ffmpeg.

Lizenz

MIT