# 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: ```ini VOICE_AZURE_KEY= 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//` e **consentimento obrigatório** (`consent: true`; sem ele a voz fica de fora): ```json { "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//`. 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. ```json { "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 ```bash 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/) ```