手里有一本 EPUB 、一份 PDF 或几万字的 TXT，想在通勤时听完，通常要先找配音平台、上传文件，再按字符数付费。碰到未出版稿件、内部材料或个人笔记，上传云端又多了一层顾虑。
Abogen 可以在自己的电脑上完成这件事：导入电子书或文档，选择普通话与中文音色，生成 MP3 、 M4B 、 WAV 等音频，还能同步导出字幕。默认使用约 8200 万参数的 Kokoro-82M，常规转换不要求 LLM，也没有独立显卡门槛。
这份教程按“先跑通一小段普通话，再转换整本书”的顺序来写。
Abogen 是一个本地文档转语音工具，有桌面 GUI 和 Web UI 两条路线。桌面版更稳定，Web UI 更新更快，带人物识别、多角色配音、发音覆盖、 EPUB 3 媒体叠加和可选 LLM 文本规范化。
主要能力包括：
- • 将 EPUB 、 PDF 、 TXT 、 Markdown 转成有声书；
- • 把 SRT 、 ASS 、 VTT 字幕直接配音；
- • 按 EPUB 章节或 PDF 页面选择内容；
- • 将各章节分开保存，或合并成一本完整有声书；
- • 输出 MP3 、 M4B 、 WAV 、 FLAC 、 OPUS；
- • 生成 SRT 或 ASS 字幕；
- • 把多个内置音色按权重混合；
- • 批量排队处理多本书。
核验时最新正式版为 v1.3.1。项目仍在快速开发，桌面版和 Web UI 的按钮、格式支持及高级功能存在差异。
电脑要求：没有显卡也能跑
项目没有公布严格的最低 CPU 、内存、显存或硬盘数字。下面分“硬要求”和“速度差异”说明。
硬要求
- • 操作系统：Windows 、 Linux 、 macOS；
- • Python：
3.10、3.11 或 3.12； - • 推荐 Python：
3.12； - • 系统依赖：eSpeak NG；
- • 首次安装及首次下载模型、音色时需要联网。
pyproject.toml 要求 Python <3.13。 README 的 Apple Silicon 示例曾出现 Python 3.13，两处信息有冲突，使用 3.12 更稳。
CPU 、内存和硬盘
- • CPU 可以完成普通话合成，速度会慢于受支持的 GPU；
- • Docker Compose 示例分配 4 个 CPU 和 8GB 内存，这只是容器预设，不能当作官方最低配置；
- • 长书会产生模型缓存、临时 WAV 、字幕和最终音频，硬盘要按书的长度预留；
- • 项目已经加入分块处理和音频直接写盘，能降低长文件的内存峰值，但不会消除转码时间与临时文件。
哪些显卡能加速
Windows：
- • NVIDIA 支持 CUDA，当前安装说明优先给出 CUDA 12.8；
- • 旧驱动可使用 CUDA 12.6 路线；
- • 较新驱动可尝试 CUDA 13.0；
- • Windows AMD 没有 ROCm 加速路径，可以继续使用 CPU 。
Linux：
- • NVIDIA 支持 CUDA；
- • AMD 可使用 ROCm 6.4 nightly PyTorch；
- • 没有 GPU 时使用 CPU 。
macOS：
- • Apple Silicon 可通过 Kokoro 开发版走 MPS；
- • Intel Mac 使用 CPU 。
简化理解：旧办公电脑可以先转一小段试听；经常制作长篇小说、教材或多本书时，GPU 能省下不少等待时间。
支持哪些输入和输出格式
桌面版输入
.epub
.pdf
.txt
.md
.markdown
.srt
.ass
.vtt
也可以直接把文字粘贴到编辑框。
Web UI 输入
当前 Web 上传流程直接处理：
.txt
.pdf
.md
.markdown
.epub
Web UI 上传上限为 400 MB。字幕文件转语音优先使用桌面版，因为当前 Web 提取器没有 SRT 、 ASS 、 VTT 分支。
音频输出
.wav
.flac
.mp3
.opus
.m4b
- • WAV：无压缩，体积大，方便后期剪辑；
- • FLAC：无损压缩；
- • MP3：播放器兼容性最好；
- • OPUS：压缩效率高；
- • M4B：支持章节、封面和元数据，适合完整有声书。
字幕输出
SRT
ASS wide
ASS narrow
ASS centered wide
ASS centered narrow
VTT 可以作为输入，当前配置没有把 VTT 列为字幕输出格式。
普通话适合使用 Line、Sentence 或 Sentence + Comma。中文没有可靠的逐词时间戳，句级和逗号级字幕根据音频时长估算。需要逐字卡拉 OK 式高亮时，这套方案暂时不合适。
Windows 详细安装教程
方案一：一键脚本
第一步，安装 eSpeak NG：
https://github.com/espeak-ng/espeak-ng/releases/latest
下载 Windows .msi 并完成安装。
第二步，下载 Abogen 源码 ZIP：
https://github.com/denizsafak/abogen/archive/refs/heads/main.zip
解压后双击：
WINDOWS_INSTALL.bat
脚本会在当前目录安装嵌入式 Python 3.12 、 uv 和 Abogen，检测 NVIDIA GPU，并尝试匹配 CUDA 版 PyTorch 。 Python 文件保存在：
python_embedded
桌面程序通常位于：
python_embedded\Scripts\abogen.exe
一键脚本会联网下载 Python 、 PyTorch 和多个依赖。企业电脑或敏感环境可以先检查 WINDOWS_INSTALL.bat，再决定是否运行。
方案二：用 uv 安装
无 NVIDIA GPU：
uv tool install --python 3.12 abogen
NVIDIA CUDA 12.8：
uv tool install --python 3.12 "abogen[cuda]" `
--extra-index-url https://download.pytorch.org/whl/cu128 `
--index-strategy unsafe-best-match
CUDA 12.6：
uv tool install --python 3.12 "abogen[cuda126]" `
--extra-index-url https://download.pytorch.org/whl/cu126 `
--index-strategy unsafe-best-match
CUDA 13.0：
uv tool install --python 3.12 "abogen[cuda130]" `
--extra-index-url https://download.pytorch.org/whl/cu130 `
--index-strategy unsafe-best-match
安装后启动桌面版：
abogen
Linux 安装
Ubuntu 或 Debian：
sudo apt update
sudo apt install espeak-ng
uv tool install --python 3.12 abogen
Arch Linux：
sudo pacman -S espeak-ng
uv tool install --python 3.12 abogen
Fedora：
sudo dnf install espeak-ng
uv tool install --python 3.12 abogen
Linux AMD ROCm 6.4：
uv tool install --python 3.12 "abogen[rocm]" \
--extra-index-url https://download.pytorch.org/whl/nightly/rocm6.4 \
--index-strategy unsafe-best-match
如果终端提示找不到 abogen：
echo "export PATH=\"/home/$USER/.local/bin:\$PATH\"" >> ~/.bashrc
source ~/.bashrc
macOS 安装
先安装 eSpeak NG：
brew install espeak-ng
使用 Python 3.12 安装：
uv tool install --python 3.12 abogen \
--with "kokoro @ git+https://github.com/hexgrad/kokoro.git,numpy<2"
Apple Silicon 可使用 MPS 加速，Intel Mac 会走 CPU 。
普通话有声书完整教程
第一步：先准备一小段中文测试
先别急着转换整本书。创建一个 UTF-8 编码的 TXT，写入：
这是普通话语音测试。
重庆银行今天发布了新的公告。
项目版本是二点零，价格是一百二十八元。
这段话可以同时检查普通话自然度、多音词、数字和标点停顿。
第二步：启动桌面版
abogen
也可以显式启动 PyQt 入口：
abogen-pyqt
把 TXT 、 EPUB 、 PDF 或 Markdown 拖进窗口，也可以直接粘贴文字。
第三步：选择普通话
语言必须选择：
Mandarin Chinese
Kokoro 对应的普通话代码是：
z
只更换中文音色、语言仍保留 English 时，分词和发音可能异常。语言与音色要一起切换。
第四步：选择中文音色
当前 Kokoro 插件列出八个中文音色：
zf_xiaobei
zf_xiaoni
zf_xiaoxiao
zf_xiaoyi
zm_yunjian
zm_yunxi
zm_yunxia
zm_yunyang
zf_ 和 zm_ 是中文音色 ID 的前缀。界面里的性别标签可能存在个别不一致，尤其是 zm_yunxia，以实际试听为准。
同一段中文逐个点击 Voice preview，重点听：
- • 人名和地名；
- • “重庆”“银行”等多音词；
- • 数字、日期和金额；
- • 中英文混排；
- • 句号、逗号带来的停顿。
第五步：设置语速
普通话可以先从：
0.9–1.0
开始试听。小说对白可能适合稍快，教材和知识类内容通常需要更慢。这里没有通用最佳值，以同一段样音比较最可靠。
第六步：确认章节和文本
EPUB 可以按章节选择；PDF 可以按页面范围处理。扫描版 PDF 如果无法复制文字，Abogen 当前没有内置 OCR，建议先用 OCR 工具生成可检索 PDF 或 TXT 。
检查文本时留意：
- • 页眉页脚有没有被反复读出；
- • 目录和页码要不要保留；
- • 脚注是否打断正文；
- • 英文缩写是否需要改写；
- • 专名和多音字是否需要手动替换。
第七步：选择输出格式
完整小说或教材，优先考虑：
M4B (with chapters)
需要后期剪辑：
WAV
希望手机和车机都方便播放：
MP3
普通话字幕建议：
Sentence
或：
Sentence + Comma
第八步：先生成一章
先生成一章或几分钟样音，检查多音字、音量、语速、断句和章节标题。确认设置后再把整本书加入队列。
长书处理时可以查看队列、取消任务并逐章保存。 CPU 电脑的等待时间会更长，属于正常情况。
Web UI 怎么用
启动：
abogen-web
浏览器打开：
http://localhost:8808
Web UI 更适合使用人物识别、多角色音色、发音覆盖、 EPUB 3 和 LLM 文本规范化。字幕文件 SRT 、 ASS 、 VTT 的直接输入支持目前更偏桌面版。
Web 服务默认监听 0.0.0.0:8808，没有完整的内置用户登录体系。只在本机使用时，应把端口限制为 127.0.0.1；不要直接把 8808 暴露到公网。
Voice Mixer 能不能克隆声音
Voice Mixer 会把多个已有音色按权重混合，用来微调听感。它没有上传真人样本并训练新声音的流程，也没有正式的声音克隆接口。
混合音色同样建议先用短句试听。权重增加不代表音色会线性变化，部分组合可能产生含混、失真或发音不稳定。
LLM 要求：常规转换可以完全不用
Abogen 的普通话 TTS 由 Kokoro 完成。导入文档、选择中文音色、生成有声书，不需要 ChatGPT 、 Claude 或其他 LLM 。
默认文本规范化模式使用 spaCy 。 LLM 只在 Web UI 的可选规范化功能中出现，用于处理缩写、撇号和特定文本替换。当前规则明显偏英语，纯中文内容启用后要先检查改写结果。
想接 LLM，需要什么接口
服务要兼容 OpenAI API：
GET /v1/models
POST /v1/chat/completions
配置项包括：
ABOGEN_LLM_BASE_URL
ABOGEN_LLM_API_KEY
ABOGEN_LLM_MODEL
ABOGEN_LLM_TIMEOUT
ABOGEN_LLM_CONTEXT_MODE
ABOGEN_LLM_PROMPT
本机 Ollama 示例：
ABOGEN_LLM_BASE_URL=http://localhost:11434
ABOGEN_LLM_API_KEY=***
ABOGEN_LLM_MODEL=llama3.1:8b
ABOGEN_LLM_TIMEOUT=45
ABOGEN_LLM_CONTEXT_MODE=sentence
当前客户端会向模型提供 apply_regex_replacements function tool 。模型最好支持 OpenAI 风格工具调用，并能稳定返回结构化 JSON 。只做普通话有声书时，可以把 LLM 功能保持关闭，安装更简单，隐私边界也更清楚。
如何完全离线使用
第一次安装和下载模型、音色时需要联网。下载完成后，在设置里执行：
Pre-download models and voices for offline use
再启用：
Disable Kokoro's internet access
程序会设置：
HF_HUB_OFFLINE=1
Hugging Face 遥测默认关闭。只使用 Kokoro 、本地文件和本机 Ollama 时，可以把语音生成及可选 LLM 处理都留在电脑上。
以下功能会产生网络访问：
- • 远程 OpenAI 兼容 LLM；
- • 首次模型和音色下载；
- • SuperTonic 首次自动下载；
- • 自动更新检查；
- • Calibre OPDS 与 Audiobookshelf 集成。
几个容易踩的坑
- 1. 普通话选了中文音色却仍用英文语言
语言改成 Mandarin Chinese，代码为 z，音色使用 zf_ 或 zm_ 开头的 ID 。 - 2. 扫描 PDF 读不出文字
当前没有 OCR 。先把扫描件转换成可检索 PDF 、 TXT 或 EPUB 。 - 3. 想要中文逐词高亮字幕
中文只有句级、行级和逗号级近似时间轴。逐词 token 时间戳目前只对英文可靠。 - 4. macOS 按 README 装 Python 3.13 报错
项目元数据限制 <3.13，改用 Python 3.12 。 - 5. Web UI 上传字幕文件没有反应
SRT 、 ASS 、 VTT 转语音优先用桌面版。 - 6. 长文转换很慢
CPU 可以运行，等待时间会更长。先转一章确认设置，避免整本书完成后才发现音色或语速不合适。 - 7. 多音字和人名读错
用短样音测试，必要时在 Web UI 设置发音覆盖，或在转换前直接替换文本。
隐私、密钥和版权
远程 LLM 规范化会把文本发送给对应服务。未出版书稿、公司材料和个人隐私内容，适合关闭远程 LLM，或改用本机 Ollama 。
Web UI 的 LLM Key 、 Calibre 密码和 Audiobookshelf Token 会进入本地配置。源码没有显示这些字段经过专门加密，应把配置目录当作明文敏感文件保护，不要提交到 Git 。
Abogen 使用 MIT License，Kokoro 使用 Apache-2.0 。软件开源不代表输入书籍自动获得有声化和公开发行权。生成有声书用于公开发布或商业传播前，还要确认书籍版权、模型与音色许可。
如果只是想把自己的笔记、已购电子书或获授权材料转成普通话有声书，推荐起步配置很简单：Python 3.12 、 Kokoro 、 Mandarin Chinese 、任选一个 zf_ 或 zm_ 音色、 0.9–1.0 语速、 M4B 或 MP3，LLM 先关闭。
你更想用它转换小说、学习资料，还是自己的长文笔记？
来源链接: https://github.com/denizsafak/abogen
