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

backend/tests/test_routes_jobs.py

@@ -0,0 +1,282 @@
+"""
+Unit tests for jobs.py routes.
+
+These tests exercise the route logic with mocked services.
+"""
+import pytest
+from datetime import datetime, UTC
+from unittest.mock import MagicMock, AsyncMock, patch
+
+from backend.models.job import Job, JobStatus
+
+
+class TestJobsRouteHelpers:
+    """Tests for helper functions in jobs.py routes."""
+    
+    def test_jobs_router_structure(self):
+        """Test jobs router has expected structure."""
+        from backend.api.routes.jobs import router
+        assert router is not None
+        
+        # Check that common route patterns exist
+        route_paths = [route.path for route in router.routes]
+        assert any('/jobs' in p or 'jobs' in str(p) for p in route_paths)
+
+
+class TestJobStatusTransitions:
+    """Tests for job status transition validation.
+    
+    These test the Job model's state machine which is critical for
+    preventing invalid operations.
+    """
+    
+    def test_valid_pending_to_downloading(self):
+        """Test PENDING -> DOWNLOADING is valid."""
+        from backend.models.job import STATE_TRANSITIONS
+        valid_transitions = STATE_TRANSITIONS.get(JobStatus.PENDING, [])
+        assert JobStatus.DOWNLOADING in valid_transitions
+    
+    def test_valid_downloading_to_separating(self):
+        """Test DOWNLOADING -> SEPARATING_STAGE1 is valid."""
+        from backend.models.job import STATE_TRANSITIONS
+        valid_transitions = STATE_TRANSITIONS.get(JobStatus.DOWNLOADING, [])
+        assert JobStatus.SEPARATING_STAGE1 in valid_transitions
+    
+    def test_invalid_pending_to_complete(self):
+        """Test PENDING -> COMPLETE is invalid."""
+        from backend.models.job import STATE_TRANSITIONS
+        valid_transitions = STATE_TRANSITIONS.get(JobStatus.PENDING, [])
+        assert JobStatus.COMPLETE not in valid_transitions
+    
+    def test_any_active_status_can_fail(self):
+        """Test any active (non-terminal, non-legacy) status can transition to FAILED."""
+        from backend.models.job import STATE_TRANSITIONS
+        # Terminal states and legacy states are excluded
+        excluded = [
+            JobStatus.COMPLETE, JobStatus.FAILED, JobStatus.CANCELLED,
+            # Legacy states that don't include FAILED
+            JobStatus.QUEUED, JobStatus.PROCESSING, 
+            JobStatus.READY_FOR_FINALIZATION, JobStatus.FINALIZING, JobStatus.ERROR
+        ]
+        for status in JobStatus:
+            if status not in excluded:
+                valid_transitions = STATE_TRANSITIONS.get(status, [])
+                assert JobStatus.FAILED in valid_transitions, f"{status} should be able to fail"
+    
+    def test_failed_can_transition_for_retry(self):
+        """Test FAILED status can transition to retry checkpoint states."""
+        from backend.models.job import STATE_TRANSITIONS
+        valid_transitions = STATE_TRANSITIONS.get(JobStatus.FAILED, [])
+
+        # FAILED should allow retry transitions
+        assert JobStatus.INSTRUMENTAL_SELECTED in valid_transitions, "FAILED should allow retry to INSTRUMENTAL_SELECTED"
+        assert JobStatus.REVIEW_COMPLETE in valid_transitions, "FAILED should allow retry to REVIEW_COMPLETE"
+        assert JobStatus.LYRICS_COMPLETE in valid_transitions, "FAILED should allow retry to LYRICS_COMPLETE"
+
+    def test_cancelled_can_transition_for_retry(self):
+        """Test CANCELLED status can transition to retry checkpoint states."""
+        from backend.models.job import STATE_TRANSITIONS
+        valid_transitions = STATE_TRANSITIONS.get(JobStatus.CANCELLED, [])
+
+        # CANCELLED should allow same retry transitions as FAILED
+        assert JobStatus.INSTRUMENTAL_SELECTED in valid_transitions, "CANCELLED should allow retry to INSTRUMENTAL_SELECTED"
+        assert JobStatus.REVIEW_COMPLETE in valid_transitions, "CANCELLED should allow retry to REVIEW_COMPLETE"
+        assert JobStatus.LYRICS_COMPLETE in valid_transitions, "CANCELLED should allow retry to LYRICS_COMPLETE"
+        assert JobStatus.DOWNLOADING in valid_transitions, "CANCELLED should allow retry to DOWNLOADING (restart)"
+
+    def test_failed_can_restart_from_beginning(self):
+        """Test FAILED status can transition to DOWNLOADING for restart from beginning."""
+        from backend.models.job import STATE_TRANSITIONS
+        valid_transitions = STATE_TRANSITIONS.get(JobStatus.FAILED, [])
+
+        # FAILED should allow restart from beginning
+        assert JobStatus.DOWNLOADING in valid_transitions, "FAILED should allow restart to DOWNLOADING"
+
+
+class TestJobModelSerialization:
+    """Tests for Job model serialization to/from API."""
+    
+    def test_job_to_dict(self):
+        """Test Job converts to dict correctly."""
+        job = Job(
+            job_id="test123",
+            status=JobStatus.PENDING,
+            created_at=datetime.now(UTC),
+            updated_at=datetime.now(UTC),
+            artist="Test Artist",
+            title="Test Song"
+        )
+        data = job.model_dump()
+        assert data["job_id"] == "test123"
+        assert data["status"] == "pending"
+        assert data["artist"] == "Test Artist"
+    
+    def test_job_from_dict(self):
+        """Test Job can be created from dict."""
+        data = {
+            "job_id": "test123",
+            "status": "pending",
+            "created_at": datetime.now(UTC).isoformat(),
+            "updated_at": datetime.now(UTC).isoformat(),
+            "artist": "Test",
+            "title": "Song"
+        }
+        job = Job.model_validate(data)
+        assert job.job_id == "test123"
+        assert job.status == JobStatus.PENDING
+    
+    def test_job_handles_null_optional_fields(self):
+        """Test Job handles null optional fields."""
+        job = Job(
+            job_id="test",
+            status=JobStatus.PENDING,
+            created_at=datetime.now(UTC),
+            updated_at=datetime.now(UTC)
+        )
+        assert job.artist is None
+        assert job.title is None
+        assert job.url is None
+        assert job.file_urls == {}
+
+
+class TestRetryEndpoint:
+    """Tests for the retry job endpoint."""
+
+    @pytest.fixture
+    def mock_job_manager(self):
+        """Create mock job manager."""
+        return MagicMock()
+
+    @pytest.fixture
+    def mock_worker_service(self):
+        """Create mock worker service."""
+        return MagicMock()
+
+    def test_retry_rejects_pending_job(self, mock_job_manager):
+        """Test retry endpoint rejects jobs that are not failed or cancelled."""
+        # Create a pending job
+        job = Job(
+            job_id="test123",
+            status=JobStatus.PENDING,
+            created_at=datetime.now(UTC),
+            updated_at=datetime.now(UTC),
+            artist="Test",
+            title="Song"
+        )
+        mock_job_manager.get_job.return_value = job
+
+        # The endpoint should reject this with a 400 error
+        # (status check happens before any logic)
+        assert job.status not in [JobStatus.FAILED, JobStatus.CANCELLED]
+
+    def test_retry_accepts_failed_job(self, mock_job_manager):
+        """Test retry endpoint accepts failed jobs."""
+        job = Job(
+            job_id="test123",
+            status=JobStatus.FAILED,
+            created_at=datetime.now(UTC),
+            updated_at=datetime.now(UTC),
+            artist="Test",
+            title="Song",
+            input_media_gcs_path="jobs/test123/input/audio.flac"
+        )
+        mock_job_manager.get_job.return_value = job
+
+        # Status should be accepted
+        assert job.status in [JobStatus.FAILED, JobStatus.CANCELLED]
+
+    def test_retry_accepts_cancelled_job(self, mock_job_manager):
+        """Test retry endpoint accepts cancelled jobs."""
+        job = Job(
+            job_id="test123",
+            status=JobStatus.CANCELLED,
+            created_at=datetime.now(UTC),
+            updated_at=datetime.now(UTC),
+            artist="Test",
+            title="Song",
+            input_media_gcs_path="jobs/test123/input/audio.flac"
+        )
+        mock_job_manager.get_job.return_value = job
+
+        # Status should be accepted
+        assert job.status in [JobStatus.FAILED, JobStatus.CANCELLED]
+
+    def test_retry_checkpoint_detection_video_generation(self):
+        """Test retry detects video generation checkpoint."""
+        job = Job(
+            job_id="test123",
+            status=JobStatus.FAILED,
+            created_at=datetime.now(UTC),
+            updated_at=datetime.now(UTC),
+            artist="Test",
+            title="Song",
+            file_urls={
+                'videos': {'with_vocals': 'gs://bucket/path/video.mkv'}
+            },
+            state_data={
+                'instrumental_selection': 'clean'
+            }
+        )
+
+        # This job has video and instrumental selection - should retry from video generation
+        has_video = job.file_urls.get('videos', {}).get('with_vocals')
+        has_instrumental_selection = (job.state_data or {}).get('instrumental_selection')
+        assert has_video and has_instrumental_selection
+
+    def test_retry_checkpoint_detection_render_stage(self):
+        """Test retry detects render stage checkpoint."""
+        job = Job(
+            job_id="test123",
+            status=JobStatus.FAILED,
+            created_at=datetime.now(UTC),
+            updated_at=datetime.now(UTC),
+            artist="Test",
+            title="Song",
+            file_urls={
+                'lyrics': {'corrections': 'gs://bucket/path/corrections.json'},
+                'screens': {'title': 'gs://bucket/path/title.mov'}
+            }
+        )
+
+        # This job has corrections and screens - should retry from render
+        has_corrections = job.file_urls.get('lyrics', {}).get('corrections')
+        has_screens = job.file_urls.get('screens', {}).get('title')
+        has_video = job.file_urls.get('videos', {}).get('with_vocals')
+        assert has_corrections and has_screens and not has_video
+
+    def test_retry_checkpoint_detection_from_beginning(self):
+        """Test retry detects need to restart from beginning."""
+        job = Job(
+            job_id="test123",
+            status=JobStatus.CANCELLED,
+            created_at=datetime.now(UTC),
+            updated_at=datetime.now(UTC),
+            artist="Test",
+            title="Song",
+            input_media_gcs_path="jobs/test123/input/audio.flac",
+            file_urls={}  # No progress yet
+        )
+
+        # This job has input audio but no other files - should restart from beginning
+        has_input = job.input_media_gcs_path
+        has_stems = job.file_urls.get('stems', {}).get('instrumental_clean')
+        has_corrections = job.file_urls.get('lyrics', {}).get('corrections')
+        assert has_input and not has_stems and not has_corrections
+
+    def test_retry_no_input_audio(self):
+        """Test retry fails when no input audio available."""
+        job = Job(
+            job_id="test123",
+            status=JobStatus.CANCELLED,
+            created_at=datetime.now(UTC),
+            updated_at=datetime.now(UTC),
+            artist="Test",
+            title="Song",
+            # No input_media_gcs_path and no url
+            file_urls={}
+        )
+
+        # This job has no input audio - should not be retryable
+        has_input = job.input_media_gcs_path or job.url
+        assert not has_input
+

backend/tests/test_routes_review.py

@@ -0,0 +1,337 @@
+"""
+Unit tests for review.py routes and related components.
+
+These tests verify the review-related state transitions and data structures.
+Tests that require full backend imports are in the emulator integration tests.
+"""
+import pytest
+import json
+
+
+class TestJobStatusTransitionsForReview:
+    """Tests for review-related state transitions.
+    
+    These tests verify the Job model's state machine handles review flow correctly.
+    """
+    
+    def test_awaiting_review_can_transition_to_in_review(self):
+        """Test AWAITING_REVIEW -> IN_REVIEW is valid."""
+        from backend.models.job import STATE_TRANSITIONS, JobStatus
+        valid_transitions = STATE_TRANSITIONS.get(JobStatus.AWAITING_REVIEW, [])
+        assert JobStatus.IN_REVIEW in valid_transitions
+    
+    def test_awaiting_review_can_transition_to_review_complete(self):
+        """Test AWAITING_REVIEW -> REVIEW_COMPLETE is valid (skip in_review)."""
+        from backend.models.job import STATE_TRANSITIONS, JobStatus
+        valid_transitions = STATE_TRANSITIONS.get(JobStatus.AWAITING_REVIEW, [])
+        assert JobStatus.REVIEW_COMPLETE in valid_transitions
+    
+    def test_in_review_can_transition_to_review_complete(self):
+        """Test IN_REVIEW -> REVIEW_COMPLETE is valid."""
+        from backend.models.job import STATE_TRANSITIONS, JobStatus
+        valid_transitions = STATE_TRANSITIONS.get(JobStatus.IN_REVIEW, [])
+        assert JobStatus.REVIEW_COMPLETE in valid_transitions
+    
+    def test_review_complete_transitions_to_rendering_video(self):
+        """Test REVIEW_COMPLETE -> RENDERING_VIDEO is valid."""
+        from backend.models.job import STATE_TRANSITIONS, JobStatus
+        valid_transitions = STATE_TRANSITIONS.get(JobStatus.REVIEW_COMPLETE, [])
+        assert JobStatus.RENDERING_VIDEO in valid_transitions
+    
+    def test_rendering_video_status_exists(self):
+        """Test RENDERING_VIDEO status exists in JobStatus enum."""
+        from backend.models.job import JobStatus
+        assert hasattr(JobStatus, 'RENDERING_VIDEO')
+        assert JobStatus.RENDERING_VIDEO.value == "rendering_video"
+    
+    def test_rendering_video_transitions_to_instrumental(self):
+        """Test RENDERING_VIDEO -> AWAITING_INSTRUMENTAL_SELECTION is valid."""
+        from backend.models.job import STATE_TRANSITIONS, JobStatus
+        valid_transitions = STATE_TRANSITIONS.get(JobStatus.RENDERING_VIDEO, [])
+        assert JobStatus.AWAITING_INSTRUMENTAL_SELECTION in valid_transitions
+
+
+class TestStylesConfigRequirements:
+    """Tests documenting the required fields for ASS subtitle generation.
+    
+    These tests verify that the styles config format is documented correctly.
+    The actual styles creation is tested in integration tests.
+    """
+    
+    def test_required_karaoke_fields_documented(self):
+        """Document required karaoke style fields for ASS generation."""
+        # These fields are required by the ASS subtitle generator
+        # Missing any of them will cause video generation to fail
+        required_fields = [
+            "font",        # Font name for ASS
+            "font_path",   # Path to font file (can be empty string, NOT None)
+            "ass_name",    # Style name in ASS file
+            "primary_color",    # Format: "R, G, B, A"
+            "secondary_color",  # Format: "R, G, B, A"
+            "outline_color",    # Format: "R, G, B, A"
+            "back_color",       # Format: "R, G, B, A"
+            "bold",        # Boolean
+            "italic",      # Boolean
+            "underline",   # Boolean
+            "strike_out",  # Boolean
+            "scale_x",     # Integer
+            "scale_y",     # Integer
+            "spacing",     # Integer
+            "angle",       # Float
+            "border_style", # Integer
+            "outline",     # Integer
+            "shadow",      # Integer
+            "margin_l",    # Integer
+            "margin_r",    # Integer
+            "margin_v",    # Integer
+            "encoding",    # Integer
+        ]
+        
+        # This test documents the required fields
+        # Actual validation happens in integration tests
+        assert len(required_fields) == 22
+        assert "ass_name" in required_fields  # This was missing initially
+        assert "font_path" in required_fields  # Must be string, not None
+    
+    def test_minimal_styles_structure(self):
+        """Document the minimal styles JSON structure."""
+        minimal_styles = {
+            "karaoke": {
+                "background_color": "#000000",
+                "font_path": "",  # MUST be string, NOT None
+                "font": "Noto Sans",
+                "ass_name": "Default",  # REQUIRED
+                "primary_color": "112, 112, 247, 255",
+                "secondary_color": "255, 255, 255, 255",
+                "outline_color": "26, 58, 235, 255",
+                "back_color": "0, 0, 0, 0",
+                "bold": False,
+                "italic": False,
+                "underline": False,
+                "strike_out": False,
+                "scale_x": 100,
+                "scale_y": 100,
+                "spacing": 0,
+                "angle": 0.0,
+                "border_style": 1,
+                "outline": 1,
+                "shadow": 0,
+                "margin_l": 0,
+                "margin_r": 0,
+                "margin_v": 0,
+                "encoding": 0
+            }
+        }
+        
+        # Verify structure is valid JSON
+        json_str = json.dumps(minimal_styles)
+        parsed = json.loads(json_str)
+        
+        assert "karaoke" in parsed
+        assert parsed["karaoke"]["font_path"] == ""  # Not None
+        assert parsed["karaoke"]["ass_name"] == "Default"
+
+
+class TestCorrectionDataMerging:
+    """Tests documenting correction data merging requirements.
+    
+    The LyricsTranscriber React UI sends only partial correction data:
+    - corrections
+    - corrected_segments
+    
+    The backend must merge this with the original corrections.json to
+    reconstruct a full CorrectionResult.
+    """
+    
+    def test_frontend_sends_partial_data(self):
+        """Document what the frontend sends."""
+        # The frontend sends only these fields
+        frontend_payload = {
+            "corrections": [],  # List of corrections made
+            "corrected_segments": []  # Updated segment data
+        }
+        
+        # This is NOT a full CorrectionResult
+        assert "original_segments" not in frontend_payload
+        assert "metadata" not in frontend_payload
+    
+    def test_merging_strategy(self):
+        """Document the merging strategy for corrections."""
+        # Original data has full structure
+        original_data = {
+            "original_segments": [{"id": 1, "text": "test"}],
+            "corrected_segments": [{"id": 1, "text": "test"}],
+            "corrections": [],
+            "metadata": {"artist": "Test"}
+        }
+        
+        # Frontend sends partial update
+        frontend_update = {
+            "corrections": [{"id": 1, "type": "edit"}],
+            "corrected_segments": [{"id": 1, "text": "updated"}]
+        }
+        
+        # Merging strategy: update only the fields sent by frontend
+        if 'corrections' in frontend_update:
+            original_data['corrections'] = frontend_update['corrections']
+        if 'corrected_segments' in frontend_update:
+            original_data['corrected_segments'] = frontend_update['corrected_segments']
+        
+        # Result preserves original_segments and metadata
+        assert original_data['original_segments'] == [{"id": 1, "text": "test"}]
+        assert original_data['metadata'] == {"artist": "Test"}
+        # But has updated corrections and corrected_segments
+        assert original_data['corrections'] == [{"id": 1, "type": "edit"}]
+        assert original_data['corrected_segments'] == [{"id": 1, "text": "updated"}]
+
+
+class TestAddLyricsEndpoint:
+    """Tests for the add-lyrics endpoint."""
+    
+    def test_add_lyrics_requires_source_and_lyrics(self):
+        """Document that add_lyrics expects source and lyrics fields."""
+        # The frontend sends this payload
+        valid_payload = {
+            "source": "custom",
+            "lyrics": "Line 1\nLine 2\nLine 3"
+        }
+        
+        # Both fields are required
+        assert "source" in valid_payload
+        assert "lyrics" in valid_payload
+        assert len(valid_payload["source"].strip()) > 0
+        assert len(valid_payload["lyrics"].strip()) > 0
+    
+    def test_add_lyrics_uses_correction_operations(self):
+        """Verify CorrectionOperations.add_lyrics_source is available."""
+        from lyrics_transcriber.correction.operations import CorrectionOperations
+        
+        # The method should exist
+        assert hasattr(CorrectionOperations, 'add_lyrics_source')
+        
+        # It should be a static method
+        import inspect
+        # Get the method and check it's callable
+        method = getattr(CorrectionOperations, 'add_lyrics_source')
+        assert callable(method)
+
+
+class TestPreviewStyleLoading:
+    """Tests for the unified style loader used in preview video generation.
+    
+    When a job has custom styles (uploaded via --style_params_json), these
+    must be loaded and applied to preview videos, not just the final render.
+    
+    This was a bug: preview videos were using minimal styles (black background)
+    even when the job had custom backgrounds and fonts configured.
+    
+    The style loading logic is now consolidated in karaoke_gen.style_loader
+    to avoid duplication between workers and API routes.
+    """
+    
+    def test_load_styles_from_gcs_with_custom_styles(self, tmp_path):
+        """Test that custom styles are downloaded and applied for preview."""
+        import os
+        from karaoke_gen.style_loader import load_styles_from_gcs
+        
+        # Create source style params file
+        source_style_params = tmp_path / "source_styles.json"
+        style_data = {
+            "karaoke": {
+                "background_image": "/original/path/background.png",
+                "font_path": "/original/path/font.ttf",
+                "background_color": "#000000",
+                "font": "Noto Sans",
+                "ass_name": "Default",
+            }
+        }
+        source_style_params.write_text(json.dumps(style_data))
+        
+        # Create source asset files
+        source_background = tmp_path / "background.png"
+        source_background.write_bytes(b"PNG image data")
+        source_font = tmp_path / "font.ttf"
+        source_font.write_bytes(b"TTF font data")
+        
+        # Create mock download function that simulates GCS download
+        def mock_download(gcs_path, local_path):
+            if "style_params.json" in gcs_path:
+                with open(local_path, 'w') as f:
+                    f.write(source_style_params.read_text())
+            elif "karaoke_background" in gcs_path:
+                with open(local_path, 'wb') as f:
+                    f.write(source_background.read_bytes())
+            elif "font.ttf" in gcs_path:
+                with open(local_path, 'wb') as f:
+                    f.write(source_font.read_bytes())
+        
+        # Call the unified style loader function
+        style_assets = {
+            "style_params": "uploads/test123/style/style_params.json",
+            "karaoke_background": "uploads/test123/style/karaoke_background.png",
+            "font": "uploads/test123/style/font.ttf",
+        }
+        
+        styles_path, result_styles = load_styles_from_gcs(
+            style_params_gcs_path="uploads/test123/style/style_params.json",
+            style_assets=style_assets,
+            temp_dir=str(tmp_path / "workdir"),
+            download_func=mock_download,
+        )
+        
+        # Verify styles file was created
+        assert os.path.exists(styles_path)
+        
+        # The paths should now point to the local downloaded files, not the original paths
+        assert "karaoke" in result_styles
+        assert result_styles["karaoke"]["background_image"] != "/original/path/background.png"
+        assert "karaoke_background.png" in result_styles["karaoke"]["background_image"]
+        assert result_styles["karaoke"]["font_path"] != "/original/path/font.ttf"
+        assert "font.ttf" in result_styles["karaoke"]["font_path"]
+    
+    def test_load_styles_from_gcs_falls_back_to_minimal(self, tmp_path):
+        """Test that minimal styles are used when job has no custom styles."""
+        import os
+        from karaoke_gen.style_loader import load_styles_from_gcs
+        
+        # Call with no custom styles
+        styles_path, result_styles = load_styles_from_gcs(
+            style_params_gcs_path=None,  # No custom styles
+            style_assets={},
+            temp_dir=str(tmp_path),
+            download_func=lambda gcs_path, local_path: None,  # Won't be called
+        )
+        
+        # Verify styles file was created
+        assert os.path.exists(styles_path)
+        
+        # Should have karaoke section with minimal/default values
+        assert "karaoke" in result_styles
+        assert result_styles["karaoke"]["background_color"] == "#000000"
+        assert result_styles["karaoke"]["font"] == "Noto Sans"
+        # Minimal styles have background_image as None (default)
+        assert result_styles["karaoke"].get("background_image") is None
+    
+    def test_asset_mapping_is_complete(self):
+        """Verify all required asset mappings are defined in the unified style loader."""
+        from karaoke_gen.style_loader import ASSET_KEY_MAPPINGS
+        
+        # These mappings must be present for styles to work correctly
+        required_keys = [
+            "karaoke_background",
+            "intro_background",
+            "end_background",
+            "font",
+        ]
+        
+        for key in required_keys:
+            assert key in ASSET_KEY_MAPPINGS, f"Asset mapping '{key}' not found in ASSET_KEY_MAPPINGS"
+        
+        # Verify karaoke_background maps to the correct path
+        karaoke_mapping = ASSET_KEY_MAPPINGS["karaoke_background"]
+        assert karaoke_mapping == ("karaoke", "background_image")
+        
+        # Verify font maps to multiple sections
+        font_mappings = ASSET_KEY_MAPPINGS["font"]
+        assert isinstance(font_mappings, list)
+        assert ("karaoke", "font_path") in font_mappings