VoiceStudio — OmniVoice 引擎（默认）{#omnivoice-engine-default}¶

OmniVoice (k2-fsa/OmniVoice) 是 VoiceStudio 的默认 TTS 引擎——全新安装后无需任何配置即可使用的引擎。它支持 600 多种语言的零样本声音克隆，输出 24 kHz 单声道音频。声音克隆、配音和听写功能开箱即用。

何时选择它¶

• 你需要克隆功能以及最广泛的语言覆盖（参见 languages.md）。
• 你拥有 GPU（CUDA、Linux 上的 AMD ROCm 或 Apple Silicon MPS），且 VRAM 约 6 GB 或更高。
• 你刚刚安装了 VoiceStudio——它已被默认选中。

对于低 VRAM 或仅 CPU 的机器，OmniVoice GGUF 变体通过量化原生二进制运行相同模型，内存占用大幅降低。

要求¶

• 支持 CUDA、AMD ROCm（Linux）、MPS（Apple Silicon）或 CPU 运行——自动检测。
• 推荐 VRAM 下限：独立 GPU 6 GB。这是唯一一个有实测下限的引擎：在 4 GB 显卡（GTX 1650 Ti、Quadro P2000——问题 #1226 / #1222）上，驱动程序会将内存换页到系统 RAM，本应几秒完成的渲染会运行数分钟，直到计算预算将其终止。UI 会在你等待之前发出警告；没有硬性阻止，因为短输入仍然可以容纳。低于下限的 CUDA 或 ROCm 显卡也会按其所表现的 CPU 级硬件进行预算——使用更长的 OMNIVOICE_CPU_GENERATE_TIMEOUT_S（600 秒），而非加速的 300 秒（#1804）。Apple Silicon 被排除在外：统一内存没有可比较的专用内存池。
• 无需额外安装——模型随应用一起提供，并在首次使用时下载权重（参见 downloading-models.md）。

选择引擎¶

OmniVoice 是默认引擎，因此通常无需任何操作。如果你曾切换走并想切回来：

• Model Catalogue，或
• 设置 OMNIVOICE_TTS_BACKEND=omnivoice。

环境变量会覆盖持久化的 UI 选择。

行为说明¶

• 权重在首次使用时惰性加载，并与应用其他部分（配音、听写）共享——模型永远不会被重复加载。
• 在 CUDA 和 ROCm 上，模型以 fp16 配合 torch.compile 运行；PyTorch 通过其 cuda API 暴露 ROCm/HIP 设备，而 VoiceStudio 的引擎矩阵将硬件报告为 ROCm。已安装的语音识别器可以为克隆提供缺失的参考转写文本。
• 输出为 24 kHz 单声道；共享母带处理链（高通滤波器 + 压缩器）针对该采样率调校并自动应用。
• 克隆需要一段简短的参考音频片段（ref_audio）；3–10 秒是理想长度。片段的转写文本可改善条件效果——如果配置文件没有转写文本，VoiceStudio 会在首次使用时调用已安装的语音识别器，并将结果保存到配置文件中。这包括目录中的 Whisper Turbo CT2 构建；克隆不需要第二份 Transformers 副本。在声音克隆中，你输入的参考转写文本也会伴随所选保存的声音，并在该次生成中覆盖其存储的转写文本。将该字段留空则保留存储的转写文本或自动转写路径。模型级别的 Whisper 回退方案也需要缓存的权重；它绝不会在克隆期间下载另一个 ASR。它复用已安装的已配置 PyTorch Whisper 模型的任何快照（OMNIVOICE_PYTORCH_ASR_MODEL）、openai/whisper-large-v3-turbo 或 openai/whisper-large-v3，包括 Model Catalogue 在 Hugging Face 缓存中留下的固定提交布局。 如果没有安装识别器，请提供匹配的参考转写文本，或在 Model Catalogue 中显式安装并选择语音转文本模型。提供了转写文本的片段限制为 20 秒，以确保两者保持一致；请将两者裁剪到同一段内容。没有转写文本时，VoiceStudio 可在五次连续、有界的转写扫描中搜索最多 75 秒，并选择检测到最多语音的 15 秒段落。这些扫描使用 Model Catalogue 中已安装的语音转文本模型。对于超过 20 秒的片段，VoiceStudio 会跳过整段转写并忽略已保存的配置文件转写文本，因此较长的已保存声音也使用此选择逻辑。OmniVoice 自身的 Whisper 快照仅在目录识别器无法转写任何窗口时作为回退方案，且绝不在克隆期间下载。当两者都无法运行时，错误信息会提示片段过长，请裁剪到 3–10 秒，因为转写文本无法挽救。对这种片段在请求中输入的转写文本会被拒绝并返回 [clone_ref_too_long]。只有那个 15 秒窗口会被发送到模型。超过 75 秒的片段必须首先裁剪。如果未检测到任何语音，请裁剪到清晰的 3–10 秒段落或提供其匹配的转写文本。
• 对于跨语言克隆，请将参考转写文本保留在样本的原始语言中，并用目标输出语言编写新脚本。选择该输出语言，或选择 Auto 进行与语言无关的合成。选择/上传不同的参考声音会保留脚本的语言设置。语言选择器指导合成；它不会翻译文本。在 POST /generate 和共享配置文件条件设置中，显式的 language=Auto 会覆盖已保存的配置文件语言；省略 language 则保留配置文件默认值，以兼容现有 API 客户端。引擎的语言覆盖范围和口音质量仍会有所不同；请使用支持目标语言的多语言引擎。
• 编码后的声音参考会持久化存储在磁盘上（应用数据目录中的 prompt_cache/），因此已知的短参考在重启后可跳过重新编码和转写。长参考在重启后必须对窗口进行一次排序以恢复选定的转写文本；后续生成会复用所选段落和缓存的提示，而无需重新解码音频片段。设置 OMNIVOICE_PROMPT_DISK_CACHE=0 可将提示缓存仅保留在内存中。
• 风格属性（instruct）和参考片段可以组合：当它们一致时，instruct 会稳定其指定的属性的克隆效果（上游将方言克隆记录为典型用例——方言参考 + 匹配的方言 instruct）。当它们冲突时，参考音频优先。
• 内联发音控制：中文通过带声调数字的拼音（打ZHE2出售），英文通过方括号中的 CMU 音素（[B EY1 S]）。非语言标签（如 [laughter]）在 expressive-speech.md 中有说明。
• 声音设计可通过 Design 标签页从属性（性别、年龄、音高、耳语、英语口音、中文方言）入手——无需参考音频。
• CUDA 上可选的 FlashInfer 加速：安装 flashinfer-python 包后设置 OMNIVOICE_FLASHINFER=1（或 =graph 以启用 CUDA 图捕获，最适合一次一个渲染）——参见 performance.md。默认关闭；如果包缺失或内核失败，应用会记录原因并继续使用标准路径。

Known limits 已知限制¶

• Voice design 语音设计仅理解固定的属性词汇表——自由形式的设计文本会映射到这些属性上，超出该范围的措辞会被忽略。设计基于英语和中文训练，在低资源语言中可能不稳定；其他情况下的描述驱动设计请尝试 VoxCPM2。
• 在 CUDA 或 ROCm 显卡上低于 6 GB VRAM 下限时，渲染速度会非常慢；它们获得的是更长的 CPU 计算时间预算而非加速预算，但仍可能超时。建议优先使用 OmniVoice GGUF 或 CPU 引擎（如 PocketTTS）。

Troubleshooting 故障排查¶

• 在小型 GPU 上出现"Too heavy for the available compute"：请参见上面的 VRAM 下限——切换到 OmniVoice GGUF 或关闭其他 GPU 应用程序。
• 首次生成较慢：第一次调用会下载数 GB 的权重。为了让首次渲染更快，请提前从 Model Catalogue（TTS 标签页 → 引擎的 Weights） 安装模型——首次生成耗时较长几乎总是下载所致，而非卡死。
• 一般安装问题：install/troubleshooting.md。

另请参阅：benchmarks.md、 performance.md、 expressive-speech.md、 disk usage。

超时的子进程会被终止，并在请求返回前获得一个有限的退出等待时间，因此重试无法复用其正在关闭的进程。超时清理仍绑定于原始子进程，无法终止替换的 sidecar。如果该等待无法确认退出，VoiceStudio 会保留该进程以进行清理，并阻止另一次尝试，直至该进程可以被回收，而不是在其旁边启动第二个引擎。后续的重试或关闭会重新尝试有限的清理。