Files
CenaForge/voice/README.md
T
MateuusandClaude Opus 5.5 84f30bbc2d CenaForge: primeira versão pública
Gerador de vídeos narrativos (Godot + FFmpeg), painel Next.js, serviço de voz,
Clipador de lives e Publicador para YouTube, TikTok e Instagram.

Inclui a leitura das visualizações dos posts para o Dashboard e o botão
"Publicar no <rede>" nos cartões das publicações.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 16:35:09 -03:00

12 KiB
Raw Blame History

Serviço de voz do CenaForge

Narração (TTS), vozes de personagem (RVC/Applio) e transcrição com tempos (legenda), num serviço HTTP local. Roda nativo no PC (sem Docker), em 127.0.0.1:4510, e sobe junto com o painel (start.bat ou pnpm dev).

Base: cópia adaptada do dropsz_voice (F:\Projects\dropsz\dropsz_voice). O original não é alterado. Foram mantidos as chaves com escopo, a fila por chave, o cache e a idempotência, e a conferência de sha256 dos pesos.

Instalação

setup.bat na raiz do projeto. Ele instala tudo e pode ser rodado de novo, porque pula o que já está pronto.

Etapa O que acontece
Python uv cria voice/.venv com Python 3.12 isolado; o Python do sistema não é tocado
GPU nvidia-smi responde → DLLs CUDA 12 (requirements-cuda.txt) e torch cu128; sem GPU → tudo em CPU
voice/.env criado a partir de .env.example, com chave aleatória; Whisper large-v3-turbo com GPU, small sem
Pesos scripts/fetch_models.py → data/voice/models/, conferidos contra models.lock.json
Applio tag 3.7.0 em voice/vendor/applio, torch 2.11 e pré-requisitos de inferência (contentvec, rmvpe)

Opções: setup.bat -NoRvc (sem Applio; economiza ~4 GB), setup.bat -Cpu (ignora a GPU) e setup.bat -Clone (instala a clonagem de voz: venv próprio com torch 2.6 + Chatterbox, ~4 GB; os pesos, ~3,3 GB, baixam na 1ª subida).

Vozes padrão

voiceId Motor Gênero Offline
pt-br-antonio (padrão) Edge TTS pt-BR-AntonioNeural masculina não
pt-br-francisca Edge TTS pt-BR-FranciscaNeural feminina não
pt-br-faber Piper pt_BR-faber-medium masculina sim
pt-br-cadu Piper pt_BR-cadu-medium masculina sim
pt-br-jeff Piper pt_BR-jeff-medium (articulação mais fraca) masculina sim
pt-br-thalita Edge TTS pt-BR-ThalitaMultilingualNeural feminina não
pt-pt-duarte / pt-pt-raquel Edge TTS pt-PT-DuarteNeural / pt-PT-RaquelNeural (sotaque de Portugal) masc. / fem. não
multi-andrew, multi-brian, multi-william, multi-remy, multi-giuseppe Edge TTS *MultilingualNeural masculina não
multi-ava, multi-emma Edge TTS *MultilingualNeural feminina não
kokoro-pf-dora · kokoro-pm-alex · kokoro-pm-santa Kokoro-82M, estilos pt-BR nativos fem. / masc. / masc. sim
kokoro-* (mais 42) Kokoro-82M, estilos de outros idiomas com fonemas pt-BR (espeak-ng) ambos sim
google-pt-br · google-pt-pt gTTS ("voz do Google", Google Tradutor) feminina não
azure-* (14) Azure Speech pt-BR-*Neural (só com chave; ver abaixo) ambos não

Kokoro (Apache-2.0): um modelo só (kokoro/kokoro-v1.0.fp16.onnx + voices-v1.0.bin, ~190 MB, grupo v1), CPU, ~0,2 s por segundo de áudio depois de carregado. A pronúncia é sempre pt-BR (espeak-ng); o estilo muda o timbre. Das 54 vozes do Kokoro, 45 passaram no teste com Whisper small (16/11/2026); ficaram de fora af_bella, bf_alice, bf_emma, bf_isabella, bm_fable, em_santa, ff_siwis, jf_alpha, af_nicole (texto errado ou idioma ambíguo). O modelo int8 não roda no onnxruntime 1.31 (ConvInteger); use o fp16. Google (gTTS) só tem velocidade normal ou lenta (speed ≤ 0,75).

Campos do catalog.json por motor (além de id, name, language, sampleRate, source, license):

Motor Campos
edge edgeVoice (ex.: pt-BR-ThalitaMultilingualNeural)
piper model + config (caminhos no models.lock.json)
kokoro model (.onnx) + config (voices-v1.0.bin) no lock, kokoroVoice (obrigatório, ex.: pf_dora), kokoroLang (padrão pt-br)
google googleLang (padrão pt), googleTld (padrão com.br; pt = Portugal)
azure azureVoice (ex.: pt-BR-FabioNeural)
clone só em user-voices.json (kind: "clone"), escrito pelo painel; ver "Clonagem de voz"

Motor online (edge, google, azure) aparece no painel como "online · mais lenta". Voz nova num motor que o serviço já conhece entra sozinha (recarga automática); motor novo exige reiniciar o serviço.

As multi-* são vozes multilíngues de outro idioma que leem português (Whisper reconheceu pt em todas no teste de 16/11/2026); o sotaque pode puxar para a língua de origem, o que serve para personagem estrangeiro.

Vozes neutras, sem personagem e sem imitar ninguém. Feminina offline: kokoro-pf-dora (o Piper não tem feminina em pt-BR; edresson ficou de fora por ser 16 kHz/qualidade baixa).

Azure Speech (opcional, com chave)

14 vozes neurais pt-BR (azure-*: Brenda, Donato, Elza, Fabio, Giovanna, Humberto, Julio, Leila, Leticia, Manuela, Nicolau, Valerio, Yara e Macerio multilíngue). Sem VOICE_AZURE_KEY no voice/.env, elas ficam fora da lista. Configure no painel (Vozes → Serviço → Azure Speech) ou à mão:

VOICE_AZURE_KEY=<KEY 1 do recurso "Fala"/Speech no portal do Azure>
VOICE_AZURE_REGION=eastus

Plano F0 (grátis): 0,5 milhão de caracteres por mês. Chamada REST direta (sem SDK), WAV 24 kHz; 401/403/429 viram 502 engine_unavailable e 400 (voz que não existe na região) vira 400. GET /v1/status traz azure: {configured, region} (nunca a chave).

Clonagem de voz (opcional: setup.bat -Clone)

Chatterbox Multilingual (Resemble AI, MIT) clona uma voz a partir de 10–30 s de gravação e fala português. Roda num venv próprio (voice/.venv-clone: torch 2.6, numpy < 2), porque conflita com o voice/.venv. O pnpm dev sobe voice/clone/worker.py em 127.0.0.1:4511 (VOICE_CLONE_PORT) quando o venv existe; o serviço de voz repassa as falas das vozes clone para ele (mesma X-Service-Key). Pesos (~3,3 GB) baixam do Hugging Face na primeira subida para data/voice/models/clone-hf/ (revisão main, sem commit fixo nem sha256 — exceção ao models.lock.json; o worker usa download HTTP comum porque o Xet travou nesta máquina). Sem o processo no ar, a voz clonada responde 503 clone_unavailable. A velocidade não se aplica (o Chatterbox não tem); todo áudio sai com a marca d'água inaudível do Chatterbox (PerTh).

A voz clonada é uma voz do usuário com kind: "clone", a gravação em data/voice/models/clone/<id>/ e consentimento obrigatório (consent: true; sem ele a voz fica de fora):

{ "id": "clone-narrador", "name": "Narrador", "kind": "clone", "gender": "male", "source": "minha voz",
  "license": "…", "consent": true, "consentAt": "2026-11-16T21:00:00Z",
  "clone": { "reference": "clone/clone-narrador/reference.wav", "referenceSha256": "…", "language": "pt",
             "exaggeration": 0.5, "cfgWeight": 0.5 } }

Vozes de personagem ficam em data/voice/user-voices.json, que o painel escreve. Cada uma combina uma voz base com um modelo RVC (.pth e, opcionalmente, .index) em data/voice/models/rvc/<id>/. O sha256 de cada arquivo é gravado ao adicionar e conferido a cada subida. Uma voz com defeito fica de fora, com aviso no log, e as outras continuam funcionando.

{ "voices": [ { "id": "heroi", "name": "Herói", "baseVoice": "pt-br-antonio",
  "rvc": { "model": "rvc/heroi/heroi.pth", "modelSha256": "…", "index": "rvc/heroi/heroi.index",
           "indexSha256": "…", "pitch": 0, "f0Method": "rmvpe", "indexRate": 0.5, "protect": 0.33 } } ] }

API (todas as rotas exigem X-Service-Key, exceto GET /health)

A chave fica em voice/.env (VOICE_SERVICE_KEY) e tem todos os escopos.

Rota Escopo Uso
GET /v1/status status dispositivo (cuda/cpu), RVC, motores, filas, vozes
GET /v1/voices · GET /v1/voices/{id} tts catálogo; provider, offline, baseVoice, rvc (só parâmetros, nunca caminho)
POST /v1/voices/reload admin relê o catálogo e as vozes do usuário (o painel chama ao adicionar ou remover)
POST /v1/synthesize tts (+convert para RVC) {requestId, text, voiceId, params:{speed, format: "wav"|"ogg_opus"}}
POST /v1/transcribe transcribe corpo = áudio cru (WAV/MP3/OGG/M4A/FLAC/WebM)
GET /v1/transcribe/jobs/{ref} transcribe resultado de um job pending

Recarga automática: GET /v1/voices, GET /v1/voices/{id} e POST /v1/synthesize conferem se catalog.json, models.lock.json ou user-voices.json mudaram (data e tamanho) e, se sim, releem o catálogo — voz nova aparece no painel sem reiniciar. Catálogo com defeito (ex.: peso não baixado) mantém as vozes atuais e avisa no log. O reload acima continua servindo para forçar. Mudança de código em voice/app/ ainda exige reiniciar o serviço (o pnpm dev não usa --reload).

Síntese: use wav para o render (o FFmpeg mistura sem perda) e ogg_opus para ouvir no painel. O limite é de 2000 caracteres e 120 s por fala. Uma voz com RVC sem o Applio instalado responde 501 rvc_disabled; um .pth que não é RVC (ou incompatível com o Applio 3.7.0) responde 422 rvc_failed. O Edge sem internet responde 502 engine_unavailable; nesse caso, use o Faber (offline).

Transcrição: os cabeçalhos são X-Idempotency-Key, X-Language (pt-BR, en ou es), X-Detail e, opcional, X-Audio-Duration-Ms (sem ele vale só o teto conferido na decodificação).

X-Detail Resposta (200 ready)
text (padrão) {status, text, noSpeechProb}
segments + durationS, segments: [{start, end, text}]
words + segments[].words: [{start, end, text, p}] (legenda palavra a palavra)

Áudio de até 30 min (VOICE_STT_MAX_AUDIO_S). O POST espera 10 s; depois disso devolve 202 pending com jobRef e retryAfterMs.

GPU e CPU

VOICE_DEVICE=auto, na subida:

  1. pergunta ao nvidia-smi se a placa está livre. Com menos de 2048 MiB livres ou 85% de uso ou mais (um jogo aberto, por exemplo), usa a CPU e mostra o motivo no /v1/status e na página Vozes;
  2. testa o CUDA de verdade, transcrevendo 1 s de áudio sem VAD. Se falhar (DLL ausente, driver antigo), registra no log e a transcrição cai para a CPU com int8. Na GPU o compute type é float16.

A decisão vale até o próximo reinício. Se a placa ficar ocupada depois, escolha CPU nas configurações da página Vozes (o serviço reinicia sozinho). VOICE_DEVICE=cuda força a GPU mesmo ocupada. O Applio escolhe a GPU sozinho (torch); quando o serviço decide pela CPU, o CUDA fica invisível para ele também.

Página Vozes do painel (/voices): ouvir as vozes, adicionar e remover vozes de personagem, testar legenda (baixa o .srt) e mudar dispositivo, Whisper e RVC. As configurações vão para o voice/.env e o pnpm dev reinicia o serviço; modelo do Whisper que falta é baixado antes de gravar.

Armadilhas medidas em 16/11/2026, RTX 2060 SUPER 8 GB, Windows 11:

  • O ctranslate2 enxerga a GPU sem cuBLAS/cuDNN e só quebra na primeira inferência (cublas64_12.dll is not found). Por isso o aquecimento acontece na subida.
  • GPU ocupada por um jogo (98–99% de uso, 7,2–7,4/8 GB): 6,5 s de fala levaram de 41 s a mais de 8 min na GPU, contra 2,5–2,7 s na CPU. Por isso o auto passou a consultar a placa antes de escolher.
  • edge-tts 7.2.8 leva 403 do servidor da Microsoft desde out/2026; a 7.3.1 corrige.
  • O lock antigo do Piper apontava para resolve/main e o arquivo mudou no Hugging Face. Agora a URL é fixada em um commit.

Comandos

pnpm dev                      # painel 4500 + voz 4510
pnpm voice                    # só a voz
pnpm test:voice               # testes (pytest, motores falsos)
voice/.venv/Scripts/python voice/scripts/smoke.py   # fumaça contra o serviço no ar (grava em output/voice-smoke)
voice/.venv/Scripts/python voice/scripts/fetch_models.py --group stt-large-v3-turbo   # outro Whisper
voice/.venv/Scripts/python -m app.keys create --name painel --scopes tts,transcribe,status   # (rode em voice/)