manim-skill

## Project Structure

Create a dedicated folder for each animation project **in the user's current working directory** (NOT in this skill's base directory). Use this flat structure:

```
<project-name>/
├── plan.md              # Planning document (Phase 1)
├── script.py            # Manim code (Phase 2)
├── concat.txt           # ffmpeg scene list (Phase 3)
├── final.mp4            # Stitched output (Phase 3)
└── media/               # Auto-generated by manim
    └── videos/
        └── script/
            └── 480p15/  # or 1080p60
                ├── Scene1_Name.mp4
                ├── Scene2_Name.mp4
                └── ...
```

**Before starting**: Create the project folder and work from within it. All commands should be run from the project directory.

```bash
mkdir -p <project-name> && cd <project-name>
```

## Workflow Overview

```
Plan → Code → Render → Iterate
```

### Phase 1: Plan

**If the user has already used plan mode in claude code or provided detailed requirements, write that in `plan.md` and skip to Phase 2. Otherwise, you MUST carefully plan the video structure before writing code.**

Before writing any Manim code, wrtie `plan.md`:

```markdown
# [Video Title]

## Overview
- **Topic**: [Core concept]
- **Hook**: [Opening question/mystery]
- **Target Audience**: [Prerequisites]
- **Estimated Length**: [X minutes]
- **Key Insight**: [The "aha moment"]
- **Resolution**: [480p(default), 1080p]
- **Aspect Ratio**: [16:9(default) / 9:16 / 1:1]

## 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]

### Voiceover
- **Text**: "[Exact script or key points]"
- **Sync Points**: "[phrase]" → syncs with [animation]

### 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]

## Shared Elements
- [Recurring mobjects across scenes, e.g., "coordinate axes reappear in scenes 2, 4, 6"]
- [Visual motifs, e.g., "blue highlight for key terms"]

## Color Palette
- Primary: [color] - used for [purpose]
- Secondary: [color] - used for [purpose]
- Accent: [color] - used for [purpose]
- Background: [color]

```

### Phase 2: Code

**BEFORE writing any code, you MUST invoke the `manimce-best-practices` skill using the Skill tool, then read the relevant rule files it references (e.g., `rules/scenes.md`, `rules/animations.md`) based on what your video needs.**

Write Manim Community Edition code in `script.py`.

#### Code Structure
1. **One class per scene** - Name scenes descriptively: `Scene1_Introduction`, `Scene2_DerivePDE`
2. Always add subtitles to your animations with `add_subcaption()`
    - Manim generates a `.srt` file automatically
    - The viewer handles subtitle display and lets users toggle/resize them

```python
from manim import *

## Scene1_Introduction
class Scene1_Introduction(Scene):
    def construct(self):
        ## Scene1_Introduction.title
        title = Text("My Topic", font_size=48, color=BLUE)
        self.add_subcaption("Introducing our topic", duration=2)
        self.play(Write(title))
        self.wait(1)

        ## Scene1_Introduction.fadeout
        self.play(FadeOut(title), subcaption="Let's begin", subcaption_duration=1)
```

### Phase 3: Render

Use `manim` CLI to render scenes. Multiple scenes can be rendered in parallel with one command.

```bash
manim -q<quality> [--media_dir <output_dir>] <script.py> Scene1 Scene2 Scene3 ...
```

**Quality flags:**
- `-ql` - Low quality (480p15, fastest for testing. Use by default)
- `-qh` - High quality (1080p60, only when user explicitly requests)

**Output location:**
`/media/videos/<script_name>/<quality>/SceneName.mp4`

Default `/media` is located in current directory.

**If any scene fails:** Read the error, fix the code, re-render only the failed scenes.

#### Stitch scenes with ffmpeg

Once all scenes render successfully, combine them. All paths are relative to the project folder:

```bash
# Create concat list (run from project folder)
cat > concat.txt << 'EOF'
file 'media/videos/script/480p15/Scene1_Intro.mp4'
file 'media/videos/script/480p15/Scene2_Main.mp4'
file 'media/videos/script/480p15/Scene3_Conclusion.mp4'
EOF

# Combine videos
ffmpeg -y -f concat -safe 0 -i concat.txt -c copy final.mp4
```

**Result**: `final.mp4` is created in the project folder alongside `script.py` and `concat.txt`.

### Phase 4: Iterate on User Feedback

Launch the viewer for user to review and provide feedback (run from project folder):

```bash
python3 ../tools/video_viewer.py final.mp4 --order concat.txt [--script script.py]
```

- `--order`: Video order file (concat.txt, required for chapters)
- `--script`: Manim script (enables high-quality download option)

When user provides feedback:
1. Identify which scenes need changes
2. Modify the code
3. Re-render only affected scenes
4. Re-stitch the final video
5. Run the viewer command again