VoxCPM Text-to-Speech (Conversão de Texto em Fala)
Sintetize fala a partir de texto em chinês/inglês/multilíngue usando o VoxCPM da OpenBMB. Dois níveis de modelo, três modos de entrada, trinta idiomas, nove dialetos chineses. Licenciado sob Apache-2.0.
Verificado em 2026-07-04: voxcpm 2.0.3 no PyPI, grafo de dependências resolvido corretamente (torch ≥ 2.5, transformers ≥ 4.36, gradio 6.x). PyPI acessível. Pesos dos modelos hospedados no Hugging Face (openbmb/VoxCPM2, openbmb/VoxCPM-0.5B).
Este ambiente (sandbox QoderWork) não possui GPU e não consegue acessar huggingface.co diretamente — a geração de áudio não é exercitada aqui. Implante em uma máquina com CUDA / Apple Silicon / um mirror HF para realmente sintetizar.
Pré-requisitos
| Componente | Requisito |
|---|---|
| Python | ≥ 3.10, < 3.13 (testado oficialmente) |
| PyTorch | ≥ 2.5.0 |
| CUDA | ≥ 12.0 (recomendado); MPS ou CPU também funcionam (mais lentos) |
| VRAM da GPU | 5 GB para VoxCPM-0.5B, 8 GB para VoxCPM2 (2B) |
| Disco | ~2 GB por modelo (pesos baixados automaticamente do HF) |
| Rede | Acesso a huggingface.co (ou configure HF_ENDPOINT para um mirror) |
Instalação:
pip install voxcpm
Para implantações na China onde o HF é lento, use o mirror ModelScope:
export HF_ENDPOINT=https://hf-mirror.com
# ou use o ModelScope diretamente:
pip install modelscope
Início Rápido
CLI (mais simples)
# Síntese básica para WAV
voxcpm design --text "你好,欢迎收听三分钟 AI 快报。" --output saudacao.wav
# Com descrição em linguagem natural do estilo de voz
voxcpm design --text "(voz feminina jovem, doce e suave) Hoje está um dia lindo, vamos falar sobre IA." --output calorosa.wav
# Inglês
voxcpm design --text "Welcome to today's AI briefing." --output en.wav
# Lote
voxcpm batch --input-file linhas.txt --output-dir out/
SDK Python (programático)
from voxcpm import VoxCPM
import soundfile as sf
model = VoxCPM.from_pretrained("openbmb/VoxCPM2", load_denoiser=False)
wav = model.generate(
text="Olá, este é um teste de fala.",
cfg_value=2.0, # força da orientação livre de classificador (maior = mais expressivo)
inference_timesteps=10, # passos de difusão (mais = melhor qualidade, mais lento)
seed=42 # reprodutibilidade
)
sf.write("demo.wav", wav, model.tts_model.sample_rate) # saída de 24 kHz
Síntese em streaming (para textos longos)
for chunk in model.generate_streaming(text="Um texto muito longo..."):
# chunk é np.ndarray de amostras PCM
processar(chunk)
Modos de Entrada
1. Design (controle de voz por linguagem natural)
Coloque a descrição da voz entre () no início do texto:
"(voz feminina jovem, tom doce, ritmo ligeiramente rápido) Hoje vou apresentar uma ferramenta de IA interessante."
"(voz masculina de meia-idade, estável, profissional) Bem-vindo ao programa de hoje."
"(voz feminina com sotaque de Sichuan, descontraída) O que é isso?!"
Dicas disponíveis (combináveis):
- Tipo de voz: masculina / feminina / infantil / masculina idosa / feminina meia-idade ...
- Tom: suave / sério / animado / calmo / melancólico / preguiçoso ...
- Ritmo: rápido / lento / ligeiramente rápido / ligeiramente lento
- Estilo: locução / coloquial / contador de histórias / teatro infantil / propaganda
- Dialeto: Sichuanês / Cantonês / Wu / Nordestino / Henanês / Shaanxi / Shandong / Tianjin / Hokkien
2. Clonagem de voz (zero-shot)
Forneça um áudio de referência de 3 a 30 segundos + sua transcrição:
wav = model.generate(
text="Novo texto a ser sintetizado.",
prompt_wav_path="referencia.wav",
prompt_text="Texto original do áudio de referência (transcrição exata)"
)
A voz gerada corresponde ao locutor de referência.
3. Combinado (clonagem + ajuste de estilo)
wav = model.generate(
text="(ligeiramente rápido, animado) Novo texto a ser sintetizado.",
reference_wav_path="referencia.wav" # forma mais suave de clonagem; mantém o timbre, mas o estilo se sobrepõe
)
Fluxos de Trabalho Comuns
Ponta a ponta: roteiro → áudio
Combine com podcast-scriptwriter. Dado um roteiro:
A (descontraído): Bem-vindos ao Boletim de IA de 3 Minutos.
B (sério): Muita ação esta semana.
import re
from voxcpm import VoxCPM
import soundfile as sf, numpy as np
model = VoxCPM.from_pretrained("openbmb/VoxCPM2", load_denoiser=False)
vozes = {
'A': "referencia_feminina.wav", # ou use "(voz feminina jovem, tom racional e afiado)" como prefixo
'B': "referencia_masculina.wav",
}
segmentos = []
for linha in open('roteiro.txt', encoding='utf-8'):
m = re.match(r'^([AB])(([^)]+)):(.+)$', linha.strip())
if not m: continue
locutor, tom, texto = m.groups()
estilizado = f"({tom}) {texto}"
wav = model.generate(text=estilizado, prompt_wav_path=vozes[locutor], cfg_value=2.0, inference_timesteps=10)
segmentos.append(wav)
segmentos.append(np.zeros(int(0.4 * model.tts_model.sample_rate))) # pausa de 0,4s
completo = np.concatenate(segmentos)
sf.write('episodio.wav', completo, model.tts_model.sample_rate)
Podcast multilíngue
Alimente o mesmo roteiro traduzido para en/ja/ko/fr; o VoxCPM detecta automaticamente o idioma por linha. Mantenha o mesmo áudio de referência para preservar a identidade do apresentador entre os idiomas.
Serviço vLLM de alto rendimento
Para volume, use o servidor vLLM Omni compatível com OpenAI:
vllm serve openbmb/VoxCPM2 --omni --port 8000
Em seguida, acesse /v1/audio/speech como o TTS da OpenAI.
Fallback: edge-tts (sem GPU)
Se o VoxCPM for impossível no ambiente (sem GPU, HF bloqueado, tempo curto), recorra ao Microsoft Edge TTS (gratuito, sem chave de API, 400+ vozes):
pip install edge-tts
edge-tts --voice pt-BR-FranciscaNeural --text "Olá mundo" --write-media ola.mp3
Compensações: sem clonagem de voz, pool de vozes fixo, dependente de rede, não é código aberto. Solução temporária aceitável.
Limitações
- GPU fortemente recomendada — CPU funciona, mas é ~10-50× mais lento.
- Primeira execução baixa ~2 GB do HF; use
HF_ENDPOINTpara um mirror se estiver lento. - CUDA 12+ requer driver recente — drivers mais antigos podem precisar da build CUDA 11; verifique
torch.cuda.is_available(). - Texto longo (> 2 min): use
generate_streaminge una os chunks; ogeneratepuro pode atingir o limite de VRAM. - Clonagem apenas em inglês: funciona, mas a qualidade da amostra é ligeiramente inferior à nativa em chinês.
- Dialetos exigem formato de prefixo —
(Cantonês) Bom dia.nãoCantonês: Bom dia.. - Sem saída de timing no nível da palavra — para karaokê, use alinhamento STT tipo whisper no WAV produzido.
- Taxa de amostragem fixa em 24 kHz — reamostre downstream se necessário.
- Python 3.13+ não testado — fixe em 3.10-3.12.
Modos de Falha
| Sintoma | Causa | Ação |
|---|---|---|
torch.cuda.OutOfMemoryError | Modelo grande demais para a GPU | Mude para openbmb/VoxCPM-0.5B ou use CPU |
| Download do modelo trava | Conectividade HF | Configure HF_ENDPOINT=https://hf-mirror.com |
| Voz robótica / metálica | cfg_value muito alto | Tente 1.5-2.5; ponto ideal é 2.0 |
| Clonagem de voz não corresponde | Referência muito curta/ruidosa | Use amostra limpa de 5-15 s; ative load_denoiser=True |
| Idioma detectado errado | Texto misturado | Separe por idioma, gere por segmento |
CLI voxcpm: comando não encontrado | Não no PATH do venv | pip install voxcpm no ambiente ativo; ou python -m voxcpm ... |
Referências
- Repositório: https://github.com/OpenBMB/VoxCPM ⭐ 32.4k
- Documentação: https://voxcpm.readthedocs.io/
- Modelo HF: https://huggingface.co/openbmb/VoxCPM2 (2B) ou https://huggingface.co/openbmb/VoxCPM-0.5B (pequeno)
- Demonstração: https://openbmb.github.io/VoxCPM-demopage/
- Licença: Apache-2.0
- Fallback: Microsoft Edge TTS (
pip install edge-tts) — sem chave de API, sem clonagem