文档听书 TTS 功能 — 技术实现详解

概述

为文档浏览模块增加了"听书"能力：点击按钮即可用豆包语音合成朗读 Markdown 文档内容，支持三音色混音、语速/音高调节、断点续听、进度条拖拽。后端对接火山引擎豆包语音大模型 V3 HTTP API，前端使用 HTML5 Audio API 播放。

核心架构

浏览器（前端）                               Python HTTP Server（后端）                   火山引擎 TTS API
-----------                               ------------------------                   -----------------
DOC_PAGE 模板                              unified_server.py                         openspeech.bytedance.com
├─ JS: ttsExtractChunks() 提取文本片段       ├─ GET /api/tts/voices ──► JSON 声音列表     /api/v3/tts/unidirectional
├─ JS: ttsBuildUrl() 构造请求              ├─ GET /api/tts?text=...──► MP3 音频流      ├─ x-api-key 鉴权
├─ JS: ttsPlayChunk() 播放+预加载下一段       │   └─ TTSService.synthesize()           ├─ custom_mix_bigtts 混音
├─ JS: ttsSaveProgress() → localStorage    │       ├─ SQLite 缓存查询/写入              ├─ speech_rate [-50, 100]
├─ CSS: 底部固定悬浮播放器                      │       ├─ _call_api() → HTTP POST        └─ post_process.pitch [-12,12]
└─ HTML: 设置面板（模式/声音/语速/音高/混音比例）      │       └─ 流式 JSON Lines → base64 解码
                                           └─ tts_cache.db（SQLite WAL）

关键技术点

1. 火山引擎豆包语音 V3 HTTP API

• 端点: https://openspeech.bytedance.com/api/v3/tts/unidirectional
• 资源 ID: seed-tts-1.0（豆包语音大模型）
• 鉴权: 新版控制台使用 x-api-key header（非旧版 Bearer;token）
• 配置位置: api_balance_config.json → volcengine.tts.api_key
• 参考文档: https://www.volcengine.com/docs/6561/1361252

请求结构

{
  "user": {"uid": "aohan_quant"},
  "req_params": {
    "text": "要合成的文本",
    "speaker": "custom_mix_bigtts",
    "audio_params": {
      "format": "mp3",
      "sample_rate": 24000,
      "speech_rate": -30
    },
    "mix_speaker": {
      "speakers": [
        {"source_speaker": "zh_female_cancan_mars_bigtts", "mix_factor": 0.6},
        {"source_speaker": "zh_female_sajiaonvyou_moon_bigtts", "mix_factor": 0.1},
        {"source_speaker": "zh_female_meilinvyou_moon_bigtts", "mix_factor": 0.3}
      ]
    },
    "additions": "{\"post_process\":{\"pitch\":7}}"
  }
}

响应解析

API 返回流式 JSON Lines，每行一个 JSON 对象：

• code: 0 + data 字段 → base64 编码的 MP3 音频块
• code: 20000000 → 合成完成标记
• 其他 code → 错误信息

将所有 code=0 的 data 解码后拼接即得完整 MP3。

2. 多音色混音

使用 custom_mix_bigtts speaker + mix_speaker.speakers[] 实现最多 3 种音色同时混合：

> 注意：如果用户在豆包 App 中使用了"声音复刻"功能创建了专属声音，其 voice_id 为 S_xxx 或 ICL_xxx 格式，可在火山引擎控制台 → 音色库 → 我的音色中获取，然后替换 default_mix 中的 source_speaker。

3. 参数映射（用户配置 → API 参数）

用户截图中的配置到 API 参数的映射关系：

speed 范围 [0.5, 2.0]，对应 speech_rate [-50, 100]。speech_rate=0 表示正常语速。

4. SQLite 本地音频缓存

为避免重复合成相同内容，通过 SQLite 本地缓存合成结果：

• 数据库: adata/aohan/quant/db/tts_cache.db
• 表结构: tts_cache(cache_key TEXT PK, audio_blob BLOB, text_length INT, voice_sig TEXT, created_at TIMESTAMP)
• 缓存键: SHA256(text | voice_signature) — 换声音/语速/音高都会产生不同缓存
• 写入策略: INSERT OR REPLACE 保证幂等

5. 前端文本清洗与分段

文本提取规则（ttsExtractChunks）

从 Markdown 渲染后的 HTML DOM 中提取纯文本，跳过以下内容：

• <pre><code> 代码块
• .mermaid 图表
• <table> 表格
• <img> 图片
• URL 链接（提取链接文本部分）
• Frontmatter（YAML --- 块）

分段策略（TTSService.split_text）

• 按句号、问号、感叹号等句子边界切分
• 每段不超过 900 字节（UTF-8）
• 短尾段（<200 字节）合并到上一段
• TTS API 单次请求上限对应 900 字节

6. 前端播放引擎

核心状态

tts_chunks = [];     // 文本片段数组
tts_idx = 0;         // 当前播放片段索引
tts_audio = null;    // HTML5 Audio 对象
tts_playing = false; // 播放状态

播放流程

• ttsPlay() → 重置索引，调用 ttsPlayChunk(0)
• ttsPlayChunk(i) → 用 ttsBuildUrl(chunks[i]) 构造请求 URL → fetch() 获取 MP3 → URL.createObjectURL() → new Audio(blobUrl) → audio.play()
• 同一时刻预加载下一段（tts_idx + 1），消除段落间停顿
• audio.onended → tts_idx++ → 如果还有下一段，ttsPlayChunk(tts_idx)
• 进度条 tts_audio.ontimeupdate → 当前段内偏移 + 已播完段落估算时长 → 更新 UI

断点续听

• localStorage key: tts_v2:{pathname}
• 保存: {idx, time, total}
• 加载: 页面初始化时检测，显示"续听"按钮
• 续听: ttsJump(saved.idx, saved.time) 跳转到保存的段落和时间

7. 前端 UI 组件

播放器栏（底部固定悬浮）

┌──────────────────────────────────────────────────────────┐
│ 项目架构文档                                        ⚙️ □  │
│ [▶] ────●──────────── 02:00 / 05:30                     │
└──────────────────────────────────────────────────────────┘

设置面板（点击 ⚙️ 展开）

• 模式选择: 混音模式 / 单音色模式
• 声音选择: 10 个预置音色下拉框
• 混音滑块（混音模式）: 3 个通道的音量比例滑块，自动归一化
• 语速滑块: 0.5x ~ 2.0x
• 音高滑块: -12 ~ +12 半音

浏览器兼容性

• HTML5 Audio API（所有现代浏览器支持）
• Blob URL 播放 MP3
• audio.ontimeupdate 进度更新
• 移动端响应式适配（@media max-width: 600px）

8. 后端路由

核心文件

安全性

• api_balance_config.json 已加入 .gitignore，API Key 不会提交到仓库
• 服务端代理模式：前端不暴露 API Key，所有 TTS 请求走后端中转
• 音频缓存 key 为 SHA256 hash，不含原文可还原信息