# 3b1b/videos architecture

> Architecture diagram of the GitHub repository 3b1b/videos, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/3b1b/videos
- Repository: https://github.com/3b1b/videos

## Overview

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`](https://github.com/3b1b/videos/blob/master/manim_imports_ext.py) (Import bridge), [`custom`](https://github.com/3b1b/videos/tree/master/custom) (Custom layer), [`once_useful_constructs`](https://github.com/3b1b/videos/tree/master/once_useful_constructs) (Reusable constructs), [`_2024/transformers`](https://github.com/3b1b/videos/tree/master/_2024/transformers) (Transformers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core runtime"]
  node_manim_runtime(("Manim GL<br/>render engine"))
  node_manim_imports_ext["Import bridge<br/>shared import hub"]
  node_custom_layer["Custom layer<br/>style toolkit"]
  node_once_useful_constructs["Reusable constructs<br/>math helpers"]
end

subgraph group_series["Video series"]
  node_series_2016_eola["EoLA<br/>linear algebra series"]
  node_series_2017_nn["Neural nets<br/>nn visuals"]
  node_series_2018_eop["EoP<br/>probability series"]
  node_series_2019_diffyq["DiffyQ<br/>differential eqs"]
  node_series_2022_wordle["Wordle<br/>analysis series"]
  node_series_2023_optics["Optics puzzles<br/>wave optics"]
  node_series_2024_transformers["Transformers<br/>attention series"]
  node_series_2025_grover["Grover<br/>quantum series"]
end

subgraph group_support["Support"]
  node_stage_scenes["Stage scenes<br/>authoring helper<br/>[stage_scenes.py]"]
  node_sublime_commands["Editor cmds<br/>workflow plugins"]
  node_shared_data[("Assets & data<br/>static inputs")]
  node_outside_videos["Outside videos<br/>one-off content"]
end

node_manim_runtime -->|"renders via"| node_manim_imports_ext
node_manim_imports_ext -->|"reexports"| node_custom_layer
node_manim_imports_ext -->|"reexports"| node_once_useful_constructs
node_manim_imports_ext -->|"imports"| node_series_2016_eola
node_manim_imports_ext -->|"imports"| node_series_2017_nn
node_manim_imports_ext -->|"imports"| node_series_2018_eop
node_manim_imports_ext -->|"imports"| node_series_2019_diffyq
node_manim_imports_ext -->|"imports"| node_series_2022_wordle
node_manim_imports_ext -->|"imports"| node_series_2023_optics
node_manim_imports_ext -->|"imports"| node_series_2024_transformers
node_manim_imports_ext -->|"imports"| node_series_2025_grover
node_manim_imports_ext -->|"imports"| node_outside_videos
node_custom_layer -->|"styles"| node_series_2016_eola
node_custom_layer -->|"styles"| node_series_2019_diffyq
node_custom_layer -->|"styles"| node_series_2024_transformers
node_once_useful_constructs -->|"supports"| node_series_2018_eop
node_once_useful_constructs -->|"supports"| node_series_2023_optics
node_shared_data -->|"feeds"| node_series_2017_nn
node_shared_data -->|"feeds"| node_series_2022_wordle
node_shared_data -->|"feeds"| node_series_2024_transformers
node_shared_data -->|"feeds"| node_series_2025_grover
node_stage_scenes -->|"enabled by"| node_sublime_commands
node_sublime_commands -->|"supports"| node_series_2019_diffyq
node_sublime_commands -->|"supports"| node_series_2024_transformers
node_outside_videos -->|"uses"| node_custom_layer
node_outside_videos -->|"uses"| node_once_useful_constructs

click node_manim_imports_ext "https://github.com/3b1b/videos/blob/master/manim_imports_ext.py"
click node_custom_layer "https://github.com/3b1b/videos/tree/master/custom"
click node_once_useful_constructs "https://github.com/3b1b/videos/tree/master/once_useful_constructs"
click node_stage_scenes "https://github.com/3b1b/videos/blob/master/stage_scenes.py"
click node_sublime_commands "https://github.com/3b1b/videos/tree/master/sublime_custom_commands"
click node_series_2016_eola "https://github.com/3b1b/videos/tree/master/_2016/eola"
click node_series_2017_nn "https://github.com/3b1b/videos/tree/master/_2017/nn"
click node_series_2018_eop "https://github.com/3b1b/videos/tree/master/_2018/eop"
click node_series_2019_diffyq "https://github.com/3b1b/videos/tree/master/_2019/diffyq"
click node_series_2022_wordle "https://github.com/3b1b/videos/tree/master/_2022/wordle"
click node_series_2023_optics "https://github.com/3b1b/videos/tree/master/_2023/optics_puzzles"
click node_series_2024_transformers "https://github.com/3b1b/videos/tree/master/_2024/transformers"
click node_series_2025_grover "https://github.com/3b1b/videos/tree/master/_2025/grover"
click node_outside_videos "https://github.com/3b1b/videos/tree/master/outside_videos"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_manim_runtime,node_manim_imports_ext,node_custom_layer,node_once_useful_constructs toneBlue
class node_series_2016_eola,node_series_2017_nn,node_series_2018_eop,node_series_2019_diffyq,node_series_2022_wordle,node_series_2023_optics,node_series_2024_transformers,node_series_2025_grover toneAmber
class node_stage_scenes,node_sublime_commands,node_shared_data,node_outside_videos toneMint
```

## Components

### Core runtime

Shared Manim bridge and repo-specific animation infrastructure.

- **Manim GL**: render engine · Older 3Blue1Brown Manim runtime used to render scenes.
- [Import bridge](https://github.com/3b1b/videos/blob/master/manim_imports_ext.py): shared import hub · Central module that gathers Manim primitives and repo helpers for scene files. · `manim_imports_ext.py`
- [Custom layer](https://github.com/3b1b/videos/tree/master/custom): style toolkit · Repo-specific visuals, characters, banners, and animation helpers. · `custom`
- [Reusable constructs](https://github.com/3b1b/videos/tree/master/once_useful_constructs): math helpers · General-purpose scene patterns and math-visualization utilities reused across series. · `once_useful_constructs`

### Video series

Major annual or topic-based content packages.

- [EoLA](https://github.com/3b1b/videos/tree/master/_2016/eola): linear algebra series · Chapter-based linear algebra video package. · `_2016/eola`
- [Neural nets](https://github.com/3b1b/videos/tree/master/_2017/nn): nn visuals · Neural-network explainer scenes, loaders, and pretrained weights. · `_2017/nn`
- [EoP](https://github.com/3b1b/videos/tree/master/_2018/eop): probability series · Probability chapter scenes plus reusable probability-specific constructs. · `_2018/eop`
- [DiffyQ](https://github.com/3b1b/videos/tree/master/_2019/diffyq): differential eqs · Multi-part differential equations series with staging and shared constructs. · `_2019/diffyq`
- [Wordle](https://github.com/3b1b/videos/tree/master/_2022/wordle): analysis series · Wordle analysis scenes driven by word lists and simulation outputs. · `_2022/wordle`
- [Optics puzzles](https://github.com/3b1b/videos/tree/master/_2023/optics_puzzles): wave optics · Specialized wave and optics mini-ecosystem. · `_2023/optics_puzzles`
- [Transformers](https://github.com/3b1b/videos/tree/master/_2024/transformers): attention series · Transformer explainer spanning embeddings, attention, generation, and helpers. · `_2024/transformers`
- [Grover](https://github.com/3b1b/videos/tree/master/_2025/grover): quantum series · Quantum-computing scenes and runtime support. · `_2025/grover`

### Support

Assets, data, and authoring workflow tooling.

- [Stage scenes](https://github.com/3b1b/videos/blob/master/stage_scenes.py): authoring helper · Workflow support for launching and iterating on individual scenes. · `stage_scenes.py`
- [Editor cmds](https://github.com/3b1b/videos/tree/master/sublime_custom_commands): workflow plugins · Sublime Text commands and plugins for checkpoint-driven scene authoring. · `sublime_custom_commands`
- **Assets & data**: static inputs · Precomputed text, JSON, image, and shader assets consumed by scene code.
- [Outside videos](https://github.com/3b1b/videos/tree/master/outside_videos): one-off content · Independent or commissioned pieces using the same rendering stack. · `outside_videos`

## Connections

- 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.
