3brown1blue 0.3.0

Generate 3Blue1Brown-style Manim explainer videos from topics or slide decks

3brown1blue

Generate 3Blue1Brown-style Manim explainer videos from topics or slide decks, or install the Manim skill into your AI coding tool.

What's new in v0.2.5

Audience-aware generation -- videos now adapt to who's watching:

3brown1blue generate "attention mechanism" -a graduate -d machine-learning -p claude-code
3brown1blue generate "CRISPR" -a high-school -d biology -p anthropic --render
3brown1blue from-slides lecture.pptx -a undergrad -d physics -p claude-code

• --audience / -a: high-school, undergrad (default), graduate, industry -- each level has its own curriculum structure, pacing, vocabulary, and annotation depth
• --domain / -d: machine-learning, mathematics, physics, biology, security, neuroscience, algorithms (or auto) -- domain-specific visual patterns, color semantics, and notation conventions
• Misconception engine: the planner now identifies what the audience wrongly believes and structures the video to show the wrong intuition first, then correct it (based on Muller's research, effect size 0.8)
• Narration scripts: every plan now includes a per-scene narration script matched to audience vocabulary
• 18 production rules (was 10): new rules for text centering, container label safety, dim-vs-fadeout, transition density, arrow spacing, chart legend placement
• 35 domain-specific visual patterns (5 per domain) extending the 22 general patterns
• Automated audit tools: audit_video.sh extracts frames and prints a visual checklist; concat_scenes.sh joins scenes with ffmpeg

Install the skill (recommended)

The primary use: install rule files, templates, and safe wrappers into your AI tool so it generates production-quality animations.

pip install 3brown1blue
3brown1blue install

Supports: Claude Code, Cursor, Windsurf, GitHub Copilot

Then just ask your AI: "make a video explaining backpropagation" -- the skill handles layout templates, production rules, visual design principles, and common gotchas automatically.

Generate from a topic

Two-step pipeline: plans the video first (research, misconception analysis, curriculum, scene plans, narration script, style contract), shows you the plan for review, then generates Manim code.

# one-shot with uvx (no permanent install)
uvx '3brown1blue[anthropic]' generate "Fourier transforms" --render

# with Claude Code (no API key needed)
3brown1blue generate "attention mechanism" -p claude-code --render -q h

# audience + domain aware
3brown1blue generate "neural ODEs" -a graduate -d machine-learning -p claude-code
3brown1blue generate "sorting algorithms" -a high-school -d algorithms -p anthropic --render

# save the reviewed plan so you can generate voiceover later
3brown1blue generate "attention mechanism" -p claude-code --plan-output attention_plan.md

Quick single-scene mode

Skip the planning step and generate one self-contained scene directly. Great for quick explanations, demos, or testing a concept:

# one scene, default 30s, FULL_CENTER layout
3brown1blue generate "dot product" -1 -p claude-code --render

# custom duration and layout template
3brown1blue generate "softmax function" -1 --duration 20 --template BUILD_UP -p claude-code

# with audience and domain
3brown1blue generate "gradient descent" -1 -a undergrad -d machine-learning -p anthropic --render

Flags: -1 / --single-scene, --duration (seconds), --template (layout).

Generate from slides

Extract content from a PowerPoint deck, plan a video, and generate Manim code. Auto-detects whether vision extraction is needed for diagram-heavy slides.

pip install '3brown1blue[slides]'
3brown1blue from-slides lecture.pptx -p claude-code --render
3brown1blue from-slides research_talk.pptx -a graduate -d neuroscience -p anthropic

Generate voiceover

The narration pipeline now supports two open-source single-speaker backends:

• vibevoice: Microsoft's VibeVoice-Realtime with prompt-based speaker packs
• kokoro: Kokoro-82M with a larger built-in voice inventory and speed control

VibeVoice-Realtime

Install VibeVoice separately in the same environment:

git clone https://github.com/microsoft/VibeVoice.git
cd VibeVoice
pip install -e .[streamingtts]

Then save a video plan and turn its ## Narration Script into per-scene WAVs:

3brown1blue generate "backpropagation" -p claude-code --plan-output backprop_plan.md

3brown1blue voiceover backprop_plan.md \
  --backend vibevoice \
  --voices-dir /path/to/VibeVoice/demo/voices/streaming_model \
  --speaker-name Carter \
  --output-dir backprop_voice

# mux the generated WAVs onto rendered scene videos
3brown1blue compose-voiceover videos/backprop_project \
  --audio-dir backprop_voice \
  --quality l

You can also point voiceover at a project directory. It will first look for # NARRATION: comments in scene_*.py, then fall back to narration.md, plan.md, video_plan.md, or storyboard.md. In auto mode, project comments are preferred because they can be grouped into timed beat audio that aligns better with self.play() blocks during compose-voiceover.

To explore more English speaker styles, download the experimental voice packs:

bash /path/to/VibeVoice/demo/download_experimental_voices.sh
3brown1blue voiceover my_project --backend vibevoice --voices-dir /path/to/VibeVoice/demo/voices/streaming_model --list-voices

Kokoro

Kokoro works best from a dedicated Python 3.11 runtime so it does not disturb the main project environment:

python3.11 -m venv .tts311
./.tts311/bin/pip install 'kokoro>=0.9.4' 'misaki[en]' soundfile

Then generate narration with a built-in voice or a voice mix:

3brown1blue voiceover videos/backprop_project \
  --backend kokoro \
  --kokoro-python .tts311/bin/python \
  --speaker-name af_bella,af_sarah \
  --speech-speed 1.2 \
  --output-dir voiceover_audio_kokoro

3brown1blue voiceover videos/backprop_project --backend kokoro --list-voices

Audience levels

Level	Assumes	Curriculum	Scenes	Style
high-school	Algebra, curiosity	Concrete example first, generalize, real world	5-7	Metaphor-heavy, generous pacing
undergrad	Calculus, linear algebra, intro field	Hook, background, method, results, takeaway	8-10	Balance of intuition and formalism
graduate	Deep field knowledge	Skip background, start with contribution	10-12	Dense, fast-paced, more equations
industry	Practical focus	Problem, solution, how to adopt	6-8	Applied, demo-oriented, benchmarks

Domain support

Each domain includes a visual vocabulary, preferred layout templates, 5 domain-specific patterns, color semantics, and notation conventions.

Domain	Key patterns
machine-learning	Layer-by-layer build, forward/backward overlay, loss landscape, attention heatmap, training dynamics
mathematics	Geometry-first reveal, dim-and-reveal decomposition, continuous morphing, proof step counter
physics	Phenomenon-first intro, free body diagram build, field line animation, conservation partition
biology	Scale transition zoom, pathway state animation, structure-function annotation
security	Threat model setup, exploit chain, expected-vs-actual, memory layout diagram
neuroscience	Anatomy-first grounding, multi-channel signal trace, imaging modality setup, connectivity matrix
algorithms	Concrete data execution, pseudocode cursor, complexity growth, recursion tree build

Supported providers

Provider	Install extra	Env var	Notes
Claude Code	none	none	Uses claude -p, no API key needed
Anthropic	[anthropic]	ANTHROPIC_API_KEY
OpenAI	[openai]	OPENAI_API_KEY
Google Gemini	[openai]	GOOGLE_API_KEY	OpenAI-compatible API
Groq	[openai]	GROQ_API_KEY	OpenAI-compatible API
Mistral	[openai]	MISTRAL_API_KEY	OpenAI-compatible API

What the skill includes

• 24 rule files: animations, equations, visual design, production quality, 3D, graphs, updaters, troubleshooting, and more
• 4 audience profiles: high-school, undergrad, graduate, industry -- each with curriculum, pacing, and vocabulary rules
• 7 domain rule sets: ML, math, physics, bio, security, neuro, algorithms -- with 35 domain-specific visual patterns
• 3 templates: equation explainer, paper explainer, shared style.py with safe_multiline(), pipeline_arrow(), bottom_note()
• Safe wrappers: drop-in replacements for crash-prone Manim APIs
• 18 production rules: layout, text centering, container safety, lifecycle, transitions, arrow spacing, chart legends
• Misconception engine: plans videos to show wrong intuition before correcting it
• Narration scripts: per-scene scripts generated alongside the video plan
• Audit tools: audit_video.sh for frame extraction + checklist, concat_scenes.sh for joining scenes

CLI reference

3brown1blue generate TOPIC [OPTIONS]
3brown1blue from-slides DECK [OPTIONS]
3brown1blue voiceover SOURCE [OPTIONS]
3brown1blue compose-voiceover PROJECT_DIR [OPTIONS]
3brown1blue install [--platform] [--force]
3brown1blue uninstall [--platform]
3brown1blue update [--platform]
3brown1blue status

Common options for generate/from-slides:

  --provider  -p   claude-code | anthropic | openai | google | groq | mistral
  --audience  -a   high-school | undergrad | graduate | industry  [default: undergrad]
  --domain    -d   auto | machine-learning | mathematics | physics | biology |
                   security | neuroscience | algorithms  [default: auto]
  --model     -m   generation model (provider default if omitted)
  --plan-model     planning model (same as --model if omitted)
  --api-key   -k   API key (or set the provider env var)
  --output    -o   output file  [default: scene.py]
  --plan-output    optional markdown file to save the reviewed plan
  --render         run manim after generation
  --quality   -q   l=fast | m=medium | h=1080p | k=4K  [default: l]

Voiceover options:

  --project-dir -d   project directory for scene-name matching
  --source-mode      auto | scene-comments | plan  [default: auto]
  --backend          vibevoice | kokoro  [default: vibevoice]
  --model-path       VibeVoice-Realtime model id/path
  --speaker-name     voice preset name  [default: Carter]
  --voice-prompt     explicit .pt voice prompt file
  --voices-dir       directory containing VibeVoice voice prompts
  --kokoro-python    Python 3.11 runtime for Kokoro
  --kokoro-lang      Kokoro language code  [default: a]
  --speech-speed     Kokoro speech rate  [default: 1.15]
  --output-dir -o    output directory for wav files
  --device           auto | cuda | mps | cpu  [default: auto]
  --cfg-scale        guidance scale  [default: 1.5]
  --ddpm-steps       diffusion steps  [default: 5]
  --list-voices      list available prompts and exit

Compose voiceover options:

  --audio-dir -a     directory containing per-scene wav files
  --quality -q       l=480p15 | m=720p30 | h=1080p60 | k=2160p60
  --output-dir -o    directory for narrated per-scene mp4 files
  --final-output     optional explicit path for final narrated mp4
  --audio-fit        extend | atempo | hybrid  [default: hybrid]
  --max-atempo       max narration speed-up when fitting audio  [default: 1.35]

Showcase

See generated videos: 3brown1blue-showcase

Prerequisites

pip install manim
# macOS: brew install mactex
# Linux: apt install texlive-full
# Windows: install MiKTeX

License

MIT