manim-mcp 0.1.0

package/references/manimce/rules/long-form-video.md

@@ -0,0 +1,552 @@
+---
+name: long-form-video
+description: Comprehensive guide to structuring long-form math videos (15-30+ min) in the 3Blue1Brown style using ManimCE
+metadata:
+  tags: video-structure, narrative, pacing, transitions, scenes, long-form, 3b1b
+---
+
+# Long-Form Video Structure in ManimCE
+
+This guide captures the architectural patterns from 407 3Blue1Brown video files (2015-2026) for building coherent, long-form mathematical explainer videos.
+
+## Scene-Per-Section Architecture
+
+3b1b videos decompose into 10-40 individual Scene classes per video file. Each Scene class corresponds to one conceptual section of the video. Within each Scene, the `construct()` method is organized into commented sections that follow a clear narrative arc.
+
+### Method-Per-Section Pattern
+
+```python
+from manim import *
+
+class ExplainEigenvalues(MovingCameraScene):
+    """One section of a larger linear algebra video."""
+
+    def construct(self):
+        # Setup: establish the visual environment
+        self.setup_coordinate_plane()
+
+        # Introduce: present the concept with simple example
+        self.introduce_matrix_action()
+
+        # Demonstrate: show the key behavior
+        self.show_eigenvector_behavior()
+
+        # Deepen: build complexity
+        self.show_eigenvalue_equation()
+
+        # Conclude: transition to next topic
+        self.conclude_with_question()
+
+    def setup_coordinate_plane(self):
+        plane = NumberPlane()
+        plane.set_stroke(BLUE, 1, opacity=0.4)
+        basis_i = Vector([1, 0], color=GREEN)
+        basis_j = Vector([0, 1], color=RED)
+        i_label = MathTex(r"\hat{\imath}").next_to(basis_i, DOWN)
+        j_label = MathTex(r"\hat{\jmath}").next_to(basis_j, LEFT)
+        i_label.set_color(GREEN)
+        j_label.set_color(RED)
+
+        self.play(Create(plane), run_time=2)
+        self.play(
+            GrowArrow(basis_i), GrowArrow(basis_j),
+            Write(i_label), Write(j_label),
+        )
+        self.wait()
+
+        self.plane = plane
+        self.basis_vectors = VGroup(basis_i, basis_j)
+
+    def introduce_matrix_action(self):
+        matrix = Matrix([[3, 1], [0, 2]])
+        matrix.to_corner(UL)
+        self.play(Write(matrix))
+        self.wait()
+        self.matrix_mob = matrix
+
+    def show_eigenvector_behavior(self):
+        # Eigenvector stays on its span
+        eigen_vec = Vector([1, 0], color=YELLOW)
+        label = MathTex(r"\vec{v}", color=YELLOW)
+        label.next_to(eigen_vec, UP)
+        self.play(GrowArrow(eigen_vec), Write(label))
+        self.wait()
+
+        # After transformation, still on span but scaled
+        scaled_vec = Vector([3, 0], color=YELLOW)
+        self.play(
+            Transform(eigen_vec, scaled_vec),
+            run_time=2,
+        )
+        self.wait()
+
+    def show_eigenvalue_equation(self):
+        equation = MathTex(
+            r"A", r"\vec{v}", r"=", r"\lambda", r"\vec{v}",
+            tex_to_color_map={
+                r"\vec{v}": YELLOW,
+                r"\lambda": TEAL,
+                r"A": WHITE,
+            }
+        )
+        equation.to_edge(UP)
+        self.play(Write(equation))
+        self.wait(2)
+
+    def conclude_with_question(self):
+        question = Text("But how do we find these special vectors?")
+        question.scale(0.8)
+        question.to_edge(DOWN)
+        self.play(Write(question))
+        self.wait(2)
+        self.play(FadeOut(question))
+```
+
+## Composing 20+ Scenes Into a Video
+
+In 3b1b's workflow, a single Python file contains many Scene classes that together form one video. Scenes are rendered individually and concatenated. Here is the typical organization pattern:
+
+```python
+from manim import *
+
+# --- Constants used across all scenes ---
+FORMULA_COLOR = YELLOW
+GRAPH_COLOR = BLUE
+HIGHLIGHT_COLOR = GREEN
+
+# --- Section 1: Opening ---
+class OpeningQuote(Scene):
+    """Every EoLA/EoC chapter opens with a quote."""
+    def construct(self):
+        quote = Tex(
+            r"``There is hardly any theory which is more elementary \\"
+            r"than linear algebra, in spite of the fact that generations \\"
+            r"of professors and textbook writers have obscured its \\"
+            r"simplicity by preposterous calculations with matrices.''",
+            font_size=36,
+        )
+        quote.to_edge(UP, buff=1.0)
+        author = Text("-- Jean Dieudonne", color=YELLOW)
+        author.next_to(quote, DOWN, buff=1.0)
+
+        self.play(FadeIn(quote, lag_ratio=0.5, rate_func=linear, run_time=5))
+        self.wait(2)
+        self.play(Write(author, run_time=3))
+        self.wait()
+
+# --- Section 2: Introduce the Problem ---
+class IntroduceProblem(Scene):
+    def construct(self):
+        # Present the mystery first (see "Mystery First" pattern below)
+        ...
+
+# --- Section 3: Build Intuition ---
+class BuildIntuition(Scene):
+    def construct(self):
+        ...
+
+# --- Section 4: Formal Proof ---
+class FormalProof(Scene):
+    def construct(self):
+        ...
+
+# --- Section 5: End Screen ---
+class EndScreen(Scene):
+    def construct(self):
+        # Standard 3b1b end screen with two video recommendations
+        ...
+```
+
+### Scene Naming Conventions (from the codebase)
+
+- **Descriptive names**: `AttentionPatterns`, `IntroduceEulersFormula`, `ShowPattern`
+- **Teacher-student scenes**: `AskAboutPosition`, `ProblemSolvingRule1` (using `TeacherStudentsScene`)
+- **Simple utility scenes**: `SimpleRect`, `SimpleFEq` (small annotation clips)
+- **Supplement scenes**: placed in `supplements.py` for tangential content
+
+## Progressive Complexity Pattern
+
+Every 3b1b video follows: simple cases first, complex cases later. Concrete examples before abstract formulas.
+
+```python
+class ProgressiveComplexity(Scene):
+    def construct(self):
+        # Phase 1: Simplest possible case
+        simple_eq = MathTex(r"2 \times 3 = 6")
+        self.play(Write(simple_eq))
+        self.wait()
+
+        # Phase 2: Slightly more complex
+        medium_eq = MathTex(r"x^2 + y^2 = r^2")
+        self.play(
+            simple_eq.animate.shift(UP * 1.5).scale(0.7).set_opacity(0.5),
+            Write(medium_eq),
+        )
+        self.wait()
+
+        # Phase 3: The general case
+        general_eq = MathTex(
+            r"\sum_{n=0}^{\infty} \frac{f^{(n)}(a)}{n!}(x-a)^n"
+        )
+        self.play(
+            medium_eq.animate.shift(UP * 1.5).scale(0.7).set_opacity(0.5),
+            Write(general_eq),
+        )
+        self.wait(2)
+```
+
+## Pacing: wait(), run_time, and lag_ratio
+
+### self.wait() usage
+
+3b1b uses `self.wait()` generously, typically 1-2 seconds between concepts and up to `self.wait(2)` or `self.wait(3)` for important pauses where voiceover explains.
+
+```python
+# After revealing a key result, pause for the viewer
+self.play(Write(result))
+self.wait(2)  # Let it sink in
+
+# Quick pause between steps
+self.play(Create(arrow))
+self.wait()  # Default 1 second
+
+# Long pause for complex diagrams
+self.play(FadeIn(full_diagram))
+self.wait(3)  # Give viewer time to read everything
+```
+
+### run_time Control
+
+```python
+# Fast animations for simple transitions (0.5s)
+self.play(FadeOut(old_stuff), run_time=0.5)
+
+# Standard animations (1s default)
+self.play(Create(circle))
+
+# Slow, dramatic reveals (2-3s)
+self.play(Write(important_equation), run_time=2)
+
+# Very slow for complex transformations (3-5s)
+self.play(
+    Transform(plane, transformed_plane),
+    run_time=3,
+    rate_func=smooth,
+)
+```
+
+### lag_ratio for Staggered Effects
+
+The `lag_ratio` parameter is used extensively throughout the codebase for wave-like, cascading animations:
+
+```python
+# Staggered fade-in of word-by-word text
+words = VGroup(*[Text(w) for w in ["Hello", "beautiful", "world"]])
+words.arrange(RIGHT, buff=0.3)
+self.play(
+    LaggedStartMap(FadeIn, words, shift=0.5 * UP, lag_ratio=0.25)
+)
+
+# Cascading creation of bars in a chart
+bars = VGroup(*[Rectangle(height=h, width=0.3) for h in [1, 2, 3, 2, 1]])
+bars.arrange(RIGHT, buff=0.1, aligned_edge=DOWN)
+self.play(
+    LaggedStartMap(GrowFromEdge, bars, edge=DOWN, lag_ratio=0.15),
+    run_time=2,
+)
+
+# Lagged arrow growth
+arrows = VGroup(*[Arrow(ORIGIN, RIGHT) for _ in range(5)])
+self.play(
+    LaggedStartMap(GrowArrow, arrows, lag_ratio=0.2, run_time=1.5)
+)
+```
+
+## Transition Patterns Between Topics
+
+### FadeOut/FadeIn Group Transitions
+
+The most common pattern: fade out everything from the previous section, fade in the new section.
+
+```python
+class TransitionPatterns(Scene):
+    def construct(self):
+        # --- Section A content ---
+        title_a = Text("Linear Transformations")
+        diagram_a = NumberPlane()
+        section_a = VGroup(title_a, diagram_a)
+
+        self.play(Write(title_a), Create(diagram_a))
+        self.wait(2)
+
+        # --- Transition: clear and introduce next section ---
+        title_b = Text("Matrix Multiplication")
+        self.play(
+            FadeOut(section_a, shift=LEFT),
+            FadeIn(title_b, shift=RIGHT),
+        )
+
+        # --- Section B content ---
+        ...
+```
+
+### Zooming Transition (MovingCameraScene)
+
+```python
+class ZoomTransition(MovingCameraScene):
+    def construct(self):
+        overview = VGroup(
+            *[Circle(radius=0.5).shift(2 * d) for d in [LEFT, RIGHT, UP, DOWN]]
+        )
+        self.add(overview)
+
+        # Zoom into one element
+        target = overview[0]
+        self.play(
+            self.camera.frame.animate.set_width(3).move_to(target),
+            run_time=2,
+        )
+        self.wait()
+
+        # Zoom back out
+        self.play(
+            self.camera.frame.animate.set_width(14).move_to(ORIGIN),
+            run_time=2,
+        )
+```
+
+### Rearrangement Transition
+
+A 3b1b hallmark: instead of cutting, rearrange existing elements into a new configuration.
+
+```python
+# Move equation to corner, make room for diagram
+equation.generate_target()
+equation.target.scale(0.6).to_corner(UL)
+self.play(MoveToTarget(equation))
+
+# Or with .animate
+self.play(
+    equation.animate.scale(0.6).to_corner(UL),
+    FadeIn(new_diagram),
+)
+```
+
+## The "Mystery First" Pattern
+
+3b1b videos almost always open with a surprising or mysterious result, then spend the video explaining it. This is the signature pedagogical hook.
+
+```python
+class MysteryFirst(Scene):
+    """Pattern: Show the surprising result, THEN explain."""
+
+    def construct(self):
+        # Step 1: Show the surprising claim
+        claim = MathTex(r"1 + 2 + 4 + 8 + \cdots = -1")
+        claim.scale(1.5)
+        question_mark = Text("???", color=RED, font_size=72)
+        question_mark.next_to(claim, RIGHT)
+
+        self.play(Write(claim))
+        self.play(FadeIn(question_mark, scale=1.5))
+        self.wait(2)
+
+        # Step 2: "Let me show you what I mean..."
+        self.play(FadeOut(question_mark))
+        explanation_title = Text("Here's what's going on...")
+        explanation_title.to_edge(UP)
+        self.play(
+            claim.animate.scale(0.6).to_corner(UL),
+            Write(explanation_title),
+        )
+        self.wait()
+
+        # Step 3: Build up the explanation from scratch
+        # ... rest of the scene
+```
+
+### Moser's Circle Problem Pattern (Build false confidence, then reveal truth)
+
+From `_2023/moser_reboot/main.py` and `_2015/moser_main.py`:
+
+```python
+class BuildFalseConfidence(Scene):
+    """Show a pattern that LOOKS like powers of 2, then reveal it breaks."""
+
+    def construct(self):
+        # Reveal values one by one
+        values = [1, 2, 4, 8, 16, 31]  # NOT 32!
+        labels = VGroup()
+        for i, v in enumerate(values):
+            label = MathTex(str(v))
+            labels.add(label)
+            self.play(FadeIn(label, shift=0.25 * UP), run_time=0.5)
+            self.wait(0.5)
+
+        # Highlight the "pattern"
+        brace = Brace(labels[:5], DOWN)
+        pattern_text = brace.get_text("Powers of 2?")
+        self.play(GrowFromCenter(brace), Write(pattern_text))
+        self.wait(2)
+
+        # The reveal: it BREAKS
+        highlight = SurroundingRectangle(labels[-1], color=RED)
+        not_32 = MathTex(r"\neq 32", color=RED)
+        not_32.next_to(labels[-1], RIGHT)
+        self.play(Create(highlight), Write(not_32))
+        self.wait(2)
+```
+
+## Opening Quote Pattern
+
+Every Essence of Linear Algebra and Essence of Calculus chapter opens with a literary or mathematical quote. The ManimCE equivalent:
+
+```python
+class OpeningQuoteScene(Scene):
+    """Standard 3b1b opening quote."""
+
+    def construct(self):
+        quote_text = (
+            r"``The introduction of numbers as coordinates is an act of "
+            r"violence.'' "
+        )
+        quote = Tex(quote_text, font_size=40)
+        quote.set_width(FRAME_WIDTH - 2)
+        quote.to_edge(UP, buff=1.0)
+
+        author = Text("-- Hermann Weyl", color=YELLOW)
+        author.next_to(quote, DOWN, buff=1.0)
+
+        self.play(
+            FadeIn(quote, lag_ratio=0.5, rate_func=linear, run_time=5)
+        )
+        self.wait(2)
+        self.play(Write(author, run_time=3))
+        self.wait()
+```
+
+## End Screen Pattern
+
+3b1b videos end with a standard screen showing clickable video thumbnails and patron credits.
+
+```python
+class SimpleEndScreen(Scene):
+    """Simplified ManimCE end screen pattern."""
+
+    def construct(self):
+        # Black background with divider
+        divider = DashedLine(
+            FRAME_WIDTH / 2 * LEFT, FRAME_WIDTH / 2 * RIGHT
+        )
+        self.add(divider)
+
+        # Title
+        title = Text("Clicky Stuffs", font_size=54)
+        title.to_edge(UP, buff=0.3)
+        self.add(title)
+
+        # Video recommendation placeholders
+        screen1 = ScreenRectangle(height=2.5)
+        screen2 = ScreenRectangle(height=2.5)
+        screens = VGroup(screen1, screen2).arrange(RIGHT, buff=0.5)
+        screens.next_to(divider, UP, buff=0.5)
+
+        self.play(
+            FadeIn(screens, lag_ratio=0.3),
+            Write(title),
+        )
+
+        # Patron credits scroll
+        thanks = Text(
+            "These videos are funded by viewers.\n"
+            "Special thanks to channel supporters.",
+            font_size=24,
+            color=GREY_A,
+        )
+        thanks.next_to(divider, DOWN, buff=0.3)
+        self.play(Write(thanks))
+        self.wait(5)
+```
+
+## Comment-Driven Section Structure
+
+Inside every 3b1b `construct()` method, sections are separated by descriptive comments. This is the universal organizational pattern across all 407 files:
+
+```python
+def construct(self):
+    # Setup
+    axes = Axes(...)
+    self.add(axes)
+
+    # Show the function
+    graph = axes.plot(lambda x: x**2)
+    self.play(Create(graph))
+    self.wait()
+
+    # Highlight the derivative
+    tangent = ...
+    self.play(Create(tangent))
+    self.wait()
+
+    # Show the formula
+    formula = MathTex(...)
+    self.play(Write(formula))
+    self.wait(2)
+
+    # Transition to next concept
+    self.play(FadeOut(VGroup(graph, tangent, formula)))
+```
+
+## Scene Class Attributes for Configuration
+
+Instead of ManimGL's `CONFIG` dict pattern, ManimCE uses class attributes or `__init__` parameters:
+
+```python
+class ConfigurableScene(Scene):
+    """ManimCE pattern: use class attributes for configuration."""
+    wave_color = BLUE
+    wave_amplitude = 1.0
+    n_waves = 5
+    run_time = 30
+
+    def construct(self):
+        axes = Axes((-12, 12), (-4, 4))
+        for i in range(self.n_waves):
+            wave = axes.plot(
+                lambda x: self.wave_amplitude * np.sin(x + i),
+                color=self.wave_color,
+            )
+            self.play(Create(wave), run_time=0.5)
+        self.wait()
+```
+
+## Reusable Helper Functions
+
+Complex scenes extract helper functions (the `get_*` naming pattern):
+
+```python
+def get_labeled_vector(direction, label_text, color):
+    """Helper to create a consistently styled labeled vector."""
+    vec = Vector(direction, color=color)
+    label = MathTex(label_text, color=color, font_size=30)
+    label.next_to(vec.get_end(), normalize(direction), buff=0.1)
+    return VGroup(vec, label)
+
+def get_matrix_mob(entries, bracket_color=WHITE):
+    """Create a styled matrix mobject."""
+    m = Matrix(entries)
+    m.get_brackets().set_color(bracket_color)
+    return m
+```
+
+## Best Practices Summary
+
+1. **One Scene class per conceptual section** -- 10-40 scenes per video
+2. **Comment every section** inside `construct()` with `# Description`
+3. **Mystery first** -- open with the surprising result
+4. **Progressive complexity** -- simple to complex, concrete to abstract
+5. **Generous pauses** -- `self.wait(2)` after key reveals
+6. **Rearrange, don't cut** -- move existing elements rather than fade-out/fade-in when possible
+7. **Extract helpers** -- `get_*` functions for reusable mobject creation
+8. **Class attributes** for configuration, not `CONFIG` dicts
+9. **End with a question** -- each section should leave the viewer wanting the next one