需要本地语音克隆与 TTS 时：用 Voicebox 合成…

在本地或自托管环境通过 Voicebox 的 REST API、桌面端和模型队列完成语音克隆、TTS 生成、批量长文合成与故障处理。

适用场景

解决思路

1. 选择安装方式：macOS Apple Silicon 使用 https://voicebox.sh/download/mac-arm；macOS Intel 使用 https://voicebox.sh/download/mac-intel；Windows 使用 https://voicebox.sh/download/windows；Docker 使用 `docker compose up`；Linux 从 https://voicebox.sh/linux-install 源码构建。
2. 从源码构建前安装依赖：Bun、Rust、Python 3.11+、Tauri prerequisites。
3. 源码构建：执行 `git clone https://github.com/jamiepine/voicebox.git`，然后 `cd voicebox`。
4. 安装 just 任务运行器：macOS 执行 `brew install just`，任意平台执行 `cargo install just`。
5. 设置 Python venv 和所有依赖：执行 `just setup`。
6. 启动后端和桌面应用开发模式：执行 `just dev`。
7. 查看所有可用命令：执行 `just --list`。
8. 理解服务入口：FastAPI 后端运行在 `http://localhost:17493`，即使使用桌面应用也可直接访问该 API；交互文档在 `http://localhost:17493/docs`。
9. 生成语音：向 `http://localhost:17493/generate` 发送 POST 请求，请求体包含 `text`、`profile_id`、`language`。
10. 指定引擎生成语音：在 `/generate` 请求体中增加 `engine`，可选值为 `qwen3-tts`、`luxtts`、`chatterbox`、`chatterbox-turbo`、`tada`。
11. 使用副语言标签生成语音：仅在使用 `chatterbox-turbo` 时，在 `text` 中插入如 `[laugh]`，例如 `That is absolutely hilarious! [laugh] I cannot believe it.`，并设置 `engine` 为 `chatterbox-turbo`。
12. 列出所有语音配置：GET `http://localhost:17493/profiles`。
13. 创建语音配置：POST `http://localhost:17493/profiles`，请求体包含 `name`、`language`，可选 `description`。
14. 上传音频样本到语音配置：POST `http://localhost:17493/profiles/{profile_id}/samples`，使用 multipart 表单字段 `file=@/path/to/voice-sample.wav`。
15. 导出语音配置：GET `http://localhost:17493/profiles/{profile_id}/export --output narrator-profile.zip`。
16. 导入语音配置：POST `http://localhost:17493/profiles/import`，使用 multipart 表单字段 `file=@narrator-profile.zip`。
17. 获取生成状态：使用 SSE 流 GET `http://localhost:17493/generate/{generation_id}/status`，可配合 `curl -N`。
18. 列出最近生成：GET `http://localhost:17493/generations`。
19. 重试失败生成：POST `http://localhost:17493/generations/{generation_id}/retry`。
20. 下载生成音频：GET `http://localhost:17493/generations/{generation_id}/audio --output output.wav`。
21. 列出可用模型及下载状态：GET `http://localhost:17493/models`。
22. 从 GPU 内存卸载模型但不删除：POST `http://localhost:17493/models/{model_id}/unload`。
23. TypeScript/JavaScript 基础 TTS 客户端：定义 `VOICEBOX_URL` 为 `process.env.VOICEBOX_API_URL ?? "http://localhost:17493"`；用 `fetch` POST `/generate`，设置请求头 `Content-Type: application/json`，body 为包含 `text`、`profile_id`、`language`、`engine` 的对象；若响应非 ok 则抛错；返回 JSON。
24. TypeScript/JavaScript 轮询完成：循环 fetch `/generations/${generationId}`；若 `status` 为 `complete` 返回 `${VOICEBOX_URL}/generations/${generationId}/audio`；若为 `failed` 抛错；每次等待 1000ms；默认超时 60000ms。
25. TypeScript/JavaScript 用 SSE 流状态：用 `EventSource` 连接 `${VOICEBOX_URL}/generate/${generationId}/status`；在 `onmessage` 中解析 JSON 并回调 status；当 status 为 `complete` 或 `failed` 时关闭 EventSource；返回 cleanup 函数用于关闭连接。
26. TypeScript/JavaScript 下载音频为 Blob：fetch `/generations/${generationId}/audio`；检查响应 ok；返回 `response.blob()`；播放时用 `URL.createObjectURL(blob)` 创建 URL，`new Audio(url).play()`，并在 `onended` 中 `URL.revokeObjectURL(url)`。
27. Python 集成：用 `httpx.AsyncClient(timeout=120.0)` POST `/generate`，取 `generation_id`；轮询 `/generations/{generation_id}` 最多 120 次，每次 `asyncio.sleep(1.0)`；若 status 为 `complete` 则 GET `/generations/{generation_id}/audio` 并返回 content；若为 `failed` 抛 `RuntimeError`；超时抛 `TimeoutError`；最后写入 `output.wav`。
28. 选择 TTS 引擎：`qwen3-tts` 适合质量与指令，支持 10 种语言，中等 VRAM，支持在文本中写 delivery instructions；`luxtts` 适合快速 CPU 生成，仅英文，约 1GB，CPU 上 150x 实时，48kHz；`chatterbox` 适合多语言覆盖，支持 23 种语言；`chatterbox-turbo` 适合表现力与情绪，仅英文，低 VRAM 350M，支持 `[laugh]`、`[sigh]`、`[gasp]` 等标签；`tada` 适合长文连贯，支持 10 种语言，高 VRAM，可处理 700s+ 音频，HumeAI 模型。
29. 使用 Qwen3-TTS 的 delivery instructions：在 `text` 中嵌入自然语言指令，例如 `(whisper) I have a secret to tell you.` 或 `(speak slowly and clearly) Step one: open the application.`，并设置 `engine` 为 `qwen3-tts`。
30. 使用 Chatterbox Turbo 的 paralinguistic tags：可用 `[laugh]`、`[chuckle]`、`[gasp]`、`[cough]`、`[sigh]`、`[groan]`、`[sniff]`、`[shush]`、`[clear throat]`；在 `text` 中插入这些标签，并设置 `engine` 为 `chatterbox-turbo`。
31. 配置模型目录：启动前执行 `export VOICEBOX_MODELS_DIR=/path/to/models`。
32. 配置 AMD ROCm GPU：可覆盖执行 `export HSA_OVERRIDE_GFX_VERSION=11.0.0`。
33. Docker 配置：在 `docker-compose.yml` 的 voicebox 服务中设置环境变量 `VOICEBOX_MODELS_DIR=/models`；挂载 `/host/models:/models`；映射端口 `17493:17493`；NVIDIA GPU 直通使用 `deploy.resources.reservations.devices`，配置 `driver: nvidia`、`count: 1`、`capabilities: [gpu]`。
34. 创建语音配置完整流程：1) POST `/profiles` 创建 profile；2) 用 FormData append `file` 为音频 blob，文件名为 `sample.wav`，POST 到 `/profiles/${profile.id}/samples`；3) 用新 `profile_id` 调用 `generateSpeech`。
35. 批量生成：对每个 item 调用 `generateSpeech` 全部提交；Voicebox 会串行排队以避免 GPU 争用；然后用 `waitForGeneration` 等待全部完成并返回 audioUrls。
36. 长文本生成：Voicebox 会在句子边界自动分块，直接发送完整文本，最多支持 50000 字符；长文一致性推荐 `engine` 使用 `tada`。
37. API 无响应排查：执行 `curl http://localhost:17493/health`；开发模式重启后端执行 `just backend`；查看日志执行 `just logs`。
38. GPU 未检测排查：执行 `curl http://localhost:17493/system/info` 查看检测到的后端；启动前执行 `export VOICEBOX_FORCE_CPU=1` 强制 CPU 模式。
39. 模型下载失败或慢排查：设置空间更大的模型目录，例如 `export VOICEBOX_MODELS_DIR=/path/with/space`，然后执行 `just dev`；取消卡住的下载可通过 API 执行 `curl -X DELETE http://localhost:17493/models/{model_id}/download`。
40. VRAM 不足排查：执行 `curl http://localhost:17493/models | jq '.[] | select(.loaded == true)'` 列出已加载模型；执行 `curl -X POST http://localhost:17493/models/{model_id}/unload` 卸载指定模型。
41. 音频质量优化：使用 5–30 秒干净、无噪声的语音样本；上传 3–5 个不同句子的多个样本以提升克隆质量；多语言克隆使用 `chatterbox` 引擎；样本音频最好为 16kHz+ 单声道 WAV；英文最高输出质量使用 `luxtts`，其输出为 48kHz。
42. 崩溃后生成卡在队列处理：Voicebox 启动时会自动恢复 stale generations；若问题持续，执行 `curl -X POST http://localhost:17493/generations/{generation_id}/retry`。
43. React 前端集成：定义 `VOICEBOX_URL = import.meta.env.VITE_VOICEBOX_URL ?? "http://localhost:17493"`；组件维护 `text`、`audioUrl`、`loading` 状态；`handleGenerate` 中 POST `/generate`，取 `generation_id`；每秒轮询 `/generations/${generation_id}`，直到 `complete` 时设置 `audioUrl` 为 `${VOICEBOX_URL}/generations/${generation_id}/audio`，`failed` 时抛错；`finally` 中 `setLoading(false)`；渲染 textarea、button 和 audio controls。

适用边界 · 注意事项

• 不适用于无法或不愿在本机运行/安装 Voicebox 服务、不能访问 `localhost:17493` 的场景。
• 不适用于需要 Voicebox 未覆盖的语言、引擎能力或必须使用托管云 TTS 的场景。
• 不适用于不能管理本地模型文件、GPU/CPU 资源或不能接受本地推理资源占用的场景。