Communitygithub.com

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.

¿Qué es VoxCPM Text-to-Speech?

Esta habilidad de agente de IA proporciona un motor de síntesis de voz de última generación basado en OpenBMB VoxCPM, ideal para agentes de IA que necesitan generar locuciones naturales en chino, inglés u otros idiomas, incluyendo dialectos chinos. Soporta tres modos de entrada: control por lenguaje natural (descripción de la voz), clonación de voz zero-shot (con una muestra de referencia de 3-30 segundos) y una combinación de ambos. Es útil en flujos de trabajo como producción de podcasts, locución para videos, asistentes de voz multilingües y generación de contenido accesible. Se integra bien con herramientas de operador como QoderWork o PilotDeck, pero requiere GPU (preferiblemente con CUDA 12+ y 5-8 GB de VRAM) para un rendimiento óptimo. Se despliega como CLI, Python SDK o servidor compatible con OpenAI mediante vLLM. Incluye un respaldo con edge-tts, gratuito y sin clave API, útil en entornos sin GPU.

Compatible con~Claude Code✓Codex CLI~Cursor
npx skills add AaronAust1n/china-productivity-skills

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

¿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

ComponenteRequisito
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 GPU5 GB para VoxCPM-0.5B, 8 GB para VoxCPM2 (2B)
Disco~2 GB por modelo (los pesos se descargan automáticamente de HF)
RedAcceso 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_ENDPOINT para 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_streaming y une fragmentos; generate puro 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íntomaCausaAcción
torch.cuda.OutOfMemoryErrorModelo demasiado grande para la GPUCambia a openbmb/VoxCPM-0.5B, o usa CPU
La descarga del modelo se detieneConectividad de HFConfigura HF_ENDPOINT=https://hf-mirror.com
Voz robótica / metálicacfg_value demasiado altoPrueba 1.5-2.5; el punto óptimo es 2.0
La clonación de voz no coincideReferencia demasiado corta/ruidosaUsa una muestra limpia de 5-15 s; habilita load_denoiser=True
El idioma se detectó incorrectamenteTexto mezcladoDivide por idioma, genera por segmento
CLI voxcpm: command not foundNo está en el PATH del entorno virtualpip install voxcpm en el entorno activo; o python -m voxcpm ...

Referencias

Skills relacionados