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

backend/models/theme.py

@@ -0,0 +1,153 @@
+"""
+Theme data models for karaoke-gen.
+
+Themes are pre-created style configurations stored in GCS that users can select
+when creating karaoke jobs. Each theme includes:
+- Style parameters (fonts, colors, backgrounds, layouts)
+- Asset files (images, fonts)
+- Preview images
+- Optional YouTube description template
+"""
+
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field
+
+
+class ThemeSummary(BaseModel):
+    """Summary of a theme for listing purposes."""
+
+    id: str = Field(..., description="Unique theme identifier (e.g., 'nomad', 'default')")
+    name: str = Field(..., description="Human-readable theme name")
+    description: str = Field(..., description="Brief description of the theme style")
+    preview_url: Optional[str] = Field(None, description="Signed URL for preview image")
+    thumbnail_url: Optional[str] = Field(None, description="Signed URL for smaller thumbnail")
+    is_default: bool = Field(False, description="Whether this is the default theme")
+
+
+class ThemeMetadata(BaseModel):
+    """Metadata for a single theme in the registry."""
+
+    id: str
+    name: str
+    description: str
+    is_default: bool = False
+    created_at: Optional[datetime] = None
+
+
+class ThemeRegistry(BaseModel):
+    """Registry of all available themes, stored as _metadata.json in GCS."""
+
+    version: int = 1
+    themes: List[ThemeMetadata] = Field(default_factory=list)
+
+
+class ThemeDetail(BaseModel):
+    """Full theme details including style parameters."""
+
+    id: str
+    name: str
+    description: str
+    preview_url: Optional[str] = None
+    is_default: bool = False
+    style_params: Dict[str, Any] = Field(default_factory=dict)
+    has_youtube_description: bool = False
+
+
+class ColorOverrides(BaseModel):
+    """
+    User-customizable color overrides that can be applied on top of a theme.
+
+    All colors are hex format (#RRGGBB). When applied:
+    - artist_color: Applied to intro.artist_color, end.artist_color, cdg.artist_color
+    - title_color: Applied to intro.title_color, end.title_color, cdg.title_color
+    - sung_lyrics_color: Applied to karaoke.primary_color (converted to RGBA), cdg.active_fill
+    - unsung_lyrics_color: Applied to karaoke.secondary_color (converted to RGBA), cdg.inactive_fill
+    """
+
+    artist_color: Optional[str] = Field(
+        None,
+        pattern=r"^#[0-9A-Fa-f]{6}$",
+        description="Hex color for artist name on intro/end screens",
+    )
+    title_color: Optional[str] = Field(
+        None,
+        pattern=r"^#[0-9A-Fa-f]{6}$",
+        description="Hex color for song title on intro/end screens",
+    )
+    sung_lyrics_color: Optional[str] = Field(
+        None,
+        pattern=r"^#[0-9A-Fa-f]{6}$",
+        description="Hex color for lyrics being sung (highlighted)",
+    )
+    unsung_lyrics_color: Optional[str] = Field(
+        None,
+        pattern=r"^#[0-9A-Fa-f]{6}$",
+        description="Hex color for lyrics not yet sung",
+    )
+
+    def has_overrides(self) -> bool:
+        """Check if any color overrides are set."""
+        return any(
+            [
+                self.artist_color,
+                self.title_color,
+                self.sung_lyrics_color,
+                self.unsung_lyrics_color,
+            ]
+        )
+
+    def to_dict(self) -> Dict[str, str]:
+        """Convert to dict, excluding None values."""
+        return {k: v for k, v in self.model_dump().items() if v is not None}
+
+
+class ThemesListResponse(BaseModel):
+    """Response from GET /api/themes endpoint."""
+
+    themes: List[ThemeSummary]
+
+
+class ThemeDetailResponse(BaseModel):
+    """Response from GET /api/themes/{theme_id} endpoint."""
+
+    theme: ThemeDetail
+
+
+# Utility functions for color conversion
+
+
+def hex_to_rgba(hex_color: str, alpha: int = 255) -> str:
+    """
+    Convert hex color (#RRGGBB) to RGBA format for ASS subtitles.
+
+    ASS subtitle format uses "R, G, B, A" string format.
+
+    Args:
+        hex_color: Hex color string like "#7070F7"
+        alpha: Alpha value 0-255 (default 255 = opaque)
+
+    Returns:
+        RGBA string like "112, 112, 247, 255"
+    """
+    hex_color = hex_color.lstrip("#")
+    r = int(hex_color[0:2], 16)
+    g = int(hex_color[2:4], 16)
+    b = int(hex_color[4:6], 16)
+    return f"{r}, {g}, {b}, {alpha}"
+
+
+def rgba_to_hex(rgba_str: str) -> str:
+    """
+    Convert RGBA format to hex color.
+
+    Args:
+        rgba_str: RGBA string like "112, 112, 247, 255"
+
+    Returns:
+        Hex color string like "#7070F7"
+    """
+    parts = [int(x.strip()) for x in rgba_str.split(",")]
+    r, g, b = parts[0], parts[1], parts[2]
+    return f"#{r:02x}{g:02x}{b:02x}"

backend/models/user.py

@@ -0,0 +1,254 @@
+"""
+User model for authentication and credits.
+
+Supports:
+- Magic link authentication (email-based)
+- Credit system for karaoke generation
+- Role-based access control (user/admin)
+- Stripe integration for payments
+- Beta tester program with feedback collection
+"""
+from datetime import datetime
+from enum import Enum
+from typing import Optional, List
+from pydantic import BaseModel, Field
+
+
+class UserRole(str, Enum):
+    """User roles for access control."""
+    USER = "user"
+    ADMIN = "admin"
+
+
+class BetaTesterStatus(str, Enum):
+    """Status of beta tester participation."""
+    ACTIVE = "active"  # Enrolled, free credits available
+    PENDING_FEEDBACK = "pending_feedback"  # Job completed, awaiting feedback
+    COMPLETED = "completed"  # Feedback submitted
+    EXPIRED = "expired"  # 24hr deadline passed without feedback
+
+
+class CreditTransaction(BaseModel):
+    """Record of a credit transaction."""
+    id: str
+    amount: int  # Positive = add, negative = deduct
+    reason: str  # e.g., "purchase", "refund", "admin_grant", "job_creation"
+    job_id: Optional[str] = None
+    stripe_session_id: Optional[str] = None
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    created_by: Optional[str] = None  # Admin email if granted by admin
+
+
+class User(BaseModel):
+    """
+    User model stored in Firestore.
+
+    Users are identified by email address. Authentication is via magic links
+    (no passwords). Credits are consumed when creating karaoke jobs.
+    """
+    email: str  # Primary identifier
+    role: UserRole = UserRole.USER
+    credits: int = 0
+
+    # Stripe integration
+    stripe_customer_id: Optional[str] = None
+
+    # Account state
+    is_active: bool = True
+    email_verified: bool = False
+
+    # Timestamps
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    updated_at: datetime = Field(default_factory=datetime.utcnow)
+    last_login_at: Optional[datetime] = None
+
+    # Credit history (last 100 transactions)
+    credit_transactions: List[CreditTransaction] = Field(default_factory=list)
+
+    # Job tracking
+    total_jobs_created: int = 0
+    total_jobs_completed: int = 0
+
+    # Optional profile fields for future use
+    display_name: Optional[str] = None
+
+    # Beta tester program
+    is_beta_tester: bool = False
+    beta_tester_status: Optional[BetaTesterStatus] = None
+    beta_enrolled_at: Optional[datetime] = None
+    beta_promise_text: Optional[str] = None  # User's promise statement
+    beta_feedback_due_at: Optional[datetime] = None  # 24hr after job completion
+    beta_feedback_email_sent: bool = False
+
+
+class MagicLinkToken(BaseModel):
+    """
+    Magic link token for passwordless authentication.
+
+    Tokens are short-lived (15 minutes) and single-use.
+    Stored in Firestore with automatic TTL.
+    """
+    token: str  # Secure random token
+    email: str
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    expires_at: datetime
+    used: bool = False
+    used_at: Optional[datetime] = None
+    ip_address: Optional[str] = None
+    user_agent: Optional[str] = None
+
+
+class Session(BaseModel):
+    """
+    User session for authenticated requests.
+
+    Sessions are created after successful magic link verification.
+    Sessions expire after 7 days of inactivity or 30 days absolute.
+    """
+    token: str  # Secure random session token
+    user_email: str
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    expires_at: datetime
+    last_activity_at: datetime = Field(default_factory=datetime.utcnow)
+    ip_address: Optional[str] = None
+    user_agent: Optional[str] = None
+    is_active: bool = True
+
+
+# Pydantic models for API requests/responses
+
+class SendMagicLinkRequest(BaseModel):
+    """Request to send a magic link email."""
+    email: str
+
+
+class SendMagicLinkResponse(BaseModel):
+    """Response after sending magic link."""
+    status: str
+    message: str
+
+
+class VerifyMagicLinkRequest(BaseModel):
+    """Request to verify a magic link token."""
+    token: str
+
+
+class VerifyMagicLinkResponse(BaseModel):
+    """Response after verifying magic link."""
+    status: str
+    session_token: str
+    user: "UserPublic"
+    message: str
+
+
+class UserPublic(BaseModel):
+    """Public user information (safe to expose to frontend)."""
+    email: str
+    role: UserRole
+    credits: int
+    display_name: Optional[str] = None
+    total_jobs_created: int = 0
+    total_jobs_completed: int = 0
+
+
+class AddCreditsRequest(BaseModel):
+    """Admin request to add credits to a user."""
+    email: str
+    amount: int
+    reason: str = "admin_grant"
+
+
+class AddCreditsResponse(BaseModel):
+    """Response after adding credits."""
+    status: str
+    email: str
+    credits_added: int
+    new_balance: int
+    message: str
+
+
+class UserListResponse(BaseModel):
+    """Response for listing users (admin only)."""
+    users: List[UserPublic]
+    total: int
+
+
+# ============================================================================
+# Beta Tester Program Models
+# ============================================================================
+
+class BetaTesterFeedback(BaseModel):
+    """
+    Feedback from a beta tester after using the service.
+
+    Stored in Firestore 'beta_feedback' collection.
+    """
+    id: str  # Unique feedback ID
+    user_email: str
+    job_id: Optional[str] = None  # The job they're providing feedback on
+
+    # Ratings (1-5 scale)
+    overall_rating: int = Field(ge=1, le=5)
+    ease_of_use_rating: int = Field(ge=1, le=5)
+    lyrics_accuracy_rating: int = Field(ge=1, le=5)
+    correction_experience_rating: int = Field(ge=1, le=5)
+
+    # Open-ended feedback
+    what_went_well: Optional[str] = None
+    what_could_improve: Optional[str] = None
+    additional_comments: Optional[str] = None
+
+    # Would they recommend / use again?
+    would_recommend: bool = True
+    would_use_again: bool = True
+
+    # Metadata
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    submitted_via: str = "web"  # 'web' or 'email'
+
+
+class BetaTesterEnrollRequest(BaseModel):
+    """Request to enroll as a beta tester."""
+    email: str
+    promise_text: str = Field(
+        min_length=10,
+        description="User's promise to provide feedback (min 10 chars)"
+    )
+    accept_corrections_work: bool = Field(
+        description="User accepts they may need to review/correct lyrics"
+    )
+
+
+class BetaTesterEnrollResponse(BaseModel):
+    """Response after enrolling as beta tester."""
+    status: str
+    message: str
+    credits_granted: int
+    session_token: Optional[str] = None  # If new user, provide session
+
+
+class BetaFeedbackRequest(BaseModel):
+    """Request to submit beta tester feedback."""
+    job_id: Optional[str] = None
+
+    # Ratings (1-5 scale)
+    overall_rating: int = Field(ge=1, le=5)
+    ease_of_use_rating: int = Field(ge=1, le=5)
+    lyrics_accuracy_rating: int = Field(ge=1, le=5)
+    correction_experience_rating: int = Field(ge=1, le=5)
+
+    # Open-ended feedback
+    what_went_well: Optional[str] = None
+    what_could_improve: Optional[str] = None
+    additional_comments: Optional[str] = None
+
+    # Would they recommend / use again?
+    would_recommend: bool = True
+    would_use_again: bool = True
+
+
+class BetaFeedbackResponse(BaseModel):
+    """Response after submitting feedback."""
+    status: str
+    message: str
+    bonus_credits: int = 0  # Bonus credits for great feedback

backend/models/worker_log.py

@@ -0,0 +1,164 @@
+"""
+Worker log entry model for subcollection storage.
+
+This module defines the LogEntry model for storing worker logs in a Firestore
+subcollection instead of an embedded array. This avoids the 1MB document size
+limit that caused job 501258e1 to fail when logs reached 1.26 MB.
+"""
+from dataclasses import dataclass, field
+from datetime import datetime, timezone, timedelta
+from typing import Optional, Dict, Any
+import uuid
+
+
+# Default TTL for log entries (30 days)
+DEFAULT_LOG_TTL_DAYS = 30
+
+
+@dataclass
+class WorkerLogEntry:
+    """
+    Worker log entry for Firestore subcollection storage.
+
+    Stored at: jobs/{job_id}/logs/{log_id}
+
+    This model is separate from the legacy LogEntry (in job.py) which is
+    stored as an embedded array in the job document. This new model supports
+    the subcollection approach with TTL and richer metadata.
+    """
+    # Core fields (required)
+    timestamp: datetime
+    level: str  # "DEBUG", "INFO", "WARNING", "ERROR"
+    worker: str  # "audio", "lyrics", "screens", "video", "render", "distribution"
+    message: str
+
+    # Identifiers
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    job_id: str = ""  # Set when writing to Firestore
+
+    # TTL for automatic cleanup
+    ttl_expiry: datetime = field(
+        default_factory=lambda: datetime.now(timezone.utc) + timedelta(days=DEFAULT_LOG_TTL_DAYS)
+    )
+
+    # Optional metadata for debugging
+    metadata: Optional[Dict[str, Any]] = None
+
+    @classmethod
+    def create(
+        cls,
+        job_id: str,
+        worker: str,
+        level: str,
+        message: str,
+        metadata: Optional[Dict[str, Any]] = None,
+        ttl_days: int = DEFAULT_LOG_TTL_DAYS
+    ) -> "WorkerLogEntry":
+        """
+        Factory method to create a new log entry.
+
+        Args:
+            job_id: Job ID this log belongs to
+            worker: Worker name (audio, lyrics, screens, video, render, distribution)
+            level: Log level (DEBUG, INFO, WARNING, ERROR)
+            message: Log message (truncated to 1000 chars)
+            metadata: Optional additional metadata
+            ttl_days: Days until log expires (default 30)
+
+        Returns:
+            New WorkerLogEntry instance
+        """
+        now = datetime.now(timezone.utc)
+        return cls(
+            id=str(uuid.uuid4()),
+            job_id=job_id,
+            timestamp=now,
+            level=level.upper(),
+            worker=worker,
+            message=message[:1000],  # Truncate long messages
+            metadata=metadata,
+            ttl_expiry=now + timedelta(days=ttl_days)
+        )
+
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Convert to dictionary for Firestore storage.
+
+        Returns:
+            Dictionary representation for Firestore
+        """
+        result = {
+            "id": self.id,
+            "job_id": self.job_id,
+            "timestamp": self.timestamp,
+            "level": self.level,
+            "worker": self.worker,
+            "message": self.message,
+            "ttl_expiry": self.ttl_expiry
+        }
+        if self.metadata:
+            result["metadata"] = self.metadata
+        return result
+
+    def to_legacy_dict(self) -> Dict[str, Any]:
+        """
+        Convert to legacy format for backward compatibility with API responses.
+
+        The existing API returns logs in this format:
+        {"timestamp": "...", "level": "INFO", "worker": "audio", "message": "..."}
+
+        Returns:
+            Dictionary in legacy format
+        """
+        # Format timestamp: use "Z" suffix for UTC, isoformat() for others
+        if self.timestamp.tzinfo is None:
+            # Naive datetime - use as-is
+            timestamp_str = self.timestamp.isoformat()
+        elif self.timestamp.utcoffset() == timedelta(0):
+            # UTC datetime - replace +00:00 with Z for cleaner format
+            timestamp_str = self.timestamp.replace(tzinfo=None).isoformat() + "Z"
+        else:
+            # Non-UTC timezone-aware - use full isoformat with offset
+            timestamp_str = self.timestamp.isoformat()
+
+        return {
+            "timestamp": timestamp_str,
+            "level": self.level,
+            "worker": self.worker,
+            "message": self.message
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "WorkerLogEntry":
+        """
+        Create from Firestore document data.
+
+        Args:
+            data: Dictionary from Firestore document
+
+        Returns:
+            WorkerLogEntry instance
+        """
+        # Handle timestamp conversion (Firestore returns datetime objects)
+        timestamp = data.get("timestamp")
+        if isinstance(timestamp, str):
+            # Parse ISO format string
+            timestamp = datetime.fromisoformat(timestamp.rstrip("Z")).replace(tzinfo=timezone.utc)
+
+        ttl_expiry = data.get("ttl_expiry")
+        if isinstance(ttl_expiry, str):
+            ttl_expiry = datetime.fromisoformat(ttl_expiry.rstrip("Z")).replace(tzinfo=timezone.utc)
+        elif ttl_expiry is None:
+            # Default TTL if not set
+            ttl_expiry = datetime.now(timezone.utc) + timedelta(days=DEFAULT_LOG_TTL_DAYS)
+
+        return cls(
+            id=data.get("id", str(uuid.uuid4())),
+            job_id=data.get("job_id", ""),
+            timestamp=timestamp or datetime.now(timezone.utc),
+            level=data.get("level", "INFO"),
+            worker=data.get("worker", "unknown"),
+            message=data.get("message", ""),
+            metadata=data.get("metadata"),
+            ttl_expiry=ttl_expiry
+        )

backend/pyproject.toml

@@ -0,0 +1,29 @@
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = [
+    "-v",
+    "--tb=short",
+    "--strict-markers",
+    "-ra",
+]
+
+markers = [
+    "slow: marks tests as slow (deselect with '-m \"not slow\"')",
+    "integration: marks tests as integration tests requiring live service",
+]
+
+# Timeout for slow tests (in seconds)
+timeout = 300
+
+[tool.coverage.run]
+source = ["backend"]
+omit = ["*/tests/*", "*/test_*"]
+
+[tool.coverage.report]
+precision = 2
+show_missing = true
+skip_covered = false
+

backend/quick-check.sh

@@ -0,0 +1,93 @@
+#!/bin/bash
+# Quick syntax and structure check (no dependencies required)
+# Run this before every deployment!
+
+set -e
+
+echo "🔍 Quick Backend Check (no dependencies required)"
+echo "=================================================="
+echo ""
+
+# Change to backend directory
+cd "$(dirname "$0")"
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+NC='\033[0m'
+
+ERRORS=0
+
+# Check 1: Python syntax
+echo "1. Checking Python syntax..."
+for file in $(find . -name "*.py" -not -path "./__pycache__/*" -not -path "./venv/*"); do
+    if ! python3 -m py_compile "$file" 2>/dev/null; then
+        echo -e "  ${RED}❌ Syntax error in $file${NC}"
+        python3 -m py_compile "$file"
+        ERRORS=$((ERRORS+1))
+    fi
+done
+
+if [ $ERRORS -eq 0 ]; then
+    echo -e "  ${GREEN}✅ All Python files have valid syntax${NC}"
+fi
+
+# Check 2: No missing imports (basic check)
+echo ""
+echo "2. Checking for obvious import issues..."
+
+# Check that we don't import deleted modules
+if grep -r "from backend.services.processing_service import" --include="*.py" . 2>/dev/null; then
+    echo -e "  ${RED}❌ Found import of deleted processing_service${NC}"
+    ERRORS=$((ERRORS+1))
+else
+    echo -e "  ${GREEN}✅ No imports of deleted modules${NC}"
+fi
+
+# Check 3: Required files exist
+echo ""
+echo "3. Checking required files exist..."
+REQUIRED_FILES=(
+    "main.py"
+    "config.py"
+    "requirements.txt"
+    "Dockerfile"
+    "api/routes/health.py"
+    "api/routes/jobs.py"
+    "api/routes/internal.py"
+    "api/routes/file_upload.py"
+    "services/job_manager.py"
+    "services/firestore_service.py"
+    "services/storage_service.py"
+    "services/worker_service.py"
+    "services/auth_service.py"
+    "workers/audio_worker.py"
+    "workers/lyrics_worker.py"
+    "workers/screens_worker.py"
+    "workers/video_worker.py"
+    "models/job.py"
+    "models/requests.py"
+)
+
+for file in "${REQUIRED_FILES[@]}"; do
+    if [ ! -f "$file" ]; then
+        echo -e "  ${RED}❌ Missing required file: $file${NC}"
+        ERRORS=$((ERRORS+1))
+    fi
+done
+
+if [ $ERRORS -eq 0 ]; then
+    echo -e "  ${GREEN}✅ All required files exist${NC}"
+fi
+
+# Summary
+echo ""
+echo "=================================================="
+if [ $ERRORS -eq 0 ]; then
+    echo -e "${GREEN}✅ All checks passed! Safe to deploy.${NC}"
+    exit 0
+else
+    echo -e "${RED}❌ $ERRORS error(s) found. Fix before deploying!${NC}"
+    exit 1
+fi
+