Manim 动画：动画 + 语音旁白 + 字幕生成器

作者： ericksun（孙自翔）

概述

本技能基于 Manim Community 构建，用于生成数学/教育类动画，并通过集成 manim-voiceover 插件实现 TTS 语音旁白与同步字幕。所有处理均在本地完成，无需调用付费 API。

核心能力：

• 🎬 动画生成：使用 Manim 创建数学公式、几何图形、图表等动画
• 🎙️ 语音旁白：通过 manim-voiceover 插件集成 TTS，自动实现动画与语音的精准同步
• 📝 字幕系统：支持场景内字幕（Manim Text）与外部 SRT 字幕（ffmpeg 烧录）双模式
• 🔄 一键流水线：描述需求 → 生成代码 → 渲染视频 → 烧录字幕

TTS 引擎（推荐 gTTS）：

• gTTS（推荐）：Google 免费 TTS，支持中文，无需 API Key
• pyttsx3（备用）：离线 TTS，无需网络连接
• Azure/OpenAI/ElevenLabs（高音质）：需提供付费 API Key

前置条件

🔍 一键环境检查

首次使用前，请运行环境检查脚本，验证所有依赖是否就绪：

python3 {SKILL_DIR}/scripts/check_environment.py

该脚本将检查以下项目：

• ✅ Manim Community 安装状态（可执行 manim 命令）
• ✅ manim-voiceover + gTTS 插件安装状态
• ✅ FFmpeg 及 libx264 编码器（Manim 硬编码依赖，必需）
• ✅ FFmpeg 及 libass（用于 SRT 字幕烧录）
• ✅ Python 依赖包
• ✅ 中文字体可用性

必需系统工具

• Manim Community：pip install manim
• FFmpeg（需包含 libx264 + libass）：Manim 在视频渲染中硬编码使用 libx264 编码器；字幕烧录需 libass
  • macOS（Homebrew）：brew install ffmpeg（默认包含 x264 和 libass）
  • macOS（Conda）：conda install x264 -c conda-forge（⚠️ Conda 版本的 ffmpeg 默认不包含 libx264）
  • Linux：sudo apt install ffmpeg libx264-dev libass-dev
• Python 3.9+ 及 pip

必需 Python 包

# 核心依赖
pip install manim

# 语音旁白 + TTS
pip install "manim-voiceover[gtts]"

可选（增强功能）

• pyttsx3：离线 TTS（pip install "manim-voiceover[pyttsx3]"）

⚡ 快速安装

pip install manim "manim-voiceover[gtts]"

# macOS（Homebrew）——推荐，已含 libx264 + libass
brew install ffmpeg

# macOS（Conda）——需额外安装 x264，否则 Manim 渲染将因 UnknownCodecError: libx264 失败
conda install x264 -c conda-forge

# 验证 ffmpeg 是否支持 libx264 和 libass
ffmpeg -codecs 2>&1 | grep libx264     # 应显示：encoders: libx264
ffmpeg -filters 2>&1 | grep subtitles  # 应显示：subtitles filter

工作流

快速开始 —— 一键运行

用户描述需求后，可通过流水线脚本一键执行全流程：

python3 {SKILL_DIR}/scripts/run_pipeline.py 
    --scene_file  
    --scene_name  
    --quality high 
    --burn_subtitles

常用参数说明：

完整工作流（共 4 步）

第 1 步：理解用户需求并生成 Manim 场景代码

根据用户描述，生成符合规范的 Manim 场景 Python 文件。代码应遵循以下模式：

无语音旁白模式（仅动画）：

from manim import *

class MyScene(Scene):
    def construct(self):
        title = Text("标题", font_size=48, color=BLUE)
        self.play(Write(title))
        self.wait(1)

语音旁白模式（动画 + 语音 + 字幕）：

from manim import *
from manim_voiceover import VoiceoverScene
from manim_voiceover.services.gtts import GTTSService

class MyScene(VoiceoverScene):
    def _make_subtitle(self, text_str):
        """创建带深色背景的底部居中字幕。"""
        sub = Text(text_str, font_size=22, color=WHITE, weight=BOLD)
        # 防止字幕超出左右边界
        max_width = config.frame_width - 1.0  # 每侧预留 0.5 单位边距
        if sub.width > max_width:
            sub.scale_to_fit_width(max_width)
        sub.to_edge(DOWN, buff=0.4)
        bg = BackgroundRectangle(sub, color=BLACK, fill_opacity=0.6, buff=0.15)
        return VGroup(bg, sub)

    def construct(self):
        self.set_speech_service(GTTSService(lang="en"))

        sub_text = "欢迎观看演示"
        with self.voiceover(text=sub_text) as tracker:
            sub = self._make_subtitle(sub_text)
            title = Text("Demo", font_size=48)
            self.play(Write(title), FadeIn(sub), run_time=tracker.duration)

        self.play(FadeOut(sub))
        self.wait(0.3)

关键模式 —— voiceover 上下文管理器：

with self.voiceover(text="语音文本") as tracker:
    # tracker.duration = TTS 语音时长（秒）
    # 此区块内所有动画将自动与语音同步
    self.play(SomeAnimation(), run_time=tracker.duration)

with self.voiceover(text=...) as tracker 执行三项操作：

1. 调用 TTS 引擎生成语音音频
2. 自动计算语音总时长
3. 提供 tracker.duration 供动画与语音对齐

字幕最佳实践：

• 场景内字幕：使用 _make_subtitle() 辅助函数，在屏幕底部渲染白色粗体文字+深色背景
• 防溢出：_make_subtitle() 自动检测字幕宽度，若超出画面范围则按比例缩放（scale_to_fit_width）；长文本建议采用 font_size=22
• 字幕同步：在 voiceover 块内的 首个 self.play() 中使用 FadeIn(sub)，确保字幕与语音起始严格同步 —— 切勿延迟
• 每个 voiceover 块开始时 FadeIn 字幕，结束后 FadeOut
• 字幕文本必须与 voiceover 文本完全一致

⚠️ 避免双重字幕：若场景代码已使用 _make_subtitle() 渲染场景内字幕，则切勿同时启用 --burn_subtitles 烧录 SRT 字幕，否则将出现两层重叠字幕。请二选一：

• 选项 A（推荐）：在代码中渲染字幕（_make_subtitle()），不烧录 SRT
• 选项 B：不在代码中渲染字幕，通过 --burn_subtitles 烧录 SRT

第 2 步：配置渲染参数

在场景文件同级目录下创建 manim.cfg：

[CLI]
quality = high_quality
preview = False

[ffmpeg]
video_codec = h264

质量对照表：

第 3 步：渲染视频

manim render  

输出路径格式：media/videos///.mp4

第 4 步：烧录 SRT 字幕（可选）

manim-voiceover 会自动在视频所在目录生成 .srt 字幕文件。使用 ffmpeg 烧录：

ffmpeg -y -i  
    -vf "subtitles=:force_style='FontSize=22,PrimaryColour=&H00FFFFFF,OutlineColour=&H00000000,Outline=2,BackColour=&H80000000,BorderStyle=4,MarginV=30'" 
    -c:a copy 
    

⚠️ 双重字幕陷阱：若场景 Python 代码已通过 _make_subtitle() 渲染了场景内字幕，则切勿再烧录 SRT 字幕，否则将出现两层重叠字幕。

注意：ffmpeg 需启用 libass 支持。macOS 下 brew install ffmpeg 通常已包含；Conda 环境可能需要额外执行 conda install x264 -c conda-forge。

第 5 步：加速视频（可选）

使用 ffmpeg 加速视频，默认 1.35 倍速：

SPEED=1.35
ffmpeg -y -i  
    -filter_complex "[0:v]setpts=PTS/${SPEED}[v];[0:a]atempo=${SPEED}[a]" 
    -map "[v]" -map "[a]" 
    

注意：加速应作为最终输出步骤。若场景代码中已含场景内字幕（_make_subtitle），则加速输入应使用原始视频（而非已烧录 SRT 的版本），以避免双重字幕。run_pipeline.py 的 --speed 参数已自动处理此逻辑。

Manim 常用动画参考

创建/显示动画

• Write(text) —— 逐字写出文本
• Create(mobject) —— 绘制图形对象
• FadeIn(mobject) / FadeOut(mobject) —— 淡入/淡出
• DrawBorderThenFill(mobject) —— 先绘制边框再填充

变换动画

• Transform(source, target) —— 形态渐变（morph）
• ReplacementTransform(source, target) —— 替换式渐变
• TransformMatchingShapes(source, target) —— 形状匹配渐变

移动/缩放

• mobject.animate.to_edge(UP) —— 移至画面边缘
• mobject.animate.shift(RIGHT * 2) —— 平移
• mobject.animate.scale(2) —— 缩放
• Rotate(mobject, angle=PI) —— 旋转

常用对象

• Text("文本", font_size=48, color=BLUE) —— 文本对象
• MathTex(r"e^{i\pi}+1=0") —— LaTeX 公式
• Circle(radius=1, color=RED) —— 圆形
• Square(side_length=2, color=GREEN) —— 正方形
• Arrow(start, end) —— 箭头
• NumberPlane() —— 坐标平面
• Axes(x_range, y_range) —— 坐标轴

分组与布局

• VGroup(obj1, obj2) —— 垂直分组
• group.arrange(RIGHT, buff=0.5) —— 水平排列
• BackgroundRectangle(obj, color=BLACK, fill_opacity=0.6) —— 背景矩形

已知问题与解决方案

⚠️ 缺失 libx264 编码器（最常见问题）

现象：UnknownCodecError: libx264

根本原因：Manim 在 scene_file_writer.py 中硬编码使用 libx264 编码器（无法通过 config/cfg 覆盖），而 conda 环境中的 ffmpeg 编译时启用了 --disable-gpl，因此未包含 GPL 授权的 libx264。

解决方案：

# Conda 环境（最常见场景）
conda install x264 -c conda-forge
# 安装后，conda-forge 版 ffmpeg 将自动重新链接 x264 库

# 验证
ffmpeg -codecs 2>&1 | grep libx264
# 输出应包含：encoders: libx264 libx264rgb

注意：brew install ffmpeg 默认内置 x264，但 conda 环境优先使用其自带的 ffmpeg，不会调用 Homebrew 版本。

setuptools 兼容性问题

manim-voiceover 依赖 pkg_resources，在 Python 3.12+ 上可能出现兼容性错误：

pip install "setuptools>=69.0,<72.0"

ffmpeg 缺失 libass

SRT 字幕烧录依赖 libass。macOS：

brew install ffmpeg
# 验证
ffmpeg -filters 2>&1 | grep subtitles

Linux：

sudo apt install libass-dev
# 可能需要重新编译 ffmpeg

gTTS 网络问题

gTTS 需访问 Google TTS 服务。若网络不可用，请切换至 pyttsx3 离线引擎：

from manim_voiceover.services.pyttsx3 import Pyttsx3Service
self.set_speech_service(Pyttsx3Service())

中文字体

Manim 使用系统字体渲染 Text 对象。请确保中文字体可用：

• macOS：PingFang SC（系统内置）
• Linux：sudo apt install fonts-noto-cjk
• 指定字体：Text("文本", font="PingFang SC")

相关资源

• GitHub 仓库：https://github.com/hzsunzixiang/manim-animation-skill
• Manim 技术指南：references/manim_guide.md —— Manim + voiceover + 字幕的详细技术文档
• 环境检查脚本：scripts/check_environment.py —— 一键依赖检查
• 渲染流水线脚本：scripts/run_pipeline.py —— 一键渲染 + 字幕烧录