听书功能体验复盘与改进方案

> 📅 2026-10-25 建立 > 起因：车上通勤时想听《截面选品与择时信号的双时钟错配与持仓年龄》（learn/截面选基-理解手册/11-截面选品与择时信号的双时钟错配与持仓年龄.md），结果被四个问题全程打断——断断续续、读到一半没了、写着 15 分钟却几分钟就结束、声音小到听不清，而且不知道该给"车里"选哪个音色。 > 一句话结论：这次不是"今天网不好"的偶发，而是播放架构（逐段同步请求 + 只预取 2 段 + 服务端非流式）和参数设计（语速被应用两次 + 默认气声甜妹混音）共同决定的必然结果。 > 本文所有结论都标了代码位置，区分「代码已确认」与「无法确认（缺埋点）」，不做猜测式归因。

---

一、现场还原：五个卡点

---

二、逐条根因（代码级）

2.1 断断续续：一段一次 HTTP，预取只有 2 段，且服务端不是流式

事实链（全部代码确认）：

• 文档被切成一堆独立段：ttsExtractChunks() 把 h2,h3,h4,h5,p,blockquote,li 每个元素当成一个 chunk，各自发一次请求（unified_server.py:5661-5677）。按同规则静态统计这篇文档：84 段 / 5005 字 / 平均 59.6 字/段。
• 服务端不是流式：上游本身是逐行 JSON + base64 分片的流，但服务端先 resp.read() 把整包读完，再把所有分片 b"".join() 成完整 MP3 一次性返回（tts_service.py:382-425）。所以首字节时间 = 整段合成完成时间，无法边合成边播。
• 单段确实会慢：logs/slow_api/2026-10-25.jsonl 里今天唯一一条 TTS 慢请求是 dur_ms: 5067.0（12:40:16）。慢请求阈值是 5000ms（web_perf.py:72），也就是说 5 秒以内的段根本不会留痕——真实分布比日志里看到的更差。
• 预取是"2 级串行流水"，不是"滑动窗口"：

- 首次播放：并发预取前 3 段（unified_server.py:5823-5829）； - 稳态：第 idx 段下载完成后才开始预取 idx+1（:5878-5881），idx+1 下载完成后才开始预取 idx+2（:5882-5887）； - 也就是说预取要跟着"下载完成"排队，而不是跟着"播放进度"提前跑。一旦某段耗时 5s，后面两段只能干等。

• 音频本身很短：59.6 字 ÷ 4.5 字/秒 ≈ 13 秒（1.0x）。叠上 2.3 节的语速双重生效，实际只剩 6–9 秒。每段可用时间只有几秒，而单次请求可能是 0.3s，也可能是 5s——只要连续两段的合成时间超过音频时长，就出现静音空洞，听起来就是"断断续续"。
• 后台/锁屏会放大问题：TTS 块内没有任何 visibilitychange 保活、也没有 Media Session（全文件 grep 无 mediaSession / wakeLock）。手机锁屏或切到别的 App 后，页面被降频调度，预取更容易掉队；而且锁屏上没有播放控制，只能回浏览器里点。

结论：不是"拉取下一段时网络超时"这么简单，而是预取深度只有 2、且是串行的，加上服务端非流式，让每一段都必须独立扛住一次完整的网络往返 + 合成。

2.2 中途断掉：四条路径静默跳段，错误提示 5 秒后自动消失

播放链路上有四条失败分支，行为完全一致：报错一声、tts_idx++、立刻播下一段，不重试、不暂停。

而 ttsShowError() 的提示 5 秒后自动隐藏（:5721-5727）。

这就是"读着读着就没了"的机制：隧道抖动时如果连续十几段 fetch 同时失败，这十几段会在两三秒内被逐个 tts_idx++ 冲过去，一路冲到第 84 段，触发 ttsStop()——用户感知就是"突然停了"，而且错误条早消失了，看起来像什么都没发生。

还有两个"合法停止"也会被误认为异常：

• 睡眠定时选了 📖 本章：播到文末 ttsStop() 并提示"本章播完，已自动停止"（:5935-5938）；15/30/60 分钟到点也会停（:5774-5779）。
• 拖动语速/音高滑块会立刻 ttsClearAudioCache()，把所有已下载段的 blob URL 全部 revokeObjectURL（:5701-5712、:5715-5719）。正在播的那段如果还没解码进内存，也会失败 → onerror → 跳段。车上手忙脚乱调音量/语速时，这条很容易踩中。

2.3 15 分钟只听了 6 分钟：语速被应用了两次

估算公式（unified_server.py:5958、:5961-5965）：

t += tts_chunks[i].duration || (tts_chunks[i].text.length / 4.5);

完全不看语速。这篇文档按它是 1112 秒 ≈ 18.5 分钟（与用户记忆里的"15 分钟"同一量级，取决于当时正文版本）。

真正的元凶是语速被算了两次：

• 请求时把 speed 转成上游 speech_rate（tts_service.py:459-460）→ 合成出来的音频本身就快了一档；
• 播放时又设 tts_audio.playbackRate = tts_speed（unified_server.py:5904）→ 再快一档。

于是实际耗时 ≈ 估算时长 ÷ 语速²：

用户"才听了几分钟"完全对得上 2.0x 档——显示的还是 1.0x 的时长，所以体感是"写了 15 分钟，几分钟就没了"。再叠加 2.2 节的静默跳段，还会更短。

2.4 声音小听不清：不是音量没开，是音色和响度

• 没有音量 UI，也没有任何 audio.volume 赋值（全文件 grep 无 .volume）。浏览器默认就是 100%，也就是说：加一个音量滑块也救不了，上限已经被系统媒体音量锁死了。
• 默认音色是气声甜妹混音（api_balance_config.json:15-22）：custom_mix_bigtts = 灿灿 zh_female_cancan_mars_bigtts 0.6 + 奶音甜妹 zh_female_sajiaonvyou_moon_bigtts 0.1 + 魅力女友 zh_female_meilinvyou_moon_bigtts 0.3。三个都是偏高、偏气声的女声，中低频薄、齿音靠前。
• 车内噪声主要是低频＋宽频掩蔽，最先被淹没的正是气声和弱辅音。所以"声音特别小"的体感，本质是"可懂度低"，不是音量表上的小。
• 上游请求体只传 format / sample_rate / speech_rate（tts_service.py:352-360），没有任何响度/增益字段，服务端也没做响度归一化（例如 ffmpeg loudnorm）。

2.5 选不出音色：约 100 个音色只有"分类"，没有"场景"

VOICE_PRESETS 约 100 条（tts_service.py:25-...），字段是 id / name / category / desc。category 是"通用""解说""温柔女声"这种描述性标签，不是"什么场景用"。面板里只有：女声/男声/另类三个 tab + 名字搜索（unified_server.py:4998-5005）——没有推荐、没有预设、没有"场景 → 配置"的记忆。

偏好里只存了 speed / pitch / mix（tts_prefs，:5389、:6097-6133），没有"场景"概念，也无法为"车里"和"睡前"各存一套。

> 混音补充：_saturn / _uranus 系音色不支持混音，混了会返回空音频（tts_service.py:415-419，logs/tts_errors.log 里 2026-06-27 那批就是此原因）。做预设时必须避开这三系混音。

---

三、埋点与可观测性现状（回答"能看到是什么原因吗"）

结论先说：今天这次"断断续续 / 中途断"无法精确归因。 现有三个通道都照不到播放链路。

另外两个盲区：

• 服务端 /api/tts 的 TTSError 分支直接返回 500，不写任何日志（unified_server.py:20164-20166）；超时、HTTP 非 200、上游 code 异常同理。
• 前端 ttsShowError() 只弹 toast，不上报（:5721-5727）。所有跳段事件在服务端和日志里都不存在。

所以第 2.1/2.2 节是"机制上的必然"，但这次具体是哪几段超时、跳了几段，数据已经丢了。

埋点最小集（建议 P0 一并做）

有了这五项，才能回答用户原话里的问题："到底哪一段断的、等了多久、为什么跳。"

---

四、改进方案

P0 的落地顺序建议：先做 P0-2（改一行，立刻消除"时间骗人"）→ P0-1（消除双重加速）→ P0-3（把静默失败变成可见）→ 埋点 → P0-4 / P0-5（真正解决断断续续）。前三个改动小、体验收益大，可在一次迭代内完成。

---

五、场景化音色预设（可直接落地）

设计原则：用户只选场景，不选参数。每个预设 = {voice, speed, pitch, volume} 四元组，一键应用，并记住"每个场景上次用的配置"。

落地形态（前端）：

// 预设表：场景 → 参数
var TTS_SCENES = {
  car_male: {label:'🚗 车内·男声', voice:'zh_male_jieshuoxiaoming_moon_bigtts', speed:1.0, pitch:0, volume:1.0},
  car_female:{label:'🚗 车内·女声', voice:'zh_female_shuangkuaisisi_moon_bigtts', speed:1.0, pitch:0, volume:1.0},
  commute:  {label:'🎧 通勤耳机', voice:'zh_male_m191_uranus_bigtts', speed:1.2, pitch:0, volume:1.0},
  bedtime:  {label:'🌙 睡前',     voice:'zh_female_wenrouxiaoya_moon_bigtts', speed:0.9, pitch:0, volume:0.8}
};
// 存储：当前场景 + 每个场景的覆盖值
localStorage['tts_scene'] = 'car_male';
localStorage['tts_scene_overrides'] = JSON.stringify({car_male:{speed:1.1}});

两个细节：

• 预设里的音色都是单音色，天然避开 _saturn/_uranus 混音不支持的问题；若用户手动混音，仍按现有 mix_compatible 限制拦。
• 场景选择要放在播放器主条（不是藏在 ⚙️ 里）——车上单手操作，两步以上就等于没有。

---

六、产品经理的方法论（这件事说明了什么）

用户的原话是：「产品经理要做的事情好像就是这些吧？不同体验产品，提出问题，然后反复去优化，还有什么思维？」以这次听书为例，能抽出 9 条可复用的：

• 先当用户，再当工程师。 办公室里 WiFi + 桌面 Chrome + 耳机，这三个条件同时成立时，2.1/2.2 的问题几乎测不出来。是"车上 + 锁屏 + 车噪 + 单手"这组真实约束把问题逼出来的——新功能的验收场景必须包含"最差使用场景"。
• 把感受翻译成可观测指标。 "断断续续"要变成"段间静音 >0.3s 的占比"；"中途断了"要变成"跳段数 / 会话"；"声音小"要变成"嘈杂环境下的字错率"。翻译不了的感受，就无法优化。
• 先有仪表盘，再改代码。 这次最扎心的不是有 bug，而是bug 发生时没有留下任何证据（第三节）。没有埋点的优化，全凭猜。
• 区分"机制缺陷"和"参数缺陷"。 非流式合成、逐段同步请求是机制缺陷，要改架构；默认音色、语速算两次是参数缺陷，改几行就好。先把参数缺陷摘掉——用户当天就能感知到改善。
• 默认值就是产品。 默认音色决定了 90% 用户的第一印象。把默认值设成"开发者自己觉得好听"，等于把调参成本转嫁给用户。
• 场景化 = 把专家判断固化成默认值。 用户不该被迫成为音色调参师。"车内用什么"应该是一个按钮，而不是 100 个音色里的一次赌博。
• 失败必须可见、可恢复、可归因。 静默降级比报错更糟：用户不知道发生了什么，开发者拿不到任何信息。宁可停下来说"第 37 段失败了，重试？"
• 度量"完成率"而不是"功能上线"。 听书的核心指标不是"有没有播放按钮"，而是听完率、中断率、平均中断位置。这三个数才决定下一版做什么。
• 修"必然发生"的，再修"偶发"的。 语速双算、估算不随语速变化是 100% 必然发生；隧道抖动是偶发。先把必然的修掉，噪声才会显出来。

这次的具体行动线（按顺序）：

• 今天：P0-2 估算跟随语速 + P0-1 关掉双重加速（先让"15 分钟"变真）
• 本周：P0-3 静默跳段改为"重试 + 暂停 + 常驻提示"；补齐第三节五项埋点
• 下次迭代：P0-4 滑动窗口预取 + P0-5 首段流式；P1-1 场景预设
• 之后：P1-2 音量/响度、P1-3 锁屏控制、P1-4 缓存治理

---

七、证据索引（便于复核）