karaoke-gen 0.90.1__py3-none-any.whl → 0.99.3__py3-none-any.whl

backend/config.py

@@ -0,0 +1,172 @@
+"""
+Configuration management for the karaoke generation backend.
+"""
+import os
+import logging
+from typing import Optional, Dict
+from pydantic_settings import BaseSettings
+from google.cloud import secretmanager
+
+
+logger = logging.getLogger(__name__)
+
+
+class Settings(BaseSettings):
+    """Application settings."""
+    
+    # Google Cloud
+    google_cloud_project: str = os.getenv("GOOGLE_CLOUD_PROJECT", "")
+    gcs_bucket_name: str = os.getenv("GCS_BUCKET_NAME", "karaoke-gen-storage")
+    gcs_temp_bucket: str = os.getenv("GCS_TEMP_BUCKET", "karaoke-gen-temp")
+    gcs_output_bucket: str = os.getenv("GCS_OUTPUT_BUCKET", "karaoke-gen-outputs")
+    firestore_collection: str = os.getenv("FIRESTORE_COLLECTION", "jobs")
+    
+    # Audio Separator API (for GPU processing)
+    audio_separator_api_url: Optional[str] = os.getenv("AUDIO_SEPARATOR_API_URL")
+    
+    # External APIs (can be set via env or Secret Manager)
+    audioshake_api_key: Optional[str] = os.getenv("AUDIOSHAKE_API_KEY")
+    genius_api_key: Optional[str] = os.getenv("GENIUS_API_KEY")
+    spotify_cookie: Optional[str] = os.getenv("SPOTIFY_COOKIE_SP_DC")
+    rapidapi_key: Optional[str] = os.getenv("RAPIDAPI_KEY")
+    
+    # Authentication
+    admin_tokens: Optional[str] = os.getenv("ADMIN_TOKENS")  # Comma-separated list
+    
+    # Application
+    environment: str = os.getenv("ENVIRONMENT", "development")
+    log_level: str = os.getenv("LOG_LEVEL", "INFO")
+    
+    # Processing
+    max_concurrent_jobs: int = int(os.getenv("MAX_CONCURRENT_JOBS", "5"))
+    job_timeout_seconds: int = int(os.getenv("JOB_TIMEOUT_SECONDS", "3600"))
+
+    # Agentic AI Correction (for lyrics correction via LLM)
+    # When enabled, uses Gemini via Vertex AI for intelligent lyrics correction
+    use_agentic_ai: bool = os.getenv("USE_AGENTIC_AI", "true").lower() in ("true", "1", "yes")
+    agentic_ai_model: str = os.getenv("AGENTIC_AI_MODEL", "vertexai/gemini-3-flash-preview")
+    # Timeout for agentic correction in seconds. If correction takes longer, abort and
+    # use uncorrected transcription - human review will fix any issues.
+    agentic_correction_timeout_seconds: int = int(os.getenv("AGENTIC_CORRECTION_TIMEOUT_SECONDS", "180"))
+
+    # Cloud Tasks (for scalable worker coordination)
+    # When enabled, workers are triggered via Cloud Tasks for guaranteed delivery
+    # When disabled (default), workers are triggered via direct HTTP (for development)
+    enable_cloud_tasks: bool = os.getenv("ENABLE_CLOUD_TASKS", "false").lower() in ("true", "1", "yes")
+    gcp_region: str = os.getenv("GCP_REGION", "us-central1")
+    
+    # Cloud Run Jobs (for long-running video encoding)
+    # When enabled AND enable_cloud_tasks is true, video worker uses Cloud Run Jobs
+    # instead of Cloud Tasks. This supports encoding times >30 minutes (up to 24 hours).
+    # Default is false - Cloud Tasks is sufficient for most videos (15-20 min).
+    use_cloud_run_jobs_for_video: bool = os.getenv("USE_CLOUD_RUN_JOBS_FOR_VIDEO", "false").lower() in ("true", "1", "yes")
+
+    # GCE Encoding Worker (for high-performance video encoding)
+    # When enabled, video encoding is offloaded to a dedicated C4 GCE instance
+    # with faster CPU (Intel Granite Rapids 3.9 GHz) instead of Cloud Run.
+    # This provides 2-3x faster encoding times for CPU-bound FFmpeg libx264 encoding.
+    use_gce_encoding: bool = os.getenv("USE_GCE_ENCODING", "false").lower() in ("true", "1", "yes")
+    encoding_worker_url: Optional[str] = os.getenv("ENCODING_WORKER_URL")  # e.g., http://136.119.50.148:8080
+    encoding_worker_api_key: Optional[str] = os.getenv("ENCODING_WORKER_API_KEY")
+
+    # GCE Preview Encoding (for faster preview video generation)
+    # When enabled, preview video encoding during lyrics review is offloaded to the GCE worker.
+    # This reduces preview generation time from 60+ seconds to ~15-20 seconds.
+    # Requires use_gce_encoding to be enabled and the GCE worker to support /encode-preview endpoint.
+    use_gce_preview_encoding: bool = os.getenv("USE_GCE_PREVIEW_ENCODING", "false").lower() in ("true", "1", "yes")
+    
+    # Storage paths
+    temp_dir: str = os.getenv("TEMP_DIR", "/tmp/karaoke-gen")
+
+    # Worker logs storage mode
+    # When enabled, worker logs are stored in a Firestore subcollection (jobs/{job_id}/logs)
+    # instead of an embedded array. This avoids the 1MB document size limit.
+    # Default is true for new deployments.
+    use_log_subcollection: bool = os.getenv("USE_LOG_SUBCOLLECTION", "true").lower() in ("true", "1", "yes")
+    
+    # Flacfetch remote service (for torrent downloads)
+    # When configured, audio search uses the remote flacfetch HTTP API instead of local flacfetch.
+    # This is required for torrent downloads since Cloud Run doesn't support BitTorrent.
+    flacfetch_api_url: Optional[str] = os.getenv("FLACFETCH_API_URL")  # e.g., http://10.0.0.5:8080
+    flacfetch_api_key: Optional[str] = os.getenv("FLACFETCH_API_KEY")
+    
+    # Default distribution settings (can be overridden per-request)
+    default_dropbox_path: Optional[str] = os.getenv("DEFAULT_DROPBOX_PATH")
+    default_gdrive_folder_id: Optional[str] = os.getenv("DEFAULT_GDRIVE_FOLDER_ID")
+    # Strip whitespace/newlines from webhook URL - common issue when env vars are set with trailing newlines
+    default_discord_webhook_url: Optional[str] = (
+        os.getenv("DEFAULT_DISCORD_WEBHOOK_URL", "").strip() or None
+    )
+
+    # Default values for web service jobs (YouTube/Dropbox distribution)
+    default_enable_youtube_upload: bool = os.getenv("DEFAULT_ENABLE_YOUTUBE_UPLOAD", "false").lower() in ("true", "1", "yes")
+    default_brand_prefix: Optional[str] = os.getenv("DEFAULT_BRAND_PREFIX")
+    default_youtube_description: str = os.getenv(
+        "DEFAULT_YOUTUBE_DESCRIPTION",
+        "Karaoke video created with Nomad Karaoke (https://nomadkaraoke.com)\n\n"
+        "AI-powered vocal separation and synchronized lyrics.\n\n"
+        "#karaoke #music #singing #instrumental #lyrics"
+    )
+    
+    # Secret Manager cache
+    _secret_cache: Dict[str, str] = {}
+    
+    class Config:
+        env_file = ".env"
+        case_sensitive = False
+    
+    def get_secret(self, secret_id: str) -> Optional[str]:
+        """
+        Get a secret from Google Secret Manager.
+        
+        Caches secrets in memory to avoid repeated API calls.
+        Falls back to environment variables if Secret Manager unavailable.
+        
+        Args:
+            secret_id: Secret name (e.g., "audioshake-api-key")
+            
+        Returns:
+            Secret value or None if not found
+        """
+        # Check cache first
+        if secret_id in self._secret_cache:
+            return self._secret_cache[secret_id]
+        
+        # Check environment variable (development mode)
+        env_var = secret_id.upper().replace('-', '_')
+        env_value = os.getenv(env_var)
+        if env_value:
+            logger.debug(f"Using {secret_id} from environment variable")
+            self._secret_cache[secret_id] = env_value
+            return env_value
+        
+        # Try Secret Manager (production mode)
+        if not self.google_cloud_project:
+            logger.warning(f"Cannot fetch secret {secret_id}: No GCP project configured")
+            return None
+        
+        try:
+            client = secretmanager.SecretManagerServiceClient()
+            name = f"projects/{self.google_cloud_project}/secrets/{secret_id}/versions/latest"
+            response = client.access_secret_version(request={"name": name})
+            # Strip whitespace/newlines - common issue when secrets are created with trailing newlines
+            secret_value = response.payload.data.decode('UTF-8').strip()
+            
+            # Cache it
+            self._secret_cache[secret_id] = secret_value
+            logger.info(f"Loaded secret {secret_id} from Secret Manager")
+            return secret_value
+            
+        except Exception as e:
+            logger.error(f"Failed to load secret {secret_id} from Secret Manager: {e}")
+            return None
+
+
+# Global settings instance
+settings = Settings()
+
+
+def get_settings() -> Settings:
+    """Get the global settings instance."""
+    return settings
+

backend/main.py

@@ -0,0 +1,157 @@
+"""
+FastAPI application entry point for karaoke generation backend.
+"""
+import logging
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from backend.config import settings
+from backend.api.routes import health, jobs, internal, file_upload, review, auth, audio_search, themes, users, admin
+from backend.services.tracing import setup_tracing, instrument_app, get_current_trace_id
+from backend.services.structured_logging import setup_structured_logging
+from backend.services.spacy_preloader import preload_spacy_model
+from backend.services.nltk_preloader import preload_all_nltk_resources
+from backend.services.langfuse_preloader import preload_langfuse_handler
+from backend.middleware.audit_logging import AuditLoggingMiddleware
+
+
+from backend.version import VERSION
+
+
+# Configure structured logging (JSON in Cloud Run, human-readable locally)
+# This must happen before any logging calls
+setup_structured_logging()
+logger = logging.getLogger(__name__)
+
+# Initialize OpenTelemetry tracing (must happen before app creation)
+tracing_enabled = setup_tracing(
+    service_name="karaoke-backend",
+    service_version=VERSION,
+    enable_in_dev=False,  # Set to True to enable tracing locally
+)
+
+
+async def validate_credentials_on_startup():
+    """Validate OAuth credentials on startup and send alerts if needed."""
+    try:
+        from backend.services.credential_manager import get_credential_manager, CredentialStatus
+        
+        manager = get_credential_manager()
+        results = manager.check_all_credentials()
+        
+        invalid_services = [
+            result for result in results.values()
+            if result.status in (CredentialStatus.INVALID, CredentialStatus.EXPIRED)
+        ]
+        
+        if invalid_services:
+            logger.warning(f"Some OAuth credentials need attention:")
+            for result in invalid_services:
+                logger.warning(f"  - {result.service}: {result.message}")
+            
+            # Try to send Discord alert
+            discord_url = settings.get_secret("discord-alert-webhook") if hasattr(settings, 'get_secret') else None
+            if discord_url:
+                manager.send_credential_alert(invalid_services, discord_url)
+                logger.info("Sent credential alert to Discord")
+        else:
+            logger.info("All OAuth credentials validated successfully")
+            
+    except Exception as e:
+        logger.error(f"Failed to validate credentials on startup: {e}")
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Lifespan event handler for startup and shutdown."""
+    # Startup
+    logger.info("Starting karaoke generation backend")
+    logger.info(f"Environment: {settings.environment}")
+    logger.info(f"GCS Bucket: {settings.gcs_bucket_name}")
+    logger.info(f"Tracing enabled: {tracing_enabled}")
+
+    # Preload NLP models and resources to avoid cold start delays
+    # See docs/archive/2026-01-08-performance-investigation.md for background
+
+    # 1. SpaCy model (60+ second delay without preload)
+    try:
+        preload_spacy_model("en_core_web_sm")
+    except Exception as e:
+        logger.warning(f"SpaCy preload failed (will load lazily): {e}")
+
+    # 2. NLTK cmudict (50-100+ second delay without preload)
+    try:
+        preload_all_nltk_resources()
+    except Exception as e:
+        logger.warning(f"NLTK preload failed (will load lazily): {e}")
+
+    # 3. Langfuse callback handler (200+ second delay without preload)
+    try:
+        preload_langfuse_handler()
+    except Exception as e:
+        logger.warning(f"Langfuse preload failed (will initialize lazily): {e}")
+
+    # Validate OAuth credentials (non-blocking)
+    try:
+        await validate_credentials_on_startup()
+    except Exception as e:
+        logger.error(f"Credential validation failed: {e}")
+    
+    yield
+    
+    # Shutdown
+    logger.info("Shutting down karaoke generation backend")
+
+
+# Create FastAPI app
+app = FastAPI(
+    title="Karaoke Generator API",
+    description="Backend API for web-based karaoke video generation",
+    version=VERSION,
+    lifespan=lifespan
+)
+
+# Instrument FastAPI with OpenTelemetry (adds automatic spans for all requests)
+if tracing_enabled:
+    instrument_app(app)
+
+# Configure CORS
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],  # Configure this properly for production
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Add audit logging middleware (captures all requests with request_id for correlation)
+app.add_middleware(AuditLoggingMiddleware)
+
+# Include routers
+app.include_router(health.router, prefix="/api")
+app.include_router(jobs.router, prefix="/api")
+app.include_router(file_upload.router, prefix="/api")  # File upload endpoint
+app.include_router(internal.router, prefix="/api")  # Internal worker endpoints
+app.include_router(review.router, prefix="/api")  # Review UI compatibility endpoints
+app.include_router(auth.router, prefix="/api")  # OAuth credential management
+app.include_router(audio_search.router, prefix="/api")  # Audio search (artist+title mode)
+app.include_router(themes.router, prefix="/api")  # Theme selection for styles
+app.include_router(users.router, prefix="/api")  # User auth, credits, and Stripe webhooks
+app.include_router(admin.router, prefix="/api")  # Admin dashboard and management
+
+
+@app.get("/")
+async def root():
+    """Root endpoint."""
+    return {
+        "service": "karaoke-gen-backend",
+        "version": VERSION,
+        "status": "running"
+    }
+
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=8080)
+

backend/middleware/__init__.py

@@ -0,0 +1,5 @@
+"""Middleware package for FastAPI application."""
+
+from backend.middleware.audit_logging import AuditLoggingMiddleware
+
+__all__ = ["AuditLoggingMiddleware"]

backend/middleware/audit_logging.py

@@ -0,0 +1,124 @@
+"""
+Audit logging middleware for tracking all HTTP requests.
+
+This middleware captures request metadata and logs it to Cloud Logging
+for audit trail and user activity investigation purposes.
+"""
+import logging
+import time
+import uuid
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import Response
+
+
+logger = logging.getLogger("audit")
+
+# Endpoints to exclude from audit logging (high-frequency health checks)
+EXCLUDED_PATHS = {
+    "/",
+    "/api/health",
+    "/api/health/detailed",
+    "/api/readiness",
+    "/healthz",
+    "/ready",
+}
+
+
+class AuditLoggingMiddleware(BaseHTTPMiddleware):
+    """
+    Middleware that logs all HTTP requests for audit purposes.
+
+    Captures:
+    - request_id: UUID for correlating with auth logs
+    - method: HTTP method
+    - path: Request path
+    - status_code: Response status
+    - latency_ms: Request duration
+    - client_ip: Client IP (from X-Forwarded-For for proxied requests)
+    - user_agent: Browser/client identifier
+
+    The request_id is stored in request.state and added to response headers,
+    allowing correlation with auth logs that capture user_email.
+    """
+
+    async def dispatch(self, request: Request, call_next) -> Response:
+        # Skip excluded paths (health checks)
+        if request.url.path in EXCLUDED_PATHS:
+            return await call_next(request)
+
+        # Generate unique request ID for correlation
+        request_id = str(uuid.uuid4())
+        request.state.request_id = request_id
+
+        # Capture start time
+        start_time = time.time()
+
+        # Extract client info
+        client_ip = self._get_client_ip(request)
+        user_agent = request.headers.get("user-agent", "")
+
+        # Process request
+        try:
+            response = await call_next(request)
+        except Exception:
+            # Log failed requests too (exception() auto-includes stack trace)
+            latency_ms = int((time.time() - start_time) * 1000)
+            logger.exception(
+                "request_audit_error",
+                extra={
+                    "request_id": request_id,
+                    "method": request.method,
+                    "path": request.url.path,
+                    "query_string": str(request.query_params) if request.query_params else None,
+                    "latency_ms": latency_ms,
+                    "client_ip": client_ip,
+                    "user_agent": user_agent[:200] if user_agent else None,
+                    "audit_type": "http_request",
+                }
+            )
+            raise
+
+        # Calculate latency
+        latency_ms = int((time.time() - start_time) * 1000)
+
+        # Log audit entry (INFO level for successful requests)
+        log_level = logging.WARNING if response.status_code >= 400 else logging.INFO
+        logger.log(
+            log_level,
+            "request_audit",
+            extra={
+                "request_id": request_id,
+                "method": request.method,
+                "path": request.url.path,
+                "query_string": str(request.query_params) if request.query_params else None,
+                "status_code": response.status_code,
+                "latency_ms": latency_ms,
+                "client_ip": client_ip,
+                "user_agent": user_agent[:200] if user_agent else None,
+                "audit_type": "http_request",
+            }
+        )
+
+        # Add request_id to response headers for debugging/correlation
+        response.headers["X-Request-ID"] = request_id
+
+        return response
+
+    def _get_client_ip(self, request: Request) -> str:
+        """
+        Extract client IP address, handling proxy scenarios.
+
+        Cloud Run and other proxies set X-Forwarded-For header.
+        """
+        # Check X-Forwarded-For for proxy scenarios (Cloud Run, load balancers)
+        forwarded = request.headers.get("x-forwarded-for", "")
+        if forwarded:
+            # First IP is the original client
+            return forwarded.split(",")[0].strip()
+
+        # Fall back to direct connection
+        if request.client:
+            return request.client.host
+
+        return "unknown"