VoiceStudio — VoxCPM2 Engine¶

VoxCPM2 (OpenBMB) 是 VoiceStudio 中达到工作室级质量的选项：原生 48 kHz 输出、零样本声音克隆，并且是 VoiceStudio 各引擎中唯一支持声音设计的引擎——仅凭文本描述（“年轻女性、温暖音色、英式口音”）即可创建合成声音，完全不需要参考音频。

何时选用¶

• 你希望在不提供参考片段的情况下进行声音设计。
• 你希望获得最高的输出采样率（48 kHz，OmniVoice 为 24 kHz）。
• 你的语言属于其支持的 30 种语言之一：阿拉伯语、缅甸语、中文、丹麦语、荷兰语、英语、芬兰语、法语、德语、希腊语、希伯来语、印地语、印度尼西亚语、意大利语、日语、高棉语、韩语、老挝语、马来语、挪威语、波兰语、葡萄牙语、俄语、西班牙语、斯瓦希里语、瑞典语、他加禄语、泰语、土耳其语、越南语。

环境要求¶

• Python ≥ 3.10，PyTorch ≥ 2.5。
• 建议使用 CUDA ≥ 12 以获得全速；MPS（Apple Silicon）和 CPU 也可用。

安装¶

将包安装到 VoiceStudio 的 Python 环境中：

pip install "voxcpm>=2.0.3"

这是一个版本下限，而不是固定版本锁定——较早安装的版本仍可使用，但引擎会在加载时提示升级。然后通过 Model Catalogue 或 OMNIVOICE_TTS_BACKEND=voxcpm2 选择引擎。

模型选择¶

首次使用会从 HuggingFace 下载一个数 GB 的 checkpoint。过去，接近下载完成时被中断会直接导致加载中止（#1224）；现在加载时会使用全新客户端重试一次。另见 downloading-models.md。

行为说明¶

• 声音设计： 提供描述而不提供参考音频。VoiceStudio 会以原生 (description)text 格式传递该描述；VoxCPM 2.0.3 中没有单独的 voice_description 参数。
• 克隆： 参考片段会在使用前进行预处理（修剪边缘静音，并截取前 30 秒），这样原始片段中的空白静音不会影响输出；若预处理出现任何问题，则按原样使用原始片段。当截断对片段造成裁剪时，其整段转写文本不再匹配，因此该文本会被忽略，被截断的片段将作为普通参考进行克隆。
• 风格指令（Style 字段、API instruct，或文本开头的 (instruction)）使用可控克隆：参考提供音色，而保存的转写文本不会强制延续其原有表达方式。
• 普通克隆 在提供参考和转写文本时保留上游的续说模式。仅有转写文本而无参考音频时，该文本会被忽略。在托管 sidecar 和进程内适配器中，这些映射均遵循 VoxCPM 2.0.3 示例。
• VoxCPM2 输出已母带处理的工作室级音频，因此 VoiceStudio 会跳过其共用的母带处理链路（该链路针对 24 kHz 引擎调校）——仅应用良性的响度归一化。
• 尾部静音保护会从生成结果中修剪较长的近静音尾段，同时保留一个简短的自然尾音。

已知限制¶

• 比轻量级 CPU 引擎慢——参见 benchmarks.md 和 performance.md。
• 语言覆盖为 30 种；其他语言请使用默认的 OmniVoice 引擎（languages.md）。

一键安装¶

点击 Model Catalogue → VoxCPM2 中的 Install。VoiceStudio 会将 VoxCPM2 放入其数据目录下独立的 Python 环境中，并在独立进程中运行。在 NVIDIA GPU 上安装 PyTorch 的 CUDA 构建版本，在其他 Windows 和 Linux 机器上安装 CPU 构建版本，在 Apple Silicon 上安装常规构建版本。

它安装的任何内容都不会影响 VoiceStudio 本身或任何其他引擎；同一行中的 Uninstall 只会删除该文件夹。已有的 pip install voxcpm 安装会照常工作。在 Intel Mac 上不提供该按钮，因为那里没有它所需的 PyTorch 构建版本。模型权重在首次使用时下载。

故障排除¶

• 引擎显示不可用：未安装 voxcpm 包——请运行上面的 pip install 并重启 VoiceStudio。
• 首次下载反复失败：请检查网络连接/HF 访问，然后参阅 install/troubleshooting.md。

另见：expressive-speech.md、磁盘使用。