Manim (manimlib) 自定义配置完全指南：custom_config.yml 与 default_config.yml 详解

2026-09-03 16:16:23作者：邵娇湘

本文基于 manim（manimlib）仓库中的自定义配置文档，系统讲解 custom_config.yml 的全部配置分组（directories、window、camera、file_writer、scene、text、tex、sizes、colors 等）及其默认值来源，并结合 config.py 的合并逻辑与 default_config.yml 的默认参数，给出可直接复制的完整配置示例。读完本文，你可以精确控制 manim 的渲染输出目录、预览窗口、相机参数、ffmpeg 编码与 LaTeX/Text 字体，并理解每个配置项在源码中的真实作用位置。

配置加载机制：三层合并，命令行最高优先级

manim 的全局配置是一个名为 manim_config 的字典，它在 manimlib 包被导入时由 initialize_manim_config() 一次性构建。从源码看，其合并顺序为：

全局默认：读取 manimlib 目录下的 default_config.yml；
项目自定义：读取当前工作目录下的 custom_config.yml（文件不存在时静默返回空字典）；
命令行参数：通过 --config_file /path/to/custom/config/file.yml 指定任意位置的配置文件，再用 CLI 参数（如 -r、--fps、-c）逐条覆盖。

三者通过 merge_dicts_recursively 递归合并（见 load_yaml 与 parse_cli）。这意味着 custom_config.yml 中只需写你想覆盖的键，其余键自动继承默认值——这正是该文档推荐的工作方式。

合并完成后，update_directory_config、update_window_config、update_camera_config、update_file_writer_config、update_scene_config、update_run_config 等函数会对原始 YAML 做二次加工（例如把 window.position/window.size 的字符串字面量用 literal_eval 解析成元组，见 update_window_config）。

directories：目录结构与输出路径

directories 分组决定 manim 在文件系统中读写哪些位置，对应 default_config.yml 中 base: "" 加 subdirs 的结构，并在加载时由 update_directory_config 把每个子目录拼接成 base + 子目录名 的绝对路径。

mirror_module_path（True / False，默认 False）

是否根据运行脚本的文件名在 output 路径下创建同名文件夹，把输出（images/ 或 videos/）保存其中。文档给出的两种典型目录结构如下。

output 设为 "/.../manim/output"、mirror_module_path: False 时：

manim/
├── manimlib/
│   ├── animation/
│   ├── ...
│   ├── default_config.yml
│   └── window.py
├── output/
│   ├── images
│   │   └── Scene1.png
│   └── videos
│       └── Scene1.mp4
├── code.py
└── custom_config.yml

设为 True 时，输出会落入以脚本名命名的子目录：

manim/
├── manimlib/
│   ├── animation/
│   ├── ...
│   ├── default_config.yml
│   └── window.py
├── output/
│   └── code/
│       ├── images
│       │   └── Scene1.png
│       └── videos
│           └── Scene1.mp4
├── code.py
└── custom_config.yml

源码中该行为的实现在 get_output_directory：当 mirror_module_path 为真且指定了脚本文件时，取脚本文件名（.stem）作为 output 下的子目录；若脚本路径以 removed_mirror_prefix 开头，则会改用相对路径结构，使输出目录树与源码目录树保持一致——这对大型项目（如多集、多章节的组织）非常有用。

base / output

base：文件根目录，manim 渲染的视频、读取的图片资源都相对它定位。默认 ""，即当前工作目录。
output：输出目录名，视频存于其下 videos/，图片存于其下 images/。在 default_config.yml 中它其实是 subdirs.output: "videos"，最终目录为 base + "videos"。

raster_images / vector_images / sounds

raster_images（默认 raster_images）：存放 .jpg、.jpeg、.png、.gif 等位图资源的目录，供 ImageMobject 按名读取，查找逻辑见 utils/images.py（调用 get_raster_image_dir）。
vector_images（默认 vector_images）：存放 .svg、.xdv 矢量图的目录，供 SVGMobject 读取（经 get_vector_image_dir）。
sounds（默认 sounds）：存放 .wav、.mp3 的目录，供 Scene.add_sound() 按名查找（见 utils/sounds.py）。

cache

存放临时缓存文件的目录，包括 Tex 缓存、Text 缓存与对象点数据。若配置为空字符串，则回退到系统用户缓存目录 appdirs.user_cache_dir("manim")，见 get_cache_dir 与 utils/cache.py。命令行另有 --clear-cache 可清除 Tex/Text 缓存（见 parse_cli）。

window：预览窗口定位

window 分组控制预览窗口的显示，对应 window.py 中 Window.__init__ 的入参：

position_string：窗口在屏幕上的相对位置，两个字符：第一位 U（上）/ O（中）/ D（下），第二位 L（左）/ O（中）/ R（右），例如默认 UR 即右上。定位计算见 window.py 中的 POSITION_STEPS。
monitor_index：多显示器环境下窗口出现在哪块屏幕上，默认 0。
full_screen：是否全屏预览；不为全屏时默认取屏幕的一半（见 default_config.yml 注释）。CLI 的 -f/--full_screen 会强制置真。
position：以像素坐标手工指定窗口位置，如 (500, 300)，覆盖 position_string。
size：以像素坐标手工指定窗口大小，如 (1920, 1080)，覆盖默认尺寸。

注意 position/size 在 YAML 中写作字符串形式（如 "(500, 500)"），加载时由 update_window_config 的 literal_eval 转换为真正的元组。

camera：分辨率、背景与帧率

resolution：渲染分辨率，默认 (1920, 1080)。CLI 的 -r "WxH"、-l(480p)、-m(720p)、--hd(1080p)、--uhd(4K) 会覆盖此值，各档位取值来自 default_config.yml 的 resolution_options（low: (854, 480)、med: (1280, 720)、high: (1920, 1080)、4k: (3840, 2160)），解析逻辑见 get_resolution_from_args。
background_color：场景默认背景色，默认 "#333333"。CLI -c/--color 会用 colour.Color 解析并覆盖（见 update_camera_config）。
fps：帧率，默认 30，可被 --fps 覆盖。
background_opacity：背景不透明度，默认 1.0；-t/--transparent 会将其置为 0.0 并切换为带 alpha 通道的输出。

此外 default_config.yml 还提供文档未列出的两个相机开关：bundle_draws: True（将一帧的绘制聚合成渲染束回放）与 draw_together: True（把一次绘制可覆盖的多个 mobject 合并绘制），两者关闭后渲染结果不变但速度变慢，适合调试。

file_writer：ffmpeg 输出参数

file_writer 分组指定文件写入方式，核心是传给 ffmpeg 的参数（见 default_config.yml）：

ffmpeg_bin：ffmpeg 可执行文件名，默认 "ffmpeg"；
video_codec：默认 "libx264"；
pixel_format：默认 "yuv420p"；
saturation / gamma：默认均为 1.0。

默认文件还给出了无损输出的参考组合：video_codec: "libx264rgb" + pixel_format: "rgb24" + crf: 0，可在渲染时逐像素保留绘制结果。

运行时行为由 update_file_writer_config 结合 CLI 补齐：-s 保存最后一帧（PNG）、-w 写出视频、--subdivide 按动画拆分输出文件、-i/--gif 输出 GIF（此时 video_codec 置空）、--transparent 则改用 prores_ks 编码输出 .mov（见 get_file_ext）。CLI 的 --vcodec 与 --pix_fmt 也会覆盖对应配置。

scene：Scene 类的默认行为

scene 分组为 Scene 类提供默认配置。文档中该节较简略，完整默认值见 default_config.yml：

show_animation_progress: False：是否为每个动画显示进度条；
leave_progress_bars: False：终端进度条渲染完成后是否保留；
preview_while_skipping: True：-s 跳过动画时，是否在每次 play 结束渲染单帧预览；
default_wait_time: 1.0：Scene.wait() 的默认暂停时长（秒）；
invert_zoom_scroll: False：是否反转滚轮缩放方向。

CLI 参数 -p/--presenter_mode、-n/--start_at_animation_number 等也会在 update_scene_config 中写入该分组。

text 与 tex：字体、对齐与 LaTeX 模板

text

font：Text 的默认字体，默认 "Consolas"（default_config.yml）；
alignment：默认文字对齐方式，默认 "LEFT"（文档中写作 text_alignment，默认 YAML 中的键名为 alignment，供 LaTeX 排版使用）；
font_size_for_unit_height：默认 144，表示 Text("0") 高度为 1 manim 单位时的字号。该值被 text_mobject.py 的字号标定逻辑读取，用于按渲染结果反向校准 SVG 字号。

tex

template：决定使用 tex_templates.yml 中哪个模板来选取 LaTeX 编译器与导言区（preamble），默认 "default"。可选模板包括 default（latex 编译器 + 完整宏包）、ctex（xelatex + ctex 宏包，用于中文）、basic、basic_ctex、empty 等，完整清单见 tex_templates.yml。模板名在 tex_file_writing.py 中作为缺省值读取。
font_size_for_unit_height：默认 144，含义同上，作用于 Tex 的字号标定（见 tex_mobject.py）。

sizes 与 colors：坐标系刻度与调色板

sizes

sizes 决定 manim 坐标系与视框的尺度及各类间距常量，全部被 constants.py 直接读取为全局常量：

配置键	默认值	对应常量
`frame_height`	8.0	`FRAME_HEIGHT`（视框高度，单位 manim 单位）
`small_buff`	0.1	`SMALL_BUFF`
`med_small_buff`	0.25	`MED_SMALL_BUFF`
`med_large_buff`	0.5	`MED_LARGE_BUFF`
`large_buff`	1.0	`LARGE_BUFF`
`default_mobject_to_edge_buff`	0.5	`DEFAULT_MOBJECT_TO_EDGE_BUFF`（`to_edge` 默认间距）
`default_mobject_to_mobject_buff`	0.25	`DEFAULT_MOBJECT_TO_MOBJECT_BUFF`（`next_to` 默认间距）

colors

colors 是整套颜色调色板，决定 RED、BLUE_E、TEAL 等颜色常量的取值。default_config.yml 为每种色相提供 _e 到 _a 五级深浅（如 blue_e: "#1C758A" 至 blue_a: "#C7E9F1"）以及 white、black、grey_brown、pink、pure_red 等纯色，并在 constants.py 中逐一对应成 BLUE_E…RED_A 等 ManimColor 常量。替换整套配色时，只需在 custom_config.yml 的 colors 下覆盖相应键。

log_level、universal_import_line 与 reload 行为

log_level（文档中写作 loglevel）：取值 DEBUG / INFO / WARNING / ERROR / CRITICAL，默认 "INFO"。CLI --log-level 优先于配置（见 initialize_manim_config）。
universal_import_line：进入交互模式（-e embed）时自动执行的导入语句，默认 "from manimlib import *"，执行点在 extract_scene.py。
ignore_manimlib_modules_on_reload：交互模式下调用 reload 时，默认会重新加载用户导入的模块以便刷新跨文件的场景代码；manim 库自身模块默认被忽略（True）。manim 开发者可将其设为 False，使对库本身的修改也能被热重载，见 module_loader.py。CLI 另有 --autoreload 自动重载。

一份可直接使用的 custom_config.yml 示例

结合 default_config.yml 的默认值，一个典型的 custom_config.yml（放置于运行 manim 的当前工作目录）可以这样写：

directories:
  base: ""
  mirror_module_path: True
  subdirs:
    output: "videos"
    raster_images: "raster_images"
    vector_images: "vector_images"
    sounds: "sounds"
  cache: ""
window:
  position_string: UR
  monitor_index: 0
  full_screen: False
  # position: (500, 500)   # 需要时取消注释
  # size: (1920, 1080)
camera:
  resolution: (1920, 1080)
  background_color: "#333333"
  fps: 30
  background_opacity: 1.0
file_writer:
  video_codec: "libx264"
  pixel_format: "yuv420p"
tex:
  template: "ctex"   # 渲染中文公式时改用 xelatex + ctex 模板
text:
  font: "Consolas"
  alignment: "LEFT"
log_level: "INFO"

保存后用标准方式运行即可，例如 manim -w code.py Scene1；若希望使用其他位置的配置文件，则加 --config_file /path/to/custom/config.yml（见 parse_cli 的 --config_file 参数）。

小结

manim 的配置体系以 default_config.yml 为基线，以工作目录下的 custom_config.yml 为覆盖层，以命令行参数为最高优先级，最终汇聚为 config.py 中导入时即构建的全局 manim_config 字典。理解这条“默认 → 自定义 → 命令行”的三层覆盖链后，本文覆盖的 directories、window、camera、file_writer、scene、text/tex、sizes、colors、log_level、universal_import_line、ignore_manimlib_modules_on_reload 各分组就都可以在自己的项目中按需微调：目录结构决定产物落盘位置，相机分组决定输出规格，而 sizes 与 colors 则直接影响坐标与配色的全局观感。