references/narrative-patterns.md
# Narrative Patterns for Math Explainers
Common structures used in effective 3Blue1Brown-style videos.
## Pattern 1: Mystery → Investigation → Resolution
**Structure:**
1. Present a puzzling result or paradox
2. Investigate why it's true through visual exploration
3. Reveal the underlying principle
4. Show how the principle generalizes
**Example topics:** Euler's identity, Bayes theorem, infinite series paradoxes
**Opening hooks:**
- "What does it even mean to raise a number to an imaginary power?"
- "This equation looks wrong, but it's actually true..."
- "Most people get this probability question wrong..."
---
## Pattern 2: Build Up → Payoff
**Structure:**
1. Introduce simple building blocks
2. Combine them to create something complex
3. Show the beautiful/surprising result
4. Reflect on why it works
**Example topics:** Fourier series, neural networks, linear algebra
**Opening hooks:**
- "Let's start with something simple..."
- "Each piece here is easy, but together they do something remarkable..."
---
## Pattern 3: Two Perspectives → Unity
**Structure:**
1. Show concept from perspective A (e.g., algebraic)
2. Show same concept from perspective B (e.g., geometric)
3. Reveal they're the same thing
4. Explore implications of this connection
**Example topics:** Dot product, determinants, complex multiplication
**Opening hooks:**
- "There are two ways to think about this..."
- "These seem like completely different ideas, but..."
---
## Pattern 4: Wrong → Less Wrong → Right
**Structure:**
1. Present common misconception or naive approach
2. Show why it fails
3. Refine the approach
4. Arrive at correct understanding
**Example topics:** Limits, probability distributions, definitions
**Opening hooks:**
- "Your first instinct here is probably wrong..."
- "The obvious approach doesn't quite work..."
---
## Pattern 5: Specific → General
**Structure:**
1. Solve a specific concrete example
2. Notice patterns in the solution
3. Abstract to general principle
4. Apply to new situations
**Example topics:** Derivatives, group theory, algorithm analysis
**Opening hooks:**
- "Let's work through a specific example..."
- "Once you see the pattern here, it shows up everywhere..."
---
## Pattern 6: History as Narrative
**Structure:**
1. Present the problem as historically encountered
2. Follow the journey of discovery
3. Show key insights that led to breakthroughs
4. Connect to modern understanding
**Example topics:** Calculus, cryptography, quantum mechanics
**Opening hooks:**
- "Imagine you're a mathematician in the 1600s..."
- "This problem stumped the greatest minds for centuries..."
---
## Combining Patterns
Most effective videos combine multiple patterns:
- Mystery hook + Build Up explanation
- Two Perspectives + Specific → General examples
- Wrong → Right + History narrative
## Pacing Guidelines
| Video Length | Intro Hook | Main Content | Recap/Implications |
|--------------|------------|--------------|-------------------|
| 5-10 min | 30-60s | 4-8 min | 30-60s |
| 15-20 min | 1-2 min | 12-16 min | 1-2 min |
| 30+ min | 2-3 min | 24-26 min | 2-4 min |
## Emotional Arc
Every video should have emotional beats:
1. **Curiosity** (opening) - Why should I care?
2. **Confusion** (early) - This is harder than it looks
3. **Partial clarity** (middle) - I'm starting to see...
4. **Aha moment** (climax) - Oh! That's beautiful!
5. **Satisfaction** (end) - Now I truly understand
references/scene-examples.md
# Scene Examples
Example scene breakdowns from 3b1b-style videos.
---
## Example 1: Explaining the Dot Product
### Scene 1: The Question
**Duration**: ~30 seconds
**Purpose**: Hook the viewer with the mystery
**Visual Elements**
- Two vectors a and b drawn as arrows
- The dot product formula: a · b = |a||b|cos(θ)
- Question mark animation
**Content**
Open on two vectors. Show the formula. Pose the question: "Why does multiplying components and adding them give you something related to the angle between vectors?"
**Narration Notes**
Tone: curious, slightly puzzled. Emphasize that the formula seems arbitrary.
**Technical Notes**
- Use Arrow for vectors
- MathTex for formula
- Indicate() on the cos(θ) term
---
### Scene 2: Geometric Interpretation
**Duration**: ~90 seconds
**Purpose**: Show projection interpretation
**Visual Elements**
- Vector a (horizontal, blue)
- Vector b (angled, green)
- Projection of b onto a (dashed line)
- Right angle marker
- Length labels
**Content**
Show that a · b equals |a| times the projection of b onto a. Animate the projection dropping down. Show this equals |a||b|cos(θ) geometrically.
**Narration Notes**
"The dot product measures how much one vector goes in the direction of another."
**Technical Notes**
- DashedLine for projection
- RightAngle mobject
- animate.rotate() for showing different angles
---
### Scene 3: Numeric Connection
**Duration**: ~60 seconds
**Purpose**: Connect geometry to algebra
**Visual Elements**
- Coordinate grid
- Vector a = [a₁, a₂]
- Vector b = [b₁, b₂]
- Components highlighted
**Content**
Show vectors on grid with components labeled. Demonstrate why a₁b₁ + a₂b₂ equals the geometric interpretation. Use specific numbers.
**Narration Notes**
Walk through calculation slowly. "Let's see why the algebra matches the geometry."
**Technical Notes**
- NumberPlane or Axes
- Brace for component labels
- TransformMatchingTex for equation steps
---
## Example 2: Introduction to Fourier Series
### Scene 1: The Hook
**Duration**: ~45 seconds
**Purpose**: Show the surprising result
**Visual Elements**
- A square wave (sharp corners)
- Sum of smooth sine waves
- Morphing animation between them
**Content**
"You can build a square wave—something with sharp corners—from perfectly smooth sine waves." Show the result first, then promise to explain how.
**Narration Notes**
Tone: wonder, slight disbelief. This should feel surprising.
**Technical Notes**
- ParametricFunction for waves
- Transform animation for the morph
- Consider showing 1, 3, 5 terms building up
---
### Scene 2: Building Blocks
**Duration**: ~120 seconds
**Purpose**: Introduce sine waves as basis
**Visual Elements**
- Single sine wave
- Frequency visualization (faster oscillation)
- Amplitude visualization (taller/shorter)
- Phase visualization (shifting left/right)
**Content**
Introduce the three parameters: frequency, amplitude, phase. Show each one separately, then combine.
**Narration Notes**
Go slow. "A sine wave has three knobs we can adjust..."
**Technical Notes**
- ValueTracker for animating parameters
- Updaters to make wave respond to trackers
- Labels for each parameter
---
### Scene 3: Superposition
**Duration**: ~90 seconds
**Purpose**: Show waves can be added
**Visual Elements**
- Two sine waves (different colors)
- Their sum (third color)
- Point-by-point addition visualization
**Content**
Show that adding waves means adding their heights at each point. Demonstrate with two specific frequencies combining.
**Narration Notes**
"Adding waves is simple—at each point, just add the heights."
**Technical Notes**
- VGroup of three function graphs
- Vertical lines showing addition at specific x values
- Animate the addition happening
---
## Example 3: Matrix as Linear Transformation
### Scene 1: Grid Transformation
**Duration**: ~60 seconds
**Purpose**: Visual foundation
**Visual Elements**
- 2D coordinate grid (NumberPlane)
- Basis vectors i-hat and j-hat (colored arrows)
- Grid lines transforming
**Content**
Show a grid. Highlight i-hat (1,0) and j-hat (0,1). Apply a transformation—watch the entire grid move while tracking where basis vectors land.
**Narration Notes**
"Watch what happens to the grid when we apply this transformation. Notice how every point moves."
**Technical Notes**
- NumberPlane with visible grid lines
- apply_matrix() method
- Keep basis vectors visually distinct
---
### Scene 2: Basis Vectors Determine Everything
**Duration**: ~90 seconds
**Purpose**: Key insight
**Visual Elements**
- Transformed i-hat and j-hat
- Arbitrary vector v as combination
- v = xi + yj visualization
**Content**
Show that knowing where i-hat and j-hat land tells you where ANY vector lands. Because v = xi + yj, the transformed v = x(new i) + y(new j).
**Narration Notes**
"Here's the key insight..." Build anticipation before the reveal.
**Technical Notes**
- Vector addition animation (tip-to-tail)
- Scaling animation for coefficients
- TransformMatchingShapes for the combination
---
## Scene Transition Patterns
### Zoom Focus
```
Full scene → Zoom into detail → Explain → Zoom out
```
### Side-by-Side Build
```
Empty left | Empty right
Add to left | Compare
Add to right | Connect them
```
### Transform Chain
```
Object A → Transform → Object B → Transform → Object C
(Maintain visual continuity throughout)
```
### Reset and Rebuild
```
Complex scene → Clear/fade most → Focus on one element → Build new complexity
```
references/visual-techniques.md
# Visual Techniques for Math Animation
Effective visualization patterns for explaining mathematical concepts.
## Core Principles
### 1. Progressive Disclosure
Never show everything at once. Build complexity gradually.
**Bad:** Show complete equation immediately
**Good:** Build equation term by term, explaining each part
```
Scene flow:
1. Show simple case: f(x) = x²
2. Add complexity: f(x) = ax²
3. Full form: f(x) = ax² + bx + c
```
### 2. Transform, Don't Replace
When possible, morph objects into new forms rather than fading out/in.
**Bad:** FadeOut(equation1), FadeIn(equation2)
**Good:** TransformMatchingTex(equation1, equation2)
This maintains visual continuity and shows the relationship between forms.
### 3. Color as Meaning
Use color consistently to encode meaning throughout the video.
**Pattern:**
- Input/given values: BLUE
- Output/results: GREEN
- Key terms being discussed: YELLOW highlight
- Errors/negatives: RED
- Neutral/supporting: WHITE/GREY
### 4. Spatial Relationships
Position encodes relationships:
- Left-to-right: transformation, time, causation
- Top-to-bottom: hierarchy, derivation
- Center: focus of attention
- Periphery: context, reference
---
## Animation Techniques
### Highlighting & Focus
**Indicate** - Brief flash to draw attention
```python
self.play(Indicate(term))
```
**Circumscribe** - Circle around important element
```python
self.play(Circumscribe(equation, color=YELLOW))
```
**FlashAround** - Dramatic attention on revelation
```python
self.play(FlashAround(result))
```
### Equation Manipulation
**Isolate terms** - Color or move specific parts
```python
equation.set_color_by_tex("x", BLUE)
```
**Step-by-step derivation** - Show each algebraic step
```python
step1 = MathTex(r"2x + 4 = 10")
step2 = MathTex(r"2x = 6")
step3 = MathTex(r"x = 3")
# Transform between steps with alignment
```
**Substitution** - Show value being plugged in
```python
# Animate the number moving into the variable's position
```
### Geometric Intuition
**Coordinate systems** - Always label axes
```python
axes = Axes(x_range=[-3, 3], y_range=[-2, 2])
labels = axes.get_axis_labels(x_label="x", y_label="f(x)")
```
**Trace paths** - Show how points move
```python
trace = TracedPath(dot.get_center, stroke_color=YELLOW)
```
**Area visualization** - For integrals, sums
```python
area = axes.get_area(graph, x_range=[a, b], color=BLUE, opacity=0.5)
```
### 3D Techniques
**Camera orbiting** - Reveal 3D structure
```python
self.play(frame.animate.reorient(60, 70), run_time=3)
```
**Projection** - Show 3D object's 2D shadow
```python
# Helps connect 3D intuition to 2D formulas
```
**Slicing** - Cut through 3D objects
```python
# Show cross-sections to understand structure
```
---
## Common Visual Metaphors
### Vectors as Arrows
- Position vectors: arrows from origin
- Addition: tip-to-tail
- Scaling: stretching/shrinking
### Functions as Machines
- Input goes in one side
- Transformation happens
- Output comes out
### Matrices as Transformations
- Show grid being transformed
- Track where basis vectors go
- Emphasize determinant as area scaling
### Derivatives as Slopes
- Tangent line touching curve
- Zoom in to show local linearity
- Animate slope changing as point moves
### Integrals as Accumulation
- Riemann sums with rectangles
- Width → 0 animation
- Area filling under curve
---
## Scene Composition
### The Golden Layout
```
┌─────────────────────────────────┐
│ TITLE/CONTEXT │ (top edge)
├─────────────────────────────────┤
│ │
│ MAIN VISUALIZATION │ (center, largest area)
│ │
├─────────────────────────────────┤
│ EQUATION / FORMULA │ (bottom third)
└─────────────────────────────────┘
```
### Side-by-Side Comparison
```
┌───────────────┬───────────────┐
│ BEFORE / │ AFTER / │
│ CONCEPT A │ CONCEPT B │
└───────────────┴───────────────┘
```
### Zoomed Detail
```
┌─────────────────────────────────┐
│ ┌─────┐ │
│ │ZOOM │ ←── magnified detail │
│ └─────┘ │
│ Main context │
└─────────────────────────────────┘
```
---
## Timing Guidelines
| Action | Typical Duration |
|--------|------------------|
| Simple shape creation | 0.5-1s |
| Text/equation writing | 1-2s |
| Transformation | 1-2s |
| Camera movement | 2-3s |
| Pause for absorption | 0.5-1s |
| Complex animation | 2-4s |
### Rhythm Pattern
Fast-fast-SLOW-fast-fast-SLOW
Quick animations for setup, slow down for key insights.
---
## Color Palettes
### Classic 3b1b
- Background: #1C1C1C (dark grey)
- Primary: #58C4DD (blue)
- Secondary: #83C167 (green)
- Accent: #FFFF00 (yellow)
- Warning: #FF6666 (red)
### High Contrast
- Background: #000000
- Primary: #FFFFFF
- Accent: #FFD700
### Soft Academic
- Background: #2D2D2D
- Primary: #6ECFFF
- Secondary: #98E898
- Accent: #FFE66D
SKILL.md
---
name: manim-composer
description: |
Trigger when: (1) User wants to create an educational/explainer video, (2) User has a vague concept they want visualized, (3) User mentions "3b1b style" or "explain like 3Blue1Brown", (4) User wants to plan a Manim video or animation sequence, (5) User asks to "compose" or "plan" a math/science visualization.
Transforms vague video ideas into detailed scene-by-scene plans (scenes.md). Conducts research, asks clarifying questions about audience/scope/focus, and outputs comprehensive scene specifications ready for implementation with ManimCE or ManimGL.
Use this BEFORE writing any Manim code. This skill plans the video; use manimce-best-practices or manimgl-best-practices for implementation.
---
## Workflow
### Phase 1: Understand the Concept
1. **Research the topic** deeply before asking questions
- Use web search to understand the core concepts
- Identify the key insights that make this topic interesting
- Find the "aha moment" - what makes this click for learners
- Note common misconceptions to address
2. **Identify the narrative hook**
- What question does this video answer?
- Why should the viewer care?
- What's the surprising or counterintuitive element?
### Phase 2: Clarify with User
Ask targeted questions (not all at once - adapt based on responses):
**Audience & Scope**
- What math/science background should I assume? (e.g., "knows calculus" or "high school algebra")
- Target video length? (short: 5-10min, medium: 15-20min, long: 30min+)
- Should this be self-contained or part of a series?
**Focus & Depth**
- Any specific aspects to emphasize or skip?
- Proof-heavy or intuition-focused?
- Real-world applications to include?
**Style Preferences**
- Color scheme preferences?
- Narration style? (casual, formal, playful)
- Any specific visual metaphors you have in mind?
### Phase 3: Create scenes.md
Output a comprehensive `scenes.md` file with this structure:
```markdown
# [Video Title]
## Overview
- **Topic**: [Core concept]
- **Hook**: [Opening question/mystery]
- **Target Audience**: [Prerequisites]
- **Estimated Length**: [X minutes]
- **Key Insight**: [The "aha moment"]
## Narrative Arc
[2-3 sentences describing the journey from confusion to understanding]
---
## Scene 1: [Scene Name]
**Duration**: ~X seconds
**Purpose**: [What this scene accomplishes]
### Visual Elements
- [List of mobjects needed]
- [Animations to use]
- [Camera movements]
### Content
[Detailed description of what happens, what's shown, what's explained]
### Narration Notes
[Key points to convey, tone, pacing notes]
### Technical Notes
- [Specific Manim classes/methods to use]
- [Any tricky implementations to note]
---
## Scene 2: [Scene Name]
...
---
## Transitions & Flow
[Notes on how scenes connect, recurring visual motifs]
## Color Palette
- Primary: [color] - used for [purpose]
- Secondary: [color] - used for [purpose]
- Accent: [color] - used for [purpose]
- Background: [color]
## Mathematical Content
[List of equations, formulas, or mathematical objects that need to be rendered]
## Implementation Order
[Suggested order for implementing scenes, noting dependencies]
```
## 3b1b Style Principles
Apply these principles when composing scenes:
### Visual Storytelling
- **Show, don't just tell** - Every concept needs a visual representation
- **Progressive revelation** - Build complexity gradually, don't show everything at once
- **Visual continuity** - Transform objects rather than replacing them when possible
### Pacing & Rhythm
- **Pause for insight** - Give viewers time to absorb key moments
- **Vary the pace** - Mix quick sequences with slower explanations
- **End scenes with resolution** - Each scene should feel complete
### Mathematical Beauty
- **Emphasize elegance** - Highlight when math is surprisingly simple or beautiful
- **Connect representations** - Show the same concept multiple ways (algebraic, geometric, intuitive)
- **Embrace abstraction gradually** - Start concrete, then generalize
### Engagement Techniques
- **Pose questions** - Make viewers curious before revealing answers
- **Acknowledge difficulty** - "This might seem confusing at first..."
- **Celebrate insight** - Make the "aha moment" feel earned
## References
- [references/narrative-patterns.md](references/narrative-patterns.md) - Common 3b1b narrative structures
- [references/visual-techniques.md](references/visual-techniques.md) - Effective visualization patterns
- [references/scene-examples.md](references/scene-examples.md) - Example scenes.md excerpts
## Templates
- [templates/scenes-template.md](templates/scenes-template.md) - Blank scenes.md template
templates/scenes-template.md
# [Video Title]
## Overview
- **Topic**: [Core mathematical/scientific concept]
- **Hook**: [Opening question or mystery that draws viewers in]
- **Target Audience**: [Prerequisites - what math/science background is assumed]
- **Estimated Length**: [X minutes]
- **Key Insight**: [The central "aha moment" - the one thing viewers should remember]
## Narrative Arc
[2-3 sentences describing the emotional and intellectual journey. Example: "We start with a puzzling observation, investigate why it's true, and discover a beautiful underlying principle that connects seemingly different ideas."]
---
## Scene 1: [Scene Name]
**Duration**: ~X seconds
**Purpose**: [What this scene accomplishes in the overall narrative]
### Visual Elements
- [Mobject 1: description, color, position]
- [Mobject 2: description, color, position]
- [Animation sequence]
- [Camera movements if any]
### Content
[Detailed description of what happens visually and conceptually. Be specific enough that someone could implement this scene.]
### Narration Notes
[Key points to convey, suggested tone, pacing. Not a full script, but guidance.]
### Technical Notes
- [Specific Manim classes to use]
- [Tricky implementations or gotchas]
- [Dependencies on previous scenes]
---
## Scene 2: [Scene Name]
**Duration**: ~X seconds
**Purpose**: [Purpose]
### Visual Elements
- [List elements]
### Content
[Description]
### Narration Notes
[Notes]
### Technical Notes
- [Notes]
---
## Scene 3: [Scene Name]
**Duration**: ~X seconds
**Purpose**: [Purpose]
### Visual Elements
- [List elements]
### Content
[Description]
### Narration Notes
[Notes]
### Technical Notes
- [Notes]
---
[Add more scenes as needed]
---
## Transitions & Flow
### Scene Connections
- Scene 1 → Scene 2: [How they connect, what carries over visually]
- Scene 2 → Scene 3: [Connection]
- [Continue for all transitions]
### Recurring Visual Motifs
- [Element that appears throughout, providing continuity]
- [Color or shape that reinforces key concept]
---
## Color Palette
| Role | Color | Hex | Usage |
|------|-------|-----|-------|
| Primary | [e.g., Blue] | #58C4DD | [Main objects, key terms] |
| Secondary | [e.g., Green] | #83C167 | [Results, outputs] |
| Accent | [e.g., Yellow] | #FFFF00 | [Highlights, emphasis] |
| Warning | [e.g., Red] | #FF6666 | [Errors, negatives] |
| Background | [e.g., Dark grey] | #1C1C1C | [Scene background] |
---
## Mathematical Content
### Equations to Render
1. `[LaTeX equation 1]` - used in Scene X
2. `[LaTeX equation 2]` - used in Scene Y
3. [Continue...]
### Graphs/Plots
1. [Function 1]: domain, key features
2. [Function 2]: domain, key features
### Geometric Objects
1. [Object]: properties, how it transforms
2. [Continue...]
---
## Implementation Order
Suggested order for building scenes (accounting for dependencies):
1. **[Scene name]** - [Why first: standalone, establishes base objects]
2. **[Scene name]** - [Dependency notes]
3. **[Scene name]** - [Dependency notes]
4. [Continue...]
### Shared Components
Objects or code that should be defined once and reused:
- [Component 1]: used in Scenes X, Y, Z
- [Component 2]: used in Scenes A, B
---
## Open Questions / Decisions Needed
- [ ] [Question about scope, implementation, or creative direction]
- [ ] [Another decision point]
---
## Reference Material
- [Link or citation to source material]
- [Inspiration videos or images]
- [Academic papers if relevant]