Files
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

187 lines
12 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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/)
```