⚠️ 本项目代码由 AI (Claude) 生成

这是 autobcb/read 的第三方 iOS 听书应用，专注于提供优质的语音朗读体验。

ReadApp 是一个专为 iOS 平台设计的轻阅读听书客户端，对接 轻阅读后端 API，提供流畅的在线听书体验。

主要特色：

• 🎧 专注听书功能 - 基于后端 HttpTTS 引擎的高质量语音朗读
• 📱 原生 iOS 体验 - 完整的系统音频集成（后台播放、锁屏控制）
• 🎨 简洁 UI - 清晰的控制界面，专为听书优化
• 🔄 多端同步 - 自动同步阅读进度到轻阅读后端

• 显示书籍列表（封面、书名、作者）
• 搜索书籍（按书名或作者）
• 显示阅读进度和最新章节
• 支持正序/倒序排列
• 最近阅读排序
• 清除远程缓存

• 章节列表浏览（支持倒序）
• 上一章/下一章快速切换
• 自动聚焦当前阅读章节
• 段落缩进优化
• 原文分段保留

• 基于后端 HttpTTS - 高质量在线语音合成
• 章节名朗读 - 自动朗读章节标题，更清晰的章节切换
• 段落级控制 - 精确的段落导航（上一段/下一段）
• 段落进度显示 - 实时显示当前段落位置
• 智能预加载 - 自动预载后续段落，流畅无间断
  • 预载当前章节后续段落
  • 接近章节末尾时自动预载下一章
  • 使用预载数据实现无缝章节切换
• 可视化反馈：
  • 蓝色高亮：当前播放段落
  • 绿色高亮：已预载成功的段落
• 后台持续播放 - 锁屏、切换应用均可播放
• 沉浸式播放界面 - 播放时隐藏多余 UI，专注听书
• 自动章节切换 - 播放完自动跳转下一章
• 记忆播放位置 - 保存最后播放的段落，下次打开自动定位
• 本地缓存 - 智能缓存文本内容，减少重复请求

• ✅ 后台音频播放
• ✅ 后台任务保活（确保长时间播放稳定）
• ✅ 控制中心集成（暂停/播放/切换章节）
• ✅ 锁屏媒体控制（完整支持）
• ✅ 蓝牙设备支持（耳机、车载等）
• ✅ Now Playing 信息显示
• ✅ 音频中断处理（闹钟、来电等中断后自动恢复）
• ✅ 耳机拔出自动暂停

• 账号密码登录
• 选择 TTS 引擎
• 调节语速（5-50）
• 设置书架排序方式
• 配置 TTS 预加载数量
• 导出日志（调试用）
• 清除本地缓存

本应用的设计理念是以听书为核心，所有功能围绕提供最佳的听书体验展开：

1. 段落级精确控制

   • 智能分段算法，保留原文段落结构
   • 支持上一段/下一段快速跳转
   • 实时显示段落进度（如：14/198）

2. 流畅播放机制

   • 多层预加载策略：
     • 预加载当前章节后续段落（可配置数量）
     • 接近章节末尾时自动预载下一章（前3段）
     • 使用预载数据实现无缝章节切换
     • 智能预载重试（失败自动重试最多3次）
   • 绿色高亮提示预载成功
   • 减少播放中断，提升连贯性
   • 章节名自动朗读，更清晰的章节过渡
   • 章节名播放时同步预载内容，避免阻塞

3. 沉浸式界面

   • TTS 播放时自动隐藏阅读控制栏
   • 只显示必要的播放控制（播放/暂停、上下段、退出）
   • 点击屏幕中间可显示/隐藏 UI

4. 智能记忆

   • 记住最后播放的段落位置
   • 重新打开书籍时自动定位到该段落
   • 高亮显示，便于继续播放

工作原理：

1. 用户点击听书按钮
   ↓
2. 朗读章节名（如果从头开始）
   - 同时启动内容预载（避免阻塞）
   ↓
3. 将章节内容按段落分割（保留原文换行）
   - 自动跳过纯标点或空白段落
   ↓
4. 对每个段落：
   - 构建 TTS API URL
   - 请求音频流 (MP3)
   - 使用 AVAudioPlayer 播放
   - 如失败：自动跳到下一段（错误恢复）
   ↓
5. 智能预加载：
   - 预载当前章节后续段落（可配置数量）
   - 接近章节末尾时预载下一章（前3段）
   - 失败自动重试（最多3次，延迟2秒）
   - 跳过纯标点段落
   ↓
6. 播放完成后自动播放下一段
   ↓
7. 当前章节播放完后：
   - 朗读下一章章节名
   - 使用预载数据无缝切换

优势：

• ✅ 支持多种高质量 TTS 引擎
• ✅ 语音自然流畅
• ✅ 可灵活配置语速
• ✅ 服务器端统一管理引擎

API 端点：

• GET /api/5/getalltts - 获取 TTS 引擎列表
• GET /api/5/tts?id=xxx&text=段落内容&speakSpeed=10 - 获取音频流

1. 音频会话配置

   AVAudioSession.setCategory(.playback, options: [])
   AVAudioSession.setActive(true)

2. 后台模式

   • Info.plist 配置 UIBackgroundModes 包含 audio
   • 激进的后台保留策略

3. 远程控制

   • 支持锁屏界面和控制中心的播放/暂停
   • 显示书名、章节名等 Now Playing 信息

4. 音频中断处理

   • 监听 AVAudioSession.interruptionNotification
   • 闹钟、来电等中断时自动暂停
   • 中断结束后根据系统建议自动恢复
   • 监听 AVAudioSession.routeChangeNotification
   • 耳机拔出时自动暂停播放

5. 数据持久化

   • 使用 UserDefaults 保存 TTS 进度
   • 记录最后播放的段落索引

• iOS: 15.0 或更高版本
• Xcode: 15.0 或更高版本
• Swift: 5.0
• 网络: 稳定的网络连接（听书功能必需）

1. 部署轻阅读后端

   • 参考 autobcb/read 的部署教程
   • 确保后端已配置 TTS 引擎

2. 配置 TTS 引擎

   • 在后端管理界面添加至少一个 TTS 引擎
   • 建议使用高质量的在线 TTS 服务

1. 下载或构建 IPA

   cd ReadApp
   ./build_unsigned_ipa.sh

2. 使用签名工具安装

   • 使用 轻松签、爱思助手 等工具
   • 或在 Xcode 中使用开发者证书签名

1. 打开项目

   open ReadApp.xcodeproj

2. 选择目标设备

   • 真机（推荐，后台播放测试需要）
   • 或模拟器

3. 运行

   • 点击 ⌘R 或运行按钮

1. 登录

   • 输入后端服务器地址（如：http://192.168.1.100:8080）
   • 输入账号和密码
   • 点击"登录"

2. 配置 TTS

   • 进入"设置"页面
   • 点击"TTS 引擎"
   • 选择一个可用的引擎
   • 调整语速（建议 10-20）
   • 配置预加载数量（建议 3-5）

3. 开始听书

   • 返回书架
   • 点击任意书籍
   • 点击底部"听书"按钮
   • 享受听书体验！

1. 启动听书

   • 在阅读页面点击底部的"听书"按钮（喇叭图标）
   • 应用自动切换到 TTS 模式

2. TTS 控制界面

   • 顶部: 段落导航（上一段 | 进度 | 下一段）
   • 中部: 内容显示区（蓝色高亮=播放中，绿色高亮=已预载）
   • 底部: 播放控制（上一章 | 目录 | 播放/暂停 | 退出 | 下一章）

3. 段落控制

   • 点击"上一段"返回上一个段落
   • 点击"下一段"跳到下一个段落
   • 段落进度实时更新（如：14/198）

4. 沉浸模式

   • 播放时自动隐藏其他 UI
   • 点击屏幕中间可显示/隐藏控制栏
   • 专注听书，减少干扰

5. 后台播放

   • 锁屏或切换应用，播放继续
   • 在锁屏界面控制播放
   • 使用蓝牙耳机远程控制

6. 退出 TTS

   • 点击"退出"按钮
   • 自动保存播放位置
   • 下次打开自动定位到该位置

1. 阅读控制

   • 上一章 - 切换到上一章
   • 目录 - 查看章节列表
   • 听书 - 启动 TTS 模式
   • 字体 - 调整字体大小（TODO）
   • 下一章 - 切换到下一章

2. 章节列表

   • 显示所有章节
   • 当前章节高亮显示
   • 支持倒序查看
   • 点击章节快速跳转

3. 自动定位

   • 打开书籍时自动定位到上次 TTS 位置
   • 黄色高亮标记该段落

1. 搜索书籍

   • 使用顶部搜索框
   • 支持按书名或作者搜索

2. 排序选项

   • 正序/倒序 - 切换列表顺序
   • 最近阅读 - 在设置中开启，按阅读时间排序

3. 清除缓存

   • 长按书籍
   • 选择"清除所有远程缓存"
   • 清除服务器上的缓存数据

ReadApp/
├── ReadAppApp.swift              # 应用入口
├── ContentView.swift             # 主视图
├── Info.plist                    # 应用配置（含后台音频）
├── Models/
│   └── Models.swift              # 数据模型
├── Services/
│   ├── APIService.swift          # API 服务（含本地缓存）
│   ├── TTSManager.swift          # TTS 管理器（AVAudioPlayer）
│   └── LogManager.swift          # 日志管理器
├── Views/
│   ├── BookListView.swift        # 书架视图
│   ├── ReadingView.swift         # 阅读视图（含 TTS 控制）
│   ├── SettingsView.swift        # 设置视图
│   ├── TTSSelectionView.swift    # TTS 引擎选择
│   ├── LoginView.swift           # 登录视图
│   └── HTMLContentView.swift     # HTML 内容渲染（已废弃）
└── Assets.xcassets/              # 资源文件

• POST /api/5/login - 用户登录
• GET /api/5/userInfo - 获取用户信息
• GET /api/5/getBookshelf - 获取书架
• GET /api/5/getChapterList - 获取章节列表
• GET /api/5/getBookContent - 获取章节内容
• POST /api/5/saveBookProcess - 保存阅读进度

• GET /api/5/getalltts - 获取 TTS 引擎列表
• GET /api/5/tts?id=xxx&text=段落&speakSpeed=10 - 获取音频流

• GET /api/5/cleancaches - 清除所有远程缓存

private func splitIntoParagraphs(_ text: String) -> [String] {
    // 按换行符分割，保持原文分段
    let paragraphs = text.components(separatedBy: "\n")
        .map { $0.trimmingCharacters(in: .whitespaces) }
        .filter { !$0.isEmpty }
    
    return paragraphs
}

// 预加载后续段落
for i in 1...preloadCount {
    let nextIndex = currentIndex + i
    if nextIndex < totalSentences {
        preloadSentence(at: nextIndex)
    }
}

// 标记预载成功
preloadedIndices.insert(nextIndex)

// 当前播放：蓝色高亮
if index == ttsManager.currentSentenceIndex {
    Color.blue.opacity(0.2)
}
// 已预载：绿色高亮
else if ttsManager.preloadedIndices.contains(index) 
    && index > ttsManager.currentSentenceIndex {
    Color.green.opacity(0.15)
}
// 普通段落
else {
    Color.clear
}

• ❌ 听书需要持续的网络连接
• ❌ 每次朗读都需从服务器获取音频
• ❌ 音频质量取决于后端 TTS 引擎
• ❌ 不支持离线播放

• 音频文件缓存（减少流量消耗）
• 更多预加载策略优化
• 支持调整字体大小
• 夜间模式
• 阅读统计
• 书签和笔记

可能原因：

1. 未选择 TTS 引擎
2. 网络连接问题
3. 后端 TTS 引擎配置错误
4. 段落内容包含特殊字符

解决方案：

1. 进入设置 → 选择 TTS 引擎
2. 检查网络连接状态
3. 查看 Xcode 控制台日志
4. 导出日志并检查错误信息

可能原因：

1. 在模拟器上测试（模拟器后台限制）
2. 网络中断

解决方案：

1. 使用真机测试
2. 确保网络连接稳定
3. 检查系统音频权限

可能原因：

1. 预加载数量设置为 0
2. 网络速度过慢
3. 后端响应延迟

解决方案：

1. 在设置中增加预加载数量（建议 3-5）
2. 检查网络速度
3. 查看日志中的预加载错误

• ✅ 基础书架和阅读功能
• ✅ 账号密码登录
• ✅ HttpTTS 集成
• ✅ 后台音频播放
• ✅ 锁屏控制
• ✅ 搜索和排序
• ✅ 段落级 TTS 控制
• ✅ 预加载机制
• ✅ 可视化高亮
• ✅ 沉浸式播放界面
• ✅ 播放位置记忆
• ✅ 本地文本缓存
• ✅ UI 控件优化
• ✅ 原文分段保留
• ✅ 后台保活优化
• ✅ 预载智能重试
• ✅ 自动跳过纯标点
• ✅ 增强错误恢复
• ✅ 音频中断自动恢复
• ✅ 耳机拔出检测

• 后台保活增强: 添加后台任务管理，确保长时间播放稳定
• 智能预载重试: 预载失败自动重试最多3次，提升成功率
• 章节名并行预载: 章节名播放时同步预载内容，避免阻塞

• 跳过纯标点: 自动跳过纯标点或空白段落，避免无效朗读
• 增强错误恢复: 音频播放失败自动跳到下一段，确保连续性
• 系统控制修复: 修复锁屏/控制中心播放恢复问题

• 预载重试详细日志
• 后台任务状态日志
• 更清晰的错误分类

• 自动暂停: 闹钟、来电等中断时自动暂停播放
• 智能恢复: 中断结束后根据系统建议自动恢复播放
• 耳机检测: 耳机拔出时自动暂停，避免外放
• 音频会话管理: 中断恢复时重新激活音频会话

本项目代码由 AI (Claude) 生成，仅供学习和个人使用。

如有问题或建议，欢迎提交 Issue。

• 后端项目: autobcb/read
• 后端部署教程: https://space.bilibili.com/517034064

1. 本项目为第三方客户端，与 autobcb/read 官方无关
2. 本项目仅供学习交流使用
3. 使用本应用产生的任何问题，由使用者自行承担
4. 请遵守相关法律法规和版权规定

MIT License

Copyright (c) 2025 ReadApp

本项目采用 MIT 许可证。详见 LICENSE 文件。

Powered by AI (Claude) | Made with ❤️ for 轻阅读社区