Files
MateuusandClaude Opus 5.5 84f30bbc2d CenaForge: primeira versão pública
Gerador de vídeos narrativos (Godot + FFmpeg), painel Next.js, serviço de voz,
Clipador de lives e Publicador para YouTube, TikTok e Instagram.

Inclui a leitura das visualizações dos posts para o Dashboard e o botão
"Publicar no <rede>" nos cartões das publicações.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 16:35:09 -03:00

508 lines
25 KiB
Python
Raw Permalink Blame History

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