VoiceStudio — Sherpa-ONNX 引擎¶

Sherpa-ONNX (k2-fsa/sherpa-onnx) 是一个统一的 C++ ONNX 运行时，它在单一 API 背后封装了 20+ 个 TTS 模型家族（VITS、MeloTTS、Piper、Kokoro、Matcha 等），并提供适用于 Linux、Windows 和 macOS（x86 与 ARM）的预构建 wheel 包。你需要自行提供模型：将 VoiceStudio 指向任何已下载的 sherpa-onnx TTS 模型目录即可。

何时选择它¶

• 你想要某个其他引擎没有提供的特定社区模型（例如适合你语言的 Piper 或 VITS 语音）。
• 你需要一个可靠的 CPU 引擎，并可选 CUDA 加速。

设置¶

1. 安装运行时：

pip install sherpa-onnx

1. 从 sherpa-onnx releases 下载一个 TTS 模型，并将其解压到某个长期保留的位置。

2. 将 VoiceStudio 指向该模型目录并重新启动：

export OMNIVOICE_SHERPA_MODEL=/path/to/model-dir

1. 通过 Model Catalogue（TTS 标签页 → Use）或 OMNIVOICE_TTS_BACKEND=sherpa-onnx 选择该引擎。

所选目录必须包含 tokens.txt 和一个模型：model.onnx，或 Piper 压缩包中以语音名称命名的 .onnx 文件。如果存在，espeak-ng-data/ 会用于 Piper 音素化，lexicon.txt 会用于由词典驱动的 VITS 模型（如 MeloTTS 和中文语音）；两者都不需要额外设置。

Sherpa-ONNX 没有内置默认模型，因此在 OMNIVOICE_SHERPA_MODEL 指向有效目录之前，引擎会报告不可用并附带原因。（在此检查之前，未配置就选择该引擎会导致一个被误标为内存不足的失败——#919。

配置¶

示例：美式英语 Piper 语音¶

curl -LO https://github.com/k2-fsa/sherpa-onnx/releases/download/tts-models/vits-piper-en_US-lessac-medium.tar.bz2
tar -xjf vits-piper-en_US-lessac-medium.tar.bz2
export OMNIVOICE_SHERPA_MODEL="$PWD/vits-piper-en_US-lessac-medium"

对其他 Piper 语音，使用相同的步骤，只需替换为相应的压缩包文件名和解压出的文件夹名。

许可证¶

通过此目录提供的模型仍受其各自许可条款的约束。由于 VoiceStudio 不提供也不编录此模型，其目录许可提示不涵盖该模型。在使用或分发生成的音频之前，请阅读解压文件夹中包含的模型卡。

行为说明¶

• 输出默认使用 22.05 kHz（VITS 默认值）；一旦加载模型，则使用模型自身的采样率。
• CPU 是通用基线；CUDA onnxruntime 提供程序在 Linux/Windows 安装中可用。
• 不支持克隆：语音来自模型本身。多说话人 VITS 模型通过数值 speaker id 选择语音；支持速度调节。
• 语言完全取决于你下载的模型。

已知限制¶

• 一次只能使用一个模型 — 切换模型需要更改 OMNIVOICE_SHERPA_MODEL 并重新启动。
• 不支持语音设计、参考音频克隆、情感控制（参见 expressive-speech.md）。

故障排查¶

• “OMNIVOICE_SHERPA_MODEL not set” / “No model.onnx in …”：请按照上方“设置”操作 — 变量必须指向 解压后的 模型目录，而不是下载的压缩包。包含多个 .onnx 文件但没有确切 model.onnx 的文件夹也会被拒绝，因为无法确定要使用哪个语音。
• 数字的朗读取决于模型语言是否有受支持的文本归一化器。逗号小数（例如 2,5）会以数字的形式传给语音；请将其写成文字（例如“two point five”）以获得更可靠的语音输出。
• 其他问题：install/troubleshooting.md。

另见：benchmarks.md、languages.md、disk usage。