这是一份面向 Windows / Linux / macOS 用户的 ebook2audiobook 本地部署与使用笔记。它把电子书、文档、短文本在自己电脑上转成有声书，支持 GPU 加速、声音克隆、局域网 API 和 M4B 章节输出。
引子：想"听"书，你其实卡在这几步
先对号入座一下：
- 攒了几百本 EPUB、PDF，眼睛累了想"听"，结果发现冷门书根本没有有声版，热门书整本买又不值？
- 试过云朗读 App，但一想"我的书要上传到别人服务器"，隐私那关就过不去？
- 手机阅读 App 自带的"朗读"音色机械、不能后台、还不支持章节跳转，听两分钟就烦了？
- 自己找过 TTS 工具，配置劝退，长文本跑一半崩了还得从头来？
如果你中了两条以上，那 ebook2audiobook 值得你花十分钟。它不是一个"能念字的网页"，而是把电子书 → 分句 → TTS 合成 → 章节音频 → 有声书文件这条链路，完整地跑在你自己机器上的开源项目。
下面先把优点讲透，再上详细教程。
一、这套方案是什么
ebook2audiobook 是一个把电子书、文档或短文本转换为有声书的本地工具。它的核心流程是：读取电子书内容，按章节或片段拆分文本，调用 TTS 引擎生成语音，再把句子音频合成为章节音频和最终有声书文件。
适合的使用场景：
- 把 EPUB、MOBI、TXT、PDF、DOCX、HTML 等内容转换为有声书。
- 用网页界面手动上传、选择语言、选择声音并生成音频。
二、为什么选 ebook2audiobook：它到底好在哪
2.1 先说痛点：听书这条路上，传统方案有多尴尬
| |
|---|
| |
| 云朗读 App 要把书传到第三方服务器，隐私没保障还要订阅费 |
| 手机"朗读"音色机械、不能后台、不支持 M4B 章节跳转 |
| |
ebook2audiobook 的定位，正好补齐这一整片空白：在本地把书变成可章节跳转、可后台播放、还能定制声音的有声书，且内容不出本机。
2.2 6 大优点详解
① 隐私不出本机——最核心的卖点电子书和声音素材都在你自己的机器上处理，不必上传到任何第三方服务。对隐私敏感、或有不愿外传的文档的人来说，这一点比什么都重要。
② GPU 加速——长文本不再等到天荒地老可使用 CUDA、ROCm、MPS、XPU 等硬件后端。长文本转换速度明显优于纯 CPU；有 NVIDIA 显卡的话，一本几十万字的书也能在可接受时间内跑完。
③ 有声书级输出——M4B 才是"听得舒服"的格式支持输出 M4B、MP3、WAV、FLAC、M4A、OGG。其中 M4B 自带章节和元数据，对 Audible 类播放器、iOS 图书、各种听书 App 都更友好，进度、章节一目了然。
④ 断点续传 + 缓存——失败不用从零开始支持断点和缓存，中途失败后通常不必从头重跑。对动辄几小时的转换任务来说，这是"敢不敢跑整本"的关键保障。
⑤ 网页 + 局域网 API 双模式——既能点也能批既有适合小白的网页界面（上传、选语言、选声音、生成），也有局域网 API，可供 NAS、自动化脚本或其他程序调用，适合批量处理和服务器常驻。
⑥ 一切可控、可迁移、可清理依赖、模型、缓存、输出都可以约束在项目目录中，便于整体迁移、备份和清理。不像某些工具把模型散落到系统各处，重装就抓瞎。
2.3 它还能做什么（能力清单）
光说优点不够，直接看硬指标：
- 输入格式极广：EPUB、MOBI、AZW3、PDF、TXT、RTF、DOC、DOCX、HTML、ODT、甚至图片。
- TTS 引擎可选：XTTSv2、Bark、Piper、VITS、Fairseq、Tortoise 等，不同引擎在音色、速度、语言上各有侧重。
- 声音克隆：可上传参考音频，生成接近指定声音的朗读——想让"自己的声音"念书给孩子听，技术上完全可行。
- 多语言朗读：语言能力取决于所选 TTS 引擎和模型（中文
zho、英文 eng、日文 jpn 等）。 - 章节 / 元数据 / 长音频拆分：成品天然适配有声书播放器。
- SML 标记：可控制停顿、换声音等朗读细节，做"旁白 + 对白"分角色也不是梦。
- 硬件后端：CUDA、ROCm、MPS、XPU，按系统和模型支持选用。
2.4 谁最适合用（对号入座）
✅ 通勤 / 家务想"听"书、眼睛累的人✅ 有大量 EPUB / PDF 想转听的人✅ 在意隐私、不想把书上传第三方的人✅ 有 NVIDIA GPU、想加速转换的人✅ 想做"专属声音"朗读（声音克隆）的人
❌ 完全没有命令行基础、且不愿折腾环境的人——它毕竟要装 Python、虚拟环境、FFmpeg、Calibre。❌ 想在低端电脑零成本跑"高质量"TTS 的人——CPU 能跑，但现代高质量模型偏慢，要有心理预期。
注意：本文采用的是非 Docker 的本地部署（Windows 手动安装），这样更灵活，也更便于控制模型与缓存目录。
三、部署前准备
建议准备：
- Windows、Linux 或 macOS 系统。
- FFmpeg，Windows 建议使用 full / shared 构建。
- NVIDIA GPU 用户需要安装合适的显卡驱动，并安装匹配 CUDA 的 PyTorch。
- OCR 场景可安装 Tesseract，用于图片型 PDF 或图片文字识别。
- 预留足够磁盘空间，模型、缓存和中间音频可能占用较大空间。
注意：
- 不建议把模型缓存散落到系统用户目录，最好统一放在项目相关目录或专门的数据目录。
四、推荐目录结构
下面是通用结构示例，可按自己的机器调整：
ebook2audiobook/# 项目根目录，所有服务从这里启动├─ .venv/# Python 虚拟环境，隔离项目依赖├─ models/# 模型缓存目录，保存 TTS 模型├─ tools/# 外部工具目录，例如 FFmpeg、Calibre├─ ebooks/# 可选：放待转换电子书├─ voices/# 可选：放声音克隆参考音频├─ audiobooks/# 默认输出目录，保存最终有声书├─ run/# 运行期临时文件、上传缓存、pid 文件└─ tmp/# 转换处理中间目录、Calibre 临时缓存
五、Windows 手动部署
以下示例使用 PowerShell。请把示例路径替换成自己的通用项目目录。
cd C:\AI# 进入准备放置项目的上级目录。git clone https://github.com/DrewThomasson/ebook2audiobook.git# 克隆官方仓库到本地。cd .\ebook2audiobook# 进入项目目录。python -m venv .venv# 创建 Python 虚拟环境，避免污染系统 Python。.\.venv\Scripts\Activate.ps1# 激活当前项目的虚拟环境。python -m pip install --upgrade pip# 升级 pip，减少安装依赖时的兼容问题。pip install -r requirements.txt# 安装项目依赖。
如果使用 NVIDIA GPU，通常还需要安装与显卡驱动匹配的 PyTorch CUDA 版本。下面只是示例，实际 CUDA 版本要按自己的环境选择。
pip uninstall -y torch torchaudio torchvision# 卸载可能装错的 CPU 版或不匹配版本。pip install torch torchaudio torchvision --index-url https://download.pytorch.org/whl/cuXXX# 安装示例 CUDA 版 PyTorch，请按官方说明替换 cuXXX。python -c ”import torch; print(torch.cuda.is_available()); print(torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'CPU')”# 检查 PyTorch 是否能看到 CUDA。
六、FFmpeg 与 Calibre
FFmpeg 用于音频编码、合并和格式转换。Calibre 用于把 EPUB 以外的电子书格式转换成内部 EPUB。
Windows 上建议：
- FFmpeg 使用 full / shared 构建，避免缺少动态库。
- Calibre 可以使用安装版，也可以使用便携版。
- 如果希望完全隔离，可以把 FFmpeg 和 Calibre 放到项目的
tools/ 目录。 - 启动脚本中临时追加 PATH，比长期修改系统 PATH 更容易迁移。
示例：
$ffmpegBin = ”.\tools\ffmpeg\bin”# 假设 FFmpeg 解压在项目 tools 目录中。$calibreBin = ”.\tools\Calibre”# 假设 Calibre 位于项目 tools 目录中。$env:PATH = ”$ffmpegBin;$calibreBin;$env:PATH”# 仅给当前终端追加 PATH，不影响系统其它项目。ffmpeg -version# 检查 FFmpeg 是否可用。ebook-convert --version# 检查 Calibre 的 ebook-convert 是否可用。
七、启动网页界面
基础启动方式：
cd C:\AI\ebook2audiobook# 进入项目目录。.\.venv\Scripts\Activate.ps1# 激活项目虚拟环境。python app.py --script_mode native# 启动 Gradio 网页界面。
启动后浏览器访问：
局域网访问时，把 127.0.0.1 替换成运行电脑的局域网 IP：
八、启动本地 API
如果项目中已有 FastAPI 包装脚本，可用类似方式启动：
cd C:\AI\ebook2audiobook# 进入项目目录。.\.venv\Scripts\Activate.ps1# 激活项目虚拟环境。python local-api.py# 启动本地 API 服务。
API 文档地址：
http://127.0.0.1:7861/docs
局域网 API 地址：
九、API 调用示例
下面是 PowerShell 调用示例。所有路径和 IP 都是占位符，使用时请替换。
$api = ”http://<局域网IP>:7861/convert”# 设置 API 地址，局域网调用时替换成服务器电脑的 IP。$body = @{# 准备请求体，提交本地服务器上可访问的电子书路径。 ebook_path = ”D:\Books\example.epub”# 设置电子书文件路径，路径必须能被服务器电脑访问。 language = ”zho”# 设置电子书语言，zho 表示中文。 tts_engine = ”XTTS”# 设置 TTS 引擎。 device = ”cuda”# 设置使用 CUDA GPU；没有 GPU 时可改为 cpu。 output_format = ”m4b”# 设置输出格式，m4b 更适合有声书。 output_dir = ”D:\Audiobooks”# 设置输出目录，路径必须在服务器电脑上存在或可创建。 chapter_range = ”3-8”# 设置章节范围，留空或删除此行表示转换全部。} | ConvertTo-Json# 把 PowerShell 哈希表转换成 JSON 请求体。$job = Invoke-RestMethod -Method Post -Uri $api -ContentType ”application/json” -Body $body# 发送转换请求，并得到任务 ID。$job# 查看返回的任务信息。
查询任务状态：
$jobId = ””# 设置任务 ID，这里使用提交任务后返回的 job_id。Invoke-RestMethod -Uri ”http://<局域网IP>:7861/status/$jobId”# 请求任务状态。
暂停、继续、停止：
Invoke-RestMethod -Method Post -Uri ”http://<局域网IP>:7861/pause/$jobId”# 暂停正在运行的任务。Invoke-RestMethod -Method Post -Uri ”http://<局域网IP>:7861/resume/$jobId”# 继续已暂停的任务。Invoke-RestMethod -Method Post -Uri ”http://<局域网IP>:7861/stop/$jobId”# 停止任务。
下载结果：
Invoke-WebRequest -Uri ”http://<局域网IP>:7861/download/$jobId” -OutFile ”.\result.m4b”# 下载转换完成后的有声书文件。
十、常用参数说明
| | |
|---|
language | | zho |
tts_engine | | XTTS |
device | | cuda |
voice_path | | D:\Voices\sample.wav |
output_format | | m4b |
output_dir | | D:\Audiobooks |
chapter_range | | 3-8 |
十一、章节范围
章节范围适合长书测试、分批转换或只转换指定章节。
支持写法：
注意：
- EPUB 的章节结构并没有完全统一标准，软件识别到的"章节"有时更接近"文本片段"。
- 如果要精确选择，建议先开启章节预览，再确认每段内容。
十二、使用建议
- EPUB 或 MOBI 通常比 PDF 更适合自动章节识别。
- CPU 可以跑，但现代高质量 TTS 通常较慢；有条件建议使用 GPU。
- 第一次使用某个模型时，需要下载模型，耗时和磁盘占用都较大。
- 短文本测试时可以先只选一两个章节，确认声音、语速、语言都正确后再转换整本。
- 输出 M4B 适合有声书播放器，MP3 适合通用播放器。
- 长书建议分段或指定章节范围转换，降低失败后重跑成本。
十三、启停与清理
建议为本地部署准备成对脚本：
启动.cmd：启动前先停止旧残留，再启动 Web 和 API。停止.cmd：停止 Web、API、TTS 子进程、FFmpeg 和转换残留进程。cleanup-project-temp.cmd
安全清理原则：
- 可以清理：
run/ 下的临时目录、上传缓存、日志和 pid 文件。 - 可以清理：
tmp/calibre-temp、tmp/calibre-cache、tmp/hf-temp。 - 谨慎清理：
tmp/proc-*，这里可能包含断点恢复、章节音频缓存和中间 EPUB。 - 不建议清理：
models/，否则需要重新下载模型。 - 不建议清理：
tools/，否则 FFmpeg、Calibre 等工具会丢失。 - 不建议清理：
audiobooks/，这里通常是最终输出。
十四、常见问题
转换很慢
可能原因：
处理建议：
convert2epub 失败
可能原因：
- Calibre 没装好，或
ebook-convert 不在 PATH。 - PDF / 图片内容需要 OCR，但 OCR 依赖不可用。
处理建议：
- 确认 FFmpeg 和 Calibre 能在当前终端运行。
- 避免在权限复杂的系统临时目录中运行，尽量使用项目内临时目录。
网页打不开
处理建议：
- 确认服务是否已经启动完成，首次启动可能需要几分钟。
- 重启服务后刷新浏览器页面，必要时清理浏览器缓存或 Cookie。
十五、更新与维护
建议更新前先备份：
models/voices/audiobooks/
通用更新流程：
cd C:\AI\ebook2audiobook# 进入项目目录。.\停止.cmd# 停止正在运行的服务。git pull# 拉取上游代码更新。.\.venv\Scripts\Activate.ps1# 激活虚拟环境。pip install -r requirements.txt# 更新依赖。.\启动.cmd# 重新启动服务。
十六、一句话结论
ebook2audiobook 的价值在于：它把"电子书变有声书"这件原本要么花钱买、要么冒险上传云端、要么自己硬啃 TTS 的事，变成了在自己电脑上可控、可加速、可定制声音、可断点续传的一条龙。部署时最重要的不是"装好"，而是把虚拟环境、模型目录、工具目录和输出目录规划清楚，并养成"先小章节试跑、再整本转换"的习惯。
资料来源：
- 官方 README 中的功能、格式、硬件要求和基本用法。
- 本地部署经验：依赖隔离、GPU 加速、局域网 API、启动停止脚本、缓存目录清理。
你最想把哪类书转成有声书？是想解放双眼的通勤党，还是想用"自己的声音"给家人念书的玩家？欢迎在评论区聊聊你的场景。
