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

backend/requirements.txt

@@ -0,0 +1,29 @@
+# DEPRECATED: This file is no longer used for Docker builds or CI.
+# Docker and CI both use poetry/pyproject.toml directly.
+# This file is kept for reference only.
+
+fastapi>=0.104.0,<1.0.0
+uvicorn[standard]>=0.24.0,<1.0.0
+pydantic>=2.5.0,<3.0.0
+pydantic-settings>=2.1.0,<3.0.0
+python-multipart>=0.0.6,<1.0.0
+httpx>=0.25.0,<1.0.0
+google-cloud-firestore>=2.14.0,<3.0.0
+google-cloud-storage>=2.14.0,<3.0.0
+google-cloud-secret-manager>=2.18.0,<3.0.0
+google-cloud-tasks>=2.14.0,<3.0.0
+google-cloud-run>=0.10.0,<1.0.0
+python-dotenv>=1.0.0,<2.0.0
+
+# Audio processing (reuses karaoke_gen library)
+audio-separator[remote]>=0.18.0  # Remote Modal API client
+pydub>=0.25.1  # Audio manipulation (used by karaoke_gen)
+yt-dlp>=2024.0.0  # YouTube downloads (future use)
+
+# Cloud storage native APIs
+dropbox>=11.0.0  # Dropbox Python SDK for native API access
+# google-api-python-client already installed via karaoke_gen for YouTube
+
+# karaoke-gen dependencies (will be installed from parent dir in Dockerfile)
+# Using explicit dependencies instead of -e ../
+

backend/run_tests.sh

@@ -0,0 +1,60 @@
+#!/bin/bash
+# Backend Test Runner
+# Runs integration tests against the deployed Cloud Run service
+
+set -e
+
+echo "🧪 Backend Integration Test Suite"
+echo "=================================="
+echo ""
+
+# Check prerequisites
+echo "Checking prerequisites..."
+if ! command -v gcloud &> /dev/null; then
+    echo "❌ gcloud CLI not found. Please install Google Cloud SDK."
+    exit 1
+fi
+
+if ! command -v pytest &> /dev/null; then
+    echo "❌ pytest not found. Installing test dependencies..."
+    pip install -r tests/requirements.txt
+fi
+
+# Verify authentication
+echo "Verifying authentication..."
+if ! gcloud auth print-identity-token &> /dev/null; then
+    echo "❌ Not authenticated with gcloud. Run: gcloud auth login"
+    exit 1
+fi
+
+echo "✅ Prerequisites met"
+echo ""
+
+# Run tests
+echo "Running integration tests..."
+echo ""
+
+# Run fast tests (no slow marker)
+echo "📝 Running fast tests..."
+pytest tests/test_api_integration.py -v -m "not slow" --tb=short
+
+echo ""
+echo "✅ Fast tests complete!"
+echo ""
+
+# Ask if user wants to run slow tests
+read -p "Run slow/integration tests? These test actual job processing (5-10 min). [y/N] " -n 1 -r
+echo
+if [[ $REPLY =~ ^[Yy]$ ]]; then
+    echo "🐌 Running slow integration tests..."
+    pytest tests/test_api_integration.py -v -m "slow" --tb=short
+    echo ""
+    echo "✅ All tests complete!"
+else
+    echo "⏭️  Skipping slow tests"
+fi
+
+echo ""
+echo "=================================="
+echo "Test run complete! 🎉"
+

backend/services/audio_analysis_service.py

@@ -0,0 +1,243 @@
+"""
+Audio analysis service for analyzing backing vocals.
+
+This service wraps the shared karaoke_gen.instrumental_review module
+to provide GCS-integrated audio analysis capabilities.
+"""
+
+import logging
+import os
+import tempfile
+from typing import Optional
+
+from backend.services.storage_service import StorageService
+from karaoke_gen.instrumental_review import (
+    AudioAnalyzer,
+    AnalysisResult,
+    WaveformGenerator,
+)
+
+
+logger = logging.getLogger(__name__)
+
+
+class AudioAnalysisService:
+    """
+    Service for analyzing backing vocals audio files stored in GCS.
+    
+    This service acts as a thin wrapper around the shared AudioAnalyzer
+    and WaveformGenerator classes, handling GCS download/upload operations.
+    
+    The actual analysis logic is in the shared karaoke_gen.instrumental_review
+    module, ensuring feature parity between local and remote workflows.
+    """
+    
+    def __init__(
+        self,
+        storage_service: Optional[StorageService] = None,
+        silence_threshold_db: float = -40.0,
+        min_segment_duration_ms: int = 100,
+    ):
+        """
+        Initialize the audio analysis service.
+        
+        Args:
+            storage_service: GCS storage service. If not provided, a new
+                instance will be created.
+            silence_threshold_db: Threshold for considering audio as silent.
+                Default is -40.0 dB.
+            min_segment_duration_ms: Minimum duration for audible segments.
+                Default is 100ms.
+        """
+        self.storage_service = storage_service or StorageService()
+        self.analyzer = AudioAnalyzer(
+            silence_threshold_db=silence_threshold_db,
+            min_segment_duration_ms=min_segment_duration_ms,
+        )
+        self.waveform_generator = WaveformGenerator()
+    
+    def analyze_backing_vocals(
+        self,
+        gcs_audio_path: str,
+        job_id: str,
+    ) -> AnalysisResult:
+        """
+        Analyze a backing vocals audio file from GCS.
+        
+        This method:
+        1. Downloads the audio file from GCS to a temp file
+        2. Runs the analysis using the shared AudioAnalyzer
+        3. Returns the analysis result
+        
+        Args:
+            gcs_audio_path: Path to the audio file in GCS
+            job_id: Job ID for logging
+        
+        Returns:
+            AnalysisResult containing analysis data
+        """
+        logger.info(f"[{job_id}] Analyzing backing vocals: {gcs_audio_path}")
+        
+        with tempfile.TemporaryDirectory() as temp_dir:
+            # Download audio file
+            local_audio_path = os.path.join(temp_dir, "backing_vocals.flac")
+            self.storage_service.download_file(gcs_audio_path, local_audio_path)
+            
+            # Run analysis
+            result = self.analyzer.analyze(local_audio_path)
+            
+            logger.info(
+                f"[{job_id}] Analysis complete: "
+                f"has_audible={result.has_audible_content}, "
+                f"segments={result.segment_count}, "
+                f"recommendation={result.recommended_selection.value}"
+            )
+            
+            return result
+    
+    def analyze_and_generate_waveform(
+        self,
+        gcs_audio_path: str,
+        job_id: str,
+        gcs_waveform_destination: str,
+    ) -> tuple[AnalysisResult, str]:
+        """
+        Analyze backing vocals and generate a waveform image.
+        
+        This method:
+        1. Downloads the audio file from GCS
+        2. Runs analysis using AudioAnalyzer
+        3. Generates waveform image using WaveformGenerator
+        4. Uploads the waveform image to GCS
+        5. Returns analysis result and waveform GCS path
+        
+        Args:
+            gcs_audio_path: Path to the audio file in GCS
+            job_id: Job ID for logging
+            gcs_waveform_destination: Where to upload the waveform image in GCS
+        
+        Returns:
+            Tuple of (AnalysisResult, waveform_gcs_path)
+        """
+        logger.info(f"[{job_id}] Analyzing and generating waveform: {gcs_audio_path}")
+        
+        with tempfile.TemporaryDirectory() as temp_dir:
+            # Download audio file
+            local_audio_path = os.path.join(temp_dir, "backing_vocals.flac")
+            self.storage_service.download_file(gcs_audio_path, local_audio_path)
+            
+            # Run analysis
+            result = self.analyzer.analyze(local_audio_path)
+            
+            # Generate waveform
+            local_waveform_path = os.path.join(temp_dir, "waveform.png")
+            self.waveform_generator.generate(
+                audio_path=local_audio_path,
+                output_path=local_waveform_path,
+                segments=result.audible_segments,
+                show_time_axis=True,
+                silence_threshold_db=self.analyzer.silence_threshold_db,
+            )
+            
+            # Upload waveform to GCS
+            self.storage_service.upload_file(
+                local_waveform_path,
+                gcs_waveform_destination
+            )
+            
+            logger.info(
+                f"[{job_id}] Analysis and waveform generation complete. "
+                f"Waveform uploaded to: {gcs_waveform_destination}"
+            )
+            
+            return result, gcs_waveform_destination
+    
+    def get_waveform_data(
+        self,
+        gcs_audio_path: str,
+        job_id: str,
+        num_points: int = 500,
+    ) -> tuple[list[float], float]:
+        """
+        Get waveform data (amplitude envelope) for client-side rendering.
+        
+        This is useful when the frontend wants to render the waveform
+        itself using Canvas or SVG, rather than displaying a pre-generated
+        image.
+        
+        Args:
+            gcs_audio_path: Path to the audio file in GCS
+            job_id: Job ID for logging
+            num_points: Number of data points to return
+        
+        Returns:
+            Tuple of (amplitude_values, duration_seconds)
+        """
+        logger.info(f"[{job_id}] Getting waveform data: {gcs_audio_path}")
+        
+        with tempfile.TemporaryDirectory() as temp_dir:
+            # Download audio file
+            local_audio_path = os.path.join(temp_dir, "backing_vocals.flac")
+            self.storage_service.download_file(gcs_audio_path, local_audio_path)
+            
+            # Generate waveform data
+            amplitudes, duration = self.waveform_generator.generate_data_only(
+                audio_path=local_audio_path,
+                num_points=num_points,
+            )
+            
+            return amplitudes, duration
+    
+    def generate_waveform_with_mutes(
+        self,
+        gcs_audio_path: str,
+        job_id: str,
+        gcs_waveform_destination: str,
+        mute_regions: list,
+    ) -> str:
+        """
+        Generate a waveform image with mute regions highlighted.
+        
+        This is useful for showing the user which regions will be muted
+        in the custom instrumental.
+        
+        Args:
+            gcs_audio_path: Path to the audio file in GCS
+            job_id: Job ID for logging
+            gcs_waveform_destination: Where to upload the waveform image
+            mute_regions: List of MuteRegion objects to highlight
+        
+        Returns:
+            GCS path to the uploaded waveform image
+        """
+        from karaoke_gen.instrumental_review import MuteRegion
+        
+        logger.info(
+            f"[{job_id}] Generating waveform with {len(mute_regions)} mute regions"
+        )
+        
+        with tempfile.TemporaryDirectory() as temp_dir:
+            # Download audio file
+            local_audio_path = os.path.join(temp_dir, "backing_vocals.flac")
+            self.storage_service.download_file(gcs_audio_path, local_audio_path)
+            
+            # First run analysis to get segments
+            result = self.analyzer.analyze(local_audio_path)
+            
+            # Generate waveform with mute regions
+            local_waveform_path = os.path.join(temp_dir, "waveform_with_mutes.png")
+            self.waveform_generator.generate(
+                audio_path=local_audio_path,
+                output_path=local_waveform_path,
+                segments=result.audible_segments,
+                mute_regions=mute_regions,
+                show_time_axis=True,
+            )
+            
+            # Upload to GCS
+            self.storage_service.upload_file(
+                local_waveform_path,
+                gcs_waveform_destination
+            )
+            
+            return gcs_waveform_destination

backend/services/audio_editing_service.py

@@ -0,0 +1,278 @@
+"""
+Audio editing service for creating custom instrumentals.
+
+This service wraps the shared karaoke_gen.instrumental_review module
+to provide GCS-integrated audio editing capabilities.
+"""
+
+import logging
+import os
+import tempfile
+from typing import List, Optional
+
+from backend.services.storage_service import StorageService
+from karaoke_gen.instrumental_review import (
+    AudioEditor,
+    MuteRegion,
+)
+from karaoke_gen.instrumental_review.models import CustomInstrumentalResult
+
+
+logger = logging.getLogger(__name__)
+
+
+class AudioEditingService:
+    """
+    Service for creating custom instrumental tracks with GCS integration.
+    
+    This service acts as a thin wrapper around the shared AudioEditor
+    class, handling GCS download/upload operations.
+    
+    The actual editing logic is in the shared karaoke_gen.instrumental_review
+    module, ensuring feature parity between local and remote workflows.
+    """
+    
+    def __init__(
+        self,
+        storage_service: Optional[StorageService] = None,
+        output_format: str = "flac",
+    ):
+        """
+        Initialize the audio editing service.
+        
+        Args:
+            storage_service: GCS storage service. If not provided, a new
+                instance will be created.
+            output_format: Output audio format. Default is "flac".
+        """
+        self.storage_service = storage_service or StorageService()
+        self.editor = AudioEditor(output_format=output_format)
+    
+    def create_custom_instrumental(
+        self,
+        gcs_clean_instrumental_path: str,
+        gcs_backing_vocals_path: str,
+        mute_regions: List[MuteRegion],
+        gcs_output_path: str,
+        job_id: str,
+    ) -> CustomInstrumentalResult:
+        """
+        Create a custom instrumental by muting regions of backing vocals.
+        
+        This method:
+        1. Downloads clean instrumental and backing vocals from GCS
+        2. Applies mute regions to backing vocals
+        3. Combines with clean instrumental
+        4. Uploads result to GCS
+        
+        Args:
+            gcs_clean_instrumental_path: Path to clean instrumental in GCS
+            gcs_backing_vocals_path: Path to backing vocals in GCS
+            mute_regions: List of regions to mute in backing vocals
+            gcs_output_path: Where to upload the custom instrumental in GCS
+            job_id: Job ID for logging
+        
+        Returns:
+            CustomInstrumentalResult with details about the created file
+        """
+        logger.info(
+            f"[{job_id}] Creating custom instrumental with "
+            f"{len(mute_regions)} mute regions"
+        )
+        
+        with tempfile.TemporaryDirectory() as temp_dir:
+            # Download input files
+            local_clean_path = os.path.join(temp_dir, "clean_instrumental.flac")
+            local_backing_path = os.path.join(temp_dir, "backing_vocals.flac")
+            local_output_path = os.path.join(temp_dir, "custom_instrumental.flac")
+            
+            logger.debug(f"[{job_id}] Downloading clean instrumental")
+            self.storage_service.download_file(
+                gcs_clean_instrumental_path,
+                local_clean_path
+            )
+            
+            logger.debug(f"[{job_id}] Downloading backing vocals")
+            self.storage_service.download_file(
+                gcs_backing_vocals_path,
+                local_backing_path
+            )
+            
+            # Create custom instrumental using shared editor
+            result = self.editor.create_custom_instrumental(
+                clean_instrumental_path=local_clean_path,
+                backing_vocals_path=local_backing_path,
+                mute_regions=mute_regions,
+                output_path=local_output_path,
+            )
+            
+            # Upload result to GCS
+            logger.debug(f"[{job_id}] Uploading custom instrumental to GCS")
+            self.storage_service.upload_file(local_output_path, gcs_output_path)
+            
+            # Update result with GCS path
+            result.output_path = gcs_output_path
+            
+            logger.info(
+                f"[{job_id}] Custom instrumental created: {gcs_output_path}, "
+                f"muted {result.total_muted_duration_seconds:.1f}s across "
+                f"{len(result.mute_regions_applied)} regions"
+            )
+            
+            return result
+    
+    def create_preview(
+        self,
+        gcs_clean_instrumental_path: str,
+        gcs_backing_vocals_path: str,
+        mute_regions: List[MuteRegion],
+        gcs_preview_path: str,
+        job_id: str,
+        preview_duration_seconds: Optional[float] = None,
+    ) -> str:
+        """
+        Create a preview of the custom instrumental.
+        
+        This is similar to create_custom_instrumental but optimized for
+        quick preview generation (optionally truncated duration).
+        
+        Args:
+            gcs_clean_instrumental_path: Path to clean instrumental in GCS
+            gcs_backing_vocals_path: Path to backing vocals in GCS
+            mute_regions: List of regions to mute
+            gcs_preview_path: Where to upload the preview in GCS
+            job_id: Job ID for logging
+            preview_duration_seconds: Optional max duration for preview
+        
+        Returns:
+            GCS path to the uploaded preview
+        """
+        logger.info(f"[{job_id}] Creating preview with {len(mute_regions)} mute regions")
+        
+        with tempfile.TemporaryDirectory() as temp_dir:
+            # Download input files
+            local_clean_path = os.path.join(temp_dir, "clean_instrumental.flac")
+            local_backing_path = os.path.join(temp_dir, "backing_vocals.flac")
+            local_preview_path = os.path.join(temp_dir, "preview.flac")
+            
+            self.storage_service.download_file(
+                gcs_clean_instrumental_path,
+                local_clean_path
+            )
+            self.storage_service.download_file(
+                gcs_backing_vocals_path,
+                local_backing_path
+            )
+            
+            # Generate preview
+            from pydub import AudioSegment
+            
+            preview = self.editor.preview_with_mutes(
+                clean_instrumental_path=local_clean_path,
+                backing_vocals_path=local_backing_path,
+                mute_regions=mute_regions,
+            )
+            
+            # Optionally truncate
+            if preview_duration_seconds:
+                max_ms = int(preview_duration_seconds * 1000)
+                preview = preview[:max_ms]
+            
+            # Export and upload
+            preview.export(local_preview_path, format="flac")
+            self.storage_service.upload_file(local_preview_path, gcs_preview_path)
+            
+            logger.info(f"[{job_id}] Preview created: {gcs_preview_path}")
+            
+            return gcs_preview_path
+    
+    def mute_backing_vocals_only(
+        self,
+        gcs_backing_vocals_path: str,
+        mute_regions: List[MuteRegion],
+        gcs_output_path: str,
+        job_id: str,
+    ) -> str:
+        """
+        Apply mute regions to backing vocals without combining with instrumental.
+        
+        This is useful for creating an edited backing vocals track that
+        can be combined with the instrumental later.
+        
+        Args:
+            gcs_backing_vocals_path: Path to backing vocals in GCS
+            mute_regions: List of regions to mute
+            gcs_output_path: Where to upload the edited backing vocals
+            job_id: Job ID for logging
+        
+        Returns:
+            GCS path to the uploaded edited backing vocals
+        """
+        logger.info(
+            f"[{job_id}] Muting backing vocals with {len(mute_regions)} regions"
+        )
+        
+        with tempfile.TemporaryDirectory() as temp_dir:
+            local_backing_path = os.path.join(temp_dir, "backing_vocals.flac")
+            local_output_path = os.path.join(temp_dir, "muted_backing.flac")
+            
+            self.storage_service.download_file(
+                gcs_backing_vocals_path,
+                local_backing_path
+            )
+            
+            self.editor.apply_mute_to_single_track(
+                audio_path=local_backing_path,
+                mute_regions=mute_regions,
+                output_path=local_output_path,
+            )
+            
+            self.storage_service.upload_file(local_output_path, gcs_output_path)
+            
+            logger.info(f"[{job_id}] Muted backing vocals: {gcs_output_path}")
+            
+            return gcs_output_path
+    
+    def validate_mute_regions(
+        self,
+        mute_regions: List[MuteRegion],
+        total_duration_seconds: float,
+    ) -> List[str]:
+        """
+        Validate mute regions for consistency.
+        
+        Args:
+            mute_regions: List of mute regions to validate
+            total_duration_seconds: Total duration of the audio
+        
+        Returns:
+            List of validation error messages (empty if valid)
+        """
+        errors = []
+        
+        for i, region in enumerate(mute_regions):
+            if region.start_seconds < 0:
+                errors.append(
+                    f"Region {i}: start_seconds ({region.start_seconds}) cannot be negative"
+                )
+            
+            if region.end_seconds <= region.start_seconds:
+                errors.append(
+                    f"Region {i}: end_seconds ({region.end_seconds}) must be after "
+                    f"start_seconds ({region.start_seconds})"
+                )
+            
+            if region.start_seconds > total_duration_seconds:
+                errors.append(
+                    f"Region {i}: start_seconds ({region.start_seconds}) exceeds "
+                    f"audio duration ({total_duration_seconds})"
+                )
+            
+            if region.end_seconds > total_duration_seconds:
+                # Not an error, but log a warning - the region will be clamped
+                logger.warning(
+                    f"Region {i}: end_seconds ({region.end_seconds}) exceeds "
+                    f"audio duration ({total_duration_seconds}), will be clamped"
+                )
+        
+        return errors