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