Manim Animation: Animation + Voiceover + Subtitle Generator

Author: ericksun（孙自翔）

Overview

This skill uses Manim Community to generate mathematical/educational animations, with manim-voiceover plugin integration for TTS voice narration and synchronized subtitles. All processing runs locally — no paid API required.

Core Capabilities:

• - 🎬 Animation Generation: Create animations of math formulas, geometric shapes, charts, and more with Manim
• 🎙️ Voice Narration: Integrate TTS via manim-voiceover plugin with automatic animation-voice sync
• 📝 Subtitle System: In-scene subtitles (Manim Text) + SRT external subtitles (ffmpeg burn-in)
• 🔄 One-Click Pipeline: Describe requirements → Generate code → Render video → Burn subtitles

TTS Engines (gTTS preferred):

• - gTTS (Recommended): Google free TTS, supports Chinese, no API Key needed
• pyttsx3 (Fallback): Offline TTS, no network required
• Azure/OpenAI/ElevenLabs (High quality): Requires paid API Key

Prerequisites

🔍 One-Click Environment Check

Before first use, run the environment check script to verify all dependencies are ready:

CODEBLOCK0

This script checks:

• - ✅ Manim Community installation (manim command)
• ✅ manim-voiceover + gTTS plugin
• ✅ FFmpeg + libx264 encoder (hardcoded Manim dependency, required)
• ✅ FFmpeg + libass (for SRT subtitle burn-in)
• ✅ Python dependencies
• ✅ Chinese font availability

Required System Tools

• - Manim Community: INLINECODE1
• FFmpeg (with libx264 + libass): Manim hardcodes the libx264 encoder for video rendering; subtitle burn-in requires INLINECODE3

- macOS (Homebrew): brew install ffmpeg (includes x264 and libass by default) - macOS (Conda): conda install x264 -c conda-forge (⚠️ conda's ffmpeg does not include libx264 by default) - Linux: sudo apt install ffmpeg libx264-dev libass-dev

• - Python 3.9+ and pip

Required Python Packages

CODEBLOCK1

Optional (Enhanced Features)

• - pyttsx3: Offline TTS (pip install "manim-voiceover[pyttsx3]")

⚡ Quick Install

CODEBLOCK2

Workflow

Quick Start — One-Click Run

After the user describes their requirements, use the pipeline script for one-click execution:

CODEBLOCK3

Common Options:

Option	Default	Description
INLINECODE8	Required	Manim scene Python file
INLINECODE9

Required | Scene class name |
| --quality | high | Render quality: low/medium/high/production |
| --burn_subtitles | False | Whether to burn SRT subtitles with ffmpeg |
| --speed | 1.35 | Playback speed multiplier (e.g., 1.35 means 1.35x speed; set to 1.0 to disable) |
| --preview | False | Auto-open preview after rendering |
| --output_dir | ./output | Output directory |

Complete Workflow (4 Steps)

Step 1: Understand User Requirements and Generate Manim Scene Code

Based on the user's description, generate a Manim scene Python file. Scene code should follow these patterns:

No-voiceover mode (animation only):

CODEBLOCK4

Voiceover mode (animation + voice + subtitles):

CODEBLOCK5

Key Pattern — voiceover context manager:

CODEBLOCK6

INLINECODE22 does three things:

1. 1. Calls the TTS engine to generate speech audio
2. Automatically calculates speech duration
3. Provides tracker.duration to sync animations with voice

Subtitle Best Practices:

• - In-scene subtitles: Use the _make_subtitle() helper to display white bold text with dark background at the bottom of the screen
• Overflow prevention: _make_subtitle() auto-detects subtitle width and scales proportionally (scale_to_fit_width) when exceeding frame bounds; uses font_size=22 for long text
• Subtitle sync: FadeIn(sub) in the first self.play() within the voiceover block ensures subtitles appear in sync with voice — do not delay
• FadeIn subtitle at the start of each voiceover block, FadeOut after it ends
• Subtitle text should match the voiceover text

⚠️ Avoid Double Subtitles: If the scene code already uses _make_subtitle() to render in-scene subtitles, do not also use --burn_subtitles to burn SRT subtitles, otherwise two overlapping subtitle layers will appear. Choose only one approach:

• - Option A (Recommended): Render subtitles in code with _make_subtitle(), do not burn SRT
• Option B: Do not render subtitles in code, burn SRT via INLINECODE33

Step 2: Configure Rendering Parameters

Create manim.cfg in the same directory as the scene file:

CODEBLOCK7

Quality Reference Table:

Quality	Flag	Resolution	FPS	manim.cfg Value
Low	-ql	480p	15	lowquality
Medium

-qm | 720p | 30 | mediumquality |
| High | -qh | 1080p | 60 | high_quality |
| Production | -qp | 2160p | 60 | production_quality |

Step 3: Render Video

CODEBLOCK8

Output path pattern: INLINECODE35

Step 4: Burn SRT Subtitles (Optional)

manim-voiceover automatically generates .srt subtitle files in the same directory as the video. Burn with ffmpeg:

CODEBLOCK9

⚠️ Double Subtitle Pitfall: If the scene Python code already renders in-scene subtitles with _make_subtitle(), do not also burn SRT subtitles, otherwise two overlapping subtitle layers will appear.

Note: ffmpeg requires libass support. On macOS, brew install ffmpeg typically includes it. Conda environments may require conda install x264 -c conda-forge.

Step 5: Speed Up Video (Optional)

Use ffmpeg to speed up the video, default 1.35x:

CODEBLOCK10

Note: Speed-up should be the final output step. If the scene code has in-scene subtitles (_make_subtitle), the speed-up input should use the original video (not the SRT-burned version) to avoid double subtitles. The run_pipeline.py --speed parameter handles this logic automatically.

Manim Common Animation Reference

Create/Display Animations

• - Write(text) — Write text
• INLINECODE44 — Draw shapes
• INLINECODE45 / FadeOut(mobject) — Fade in/out
• INLINECODE47 — Draw border then fill

Transform Animations

• - Transform(source, target) — Morph
• INLINECODE49 — Replacement morph
• INLINECODE50 — Shape-matching morph

Move/Scale

• - mobject.animate.to_edge(UP) — Move to edge
• INLINECODE52 — Translate
• INLINECODE53 — Scale
• INLINECODE54 — Rotate

Common Objects

• - Text("Text", font_size=48, color=BLUE) — Text
• INLINECODE56 — LaTeX formula
• INLINECODE57 — Circle
• INLINECODE58 — Square
• INLINECODE59 — Arrow
• INLINECODE60 — Coordinate plane
• INLINECODE61 — Axes

Grouping and Layout

• - VGroup(obj1, obj2) — Vertical group
• INLINECODE63 — Horizontal arrangement
• INLINECODE64 — Background rectangle

Known Issues and Solutions

⚠️ Missing libx264 Codec (Most Common Issue)

Symptom: INLINECODE65

Root Cause: Manim hardcodes the libx264 encoder in scene_file_writer.py (cannot be overridden via config/cfg), but conda environment's ffmpeg is compiled with --disable-gpl and does not include the GPL-licensed libx264.

Solution:
CODEBLOCK11

Note: brew install ffmpeg installs ffmpeg with built-in x264, but conda environments prioritize their own ffmpeg and will not use the Homebrew version.

setuptools Compatibility

manim-voiceover depends on pkg_resources, which may fail on Python 3.12+: CODEBLOCK12

ffmpeg Missing libass

SRT subtitle burn-in requires libass. macOS: CODEBLOCK13

Linux:
CODEBLOCK14

gTTS Network Issues

gTTS requires access to Google TTS service. If network is unavailable, switch to pyttsx3 offline engine: CODEBLOCK15

Chinese Fonts

Manim uses system fonts to render Text objects. Ensure Chinese fonts are available:

• - macOS: PingFang SC (built-in)
• Linux: INLINECODE73
• Specify font: INLINECODE74

Related Resources

• - GitHub Repository: https://github.com/hzsunzixiang/manim-animation-skill
• Manim Technical Guide: references/manim_guide.md — Detailed Manim + voiceover + subtitle technical documentation
• Environment Check Script: scripts/check_environment.py — One-click dependency check
• Render Pipeline Script: scripts/run_pipeline.py — One-click render + subtitle burn-in