¿Qué hace VoxCPM Text-to-Speech?
Sintetiza voz a partir de texto en chino/inglés/multilingüe usando OpenBMB VoxCPM. Dos niveles de modelo, tres modos de entrada, treinta idiomas, nueve dialectos chinos. Con licencia Apache-2.0.
Verificado 2026-07-04: voxcpm 2.0.3 en PyPI, el grafo de dependencias se resuelve limpiamente (torch ≥ 2.5, transformers ≥ 4.36, gradio 6.x). PyPI accesible. Los pesos del modelo se alojan en Hugging Face (openbmb/VoxCPM2, openbmb/VoxCPM-0.5B).
Este entorno (sandbox de QoderWork) no tiene GPU y no puede acceder a huggingface.co directamente — la generación de audio no se prueba aquí. Despliega en una máquina con CUDA / Apple Silicon / un mirror de HF para sintetizar realmente.
Prerrequisitos
| Componente | Requisito |
|---|---|
| Python | ≥ 3.10, < 3.13 (probado oficialmente) |
| PyTorch | ≥ 2.5.0 |
| CUDA | ≥ 12.0 (recomendado); MPS o CPU también funcionan (más lentos) |
| VRAM de GPU | 5 GB para VoxCPM-0.5B, 8 GB para VoxCPM2 (2B) |
| Disco | ~2 GB por modelo (los pesos se descargan automáticamente de HF) |
| Red | Acceso a huggingface.co (o configura HF_ENDPOINT con un mirror) |
Instalación:
pip install voxcpm
Para despliegues en China donde HF es lento, usa el mirror de ModelScope:
export HF_ENDPOINT=https://hf-mirror.com
# o usa ModelScope directamente:
pip install modelscope
Inicio rápido
CLI (el más sencillo)
# Síntesis básica a WAV
voxcpm design --text "你好,欢迎收听三分钟 AI 快报。" --output greeting.wav
# Con descripción en lenguaje natural del estilo de voz
voxcpm design --text "(年轻女声,温柔甜美) 今天天气真好,我们来聊聊 AI。" --output warm.wav
# Inglés
voxcpm design --text "Welcome to today's AI briefing." --output en.wav
# Lote
voxcpm batch --input-file lines.txt --output-dir out/
SDK de Python (programático)
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, # fuerza de guía libre de clasificador (mayor = más expresivo)
inference_timesteps=10, # pasos de difusión (más = mejor calidad, más lento)
seed=42 # reproducibilidad
)
sf.write("demo.wav", wav, model.tts_model.sample_rate) # salida a 24 kHz
Síntesis en streaming (para texto largo)
for chunk in model.generate_streaming(text="很长的一段文本..."):
# chunk es np.ndarray de muestras PCM
process(chunk)
Modos de entrada
1. Diseño (control de voz por lenguaje natural)
Envuelve la descripción de la voz entre () al inicio del texto:
"(年轻女声,语气甜美,稍快语速) 今天要给大家介绍一款有意思的 AI 工具。"
"(中年男声,稳重、专业) 欢迎收听本期节目。"
"(带四川口音的女生,轻松) 这个咋回事嘛!"
Señales disponibles (componibles):
- Tipo de voz: 男声 / 女声 / 童声 / 老年男声 / 中年女声 ...
- Tono: 温柔 / 严肃 / 兴奋 / 平静 / 忧郁 / 慵懒 ...
- Ritmo: 快语速 / 慢语速 / 稍快 / 稍慢
- Estilo: 播音腔 / 口语化 / 说书人 / 儿童剧 / 广告腔
- Dialecto: 四川话 / 粤语 / 吴语 / 东北话 / 河南话 / 陕西话 / 山东话 / 天津话 / 闽南话
2. Clonación de voz (zero-shot)
Proporciona un audio de referencia de 3-30 segundos y su transcripción:
wav = model.generate(
text="要合成的新文本。",
prompt_wav_path="reference.wav",
prompt_text="参考音频对应的原文(准确抄写)"
)
La voz generada coincide con el hablante de referencia.
3. Combinado (clonación + ajuste de estilo)
wav = model.generate(
text="(稍快,兴奋) 要合成的新文本。",
reference_wav_path="reference.wav" # forma más suave de clonación; conserva el timbre pero el estilo se sobreescribe
)
Flujos de trabajo comunes
De extremo a extremo: guión → audio
Combínalo con podcast-scriptwriter. Dado un guión:
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", # o usa "(年轻女声,语气理性犀利)" como prefijo
'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))) # pausa de 0.4 s
full = np.concatenate(segments)
sf.write('episode.wav', full, model.tts_model.sample_rate)
Podcast multilingüe
Alimenta el mismo guión traducido a en/ja/ko/fr; VoxCPM detecta el idioma automáticamente por línea. Mantén el mismo audio de referencia para preservar la identidad del presentador entre idiomas.
Servicio vLLM de alto rendimiento
Para volumen, usa el servidor Omni compatible con OpenAI de vLLM:
vllm serve openbmb/VoxCPM2 --omni --port 8000
Luego llama a /v1/audio/speech como en OpenAI TTS.
Respaldo: edge-tts (sin GPU)
Si VoxCPM no es posible en el entorno (sin GPU, HF bloqueado, tiempo ajustado), recurre a Microsoft Edge TTS (gratuito, sin clave API, más de 400 voces):
pip install edge-tts
edge-tts --voice zh-CN-XiaoxiaoNeural --text "你好世界" --write-media hello.mp3
Compensaciones: sin clonación de voz, grupo de voces fijo, dependiente de red, no es de código abierto. Solución temporal aceptable.
Limitaciones
- GPU muy recomendada — la CPU funciona pero es ~10-50× más lenta.
- La primera descarga es de ~2 GB desde HF; usa
HF_ENDPOINTpara un mirror si es lento. - CUDA 12+ requiere controladores recientes — los controladores antiguos pueden necesitar una compilación para CUDA 11; verifica
torch.cuda.is_available(). - Texto largo (> 2 min): usa
generate_streamingy une fragmentos;generatepuro puede alcanzar el límite de VRAM. - Clonación solo en inglés: funciona pero la calidad de la muestra es ligeramente inferior a la nativa china.
- Los dialectos requieren formato de prefijo —
(粤语) 早晨。no粤语:早晨。. - No hay salida de sincronización a nivel de palabra — para karaoke usa un alineamiento STT tipo whisper en el WAV producido.
- La frecuencia de muestreo es fija a 24 kHz — remuestrea aguas abajo si es necesario.
- Python 3.13+ no probado — quédate en 3.10-3.12.
Modos de fallo
| Síntoma | Causa | Acción |
|---|---|---|
torch.cuda.OutOfMemoryError | Modelo demasiado grande para la GPU | Cambia a openbmb/VoxCPM-0.5B, o usa CPU |
| La descarga del modelo se detiene | Conectividad de HF | Configura HF_ENDPOINT=https://hf-mirror.com |
| Voz robótica / metálica | cfg_value demasiado alto | Prueba 1.5-2.5; el punto óptimo es 2.0 |
| La clonación de voz no coincide | Referencia demasiado corta/ruidosa | Usa una muestra limpia de 5-15 s; habilita load_denoiser=True |
| El idioma se detectó incorrectamente | Texto mezclado | Divide por idioma, genera por segmento |
CLI voxcpm: command not found | No está en el PATH del entorno virtual | pip install voxcpm en el entorno activo; o python -m voxcpm ... |
Referencias
- Repositorio: https://github.com/OpenBMB/VoxCPM ⭐ 32.4k
- Documentos: https://voxcpm.readthedocs.io/
- Modelo HF: https://huggingface.co/openbmb/VoxCPM2 (2B) o https://huggingface.co/openbmb/VoxCPM-0.5B (pequeño)
- Demo: https://openbmb.github.io/VoxCPM-demopage/
- Licencia: Apache-2.0
- Respaldo: Microsoft Edge TTS (
pip install edge-tts) — sin clave API, sin clonación