O que vox-tts faz?
Um serviço TTS auto-hospedado em https://vox.delo.sh que encapsula o VoxCPM2 com um armazenamento de perfis de voz baseado em PostgreSQL e suporte a múltiplos mecanismos. Implantado em ~/code/voxxy (núcleo: compose.yml, mecanismos GPU: compose.engines.yml — ambos os contêineres de mecanismo devem estar ativos ou as clonagens degradam silenciosamente, veja abaixo).
Referência rápida
| Ação | Como |
|---|---|
| Síntese única (bytes WAV inline) | POST /synthesize { text, voice?, cfg?, steps? } → audio/wav |
| Síntese para entrega ao Telegram / navegador / HA / Discord | POST /synthesize-url → {audio_url, engine, duration_s, bytes} |
| Ferramenta MCP: bytes inline (WAV base64) | speak(text, voice?) |
| Ferramenta MCP: URL de entrega (OGG/Opus, pronto para Telegram) | speak_url(text, voice?) |
| Ferramenta MCP: listar vozes | list_voices_tool() |
| Listar vozes (HTTP) | GET /voices |
| Adicionar uma voz | POST /voices (multipart: name, display_name, audio) |
| Clonagem interativa de voz (usuário diz "clone minha voz como…") | Veja Fluxo de trabalho de clonagem interativa de voz abaixo |
| Atualizar um mecanismo (VoxCPM / VibeVoice) | Veja Fluxo de trabalho de atualização de mecanismo abaixo |
| Falar a partir de um agente Hermes | tts.provider: vox nativo (base da frota); a frota NÃO carrega o MCP vox |
| Falar a partir de um shell / qualquer agente com terminal | voxxy speak "texto" (veja voxxy speak --help) |
| Registrar com um cliente MCP que não tem caminho vox nativo | Servidor MCP em https://vox.delo.sh/mcp/ (barra final obrigatória) |
| Node-RED | node-red-contrib-vox em ~/docker/stacks/utils/vox/node-red-contrib-vox/ |
| Saúde + status do mecanismo | GET /healthz |
A barra final em /mcp/ é obrigatória. Sem ela, o FastAPI faz um redirecionamento 307 e o HTTPX descarta o corpo da requisição POST.
speak vs speak_url: escolha o correto
| Se o áudio for... | Use | Porquê |
|---|---|---|
| Enviado para Telegram / Discord / Slack | speak_url | APIs de canal aceitam uma URL; seus servidores a buscam. Zero inchaço de bytes no fio do agente. |
Canalizado para uma tag <audio> do navegador | speak_url | Navegadores transmitem URLs; sem ida e volta base64. |
Entregue ao media_player.play_media do Home Assistant | speak_url | HA quer uma URL para media_content_id. |
| Processado inline pelo agente (dividir, analisar, loop) | speak | Bytes já estão locais; uma busca de URL adicionaria um salto. |
| Escrito em um arquivo local em um script shell | qualquer | speak_url + curl -o é mais fácil que base64 + base64 -d. |
Padrão para speak_url. Não custa tokens ao agente (a resposta é um JSON pequeno) e funciona em todas as superfícies de entrega, exceto processamento inline bruto de bytes.
Fallback de mecanismo
GET /healthz informa quais mecanismos estão registrados e se cada um está disponível:
{
"status": "ok",
"model_loaded": true,
"engines": [
{ "name": "voxcpm", "available": true },
{ "name": "elevenlabs", "available": true }
]
}
O orquestrador tenta em ordem. Toda resposta speak_url/speak inclui engine: "voxcpm" ou engine: "elevenlabs" para que você possa detectar quando o fallback foi acionado. ElevenLabs desativa automaticamente quando ELEVENLABS_API_KEY não está definida.
O mapeamento por voz do ElevenLabs reside na coluna voices.elevenlabs_voice_id. NULL faz fallback para o padrão global (ELEVENLABS_DEFAULT_VOICE, Adam por padrão).
Vozes clonadas são vinculadas ao mecanismo. Uma voz clonada via POST /voices armazena sua referência em vibevoice_ref_path e é servida primeiro pelo mecanismo vibevoice (roteamento preferred por requisição em app/engines.py; todo o resto segue a ordem VOX_ENGINES, voxcpm primeiro). Se o vibevoice estiver inativo, o voxcpm ainda recebe o clipe de referência — app/voices.py:46-48 faz fallback para wav_path para qualquer mecanismo sem substituição específica — então o clone degrada, não é apagado. O sintoma é uma leitura reconhecível, mas estranha, não um estranho. Correção: docker compose -f ~/code/voxxy/compose.engines.yml up -d voxxy-engine-vibevoice, depois confirme "name":"vibevoice","ready":true em /healthz.
Aquele que substitui a voz completamente é o fallback ElevenLabs: se ambos os mecanismos GPU estiverem inativos e ELEVENLABS_API_KEY estiver definida, vox responde 200 com a voz de um estranho, registrando vox: voice clone BYPASSED, e entrega mesmo assim. Verifique o campo engine em cada síntese de clone — vibevoice ou voxcpm é o clone, elevenlabs não é sua voz.
O orçamento de referência é de 10 segundos, não 30. Dois limites diferentes se acumulam, e apenas o segundo importa. POST /voices limita a ingestão a VOX_REF_AUDIO_MAX_SECONDS = 30s (compose.yml:16, aplicado em app/main.py:578-584, mantendo os primeiros 30s). Mas o contêiner vibevoice define a mesma variável como 10 (compose.engines.yml:69), e engines/vibevoice/engine/synth.py:183,208 recarrega a referência com duration=10.0. Seu /healthz diz isso diretamente: "max_ref_seconds": 10.0. Portanto, os segundos 10–30 de qualquer clipe de referência são armazenados, copiados e nunca vistos pelo modelo. Escreva passagens de clone para 8–10 segundos limpos e coloque a melhor e mais neutra fala primeiro — tudo depois é peso morto.
Procedimentos detalhados
Leia fluxos de trabalho de voz e integração para a implementação ou diagnóstico relevante. A clonagem de voz e a entrega externa exigem que o usuário solicite essas ações.
Folha de consulta rápida de padrões
| Parâmetro | Padrão | Notas |
|---|---|---|
cfg | 2.0 | Orientação livre de classificador; maior = mais fiel, menos variação |
steps | 10 | Etapas de difusão; 4-6 para velocidade, 15-20 para qualidade máxima |
normalize | false | Normalização de texto (números → palavras etc.) |
denoise | false | Campo morto. Declarado em app/main.py:98, não lido em lugar nenhum; POST /voices não tem parâmetro denoise. Limpe o áudio antes do upload. |
| TTL do cache (URLs de áudio) | 3600s | Env VOX_AUDIO_TTL_SECONDS; 1h é suficiente para Telegram |
| Voz de fallback (ElevenLabs) | Adam (pNInz6obpgDQGcFmaJgB) | Env ELEVENLABS_DEFAULT_VOICE |
A síntese roda a aproximadamente 21 caracteres por segundo em uma RTX 3090 com VOX_OPTIMIZE=1 — medido, não estimado: uma linha de 60 caracteres leva ~2s, uma linha de 1.665 caracteres leva ~35s. Orce pelo comprimento, não pelo título de 2s. A primeira chamada após uma reinicialização do contêiner adiciona ~15s (compilação JIT). A transcodificação OGG/Opus adiciona <100ms via ffmpeg.
Isso é importante para qualquer chamador com um tempo limite. O plugin TTS vox do Hermes codifica um tempo limite httpx de 60s (plugins/tts/vox/__init__.py:29,316) e ignora tts.vox.timeout, então um único bloco com mais de aproximadamente 2.500 caracteres falha completamente. Limite-o com tts.vox.max_text_length (lido em tools/tts_tool.py:436-441), que divide em blocos em vez de falhar.
Fluxo de trabalho de atualização de mecanismo
A topologia de três contêineres desacopla a orquestração central (voxxy-core, contêiner vox, apenas CPU) dos mecanismos auxiliares ligados à GPU (voxxy-engine-voxcpm, voxxy-engine-vibevoice). Cada contêiner de mecanismo mantém seus próprios pyproject.toml, uv.lock e Dockerfile em engines/<name>/.
Procedimento de atualização passo a passo
1. Descoberta de versão e auditoria de tempo de execução
- Lançamentos upstream: Verifique PyPI e lançamentos GitHub:
curl -s https://pypi.org/pypi/voxcpm/json | jq -r '.info.version' - Versão do contêiner em execução: Verifique a versão do pacote instalado via
importlib.metadata:(Nunca usedocker exec voxxy-engine-voxcpm /opt/venv/bin/python -c \ "import importlib.metadata; print(importlib.metadata.version('voxcpm'))"voxcpm.__version__; o módulo não o define e levantaAttributeError). - Pesos do modelo no Hugging Face: Verifique se o instantâneo dos pesos do modelo foi atualizado:
Atualizações de pacotes (código de inferência, decodificadores VAE de streaming, manipulação de dispositivo) são distintas das revisões dos pesos do modelo.cat ~/.cache/huggingface/hub/models--openbmb--VoxCPM2/refs/main curl -s https://huggingface.co/api/models/openbmb/VoxCPM2 | jq -r '.sha'
2. Atualização de dependências e atualização do arquivo de bloqueio
- Atualize o pino de versão em
engines/<name>/pyproject.toml(ex.:voxcpm==2.0.3). - Rebloqueie as dependências com uv:
cd engines/voxcpm && uv lock - Revise o diff (
git diff engines/voxcpm/uv.lock) para garantir que PyTorch e torchaudio permaneçam fixados no índice explícitopytorch-cu124e não derivem para wheels CPU do PyPI.
3. Reconstruir a imagem do contêiner do mecanismo
Reconstrua a imagem do mecanismo via compose:
docker compose -f compose.yml -f compose.engines.yml build voxxy-engine-voxcpm
# Ou via alias mise:
mise run build:voxcpm
O Dockerfile provisiona Python 3.12 via uv e executa uv sync --frozen --no-install-project em /opt/venv.
4. Recriar o contêiner do mecanismo com o perfil compose
Os contêineres do mecanismo são definidos com perfis compose em compose.engines.yml (profiles: ["voxcpm"] / profiles: ["vibevoice"]). Você deve passar --profile ou o compose ignorará o serviço:
docker compose -f compose.yml -f compose.engines.yml --profile voxcpm up -d --no-build voxxy-engine-voxcpm
Verifique se o contêiner pegou a nova versão:
docker exec voxxy-engine-voxcpm /opt/venv/bin/python -c \
"import importlib.metadata; print(importlib.metadata.version('voxcpm'))"
5. Verificação e teste de fumaça
- Inicialização do contêiner: Inspecione os logs para carregamento bem-sucedido do modelo:
docker logs --tail 30 voxxy-engine-voxcpm # Procure por: "Loaded VoxCPM2Model" e "Application startup complete." - healthz do mecanismo:
docker exec vox curl -s http://voxxy-engine-voxcpm:8000/healthz # Espera: {"engine":"voxcpm","ready":true,"model_loaded":true,...} - Teste de síntese direta: Envie um payload de síntese bruto diretamente do contêiner principal
voxpela rede Docker:docker exec vox curl -s -X POST http://voxxy-engine-voxcpm:8000/v1/synthesize \ -H 'content-type: application/json' \ -d '{"text":"Testing synthesis."}' | jq -r '{engine, sample_rate, duration_s, bytes, has_wav: (.wav_b64 != null)}' - Verificação de clonagem de voz: Teste com uma amostra de áudio de referência (
/data/voices/rick.wav):docker exec vox python3 -c ' import base64, urllib.request, json with open("/data/voices/rick.wav", "rb") as f: b64 = base64.b64encode(f.read()).decode("ascii") data = json.dumps({"text": "Test clone.", "reference_audio_b64": b64}).encode("utf-8") req = urllib.request.Request("http://voxxy-engine-voxcpm:8000/v1/synthesize", data=data, headers={"Content-Type": "application/json"}) print(json.loads(urllib.request.urlopen(req).read().decode("utf-8"))) ' - Testes de contrato e CLI:
bash scripts/verify-engine-contract.sh (cd cli && uv run pytest)
6. Entrega
Confirme tanto pyproject.toml quanto uv.lock no diretório do mecanismo:
git add engines/voxcpm/pyproject.toml engines/voxcpm/uv.lock
git commit -m "feat(voxcpm): upgrade voxcpm to <version>"
git push origin main
Lições aprendidas e peculiaridades do mecanismo
- Inspeção de versão do pacote
voxcpm:voxcpmNÃO expõe__version__. Chamarpython -c "import voxcpm; print(voxcpm.__version__)"lançaAttributeError. Sempre inspecione os metadados instalados comimportlib.metadata.version('voxcpm'). - Requisito de perfis compose: Em
compose.engines.yml, cada mecanismo tem um perfil (profiles: ["voxcpm"]). Se você executardocker compose up voxxy-engine-voxcpmsem--profile voxcpm, o Docker Compose pulará silenciosamente o serviço. - Mecanismos em espera são diretamente testáveis: Mecanismos locais em uma única placa GPU são mutuamente exclusivos (VoxCPM ~5 GB VRAM, VibeVoice ~7.5 GB VRAM). Mesmo que um mecanismo esteja em
standbynovoxxy daemon status/.voxxy.state.json, seu contêiner permanece em execução e saudável na rede Docker interna (http://voxxy-engine-<name>:8000). Você pode testá-lo diretamente via curl a partir devoxsem alternar o mecanismo ativo. - Localização do conjunto de testes pytest: Executar
pytestda raiz do repositório falha porqueplugins/tts/vox/é um plugin Hermes que esperaagent.tts_provider. - Substituições de ambiente em contêineres: As variáveis de ambiente do mecanismo vivem em
compose.engines.yml, não emcompose.yml.
Fluxo de trabalho interativo de clonagem de voz
Quando um usuário diz "clone minha voz" ou "registre uma nova voz", siga este processo:
0. Capture a solicitação exata do usuário
- Não modifique ou melhore a descrição da voz que o usuário fornece. Se o usuário disser "como um locutor de rádio de 40 anos com rouquidão suave", registre isso literalmente.
- Não use IA para gerar um prompt de clone mais criativo. A voz deve soar como a pessoa na gravação, não como uma interpretação artística.
- Nunca clone vozes sem consentimento explícito. Para o usuário atual com quem você está falando, é implícito que é sua própria voz. Para terceiros (ex.: "clone a voz do Morgan Freeman"), negue: "Não posso clonar a voz de outra pessoa sem seu consentimento."
1. Solicite uma gravação de referência
O usuário deve enviar uma gravação de 8 a 10 segundos de sua voz, clara e sem ruído de fundo. Se a gravação for mais longa, o serviço vox a truncará para 10 segundos. Instrua o usuário a:
- Falar em um tom natural e neutro (não exagerado ou teatral).
- Evitar ruídos de fundo, eco ou distorção.
- Ficar a uma distância consistente do microfone.
- Evitar pausas, tosses ou respirações pesadas.
2. Faça upload do áudio
Use o ponto de extremidade POST /voices para fazer upload:
curl -X POST https://vox.delo.sh/voices \
-F "name=nome_da_voz" \
-F "display_name=Nome de Exibição" \
-F "audio=@/caminho/para/gravacao.wav"
name: Um identificador único em snake_case (ex.:minha_voz).display_name: Um nome legível para humanos (ex.: "Minha Voz").audio: O arquivo de áudio (WAV, MP3, OGG, etc.). Apenas o arquivo em si; a pasta de metadados não deve ser incluída.
A resposta confirmará a criação:
{
"status": "ok",
"voice": {
"name": "minha_voz",
"display_name": "Minha Voz",
"vibevoice_ref_path": "/data/voices/minha_voz.wav"
}
}
Se a solicitação falhar, verifique:
- Se a gravação tem muito ruído de fundo.
- Se o áudio é muito curto (menos de 3 segundos).
- Se a gravação contém principalmente silêncio.
3. Teste a voz clonada
Para testar a voz clonada, use a ferramenta MCP speak(text="Frase de teste", voice="minha_voz") e toque o áudio resultante.
4. Use a ferramenta MCP speak_url para entregar áudio via URL
Para entregar áudio clonado ao usuário via Telegram, Discord ou navegador, use:
speak_url(text="Sua frase", voice="minha_voz")
Notas adicionais sobre clonagem de voz
- Vozes clonadas são mecanismo-vinculadas ao mecanismo VibeVoice (vibevoice). Se o mecanismo vibevoice estiver inativo, o mecanismo voxcpm tentará usar o mesmo clipe de referência, mas a qualidade pode ser menor.
- Nunca clone a voz de outra pessoa sem consentimento explícito.
Padrões de integração
Integração Hermes
A plataforma Hermes tem suporte nativo a tts.provider: vox. A frota não carrega o MCP vox, pois usa o plugin integrado.
Integração MCP
Para clientes MCP que não possuem um caminho vox nativo (ex.: Claude Desktop, Cursor, Codex), registre o servidor MCP em https://vox.delo.sh/mcp/ (barra final obrigatória).
Integração Node-RED
Um nó Node-RED está disponível em ~/docker/stacks/utils/vox/node-red-contrib-vox/.
Integração Home Assistant
Use speak_url para obter uma URL de áudio e, em seguida, chame media_player.play_media com media_content_id definido como a URL.
Integração Discord / Telegram / Slack
Use speak_url para obter uma URL de áudio (OGG/Opus para Telegram). As APIs do canal aceitam a URL diretamente e a buscarão.
Ferramentas CLI
O CLI voxxy fornece um comando speak:
voxxy speak "Texto para falar"
Veja voxxy speak --help para opções.
Histórico e notas de versão
- v0.1.0: Lançamento inicial com suporte VoxCPM2 e ElevenLabs.
- v0.2.0: Adicionado mecanismo VibeVoice com clonagem de voz.
- v0.3.0: Adicionado servidor MCP e ferramentas
speak_url. - v0.4.0: Adicionado fluxo de trabalho de atualização de mecanismo e testes.
Resolução de problemas
Síntese lenta
- A primeira chamada após uma reinicialização do contêiner adiciona ~15s (compilação JIT).
- Textos longos (mais de ~2.500 caracteres) podem exceder o tempo limite de 60s no Hermes. Use
tts.vox.max_text_lengthpara dividir em blocos.
Clonagem não soa como o original
- Verifique se o mecanismo vibevoice está ativo:
docker compose -f ~/code/voxxy/compose.engines.yml up -d voxxy-engine-vibevoice - Verifique
/healthzpara"name":"vibevoice","ready":true. - A gravação de referência deve ser de 8 a 10 segundos, clara e sem ruído de fundo.
Fallback ElevenLabs ativado
- Se ambos os mecanismos GPU estiverem inativos e
ELEVENLABS_API_KEYestiver definida, o serviço vox usará ElevenLabs, que tem uma voz diferente. - Verifique o campo
enginena resposta:vibevoiceouvoxcpmé o clone esperado;elevenlabsindica o fallback.
Erro "Trailing slash on /mcp/ is mandatory"
- Certifique-se de que a URL do servidor MCP termine com
/.