使用指南

本页说明 VoxCPM 2 的生成参数与三种生成模式，并更细地介绍文本输入、参考音频、质量调优与流式输出。

生成参数

generate() 方法接受以下主要参数：

参数

默认值

说明

text

（必填）

待合成文本。支持 VoxCPM 2 提供的 30 种语言。

reference_wav_path

None

声音克隆用的参考音频（仅 VoxCPM 2）。模型提取音色，无需转写文本。

prompt_wav_path

None

延续式克隆的 prompt 音频，必须与 prompt_text 配对。

prompt_text

None

prompt_wav_path 的逐字转写，须与其同时提供。

cfg_value

2.0

引导强度。越高越严格遵循条件；越低变化越大。常用范围：1.0–3.0。

inference_timesteps

10

扩散步数。步数越多细节与自然度越好，速度越慢。建议：4–30。

normalize

False

进行文本规范化以展开数字、日期等，适合原始文本输入。

denoise

False

生成前对 prompt/参考音频降噪。参考音频较吵时更有用。

retry_badcase

True

当生成音频相对文本异常偏短或偏长时自动重试。

三种生成模式

VoxCPM 2 支持三种模式，取决于你想对输出声音控制到什么程度。

声音设定

无需参考音频。在正文前加控制指令描述想要的音色，VoxCPM 会从零生成新声音。

from voxcpm import VoxCPM
import soundfile as sf

model = VoxCPM.from_pretrained("openbmb/VoxCPM2", load_denoiser=False)

wav = model.generate(
    text="(A young woman, gentle and sweet voice)Hello, welcome to VoxCPM!",
    cfg_value=2.0,
    inference_timesteps=10,
)
sf.write("voice_design.wav", wav, model.tts_model.sample_rate)

控制指令写在目标文本前的括号里，例如 (年轻女性，温柔甜美) 或 (an excited young man)。指令中中英文均可。

可控声音克隆

上传参考音频，模型克隆音色；你仍可用控制指令调节语速、情绪或风格。

wav = model.generate(
    text="(slightly faster, cheerful tone)This is a cloned voice with style control.",
    reference_wav_path="speaker.wav",
    cfg_value=2.0,
    inference_timesteps=10,
)
sf.write("controllable_clone.wav", wav, model.tts_model.sample_rate)

此模式下，reference_wav_path 提供音色，括号内指令控制风格；无需参考音频转写。

高保真克隆

追求最高相似度时，请同时提供参考音频及其逐字转写。模型用转写精确对齐 prompt 音频，克隆保真度最高。

wav = model.generate(
    text="This is a high-fidelity cloned voice.",
    prompt_wav_path="speaker.wav",
    prompt_text="The exact transcript of speaker.wav goes here.",
    reference_wav_path="speaker.wav",
    cfg_value=2.0,
    inference_timesteps=10,
)
sf.write("hifi_clone.wav", wav, model.tts_model.sample_rate)

小技巧

转写建议用 ASR 获取，不必手打。网页演示会通过 SenseVoice 自动完成。启用 Hi-Fi 模式时，控制指令会被忽略。

文本输入

普通文本与音素输入

多数情况用**普通文本**。若希望 VoxCPM 自动展开数字、日期等格式，请保持 normalize=True。

仅在需要更细粒度发音控制时使用**音素输入**，此时应关闭文本规范化：

wav = model.generate(
    text="{ni3}{hao3}{shi4}{jie4}",
    normalize=False,
)

  • 中文： 使用带声调数字的拼音，例如 {ni3}{hao3}

  • 英文： 使用 CMUDict 式音素，例如 {HH AH0 L OW1}

文本规范化

若数字被逐位朗读，请启用文本规范化：

wav = model.generate(
    text="总建筑面积为5640平方米",
    normalize=True,
)

备注

文本规范化未必覆盖所有边角情况。例如部分模型名、商品名可能需要人工预处理。

标点与停顿

VoxCPM 将标点作为韵律提示：

  • 句号、问号通常带来更清晰的句末停顿

  • 逗号通常带来较短停顿

  • 省略号可产生迟疑或拖尾感

若需要更强停顿，把文本拆成更短句，而不要只依赖标点。

短文本

极短输入如 "Hello" 或 "好的" 可能听起来偏弱，因训练时最短音频约一秒。实践中，自然能产出数秒语音的输入更稳定。

方言建议

要生成某种方言，请用该方言自身的词汇与说法写目标文本，不要用标准普通话硬写：

  • 粤语：(广东话，中年男性)伙計，唔該一個A餐，凍奶茶少甜！ ✅

  • 粤语：(广东话，中年男性)伙计，麻烦来一个A餐，冻奶茶少甜！ ❌（标准普通话）

若不确定如何写地道方言，可先用 DeepSeek、豆包等 LLM 从普通话转写。

参考音频

音频质量

  • 时长： 5–30 秒较为实用

  • 格式： torchaudio 支持的任意格式，含 WAV、FLAC、MP3

  • 音质： 越干净通常越利于保留音色

  • 语言： VoxCPM 2 支持 30 种语言

没有参考音频时

不提供参考音频时，VoxCPM 每次会随机一种声音。模型仍可从文本推断合适说话风格，但音色在多次调用间不会一致。

如何保持声音一致

  1. 每次复用同一段参考音频。

  2. 在 Voice Cloning 模式下使用 reference_wav_path 以稳定音色。

  3. 若需生产级一致性，可考虑 LoRA 微调。见 微调指南。

备注

VoxCPM 1.x 克隆需 prompt_wav_path + prompt_text，不支持 reference_wav_path。1.x 专用用法见 VoxCPM 1.5。

质量调优

CFG 参数

取值

效果

1.0–2.0

更松弛自然，但可能略微偏离目标文本

2.0

均衡默认

2.0–3.0

更贴文本，但在难例上更易出现噪声或瑕疵

若长音频输出发糊、发嗡，把 cfg_value 降到 1.5–1.6 附近往往更稳。

长文本

长文本最容易触发不稳定行为，包括：

  • 逐渐加速或嗡嗡声

  • KV cache 增长导致显存不足

  • 生成停不下来

实用做法是把长文切成较短段落，再拼接各段波形：

import numpy as np

segments = ["First paragraph...", "Second paragraph...", "Third paragraph..."]
all_wavs = []
for seg in segments:
    wav = model.generate(text=seg, reference_wav_path="voice.wav")
    all_wavs.append(wav)
full_wav = np.concatenate(all_wavs)

首尾伪影

若生成音频首尾有多余杂音：

  • VoxCPM 1.x： 检查 prompt_text 是否与参考音频完全一致——转写不匹配最常见

还可尝试：

  • 启用 retry_badcase=True

  • 降低 cfg_value

  • 必要时后处理裁切输出

import librosa
wav_trimmed, _ = librosa.effects.trim(wav)

降噪

denoise 改善的是 prompt 音频，不是生成结果本身：

  • 参考音频嘈杂时 denoise=True 有用

  • prompt 已很干净且想保留原声特征时，denoise=False 更合适

警告

降噪器在 16 kHz 流水线中运行，可能轻微改变声线。若克隆变差，可尝试关闭。

流式生成

VoxCPM 通过 generate_streaming() 支持流式音频。交互场景下，按句处理通常比对不断增长的一段文本流式生成更稳：

  1. 将输入文本按句切分。

  2. 对每句调用 generate_streaming()。

  3. 按顺序播放或缓冲各音频块。

import numpy as np
import soundfile as sf

chunks = []
for chunk in model.generate_streaming(
    text="Streaming text to speech is easy with VoxCPM!",
):
    chunks.append(chunk)
wav = np.concatenate(chunks)
sf.write("streaming.wav", wav, model.tts_model.sample_rate)

文本逐 token 到达且同步生成音频的双向流式目前不支持。

What's Next?