From 591c0505459423bf5a56bdc764a626efaba1c14e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andrew=20Beveridge=20=E2=98=84=EF=B8=8F?= Date: Sun, 29 Mar 2026 20:25:47 -0400 Subject: [PATCH] feat: Reference lyrics search with relevance filtering (#632) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Summary - Add relevance filtering to the correction pipeline — automatically rejects wrong-song reference lyrics (below 30% word match threshold, validated against 168 prod source pairs) - New `POST /api/review/{job_id}/search-lyrics` endpoint lets users search with alternate artist/title from the review UI, with force-add override for edge cases - Redesigned Add Reference Lyrics modal with Search (default) and Paste tabs, plus inline empty state when no valid sources exist ## Changes ### Backend - **Relevance filtering** (`correction/relevance.py`): Per-source scoring based on anchor sequence word coverage. Integrated into `LyricsCorrector.run()` after anchor finding — sources below threshold removed before corrections computed - **Search endpoint** (`routes/review.py`): Queries all providers (Genius, Spotify, Musixmatch, LRCLIB) with user-supplied artist/title, auto-filters results, returns added/rejected/not-found breakdown - **Provider factory** (`operations.py`): `create_lyrics_providers()` reads env vars, `search_lyrics_sources()` orchestrates fetch+filter+correct - **Force override**: `add-lyrics` and `search-lyrics` support `force` flag to bypass threshold ### Frontend - **Tabbed modal**: `AddLyricsModal` rewritten with Search (default) and Paste tabs - **SearchLyricsTab**: Artist/title inputs, provider search, rejected source cards with force-add checkboxes - **ReferenceEmptyState**: Inline search/paste UI when no valid reference sources exist - **API client**: New `searchLyrics()` method with `SearchLyricsResponse` types ### Analysis - Empirical threshold analysis script (`scripts/analyze_reference_relevance.py`) + visual review tool - 168 source pairs from 81 prod jobs: wrong-song max 3.5%, correct-song min 26.8% → 30% threshold ## Testing - 35 new backend tests (relevance scoring, filtering, corrector integration, search operation, API endpoint) - 717 existing frontend tests passing (no regressions) - Edge case: all sources filtered out handled gracefully ## Review - [x] Local CodeRabbit review completed (3 issues fixed: response contract, force param coercion, null checks) @coderabbitai ignore --- 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.6 (1M context) --- .gitignore | 1 + backend/api/routes/review.py | 156 +- backend/tests/test_search_lyrics.py | 551 +++++ docs/API.md | 55 + docs/LESSONS-LEARNED.md | 8 + .../2026-03-29-reference-lyrics-search.md | 1924 +++++++++++++++++ ...26-03-29-reference-lyrics-search-design.md | 165 ++ .../lyrics-review/LyricsAnalyzer.tsx | 24 + .../lyrics-review/ReferenceEmptyState.tsx | 61 + .../lyrics-review/ReferenceView.tsx | 14 + .../lyrics-review/modals/AddLyricsModal.tsx | 119 +- .../lyrics-review/modals/PasteLyricsTab.tsx | 101 + .../lyrics-review/modals/SearchLyricsTab.tsx | 216 ++ .../components/lyrics-review/modals/index.ts | 2 + frontend/lib/api.ts | 22 +- frontend/lib/lyrics-review/types.ts | 23 + .../correction/corrector.py | 46 +- .../correction/operations.py | 245 ++- .../correction/relevance.py | 112 + pyproject.toml | 2 +- scripts/analyze_reference_relevance.py | 369 ++++ scripts/relevance_review_results.json | 1519 +++++++++++++ scripts/review_reference_relevance.py | 1198 ++++++++++ tests/correction/__init__.py | 0 tests/correction/test_relevance.py | 257 +++ 25 files changed, 7093 insertions(+), 97 deletions(-) create mode 100644 backend/tests/test_search_lyrics.py create mode 100644 docs/superpowers/plans/2026-03-29-reference-lyrics-search.md create mode 100644 docs/superpowers/specs/2026-03-29-reference-lyrics-search-design.md create mode 100644 frontend/components/lyrics-review/ReferenceEmptyState.tsx create mode 100644 frontend/components/lyrics-review/modals/PasteLyricsTab.tsx create mode 100644 frontend/components/lyrics-review/modals/SearchLyricsTab.tsx create mode 100644 karaoke_gen/lyrics_transcriber/correction/relevance.py create mode 100755 scripts/analyze_reference_relevance.py create mode 100644 scripts/relevance_review_results.json create mode 100755 scripts/review_reference_relevance.py create mode 100644 tests/correction/__init__.py create mode 100644 tests/correction/test_relevance.py diff --git a/.gitignore b/.gitignore index 28f7a669..ac2cb021 100644 --- a/.gitignore +++ b/.gitignore @@ -232,3 +232,4 @@ flacfetch # Test output directories Rick Astley*/ +.superpowers/ diff --git a/backend/api/routes/review.py b/backend/api/routes/review.py index d4e1c3cc..8e0c827d 100644 --- a/backend/api/routes/review.py +++ b/backend/api/routes/review.py @@ -19,7 +19,7 @@ import json import os import tempfile from pathlib import Path -from typing import Dict, Any, Set, Tuple +from typing import Dict, Any, List, Optional, Set, Tuple from fastapi import APIRouter, HTTPException, Request, Depends from fastapi.responses import FileResponse, RedirectResponse, StreamingResponse @@ -427,8 +427,10 @@ async def add_lyrics( source = data.get("source", "").strip() lyrics_text = data.get("lyrics", "").strip() - - logger.info(f"Job {job_id}: Adding lyrics source '{source}' with {len(lyrics_text)} characters") + raw_force = data.get("force", False) + force = raw_force if isinstance(raw_force, bool) else str(raw_force).lower() == "true" + + logger.info(f"Job {job_id}: Adding lyrics source '{source}' with {len(lyrics_text)} characters (force={force})") # Use tracing and job_log_context for full observability with create_span("add-lyrics", {"job_id": job_id, "source": source, "lyrics_length": len(lyrics_text)}) as span: @@ -465,7 +467,8 @@ async def add_lyrics( source=source, lyrics_text=lyrics_text, cache_dir=cache_dir, - logger=logger + logger=logger, + force=force, ) add_span_event("correction_complete", { "new_segments": len(updated_result.corrected_segments) if updated_result.corrected_segments else 0, @@ -501,6 +504,151 @@ async def add_lyrics( raise HTTPException(status_code=500, detail=f"Failed to add lyrics: {str(e)}") +@router.post("/{job_id}/search-lyrics") +async def search_lyrics( + job_id: str, + data: Dict[str, Any], + auth_info: Tuple[str, str] = Depends(require_review_auth) +): + """ + Search for lyrics using an alternate artist/title and rerun correction. + + Queries all configured lyrics providers (Genius, Spotify, Musixmatch, LRCLIB) + with the supplied artist and title, then runs the correction pipeline (which + includes the relevance filter). Sources that pass the filter are added to the + job's corrections.json and returned to the frontend. + + Request body: + artist (str): Artist name to search. + title (str): Song title to search. + force_sources (list[str], optional): Provider names whose results should + bypass the relevance filter. + + Response: + 200 {"status": "success", "data": {...CorrectionData...}, "sources_added": [...], + "sources_rejected": {...}, "sources_not_found": [...]} + 200 {"status": "no_results", "message": "...", "sources_rejected": {...}, + "sources_not_found": [...]} + 400 on invalid request / wrong job state + 500 on internal error + """ + job_manager = JobManager() + storage = StorageService() + + job = job_manager.get_job(job_id) + if not job: + raise HTTPException(status_code=404, detail="Job not found") + + if job.status not in [JobStatus.AWAITING_REVIEW, JobStatus.IN_REVIEW]: + raise HTTPException( + status_code=400, + detail=f"Job not in review state (current status: {job.status})" + ) + + artist = (data.get("artist") or "").strip() + title = (data.get("title") or "").strip() + force_sources: List[str] = data.get("force_sources") or [] + + if not artist or not title: + raise HTTPException(status_code=400, detail="artist and title are required") + + logger.info(f"Job {job_id}: Searching lyrics for '{artist}' - '{title}' (force={force_sources})") + + with create_span("search-lyrics", {"job_id": job_id, "artist": artist, "title": title}) as span: + with job_log_context(job_id, worker="search-lyrics"): + try: + with tempfile.TemporaryDirectory() as temp_dir: + # Download current corrections.json + with create_span("download-corrections") as download_span: + corrections_gcs = f"jobs/{job_id}/lyrics/corrections.json" + corrections_path = os.path.join(temp_dir, "corrections.json") + storage.download_file(corrections_gcs, corrections_path) + download_span.set_attribute("gcs_path", corrections_gcs) + + with open(corrections_path, "r", encoding="utf-8") as f: + original_data = json.load(f) + + correction_result = CorrectionResult.from_dict(original_data) + add_span_event("corrections_loaded", { + "segments": len(correction_result.corrected_segments) if correction_result.corrected_segments else 0, + "reference_sources": len(correction_result.reference_lyrics) if correction_result.reference_lyrics else 0, + }) + + cache_dir = os.path.join(temp_dir, "cache") + os.makedirs(cache_dir, exist_ok=True) + + with create_span("correction-operations-search-lyrics") as correction_span: + correction_span.set_attribute("artist", artist) + correction_span.set_attribute("title", title) + search_result = CorrectionOperations.search_lyrics_sources( + correction_result=correction_result, + artist=artist, + title=title, + cache_dir=cache_dir, + force_sources=force_sources, + logger=logger, + ) + + sources_added = search_result["sources_added"] + sources_rejected = search_result["sources_rejected"] + sources_not_found = search_result["sources_not_found"] + updated_result = search_result["updated_result"] + + if not sources_added or updated_result is None: + logger.info( + f"Job {job_id}: No valid lyrics found via search " + f"(rejected={list(sources_rejected.keys())}, not_found={sources_not_found})" + ) + span.set_attribute("success", False) + return { + "status": "no_results", + "message": "No matching lyrics found from any provider", + "sources_added": [], + "sources_rejected": sources_rejected, + "sources_not_found": sources_not_found, + } + + # Add audio hash / job metadata for the frontend + audio_hash = _get_audio_hash(job_id) + if not updated_result.metadata: + updated_result.metadata = {} + updated_result.metadata["audio_hash"] = audio_hash + updated_result.metadata["artist"] = job.artist + updated_result.metadata["title"] = job.title + + # Upload updated corrections back to GCS + with create_span("upload-corrections") as upload_span: + updated_data = updated_result.to_dict() + storage.upload_json(corrections_gcs, updated_data) + upload_span.set_attribute("gcs_path", corrections_gcs) + + logger.info( + f"Job {job_id}: Search complete — added={sources_added}, " + f"rejected={list(sources_rejected.keys())}, not_found={sources_not_found}" + ) + span.set_attribute("success", True) + span.set_attribute("sources_added", len(sources_added)) + + return { + "status": "success", + "data": updated_data, + "sources_added": sources_added, + "sources_rejected": sources_rejected, + "sources_not_found": sources_not_found, + } + + except HTTPException: + raise + except ValueError as e: + logger.warning(f"Job {job_id}: Invalid search lyrics request: {e}") + span.set_attribute("error", str(e)) + raise HTTPException(status_code=400, detail=str(e)) + except Exception as e: + logger.error(f"Job {job_id}: Failed to search lyrics: {e}", exc_info=True) + span.set_attribute("error", str(e)) + raise HTTPException(status_code=500, detail=f"Failed to search lyrics: {str(e)}") + + @router.post("/{job_id}/preview-video") async def generate_preview_video( job_id: str, diff --git a/backend/tests/test_search_lyrics.py b/backend/tests/test_search_lyrics.py new file mode 100644 index 00000000..9040b304 --- /dev/null +++ b/backend/tests/test_search_lyrics.py @@ -0,0 +1,551 @@ +""" +Tests for the search-lyrics operation and API endpoint. + +Covers: +- create_lyrics_providers() factory function +- CorrectionOperations.search_lyrics_sources() static method +- CorrectionOperations.add_lyrics_source() force parameter +- POST /{job_id}/search-lyrics API endpoint +""" +import pytest +import os +from unittest.mock import MagicMock, patch, call +from typing import Dict, Any, List + + +# --------------------------------------------------------------------------- +# Helpers / fixtures +# --------------------------------------------------------------------------- + +def _make_lyrics_data(source: str = "TestSource", text: str = "Hello world\nTest line") -> "LyricsData": + """Create a minimal LyricsData object for testing.""" + from karaoke_gen.lyrics_transcriber.types import LyricsData, LyricsSegment, LyricsMetadata, Word + from karaoke_gen.lyrics_transcriber.utils.word_utils import WordUtils + + segments = [] + for line in text.strip().splitlines(): + words = [ + Word(id=WordUtils.generate_id(), text=w, start_time=None, end_time=None) + for w in line.split() + ] + segments.append( + LyricsSegment( + id=WordUtils.generate_id(), + text=line, + words=words, + start_time=None, + end_time=None, + ) + ) + return LyricsData(source=source, segments=segments, metadata=LyricsMetadata(source=source, track_name="Test Track", artist_names="Test Artist")) + + +def _make_correction_result( + reference_lyrics: Dict = None, + metadata: Dict = None, +) -> "CorrectionResult": + """Create a minimal CorrectionResult for testing.""" + from karaoke_gen.lyrics_transcriber.types import ( + CorrectionResult, LyricsSegment, Word, LyricsData, LyricsMetadata + ) + from karaoke_gen.lyrics_transcriber.utils.word_utils import WordUtils + + # A single transcription segment + word = Word(id=WordUtils.generate_id(), text="hello", start_time=0.0, end_time=0.5) + segment = LyricsSegment(id=WordUtils.generate_id(), text="hello", words=[word], start_time=0.0, end_time=0.5) + + return CorrectionResult( + original_segments=[segment], + corrected_segments=[segment], + corrections=[], + corrections_made=0, + confidence=1.0, + reference_lyrics=reference_lyrics or {}, + anchor_sequences=[], + gap_sequences=[], + resized_segments=None, + metadata=metadata or {"audio_hash": "testhash"}, + correction_steps=[], + word_id_map={}, + segment_id_map={}, + ) + + +# --------------------------------------------------------------------------- +# Tests: create_lyrics_providers factory +# --------------------------------------------------------------------------- + +class TestCreateLyricsProviders: + """Tests for the create_lyrics_providers() module-level factory.""" + + def test_returns_list(self): + """Factory always returns a list.""" + from karaoke_gen.lyrics_transcriber.correction.operations import create_lyrics_providers + with patch.dict(os.environ, {}, clear=False): + # Remove API keys so only LRCLIB is created + env_override = { + k: "" for k in ["GENIUS_API_KEY", "RAPIDAPI_KEY", "SPOTIFY_COOKIE_SP_DC"] + } + with patch.dict(os.environ, env_override): + providers = create_lyrics_providers(cache_dir="/tmp") + assert isinstance(providers, list) + + def test_lrclib_always_included(self): + """LRCLIBProvider is always included regardless of env vars.""" + from karaoke_gen.lyrics_transcriber.correction.operations import create_lyrics_providers + with patch.dict(os.environ, {"GENIUS_API_KEY": "", "RAPIDAPI_KEY": "", "SPOTIFY_COOKIE_SP_DC": ""}): + providers = create_lyrics_providers(cache_dir="/tmp") + provider_names = [p.get_name() for p in providers] + assert "LRCLIB" in provider_names + + def test_genius_included_when_genius_key_set(self): + """GeniusProvider is included when GENIUS_API_KEY is set.""" + from karaoke_gen.lyrics_transcriber.correction.operations import create_lyrics_providers + with patch.dict(os.environ, {"GENIUS_API_KEY": "fake-key", "RAPIDAPI_KEY": "", "SPOTIFY_COOKIE_SP_DC": ""}): + providers = create_lyrics_providers(cache_dir="/tmp") + provider_names = [p.get_name() for p in providers] + assert "Genius" in provider_names + + def test_genius_included_when_rapidapi_key_set(self): + """GeniusProvider is included when RAPIDAPI_KEY is set (uses RapidAPI path).""" + from karaoke_gen.lyrics_transcriber.correction.operations import create_lyrics_providers + with patch.dict(os.environ, {"GENIUS_API_KEY": "", "RAPIDAPI_KEY": "fake-rapidapi", "SPOTIFY_COOKIE_SP_DC": ""}): + providers = create_lyrics_providers(cache_dir="/tmp") + provider_names = [p.get_name() for p in providers] + assert "Genius" in provider_names + + def test_spotify_included_when_cookie_set(self): + """SpotifyProvider is included when SPOTIFY_COOKIE_SP_DC is set.""" + from karaoke_gen.lyrics_transcriber.correction.operations import create_lyrics_providers + with patch.dict(os.environ, {"GENIUS_API_KEY": "", "RAPIDAPI_KEY": "", "SPOTIFY_COOKIE_SP_DC": "fake-cookie"}): + providers = create_lyrics_providers(cache_dir="/tmp") + provider_names = [p.get_name() for p in providers] + assert "Spotify" in provider_names + + def test_musixmatch_included_when_rapidapi_key_set(self): + """MusixmatchProvider is included when RAPIDAPI_KEY is set.""" + from karaoke_gen.lyrics_transcriber.correction.operations import create_lyrics_providers + with patch.dict(os.environ, {"GENIUS_API_KEY": "", "RAPIDAPI_KEY": "fake-rapidapi", "SPOTIFY_COOKIE_SP_DC": ""}): + providers = create_lyrics_providers(cache_dir="/tmp") + provider_names = [p.get_name() for p in providers] + assert "Musixmatch" in provider_names + + def test_genius_not_included_without_keys(self): + """GeniusProvider is excluded when neither key is set.""" + from karaoke_gen.lyrics_transcriber.correction.operations import create_lyrics_providers + with patch.dict(os.environ, {"GENIUS_API_KEY": "", "RAPIDAPI_KEY": "", "SPOTIFY_COOKIE_SP_DC": ""}): + providers = create_lyrics_providers(cache_dir="/tmp") + provider_names = [p.get_name() for p in providers] + assert "Genius" not in provider_names + + def test_all_providers_when_all_keys_set(self): + """All four providers are returned when all credentials are set.""" + from karaoke_gen.lyrics_transcriber.correction.operations import create_lyrics_providers + with patch.dict(os.environ, { + "GENIUS_API_KEY": "gk", + "RAPIDAPI_KEY": "rk", + "SPOTIFY_COOKIE_SP_DC": "sc", + }): + providers = create_lyrics_providers(cache_dir="/tmp") + provider_names = [p.get_name() for p in providers] + assert "Genius" in provider_names + assert "Spotify" in provider_names + assert "Musixmatch" in provider_names + assert "LRCLIB" in provider_names + assert len(providers) == 4 + + +# --------------------------------------------------------------------------- +# Tests: CorrectionOperations.search_lyrics_sources +# --------------------------------------------------------------------------- + +class TestSearchLyricsSources: + """Tests for CorrectionOperations.search_lyrics_sources().""" + + def _mock_provider(self, name: str, lyrics_data=None): + """Build a mock BaseLyricsProvider that returns lyrics_data.""" + mock = MagicMock() + mock.get_name.return_value = name + mock.fetch_lyrics.return_value = lyrics_data + return mock + + def test_returns_dict_with_expected_keys(self): + """Return value always contains all four expected keys.""" + from karaoke_gen.lyrics_transcriber.correction.operations import CorrectionOperations + + correction_result = _make_correction_result() + + with patch("karaoke_gen.lyrics_transcriber.correction.operations.create_lyrics_providers") as mock_factory: + mock_factory.return_value = [] # No providers — simulates empty env + result = CorrectionOperations.search_lyrics_sources( + correction_result=correction_result, + artist="Artist", + title="Title", + cache_dir="/tmp", + ) + + assert "updated_result" in result + assert "sources_added" in result + assert "sources_rejected" in result + assert "sources_not_found" in result + + def test_no_providers_returns_no_results(self): + """When no providers are available, returns no results.""" + from karaoke_gen.lyrics_transcriber.correction.operations import CorrectionOperations + + correction_result = _make_correction_result() + + with patch("karaoke_gen.lyrics_transcriber.correction.operations.create_lyrics_providers") as mock_factory: + mock_factory.return_value = [] + result = CorrectionOperations.search_lyrics_sources( + correction_result=correction_result, + artist="Artist", + title="Title", + cache_dir="/tmp", + ) + + assert result["updated_result"] is None + assert result["sources_added"] == [] + + def test_provider_not_found_appended_to_not_found(self): + """Provider returning None is recorded in sources_not_found.""" + from karaoke_gen.lyrics_transcriber.correction.operations import CorrectionOperations + + correction_result = _make_correction_result() + mock_provider = self._mock_provider("LRCLIB", lyrics_data=None) + + with patch("karaoke_gen.lyrics_transcriber.correction.operations.create_lyrics_providers") as mock_factory: + mock_factory.return_value = [mock_provider] + result = CorrectionOperations.search_lyrics_sources( + correction_result=correction_result, + artist="Artist", + title="Title", + cache_dir="/tmp", + ) + + assert "LRCLIB" in result["sources_not_found"] + assert result["updated_result"] is None + + def test_provider_exception_appended_to_not_found(self): + """Provider raising an exception is recorded in sources_not_found.""" + from karaoke_gen.lyrics_transcriber.correction.operations import CorrectionOperations + + correction_result = _make_correction_result() + mock_provider = self._mock_provider("Genius") + mock_provider.fetch_lyrics.side_effect = RuntimeError("network error") + + with patch("karaoke_gen.lyrics_transcriber.correction.operations.create_lyrics_providers") as mock_factory: + mock_factory.return_value = [mock_provider] + result = CorrectionOperations.search_lyrics_sources( + correction_result=correction_result, + artist="Artist", + title="Title", + cache_dir="/tmp", + ) + + assert "Genius" in result["sources_not_found"] + + def test_existing_source_skipped(self): + """Provider whose name is already in reference_lyrics is skipped.""" + from karaoke_gen.lyrics_transcriber.correction.operations import CorrectionOperations + + existing_lyrics = {"Genius": _make_lyrics_data("Genius")} + correction_result = _make_correction_result(reference_lyrics=existing_lyrics) + mock_provider = self._mock_provider("Genius", lyrics_data=_make_lyrics_data("Genius")) + + with patch("karaoke_gen.lyrics_transcriber.correction.operations.create_lyrics_providers") as mock_factory: + mock_factory.return_value = [mock_provider] + result = CorrectionOperations.search_lyrics_sources( + correction_result=correction_result, + artist="Artist", + title="Title", + cache_dir="/tmp", + ) + + # fetch_lyrics should NOT have been called + mock_provider.fetch_lyrics.assert_not_called() + assert result["updated_result"] is None # Nothing new to add + + def test_lyrics_found_runs_corrector(self): + """When lyrics are found, LyricsCorrector.run is called.""" + from karaoke_gen.lyrics_transcriber.correction.operations import CorrectionOperations + + correction_result = _make_correction_result() + lyrics_data = _make_lyrics_data("LRCLIB") + mock_provider = self._mock_provider("LRCLIB", lyrics_data=lyrics_data) + + mock_corrector = MagicMock() + mock_corrector.all_handlers = [] + mock_corrector.handlers = [] + mock_updated = _make_correction_result(metadata={"audio_hash": "testhash"}) + mock_corrector.run.return_value = mock_updated + + with patch("karaoke_gen.lyrics_transcriber.correction.operations.create_lyrics_providers") as mock_factory, \ + patch("karaoke_gen.lyrics_transcriber.correction.operations.LyricsCorrector") as MockCorrector: + mock_factory.return_value = [mock_provider] + MockCorrector.return_value = mock_corrector + result = CorrectionOperations.search_lyrics_sources( + correction_result=correction_result, + artist="Artist", + title="Title", + cache_dir="/tmp", + ) + + assert mock_corrector.run.called + + def test_force_sources_bypass_rejection(self): + """Sources in force_sources are added even if the corrector rejects them.""" + from karaoke_gen.lyrics_transcriber.correction.operations import CorrectionOperations + + correction_result = _make_correction_result() + lyrics_data = _make_lyrics_data("Genius") + mock_provider = self._mock_provider("Genius", lyrics_data=lyrics_data) + + # Corrector result that puts "Genius" in rejected_sources + mock_corrector = MagicMock() + mock_corrector.all_handlers = [] + mock_corrector.handlers = [] + mock_updated = _make_correction_result( + reference_lyrics={}, # Corrector filtered it out + metadata={ + "audio_hash": "testhash", + "rejected_sources": { + "Genius": {"relevance": 0.0, "matched_words": 0, "total_words": 10, + "track_name": "", "artist_names": ""}, + }, + } + ) + mock_corrector.run.return_value = mock_updated + + with patch("karaoke_gen.lyrics_transcriber.correction.operations.create_lyrics_providers") as mock_factory, \ + patch("karaoke_gen.lyrics_transcriber.correction.operations.LyricsCorrector") as MockCorrector: + mock_factory.return_value = [mock_provider] + MockCorrector.return_value = mock_corrector + + result = CorrectionOperations.search_lyrics_sources( + correction_result=correction_result, + artist="Artist", + title="Title", + cache_dir="/tmp", + force_sources=["Genius"], + ) + + # The forced source should be in sources_added, not rejected + assert "Genius" in result["sources_added"] + assert "Genius" not in result["sources_rejected"] + # And it should have been re-added to reference_lyrics + assert "Genius" in result["updated_result"].reference_lyrics + + def test_audio_hash_preserved(self): + """The audio_hash from the original correction_result is preserved.""" + from karaoke_gen.lyrics_transcriber.correction.operations import CorrectionOperations + + original_hash = "original-audio-hash-abc" + correction_result = _make_correction_result(metadata={"audio_hash": original_hash}) + lyrics_data = _make_lyrics_data("LRCLIB") + mock_provider = self._mock_provider("LRCLIB", lyrics_data=lyrics_data) + + mock_corrector = MagicMock() + mock_corrector.all_handlers = [] + mock_corrector.handlers = [] + mock_updated = _make_correction_result(metadata={}) # metadata without audio_hash + mock_corrector.run.return_value = mock_updated + + with patch("karaoke_gen.lyrics_transcriber.correction.operations.create_lyrics_providers") as mock_factory, \ + patch("karaoke_gen.lyrics_transcriber.correction.operations.LyricsCorrector") as MockCorrector: + mock_factory.return_value = [mock_provider] + MockCorrector.return_value = mock_corrector + result = CorrectionOperations.search_lyrics_sources( + correction_result=correction_result, + artist="Artist", + title="Title", + cache_dir="/tmp", + ) + + if result["updated_result"] is not None: + assert result["updated_result"].metadata.get("audio_hash") == original_hash + + +# --------------------------------------------------------------------------- +# Tests: CorrectionOperations.add_lyrics_source force parameter +# --------------------------------------------------------------------------- + +class TestAddLyricsSourceForce: + """Tests for the force parameter added to add_lyrics_source.""" + + def test_force_false_does_not_override_rejection(self): + """With force=False (default), rejected sources remain rejected.""" + from karaoke_gen.lyrics_transcriber.correction.operations import CorrectionOperations + + correction_result = _make_correction_result() + + mock_corrector = MagicMock() + mock_corrector.all_handlers = [] + mock_corrector.handlers = [] + mock_updated = _make_correction_result( + reference_lyrics={}, # source was filtered out + metadata={ + "audio_hash": "testhash", + "rejected_sources": { + "custom": {"relevance": 0.0, "matched_words": 0, "total_words": 5, + "track_name": "", "artist_names": ""}, + }, + } + ) + mock_corrector.run.return_value = mock_updated + + with patch("karaoke_gen.lyrics_transcriber.correction.operations.LyricsCorrector") as MockCorrector: + MockCorrector.return_value = mock_corrector + result = CorrectionOperations.add_lyrics_source( + correction_result=correction_result, + source="custom", + lyrics_text="Hello world\nTest line", + cache_dir="/tmp", + force=False, + ) + + # Source should NOT be in reference_lyrics when force=False + assert "custom" not in result.reference_lyrics + + def test_force_true_adds_source_even_if_rejected(self): + """With force=True, source is added back even if the corrector rejected it.""" + from karaoke_gen.lyrics_transcriber.correction.operations import CorrectionOperations + + correction_result = _make_correction_result() + + mock_corrector = MagicMock() + mock_corrector.all_handlers = [] + mock_corrector.handlers = [] + mock_updated = _make_correction_result( + reference_lyrics={}, # source was filtered out + metadata={ + "audio_hash": "testhash", + "rejected_sources": { + "custom": {"relevance": 0.0, "matched_words": 0, "total_words": 5, + "track_name": "", "artist_names": ""}, + }, + } + ) + mock_corrector.run.return_value = mock_updated + + with patch("karaoke_gen.lyrics_transcriber.correction.operations.LyricsCorrector") as MockCorrector: + MockCorrector.return_value = mock_corrector + result = CorrectionOperations.add_lyrics_source( + correction_result=correction_result, + source="custom", + lyrics_text="Hello world\nTest line", + cache_dir="/tmp", + force=True, + ) + + # Source SHOULD be in reference_lyrics when force=True + assert "custom" in result.reference_lyrics + + def test_force_true_no_op_when_source_not_rejected(self): + """With force=True but source wasn't rejected, nothing extra happens.""" + from karaoke_gen.lyrics_transcriber.correction.operations import CorrectionOperations + + correction_result = _make_correction_result() + + mock_corrector = MagicMock() + mock_corrector.all_handlers = [] + mock_corrector.handlers = [] + # Source is accepted (not in rejected_sources) + mock_updated = _make_correction_result( + reference_lyrics={"custom": _make_lyrics_data("custom")}, + metadata={"audio_hash": "testhash"}, + ) + mock_corrector.run.return_value = mock_updated + + with patch("karaoke_gen.lyrics_transcriber.correction.operations.LyricsCorrector") as MockCorrector: + MockCorrector.return_value = mock_corrector + result = CorrectionOperations.add_lyrics_source( + correction_result=correction_result, + source="custom", + lyrics_text="Hello world\nTest line", + cache_dir="/tmp", + force=True, + ) + + # Source remains in reference_lyrics normally + assert "custom" in result.reference_lyrics + + +# --------------------------------------------------------------------------- +# Tests: POST /{job_id}/search-lyrics API endpoint +# --------------------------------------------------------------------------- + +class TestSearchLyricsEndpoint: + """Tests for the POST /{job_id}/search-lyrics API endpoint.""" + + def test_endpoint_exists(self): + """Verify the search-lyrics endpoint is registered in the router.""" + from backend.api.routes.review import router + paths = [route.path for route in router.routes] + assert any("search-lyrics" in p for p in paths), f"search-lyrics not found in: {paths}" + + def test_search_lyrics_requires_artist_and_title(self): + """Document that the endpoint requires artist and title fields.""" + valid_payload = { + "artist": "The Beatles", + "title": "Hey Jude", + } + assert "artist" in valid_payload + assert "title" in valid_payload + assert valid_payload["artist"].strip() + assert valid_payload["title"].strip() + + def test_search_lyrics_accepts_force_sources(self): + """Document that force_sources is an optional list of provider names.""" + payload_with_force = { + "artist": "The Beatles", + "title": "Hey Jude", + "force_sources": ["Genius", "LRCLIB"], + } + assert isinstance(payload_with_force["force_sources"], list) + + def test_success_response_format(self): + """Document the expected success response format.""" + example_success_response = { + "status": "success", + "data": {}, # CorrectionData dict + "sources_added": ["LRCLIB"], + "sources_rejected": {"Genius": {"relevance": 0.1}}, + "sources_not_found": ["Spotify"], + } + assert example_success_response["status"] == "success" + assert "data" in example_success_response + assert "sources_added" in example_success_response + assert "sources_rejected" in example_success_response + assert "sources_not_found" in example_success_response + + def test_no_results_response_format(self): + """Document the expected no_results response format.""" + example_no_results_response = { + "status": "no_results", + "message": "No matching lyrics found from any provider", + "sources_rejected": {}, + "sources_not_found": ["Genius", "LRCLIB"], + } + assert example_no_results_response["status"] == "no_results" + assert "message" in example_no_results_response + assert "sources_rejected" in example_no_results_response + assert "sources_not_found" in example_no_results_response + + def test_search_lyrics_uses_correction_operations(self): + """Verify CorrectionOperations.search_lyrics_sources exists and is callable.""" + from karaoke_gen.lyrics_transcriber.correction.operations import CorrectionOperations + + assert hasattr(CorrectionOperations, "search_lyrics_sources") + method = getattr(CorrectionOperations, "search_lyrics_sources") + assert callable(method) + + def test_add_lyrics_source_has_force_parameter(self): + """Verify add_lyrics_source now accepts a force parameter.""" + import inspect + from karaoke_gen.lyrics_transcriber.correction.operations import CorrectionOperations + + sig = inspect.signature(CorrectionOperations.add_lyrics_source) + assert "force" in sig.parameters + # Default should be False + assert sig.parameters["force"].default is False diff --git a/docs/API.md b/docs/API.md index ebb09dd9..d9502095 100644 --- a/docs/API.md +++ b/docs/API.md @@ -441,6 +441,61 @@ Content-Type: application/json Stores annotations to `jobs/{job_id}/lyrics/annotations.json`. Merges with existing annotations if present. +#### Add Reference Lyrics (Paste) + +```http +POST /api/review/{job_id}/add-lyrics +Content-Type: application/json + +{ + "source": "manual", + "lyrics": "Full lyrics text...", + "force": false +} +``` + +Adds user-pasted lyrics as a new reference source, re-runs the correction pipeline with all sources, and uploads updated corrections to GCS. The `force` flag (default `false`) bypasses the relevance threshold — use when the transcription is poor and a low match % doesn't mean wrong song. + +Returns `{ "status": "success", "data": }`. + +#### Search Reference Lyrics + +```http +POST /api/review/{job_id}/search-lyrics +Content-Type: application/json + +{ + "artist": "Billie Eilish", + "title": "What Was I Made For", + "force_sources": [] +} +``` + +Searches all configured lyrics providers (Genius, Spotify, Musixmatch, LRCLIB) with the given artist/title. Results are filtered through the relevance threshold (30% word match minimum) — sources below are rejected as likely wrong-song matches. Sources in `force_sources` bypass the threshold. + +**Success response** (at least one source passed): +```json +{ + "status": "success", + "data": { "...CorrectionData..." }, + "sources_added": ["genius", "lrclib"], + "sources_rejected": { + "spotify": { "relevance": 0.12, "matched_words": 18, "total_words": 150, "track_name": "...", "artist_names": "..." } + }, + "sources_not_found": ["musixmatch"] +} +``` + +**No results response** (all filtered or nothing found): +```json +{ + "status": "no_results", + "message": "No matching lyrics found from any provider", + "sources_rejected": { "genius": { "relevance": 0.05, "..." } }, + "sources_not_found": ["lrclib", "musixmatch"] +} +``` + #### Review Sessions Server-side backup/restore of lyrics review editing sessions. Correction data is stored in GCS; metadata in Firestore subcollection `jobs/{job_id}/review_sessions/{session_id}`. diff --git a/docs/LESSONS-LEARNED.md b/docs/LESSONS-LEARNED.md index 1568bb73..04cf14e9 100644 --- a/docs/LESSONS-LEARNED.md +++ b/docs/LESSONS-LEARNED.md @@ -1037,6 +1037,14 @@ For this bug, the missing test was: "does `transcribe_lyrics()` return `lyrics_d **Key insight:** Long-running workers should avoid re-reading mutable metadata to reconstruct local file paths. If a file was created earlier in the same pipeline, find it by pattern rather than reconstructing its name from state that may have changed. This is a variant of TOCTOU — the "check" (reading artist/title) and "use" (looking for the file) happen at different times, and the underlying data can change between them. +### Reference Lyrics Relevance Filtering: Data-Driven Thresholds (Mar 2026) + +**Problem:** Lyrics providers often return wrong-song results for tracks with remixes, "feat." artists, or unusual naming. These irrelevant references pollute anchor/gap statistics and confuse correction tooling. + +**Solution:** Added relevance filtering in `LyricsCorrector` — after anchor sequences are found, compute `(reference words in anchors) / (total reference words)` per source. Sources below 30% are rejected. The threshold was determined empirically by analyzing 168 source pairs across 81 production jobs: wrong-song sources maxed at 3.5%, correct-song sources started at 26.8%. + +**Key insight:** Don't guess thresholds — measure them. A visual review tool showing side-by-side lyrics with match highlighting made it trivial to classify 168 pairs in minutes. The massive gap between wrong (0-3.5%) and correct (26.8%+) meant any threshold from 5-25% would work, but 30% provides safety margin. Always include a force-add override for edge cases where the transcription is bad (not the reference). + ### Cloud Scheduler OIDC Tokens ≠ Admin Tokens (Mar 2026) **Problem:** All 4 Cloud Scheduler → backend jobs (stale review processor, stuck job recovery, YouTube queue, disposable domain sync) were silently returning 401 since deployment. The auth system only validated admin tokens, Firestore tokens, and session tokens — it had no OIDC JWT validation. Cloud Scheduler sends a Google-signed OIDC JWT in the `Authorization: Bearer` header, which the auth service didn't recognize. diff --git a/docs/superpowers/plans/2026-03-29-reference-lyrics-search.md b/docs/superpowers/plans/2026-03-29-reference-lyrics-search.md new file mode 100644 index 00000000..8eb2455c --- /dev/null +++ b/docs/superpowers/plans/2026-03-29-reference-lyrics-search.md @@ -0,0 +1,1924 @@ +# Reference Lyrics Search & Relevance Filtering Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Add relevance filtering to reject wrong-song reference lyrics, a search-with-alternate-artist/title endpoint, and improved frontend UX with tabbed Search/Paste modal and empty-state inline UI. + +**Architecture:** Relevance filtering is added inside `LyricsCorrector.run()` after anchor finding — sources below a configurable threshold are removed before corrections are computed. A new `search-lyrics` API endpoint creates lyrics providers with user-supplied artist/title, fetches from all providers, and runs through the same correction pipeline. The frontend `AddLyricsModal` is redesigned with Search/Paste tabs, and the Reference panel shows an inline add-lyrics UI when no valid sources exist. + +**Tech Stack:** Python (FastAPI, pytest), TypeScript (Next.js, React, Jest/RTL), Firestore, GCS + +**Spec:** `docs/superpowers/specs/2026-03-29-reference-lyrics-search-design.md` + +--- + +## File Structure + +### New Files + +| File | Responsibility | +|------|---------------| +| `karaoke_gen/lyrics_transcriber/correction/relevance.py` | Per-source relevance scoring and filtering logic | +| `tests/correction/test_relevance.py` | Unit tests for relevance filtering | +| `backend/tests/test_search_lyrics.py` | Unit tests for the search-lyrics endpoint | +| `frontend/components/lyrics-review/modals/SearchLyricsTab.tsx` | Search tab component (artist/title inputs, results display) | +| `frontend/components/lyrics-review/modals/PasteLyricsTab.tsx` | Paste tab component (extracted from current AddLyricsModal) | +| `frontend/components/lyrics-review/ReferenceEmptyState.tsx` | Inline add-lyrics UI for empty reference panel | +| `scripts/analyze_reference_relevance.py` | One-off script to analyze prod jobs for threshold tuning | + +### Modified Files + +| File | Changes | +|------|---------| +| `karaoke_gen/lyrics_transcriber/correction/corrector.py` | Call relevance filter after anchor finding, remove filtered sources before corrections | +| `karaoke_gen/lyrics_transcriber/correction/operations.py` | New `search_lyrics_sources()` static method; add `force` param to `add_lyrics_source()` | +| `backend/api/routes/review.py` | New `POST /{job_id}/search-lyrics` endpoint; add `force` param to `add-lyrics` | +| `frontend/components/lyrics-review/modals/AddLyricsModal.tsx` | Rewrite as tabbed container for SearchLyricsTab + PasteLyricsTab | +| `frontend/components/lyrics-review/ReferenceView.tsx` | Show ReferenceEmptyState when no sources exist | +| `frontend/components/lyrics-review/LyricsAnalyzer.tsx` | Add `handleSearchLyrics` handler, wire up new modal props | +| `frontend/lib/api.ts` | New `searchLyrics()` method | +| `frontend/lib/lyrics-review/types.ts` | New `SearchLyricsResponse` and `RejectedSource` types | + +--- + +## Task 0: Empirical Threshold Analysis + +**Files:** +- Create: `scripts/analyze_reference_relevance.py` + +This task determines the right `MIN_REFERENCE_RELEVANCE` threshold from real production data. Must be done first since the threshold value is used in all subsequent tasks. + +- [ ] **Step 0.1: Write the analysis script** + +```python +# scripts/analyze_reference_relevance.py +""" +Analyze reference lyrics relevance across production jobs. + +Pulls ~30 jobs from Firestore, downloads their corrections.json from GCS, +computes per-source relevance scores, and generates a report for human review. + +Usage: + python scripts/analyze_reference_relevance.py +""" +import json +import os +import sys +import tempfile +from collections import defaultdict + +from google.cloud import firestore, storage + + +def get_total_words(source_data: dict) -> int: + """Count total words across all segments in a reference source.""" + total = 0 + for segment in source_data.get("segments", []): + total += len(segment.get("words", [])) + return total + + +def get_anchor_word_ids_for_source(anchor_sequences: list, source_name: str) -> set: + """Get all reference word IDs that appear in anchor sequences for a given source.""" + word_ids = set() + for anchor in anchor_sequences: + ref_word_ids = anchor.get("reference_word_ids", {}) + if source_name in ref_word_ids: + word_ids.update(ref_word_ids[source_name]) + return word_ids + + +def compute_relevance(source_data: dict, anchor_sequences: list, source_name: str) -> float: + """Compute relevance score: fraction of reference words appearing in anchors.""" + total_words = get_total_words(source_data) + if total_words == 0: + return 0.0 + matched_word_ids = get_anchor_word_ids_for_source(anchor_sequences, source_name) + return len(matched_word_ids) / total_words + + +def main(): + db = firestore.Client(project="nomadkaraoke") + gcs = storage.Client(project="nomadkaraoke") + bucket = gcs.bucket("karaoke-gen-outputs") + + # Query jobs that have corrections and are in review states + jobs_ref = db.collection("jobs") + query = jobs_ref.where("status", "in", ["awaiting_review", "in_review", "review_completed"]).limit(100) + jobs = list(query.stream()) + + print(f"Found {len(jobs)} jobs in review states") + + results = [] + + for job_doc in jobs: + job = job_doc.to_dict() + job_id = job_doc.id + corrections_path = job.get("file_urls", {}).get("lyrics", {}).get("corrections") + if not corrections_path: + continue + + # Download corrections.json + blob = bucket.blob(corrections_path) + if not blob.exists(): + continue + + try: + data = json.loads(blob.download_as_text()) + except Exception as e: + print(f" Error downloading {job_id}: {e}") + continue + + reference_lyrics = data.get("reference_lyrics", {}) + anchor_sequences = data.get("anchor_sequences", []) + original_segments = data.get("original_segments", []) + + if not reference_lyrics or not anchor_sequences: + continue + + # Get first 2 lines of transcription for context + trans_preview = " | ".join( + seg.get("text", "")[:60] for seg in original_segments[:2] + ) + + artist = data.get("metadata", {}).get("artist", "unknown") + title = data.get("metadata", {}).get("title", "unknown") + + for source_name, source_data in reference_lyrics.items(): + relevance = compute_relevance(source_data, anchor_sequences, source_name) + total_words = get_total_words(source_data) + matched_count = len(get_anchor_word_ids_for_source(anchor_sequences, source_name)) + + # Get first 2 lines of reference for context + ref_preview = " | ".join( + seg.get("text", "")[:60] for seg in source_data.get("segments", [])[:2] + ) + + results.append({ + "job_id": job_id, + "artist": artist, + "title": title, + "source": source_name, + "relevance": relevance, + "matched_words": matched_count, + "total_words": total_words, + "trans_preview": trans_preview, + "ref_preview": ref_preview, + }) + + if len(results) >= 60: # ~30 jobs × 2 sources each + break + + # Sort by relevance score to make threshold analysis easy + results.sort(key=lambda r: r["relevance"]) + + # Print report + print(f"\n{'='*120}") + print(f"REFERENCE LYRICS RELEVANCE ANALYSIS — {len(results)} source entries from {len(set(r['job_id'] for r in results))} jobs") + print(f"{'='*120}\n") + + for r in results: + print(f"Job: {r['job_id'][:12]} Source: {r['source']:<12} " + f"Relevance: {r['relevance']:.1%} ({r['matched_words']}/{r['total_words']} words)") + print(f" Track: {r['artist']} - {r['title']}") + print(f" Transcription: {r['trans_preview'][:80]}") + print(f" Reference: {r['ref_preview'][:80]}") + print() + + # Summary stats + scores = [r["relevance"] for r in results] + if scores: + print(f"\n{'='*120}") + print(f"SUMMARY") + print(f" Min: {min(scores):.1%} Max: {max(scores):.1%} Mean: {sum(scores)/len(scores):.1%}") + print(f" Scores < 10%: {sum(1 for s in scores if s < 0.10)}") + print(f" Scores < 20%: {sum(1 for s in scores if s < 0.20)}") + print(f" Scores < 30%: {sum(1 for s in scores if s < 0.30)}") + print(f" Scores < 40%: {sum(1 for s in scores if s < 0.40)}") + print(f" Scores < 50%: {sum(1 for s in scores if s < 0.50)}") + print(f"{'='*120}") + + +if __name__ == "__main__": + main() +``` + +- [ ] **Step 0.2: Run the analysis script** + +Run: `cd /Users/andrew/Projects/nomadkaraoke/karaoke-gen-reference-lyrics-search && python scripts/analyze_reference_relevance.py` + +Review the output with the user. For each low-scoring source, the user classifies it as "correct song" or "wrong song". Determine the threshold that best separates the two groups. + +- [ ] **Step 0.3: Record the threshold** + +Based on the analysis, set the `MIN_REFERENCE_RELEVANCE` constant value. This value is used in Task 1. + +- [ ] **Step 0.4: Commit** + +```bash +git add scripts/analyze_reference_relevance.py +git commit -m "feat: add reference lyrics relevance analysis script" +``` + +--- + +## Task 1: Relevance Filtering Module + +**Files:** +- Create: `karaoke_gen/lyrics_transcriber/correction/relevance.py` +- Create: `tests/correction/test_relevance.py` + +This task creates the standalone relevance scoring and filtering logic. It's a pure function module with no side effects — given anchor sequences and reference lyrics, it returns which sources pass and which are rejected. + +- [ ] **Step 1.1: Write failing tests for relevance scoring** + +```python +# tests/correction/test_relevance.py +import pytest +from karaoke_gen.lyrics_transcriber.correction.relevance import ( + compute_source_relevance, + filter_irrelevant_sources, + SourceRelevanceResult, +) +from karaoke_gen.lyrics_transcriber.types import ( + AnchorSequence, + LyricsData, + LyricsMetadata, + LyricsSegment, + Word, +) + + +def _make_words(texts: list[str], id_prefix: str = "w") -> list[Word]: + """Create Word objects from text strings.""" + return [ + Word(id=f"{id_prefix}_{i}", text=t, start_time=0.0, end_time=0.0) + for i, t in enumerate(texts) + ] + + +def _make_lyrics_data(word_texts: list[list[str]], source: str) -> LyricsData: + """Create LyricsData from a list of lines (each line is a list of word strings).""" + segments = [] + for i, line_words in enumerate(word_texts): + words = _make_words(line_words, id_prefix=f"{source}_s{i}_w") + segments.append( + LyricsSegment( + id=f"{source}_seg_{i}", + text=" ".join(line_words), + words=words, + start_time=0.0, + end_time=0.0, + ) + ) + return LyricsData( + segments=segments, + metadata=LyricsMetadata(source=source, track_name="Test", artist_names="Test"), + source=source, + ) + + +def _make_anchor( + trans_word_ids: list[str], + reference_word_ids: dict[str, list[str]], + confidence: float = 1.0, +) -> AnchorSequence: + """Create an AnchorSequence with given word ID mappings.""" + return AnchorSequence( + id=f"anchor_{trans_word_ids[0]}", + transcribed_word_ids=trans_word_ids, + transcription_position=0, + reference_positions={s: 0 for s in reference_word_ids}, + reference_word_ids=reference_word_ids, + confidence=confidence, + ) + + +class TestComputeSourceRelevance: + def test_high_match_returns_high_score(self): + """Source with 8/10 words in anchors scores 0.8.""" + lyrics = _make_lyrics_data([["a", "b", "c", "d", "e", "f", "g", "h", "i", "j"]], "genius") + all_word_ids = [w.id for seg in lyrics.segments for w in seg.words] + # 8 of 10 words matched + anchors = [ + _make_anchor(["t1", "t2"], {"genius": all_word_ids[0:2]}), + _make_anchor(["t3", "t4", "t5"], {"genius": all_word_ids[2:5]}), + _make_anchor(["t6", "t7", "t8"], {"genius": all_word_ids[5:8]}), + ] + result = compute_source_relevance("genius", lyrics, anchors) + assert result.relevance == pytest.approx(0.8) + assert result.matched_words == 8 + assert result.total_words == 10 + + def test_no_match_returns_zero(self): + """Source with no words in any anchors scores 0.0.""" + lyrics = _make_lyrics_data([["a", "b", "c"]], "spotify") + anchors = [ + _make_anchor(["t1"], {"genius": ["other_id"]}), # Different source + ] + result = compute_source_relevance("spotify", lyrics, anchors) + assert result.relevance == 0.0 + assert result.matched_words == 0 + + def test_empty_source_returns_zero(self): + """Source with zero words scores 0.0.""" + lyrics = _make_lyrics_data([], "empty") + result = compute_source_relevance("empty", lyrics, []) + assert result.relevance == 0.0 + + +class TestFilterIrrelevantSources: + def test_filters_below_threshold(self): + """Sources below threshold are removed from lyrics_results.""" + good_lyrics = _make_lyrics_data([["a", "b", "c", "d", "e"]], "genius") + bad_lyrics = _make_lyrics_data([["x", "y", "z", "q", "r"]], "spotify") + good_word_ids = [w.id for seg in good_lyrics.segments for w in seg.words] + + lyrics_results = {"genius": good_lyrics, "spotify": bad_lyrics} + anchors = [ + _make_anchor(["t1", "t2", "t3", "t4"], {"genius": good_word_ids[0:4]}), + ] + + filtered, rejected = filter_irrelevant_sources( + lyrics_results, anchors, min_relevance=0.5 + ) + assert "genius" in filtered + assert "spotify" not in filtered + assert "spotify" in rejected + assert rejected["spotify"].relevance == 0.0 + + def test_keeps_all_above_threshold(self): + """All sources above threshold are kept.""" + lyrics_a = _make_lyrics_data([["a", "b"]], "src_a") + lyrics_b = _make_lyrics_data([["a", "b"]], "src_b") + a_ids = [w.id for seg in lyrics_a.segments for w in seg.words] + b_ids = [w.id for seg in lyrics_b.segments for w in seg.words] + + anchors = [ + _make_anchor(["t1", "t2"], {"src_a": a_ids, "src_b": b_ids}), + ] + filtered, rejected = filter_irrelevant_sources( + {"src_a": lyrics_a, "src_b": lyrics_b}, anchors, min_relevance=0.5 + ) + assert len(filtered) == 2 + assert len(rejected) == 0 + + def test_empty_input_returns_empty(self): + """No sources in, no sources out.""" + filtered, rejected = filter_irrelevant_sources({}, [], min_relevance=0.5) + assert filtered == {} + assert rejected == {} +``` + +- [ ] **Step 1.2: Run tests to verify they fail** + +Run: `cd /Users/andrew/Projects/nomadkaraoke/karaoke-gen-reference-lyrics-search && python -m pytest tests/correction/test_relevance.py -v` +Expected: FAIL — module does not exist yet. + +- [ ] **Step 1.3: Implement the relevance module** + +```python +# karaoke_gen/lyrics_transcriber/correction/relevance.py +"""Reference lyrics relevance scoring and filtering. + +Computes how well each reference source matches the transcription based on +anchor sequence coverage. Sources below the relevance threshold are filtered +out to prevent wrong-song lyrics from polluting corrections. +""" +import logging +from dataclasses import dataclass +from typing import Dict, List, Tuple + +from karaoke_gen.lyrics_transcriber.types import AnchorSequence, LyricsData + +# Default threshold — determined by empirical analysis of production jobs. +# See scripts/analyze_reference_relevance.py and the design spec for methodology. +MIN_REFERENCE_RELEVANCE = 0.30 # TODO: Update after Task 0 analysis + + +@dataclass +class SourceRelevanceResult: + """Relevance scoring result for a single reference source.""" + source: str + relevance: float # 0.0 to 1.0 — fraction of reference words in anchors + matched_words: int + total_words: int + track_name: str = "" + artist_names: str = "" + + +def compute_source_relevance( + source_name: str, + lyrics_data: LyricsData, + anchor_sequences: List[AnchorSequence], +) -> SourceRelevanceResult: + """Compute relevance score for a single reference source. + + Relevance = (reference words appearing in anchor sequences) / (total reference words). + """ + total_words = sum(len(seg.words) for seg in lyrics_data.segments) + if total_words == 0: + return SourceRelevanceResult( + source=source_name, + relevance=0.0, + matched_words=0, + total_words=0, + track_name=lyrics_data.metadata.track_name or "", + artist_names=lyrics_data.metadata.artist_names or "", + ) + + # Collect all reference word IDs for this source across all anchors + all_ref_word_ids = set() + for anchor in anchor_sequences: + source_word_ids = anchor.reference_word_ids.get(source_name, []) + all_ref_word_ids.update(source_word_ids) + + # Count how many of this source's word IDs appear in anchors + source_word_ids = {w.id for seg in lyrics_data.segments for w in seg.words} + matched = len(all_ref_word_ids & source_word_ids) + + return SourceRelevanceResult( + source=source_name, + relevance=matched / total_words, + matched_words=matched, + total_words=total_words, + track_name=lyrics_data.metadata.track_name or "", + artist_names=lyrics_data.metadata.artist_names or "", + ) + + +def filter_irrelevant_sources( + lyrics_results: Dict[str, LyricsData], + anchor_sequences: List[AnchorSequence], + min_relevance: float = MIN_REFERENCE_RELEVANCE, + logger: logging.Logger = None, +) -> Tuple[Dict[str, LyricsData], Dict[str, SourceRelevanceResult]]: + """Filter out reference sources below the relevance threshold. + + Args: + lyrics_results: Dict mapping source name to LyricsData. + anchor_sequences: Anchor sequences from the anchor finder. + min_relevance: Minimum relevance score to keep a source. + logger: Optional logger. + + Returns: + Tuple of (filtered_lyrics_results, rejected_sources). + filtered_lyrics_results: Sources that passed the threshold. + rejected_sources: Dict mapping source name to SourceRelevanceResult for rejected sources. + """ + if not logger: + logger = logging.getLogger(__name__) + + filtered = {} + rejected = {} + + for source_name, lyrics_data in lyrics_results.items(): + result = compute_source_relevance(source_name, lyrics_data, anchor_sequences) + + if result.relevance >= min_relevance: + filtered[source_name] = lyrics_data + logger.info( + f"Source '{source_name}' passed relevance filter: " + f"{result.relevance:.1%} ({result.matched_words}/{result.total_words} words)" + ) + else: + rejected[source_name] = result + logger.info( + f"Source '{source_name}' rejected by relevance filter: " + f"{result.relevance:.1%} ({result.matched_words}/{result.total_words} words)" + ) + + return filtered, rejected +``` + +- [ ] **Step 1.4: Run tests to verify they pass** + +Run: `cd /Users/andrew/Projects/nomadkaraoke/karaoke-gen-reference-lyrics-search && python -m pytest tests/correction/test_relevance.py -v` +Expected: All 6 tests PASS. + +- [ ] **Step 1.5: Commit** + +```bash +git add karaoke_gen/lyrics_transcriber/correction/relevance.py tests/correction/test_relevance.py +git commit -m "feat: add reference lyrics relevance scoring and filtering module" +``` + +--- + +## Task 2: Integrate Relevance Filtering into LyricsCorrector + +**Files:** +- Modify: `karaoke_gen/lyrics_transcriber/correction/corrector.py:107-221` +- Modify: `tests/correction/test_relevance.py` (add integration-style test) + +This task wires the relevance filter into the correction pipeline so that all code paths (initial processing, add-lyrics, search-lyrics) benefit from filtering. + +- [ ] **Step 2.1: Write failing test for corrector filtering** + +Add to `tests/correction/test_relevance.py`: + +```python +class TestCorrectorRelevanceIntegration: + """Test that LyricsCorrector filters irrelevant sources.""" + + def test_corrector_removes_irrelevant_source(self, tmp_path): + """A source with 0% match should be excluded from the CorrectionResult.""" + from karaoke_gen.lyrics_transcriber.correction.corrector import LyricsCorrector + from karaoke_gen.lyrics_transcriber.types import TranscriptionData, TranscriptionResult + + # Transcription: "hello world foo bar" + trans_words = _make_words(["hello", "world", "foo", "bar"], "trans") + trans_segment = LyricsSegment( + id="trans_seg_0", text="hello world foo bar", + words=trans_words, start_time=0.0, end_time=1.0, + ) + transcription = TranscriptionData( + segments=[trans_segment], + words=trans_words, + text="hello world foo bar", + source="test", + ) + + # Good source: matching words + good_lyrics = _make_lyrics_data([["hello", "world", "foo", "bar"]], "good_source") + # Bad source: completely different words + bad_lyrics = _make_lyrics_data([["alpha", "beta", "gamma", "delta"]], "bad_source") + + corrector = LyricsCorrector(cache_dir=str(tmp_path)) + result = corrector.run( + transcription_results=[TranscriptionResult(name="test", priority=1, result=transcription)], + lyrics_results={"good_source": good_lyrics, "bad_source": bad_lyrics}, + ) + + # Good source should be in result, bad source should not + assert "good_source" in result.reference_lyrics + assert "bad_source" not in result.reference_lyrics + + # Rejected sources should be logged in metadata + assert "rejected_sources" in result.metadata + assert "bad_source" in result.metadata["rejected_sources"] +``` + +- [ ] **Step 2.2: Run test to verify it fails** + +Run: `cd /Users/andrew/Projects/nomadkaraoke/karaoke-gen-reference-lyrics-search && python -m pytest tests/correction/test_relevance.py::TestCorrectorRelevanceIntegration -v` +Expected: FAIL — corrector doesn't filter sources yet. + +- [ ] **Step 2.3: Modify LyricsCorrector.run() to apply relevance filtering** + +In `karaoke_gen/lyrics_transcriber/correction/corrector.py`, add the import at the top: + +```python +from karaoke_gen.lyrics_transcriber.correction.relevance import filter_irrelevant_sources +``` + +Then modify the `run()` method. After the anchor finding (line 157) and before gap finding, insert the relevance filter. Replace lines 156-160 with: + +```python + anchor_sequences = self.anchor_finder.find_anchors(transcribed_text, lyrics_results, primary_transcription_result) + + # Filter irrelevant reference sources based on anchor match quality + filtered_lyrics, rejected_sources = filter_irrelevant_sources( + lyrics_results, anchor_sequences, logger=self.logger, + ) + + # If sources were filtered, re-run anchor finding with only valid sources + if len(filtered_lyrics) < len(lyrics_results): + self.logger.info( + f"Relevance filter: {len(lyrics_results)} -> {len(filtered_lyrics)} sources " + f"(rejected: {', '.join(rejected_sources.keys())})" + ) + if filtered_lyrics: + # Re-find anchors with only the valid sources + self._anchor_finder = None # Reset to clear cached state + anchor_sequences = self.anchor_finder.find_anchors( + transcribed_text, filtered_lyrics, primary_transcription_result + ) + else: + anchor_sequences = [] + + # Update lyrics_results to only include filtered sources + lyrics_results = filtered_lyrics + + gap_sequences = self.anchor_finder.find_gaps(transcribed_text, anchor_sequences, lyrics_results, primary_transcription_result) + if anchor_span: + anchor_span.set_attribute("anchor_count", len(anchor_sequences)) + anchor_span.set_attribute("gap_count", len(gap_sequences)) + anchor_span.set_attribute("sources_rejected", len(rejected_sources)) +``` + +Then in the metadata section (around line 192), add the rejected sources info. After the `result_metadata` dict is built, add: + +```python + # Add rejected sources to metadata for debugging and frontend display + if rejected_sources: + result_metadata["rejected_sources"] = { + name: { + "relevance": result.relevance, + "matched_words": result.matched_words, + "total_words": result.total_words, + "track_name": result.track_name, + "artist_names": result.artist_names, + } + for name, result in rejected_sources.items() + } +``` + +Also update the `self.reference_lyrics = lyrics_results` on line 146 — move it to AFTER the filtering so handlers use the filtered set: + +Remove line 146 (`self.reference_lyrics = lyrics_results`) and add it after the filtering block: + +```python + # Update lyrics_results to only include filtered sources + lyrics_results = filtered_lyrics + + # Store filtered reference lyrics for use in word map + self.reference_lyrics = lyrics_results +``` + +- [ ] **Step 2.4: Run test to verify it passes** + +Run: `cd /Users/andrew/Projects/nomadkaraoke/karaoke-gen-reference-lyrics-search && python -m pytest tests/correction/test_relevance.py -v` +Expected: All tests PASS. + +- [ ] **Step 2.5: Run full backend test suite to check for regressions** + +Run: `cd /Users/andrew/Projects/nomadkaraoke/karaoke-gen-reference-lyrics-search && python -m pytest tests/ backend/tests/ -v --timeout=60 2>&1 | tail -50` +Expected: All existing tests PASS. If any fail due to the new filtering behavior, investigate — some tests may have reference lyrics that don't match their transcription and now get filtered. Fix by either adjusting test data or setting the threshold appropriately for test scenarios. + +- [ ] **Step 2.6: Commit** + +```bash +git add karaoke_gen/lyrics_transcriber/correction/corrector.py tests/correction/test_relevance.py +git commit -m "feat: integrate relevance filtering into LyricsCorrector pipeline" +``` + +--- + +## Task 3: Search Lyrics Operation + API Endpoint + +**Files:** +- Modify: `karaoke_gen/lyrics_transcriber/correction/operations.py` +- Modify: `backend/api/routes/review.py` +- Modify: `backend/config.py` (if needed for provider config access) +- Create: `backend/tests/test_search_lyrics.py` + +This task adds the backend capability to search for lyrics with an alternate artist/title and the API endpoint that the frontend calls. + +- [ ] **Step 3.1: Write failing test for search_lyrics_sources operation** + +```python +# backend/tests/test_search_lyrics.py +import pytest +from unittest.mock import MagicMock, patch, AsyncMock +from karaoke_gen.lyrics_transcriber.correction.operations import CorrectionOperations +from karaoke_gen.lyrics_transcriber.types import ( + CorrectionResult, LyricsData, LyricsMetadata, LyricsSegment, Word, + TranscriptionData, TranscriptionResult, +) + + +def _make_words(texts, prefix="w"): + return [Word(id=f"{prefix}_{i}", text=t, start_time=0.0, end_time=0.0) for i, t in enumerate(texts)] + + +def _make_correction_result(transcription_words=None): + """Create a minimal CorrectionResult for testing.""" + if transcription_words is None: + transcription_words = ["hello", "world", "this", "is", "a", "test"] + words = _make_words(transcription_words, "trans") + segment = LyricsSegment( + id="seg_0", text=" ".join(transcription_words), + words=words, start_time=0.0, end_time=1.0, + ) + return CorrectionResult( + original_segments=[segment], + corrected_segments=[segment], + corrections=[], + corrections_made=0, + confidence=1.0, + reference_lyrics={}, + anchor_sequences=[], + gap_sequences=[], + resized_segments=[], + metadata={"enabled_handlers": []}, + correction_steps=[], + word_id_map={}, + segment_id_map={}, + ) + + +def _make_lyrics_data(word_texts, source): + segments = [] + for i, line in enumerate(word_texts): + words = _make_words(line, f"{source}_s{i}") + segments.append(LyricsSegment( + id=f"{source}_seg_{i}", text=" ".join(line), + words=words, start_time=0.0, end_time=0.0, + )) + return LyricsData( + segments=segments, + metadata=LyricsMetadata(source=source, track_name="Test Song", artist_names="Test Artist"), + source=source, + ) + + +class TestSearchLyricsSources: + def test_returns_added_and_rejected_sources(self, tmp_path): + """search_lyrics_sources should return which sources were added vs rejected.""" + correction_result = _make_correction_result(["hello", "world", "foo", "bar"]) + + # Mock providers: one returns matching lyrics, one returns non-matching + good_lyrics = _make_lyrics_data([["hello", "world", "foo", "bar"]], "genius") + bad_lyrics = _make_lyrics_data([["alpha", "beta", "gamma", "delta"]], "spotify") + + mock_providers = { + "genius": MagicMock(**{"fetch_lyrics.return_value": good_lyrics, "get_name.return_value": "genius"}), + "spotify": MagicMock(**{"fetch_lyrics.return_value": bad_lyrics, "get_name.return_value": "spotify"}), + } + + with patch( + "karaoke_gen.lyrics_transcriber.correction.operations.create_lyrics_providers", + return_value=mock_providers, + ): + updated_result, sources_added, sources_rejected, sources_not_found = ( + CorrectionOperations.search_lyrics_sources( + correction_result=correction_result, + artist="Test Artist", + title="Test Song", + cache_dir=str(tmp_path), + ) + ) + + assert "genius" in sources_added + assert "spotify" in sources_rejected + assert "genius" in updated_result.reference_lyrics + + def test_force_sources_bypass_threshold(self, tmp_path): + """Sources in force_sources should be added even with low relevance.""" + correction_result = _make_correction_result(["hello", "world", "foo", "bar"]) + bad_lyrics = _make_lyrics_data([["alpha", "beta", "gamma", "delta"]], "spotify") + + mock_providers = { + "spotify": MagicMock(**{"fetch_lyrics.return_value": bad_lyrics, "get_name.return_value": "spotify"}), + } + + with patch( + "karaoke_gen.lyrics_transcriber.correction.operations.create_lyrics_providers", + return_value=mock_providers, + ): + updated_result, sources_added, sources_rejected, sources_not_found = ( + CorrectionOperations.search_lyrics_sources( + correction_result=correction_result, + artist="Test", + title="Test", + cache_dir=str(tmp_path), + force_sources=["spotify"], + ) + ) + + assert "spotify" in sources_added + assert len(sources_rejected) == 0 + + def test_no_results_from_providers(self, tmp_path): + """When no provider returns lyrics, all are in sources_not_found.""" + correction_result = _make_correction_result() + + mock_providers = { + "genius": MagicMock(**{"fetch_lyrics.return_value": None, "get_name.return_value": "genius"}), + "lrclib": MagicMock(**{"fetch_lyrics.return_value": None, "get_name.return_value": "lrclib"}), + } + + with patch( + "karaoke_gen.lyrics_transcriber.correction.operations.create_lyrics_providers", + return_value=mock_providers, + ): + updated_result, sources_added, sources_rejected, sources_not_found = ( + CorrectionOperations.search_lyrics_sources( + correction_result=correction_result, + artist="Unknown", + title="Unknown", + cache_dir=str(tmp_path), + ) + ) + + assert len(sources_added) == 0 + assert len(sources_rejected) == 0 + assert "genius" in sources_not_found + assert "lrclib" in sources_not_found +``` + +- [ ] **Step 3.2: Run tests to verify they fail** + +Run: `cd /Users/andrew/Projects/nomadkaraoke/karaoke-gen-reference-lyrics-search && python -m pytest backend/tests/test_search_lyrics.py -v` +Expected: FAIL — `search_lyrics_sources` and `create_lyrics_providers` don't exist yet. + +- [ ] **Step 3.3: Create provider factory function and implement search_lyrics_sources** + +First, add the provider factory. Create or add to an appropriate location — adding to `operations.py` since it's the only consumer: + +Add these imports to the top of `karaoke_gen/lyrics_transcriber/correction/operations.py`: + +```python +from karaoke_gen.lyrics_transcriber.lyrics.base_lyrics_provider import BaseLyricsProvider, LyricsProviderConfig +from karaoke_gen.lyrics_transcriber.lyrics.genius import GeniusProvider +from karaoke_gen.lyrics_transcriber.lyrics.spotify import SpotifyProvider +from karaoke_gen.lyrics_transcriber.lyrics.musixmatch import MusixmatchProvider +from karaoke_gen.lyrics_transcriber.lyrics.lrclib import LRCLIBProvider +from karaoke_gen.lyrics_transcriber.correction.relevance import ( + compute_source_relevance, + filter_irrelevant_sources, + SourceRelevanceResult, +) +``` + +Then add the factory function before the `CorrectionOperations` class: + +```python +def create_lyrics_providers( + cache_dir: str, + logger: Optional[logging.Logger] = None, +) -> Dict[str, BaseLyricsProvider]: + """Create all available lyrics providers from environment config. + + Providers requiring API keys are only included if the keys are set. + """ + import os + + config = LyricsProviderConfig( + genius_api_token=os.getenv("GENIUS_API_KEY"), + rapidapi_key=os.getenv("RAPIDAPI_KEY"), + spotify_cookie=os.getenv("SPOTIFY_COOKIE_SP_DC"), + cache_dir=cache_dir, + ) + + providers: Dict[str, BaseLyricsProvider] = {} + + # LRCLIB is always available (no API key required) + providers["lrclib"] = LRCLIBProvider(config=config, logger=logger) + + if config.genius_api_token: + providers["genius"] = GeniusProvider(config=config, logger=logger) + + if config.spotify_cookie: + providers["spotify"] = SpotifyProvider(config=config, logger=logger) + + if config.rapidapi_key: + providers["musixmatch"] = MusixmatchProvider(config=config, logger=logger) + + return providers +``` + +Then add the `search_lyrics_sources` method to `CorrectionOperations`: + +```python + @staticmethod + def search_lyrics_sources( + correction_result: CorrectionResult, + artist: str, + title: str, + cache_dir: str, + force_sources: Optional[List[str]] = None, + logger: Optional[logging.Logger] = None, + ) -> tuple: + """Search for lyrics with alternate artist/title and add passing sources. + + Args: + correction_result: Current correction result. + artist: Artist name to search with. + title: Track title to search with. + cache_dir: Cache directory for providers and correction. + force_sources: Source names to add regardless of relevance threshold. + logger: Optional logger. + + Returns: + Tuple of (updated_result, sources_added, sources_rejected, sources_not_found). + - updated_result: CorrectionResult with new sources added (or original if none added). + - sources_added: List of source names that were added. + - sources_rejected: Dict of source name -> SourceRelevanceResult for rejected sources. + - sources_not_found: List of source names that returned no lyrics. + """ + if not logger: + logger = logging.getLogger(__name__) + + force_sources = force_sources or [] + sources_added = [] + sources_rejected = {} + sources_not_found = [] + + # Create providers and fetch lyrics + providers = create_lyrics_providers(cache_dir=cache_dir, logger=logger) + logger.info(f"Searching {len(providers)} providers for '{artist}' - '{title}'") + + fetched_lyrics = {} + for name, provider in providers.items(): + # Skip sources already in the correction result + if name in correction_result.reference_lyrics: + logger.info(f"Skipping '{name}' — already in reference lyrics") + continue + + try: + lyrics_data = provider.fetch_lyrics(artist, title) + if lyrics_data: + fetched_lyrics[name] = lyrics_data + logger.info(f"Provider '{name}' returned lyrics ({len(lyrics_data.segments)} segments)") + else: + sources_not_found.append(name) + logger.info(f"Provider '{name}' returned no results") + except Exception as e: + sources_not_found.append(name) + logger.warning(f"Provider '{name}' failed: {e}") + + if not fetched_lyrics: + return correction_result, sources_added, sources_rejected, sources_not_found + + # Combine existing + new sources for correction + combined_lyrics = correction_result.reference_lyrics.copy() + combined_lyrics.update(fetched_lyrics) + + # Create transcription data from original segments + transcription_data = TranscriptionData( + segments=correction_result.original_segments, + words=[w for seg in correction_result.original_segments for w in seg.words], + text="\n".join(seg.text for seg in correction_result.original_segments), + source="original", + ) + + # Get enabled handlers from metadata + enabled_handlers = None + if correction_result.metadata: + enabled_handlers = correction_result.metadata.get("enabled_handlers") + + # Store audio hash + audio_hash = correction_result.metadata.get("audio_hash") if correction_result.metadata else None + + # Run correction with all sources — the corrector's relevance filter handles rejection + corrector = LyricsCorrector( + cache_dir=cache_dir, + enabled_handlers=enabled_handlers, + logger=logger, + ) + + # For force_sources, we need to temporarily bypass the filter. + # We do this by running correction normally, then checking what got rejected. + updated_result = corrector.run( + transcription_results=[TranscriptionResult(name="original", priority=1, result=transcription_data)], + lyrics_results=combined_lyrics, + metadata=correction_result.metadata, + ) + + # Check which new sources survived vs were rejected + rejected_meta = updated_result.metadata.get("rejected_sources", {}) + for name in fetched_lyrics: + if name in updated_result.reference_lyrics: + sources_added.append(name) + elif name in rejected_meta: + if name in force_sources: + # Force-add: re-add to reference lyrics and re-run correction + sources_added.append(name) + else: + sources_rejected[name] = SourceRelevanceResult( + source=name, + relevance=rejected_meta[name]["relevance"], + matched_words=rejected_meta[name]["matched_words"], + total_words=rejected_meta[name]["total_words"], + track_name=rejected_meta[name].get("track_name", ""), + artist_names=rejected_meta[name].get("artist_names", ""), + ) + + # If there are force sources that were rejected, re-run with them included + if any(name in force_sources for name in rejected_meta): + force_lyrics = { + name: fetched_lyrics[name] + for name in force_sources + if name in fetched_lyrics and name not in updated_result.reference_lyrics + } + if force_lyrics: + force_combined = updated_result.reference_lyrics.copy() + force_combined.update(force_lyrics) + + # Re-run correction skipping the relevance filter won't work since it's + # built into the corrector. Instead, add them via add_lyrics_source. + for name, lyrics_data in force_lyrics.items(): + lyrics_text = lyrics_data.get_full_text() + updated_result = CorrectionOperations.add_lyrics_source( + correction_result=updated_result, + source=name, + lyrics_text=lyrics_text, + cache_dir=cache_dir, + logger=logger, + force=True, + ) + + # Update metadata + if not updated_result.metadata: + updated_result.metadata = {} + updated_result.metadata.update({ + "available_handlers": corrector.all_handlers, + "enabled_handlers": [getattr(h, "name", h.__class__.__name__) for h in corrector.handlers], + }) + if audio_hash: + updated_result.metadata["audio_hash"] = audio_hash + + return updated_result, sources_added, sources_rejected, sources_not_found +``` + +Also update `add_lyrics_source` to accept a `force` parameter. Add `force: bool = False` to its signature and pass it through to skip relevance filtering. In the method, after the `corrector.run()` call, if `force=True` and the source was rejected, re-add it: + +In `add_lyrics_source`, change the signature: + +```python + @staticmethod + def add_lyrics_source( + correction_result: CorrectionResult, + source: str, + lyrics_text: str, + cache_dir: str, + logger: Optional[logging.Logger] = None, + force: bool = False, + ) -> CorrectionResult: +``` + +After the `corrector.run()` call (around line 184), add: + +```python + # If force=True and the source was rejected by relevance filter, re-add it + if force and source not in updated_result.reference_lyrics: + logger.info(f"Force-adding source '{source}' despite low relevance") + updated_result.reference_lyrics[source] = lyrics_data + # Rejected sources metadata should note this was force-added + if "rejected_sources" in updated_result.metadata: + rejected_info = updated_result.metadata["rejected_sources"].pop(source, None) + if rejected_info: + if "force_added_sources" not in updated_result.metadata: + updated_result.metadata["force_added_sources"] = {} + updated_result.metadata["force_added_sources"][source] = rejected_info +``` + +- [ ] **Step 3.4: Run tests to verify they pass** + +Run: `cd /Users/andrew/Projects/nomadkaraoke/karaoke-gen-reference-lyrics-search && python -m pytest backend/tests/test_search_lyrics.py -v` +Expected: All 3 tests PASS. + +- [ ] **Step 3.5: Add the API endpoint** + +In `backend/api/routes/review.py`, add the new endpoint after the existing `add_lyrics` endpoint. Add near the other imports: + +```python +from karaoke_gen.lyrics_transcriber.correction.relevance import SourceRelevanceResult +``` + +Then add the endpoint: + +```python +@router.post("/{job_id}/search-lyrics") +async def search_lyrics( + job_id: str, + data: Dict[str, Any], + auth_info: Tuple[str, str] = Depends(require_review_auth), +): + """Search for lyrics with alternate artist/title. + + Request body: + artist: Artist name to search with. + title: Track title to search with. + force_sources: Optional list of source names to add regardless of threshold. + """ + with create_span("review.search_lyrics", {"job_id": job_id}) as span: + try: + with job_log_context(job_id): + job_manager = JobManager() + job = job_manager.get_job(job_id) + + if job.status not in [JobStatus.AWAITING_REVIEW, JobStatus.IN_REVIEW]: + raise HTTPException(status_code=400, detail=f"Job must be in review state, currently: {job.status}") + + artist = data.get("artist", "").strip() + title = data.get("title", "").strip() + force_sources = data.get("force_sources", []) + + if not artist or not title: + raise HTTPException(status_code=400, detail="Artist and title are required") + + # Download current corrections + storage = StorageService() + corrections_path = job.file_urls.get("lyrics", {}).get("corrections") + if not corrections_path: + raise HTTPException(status_code=404, detail="No corrections file found") + + original_data = storage.download_json(corrections_path) + correction_result = CorrectionResult.from_dict(original_data) + + # Create temp cache dir + import tempfile + cache_dir = tempfile.mkdtemp(prefix="search_lyrics_") + + # Search and add sources + updated_result, sources_added, sources_rejected, sources_not_found = ( + CorrectionOperations.search_lyrics_sources( + correction_result=correction_result, + artist=artist, + title=title, + cache_dir=cache_dir, + force_sources=force_sources, + logger=logger, + ) + ) + + if sources_added: + # Add metadata + if not updated_result.metadata: + updated_result.metadata = {} + audio_hash = original_data.get("metadata", {}).get("audio_hash") + if audio_hash: + updated_result.metadata["audio_hash"] = audio_hash + artist_meta = original_data.get("metadata", {}).get("artist") + if artist_meta: + updated_result.metadata["artist"] = artist_meta + title_meta = original_data.get("metadata", {}).get("title") + if title_meta: + updated_result.metadata["title"] = title_meta + + # Upload updated corrections + updated_data = updated_result.to_dict() + storage.upload_json(corrections_path, updated_data) + + return { + "status": "success", + "data": updated_data, + "sources_added": sources_added, + "sources_rejected": { + name: { + "relevance": r.relevance, + "matched_words": r.matched_words, + "total_words": r.total_words, + "track_name": r.track_name, + "artist_names": r.artist_names, + } + for name, r in sources_rejected.items() + }, + "sources_not_found": sources_not_found, + } + else: + return { + "status": "no_results", + "message": "No lyrics sources passed the relevance threshold", + "sources_rejected": { + name: { + "relevance": r.relevance, + "matched_words": r.matched_words, + "total_words": r.total_words, + "track_name": r.track_name, + "artist_names": r.artist_names, + } + for name, r in sources_rejected.items() + }, + "sources_not_found": sources_not_found, + } + + except HTTPException: + raise + except ValueError as e: + raise HTTPException(status_code=400, detail=str(e)) + except Exception as e: + logger.error(f"Error searching lyrics for job {job_id}: {e}", exc_info=True) + raise HTTPException(status_code=500, detail=f"Failed to search lyrics: {str(e)}") +``` + +- [ ] **Step 3.6: Run full backend tests** + +Run: `cd /Users/andrew/Projects/nomadkaraoke/karaoke-gen-reference-lyrics-search && python -m pytest backend/tests/ tests/ -v --timeout=60 2>&1 | tail -50` +Expected: All tests PASS. + +- [ ] **Step 3.7: Commit** + +```bash +git add karaoke_gen/lyrics_transcriber/correction/operations.py backend/api/routes/review.py backend/tests/test_search_lyrics.py +git commit -m "feat: add search-lyrics endpoint and search_lyrics_sources operation" +``` + +--- + +## Task 4: Frontend Types and API Client + +**Files:** +- Modify: `frontend/lib/lyrics-review/types.ts` +- Modify: `frontend/lib/api.ts` + +This task adds the TypeScript types and API method for the search-lyrics endpoint. + +- [ ] **Step 4.1: Add frontend types** + +Add to `frontend/lib/lyrics-review/types.ts`: + +```typescript +export interface RejectedSource { + relevance: number + matched_words: number + total_words: number + track_name: string + artist_names: string +} + +export interface SearchLyricsResponse { + status: 'success' | 'no_results' + data?: CorrectionData + message?: string + sources_added: string[] + sources_rejected: Record + sources_not_found: string[] +} +``` + +- [ ] **Step 4.2: Add searchLyrics method to API client** + +Add to `frontend/lib/api.ts`, in the API client class near the `addLyrics` method: + +```typescript + async searchLyrics( + artist: string, + title: string, + forceSources: string[] = [], + ): Promise { + const response = await fetch( + `${API_BASE_URL}/api/review/${this.jobId}/search-lyrics`, + { + method: 'POST', + headers: { + 'Content-Type': 'application/json', + ...this.getAuthHeaders(), + }, + body: JSON.stringify({ + artist, + title, + force_sources: forceSources, + }), + }, + ) + return handleResponse(response) + } +``` + +Note: Unlike `addLyrics` which unwraps `result.data`, `searchLyrics` returns the full response so the frontend can inspect `status`, `sources_rejected`, etc. + +- [ ] **Step 4.3: Commit** + +```bash +git add frontend/lib/lyrics-review/types.ts frontend/lib/api.ts +git commit -m "feat: add SearchLyricsResponse types and searchLyrics API method" +``` + +--- + +## Task 5: SearchLyricsTab Component + +**Files:** +- Create: `frontend/components/lyrics-review/modals/SearchLyricsTab.tsx` + +This task builds the Search tab — artist/title inputs, search button, loading state, and the rejected-sources-with-checkboxes UI for the no-results case. + +- [ ] **Step 5.1: Create the SearchLyricsTab component** + +```tsx +// frontend/components/lyrics-review/modals/SearchLyricsTab.tsx +'use client' + +import { useState } from 'react' +import { Box, TextField, Button, Typography, Checkbox, FormControlLabel, CircularProgress, Alert } from '@mui/material' +import { SearchLyricsResponse, RejectedSource } from '@/lib/lyrics-review/types' + +interface SearchLyricsTabProps { + defaultArtist: string + defaultTitle: string + onSearch: (artist: string, title: string, forceSources: string[]) => Promise + onClose: () => void + disabled?: boolean +} + +export default function SearchLyricsTab({ + defaultArtist, + defaultTitle, + onSearch, + onClose, + disabled = false, +}: SearchLyricsTabProps) { + const [artist, setArtist] = useState(defaultArtist) + const [title, setTitle] = useState(defaultTitle) + const [isSearching, setIsSearching] = useState(false) + const [searchResult, setSearchResult] = useState(null) + const [selectedForce, setSelectedForce] = useState>(new Set()) + const [error, setError] = useState(null) + + const handleSearch = async (forceSources: string[] = []) => { + if (!artist.trim() || !title.trim()) return + + setIsSearching(true) + setError(null) + setSearchResult(null) + setSelectedForce(new Set()) + + try { + const result = await onSearch(artist.trim(), title.trim(), forceSources) + if (result.status === 'success') { + // Success — modal will close via parent + return + } + // No results — show rejected sources + setSearchResult(result) + } catch (e) { + setError(e instanceof Error ? e.message : 'Search failed') + } finally { + setIsSearching(false) + } + } + + const handleForceAdd = async () => { + if (selectedForce.size === 0) return + await handleSearch(Array.from(selectedForce)) + } + + const toggleForceSource = (source: string) => { + setSelectedForce(prev => { + const next = new Set(prev) + if (next.has(source)) { + next.delete(source) + } else { + next.add(source) + } + return next + }) + } + + const rejectedEntries = searchResult + ? Object.entries(searchResult.sources_rejected) + : [] + const notFoundSources = searchResult?.sources_not_found ?? [] + + return ( + + + + Artist + + setArtist(e.target.value)} + disabled={isSearching || disabled} + /> + + + + + Title + + setTitle(e.target.value)} + disabled={isSearching || disabled} + /> + + + + Tip: Try removing "feat.", "remix", or other extras from the title if the + original search didn't find the right lyrics. + + + {error && {error}} + + {searchResult && searchResult.status === 'no_results' && ( + + + No relevant lyrics found + + + These sources were found but had low word match with your transcription. This could mean + wrong song — or the transcription may just be inaccurate. + + + {rejectedEntries.map(([source, info]) => ( + toggleForceSource(source)} + size="small" + /> + } + label={ + + + {source} + + {Math.round(info.relevance * 100)}% word match + + + {info.track_name && ( + + Found: "{info.track_name}" + {info.artist_names ? ` by ${info.artist_names}` : ''} + + )} + + } + /> + ))} + + {notFoundSources.map(source => ( + + + {source} — No results found + + + ))} + + + Select any sources above to add them anyway, or try a different search. + + + )} + + + + {searchResult && selectedForce.size > 0 && ( + + )} + + + + ) +} +``` + +- [ ] **Step 5.2: Commit** + +```bash +git add frontend/components/lyrics-review/modals/SearchLyricsTab.tsx +git commit -m "feat: add SearchLyricsTab component for lyrics provider search" +``` + +--- + +## Task 6: PasteLyricsTab Component + +**Files:** +- Create: `frontend/components/lyrics-review/modals/PasteLyricsTab.tsx` + +Extract the existing paste functionality from AddLyricsModal into its own tab component. + +- [ ] **Step 6.1: Create PasteLyricsTab component** + +```tsx +// frontend/components/lyrics-review/modals/PasteLyricsTab.tsx +'use client' + +import { useState } from 'react' +import { Box, TextField, Button, Typography, CircularProgress, Alert } from '@mui/material' + +interface PasteLyricsTabProps { + onAdd: (source: string, lyrics: string) => Promise + onClose: () => void + disabled?: boolean +} + +export default function PasteLyricsTab({ onAdd, onClose, disabled = false }: PasteLyricsTabProps) { + const [source, setSource] = useState('') + const [lyrics, setLyrics] = useState('') + const [isAdding, setIsAdding] = useState(false) + const [error, setError] = useState(null) + + const handleAdd = async () => { + if (!source.trim() || !lyrics.trim()) return + + setIsAdding(true) + setError(null) + try { + await onAdd(source.trim(), lyrics.trim()) + } catch (e) { + setError(e instanceof Error ? e.message : 'Failed to add lyrics') + setIsAdding(false) + } + } + + return ( + + + + Source Name + + setSource(e.target.value)} + disabled={isAdding || disabled} + /> + + + + + Lyrics + + setLyrics(e.target.value)} + disabled={isAdding || disabled} + sx={{ '& textarea': { fontFamily: 'monospace' } }} + /> + + + {error && {error}} + + + + + + + ) +} +``` + +- [ ] **Step 6.2: Commit** + +```bash +git add frontend/components/lyrics-review/modals/PasteLyricsTab.tsx +git commit -m "feat: add PasteLyricsTab component for manual lyrics entry" +``` + +--- + +## Task 7: Rewrite AddLyricsModal with Tabs + +**Files:** +- Modify: `frontend/components/lyrics-review/modals/AddLyricsModal.tsx` +- Modify: `frontend/components/lyrics-review/LyricsAnalyzer.tsx` + +This task rewrites the modal as a tabbed container and wires up the new search handler in LyricsAnalyzer. + +- [ ] **Step 7.1: Rewrite AddLyricsModal** + +Replace the entire content of `frontend/components/lyrics-review/modals/AddLyricsModal.tsx`: + +```tsx +// frontend/components/lyrics-review/modals/AddLyricsModal.tsx +'use client' + +import { useState } from 'react' +import { Dialog, DialogTitle, DialogContent, IconButton, Tabs, Tab, Box } from '@mui/material' +import CloseIcon from '@mui/icons-material/Close' +import SearchLyricsTab from './SearchLyricsTab' +import PasteLyricsTab from './PasteLyricsTab' +import { SearchLyricsResponse } from '@/lib/lyrics-review/types' + +interface AddLyricsModalProps { + open: boolean + onClose: () => void + onAdd: (source: string, lyrics: string) => Promise + onSearch: (artist: string, title: string, forceSources: string[]) => Promise + defaultArtist: string + defaultTitle: string +} + +export default function AddLyricsModal({ + open, + onClose, + onAdd, + onSearch, + defaultArtist, + defaultTitle, +}: AddLyricsModalProps) { + const [tab, setTab] = useState(0) + + const handleClose = () => { + setTab(0) // Reset to search tab + onClose() + } + + return ( + + + Add Reference Lyrics + + + + + + setTab(v)} sx={{ mb: 2 }}> + + + + + {tab === 0 && ( + + )} + + {tab === 1 && ( + + )} + + + ) +} +``` + +- [ ] **Step 7.2: Update LyricsAnalyzer to wire up search handler** + +In `frontend/components/lyrics-review/LyricsAnalyzer.tsx`: + +Add the import for `SearchLyricsResponse`: + +```typescript +import { SearchLyricsResponse } from '@/lib/lyrics-review/types' +``` + +Add the `handleSearchLyrics` callback near `handleAddLyrics` (around line 1035): + +```typescript + const handleSearchLyrics = useCallback( + async (artist: string, title: string, forceSources: string[]): Promise => { + if (!apiClient) { + return { status: 'no_results', message: 'No API client', sources_added: [], sources_rejected: {}, sources_not_found: [] } + } + + const result = await apiClient.searchLyrics(artist, title, forceSources) + + if (result.status === 'success' && result.data) { + updateDataWithHistory(result.data, 'search lyrics') + } + + return result + }, + [apiClient, updateDataWithHistory], + ) +``` + +Update the `AddLyricsModal` usage (around line 1373) to pass the new props: + +```tsx + setIsAddLyricsModalOpen(false)} + onAdd={handleAddLyrics} + onSearch={handleSearchLyrics} + defaultArtist={data.metadata?.artist || ''} + defaultTitle={data.metadata?.title || ''} +/> +``` + +- [ ] **Step 7.3: Run frontend tests** + +Run: `cd /Users/andrew/Projects/nomadkaraoke/karaoke-gen-reference-lyrics-search/frontend && npm test 2>&1 | tail -30` +Expected: Tests pass. Some tests may need updating if they directly render AddLyricsModal with the old props. Fix any failures by updating the test props to include the new required `onSearch`, `defaultArtist`, `defaultTitle` props. + +- [ ] **Step 7.4: Commit** + +```bash +git add frontend/components/lyrics-review/modals/AddLyricsModal.tsx frontend/components/lyrics-review/LyricsAnalyzer.tsx +git commit -m "feat: rewrite AddLyricsModal with Search/Paste tabs" +``` + +--- + +## Task 8: Reference Panel Empty State + +**Files:** +- Create: `frontend/components/lyrics-review/ReferenceEmptyState.tsx` +- Modify: `frontend/components/lyrics-review/ReferenceView.tsx` + +This task adds the inline add-lyrics UI when no valid reference sources exist. + +- [ ] **Step 8.1: Create ReferenceEmptyState component** + +```tsx +// frontend/components/lyrics-review/ReferenceEmptyState.tsx +'use client' + +import { useState } from 'react' +import { Box, Typography, Tabs, Tab, Alert } from '@mui/material' +import SearchLyricsTab from './modals/SearchLyricsTab' +import PasteLyricsTab from './modals/PasteLyricsTab' +import { SearchLyricsResponse } from '@/lib/lyrics-review/types' + +interface ReferenceEmptyStateProps { + defaultArtist: string + defaultTitle: string + onAdd: (source: string, lyrics: string) => Promise + onSearch: (artist: string, title: string, forceSources: string[]) => Promise +} + +export default function ReferenceEmptyState({ + defaultArtist, + defaultTitle, + onAdd, + onSearch, +}: ReferenceEmptyStateProps) { + const [tab, setTab] = useState(0) + + return ( + + + + No valid reference lyrics found + + + The automatic search didn't find lyrics matching this track. This often happens with + remixes, live versions, or tracks with "feat." in the name. Try searching with a + simplified artist/title, or paste lyrics manually. + + + + setTab(v)} sx={{ mb: 2 }}> + + + + + {tab === 0 && ( + {}} // No-op — not a modal, nothing to close + /> + )} + + {tab === 1 && ( + {}} // No-op + /> + )} + + ) +} +``` + +- [ ] **Step 8.2: Integrate into ReferenceView** + +In `frontend/components/lyrics-review/ReferenceView.tsx`, add the import: + +```typescript +import ReferenceEmptyState from './ReferenceEmptyState' +import { SearchLyricsResponse } from '@/lib/lyrics-review/types' +``` + +Add new props to the component's props interface: + +```typescript + onSearchLyrics?: (artist: string, title: string, forceSources: string[]) => Promise + defaultArtist?: string + defaultTitle?: string +``` + +In the component body, after computing `availableSources`, add a check for the empty state. Find where the reference lyrics segments are rendered and wrap with a conditional: + +```tsx +{availableSources.length === 0 && onAddLyrics && onSearchLyrics ? ( + +) : ( + // ... existing reference lyrics rendering +)} +``` + +- [ ] **Step 8.3: Pass new props through from LyricsAnalyzer** + +In `frontend/components/lyrics-review/LyricsAnalyzer.tsx`, update the `ReferenceView` usage to pass the new props: + +```tsx + +``` + +- [ ] **Step 8.4: Run frontend tests** + +Run: `cd /Users/andrew/Projects/nomadkaraoke/karaoke-gen-reference-lyrics-search/frontend && npm test 2>&1 | tail -30` +Expected: All tests PASS. + +- [ ] **Step 8.5: Commit** + +```bash +git add frontend/components/lyrics-review/ReferenceEmptyState.tsx frontend/components/lyrics-review/ReferenceView.tsx frontend/components/lyrics-review/LyricsAnalyzer.tsx +git commit -m "feat: add inline empty state for Reference panel when no valid sources exist" +``` + +--- + +## Task 9: Full Integration Testing + +**Files:** +- Run existing test suites +- Manual verification with dev server + +- [ ] **Step 9.1: Run full backend test suite** + +Run: `cd /Users/andrew/Projects/nomadkaraoke/karaoke-gen-reference-lyrics-search && python -m pytest tests/ backend/tests/ -v --timeout=120 2>&1 | tail -80` +Expected: All tests PASS. + +- [ ] **Step 9.2: Run full frontend test suite** + +Run: `cd /Users/andrew/Projects/nomadkaraoke/karaoke-gen-reference-lyrics-search/frontend && npm test 2>&1 | tail -50` +Expected: All tests PASS. + +- [ ] **Step 9.3: Run full make test** + +Run: `cd /Users/andrew/Projects/nomadkaraoke/karaoke-gen-reference-lyrics-search && make test 2>&1 | tail -500` +Expected: All tests PASS. + +- [ ] **Step 9.4: Version bump** + +Bump `tool.poetry.version` in `pyproject.toml` for the new feature. + +- [ ] **Step 9.5: Final commit** + +```bash +git add pyproject.toml +git commit -m "chore: bump version for reference lyrics search feature" +``` diff --git a/docs/superpowers/specs/2026-03-29-reference-lyrics-search-design.md b/docs/superpowers/specs/2026-03-29-reference-lyrics-search-design.md new file mode 100644 index 00000000..972b59cb --- /dev/null +++ b/docs/superpowers/specs/2026-03-29-reference-lyrics-search-design.md @@ -0,0 +1,165 @@ +# Reference Lyrics Search & Relevance Filtering + +## Problem + +When a track has a remix, "feat." artist, or unusual naming, the automatic lyrics search during job processing often returns irrelevant results (wrong song entirely) or nothing useful. Users must then manually Google lyrics, copy/paste into the "Add Reference Lyrics" modal — introducing formatting errors and friction. Additionally, irrelevant reference lyrics that do get through skew anchor/gap statistics and confuse correction tooling. + +## Solution + +Three interconnected improvements: + +1. **Relevance filtering in the correction pipeline** — automatically reject reference lyrics that don't match the transcription +2. **Search with alternate artist/title** — let users retry the lyrics search with adjusted metadata from the review UI +3. **Better empty state** — when no valid references exist, show the search/paste UI inline in the Reference panel + +## Design + +### 1. Relevance Filtering in the Correction Pipeline + +**Location:** Inside `LyricsCorrector`, after anchor sequences are found but before corrections are applied. + +**Per-source relevance score:** +``` +relevance = (reference words appearing in anchor sequences) / (total words in reference source) +``` + +Sources below `MIN_REFERENCE_RELEVANCE` (default TBD — see Section 5) are removed from `reference_lyrics` and excluded from gap/correction processing. + +**Applies to all code paths:** +- Initial job processing — irrelevant sources filtered before corrections saved to GCS +- Add lyrics (paste) — pasted text subject to same threshold +- Search lyrics (new endpoint) — results filtered automatically + +**Edge case:** If all sources are filtered out, the job proceeds with zero reference sources. The transcription stands as-is with no corrections. The frontend shows the empty state (Section 4). + +**Metadata:** Filtered-out sources are logged in correction metadata (source name + score) for debugging but not stored in `reference_lyrics`. + +**Override:** The `search-lyrics` endpoint and `add-lyrics` endpoint accept a `force: true` flag to bypass the threshold for user-selected sources. This handles cases where the transcription is poor and a low match % doesn't mean wrong song. + +### 2. New Backend Endpoint — Search Lyrics + +**Endpoint:** `POST /api/review/{job_id}/search-lyrics` + +**Request:** +```json +{ + "artist": "Billie Eilish", + "title": "What Was I Made For", + "force_sources": [] +} +``` + +- `artist` and `title`: Used for the lyrics search across all providers +- `force_sources`: Optional list of source names to add regardless of threshold (for the override flow) + +**Behavior:** +1. Download current `corrections.json` from GCS +2. Create all standard lyrics providers (Genius, Spotify, Musixmatch, LRCLIB) with provided artist/title +3. Fetch lyrics from all providers +4. Run through the correction pipeline with relevance filtering +5. Sources passing threshold are added to `reference_lyrics`, corrections recomputed +6. Sources in `force_sources` bypass the threshold +7. Upload updated `corrections.json` to GCS + +**Response — success (at least one source passed or force-added):** +```json +{ + "status": "success", + "data": { "...full CorrectionData..." }, + "sources_added": ["genius", "lrclib"], + "sources_rejected": { + "spotify": {"relevance": 0.12, "track_name": "What Was I Made For", "artist": "Billie Eilish"}, + "musixmatch": {"relevance": 0.08, "track_name": "What Was I Made For", "artist": "Billie Eilish"} + } +} +``` + +**Response — no valid results:** +```json +{ + "status": "no_results", + "message": "No lyrics sources passed the relevance threshold", + "sources_rejected": { + "genius": {"relevance": 0.15, "track_name": "What Was I Made For", "artist": "Billie Eilish"}, + "spotify": {"relevance": 0.09, "track_name": "What Was I Made For", "artist": "Billie Eilish"} + }, + "sources_not_found": ["lrclib", "musixmatch"] +} +``` + +### 3. Frontend — Add Reference Lyrics Modal Redesign + +The modal gets two tabs: **Search** (default) and **Paste**. + +#### Search Tab + +- Two input fields pre-populated from job metadata: **Artist** and **Title** +- Helpful tip: "Try removing 'feat.', 'remix', or other extras from the title" +- "Search All Providers" button +- **Loading state:** Spinner with "Searching providers..." +- **Success (sources passed threshold):** Modal closes, new sources appear in Reference Lyrics panel +- **No results state:** Modal stays open, shows rejected sources as selectable cards: + - Each card shows: provider name, match %, track name/artist found + - Checkbox on each to select for force-add + - Providers that returned nothing shown grayed out (no checkbox) + - Explanation: "These sources were found but had low word match with your transcription. This could mean wrong song — or the transcription may just be inaccurate." + - "Add Selected" button (disabled until something checked) to force-add + - "Search Again" button to retry with adjusted terms + - Suggestion to try different terms or switch to Paste tab + +#### Paste Tab + +Identical to current modal: Source Name input + Lyrics textarea. No changes to the paste flow — still calls existing `add-lyrics` endpoint, still subject to relevance filtering. If pasted lyrics fail the threshold, the user gets a similar rejection message with option to force-add. + +### 4. Empty State — Reference Panel Inline UI + +When no valid reference sources exist after job processing (all filtered or none found), the Reference Lyrics panel shows: + +1. **Explanation banner:** "No valid reference lyrics found" with context about why (remixes, feat., live versions) +2. **Inline Search/Paste tabbed UI** — same as the modal content but embedded directly in the panel. No "+ New" button click needed. +3. Artist/Title fields pre-populated from job metadata + +Once a valid source is added (via search or paste), the panel switches back to the normal view: source buttons + lyrics display + "+ New" button for the modal. + +### 5. Empirical Threshold Analysis + +**Goal:** Determine the right `MIN_REFERENCE_RELEVANCE` value from real data. + +**Method:** +1. Pull ~30 prod jobs from Firestore that have correction data with reference lyrics +2. Bias sampling toward jobs with mixed results (at least one source with low match %) — pure high-match jobs aren't useful for threshold tuning +3. For each job × source, compute: `(reference words in anchor sequences) / (total reference words)` +4. Generate a report with: job ID, source name, match %, first ~2 lines of transcription and reference (for quick visual comparison) +5. User visually classifies each source as "correct song" or "wrong song" +6. Find the threshold that best separates the two groups + +**Output:** A concrete `MIN_REFERENCE_RELEVANCE` value backed by data. Stored as a constant in the corrector module, easily tunable later. + +**Timing:** Research step early in implementation, before filtering logic is finalized. + +## API Changes Summary + +| Endpoint | Change | +|----------|--------| +| `POST /api/review/{job_id}/search-lyrics` | **New** — search with alternate artist/title | +| `POST /api/review/{job_id}/add-lyrics` | **Modified** — add `force` flag for threshold bypass | + +## Files Likely Modified + +### Backend +- `karaoke_gen/lyrics_transcriber/correction/corrector.py` — relevance filtering after anchor finding +- `karaoke_gen/lyrics_transcriber/correction/anchor_sequence.py` — expose per-source word match stats +- `backend/api/routes/review.py` — new `search-lyrics` endpoint, `force` flag on `add-lyrics` +- `karaoke_gen/lyrics_transcriber/correction/operations.py` — new operation for search-and-add flow + +### Frontend +- `frontend/components/lyrics-review/modals/AddLyricsModal.tsx` — tabbed redesign with Search/Paste +- `frontend/components/lyrics-review/ReferenceView.tsx` — empty state inline UI +- `frontend/lib/api.ts` — new `searchLyrics()` method +- `frontend/lib/lyrics-review/types.ts` — types for search response + +## Out of Scope + +- Changing which providers are used during initial job processing +- Provider-specific configuration (API keys, rate limits) +- Lyrics quality beyond relevance (e.g., formatting, completeness) diff --git a/frontend/components/lyrics-review/LyricsAnalyzer.tsx b/frontend/components/lyrics-review/LyricsAnalyzer.tsx index ad5d3987..a0fb742f 100644 --- a/frontend/components/lyrics-review/LyricsAnalyzer.tsx +++ b/frontend/components/lyrics-review/LyricsAnalyzer.tsx @@ -18,6 +18,7 @@ import { Word, WordClickInfo, ModalContent, + SearchLyricsResponse, } from '@/lib/lyrics-review/types' import type { EditLog, EditLogEntry, EditFeedbackReason } from '@/lib/lyrics-review/types' import type { InstrumentalSelectionType, LyricsReviewApiClient } from '@/lib/api' @@ -71,6 +72,7 @@ interface ApiClient { submitEditLog: (editLog: EditLog) => Promise updateHandlers: (handlers: string[]) => Promise addLyrics: (source: string, lyrics: string) => Promise + searchLyrics?: (artist: string, title: string, forceSources?: string[]) => Promise getAudioUrl: (hash: string) => string generatePreviewVideo: (data: CorrectionData) => Promise<{ status: string @@ -1047,6 +1049,21 @@ export default function LyricsAnalyzer({ [apiClient, updateDataWithHistory] ) + // Search lyrics (reference lyrics search) + const handleSearchLyrics = useCallback( + async (artist: string, title: string, forceSources: string[]): Promise => { + if (!apiClient || !apiClient.searchLyrics) { + return { status: 'no_results', message: 'No API client', sources_added: [], sources_rejected: {}, sources_not_found: [] } + } + const result = await apiClient.searchLyrics(artist, title, forceSources) + if (result.status === 'success' && result.data) { + updateDataWithHistory(result.data, 'search lyrics') + } + return result + }, + [apiClient, updateDataWithHistory], + ) + // Find/replace const handleFindReplace = useCallback( ( @@ -1250,6 +1267,10 @@ export default function LyricsAnalyzer({ corrected_segments={data.corrected_segments} corrections={data.corrections} onAddLyrics={() => setIsAddLyricsModalOpen(true)} + onAddLyricsInline={handleAddLyrics} + onSearchLyrics={handleSearchLyrics} + defaultArtist={data.metadata?.artist || ''} + defaultTitle={data.metadata?.title || ''} /> @@ -1374,6 +1395,9 @@ export default function LyricsAnalyzer({ open={isAddLyricsModalOpen} onClose={() => setIsAddLyricsModalOpen(false)} onAdd={handleAddLyrics} + onSearch={handleSearchLyrics} + defaultArtist={data.metadata?.artist || ''} + defaultTitle={data.metadata?.title || ''} /> Promise + onSearch: (artist: string, title: string, forceSources: string[]) => Promise +} + +export default function ReferenceEmptyState({ + defaultArtist, + defaultTitle, + onAdd, + onSearch, +}: ReferenceEmptyStateProps) { + // onClose is a no-op here — it's inline, not a modal + const handleClose = () => {} + + return ( +
+ + + + No reference lyrics were found for this song. Search all configured lyrics providers or + paste lyrics manually to enable gap correction. + + + + + + + Search + + + Paste + + + + + + + + + + + +
+ ) +} diff --git a/frontend/components/lyrics-review/ReferenceView.tsx b/frontend/components/lyrics-review/ReferenceView.tsx index f9e4fc72..4ce85a0a 100644 --- a/frontend/components/lyrics-review/ReferenceView.tsx +++ b/frontend/components/lyrics-review/ReferenceView.tsx @@ -9,6 +9,7 @@ import { calculateReferenceLinePositions } from '@/lib/lyrics-review/utils/refer import { getWordsFromIds } from '@/lib/lyrics-review/utils/wordUtils' import { SourceSelector } from './shared/SourceSelector' import { HighlightedText } from './shared/HighlightedText' +import ReferenceEmptyState from './ReferenceEmptyState' export default function ReferenceView({ referenceSources, @@ -24,6 +25,10 @@ export default function ReferenceView({ gaps, corrections, onAddLyrics, + onAddLyricsInline, + onSearchLyrics, + defaultArtist = '', + defaultTitle = '', }: ReferenceViewProps) { const availableSources = useMemo(() => Object.keys(referenceSources), [referenceSources]) @@ -180,6 +185,15 @@ export default function ReferenceView({ /> + {availableSources.length === 0 && onAddLyricsInline && onSearchLyrics && ( + + )} +
{currentSourceSegments.map((segment, index) => (
diff --git a/frontend/components/lyrics-review/modals/AddLyricsModal.tsx b/frontend/components/lyrics-review/modals/AddLyricsModal.tsx index da603eb0..7cce3861 100644 --- a/frontend/components/lyrics-review/modals/AddLyricsModal.tsx +++ b/frontend/components/lyrics-review/modals/AddLyricsModal.tsx @@ -1,50 +1,34 @@ 'use client' import { useState } from 'react' -import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogFooter } from '@/components/ui/dialog' -import { Button } from '@/components/ui/button' -import { Input } from '@/components/ui/input' -import { Textarea } from '@/components/ui/textarea' -import { Label } from '@/components/ui/label' -import { Loader2 } from 'lucide-react' +import { Dialog, DialogContent, DialogHeader, DialogTitle } from '@/components/ui/dialog' +import { Tabs, TabsList, TabsTrigger, TabsContent } from '@/components/ui/tabs' +import { SearchLyricsResponse } from '@/lib/lyrics-review/types' +import SearchLyricsTab from './SearchLyricsTab' +import PasteLyricsTab from './PasteLyricsTab' interface AddLyricsModalProps { open: boolean onClose: () => void onAdd: (source: string, lyrics: string) => Promise + onSearch: (artist: string, title: string, forceSources: string[]) => Promise + defaultArtist: string + defaultTitle: string } -export default function AddLyricsModal({ open, onClose, onAdd }: AddLyricsModalProps) { - const [source, setSource] = useState('') - const [lyrics, setLyrics] = useState('') - const [isAdding, setIsAdding] = useState(false) - const [error, setError] = useState(null) - - const handleAdd = async () => { - if (!source.trim() || !lyrics.trim()) return - - setIsAdding(true) - setError(null) - - try { - await onAdd(source.trim(), lyrics.trim()) - setSource('') - setLyrics('') - onClose() - } catch (err) { - setError(err instanceof Error ? err.message : 'Failed to add lyrics') - } finally { - setIsAdding(false) - } - } +export default function AddLyricsModal({ + open, + onClose, + onAdd, + onSearch, + defaultArtist, + defaultTitle, +}: AddLyricsModalProps) { + const [activeTab, setActiveTab] = useState('search') const handleClose = () => { - if (!isAdding) { - setSource('') - setLyrics('') - setError(null) - onClose() - } + setActiveTab('search') + onClose() } return ( @@ -54,52 +38,29 @@ export default function AddLyricsModal({ open, onClose, onAdd }: AddLyricsModalP Add Reference Lyrics -
-
- - setSource(e.target.value)} - placeholder="e.g., manual, genius, azlyrics..." - disabled={isAdding} + + + + Search + + + Paste + + + + + -
+ -
- -