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>
187 lines
12 KiB
Markdown
187 lines
12 KiB
Markdown
# 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=<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):
|
||
|
||
```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/<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.
|
||
|
||
```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/)
|
||
```
|