# audio_book_reader

**Repository Path**: amdyhaha/audio_book_reader

## Basic Information

- **Project Name**: audio_book_reader
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-04
- **Last Updated**: 2026-08-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Audio Book Reader

> 开源有声书生成系统 —— 从 [Project Gutenberg](https://www.gutenberg.org/) 拉取公版图书，通过 [Piper TTS](https://github.com/rhasspy/piper) 本地神经网络合成语音，对接 [Audiobookshelf](https://www.audiobookshelf.org/) 播放管理。
>
> 任何人都可贡献文字与语音，共建开放有声图书馆。

<p align="center">
  <img src="https://img.shields.io/badge/license-MIT-green" alt="License">
  <img src="https://img.shields.io/badge/python-3.9+-blue" alt="Python">
  <img src="https://img.shields.io/badge/TTS-Piper-orange" alt="Piper TTS">
</p>

---

## ✨ 特性

| 模块 | 说明 |
|------|------|
| **图书抓取** | 搜索与下载 Gutenberg 海量公版图书，支持 TXT / EPUB 格式 |
| **多格式解析** | 适配器模式解析 EPUB / Markdown / TXT，按章节智能分段 |
| **本地 TTS** | 基于 Piper 神经网络，离线合成，隐私友好，无需 GPU |
| **多引擎架构** | 抽象基类 + 注册表模式，可插拔 Edge TTS、Coqui 等 |
| **音频管道** | 分段合成 → 章节合并 → MP3 导出，支持断点续传 |
| **Web 管理面板** | 章节浏览、一键生成、SSE 实时进度推送、在线播放 |
| **边听边读** | 播放时同步高亮当前文本段落，字符加权精确定位 |
| **Audiobookshelf** | 目录结构自动适配 + API 注册，专业有声书服务器 |
| **开源协作** | 元数据内置贡献者字段，支持文本/语音/代码三种贡献 |

## 🏗 架构

```
┌──────────────────────────────────────────────────────────┐
│                     Audio Book Reader                     │
├──────────────────────────────────────────────────────────┤
│  CLI 入口 (cli.py)          Web API (api_server.py)       │
│  ├─ search / fetch           ├─ 章节列表 / 生成 / 进度       │
│  ├─ parse / generate         └─ 音频服务 / 文本同步          │
│  └─ list-voices                                            │
├──────────────────────────────────────────────────────────┤
│  核心引擎                                                   │
│  ├─ book_parser.py    ← 多格式适配器 (TXT/EPUB/Markdown)      │
│  ├─ tts_engine.py     ← TTS 抽象基类 + 注册表                  │
│  ├─ piper_tts.py      ← Piper TTS 引擎实现                  │
│  ├─ audio_pipeline.py ← 音频合成管道 (分段→合并→导出)          │
│  └─ integrate.py      ← Audiobookshelf 对接 (目录+API)        │
├──────────────────────────────────────────────────────────┤
│  数据层                                                    │
│  └─ models.py / metadata.py  ← 数据模型、配置、元数据管理       │
├──────────────────────────────────────────────────────────┤
│  外部系统                                                   │
│  ├─ Project Gutenberg  ← 公版图书源                         │
│  ├─ Piper TTS          ← 神经网络语音合成                     │
│  └─ Audiobookshelf     ← 有声书播放服务器                     │
└──────────────────────────────────────────────────────────┘
```

**数据流：**
```
Gutenberg/本地 → 文本解析 → List<Segment> → Piper TTS → 分段WAV
                                                          ↓
               Audiobookshelf 播放 ← output/final/ ← 章节MP3合并
                                                          ↑
                 Web 面板 SSE 进度 ←── 生成管理 ←──┘
```

## 🚀 快速开始

### 环境要求

- **Python** 3.9+
- **Node.js** 18+（Audiobookshelf 需要）
- **ffmpeg**（MP3 编码，需在 PATH 中）
  - Windows: `winget install ffmpeg` 或 [下载](https://ffmpeg.org/download.html)

### 安装

```bash
git clone https://gitee.com/amdyhaha/audio_book_reader.git
cd audio_book_reader

# 安装 Python 依赖
pip install -r requirements.txt

# 下载中文语音模型（国内用 hf-mirror 镜像）
$env:PIPER_MIRROR='https://hf-mirror.com/rhasspy/piper-voices/resolve/main'
python scripts/cli.py download-voice zh_CN-huayan-medium

# 安装 Audiobookshelf (可选)
cd audiobookshelf && npm ci && cd client && npm ci && npm run generate && cd ../..
```

### 一键启动

```bash
# 启动 Web 管理面板
python scripts/api_server.py

# 浏览器访问: http://localhost:8899
```

## 📖 使用指南

### Web 管理面板（推荐）

访问 `http://localhost:8899`：

1. **左侧章节列表** —— 浏览书籍所有章节，每回显示段数与字数
2. **▶ 生成按钮** —— 点击生成音频，SSE 实时推送进度条
3. **▶ 播放按钮** —— 生成完成后在线播放
4. **右侧文本面板** —— 播放时同步显示文字，字符加权高亮跟随
5. **📍 跟随开关** —— 可切换自动滚动/自由浏览模式
6. **一键生成未完成** —— 批量生成所有未完成章节

### 命令行工具

```bash
# 搜索图书
python scripts/cli.py search "红楼梦"

# 下载图书文本
python scripts/cli.py fetch 24264 --format txt

# 查看图书信息
python scripts/cli.py info 24264

# 解析文本（查看分段结果）
python scripts/cli.py parse books/text/24264.txt --language zh

# 查看可用语音模型
python scripts/cli.py list-voices

# 下载语音模型
python scripts/cli.py download-voice zh_CN-huayan-medium

# 一键生成有声书（CLI 全流程）
python scripts/cli.py generate books/text/24264.txt \
  --title "红楼梦" --author "曹雪芹" \
  --language zh --voice zh_CN-huayan-medium \
  --output-format mp3

# 查看已生成列表
python scripts/cli.py list
```

### 使用本地文件

将任意 TXT / EPUB / Markdown 文件放入 `books/` 目录，创建对应的 `.meta.json` 元数据文件：

```json
{
  "title": "我的书",
  "author": "作者名",
  "language": "zh"
}
```

然后在 Web 面板中即可看到该书，按章节生成音频。

## ⚙ 配置

编辑 `config/config.yaml`：

```yaml
# TTS 引擎
tts:
  engine: "piper"          # piper | edge | coqui
  language: "zh"           # 默认语言
  speed: 1.0               # 语速 (0.5~2.0)
  volume: 1.0              # 音量 (0.0~2.0)

# Piper TTS
piper:
  default_model: "zh_CN-huayan-medium"
  use_cuda: false           # GPU 加速（需 onnxruntime-gpu）
  max_chunk_size: 500       # 单次合成最大字符数

# 音频输出
audio:
  format: "mp3"             # mp3 | wav | ogg | flac
  mp3_bitrate: "128k"
  silence_padding: 500      # 段间静音(ms)

# Audiobookshelf
audiobookshelf:
  api_url: "http://localhost:13378"
  api_token: ""             # 在 ABS 管理后台 → 设置 → 用户 → API Token
  library_id: ""            # 音频库 ID
  auto_register: false      # 生成后自动触发扫描

# 日志
logging:
  level: "INFO"             # DEBUG | INFO | WARNING | ERROR
```

## 🔊 语音模型

### 中文模型

| 模型名 | 质量 | 描述 | 下载 |
|--------|------|------|------|
| `zh_CN-huayan-medium` | Medium | 女声（花颜） | `download-voice zh_CN-huayan-medium` |

### 英文模型

| 模型名 | 质量 | 描述 |
|--------|------|------|
| `en_US-lessac-medium` | Medium | 清晰美式女声 |
| `en_US-amy-medium` | Medium | 自然美式女声 |
| `en_US-libritts-high` | High | LibriTTS 高质量 |
| `en_US-ryan-high` | High | 高质量男声 |

> 更多模型请访问 [Piper 语音模型库](https://huggingface.co/rhasspy/piper-voices)。
> 国内用户设置环境变量 `PIPER_MIRROR=https://hf-mirror.com/rhasspy/piper-voices/resolve/main` 使用镜像下载。

## 🔌 Audiobookshelf 集成

Audiobookshelf 是本项目的播放引擎，提供专业的书架管理、多端同步、倍速播放等功能。

### 方式一：目录扫描（推荐）

本项目的 `output/final/` 目录结构天然符合 Audiobookshelf 规范：

```
output/final/
  曹雪芹/
    红楼梦/
      第1回_甄士隱夢幻識通靈.mp3
      第2回_賈夫人仙逝揚州城.mp3
      ...
      metadata.json
```

在 Audiobookshelf 中创建音频库，将路径指向 `output/final/`，即可自动识别。

### 方式二：API 注册

在 `config.yaml` 中配置 API Token：
```yaml
audiobookshelf:
  api_token: "eyJhbGciOi..."
  library_id: "lib_xxx"
  auto_register: true
```

### 启动 Audiobookshelf

```bash
cd audiobookshelf
# 安装依赖（如未安装）
npm ci && cd client && npm ci && npm run generate && cd ..
# 启动服务（默认端口 13378）
node index.js
```

访问 `http://localhost:13378`，创建账户后即可使用。

## 🏗 项目结构

```
audio_book_reader/
├── scripts/                   # 核心引擎
│   ├── models.py              #   数据模型 (10 个数据类)
│   ├── metadata.py            #   元数据管理 + 配置加载
│   ├── fetch_books.py         #   Gutenberg 图书抓取
│   ├── book_parser.py         #   多格式文本解析器 (适配器模式)
│   ├── tts_engine.py          #   TTS 抽象基类 + 注册表
│   ├── piper_tts.py           #   Piper TTS 引擎实现
│   ├── audio_pipeline.py      #   音频合成管道
│   ├── integrate.py           #   Audiobookshelf 对接
│   ├── api_server.py          #   FastAPI Web 服务
│   └── cli.py                 #   命令行入口
├── templates/
│   └── index.html             # Web 管理面板前端
├── config/
│   └── config.yaml            # 全局配置
├── audiobookshelf/            # Audiobookshelf 源码 (git submodule)
├── voices/                    # Piper 语音模型 (需自行下载)
├── output/                    # 输出目录
│   ├── raw/                   #   分段原始 WAV
│   └── final/                 #   最终合并 MP3 + 元数据
├── books/                     # 图书源文件缓存
│   ├── text/                  #   文本
│   └── epub/                  #   EPUB
├── start.py                   # 一键启动脚本
├── requirements.txt
├── .gitignore
├── LICENSE                    # MIT
└── README.md
```

## 🤝 贡献指南

欢迎贡献文本、语音模型、代码或文档！

### 贡献图书文本
1. Fork 仓库
2. 准备文本文件（TXT / EPUB / Markdown），放入 `books/`
3. 添加 `.meta.json` 填写书名、作者等基本信息
4. 提交 PR

### 贡献语音模型
1. 训练或获取 Piper 兼容的语音模型（`.onnx` + `.json`）
2. 将模型信息添加到 `scripts/piper_tts.py` 的 `PRESET_VOICES` 字典
3. 提交 PR（注意：模型文件不入库，仅提交配置信息）

### 贡献代码
1. Fork → Feature 分支 → 遵循现有代码风格 → PR
2. 新 TTS 引擎：继承 `BaseTTSEngine`，注册到 `TTSEngineRegistry`
3. 新文本格式：继承 `BaseBookParser`，注册到 `ParserRegistry`

## 📋 API 文档

| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/books` | GET | 书籍列表 |
| `/api/books/{id}` | GET | 书籍详情 + 章节列表 |
| `/api/chapters/{book_id}/{idx}/text` | GET | 章节文本内容 |
| `/api/chapters/{book_id}/{idx}/generate` | POST | 启动章节生成 |
| `/api/chapters/{book_id}/{idx}/progress` | GET | SSE 进度推送 |
| `/audio/{author}/{title}/{chapter}.mp3` | GET | 音频文件服务 |

### SSE 进度事件格式

```json
{
  "event": "progress",
  "data": {
    "state": "running",
    "progress": 45,
    "progress_text": "合成中 5/21 (1850字)",
    "audio_url": "",
    "error": ""
  }
}
```

## 🛠 技术栈

| 层级 | 技术 |
|------|------|
| 后端 API | Python 3.13 / FastAPI / Uvicorn |
| 前端 | 纯 HTML/CSS/JS / SSE |
| TTS 引擎 | Piper TTS / ONNX Runtime |
| 音频处理 | pydub / wave / ffmpeg |
| 图书来源 | gutenbergpy / urllib |
| 文本解析 | ebooklib / BeautifulSoup4 |
| 配置 | PyYAML |
| 播放器 | Audiobookshelf (Node.js / Nuxt.js) |

## 📝 路线图

- [x] Piper TTS 引擎（中文+英文）
- [x] Gutenberg 图书抓取（搜索/下载）
- [x] 多格式文本解析（TXT/EPUB/Markdown）
- [x] Web 管理面板 + SSE 进度推送
- [x] 边听边读文本同步
- [x] Audiobookshelf 集成
- [ ] Edge TTS 引擎（免模型，云端合成）
- [ ] 精确字段时间戳（当前为字符加权估算）
- [ ] Docker Compose 一键部署
- [ ] 声音克隆（Voice Cloning）
- [ ] 多语言混读（中英混合段落）
- [ ] 移动端适配

## 📄 依赖致谢

- [Piper TTS](https://github.com/rhasspy/piper) — 本地神经网络 TTS
- [Project Gutenberg](https://www.gutenberg.org/) — 公版图书库
- [Audiobookshelf](https://github.com/advplyr/audiobookshelf) — 开源有声书服务器
- [gutenbergpy](https://github.com/raduangelescu/gutenbergpy) — Gutenberg Python 客户端
- [pydub](https://github.com/jiaaro/pydub) — 音频处理
- [ebooklib](https://github.com/aerkalov/ebooklib) — EPUB 解析
- [FastAPI](https://fastapi.tiangolo.com/) — Web 框架

## License

MIT License — 详见 [LICENSE](LICENSE)