karaoke-gen 0.86.7__py3-none-any.whl → 0.96.0__py3-none-any.whl

backend/.coveragerc

@@ -0,0 +1,20 @@
+[run]
+source = backend
+omit =
+    backend/tests/*
+    backend/validate.py
+    backend/tests/emulator/*
+    # Workers that require external APIs are tested via integration tests
+    backend/workers/screens_worker.py
+    backend/workers/video_worker.py
+
+[report]
+exclude_lines =
+    pragma: no cover
+    def __repr__
+    raise NotImplementedError
+    if __name__ == .__main__.:
+    pass
+
+show_missing = True
+

backend/.gitignore

@@ -0,0 +1,37 @@
+# Ignore Python cache and virtual environments
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Environment files
+.env
+.env.local
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Temporary files
+*.log
+temp/
+tmp/
+
+# Google Cloud
+.gcloud/
+*.json
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+

backend/Dockerfile

@@ -0,0 +1,43 @@
+# Fast application image - uses pre-built base with all dependencies
+#
+# The base image (karaoke-backend-base) contains:
+# - Python 3.11, ffmpeg, sox, system deps
+# - All pip dependencies from requirements-frozen.txt (NO code)
+#
+# This Dockerfile adds the actual application code on top.
+# Build time: ~1-2 minutes (deps already cached in base)
+# 
+# If the base image doesn't exist yet, build it first:
+#   gcloud builds submit --config=cloudbuild-base.yaml --project=nomadkaraoke
+
+# Use pre-built base image with all dependencies
+# Override with --build-arg BASE_IMAGE=karaoke-backend-base:local for local testing
+ARG BASE_IMAGE=us-central1-docker.pkg.dev/nomadkaraoke/karaoke-repo/karaoke-backend-base:latest
+FROM ${BASE_IMAGE}
+
+# Set working directory (should already exist from base)
+WORKDIR /app
+
+# Copy backend code (this is the only thing that changes frequently)
+COPY backend /app/backend
+
+# Copy and reinstall karaoke_gen from local source
+# This ensures new modules (like style_loader.py) are included without rebuilding base image
+# Note: lyrics_transcriber is vendored in lyrics_transcriber_temp/ and bundled via pyproject.toml
+COPY karaoke_gen /app/karaoke_gen
+COPY lyrics_transcriber_temp /app/lyrics_transcriber_temp
+COPY pyproject.toml README.md LICENSE /app/
+RUN pip install --no-cache-dir -e .
+
+# Set environment variables
+ENV PYTHONUNBUFFERED=1
+ENV PORT=8080
+
+# Expose port
+EXPOSE 8080
+
+# Run uvicorn directly
+# Note: Transmission daemon removed - torrent downloads now handled by
+# dedicated flacfetch VM service (see docs/00-current-plan/TORRENT-SERVICE-PLAN.md)
+# Using --loop asyncio (instead of uvloop) to support nest_asyncio for remote flacfetch calls
+CMD ["uvicorn", "backend.main:app", "--host", "0.0.0.0", "--port", "8080", "--loop", "asyncio"]

backend/Dockerfile.base

@@ -0,0 +1,74 @@
+# Base image with all Python dependencies pre-installed
+# This image is rebuilt only when poetry.lock changes
+# 
+# Build with: gcloud builds submit --config=cloudbuild-base.yaml
+# Or manually: docker build -f backend/Dockerfile.base -t karaoke-backend-base .
+
+FROM python:3.11-slim
+
+# Install system dependencies required by karaoke-gen
+# Note: Transmission daemon removed - torrent downloads now handled by
+# dedicated flacfetch VM service (see docs/00-current-plan/TORRENT-SERVICE-PLAN.md)
+RUN apt-get update && apt-get install -y \
+    libsndfile1 \
+    libsox-dev \
+    sox \
+    build-essential \
+    curl \
+    xz-utils \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install comprehensive font support for international lyrics and symbols
+# Noto fonts provide full Unicode coverage including:
+# - Latin, Greek, Cyrillic (core)
+# - CJK: Chinese, Japanese, Korean (~150MB)
+# - Arabic, Hebrew, Thai, Hindi, and other scripts (extra)
+# - Color emoji (limited support in libass, but available)
+# - Musical symbols (♪ ♫ etc.)
+# Note: This adds ~200-300MB to the image but ensures all languages render correctly
+RUN apt-get update && apt-get install -y \
+    fonts-noto-core \
+    fonts-noto-cjk \
+    fonts-noto-extra \
+    fonts-noto-color-emoji \
+    fontconfig \
+    && fc-cache -f \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install optimized static FFmpeg build (7.0.2) instead of Debian package (5.1.8)
+# John Van Sickle's builds are compiled with better optimizations for x86_64
+# This provides ~20-40% performance improvement for encoding tasks
+# Source: https://johnvansickle.com/ffmpeg/
+RUN curl -L https://johnvansickle.com/ffmpeg/releases/ffmpeg-release-amd64-static.tar.xz -o /tmp/ffmpeg.tar.xz && \
+    tar -xf /tmp/ffmpeg.tar.xz -C /tmp && \
+    cp /tmp/ffmpeg-*-amd64-static/ffmpeg /usr/local/bin/ && \
+    cp /tmp/ffmpeg-*-amd64-static/ffprobe /usr/local/bin/ && \
+    chmod +x /usr/local/bin/ffmpeg /usr/local/bin/ffprobe && \
+    rm -rf /tmp/ffmpeg* && \
+    ffmpeg -version
+
+# Set working directory
+WORKDIR /app
+
+# Copy dependency files and source code needed for pip install
+COPY pyproject.toml README.md LICENSE /app/
+COPY karaoke_gen /app/karaoke_gen
+COPY lyrics_transcriber_temp /app/lyrics_transcriber_temp
+
+# Install all Python dependencies (the slow part - cached in base image)
+RUN pip install --no-cache-dir --upgrade pip && \
+    pip install --no-cache-dir -e .
+
+# Download spaCy language model for lyrics transcription
+# This must be done at build time, not runtime (Cloud Run network restrictions)
+RUN python -m spacy download en_core_web_sm
+
+# Label with build info
+ARG BUILD_DATE
+ARG BUILD_ID
+ARG BASE_CONTENT_HASH
+LABEL org.opencontainers.image.created="${BUILD_DATE}"
+LABEL org.opencontainers.image.revision="${BUILD_ID}"
+LABEL org.opencontainers.image.title="karaoke-backend-base"
+LABEL org.opencontainers.image.description="Base image with Python dependencies and system tools for karaoke-backend"
+LABEL base.content.hash="${BASE_CONTENT_HASH}"

backend/README.md

@@ -0,0 +1,242 @@
+# Backend Development Setup
+
+## One-Time Setup
+
+### 1. Create Virtual Environment
+
+```bash
+cd /Users/andrew/Projects/karaoke-gen
+python3 -m venv backend/venv
+```
+
+### 2. Activate Virtual Environment
+
+```bash
+source backend/venv/bin/activate
+```
+
+### 3. Install Dependencies
+
+**IMPORTANT:** Use Python 3.12 (not 3.13/3.14 - pydantic has compatibility issues)
+
+```bash
+# Backend dependencies
+pip install -r backend/requirements.txt
+
+# Install karaoke_gen in development mode
+pip install -e .
+
+# Install lyrics_transcriber submodule
+pip install -e lyrics_transcriber_local/
+
+# Install Google API client (for YouTube upload)
+pip install google-api-python-client google-auth-httplib2 google-auth-oauthlib
+```
+
+### 4. Add Shell Alias (Optional)
+
+Add to `~/.zshrc`:
+
+```bash
+alias backend='cd /Users/andrew/Projects/karaoke-gen && source backend/venv/bin/activate'
+```
+
+Then you can just run:
+```bash
+backend
+# Now you're in the project directory with venv activated!
+```
+
+---
+
+## Daily Workflow
+
+### Before Making Changes
+
+```bash
+# Activate venv
+source backend/venv/bin/activate
+
+# Or if you set up the alias:
+backend
+```
+
+### After Making Changes
+
+```bash
+# 1. Run full validation (catches import errors!)
+python3 backend/validate.py
+
+# 2. If validation passes, deploy
+./scripts/deploy.sh
+```
+
+---
+
+## Validation Options
+
+### Full Validation (Recommended - Requires venv)
+
+```bash
+source backend/venv/bin/activate
+python3 backend/validate.py
+```
+
+**Catches:**
+- ✅ Syntax errors
+- ✅ **Import errors** (like the processing_service issue!)
+- ✅ Configuration issues
+- ✅ FastAPI app creation problems
+- ✅ Missing dependencies
+
+**This would have caught the ModuleNotFoundError!**
+
+### Quick Check (No venv needed)
+
+```bash
+./backend/quick-check.sh
+```
+
+**Catches:**
+- ✅ Syntax errors
+- ✅ Missing files
+- ✅ Some obvious import issues
+
+**Good for quick checks, but won't catch all import errors**
+
+---
+
+## Example: Complete Development Session
+
+```bash
+# 1. Activate environment
+backend  # or: source backend/venv/bin/activate
+
+# 2. Make your changes
+vim backend/api/routes/jobs.py
+
+# 3. Validate (catches import errors!)
+python3 backend/validate.py
+# ✅ All validations passed!
+
+# 4. Deploy
+./scripts/deploy.sh
+
+# 5. Test
+export BACKEND_URL="https://karaoke-backend-ipzqd2k4yq-uc.a.run.app"
+export AUTH_TOKEN=$(gcloud auth print-identity-token)
+curl -H "Authorization: Bearer $AUTH_TOKEN" $BACKEND_URL/api/health
+```
+
+---
+
+## What About karaoke_gen Imports?
+
+The backend imports from `karaoke_gen` (the CLI package):
+
+```python
+from karaoke_gen.karaoke_gen import KaraokePrep
+from karaoke_gen.audio_processor import AudioProcessor
+```
+
+**Options:**
+
+### Option 1: Install in development mode (Recommended)
+
+```bash
+source backend/venv/bin/activate
+pip install -e .
+```
+
+This makes `karaoke_gen` available in the venv without copying files.
+
+### Option 2: Use system Python
+
+Your system Python already has `karaoke_gen` installed, so validation will work even if the venv doesn't have it (Python will fall back to system packages).
+
+---
+
+## Running the Backend Locally
+
+```bash
+# Activate venv
+source backend/venv/bin/activate
+
+# Set required environment variables
+export GOOGLE_CLOUD_PROJECT="nomadkaraoke"
+export GCS_BUCKET_NAME="karaoke-gen-storage-nomadkaraoke"
+
+# Optional: Point to local credentials
+export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json"
+
+# Run the server
+cd backend
+uvicorn main:app --reload --port 8080
+```
+
+Visit: http://localhost:8080/api/health
+
+---
+
+## Troubleshooting
+
+### "No module named 'fastapi'"
+
+**Fix:**
+```bash
+source backend/venv/bin/activate
+pip install -r backend/requirements.txt
+```
+
+### "No module named 'karaoke_gen'"
+
+**Fix:**
+```bash
+source backend/venv/bin/activate
+cd /Users/andrew/Projects/karaoke-gen
+pip install -e .
+```
+
+### Validation passes locally but fails in Cloud Run
+
+**Check:**
+1. Is `requirements.txt` up to date?
+2. Did you add a new dependency without adding it to `requirements.txt`?
+3. Run: `pip freeze | grep <package-name>`
+
+---
+
+## Updating Dependencies
+
+When you add new packages:
+
+```bash
+# 1. Install in venv
+source backend/venv/bin/activate
+pip install new-package
+
+# 2. Update requirements.txt
+pip freeze > backend/requirements.txt
+
+# 3. Or manually add just the new package:
+echo "new-package==1.2.3" >> backend/requirements.txt
+
+# 4. Validate
+python3 backend/validate.py
+
+# 5. Deploy
+./scripts/deploy.sh
+```
+
+---
+
+## Summary
+
+**Best practice workflow:**
+
+1. **One-time setup:** Create venv and install dependencies
+2. **Daily:** Activate venv when working on backend
+3. **Before deploy:** Run `python3 backend/validate.py` (catches import errors!)
+4. **Deploy:** Use `./scripts/deploy.sh`
+
+**The import error would have been caught if you ran validation in a venv!** ✅