@prismer/runtime 2.0.8 → 2.2.63

package/built-in-skills/prismer-manim-video/SKILL.md

@@ -0,0 +1,279 @@
+---
+name: prismer-manim-video
+scope: common
+category: creative
+description: "Manim CE animations: 3Blue1Brown math/algo videos."
+version: 1.0.0
+author: SHL0MS, Hermes Agent
+license: MIT
+platforms: [ linux, macos, windows ]
+metadata:
+  nativeReplaces: [ manim-video ]
+  hermes:
+    tags: [ Manim, Animation, Math, Video ]
+    related_skills: []
+  requiresExplicitGrant: true
+---
+
+# Manim Video Production Pipeline
+
+## When to use
+
+Use when users request: animated explanations, math animations, concept visualizations, algorithm walkthroughs, technical explainers, 3Blue1Brown style videos, or any programmatic animation with geometric/mathematical content. Creates 3Blue1Brown-style explainer videos, algorithm visualizations, equation derivations, architecture diagrams, and data stories using Manim Community Edition.
+
+## Creative Standard
+
+This is educational cinema. Every frame teaches. Every animation reveals structure.
+
+**Before writing a single line of code**, articulate the narrative arc. What misconception does this correct? What is the "aha moment"? What visual story takes the viewer from confusion to understanding? The user's prompt is a starting point — interpret it with pedagogical ambition.
+
+**Geometry before algebra.** Show the shape first, the equation second. Visual memory encodes faster than symbolic memory. When the viewer sees the geometric pattern before the formula, the equation feels earned.
+
+**First-render excellence is non-negotiable.** The output must be visually clear and aesthetically cohesive without revision rounds. If something looks cluttered, poorly timed, or like "AI-generated slides," it is wrong.
+
+**Opacity layering directs attention.** Never show everything at full brightness. Primary elements at 1.0, contextual elements at 0.4, structural elements (axes, grids) at 0.15. The brain processes visual salience in layers.
+
+**Breathing room.** Every animation needs `self.wait()` after it. The viewer needs time to absorb what just appeared. Never rush from one animation to the next. A 2-second pause after a key reveal is never wasted.
+
+**Cohesive visual language.** All scenes share a color palette, consistent typography sizing, matching animation speeds. A technically correct video where every scene uses random different colors is an aesthetic failure.
+
+## Prerequisites
+
+Run `scripts/setup.sh` to verify all dependencies. Requires: Python 3.10+, Manim Community Edition v0.20+ (`pip install manim`), LaTeX (`texlive-full` on Linux, `mactex` on macOS), and ffmpeg. Reference docs tested against Manim CE v0.20.1.
+
+## Modes
+
+| Mode | Input | Output | Reference |
+|------|-------|--------|-----------|
+| **Concept explainer** | Topic/concept | Animated explanation with geometric intuition | `references/scene-planning.md` |
+| **Equation derivation** | Math expressions | Step-by-step animated proof | `references/equations.md` |
+| **Algorithm visualization** | Algorithm description | Step-by-step execution with data structures | `references/graphs-and-data.md` |
+| **Data story** | Data/metrics | Animated charts, comparisons, counters | `references/graphs-and-data.md` |
+| **Architecture diagram** | System description | Components building up with connections | `references/mobjects.md` |
+| **Paper explainer** | Research paper | Key findings and methods animated | `references/scene-planning.md` |
+| **3D visualization** | 3D concept | Rotating surfaces, parametric curves, spatial geometry | `references/camera-and-3d.md` |
+
+## Stack
+
+Single Python script per project. No browser, no Node.js, no GPU required.
+
+| Layer | Tool | Purpose |
+|-------|------|---------|
+| Core | Manim Community Edition | Scene rendering, animation engine |
+| Math | LaTeX (texlive/MiKTeX) | Equation rendering via `MathTex` |
+| Video I/O | ffmpeg | Scene stitching, format conversion, audio muxing |
+| TTS | ElevenLabs / Qwen3-TTS (optional) | Narration voiceover |
+
+## Pipeline
+
+```
+PLAN --> CODE --> RENDER --> STITCH --> AUDIO (optional) --> REVIEW
+```
+
+1. **PLAN** — Write `plan.md` with narrative arc, scene list, visual elements, color palette, voiceover script
+2. **CODE** — Write `script.py` with one class per scene, each independently renderable
+3. **RENDER** — `manim -ql script.py Scene1 Scene2 ...` for draft, `-qh` for production
+4. **STITCH** — ffmpeg concat of scene clips into `final.mp4`
+5. **AUDIO** (optional) — Add voiceover and/or background music via ffmpeg. See `references/rendering.md`
+6. **REVIEW** — Render preview stills, verify against plan, adjust
+
+## Project Structure
+
+```
+project-name/
+  plan.md                # Narrative arc, scene breakdown
+  script.py              # All scenes in one file
+  concat.txt             # ffmpeg scene list
+  final.mp4              # Stitched output
+  media/                 # Auto-generated by Manim
+    videos/script/480p15/
+```
+
+## Creative Direction
+
+### Color Palettes
+
+| Palette | Background | Primary | Secondary | Accent | Use case |
+|---------|-----------|---------|-----------|--------|----------|
+| **Classic 3B1B** | `#1C1C1C` | `#58C4DD` (BLUE) | `#83C167` (GREEN) | `#FFFF00` (YELLOW) | General math/CS |
+| **Warm academic** | `#2D2B55` | `#FF6B6B` | `#FFD93D` | `#6BCB77` | Approachable |
+| **Neon tech** | `#0A0A0A` | `#00F5FF` | `#FF00FF` | `#39FF14` | Systems, architecture |
+| **Monochrome** | `#1A1A2E` | `#EAEAEA` | `#888888` | `#FFFFFF` | Minimalist |
+
+### Animation Speed
+
+| Context | run_time | self.wait() after |
+|---------|----------|-------------------|
+| Title/intro appear | 1.5s | 1.0s |
+| Key equation reveal | 2.0s | 2.0s |
+| Transform/morph | 1.5s | 1.5s |
+| Supporting label | 0.8s | 0.5s |
+| FadeOut cleanup | 0.5s | 0.3s |
+| "Aha moment" reveal | 2.5s | 3.0s |
+
+### Typography Scale
+
+| Role | Font size | Usage |
+|------|-----------|-------|
+| Title | 48 | Scene titles, opening text |
+| Heading | 36 | Section headers within a scene |
+| Body | 30 | Explanatory text |
+| Label | 24 | Annotations, axis labels |
+| Caption | 20 | Subtitles, fine print |
+
+### Fonts
+
+**Use monospace fonts for all text.** Manim's Pango renderer produces broken kerning with proportional fonts at all sizes. See `references/visual-design.md` for full recommendations.
+
+```python
+MONO = "Menlo"  # define once at top of file
+
+Text("Fourier Series", font_size=48, font=MONO, weight=BOLD)  # titles
+Text("n=1: sin(x)", font_size=20, font=MONO)                  # labels
+MathTex(r"\nabla L")                                            # math (uses LaTeX)
+```
+
+Minimum `font_size=18` for readability.
+
+### Per-Scene Variation
+
+Never use identical config for all scenes. For each scene:
+- **Different dominant color** from the palette
+- **Different layout** — don't always center everything
+- **Different animation entry** — vary between Write, FadeIn, GrowFromCenter, Create
+- **Different visual weight** — some scenes dense, others sparse
+
+## Workflow
+
+### Step 1: Plan (plan.md)
+
+Before any code, write `plan.md`. See `references/scene-planning.md` for the comprehensive template.
+
+### Step 2: Code (script.py)
+
+One class per scene. Every scene is independently renderable.
+
+```python
+from manim import *
+
+BG = "#1C1C1C"
+PRIMARY = "#58C4DD"
+SECONDARY = "#83C167"
+ACCENT = "#FFFF00"
+MONO = "Menlo"
+
+class Scene1_Introduction(Scene):
+    def construct(self):
+        self.camera.background_color = BG
+        title = Text("Why Does This Work?", font_size=48, color=PRIMARY, weight=BOLD, font=MONO)
+        self.add_subcaption("Why does this work?", duration=2)
+        self.play(Write(title), run_time=1.5)
+        self.wait(1.0)
+        self.play(FadeOut(title), run_time=0.5)
+```
+
+Key patterns:
+- **Subtitles** on every animation: `self.add_subcaption("text", duration=N)` or `subcaption="text"` on `self.play()`
+- **Shared color constants** at file top for cross-scene consistency
+- **`self.camera.background_color`** set in every scene
+- **Clean exits** — FadeOut all mobjects at scene end: `self.play(FadeOut(Group(*self.mobjects)))`
+
+### Step 3: Render
+
+```bash
+manim -ql script.py Scene1_Introduction Scene2_CoreConcept  # draft
+manim -qh script.py Scene1_Introduction Scene2_CoreConcept  # production
+```
+
+### Step 4: Stitch
+
+```bash
+cat > concat.txt << 'EOF'
+file 'media/videos/script/480p15/Scene1_Introduction.mp4'
+file 'media/videos/script/480p15/Scene2_CoreConcept.mp4'
+EOF
+ffmpeg -y -f concat -safe 0 -i concat.txt -c copy final.mp4
+```
+
+### Step 5: Review
+
+```bash
+manim -ql --format=png -s script.py Scene2_CoreConcept  # preview still
+```
+
+## Critical Implementation Notes
+
+### Raw Strings for LaTeX
+```python
+# WRONG: MathTex("\frac{1}{2}")
+# RIGHT:
+MathTex(r"\frac{1}{2}")
+```
+
+### buff >= 0.5 for Edge Text
+```python
+label.to_edge(DOWN, buff=0.5)  # never < 0.5
+```
+
+### FadeOut Before Replacing Text
+```python
+self.play(ReplacementTransform(note1, note2))  # not Write(note2) on top
+```
+
+### Never Animate Non-Added Mobjects
+```python
+self.play(Create(circle))  # must add first
+self.play(circle.animate.set_color(RED))  # then animate
+```
+
+## Performance Targets
+
+| Quality | Resolution | FPS | Speed |
+|---------|-----------|-----|-------|
+| `-ql` (draft) | 854x480 | 15 | 5-15s/scene |
+| `-qm` (medium) | 1280x720 | 30 | 15-60s/scene |
+| `-qh` (production) | 1920x1080 | 60 | 30-120s/scene |
+
+Always iterate at `-ql`. Only render `-qh` for final output.
+
+## References
+
+| File | Contents |
+|------|----------|
+| `references/animations.md` | Core animations, rate functions, composition, `.animate` syntax, timing patterns |
+| `references/mobjects.md` | Text, shapes, VGroup/Group, positioning, styling, custom mobjects |
+| `references/visual-design.md` | 12 design principles, opacity layering, layout templates, color palettes |
+| `references/equations.md` | LaTeX in Manim, TransformMatchingTex, derivation patterns |
+| `references/graphs-and-data.md` | Axes, plotting, BarChart, animated data, algorithm visualization |
+| `references/camera-and-3d.md` | MovingCameraScene, ThreeDScene, 3D surfaces, camera control |
+| `references/scene-planning.md` | Narrative arcs, layout templates, scene transitions, planning template |
+| `references/rendering.md` | CLI reference, quality presets, ffmpeg, voiceover workflow, GIF export |
+| `references/troubleshooting.md` | LaTeX errors, animation errors, common mistakes, debugging |
+| `references/animation-design-thinking.md` | When to animate vs show static, decomposition, pacing, narration sync |
+| `references/updaters-and-trackers.md` | ValueTracker, add_updater, always_redraw, time-based updaters, patterns |
+| `references/paper-explainer.md` | Turning research papers into animations — workflow, templates, domain patterns |
+| `references/decorations.md` | SurroundingRectangle, Brace, arrows, DashedLine, Angle, annotation lifecycle |
+| `references/production-quality.md` | Pre-code, pre-render, post-render checklists, spatial layout, color, tempo |
+
+---
+
+## Creative Divergence (use only when user requests experimental/creative/unique output)
+
+If the user asks for creative, experimental, or unconventional explanatory approaches, select a strategy and reason through it BEFORE designing the animation.
+
+- **SCAMPER** — when the user wants a fresh take on a standard explanation
+- **Assumption Reversal** — when the user wants to challenge how something is typically taught
+
+### SCAMPER Transformation
+Take a standard mathematical/technical visualization and transform it:
+- **Substitute**: replace the standard visual metaphor (number line → winding path, matrix → city grid)
+- **Combine**: merge two explanation approaches (algebraic + geometric simultaneously)
+- **Reverse**: derive backward — start from the result and deconstruct to axioms
+- **Modify**: exaggerate a parameter to show why it matters (10x the learning rate, 1000x the sample size)
+- **Eliminate**: remove all notation — explain purely through animation and spatial relationships
+
+### Assumption Reversal
+1. List what's "standard" about how this topic is visualized (left-to-right, 2D, discrete steps, formal notation)
+2. Pick the most fundamental assumption
+3. Reverse it (right-to-left derivation, 3D embedding of a 2D concept, continuous morphing instead of steps, zero notation)
+4. Explore what the reversal reveals that the standard approach hides

package/built-in-skills/prismer-manim-video/references/animation-design-thinking.md

@@ -0,0 +1,161 @@
+# Animation Design Thinking
+
+How to decide WHAT to animate and HOW to structure it — before writing any code.
+
+## Should I animate this?
+
+Not everything benefits from animation. Motion adds cognitive load. Bad animation is worse than a good static diagram.
+
+**Animate when:**
+- A sequence unfolds over time (algorithm steps, derivation, pipeline stages)
+- Spatial relationships change (transformation, deformation, rotation)
+- Something is built from parts (construction, assembly, accumulation)
+- You're comparing states (before/after, method A vs method B)
+- Temporal evolution is the point (training curves, wave propagation, gradient descent)
+
+**Show static when:**
+- The concept is a single labeled diagram (circuit, anatomy, architecture overview)
+- Motion would distract from spatial layout
+- The viewer needs to study it carefully (dense table, reference chart)
+- The concept is already intuitive from a well-labeled figure
+
+**Rule of thumb:** If you'd explain it with "first X, then Y, then Z" — animate it. If you'd explain it by pointing at parts of one picture — show it static.
+
+## Decomposing a concept into animation
+
+### Step 1: Write the narration first
+
+Before any code, write what the narrator would say. This determines:
+- **Order** — what concept comes first
+- **Duration** — how long each idea gets
+- **Visuals** — what the viewer must SEE when they HEAR each sentence
+
+A scene where the narration says "the gradient points uphill" must show a gradient arrow at that moment. If the visual doesn't match the audio, the viewer's brain splits attention and both tracks are lost.
+
+### Step 2: Identify visual beats
+
+A "beat" is a moment where something changes on screen. Mark each beat in your narration:
+
+```
+"Consider a function f of x."         → [BEAT: axes + curve appear]
+"At this point..."                     → [BEAT: dot appears on curve]
+"...the slope is positive."            → [BEAT: tangent line drawn]
+"So the gradient tells us to go left." → [BEAT: arrow points left, dot moves]
+```
+
+Each beat is one `self.play()` call or a small group of simultaneous animations.
+
+### Step 3: Choose the right tool per beat
+
+| Visual need | Manim approach |
+|-------------|----------------|
+| Object appears for first time | `Create`, `Write`, `FadeIn`, `GrowFromCenter` |
+| Object transforms into another | `Transform`, `ReplacementTransform`, `FadeTransform` |
+| Attention drawn to existing object | `Indicate`, `Circumscribe`, `Flash`, `ShowPassingFlash` |
+| Continuous relationship maintained | `add_updater`, `always_redraw`, `ValueTracker` |
+| Object leaves the scene | `FadeOut`, `Uncreate`, `ShrinkToCenter` |
+| Static context that stays visible | `self.add()` (no animation) |
+
+## Pacing: the universal mistake is too fast
+
+### Timing rules
+
+| Content type | Minimum on-screen time |
+|-------------|----------------------|
+| New equation appearing | 2.0s animation + 2.0s pause |
+| New concept label | 1.0s animation + 1.0s pause |
+| Key insight ("aha moment") | 2.5s animation + 3.0s pause |
+| Supporting annotation | 0.8s animation + 0.5s pause |
+| Scene transition (FadeOut all) | 0.5s animation + 0.3s pause |
+
+### Breathing room
+
+After every reveal, add `self.wait()`. The viewer needs time to:
+1. Read the new text
+2. Connect it to what's already on screen
+3. Form an expectation about what comes next
+
+**No wait = the viewer is always behind you.** They're still reading the equation when you've already started transforming it.
+
+### Tempo variation
+
+Monotonous pacing feels like a lecture. Vary the tempo:
+- **Slow build** for core concepts (long run_time, long pauses)
+- **Quick succession** for supporting details (short run_time, minimal pauses)
+- **Dramatic pause** before the key reveal (extra `self.wait(2.0)` before the "aha")
+- **Rapid montage** for "and this applies to X, Y, Z..." sequences (`LaggedStart` with tight lag_ratio)
+
+## Narration synchronization
+
+### The "see then hear" principle
+
+The visual should appear slightly BEFORE the narration describes it. When the viewer sees a circle appear and THEN hears "consider a circle," the visual primes their brain for the concept. The reverse — hearing first, seeing second — creates confusion because they're searching the screen for something that isn't there yet.
+
+### Practical timing
+
+```python
+# Scene duration should match narration duration.
+# If narration for this scene is 8 seconds:
+# Total animation run_times + total self.wait() times = ~8 seconds.
+
+# Use manim-voiceover for automatic sync:
+with self.voiceover(text="The gradient points downhill") as tracker:
+    self.play(GrowArrow(gradient_arrow), run_time=tracker.duration)
+```
+
+## Equation decomposition strategy
+
+### The "dim and reveal" pattern
+
+When building a complex equation step by step:
+1. Show the full equation dimmed at `opacity=0.2` (sets expectation for where you're going)
+2. Highlight the first term at full opacity
+3. Explain it
+4. Highlight the next term, dim the first to `0.5` (it's now context)
+5. Repeat until the full equation is bright
+
+This is better than building left-to-right because the viewer always sees the destination.
+
+### Term ordering
+
+Animate terms in the order the viewer needs to understand them, not in the order they appear in the equation. For `E = mc²`:
+- Show `E` (the thing we want to know)
+- Then `m` (the input)
+- Then `c²` (the constant that makes it work)
+- Then the `=` (connecting them)
+
+## Architecture and pipeline diagrams
+
+### Box granularity
+
+The most common mistake: too many boxes. Each box is a concept the viewer must track. Five boxes with clear labels beats twelve boxes with abbreviations.
+
+**Rule:** If two consecutive boxes could be labeled "X" and "process X output," merge them into one box.
+
+### Animation strategy
+
+Build pipelines left-to-right (or top-to-bottom) with arrows connecting them:
+1. First box appears alone → explain it
+2. Arrow grows from first to second → "the output feeds into..."
+3. Second box appears → explain it
+4. Repeat
+
+Then show data flowing through: `ShowPassingFlash` along the arrows, or a colored dot traversing the path.
+
+### The zoom-and-return pattern
+
+For complex systems:
+1. Show the full overview (all boxes, small)
+2. Zoom into one box (`MovingCameraScene.camera.frame.animate`)
+3. Expand that box into its internal components
+4. Zoom back out to the overview
+5. Zoom into the next box
+
+## Common design mistakes
+
+1. **Animating everything at once.** The viewer can track 1-2 simultaneous animations. More than that and nothing registers.
+2. **No visual hierarchy.** Everything at the same opacity/size/color means nothing stands out. Use opacity layering.
+3. **Equations without context.** An equation appearing alone means nothing. Always show the geometric/visual interpretation first or simultaneously.
+4. **Skipping the "why."** Showing HOW a transformation works without WHY it matters. Add a sentence/label explaining the purpose.
+5. **Identical pacing throughout.** Every animation at run_time=1.5, every wait at 1.0. Vary it.
+6. **Forgetting the audience.** A video for high schoolers needs different pacing and complexity than one for PhD students. Decide the audience in the planning phase.