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>
This commit is contained in:
2026-11-17 16:35:09 -03:00
co-authored by Claude Opus 5.5
commit 84f30bbc2d
484 changed files with 74826 additions and 0 deletions
+27
View File
@@ -0,0 +1,27 @@
# Serviço de voz do CenaForge. O setup.bat copia este arquivo para voice/.env e preenche a chave.
# Gere uma chave à mão com: python -c "import secrets; print(secrets.token_urlsafe(48))"
VOICE_SERVICE_KEY=
# Porta (faixa 4500–4599 do CenaForge). Escuta só em 127.0.0.1.
VOICE_PORT=4510
# auto = GPU NVIDIA quando houver; cpu = força CPU; cuda = exige GPU (cai para CPU com aviso se falhar)
VOICE_DEVICE=auto
# 1 = vozes de personagem (RVC/Applio). O setup liga quando instala o Applio.
VOICE_ENABLE_RVC=0
VOICE_MAX_CONCURRENCY=1
VOICE_MAX_QUEUE_PER_KEY=8
VOICE_QUEUE_TIMEOUT_S=180
VOICE_SYNTH_TIMEOUT_S=90
VOICE_MAX_TEXT_CHARS=2000
VOICE_MAX_AUDIO_S=120
VOICE_CACHE_MAX_MB=1024
VOICE_ONNX_THREADS=2
# Transcrição/legenda (faster-whisper). Modelos: base | small | medium | large-v3-turbo
# O setup escolhe large-v3-turbo com GPU e small sem GPU.
VOICE_ENABLE_STT=1
VOICE_STT_MODEL=small
VOICE_STT_COMPUTE_TYPE=auto
VOICE_STT_THREADS=4
VOICE_STT_BEAM_SIZE=1
VOICE_STT_MAX_AUDIO_S=1800
VOICE_STT_TIMEOUT_S=600
VOICE_STT_QUEUE_TIMEOUT_S=1200
+186
View File
@@ -0,0 +1,186 @@
# 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/)
```
View File
+48
View File
@@ -0,0 +1,48 @@
"""Codificação para OGG/Opus em memória (libsndfile via soundfile). Nenhum processo externo."""
from __future__ import annotations
import io
import numpy as np
import soundfile
import soxr
from .engine import Pcm
OPUS_RATE = 48000 # Opus só aceita 8/12/16/24/48 kHz
def encode_ogg_opus(pcm: Pcm, bitrate: int = 48000) -> bytes:
audio = pcm.samples.astype(np.float32) / 32768.0
if pcm.sample_rate != OPUS_RATE:
audio = soxr.resample(audio, pcm.sample_rate, OPUS_RATE, quality="HQ")
buffer = io.BytesIO()
with soundfile.SoundFile(
buffer, mode="w", samplerate=OPUS_RATE, channels=1, format="OGG", subtype="OPUS",
compression_level=_compression_level(bitrate),
) as handle:
handle.write(audio)
return buffer.getvalue()
def _compression_level(bitrate: int) -> float:
"""libsndfile controla a taxa do Opus por 'compression level' (0 = maior taxa, 1 = menor).
Medido no libsndfile 1.2.2 (quase linear): nível 1.0 ≈ 6 kb/s, 0.8 ≈ 58 kb/s, 0.0 ≈ 260 kb/s.
"""
return min(1.0, max(0.0, 1.0 - (bitrate - 6000) / (260000 - 6000)))
def encode_wav(pcm: Pcm) -> bytes:
"""PCM int16 mono → WAV na taxa original. É o formato que o render (FFmpeg) mistura sem perda."""
buffer = io.BytesIO()
soundfile.write(buffer, pcm.samples, pcm.sample_rate, format="WAV", subtype="PCM_16")
return buffer.getvalue()
def encode(pcm: Pcm, fmt: str, bitrate: int) -> bytes:
return encode_wav(pcm) if fmt == "wav" else encode_ogg_opus(pcm, bitrate)
MEDIA_TYPES = {"wav": "audio/wav", "ogg_opus": "audio/ogg; codecs=opus"}
+246
View File
@@ -0,0 +1,246 @@
"""Catálogo de vozes + verificação dos modelos (sha256).
Duas fontes:
- `voices/catalog.json` (versionado): vozes base. Motor `piper` (pesos no models.lock.json) ou `edge`
(Edge TTS, online, sem arquivo local).
- `data/voice/user-voices.json` (local, escrito pelo painel): vozes de personagem = uma voz base + um modelo
RVC (.pth/.index) adicionado pelo usuário. O sha256 de cada arquivo é gravado na hora de adicionar e
conferido em toda subida, como o lock faz com os pesos oficiais.
"""
from __future__ import annotations
import hashlib
import json
import logging
from dataclasses import dataclass, replace
from pathlib import Path
from .config import ConfigError
log = logging.getLogger("cenaforge_voice")
ENGINES = ("piper", "edge", "kokoro", "google", "azure", "clone", "fake")
# Voz clonada: áudio de referência + parâmetros do Chatterbox (o processo de clonagem lê o arquivo).
CLONE_DEFAULTS = {"exaggeration": 0.5, "cfgWeight": 0.5}
# Motores que mandam o texto para fora (precisam de internet e costumam ser mais lentos).
ONLINE_ENGINES = ("edge", "google", "azure")
RVC_DEFAULTS = {"pitch": 0, "f0Method": "rmvpe", "indexRate": 0.5, "protect": 0.33}
@dataclass(frozen=True)
class Voice:
id: str
name: str
language: str
engine: str
model: Path | None
config: Path | None
sample_rate: int
default: bool
source: str
license: str
revision: str # sha256 do modelo (prefixo); entra na chave de cache
rvc: dict | None = None # {"modelPath": Path, "indexPath": Path|None, "pitch", "f0Method", "indexRate", "protect"}
description: str | None = None
gender: str | None = None # female|male|neutral
age_range: str | None = None # child|young|adult|senior
accent: str | None = None
edge_voice: str | None = None # nome da voz no Edge TTS (ex.: pt-BR-FranciscaNeural)
engine_voice: str | None = None # kokoro: estilo (ex.: pf_dora); google: domínio (ex.: com.br); azure: voz
engine_lang: str | None = None # kokoro: idioma do espeak (ex.: pt-br); google: idioma (ex.: pt)
base_voice: str | None = None # voz base de uma voz de personagem (RVC)
clone: dict | None = None # voz clonada: {"exaggeration", "cfgWeight"}; o áudio de referência fica em `model`
user: bool = False # adicionada pelo painel
# Hash já calculado por (caminho, mtime, tamanho): várias vozes Kokoro dividem o mesmo modelo de ~160 MB e a
# recarga automática do catálogo não deve re-hashear tudo a cada mudança.
_HASH_CACHE: dict[tuple[str, int, int], str] = {}
def sha256_file(path: Path) -> str:
info = path.stat()
key = (str(path.resolve()), info.st_mtime_ns, info.st_size)
cached = _HASH_CACHE.get(key)
if cached is not None:
return cached
digest = hashlib.sha256()
with path.open("rb") as handle:
for block in iter(lambda: handle.read(1 << 20), b""):
digest.update(block)
_HASH_CACHE[key] = digest.hexdigest()
return _HASH_CACHE[key]
def _short_hash(*parts: str) -> str:
return hashlib.sha256("|".join(parts).encode("utf-8")).hexdigest()[:16]
def load_lock(lock_path: Path) -> dict[str, dict]:
data = json.loads(lock_path.read_text(encoding="utf-8"))
return {entry["path"]: entry for entry in data["files"]}
def _check_locked(voice_id: str, rel: str, lock: dict, models_dir: Path, verify: bool) -> None:
if rel not in lock:
raise ConfigError(f"voz {voice_id}: {rel} não está no models.lock.json")
path = models_dir / rel
if not path.is_file():
raise ConfigError(f"voz {voice_id}: modelo ausente ({rel}); rode o setup.bat (ou scripts/fetch_models.py)")
if verify and sha256_file(path) != lock[rel]["sha256"]:
raise ConfigError(f"voz {voice_id}: checksum diferente do lock ({rel})")
def _base_voice(item: dict, lock: dict, models_dir: Path, verify: bool) -> Voice:
engine = item["engine"]
if engine not in ENGINES:
raise ConfigError(f"voz {item['id']}: motor desconhecido {engine!r} (válidos: {', '.join(ENGINES)})")
model = config = edge_voice = engine_voice = engine_lang = None
if engine == "edge":
edge_voice = item.get("edgeVoice")
if not edge_voice:
raise ConfigError(f"voz {item['id']}: motor edge exige edgeVoice")
revision = _short_hash("edge", edge_voice)
elif engine == "azure":
engine_voice = item.get("azureVoice")
if not engine_voice:
raise ConfigError(f"voz {item['id']}: motor azure exige azureVoice")
revision = _short_hash("azure", engine_voice)
elif engine == "google":
engine_lang, engine_voice = item.get("googleLang", "pt"), item.get("googleTld", "com.br")
revision = _short_hash("google", engine_lang, engine_voice)
else:
# piper/kokoro/fake: pesos locais conferidos contra o lock. No kokoro, `config` é o voices.bin.
for rel in (item["model"], item["config"]):
_check_locked(item["id"], rel, lock, models_dir, verify)
model, config = models_dir / item["model"], models_dir / item["config"]
revision = lock[item["model"]]["sha256"][:16]
if engine == "kokoro":
engine_voice, engine_lang = item.get("kokoroVoice"), item.get("kokoroLang", "pt-br")
if not engine_voice:
raise ConfigError(f"voz {item['id']}: motor kokoro exige kokoroVoice")
revision = _short_hash(revision, engine_voice, engine_lang)
return Voice(
id=item["id"],
name=item["name"],
language=item["language"],
engine=engine,
model=model,
config=config,
sample_rate=int(item["sampleRate"]),
default=bool(item.get("default", False)),
source=item["source"],
license=item["license"],
revision=revision,
description=item.get("description"),
gender=item.get("gender"),
age_range=item.get("ageRange"),
accent=item.get("accent"),
edge_voice=edge_voice,
engine_voice=engine_voice,
engine_lang=engine_lang,
)
def _user_file(voice_id: str, rel: str, expected: str, models_dir: Path, verify: bool) -> Path:
"""Arquivo de voz do usuário: dentro da pasta de modelos, presente e com o sha256 gravado ao adicionar."""
path = (models_dir / rel).resolve()
if models_dir.resolve() not in path.parents:
raise ConfigError(f"voz {voice_id}: caminho fora da pasta de modelos ({rel})")
if not path.is_file():
raise ConfigError(f"voz {voice_id}: arquivo ausente ({rel})")
if verify and sha256_file(path) != expected:
raise ConfigError(f"voz {voice_id}: checksum diferente do registrado ({rel})")
return path
def _clone_voice(item: dict, models_dir: Path, verify: bool) -> Voice:
voice_id = item["id"]
raw = item.get("clone") or {}
if not raw.get("reference"):
raise ConfigError(f"voz {voice_id}: clone.reference é obrigatório")
if item.get("consent") is not True:
raise ConfigError(f"voz {voice_id}: voz clonada sem autorização registrada (consent)")
expected = raw.get("referenceSha256", "")
path = _user_file(voice_id, raw["reference"], expected, models_dir, verify)
params = {key: float(raw.get(key, default)) for key, default in CLONE_DEFAULTS.items()}
return Voice(
id=voice_id, name=item["name"], language=item.get("language", "pt-BR"), engine="clone",
model=path, config=None, sample_rate=24000, default=False,
source=item.get("source", "gravação enviada pelo painel"), license=item.get("license", "informada pelo usuário"),
revision=_short_hash("clone", expected, json.dumps(params, sort_keys=True)),
description=item.get("description"), gender=item.get("gender"), age_range=item.get("ageRange"),
accent=item.get("accent", "pt-BR"), engine_lang=raw.get("language", "pt"), clone=params, user=True,
)
def _user_voice(item: dict, bases: dict[str, Voice], models_dir: Path, verify: bool) -> Voice:
voice_id = item["id"]
if item.get("kind") == "clone":
return _clone_voice(item, models_dir, verify)
base = bases.get(item.get("baseVoice", ""))
if base is None:
raise ConfigError(f"voz {voice_id}: baseVoice {item.get('baseVoice')!r} não existe no catálogo")
raw = item.get("rvc") or {}
files: dict[str, Path | None] = {}
hashes: list[str] = []
for field in ("model", "index"):
rel = raw.get(field)
if not rel:
if field == "model":
raise ConfigError(f"voz {voice_id}: rvc.model é obrigatório")
files[field] = None
continue
path = (models_dir / rel).resolve()
if models_dir.resolve() not in path.parents:
raise ConfigError(f"voz {voice_id}: caminho fora da pasta de modelos ({rel})")
if not path.is_file():
raise ConfigError(f"voz {voice_id}: arquivo ausente ({rel})")
expected = raw.get(f"{field}Sha256", "")
if verify and sha256_file(path) != expected:
raise ConfigError(f"voz {voice_id}: checksum diferente do registrado ({rel})")
files[field] = path
hashes.append(expected)
rvc = {key: raw.get(key, default) for key, default in RVC_DEFAULTS.items()}
rvc.update(modelPath=files["model"], indexPath=files["index"])
params = json.dumps({k: rvc[k] for k in RVC_DEFAULTS}, sort_keys=True)
return replace(
base,
id=voice_id,
name=item["name"],
default=False,
source=item.get("source", "adicionada pelo painel"),
license=item.get("license", "informada pelo usuário"),
revision=_short_hash(base.revision, *hashes, params),
rvc=rvc,
description=item.get("description"),
gender=item.get("gender", base.gender),
age_range=item.get("ageRange", base.age_range),
accent=item.get("accent", base.accent),
base_voice=base.id,
user=True,
)
def load_catalog(
catalog_path: Path, lock_path: Path, models_dir: Path, verify: bool = True, user_catalog_path: Path | None = None
) -> dict[str, Voice]:
lock = load_lock(lock_path)
raw = json.loads(catalog_path.read_text(encoding="utf-8"))
voices: dict[str, Voice] = {}
for item in raw["voices"]:
voices[item["id"]] = _base_voice(item, lock, models_dir, verify)
if sum(v.default for v in voices.values()) != 1:
raise ConfigError("o catálogo precisa de exatamente uma voz padrão")
if user_catalog_path is not None and user_catalog_path.is_file():
bases = dict(voices)
for item in json.loads(user_catalog_path.read_text(encoding="utf-8")).get("voices", []):
# Voz do usuário com defeito fica de fora (com aviso); não derruba as vozes base.
try:
if item.get("id") in voices:
raise ConfigError(f"voz {item.get('id')}: id repetido entre o catálogo e as vozes do usuário")
voices[item["id"]] = _user_voice(item, bases, models_dir, verify)
except (ConfigError, KeyError) as exc:
log.warning("voz do usuário ignorada: %s", exc)
return voices
+215
View File
@@ -0,0 +1,215 @@
"""Configuração do serviço de voz do CenaForge, lida de variáveis de ambiente e de `voice/.env`.
Roda nativo no PC (sem Docker): as pastas padrão ficam em `data/voice/` na raiz do projeto.
Falha fechado: sem chave de serviço forte o processo não sobe (o setup gera uma no `voice/.env`).
"""
from __future__ import annotations
import os
from dataclasses import dataclass
from pathlib import Path
MIN_KEY_LENGTH = 32
# Variáveis que deixaram de valer: a fila virou cota por chave (`*_PER_KEY`). Avisamos no boot para o
# operador não achar que o valor antigo continua limitando alguma coisa.
# Timeout do cliente HTTP (painel e render do CenaForge). A síntese é síncrona: espera na fila + execução
# precisa caber nele, ou o cliente desiste antes da resposta.
BACKEND_CLIENT_TIMEOUT_S = 300.0
VOICE_ROOT = Path(__file__).resolve().parent.parent
PROJECT_ROOT = VOICE_ROOT.parent
STT_MODELS = ("base", "small", "medium", "large-v3-turbo")
DEVICES = ("auto", "cuda", "cpu")
# A espera na fila precisa cobrir pelo menos este múltiplo da execução: com a CPU em rodízio, a outra chave pode
# pegar um trabalho no teto na frente (e a vaga só volta quando a thread termina, um pouco depois do teto).
QUEUE_TO_RUN_RATIO = 2.0
RETIRED_VARS = {"VOICE_MAX_QUEUE": "VOICE_MAX_QUEUE_PER_KEY", "VOICE_STT_MAX_QUEUE": "VOICE_STT_MAX_QUEUE_PER_KEY"}
class ConfigError(RuntimeError):
"""Configuração inválida; o serviço não deve subir."""
def load_dotenv(path: Path) -> None:
"""Carrega `CHAVE=valor` de um arquivo .env sem sobrescrever o que já está no ambiente."""
if not path.is_file():
return
for line in path.read_text(encoding="utf-8").splitlines():
line = line.strip()
if not line or line.startswith("#") or "=" not in line:
continue
name, value = line.split("=", 1)
os.environ.setdefault(name.strip(), value.strip().strip('"').strip("'"))
def _path(name: str, default: Path) -> Path:
raw = os.environ.get(name, "")
if not raw:
return default
value = Path(raw)
return value if value.is_absolute() else PROJECT_ROOT / value
def _int(name: str, default: int, minimum: int = 1) -> int:
raw = os.environ.get(name)
value = default if raw in (None, "") else int(raw)
if value < minimum:
raise ConfigError(f"{name} precisa ser >= {minimum}")
return value
def _float(name: str, default: float, minimum: float = 0.1) -> float:
raw = os.environ.get(name)
value = default if raw in (None, "") else float(raw)
if value < minimum:
raise ConfigError(f"{name} precisa ser >= {minimum}")
return value
def _azure_region() -> str:
region = os.environ.get("VOICE_AZURE_REGION", "eastus").strip().lower() or "eastus"
if not region.isascii() or not region.isalnum():
raise ConfigError(f"VOICE_AZURE_REGION inválida: {region!r} (ex.: eastus, brazilsouth)")
return region
def _clone_port() -> int:
port = _int("VOICE_CLONE_PORT", 4511)
if not 4500 <= port <= 4599:
raise ConfigError(f"VOICE_CLONE_PORT={port} fora da faixa 4500–4599 do CenaForge")
return port
def _choice(name: str, default: str, allowed: tuple[str, ...]) -> str:
value = os.environ.get(name) or default
if value not in allowed:
raise ConfigError(f"{name} precisa ser um de {allowed}")
return value
@dataclass(frozen=True)
class Settings:
service_key: str
models_dir: Path
data_dir: Path
catalog_path: Path
lock_path: Path
max_concurrency: int = 1
# Cota de espera POR CHAVE de serviço: a fila cheia de uma chave nunca recusa a outra.
max_queue_per_key: int = 8
# Uma fala de episódio (até 2 min) com RVC em CPU leva ~1 min. 180 + 90 = 270 s < 300 s do cliente.
queue_timeout_s: float = 180.0
synth_timeout_s: float = 90.0
max_text_chars: int = 2000
max_audio_s: float = 120.0
cache_max_mb: int = 512
idempotency_ttl_h: int = 72
onnx_threads: int = 2
opus_bitrate: int = 48000
verify_models: bool = True
enable_rvc: bool = False
# Azure Speech (opcional): sem chave, as vozes do motor azure ficam fora do catálogo.
azure_key: str = ""
azure_region: str = "eastus"
# Processo de clonagem (Chatterbox, venv próprio): porta local na faixa do CenaForge.
clone_port: int = 4511
applio_dir: Path = VOICE_ROOT / "vendor" / "applio"
# auto = CUDA quando houver GPU NVIDIA utilizável; senão CPU. Vale para Whisper e RVC.
device: str = "auto"
# Vozes adicionadas pelo painel (fora do models.lock.json; o sha256 é gravado na hora de adicionar).
user_catalog_path: Path | None = None
# Transcrição (faster-whisper). Fila própria: STT não toma a vaga do TTS.
enable_stt: bool = False
stt_model: str = "small"
stt_compute_type: str = "auto"
stt_threads: int = 2
stt_beam_size: int = 1
stt_vad: bool = True
stt_max_bytes: int = 256 * 1024 * 1024
# Episódio inteiro: até 30 min. small int8 em CPU ≈ 0,25 s de CPU por 1 s de fala (≈ 8 min para 30 min).
stt_max_audio_s: float = 1800.0
stt_max_concurrency: int = 1
stt_max_queue_per_key: int = 4
# O job é assíncrono (o POST espera só stt_sync_wait_s), então a espera na fila não conta no timeout HTTP.
stt_queue_timeout_s: float = 1200.0
stt_timeout_s: float = 600.0
stt_sync_wait_s: float = 10.0
stt_job_ttl_s: int = 3600
stt_max_chars: int = 200_000
def timeout_warnings(self) -> list[str]:
"""Relações de timeout que, se não valerem, deixam uma chave levar `queue_timeout` por trabalho da outra."""
warnings = []
pairs = (
("VOICE_QUEUE_TIMEOUT_S", self.queue_timeout_s, "VOICE_SYNTH_TIMEOUT_S", self.synth_timeout_s),
("VOICE_STT_QUEUE_TIMEOUT_S", self.stt_queue_timeout_s, "VOICE_STT_TIMEOUT_S", self.stt_timeout_s),
)
for queue_name, queue_s, run_name, run_s in pairs:
if queue_s < QUEUE_TO_RUN_RATIO * run_s:
warnings.append(
f"{queue_name}={queue_s:g} abaixo de {QUEUE_TO_RUN_RATIO:g}x {run_name}={run_s:g}: "
"uma chave pode levar queue_timeout atrás de trabalho longo de outra"
)
if self.queue_timeout_s + self.synth_timeout_s >= BACKEND_CLIENT_TIMEOUT_S:
warnings.append(
f"VOICE_QUEUE_TIMEOUT_S + VOICE_SYNTH_TIMEOUT_S = {self.queue_timeout_s + self.synth_timeout_s:g} s "
f"não cabe no timeout do backend ({BACKEND_CLIENT_TIMEOUT_S:g} s): ele desiste antes da resposta"
)
return warnings
@staticmethod
def retired_vars_in_env() -> list[tuple[str, str]]:
"""(variável antiga, substituta) para cada variável aposentada ainda presente no ambiente."""
return [(old, new) for old, new in RETIRED_VARS.items() if os.environ.get(old, "") != ""]
@staticmethod
def from_env() -> "Settings":
load_dotenv(VOICE_ROOT / ".env")
key = os.environ.get("VOICE_SERVICE_KEY", "")
if len(key) < MIN_KEY_LENGTH:
raise ConfigError(
f"VOICE_SERVICE_KEY ausente ou curta (mínimo {MIN_KEY_LENGTH} caracteres); rode o setup.bat"
)
root = VOICE_ROOT
data = PROJECT_ROOT / "data" / "voice"
return Settings(
service_key=key,
models_dir=_path("VOICE_MODELS_DIR", data / "models"),
data_dir=_path("VOICE_DATA_DIR", data / "state"),
catalog_path=_path("VOICE_CATALOG", root / "voices" / "catalog.json"),
lock_path=_path("VOICE_MODELS_LOCK", root / "models.lock.json"),
user_catalog_path=_path("VOICE_USER_CATALOG", data / "user-voices.json"),
max_concurrency=_int("VOICE_MAX_CONCURRENCY", 1),
max_queue_per_key=_int("VOICE_MAX_QUEUE_PER_KEY", 8, minimum=0),
queue_timeout_s=_float("VOICE_QUEUE_TIMEOUT_S", 180.0),
synth_timeout_s=_float("VOICE_SYNTH_TIMEOUT_S", 90.0),
max_text_chars=_int("VOICE_MAX_TEXT_CHARS", 2000),
max_audio_s=_float("VOICE_MAX_AUDIO_S", 120.0),
cache_max_mb=_int("VOICE_CACHE_MAX_MB", 512),
idempotency_ttl_h=_int("VOICE_IDEMPOTENCY_TTL_H", 72),
onnx_threads=_int("VOICE_ONNX_THREADS", 2),
opus_bitrate=_int("VOICE_OPUS_BITRATE", 48000, minimum=6000),
verify_models=os.environ.get("VOICE_VERIFY_MODELS", "1") != "0",
enable_rvc=os.environ.get("VOICE_ENABLE_RVC", "0") == "1",
azure_key=os.environ.get("VOICE_AZURE_KEY", "").strip(),
azure_region=_azure_region(),
clone_port=_clone_port(),
applio_dir=_path("VOICE_APPLIO_DIR", root / "vendor" / "applio"),
device=_choice("VOICE_DEVICE", "auto", DEVICES),
enable_stt=os.environ.get("VOICE_ENABLE_STT", "1") == "1",
stt_model=_choice("VOICE_STT_MODEL", "small", STT_MODELS),
stt_compute_type=_choice(
"VOICE_STT_COMPUTE_TYPE", "auto", ("auto", "int8", "int8_float32", "int8_float16", "float16", "float32")
),
stt_threads=_int("VOICE_STT_THREADS", 2),
stt_beam_size=_int("VOICE_STT_BEAM_SIZE", 1),
stt_vad=os.environ.get("VOICE_STT_VAD", "1") != "0",
stt_max_bytes=_int("VOICE_STT_MAX_BYTES", 256 * 1024 * 1024, minimum=1024),
stt_max_audio_s=_float("VOICE_STT_MAX_AUDIO_S", 1800.0),
stt_max_concurrency=_int("VOICE_STT_MAX_CONCURRENCY", 1),
stt_max_queue_per_key=_int("VOICE_STT_MAX_QUEUE_PER_KEY", 4, minimum=0),
stt_queue_timeout_s=_float("VOICE_STT_QUEUE_TIMEOUT_S", 1200.0),
stt_timeout_s=_float("VOICE_STT_TIMEOUT_S", 600.0),
stt_sync_wait_s=_float("VOICE_STT_SYNC_WAIT_S", 10.0, minimum=0.0),
stt_job_ttl_s=_int("VOICE_STT_JOB_TTL_S", 3600, minimum=60),
)
+44
View File
@@ -0,0 +1,44 @@
"""Decodificação de áudio em memória com PyAV (vem com o faster-whisper). Sem ffmpeg nem subprocesso.
Aceita qualquer contêiner que o PyAV abra (WAV, MP3, OGG/Opus, FLAC, M4A/MP4, WebM). Para de decodificar ao
passar de `max_seconds` (AudioTooLong): um arquivo pequeno em bitrate baixo pode descomprimir em horas de PCM.
"""
from __future__ import annotations
import io
import numpy as np
from .errors import AudioTooLong, InvalidAudio
def decode_audio(data: bytes, rate: int, max_seconds: float, sample_format: str = "flt") -> np.ndarray:
"""Bytes de áudio → PCM mono em `rate` Hz. `flt` = float32 em -1..1; `s16` = int16."""
import av
max_samples = int(max_seconds * rate)
try:
with av.open(io.BytesIO(data), mode="r") as container:
stream = next((s for s in container.streams if s.type == "audio"), None)
if stream is None:
raise InvalidAudio()
resampler = av.AudioResampler(format=sample_format, layout="mono", rate=rate)
chunks: list[np.ndarray] = []
total = 0
for frame in [*container.decode(stream), None]: # None esvazia o resampler no fim
for out in resampler.resample(frame):
chunk = out.to_ndarray().reshape(-1)
total += chunk.size
if total > max_samples:
raise AudioTooLong()
chunks.append(chunk)
except (InvalidAudio, AudioTooLong):
raise
except Exception: # noqa: BLE001 - qualquer falha do PyAV = áudio ilegível
raise InvalidAudio() from None
dtype = np.float32 if sample_format == "flt" else np.int16
samples = np.concatenate(chunks).astype(dtype, copy=False) if chunks else np.zeros(0, dtype)
if samples.size == 0:
raise InvalidAudio()
return samples
+106
View File
@@ -0,0 +1,106 @@
"""Escolha do dispositivo de inferência: GPU NVIDIA (CUDA) quando houver e funcionar; senão CPU.
No Windows as DLLs do CUDA (cuBLAS, cuDNN) vêm de pacotes pip `nvidia-*-cu12` e da pasta `torch/lib`.
Elas precisam ser registradas ANTES de importar ctranslate2/torch, ou o CUDA "existe" mas a carga falha.
"""
from __future__ import annotations
import logging
import os
import sys
from dataclasses import dataclass
from pathlib import Path
log = logging.getLogger("cenaforge_voice")
_registered = False
@dataclass(frozen=True)
class DeviceInfo:
kind: str # "cuda" | "cpu"
name: str | None # nome da GPU, quando houver
reason: str # por que caiu nesse dispositivo (vai para o /v1/status e para o log)
def register_cuda_dlls() -> None:
"""Coloca as pastas de DLL do CUDA (pip nvidia-* e torch/lib) no caminho de busca do Windows."""
global _registered
if _registered or sys.platform != "win32":
_registered = True
return
_registered = True
for site in {Path(p) for p in sys.path if p.endswith("site-packages")}:
candidates = list((site / "nvidia").glob("*/bin")) + [site / "torch" / "lib"]
for folder in candidates:
if folder.is_dir():
os.add_dll_directory(str(folder))
os.environ["PATH"] = f"{folder}{os.pathsep}{os.environ.get('PATH', '')}"
def resolve_device(setting: str) -> DeviceInfo:
"""`auto` testa o CUDA de verdade (contagem de GPUs no CTranslate2/torch); `cpu` desliga o CUDA de vez."""
if setting == "cpu":
# Também impede o Applio (torch) de pegar a GPU por conta própria.
os.environ["CUDA_VISIBLE_DEVICES"] = ""
return DeviceInfo("cpu", None, "VOICE_DEVICE=cpu")
register_cuda_dlls()
count = 0
try:
import ctranslate2
count = ctranslate2.get_cuda_device_count()
except Exception as exc: # noqa: BLE001 - qualquer falha de driver/DLL = sem CUDA
log.warning("cuda: ctranslate2 não enxergou a GPU (%s)", type(exc).__name__)
name = _gpu_name()
if count > 0:
busy = gpu_busy_reason() if setting == "auto" else None
if busy:
# Medido: com um jogo usando a placa (99%, 7,2/8 GB), 6,5 s de fala levaram minutos na GPU contra
# ~3 s na CPU. No auto, GPU ocupada na subida = CPU (e o Applio também, pelo CUDA_VISIBLE_DEVICES).
os.environ["CUDA_VISIBLE_DEVICES"] = ""
log.warning("cuda: %s; usando CPU (force com VOICE_DEVICE=cuda)", busy)
return DeviceInfo("cpu", name, busy)
return DeviceInfo("cuda", name, "GPU NVIDIA detectada")
if setting == "cuda":
log.warning("cuda: VOICE_DEVICE=cuda, mas nenhuma GPU utilizável foi encontrada; usando CPU")
return DeviceInfo("cpu", None, "sem GPU NVIDIA utilizável")
MIN_FREE_MIB = 2048 # Whisper small/turbo em float16 + RVC cabem com folga em ~2 GB
MAX_BUSY_PERCENT = 85
def gpu_busy_reason() -> str | None:
"""Pergunta ao nvidia-smi (argumentos fixos) quanto da GPU 0 está livre. Ocupada demais → motivo; senão None."""
import subprocess
try:
out = subprocess.run(
["nvidia-smi", "--query-gpu=memory.free,utilization.gpu", "--format=csv,noheader,nounits"],
capture_output=True, text=True, timeout=10, check=True,
).stdout.splitlines()[0]
free_mib, util = (int(part.strip()) for part in out.split(","))
except Exception: # noqa: BLE001 - sem nvidia-smi ou saída estranha: não bloqueia a GPU
return None
if free_mib < MIN_FREE_MIB or util >= MAX_BUSY_PERCENT:
return f"GPU ocupada por outro programa ({util}% de uso, {free_mib} MiB livres)"
return None
def _gpu_name() -> str | None:
try:
import torch
if torch.cuda.is_available():
return torch.cuda.get_device_name(0)
except Exception: # noqa: BLE001 - torch ausente (instalação sem RVC) ou sem CUDA
return None
return None
def stt_compute_type(setting: str, device: DeviceInfo) -> str:
"""`auto`: float16 na GPU (rápido, sem perda perceptível), int8 na CPU (medido no dropsz_voice)."""
if setting != "auto":
return setting
return "float16" if device.kind == "cuda" else "int8"
+361
View File
@@ -0,0 +1,361 @@
"""Motores de TTS. Cada motor devolve PCM int16 mono; quem codifica é app.audio.
Contrato: `synthesize(voice, text, speed, max_seconds)` levanta AudioTooLong assim que o
áudio acumulado passa do limite — o custo de CPU para no limite, não depois.
Motores:
- `PiperEngine`: offline (ONNX, CPU). Licença clara; voz mais "lida".
- `EdgeEngine`: Edge TTS (online, Microsoft). Melhor prosódia em pt-BR; precisa de internet.
- `KokoroEngine`: Kokoro-82M (offline, ONNX, CPU, Apache-2.0). Um modelo, várias vozes (estilos).
- `GoogleEngine`: "voz do Google" (gTTS, online, API não oficial do Google Tradutor).
- `AzureEngine`: Azure Speech (online, chave do usuário). Vozes neurais pt-BR que o Edge não expõe.
- `CloneEngine`: voz clonada (Chatterbox) pelo processo de clonagem local, num venv próprio (porta 4511).
- `RoutingEngine`: escolhe o motor pelo campo `engine` da voz do catálogo.
"""
from __future__ import annotations
import asyncio
import threading
import time
from dataclasses import dataclass
from typing import Protocol
import numpy as np
from .catalog import Voice
from .errors import AudioTooLong, CloneUnavailable, EngineUnavailable, InvalidRequest, ServiceError, VoiceNotFound
@dataclass(frozen=True)
class Pcm:
samples: np.ndarray # int16 mono
sample_rate: int
@property
def duration_s(self) -> float:
return len(self.samples) / self.sample_rate
class TtsEngine(Protocol):
name: str
def synthesize(self, voice: Voice, text: str, speed: float, max_seconds: float) -> Pcm: ...
class PiperEngine:
"""Piper (ONNX, CPU). Sessões carregadas uma vez por voz, com número de threads fixo."""
name = "piper"
def __init__(self, onnx_threads: int):
self._threads = onnx_threads
self._voices: dict[str, object] = {}
self._lock = threading.Lock()
def warmup(self, voice: Voice) -> None:
self._get(voice)
def _get(self, voice: Voice):
with self._lock:
loaded = self._voices.get(voice.id)
if loaded is None:
import onnxruntime
from piper import PiperVoice
loaded = PiperVoice.load(voice.model, config_path=voice.config)
options = onnxruntime.SessionOptions()
options.intra_op_num_threads = self._threads
options.inter_op_num_threads = 1
# Troca a sessão padrão (que usa todos os núcleos) por uma com threads limitadas.
loaded.session = onnxruntime.InferenceSession(
str(voice.model), sess_options=options, providers=["CPUExecutionProvider"]
)
self._voices[voice.id] = loaded
return loaded
def synthesize(self, voice: Voice, text: str, speed: float, max_seconds: float) -> Pcm:
from piper import SynthesisConfig
piper_voice = self._get(voice)
config = SynthesisConfig(length_scale=1.0 / speed)
max_samples = int(max_seconds * voice.sample_rate)
chunks: list[np.ndarray] = []
total = 0
rate = voice.sample_rate
# O Piper gera por frase; paramos assim que o acumulado passa do limite.
for chunk in piper_voice.synthesize(text, syn_config=config):
rate = chunk.sample_rate
data = np.frombuffer(chunk.audio_int16_bytes, dtype=np.int16)
total += len(data)
if total > max_samples:
raise AudioTooLong()
chunks.append(data)
if not chunks:
raise InvalidRequest("Texto não gerou áudio.")
return Pcm(np.concatenate(chunks), rate)
def edge_rate(speed: float) -> str:
"""Velocidade (0,5–2,0) → taxa do Edge TTS ("+25%", "-10%")."""
return f"{round((speed - 1.0) * 100):+d}%"
class EdgeEngine:
"""Edge TTS: o texto vai para o serviço da Microsoft e volta como MP3 24 kHz, decodificado em memória.
Roda dentro da thread do WorkQueue, que não tem event loop: `asyncio.run` cria um só para esta síntese.
"""
name = "edge"
def __init__(self, timeout_s: float = 60.0):
self._timeout_s = timeout_s
def synthesize(self, voice: Voice, text: str, speed: float, max_seconds: float) -> Pcm:
from .decode import decode_audio
try:
mp3 = asyncio.run(asyncio.wait_for(self._fetch(voice, text, speed), self._timeout_s))
except ServiceError:
raise
except Exception as exc: # noqa: BLE001 - rede, DNS, recusa do serviço
raise EngineUnavailable() from exc
if not mp3:
raise InvalidRequest("Texto não gerou áudio.")
samples = decode_audio(mp3, voice.sample_rate, max_seconds, sample_format="s16")
return Pcm(np.ascontiguousarray(samples), voice.sample_rate)
async def _fetch(self, voice: Voice, text: str, speed: float) -> bytes:
import edge_tts
communicate = edge_tts.Communicate(text, voice.edge_voice, rate=edge_rate(speed))
chunks: list[bytes] = []
async for chunk in communicate.stream():
if chunk["type"] == "audio":
chunks.append(chunk["data"])
return b"".join(chunks)
class KokoroEngine:
"""Kokoro-82M via kokoro-onnx. Um só modelo para todas as vozes; a voz é um estilo do voices.bin.
Fonemas pelo espeak-ng embutido (`lang` = pt-br). Velocidade nativa (0,5–2,0).
"""
name = "kokoro"
def __init__(self, onnx_threads: int):
self._threads = onnx_threads
self._models: dict[tuple[str, str], object] = {}
self._lock = threading.Lock()
def warmup(self, voice: Voice) -> None:
self._get(voice)
def _get(self, voice: Voice):
key = (str(voice.model), str(voice.config))
with self._lock:
loaded = self._models.get(key)
if loaded is None:
import onnxruntime
from kokoro_onnx import Kokoro
options = onnxruntime.SessionOptions()
options.intra_op_num_threads = self._threads
options.inter_op_num_threads = 1
# O modelo fp16 gera centenas de avisos inofensivos de "constant folding"; só erros vão ao log.
options.log_severity_level = 3
session = onnxruntime.InferenceSession(
str(voice.model), sess_options=options, providers=["CPUExecutionProvider"]
)
loaded = Kokoro.from_session(session, str(voice.config))
self._models[key] = loaded
return loaded
def synthesize(self, voice: Voice, text: str, speed: float, max_seconds: float) -> Pcm:
kokoro = self._get(voice)
try:
samples, rate = kokoro.create(text, voice=voice.engine_voice, speed=speed, lang=voice.engine_lang or "pt-br")
except (KeyError, ValueError) as exc:
raise InvalidRequest(f"Kokoro recusou o texto ou a voz: {exc}") from exc
if samples is None or len(samples) == 0:
raise InvalidRequest("Texto não gerou áudio.")
if len(samples) / rate > max_seconds:
raise AudioTooLong()
pcm = (np.clip(samples, -1.0, 1.0) * 32767).astype(np.int16)
return Pcm(pcm, rate)
class GoogleEngine:
"""gTTS ("voz do Google"): MP3 do Google Tradutor, decodificado em memória.
Só tem velocidade normal ou lenta: `speed` ≤ 0,75 usa o modo lento; outros valores saem na velocidade normal.
"""
name = "google"
def __init__(self, timeout_s: float = 60.0):
self._timeout_s = timeout_s
def synthesize(self, voice: Voice, text: str, speed: float, max_seconds: float) -> Pcm:
import io
from .decode import decode_audio
try:
from gtts import gTTS
buffer = io.BytesIO()
gTTS(text, lang=voice.engine_lang or "pt", tld=voice.engine_voice or "com.br", slow=speed <= 0.75,
timeout=self._timeout_s).write_to_fp(buffer)
except Exception as exc: # noqa: BLE001 - rede, DNS, recusa do serviço
raise EngineUnavailable() from exc
mp3 = buffer.getvalue()
if not mp3:
raise InvalidRequest("Texto não gerou áudio.")
samples = decode_audio(mp3, voice.sample_rate, max_seconds, sample_format="s16")
return Pcm(np.ascontiguousarray(samples), voice.sample_rate)
class AzureEngine:
"""Azure Speech pela API REST (sem SDK): SSML → WAV PCM 24 kHz mono, decodificado em memória.
A chave nunca vai para log nem para resposta. 401/403 = chave ou região erradas; 429 = cota do mês ou do minuto.
"""
name = "azure"
def __init__(self, key: str, region: str, timeout_s: float = 60.0):
self._key = key
self._region = region
self._timeout_s = timeout_s
def ssml(self, voice: Voice, text: str, speed: float) -> bytes:
from xml.sax.saxutils import escape, quoteattr
lang = (voice.engine_voice or "pt-BR-x").rsplit("-", 1)[0]
body = (
f"<speak version='1.0' xmlns='http://www.w3.org/2001/10/synthesis' xml:lang={quoteattr(lang)}>"
f"<voice name={quoteattr(voice.engine_voice or '')}>"
f"<prosody rate={quoteattr(edge_rate(speed))}>{escape(text)}</prosody></voice></speak>"
)
return body.encode("utf-8")
def synthesize(self, voice: Voice, text: str, speed: float, max_seconds: float) -> Pcm:
import urllib.error
import urllib.request
from .decode import decode_audio
if not self._key:
raise EngineUnavailable()
request = urllib.request.Request(
f"https://{self._region}.tts.speech.microsoft.com/cognitiveservices/v1",
data=self.ssml(voice, text, speed),
method="POST",
headers={
"Ocp-Apim-Subscription-Key": self._key,
"Content-Type": "application/ssml+xml",
"X-Microsoft-OutputFormat": "riff-24khz-16bit-mono-pcm",
"User-Agent": "cenaforge-voice",
},
)
try:
with urllib.request.urlopen(request, timeout=self._timeout_s) as response: # noqa: S310 - URL fixa https
wav = response.read()
except urllib.error.HTTPError as exc:
if exc.code == 400:
raise InvalidRequest("O Azure recusou o texto ou a voz (confira se a voz existe na sua região).") from exc
raise EngineUnavailable() from exc
except Exception as exc: # noqa: BLE001 - rede, DNS, timeout
raise EngineUnavailable() from exc
if not wav:
raise InvalidRequest("Texto não gerou áudio.")
samples = decode_audio(wav, voice.sample_rate, max_seconds, sample_format="s16")
return Pcm(np.ascontiguousarray(samples), voice.sample_rate)
class CloneEngine:
"""Voz clonada: repassa texto + áudio de referência ao processo de clonagem (voice/clone/worker.py).
O Chatterbox não tem velocidade; `speed` é ignorado. O processo devolve WAV 24 kHz mono.
"""
name = "clone"
def __init__(self, port: int, key: str, timeout_s: float = 90.0):
self._url = f"http://127.0.0.1:{port}/synthesize"
self._key = key
self._timeout_s = timeout_s
def synthesize(self, voice: Voice, text: str, speed: float, max_seconds: float) -> Pcm:
import json
import urllib.error
import urllib.request
from .decode import decode_audio
body = {"text": text, "reference": str(voice.model), "language": voice.engine_lang or "pt", **(voice.clone or {})}
request = urllib.request.Request(
self._url, data=json.dumps(body).encode("utf-8"), method="POST",
headers={"Content-Type": "application/json", "X-Service-Key": self._key},
)
try:
with urllib.request.urlopen(request, timeout=self._timeout_s) as response: # noqa: S310 - 127.0.0.1 fixo
wav = response.read()
except urllib.error.HTTPError as exc:
if exc.code == 400:
raise InvalidRequest("A clonagem recusou o texto ou o áudio de referência.") from exc
raise CloneUnavailable() from exc
except Exception as exc: # noqa: BLE001 - processo fora do ar, porta fechada, timeout
raise CloneUnavailable() from exc
samples = decode_audio(wav, voice.sample_rate, max_seconds, sample_format="s16")
return Pcm(np.ascontiguousarray(samples), voice.sample_rate)
class RoutingEngine:
"""Despacha para o motor da voz (`voice.engine`). Motor ausente = voz fora do catálogo."""
name = "cenaforge-tts"
def __init__(self, engines: dict[str, TtsEngine]):
self.engines = engines
def warmup(self, voice: Voice) -> None:
engine = self.engines.get(voice.engine)
if engine is not None and hasattr(engine, "warmup"):
engine.warmup(voice)
def synthesize(self, voice: Voice, text: str, speed: float, max_seconds: float) -> Pcm:
engine = self.engines.get(voice.engine)
if engine is None:
raise VoiceNotFound()
return engine.synthesize(voice, text, speed, max_seconds)
class FakeEngine:
"""Motor de teste: tom senoidal, ~15 caracteres por segundo. Pode ser bloqueado para testar a fila."""
name = "fake"
def __init__(self, delay_s: float = 0.0):
self.delay_s = delay_s
self.calls = 0
self.gate: threading.Event | None = None
def warmup(self, voice: Voice) -> None: # pragma: no cover - nada a carregar
return None
def synthesize(self, voice: Voice, text: str, speed: float, max_seconds: float) -> Pcm:
self.calls += 1
if self.gate is not None:
self.gate.wait(10)
if self.delay_s:
time.sleep(self.delay_s)
seconds = max(0.3, len(text) / (15.0 * speed))
if seconds > max_seconds:
raise AudioTooLong()
t = np.arange(int(seconds * voice.sample_rate)) / voice.sample_rate
samples = (np.sin(2 * np.pi * 220 * t) * 8000).astype(np.int16)
return Pcm(samples, voice.sample_rate)
+125
View File
@@ -0,0 +1,125 @@
"""Erros de domínio → resposta HTTP padronizada `{"error": {"code", "message"}}`."""
from __future__ import annotations
class ServiceError(Exception):
status = 500
code = "internal_error"
message = "Erro interno."
retry_after: int | None = None
def __init__(self, message: str | None = None, retry_after: int | None = None):
super().__init__(message or self.message)
if message:
self.message = message
if retry_after is not None:
self.retry_after = retry_after
class Unauthorized(ServiceError):
status, code, message = 401, "unauthorized", "Chave de serviço ausente ou inválida."
class InsufficientScope(ServiceError):
"""403: a chave é válida, mas não tem o escopo da operação (ADR 0027 §10)."""
status, code, message = 403, "insufficient_scope", "A chave não tem o escopo desta operação."
def __init__(self, scope: str):
super().__init__()
self.scope = scope
class InvalidRequest(ServiceError):
status, code, message = 422, "invalid_request", "Requisição inválida."
class TextTooLong(ServiceError):
status, code, message = 422, "text_too_long", "Texto acima do limite."
class VoiceNotFound(ServiceError):
status, code, message = 422, "voice_not_found", "Voz fora do catálogo."
class VoiceDetailNotFound(ServiceError):
"""404 de GET /v1/voices/{voiceId} (a síntese continua com 422 voice_not_found)."""
status, code, message = 404, "voice_not_found", "Voz fora do catálogo."
class AudioTooLong(ServiceError):
status, code, message = 422, "audio_too_long", "Áudio passaria do limite de duração."
class IdempotencyConflict(ServiceError):
status, code = 409, "idempotency_conflict"
message = "Este requestId já foi usado com outro conteúdo."
class QueueFull(ServiceError):
status, code, message, retry_after = 503, "queue_full", "Fila cheia.", 5
class QueueTimeout(ServiceError):
status, code, message, retry_after = 503, "queue_timeout", "Tempo de espera na fila esgotado.", 5
class SynthesisTimeout(ServiceError):
status, code, message = 504, "synthesis_timeout", "Síntese passou do tempo limite."
class SynthesisFailed(ServiceError):
status, code, message = 500, "synthesis_failed", "Falha na síntese."
class EngineUnavailable(ServiceError):
# 502: o motor depende de um serviço de fora (Edge TTS) que não respondeu. Tente de novo ou use uma voz offline.
status, code, message, retry_after = 502, "engine_unavailable", "Motor de voz indisponível (sem internet?).", 5
class RvcFailed(ServiceError):
status, code = 422, "rvc_failed"
message = "O modelo RVC desta voz não pôde ser usado (arquivo inválido ou incompatível com o Applio 3.7.0)."
class RvcUnavailable(ServiceError):
status, code, message = 501, "rvc_disabled", "Voz de personagem (RVC) exige o Applio instalado pelo setup."
class CloneUnavailable(ServiceError):
# 503: a voz clonada depende do processo de clonagem (voice/.venv-clone, porta 4511), que não respondeu.
status, code, retry_after = 503, "clone_unavailable", 10
message = "A clonagem de voz não está rodando: rode setup.bat -Clone e reinicie o start.bat."
# ---------- transcrição ----------
class InvalidAudio(ServiceError):
status, code, message = 422, "invalid_audio", "Áudio ilegível ou em formato não suportado."
class AudioTooLarge(ServiceError):
status, code, message = 413, "audio_too_large", "Áudio acima do limite de bytes."
class LanguageNotSupported(ServiceError):
status, code, message = 422, "language_not_supported", "Idioma não atendido."
class SttDisabled(ServiceError):
# 501: configuração do serviço, não sobrecarga (o 503 do serviço quer dizer "fila cheia").
status, code, message = 501, "stt_disabled", "Transcrição desligada neste serviço."
class JobNotFound(ServiceError):
# 410 (e não 404): o 404 genérico do serviço significa rota errada (= `misconfigured` no backend).
status, code, message = 410, "job_not_found", "Job desconhecido ou expirado."
class TranscriptionTimeout(ServiceError):
status, code, message = 504, "transcription_timeout", "Transcrição passou do tempo limite."
class TranscriptionFailed(ServiceError):
status, code, message = 500, "transcription_failed", "Falha na transcrição."
+310
View File
@@ -0,0 +1,310 @@
"""Chaves de serviço nomeadas (ADR 0027 §10): emitir, listar e revogar sem reiniciar o serviço.
Formato: `dvk_<keyId 12>_<segredo 32 bytes em base64url>`.
- O arquivo guarda só o SHA-256 do segredo, mais `keyId`, `name`, `scopes`, `createdAt` e `revokedAt`.
O segredo tem 256 bits, então não precisa de KDF lenta.
- A busca é por `keyId` (não é segredo); a comparação do hash é em tempo constante.
- O arquivo fica no volume de dados (`/data/keys/service_keys.json`), fora do Git. O serviço relê quando ele muda.
- A `VOICE_SERVICE_KEY` do `.env` continua aceita como a chave `env`: partida e recuperação, com todos os escopos.
CLI (dentro do container, que já tem `VOICE_DATA_DIR`):
python -m app.keys create --name backend-prod --scopes tts,transcribe,status
python -m app.keys list
python -m app.keys revoke <keyId>
A chave em claro só aparece na saída do `create`. Nunca vai para log nem para arquivo.
"""
from __future__ import annotations
import argparse
import base64
import contextlib
import hashlib
import hmac
import json
import logging
import os
import re
import secrets
import sys
import threading
from dataclasses import dataclass
from datetime import datetime, timezone
from pathlib import Path
try: # o container é Linux; no Windows (fora do container) o CLI roda sem trava entre processos
import fcntl
except ImportError: # pragma: no cover
fcntl = None # type: ignore[assignment]
SCOPES = ("tts", "transcribe", "convert", "status", "admin")
KEY_PREFIX = "dvk_"
KEY_ID_ALPHABET = "abcdefghijklmnopqrstuvwxyz0123456789"
KEY_ID_LENGTH = 12
SECRET_BYTES = 32
KEY_RE = re.compile(r"^dvk_([a-z0-9]{12})_([A-Za-z0-9_-]{43})$")
KEY_ID_RE = re.compile(r"^[a-z0-9]{12}$")
NAME_RE = re.compile(r"^[A-Za-z0-9._-]{1,64}$")
SHA256_RE = re.compile(r"^[0-9a-f]{64}$")
ENV_KEY_ID = "env"
FILE_VERSION = 1
log = logging.getLogger("cenaforge_voice.keys")
class KeyFileError(RuntimeError):
"""Arquivo de chaves ilegível ou fora do formato."""
@dataclass(frozen=True)
class Principal:
"""Quem chamou: só o que pode aparecer em log e no /v1/status (nunca a chave)."""
key_id: str
name: str
scopes: frozenset[str]
@dataclass(frozen=True)
class KeyRecord:
key_id: str
name: str
scopes: tuple[str, ...]
secret_sha256: str
created_at: str
revoked_at: str | None = None
def to_json(self) -> dict:
return {
"keyId": self.key_id, "name": self.name, "scopes": list(self.scopes),
"secretSha256": self.secret_sha256, "createdAt": self.created_at, "revokedAt": self.revoked_at,
}
def public(self) -> dict:
"""Sem o hash: o que o `list` mostra."""
data = self.to_json()
del data["secretSha256"]
return data
def keys_path(data_dir: Path) -> Path:
return data_dir / "keys" / "service_keys.json"
def _hash_secret(secret: str) -> str:
return hashlib.sha256(secret.encode("ascii")).hexdigest()
def _now() -> str:
return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
def parse_scopes(raw: str) -> tuple[str, ...]:
scopes = sorted({part.strip() for part in raw.split(",") if part.strip()})
if not scopes:
raise ValueError("informe ao menos um escopo")
unknown = [s for s in scopes if s not in SCOPES]
if unknown:
raise ValueError(f"escopo desconhecido: {', '.join(unknown)} (válidos: {', '.join(SCOPES)})")
return tuple(scopes)
def _parse_record(item: object) -> KeyRecord:
if not isinstance(item, dict):
raise KeyFileError("entrada não é objeto")
key_id, name, scopes, digest = item.get("keyId"), item.get("name"), item.get("scopes"), item.get("secretSha256")
created, revoked = item.get("createdAt"), item.get("revokedAt")
if not (isinstance(key_id, str) and KEY_ID_RE.fullmatch(key_id)):
raise KeyFileError("keyId inválido")
if not (isinstance(name, str) and NAME_RE.fullmatch(name)):
raise KeyFileError("name inválido")
if not (isinstance(scopes, list) and scopes and all(isinstance(s, str) and s in SCOPES for s in scopes)):
raise KeyFileError("scopes inválidos")
if not (isinstance(digest, str) and SHA256_RE.fullmatch(digest)):
raise KeyFileError("secretSha256 inválido")
if not isinstance(created, str) or not (revoked is None or isinstance(revoked, str)):
raise KeyFileError("datas inválidas")
return KeyRecord(key_id, name, tuple(sorted(set(scopes))), digest, created, revoked)
def read_records(path: Path) -> list[KeyRecord]:
"""Lê e valida o arquivo inteiro. Arquivo ausente = nenhuma chave nomeada."""
try:
raw = path.read_text(encoding="utf-8")
except FileNotFoundError:
return []
try:
data = json.loads(raw)
except ValueError:
raise KeyFileError("JSON ilegível") from None
if not isinstance(data, dict) or data.get("version") != FILE_VERSION or not isinstance(data.get("keys"), list):
raise KeyFileError("formato do arquivo desconhecido")
records = [_parse_record(item) for item in data["keys"]]
if len({r.key_id for r in records}) != len(records):
raise KeyFileError("keyId repetido")
return records
def _write_records(path: Path, records: list[KeyRecord]) -> None:
"""Grava atômico (arquivo temporário 0600 + rename) para o serviço nunca ler um arquivo pela metade."""
payload = json.dumps({"version": FILE_VERSION, "keys": [r.to_json() for r in records]}, indent=2) + "\n"
tmp = path.with_name(f".{path.name}.{secrets.token_hex(6)}.tmp")
fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
try:
with os.fdopen(fd, "w", encoding="utf-8") as handle:
handle.write(payload)
handle.flush()
os.fsync(handle.fileno())
os.replace(tmp, path)
except BaseException:
with contextlib.suppress(FileNotFoundError):
os.unlink(tmp)
raise
@contextlib.contextmanager
def _locked(path: Path):
"""Trava entre processos do CLI (leitura-alteração-gravação). O serviço só lê."""
path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
if fcntl is None: # pragma: no cover
yield
return
fd = os.open(path.with_name(".lock"), os.O_RDWR | os.O_CREAT, 0o600)
try:
fcntl.flock(fd, fcntl.LOCK_EX)
yield
finally:
fcntl.flock(fd, fcntl.LOCK_UN)
os.close(fd)
def issue_key(path: Path, name: str, scopes: tuple[str, ...]) -> tuple[KeyRecord, str]:
"""Emite uma chave. Devolve o registro e a chave em claro, que o chamador mostra uma vez e descarta."""
if not NAME_RE.fullmatch(name):
raise ValueError("nome inválido: use 1 a 64 caracteres entre letras, números, '.', '_' e '-'")
scopes = parse_scopes(",".join(scopes))
with _locked(path):
records = read_records(path)
taken = {r.key_id for r in records}
key_id = "".join(secrets.choice(KEY_ID_ALPHABET) for _ in range(KEY_ID_LENGTH))
while key_id in taken: # pragma: no cover - 36^12 combinações
key_id = "".join(secrets.choice(KEY_ID_ALPHABET) for _ in range(KEY_ID_LENGTH))
secret = base64.urlsafe_b64encode(secrets.token_bytes(SECRET_BYTES)).decode("ascii").rstrip("=")
record = KeyRecord(key_id, name, scopes, _hash_secret(secret), _now())
_write_records(path, [*records, record])
return record, f"{KEY_PREFIX}{key_id}_{secret}"
def revoke_key(path: Path, key_id: str) -> KeyRecord:
"""Marca `revokedAt` (o registro fica para auditoria). Revogar de novo não muda a data."""
with _locked(path):
records = read_records(path)
for index, record in enumerate(records):
if record.key_id == key_id:
if record.revoked_at is None:
record = KeyRecord(
record.key_id, record.name, record.scopes, record.secret_sha256, record.created_at, _now()
)
records[index] = record
_write_records(path, records)
return record
raise LookupError(key_id)
class KeyRing:
"""Autenticação do serviço: chave `env` + chaves nomeadas do arquivo, relido quando muda.
Arquivo ilegível → nenhuma chave nomeada vale (falha fechada); a chave `env` continua valendo para recuperar.
"""
def __init__(self, path: Path, env_key: str):
self._path = path
self._env_key = env_key.encode("utf-8")
self._env = Principal(ENV_KEY_ID, ENV_KEY_ID, frozenset(SCOPES))
self._lock = threading.Lock()
self._signature: tuple | None = ("never-loaded",)
self._records: dict[str, KeyRecord] = {}
# Hash fixo para a comparação quando o keyId não existe: o tempo não diz se o keyId existe.
self._dummy = _hash_secret(secrets.token_urlsafe(SECRET_BYTES))
def _stat_signature(self) -> tuple | None:
try:
st = os.stat(self._path)
except FileNotFoundError:
return None
return (st.st_ino, st.st_mtime_ns, st.st_size)
def _refresh(self) -> None:
signature = self._stat_signature()
if signature == self._signature:
return
with self._lock:
if signature == self._signature:
return
try:
records = {r.key_id: r for r in read_records(self._path)}
except (KeyFileError, OSError) as exc:
records = {}
log.error("arquivo de chaves rejeitado (%s); só a chave env vale até ele ser corrigido", exc)
self._records = records
self._signature = signature
active = sum(1 for r in records.values() if r.revoked_at is None)
log.info("chaves de serviço carregadas: %d ativa(s), %d revogada(s)", active, len(records) - active)
def authenticate(self, provided: str) -> Principal | None:
self._refresh()
match = KEY_RE.fullmatch(provided)
principal: Principal | None = None
if match:
key_id, secret = match.groups()
record = self._records.get(key_id)
expected = record.secret_sha256 if record else self._dummy
if hmac.compare_digest(_hash_secret(secret), expected) and record and record.revoked_at is None:
principal = Principal(record.key_id, record.name, frozenset(record.scopes))
# A chave env é sempre comparada (tempo constante em relação ao conteúdo), casando ou não com o formato dvk_.
env_ok = hmac.compare_digest(provided.encode("utf-8"), self._env_key)
if principal is None and env_ok:
principal = self._env
return principal
def _data_dir() -> Path:
return Path(os.environ.get("VOICE_DATA_DIR", "/data"))
def main(argv: list[str] | None = None) -> int:
parser = argparse.ArgumentParser(prog="python -m app.keys", description="Chaves de serviço do dropsz_voice.")
sub = parser.add_subparsers(dest="command", required=True)
create = sub.add_parser("create", aliases=["issue"], help="emite uma chave e mostra-a uma única vez")
create.add_argument("--name", required=True)
create.add_argument("--scopes", required=True, help=f"lista separada por vírgula: {','.join(SCOPES)}")
sub.add_parser("list", help="lista as chaves (sem segredo nem hash)")
revoke = sub.add_parser("revoke", help="revoga uma chave pelo keyId")
revoke.add_argument("key_id")
args = parser.parse_args(argv)
path = keys_path(_data_dir())
try:
if args.command in ("create", "issue"):
record, plaintext = issue_key(path, args.name, parse_scopes(args.scopes))
print(f"keyId: {record.key_id}\nname: {record.name}\nscopes: {','.join(record.scopes)}")
print("chave (aparece só agora; guarde no cofre do backend):")
print(plaintext)
elif args.command == "list":
print(json.dumps([r.public() for r in read_records(path)], indent=2, ensure_ascii=False))
else:
if not KEY_ID_RE.fullmatch(args.key_id):
print("keyId inválido", file=sys.stderr)
return 2
record = revoke_key(path, args.key_id)
print(f"revogada: {record.key_id} ({record.name}) em {record.revoked_at}")
except LookupError:
print("keyId não encontrado", file=sys.stderr)
return 1
except (ValueError, KeyFileError) as exc:
print(f"erro: {exc}", file=sys.stderr)
return 2
return 0
if __name__ == "__main__": # pragma: no cover
raise SystemExit(main())
+507
View File
@@ -0,0 +1,507 @@
"""App FastAPI do serviço de voz do CenaForge (base: dropsz_voice). Toda rota exige uma chave de serviço com o
escopo dela; sem /docs públicos. Escuta só em 127.0.0.1 (porta 4510, faixa 4500–4599 do CenaForge)."""
from __future__ import annotations
import base64
import hashlib
import json
import logging
import re
import unicodedata
from contextlib import asynccontextmanager
from fastapi import FastAPI, Request
from fastapi.exceptions import RequestValidationError
from fastapi.responses import FileResponse, JSONResponse
from starlette.exceptions import HTTPException as StarletteHTTPException
from .audio import MEDIA_TYPES
from .catalog import ONLINE_ENGINES, Voice, load_catalog, load_lock, sha256_file
from .config import ConfigError, Settings
from .device import DeviceInfo, resolve_device, stt_compute_type
from .engine import AzureEngine, CloneEngine, EdgeEngine, GoogleEngine, KokoroEngine, PiperEngine, RoutingEngine, TtsEngine
from .errors import (
AudioTooLarge, InsufficientScope, InvalidRequest, RvcUnavailable, ServiceError, SttDisabled, Unauthorized,
VoiceDetailNotFound,
)
from .keys import KeyRing, Principal, keys_path
from .schemas import SynthesizeRequest, VoiceDescriptor, VoicesPage
from .service import VoiceService
from .store import Store
from .stt import DETAILS, MODEL_FILES, SttEngine
from .transcription import TranscriptionJob, TranscriptionService
from .work_queue import WorkQueue
KEY_HEADER = "X-Service-Key"
VERSION = "2.0.0"
# Mesmo padrão do contrato `voice` do backend (VOICE_IDEMPOTENCY_KEY_PATTERN).
IDEMPOTENCY_KEY_RE = re.compile(r"^[A-Za-z0-9:_.-]{1,128}$")
JOB_REF_RE = re.compile(r"^[A-Za-z0-9_-]{8,64}$")
VOICE_ID_RE = re.compile(r"^[A-Za-z0-9_-]{1,64}$")
CURSOR_RE = re.compile(r"^[A-Za-z0-9_-]{1,512}$")
DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE, MAX_QUERY_CHARS = 50, 100, 64
# Qualquer áudio que o PyAV decodifique; o tipo só filtra lixo óbvio antes de ler o corpo.
AUDIO_CONTENT_TYPES = (
"audio/ogg", "application/ogg", "audio/opus", "audio/wav", "audio/x-wav", "audio/wave", "audio/mpeg",
"audio/mp3", "audio/mp4", "audio/m4a", "audio/x-m4a", "audio/flac", "audio/x-flac", "audio/webm",
"video/mp4", "video/webm", "application/octet-stream",
)
def required_scope(path: str) -> str | None:
"""Escopo exigido por caminho. Caminho desconhecido → None (segue para o 404/405 de sempre)."""
if path == "/v1/status":
return "status"
if path == "/v1/voices/reload":
return "admin"
if path in ("/v1/synthesize", "/v1/voices") or path.startswith("/v1/voices/"):
return "tts"
if path == "/v1/transcribe" or path.startswith("/v1/transcribe/"):
return "transcribe"
return None
def _error_body(exc: ServiceError) -> dict:
error: dict = {"code": exc.code, "message": exc.message}
if isinstance(exc, InsufficientScope):
error["requiredScope"] = exc.scope
return {"error": error}
logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s %(message)s")
def _load_stt(settings: Settings, device: DeviceInfo) -> SttEngine:
"""Confere o modelo local contra o models.lock.json (sha256) e carrega o faster-whisper.
Na GPU, se o CUDA falhar na carga (DLL faltando, driver velho), cai para a CPU em vez de não subir.
"""
from .stt import FasterWhisperEngine
lock = load_lock(settings.lock_path)
for name in MODEL_FILES[settings.stt_model]:
rel = f"whisper/{settings.stt_model}/{name}"
if rel not in lock:
raise ConfigError(f"stt: {rel} não está no models.lock.json")
path = settings.models_dir / rel
if not path.is_file():
raise ConfigError(
f"stt: modelo ausente ({rel}); rode scripts/fetch_models.py --group stt-{settings.stt_model}"
)
if settings.verify_models and sha256_file(path) != lock[rel]["sha256"]:
raise ConfigError(f"stt: checksum diferente do lock ({rel})")
model_dir = settings.models_dir / "whisper" / settings.stt_model
args = (settings.stt_threads, settings.stt_beam_size, settings.stt_vad, settings.stt_max_chars)
if device.kind == "cuda":
try:
engine = FasterWhisperEngine(
model_dir, settings.stt_model, "cuda", stt_compute_type(settings.stt_compute_type, device), *args
)
# O CTranslate2 só carrega cuBLAS/cuDNN na primeira inferência: sem este aquecimento a GPU "existe" na
# subida e a primeira legenda quebra com RuntimeError (DLL ausente). Medido no Windows sem nvidia-*-cu12.
engine.warmup()
return engine
except Exception as exc: # noqa: BLE001 - CUDA presente mas inutilizável
logging.getLogger("cenaforge_voice").warning(
"stt: CUDA falhou no aquecimento (%s: %s); usando CPU", type(exc).__name__, str(exc)[:160]
)
cpu = DeviceInfo("cpu", None, "fallback")
return FasterWhisperEngine(
model_dir, settings.stt_model, "cpu", stt_compute_type(settings.stt_compute_type, cpu), *args
)
def _transcription_response(service: TranscriptionService, job: TranscriptionJob, replay: bool) -> JSONResponse:
headers = {"X-Job-Ref": job.ref, "X-Idempotent-Replay": "true" if replay else "false", "Cache-Control": "no-store"}
if job.error is not None:
raise job.error
if job.result is None:
payload = {"status": "pending", "jobRef": job.ref, "retryAfterMs": service.retry_after_ms(job)}
return JSONResponse(payload, status_code=202, headers=headers)
payload: dict = {"status": "ready", "text": job.result.text, "noSpeechProb": round(job.result.no_speech_prob, 4)}
if job.detail != "text":
payload["durationS"] = round(job.result.duration_s, 3)
payload["segments"] = [
{
"start": seg.start, "end": seg.end, "text": seg.text,
**({"words": [{"start": w.start, "end": w.end, "text": w.text, "p": w.probability} for w in seg.words]}
if job.detail == "words" else {}),
}
for seg in job.result.segments
]
return JSONResponse(payload, status_code=200, headers=headers)
async def _read_capped(request: Request, max_bytes: int) -> bytes:
"""Lê o corpo cru até `max_bytes`; passou disso, para de ler e recusa (sem bufferizar o resto)."""
declared = request.headers.get("content-length", "")
if declared.isascii() and declared.isdigit() and int(declared) > max_bytes:
raise AudioTooLarge()
chunks: list[bytes] = []
total = 0
async for chunk in request.stream():
total += len(chunk)
if total > max_bytes:
raise AudioTooLarge()
chunks.append(chunk)
return b"".join(chunks)
def create_app(
settings: Settings | None = None, engine: TtsEngine | None = None, stt_engine: SttEngine | None = None
) -> FastAPI:
settings = settings or Settings.from_env()
# Chave env (VOICE_SERVICE_KEY, todos os escopos) + chaves nomeadas do volume de dados, relidas quando mudam.
keyring = KeyRing(keys_path(settings.data_dir), settings.service_key)
log = logging.getLogger("cenaforge_voice")
def _catalog_stamp() -> tuple:
"""Data de modificação e tamanho dos arquivos de catálogo; muda quando alguém edita um deles."""
stamp = []
for path in (settings.catalog_path, settings.lock_path, settings.user_catalog_path):
try:
info = path.stat() if path is not None else None
stamp.append((info.st_mtime_ns, info.st_size) if info else None)
except OSError:
stamp.append(None)
return tuple(stamp)
def _load_voices() -> dict[str, Voice]:
app.state.catalog_stamp = _catalog_stamp()
voices = load_catalog(
settings.catalog_path, settings.lock_path, settings.models_dir, settings.verify_models,
settings.user_catalog_path,
)
if settings.azure_key:
return voices
# Sem chave do Azure, as vozes dele (e as de personagem feitas em cima delas) ficam fora da lista.
azure = {v.id for v in voices.values() if v.engine == "azure"}
return {k: v for k, v in voices.items() if v.id not in azure and v.base_voice not in azure}
def _install_voices(service: VoiceService, voices: dict[str, Voice]) -> None:
for voice in voices.values():
if hasattr(service.engine, "warmup"):
service.engine.warmup(voice)
service.voices = voices
def _refresh_voices_if_changed(service: VoiceService) -> None:
"""Relê o catálogo quando um dos arquivos mudou: voz nova aparece sem reiniciar o serviço.
Se o catálogo novo estiver com defeito (ex.: peso ainda não baixado), mantém as vozes atuais e avisa
no log; a próxima mudança no arquivo tenta de novo.
"""
if getattr(app.state, "catalog_stamp", None) == _catalog_stamp():
return
try:
voices = _load_voices()
except (ConfigError, OSError, ValueError, KeyError) as error:
log.warning("catálogo mudou mas não carregou; mantendo as vozes atuais: %s", error)
return
_install_voices(service, voices)
log.info("catálogo mudou; vozes recarregadas: %d", len(voices))
@asynccontextmanager
async def lifespan(app: FastAPI):
# Testes injetam motores falsos: aí não há GPU a procurar.
device = (
DeviceInfo("cpu", None, "motores injetados") if engine is not None else resolve_device(settings.device)
)
log.info("dispositivo: %s (%s)%s", device.kind, device.reason, f" — {device.name}" if device.name else "")
app.state.device = device
voices = _load_voices()
tts = engine or RoutingEngine({
"piper": PiperEngine(settings.onnx_threads), "edge": EdgeEngine(),
"kokoro": KokoroEngine(settings.onnx_threads), "google": GoogleEngine(),
"azure": AzureEngine(settings.azure_key, settings.azure_region),
"clone": CloneEngine(settings.clone_port, settings.service_key, settings.synth_timeout_s),
})
if settings.enable_rvc:
from .rvc import ApplioRvcEngine # importa torch/Applio só quando o setup instalou o RVC
tts = ApplioRvcEngine(tts, settings.applio_dir)
for voice in voices.values():
if hasattr(tts, "warmup"):
tts.warmup(voice)
settings.data_dir.mkdir(parents=True, exist_ok=True)
store = Store(settings.data_dir, settings.cache_max_mb, settings.idempotency_ttl_h)
for old, new in Settings.retired_vars_in_env():
log.warning("config: %s não vale mais e foi ignorada; a fila agora é por chave (%s)", old, new)
for warning in settings.timeout_warnings():
log.warning("config: %s", warning)
queue = WorkQueue(
settings.max_concurrency, settings.max_queue_per_key, settings.queue_timeout_s, settings.synth_timeout_s
)
app.state.service = VoiceService(settings, voices, tts, store, queue)
# Transcrição: fila própria (não toma a vaga do TTS); motor carregado e conferido na subida.
stt = stt_engine or (_load_stt(settings, device) if settings.enable_stt else None)
if stt is not None:
log.info("transcrição: %s", stt.name)
stt_queue = WorkQueue(
settings.stt_max_concurrency, settings.stt_max_queue_per_key, settings.stt_queue_timeout_s,
settings.stt_timeout_s,
)
app.state.transcription = TranscriptionService(settings, stt, store, stt_queue) if stt else None
try:
yield
finally:
stt_queue.shutdown()
queue.shutdown()
store.close()
# Desligamos /docs, /redoc e /openapi.json: nada é público. O contrato está no README.
app = FastAPI(
title="cenaforge_voice", version=VERSION, docs_url=None, redoc_url=None, openapi_url=None, lifespan=lifespan
)
@app.middleware("http")
async def require_key(request: Request, call_next):
# Única rota sem chave: GET /health, liveness (o pnpm dev e o painel usam), sem nenhum dado.
if request.method == "GET" and request.url.path == "/health":
return await call_next(request)
# Antes de tudo (inclusive 404 e JSON malformado): sem chave válida, 401; sem o escopo da rota, 403.
principal = keyring.authenticate(request.headers.get(KEY_HEADER, ""))
if principal is None:
error: ServiceError = Unauthorized()
return JSONResponse(_error_body(error), status_code=error.status)
scope = required_scope(request.url.path)
if scope is not None and scope not in principal.scopes:
log.warning("chave sem escopo: keyId=%s escopo=%s", principal.key_id, scope)
error = InsufficientScope(scope)
return JSONResponse(_error_body(error), status_code=error.status)
request.state.principal = principal
return await call_next(request)
@app.exception_handler(ServiceError)
async def _service_error(_: Request, exc: ServiceError) -> JSONResponse:
headers = {"Retry-After": str(exc.retry_after)} if exc.retry_after else None
return JSONResponse(_error_body(exc), status_code=exc.status, headers=headers)
@app.exception_handler(RequestValidationError)
async def _validation_error(_: Request, exc: RequestValidationError) -> JSONResponse:
# Só o caminho e o tipo do erro — nunca o valor recebido (pode ser o texto do espectador).
fields = [{"field": ".".join(str(p) for p in e["loc"][1:]), "type": e["type"]} for e in exc.errors()]
return JSONResponse(
{"error": {"code": "invalid_request", "message": "Requisição inválida.", "fields": fields}}, status_code=422
)
@app.exception_handler(StarletteHTTPException)
async def _http_error(_: Request, exc: StarletteHTTPException) -> JSONResponse:
# 400 (corpo ilegível), 404, 405... no mesmo formato do contrato.
codes = {400: "invalid_request", 404: "not_found", 405: "method_not_allowed"}
code = codes.get(exc.status_code, "http_error")
return JSONResponse({"error": {"code": code, "message": "Requisição inválida."}}, status_code=exc.status_code)
@app.exception_handler(Exception)
async def _unexpected(_: Request, exc: Exception) -> JSONResponse:
log.error("erro inesperado: %s", type(exc).__name__)
return JSONResponse({"error": {"code": "internal_error", "message": "Erro interno."}}, status_code=500)
@app.get("/health")
async def health() -> JSONResponse:
"""Liveness sem dado e sem chave. O estado operacional fica só no /v1/status."""
return JSONResponse({"status": "ok"}, headers={"Cache-Control": "no-store"})
def _uses_rvc(voice: Voice) -> bool:
return bool(voice.rvc) and settings.enable_rvc
def _voice_operations(voice: Voice) -> list[str]:
return ["tts", "convert"] if _uses_rvc(voice) else ["tts"]
@app.get("/v1/status")
async def status(request: Request) -> JSONResponse:
"""Estado para o painel: dispositivo, motores, operações, filas, vozes e a própria chave. Sem caminho nem URL."""
service: VoiceService = request.app.state.service
transcription: TranscriptionService | None = request.app.state.transcription
principal: Principal = request.state.principal
operations = ["tts"] + (["transcribe"] if transcription else []) + (["convert"] if settings.enable_rvc else [])
items = [
{"id": v.id, "revision": v.revision, "operations": _voice_operations(v)}
for v in sorted(service.voices.values(), key=lambda v: v.id)
]
# Hash do catálogo (id + revision + operações): servidores com o mesmo hash têm as mesmas vozes (§6).
canonical = json.dumps(items, separators=(",", ":"), sort_keys=True).encode("utf-8")
device: DeviceInfo = request.app.state.device
payload = {
"status": "ok",
"version": VERSION,
"device": {"kind": device.kind, "name": device.name, "reason": device.reason},
"rvc": settings.enable_rvc,
"azure": {"configured": bool(settings.azure_key), "region": settings.azure_region},
"engines": {"tts": service.engine.name, "transcribe": transcription.engine.name if transcription else None},
"operations": operations,
"queues": {
"synthesis": _queue_state(service.queue, principal.key_id),
"transcription": _stt_queue(request, principal.key_id),
},
"voices": {"count": len(items), "catalogHash": hashlib.sha256(canonical).hexdigest(), "items": items},
"key": {"keyId": principal.key_id, "name": principal.name, "scopes": sorted(principal.scopes)},
}
return JSONResponse(payload, headers={"Cache-Control": "no-store"})
def _queue_state(queue: WorkQueue, key_id: str) -> dict:
# `waiting`/`maxQueue` são a fila DESTA chave (a cota é por chave); `running`/`maxConcurrency`, a CPU
# compartilhada. Assim o backend de uma stack só vê "fila cheia" quando a cota dele acabou.
return {
"running": queue.running, "waiting": queue.waiting_for(key_id),
"maxConcurrency": queue.max_concurrency, "maxQueue": queue.max_queue_per_key,
}
def _stt_queue(request: Request, key_id: str) -> dict | None:
transcription: TranscriptionService | None = request.app.state.transcription
return _queue_state(transcription.queue, key_id) if transcription else None
def _transcription(request: Request) -> TranscriptionService:
transcription: TranscriptionService | None = request.app.state.transcription
if transcription is None:
raise SttDisabled()
return transcription
def _descriptor(voice: Voice) -> VoiceDescriptor:
rvc = None
if voice.rvc:
# Só os parâmetros: nunca o caminho do arquivo.
rvc = {k: voice.rvc[k] for k in ("pitch", "f0Method", "indexRate", "protect")}
rvc["hasIndex"] = bool(voice.rvc.get("indexPath"))
return VoiceDescriptor(
id=voice.id, name=voice.name, languages=[voice.language], revision=voice.revision,
engine="tts+rvc" if voice.rvc else "tts", default=voice.default,
description=voice.description, gender=voice.gender, ageRange=voice.age_range, accent=voice.accent,
provider=voice.engine, baseVoice=voice.base_voice, user=voice.user,
offline=voice.engine not in ONLINE_ENGINES, rvc=rvc,
)
def _fold(text: str) -> str:
"""Minúsculas e sem acento, para a busca."""
decomposed = unicodedata.normalize("NFKD", text.casefold())
return "".join(c for c in decomposed if not unicodedata.combining(c))
def _decode_cursor(raw: str | None) -> str | None:
"""Cursor opaco = id da última voz entregue (base64url). Inválido → 422."""
if raw is None:
return None
try:
if not CURSOR_RE.fullmatch(raw):
raise ValueError
return base64.urlsafe_b64decode(raw + "=" * (-len(raw) % 4)).decode("utf-8")
except ValueError:
raise InvalidRequest("cursor inválido.") from None
@app.get("/v1/voices", response_model=VoicesPage)
async def voices(
request: Request, cursor: str | None = None, limit: str = str(DEFAULT_PAGE_SIZE), query: str | None = None
) -> VoicesPage:
service: VoiceService = request.app.state.service
_refresh_voices_if_changed(service)
if not (limit.isascii() and limit.isdigit() and 1 <= int(limit) <= MAX_PAGE_SIZE):
raise InvalidRequest("limit precisa estar entre 1 e 100.")
if query is not None and len(query) > MAX_QUERY_CHARS:
raise InvalidRequest("query acima de 64 caracteres.")
after = _decode_cursor(cursor)
needle = _fold(query.strip()) if query else ""
# Ordem estável por id; o cursor guarda o último id entregue (não sofre com inserções no meio).
matching = sorted(
(v for v in service.voices.values() if not needle or needle in _fold(v.id) or needle in _fold(v.name)),
key=lambda v: v.id,
)
if after is not None:
matching = [v for v in matching if v.id > after]
size = int(limit)
page = matching[:size]
next_cursor = None
if len(matching) > size:
next_cursor = base64.urlsafe_b64encode(page[-1].id.encode("utf-8")).decode("ascii").rstrip("=")
return VoicesPage(items=[_descriptor(v) for v in page], nextCursor=next_cursor)
@app.post("/v1/voices/reload")
async def reload_voices(request: Request) -> JSONResponse:
"""Relê o catálogo e as vozes do usuário (o painel chama depois de adicionar ou remover uma voz)."""
service: VoiceService = request.app.state.service
voices = _load_voices()
_install_voices(service, voices)
log.info("vozes recarregadas: %d", len(voices))
return JSONResponse({"status": "ok", "count": len(voices)}, headers={"Cache-Control": "no-store"})
@app.get("/v1/voices/{voice_id}", response_model=VoiceDescriptor)
async def voice_detail(voice_id: str, request: Request) -> VoiceDescriptor:
service: VoiceService = request.app.state.service
_refresh_voices_if_changed(service)
voice = service.voices.get(voice_id) if VOICE_ID_RE.fullmatch(voice_id) else None
if voice is None:
raise VoiceDetailNotFound()
return _descriptor(voice)
@app.post("/v1/synthesize")
async def synthesize(body: SynthesizeRequest, request: Request) -> FileResponse:
service: VoiceService = request.app.state.service
_refresh_voices_if_changed(service)
voice = service.voices.get(body.voiceId)
if voice is not None and voice.rvc and not settings.enable_rvc:
raise RvcUnavailable()
# Voz com RVC exige também o escopo convert.
if voice is not None and _uses_rvc(voice) and "convert" not in request.state.principal.scopes:
log.warning("chave sem escopo: keyId=%s escopo=convert", request.state.principal.key_id)
raise InsufficientScope("convert")
result = await service.synthesize(body, request.state.principal.key_id)
return FileResponse(
result.audio.path,
media_type=MEDIA_TYPES[body.params.format],
headers={
"X-Request-Id": body.requestId,
"X-Voice-Id": body.voiceId,
"X-Cache": "hit" if result.cache_hit else "miss",
"X-Idempotent-Replay": "true" if result.replay else "false",
"X-Audio-Duration-Ms": str(result.audio.duration_ms),
"X-Audio-Sha256": result.audio.sha256,
"Cache-Control": "no-store",
},
)
@app.post("/v1/transcribe")
async def transcribe(request: Request) -> JSONResponse:
"""Corpo = bytes de áudio crus (WAV, MP3, OGG, M4A...). Metadados em cabeçalhos, validados antes do corpo.
`X-Detail`: text (padrão) | segments | words — os dois últimos trazem tempos para legenda.
"""
transcription = _transcription(request)
idempotency_key = request.headers.get("X-Idempotency-Key", "")
duration = request.headers.get("X-Audio-Duration-Ms", "")
language = request.headers.get("X-Language", "")
detail = request.headers.get("X-Detail", "text")
content_type = request.headers.get("content-type", "").split(";")[0].strip().lower()
if not IDEMPOTENCY_KEY_RE.fullmatch(idempotency_key):
raise InvalidRequest("X-Idempotency-Key ausente ou inválida.")
# Opcional no CenaForge (o painel recebe arquivos sem saber a duração): sem ele, vale só o teto da
# decodificação, que para de ler ao passar de VOICE_STT_MAX_AUDIO_S.
if duration == "":
duration = "0"
elif not (duration.isascii() and duration.isdigit() and 1 <= int(duration) <= 10_000_000):
raise InvalidRequest("X-Audio-Duration-Ms inválida.")
if content_type not in AUDIO_CONTENT_TYPES:
raise InvalidRequest("Content-Type precisa ser de áudio (wav, mp3, ogg, m4a, flac, webm).")
if detail not in DETAILS:
raise InvalidRequest(f"X-Detail precisa ser um de {', '.join(DETAILS)}.")
transcription.validate(0, int(duration), language, detail) # idioma e duração antes de ler o corpo
audio = await _read_capped(request, settings.stt_max_bytes)
if not audio:
raise InvalidRequest("Corpo vazio.")
job, replay = await transcription.submit(
audio, int(duration), language, idempotency_key, request.state.principal.key_id, detail
)
await transcription.wait(job, settings.stt_sync_wait_s)
return _transcription_response(transcription, job, replay)
@app.get("/v1/transcribe/jobs/{job_ref}")
async def transcription_job(job_ref: str, request: Request) -> JSONResponse:
transcription = _transcription(request)
if not JOB_REF_RE.fullmatch(job_ref):
raise InvalidRequest("jobRef inválido.")
job = transcription.get(job_ref, request.state.principal.key_id)
return _transcription_response(transcription, job, replay=False)
return app
def build() -> FastAPI: # pragma: no cover - ponto de entrada do uvicorn (--factory)
return create_app()
+84
View File
@@ -0,0 +1,84 @@
"""Etapa RVC (Applio 3.7.0 em voice/vendor/applio, instalado pelo setup.bat).
Envolve um motor de TTS: gera a fala com a voz base e converte o timbre com o `VoiceConverter` do Applio.
Só roda para vozes com o bloco `rvc` (vozes de personagem adicionadas pelo painel) e com VOICE_ENABLE_RVC=1.
O Applio escolhe a GPU sozinho (torch.cuda); com VOICE_DEVICE=cpu o CUDA fica invisível para ele.
"""
from __future__ import annotations
import logging
import os
import sys
import tempfile
import threading
from pathlib import Path
import numpy as np
import soundfile
from .catalog import Voice
from .engine import Pcm, TtsEngine
from .errors import RvcFailed, RvcUnavailable
log = logging.getLogger("cenaforge_voice")
class ApplioRvcEngine:
def __init__(self, inner: TtsEngine, applio_dir: Path):
self.inner = inner
self.name = f"{inner.name}+rvc"
self._applio_dir = applio_dir
self._converter = None
self._lock = threading.Lock()
def warmup(self, voice: Voice) -> None:
if hasattr(self.inner, "warmup"):
self.inner.warmup(voice)
def _get_converter(self):
with self._lock:
if self._converter is None:
if not (self._applio_dir / "rvc" / "infer" / "infer.py").is_file():
raise RvcUnavailable()
# O Applio resolve rvc/models/... relativo ao diretório atual.
os.chdir(self._applio_dir)
if str(self._applio_dir) not in sys.path:
sys.path.insert(0, str(self._applio_dir))
from rvc.infer.infer import VoiceConverter # type: ignore[import-not-found]
self._converter = VoiceConverter()
return self._converter
def synthesize(self, voice: Voice, text: str, speed: float, max_seconds: float) -> Pcm:
pcm = self.inner.synthesize(voice, text, speed, max_seconds)
if not voice.rvc:
return pcm
rvc = voice.rvc
converter = self._get_converter()
with tempfile.TemporaryDirectory(prefix="rvc-") as tmp:
src, dst = Path(tmp, "in.wav"), Path(tmp, "out.wav")
soundfile.write(src, pcm.samples, pcm.sample_rate, subtype="PCM_16")
try:
self._convert(converter, rvc, src, dst)
data, rate = soundfile.read(dst, dtype="int16")
except Exception as exc: # noqa: BLE001 - .pth sem "config"/"weight", índice quebrado, saída ausente
log.error("rvc: voz=%s falhou (%s: %s)", voice.id, type(exc).__name__, str(exc)[:160])
raise RvcFailed() from exc
if data.ndim > 1:
data = data[:, 0]
return Pcm(np.ascontiguousarray(data), rate)
@staticmethod
def _convert(converter, rvc: dict, src: Path, dst: Path) -> None:
converter.convert_audio(
audio_input_path=str(src),
audio_output_path=str(dst),
model_path=str(rvc["modelPath"]),
index_path=str(rvc["indexPath"]) if rvc.get("indexPath") else "",
pitch=int(rvc.get("pitch", 0)),
f0_method=rvc.get("f0Method", "rmvpe"),
index_rate=float(rvc.get("indexRate", 0.5)),
protect=float(rvc.get("protect", 0.33)),
export_format="WAV",
)
+75
View File
@@ -0,0 +1,75 @@
"""Contrato HTTP v1 do serviço de voz do CenaForge (herdado do dropsz_voice; campos em camelCase)."""
from __future__ import annotations
import re
import unicodedata
from typing import Literal
from pydantic import BaseModel, ConfigDict, Field, field_validator
# Limite duro do schema; o limite efetivo (VOICE_MAX_TEXT_CHARS) é aplicado no serviço.
HARD_TEXT_LIMIT = 5000
REQUEST_ID_PATTERN = r"^[A-Za-z0-9_-]{8,64}$"
VOICE_ID_PATTERN = r"^[a-z0-9][a-z0-9-]{1,47}$"
_CONTROL = re.compile(r"[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]")
_SPACES = re.compile(r"\s+")
def normalize_text(text: str) -> str:
"""NFC, sem caracteres de controle, espaços colapsados. É o texto que vira chave de cache."""
text = unicodedata.normalize("NFC", text)
text = _CONTROL.sub(" ", text)
return _SPACES.sub(" ", text).strip()
class SynthesisParams(BaseModel):
model_config = ConfigDict(extra="forbid")
speed: float = Field(1.0, ge=0.5, le=2.0, description="1.0 = normal; 2.0 = duas vezes mais rápido")
# wav = para o render (FFmpeg mistura sem perda); ogg_opus = leve, para ouvir no painel.
format: str = Field("ogg_opus", pattern=r"^(ogg_opus|wav)$")
class SynthesizeRequest(BaseModel):
model_config = ConfigDict(extra="forbid")
requestId: str = Field(..., pattern=REQUEST_ID_PATTERN)
text: str = Field(..., min_length=1, max_length=HARD_TEXT_LIMIT)
voiceId: str = Field(..., pattern=VOICE_ID_PATTERN)
params: SynthesisParams = Field(default_factory=SynthesisParams)
@field_validator("text")
@classmethod
def _normalize(cls, value: str) -> str:
value = normalize_text(value)
if not value:
raise ValueError("texto vazio")
return value
class VoiceDescriptor(BaseModel):
"""Descritor público de voz (ADR 0025 §2.3). Sem caminho de arquivo, URL ou origem interna."""
id: str
name: str
languages: list[str]
revision: str
engine: Literal["tts", "tts+rvc"]
default: bool
# Campos do CenaForge: motor base, voz base (vozes de personagem) e se veio do painel.
provider: Literal["piper", "edge", "kokoro", "google", "azure", "clone", "fake"] | None = None
baseVoice: str | None = None
user: bool = False
offline: bool | None = None
rvc: dict | None = None
description: str | None = None
gender: Literal["female", "male", "neutral"] | None = None
ageRange: Literal["child", "young", "adult", "senior"] | None = None
accent: str | None = None
class VoicesPage(BaseModel):
items: list[VoiceDescriptor]
nextCursor: str | None
+113
View File
@@ -0,0 +1,113 @@
"""Orquestra um pedido de síntese: idempotência → cache → deduplicação em voo → fila → motor → Opus."""
from __future__ import annotations
import asyncio
import hashlib
import json
import logging
import time
from dataclasses import dataclass
from .audio import encode
from .catalog import Voice
from .config import Settings
from .engine import TtsEngine
from .errors import IdempotencyConflict, TextTooLong, VoiceNotFound
from .schemas import SynthesizeRequest
from .store import CachedAudio, Store
from .work_queue import WorkQueue
log = logging.getLogger("cenaforge_voice")
CACHE_SCHEMA = 3 # suba quando mudar o formato de saída ou o pipeline
@dataclass(frozen=True)
class SynthesisResult:
audio: CachedAudio
cache_hit: bool
replay: bool
def cache_key_for(voice: Voice, engine_name: str, text: str, speed: float, fmt: str, bitrate: int) -> str:
payload = {
"schema": CACHE_SCHEMA,
"engine": engine_name,
"voice": voice.id,
"voiceRev": voice.revision,
"text": text,
"params": {"speed": round(speed, 2), "format": fmt, "bitrate": bitrate},
}
return hashlib.sha256(json.dumps(payload, sort_keys=True, ensure_ascii=False).encode("utf-8")).hexdigest()
class VoiceService:
def __init__(self, settings: Settings, voices: dict[str, Voice], engine: TtsEngine, store: Store, queue: WorkQueue):
self.settings = settings
self.voices = voices
self.engine = engine
self.store = store
self.queue = queue
# Deduplicação em voo por (keyId, chave de cache): uma chave nunca herda a espera (nem o erro de fila)
# da outra. O cache em disco segue global por conteúdo.
self._inflight: dict[tuple[str, str], asyncio.Future[CachedAudio]] = {}
async def synthesize(self, req: SynthesizeRequest, key_id: str) -> SynthesisResult:
voice = self.voices.get(req.voiceId)
if voice is None:
raise VoiceNotFound()
if len(req.text) > self.settings.max_text_chars:
raise TextTooLong(f"Texto acima de {self.settings.max_text_chars} caracteres.")
speed = round(req.params.speed, 2)
key = cache_key_for(voice, self.engine.name, req.text, speed, req.params.format, self.settings.opus_bitrate)
is_new, bound_key = self.store.bind_request(key_id, req.requestId, key)
if bound_key != key:
raise IdempotencyConflict()
replay = not is_new
cached = self.store.get(key)
if cached is not None:
self._log(req, key_id, voice, "hit", replay, cached.duration_ms, 0.0)
return SynthesisResult(cached, cache_hit=True, replay=replay)
# Mesmo conteúdo já sendo gerado (outro requestId ou retry): espera o mesmo resultado.
inflight_key = (key_id, key)
pending = self._inflight.get(inflight_key)
if pending is not None:
audio = await asyncio.shield(pending)
self._log(req, key_id, voice, "inflight", replay, audio.duration_ms, 0.0)
return SynthesisResult(audio, cache_hit=True, replay=replay)
future: asyncio.Future[CachedAudio] = asyncio.get_running_loop().create_future()
self._inflight[inflight_key] = future
started = time.perf_counter()
try:
audio = await self.queue.run(
lambda: self._render(voice, req.text, speed, req.params.format, key), owner=key_id
)
future.set_result(audio)
except BaseException as exc:
future.set_exception(exc)
future.exception() # marca como lida; quem esperava recebe o mesmo erro
raise
finally:
self._inflight.pop(inflight_key, None)
self._log(req, key_id, voice, "miss", replay, audio.duration_ms, time.perf_counter() - started)
return SynthesisResult(audio, cache_hit=False, replay=replay)
def _render(self, voice: Voice, text: str, speed: float, fmt: str, key: str) -> CachedAudio:
pcm = self.engine.synthesize(voice, text, speed, self.settings.max_audio_s)
data = encode(pcm, fmt, self.settings.opus_bitrate)
digest = hashlib.sha256(data).hexdigest()
return self.store.put(key, data, int(pcm.duration_s * 1000), digest)
def _log(self, req: SynthesizeRequest, key_id: str, voice: Voice, cache: str, replay: bool, duration_ms: int, seconds: float) -> None:
# Nunca o texto: só tamanho, voz e métricas.
log.info(
"synthesize request_id=%s key_id=%s voice=%s chars=%d cache=%s replay=%s audio_ms=%d wall_ms=%d",
req.requestId, key_id, voice.id, len(req.text), cache, replay, duration_ms, int(seconds * 1000),
)
+171
View File
@@ -0,0 +1,171 @@
"""Persistência local: idempotência por requestId (PRIMARY KEY no SQLite) e cache de áudio em disco.
- `requests_v2`: (keyId, requestId) → chave de cache. O PRIMARY KEY do banco é quem garante a idempotência.
O `keyId` faz parte da chave: o mesmo `requestId` vindo de duas chaves de serviço (homologação e produção)
são dois pedidos distintos, e uma chave não enxerga nem colide com a amarração da outra.
- `transcribe_requests_v2`: (keyId, idempotencyKey) → hash do conteúdo, mesma regra.
- As tabelas da versão anterior (`requests`, `transcribe_requests`, sem `keyId`) ficam no arquivo, intocadas:
esta versão não lê nem apaga, para a imagem anterior continuar funcionando sobre o mesmo `/data` se o
deploy for revertido. As amarrações antigas não migram (não têm dono conhecido); um retry de pedido anterior
ao deploy vira pedido novo e cai no cache por conteúdo, que é compartilhado e devolve o mesmo áudio.
- `cache`: chave → arquivo .ogg, com LRU por `last_used_at` e teto em MB.
Nenhum texto é gravado — só hashes.
"""
from __future__ import annotations
import os
import sqlite3
import threading
import time
from dataclasses import dataclass
from pathlib import Path
@dataclass(frozen=True)
class CachedAudio:
cache_key: str
path: Path
duration_ms: int
sha256: str
size: int
class Store:
def __init__(self, data_dir: Path, cache_max_mb: int, idempotency_ttl_h: int):
self.cache_dir = data_dir / "cache"
self.cache_dir.mkdir(parents=True, exist_ok=True)
self._max_bytes = cache_max_mb * 1024 * 1024
self._ttl_s = idempotency_ttl_h * 3600
self._lock = threading.Lock()
self._last_tick = 0
self._db = sqlite3.connect(data_dir / "voice.sqlite3", check_same_thread=False, isolation_level=None)
self._db.execute("PRAGMA journal_mode=WAL")
self._db.executescript(
"""
CREATE TABLE IF NOT EXISTS requests_v2 (
key_id TEXT NOT NULL,
request_id TEXT NOT NULL,
cache_key TEXT NOT NULL,
created_at INTEGER NOT NULL,
PRIMARY KEY (key_id, request_id)
);
CREATE TABLE IF NOT EXISTS cache (
cache_key TEXT PRIMARY KEY,
size INTEGER NOT NULL,
duration_ms INTEGER NOT NULL,
sha256 TEXT NOT NULL,
created_at INTEGER NOT NULL,
last_used_at INTEGER NOT NULL -- time.time_ns()
);
CREATE INDEX IF NOT EXISTS cache_lru ON cache(last_used_at);
-- Transcrição: (keyId, idempotencyKey) → hash do (áudio, idioma, motor). O texto NUNCA vai ao disco.
CREATE TABLE IF NOT EXISTS transcribe_requests_v2 (
key_id TEXT NOT NULL,
idempotency_key TEXT NOT NULL,
content_key TEXT NOT NULL,
created_at INTEGER NOT NULL,
PRIMARY KEY (key_id, idempotency_key)
);
"""
)
# ---------- idempotência ----------
def bind_request(self, key_id: str, request_id: str, cache_key: str) -> tuple[bool, str]:
"""Grava (keyId, requestId)→chave. Devolve (é_novo, chave_gravada). Corrida resolvida pelo PRIMARY KEY."""
now = int(time.time())
with self._lock:
self._db.execute("DELETE FROM requests_v2 WHERE created_at < ?", (now - self._ttl_s,))
try:
self._db.execute(
"INSERT INTO requests_v2(key_id, request_id, cache_key, created_at) VALUES (?, ?, ?, ?)",
(key_id, request_id, cache_key, now),
)
return True, cache_key
except sqlite3.IntegrityError:
row = self._db.execute(
"SELECT cache_key FROM requests_v2 WHERE key_id = ? AND request_id = ?", (key_id, request_id)
).fetchone()
return False, row[0]
def bind_transcription(self, key_id: str, idempotency_key: str, content_key: str) -> tuple[bool, str]:
"""Mesmo papel do `bind_request`, para a transcrição. Corrida resolvida pelo PRIMARY KEY."""
now = int(time.time())
with self._lock:
self._db.execute("DELETE FROM transcribe_requests_v2 WHERE created_at < ?", (now - self._ttl_s,))
try:
self._db.execute(
"INSERT INTO transcribe_requests_v2(key_id, idempotency_key, content_key, created_at)"
" VALUES (?, ?, ?, ?)",
(key_id, idempotency_key, content_key, now),
)
return True, content_key
except sqlite3.IntegrityError:
row = self._db.execute(
"SELECT content_key FROM transcribe_requests_v2 WHERE key_id = ? AND idempotency_key = ?",
(key_id, idempotency_key),
).fetchone()
return False, row[0]
# ---------- cache ----------
def _path(self, cache_key: str) -> Path:
return self.cache_dir / cache_key[:2] / f"{cache_key}.ogg"
def get(self, cache_key: str) -> CachedAudio | None:
with self._lock:
row = self._db.execute(
"SELECT size, duration_ms, sha256 FROM cache WHERE cache_key = ?", (cache_key,)
).fetchone()
if row is None:
return None
path = self._path(cache_key)
if not path.is_file():
self._db.execute("DELETE FROM cache WHERE cache_key = ?", (cache_key,))
return None
self._db.execute(
"UPDATE cache SET last_used_at = ? WHERE cache_key = ?", (self._tick(), cache_key)
)
return CachedAudio(cache_key, path, row[1], row[2], row[0])
def _tick(self) -> int:
"""Relógio do LRU estritamente crescente. No Windows o time_ns() anda em passos de ~1 ms e dois
acessos seguidos empatavam (o LRU expulsava o arquivo errado). Chame com self._lock."""
self._last_tick = max(time.time_ns(), self._last_tick + 1)
return self._last_tick
def put(self, cache_key: str, audio: bytes, duration_ms: int, sha256: str) -> CachedAudio:
path = self._path(cache_key)
path.parent.mkdir(parents=True, exist_ok=True)
tmp = path.with_suffix(f".{os.getpid()}.{threading.get_ident()}.tmp")
tmp.write_bytes(audio)
os.replace(tmp, path) # escrita atômica
with self._lock:
now = self._tick()
self._db.execute(
"INSERT OR REPLACE INTO cache(cache_key, size, duration_ms, sha256, created_at, last_used_at)"
" VALUES (?, ?, ?, ?, ?, ?)",
(cache_key, len(audio), duration_ms, sha256, now, now),
)
self._evict_locked()
return CachedAudio(cache_key, path, duration_ms, sha256, len(audio))
def _evict_locked(self) -> None:
total = self._db.execute("SELECT COALESCE(SUM(size), 0) FROM cache").fetchone()[0]
if total <= self._max_bytes:
return
for key, size in self._db.execute(
"SELECT cache_key, size FROM cache ORDER BY last_used_at ASC"
).fetchall():
if total <= self._max_bytes:
break
self._path(key).unlink(missing_ok=True)
self._db.execute("DELETE FROM cache WHERE cache_key = ?", (key,))
total -= size
def stats(self) -> dict[str, int]:
with self._lock:
entries, size = self._db.execute("SELECT COUNT(*), COALESCE(SUM(size), 0) FROM cache").fetchone()
return {"entries": entries, "bytes": size}
def close(self) -> None:
self._db.close()
+176
View File
@@ -0,0 +1,176 @@
"""Motor de transcrição (STT): faster-whisper na GPU (float16) ou na CPU (int8).
Uso no CenaForge: legenda dos episódios. Além do texto, devolve segmentos e (opcional) palavras com tempo
de início e fim — é o que o render precisa para gerar SRT/ASS. O áudio é decodificado em memória (PyAV),
em qualquer formato comum. Nada de texto ou áudio em log.
"""
from __future__ import annotations
import time
from dataclasses import dataclass, field
from pathlib import Path
from typing import Protocol
import numpy as np
from .decode import decode_audio
from .errors import AudioTooLong, InvalidAudio
SAMPLE_RATE = 16000
# Idioma do contrato → código do Whisper.
WHISPER_LANGUAGES = {"pt-BR": "pt", "en": "en", "es": "es"}
# Arquivos de cada modelo (o turbo da mobiuslabs troca vocabulary.txt por .json e traz o preprocessor).
MODEL_FILES = {
"base": ("config.json", "model.bin", "tokenizer.json", "vocabulary.txt"),
"small": ("config.json", "model.bin", "tokenizer.json", "vocabulary.txt"),
"medium": ("config.json", "model.bin", "tokenizer.json", "vocabulary.txt"),
"large-v3-turbo": ("config.json", "model.bin", "preprocessor_config.json", "tokenizer.json", "vocabulary.json"),
}
# text = só o texto (mais barato); segments = frases com tempo; words = frases + cada palavra com tempo.
DETAILS = ("text", "segments", "words")
@dataclass(frozen=True)
class Word:
start: float
end: float
text: str
probability: float
@dataclass(frozen=True)
class Segment:
start: float
end: float
text: str
words: tuple[Word, ...] = ()
@dataclass(frozen=True)
class Transcript:
text: str
no_speech_prob: float # média dos segmentos; 1.0 quando não houve segmento nenhum
segment_count: int
cpu_s: float # tempo de CPU do processo gasto na transcrição (para medir custo)
segments: tuple[Segment, ...] = field(default=())
duration_s: float = 0.0
class SttEngine(Protocol):
name: str
def decode(self, data: bytes, max_seconds: float) -> np.ndarray: ...
def transcribe(self, samples: np.ndarray, language: str, detail: str = "text") -> Transcript: ...
def mean_no_speech(probs: list[float]) -> float:
"""Média do `no_speech_prob` dos segmentos, presa em 0..1. Sem segmento = sem fala (1.0)."""
if not probs:
return 1.0
return float(min(1.0, max(0.0, sum(probs) / len(probs))))
def join_text(parts: list[str], max_chars: int) -> str:
text = " ".join(p.strip() for p in parts if p.strip())
return text[:max_chars]
def decode_ogg_opus(data: bytes, max_seconds: float) -> np.ndarray:
"""Mantido do dropsz_voice: só OGG/Opus. Hoje o serviço usa `decode_audio` (qualquer formato)."""
if not data.startswith(b"OggS"):
raise InvalidAudio()
return decode_audio(data, SAMPLE_RATE, max_seconds)
class FasterWhisperEngine:
"""faster-whisper (CTranslate2) carregado da pasta de modelos local, nunca da internet."""
def __init__(self, model_dir: Path, model_name: str, device: str, compute_type: str, threads: int,
beam_size: int, vad: bool, max_chars: int):
from faster_whisper import WhisperModel # import tardio: os testes usam o motor falso
self.name = f"faster-whisper-{model_name}-{device}-{compute_type}"
self.device = device
self._beam_size = beam_size
self._vad = vad
self._max_chars = max_chars
self._model = WhisperModel(
str(model_dir), device=device, compute_type=compute_type, cpu_threads=threads, num_workers=1,
local_files_only=True,
)
def decode(self, data: bytes, max_seconds: float) -> np.ndarray:
return decode_audio(data, SAMPLE_RATE, max_seconds)
def warmup(self) -> None:
"""Roda o decodificador de verdade (sem VAD: com VAD o silêncio nunca chega ao modelo). É aqui que o
CTranslate2 carrega cuBLAS/cuDNN; se faltar DLL, a falha aparece na subida e não na primeira legenda."""
tone = (np.sin(np.arange(SAMPLE_RATE) * 2 * np.pi * 220 / SAMPLE_RATE) * 0.1).astype(np.float32)
segments, _ = self._model.transcribe(tone, language="pt", beam_size=1, vad_filter=False)
list(segments)
def transcribe(self, samples: np.ndarray, language: str, detail: str = "text") -> Transcript:
cpu_start = time.process_time()
segments, _info = self._model.transcribe(
samples,
language=language,
beam_size=self._beam_size,
vad_filter=self._vad,
condition_on_previous_text=False, # evita laço de alucinação em áudio curto/ruidoso
without_timestamps=detail == "text",
word_timestamps=detail == "words",
)
texts: list[str] = []
probs: list[float] = []
items: list[Segment] = []
for segment in segments: # gerador: a transcrição acontece aqui
texts.append(segment.text)
probs.append(segment.no_speech_prob)
if detail != "text":
words = tuple(
Word(round(w.start, 3), round(w.end, 3), w.word.strip(), round(w.probability, 3))
for w in (segment.words or ())
)
items.append(Segment(round(segment.start, 3), round(segment.end, 3), segment.text.strip(), words))
return Transcript(
join_text(texts, self._max_chars), mean_no_speech(probs), len(probs),
time.process_time() - cpu_start, tuple(items), samples.size / SAMPLE_RATE,
)
class FakeSttEngine:
"""Motor falso para testes: "decodifica" bytes OggS e devolve um texto fixo."""
name = "fake-stt"
def __init__(self, text: str = "valeu pela live", probs: tuple[float, ...] = (0.1, 0.3), delay_s: float = 0.0):
self.text = text
self.probs = probs
self.delay_s = delay_s
self.calls = 0
self.details: list[str] = []
def decode(self, data: bytes, max_seconds: float) -> np.ndarray:
if not data.startswith(b"OggS"):
raise InvalidAudio()
# Convenção do falso: cada byte depois do cabeçalho vale 10 ms de áudio.
samples = max(1, (len(data) - 4)) * SAMPLE_RATE // 100
if samples > max_seconds * SAMPLE_RATE:
raise AudioTooLong()
return np.zeros(samples, dtype=np.float32)
def transcribe(self, samples: np.ndarray, language: str, detail: str = "text") -> Transcript:
self.calls += 1
self.details.append(detail)
if self.delay_s:
time.sleep(self.delay_s)
duration = samples.size / SAMPLE_RATE
segments: tuple[Segment, ...] = ()
if detail != "text" and self.text:
tokens = self.text.split()
step = duration / max(1, len(tokens))
words = tuple(Word(round(i * step, 3), round((i + 1) * step, 3), t, 0.9) for i, t in enumerate(tokens))
segments = (Segment(0.0, round(duration, 3), self.text, words if detail == "words" else ()),)
return Transcript(self.text, mean_no_speech(list(self.probs)), len(self.probs), 0.0, segments, duration)
+187
View File
@@ -0,0 +1,187 @@
"""Orquestra a transcrição: validação → idempotência → job em memória → fila → motor STT.
Modelo híbrido (ver README, "Transcrição"): o POST espera o job até `stt_sync_wait_s`; se terminar,
responde `ready`, senão `pending` + `jobRef`, consultado em `GET /v1/transcribe/jobs/{jobRef}`.
Privacidade: o áudio só vive em memória até o job rodar; o texto só vive em memória até o job
expirar (`stt_job_ttl_s`). No disco fica apenas (keyId, idempotencyKey) → hash. Nada de texto em log.
Isolamento por chave de serviço: o job pertence ao `keyId` que o criou. Consultar o `jobRef` com outra
chave dá o mesmo 410 `job_not_found` de um job inexistente (não revela que ele existe), e o mesmo áudio
enviado por duas chaves vira dois jobs.
"""
from __future__ import annotations
import asyncio
import hashlib
import json
import logging
import secrets
import time
from dataclasses import dataclass, field
from .config import Settings
from .errors import (
AudioTooLarge,
AudioTooLong,
IdempotencyConflict,
InvalidRequest,
JobNotFound,
LanguageNotSupported,
QueueFull,
ServiceError,
SynthesisTimeout,
TranscriptionFailed,
TranscriptionTimeout,
)
from .store import Store
from .stt import DETAILS, WHISPER_LANGUAGES, SttEngine, Transcript
from .work_queue import WorkQueue
log = logging.getLogger("cenaforge_voice")
STT_SCHEMA = 2 # suba quando mudar o pipeline (muda a chave de conteúdo)
# Folga sobre o teto de duração: o backend mede em ms e o container OGG arredonda.
DURATION_TOLERANCE_S = 0.5
MIN_RETRY_AFTER_MS = 500
MAX_RETRY_AFTER_MS = 10_000
@dataclass
class TranscriptionJob:
ref: str
key_id: str
content_key: str
audio_s: float
detail: str = "text"
created_at: float = field(default_factory=time.monotonic)
finished_at: float | None = None
result: Transcript | None = None
error: ServiceError | None = None
task: asyncio.Task | None = None
@property
def done(self) -> bool:
return self.finished_at is not None
def content_key_for(audio: bytes, language: str, engine_name: str, detail: str = "text") -> str:
payload = {
"schema": STT_SCHEMA,
"engine": engine_name,
"language": language,
"detail": detail,
"audio": hashlib.sha256(audio).hexdigest(),
}
return hashlib.sha256(json.dumps(payload, sort_keys=True).encode("utf-8")).hexdigest()
class TranscriptionService:
def __init__(self, settings: Settings, engine: SttEngine, store: Store, queue: WorkQueue):
self.settings = settings
self.engine = engine
self.store = store
self.queue = queue
self._by_content: dict[tuple[str, str], TranscriptionJob] = {} # (keyId, chave de conteúdo)
self._by_ref: dict[str, TranscriptionJob] = {}
# Segundos de relógio por segundo de áudio, medido (média móvel). Só estima o retryAfterMs.
self._wall_per_audio_s = 0.5
def validate(self, size: int, duration_ms: int, language: str, detail: str = "text") -> str:
whisper_language = WHISPER_LANGUAGES.get(language)
if whisper_language is None:
raise LanguageNotSupported()
if detail not in DETAILS:
raise InvalidRequest(f"X-Detail precisa ser um de {', '.join(DETAILS)}.")
if size > self.settings.stt_max_bytes:
raise AudioTooLarge()
if duration_ms > self.settings.stt_max_audio_s * 1000:
raise AudioTooLong()
return whisper_language
async def submit(
self, audio: bytes, duration_ms: int, language: str, idempotency_key: str, key_id: str, detail: str = "text"
) -> tuple[TranscriptionJob, bool]:
"""Cria (ou reaproveita) o job. Devolve (job, é_replay)."""
whisper_language = self.validate(len(audio), duration_ms, language, detail)
key = content_key_for(audio, whisper_language, self.engine.name, detail)
is_new, bound = self.store.bind_transcription(key_id, idempotency_key, key)
if bound != key:
raise IdempotencyConflict("Esta idempotencyKey já foi usada com outro áudio.")
self._purge()
job = self._by_content.get((key_id, key))
if job is not None and job.error is None:
return job, not is_new # em andamento ou pronto: mesmo resultado
if job is not None: # falhou antes: o retry com a mesma chave tenta de novo
self._forget(job)
if self.queue.is_full(key_id):
raise QueueFull()
job = TranscriptionJob(
ref=secrets.token_urlsafe(18), key_id=key_id, content_key=key, audio_s=duration_ms / 1000, detail=detail
)
self._by_content[(key_id, key)] = job
self._by_ref[job.ref] = job
job.task = asyncio.create_task(self._run(job, audio, whisper_language, detail))
return job, not is_new
async def wait(self, job: TranscriptionJob, timeout_s: float) -> None:
if job.task is not None and not job.done and timeout_s > 0:
await asyncio.wait({job.task}, timeout=timeout_s)
def get(self, ref: str, key_id: str) -> TranscriptionJob:
self._purge()
job = self._by_ref.get(ref)
# Job de outra chave responde igual a job inexistente: nem 403, nem pista de que existe.
if job is None or job.key_id != key_id:
raise JobNotFound()
return job
def retry_after_ms(self, job: TranscriptionJob) -> int:
elapsed = time.monotonic() - job.created_at
remaining = job.audio_s * self._wall_per_audio_s - elapsed
return int(min(MAX_RETRY_AFTER_MS, max(MIN_RETRY_AFTER_MS, remaining * 1000)))
async def _run(self, job: TranscriptionJob, audio: bytes, language: str, detail: str) -> None:
started = time.perf_counter()
try:
job.result = await self.queue.run(lambda: self._work(audio, language, detail), owner=job.key_id)
except SynthesisTimeout:
job.error = TranscriptionTimeout()
except ServiceError as exc:
job.error = exc
except Exception as exc: # noqa: BLE001 - qualquer falha do motor vira erro estável
# Mensagem da biblioteca (DLL, memória da GPU), nunca o texto transcrito.
log.error("transcribe job=%s erro=%s: %s", job.ref, type(exc).__name__, str(exc)[:200])
job.error = TranscriptionFailed()
finally:
job.finished_at = time.monotonic()
wall = time.perf_counter() - started
if job.result is not None:
if job.audio_s > 0:
self._wall_per_audio_s = 0.7 * self._wall_per_audio_s + 0.3 * (wall / job.audio_s)
# Só métricas: nunca o texto.
log.info(
"transcribe job=%s audio_ms=%d wall_ms=%d cpu_ms=%d cpu_per_audio_s=%.3f segments=%d no_speech=%.2f",
job.ref, int(job.audio_s * 1000), int(wall * 1000), int(job.result.cpu_s * 1000),
job.result.cpu_s / job.audio_s if job.audio_s else 0.0, job.result.segment_count, job.result.no_speech_prob,
)
else:
log.info("transcribe job=%s falhou code=%s wall_ms=%d", job.ref, job.error.code, int(wall * 1000))
def _work(self, audio: bytes, language: str, detail: str) -> Transcript:
# A duração declarada pelo cliente é conferida contra a real: o teto vale para o que foi
# decodificado, e a decodificação para ao passar dele.
samples = self.engine.decode(audio, self.settings.stt_max_audio_s + DURATION_TOLERANCE_S)
return self.engine.transcribe(samples, language, detail)
def _forget(self, job: TranscriptionJob) -> None:
self._by_content.pop((job.key_id, job.content_key), None)
self._by_ref.pop(job.ref, None)
def _purge(self) -> None:
now = time.monotonic()
for job in [j for j in self._by_ref.values() if j.done and now - j.finished_at > self.settings.stt_job_ttl_s]:
self._forget(job)
+125
View File
@@ -0,0 +1,125 @@
"""Fila de trabalho: concorrência limitada, fila limitada POR CHAVE, timeout de espera e de execução.
- A cota de espera é por `owner` (o `keyId` de quem chamou): uma chave cheia recebe `QueueFull`, as outras
continuam entrando. Homologação e produção usam o mesmo serviço com chaves diferentes; o teste de uma não
pode recusar a doação paga da outra.
- A vaga de execução (CPU) é global, mas é entregue em rodízio entre as chaves que estão esperando, e a chave
que acabou de rodar vai para o fim: cada chave espera no máximo o trabalho em curso e um de cada outra chave
ativa, e não a fila inteira da outra. Por isso o timeout de espera precisa ser >= 2x o de execução.
- A vaga só é devolvida quando a thread realmente termina — mesmo que o cliente já tenha recebido 504 —,
para o limite de CPU ser real e não só aparente.
"""
from __future__ import annotations
import asyncio
from collections import deque
from collections.abc import Callable
from concurrent.futures import ThreadPoolExecutor
from typing import TypeVar
from .errors import QueueFull, QueueTimeout, SynthesisTimeout
T = TypeVar("T")
class WorkQueue:
def __init__(self, max_concurrency: int, max_queue_per_key: int, queue_timeout_s: float, run_timeout_s: float):
self.max_concurrency = max_concurrency
self.max_queue_per_key = max_queue_per_key
self.queue_timeout_s = queue_timeout_s
self.run_timeout_s = run_timeout_s
self._free = max_concurrency
# owner → esperas em ordem de chegada. A ordem do dict é o rodízio: quem é atendido vai para o fim.
self._waiters: dict[str, deque[asyncio.Future[None]]] = {}
self._executor = ThreadPoolExecutor(max_workers=max_concurrency, thread_name_prefix="work")
self.running = 0
@property
def waiting(self) -> int:
"""Total esperando, somadas todas as chaves."""
return sum(len(waiters) for waiters in self._waiters.values())
def waiting_for(self, owner: str) -> int:
waiters = self._waiters.get(owner)
return len(waiters) if waiters else 0
def is_full(self, owner: str) -> bool:
"""Verdadeiro quando um `run` novo DESTA chave seria recusado com QueueFull."""
return self._free == 0 and self.waiting_for(owner) >= self.max_queue_per_key
async def _acquire(self, owner: str) -> None:
if self._free > 0 and not self._waiters:
self._free -= 1
return
waiter: asyncio.Future[None] = asyncio.get_running_loop().create_future()
self._waiters.setdefault(owner, deque()).append(waiter)
try:
# asyncio.wait não cancela o future no timeout: dá para ver se a vaga chegou no último instante.
await asyncio.wait({waiter}, timeout=self.queue_timeout_s)
except BaseException: # cliente desistiu (CancelledError) enquanto esperava
self._abandon(owner, waiter)
raise
if not waiter.done():
self._abandon(owner, waiter)
raise QueueTimeout()
def _abandon(self, owner: str, waiter: asyncio.Future[None]) -> None:
if waiter.done() and not waiter.cancelled():
self._release() # a vaga já tinha sido entregue a esta espera: passa adiante
return
waiter.cancel()
waiters = self._waiters.get(owner)
if waiters is not None:
try:
waiters.remove(waiter)
except ValueError:
pass
if not waiters:
del self._waiters[owner]
def _release(self, finished_owner: str | None = None) -> None:
"""Entrega a vaga à próxima chave do rodízio; sem ninguém esperando, ela volta a ficar livre."""
if finished_owner is not None and finished_owner in self._waiters and len(self._waiters) > 1:
self._waiters[finished_owner] = self._waiters.pop(finished_owner) # quem acabou de rodar vai para o fim
while self._waiters:
owner = next(iter(self._waiters))
waiters = self._waiters.pop(owner)
waiter = waiters.popleft()
if waiters:
self._waiters[owner] = waiters # volta para o fim do rodízio
if not waiter.done():
waiter.set_result(None)
return
self._free += 1
async def run(self, fn: Callable[[], T], owner: str) -> T:
if self.is_full(owner):
raise QueueFull()
await self._acquire(owner)
self.running += 1
future = asyncio.get_running_loop().run_in_executor(self._executor, fn)
released = False
def _finish(_: object = None) -> None:
self.running -= 1
self._release(owner)
try:
return await asyncio.wait_for(asyncio.shield(future), timeout=self.run_timeout_s)
except asyncio.TimeoutError:
future.add_done_callback(_finish)
released = True
raise SynthesisTimeout() from None
except asyncio.CancelledError:
# Cliente desistiu no meio: a thread segue, então a vaga só volta quando ela terminar.
future.add_done_callback(_finish)
released = True
raise
finally:
if not released:
_finish()
def shutdown(self) -> None:
self._executor.shutdown(wait=False, cancel_futures=True)
+2
View File
@@ -0,0 +1,2 @@
# Clonagem de voz (voice/.venv-clone). torch/torchaudio 2.6.0 vêm do índice do PyTorch (setup -Clone).
chatterbox-tts==0.1.7
+212
View File
@@ -0,0 +1,212 @@
"""Processo de clonagem de voz do CenaForge (Chatterbox Multilingual, licença MIT).
Roda num venv próprio (voice/.venv-clone): o Chatterbox fixa torch 2.6, numpy < 2 e um transformers
diferente do serviço de voz. O serviço de voz (porta 4510) chama este processo pela rede local.
Contrato (só 127.0.0.1, cabeçalho X-Service-Key = VOICE_SERVICE_KEY):
- GET /health → {"status": "loading" | "ok" | "error", "device", "error"?}
- POST /synthesize JSON {text, reference, language, exaggeration, cfgWeight} → audio/wav (24 kHz, mono, PCM 16)
`reference` precisa estar dentro de <VOICE_MODELS_DIR>/clone/.
Pesos: baixados do Hugging Face (ResembleAI/chatterbox) na primeira subida, para data/voice/models/clone-hf.
Todo áudio gerado leva a marca d'água inaudível do Chatterbox (PerTh).
"""
from __future__ import annotations
import hmac
import io
import json
import logging
import os
import re
import sys
import threading
import time
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from pathlib import Path
VOICE_ROOT = Path(__file__).resolve().parents[1]
PROJECT_ROOT = VOICE_ROOT.parent
MAX_TEXT_CHARS = 2000
MAX_CHUNK_CHARS = 280 # o Chatterbox perde qualidade em trechos longos: gera por frase e junta
PAUSE_S = 0.18
logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s", stream=sys.stdout)
log = logging.getLogger("cenaforge_clone")
def _read_env() -> dict[str, str]:
"""voice/.env (o dev.ts já repassa, mas rodar à mão também funciona)."""
values: dict[str, str] = {}
env_file = VOICE_ROOT / ".env"
if env_file.is_file():
for line in env_file.read_text(encoding="utf-8").splitlines():
if "=" in line and not line.lstrip().startswith("#"):
name, value = line.split("=", 1)
values[name.strip()] = value.strip()
return {**values, **{k: v for k, v in os.environ.items() if k.startswith("VOICE_")}}
ENV = _read_env()
KEY = ENV.get("VOICE_SERVICE_KEY", "")
PORT = int(ENV.get("VOICE_CLONE_PORT", "4511"))
_models = ENV.get("VOICE_MODELS_DIR", "")
MODELS_DIR = (PROJECT_ROOT / _models).resolve() if _models and not Path(_models).is_absolute() else Path(
_models or PROJECT_ROOT / "data" / "voice" / "models"
).resolve()
CLONE_DIR = (MODELS_DIR / "clone").resolve()
# Cache do Hugging Face dentro de data/ (não no perfil do usuário): apagar data/voice/models remove tudo.
os.environ.setdefault("HF_HOME", str(MODELS_DIR / "clone-hf"))
# Windows sem modo desenvolvedor não cria symlink: o cache funciona copiando, e o aviso só polui o terminal.
os.environ.setdefault("HF_HUB_DISABLE_SYMLINKS_WARNING", "1")
# O download pelo protocolo Xet travou nesta máquina (256 MB em 9 min, arquivo de 2 GB parado); HTTP comum baixou tudo.
os.environ.setdefault("HF_HUB_DISABLE_XET", "1")
# Uma linha por arquivo baixado do Hugging Face enche o terminal do pnpm dev.
logging.getLogger("httpx").setLevel(logging.WARNING)
class Engine:
"""Carrega o modelo uma vez (em segundo plano) e serializa as gerações (uma placa, um modelo)."""
def __init__(self) -> None:
self.status = "loading"
self.error: str | None = None
self.device = "cpu"
self.model = None
self._lock = threading.Lock()
self._conds_key: tuple | None = None
def load(self) -> None:
try:
import torch
from chatterbox.mtl_tts import ChatterboxMultilingualTTS
wanted = ENV.get("VOICE_DEVICE", "auto")
self.device = "cuda" if wanted != "cpu" and torch.cuda.is_available() else "cpu"
started = time.monotonic()
self.model = ChatterboxMultilingualTTS.from_pretrained(device=torch.device(self.device))
self.status = "ok"
log.info("clonagem pronta em %s (%.0f s)", self.device, time.monotonic() - started)
except Exception as exc: # noqa: BLE001 - qualquer falha de carga vira estado "error" no /health
self.status, self.error = "error", f"{type(exc).__name__}: {exc}"
log.exception("falha ao carregar o Chatterbox")
def synthesize(self, text: str, reference: Path, language: str, exaggeration: float, cfg_weight: float) -> bytes:
import numpy as np
import soundfile
with self._lock:
model = self.model
stamp = reference.stat()
key = (str(reference), stamp.st_mtime_ns, stamp.st_size, exaggeration)
if key != self._conds_key:
# Condicionamento da voz (timbre da referência): caro, então só refaz quando muda.
model.prepare_conditionals(str(reference), exaggeration=exaggeration)
self._conds_key = key
pieces = []
silence = np.zeros(int(model.sr * PAUSE_S), dtype=np.float32)
for chunk in split_text(text):
wav = model.generate(chunk, language_id=language, exaggeration=exaggeration, cfg_weight=cfg_weight)
pieces.extend([wav.squeeze(0).detach().cpu().numpy().astype(np.float32), silence])
audio = np.concatenate(pieces[:-1]) if pieces else silence
buffer = io.BytesIO()
soundfile.write(buffer, np.clip(audio, -1.0, 1.0), model.sr, format="WAV", subtype="PCM_16")
return buffer.getvalue()
def split_text(text: str) -> list[str]:
"""Quebra em frases e junta as curtas até ~280 caracteres (frase longa demais é cortada nas vírgulas)."""
sentences = [s.strip() for s in re.split(r"(?<=[.!?…])\s+", text.strip()) if s.strip()]
chunks: list[str] = []
for sentence in sentences:
parts = [sentence] if len(sentence) <= MAX_CHUNK_CHARS else [p.strip() for p in re.split(r"(?<=[,;:])\s+", sentence)]
for part in parts:
if chunks and len(chunks[-1]) + 1 + len(part) <= MAX_CHUNK_CHARS:
chunks[-1] = f"{chunks[-1]} {part}"
else:
chunks.append(part[:MAX_CHUNK_CHARS * 2])
return chunks
ENGINE = Engine()
class Handler(BaseHTTPRequestHandler):
server_version = "cenaforge-clone"
def log_message(self, format: str, *args) -> None: # noqa: A002 - assinatura da stdlib
return # sem log de acesso (o texto do usuário não vai para o terminal)
def _send(self, status: int, body: bytes, content_type: str = "application/json") -> None:
self.send_response(status)
self.send_header("Content-Type", content_type)
self.send_header("Content-Length", str(len(body)))
self.send_header("Cache-Control", "no-store")
self.end_headers()
self.wfile.write(body)
def _error(self, status: int, message: str) -> None:
self._send(status, json.dumps({"error": message}, ensure_ascii=False).encode("utf-8"))
def _authorized(self) -> bool:
given = self.headers.get("X-Service-Key", "")
return bool(KEY) and hmac.compare_digest(given.encode("utf-8"), KEY.encode("utf-8"))
def do_GET(self) -> None: # noqa: N802 - nome da stdlib
if self.path != "/health":
return self._error(404, "rota desconhecida")
payload = {"status": ENGINE.status, "device": ENGINE.device}
if ENGINE.error:
payload["error"] = ENGINE.error
self._send(200, json.dumps(payload).encode("utf-8"))
def do_POST(self) -> None: # noqa: N802 - nome da stdlib
if self.path != "/synthesize":
return self._error(404, "rota desconhecida")
if not self._authorized():
return self._error(401, "chave ausente ou inválida")
if ENGINE.status != "ok":
return self._error(503, f"modelo ainda {'carregando' if ENGINE.status == 'loading' else 'com erro'}")
try:
length = int(self.headers.get("Content-Length", "0"))
if not 0 < length <= 64 * 1024:
raise ValueError("corpo vazio ou grande demais")
body = json.loads(self.rfile.read(length))
text = str(body["text"]).strip()
if not text or len(text) > MAX_TEXT_CHARS:
raise ValueError(f"texto vazio ou acima de {MAX_TEXT_CHARS} caracteres")
reference = Path(str(body["reference"])).resolve()
if CLONE_DIR not in reference.parents or not reference.is_file():
raise ValueError("áudio de referência fora de data/voice/models/clone ou ausente")
language = str(body.get("language", "pt"))[:5]
exaggeration = min(1.5, max(0.25, float(body.get("exaggeration", 0.5))))
cfg_weight = min(1.0, max(0.0, float(body.get("cfgWeight", 0.5))))
except (ValueError, KeyError, TypeError, json.JSONDecodeError) as exc:
return self._error(400, str(exc))
try:
wav = ENGINE.synthesize(text, reference, language, exaggeration, cfg_weight)
except Exception as exc: # noqa: BLE001 - falha do modelo vira 500 com o tipo do erro
log.exception("falha ao gerar a voz clonada")
return self._error(500, f"{type(exc).__name__}: {exc}")
self._send(200, wav, "audio/wav")
def main() -> None:
if len(KEY) < 32:
log.error("VOICE_SERVICE_KEY ausente: rode o setup.bat")
sys.exit(1)
if not 4500 <= PORT <= 4599:
log.error("VOICE_CLONE_PORT=%s fora da faixa 4500–4599 do CenaForge", PORT)
sys.exit(1)
threading.Thread(target=ENGINE.load, name="load-model", daemon=True).start()
server = ThreadingHTTPServer(("127.0.0.1", PORT), Handler)
log.info("clonagem ouvindo em 127.0.0.1:%d (modelo carregando…)", PORT)
try:
server.serve_forever()
except KeyboardInterrupt:
pass
if __name__ == "__main__":
main()
+155
View File
@@ -0,0 +1,155 @@
{
"comment": "Pesos fora do Git. scripts/fetch_models.py baixa para VOICE_MODELS_DIR (padrão: data/voice/models) e confere o sha256; o serviço recusa subir se divergir.",
"files": [
{
"path": "piper/pt_BR-faber-medium.onnx",
"url": "https://huggingface.co/rhasspy/piper-voices/resolve/e9ab671f2a0e50a701b34361136ba3e6a3a9eb0c/pt/pt_BR/faber/medium/pt_BR-faber-medium.onnx",
"sha256": "75e913eb463db0b6ac7ddf68d3e4c9ac19ace36dc3b710a81039b448352b8ffc",
"group": "v1"
},
{
"path": "piper/pt_BR-faber-medium.onnx.json",
"url": "https://huggingface.co/rhasspy/piper-voices/resolve/e9ab671f2a0e50a701b34361136ba3e6a3a9eb0c/pt/pt_BR/faber/medium/pt_BR-faber-medium.onnx.json",
"sha256": "fa8a8fecb01ae198bc416381e368d3206f85bad1449a0f11e1f6a9edf85a32f1",
"group": "v1"
},
{
"path": "piper/pt_BR-cadu-medium.onnx",
"url": "https://huggingface.co/rhasspy/piper-voices/resolve/e9ab671f2a0e50a701b34361136ba3e6a3a9eb0c/pt/pt_BR/cadu/medium/pt_BR-cadu-medium.onnx",
"sha256": "d5a662e3f606d5a49dd29ba9ce90c304ae45dd9543f8b0c773bcb0de282499de",
"group": "v1"
},
{
"path": "piper/pt_BR-cadu-medium.onnx.json",
"url": "https://huggingface.co/rhasspy/piper-voices/resolve/e9ab671f2a0e50a701b34361136ba3e6a3a9eb0c/pt/pt_BR/cadu/medium/pt_BR-cadu-medium.onnx.json",
"sha256": "9fa837b7c1237ea5978bcd7be38c130798e8faa064f754873bb4ce5fc498bd88",
"group": "v1"
},
{
"path": "piper/pt_BR-jeff-medium.onnx",
"url": "https://huggingface.co/rhasspy/piper-voices/resolve/e9ab671f2a0e50a701b34361136ba3e6a3a9eb0c/pt/pt_BR/jeff/medium/pt_BR-jeff-medium.onnx",
"sha256": "82ddcdb01a0342f078bd89ce2815eda27185818d15e15f06fb9a72ac3bce94e1",
"group": "v1"
},
{
"path": "piper/pt_BR-jeff-medium.onnx.json",
"url": "https://huggingface.co/rhasspy/piper-voices/resolve/e9ab671f2a0e50a701b34361136ba3e6a3a9eb0c/pt/pt_BR/jeff/medium/pt_BR-jeff-medium.onnx.json",
"sha256": "078ea4e42a680ca3cb662a8929237c32e2c0d581f5363f2f55f09bc266497bf6",
"group": "v1"
},
{
"path": "kokoro/voices-v1.0.bin",
"url": "https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files-v1.1/voices-v1.0.bin",
"sha256": "bca610b8308e8d99f32e6fe4197e7ec01679264efed0cac9140fe9c29f1fbf7d",
"group": "v1"
},
{
"path": "kokoro/kokoro-v1.0.fp16.onnx",
"url": "https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files-v1.1/kokoro-v1.0.fp16.onnx",
"sha256": "f3a290d384fbb27966d462905c71a46cef9e5fd00516b40df32a0b4afe77ac96",
"group": "v1"
},
{
"path": "whisper/base/config.json",
"url": "https://huggingface.co/Systran/faster-whisper-base/resolve/ebe41f70d5b6dfa9166e2c581c45c9c0cfc57b66/config.json",
"sha256": "56a6d8110d311f19c8f0471e562832c7527f146b567275bfca59fcf7c184da9a",
"group": "stt-base"
},
{
"path": "whisper/base/model.bin",
"url": "https://huggingface.co/Systran/faster-whisper-base/resolve/ebe41f70d5b6dfa9166e2c581c45c9c0cfc57b66/model.bin",
"sha256": "d01c3014881c9c6f3133c182f3d2887eb6ca1c789a7538c5c007196857a0a6a9",
"group": "stt-base"
},
{
"path": "whisper/base/tokenizer.json",
"url": "https://huggingface.co/Systran/faster-whisper-base/resolve/ebe41f70d5b6dfa9166e2c581c45c9c0cfc57b66/tokenizer.json",
"sha256": "fb7b63191e9bb045082c79fd742a3106a12c99513ab30df4a0d47fa6cb6fd0ab",
"group": "stt-base"
},
{
"path": "whisper/base/vocabulary.txt",
"url": "https://huggingface.co/Systran/faster-whisper-base/resolve/ebe41f70d5b6dfa9166e2c581c45c9c0cfc57b66/vocabulary.txt",
"sha256": "34ce3fe1c5041027b3f8d42912270993f986dbc4bb34cf27f951e34a1e453913",
"group": "stt-base"
},
{
"path": "whisper/small/config.json",
"url": "https://huggingface.co/Systran/faster-whisper-small/resolve/536b0662742c02347bc0e980a01041f333bce120/config.json",
"sha256": "b55496ac7940a7ae47d2c01eab40edfd8701feec1229d9cce3b40014383fb828",
"group": "stt-small"
},
{
"path": "whisper/small/model.bin",
"url": "https://huggingface.co/Systran/faster-whisper-small/resolve/536b0662742c02347bc0e980a01041f333bce120/model.bin",
"sha256": "3e305921506d8872816023e4c273e75d2419fb89b24da97b4fe7bce14170d671",
"group": "stt-small"
},
{
"path": "whisper/small/tokenizer.json",
"url": "https://huggingface.co/Systran/faster-whisper-small/resolve/536b0662742c02347bc0e980a01041f333bce120/tokenizer.json",
"sha256": "fb7b63191e9bb045082c79fd742a3106a12c99513ab30df4a0d47fa6cb6fd0ab",
"group": "stt-small"
},
{
"path": "whisper/small/vocabulary.txt",
"url": "https://huggingface.co/Systran/faster-whisper-small/resolve/536b0662742c02347bc0e980a01041f333bce120/vocabulary.txt",
"sha256": "34ce3fe1c5041027b3f8d42912270993f986dbc4bb34cf27f951e34a1e453913",
"group": "stt-small"
},
{
"path": "whisper/medium/config.json",
"url": "https://huggingface.co/Systran/faster-whisper-medium/resolve/08e178d48790749d25932bbc082711ddcfdfbc4f/config.json",
"sha256": "3622a2ddc41ec0e0fd4e68c13c6830f03b90c38d89aaad184de02c8c642cf807",
"group": "stt-medium"
},
{
"path": "whisper/medium/model.bin",
"url": "https://huggingface.co/Systran/faster-whisper-medium/resolve/08e178d48790749d25932bbc082711ddcfdfbc4f/model.bin",
"sha256": "9b45e1009dcc4ab601eff815b61d80e60ce3fd8c74c1a14f4a282258286b51ae",
"group": "stt-medium"
},
{
"path": "whisper/medium/tokenizer.json",
"url": "https://huggingface.co/Systran/faster-whisper-medium/resolve/08e178d48790749d25932bbc082711ddcfdfbc4f/tokenizer.json",
"sha256": "fb7b63191e9bb045082c79fd742a3106a12c99513ab30df4a0d47fa6cb6fd0ab",
"group": "stt-medium"
},
{
"path": "whisper/medium/vocabulary.txt",
"url": "https://huggingface.co/Systran/faster-whisper-medium/resolve/08e178d48790749d25932bbc082711ddcfdfbc4f/vocabulary.txt",
"sha256": "34ce3fe1c5041027b3f8d42912270993f986dbc4bb34cf27f951e34a1e453913",
"group": "stt-medium"
},
{
"path": "whisper/large-v3-turbo/config.json",
"url": "https://huggingface.co/mobiuslabsgmbh/faster-whisper-large-v3-turbo/resolve/0a363e9161cbc7ed1431c9597a8ceaf0c4f78fcf/config.json",
"sha256": "b0253ea6c0d3bea6b1e19e91a02acfd3b53f4467362efcb5a3e6b16c9b3a9b7e",
"group": "stt-large-v3-turbo"
},
{
"path": "whisper/large-v3-turbo/model.bin",
"url": "https://huggingface.co/mobiuslabsgmbh/faster-whisper-large-v3-turbo/resolve/0a363e9161cbc7ed1431c9597a8ceaf0c4f78fcf/model.bin",
"sha256": "e76620f83d5f5b69efd3d87e3dc180c1bd21df9fbebacfd4335e5e1efcc018da",
"group": "stt-large-v3-turbo"
},
{
"path": "whisper/large-v3-turbo/preprocessor_config.json",
"url": "https://huggingface.co/mobiuslabsgmbh/faster-whisper-large-v3-turbo/resolve/0a363e9161cbc7ed1431c9597a8ceaf0c4f78fcf/preprocessor_config.json",
"sha256": "7ccc62c6f2765af1f3b46c00c9b5894426835a05021c8b9c01eecb6dfb542711",
"group": "stt-large-v3-turbo"
},
{
"path": "whisper/large-v3-turbo/tokenizer.json",
"url": "https://huggingface.co/mobiuslabsgmbh/faster-whisper-large-v3-turbo/resolve/0a363e9161cbc7ed1431c9597a8ceaf0c4f78fcf/tokenizer.json",
"sha256": "297b13372ac43916285644fb9687add3cc62ee2a1adb60da3dc25cc94c1871fd",
"group": "stt-large-v3-turbo"
},
{
"path": "whisper/large-v3-turbo/vocabulary.json",
"url": "https://huggingface.co/mobiuslabsgmbh/faster-whisper-large-v3-turbo/resolve/0a363e9161cbc7ed1431c9597a8ceaf0c4f78fcf/vocabulary.json",
"sha256": "c69260f2ab26d659b7c398f9a2b2b48ed0df16c3b47d7326782fd9cba71690c1",
"group": "stt-large-v3-turbo"
}
]
}
+3
View File
@@ -0,0 +1,3 @@
[pytest]
testpaths = tests
addopts = -q -p no:cacheprovider
+5
View File
@@ -0,0 +1,5 @@
# DLLs do CUDA 12 para o Windows (as mesmas que o Applio 3.7.0 fixa). Usadas pelo faster-whisper (CTranslate2)
# na GPU. Só são instaladas quando o setup encontra uma GPU NVIDIA.
nvidia-cublas-cu12==12.9.2.10
nvidia-cuda-runtime-cu12==12.9.79
nvidia-cudnn-cu12==9.26.0.51
+3
View File
@@ -0,0 +1,3 @@
-r requirements.txt
pytest==9.1.1
httpx==0.28.1
+20
View File
@@ -0,0 +1,20 @@
# Motor RVC do Applio 3.7.0 (voice/vendor/applio), copiado do requirements-engine.txt dele.
# Fora daqui, de propósito:
# - torch/torchaudio: o setup instala do índice certo (CUDA cu128 com GPU NVIDIA, CPU sem);
# - onnxruntime-gpu: conflita com o onnxruntime do Piper (mesmo módulo); o RVC roda em torch.
click==8.1.8
requests==2.34.2
tqdm==4.68.4
faiss-cpu==1.14.3
librosa==0.11.0
scipy==1.18.0
stftpitchshift==2.0
torchcrepe==0.0.24
torchfcpe==0.0.4
einops==0.8.2
transformers==5.13.1
matplotlib==3.11.0
tensorboard==2.21.0
onnx==1.23.1
beautifulsoup4==4.15.0
psutil==7.2.2
+22
View File
@@ -0,0 +1,22 @@
# Serviço de voz do CenaForge (base: dropsz_voice). Versões fixas; suba com teste.
fastapi==0.159.1
uvicorn==0.54.0
pydantic==2.14.1
numpy==2.4.6
soundfile==0.14.0
soxr==1.1.0
# TTS offline (Piper, ONNX em CPU)
piper-tts==1.8.0
onnxruntime==1.31.0
# TTS online (Edge TTS). 7.3.1 corrige o 403 de out/2026 (o Applio 3.7.0 fixa 7.2.8 + patch próprio)
edge-tts==7.3.1
# Transcrição (STT): CTranslate2 (CPU ou CUDA) + PyAV (decodifica WAV/MP3/OGG/M4A sem ffmpeg nem subprocesso)
faster-whisper==1.2.1
ctranslate2==4.8.3
av==19.0.2
# TTS offline (Kokoro-82M, ONNX em CPU; Apache-2.0). Fonemas pelo espeak-ng embutido no espeakng-loader.
kokoro-onnx==0.6.1
phonemizer==3.6.0
espeakng-loader==0.2.4
# TTS online "voz do Google" (gTTS: API não oficial do Google Tradutor)
gTTS==2.5.4
+53
View File
@@ -0,0 +1,53 @@
"""Mede tempo de CPU por segundo de áudio do motor da V1 (Piper) dentro do container.
Uso: docker compose run --rm voice python scripts/bench.py
Mede síntese + codificação Opus, que é o custo real de um cache miss.
"""
from __future__ import annotations
import os
import sys
import time
from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
from app.audio import encode_ogg_opus # noqa: E402
from app.catalog import load_catalog # noqa: E402
from app.engine import PiperEngine # noqa: E402
ROOT = Path(__file__).resolve().parent.parent
TEXTS = [
"Olá! Valeu pela doação, o streamer agradece demais.",
"Atenção, sobrevivente: uma horda de infectados está chegando pelo norte, prepare a munição e corra para o galpão.",
"Isso é um teste de voz do DROPSZ, com frases um pouco mais longas, números como dois mil e vinte e seis, "
"e pontuação variada; será que fica natural?",
]
def main() -> None:
models = Path(os.environ.get("VOICE_MODELS_DIR", "/models"))
voices = load_catalog(ROOT / "voices" / "catalog.json", ROOT / "models.lock.json", models)
voice = next(v for v in voices.values() if v.default)
threads = int(os.environ.get("VOICE_ONNX_THREADS", "2"))
engine = PiperEngine(threads)
engine.synthesize(voice, "aquecimento", 1.0, 30)
rounds = int(os.environ.get("BENCH_ROUNDS", "3"))
cpu = wall = audio = 0.0
for _ in range(rounds):
for text in TEXTS:
c0, w0 = time.process_time(), time.perf_counter()
pcm = engine.synthesize(voice, text, 1.0, 60)
encode_ogg_opus(pcm)
cpu += time.process_time() - c0
wall += time.perf_counter() - w0
audio += pcm.duration_s
print(
f"voz={voice.id} threads={threads} audio={audio:.1f}s cpu={cpu:.2f}s wall={wall:.2f}s "
f"cpu_por_s_audio={cpu / audio:.3f} rtf_wall={wall / audio:.3f}"
)
if __name__ == "__main__":
main()
+89
View File
@@ -0,0 +1,89 @@
"""Mede tempo de CPU por segundo de áudio da transcrição (faster-whisper) dentro do container.
Uso: docker compose run --rm voice python scripts/bench_stt.py
BENCH_MODELS=base,small (precisa dos dois baixados: fetch_models.py --group stt-base --group stt-small)
BENCH_OUT=/tmp/x.ogg (opcional: grava o clipe de ~10 s para o teste com curl)
O áudio de teste é gerado pelo próprio Piper do serviço (texto sintético, nunca de espectador) e
codificado em OGG/Opus como o backend manda. Mede decodificação + transcrição: o custo real de um job.
"""
from __future__ import annotations
import os
import sys
import time
from pathlib import Path
import numpy as np
sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
from app.audio import encode_ogg_opus # noqa: E402
from app.catalog import load_catalog # noqa: E402
from app.engine import Pcm, PiperEngine # noqa: E402
from app.stt import SAMPLE_RATE, FasterWhisperEngine # noqa: E402
ROOT = Path(__file__).resolve().parent.parent
SENTENCES = [
"Olá! Valeu pela doação, o streamer agradece demais.",
"Atenção, sobrevivente: uma horda de infectados está chegando pelo norte, prepare a munição e corra para o galpão.",
"Isso é um teste de voz do DROPSZ, com frases um pouco mais longas e pontuação variada.",
"Manda um abraço para o pessoal do chat e boa sorte na próxima partida.",
]
def build_clip(engine: PiperEngine, voice, seconds: float) -> bytes:
parts: list[np.ndarray] = []
total = 0.0
rate = 0
index = 0
while total < seconds:
pcm = engine.synthesize(voice, SENTENCES[index % len(SENTENCES)], 1.0, 30)
rate = pcm.sample_rate
parts.append(pcm.samples)
parts.append(np.zeros(rate // 3, dtype=np.int16)) # pausa entre frases
total = sum(len(p) for p in parts) / rate
index += 1
samples = np.concatenate(parts)[: int(seconds * rate)]
return encode_ogg_opus(Pcm(samples, rate))
def main() -> None:
models_dir = Path(os.environ.get("VOICE_MODELS_DIR", "/models"))
voices = load_catalog(ROOT / "voices" / "catalog.json", ROOT / "models.lock.json", models_dir)
voice = next(v for v in voices.values() if v.default)
piper = PiperEngine(int(os.environ.get("VOICE_ONNX_THREADS", "2")))
clips = {f"{s}s": build_clip(piper, voice, s) for s in (5, 10, 30, 58)}
out = os.environ.get("BENCH_OUT")
if out:
Path(out).write_bytes(clips["10s"])
print(f"clipe de 10 s gravado em {out} ({len(clips['10s'])} bytes)")
threads = int(os.environ.get("VOICE_STT_THREADS", "2"))
beam = int(os.environ.get("VOICE_STT_BEAM_SIZE", "1"))
names = os.environ.get("BENCH_MODELS", os.environ.get("VOICE_STT_MODEL", "base")).split(",")
for name in names:
c0 = time.process_time()
w0 = time.perf_counter()
engine = FasterWhisperEngine(models_dir / "whisper" / name, name, "int8", threads, beam, True, 4000)
engine.transcribe(engine.decode(clips["5s"], 61), "pt") # aquecimento
print(f"[{name}] carga+aquecimento cpu={time.process_time() - c0:.2f}s wall={time.perf_counter() - w0:.2f}s")
cpu_total = audio_total = 0.0
for label, data in clips.items():
c0, w0 = time.process_time(), time.perf_counter()
samples = engine.decode(data, 61)
result = engine.transcribe(samples, "pt")
cpu, wall = time.process_time() - c0, time.perf_counter() - w0
audio = samples.size / SAMPLE_RATE
cpu_total += cpu
audio_total += audio
print(
f"[{name}] {label}: audio={audio:.1f}s cpu={cpu:.2f}s wall={wall:.2f}s cpu_por_s={cpu / audio:.3f} "
f"rtf_wall={wall / audio:.3f} no_speech={result.no_speech_prob:.3f} texto='{result.text[:70]}'"
)
print(f"[{name}] TOTAL threads={threads} beam={beam} cpu_por_s_audio={cpu_total / audio_total:.3f}")
if __name__ == "__main__":
main()
+67
View File
@@ -0,0 +1,67 @@
"""Baixa os pesos listados no models.lock.json para VOICE_MODELS_DIR e confere o sha256.
Uso: python scripts/fetch_models.py [--group v1 --group stt-base] [--dest /models]
Reprodutível: arquivo já presente com o hash certo não é baixado de novo; hash errado = falha.
"""
from __future__ import annotations
import argparse
import hashlib
import json
import os
import sys
import urllib.request
from pathlib import Path
ROOT = Path(__file__).resolve().parent.parent
def sha256_file(path: Path) -> str:
digest = hashlib.sha256()
with path.open("rb") as handle:
for block in iter(lambda: handle.read(1 << 20), b""):
digest.update(block)
return digest.hexdigest()
def fetch(entry: dict, dest: Path) -> None:
target = dest / entry["path"]
if target.is_file() and sha256_file(target) == entry["sha256"]:
print(f"ok (já presente) {entry['path']}")
return
if not entry["url"].startswith("https://"):
raise SystemExit(f"URL não-HTTPS recusada: {entry['path']}")
target.parent.mkdir(parents=True, exist_ok=True)
tmp = target.with_suffix(target.suffix + ".part")
print(f"baixando {entry['path']} ...")
with urllib.request.urlopen(entry["url"], timeout=120) as response, tmp.open("wb") as out: # noqa: S310 - https checado acima
while block := response.read(1 << 20):
out.write(block)
actual = sha256_file(tmp)
if actual != entry["sha256"]:
tmp.unlink(missing_ok=True)
raise SystemExit(f"checksum divergente em {entry['path']}: {actual}")
os.replace(tmp, target)
print(f"ok {entry['path']}")
def main() -> int:
parser = argparse.ArgumentParser()
parser.add_argument("--group", action="append", help="repita para baixar vários grupos (padrão: v1)")
parser.add_argument("--dest", default=os.environ.get("VOICE_MODELS_DIR", str(ROOT.parent / "data" / "voice" / "models")))
parser.add_argument("--lock", default=str(ROOT / "models.lock.json"))
args = parser.parse_args()
lock = json.loads(Path(args.lock).read_text(encoding="utf-8"))
groups = set(args.group or ["v1"])
entries = [e for e in lock["files"] if e.get("group", "v1") in groups]
if not entries:
print(f"nenhum arquivo nos grupos {sorted(groups)}", file=sys.stderr)
return 1
for entry in entries:
fetch(entry, Path(args.dest))
return 0
if __name__ == "__main__":
raise SystemExit(main())
+12
View File
@@ -0,0 +1,12 @@
"""HEALTHCHECK do container: chama /health (liveness sem chave e sem dado; o estado fica no /v1/status)."""
import os
import sys
import urllib.request
try:
url = f"http://127.0.0.1:{os.environ.get('PORT', '8000')}/health"
with urllib.request.urlopen(url, timeout=5) as response: # noqa: S310 - localhost fixo
sys.exit(0 if response.status == 200 else 1)
except Exception:
sys.exit(1)
+96
View File
@@ -0,0 +1,96 @@
"""Teste de fumaça do serviço de voz rodando (porta 4510): status, síntese de cada voz e transcrição com tempos.
Uso: voice/.venv/Scripts/python voice/scripts/smoke.py [--out output/voice-smoke]
Lê a chave do voice/.env. Grava os WAV gerados e o JSON da transcrição na pasta de saída.
"""
from __future__ import annotations
import argparse
import json
import os
import sys
import time
import urllib.error
import urllib.request
from pathlib import Path
VOICE_ROOT = Path(__file__).resolve().parent.parent
sys.path.insert(0, str(VOICE_ROOT))
from app.config import PROJECT_ROOT, load_dotenv # noqa: E402
TEXT = "Olá! Este é o serviço de voz do CenaForge, gerando a narração do episódio."
def call(method: str, path: str, key: str, port: int, body: bytes | None = None, headers: dict | None = None):
request = urllib.request.Request(
f"http://127.0.0.1:{port}{path}", data=body, method=method,
headers={"X-Service-Key": key, **(headers or {})},
)
try:
with urllib.request.urlopen(request, timeout=300) as response: # noqa: S310 - localhost fixo
return response.status, {k.lower(): v for k, v in response.headers.items()}, response.read()
except urllib.error.HTTPError as error:
return error.code, {k.lower(): v for k, v in error.headers.items()}, error.read()
def main() -> int:
parser = argparse.ArgumentParser()
parser.add_argument("--out", default=str(PROJECT_ROOT / "output" / "voice-smoke"))
parser.add_argument("--detail", default="words", choices=("text", "segments", "words"))
args = parser.parse_args()
load_dotenv(VOICE_ROOT / ".env")
key = os.environ["VOICE_SERVICE_KEY"]
port = int(os.environ.get("VOICE_PORT", "4510"))
out = Path(args.out)
out.mkdir(parents=True, exist_ok=True)
status, _, raw = call("GET", "/v1/status", key, port)
data = json.loads(raw)
print(f"status {status}: dispositivo={data['device']} rvc={data['rvc']} motores={data['engines']}")
voices = json.loads(call("GET", "/v1/voices", key, port)[2])["items"]
first_wav: Path | None = None
for voice in voices:
request_id = f"smoke-{voice['id']}-{int(time.time())}"
payload = {"requestId": request_id[:64], "text": TEXT, "voiceId": voice["id"], "params": {"format": "wav"}}
started = time.perf_counter()
code, headers, audio = call(
"POST", "/v1/synthesize", key, port, json.dumps(payload).encode(), {"Content-Type": "application/json"}
)
wall = time.perf_counter() - started
if code != 200:
print(f" {voice['id']}: ERRO {code} {audio[:200]!r}")
continue
target = out / f"{voice['id']}.wav"
target.write_bytes(audio)
first_wav = first_wav or target
print(f" {voice['id']} ({voice.get('provider')}): {headers.get('x-audio-duration-ms')} ms de áudio "
f"em {wall:.2f} s -> {target}")
if first_wav is None:
print("nenhuma voz gerou áudio")
return 1
audio = first_wav.read_bytes()
duration_ms = max(1, int((len(audio) - 44) / 2 / 24000 * 1000)) # WAV PCM16 mono; só uma estimativa
started = time.perf_counter()
code, _, raw = call("POST", "/v1/transcribe", key, port, audio, {
"Content-Type": "audio/wav", "X-Idempotency-Key": f"smoke-{int(time.time())}",
"X-Audio-Duration-Ms": str(duration_ms), "X-Language": "pt-BR", "X-Detail": args.detail,
})
result = json.loads(raw)
while code == 202:
time.sleep(result["retryAfterMs"] / 1000)
code, _, raw = call("GET", f"/v1/transcribe/jobs/{result['jobRef']}", key, port)
result = json.loads(raw)
wall = time.perf_counter() - started
(out / "transcribe.json").write_text(json.dumps(result, ensure_ascii=False, indent=2), encoding="utf-8")
print(f"transcrição {code} em {wall:.2f} s: {result.get('text')!r}")
if result.get("segments"):
words = [w for s in result["segments"] for w in s.get("words", [])]
print(f" {len(result['segments'])} segmento(s), {len(words)} palavra(s) com tempo")
return 0 if code == 200 else 1
if __name__ == "__main__":
raise SystemExit(main())
View File
+84
View File
@@ -0,0 +1,84 @@
from __future__ import annotations
import hashlib
import json
from contextlib import asynccontextmanager
from dataclasses import replace
from pathlib import Path
import httpx
import pytest
from app.config import Settings
from app.engine import FakeEngine
from app.main import create_app
from app.stt import FakeSttEngine
KEY = "k" * 40
HEADERS = {"X-Service-Key": KEY}
@pytest.fixture
def anyio_backend():
return "asyncio"
@pytest.fixture
def settings(tmp_path: Path) -> Settings:
models = tmp_path / "models"
(models / "piper").mkdir(parents=True)
files = {"piper/fake.onnx": b"fake-model", "piper/fake.onnx.json": b"{}"}
lock = []
for rel, content in files.items():
(models / rel).write_bytes(content)
lock.append({"path": rel, "url": "https://example.invalid/" + rel, "sha256": hashlib.sha256(content).hexdigest()})
(tmp_path / "lock.json").write_text(json.dumps({"files": lock}))
catalog = {
"voices": [
{
"id": "pt-br-test", "name": "Teste", "language": "pt-BR", "engine": "fake",
"model": "piper/fake.onnx", "config": "piper/fake.onnx.json", "sampleRate": 22050,
"default": True, "source": "teste", "license": "teste",
}
]
}
(tmp_path / "catalog.json").write_text(json.dumps(catalog))
return Settings(
service_key=KEY, models_dir=models, data_dir=tmp_path / "data",
catalog_path=tmp_path / "catalog.json", lock_path=tmp_path / "lock.json",
max_concurrency=1, max_queue_per_key=4, queue_timeout_s=5, synth_timeout_s=5,
max_text_chars=200, max_audio_s=10,
# Limites do contrato herdado do dropsz_voice (os testes de transcrição contam com 60 s / 8 MiB).
stt_max_audio_s=60, stt_max_bytes=8 * 1024 * 1024, stt_queue_timeout_s=90, stt_timeout_s=45,
)
@pytest.fixture
def engine() -> FakeEngine:
return FakeEngine()
@pytest.fixture
def stt_engine() -> FakeSttEngine:
return FakeSttEngine()
@pytest.fixture
def make_client(settings: Settings, engine: FakeEngine, stt_engine: FakeSttEngine):
@asynccontextmanager
async def _make(stt: FakeSttEngine | None | bool = True, **overrides):
# stt=True usa o motor falso do fixture; None desliga a transcrição; outro objeto substitui.
chosen = stt_engine if stt is True else stt
app = create_app(replace(settings, **overrides), engine=engine, stt_engine=chosen)
async with app.router.lifespan_context(app):
transport = httpx.ASGITransport(app=app)
async with httpx.AsyncClient(transport=transport, base_url="http://voice") as client:
yield client
return _make
def body(request_id: str = "req-00000001", text: str = "Olá, valeu pela doação!", **extra) -> dict:
payload = {"requestId": request_id, "text": text, "voiceId": "pt-br-test"}
payload.update(extra)
return payload
+65
View File
@@ -0,0 +1,65 @@
import pytest
from app.config import ConfigError, Settings
from tests.conftest import HEADERS, body
pytestmark = pytest.mark.anyio
@pytest.mark.parametrize(
("method", "path", "headers"),
[
("POST", "/health", {}),
("GET", "/v1/voices", {"X-Service-Key": "errada"}),
("GET", "/v1/voices/pt-br-test", {"X-Service-Key": "errada"}),
("POST", "/v1/synthesize", {}),
("GET", "/rota-que-nao-existe", {}),
("GET", "/docs", {}),
],
)
async def test_without_valid_key_is_401(make_client, method, path, headers):
async with make_client() as client:
response = await client.request(method, path, headers=headers, json=body())
assert response.status_code == 401
assert response.json()["error"]["code"] == "unauthorized"
async def test_malformed_json_without_key_is_401_not_422(make_client):
async with make_client() as client:
response = await client.post("/v1/synthesize", content=b"{nao-e-json", headers={"Content-Type": "application/json"})
assert response.status_code == 401
async def test_key_is_not_accepted_as_bearer(make_client):
async with make_client() as client:
response = await client.get("/v1/voices", headers={"Authorization": f"Bearer {HEADERS['X-Service-Key']}"})
assert response.status_code == 401
async def test_health_is_liveness_without_key_and_without_data(make_client):
async with make_client() as client:
anonymous = await client.get("/health")
wrong = await client.get("/health", headers={"X-Service-Key": "errada"})
for response in (anonymous, wrong):
assert response.status_code == 200
assert response.json() == {"status": "ok"}
async def test_valid_key_opens_status_and_voices(make_client):
async with make_client() as client:
status = await client.get("/v1/status", headers=HEADERS)
voices = await client.get("/v1/voices", headers=HEADERS)
assert status.status_code == 200 and status.json()["status"] == "ok"
assert [v["id"] for v in voices.json()["items"]] == ["pt-br-test"]
async def test_openapi_is_disabled(make_client):
async with make_client() as client:
assert (await client.get("/openapi.json", headers=HEADERS)).status_code == 404
@pytest.mark.parametrize("key", ["", "curta"])
def test_service_refuses_to_start_without_strong_key(monkeypatch, key):
monkeypatch.setenv("VOICE_SERVICE_KEY", key)
with pytest.raises(ConfigError):
Settings.from_env()
+373
View File
@@ -0,0 +1,373 @@
"""Funções que o CenaForge acrescentou ao serviço herdado do dropsz_voice.
Vozes Edge (sem arquivo local), vozes de personagem do usuário (voz base + RVC), saída WAV para o render,
transcrição com tempos (legenda) e recarga do catálogo pelo painel.
"""
import hashlib
import json
import os
from dataclasses import replace
from pathlib import Path
import numpy as np
import pytest
from app.catalog import load_catalog
from app.engine import edge_rate
from tests.conftest import HEADERS, body
pytestmark = pytest.mark.anyio
ONE_SECOND = b"OggS" + b"x" * 100
def stt_headers(detail: str, key: str = "ep01:legenda") -> dict:
return {
**HEADERS, "Content-Type": "audio/ogg", "X-Idempotency-Key": key,
"X-Audio-Duration-Ms": "1000", "X-Language": "pt-BR", "X-Detail": detail,
}
def add_edge_voice(settings) -> None:
catalog = json.loads(settings.catalog_path.read_text())
catalog["voices"].append({
"id": "pt-br-francisca", "name": "Francisca", "language": "pt-BR", "engine": "edge",
"edgeVoice": "pt-BR-FranciscaNeural", "sampleRate": 24000, "source": "edge", "license": "edge",
"gender": "female",
})
settings.catalog_path.write_text(json.dumps(catalog))
def add_user_voice(settings, tmp_path: Path, model_sha: str | None = None) -> Path:
folder = settings.models_dir / "rvc" / "heroi"
folder.mkdir(parents=True, exist_ok=True)
(folder / "heroi.pth").write_bytes(b"pesos-rvc")
(folder / "heroi.index").write_bytes(b"indice")
user = tmp_path / "user-voices.json"
user.write_text(json.dumps({"voices": [{
"id": "heroi", "name": "Herói", "baseVoice": "pt-br-test",
"rvc": {
"model": "rvc/heroi/heroi.pth", "modelSha256": model_sha or hashlib.sha256(b"pesos-rvc").hexdigest(),
"index": "rvc/heroi/heroi.index", "indexSha256": hashlib.sha256(b"indice").hexdigest(), "pitch": 2,
},
}]}))
return user
def test_edge_rate():
assert edge_rate(1.0) == "+0%"
assert edge_rate(1.25) == "+25%"
assert edge_rate(0.8) == "-20%"
def test_edge_voice_needs_no_local_file(settings):
add_edge_voice(settings)
voices = load_catalog(settings.catalog_path, settings.lock_path, settings.models_dir)
edge = voices["pt-br-francisca"]
assert edge.engine == "edge" and edge.model is None and edge.edge_voice == "pt-BR-FranciscaNeural"
# Revisão estável: a mesma voz Edge sempre cai na mesma chave de cache.
again = load_catalog(settings.catalog_path, settings.lock_path, settings.models_dir)
assert again["pt-br-francisca"].revision == edge.revision
def test_user_voice_is_verified_and_bad_one_is_skipped(settings, tmp_path, caplog):
user = add_user_voice(settings, tmp_path)
voices = load_catalog(settings.catalog_path, settings.lock_path, settings.models_dir, True, user)
heroi = voices["heroi"]
assert heroi.user and heroi.base_voice == "pt-br-test" and heroi.rvc["pitch"] == 2
assert heroi.rvc["modelPath"].name == "heroi.pth" and not heroi.default
user = add_user_voice(settings, tmp_path, model_sha="0" * 64)
voices = load_catalog(settings.catalog_path, settings.lock_path, settings.models_dir, True, user)
assert "heroi" not in voices and "pt-br-test" in voices # a voz quebrada não derruba as outras
assert "voz do usuário ignorada" in caplog.text
async def test_user_voice_descriptor_and_rvc_disabled(make_client, settings, tmp_path):
user = add_user_voice(settings, tmp_path)
async with make_client(user_catalog_path=user) as client:
described = (await client.get("/v1/voices/heroi", headers=HEADERS)).json()
response = await client.post("/v1/synthesize", json=body(voiceId="heroi"), headers=HEADERS)
assert described["engine"] == "tts+rvc" and described["user"] is True and described["baseVoice"] == "pt-br-test"
assert described["rvc"] == {"pitch": 2, "f0Method": "rmvpe", "indexRate": 0.5, "protect": 0.33, "hasIndex": True}
assert "heroi.pth" not in json.dumps(described) # nunca o caminho do arquivo
assert response.status_code == 501 and response.json()["error"]["code"] == "rvc_disabled"
async def test_wav_output_for_render(make_client):
async with make_client() as client:
wav = await client.post("/v1/synthesize", json=body(params={"format": "wav"}), headers=HEADERS)
ogg = await client.post("/v1/synthesize", json=body("req-00000002"), headers=HEADERS)
assert wav.status_code == 200 and wav.headers["content-type"] == "audio/wav"
assert wav.content[:4] == b"RIFF"
assert ogg.content[:4] == b"OggS"
@pytest.mark.parametrize("detail", ["segments", "words"])
async def test_transcribe_with_timestamps(make_client, stt_engine, detail):
async with make_client() as client:
response = await client.post("/v1/transcribe", content=ONE_SECOND, headers=stt_headers(detail))
data = response.json()
assert response.status_code == 200 and data["durationS"] == pytest.approx(1.0)
[segment] = data["segments"]
assert segment["text"] == "valeu pela live" and segment["start"] == 0.0
if detail == "words":
assert [w["text"] for w in segment["words"]] == ["valeu", "pela", "live"]
assert segment["words"][-1]["end"] == pytest.approx(1.0)
else:
assert "words" not in segment
assert stt_engine.details == [detail]
async def test_detail_changes_the_job(make_client, stt_engine):
# Mesma idempotencyKey com outro detalhe = outro conteúdo: conflito, não resposta errada do cache.
async with make_client() as client:
await client.post("/v1/transcribe", content=ONE_SECOND, headers=stt_headers("text"))
response = await client.post("/v1/transcribe", content=ONE_SECOND, headers=stt_headers("words"))
assert response.status_code == 409
async def test_reload_picks_up_new_user_voice(make_client, settings, tmp_path):
user = tmp_path / "user-voices.json"
async with make_client(user_catalog_path=user) as client:
assert (await client.get("/v1/voices/heroi", headers=HEADERS)).status_code == 404
add_user_voice(settings, tmp_path)
reloaded = await client.post("/v1/voices/reload", headers=HEADERS)
assert reloaded.json() == {"status": "ok", "count": 2}
assert (await client.get("/v1/voices/heroi", headers=HEADERS)).status_code == 200
def _add_catalog_voice(settings, voice_id: str, model: str = "piper/fake.onnx") -> None:
catalog = json.loads(settings.catalog_path.read_text())
catalog["voices"].append({
"id": voice_id, "name": "Nova", "language": "pt-BR", "engine": "fake", "model": model,
"config": "piper/fake.onnx.json", "sampleRate": 22050, "source": "teste", "license": "teste",
})
settings.catalog_path.write_text(json.dumps(catalog))
stat = settings.catalog_path.stat()
# Garante data de modificação diferente mesmo em sistema de arquivos com resolução grossa.
os.utime(settings.catalog_path, ns=(stat.st_atime_ns, stat.st_mtime_ns + 10_000_000_000))
@pytest.mark.anyio
async def test_catalog_change_shows_up_without_reload(make_client, settings):
async with make_client() as client:
assert (await client.get("/v1/voices/pt-br-nova", headers=HEADERS)).status_code == 404
_add_catalog_voice(settings, "pt-br-nova")
listed = await client.get("/v1/voices", headers=HEADERS)
assert "pt-br-nova" in [v["id"] for v in listed.json()["items"]]
@pytest.mark.anyio
async def test_broken_catalog_change_keeps_current_voices(make_client, settings):
async with make_client() as client:
_add_catalog_voice(settings, "pt-br-quebrada", model="piper/ausente.onnx")
listed = await client.get("/v1/voices", headers=HEADERS)
assert listed.status_code == 200
assert [v["id"] for v in listed.json()["items"]] == ["pt-br-test"]
def test_real_decoder_reads_wav_and_mp3_like_containers():
import io
import soundfile
from app.decode import decode_audio
from app.errors import InvalidAudio
tone = (np.sin(np.arange(22050) * 2 * np.pi * 220 / 22050) * 8000).astype(np.int16)
buffer = io.BytesIO()
soundfile.write(buffer, tone, 22050, format="WAV", subtype="PCM_16")
samples = decode_audio(buffer.getvalue(), 16000, max_seconds=10)
assert samples.dtype == np.float32 and abs(samples.size / 16000 - 1.0) < 0.05
pcm = decode_audio(buffer.getvalue(), 24000, max_seconds=10, sample_format="s16")
assert pcm.dtype == np.int16
with pytest.raises(InvalidAudio):
decode_audio(b"isto nao e audio", 16000, max_seconds=10)
def test_settings_defaults_point_inside_project(monkeypatch):
from app.config import PROJECT_ROOT, Settings
monkeypatch.setenv("VOICE_SERVICE_KEY", "k" * 40)
for name in ("VOICE_MODELS_DIR", "VOICE_DATA_DIR", "VOICE_STT_MODEL", "VOICE_DEVICE"):
monkeypatch.delenv(name, raising=False)
settings = Settings.from_env()
assert settings.models_dir == PROJECT_ROOT / "data" / "voice" / "models"
assert settings.device in ("auto", "cuda", "cpu")
monkeypatch.setenv("VOICE_MODELS_DIR", "outra/pasta")
assert Settings.from_env().models_dir == PROJECT_ROOT / "outra" / "pasta" # relativo = raiz do projeto
assert replace(settings, device="cpu").device == "cpu"
async def test_duration_header_is_optional(make_client, stt_engine):
headers = {k: v for k, v in stt_headers("text", key="sem-duracao").items() if k != "X-Audio-Duration-Ms"}
async with make_client() as client:
ok = await client.post("/v1/transcribe", content=ONE_SECOND, headers=headers)
# O teto continua valendo pelo áudio decodificado (61 s > 60 s do fixture).
long = await client.post("/v1/transcribe", content=b"OggS" + b"x" * 6100, headers={**headers, "X-Idempotency-Key": "longo"})
assert ok.status_code == 200 and ok.json()["text"] == "valeu pela live"
assert long.status_code == 422 and long.json()["error"]["code"] == "audio_too_long"
@pytest.mark.parametrize(
("smi", "busy"),
[("7000, 10", False), ("1024, 10", True), ("7000, 99", True)],
)
def test_gpu_busy_reason_reads_nvidia_smi(monkeypatch, smi, busy):
import subprocess
from types import SimpleNamespace
from app import device
monkeypatch.setattr(subprocess, "run", lambda *a, **k: SimpleNamespace(stdout=smi + "\n"))
reason = device.gpu_busy_reason()
assert (reason is not None) == busy
if busy:
assert "GPU ocupada" in reason
def test_gpu_busy_reason_without_nvidia_smi(monkeypatch):
import subprocess
from app import device
def boom(*a, **k):
raise FileNotFoundError("nvidia-smi")
monkeypatch.setattr(subprocess, "run", boom)
assert device.gpu_busy_reason() is None # sem a ferramenta, não bloqueia a GPU
def _write_catalog(settings, extra: dict) -> None:
catalog = json.loads(settings.catalog_path.read_text())
catalog["voices"].append({
"id": "extra", "name": "Extra", "language": "pt-BR", "sampleRate": 24000, "source": "teste", "license": "teste",
**extra,
})
settings.catalog_path.write_text(json.dumps(catalog))
def test_catalog_reads_kokoro_and_google_voices(settings):
_write_catalog(settings, {"engine": "kokoro", "model": "piper/fake.onnx", "config": "piper/fake.onnx.json",
"kokoroVoice": "pf_dora"})
voice = load_catalog(settings.catalog_path, settings.lock_path, settings.models_dir)["extra"]
assert (voice.engine, voice.engine_voice, voice.engine_lang) == ("kokoro", "pf_dora", "pt-br")
catalog = json.loads(settings.catalog_path.read_text())
catalog["voices"][-1] = {**catalog["voices"][-1], "engine": "google", "googleTld": "pt"}
settings.catalog_path.write_text(json.dumps(catalog))
voice = load_catalog(settings.catalog_path, settings.lock_path, settings.models_dir)["extra"]
assert (voice.engine, voice.engine_voice, voice.engine_lang) == ("google", "pt", "pt")
def test_kokoro_voice_without_style_is_rejected(settings):
from app.config import ConfigError
_write_catalog(settings, {"engine": "kokoro", "model": "piper/fake.onnx", "config": "piper/fake.onnx.json"})
with pytest.raises(ConfigError, match="kokoroVoice"):
load_catalog(settings.catalog_path, settings.lock_path, settings.models_dir)
@pytest.mark.anyio
async def test_online_flag_follows_engine(make_client, settings):
_write_catalog(settings, {"engine": "google"})
async with make_client() as client:
items = {v["id"]: v for v in (await client.get("/v1/voices", headers=HEADERS)).json()["items"]}
assert items["extra"]["offline"] is False and items["pt-br-test"]["offline"] is True
def test_azure_ssml_escapes_text_and_sets_rate():
from app.engine import AzureEngine
voice = replace(_azure_voice(), engine_voice="pt-BR-FabioNeural")
ssml = AzureEngine("k", "eastus").ssml(voice, 'Oi <b>"x"</b> & tchau', 1.25).decode("utf-8")
assert "&lt;b&gt;" in ssml and "&amp;" in ssml and "<b>" not in ssml
assert 'name="pt-BR-FabioNeural"' in ssml and 'xml:lang="pt-BR"' in ssml and 'rate="+25%"' in ssml
assert "xmlns='http://www.w3.org/2001/10/synthesis'" in ssml
def _azure_voice():
from app.catalog import Voice
return Voice(id="azure-x", name="X", language="pt-BR", engine="azure", model=None, config=None, sample_rate=24000,
default=False, source="t", license="t", revision="r", engine_voice="pt-BR-FabioNeural")
def test_azure_synthesis_sends_key_and_decodes_wav(monkeypatch):
import io
import urllib.request
import soundfile
from app.engine import AzureEngine
tone = (np.sin(np.arange(24000) * 2 * np.pi * 220 / 24000) * 8000).astype(np.int16)
buffer = io.BytesIO()
soundfile.write(buffer, tone, 24000, format="WAV", subtype="PCM_16")
seen = {}
class FakeResponse(io.BytesIO):
def __enter__(self):
return self
def __exit__(self, *exc):
return False
def fake_urlopen(request, timeout):
seen["url"], seen["key"] = request.full_url, request.get_header("Ocp-apim-subscription-key")
return FakeResponse(buffer.getvalue())
monkeypatch.setattr(urllib.request, "urlopen", fake_urlopen)
pcm = AzureEngine("segredo", "brazilsouth").synthesize(_azure_voice(), "Olá", 1.0, 10)
assert seen == {"url": "https://brazilsouth.tts.speech.microsoft.com/cognitiveservices/v1", "key": "segredo"}
assert pcm.sample_rate == 24000 and abs(pcm.duration_s - 1.0) < 0.05
@pytest.mark.anyio
async def test_azure_voices_hidden_without_key(make_client, settings):
_write_catalog(settings, {"engine": "azure", "azureVoice": "pt-BR-FabioNeural"})
async with make_client() as client:
ids = [v["id"] for v in (await client.get("/v1/voices", headers=HEADERS)).json()["items"]]
assert "extra" not in ids
async with make_client(azure_key="chave") as client:
items = {v["id"]: v for v in (await client.get("/v1/voices", headers=HEADERS)).json()["items"]}
assert items["extra"]["offline"] is False and items["extra"]["provider"] == "azure"
def _add_clone_voice(settings, tmp_path, consent=True):
reference = settings.models_dir / "clone" / "clone-eu" / "reference.wav"
reference.parent.mkdir(parents=True)
reference.write_bytes(b"RIFF-fake-wav")
entry = {
"id": "clone-eu", "name": "Eu", "kind": "clone", "gender": "male", "source": "minha voz", "license": "minha",
"consent": consent,
"clone": {"reference": "clone/clone-eu/reference.wav",
"referenceSha256": hashlib.sha256(b"RIFF-fake-wav").hexdigest(), "exaggeration": 0.7},
}
user = tmp_path / "user-voices.json"
user.write_text(json.dumps({"voices": [entry]}))
return user
def test_clone_voice_loads_with_consent(settings, tmp_path):
user = _add_clone_voice(settings, tmp_path)
voice = load_catalog(settings.catalog_path, settings.lock_path, settings.models_dir, user_catalog_path=user)["clone-eu"]
assert (voice.engine, voice.user, voice.engine_lang) == ("clone", True, "pt")
assert voice.clone == {"exaggeration": 0.7, "cfgWeight": 0.5} and voice.model.name == "reference.wav"
def test_clone_voice_without_consent_is_skipped(settings, tmp_path):
user = _add_clone_voice(settings, tmp_path, consent=False)
voices = load_catalog(settings.catalog_path, settings.lock_path, settings.models_dir, user_catalog_path=user)
assert "clone-eu" not in voices
def test_clone_engine_reports_worker_down():
from app.engine import CloneEngine
from app.errors import CloneUnavailable
voice = replace(_azure_voice(), engine="clone", model=Path("x.wav"), clone={"exaggeration": 0.5, "cfgWeight": 0.5})
with pytest.raises(CloneUnavailable):
CloneEngine(4599, "k", timeout_s=2).synthesize(voice, "Olá", 1.0, 10)
+82
View File
@@ -0,0 +1,82 @@
import pytest
from app.store import Store
from tests.conftest import HEADERS, body
pytestmark = pytest.mark.anyio
async def test_same_request_id_same_payload_is_replay(make_client, engine):
async with make_client() as client:
first = await client.post("/v1/synthesize", json=body(), headers=HEADERS)
second = await client.post("/v1/synthesize", json=body(), headers=HEADERS)
assert first.status_code == second.status_code == 200
assert second.headers["x-idempotent-replay"] == "true"
assert second.headers["x-cache"] == "hit"
assert first.content == second.content
assert engine.calls == 1
async def test_same_request_id_other_payload_is_409(make_client):
async with make_client() as client:
await client.post("/v1/synthesize", json=body(), headers=HEADERS)
other_text = await client.post("/v1/synthesize", json=body(text="Outra coisa"), headers=HEADERS)
other_speed = await client.post("/v1/synthesize", json=body(params={"speed": 1.5}), headers=HEADERS)
assert other_text.status_code == other_speed.status_code == 409
assert other_text.json()["error"]["code"] == "idempotency_conflict"
async def test_normalized_text_is_the_same_request(make_client, engine):
async with make_client() as client:
await client.post("/v1/synthesize", json=body(text="Olá, valeu\n pela doação!"), headers=HEADERS)
again = await client.post("/v1/synthesize", json=body(text=" Olá, valeu pela doação! "), headers=HEADERS)
assert again.status_code == 200
assert engine.calls == 1
async def test_cache_hit_across_request_ids(make_client, engine):
async with make_client() as client:
first = await client.post("/v1/synthesize", json=body("req-aaaaaaaa"), headers=HEADERS)
second = await client.post("/v1/synthesize", json=body("req-bbbbbbbb"), headers=HEADERS)
assert first.headers["x-cache"] == "miss"
assert second.headers["x-cache"] == "hit"
assert second.headers["x-idempotent-replay"] == "false"
assert first.headers["x-audio-sha256"] == second.headers["x-audio-sha256"]
assert engine.calls == 1
async def test_different_params_or_text_miss(make_client, engine):
async with make_client() as client:
await client.post("/v1/synthesize", json=body("req-aaaaaaaa"), headers=HEADERS)
speed = await client.post("/v1/synthesize", json=body("req-bbbbbbbb", params={"speed": 1.25}), headers=HEADERS)
text = await client.post("/v1/synthesize", json=body("req-cccccccc", text="Outro texto"), headers=HEADERS)
assert speed.headers["x-cache"] == text.headers["x-cache"] == "miss"
assert engine.calls == 3
async def test_cache_survives_restart(make_client, engine):
async with make_client() as client:
await client.post("/v1/synthesize", json=body("req-aaaaaaaa"), headers=HEADERS)
async with make_client() as client:
again = await client.post("/v1/synthesize", json=body("req-aaaaaaaa"), headers=HEADERS)
assert again.headers["x-cache"] == "hit"
assert again.headers["x-idempotent-replay"] == "true"
assert engine.calls == 1
def test_store_evicts_least_recently_used(tmp_path):
store = Store(tmp_path, cache_max_mb=1, idempotency_ttl_h=1)
chunk = b"x" * (400 * 1024)
store.put("a" * 64, chunk, 1000, "h")
store.put("b" * 64, chunk, 1000, "h")
store.get("a" * 64) # "a" fica mais recente que "b"
store.put("c" * 64, chunk, 1000, "h")
assert store.get("b" * 64) is None
assert store.get("a" * 64) is not None and store.get("c" * 64) is not None
assert store.stats()["bytes"] <= 1024 * 1024
def test_request_id_bound_by_primary_key(tmp_path):
store = Store(tmp_path, cache_max_mb=1, idempotency_ttl_h=1)
assert store.bind_request("env", "req-1", "k1") == (True, "k1")
assert store.bind_request("env", "req-1", "k2") == (False, "k1")
+274
View File
@@ -0,0 +1,274 @@
"""Isolamento entre chaves de serviço (homologação e produção no mesmo serviço): fila, idempotência e jobs."""
import asyncio
import logging
import sqlite3
import threading
from dataclasses import replace
from pathlib import Path
import pytest
from app.errors import QueueFull, QueueTimeout, SynthesisTimeout
from app.keys import issue_key, keys_path
from app.store import Store
from app.work_queue import WorkQueue
from tests.conftest import HEADERS, body
from tests.test_queue import _wait_until
from tests.test_transcribe import ONE_SECOND, stt_headers
pytestmark = pytest.mark.anyio
def _issue(settings, scopes=("tts", "transcribe", "status"), name="homolog"):
record, plaintext = issue_key(keys_path(settings.data_dir), name, tuple(scopes))
return record, {"X-Service-Key": plaintext}
# ---------- fila ----------
async def test_full_queue_of_one_key_does_not_refuse_the_other():
gate = threading.Event()
queue = WorkQueue(max_concurrency=1, max_queue_per_key=1, queue_timeout_s=5, run_timeout_s=5)
running = asyncio.create_task(queue.run(lambda: gate.wait(5), owner="homolog"))
await _wait_until(lambda: queue.running == 1)
homolog_waiting = asyncio.create_task(queue.run(lambda: "homolog-2", owner="homolog"))
await _wait_until(lambda: queue.waiting_for("homolog") == 1)
with pytest.raises(QueueFull):
await queue.run(lambda: "homolog-3", owner="homolog")
assert not queue.is_full("prod")
prod = asyncio.create_task(queue.run(lambda: "prod-1", owner="prod"))
await _wait_until(lambda: queue.waiting_for("prod") == 1)
gate.set()
assert await running is True
assert await homolog_waiting == "homolog-2"
assert await prod == "prod-1"
queue.shutdown()
async def test_cpu_slot_rotates_between_keys():
"""A vaga de CPU é global, mas entregue em rodízio: a produção não espera a fila inteira da homologação."""
gate = threading.Event()
order: list[str] = []
queue = WorkQueue(max_concurrency=1, max_queue_per_key=5, queue_timeout_s=5, run_timeout_s=5)
first = asyncio.create_task(queue.run(lambda: gate.wait(5), owner="homolog"))
await _wait_until(lambda: queue.running == 1)
tasks = [asyncio.create_task(queue.run(lambda i=i: order.append(f"homolog-{i}"), owner="homolog")) for i in range(3)]
await _wait_until(lambda: queue.waiting_for("homolog") == 3)
tasks.append(asyncio.create_task(queue.run(lambda: order.append("prod"), owner="prod")))
await _wait_until(lambda: queue.waiting_for("prod") == 1)
gate.set()
await first
await asyncio.gather(*tasks)
assert order == ["prod", "homolog-0", "homolog-1", "homolog-2"]
queue.shutdown()
async def test_http_full_queue_of_one_key_does_not_block_the_other(make_client, settings, engine):
engine.gate = threading.Event()
async with make_client(max_concurrency=1, max_queue_per_key=1) as client:
_, homolog = _issue(settings)
first = asyncio.create_task(client.post("/v1/synthesize", json=body("req-h0000001", text="um"), headers=homolog))
await _wait_until(lambda: engine.calls == 1)
second = asyncio.create_task(client.post("/v1/synthesize", json=body("req-h0000002", text="dois"), headers=homolog))
await asyncio.sleep(0.1)
refused = await client.post("/v1/synthesize", json=body("req-h0000003", text="três"), headers=homolog)
status_homolog = (await client.get("/v1/status", headers=homolog)).json()["queues"]["synthesis"]
status_prod = (await client.get("/v1/status", headers=HEADERS)).json()["queues"]["synthesis"]
prod = asyncio.create_task(client.post("/v1/synthesize", json=body("req-p0000001", text="pago"), headers=HEADERS))
await asyncio.sleep(0.1)
engine.gate.set()
results = [await first, await second, await prod]
assert refused.status_code == 503 and refused.json()["error"]["code"] == "queue_full"
assert [r.status_code for r in results] == [200, 200, 200]
# O /v1/status mostra a fila da própria chave: a homologação cheia não aparece como cheia para a produção.
assert status_homolog["waiting"] == 1 and status_homolog["maxQueue"] == 1
assert status_prod["waiting"] == 0 and status_prod["running"] == 1
# ---------- idempotência da síntese ----------
async def test_same_request_id_on_two_keys_are_distinct_requests(make_client, settings):
async with make_client() as client:
_, homolog = _issue(settings)
prod = await client.post("/v1/synthesize", json=body("req-colide01", text="texto da produção"), headers=HEADERS)
other = await client.post("/v1/synthesize", json=body("req-colide01", text="texto da homologação"), headers=homolog)
assert prod.status_code == 200 and other.status_code == 200 # sem 409: são pedidos diferentes
assert prod.headers["x-idempotent-replay"] == "false"
assert other.headers["x-idempotent-replay"] == "false"
assert prod.content != other.content
async def test_same_key_stays_idempotent(make_client, settings):
async with make_client() as client:
_, homolog = _issue(settings)
first = await client.post("/v1/synthesize", json=body("req-idem0001"), headers=homolog)
again = await client.post("/v1/synthesize", json=body("req-idem0001"), headers=homolog)
conflict = await client.post("/v1/synthesize", json=body("req-idem0001", text="outro texto"), headers=homolog)
assert first.headers["x-idempotent-replay"] == "false"
assert again.headers["x-idempotent-replay"] == "true" and again.content == first.content
assert conflict.status_code == 409
# ---------- transcrição ----------
async def test_job_of_another_key_answers_like_an_unknown_job(make_client, settings):
async with make_client(stt_sync_wait_s=0.0) as client:
_, homolog = _issue(settings)
created = await client.post("/v1/transcribe", content=ONE_SECOND, headers=stt_headers())
ref = created.headers["x-job-ref"]
await asyncio.sleep(0.05)
own = await client.get(f"/v1/transcribe/jobs/{ref}", headers=HEADERS)
foreign = await client.get(f"/v1/transcribe/jobs/{ref}", headers=homolog)
unknown = await client.get("/v1/transcribe/jobs/abcdefghijkl", headers=homolog)
assert own.status_code in (200, 202)
# Mesmo status e mesmo corpo de um job inexistente: não revela que o job existe.
assert foreign.status_code == unknown.status_code == 410
assert foreign.json() == unknown.json()
assert "x-job-ref" not in foreign.headers
async def test_same_idempotency_key_on_two_keys_does_not_collide(make_client, settings, stt_engine):
async with make_client() as client:
_, homolog = _issue(settings)
prod = await client.post("/v1/transcribe", content=ONE_SECOND, headers=stt_headers(key="order:1:t"))
other = await client.post(
"/v1/transcribe", content=ONE_SECOND + b"z", headers=stt_headers(key="order:1:t", **homolog)
)
same_audio = await client.post(
"/v1/transcribe", content=ONE_SECOND, headers=stt_headers(key="order:2:t", **homolog)
)
replay = await client.post("/v1/transcribe", content=ONE_SECOND, headers=stt_headers(key="order:1:t"))
assert prod.status_code == other.status_code == 200 # sem 409 entre chaves
assert other.headers["x-idempotent-replay"] == "false"
# O mesmo áudio por outra chave vira outro job (nada de jobRef compartilhado entre chaves).
assert same_audio.headers["x-job-ref"] != prod.headers["x-job-ref"]
assert replay.headers["x-idempotent-replay"] == "true"
assert replay.headers["x-job-ref"] == prod.headers["x-job-ref"]
# ---------- banco no formato antigo ----------
LEGACY_SCHEMA = """
CREATE TABLE IF NOT EXISTS requests (request_id TEXT PRIMARY KEY, cache_key TEXT NOT NULL, created_at INTEGER NOT NULL);
CREATE TABLE IF NOT EXISTS transcribe_requests (
idempotency_key TEXT PRIMARY KEY, content_key TEXT NOT NULL, created_at INTEGER NOT NULL
);
CREATE TABLE IF NOT EXISTS cache (
cache_key TEXT PRIMARY KEY, size INTEGER NOT NULL, duration_ms INTEGER NOT NULL, sha256 TEXT NOT NULL,
created_at INTEGER NOT NULL, last_used_at INTEGER NOT NULL
);
"""
def _legacy_bind(db_path, request_id, cache_key):
"""O que a imagem anterior faz no bind_request: INSERT sem key_id e, no conflito, lê a linha gravada."""
db = sqlite3.connect(db_path)
try:
db.execute("INSERT INTO requests(request_id, cache_key, created_at) VALUES (?, ?, strftime('%s','now'))",
(request_id, cache_key))
db.commit()
return True, cache_key
except sqlite3.IntegrityError:
return False, db.execute("SELECT cache_key FROM requests WHERE request_id = ?", (request_id,)).fetchone()[0]
finally:
db.close()
def test_store_boots_over_legacy_database_and_keeps_rollback_working(tmp_path):
db_path = tmp_path / "voice.sqlite3"
db = sqlite3.connect(db_path)
db.executescript(LEGACY_SCHEMA)
db.execute("INSERT INTO requests VALUES ('req-antigo1', 'k-antiga', strftime('%s','now'))")
db.execute("INSERT INTO transcribe_requests VALUES ('order:9:t', 'c-antiga', strftime('%s','now'))")
db.commit()
db.close()
store = Store(tmp_path, cache_max_mb=1, idempotency_ttl_h=1)
cached = store.put("a" * 64, b"ogg", 1000, "h")
assert store.bind_request("env", "req-antigo1", "k-nova") == (True, "k-nova")
assert store.bind_request("homolog", "req-antigo1", "k-outra") == (True, "k-outra")
assert store.bind_request("env", "req-antigo1", "k-x") == (False, "k-nova")
assert store.bind_transcription("env", "order:9:t", "c-nova") == (True, "c-nova")
store.close()
# As tabelas antigas continuam intactas: mesmo esquema e mesmas linhas.
db = sqlite3.connect(db_path)
assert [r[1] for r in db.execute("PRAGMA table_info(requests)")] == ["request_id", "cache_key", "created_at"]
assert db.execute("SELECT request_id, cache_key FROM requests").fetchall() == [("req-antigo1", "k-antiga")]
assert db.execute("SELECT idempotency_key, content_key FROM transcribe_requests").fetchall() == [
("order:9:t", "c-antiga")
]
db.close()
# Rollback: a imagem anterior segue gravando e fazendo replay sobre o mesmo arquivo, e enxerga o cache.
assert _legacy_bind(db_path, "req-rollback", "k-r") == (True, "k-r")
assert _legacy_bind(db_path, "req-rollback", "k-r") == (False, "k-r")
assert _legacy_bind(db_path, "req-antigo1", "k-antiga") == (False, "k-antiga")
# Volta para a versão nova: as amarrações dela continuam lá.
store = Store(tmp_path, cache_max_mb=1, idempotency_ttl_h=1)
assert store.bind_request("env", "req-antigo1", "k-x") == (False, "k-nova")
assert store.get(cached.cache_key) is not None
store.close()
# ---------- timeouts ----------
async def _hog_then_other(queue_timeout_s: float):
"""Chave A ocupa a CPU com um trabalho no teto (a thread passa do teto um pouco) e tem mais um esperando;
a chave B chega depois. Devolve o resultado (ou a exceção) de B."""
import time
queue = WorkQueue(max_concurrency=1, max_queue_per_key=4, queue_timeout_s=queue_timeout_s, run_timeout_s=0.3)
hog = asyncio.create_task(queue.run(lambda: time.sleep(0.35), owner="homolog"))
await _wait_until(lambda: queue.running == 1)
second = asyncio.create_task(queue.run(lambda: time.sleep(0.35), owner="homolog"))
await _wait_until(lambda: queue.waiting_for("homolog") == 1)
other = asyncio.create_task(queue.run(lambda: "prod", owner="prod"))
results = await asyncio.gather(hog, second, other, return_exceptions=True)
queue.shutdown()
return results
async def test_other_key_is_served_when_a_job_hits_the_ceiling():
# Espera = 2x execução (a relação dos padrões): B passa na frente do 2º trabalho de A e é atendido,
# mesmo com a thread de A passando um pouco do teto.
hog, second, other = await _hog_then_other(queue_timeout_s=0.6)
assert isinstance(hog, SynthesisTimeout)
assert other == "prod"
async def test_short_queue_timeout_lets_long_job_starve_the_other_key():
# Contraprova: espera menor que a execução, B leva queue_timeout atrás de um trabalho da outra chave.
_, _, other = await _hog_then_other(queue_timeout_s=0.2)
assert isinstance(other, QueueTimeout)
def test_default_timeouts_hold_the_relations():
from app.config import BACKEND_CLIENT_TIMEOUT_S, Settings
defaults = Settings(service_key="k" * 40, models_dir=Path("."), data_dir=Path("."), catalog_path=Path("."),
lock_path=Path("."))
assert defaults.timeout_warnings() == []
assert defaults.queue_timeout_s >= 2 * defaults.synth_timeout_s
assert defaults.stt_queue_timeout_s >= 2 * defaults.stt_timeout_s
assert defaults.queue_timeout_s + defaults.synth_timeout_s < BACKEND_CLIENT_TIMEOUT_S
bad = replace(defaults, queue_timeout_s=20.0, synth_timeout_s=30.0, stt_queue_timeout_s=90.0, stt_timeout_s=90.0)
warnings = bad.timeout_warnings()
assert any(w.startswith("VOICE_QUEUE_TIMEOUT_S=20 abaixo de 2x") for w in warnings)
assert any(w.startswith("VOICE_STT_QUEUE_TIMEOUT_S=90 abaixo de 2x") for w in warnings)
async def test_boot_logs_timeout_warning(make_client, caplog):
caplog.set_level(logging.WARNING)
async with make_client(queue_timeout_s=5, synth_timeout_s=5):
pass
assert "config: VOICE_QUEUE_TIMEOUT_S=5 abaixo de 2x VOICE_SYNTH_TIMEOUT_S=5" in caplog.text
def test_retired_queue_variable_is_reported(monkeypatch):
from app.config import Settings
monkeypatch.setenv("VOICE_MAX_QUEUE", "8")
monkeypatch.delenv("VOICE_STT_MAX_QUEUE", raising=False)
assert Settings.retired_vars_in_env() == [("VOICE_MAX_QUEUE", "VOICE_MAX_QUEUE_PER_KEY")]
+216
View File
@@ -0,0 +1,216 @@
"""Chaves nomeadas, escopos e /v1/status (ADR 0027 §9 e §10)."""
import hashlib
import json
import sys
from dataclasses import replace
import pytest
from app import keys
from app.keys import KEY_RE, issue_key, keys_path, revoke_key
from tests.conftest import HEADERS, KEY, body
pytestmark = pytest.mark.anyio
def _issue(settings, scopes, name="backend-test"):
record, plaintext = issue_key(keys_path(settings.data_dir), name, tuple(scopes))
return record, {"X-Service-Key": plaintext}
def test_issued_key_has_the_contract_format_and_only_its_hash_is_stored(settings):
record, plaintext = issue_key(keys_path(settings.data_dir), "backend-test", ("tts", "status"))
match = KEY_RE.fullmatch(plaintext)
assert match and match.group(1) == record.key_id
stored = keys_path(settings.data_dir).read_text(encoding="utf-8")
secret = match.group(2)
assert secret not in stored and plaintext not in stored
entry = json.loads(stored)["keys"][0]
assert set(entry) == {"keyId", "name", "scopes", "secretSha256", "createdAt", "revokedAt"}
assert entry["scopes"] == ["status", "tts"] and entry["revokedAt"] is None
if sys.platform != "win32": # permissão POSIX; no Windows o arquivo herda a ACL da pasta do usuário
assert (keys_path(settings.data_dir).stat().st_mode & 0o077) == 0 # 0600
async def test_env_key_keeps_working_with_every_scope(make_client):
async with make_client() as client:
status = await client.get("/v1/status", headers=HEADERS)
synth = await client.post("/v1/synthesize", headers=HEADERS, json=body())
health = await client.get("/health", headers=HEADERS)
assert status.status_code == 200 and synth.status_code == 200 and health.status_code == 200
assert status.json()["key"] == {"keyId": "env", "name": "env", "scopes": ["admin", "convert", "status", "transcribe", "tts"]}
async def test_key_issued_while_running_works_without_restart(make_client, settings):
async with make_client() as client:
_, headers = _issue(settings, ["tts"])
response = await client.post("/v1/synthesize", headers=headers, json=body())
assert response.status_code == 200
async def test_revoked_key_stops_working_without_restart(make_client, settings):
async with make_client() as client:
record, headers = _issue(settings, ["tts", "status"])
assert (await client.get("/v1/voices", headers=headers)).status_code == 200
revoke_key(keys_path(settings.data_dir), record.key_id)
response = await client.get("/v1/voices", headers=headers)
env = await client.get("/v1/voices", headers=HEADERS)
assert response.status_code == 401 and response.json()["error"]["code"] == "unauthorized"
assert env.status_code == 200
@pytest.mark.parametrize(
("method", "path", "scope"),
[
("GET", "/v1/status", "status"),
("POST", "/v1/transcribe", "transcribe"),
("GET", "/v1/transcribe/jobs/abcdefgh12", "transcribe"),
],
)
async def test_key_without_route_scope_is_403(make_client, settings, method, path, scope):
async with make_client() as client:
_, headers = _issue(settings, ["tts"])
response = await client.request(method, path, headers=headers)
assert response.status_code == 403
assert response.json() == {
"error": {"code": "insufficient_scope", "message": "A chave não tem o escopo desta operação.", "requiredScope": scope}
}
async def test_transcribe_only_key_cannot_synthesize_nor_list_voices(make_client, settings):
async with make_client() as client:
_, headers = _issue(settings, ["transcribe"])
synth = await client.post("/v1/synthesize", headers=headers, json=body())
voices = await client.get("/v1/voices/pt-br-test", headers=headers)
assert synth.status_code == 403 and voices.status_code == 403
async def test_unknown_route_is_404_with_valid_key_and_401_without(make_client, settings):
async with make_client() as client:
_, headers = _issue(settings, ["tts"])
known_key = await client.get("/rota-que-nao-existe", headers=headers)
no_key = await client.get("/rota-que-nao-existe")
assert known_key.status_code == 404 and no_key.status_code == 401
async def test_wrong_secret_for_existing_key_id_is_401(make_client, settings):
async with make_client() as client:
record, _ = _issue(settings, ["tts"])
forged = {"X-Service-Key": f"dvk_{record.key_id}_{'A' * 43}"}
response = await client.get("/v1/voices", headers=forged)
assert response.status_code == 401
async def test_corrupted_key_file_fails_closed_but_env_key_recovers(make_client, settings):
async with make_client() as client:
_, headers = _issue(settings, ["tts"])
assert (await client.get("/v1/voices", headers=headers)).status_code == 200
keys_path(settings.data_dir).write_text("{nao-e-json", encoding="utf-8")
named = await client.get("/v1/voices", headers=headers)
env = await client.get("/v1/voices", headers=HEADERS)
assert named.status_code == 401 and env.status_code == 200
async def test_status_exposes_operations_queues_voices_and_key(make_client, settings):
async with make_client() as client:
record, headers = _issue(settings, ["status", "tts"], name="srv-1")
response = await client.get("/v1/status", headers=headers)
assert response.status_code == 200 and response.headers["cache-control"] == "no-store"
data = response.json()
assert set(data) == {"status", "version", "device", "rvc", "azure", "engines", "operations", "queues", "voices", "key"}
assert data["operations"] == ["tts", "transcribe"]
assert data["engines"] == {"tts": "fake", "transcribe": "fake-stt"}
assert data["queues"]["synthesis"] == {"running": 0, "waiting": 0, "maxConcurrency": 1, "maxQueue": 4}
assert data["queues"]["transcription"]["maxQueue"] == 4 # padrão do CenaForge (episódios longos)
assert data["voices"]["count"] == 1 and len(data["voices"]["catalogHash"]) == 64
assert data["voices"]["items"] == [{"id": "pt-br-test", "revision": data["voices"]["items"][0]["revision"], "operations": ["tts"]}]
assert data["key"] == {"keyId": record.key_id, "name": "srv-1", "scopes": ["status", "tts"]}
text = response.text
for leak in (str(settings.data_dir), str(settings.models_dir), KEY, headers["X-Service-Key"], record.secret_sha256):
assert leak not in text
async def test_status_catalog_hash_is_stable_and_follows_revision(make_client, settings):
async with make_client() as client:
first = (await client.get("/v1/status", headers=HEADERS)).json()["voices"]["catalogHash"]
again = (await client.get("/v1/status", headers=HEADERS)).json()["voices"]["catalogHash"]
assert first == again
lock = json.loads(settings.lock_path.read_text())
(settings.models_dir / "piper" / "fake.onnx").write_bytes(b"outro-modelo")
lock["files"][0]["sha256"] = hashlib.sha256(b"outro-modelo").hexdigest()
settings.lock_path.write_text(json.dumps(lock))
async with make_client() as client:
changed = (await client.get("/v1/status", headers=HEADERS)).json()["voices"]["catalogHash"]
assert changed != first
async def test_status_without_stt_omits_transcribe(make_client):
async with make_client(stt=None) as client:
data = (await client.get("/v1/status", headers=HEADERS)).json()
assert data["operations"] == ["tts"]
assert data["engines"]["transcribe"] is None and data["queues"]["transcription"] is None
@pytest.fixture
def rvc_settings(settings, tmp_path):
# No CenaForge o RVC vive nas vozes de personagem do usuário (voz base + .pth), não no catálogo base.
(settings.models_dir / "rvc").mkdir(parents=True, exist_ok=True)
(settings.models_dir / "rvc" / "fake.pth").write_bytes(b"pth")
path = tmp_path / "user-voices.json"
path.write_text(json.dumps({"voices": [{
"id": "heroi", "name": "Herói", "baseVoice": "pt-br-test",
"rvc": {"model": "rvc/fake.pth", "modelSha256": hashlib.sha256(b"pth").hexdigest()},
}]}))
return replace(settings, user_catalog_path=path, enable_rvc=True)
async def test_rvc_voice_requires_convert_scope(make_client, rvc_settings):
async with make_client(user_catalog_path=rvc_settings.user_catalog_path, enable_rvc=True) as client:
_, headers = _issue(rvc_settings, ["tts", "status"])
synth = await client.post("/v1/synthesize", headers=headers, json=body(voiceId="heroi"))
status = (await client.get("/v1/status", headers=headers)).json()
assert synth.status_code == 403
assert synth.json()["error"] == {
"code": "insufficient_scope", "message": "A chave não tem o escopo desta operação.", "requiredScope": "convert"
}
assert status["operations"] == ["tts", "transcribe", "convert"]
assert status["voices"]["items"][0]["operations"] == ["tts", "convert"]
# ---------- CLI ----------
def test_cli_create_prints_key_once_and_list_never_shows_secret(settings, monkeypatch, capsys):
monkeypatch.setenv("VOICE_DATA_DIR", str(settings.data_dir))
assert keys.main(["create", "--name", "backend-prod", "--scopes", "tts,transcribe,status"]) == 0
created = capsys.readouterr().out
plaintext = next(line for line in created.splitlines() if line.startswith("dvk_"))
assert KEY_RE.fullmatch(plaintext)
assert keys.main(["list"]) == 0
listed = json.loads(capsys.readouterr().out)
assert listed[0]["name"] == "backend-prod" and listed[0]["scopes"] == ["status", "transcribe", "tts"]
assert "secretSha256" not in listed[0] and plaintext not in json.dumps(listed)
key_id = listed[0]["keyId"]
assert keys.main(["revoke", key_id]) == 0
assert key_id in capsys.readouterr().out
assert keys.main(["list"]) == 0
assert json.loads(capsys.readouterr().out)[0]["revokedAt"] is not None
@pytest.mark.parametrize(
"argv",
[
["create", "--name", "x", "--scopes", "root"],
["create", "--name", "x", "--scopes", ""],
["create", "--name", "nome com espaço", "--scopes", "tts"],
["revoke", "nao-e-um-id"],
],
)
def test_cli_rejects_bad_input(settings, monkeypatch, argv):
monkeypatch.setenv("VOICE_DATA_DIR", str(settings.data_dir))
assert keys.main(argv) == 2
assert not keys_path(settings.data_dir).exists()
def test_cli_revoke_unknown_key_id_is_1(settings, monkeypatch):
monkeypatch.setenv("VOICE_DATA_DIR", str(settings.data_dir))
assert keys.main(["revoke", "abcdefghijkl"]) == 1
+98
View File
@@ -0,0 +1,98 @@
import asyncio
import threading
import pytest
from app.errors import QueueFull, QueueTimeout, SynthesisTimeout
from app.work_queue import WorkQueue
from tests.conftest import HEADERS, body
pytestmark = pytest.mark.anyio
async def _wait_until(predicate, timeout=3.0):
loop = asyncio.get_running_loop()
end = loop.time() + timeout
while not predicate():
if loop.time() > end:
raise AssertionError("condição não atingida")
await asyncio.sleep(0.01)
async def test_concurrency_limit_and_queue_full():
gate = threading.Event()
queue = WorkQueue(max_concurrency=1, max_queue_per_key=1, queue_timeout_s=5, run_timeout_s=5)
running = asyncio.create_task(queue.run(lambda: gate.wait(5), owner="a"))
await _wait_until(lambda: queue.running == 1)
waiting = asyncio.create_task(queue.run(lambda: "segundo", owner="a"))
await _wait_until(lambda: queue.waiting == 1)
with pytest.raises(QueueFull):
await queue.run(lambda: "terceiro", owner="a")
gate.set()
assert await running is True
assert await waiting == "segundo"
queue.shutdown()
async def test_queue_timeout():
gate = threading.Event()
queue = WorkQueue(max_concurrency=1, max_queue_per_key=5, queue_timeout_s=0.2, run_timeout_s=5)
running = asyncio.create_task(queue.run(lambda: gate.wait(5), owner="a"))
await _wait_until(lambda: queue.running == 1)
with pytest.raises(QueueTimeout):
await queue.run(lambda: "nunca", owner="a")
gate.set()
await running
queue.shutdown()
async def test_synthesis_timeout_keeps_slot_until_thread_ends():
gate = threading.Event()
queue = WorkQueue(max_concurrency=1, max_queue_per_key=5, queue_timeout_s=5, run_timeout_s=0.2)
with pytest.raises(SynthesisTimeout):
await queue.run(lambda: gate.wait(5), owner="a")
# O cliente já recebeu timeout, mas a thread segue rodando: a vaga continua ocupada.
assert queue.running == 1
gate.set()
await _wait_until(lambda: queue.running == 0)
assert await queue.run(lambda: "livre", owner="a") == "livre"
queue.shutdown()
async def test_http_queue_full_returns_503_with_retry_after(make_client, engine):
engine.gate = threading.Event()
async with make_client(max_concurrency=1, max_queue_per_key=1) as client:
first = asyncio.create_task(client.post("/v1/synthesize", json=body("req-aaaaaaaa", text="um"), headers=HEADERS))
await _wait_until(lambda: engine.calls == 1)
second = asyncio.create_task(client.post("/v1/synthesize", json=body("req-bbbbbbbb", text="dois"), headers=HEADERS))
await asyncio.sleep(0.1)
third = await client.post("/v1/synthesize", json=body("req-cccccccc", text="três"), headers=HEADERS)
engine.gate.set()
assert (await first).status_code == 200
assert (await second).status_code == 200
assert third.status_code == 503
assert third.json()["error"]["code"] == "queue_full"
assert third.headers["retry-after"] == "5"
async def test_http_synthesis_timeout_is_504(make_client, engine):
engine.gate = threading.Event()
async with make_client(synth_timeout_s=0.2) as client:
response = await client.post("/v1/synthesize", json=body(), headers=HEADERS)
engine.gate.set()
assert response.status_code == 504
assert response.json()["error"]["code"] == "synthesis_timeout"
async def test_inflight_same_content_is_rendered_once(make_client, engine):
engine.gate = threading.Event()
async with make_client(max_concurrency=2) as client:
a = asyncio.create_task(client.post("/v1/synthesize", json=body("req-aaaaaaaa"), headers=HEADERS))
await _wait_until(lambda: engine.calls == 1)
b = asyncio.create_task(client.post("/v1/synthesize", json=body("req-bbbbbbbb"), headers=HEADERS))
await asyncio.sleep(0.1)
engine.gate.set()
ra, rb = await a, await b
assert ra.status_code == rb.status_code == 200
assert ra.content == rb.content
assert engine.calls == 1
+92
View File
@@ -0,0 +1,92 @@
import io
import logging
import pytest
import soundfile
from tests.conftest import HEADERS, body
pytestmark = pytest.mark.anyio
async def test_returns_ogg_opus(make_client):
async with make_client() as client:
response = await client.post("/v1/synthesize", json=body(), headers=HEADERS)
assert response.status_code == 200
assert response.headers["content-type"].startswith("audio/ogg")
assert response.headers["x-cache"] == "miss"
assert response.headers["x-idempotent-replay"] == "false"
assert int(response.headers["x-audio-duration-ms"]) > 0
info = soundfile.info(io.BytesIO(response.content))
assert (info.format, info.subtype, info.samplerate, info.channels) == ("OGG", "OPUS", 48000, 1)
@pytest.mark.parametrize(
"payload",
[
body(extra="campo"), # campo desconhecido
body(request_id="curto"), # requestId fora do padrão
body(request_id="tem espaço no meio!"),
body(text=" \n\t "), # vazio depois de normalizar
body(text=""),
body(params={"speed": 3.0}), # fora da faixa
body(params={"format": "mp3"}), # formato não suportado
body(params={"pitch": 2}), # parâmetro desconhecido
{**body(), "voiceId": "../../etc/passwd"}, # voz fora do padrão
],
)
async def test_validation_rejects(make_client, payload):
async with make_client() as client:
response = await client.post("/v1/synthesize", json=payload, headers=HEADERS)
assert response.status_code == 422
assert response.json()["error"]["code"] == "invalid_request"
async def test_validation_error_does_not_echo_text(make_client):
secret = "texto-secreto-do-espectador"
async with make_client() as client:
response = await client.post("/v1/synthesize", json=body(text=secret, extra=secret), headers=HEADERS)
assert response.status_code == 422
assert secret not in response.text
async def test_unknown_voice(make_client):
async with make_client() as client:
response = await client.post("/v1/synthesize", json={**body(), "voiceId": "pt-br-nao-existe"}, headers=HEADERS)
assert response.status_code == 422
assert response.json()["error"]["code"] == "voice_not_found"
async def test_text_too_long(make_client):
async with make_client() as client:
response = await client.post("/v1/synthesize", json=body(text="a" * 201), headers=HEADERS)
assert response.json()["error"]["code"] == "text_too_long"
async def test_audio_too_long(make_client):
# FakeEngine: ~15 caracteres/s; 190 caracteres ≈ 12,7 s > limite de 2 s.
async with make_client(max_audio_s=2) as client:
response = await client.post("/v1/synthesize", json=body(text="b" * 190), headers=HEADERS)
assert response.status_code == 422
assert response.json()["error"]["code"] == "audio_too_long"
async def test_text_never_logged(make_client, caplog):
secret = "segredo do espectador 12345"
caplog.set_level(logging.DEBUG)
async with make_client() as client:
await client.post("/v1/synthesize", json=body(text=secret), headers=HEADERS)
await client.post("/v1/synthesize", json=body(request_id="req-00000002", text=secret), headers=HEADERS)
assert "synthesize request_id=" in caplog.text
assert secret not in caplog.text
async def test_unreadable_body_uses_contract_error_format(make_client):
async with make_client() as client:
response = await client.post(
"/v1/synthesize", content=b'{"text": "\xe7\xe3o"}', headers={**HEADERS, "Content-Type": "application/json"}
)
missing = await client.get("/v1/nao-existe", headers=HEADERS)
assert response.status_code in (400, 422)
assert response.json()["error"]["code"] == "invalid_request"
assert missing.status_code == 404 and missing.json()["error"]["code"] == "not_found"
+185
View File
@@ -0,0 +1,185 @@
import asyncio
import logging
import pytest
from app.stt import FakeSttEngine, join_text, mean_no_speech
from tests.conftest import HEADERS, KEY
pytestmark = pytest.mark.anyio
# Convenção do FakeSttEngine: cada byte depois de "OggS" vale 10 ms de áudio.
ONE_SECOND = b"OggS" + b"x" * 100
def stt_headers(key: str = "order:123:transcribe", duration_ms: int = 1000, language: str = "pt-BR", **extra) -> dict:
headers = {
**HEADERS,
"Content-Type": "audio/ogg",
"X-Idempotency-Key": key,
"X-Audio-Duration-Ms": str(duration_ms),
"X-Language": language,
}
headers.update(extra)
return headers
async def test_requires_service_key(make_client):
async with make_client() as client:
no_key = {k: v for k, v in stt_headers().items() if k != "X-Service-Key"}
assert (await client.post("/v1/transcribe", content=ONE_SECOND, headers=no_key)).status_code == 401
wrong = stt_headers(**{"X-Service-Key": "x" * len(KEY)})
response = await client.post("/v1/transcribe", content=ONE_SECOND, headers=wrong)
assert response.status_code == 401
assert response.json()["error"]["code"] == "unauthorized"
assert (await client.get("/v1/transcribe/jobs/abcdefghijkl")).status_code == 401
async def test_ready_with_mean_no_speech_prob(make_client, stt_engine):
async with make_client() as client:
response = await client.post("/v1/transcribe", content=ONE_SECOND, headers=stt_headers())
assert response.status_code == 200
assert response.json() == {"status": "ready", "text": "valeu pela live", "noSpeechProb": 0.2}
assert response.headers["x-idempotent-replay"] == "false"
assert stt_engine.calls == 1
async def test_no_segments_means_no_speech(make_client):
async with make_client(stt=FakeSttEngine(text="", probs=())) as client:
response = await client.post("/v1/transcribe", content=ONE_SECOND, headers=stt_headers())
assert response.json() == {"status": "ready", "text": "", "noSpeechProb": 1.0}
def test_no_speech_helpers():
assert mean_no_speech([]) == 1.0
assert mean_no_speech([0.2, 0.4]) == pytest.approx(0.3)
assert mean_no_speech([1.5]) == 1.0 # preso em 0..1
assert join_text([" oi ", "", " tudo bem"], 4000) == "oi tudo bem"
assert len(join_text(["a" * 5000], 4000)) == 4000
async def test_idempotency_replay_and_conflict(make_client, stt_engine):
async with make_client() as client:
first = await client.post("/v1/transcribe", content=ONE_SECOND, headers=stt_headers())
again = await client.post("/v1/transcribe", content=ONE_SECOND, headers=stt_headers())
other_audio = await client.post("/v1/transcribe", content=ONE_SECOND + b"y", headers=stt_headers())
assert again.status_code == 200 and again.json() == first.json()
assert again.headers["x-idempotent-replay"] == "true"
assert stt_engine.calls == 1 # o retry não transcreve de novo
assert other_audio.status_code == 409
assert other_audio.json()["error"]["code"] == "idempotency_conflict"
@pytest.mark.parametrize(
("overrides", "code", "status"),
[
({"X-Audio-Duration-Ms": "60001"}, "audio_too_long", 422),
({"X-Audio-Duration-Ms": "0"}, "invalid_request", 422),
({"X-Language": "fr"}, "language_not_supported", 422),
({"X-Idempotency-Key": "com espaco"}, "invalid_request", 422),
({"Content-Type": "text/plain"}, "invalid_request", 422),
({"X-Detail": "frases"}, "invalid_request", 422),
],
)
async def test_header_validation(make_client, stt_engine, overrides, code, status):
async with make_client() as client:
response = await client.post("/v1/transcribe", content=ONE_SECOND, headers=stt_headers(**overrides))
assert response.status_code == status
assert response.json()["error"]["code"] == code
assert stt_engine.calls == 0
async def test_byte_limit(make_client, stt_engine):
async with make_client(stt_max_bytes=1024) as client:
response = await client.post("/v1/transcribe", content=b"OggS" + b"x" * 2000, headers=stt_headers())
assert response.status_code == 413
assert response.json()["error"]["code"] == "audio_too_large"
assert stt_engine.calls == 0
async def test_decoded_duration_limit(make_client, stt_engine):
# Declara 60 s, mas o áudio decodificado tem 61 s: vale o decodificado.
async with make_client() as client:
response = await client.post(
"/v1/transcribe", content=b"OggS" + b"x" * 6100, headers=stt_headers(duration_ms=60000)
)
assert response.status_code == 422
assert response.json()["error"]["code"] == "audio_too_long"
assert stt_engine.calls == 0
async def test_invalid_audio(make_client):
async with make_client() as client:
response = await client.post("/v1/transcribe", content=b"RIFFxxxx", headers=stt_headers())
assert response.status_code == 422
assert response.json()["error"]["code"] == "invalid_audio"
async def test_pending_then_job_ready(make_client):
async with make_client(stt=FakeSttEngine(delay_s=0.3), stt_sync_wait_s=0.0) as client:
response = await client.post("/v1/transcribe", content=ONE_SECOND, headers=stt_headers())
assert response.status_code == 202
pending = response.json()
assert pending["status"] == "pending" and pending["retryAfterMs"] >= 500
for _ in range(100):
job = await client.get(f"/v1/transcribe/jobs/{pending['jobRef']}", headers=HEADERS)
if job.json()["status"] == "ready":
break
await asyncio.sleep(0.05)
assert job.status_code == 200
assert job.json() == {"status": "ready", "text": "valeu pela live", "noSpeechProb": 0.2}
async def test_unknown_job_and_disabled(make_client):
async with make_client() as client:
response = await client.get("/v1/transcribe/jobs/abcdefghijkl", headers=HEADERS)
assert response.status_code == 410
assert response.json()["error"]["code"] == "job_not_found"
async with make_client(stt=None) as client:
response = await client.post("/v1/transcribe", content=ONE_SECOND, headers=stt_headers())
assert response.status_code == 501
assert response.json()["error"]["code"] == "stt_disabled"
async def test_queue_full(make_client):
async with make_client(stt=FakeSttEngine(delay_s=0.5), stt_sync_wait_s=0.0, stt_max_queue_per_key=0) as client:
first = await client.post("/v1/transcribe", content=ONE_SECOND, headers=stt_headers(key="a-1"))
assert first.status_code == 202
for _ in range(100):
if (await client.get("/v1/status", headers=HEADERS)).json()["queues"]["transcription"]["running"] == 1:
break
await asyncio.sleep(0.01)
second = await client.post("/v1/transcribe", content=ONE_SECOND + b"z", headers=stt_headers(key="b-2"))
assert second.status_code == 503
assert second.json()["error"]["code"] == "queue_full"
assert second.headers["retry-after"] == "5"
async def test_no_text_in_logs(make_client, caplog):
secret = "segredo do espectador"
caplog.set_level(logging.DEBUG)
async with make_client(stt=FakeSttEngine(text=secret)) as client:
response = await client.post("/v1/transcribe", content=ONE_SECOND, headers=stt_headers())
assert response.json()["text"] == secret
assert secret not in caplog.text
assert "transcribe job=" in caplog.text
def test_real_ogg_opus_decoder():
# Decodificador de verdade (PyAV), com OGG/Opus gerado pelo mesmo codificador da síntese.
import numpy as np
from app.audio import encode_ogg_opus
from app.engine import Pcm
from app.errors import AudioTooLong, InvalidAudio
from app.stt import SAMPLE_RATE, decode_ogg_opus
tone = (np.sin(np.arange(22050 * 2) * 2 * np.pi * 220 / 22050) * 8000).astype(np.int16)
data = encode_ogg_opus(Pcm(tone, 22050))
samples = decode_ogg_opus(data, max_seconds=60)
assert samples.dtype == np.float32
assert abs(samples.size / SAMPLE_RATE - 2.0) < 0.1
with pytest.raises(AudioTooLong):
decode_ogg_opus(data, max_seconds=1.0)
with pytest.raises(InvalidAudio):
decode_ogg_opus(b"OggS" + b"\x00" * 64, max_seconds=60)
+66
View File
@@ -0,0 +1,66 @@
"""GET /v1/voices (paginado, com busca) e GET /v1/voices/{voiceId}."""
import json
import pytest
pytestmark = pytest.mark.anyio
HEADERS = {"X-Service-Key": "k" * 40}
@pytest.fixture
def many_voices(settings):
base = json.loads(settings.catalog_path.read_text())["voices"][0]
base.update(description="Voz de teste.", gender="female", ageRange="young", accent="pt-BR")
voices = [base]
for vid, name in (("pt-br-ana", "Ana"), ("pt-br-jose", "José"), ("pt-br-zeca", "Zeca")):
voices.append({**base, "id": vid, "name": name, "default": False})
settings.catalog_path.write_text(json.dumps({"voices": voices}))
return settings
async def test_list_shape_and_no_internal_fields(make_client):
async with make_client() as client:
response = await client.get("/v1/voices", headers=HEADERS)
body = response.json()
assert response.status_code == 200 and body["nextCursor"] is None
item = body["items"][0]
assert item["id"] == "pt-br-test" and item["languages"] == ["pt-BR"] and item["engine"] == "tts"
assert not {"model", "config", "source", "license", "path"} & item.keys()
async def test_pagination_walks_all_pages(make_client, many_voices):
async with make_client() as client:
first = (await client.get("/v1/voices?limit=3", headers=HEADERS)).json()
assert len(first["items"]) == 3 and first["nextCursor"]
second = (await client.get("/v1/voices", params={"limit": 3, "cursor": first["nextCursor"]}, headers=HEADERS)).json()
ids = [v["id"] for v in first["items"] + second["items"]]
assert ids == sorted(ids) and len(set(ids)) == 4 and second["nextCursor"] is None
async def test_query_ignores_case_and_accents(make_client, many_voices):
async with make_client() as client:
by_name = (await client.get("/v1/voices?query=JOSE", headers=HEADERS)).json()
by_id = (await client.get("/v1/voices?query=ZECA", headers=HEADERS)).json()
none = (await client.get("/v1/voices?query=nada", headers=HEADERS)).json()
assert [v["id"] for v in by_name["items"]] == ["pt-br-jose"]
assert [v["id"] for v in by_id["items"]] == ["pt-br-zeca"]
assert none == {"items": [], "nextCursor": None}
@pytest.mark.parametrize("qs", ["limit=0", "limit=101", "limit=abc", "cursor=%25%25", "cursor=" + "a" * 513, "query=" + "a" * 65])
async def test_invalid_params_are_422(make_client, qs):
async with make_client() as client:
response = await client.get("/v1/voices?" + qs, headers=HEADERS)
assert response.status_code == 422 and response.json()["error"]["code"] == "invalid_request"
async def test_get_voice_and_404(make_client):
async with make_client() as client:
ok = await client.get("/v1/voices/pt-br-test", headers=HEADERS)
missing = await client.get("/v1/voices/nao-existe", headers=HEADERS)
weird = await client.get("/v1/voices/..%2Fx", headers=HEADERS)
assert ok.status_code == 200 and ok.json()["id"] == "pt-br-test" and ok.json()["revision"]
assert missing.status_code == 404 and missing.json()["error"]["code"] == "voice_not_found"
assert weird.status_code == 404
File diff suppressed because it is too large Load Diff