Communitygithub.com

VoxCPM Text-to-Speech

Sintetiza 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.

O que é VoxCPM Text-to-Speech?

Esta habilidade capacita agentes de IA a sintetizar fala natural a partir de texto usando o modelo VoxCPM da OpenBMB, suportando 30 idiomas e 9 dialetos chineses. Ela oferece três modos de entrada: controle por descrição em linguagem natural (design), clonagem de voz zero-shot e uma combinação de ambos, permitindo desde narrações simples até podcasts multi-personagem. Os modelos estão disponíveis em dois tamanhos (0,5B e 2B) e podem ser usados via CLI, SDK Python ou servidor vLLM compatível com OpenAI, sendo ideal para produção de conteúdo em chinês, pesquisa de IA e automação de mídia. A habilidade também inclui um fallback prático com o Microsoft Edge TTS para ambientes sem GPU. É particularmente útil no ecossistema PilotDeck, preenchendo a lacuna de habilidades para produção de conteúdo em chinês e recuperação de dados da internet chinesa.

Funciona com~Claude Code✓Codex CLI~Cursor
npx skills add AaronAust1n/china-productivity-skills

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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

ComponenteRequisito
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 GPU5 GB para VoxCPM-0.5B, 8 GB para VoxCPM2 (2B)
Disco~2 GB por modelo (pesos baixados automaticamente do HF)
RedeAcesso 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_ENDPOINT para 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_streaming e una os chunks; o generate puro 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ão Cantonê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

SintomaCausaAção
torch.cuda.OutOfMemoryErrorModelo grande demais para a GPUMude para openbmb/VoxCPM-0.5B ou use CPU
Download do modelo travaConectividade HFConfigure HF_ENDPOINT=https://hf-mirror.com
Voz robótica / metálicacfg_value muito altoTente 1.5-2.5; ponto ideal é 2.0
Clonagem de voz não correspondeReferência muito curta/ruidosaUse amostra limpa de 5-15 s; ative load_denoiser=True
Idioma detectado erradoTexto misturadoSepare por idioma, gere por segmento
CLI voxcpm: comando não encontradoNão no PATH do venvpip install voxcpm no ambiente ativo; ou python -m voxcpm ...

Referências

Habilidades Relacionadas