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
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)