manim-mcp 0.1.0

package/references/composer/references/opening-patterns.md

@@ -0,0 +1,284 @@
+# 3Blue1Brown Opening Patterns
+
+How 3b1b opens videos, derived from analysis of 400+ video source files (2015-2026). The opening 30-90 seconds determines whether a viewer stays. Grant uses several distinct patterns, often combining them.
+
+---
+
+## Pattern 1: The Opening Quote
+
+Used extensively in the Essence of Linear Algebra series (every chapter) and occasionally elsewhere. An `OpeningQuote` scene class displays a formatted quote with author attribution.
+
+### Implementation
+
+```python
+class OpeningQuote(Scene):
+    def construct(self):
+        words = OldTexText("``Quote text here.''")
+        words.set_width(2 * (FRAME_X_RADIUS - 1))
+        words.to_edge(UP)
+        # Color-highlight key phrases
+        words.set_color_by_tex("key phrase", GREEN)
+
+        author = OldTexText("-Author Name")
+        author.set_color(YELLOW)
+        author.next_to(words, DOWN, buff=0.5)
+
+        self.play(FadeIn(words))
+        self.wait(3)
+        self.play(Write(author, run_time=5))
+        self.wait()
+```
+
+### Actual Quotes Used (EoLA)
+
+| Chapter | Quote | Author | Why It Works |
+|---------|-------|--------|--------------|
+| Ch 0 | "There is hardly any theory more elementary than linear algebra, in spite of...preposterous calculations with matrices." | Jean Dieudonne | Sets up the thesis: intuition over computation |
+| Ch 1 | "The introduction of numbers as coordinates is an act of violence." | Hermann Weyl | Frames coordinates as a choice, not reality |
+| Ch 2 | "Mathematics requires a small dose not of genius but of an imaginative freedom..." | Angus K. Rodgers | Encourages creative thinking |
+| Ch 3 | "Unfortunately, no one can be told what the Matrix is. You have to see it for yourself." | Morpheus | Perfect pun + pop culture hook |
+| Ch 4 | "It is my experience that proofs involving matrices can be shortened by 50%..." | Emil Artin | Reinforces compositional thinking |
+| Ch 5 | "The purpose of computation is insight, not numbers." | Richard Hamming | Why visualization matters |
+| Ch 6 | "The essence of mathematics lies in its freedom." | Georg Cantor | The determinant captures geometric essence |
+| Ch 8 | "Every dimension is special." | Jeff Lagarias | Non-square matrices cross dimensions |
+| Ch 8.5 | "[From Grothendieck] difficulty means we have not understood..." | Pierre Deligne | Elegant proofs over hard proofs |
+| Ch 9 | "Mathematics...gives the same name to different things" | Henri Poincare | Duality between dot product and projection |
+| Ch 10 | "What does 'mathematics' mean to you?" / "What does 'music' mean to you?" | Serge Lang | Basis as language, change of basis as translation |
+| Ch 11 | "Axioms are not obvious...difficult for the uninitiated" | Vladimir Arnold | Abstract eigenvalue theory needs grounding |
+
+### When to Use Opening Quotes
+
+- Series with intellectual gravitas (foundational math courses)
+- When a famous quote perfectly encapsulates the video's thesis
+- To signal "this is part of a thoughtful curriculum"
+- NOT for standalone puzzle/fun videos
+
+---
+
+## Pattern 2: Mystery First (Surprising Result)
+
+Present a result that seems impossible or surprising, then promise to explain it. This is Grant's most common opening for standalone videos.
+
+### Examples from Actual Videos
+
+**Colliding Blocks (2019)**: "Imagine two sliding blocks, where one is much heavier. The small block bounces off the wall. Count the total collisions. With a mass ratio of 100:1, you get 31 collisions. With 10,000:1, you get 314. With 1,000,000:1, you get 3,141. Why is pi showing up?"
+
+**Basel Problem / Sum of 1/n^2 (2018)**: Start by writing `1 + 1/4 + 1/9 + 1/16 + ... = pi^2/6`. The equation sits there, looking absurd. Why would squaring natural numbers, taking reciprocals, and summing produce pi?
+
+**Borwein Integrals (2022)**: Show a sequence of integrals that all equal pi: integral of sinc(x), integral of sinc(x)*sinc(x/3), ... then suddenly one does NOT equal pi. "What goes wrong?"
+
+**Moser's Circle Problem (2023)**: Points on a circle connected by lines create regions. 1, 2, 4, 8, 16... then 31 (not 32). "The pattern breaks."
+
+### Implementation Pattern
+
+```
+1. Show the surprising result (30 seconds)
+   - Display equation/number/visual that seems wrong
+   - Let it sit. Use self.wait(2) to build tension.
+   - Optionally: Pi creature with "confused" or "surprised" expression
+
+2. Acknowledge the surprise (10 seconds)
+   - "If this seems surprising, good..."
+   - "Your first instinct might be that this is wrong..."
+
+3. Promise the explanation (10 seconds)
+   - "By the end of this video, you'll see why this has to be true."
+   - "The answer involves a beautiful connection to..."
+```
+
+---
+
+## Pattern 3: Physical Scenario Opening
+
+Open with a concrete physical setup before any math appears. Let the viewer SEE the problem.
+
+### Examples
+
+**Pendulum / DiffEq Part 1 (2019)**: A pendulum swings on screen. No equations. Just watch it move. THEN ask "How would you describe this motion mathematically?"
+
+**Heat Equation / DiffEq Part 2 (2019)**: Show a temperature distribution on a rod. Colors indicate temperature. Watch heat flow. THEN introduce the PDE.
+
+**Cosmic Distance (2025)**: Show the night sky with stars at different depths. How do we know how far away they are? Parallax visualization with 3D `GlowDots` and Earth orbit.
+
+**Optics Puzzles (2023)**: `OscillatingWave` objects propagating through media. The visual IS the question -- why does light slow down in glass?
+
+### Implementation Pattern
+
+```
+1. Show the physical system (30-60 seconds)
+   - Simulation running (pendulum, blocks, particles)
+   - No equations, no narration about math
+   - Let the viewer's curiosity build naturally
+
+2. Pose the natural question (15 seconds)
+   - "How would you predict what happens next?"
+   - "What determines the outcome?"
+
+3. Transition to mathematical framework (30 seconds)
+   - Introduce variables, axes, coordinate system
+   - Map physical quantities to mathematical objects
+```
+
+---
+
+## Pattern 4: Question-Driven Opening
+
+Open with a conceptual question that reframes a familiar idea.
+
+### Examples
+
+**EoLA Ch 1 (2016)**: "What are vectors?" -- presented through three different Pi creature perspectives (physicist, CS student, mathematician). Each has a different answer.
+
+**EoC Ch 2 (2017)**: "What does it mean for something to change instantaneously?" -- the derivative paradox.
+
+**EoC Ch 5 (2017)**: "What's so special about e?" -- why THIS number, out of all numbers?
+
+**Uncertainty Principle (2018)**: "What does it mean for a sound to have a frequency?"
+
+**Bayes Theorem (2019/2020)**: "Most people get this probability question wrong. Here's why."
+
+### Implementation Pattern
+
+```
+1. State the question simply (15 seconds)
+   - Text or spoken, centered on screen
+   - Often uses Tex or Text with emphasis coloring
+
+2. Show why it's harder than it looks (30 seconds)
+   - Present the naive answer
+   - Show why it's incomplete or wrong
+   - Pi creature reactions: confusion, frustration
+
+3. Reframe with clarity (15 seconds)
+   - "A better question is..."
+   - "What we really need is..."
+```
+
+---
+
+## Pattern 5: Pi Creature Classroom Opening
+
+Used for lighter topics, series introductions, or when establishing rapport.
+
+### Examples
+
+**SoME1 Announcement (2021)**: `TeacherStudentsScene` with Mortimer (teacher) explaining the contest to students.
+
+**Moser Reboot (2023)**: Student asks a question, teacher responds with a visual.
+
+**CLT Wordy Scenes (2023)**: `ThreeAssumptions` -- Pi creatures discuss when the CLT applies.
+
+### Implementation
+
+```python
+class IntroScene(TeacherStudentsScene):
+    def construct(self):
+        self.play(
+            self.teacher.says("Today we'll talk about..."),
+            self.change_students("happy", "pondering", "erm")
+        )
+        self.wait()
+        self.play(
+            self.students[1].says(
+                "Doesn't it depend on\nwhere the points are?",
+                mode="sassy"
+            ),
+            self.teacher.change("guilty", self.students[1].eyes)
+        )
+```
+
+### Teacher-Student Emotional Modes
+
+From the codebase, Pi creatures use these modes:
+- **Students**: `"confused"`, `"pondering"`, `"sassy"`, `"erm"`, `"happy"`, `"horrified"`, `"angry"`, `"surprised"`, `"thinking"`, `"plain"`
+- **Teacher (Mortimer)**: `"raise_right_hand"`, `"happy"`, `"tease"`, `"guilty"`, `"hesitant"`, `"surprised"`
+
+---
+
+## Pattern 6: Historical Narrative Opening
+
+Open with a historical figure or discovery, creating narrative momentum.
+
+### Examples
+
+**Galois Theory (2022)**: Galois's story -- the night before his fatal duel, scribbling mathematics. Uses `OutpaintTransition` for artwork panning, `LastWordsQuote` and `NightBeforeQuote` for historical text.
+
+**Lost Lecture / Feynman (2018)**: "There's a famous lecture by Feynman..."
+
+**Basel Problem (2018)**: "Euler solved this problem in 1734..."
+
+**Cosmic Distance / Venus Transit (2025)**: Historical timeline with `GlowDots` showing when key measurements were made.
+
+---
+
+## Pattern 7: Result Preview + Promise
+
+Show the end result of the video up front, then rewind to explain how we get there.
+
+### Examples
+
+**Fourier Series (2019)**: Show the final rotating-vector drawing (epicycles tracing a complex shape). "By the end of this video, you'll understand how this works."
+
+**Fourier (2018)**: The frequency decomposition of audio is shown immediately, then the video explains how it works.
+
+**Neural Network Part 1 (2017)**: Show a trained network recognizing digits. Then rewind: "But what IS a neural network?"
+
+### Implementation Pattern
+
+```
+1. Show the impressive end state (30-45 seconds)
+   - Complex animation, completed visualization
+   - The "wow" moment that the video will build toward
+
+2. Acknowledge it looks complex (10 seconds)
+   - "This might look intimidating..."
+   - "There's a lot going on here..."
+
+3. Promise simplicity (10 seconds)
+   - "But it's built from very simple pieces."
+   - "Let's start from the beginning."
+
+4. Reset/clear the scene (5 seconds)
+   - FadeOut everything
+   - Clean slate for the actual explanation
+```
+
+---
+
+## Combining Opening Patterns
+
+Most strong videos combine 2-3 patterns:
+
+| Video | Primary Pattern | Secondary Pattern |
+|-------|----------------|-------------------|
+| Colliding Blocks | Mystery First | Physical Scenario |
+| EoLA chapters | Opening Quote | Question-Driven |
+| DiffEq Part 1 | Physical Scenario | Question-Driven |
+| Neural Networks | Result Preview | Question-Driven |
+| Borwein Integrals | Mystery First | Pi Creature Classroom |
+| Fourier Series | Result Preview | Physical Scenario |
+| Galois Theory | Historical Narrative | Mystery First |
+
+---
+
+## Opening Timing Guidelines
+
+| Component | Duration | Notes |
+|-----------|----------|-------|
+| Quote display | 8-12 seconds | FadeIn quote (1s), wait (3-4s), Write author (4-5s), wait (1s) |
+| Surprising result | 15-30 seconds | Show result, let it sit, acknowledge surprise |
+| Physical simulation | 30-60 seconds | Let the simulation run, no rushing |
+| Question statement | 10-20 seconds | Clear text, emphasis on key words |
+| Pi creature dialogue | 20-40 seconds | 2-3 exchanges max before moving on |
+| Promise/transition | 10-15 seconds | Brief bridge to main content |
+| **Total opening** | **30-90 seconds** | Shorter for focused videos, longer for series openers |
+
+---
+
+## Anti-Patterns (What NOT to Do)
+
+1. **Don't open with definitions**: "A vector space is a set V with two operations..." -- NO. Start with WHY.
+2. **Don't open with prerequisites**: "Before we start, you need to know X, Y, Z..." -- weave prerequisites in as needed.
+3. **Don't open with apologies**: "This is a hard topic..." -- instead, make it a challenge: "This is going to be fun."
+4. **Don't show the full equation first**: Build to it. The full equation is the PAYOFF, not the opening.
+5. **Don't open with credits/logos**: Get to the content immediately. Credits come at the end.

package/references/composer/references/pacing-guide.md

@@ -0,0 +1,289 @@
+# 3Blue1Brown Pacing Guide
+
+Detailed pacing analysis derived from 400+ 3b1b video source files. This covers timing at every level: overall video structure, scene-level pacing, animation timing, and wait/pause patterns.
+
+---
+
+## Overall Video Structure
+
+### Timing by Video Length
+
+| Video Length | Opening Hook | Core Content | Recap/Implications | Pi Creature Interludes |
+|-------------|-------------|-------------|--------------------|-----------------------|
+| 5-10 min | 30-60s | 4-8 min | 30-60s | 0-1 (15-30s each) |
+| 15-20 min | 60-90s | 12-16 min | 1-2 min | 2-3 (15-30s each) |
+| 25-30 min | 90-120s | 20-25 min | 2-3 min | 3-5 (15-30s each) |
+| 30+ min | 2-3 min | 24-28 min | 2-4 min | 4-6 (15-30s each) |
+
+### The Three-Act Structure
+
+Most 3b1b videos follow a three-act structure:
+
+**Act 1 (15-20% of runtime)**: Setup
+- Hook / surprising result / question
+- Establish the problem domain
+- Introduce visual vocabulary
+- Set expectations for what we'll learn
+
+**Act 2 (60-70% of runtime)**: Investigation
+- Build concepts progressively
+- Multiple examples, increasing complexity
+- Key insight / "aha moment" at 60-70% mark
+- Pi creature interludes for emotional resets
+
+**Act 3 (15-20% of runtime)**: Resolution
+- Connect back to the opening hook
+- Broader implications
+- "Where does this lead?" forward reference
+- End screen
+
+---
+
+## Scene-Level Pacing
+
+### Concept Introduction: 2-3 Minutes Per Major Concept
+
+A "major concept" is something like "what is a determinant" or "what is attention in a transformer." The pattern:
+
+```
+1. Motivation (15-30s): Why do we need this?
+2. Visual introduction (30-60s): Show it, don't define it
+3. Formal statement (15-30s): Now the definition/formula
+4. First example (30-60s): Work through a specific case
+5. Second example or variation (30-60s): Reinforce, show edge case
+```
+
+### Example/Demonstration: 1-2 Minutes Each
+
+```
+1. Setup the specific case (15-20s)
+2. Walk through step by step (30-60s)
+3. Highlight the key observation (15-20s)
+4. Connect to the general principle (10-15s)
+```
+
+### Formula Derivation: 3-5 Minutes (Visual, Not Algebraic)
+
+Grant never grinds through algebra. The derivation IS the visualization.
+
+```
+1. State what we want to show (15-30s)
+2. Set up the geometric/visual framework (30-60s)
+3. Step-by-step transformation (60-120s)
+   - Each step: Indicate target → Transform → Wait → Explain
+4. Reveal the final formula (15-30s)
+   - FlashAround or Circumscribe for emphasis
+5. Reflect on elegance or implications (30-60s)
+```
+
+### Pi Creature Interlude: 15-30 Seconds
+
+Placed between major sections as emotional resets:
+
+```
+1. Student expresses confusion/surprise (5-10s)
+2. Teacher responds (5-10s)
+3. Brief visual gag or acknowledgment (5-10s)
+```
+
+---
+
+## Animation Timing (run_time Values)
+
+### From the Codebase
+
+| Animation Type | Typical run_time | Usage |
+|---------------|-----------------|-------|
+| `Write(equation)` | 1-2s | Writing LaTeX equations |
+| `ShowCreation(mobject)` | 1-2s | Drawing shapes, graphs |
+| `FadeIn(mobject)` | 0.5-1s | Bringing in new elements |
+| `FadeIn(mobject, shift=UP)` | 0.5-1s | Directional fade-in |
+| `FadeOut(mobject)` | 0.5-1s | Removing elements |
+| `Transform(a, b)` | 1-2s | General shape morphing |
+| `TransformMatchingTex(a, b)` | 1-2s | Equation transitions |
+| `FadeTransform(a, b)` | 1-2s | Cross-dissolve transform |
+| `Indicate(mobject)` | 0.5-1s | Brief flash to draw attention |
+| `Circumscribe(mobject)` | 1s | Circle around element |
+| `FlashAround(mobject)` | 0.5-1s | Flash effect on revelation |
+| `LaggedStartMap(FadeIn, group)` | 2-4s | Sequential group reveal |
+| `LaggedStart(*anims)` | 3-5s | Staggered animation set |
+| `apply_matrix(M)` | 2-3s | Grid transformation |
+| `frame.animate.reorient(...)` | 3-5s | Camera movement in 3D |
+| `frame.animate.set_height(...)` | 2-3s | Camera zoom |
+| `MoveAlongPath(mob, path)` | 2-4s | Path following |
+| `Rotate(mob, angle)` | 1-2s | Rotation |
+| `VShowPassingFlash(mob)` | 1-2s | Passing flash effect |
+| `VFadeInThenOut(mob)` | 0.5-1s | Temporary appearance |
+
+### Special Timing Patterns
+
+**Opening Quote Author Write**: `run_time=4-5` (slow, dramatic)
+
+**Grid Transformation**: `run_time=3` (let the viewer absorb the deformation)
+
+**Key Reveal**: `run_time=2` with preceding `self.wait(1)` and following `self.wait(2)`
+
+**Speed Ramp for Repetition**:
+```python
+# From CLT dice simulation
+for n in range(n_sums):
+    if n < 10:
+        self.run_one_sum(animated=True)   # Full animation
+    else:
+        self.run_one_sum(animated=False)   # Skip-through
+```
+
+**Scene Inheritance for Speed Variants**:
+```python
+class QuickerRegression(SimpleAutogregression):
+    skip_through = True  # Same scene, faster
+```
+
+---
+
+## Wait/Pause Patterns
+
+### From the Codebase Analysis
+
+| Context | Wait Duration | Purpose |
+|---------|--------------|---------|
+| After key reveal | `self.wait(2-3)` | Let the viewer process the insight |
+| Between animation steps | `self.wait(1)` | Brief beat for comprehension |
+| After showing equation | `self.wait(2)` | Reading time |
+| After question posed | `self.wait(1-2)` | Let viewer think |
+| After Pi creature reaction | `self.wait(1)` | Comedic timing |
+| After physical simulation starts | `self.wait(3-10)` | Let simulation play out |
+| End of scene | `self.wait(1-2)` | Transition buffer |
+| After FlashAround/Circumscribe | `self.wait(1)` | Absorb the highlight |
+
+### The Rhythm Pattern
+
+```
+Fast-Fast-SLOW-Fast-Fast-SLOW
+```
+
+Quick setup animations (FadeIn, small moves), then a SLOW key moment (Write equation, Transform, camera move with long wait), then quick again.
+
+**Example from a typical scene:**
+```python
+self.play(FadeIn(axes))                    # 0.5s - quick
+self.play(ShowCreation(graph))             # 1s   - quick
+self.wait(2)                               # 2s   - SLOW pause
+self.play(Write(equation))                 # 2s   - moderate
+self.wait(2)                               # 2s   - SLOW pause
+self.play(Indicate(equation[3:6]))         # 0.5s - quick
+self.play(Transform(equation, equation2))  # 1s   - quick
+self.wait(3)                               # 3s   - SLOW (key insight!)
+```
+
+---
+
+## Pacing for Different Content Types
+
+### Proof Video Pacing
+
+| Phase | % of Video | Pacing |
+|-------|-----------|--------|
+| State the theorem | 5% | Quick, clean |
+| Motivation ("why care?") | 10% | Moderate, hook |
+| Setup the visual framework | 15% | Slow, deliberate |
+| Step-by-step reasoning | 50% | Each step: animate (1-2s) + wait (2s) + explain (narration) |
+| Key insight moment | 5% | SLOW. FlashAround. wait(3). |
+| Implications | 10% | Moderate |
+| "Isn't that beautiful?" | 5% | Slow, reflective |
+
+### Tutorial/How-To Pacing
+
+| Phase | % of Video | Pacing |
+|-------|-----------|--------|
+| What we're building toward | 5% | Quick preview |
+| Setup prerequisites | 15% | Moderate |
+| Build concept step by step | 60% | Slow, with examples |
+| Full picture | 10% | Moderate |
+| Practice/extension | 10% | Quick |
+
+### Mystery/Puzzle Pacing
+
+| Phase | % of Video | Pacing |
+|-------|-----------|--------|
+| Present the puzzle | 10% | Quick, intriguing |
+| First attempt (wrong) | 15% | Moderate |
+| Why it fails | 10% | Quick |
+| Better approach | 25% | Slow, building |
+| The answer | 15% | SLOW. The payoff. |
+| Why it works | 15% | Moderate |
+| Generalization | 10% | Quick |
+
+---
+
+## Transition Pacing
+
+### Between Scenes
+
+- **Cut (FadeOut all, FadeIn new)**: 0.5-1s each. Use for topic changes.
+- **Transform continuity**: 1-2s. Use when the next scene builds on current objects.
+- **Camera move**: 2-3s. Use for zoom-in to detail or zoom-out to big picture.
+- **Clean slate**: FadeOut everything (0.5s), wait(0.5s), FadeIn new scene (0.5s).
+
+### Between Major Sections
+
+Insert a Pi creature interlude or a brief visual recap (15-30s) between major mathematical sections. This gives the viewer time to consolidate before new information arrives.
+
+---
+
+## Lag Ratio Guidelines
+
+The `lag_ratio` parameter controls how much sequential animations overlap:
+
+| lag_ratio | Effect | Use When |
+|-----------|--------|----------|
+| 0.0 | All at once | Revealing a complete group |
+| 0.05-0.1 | Cascading wave | Sequential group reveal (most common) |
+| 0.2-0.3 | Clearly sequential | Ordered list, step-by-step |
+| 0.5 | Half overlap | Moderate pacing |
+| 1.0 | Fully sequential | Each finishes before next starts |
+
+### Common lag_ratio Values from Codebase
+
+```python
+# Most common: staggered reveal
+LaggedStartMap(FadeIn, group, lag_ratio=0.1)
+
+# Sequential arrows or labels
+LaggedStartMap(ShowCreation, arrows, lag_ratio=0.5)
+
+# Dramatic sequential reveal
+LaggedStartMap(Write, equations, lag_ratio=0.3)
+
+# Near-simultaneous with slight cascade
+LaggedStart(*animations, lag_ratio=0.01)
+```
+
+---
+
+## Pacing Red Flags
+
+1. **More than 3 animations without a wait**: Viewer can't process. Add `self.wait(1)`.
+2. **Wait longer than 5 seconds**: Viewer gets bored. Either shorten or add subtle motion.
+3. **Formula appears without buildup**: Always Write() or Transform() equations, never just Add().
+4. **Camera moves during equation display**: Choose one focus. Move camera OR show math, not both.
+5. **More than 2 minutes without visual change**: Keep things moving. Transform, recolor, zoom.
+6. **Consistent speed throughout**: Vary the pace! Quick setups, slow reveals.
+
+---
+
+## The "Earned Wait" Principle
+
+The longest waits in 3b1b videos come AFTER the most significant reveals. The viewer has been building toward this moment, and the pause signals "this is important."
+
+```python
+# Bad: long wait after setup
+self.play(FadeIn(axes))
+self.wait(3)  # Why am I waiting? Nothing happened.
+
+# Good: long wait after insight
+self.play(FlashAround(result))
+self.wait(3)  # This is the moment. Let it breathe.
+```
+
+The wait time is proportional to the significance of what just happened.