MotionGram 📽️

The grammar of motion graphics.

Lightweight motion graphics for explainers and teaching clips: Typst math → SVG, Skia rasterization, PyAV MP4 export, optional Kitten TTS narration. Scene APIs favor explicit timelines and small composable primitives— approachable for humans and for LLM-assisted authoring.

Install and import as motiongram (pip install -e ".[dev]" from this repo).

Installing [tts] may pull a large dependency tree (for example PyTorch and friends) as required by upstream kittentts 0.8.x — keep it optional. Core animation deps stay separate.

Status: pre-alpha — core rendering pipeline (Skia + Typst + PyAV) is functional; see docs/ for requirements and design.

Tutorial: step-by-step build from ASCII to PyAV-oriented design in learn/ (phases 000–100).

Demo

Short reel rendered from examples/showcase_intro.py (720p). The same file is committed as docs/assets/readme-demo.mp4 so it shows up on GitHub without relying on external hosting.

Regenerate locally:

motiongram render examples/showcase_intro.py -o docs/assets/readme-demo.mp4

Running python examples/showcase_intro.py writes showcase_intro.mp4 in the current working directory; move or rename it if you are refreshing the committed demo.

If the preview does not load (some viewers block autoplay), open docs/assets/readme-demo.mp4 directly.

Quick start

# Install (requires Python 3.11+)
uv pip install -e ".[dev]"

# Install Typst CLI for math rendering
curl -fsSL https://github.com/typst/typst/releases/latest/download/typst-x86_64-unknown-linux-musl.tar.xz \
  | tar -xJ --strip-components=1 -C ~/.local/bin/

# Polished 720p showcase (recommended)
motiongram render examples/showcase_intro.py -o showcase.mp4

# Full-stack demo (text + math + code + circle)
motiongram render examples/math_and_text.py -o output.mp4

# Or run directly
python examples/showcase_intro.py
python examples/math_and_text.py

See the Setup Guide for platform-specific instructions.

YAML scenes

Declarative manifests drive the same Node classes and timeline animators as Python scenes — useful for lectures, LLM-authored content, and non-programmers.

# Deep-learning showcase (port of examples/deeplearning_showcase.py)
motiongram render examples/yaml/deeplearning_showcase.yaml -o showcase.mp4

# Lecture with sections, recipes, and auto section titles
motiongram render examples/yaml/weight_decay_lecture.yaml -o weight_decay.mp4

# Live side-by-side preview while editing (VS Code / browser)
motiongram preview examples/yaml/deeplearning_showcase.yaml --video-on-save

Full field reference: YAML schema (SCHEMA.md). For live editing, see the Live Preview Guide. Python scenes remain the escape hatch for custom logic; YAML covers composition, elements, animations, sections, and recipes like ForwardPass.

Principles gallery

Twelve drawing and twelve animation principle demos live under examples/principles/. Each script writes an MP4 next to itself (those outputs stay gitignored).

python examples/principles/04_value.py

Index and topics: Principles examples guide.

Documentation

• YAML schema (SCHEMA.md) — declarative scene manifests
• Setup Guide — installing skia-python and Typst
• Live Preview Guide — YAML side-by-side editing in VS Code
• Math Rendering Guide — using Typst for math
• Principles examples — examples/principles/ gallery
• Learn path (phases 000–100)
• Proposal
• Roadmap
• Software Requirements Specification (SRS)
• Software Design Document (SDD)
• Architecture
• Public API sketch

License

MIT — see LICENSE.

Author

Nabin Oli