@memef1f1y/dsh-plugin-tts 0.6.5 → 0.6.7

package/docs/adaptive-chunked-playback.md

@@ -1,194 +1,194 @@
-# 自适应分块渐进播放方案（Adaptive Chunked Progressive Playback）
-
-> RVC 长文本朗读的"先全部转换、后整体播放"改造成"边转换、边播放"的设计与实现说明。
-> 核心思想：**性能开销摊在用户本机**，不同机器自动校准块大小与预热数量，做到"即点即听、长文不卡顿"。
-
-## 1. 问题
-
-RVC 是**变声**而非 TTS：输入音频长度 = 输出音频长度，所以"长文本朗读"必须
-先把整段文本用 Edge TTS 合成底噪，再交给 RVC 转换。旧链路是：
-
-```
-整段文本 → Edge 合成整段底噪 → RVC 整段转换 → 返回 → 播放
-```
-
-对短句（≤12 秒音频）这是最优解；但对长回复（数百字、几分钟音频）会变成：
-
-- 用户点击后**干等**：合成 + 转换整段（几十秒甚至几分钟）完成才出声；
-- 期间没有任何反馈，体验像"卡死"；
-- 内存峰值高（整段音频一次性进出 RVC）。
-
-曾考虑"只读前 20 字"来缩短等待 —— 但这会**丢掉正文内容**，被否决。
-正确方向是：内容一字不丢，但**让第一块尽快出声，其余在播放的同时后台合成**。
-
-## 2. 方案总览
-
-```
-Edge 合成整段底噪? 不 —— 改成：
-1) 文本按句切块（每块 ≈ 10-20 秒音频）
-2) 先转换预热块（2-4 块）→ 立即返回给前端开始播放
-3) 播放第 n 块的同时，后台转换第 n+1、n+2 块（转换/播放重叠）
-4) 前端队列快见底时向 Host 拉取下一块，无缝续播
-```
-
-关键比率：**速度比 ratio = 转换耗时 / 音频时长**。
-
-- GPU（RTX 5070 实测）：15 秒音频 ≈ 3-4 秒转换 → ratio ≈ 0.25
-  → 转换永远追得上播放，队列不会饿死，**天然无缝**。
-- CPU 用户：ratio 可能 > 1 → 必须缩小块、加大预热，把"卡顿点"压到最少。
-
-## 3. 自适应校准（probe + 分档）
-
-首次使用长文本 RVC 时，Host 做一次 **5 秒探测**：
-
-1. Edge 合成一段固定探测文本（≈3.6 秒音频）；
-2. 本机 RVC 转换，测出 `ratio = 转换耗时 / 音频秒数`（含每块 Edge 合成耗时，
-   与真实分块流水线口径一致，偏保守）；
-3. 按分档表决定 `chunkSec`（每块音频秒数）与 `prewarm`（先转换几块再开播）；
-4. 结果按配置指纹持久化到 `~/.dsh/tts-rvc/calibration.json`：
-   - **7 天有效**，dsh 重启后直接复用，连那一次 ~7s 探测都省掉；
-   - 同时记录 `device`（RVC 服务 `/health` 上报的 GPU 名）；换显卡/切 CPU 时
-     自动重新探测，不会拿旧的 GPU 数据给 CPU 用；
-   - 探测失败不覆盖磁盘上的旧有效条目（会话内 2 分钟用保守档兜底）。
-
-| ratio | 块大小 | 预热块数 | 适用 |
-|---|---|---|---|
-| ≤ 0.4 | 20 秒 | 2 | 强 GPU，几乎无缝 |
-| 0.4 – 0.6 | 15 秒 | 2 | 中端 GPU |
-| 0.6 – 0.9 | 10 秒 | 3 | 入门 GPU / 快 CPU |
-| > 0.9 | 6 秒 | 4 | CPU，尽量平滑 |
-| 探测失败 | 10 秒 | 3 | 保守兜底（60 秒内不重复探测） |
-
-块大小换算：中文 ≈ 3.6 字/秒 → `maxChars ≈ chunkSec × 3.6`（拉丁文本按 12 字/秒）。
-
-### 为什么分档而不是固定值？
-
-同一套代码要在"4090 用户"和"核显用户"上都成立。固定大块在 CPU 上会频繁断流，
-固定小块在 GPU 上是浪费。**按本机实测速度自适应**才是"即选即用"的根基。
-
-## 4. 文本切块
-
-`splitText(text, maxChars)`：
-
-1. 按句号/感叹/问号/分号（含中英文）切句；
-2. 超长句再按逗号/顿号切段；
-3. 仍超长的硬切（每段 ≤ maxChars）；
-4. 尽量让每块落在语义边界，避免在句中切断导致听感断裂。
-5. **原子 token 保护**：URL / 邮箱 / 小数 / 版本号（如 `3.14`、`v2.0.1`）先换成无标点
-   placeholder 再切分——句子级切分不会把小数里的 `.` 误当句号拆开；硬切（`safeEnd`）会
-   滑到最近空白/标点边界，且绝不切断 placeholder（长 URL 保持整段读出）。
-6. **孤儿块合并**：末尾不足 8 字的极短句并入前一块（合并后 ≤ maxChars），避免"结巴"听感。
-
-## 5. 协议：任务队列（Host 侧）
-
-`POST /dsh-tts-api/speak`（RVC + Edge 底噪 + 预估 > 12 秒时）：
-
-```jsonc
-// 请求不变；响应变为：
-{ "jobId": "j1", "chunks": ["/dsh-tts-audio/c1", "/dsh-tts-audio/c2"], "total": 6,
-  "ratio": 0.24, "chunkSec": 20 }
-// chunks 只含"预热块"；总块数在 total
-```
-
-`GET /dsh-tts-api/rvc-next?job=j1`（前端逐块拉取）：
-
-```jsonc
-{ "url": "/dsh-tts-audio/c3", "more": true }   // 还有后续
-{ "done": true }                               // 已到末尾
-{ "error": "后续段落合成失败：..." }            // 某块失败
-```
-
-Host 内部：
-
-- 每 job 一个**串行转换链**（`job.tail`），并发拉取自动排队，RVC 服务不被并发打爆；
-- 每块 = Edge 合成该块文本 → RVC 转换 → 临时 wav → 音频路由 URL；
-- job 惰性回收：完成 2 分钟后 / 创建 10 分钟后清理，上限 50 个；
-- 单块失败不影响已缓冲的块，只把错误带给前端，前端提示后停止。
-
-## 6. 前端渐进播放（无感衔接）
-
-`playChunks(jobId, chunks, total, token)` 使用 **Web Audio 精确调度**：
-
-- 每个块 `fetch → decodeAudioData` 成 AudioBuffer（保持 2 块解码余量），
-  按采样时钟**首尾相接调度**：`src.start(prevEnd)`（prevEnd 由已调度缓冲时长累加），
-  块间零事件抖动、零重载延迟；
-- **服务端裁剪每块边缘填充静音**（rvc-server `/convert` 输出前 `trim_edges`）：
-  实测每块头 138ms / 尾 538ms 纯静音（Edge TTS + RVC 填充），裁掉并各保留
-  20ms / 120ms 自然气息，块间不再有 ~680ms 死寂；
-- 停止/打断：`speakToken` 全局令牌 + 源列表 `stop()`（waCleanup），立即静音；
-- **进度可见**：`shared.chunkProgress = { index, total }` 随块播放更新——朗读按钮
-  tooltip 与试听面板显示「第 x/y 段 · 边播边合成」（绝不静默丢内容）；
-- 失败：某块合成失败 → 红字提示并停止；无 Web Audio 环境降级为双 `<audio>` ping-pong。
-
-> 备注：`vc_single` 返回 **int16**，`trim_edges` 先归一化为 float [-1,1] 再处理，
-> 否则 `sf.write` 会把 int16 样本值当 [-1,1] 幅值整体削波（曾导致输出 99% 满幅失真）。
-
-## 7. RVC 服务端配套
-
-`rvc-server.py` 本次新增：
-
-1. **`/health` 上报 `gpu_name` / `vram_gb`** —— 校准持久化的设备指纹来源；
-2. **faiss 索引缓存**：RVC pipeline 每次转换都会 `faiss.read_index` 重新读一遍
-   ~400MB 索引文件（每块一次，代价可观）。现在按路径缓存加载好的 Index 对象，
-   `/load` 时清空 —— 分块模式下每块省掉一次 400MB 磁盘读。
-
-## 8. 边界与回退
-
-| 情况 | 行为 |
-|---|---|
-| 短文本（≤12 秒） | 不进队列，走原来的单 URL 链路（零额外开销） |
-| 探测失败 | 保守档（10 秒 / 预热 3），会话内 2 分钟不重复探测 |
-| 某块转换失败 | 已缓冲的继续播，后续报错并停止 |
-| 停止 / 换消息 / 切会话 | 令牌失效，队列立即退出，无残留播放 |
-| 刷新页面 | 队列随页面消失；Host job 按时回收 |
-
-## 10. 实测（RTX 5070 + azusa-test）
-
-| 场景 | 结果 |
-|---|---|
-| 短句链路 | ~4.6-5.4s（含 Edge 合成） |
-| 长文本首响 | 探测 + 预热 2 块 ≈ 6-7s（**此后 7 天内从 calibration.json 直接复用，不再探测**） |
-| 长文本全链 | 6/6 块取完，迟到块 RIFF 476KB；块间无感知停顿 |
-| 索引缓存收益 | ratio 0.62 → 0.48（省掉每块 400MB 索引重读），档位 10s/3 → 15s/2 |
-
-## 11. Phase 2 预留
-
-- 音色包注册表 + 下载 UI（版权干净音色）→ 已包含在下方"已完成"（含私有仓库 rvc-for-tts 示例）；
-- 便携运行时打包 → **已完成（v1）**：`tools/package-runtime.py` 复制已验证环境 + 可选
-  torch cu128 升级（RTX 50 系提速，官方 CDN 慢时用国内镜像）；本机实测转换正常。
-
-> 已完成：
-> - `calibration.json` 落盘（`~/.dsh/tts-rvc/`，7 天有效 + 设备指纹，跨会话复用探测结果）；
-> - **紧凑索引生成工具**（设置面板「索引路径」旁「压缩」按钮）：408MB 原索引
->   子采样重建为**与源同度量**的精确 flat 索引（RVC 训练默认 L2，pipeline 的
->   `square(1/score)` 加权即按 L2 设计），2k→5.9MB（-98.5%）、10k→29.3MB（-92.5%），
->   RVC 管线零改动兼容，实测转换正常；音色包分发不再受索引体积阻碍；
-> - **音色包注册表 + 下载 UI**：清单格式（schema 2：模型 + indexes 变体数组 + sha256 +
->   版权/作者/版本，url 支持相对路径），Host 代理清单与下载（规避 CORS）、sha256 逐一校验后
->   安装到 `~/.dsh/tts-rvc/packs/<id>/`，自动填入模型/索引并应用底噪/f0/index_rate 默认值；
->   失败自动清理残留；mock 仓库 `tests/mock-registry.mjs` 供本地测试；私有音色仓库
->   `github.com/1624318455/rvc-for-tts`（azusa-test 模型 + 2k/10k/20k 紧凑索引）；
-> - **便携运行时打包 v1**：`tools/package-runtime.py`（--skip-torch 零下载即可用；
->   可选 cu128 升级适配 Blackwell，官方 CDN 慢时用 aliyun 镜像）。
-
----
-
-## English summary
-
-RVC is voice **conversion** (input length == output length), not TTS, so a long
-read must first synthesize the whole base audio with Edge TTS. Instead of
-converting everything before playing (long silent wait), the plugin now:
-
-1. **Probes** the local machine once (convert a ~3.6s clip, measure
-   `ratio = convert_time / audio_seconds`); results persist to
-   `~/.dsh/tts-rvc/calibration.json` (7-day validity, GPU-name fingerprint,
-   re-probes on device change), so the probe is paid only once per config;
-2. Picks **chunk size (6–20s) and prewarm count (2–4)** from a ratio tier table;
-3. Splits the text into sentence-aligned chunks, converts the prewarm chunks,
-   and returns a **job queue** immediately;
-4. The client **plays while prefetching**: each next chunk is converted during
-   the current chunk's playback (`GET /rvc-next`), so long reads stream
-   seamlessly on GPU and degrade gracefully on CPU (smaller chunks, more
-   prewarm);
-5. The RVC server reports GPU name/VRAM in `/health` and **caches the faiss
-   index** so each chunk no longer re-reads the ~400MB index file.
+# 自适应分块渐进播放方案（Adaptive Chunked Progressive Playback）
+
+> RVC 长文本朗读的"先全部转换、后整体播放"改造成"边转换、边播放"的设计与实现说明。
+> 核心思想：**性能开销摊在用户本机**，不同机器自动校准块大小与预热数量，做到"即点即听、长文不卡顿"。
+
+## 1. 问题
+
+RVC 是**变声**而非 TTS：输入音频长度 = 输出音频长度，所以"长文本朗读"必须
+先把整段文本用 Edge TTS 合成底噪，再交给 RVC 转换。旧链路是：
+
+```
+整段文本 → Edge 合成整段底噪 → RVC 整段转换 → 返回 → 播放
+```
+
+对短句（≤12 秒音频）这是最优解；但对长回复（数百字、几分钟音频）会变成：
+
+- 用户点击后**干等**：合成 + 转换整段（几十秒甚至几分钟）完成才出声；
+- 期间没有任何反馈，体验像"卡死"；
+- 内存峰值高（整段音频一次性进出 RVC）。
+
+曾考虑"只读前 20 字"来缩短等待 —— 但这会**丢掉正文内容**，被否决。
+正确方向是：内容一字不丢，但**让第一块尽快出声，其余在播放的同时后台合成**。
+
+## 2. 方案总览
+
+```
+Edge 合成整段底噪? 不 —— 改成：
+1) 文本按句切块（每块 ≈ 10-20 秒音频）
+2) 先转换预热块（2-4 块）→ 立即返回给前端开始播放
+3) 播放第 n 块的同时，后台转换第 n+1、n+2 块（转换/播放重叠）
+4) 前端队列快见底时向 Host 拉取下一块，无缝续播
+```
+
+关键比率：**速度比 ratio = 转换耗时 / 音频时长**。
+
+- GPU（RTX 5070 实测）：15 秒音频 ≈ 3-4 秒转换 → ratio ≈ 0.25
+  → 转换永远追得上播放，队列不会饿死，**天然无缝**。
+- CPU 用户：ratio 可能 > 1 → 必须缩小块、加大预热，把"卡顿点"压到最少。
+
+## 3. 自适应校准（probe + 分档）
+
+首次使用长文本 RVC 时，Host 做一次 **5 秒探测**：
+
+1. Edge 合成一段固定探测文本（≈3.6 秒音频）；
+2. 本机 RVC 转换，测出 `ratio = 转换耗时 / 音频秒数`（含每块 Edge 合成耗时，
+   与真实分块流水线口径一致，偏保守）；
+3. 按分档表决定 `chunkSec`（每块音频秒数）与 `prewarm`（先转换几块再开播）；
+4. 结果按配置指纹持久化到 `~/.dsh/tts-rvc/calibration.json`：
+   - **7 天有效**，dsh 重启后直接复用，连那一次 ~7s 探测都省掉；
+   - 同时记录 `device`（RVC 服务 `/health` 上报的 GPU 名）；换显卡/切 CPU 时
+     自动重新探测，不会拿旧的 GPU 数据给 CPU 用；
+   - 探测失败不覆盖磁盘上的旧有效条目（会话内 2 分钟用保守档兜底）。
+
+| ratio | 块大小 | 预热块数 | 适用 |
+|---|---|---|---|
+| ≤ 0.4 | 20 秒 | 2 | 强 GPU，几乎无缝 |
+| 0.4 – 0.6 | 15 秒 | 2 | 中端 GPU |
+| 0.6 – 0.9 | 10 秒 | 3 | 入门 GPU / 快 CPU |
+| > 0.9 | 6 秒 | 4 | CPU，尽量平滑 |
+| 探测失败 | 10 秒 | 3 | 保守兜底（60 秒内不重复探测） |
+
+块大小换算：中文 ≈ 3.6 字/秒 → `maxChars ≈ chunkSec × 3.6`（拉丁文本按 12 字/秒）。
+
+### 为什么分档而不是固定值？
+
+同一套代码要在"4090 用户"和"核显用户"上都成立。固定大块在 CPU 上会频繁断流，
+固定小块在 GPU 上是浪费。**按本机实测速度自适应**才是"即选即用"的根基。
+
+## 4. 文本切块
+
+`splitText(text, maxChars)`：
+
+1. 按句号/感叹/问号/分号（含中英文）切句；
+2. 超长句再按逗号/顿号切段；
+3. 仍超长的硬切（每段 ≤ maxChars）；
+4. 尽量让每块落在语义边界，避免在句中切断导致听感断裂。
+5. **原子 token 保护**：URL / 邮箱 / 小数 / 版本号（如 `3.14`、`v2.0.1`）先换成无标点
+   placeholder 再切分——句子级切分不会把小数里的 `.` 误当句号拆开；硬切（`safeEnd`）会
+   滑到最近空白/标点边界，且绝不切断 placeholder（长 URL 保持整段读出）。
+6. **孤儿块合并**：末尾不足 8 字的极短句并入前一块（合并后 ≤ maxChars），避免"结巴"听感。
+
+## 5. 协议：任务队列（Host 侧）
+
+`POST /dsh-tts-api/speak`（RVC + Edge 底噪 + 预估 > 12 秒时）：
+
+```jsonc
+// 请求不变；响应变为：
+{ "jobId": "j1", "chunks": ["/dsh-tts-audio/c1", "/dsh-tts-audio/c2"], "total": 6,
+  "ratio": 0.24, "chunkSec": 20 }
+// chunks 只含"预热块"；总块数在 total
+```
+
+`GET /dsh-tts-api/rvc-next?job=j1`（前端逐块拉取）：
+
+```jsonc
+{ "url": "/dsh-tts-audio/c3", "more": true }   // 还有后续
+{ "done": true }                               // 已到末尾
+{ "error": "后续段落合成失败：..." }            // 某块失败
+```
+
+Host 内部：
+
+- 每 job 一个**串行转换链**（`job.tail`），并发拉取自动排队，RVC 服务不被并发打爆；
+- 每块 = Edge 合成该块文本 → RVC 转换 → 临时 wav → 音频路由 URL；
+- job 惰性回收：完成 2 分钟后 / 创建 10 分钟后清理，上限 50 个；
+- 单块失败不影响已缓冲的块，只把错误带给前端，前端提示后停止。
+
+## 6. 前端渐进播放（无感衔接）
+
+`playChunks(jobId, chunks, total, token)` 使用 **Web Audio 精确调度**：
+
+- 每个块 `fetch → decodeAudioData` 成 AudioBuffer（保持 2 块解码余量），
+  按采样时钟**首尾相接调度**：`src.start(prevEnd)`（prevEnd 由已调度缓冲时长累加），
+  块间零事件抖动、零重载延迟；
+- **服务端裁剪每块边缘填充静音**（rvc-server `/convert` 输出前 `trim_edges`）：
+  实测每块头 138ms / 尾 538ms 纯静音（Edge TTS + RVC 填充），裁掉并各保留
+  20ms / 120ms 自然气息，块间不再有 ~680ms 死寂；
+- 停止/打断：`speakToken` 全局令牌 + 源列表 `stop()`（waCleanup），立即静音；
+- **进度可见**：`shared.chunkProgress = { index, total }` 随块播放更新——朗读按钮
+  tooltip 与试听面板显示「第 x/y 段 · 边播边合成」（绝不静默丢内容）；
+- 失败：某块合成失败 → 红字提示并停止；无 Web Audio 环境降级为双 `<audio>` ping-pong。
+
+> 备注：`vc_single` 返回 **int16**，`trim_edges` 先归一化为 float [-1,1] 再处理，
+> 否则 `sf.write` 会把 int16 样本值当 [-1,1] 幅值整体削波（曾导致输出 99% 满幅失真）。
+
+## 7. RVC 服务端配套
+
+`rvc-server.py` 本次新增：
+
+1. **`/health` 上报 `gpu_name` / `vram_gb`** —— 校准持久化的设备指纹来源；
+2. **faiss 索引缓存**：RVC pipeline 每次转换都会 `faiss.read_index` 重新读一遍
+   ~400MB 索引文件（每块一次，代价可观）。现在按路径缓存加载好的 Index 对象，
+   `/load` 时清空 —— 分块模式下每块省掉一次 400MB 磁盘读。
+
+## 8. 边界与回退
+
+| 情况 | 行为 |
+|---|---|
+| 短文本（≤12 秒） | 不进队列，走原来的单 URL 链路（零额外开销） |
+| 探测失败 | 保守档（10 秒 / 预热 3），会话内 2 分钟不重复探测 |
+| 某块转换失败 | 已缓冲的继续播，后续报错并停止 |
+| 停止 / 换消息 / 切会话 | 令牌失效，队列立即退出，无残留播放 |
+| 刷新页面 | 队列随页面消失；Host job 按时回收 |
+
+## 10. 实测（RTX 5070 + azusa-test）
+
+| 场景 | 结果 |
+|---|---|
+| 短句链路 | ~4.6-5.4s（含 Edge 合成） |
+| 长文本首响 | 探测 + 预热 2 块 ≈ 6-7s（**此后 7 天内从 calibration.json 直接复用，不再探测**） |
+| 长文本全链 | 6/6 块取完，迟到块 RIFF 476KB；块间无感知停顿 |
+| 索引缓存收益 | ratio 0.62 → 0.48（省掉每块 400MB 索引重读），档位 10s/3 → 15s/2 |
+
+## 11. Phase 2 预留
+
+- 音色包注册表 + 下载 UI（版权干净音色）→ 已包含在下方"已完成"（含私有仓库 rvc-for-tts 示例）；
+- 便携运行时打包 → **已完成（v1）**：`tools/package-runtime.py` 复制已验证环境 + 可选
+  torch cu128 升级（RTX 50 系提速，官方 CDN 慢时用国内镜像）；本机实测转换正常。
+
+> 已完成：
+> - `calibration.json` 落盘（`~/.dsh/tts-rvc/`，7 天有效 + 设备指纹，跨会话复用探测结果）；
+> - **紧凑索引生成工具**（设置面板「索引路径」旁「压缩」按钮）：408MB 原索引
+>   子采样重建为**与源同度量**的精确 flat 索引（RVC 训练默认 L2，pipeline 的
+>   `square(1/score)` 加权即按 L2 设计），2k→5.9MB（-98.5%）、10k→29.3MB（-92.5%），
+>   RVC 管线零改动兼容，实测转换正常；音色包分发不再受索引体积阻碍；
+> - **音色包注册表 + 下载 UI**：清单格式（schema 2：模型 + indexes 变体数组 + sha256 +
+>   版权/作者/版本，url 支持相对路径），Host 代理清单与下载（规避 CORS）、sha256 逐一校验后
+>   安装到 `~/.dsh/tts-rvc/packs/<id>/`，自动填入模型/索引并应用底噪/f0/index_rate 默认值；
+>   失败自动清理残留；mock 仓库 `tests/mock-registry.mjs` 供本地测试；私有音色仓库
+>   `github.com/1624318455/rvc-for-tts`（azusa-test 模型 + 2k/10k/20k 紧凑索引）；
+> - **便携运行时打包 v1**：`tools/package-runtime.py`（--skip-torch 零下载即可用；
+>   可选 cu128 升级适配 Blackwell，官方 CDN 慢时用 aliyun 镜像）。
+
+---
+
+## English summary
+
+RVC is voice **conversion** (input length == output length), not TTS, so a long
+read must first synthesize the whole base audio with Edge TTS. Instead of
+converting everything before playing (long silent wait), the plugin now:
+
+1. **Probes** the local machine once (convert a ~3.6s clip, measure
+   `ratio = convert_time / audio_seconds`); results persist to
+   `~/.dsh/tts-rvc/calibration.json` (7-day validity, GPU-name fingerprint,
+   re-probes on device change), so the probe is paid only once per config;
+2. Picks **chunk size (6–20s) and prewarm count (2–4)** from a ratio tier table;
+3. Splits the text into sentence-aligned chunks, converts the prewarm chunks,
+   and returns a **job queue** immediately;
+4. The client **plays while prefetching**: each next chunk is converted during
+   the current chunk's playback (`GET /rvc-next`), so long reads stream
+   seamlessly on GPU and degrade gracefully on CPU (smaller chunks, more
+   prewarm);
+5. The RVC server reports GPU name/VRAM in `/health` and **caches the faiss
+   index** so each chunk no longer re-reads the ~400MB index file.