ebook2audiobook 本地部署与使用笔记

本笔记用于记录 ebook2audiobook 的功能、优点、本地非 Docker 部署方法、日常使用、API 调用和清理维护。

项目简介

ebook2audiobook 是一个把电子书、文档或短文本转换为有声书的本地工具。它的核心流程是：读取电子书内容，按章节或片段拆分文本，调用 TTS 引擎生成语音，再把句子音频合成为章节音频和最终有声书文件。

适合的使用场景：

• 把 EPUB、MOBI、TXT、PDF、DOCX、HTML 等内容转换为有声书。
• 用网页界面手动上传、选择语言、选择声音并生成音频。
• 在局域网内通过 API 提交转换任务。
• 使用 GPU 加速较长文本的语音生成。
• 对长书按章节或指定章节范围分批转换。

主要功能

• 支持多种输入格式：EPUB、MOBI、AZW3、PDF、TXT、RTF、DOC、DOCX、HTML、ODT、图片等。
• 支持网页界面操作，适合不熟悉命令行的用户。
• 支持命令行 headless 模式，适合批处理和服务器运行。
• 支持局域网 API，可供 NAS、自动化脚本或其他程序调用。
• 支持多种 TTS 引擎，包括 XTTSv2、Bark、Piper、VITS、Fairseq、Tortoise 等。
• 支持声音克隆，可上传参考音频生成接近指定声音的朗读。
• 支持多语言朗读，语言能力取决于所选 TTS 引擎和模型。
• 支持输出 M4B、MP3、WAV、FLAC、M4A、OGG 等格式。
• 支持章节、元数据和长音频拆分，适合有声书播放器管理。
• 支持 SML 标记，可控制停顿、换声音等朗读细节。
• 可使用 CUDA、ROCm、MPS、XPU 等硬件后端加速，具体取决于系统和模型支持。

优点

• 本地运行，电子书和声音素材不必上传到第三方服务。
• 可使用 GPU，长文本转换速度明显优于纯 CPU。
• 输出格式更贴近有声书使用习惯，M4B 对章节和播放器更友好。
• 支持断点和缓存，中途失败后通常不必从零开始。
• 可同时服务网页用户和局域网 API 用户。
• 依赖、模型、缓存、输出都可以约束在项目目录中，便于迁移、备份和清理。

部署前准备

建议准备：

• Windows、Linux 或 macOS 系统。
• Python 3.10 到 3.12。
• Git。
• FFmpeg，Windows 建议使用 full/shared 构建。
• Calibre，用于多种电子书格式转换。
• NVIDIA GPU 用户需要安装合适的显卡驱动，并安装匹配 CUDA 的 PyTorch。
• OCR 场景可安装 Tesseract，用于图片型 PDF 或图片文字识别。
• 预留足够磁盘空间，模型、缓存和中间音频可能占用较大空间。

注意：

• 本笔记不使用 Docker 部署方式。
• 不建议把项目直接装进系统 Python 环境。
• 不建议把模型缓存散落到系统用户目录，最好统一放在项目相关目录或专门的数据目录。
• 不要转换 DRM 保护或来源不合法的电子书。

推荐目录结构

下面是通用结构示例，可按自己的机器调整：

<code class="language-text">ebook2audiobook/                 # 项目根目录，所有服务从这里启动
├─ .venv/                        # Python 虚拟环境，隔离项目依赖
├─ models/                       # 模型缓存目录，保存 TTS 模型
├─ tools/                        # 外部工具目录，例如 FFmpeg、Calibre
├─ ebooks/                       # 可选：放待转换电子书
├─ voices/                       # 可选：放声音克隆参考音频
├─ audiobooks/                   # 默认输出目录，保存最终有声书
├─ run/                          # 运行期临时文件、上传缓存、pid 文件
└─ tmp/                          # 转换处理中间目录、Calibre 临时缓存
</code>

Windows 手动部署

以下示例使用 PowerShell。请把示例路径替换成自己的通用项目目录。

<code class="language-powershell">cd C:AI # 进入准备放置项目的上级目录。
git clone https://github.com/DrewThomasson/ebook2audiobook.git # 克隆官方仓库到本地。
cd .ebook2audiobook # 进入项目目录。
python -m venv .venv # 创建 Python 虚拟环境，避免污染系统 Python。
..venvScriptsActivate.ps1 # 激活当前项目的虚拟环境。
python -m pip install --upgrade pip # 升级 pip，减少安装依赖时的兼容问题。
pip install -r requirements.txt # 安装项目依赖。
</code>

如果使用 NVIDIA GPU，通常还需要安装与显卡驱动匹配的 PyTorch CUDA 版本。下面只是示例，实际 CUDA 版本要按自己的环境选择。

<code class="language-powershell">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。
</code>

FFmpeg 与 Calibre

FFmpeg 用于音频编码、合并和格式转换。Calibre 用于把 EPUB 以外的电子书格式转换成内部 EPUB。

Windows 上建议：

• FFmpeg 使用 full/shared 构建，避免缺少动态库。
• Calibre 可以使用安装版，也可以使用便携版。
• 如果希望完全隔离，可以把 FFmpeg 和 Calibre 放到项目的 tools/ 目录。
• 启动脚本中临时追加 PATH，比长期修改系统 PATH 更容易迁移。

示例：

<code class="language-powershell">$ffmpegBin = ".toolsffmpegbin" # 假设 FFmpeg 解压在项目 tools 目录中。
$calibreBin = ".toolsCalibre" # 假设 Calibre 位于项目 tools 目录中。
$env:PATH = "$ffmpegBin;$calibreBin;$env:PATH" # 仅给当前终端追加 PATH，不影响系统其它项目。
ffmpeg -version # 检查 FFmpeg 是否可用。
ebook-convert --version # 检查 Calibre 的 ebook-convert 是否可用。
</code>

启动网页界面

基础启动方式：

<code class="language-powershell">cd C:AIebook2audiobook # 进入项目目录。
..venvScriptsActivate.ps1 # 激活项目虚拟环境。
python app.py --script_mode native # 启动 Gradio 网页界面。
</code>

启动后浏览器访问：

<code class="language-text">http://127.0.0.1:7860/
</code>

局域网访问时，把 127.0.0.1 替换成运行电脑的局域网 IP：

<code class="language-text">http://<局域网IP>:7860/
</code>

启动本地 API

如果项目中已有 FastAPI 包装脚本，可用类似方式启动：

<code class="language-powershell">cd C:AIebook2audiobook # 进入项目目录。
..venvScriptsActivate.ps1 # 激活项目虚拟环境。
python local-api.py # 启动本地 API 服务。
</code>

API 文档地址：

<code class="language-text">http://127.0.0.1:7861/docs
</code>

局域网 API 地址：

<code class="language-text">http://<局域网IP>:7861/docs
</code>

API 调用示例

下面是 PowerShell 调用示例。所有路径和 IP 都是占位符，使用时请替换。

<code class="language-powershell">$api = "http://<局域网IP>:7861/convert" # 设置 API 地址，局域网调用时替换成服务器电脑的 IP。
$body = @{ # 准备请求体，提交本地服务器上可访问的电子书路径。
    ebook_path = "D:Booksexample.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 # 查看返回的任务信息。
</code>

查询任务状态：

<code class="language-powershell">$jobId = "<job_id>" # 设置任务 ID，这里使用提交任务后返回的 job_id。
Invoke-RestMethod -Uri "http://<局域网IP>:7861/status/$jobId" # 请求任务状态。
</code>

暂停、继续、停止：

<code class="language-powershell">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" # 停止任务。
</code>

下载结果：

<code class="language-powershell">Invoke-WebRequest -Uri "http://<局域网IP>:7861/download/$jobId" -OutFile ".result.m4b" # 下载转换完成后的有声书文件。
</code>

常用参数说明

章节范围

章节范围适合长书测试、分批转换或只转换指定章节。

支持写法：

• 3-8：转换第 3 到第 8 个章节或片段。
• 1,4,9：只转换第 1、第 4、第 9 个章节或片段。
• 2-4,8,12-15：混合范围和单个章节。
• 留空：转换全部。

注意：

• 章节编号从 1 开始。
• EPUB 的章节结构并没有完全统一标准，软件识别到的“章节”有时更接近“文本片段”。
• 如果要精确选择，建议先开启章节预览，再确认每段内容。

使用建议

• EPUB 或 MOBI 通常比 PDF 更适合自动章节识别。
• 图片型 PDF 需要 OCR，耗时会明显增加。
• 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。
• 不建议清理：.venv/，否则需要重新安装依赖。
• 不建议清理：models/，否则需要重新下载模型。
• 不建议清理：tools/，否则 FFmpeg、Calibre 等工具会丢失。
• 不建议清理：audiobooks/，这里通常是最终输出。

常见问题

转换很慢

可能原因：

• 当前使用 CPU，而不是 GPU。
• 第一次加载模型，需要下载或初始化。
• 文本过长，句子切分数量多。
• 使用的 TTS 引擎本身较慢。
• PDF 或图片输入触发 OCR。

处理建议：

• 检查 device 是否选择 cuda。
• 检查 PyTorch 是否能识别 CUDA。
• 先用章节范围转换少量章节测试。
• 优先使用结构清楚的 EPUB。

GPU 显存停止后仍有占用

停止本项目后，显存不一定归零。Windows 桌面、浏览器、笔记软件、聊天软件、视频软件都可能占用显存。

判断原则：

• 如果 nvidia-smi 里还有本项目 Python 或 TTS 进程，说明项目没有停干净。
• 如果只剩浏览器、桌面窗口管理器、输入法、笔记软件等，通常不是本项目残留。

convert2epub 失败

可能原因：

• Calibre 没装好，或 ebook-convert 不在 PATH。
• Calibre 临时目录权限异常。
• 输入文件损坏。
• 文件名、目录权限或临时目录被占用。
• PDF/图片内容需要 OCR，但 OCR 依赖不可用。

处理建议：

• 优先用 EPUB 格式测试。
• 确认 FFmpeg 和 Calibre 能在当前终端运行。
• 停止服务后清理临时目录再重试。
• 避免在权限复杂的系统临时目录中运行，尽量使用项目内临时目录。

网页打不开

处理建议：

• 确认服务是否已经启动完成，首次启动可能需要几分钟。
• 本机访问用 127.0.0.1。
• 局域网访问用运行电脑的真实局域网 IP。
• 确认防火墙允许 7860 和 7861 端口。
• 重启服务后刷新浏览器页面，必要时清理浏览器缓存或 Cookie。

更新与维护

建议更新前先备份：

• models/
• voices/
• audiobooks/
• 自己写的启动、停止和清理脚本
• 自己修改过的配置文件

通用更新流程：

<code class="language-powershell">cd C:AIebook2audiobook # 进入项目目录。
.停止.cmd # 停止正在运行的服务。
git pull # 拉取上游代码更新。
..venvScriptsActivate.ps1 # 激活虚拟环境。
pip install -r requirements.txt # 更新依赖。
.启动.cmd # 重新启动服务。
</code>

资料来源

• 官方仓库：https://github.com/DrewThomasson/ebook2audiobook
• 官方 README 中的功能、格式、硬件要求和基本用法。
• 本地部署经验：依赖隔离、GPU 加速、局域网 API、启动停止脚本、缓存目录清理。