在 Mac 上使用 VoxCPM2 克隆语音

通过 MLX 在 Apple Silicon 本地运行 VoxCPM2，从录音克隆声音，或用文字描述设计声音。这个 OpenBMB 模型可生成 30 种语言的 48 kHz 语音。先试听示例，再使用参考录音及其准确转写运行 CLI。

音频示例 · 使用 CLI 克隆语音 · VoxCPM2 与 Qwen3-TTS 对比

语音克隆示例

这些英语音频来自已发布的 FLEURS 对比。参考录音与生成语音使用不同句子。每段输出都是一个代表性样本；对比指标则汇总了多段音频。

参考音频英语 · 16 kHz

参考录音转写: One can only wonder what the keyboard will become when something newer comes along.

VoxCPM2 bf16英语 · 48 kHz

生成文本: While he was working at the hospital Liggins began to investigate premature labor during his spare time.

Qwen3-TTS Base 1.7B bf16 ICL英语 · 24 kHz

生成文本: While he was working at the hospital Liggins began to investigate premature labor during his spare time.

使用 CLI 克隆语音

将参考音频下载为 reference.wav。命令使用这段录音的准确转写；使用自己的声音样本时，请同时替换录音与转写。

speech speak "Hello from the cloned voice." \
    --engine voxcpm2 \
    --voxcpm2-variant bf16 \
    --voice-sample reference.wav \
    --voxcpm2-prompt-audio reference.wav \
    --voxcpm2-prompt-text "One can only wonder what the keyboard will become when something newer comes along." \
    --seed 42 \
    --output clone.wav

概述

48 kHz 输出 — 本工具链中唯一支持录音棚采样率的设备端引擎，其他 TTS 模块均上限 24 kHz。
声音设计 — 通过自然语言控制风格：--voxcpm2-instruct "young female voice, warm and gentle"。其他引擎均无此能力。
声音克隆 — 从 16 kHz 单段参考音频克隆；"ultimate cloning"（参考音频 + 文本）能更好地保留韵律。
30 种语言 — 英语、中文、印尼语、日语、韩语等。语言会从文本自动检测。
Apache 2.0 — 模型权重沿用上游 openbmb 许可，Swift 移植端遵循相同许可。

架构

由五个相互配合的组件合成 48 kHz 波形：

组件	说明
MiniCPM-4 base LM	28 层 MiniCPM-4，LongRoPE、GQA（16 Q / 2 KV 头，每头维度 128）、SwiGLU MLP。以文本 token + 音频 latent 作为条件。
Residual LM	8 层 MiniCPM-4 变体，不使用旋转位置编码。每生成一个音频 patch 后细化基础 LM 的隐状态。
FSQ + Local DiT estimator	标量量化的隐状态驱动一个 12 层 Diffusion Transformer（V2），在 64 维音频 latent 上以 patch=4 运算。默认使用 CFG-zero-star Euler 求解器，10 步时间。
AudioVAE V2	因果卷积解码器。输入 16 kHz 参考音频，输出 48 kHz 波形（内置 3× 上采样）。
停止头	对 LM 隐状态做逐步二分类。argmax = 1 表示在生成至少 `minTokens` 个 patch 后结束。

版本

当前 CLI 支持从上游 openbmb/VoxCPM2 检查点转换的 bf16 与 int8 模型包。量化用于语言模型及扩散模块的投影层；音频解码器保持全精度。

版本	量化方式	大小	HuggingFace
bf16	无（参考）	~5.0 GB	aufklarer/VoxCPM2-MLX-bf16
int8	MLX QuantizedLinear, group size 64	~3.0 GB	aufklarer/VoxCPM2-MLX-int8

回采 ASR（Qwen3-ASR 0.6B，8 句测试集，M 系列 Apple Silicon）：

版本	WER	RTF
bf16	2.04 %	1.38
int8	0.00 %	1.02
int4 (已停用)	4.08 %	0.83

CLI 默认使用 bf16；需要更小的下载体积时可选择 int8。int4 已停用，表格仅保留其历史测量结果。

快速开始

import VoxCPM2TTS

let tts = try await VoxCPM2TTSModel.fromPretrained()  // defaults to bf16
let audio = try await tts.generate(text: "Hello from VoxCPM2.", language: "english")
// audio: [Float] at 48 kHz mono

显式选择 int8 模型包：

let tts = try await VoxCPM2TTSModel.fromPretrained(
    modelId: "aufklarer/VoxCPM2-MLX-int8"
)

声音设计（指令驱动）

传入一段自然语言风格描述，模型即可无需参考音频按描述合成：

let audio = try await tts.generateVoxCPM2(
    text: "Welcome to the show.",
    instruct: "A young woman, gentle and warm voice."
)

声音克隆

从 16 kHz 单声道参考音频做单次克隆：

let ref = try AudioFileLoader.load(url: URL(fileURLWithPath: "speaker.wav"),
                                   targetSampleRate: 16000)
let audio = try await tts.generateVoxCPM2(
    text: "This is a cloned voice.",
    refAudio: ref
)

Ultimate cloning — 同时传入参考音频和与之匹配的转写文本，LM 还会条件于词汇上下文，更好地保留韵律和口音：

let audio = try await tts.generateVoxCPM2(
    text: "Hello from the cloned voice.",
    refAudio: ref,
    promptText: "this is what the reference clip actually said",
    promptAudio: ref
)

CLI

speech speak "Hello there." \
    --engine voxcpm2 \
    --voxcpm2-variant int8 \
    --output hello.wav

# Voice design
speech speak "Welcome to the show." \
    --engine voxcpm2 \
    --voxcpm2-instruct "A young woman, gentle and warm voice." \
    --output design.wav

# Voice cloning
speech speak "This is a cloned voice." \
    --engine voxcpm2 \
    --voice-sample speaker.wav \
    --output clone.wav

可用标志：--voxcpm2-variant {bf16,int8}、--voxcpm2-instruct、--voxcpm2-ref-audio、--voxcpm2-prompt-audio + --voxcpm2-prompt-text、--voxcpm2-cfg-value、--voxcpm2-timesteps、--voxcpm2-max-tokens、--voxcpm2-min-tokens、--seed（可复现的合成）。

VoxCPM2 与 Qwen3-TTS 对比

已发布的英语结果：每个模型使用十组 FLEURS 参考与目标音频对，报告 WER 和 UTMOS 均值及 RTF 中位数。WER 与 RTF 越低越好；UTMOS 是自然度预测值，不是人工评分。这些结果不代表通用排名。

模型	WER ↓	RTF ↓	UTMOS ↑
VoxCPM2 bf16	1.8%	1.11	2.97
Qwen3-TTS Base 1.7B bf16 ICL	2.4%	1.70	3.50

完整五语言语音克隆对比与方法.

在 speech-swift TTS 模块中如何选择

	Kokoro-82M	Qwen3-TTS	CosyVoice3	VoxCPM2	VibeVoice 1.5B
参数量	82M	0.6 / 1.7 B	0.5B	2B	1.5B
采样率	24 kHz	24 kHz	24 kHz	48 kHz	24 kHz
后端	CoreML (ANE)	MLX, CoreML	MLX	MLX	MLX
语言数	10	10	9	30	EN + ZH
声音设计	固定音色	—	—	指令驱动	—
声音克隆	—	ICL 参考	零样本参考	参考 + ultimate	音频 + 转写
长文本	短 / 中等	流式	流式	Patch 流式	最长 90 分钟

什么时候选 VoxCPM2

需要 48 kHz 输出（音乐 / 广播）或无需参考音频的自然语言声音设计时。如果需要最高质量的英语短文本 TTS 且包体更小，CosyVoice3 或 Qwen3-TTS 更轻量；如果是英 / 中长篇播客或有声书，VibeVoice 1.5B 才是为此而生。

负责任使用

本模型包含声音克隆能力。请在克隆任何人声前取得本人同意，不要用模型冒充他人、生成假信息或实施欺诈。完整安全准则请参考 openbmb/VoxCPM2。