VoiceStudio — audio.cpp 引擎（Breeze-TTS-2、dots.tts）¶

audio.cpp 是一个纯 C++ 实现的 ggml 音频推理框架，提供 Windows、macOS 和 Linux 预构建二进制文件，且不依赖 Python。VoiceStudio 会自动发现已安装二进制文件中所编译的计算提供程序，并选择最佳可用设备。VoiceStudio 通过回环 HTTP 驱动其 audiocpp_server。两个引擎共享同一运行时：

• audiocpp — breeze_tts 系列：Breeze-TTS-2（BreezeBlue，3B 参数，英语 + 中文，支持声音克隆 + 声音设计 + 声音方向，24 kHz）。研究/非商业权重。
• audiocpp-dots — dots_tts 系列：dots.tts SOAR（多语言零样本声音克隆，Apache-2.0）。参见 dots.tts。

始终为可选启用，永非默认。 请在 Model Catalogue → 引擎 中显式选择 audiocpp 或 audiocpp-dots（或设置 OMNIVOICE_TTS_BACKEND）。

许可协议 — 启用前请阅读¶

• audio.cpp 代码： Apache-2.0。
• Breeze-TTS-2 权重（上游 BreezeBlue/Breeze-TTS-2 及 audio-cpp/audio.cpp-gguf GGUF 重新打包）：仅限研究与非商业用途，依据 BreezeBlue Research and Non-Commercial License。自托管输出同样受此限制；BreezeBlue 付费订阅仅涵盖托管平台输出，不涵盖本引擎。

平台支持¶

VoiceStudio 会对每个已安装的二进制文件运行一次 audiocpp_server --list-devices，优先选择 CUDA、ROCm、Metal，其次是独立 Vulkan GPU，并将 CPU 保留为安全后备。设备编号仅在各后端注册表内部有效。Q8_0 GGUF 约为 4.73 GiB，另加运行时内存。

对于 CUDA、HIP 或通过 Vulkan 暴露的独立 GPU，请预留约 6 GB 专用 VRAM。Metal 和 Vulkan 集成 GPU 使用统一内存机制，因此不适用该专用 VRAM 下限。

安装¶

在受支持的桌面平台上，先从 设置 → 模型 安装模型，然后点击 audio.cpp 引擎行上的 安装（TTS 行和 Sortformer 说话人分离行会安装相同的共享运行时）。VoiceStudio 会获取固定的归档文件，校验其发布的大小和 SHA-256，拒绝不安全的归档路径，探测其设备列表，并将其安装到可跨更新保留的应用数据引擎目录下。该操作为显式操作；生成过程绝不会下载或更新可执行代码。

对于用户自行管理的运行时：

1. 从 audio.cpp releases 下载适用于你平台的 v0.7.4 预构建版本并解压。在 Windows 或 Linux 上，为获得广泛的 GPU 支持，请使用 Vulkan 归档；当 Vulkan 不可用时，使用 CPU 归档；在 Windows 上使用 NVIDIA 时，请使用匹配的 CUDA 归档。按照上游要求，Windows CUDA 安装需要将 bin-…-cuda… 和匹配的 cudart-…-cuda… 两个归档解压到同一目录。Linux 归档不保留可执行位，因此解压后请运行 chmod +x audiocpp_server。

在解压前先验证归档。固定的 SHA-256 校验和如下：

在 Linux 上运行 sha256sum <archive>，在 macOS 上运行 shasum -a 256 <archive>，或在 PowerShell 中运行 Get-FileHash <archive> -Algorithm SHA256，并将完整结果与上表进行比较。 2. 将 OMNIVOICE_AUDIOCPP_BIN 设置为 audiocpp_server 二进制文件（Windows 上为 audiocpp_server.exe）：

# macOS / Linux
echo 'export OMNIVOICE_AUDIOCPP_BIN=$HOME/apps/audio.cpp/audiocpp_server' >> ~/.zshrc
source ~/.zshrc

或者将 OMNIVOICE_AUDIOCPP_DIR 设置为包含该二进制文件的目录。 3. 重启 VoiceStudio，打开 Model Catalogue（TTS 标签页 → 该引擎的权重），找到 Breeze-TTS-2 Q8_0 for audio.cpp，查看其研究/非商业许可说明，然后点击 安装。生成过程绝不会自动开始这次约 4.73 GiB 的下载。 4. 在 Model Catalogue 中选择 audiocpp（TTS 标签页 → 使用）。服务器会在首次生成时按需启动（server.json 和 server.log 位于应用数据目录下的 audiocpp/ 目录中）。

dots.tts¶

audiocpp-dots 在同一运行时上运行 dots.tts SOAR，因此它不仅支持 macOS 和 Linux，也支持 Windows——这与 Python 版 dots.tts 引擎 不同，后者没有 Windows 安装路径（#2665）。

1. 如上所述安装运行时。
2. 在 Model Catalogue（TTS 标签页 · audio.cpp · dots.tts → Weights） 中，安装 audio.cpp dots.tts SOAR (Q8_0)（约 2.96 GB，来自与 Breeze-TTS-2 相同的固定 audio-cpp/audio.cpp-gguf 修订版本）。它是一个独立的包：安装或卸载它都不会影响 Breeze-TTS-2 或 Sortformer，反之亦然。
3. 选择 audiocpp-dots 并克隆声音：一个参考片段及其 转录文本（转录文本可选，但能提高匹配度）。它会从文本中读取语言。 没有声音设计模式，并使用自身调校的 guidance（1.2）而不是共享的 guidance 滑块。

它在端口 17861 上运行自己的服务器，server.json 和 server.log 位于应用数据目录 audiocpp-dots/ 下。

语音模式¶

Breeze-TTS-2（audiocpp）。三种模式都通过同一个语音端点——由是否存在参考音频决定：

• Clone（克隆）： ref_audio + ref_text（与上游一致，需精确转录文本）。
• Direction（定向）： ref_audio + ref_text + instruct （例如“说慢一点，语气克制而严肃”）。
• Design（设计）： description（或 instruct），不提供 ref_audio （例如“一位温暖、体贴的年轻女性……”）。上游使用 guidance_scale ≈ 4 来增强指令遵循能力。

可选环境变量¶

OMNIVOICE_AUDIOCPP_BIN/_DIR/_BACKEND/_DEVICE 同时适用于两个引擎； 不带 DOTS 的 _MODEL/_PACKAGE/_PORT 变量仅适用于 Breeze-TTS-2。

audio.cpp 的覆盖项优先于全局 Settings 中的计算选择。全局 CUDA/ROCm 选择可以匹配 通过 Vulkan 暴露的 NVIDIA/AMD GPU。显式指定的 audio.cpp 覆盖项不可用时会报错； 全局偏好不可用时会回退到 CPU，并显示为路由回退。

常见错误¶

audiocpp_server not found ...¶

未安装该二进制文件。请按照 Install（安装） 操作——错误消息中会给出 适用于你平台的确切发布 URL 和 SHA。

audiocpp_server exited during startup ...¶

受管回环端口可能被占用。请检查应用数据目录 audiocpp/ 中与 server.json 相邻的 server.log，或者设置不同的 OMNIVOICE_AUDIOCPP_PORT 并重启 VoiceStudio。

Breeze-TTS-2 ... not installed, dots.tts ... not installed or package ... not completely installed¶

请从 Model Catalogue（TTS 标签页 → 该引擎的 Weights） 安装模型。 如果安装中断导致其不完整，请在该处使用 Reinstall（重新安装）。 如果完整重新安装后错误仍然存在，请提交 issue 并附上包列表。

audio.cpp 作为受管原生服务器运行（没有 Python venv，没有 transformers 冲突）。 只有下载的 GGUF 会计入 sidecar 磁盘占用。

Model Catalogue 会自行检查共享 GGUF 仓库中的每个包（Breeze-TTS-2 + Sortformer、dots.tts）： 一个包永远不会让另一个包显示为已安装，卸载一个包也只会删除它自己的文件。 必需的权重文件还必须满足正常的权重大小下限；空的或截断的占位文件仍是不完整的。 更广泛的原生模型发现与执行仍有待集成。