VoxCPM Text-to-Speech
Synthetisiert Sprache aus chinesischen/englischen/mehrsprachigen Texten mit OpenBMBs VoxCPM. Zwei Modellstufen, drei Eingabemodi, dreißig Sprachen, neun chinesische Dialekte. Lizenz: Apache-2.0.
Überprüft am 04.07.2026: voxcpm 2.0.3 auf PyPI, Abhängigkeitsgraph löst sauber auf (torch ≥ 2.5, transformers ≥ 4.36, gradio 6.x). PyPI erreichbar. Modellgewichte werden auf Hugging Face gehostet (openbmb/VoxCPM2, openbmb/VoxCPM-0.5B).
Diese Umgebung (QoderWork-Sandbox) hat keine GPU und kann huggingface.co nicht direkt erreichen — Audio-Generierung wird hier nicht ausgeführt. Setzen Sie auf einem Rechner mit CUDA/Apple Silicon/HF-Mirror ein, um tatsächlich zu synthetisieren.
Voraussetzungen
| Komponente | Anforderung |
|---|---|
| Python | ≥ 3.10, < 3.13 (offiziell getestet) |
| PyTorch | ≥ 2.5.0 |
| CUDA | ≥ 12.0 (empfohlen); MPS oder CPU funktionieren auch (langsamer) |
| GPU VRAM | 5 GB für VoxCPM-0.5B, 8 GB für VoxCPM2 (2B) |
| Festplatte | ~2 GB pro Modell (Gewichte werden automatisch von HF heruntergeladen) |
| Netzwerk | Zugriff auf huggingface.co (oder HF_ENDPOINT auf einen Mirror setzen) |
Installation:
pip install voxcpm
Für Bereitstellungen in China, bei denen HF langsam ist, ModelScope-Mirror verwenden:
export HF_ENDPOINT=https://hf-mirror.com
# oder ModelScope direkt verwenden:
pip install modelscope
Schnellstart
CLI (am einfachsten)
# Einfache Synthese nach WAV
voxcpm design --text "你好,欢迎收听三分钟 AI 快报。" --output greeting.wav
# Mit natürlichsprachlicher Stimmstilbeschreibung
voxcpm design --text "(年轻女声,温柔甜美) 今天天气真好,我们来聊聊 AI。" --output warm.wav
# Englisch
voxcpm design --text "Welcome to today's AI briefing." --output en.wav
# Batch
voxcpm batch --input-file lines.txt --output-dir out/
Python SDK (programmatisch)
from voxcpm import VoxCPM
import soundfile as sf
model = VoxCPM.from_pretrained("openbmb/VoxCPM2", load_denoiser=False)
wav = model.generate(
text="你好,这是一段测试语音。",
cfg_value=2.0, # classifier-free guidance strength (höher = ausdrucksstärker)
inference_timesteps=10, # Diffusionsschritte (mehr = bessere Qualität, langsamer)
seed=42 # Reproduzierbarkeit
)
sf.write("demo.wav", wav, model.tts_model.sample_rate) # 24 kHz Ausgabe
Streaming-Synthese (für lange Texte)
for chunk in model.generate_streaming(text="很长的一段文本..."):
# chunk ist ein np.ndarray von PCM-Samples
process(chunk)
Eingabemodi
1. Design (natürlichsprachliche Stimmsteuerung)
Stimmbeschreibung am Anfang des Textes in () setzen:
"(年轻女声,语气甜美,稍快语速) 今天要给大家介绍一款有意思的 AI 工具。"
"(中年男声,稳重、专业) 欢迎收听本期节目。"
"(带四川口音的女生,轻松) 这个咋回事嘛!"
Verfügbare Hinweise (kombinierbar):
- Stimmtyp: 男声 / 女声 / 童声 / 老年男声 / 中年女声 ...
- Ton: 温柔 / 严肃 / 兴奋 / 平静 / 忧郁 / 慵懒 ...
- Tempo: 快语速 / 慢语速 / 稍快 / 稍慢
- Stil: 播音腔 / 口语化 / 说书人 / 儿童剧 / 广告腔
- Dialekt: 四川话 / 粤语 / 吴语 / 东北话 / 河南话 / 陕西话 / 山东话 / 天津话 / 闽南话
2. Sprachklon (Zero-Shot)
Bereitstellen eines 3-30 Sekunden Referenzaudios + dessen Transkript:
wav = model.generate(
text="要合成的新文本。",
prompt_wav_path="reference.wav",
prompt_text="参考音频对应的原文(准确抄写)"
)
Die generierte Stimme entspricht dem Referenzsprecher.
3. Kombiniert (Klon + Stilanpassung)
wav = model.generate(
text="(稍快,兴奋) 要合成的新文本。",
reference_wav_path="reference.wav" # weichere Form des Klons; behält Klangfarbe, überschreibt Stil
)
Übliche Workflows
End-to-End: Skript → Audio
In Kombination mit podcast-scriptwriter. Bei einem Skript:
A(轻松):欢迎收听《三分钟 AI 快报》。
B(认真):本周动作不小。
import re
from voxcpm import VoxCPM
import soundfile as sf, numpy as np
model = VoxCPM.from_pretrained("openbmb/VoxCPM2", load_denoiser=False)
voices = {
'A': "reference_female.wav", # oder "(年轻女声,语气理性犀利)" als Präfix verwenden
'B': "reference_male.wav",
}
segments = []
for line in open('script.txt', encoding='utf-8'):
m = re.match(r'^([AB])(([^)]+)):(.+)$', line.strip())
if not m: continue
speaker, tone, text = m.groups()
styled = f"({tone}) {text}"
wav = model.generate(text=styled, prompt_wav_path=voices[speaker], cfg_value=2.0, inference_timesteps=10)
segments.append(wav)
segments.append(np.zeros(int(0.4 * model.tts_model.sample_rate))) # 0.4 s Pause
full = np.concatenate(segments)
sf.write('episode.wav', full, model.tts_model.sample_rate)
Mehrsprachiger Podcast
Das gleiche Skript in en/ja/ko/fr übersetzt einspeisen; VoxCPM erkennt die Sprache pro Zeile automatisch. Das gleiche Referenzaudio verwenden, um die Host-Identität über Sprachen hinweg zu bewahren.
High-Throughput vLLM Serving
Für größeres Volumen den OpenAI-kompatiblen vLLM Omni-Server verwenden:
vllm serve openbmb/VoxCPM2 --omni --port 8000
Dann /v1/audio/speech wie OpenAI TTS ansprechen.
Fallback: edge-tts (keine GPU)
Wenn VoxCPM in der Umgebung nicht möglich ist (keine GPU, HF blockiert, Zeitmangel), auf Microsoft Edge TTS zurückgreifen (kostenlos, kein API-Key, 400+ Stimmen):
pip install edge-tts
edge-tts --voice zh-CN-XiaoxiaoNeural --text "你好世界" --write-media hello.mp3
Nachteile: kein Sprachklon, fester Stimmvorrat, netzwerkabhängig, nicht Open Source. Akzeptable Übergangslösung.
Einschränkungen
- GPU dringend empfohlen — CPU funktioniert, aber ~10-50× langsamer.
- Erster Download ~2 GB von HF;
HF_ENDPOINTfür einen Mirror verwenden, falls langsam. - CUDA 12+ erfordert aktuellen Treiber — ältere Treiber benötigen möglicherweise CUDA 11 Build;
torch.cuda.is_available()überprüfen. - Lange Texte (> 2 Min.):
generate_streamingverwenden und Chunks zusammensetzen; reinesgeneratekann VRAM-Grenze erreichen. - Englischsprachiger Klon: funktioniert, aber Sample-Qualität etwas geringer als chinesischsprachig.
- Dialekte erfordern Präfix-Format —
(粤语) 早晨。nicht粤语:早晨。. - Keine Wort-für-Wort-Zeitausgabe — für Karaoke whisper-ähnliche STT-Ausrichtung auf dem produzierten WAV verwenden.
- Abtastrate ist fest bei 24 kHz — bei Bedarf nachträglich resamplen.
- Python 3.13+ nicht getestet — auf 3.10-3.12 festlegen.
Fehlermodi
| Symptom | Ursache | Aktion |
|---|---|---|
torch.cuda.OutOfMemoryError | Modell zu groß für GPU | Auf openbmb/VoxCPM-0.5B wechseln oder CPU verwenden |
| Model-Download stockt | HF-Konnektivität | HF_ENDPOINT=https://hf-mirror.com setzen |
| Roboter-/Metallstimme | cfg_value zu hoch | 1.5-2.5 versuchen; Sweet Spot ist 2.0 |
| Sprachklon passt nicht | Referenz zu kurz/verrauscht | 5-15 s sauberes Sample verwenden; load_denoiser=True aktivieren |
| Sprache falsch automatisch erkannt | Text gemischt | Nach Sprache aufteilen, pro Segment generieren |
CLI voxcpm: command not found | Nicht im venv-PATH | pip install voxcpm in der aktiven Umgebung; oder python -m voxcpm ... |
Referenzen
- Repository: https://github.com/OpenBMB/VoxCPM ⭐ 32.4k
- Dokumentation: https://voxcpm.readthedocs.io/
- HF-Modell: https://huggingface.co/openbmb/VoxCPM2 (2B) oder https://huggingface.co/openbmb/VoxCPM-0.5B (klein)
- Demo: https://openbmb.github.io/VoxCPM-demopage/
- Lizenz: Apache-2.0
- Fallback: Microsoft Edge TTS (
pip install edge-tts) — kein API-Key, kein Klon