# 听阅 HearBooks

听阅是一个供个人使用的中英文听书网站。上传无 DRM 的 EPUB 或 PDF 后，网站会在浏览器中提取正文；扫描版 PDF 可在 Windows Edge 中进行中英文 OCR。校对完成后，播放器会按句生成 Edge 在线语音、同步音频和最后播放位置，并在在线语音不可用时退回浏览器自带朗读。

## 第一版包含

- 手机与电脑自适应书架、搜索、封面与书籍设置
- EPUB、文字版 PDF 与不超过 200 MB 的扫描版 PDF
- 8 MiB 分片断点续传，过期分片自动回收
- Windows Edge 中的 `chi_sim + eng` OCR，支持暂停、刷新后续做
- 章节自动识别、重命名、拆分、合并和逐句人工修改
- 自动跳过复杂公式、表格、页眉页脚和低置信度内容
- 自动识别中英文并切换语音；当前章按需生成、预生成下一章
- 原文逐句高亮、±15 秒、0.5–3 倍速、音量、章节切换
- 15/30/45/60 分钟与“本章结束”睡眠定时
- Media Session 锁屏控制，以及 Edge 在线语音失败后的系统朗读回退
- D1 同步书籍、正文和最后播放位置；R2 同步源文件、封面与生成音频
- 只保留最近收听的 5 本书音频，并设 8 GB 应用软上限

第一版不包含登录、权限保护、离线收听、多书签、批注、全文搜索或 DRM 绕过。

## 使用时请先知道

部署后的网址是公开的：知道网址的人都能查看、上传、修改和删除内容。不要上传不愿公开的数据，也不要上传受 DRM 保护或无权处理的电子书。

Edge 在线语音使用 Microsoft Edge 的非官方 Read Aloud 接口，不需要 API 密钥，但它不是带可用性保证的正式免费 API，未来可能限流、变更或失效。此时播放器会自动尝试浏览器的 `speechSynthesis` 朗读；系统朗读不能生成跨设备同步的 MP3，锁屏表现也取决于设备。

OCR、PDF 解析和 TTS 生成都在浏览器端进行。扫描书建议在 Windows Edge 中完成 OCR 后，再用 Android Edge 收听。

## 本地开发

需要 Node.js 22.13 或更高版本。

```bash
npm install
npm run db:local
npm run dev
```

常用检查：

```bash
npm run typecheck
npm run lint
npm test
npm run test:e2e
```

`npm run test:e2e` 使用本机 Microsoft Edge，重复验证 EPUB 导入、章节校对/拆分/合并、播放器控件和 Android 尺寸响应式布局；默认启动或复用 `http://127.0.0.1:3000` 的开发服务器。

`npm run build` 会先生成 `public/source.zip`，再构建 Cloudflare Worker。这个压缩包是公网交互用户可下载的对应源码，不含 `node_modules`、构建目录、环境变量或其他临时文件。

## 数据与迁移

- 结构化数据定义在 `db/schema.ts`。
- Cloudflare D1 迁移位于 `drizzle/`。
- `.openai/hosting.json` 只声明逻辑绑定 `DB` 与 `STORAGE`；真实资源由 Sites 发布流程创建和连接。
- `wrangler.local.jsonc` 只用于把迁移应用到本机模拟数据库，不参与 Sites 正式部署。
- 删除一本书会同时删除它的正文、进度、封面、源文件和已生成音频。

## 备份与恢复

第一版没有“一键备份/恢复”功能。请始终保留 EPUB/PDF 原文件；网站底部的 `source.zip` 只备份应用源码，不包含书架数据。若远端数据丢失，可重新部署源码并重新上传原书，但校对结果和最后播放位置不会自动恢复。发布、迁移、容量处理、恢复步骤与已知限制详见 `docs/operations.md`。

## 更换语音提供者

浏览器在线语音封装在 `lib/client/tts/edge-browser.ts`，播放器只依赖“输入正文、声音、速度，返回 MPEG 音频 Blob”的接口。替换时保留该接口以及 `EdgeTtsUnavailableError` 的回退语义，再运行 `tests/tts/` 与完整测试即可；书库、片段版本、R2 缓存和播放器无需重写。具体检查点见 `docs/operations.md`。

## 借鉴与第三方组件

项目流程参考了 [epub_to_audiobook](https://github.com/p0n1/epub_to_audiobook)、[ebook2audiobook](https://github.com/DrewThomasson/ebook2audiobook) 与 [Readest](https://github.com/readest/readest) 的公开实现思路；具体代码为本项目实现。PDF 提取使用 PDF.js，OCR 使用 Tesseract.js，在线语音使用 `edge-tts-universal`。完整说明见 `THIRD_PARTY_NOTICES.md`。

## 许可证与源码

HearBooks 按 GNU Affero General Public License v3.0-only 发布，详见 `LICENSE`。部署后的每个页面底部都提供与当前版本对应的源码下载入口。
