manim-storyboard

Ve cada animación en una escena de Manim como una hoja de contactos etiquetada, y compárala con un storyboard que hayas escrito.

Los primeros 18 pasos de una escena de 97 pasos. Cian es lo que se renderizó, ámbar es lo que dijiste que debería hacer.

Por qué

Manim te dice que una escena se renderizó. No te dice que el título del capítulo se salió del borde derecho, o que un banner cayó encima del texto que estaba debajo. Eso solo se ve mirando, y mirar significa rebobinar un mp4 o adivinar marcas de tiempo para extraer fotogramas.

Adivinar desperdicia muchas muestras. Un fundido entre dos secciones es un fotograma negro, y aproximadamente una cuarta parte de las marcas de tiempo elegidas a mano caen en uno.

Hay una fuente mejor. Manim escribe un clip por cada llamada self.play() en partial_movie_files/ y los lista en orden. Toma el último fotograma de cada uno y obtienes un fotograma estable por animación, en orden, sin desperdiciar nada. Esa es toda la idea.

Instalar

pip install manim-storyboard

Necesita ffmpeg en PATH, o FFMPEG_EXECUTABLE y FFPROBE_EXECUTABLE apuntando a los binarios. Es la misma convención que usa manim-mcp-server, así que una configuración existente ya funciona.

Usar

Una hoja para una escena completa:

manim-storyboard sheet scene.py MyScene

97 panels -> storyboard_MyScene.png

Cada panel lleva el índice, su tiempo de inicio en el video final, su duración y las clases de animación que realmente se ejecutaron:

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

Los grupos se expanden un nivel, para que puedas ver lo que hay dentro de un LaggedStart sin abrir el archivo. self.wait() tiene su propio panel, porque manim lo renderiza como su propio clip.

Escenas grandes paginadas:

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

Ya renderizado a través de la CLI de manim y solo quieres la hoja:

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

Pruébalo

examples/ tiene una escena pequeña sin LaTeX ni assets, más un storyboard terminado para ella:

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

Un storyboard es un archivo YAML que dice lo que se supone que debe hacer cada paso. Escríbelo a mano antes de que exista la escena, o crea un esqueleto a partir de un 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 es prosa para ti. expect es el tipo de animación que pretendes usar en ese paso, y es lo que se verifica:

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

Alimenta el storyboard de nuevo a sheet y cada panel recibe su intención impresa debajo, con los pasos desviados resaltados en rojo:

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

Reglas que vale la pena conocer

Los conteos son optativos. expect: [FadeOut] significa "este paso desvanece cosas" y funciona para cualquier número de ellas. Un ayudante que limpia el escenario desvanece tantos mobjects como haya en él, y no deberías tener que actualizar el plan cada vez que añades uno. Cuando el conteo exacto es el punto, escribe expect: [FadeOut x6] y la comparación se vuelve estricta y sensible al orden.

Los planes parciales están bien. Solo se verifican los pasos que declaran expect. Un plan puede cubrir la apertura y no decir nada sobre el resto. Usa --strict para también marcar los pasos renderizados que el plan nunca menciona.

Los planes solo de prosa nunca fallan. Los pasos con intent y sin expect son etiquetas para la hoja, no afirmaciones.

Los contenidos de los grupos se ignoran. expect: [LaggedStart] se satisface con LaggedStart[Write, FadeIn x2]. Coincide con el envoltorio, no con sus hijos.

MCP

Las mismas tres herramientas a través de MCP, para que un agente que escribe Manim pueda ver su propia salida:

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

Expone storyboard_sheet, storyboard_plan, storyboard_check y storyboard_from_media. Para conectarlas a un servidor MCP de manim que ya ejecutes:

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() envuelve Scene.play durante la duración de un render, para que el manifiesto coincida exactamente con los clips en disco. Restaura el método original después, incluso si el render lanza una excepción.

Desarrollo

pip install -e ".[dev]"
pytest

Las pruebas de coincidencia de planes no necesitan ni manim ni ffmpeg.

Licencia

MIT