Manim 動畫 — 數學與技術影片
Manim 是一個用於解說視覺效果的 Python 動畫引擎。它的強項在於精確性：可以將公式、圖表或構造動畫化為數學定義的物件，而不是設計工具中的近似值。
請閱讀 references/MANIM-PLAYBOOK.md 以獲得模式與程式碼範例。請根據已安裝的版本驗證相關旗標：https://docs.manim.community/en/stable/
1. 何時選擇 Manim
在以下情況選擇 Manim：
- 主題涉及方程式、符號或證明。
- 需要精確的坐標系、圖表、向量或幾何構造。
- 需要逐步視覺解說演算法、資料結構或流程。
- 標籤必須對齊數學物件，而非手動放置的畫面位置。
- 風格應為簡約圖解式，而非電影感。
在以下情況不選擇 Manim：電影感 3D、品牌形象重的宣傳影片、動態圖形字型排版，或互動式交付物。這些應交由 Blender、Remotion 或網頁圖形處理。
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 以及一個 TeX 發行版（例如 MacTeX，如果使用 MathTex）。
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/<file>/<quality>/ 目錄。
ffprobe -v error -show_entries stream=width,height,r_frame_rate,duration \
-of json media/videos/explain/1080p60/ExplainScene.mp4
4. 場景設計規則
- 一場景一觀念。 將內容拆分為多個
Scene子類別；透過拼接（concatentation）組成較長的影片，而非一個巨大的場景。 - 調色板與字型集中設定一次 在一個模組（
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 合併：對齊 FPS 與解析度，然後在 FFmpeg 或 Remotion 中組合。Manim 在
-qh預設為 60 FPS；可變更config.frame_rate或謹慎進行轉換。 - 對於品牌片頭/片尾與字幕，請先以 clean 方式渲染 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 的容器格式；務必驗證 |