concept-to-video

概念转视频

使用 Manim（Python）作为程序化动画引擎，根据概念创建动画解说视频。

参考文件

文件	用途
references/rules/pipeline-flow.md	RAG、ETL、CI/CD——带箭头的顺序阶段动画
references/rules/architecture-layers.md	系统堆栈、网络分层、抽象层级
references/rules/algorithm-stepthrough.md	排序、搜索、图遍历——有状态的逐步动画
references/rules/comparison.md	并排比较 A 与 B、前后对比、权衡可视化
references/rules/agent-interaction.md	多 Agent 消息传递、分布式系统、发布/订阅
references/rules/math-concept.md	方程、公式、几何证明——默认不使用 LaTeX
references/rules/training-loop.md	梯度下降、RL 循环、循环迭代过程
references/rules/transitions.md	场景片段之间的淡入和擦除转场
references/rules/text-animation.md	文本替换、逐步显示项目符号、标注、强调
references/rules/layout.md	画布坐标、VGroup 排布、间距指南
references/rules/audio-overlay.md	ffmpeg 音频叠加——背景音乐、配音、多轨混音
references/rules/voiceover-scaffold.md	计时脚本生成、TTS 衔接、旁白最佳实践
references/rules/images.md	ImageMobject 用法、徽标/屏幕截图模式、缩放与定位
references/rules/subtitles.md	根据场景时间生成 SRT、使用 ffmpeg 烧录字幕
references/rules/multi-scene.md	多个 Scene 类、ffmpeg 拼接、基于章节的合成
references/templates/data_flow_template.py	参数化管道/数据流动画（由配置驱动的 STAGES 列表）
references/templates/comparison_template.py	参数化并排比较（由配置驱动的 LEFT/RIGHT 项目）
references/templates/timeline_template.py	参数化时间线动画（由配置驱动的 EVENTS 列表）
scripts/render_video.py	Manim CLI 的封装器——处理质量、格式、输出路径清理
scripts/add_audio.py	ffmpeg 封装器——音频叠加、音量、淡入/淡出、裁剪至视频时长

为什么选择 Manim 作为引擎

Manim 是“视频领域的 SVG”——你可以编写以声明方式描述动画的 Python 代码，并将其渲染为任意分辨率的 MP4/GIF。Python 场景文件本身就是可编辑的中间产物：用户可以查看代码、提出修改要求（“把箭头改成红色”“添加第三个步骤”“放慢转场”），并且只需在满意后进行一次最终的高质量渲染。这使工作流具备迭代性和可控性，就像概念转图像使用 HTML 作为中间产物一样。

工作流

Concept → Manim scene (.py) → Preview (low-quality) → Iterate → Final render (MP4/GIF)

1. 解读用户的概念——确定最佳动画方案
2. 设计一个独立的 Manim 场景文件——一个文件，一个 Scene 类
3. 预览时以低质量（-ql）渲染，以便快速迭代
4. 根据用户反馈对场景进行迭代
5. 使用 scripts/render_video.py 以高质量导出最终视频

步骤 0：确保依赖项已就绪

编写任何场景之前，确保已安装 Manim：

# System deps (usually pre-installed)
apt-get install -y libpango1.0-dev libcairo2-dev ffmpeg 2>/dev/null

# Python package
pip install manim --break-system-packages -q

使用以下命令验证：python3 -c "import manim; print(manim.__version__)"

步骤 1：理解概念

确定最合适的动画模式，然后在编写任何代码之前阅读对应的规则文件。

用户意图	要阅读的规则文件	关键 Manim 原语
讲解管线／流程	references/rules/pipeline-flow.md	Arrow、Rectangle、Text、AnimationGroup
展示架构层	references/rules/architecture-layers.md	VGroup、Arrange、带 shift 的 FadeIn
逐步演示算法	references/rules/algorithm-stepthrough.md	Transform、ReplacementTransform、Indicate
比较不同方法	references/rules/comparison.md	分屏 VGroup、同步动画
数学概念	references/rules/math-concept.md	MathTex、几何形状、Rotate、Scale
Agent／多系统交互	references/rules/agent-interaction.md	实体间的箭头、Create／FadeOut
训练／优化循环	references/rules/training-loop.md	使用 Transform、ValueTracker、图表构成的循环
时间线／历史	references/templates/timeline_template.py	NumberLine、依次 Indicate
嵌入图像或屏幕截图	references/rules/images.md	ImageMobject、SVGMobject
添加字幕或说明文字	references/rules/subtitles.md	SRT 生成、使用 ffmpeg 烧录字幕
多个独立章节	references/rules/multi-scene.md	多个 Scene 类、ffmpeg 拼接
添加音频或配音	references/rules/audio-overlay.md	ffmpeg、scripts/add_audio.py
在章节之间过渡	references/rules/transitions.md	淡出所有内容、移出屏幕
文本显示、标注、强调	references/rules/text-animation.md	ReplacementTransform、LaggedStart、Indicate
定位、间距、布局	references/rules/layout.md	next_to、arrange、to_edge、move_to

步骤 2：设计 Manim 场景

模板优先还是从头编写

从头编写场景前，先检查参数化模板是否适用于该概念：

如果概念是……	从以下模板开始
线性管道（A→B→C→D）	references/templates/data_flow_template.py — 编辑 STAGES
两种选项的比较	references/templates/comparison_template.py — 编辑 LEFT_ITEMS、RIGHT_ITEMS
按时间顺序排列的时间线	references/templates/timeline_template.py — 编辑 EVENTS
其他任何情况	使用相关规则文件从头编写

使用模板时：将其复制到工作目录，编辑顶部的配置常量，不要重构类。

核心规则：

• 单文件、单个 Scene 类：所有内容放在一个 .py 文件中，其中包含一个 class XxxScene(Scene)。
• 自包含：除非绝对必要，否则不使用外部资源。所有内容都使用 Manim 基元。
• 代码清晰：场景文件就是用户的作品。使用清晰的变量名，并为每个动画片段添加注释。
• 有目的地使用颜色：使用 Manim 的颜色常量（BLUE、RED、GREEN、YELLOW 等）或十六进制颜色。最多使用 4–5 种颜色。每种颜色都应表达特定含义。
• 节奏：在逻辑片段之间加入 self.wait() 调用。留出 0.5 秒供观众消化，主要转场留出 1–2 秒。
• 文本可读性：正文文本的 font_size=36 起，标题的 font_size=48+ 起。在目标分辨率下进行测试。
• 场景尺寸：Manim 画布默认尺寸为 14.2 × 8 个单位（16:9）。内容应保持在水平 ±6、垂直 ±3.5 范围内。

动画最佳实践

# DO: Use animation groups for simultaneous effects
self.play(FadeIn(box), Write(label), run_time=1)

# DO: Use .animate syntax for property changes
self.play(box.animate.shift(RIGHT * 2).set_color(GREEN))

# DO: Stagger related elements
self.play(LaggedStart(*[FadeIn(item) for item in items], lag_ratio=0.2))

# DON'T: Add/remove without animation (jarring)
self.add(box)  # Only for setup before first frame

# DON'T: Make animations too fast
self.play(Transform(a, b), run_time=0.3)  # Too fast to read

结构模板

from manim import *

class ConceptScene(Scene):
    def construct(self):
        # === Section 1: Title / Setup ===
        title = Text("Concept Name", font_size=56, weight=BOLD)
        self.play(Write(title))
        self.wait(1)
        self.play(FadeOut(title))

        # === Section 2: Core animation ===
        # ... main content here ...

        # === Section 3: Summary / Conclusion ===
        # ... wrap-up animation ...
        self.wait(2)

步骤 3：预览渲染

使用低画质进行快速迭代：

python3 scripts/render_video.py scene.py ConceptScene --quality low --format mp4

这会以 480p/15fps 渲染，足以快速预览节奏和布局。将视频展示给用户。

步骤 4：迭代

常见的优化请求及其处理方法：

请求	操作
“慢一点／快一点”	调整 run_time= 参数和 self.wait() 时长
“更改颜色”	更新颜色常量
“增加一个步骤”	在片段之间插入新的动画代码块
“重新排序”	调整代码块的顺序
“更改布局”	调整 .shift()、.next_to()、.arrange() 调用
“添加标签／注释”	添加 Text 或 MathTex 对象，并使用 .next_to()
“让它循环播放”	添加相匹配的开场／结尾状态

步骤 5：最终导出

用户满意后：

python3 scripts/render_video.py scene.py ConceptScene --quality high --format mp4

画质预设

预设	分辨率	FPS	标志	用途
low	480p	15	-ql	快速预览
medium	720p	30	-qm	草稿审阅
high	1080p	60	-qh	最终交付
4k	2160p	60	-qk	演示级画质

格式选项

格式	标志	用途
mp4	--format mp4	标准视频交付
gif	--format gif	可嵌入文档或社交媒体
webm	--format webm	针对 Web 优化

交付输出

同时提供以下两项：

1. .py 场景文件（便于日后编辑）
2. 渲染后的视频文件（最终输出）

将最终视频复制到 /mnt/user-data/outputs/ 并展示给用户。

第 5.5 步：可选音频叠加

如果用户提供了音频（音乐或旁白），或提出了相关要求：

# Background music at 25% volume with fade-in/out
python3 scripts/add_audio.py final.mp4 music.mp3 \
    --output final_with_audio.mp4 \
    --volume 0.25 --fade-in 2 --fade-out 3 --trim-to-video

# Voiceover at full volume, trimmed to video length
python3 scripts/add_audio.py final.mp4 voiceover.mp3 \
    --output final_narrated.mp4 --trim-to-video

录制前编写旁白脚本，请阅读 references/rules/voiceover-scaffold.md。 制作字幕或说明文字，请阅读 references/rules/subtitles.md。 进行高级多轨混音，请阅读 references/rules/audio-overlay.md。

错误处理

错误	原因	解决方法
ModuleNotFoundError: manim	未安装 Manim	运行第 0 步的设置命令
pangocairo 构建错误	缺少系统开发头文件	apt-get install -y libpango1.0-dev
FileNotFoundError: ffmpeg	未安装 ffmpeg	apt-get install -y ffmpeg
未找到场景类	类名不匹配	确认类名与 CLI 参数一致
对象重叠	未计算位置	使用 .next_to()、.arrange()、显式调用 .shift()
文本被截断	文本过大或位置靠近边缘	减小 font_size，或将位置调整到 ±6、±3.5 范围内
渲染缓慢	对象过多或变换过于复杂	减少对象数量、简化路径、使用较低画质
LaTeX Error	未安装 LaTeX（用于 MathTex）	改用 Text，或安装 texlive-latex-base

LaTeX 替代方案

如果没有 LaTeX，请避免使用 MathTex 和 Tex。改用带 Unicode 数学符号的 Text：

# Instead of: MathTex(r"\frac{1}{n} \sum_{i=1}^{n} x_i")
# Use:        Text("(1/n) Σ xᵢ", font_size=36)

Agent 模式（可选启用）

单次执行模式（默认）快速且成本低——编码者会根据概念直接编写 scene.py。若布局正确性和素材解析的重要性足以值得额外调用大模型和 VLM，请使用 Agent 模式来渲染达到生产质量的视频。

流程

concept
  └─► plan_storyboard.py ──► storyboard.json
            │
            ▼
      fetch_assets.py (optional)
            │
            ▼
      coder writes scene.py
            │
            ▼
      render_video.py --max-fix-attempts N
            │  ▲
            │  └─ LLM fixup loop (on failure, up to N retries)
            ▼
      critic_pass.py --critic
            │  ▲
            │  └─ VLM layout patch (1 call with M image blocks)
            ▼
       final MP4

标志参考

脚本	标志	默认值	硬性上限	效果	成本影响
render_video.py	--max-fix-attempts	0	3	渲染失败时由大模型辅助自动修复；0 = 禁用	每次重试增加 1 次大模型调用
critic_pass.py	--critic	已禁用	—	启用 VLM 评审流程；未设置此标志时不执行	增加 1 次 VLM 调用（N 个图像块）
critic_pass.py	--critic-budget	50000	—	评审调用的令牌预算；超出时会明确中止	设置上限；可用于防止费用失控
critic_pass.py	--frames	5	10	从渲染的视频中为评审抽取的帧数	帧数越多 → 每次评审运行的令牌成本越高
fetch_assets.py	--adapter	none	—	素材后端：local、iconfinder、none	iconfinder 会增加外部 API 调用
fetch_assets.py	--asset-dir	—	—	--adapter=local 的根目录；使用 local 时必需	无

成本权衡

每次渲染失败后，修复循环都会增加一次大模型调用——使用 --max-fix-attempts 3 时，在循环耗尽或成功之前，最多可能额外产生 3 次调用。评审环节会增加一次 VLM 调用，其中包含 N 个 PNG 图像块（默认 5 个，最多 10 个）；每帧大约会因 Base64 编码的 PNG 每 800 字节增加 1 个 token，因此高分辨率下的复杂场景成本会显著增加。将 --critic-budget 设为较保守的 token 上限（例如 20000），会在发起 API 调用前触发 BudgetExceededError，因此不会为意外超大的请求付费——按设计，这类错误会明确报出且无法恢复。

调用示例

# 1. Plan
python3 scripts/plan_storyboard.py "explain transformer self-attention" \
    --output storyboard.json

# 2. (Optional) Fetch assets
python3 scripts/fetch_assets.py storyboard.json \
    --adapter local --asset-dir ./assets --output resolved.json

# 3. Coder writes scene.py (Claude writes this from storyboard.json)

# 4. Render with auto-fix
python3 scripts/render_video.py scene.py AttentionScene \
    --quality high --format mp4 --max-fix-attempts 3 \
    --output final.mp4

# 5. Critic pass
python3 scripts/critic_pass.py scene.py final.mp4 \
    --critic --critic-budget 40000 --frames 5

Agentic 流水线设计（分镜规划器、自动修复循环、VLM 评审器）改编自 Code2Video（arXiv 2510.01174，MIT）。随附的提示词模板位于 references/code2video/，与上游 LICENSE 一同存放。完整的随附记录、固定的提交版本和重新同步策略详见根目录 ATTRIBUTIONS.md。

限制

• 需要 Manim 和 ffmpeg —— 缺少这些依赖时无法渲染。
• 音频只能在渲染后添加 —— Manim 会渲染无声 MP4。导出后可使用 scripts/add_audio.py 叠加音频。
• LaTeX 为可选项 —— MathTex 需要安装 LaTeX。数学内容可改用带 Unicode 字符的 Text。
• 渲染时间随复杂度增加 —— 包含许多对象的 30 秒 1080p 场景可能需要 1-2 分钟渲染。
• 3D 场景需要 OpenGL —— ThreeDScene 在无头容器中可能无法运行。请使用 2D Scene 类。
• 不支持交互 —— 输出为静态视频文件，而非交互式组件。
• GIF 输出没有声音 —— 只有 MP4/WEBM 输出格式支持叠加音频。

应避免的设计反模式

• 屏幕上出现大段文字 —— 标签控制在 3-5 个词，最多 2 行
• 所有内容同时出现 —— 使用 LaggedStart 分阶段播放动画
• 时间节奏一致 —— 调整 run_time 来营造节奏（简单内容快，重要内容慢）
• 缺乏视觉层级 —— 运用大小、颜色和位置引导注意力
• 彩虹配色 —— 有意选择的颜色最多 3-4 种
• 忽略网格 —— 使用 arrange/align 将对象对齐到统一位置