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