How 3b1b/videos works
1. This repository is a content factory for 3Blue1Brown videos, not a single app. The primary runtime is Python code that defines Manim scenes, which are rendered into animations by manimgl/Manim GL. Most top-level directories are organized by year (_2015 through _2026), and each year contains self-contained video/article projects.
2. The main architectural boundary is between shared animation infrastructure and per-video scene code. Shared infrastructure lives in custom/, once_useful_constructs/, manim_imports_ext.py, and a few utility modules. Year/project folders import from these helpers and define the actual scenes, story beats, and visuals for individual videos.
3. custom/ is the core reusable layer specific to this repo. It contains the bespoke 3Blue1Brown characters, banners, opening/end screens, backdrops, logo assets, and animation helpers. This layer sits on top of Manim and encapsulates the channel’s visual style, so many scene files depend on it indirectly.
4. once_useful_constructs/ is a second reusable layer of general-purpose scene patterns and math-visualization helpers. It includes graph, vector-space, combinatorics, fractal, region, and matrix-multiplication helpers, plus some GLSL snippets. These modules are used across many projects to avoid reimplementing common animation patterns.
5. manim_imports_ext.py acts as the central import bridge. Scene files typically rely on it to pull in Manim primitives, custom classes, and shared utilities in one place. This file is the key integration point that makes the many per-project scene files feel like they belong to one ecosystem.
6. The yearly folders are mostly collections of scene modules grouped by topic or video series. Examples include _2016/eola for linear algebra chapters, _2018/eop for probability, _2019/diffyq for differential equations, _2022/wordle for the Wordle analysis series, and _2024/transformers for the transformer explainer. Many of these folders also have internal submodules for chapters, supplements, staging scenes, and reusable constructs specific to that series.
7. A lot of projects are split into “main narrative scenes” and “supporting scenes.” The narrative files encode the canonical progression of a video, while files named supplements, footnote, staging, intro, chapterX, or all_*_scenes provide helpers, side explanations, scene registries, or alternate render entry points. This suggests a rendering model where one project can produce many standalone scenes, plus reusable fragments.
8. Some projects include data files and precomputed results that feed the animations. Examples include Wordle word lists and simulation outputs, domino datasets, MNIST-related assets, and precomputed weights/biases for neural-network demos. The data flow is usually: static text/JSON/image assets are loaded by Python scene code, transformed into mathematical/graphical objects, and then rendered by Manim.
9. There are several specialized subdomains that deserve separate diagram boxes because they have their own internal mini-ecosystems. Notable examples are _2017/nn for neural-network visuals, _2023/optics_puzzles for wave/optics scenes, _2024/transformers for attention and generation, and _2025/grover for quantum-computing scenes. These subtrees often define both domain logic and scene presentation code together.
10. outside_videos/ holds independent or commissioned pieces that are not part of the main annual series but still use the same rendering stack and shared assets. This folder includes banners, podcast/talk visuals, tweet-sized animations, merch/promo assets, and other one-off content. Architecturally, it behaves like another content client of the same scene framework.
11. stage_scenes.py and the sublime_custom_commands/ folder support the authoring workflow rather than the rendered output. The repo is built around an interactive Manim development loop: open a scene at a line number, paste checkpoints, and re-render selectively. These tools matter because they explain why scene files are often structured as many small classes and checkpoints instead of one monolithic script.
12. The repository is tied to an older Manim variant (3b1b/manim, invoked as manimgl), and some older projects may not run unchanged on newer Manim Community Edition versions. That version dependency is an important architectural constraint because it affects import patterns, available scene helpers, shader usage, and rendering behavior.
13. Overall, the architecture is “shared animation toolkit + year/topic-specific scene packages + asset/data folders + editor-driven render workflow.” If you draw it, the main arrows should go from Manim/runtime into shared custom helpers, then from those helpers into the year/topic modules, with static datasets and media assets feeding individual scenes as inputs.
Main entry points: manim_imports_ext.py Import bridge · custom Custom layer · once_useful_constructs Reusable constructs · transformers Transformers
Components 16
Core runtime
Shared Manim bridge and repo-specific animation infrastructure.
- Manim GL · Older 3Blue1Brown Manim runtime used to render scenes.
- Import bridge · Central module that gathers Manim primitives and repo helpers for scene files.
manim_imports_ext.py - Custom layer · Repo-specific visuals, characters, banners, and animation helpers.
custom - Reusable constructs · General-purpose scene patterns and math-visualization utilities reused across series.
once_useful_constructs
Video series
Major annual or topic-based content packages.
- EoLA · Chapter-based linear algebra video package.
_2016/eola - Neural nets · Neural-network explainer scenes, loaders, and pretrained weights.
_2017/nn - EoP · Probability chapter scenes plus reusable probability-specific constructs.
_2018/eop - DiffyQ · Multi-part differential equations series with staging and shared constructs.
_2019/diffyq - Wordle · Wordle analysis scenes driven by word lists and simulation outputs.
_2022/wordle - Optics puzzles · Specialized wave and optics mini-ecosystem.
_2023/optics_puzzles - Transformers · Transformer explainer spanning embeddings, attention, generation, and helpers.
_2024/transformers - Grover · Quantum-computing scenes and runtime support.
_2025/grover
Support
Assets, data, and authoring workflow tooling.
- Stage scenes · Workflow support for launching and iterating on individual scenes.
stage_scenes.py - Editor cmds · Sublime Text commands and plugins for checkpoint-driven scene authoring.
sublime_custom_commands - Assets & data · Precomputed text, JSON, image, and shader assets consumed by scene code.
- Outside videos · Independent or commissioned pieces using the same rendering stack.
outside_videos
Connections 26
- Manim GL → Import bridge: renders via · Scene rendering enters the repo through the shared import bridge.
- Import bridge → Custom layer: reexports · Central bridge exposes repo-specific visual helpers.
- Import bridge → Reusable constructs: reexports · Central bridge exposes reusable mathematical scene utilities.
- Import bridge → EoLA: imports · Series scene files pull in shared primitives and helpers.
- Import bridge → Neural nets: imports · Neural-net scenes rely on the shared import bridge.
- Import bridge → EoP: imports · Probability scenes rely on the shared import bridge.
- Import bridge → DiffyQ: imports · DiffyQ scenes rely on the shared import bridge.
- Import bridge → Wordle: imports · Wordle scenes rely on the shared import bridge.
- Import bridge → Optics puzzles: imports · Optics scenes rely on the shared import bridge.
- Import bridge → Transformers: imports · Transformer scenes rely on the shared import bridge.
- Import bridge → Grover: imports · Grover scenes rely on the shared import bridge.
- Import bridge → Outside videos: imports · One-off content uses the same shared scene ecosystem.
- Custom layer → EoLA: styles · Custom visuals and helpers shape the rendered scenes.
- Custom layer → DiffyQ: styles · Custom visuals and helpers shape the rendered scenes.
- Custom layer → Transformers: styles · Custom visuals and helpers shape the rendered scenes.
- Reusable constructs → EoP: supports · Reusable probability patterns are built from shared helpers.
- Reusable constructs → Optics puzzles: supports · Reusable math and graph utilities inform specialized visuals.
- Assets & data → Neural nets: feeds · Pretrained weights, MNIST assets, and image maps feed animations.
- Assets & data → Wordle: feeds · Word lists and simulation outputs feed analysis scenes.
- Assets & data → Transformers: feeds · Precomputed or domain assets feed transformer scenes.
- Assets & data → Grover: feeds · Quantum demos use supplemental runtime data and assets.
- Stage scenes → Editor cmds: enabled by · Interactive scene staging is supported by editor commands.
- Editor cmds → DiffyQ: supports · Checkpoint-driven iteration is common in long scene packages.
- Editor cmds → Transformers: supports · Checkpoint-driven iteration is common in long scene packages.
- Outside videos → Custom layer: uses · One-off videos reuse the channel’s visual toolkit.
- Outside videos → Reusable constructs: uses · One-off videos reuse shared math-visualization helpers.