Manim 动画 —— 数学与技术视频
Manim 是一个用于解释性视觉效果的 Python 动画引擎。其优势在于精确性：公式、图形或构造可以作为数学上定义的对象进行动画化，而不是设计工具中的近似值。
阅读 references/MANIM-PLAYBOOK.md 获取模式与代码。根据已安装版本验证参数：https://docs.manim.community/en/stable/
1. 何时选择 Manim
在以下情况选择 Manim：
- 方程、符号或证明是主题。
- 坐标系、图形、向量或几何构造必须精确。
- 算法、数据结构或过程需要逐步的视觉解释。
- 标签必须与数学对象对齐，而非手动放置的帧位置。
- 风格应克制且图表化，而非电影化。
在以下情况不要选择 Manim：电影级 3D、品牌宣传片、动态图形排版或交互式交付物。这些属于 Blender、Remotion 或 Web 图形的领域。
2. 安装（隔离、可复现）
uv --version # 如果缺少 uv，先安装
uv init --python 3.12 manim-project
cd manim-project
uv add manim
uv run manim --version
Linux 通常需要本地库：
sudo apt update
sudo apt install build-essential python3-dev pkg-config libcairo2-dev libpango1.0-dev ffmpeg
sudo apt install texlive texlive-latex-extra texlive-fonts-recommended # 用于 MathTex/Tex
macOS：brew install cairo pango pkg-config ffmpeg，如果使用 MathTex 还需要 TeX 发行版（如 MacTeX）。
Windows：安装 FFmpeg 和 MiKTeX/TeX Live；可能需要 Microsoft C++ Build Tools 来构建 Cairo/Pango wheel 包。
验证：
uv run manim --version
uv run python -c "import manim; print(manim.__version__)"
如果已有项目环境，请勿将 Manim 安装到系统 Python 中。在项目 README 中记录版本号。
3. 渲染命令
# 低质量预览（快速）
uv run manim -pql scenes/explain.py ExplainScene
# 中等质量
uv run manim -qm scenes/explain.py ExplainScene
# 高质量 / 生产级
uv run manim -qh scenes/explain.py ExplainScene
# 4K
uv run manim -qk scenes/explain.py ExplainScene
# 透明背景
uv run manim -qh -t scenes/explain.py ExplainScene
# 特定区间
uv run manim -qh scenes/explain.py ExplainScene -n 12,20
质量预设：-ql 480p15，-qm 720p30，-qh 1080p60，-qk 2160p60。以已安装版本为准。输出文件位于 media/videos/<文件>/<质量>/。
ffprobe -v error -show_entries stream=width,height,r_frame_rate,duration \
-of json media/videos/explain/1080p60/ExplainScene.mp4
4. 场景设计规则
- 每个场景一个概念。 拆分为
Scene子类；通过拼接组合较长的视频，而非在一个巨大的场景中完成。 - 调色板和字体只需设置一次，放在一个模块（
theme.py）中并导入，而不是重复写十六进制值。 - 限制相机移动。 Manim 的
MovingCameraScene功能强大且容易被滥用；仅在需要揭示观看者无法直接看到的结构时才进行缩放。 - 尊重时长。 一个 3 分钟阅读效果很好的公式推导，在 40 秒内会显得仓促。根据阅读速度计算停留时间，而非直觉。
- 保持标签附着 在其所描述的对象上（使用
Tex+next_to），这样后续布局更改不会在静默中破坏对齐。 - 使用
Transform/ReplacementTransform表示含义转变，使用FadeIn/FadeOut表示存在性变化。变形无关的形状会混淆观众。 - 不要独立地逐个动画化每个元素。 使用
VGroup进行分组，并有目的地错开动画。
5. 场景组合模板
from manim import *
class ExplainScene(Scene):
def construct(self):
title = Text("为什么导数是极限", font="Inter").scale(0.7)
self.play(Write(title), run_time=1.2)
self.wait(0.6)
self.play(title.animate.to_edge(UP).scale(0.8), run_time=0.9)
formula = MathTex(r"f'(x) = \lim_{h \to 0} \frac{f(x+h)-f(x)}{h}")
formula.scale(1.2)
self.play(Write(formula), run_time=1.6)
self.wait(1.2)
self.play(formula.animate.set_color_by_tex(r"h \to 0", YELLOW), run_time=0.8)
self.wait(1.5)
6. 导出与交接
-qh以高码率生成 1080p60 视频；建议为交付内容重新编码，而不是直接提供中间文件。- 透明背景：
-t会生成带 alpha 通道的.mov文件（或配合--format=png生成 PNG 序列）。在合成前，通过棋盘格背景验证 alpha 通道。 - 要将 Manim 与 Remotion/Blender 结合：匹配帧率和分辨率，然后在 FFmpeg 或 Remotion 中进行组装。Manim 在
-qh下默认为 60 FPS；可以更改config.frame_rate或有目的地进行转换。 - 对于品牌化的片头/片尾和字幕，建议将 Manim 场景渲染干净后在 Remotion 中合成——不要强行使用 Manim 的排版系统进行品牌布局。
7. 验证
- 在渲染高质量版本之前，先观看低质量渲染版本；数学错误在 480p 下也能被发现。
- 检查没有公式被画面边缘裁剪，没有标签重叠。
- 验证 LaTeX 已编译成功，没有静默回退（注意控制台中的红色文本警告）。
- 使用
ffprobe确认最终时长和帧率。 - 逐字朗读每个符号并对照预期的数学表达式；符号翻转是正确性问题，而非风格选择。
8. 常见故障
| 症状 | 原因 | 修复方法 |
|---|---|---|
latex: command not found | 没有 TeX 发行版 | 安装 TeX Live/MiKTeX，或使用 Text 替代 MathTex |
| Cairo/Pango 构建错误 | 缺少本地库 | 安装上述列出的开发包 |
| 公式渲染为红色错误文本 | LaTeX 语法错误或缺少包 | 检查控制台；向 TexTemplate 添加包 |
| 所有内容看起来模糊 | 使用了低质量预设 | 为最终版本使用 -qh/-qk 渲染 |
| 希腊文/阿拉伯文显示异常 | 字体缺少字形或排版支持 | 使用支持排版的字体，测试静态帧，或将文本栅格化 |
| 渲染非常慢 | 60 FPS + 4K + 复杂路径 | 在 -ql 下预览，简化路径，拆分场景 |
| 透明度丢失 | 格式错误 | 使用 -t 并选择支持 alpha 的容器格式；仔细验证 |