https://docs.manim.community/en/stable/guides/add_voiceovers.html
pip install "manim-voiceover[azure,gtts]"
Basic Usage
Manim Voiceover lets you …
-
Add voiceovers to Manim videos directly in Python, without having to use a video editor.
-
Record voiceovers with your microphone during rendering through a simple command line interface.
-
Develop animations with auto-generated AI voices from various free and proprietary services.
It provides a very simple API that lets you specify your voiceover script and then record it during rendering:
# Simply inherit from VoiceoverScene instead of Scene to get all the # voiceover functionality. class RecorderExample(VoiceoverScene): def construct(self): # You can choose from a multitude of TTS services, # or in this example, record your own voice: self.set_speech_service(RecorderService()) circle = Circle() # Surround animation sections with with-statements: with self.voiceover(text="This circle is drawn as I speak.") as tracker: self.play(Create(circle), run_time=tracker.duration) # The duration of the animation is received from the audio file # and passed to the tracker automatically. # This part will not start playing until the previous voiceover is finished. with self.voiceover(text="Let's shift it to the left 2 units.") as tracker: self.play(circle.animate.shift(2 * LEFT), run_time=tracker.duration)
(zdvb-venv) PS D:\zprojects\manim> manim -pqh scene.py RecorderExample
'sox' 不是内部或外部命令，也不是可运行的程序
或批处理文件。
[05/14/26 17:19:43] WARNING SoX could not be found! __init__.py:10
If you do not have SoX, proceed here:
- - - http://sox.sourceforge.net/ - - -
If you do (or think that you should) have SoX, double-check your
path variables.
Traceback (most recent call last):
File "<frozen runpy>", line 198, in _run_module_as_main
File "<frozen runpy>", line 88, in _run_code
File "D:\venvs\zdvb-venv\Scripts\manim.exe\__main__.py", line 2, in <module>
from manim.__main__ import main
File "D:\venvs\zdvb-venv\Lib\site-packages\manim\__init__.py", line 119, in <module>
from .plugins import *
File "D:\venvs\zdvb-venv\Lib\site-packages\manim\plugins\__init__.py", line 12, in <module>
missing_plugins = requested_plugins - set(get_plugins().keys())
~~~~~~~~~~~^^
File "D:\venvs\zdvb-venv\Lib\site-packages\manim\plugins\plugins_flags.py", line 15, in get_plugins
entry_point.name: entry_point.load()
~~~~~~~~~~~~~~~~^^
File "D:\Python313\Lib\importlib\metadata\__init__.py", line 179, in load
module = import_module(match.group('module'))
File "D:\Python313\Lib\importlib\__init__.py", line 88, in import_module
return _bootstrap._gcd_import(name[level:], package, level)
~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "D:\venvs\zdvb-venv\Lib\site-packages\manim_voiceover\__init__.py", line 4, in <module>
import pkg_resources
ModuleNotFoundError: No module named 'pkg_resources'
Downloaded sox from http://sox.sourceforge.net/ and installed it.
(zdvb-venv) PS D:\zprojects\manim> manim -pqh scene.py RecorderExample
Traceback (most recent call last):
File "<frozen runpy>", line 198, in _run_module_as_main
File "<frozen runpy>", line 88, in _run_code
File "D:\venvs\zdvb-venv\Scripts\manim.exe\__main__.py", line 2, in <module>
from manim.__main__ import main
File "D:\venvs\zdvb-venv\Lib\site-packages\manim\__init__.py", line 119, in <module>
from .plugins import *
File "D:\venvs\zdvb-venv\Lib\site-packages\manim\plugins\__init__.py", line 12, in <module>
missing_plugins = requested_plugins - set(get_plugins().keys())
~~~~~~~~~~~^^
File "D:\venvs\zdvb-venv\Lib\site-packages\manim\plugins\plugins_flags.py", line 15, in get_plugins
entry_point.name: entry_point.load()
~~~~~~~~~~~~~~~~^^
File "D:\Python313\Lib\importlib\metadata\__init__.py", line 179, in load
module = import_module(match.group('module'))
File "D:\Python313\Lib\importlib\__init__.py", line 88, in import_module
return _bootstrap._gcd_import(name[level:], package, level)
~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "D:\venvs\zdvb-venv\Lib\site-packages\manim_voiceover\__init__.py", line 4, in <module>
import pkg_resources
ModuleNotFoundError: No module named 'pkg_resources'
这个报错是因为在 Python 3.12+ 版本中，原本内置在 setuptools 里的 pkg_resources 模块被彻底移除了，而你安装的 manim-voiceover 插件可能还在引用这个旧模块。
由于你使用的是 Python 3.13（从报错路径 D:\Python313 可以看到），这个问题会非常明显。
解决方法
1. 安装 setuptools（最快方案）
虽然 pkg_resources 被弃用了，但安装 setuptools 通常能把这个模块补回来，解决兼容性问题。在你的虚拟环境中运行：
pip install setuptools
2. 检查 manim-voiceover 是否安装完整
VoiceoverScene 并不是 Manim 核心库自带的，它是一个第三方插件。如果你还没安装它，或者安装版本过旧，也会出问题。建议更新到最新版：
pip install --upgrade manim-voiceover
3. 关于 RecorderService() 的特别提醒
你代码中使用了 RecorderService()，这意味着 Manim 会在渲染到这一行时停下来，等待你对着麦克风实时录音。
-
操作流程：程序会弹出一个提示，让你按下回车键开始说话，再按一次结束。
-
依赖项：你需要安装
pyaudio。如果运行录音时报错，请执行：PowerShellpip install pyaudio
代码逻辑小贴士
你的代码逻辑非常清晰：
-
with self.voiceover(...) as tracker: 这会创建一个上下文管理器。 -
run_time=tracker.duration: 这是manim-voiceover的精髓。它会自动测量你录音（或生成的语音）有多长，然后自动拉伸或压缩动画时间，确保圆圈画完的时候，你的话也刚好说完。
TL;DR: 运行 pip install setuptools 修复 ModuleNotFoundError。如果想让动画更自动化，未来可以尝试使用 AzureService 或 gTTSService（文字转语音），就不用每次渲染都自己录音了。
1, 2, 3都执行了，还是报同样的错误。
既然这三步（安装 setuptools、更新 manim-voiceover、安装 pyaudio）都执行了还是报 ModuleNotFoundError: No module named 'pkg_resources'，这说明在 Python 3.13 这个非常新的版本中，setuptools 的简单安装已经不足以兼容那些使用了旧版包管理工具的库了。
这是因为 Python 3.12+ 彻底删除了对 pkg_resources 的默认支持，转而使用更现代的 importlib.metadata。
请尝试以下深层次修复方案：
1. 强制安装或重新安装 setuptools
有时候 setuptools 虽然安装了，但由于缓存或路径问题，虚拟环境没能识别到。请尝试：
pip install --force-reinstall setuptools
2. 手动替换 pkg_resources（最有效的“偏方”）
如果上述方法无效，可以通过安装 backports.pkg_resources 来提供垫片支持：
pip install backports.pkg_resources
3. 环境隔离性排查（非常重要）
从你的路径 D:\Python313\Lib\importlib... 可以看出，尽管你在 (zdvb-venv) 下，但系统似乎在回溯调用全局安装的 Python 3.13 库。
请确认你的虚拟环境是否“干净”：
-
检查 pip 路径：
PowerShellwhich pip # 或者在 PowerShell 中使用: get-command pip确保它指向的是
D:\venvs\zdvb-venv\Scripts\pip.exe。 -
清理缓存安装： 有时候
manim-voiceover的安装包信息已经损坏，尝试完全卸载再安装：PowerShellpip uninstall manim-voiceover pip install manim-voiceover
4. 终极替代：使用 Python 3.11 或 3.12
实实话实说（Candidly）： Python 3.13 目前处于非常前沿的状态，很多 Manim 插件（尤其是涉及底层 C 库和旧版包管理工具的插件）尚未完成适配。
如果你只是想顺利运行 VoiceoverScene，最稳妥的做法是创建一个 Python 3.11 的虚拟环境。
-
Python 3.11 对
pkg_resources的兼容性最好。 -
pyaudio和各种语音服务的 SDK 在 3.11 下更稳定。
5. 临时修改代码绕过报错（不推荐但有效）
如果你不想重新折腾环境，可以尝试手动修改插件源码。报错提示是在： D:\venvs\zdvb-venv\Lib\site-packages\manim_voiceover\__init__.py 第 4 行。
你可以打开这个文件，将 import pkg_resources 这一行注释掉，看看是否能跳过。如果该插件只是用它来检查版本号，注释掉后程序通常能跑起来。
建议步骤： 先执行 pip install --force-reinstall setuptools，如果不行，强烈建议你安装一个 Python 3.11 的版本专门跑这个项目。对于开发者来说，在 3.13 这种“激进”的版本上修补旧插件的兼容性通常非常耗时。
(zdvb-venv) PS D:\zprojects\manim> pip install backports.pkg_resources
ERROR: Could not find a version that satisfies the requirement backports.pkg_resources (from versions: none)
ERROR: No matching distribution found for backports.pkg_resources
看来 backports.pkg_resources 这个补丁包在 Python 3.13 的官方源里也失效了。这反映了一个现实问题：Python 3.13 彻底移除了很多旧时代的兼容层，而 manim-voiceover 内部依然强依赖于已经过时的 pkg_resources（它是 setuptools 的一部分）。
既然我们不能改变 Python 3.13 的底层逻辑，我们就得用“开发者”的方式来手动修复这个插件。
🛠️ 终极手术：手动修改插件源码
由于报错是在 manim_voiceover 的初始化阶段，我们可以通过修改它的代码来绕过这个检查。请按照以下路径操作：
-
找到文件：
D:\venvs\zdvb-venv\Lib\site-packages\manim_voiceover\__init__.py -
用记事本或 VS Code 打开它。
-
找到第 4 行左右的
import pkg_resources。 -
将其修改为以下代码（这是一种现代的替代写法）：
try:
import pkg_resources
except ImportError:
import importlib.metadata as pkg_resources
或者，如果该插件只是用它来获取版本号，你可以更暴力一点，直接注释掉它并硬编码一个版本号：
# import pkg_resources
# __version__ = pkg_resources.get_distribution("manim-voiceover").version
__version__ = "0.3.0" # 随便写一个版本号，只要让程序不报错往下走就行
💡 为什么 pip install 总是失败？
在 Python 3.13 中，环境变得非常“挑剔”：
-
弃用期结束：
pkg_resources从 Python 3.12 开始报警告，到 3.13 正式从基础库中彻底抹除。 -
插件滞后：
manim-voiceover的开发者可能还没有针对 3.13 发布新的稳定版。
🚀 避坑指南（Candid Advice）
如果你修改了源码还是有后续的报错（比如 pyaudio 在 3.13 下的编译问题），我建议你采取最稳妥的策略：
降级虚拟环境的 Python 版本： 你不需要卸载 3.13，只需要在创建虚拟环境时指定 3.11 或 3.12。
# 如果你安装了多个版本的 Python
py -3.11 -m venv D:\venvs\zdvb-venv-stable
为什么推荐 3.11？
-
兼容性巅峰：目前绝大多数 Manim 插件、AI 语音库和音频驱动（如 PyAudio）对 3.11 的支持是最完美的。
-
省心：作为开发者，你的核心目的是创作动画，而不是在这个阶段去修补所有第三方库的底层兼容性 Bug。
TL;DR: 手动打开 __init__.py 把 import pkg_resources 改掉。如果还不行，别在 3.13 上死磕了，换 3.11 虚拟环境保平安。
浙公网安备 33010602011771号