feat: Reference lyrics search with relevance filtering (#632)

## 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) <noreply@anthropic.com>
This commit is contained in:
Andrew Beveridge ☄️andClaude Opus 4.6 authored and GitHub committed 2026-03-30 00:25:47 +00:00
1 parent 5a5ee4a780
commit 591c050545
25 files changed
+7093 -97

No files matched your search

+1
View File
@@ -232,3 +232,4 @@ flacfetch
# Test output directories
Rick Astley*/
.superpowers/
+152 -4
View File
@@ -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,
+551
View File
@@ -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
+55
View File
@@ -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": <CorrectionData> }`.
#### 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}`.
+8
View File
@@ -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.
File diff suppressed because it is too large. Load diff
@@ -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)
@@ -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<void>
updateHandlers: (handlers: string[]) => Promise<CorrectionData>
addLyrics: (source: string, lyrics: string) => Promise<CorrectionData>
searchLyrics?: (artist: string, title: string, forceSources?: string[]) => Promise<SearchLyricsResponse>
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<SearchLyricsResponse> => {
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 || ''}
/>
</div>
@@ -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 || ''}
/>
<FindReplaceModal
@@ -0,0 +1,61 @@
'use client'
import { Alert, AlertDescription } from '@/components/ui/alert'
import { Tabs, TabsList, TabsTrigger, TabsContent } from '@/components/ui/tabs'
import { Info } from 'lucide-react'
import { SearchLyricsResponse } from '@/lib/lyrics-review/types'
import SearchLyricsTab from './modals/SearchLyricsTab'
import PasteLyricsTab from './modals/PasteLyricsTab'
interface ReferenceEmptyStateProps {
defaultArtist: string
defaultTitle: string
onAdd: (source: string, lyrics: string) => Promise<void>
onSearch: (artist: string, title: string, forceSources: string[]) => Promise<SearchLyricsResponse>
}
export default function ReferenceEmptyState({
defaultArtist,
defaultTitle,
onAdd,
onSearch,
}: ReferenceEmptyStateProps) {
// onClose is a no-op here — it's inline, not a modal
const handleClose = () => {}
return (
<div className="space-y-4 p-2">
<Alert>
<Info className="h-4 w-4" />
<AlertDescription>
No reference lyrics were found for this song. Search all configured lyrics providers or
paste lyrics manually to enable gap correction.
</AlertDescription>
</Alert>
<Tabs defaultValue="search">
<TabsList className="w-full">
<TabsTrigger value="search" className="flex-1">
Search
</TabsTrigger>
<TabsTrigger value="paste" className="flex-1">
Paste
</TabsTrigger>
</TabsList>
<TabsContent value="search">
<SearchLyricsTab
defaultArtist={defaultArtist}
defaultTitle={defaultTitle}
onSearch={onSearch}
onClose={handleClose}
/>
</TabsContent>
<TabsContent value="paste">
<PasteLyricsTab onAdd={onAdd} onClose={handleClose} />
</TabsContent>
</Tabs>
</div>
)
}
@@ -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({
/>
</div>
{availableSources.length === 0 && onAddLyricsInline && onSearchLyrics && (
<ReferenceEmptyState
defaultArtist={defaultArtist}
defaultTitle={defaultTitle}
onAdd={onAddLyricsInline}
onSearch={onSearchLyrics}
/>
)}
<div className="flex flex-col gap-0.5">
{currentSourceSegments.map((segment, index) => (
<div key={index} className="flex items-start w-full hover:bg-muted/50 transition-colors">
@@ -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<void>
onSearch: (artist: string, title: string, forceSources: string[]) => Promise<SearchLyricsResponse>
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<string | null>(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
<DialogTitle>Add Reference Lyrics</DialogTitle>
</DialogHeader>
<div className="space-y-4">
<div className="space-y-2">
<Label htmlFor="source">Source Name</Label>
<Input
id="source"
value={source}
onChange={(e) => setSource(e.target.value)}
placeholder="e.g., manual, genius, azlyrics..."
disabled={isAdding}
<Tabs value={activeTab} onValueChange={setActiveTab}>
<TabsList className="w-full">
<TabsTrigger value="search" className="flex-1">
Search
</TabsTrigger>
<TabsTrigger value="paste" className="flex-1">
Paste
</TabsTrigger>
</TabsList>
<TabsContent value="search">
<SearchLyricsTab
defaultArtist={defaultArtist}
defaultTitle={defaultTitle}
onSearch={onSearch}
onClose={handleClose}
/>
</div>
</TabsContent>
<div className="space-y-2">
<Label htmlFor="lyrics">Lyrics</Label>
<Textarea
id="lyrics"
value={lyrics}
onChange={(e) => setLyrics(e.target.value)}
placeholder="Paste lyrics here..."
rows={10}
disabled={isAdding}
className="font-mono text-sm"
/>
</div>
{error && <p className="text-sm text-destructive">{error}</p>}
</div>
<DialogFooter>
<Button variant="outline" onClick={handleClose} disabled={isAdding}>
Cancel
</Button>
<Button
onClick={handleAdd}
disabled={isAdding || !source.trim() || !lyrics.trim()}
>
{isAdding ? (
<>
<Loader2 className="h-4 w-4 mr-2 animate-spin" />
Adding...
</>
) : (
'Add Lyrics'
)}
</Button>
</DialogFooter>
<TabsContent value="paste">
<PasteLyricsTab onAdd={onAdd} onClose={handleClose} />
</TabsContent>
</Tabs>
</DialogContent>
</Dialog>
)
@@ -0,0 +1,101 @@
'use client'
import { useState } from 'react'
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'
interface PasteLyricsTabProps {
onAdd: (source: string, lyrics: string) => Promise<void>
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<string | null>(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)
}
}
const handleCancel = () => {
if (!isAdding) {
setSource('')
setLyrics('')
setError(null)
onClose()
}
}
return (
<div className="space-y-4">
<div className="space-y-2">
<Label htmlFor="paste-source">Source Name</Label>
<Input
id="paste-source"
value={source}
onChange={(e) => setSource(e.target.value)}
placeholder="e.g., manual, genius, azlyrics..."
disabled={isAdding || disabled}
/>
</div>
<div className="space-y-2">
<Label htmlFor="paste-lyrics">Lyrics</Label>
<Textarea
id="paste-lyrics"
value={lyrics}
onChange={(e) => setLyrics(e.target.value)}
placeholder="Paste lyrics here..."
rows={10}
disabled={isAdding || disabled}
className="font-mono text-sm"
/>
</div>
{error && <p className="text-sm text-destructive">{error}</p>}
<div className="flex justify-end gap-2 pt-2">
<Button variant="outline" onClick={handleCancel} disabled={isAdding || disabled}>
Cancel
</Button>
<Button
onClick={handleAdd}
disabled={isAdding || disabled || !source.trim() || !lyrics.trim()}
>
{isAdding ? (
<>
<Loader2 className="h-4 w-4 mr-2 animate-spin" />
Adding...
</>
) : (
'Add Lyrics'
)}
</Button>
</div>
</div>
)
}
@@ -0,0 +1,216 @@
'use client'
import { useState } from 'react'
import { Button } from '@/components/ui/button'
import { Input } from '@/components/ui/input'
import { Label } from '@/components/ui/label'
import { Checkbox } from '@/components/ui/checkbox'
import { Spinner } from '@/components/ui/spinner'
import { Alert, AlertDescription } from '@/components/ui/alert'
import { SearchLyricsResponse, RejectedSource } from '@/lib/lyrics-review/types'
interface SearchLyricsTabProps {
defaultArtist: string
defaultTitle: string
onSearch: (artist: string, title: string, forceSources: string[]) => Promise<SearchLyricsResponse>
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<SearchLyricsResponse | null>(null)
const [selectedForce, setSelectedForce] = useState<Set<string>>(new Set())
const [error, setError] = useState<string | null>(null)
const handleSearch = async (forceSources: string[] = []) => {
if (!artist.trim() || !title.trim()) return
setIsSearching(true)
setError(null)
try {
const result = await onSearch(artist.trim(), title.trim(), forceSources)
if (result.status === 'success') {
// Success: parent handles closing and updating data
onClose()
} else {
// No results: store result to show rejected sources
setSearchResult(result)
setSelectedForce(new Set())
}
} catch (err) {
setError(err instanceof Error ? err.message : 'Search failed')
} finally {
setIsSearching(false)
}
}
const handleForceAdd = async () => {
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 (
<div className="space-y-4">
<div className="space-y-2">
<Label htmlFor="search-artist">Artist</Label>
<Input
id="search-artist"
value={artist}
onChange={(e) => setArtist(e.target.value)}
placeholder="Artist name"
disabled={isSearching || disabled}
/>
</div>
<div className="space-y-2">
<Label htmlFor="search-title">Title</Label>
<Input
id="search-title"
value={title}
onChange={(e) => setTitle(e.target.value)}
placeholder="Song title"
disabled={isSearching || disabled}
/>
</div>
<p className="text-xs text-muted-foreground">
Searches all configured lyrics providers (Genius, AZLyrics, etc.) and adds any
results that are a close match to this song.
</p>
{error && (
<Alert variant="destructive">
<AlertDescription>{error}</AlertDescription>
</Alert>
)}
{searchResult && searchResult.status === 'no_results' && (
<div className="space-y-3">
<Alert>
<AlertDescription>
{searchResult.message || 'No matching lyrics found across all providers.'}
</AlertDescription>
</Alert>
{notFoundSources.length > 0 && (
<p className="text-xs text-muted-foreground">
Not found: {notFoundSources.join(', ')}
</p>
)}
{rejectedEntries.length > 0 && (
<div className="space-y-2">
<p className="text-sm font-medium">
Low-confidence results — select any to force-add:
</p>
{rejectedEntries.map(([source, info]: [string, RejectedSource]) => (
<div
key={source}
className="flex items-start gap-3 rounded-md border p-3 text-sm"
>
<Checkbox
id={`force-${source}`}
checked={selectedForce.has(source)}
onCheckedChange={() => toggleForceSource(source)}
disabled={isSearching || disabled}
/>
<div className="flex-1 space-y-1">
<label
htmlFor={`force-${source}`}
className="cursor-pointer font-medium"
>
{source}
</label>
<p className="text-muted-foreground">
&ldquo;{info.track_name}&rdquo; by {info.artist_names}
</p>
<p className="text-muted-foreground">
Match: {info.matched_words}/{info.total_words} words (
{Math.round(info.relevance * 100)}% relevance)
</p>
</div>
</div>
))}
</div>
)}
</div>
)}
<div className="flex justify-end gap-2 pt-2">
{searchResult && searchResult.status === 'no_results' ? (
<>
<Button
variant="outline"
onClick={() => handleSearch()}
disabled={isSearching || disabled || !artist.trim() || !title.trim()}
>
{isSearching ? (
<>
<Spinner className="mr-2 h-4 w-4" />
Searching...
</>
) : (
'Search Again'
)}
</Button>
{rejectedEntries.length > 0 && (
<Button
onClick={handleForceAdd}
disabled={isSearching || disabled || selectedForce.size === 0}
>
{isSearching ? (
<>
<Spinner className="mr-2 h-4 w-4" />
Adding...
</>
) : (
`Add Selected (${selectedForce.size})`
)}
</Button>
)}
</>
) : (
<Button
onClick={() => handleSearch()}
disabled={isSearching || disabled || !artist.trim() || !title.trim()}
>
{isSearching ? (
<>
<Spinner className="mr-2 h-4 w-4" />
Searching...
</>
) : (
'Search All Providers'
)}
</Button>
)}
</div>
</div>
)
}
@@ -1,4 +1,6 @@
export { default as AddLyricsModal } from './AddLyricsModal'
export { default as PasteLyricsTab } from './PasteLyricsTab'
export { default as SearchLyricsTab } from './SearchLyricsTab'
export { default as AIFeedbackModal } from './AIFeedbackModal'
export { default as CorrectionAnnotationModal } from './CorrectionAnnotationModal'
export { default as EditModal } from './EditModal'
+21 -1
View File
@@ -4,7 +4,7 @@
import type { VideoThemeSummary, VideoThemeDetail, ThemesListResponse, ThemeDetailResponse, ColorOverrides } from './video-themes';
import type { MagicLinkResponse, VerifyMagicLinkResponse, UserProfileResponse } from './types';
import type { CorrectionData, CorrectionAnnotation, EditLog } from './lyrics-review/types';
import type { CorrectionData, CorrectionAnnotation, EditLog, SearchLyricsResponse } from './lyrics-review/types';
// In development, use relative URLs to go through Next.js proxy (avoids CORS)
// In production (static export), use the full backend URL
@@ -2732,6 +2732,7 @@ export interface LyricsReviewApiClient {
submitEditLog: (editLog: EditLog) => Promise<void>
updateHandlers: (handlers: string[]) => Promise<CorrectionData>
addLyrics: (source: string, lyrics: string) => Promise<CorrectionData>
searchLyrics: (artist: string, title: string, forceSources?: string[]) => Promise<SearchLyricsResponse>
getAudioUrl: (hash: string) => string
generatePreviewVideo: (data: CorrectionData) => Promise<{
status: string
@@ -2839,6 +2840,25 @@ export function createLyricsReviewApiClient(jobId: string): LyricsReviewApiClien
return result.data
},
/**
* Search for lyrics from configured providers
*/
async searchLyrics(artist: string, title: string, forceSources: string[] = []): Promise<SearchLyricsResponse> {
const response = await fetch(`${API_BASE_URL}/api/review/${jobId}/search-lyrics`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
...getAuthHeaders()
},
body: JSON.stringify({
artist,
title,
force_sources: forceSources,
}),
})
return handleResponse<SearchLyricsResponse>(response)
},
/**
* Get audio URL for playback
*/
+23
View File
@@ -122,6 +122,8 @@ export interface CorrectionData {
audio_hash?: string
available_handlers?: CorrectionHandler[]
enabled_handlers?: string[]
artist?: string
title?: string
}
correction_steps: CorrectionStep[]
word_id_map: Record<string, string>
@@ -390,6 +392,27 @@ export interface ReferenceViewProps extends BaseViewProps {
corrected_segments: LyricsSegment[]
corrections: WordCorrection[]
onAddLyrics?: () => void
onAddLyricsInline?: (source: string, lyrics: string) => Promise<void>
onSearchLyrics?: (artist: string, title: string, forceSources: string[]) => Promise<SearchLyricsResponse>
defaultArtist?: string
defaultTitle?: string
}
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<string, RejectedSource>
sources_not_found: string[]
}
export interface HighlightedTextProps extends BaseViewProps {
@@ -24,6 +24,7 @@ from karaoke_gen.lyrics_transcriber.types import (
Word,
)
from karaoke_gen.lyrics_transcriber.correction.anchor_sequence import AnchorSequenceFinder
from karaoke_gen.lyrics_transcriber.correction.relevance import filter_irrelevant_sources
from karaoke_gen.lyrics_transcriber.correction.handlers.base import GapCorrectionHandler
from karaoke_gen.lyrics_transcriber.correction.handlers.extend_anchor import ExtendAnchorHandler
from karaoke_gen.lyrics_transcriber.utils.word_utils import WordUtils
@@ -142,9 +143,6 @@ class LyricsCorrector:
self.logger.error("No transcription results available")
raise ValueError("No primary transcription data available")
# Store reference lyrics for use in word map
self.reference_lyrics = lyrics_results
# Get primary transcription
primary_transcription_result = sorted(transcription_results, key=lambda x: x.priority)[0]
primary_transcription = primary_transcription_result.result
@@ -152,12 +150,41 @@ class LyricsCorrector:
# Find anchor sequences and gaps
self.logger.debug("Finding anchor sequences and gaps")
rejected_sources = {}
with create_span("lyrics_corrector.find_anchors_and_gaps") as anchor_span:
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
# Store filtered reference lyrics for use in word map
self.reference_lyrics = lyrics_results
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))
# Store anchor sequences for use in correction handlers
self._anchor_sequences = anchor_sequences
@@ -199,6 +226,19 @@ class LyricsCorrector:
"agentic_routing": "agentic" if agentic_enabled else "rule-based",
}
# 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()
}
# Pass through primary transcription metadata (e.g., AudioShake task_id, asset_id)
if primary_transcription.metadata:
result_metadata["transcription_metadata"] = primary_transcription.metadata
@@ -14,13 +14,14 @@ These operations handle dynamic updates to correction results including:
import json
import hashlib
import logging
import os
from typing import Dict, Any, List, Optional
from pathlib import Path
from karaoke_gen.lyrics_transcriber.types import (
CorrectionResult,
WordCorrection,
LyricsSegment,
CorrectionResult,
WordCorrection,
LyricsSegment,
Word,
TranscriptionResult,
TranscriptionData,
@@ -28,10 +29,76 @@ from karaoke_gen.lyrics_transcriber.types import (
)
from karaoke_gen.lyrics_transcriber.correction.corrector import LyricsCorrector
from karaoke_gen.lyrics_transcriber.lyrics.user_input_provider import UserInputProvider
from karaoke_gen.lyrics_transcriber.lyrics.base_lyrics_provider import LyricsProviderConfig, BaseLyricsProvider
from karaoke_gen.lyrics_transcriber.output.generator import OutputGenerator
from karaoke_gen.lyrics_transcriber.core.config import OutputConfig
def create_lyrics_providers(
cache_dir: Optional[str] = None,
logger: Optional[logging.Logger] = None,
) -> List[BaseLyricsProvider]:
"""
Create lyrics providers based on available environment variables.
Reads API keys from environment and returns a list of providers that are
configured and ready to use. Providers with missing required credentials
are silently skipped.
Args:
cache_dir: Optional cache directory for provider caching.
logger: Optional logger instance.
Returns:
List of configured BaseLyricsProvider instances.
"""
if not logger:
logger = logging.getLogger(__name__)
# Import provider classes here to keep them mockable in tests
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
genius_api_token = os.environ.get("GENIUS_API_KEY")
rapidapi_key = os.environ.get("RAPIDAPI_KEY")
spotify_cookie = os.environ.get("SPOTIFY_COOKIE_SP_DC")
config = LyricsProviderConfig(
genius_api_token=genius_api_token,
rapidapi_key=rapidapi_key,
spotify_cookie=spotify_cookie,
cache_dir=cache_dir,
)
providers: List[BaseLyricsProvider] = []
if genius_api_token or rapidapi_key:
providers.append(GeniusProvider(config=config, logger=logger))
logger.info("GeniusProvider configured")
else:
logger.info("Skipping GeniusProvider: no GENIUS_API_KEY or RAPIDAPI_KEY")
if spotify_cookie or rapidapi_key:
providers.append(SpotifyProvider(config=config, logger=logger))
logger.info("SpotifyProvider configured")
else:
logger.info("Skipping SpotifyProvider: no SPOTIFY_COOKIE_SP_DC or RAPIDAPI_KEY")
if rapidapi_key:
providers.append(MusixmatchProvider(config=config, logger=logger))
logger.info("MusixmatchProvider configured")
else:
logger.info("Skipping MusixmatchProvider: no RAPIDAPI_KEY")
# LRCLIB needs no API key
providers.append(LRCLIBProvider(config=config, logger=logger))
logger.info("LRCLIBProvider configured")
return providers
class CorrectionOperations:
"""Static methods for common correction operations."""
@@ -104,21 +171,24 @@ class CorrectionOperations:
source: str,
lyrics_text: str,
cache_dir: str,
logger: Optional[logging.Logger] = None
logger: Optional[logging.Logger] = None,
force: bool = False,
) -> CorrectionResult:
"""
Add a new lyrics source and rerun correction.
Args:
correction_result: Current correction result
source: Name of the new lyrics source
lyrics_text: The lyrics text content
cache_dir: Cache directory for correction operations
logger: Optional logger instance
force: If True and the source is rejected by the relevance filter, re-add
it to reference_lyrics anyway so it is preserved in the result.
Returns:
Updated CorrectionResult with new lyrics source and corrections
Raises:
ValueError: If source name is already in use or inputs are invalid
"""
@@ -194,10 +264,167 @@ class CorrectionOperations:
# Restore audio hash
if audio_hash:
updated_result.metadata["audio_hash"] = audio_hash
# If force=True and the source was rejected by the relevance filter, put it back
# so the frontend can see it and the user's intent is respected.
if force:
rejected_sources = updated_result.metadata.get("rejected_sources", {})
if source in rejected_sources:
logger.info(
f"force=True: re-adding rejected source '{source}' to reference_lyrics"
)
updated_result.reference_lyrics[source] = lyrics_data
logger.info(f"Successfully added lyrics source '{source}' and updated corrections")
return updated_result
@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,
) -> Dict[str, Any]:
"""
Search for lyrics from all configured providers and run correction.
Fetches lyrics from Genius, Spotify, Musixmatch, and LRCLIB using the
supplied artist/title, then runs them through the correction pipeline
(which includes the relevance filter from Task 2).
Args:
correction_result: Current correction result (provides transcription data).
artist: Artist name to search for.
title: Song title to search for.
cache_dir: Cache directory for providers and correction operations.
force_sources: Optional list of provider names whose results should bypass
the relevance filter and be included regardless of score.
logger: Optional logger instance.
Returns:
Dict with keys:
- ``updated_result``: Updated CorrectionResult (or None if nothing passed).
- ``sources_added``: List of source names that passed the filter.
- ``sources_rejected``: Dict mapping rejected source names to relevance info.
- ``sources_not_found``: List of provider names that returned no lyrics.
"""
if not logger:
logger = logging.getLogger(__name__)
force_sources = force_sources or []
logger.info(f"Searching lyrics for artist='{artist}' title='{title}'")
# Store existing audio hash
audio_hash = correction_result.metadata.get("audio_hash") if correction_result.metadata else None
# Create and query all configured providers
providers = create_lyrics_providers(cache_dir=cache_dir, logger=logger)
new_lyrics: Dict[str, LyricsData] = {}
sources_not_found: List[str] = []
for provider in providers:
provider_name = provider.get_name()
# Skip providers whose source name is already in the existing reference_lyrics
if provider_name in correction_result.reference_lyrics:
logger.info(f"Skipping provider '{provider_name}': already present in reference_lyrics")
continue
try:
lyrics_data = provider.fetch_lyrics(artist, title)
if lyrics_data:
new_lyrics[provider_name] = lyrics_data
logger.info(f"Provider '{provider_name}' returned lyrics")
else:
sources_not_found.append(provider_name)
logger.info(f"Provider '{provider_name}' found no lyrics")
except Exception as e:
logger.warning(f"Provider '{provider_name}' raised an error: {e}")
sources_not_found.append(provider_name)
if not new_lyrics:
logger.info("No new lyrics found from any provider")
return {
"updated_result": None,
"sources_added": [],
"sources_rejected": {},
"sources_not_found": sources_not_found,
}
# Combine new lyrics with existing reference_lyrics
combined_lyrics = correction_result.reference_lyrics.copy()
combined_lyrics.update(new_lyrics)
# Create TranscriptionData from original segments
transcription_data = TranscriptionData(
segments=correction_result.original_segments,
words=[word for segment in correction_result.original_segments for word in segment.words],
text="\n".join(segment.text for segment in correction_result.original_segments),
source="original",
)
# Get currently enabled handlers from metadata
enabled_handlers = None
if correction_result.metadata:
enabled_handlers = correction_result.metadata.get("enabled_handlers")
# Run correction (relevance filter is automatic inside corrector.run)
logger.info(f"Running correction with {len(combined_lyrics)} combined reference sources")
corrector = LyricsCorrector(
cache_dir=cache_dir,
enabled_handlers=enabled_handlers,
logger=logger,
)
updated_result = corrector.run(
transcription_results=[TranscriptionResult(name="original", priority=1, result=transcription_data)],
lyrics_results=combined_lyrics,
metadata=correction_result.metadata,
)
# Update metadata with handler state
if not updated_result.metadata:
updated_result.metadata = {}
updated_result.metadata.update({
"available_handlers": corrector.all_handlers,
"enabled_handlers": [getattr(handler, "name", handler.__class__.__name__) for handler in corrector.handlers],
})
# Restore audio hash
if audio_hash:
updated_result.metadata["audio_hash"] = audio_hash
# Determine which of the *new* sources were accepted vs rejected
rejected_sources_meta = updated_result.metadata.get("rejected_sources", {})
sources_added = [name for name in new_lyrics if name not in rejected_sources_meta]
sources_rejected = {name: info for name, info in rejected_sources_meta.items() if name in new_lyrics}
# Re-add force_sources that were rejected
for source_name in force_sources:
if source_name in sources_rejected and source_name in new_lyrics:
logger.info(
f"force_sources: re-adding rejected source '{source_name}' to reference_lyrics"
)
updated_result.reference_lyrics[source_name] = new_lyrics[source_name]
sources_added.append(source_name)
del sources_rejected[source_name]
logger.info(
f"Search complete: added={sources_added}, "
f"rejected={list(sources_rejected.keys())}, "
f"not_found={sources_not_found}"
)
return {
"updated_result": updated_result,
"sources_added": sources_added,
"sources_rejected": sources_rejected,
"sources_not_found": sources_not_found,
}
@staticmethod
def update_correction_handlers(
correction_result: CorrectionResult,
@@ -0,0 +1,112 @@
"""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 # Empirical: wrong-song max 3.5%, correct-song min 26.8%
@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.
# Handle both AnchorSequence and ScoredAnchor (which wraps AnchorSequence).
all_ref_word_ids = set()
for anchor_or_scored in anchor_sequences:
anchor = getattr(anchor_or_scored, "anchor", anchor_or_scored)
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
+1 -1
View File
@@ -1,6 +1,6 @@
[tool.poetry]
name = "karaoke-gen"
version = "0.153.7"
version = "0.154.0"
description = "Generate karaoke videos with synchronized lyrics. Handles the entire process from downloading audio and lyrics to creating the final video with title screens."
authors = ["Andrew Beveridge <andrew@beveridge.uk>"]
license = "MIT"
+369
View File
@@ -0,0 +1,369 @@
#!/usr/bin/env python3
"""
Empirical threshold analysis: measure per-source reference relevance scores
from production jobs that have corrections.json files.
Relevance score = (reference words appearing in anchor sequences) / (total reference words)
This helps determine appropriate thresholds for filtering low-quality reference
sources before running anchor sequence detection.
Usage:
python scripts/analyze_reference_relevance.py
python scripts/analyze_reference_relevance.py --limit 50
python scripts/analyze_reference_relevance.py --output results.json
Requires:
- google-cloud-firestore
- google-cloud-storage
- GOOGLE_APPLICATION_CREDENTIALS or gcloud auth application-default login
"""
import argparse
import io
import json
import logging
import sys
from collections import defaultdict
from typing import Optional
from google.cloud import firestore, storage
logging.basicConfig(
level=logging.INFO,
format="%(asctime)s %(levelname)s %(message)s",
)
logger = logging.getLogger(__name__)
PROJECT = "nomadkaraoke"
GCS_BUCKET = "karaoke-gen-storage-nomadkaraoke"
# ---------------------------------------------------------------------------
# Firestore helpers
# ---------------------------------------------------------------------------
def fetch_candidate_jobs(db: firestore.Client, limit: int) -> list[dict]:
"""
Pull jobs that have a corrections file URL from Firestore.
We over-fetch (up to 3x the limit) so we can bias toward jobs where at
least one source has a low match score (mixed results). We filter down
after computing scores.
"""
logger.info("Querying Firestore for completed jobs with correction data...")
# Query jobs that are complete and have lyrics corrections URL stored
query = (
db.collection("jobs")
.where("status", "==", "complete")
.order_by("created_at", direction=firestore.Query.DESCENDING)
.limit(limit * 3)
)
jobs = []
for doc in query.stream():
data = doc.to_dict()
data["_job_id"] = doc.id
# Require a corrections URL
corrections_url = _get_corrections_url(data)
if corrections_url:
data["_corrections_url"] = corrections_url
jobs.append(data)
logger.info(f"Found {len(jobs)} jobs with corrections URL")
return jobs
def _get_corrections_url(job_data: dict) -> Optional[str]:
"""Extract the GCS path for the corrections.json from a Firestore job doc."""
file_urls = job_data.get("file_urls", {})
lyrics = file_urls.get("lyrics", {})
corrections = lyrics.get("corrections")
if corrections:
return corrections
return None
# ---------------------------------------------------------------------------
# GCS helpers
# ---------------------------------------------------------------------------
def download_corrections(gcs_client: storage.Client, gcs_path: str) -> Optional[dict]:
"""
Download and parse a corrections.json from GCS.
gcs_path may be:
- A full gs:// URL: gs://karaoke-gen-outputs/jobs/.../lyrics/corrections.json
- A bare object path: jobs/.../lyrics/corrections.json
"""
if gcs_path.startswith("gs://"):
# Strip gs://<bucket>/
parts = gcs_path[5:].split("/", 1)
bucket_name = parts[0]
blob_path = parts[1] if len(parts) > 1 else ""
else:
bucket_name = GCS_BUCKET
blob_path = gcs_path
try:
bucket = gcs_client.bucket(bucket_name)
blob = bucket.blob(blob_path)
content = blob.download_as_bytes()
return json.loads(content)
except Exception as e:
logger.warning(f"Failed to download {gcs_path}: {e}")
return None
# ---------------------------------------------------------------------------
# Relevance computation
# ---------------------------------------------------------------------------
def compute_relevance_scores(corrections: dict) -> dict[str, dict]:
"""
Compute per-source relevance scores from a corrections.json dict.
Relevance = (# reference words that appear in at least one anchor) /
(total words in that source's reference lyrics)
Returns a dict keyed by source name, each value being:
{
"total_words": int,
"anchored_words": int,
"score": float,
}
"""
reference_lyrics: dict = corrections.get("reference_lyrics", {})
anchor_sequences: list = corrections.get("anchor_sequences", [])
# Build set of anchored word IDs per source
anchored_ids: dict[str, set] = defaultdict(set)
for anchor in anchor_sequences:
ref_word_ids: dict = anchor.get("reference_word_ids", {})
for source, word_ids in ref_word_ids.items():
anchored_ids[source].update(word_ids)
scores = {}
for source, ref_data in reference_lyrics.items():
if not ref_data:
continue
# Count total words in this source
total_words = 0
for segment in ref_data.get("segments", []):
total_words += len(segment.get("words", []))
if total_words == 0:
scores[source] = {"total_words": 0, "anchored_words": 0, "score": 0.0}
continue
anchored_count = len(anchored_ids.get(source, set()))
score = anchored_count / total_words
scores[source] = {
"total_words": total_words,
"anchored_words": anchored_count,
"score": round(score, 4),
}
return scores
def has_mixed_results(scores: dict[str, dict], low_threshold: float = 0.5) -> bool:
"""Return True if at least one source has a score below low_threshold."""
if len(scores) < 2:
return False
score_values = [v["score"] for v in scores.values()]
return min(score_values) < low_threshold
# ---------------------------------------------------------------------------
# Report generation
# ---------------------------------------------------------------------------
def build_report(job_results: list[dict]) -> str:
"""Build a human-readable text report sorted by min source score."""
lines = []
lines.append("=" * 72)
lines.append("REFERENCE LYRICS RELEVANCE ANALYSIS")
lines.append(f"Jobs analyzed: {len(job_results)}")
lines.append("=" * 72)
lines.append("")
# Sort: mixed-result jobs first (most interesting), then by min score asc
def sort_key(r):
scores = [v["score"] for v in r["scores"].values()] if r["scores"] else [1.0]
return (0 if r["is_mixed"] else 1, min(scores))
sorted_results = sorted(job_results, key=sort_key)
for idx, result in enumerate(sorted_results, 1):
job_id = result["job_id"]
artist = result.get("artist", "Unknown")
title = result.get("title", "Unknown")
mixed_flag = " [MIXED]" if result["is_mixed"] else ""
lines.append(f"{idx:3d}. {artist} - {title} ({job_id}){mixed_flag}")
scores = result["scores"]
if not scores:
lines.append(" (no reference sources found)")
else:
for source, info in sorted(scores.items(), key=lambda x: x[1]["score"]):
bar_len = int(info["score"] * 20)
bar = "#" * bar_len + "-" * (20 - bar_len)
lines.append(
f" {source:<12s} [{bar}] {info['score']:.1%}"
f" ({info['anchored_words']}/{info['total_words']} words)"
)
lines.append("")
# --- Aggregate statistics ---
lines.append("=" * 72)
lines.append("AGGREGATE STATISTICS")
lines.append("=" * 72)
all_source_scores: dict[str, list[float]] = defaultdict(list)
for result in job_results:
for source, info in result["scores"].items():
all_source_scores[source].append(info["score"])
for source in sorted(all_source_scores):
vals = all_source_scores[source]
avg = sum(vals) / len(vals) if vals else 0
below_50 = sum(1 for v in vals if v < 0.5)
below_30 = sum(1 for v in vals if v < 0.3)
below_10 = sum(1 for v in vals if v < 0.1)
lines.append(
f" {source:<12s} n={len(vals):3d} avg={avg:.1%}"
f" <50%: {below_50:3d} <30%: {below_30:3d} <10%: {below_10:3d}"
)
mixed_count = sum(1 for r in job_results if r["is_mixed"])
lines.append("")
lines.append(f" Jobs with mixed results (at least 1 source <50%): {mixed_count}/{len(job_results)}")
# Score distribution across ALL sources
all_scores = [
info["score"]
for result in job_results
for info in result["scores"].values()
]
if all_scores:
thresholds = [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9]
lines.append("")
lines.append(" Score distribution (all sources):")
for t in thresholds:
count = sum(1 for s in all_scores if s < t)
pct = count / len(all_scores) * 100
lines.append(f" < {t:.0%}: {count:4d} / {len(all_scores)} ({pct:.1f}%)")
lines.append("")
return "\n".join(lines)
# ---------------------------------------------------------------------------
# Main
# ---------------------------------------------------------------------------
def main():
parser = argparse.ArgumentParser(
description="Analyze reference lyrics relevance scores from production jobs"
)
parser.add_argument(
"--limit",
type=int,
default=30,
help="Target number of jobs to analyze (default: 30)",
)
parser.add_argument(
"--output",
type=str,
default=None,
help="Write raw JSON results to this file (optional)",
)
parser.add_argument(
"--no-mixed-bias",
action="store_true",
help="Disable bias toward jobs with mixed results",
)
args = parser.parse_args()
db = firestore.Client(project=PROJECT)
gcs_client = storage.Client(project=PROJECT)
# Step 1: Fetch candidate jobs from Firestore
candidate_jobs = fetch_candidate_jobs(db, limit=args.limit)
if not candidate_jobs:
logger.error("No candidate jobs found. Check Firestore access.")
sys.exit(1)
# Step 2: Download corrections and compute scores
job_results = []
skipped = 0
for job in candidate_jobs:
job_id = job["_job_id"]
corrections_url = job["_corrections_url"]
artist = job.get("artist", job.get("state_data", {}).get("artist", "Unknown"))
title = job.get("title", job.get("state_data", {}).get("title", "Unknown"))
logger.info(f"Processing {job_id}: {artist} - {title}")
corrections = download_corrections(gcs_client, corrections_url)
if not corrections:
skipped += 1
continue
scores = compute_relevance_scores(corrections)
if not scores:
skipped += 1
continue
is_mixed = has_mixed_results(scores)
job_results.append({
"job_id": job_id,
"artist": artist,
"title": title,
"corrections_url": corrections_url,
"scores": scores,
"is_mixed": is_mixed,
})
if skipped:
logger.info(f"Skipped {skipped} jobs (download failure or no reference sources)")
if not job_results:
logger.error("No results to report.")
sys.exit(1)
# Step 3: Optionally bias toward mixed-result jobs
if not args.no_mixed_bias:
mixed = [r for r in job_results if r["is_mixed"]]
non_mixed = [r for r in job_results if not r["is_mixed"]]
# Aim for at least half mixed, rest filled with non-mixed
target_mixed = min(len(mixed), max(args.limit // 2, len(mixed)))
target_non_mixed = min(len(non_mixed), args.limit - target_mixed)
job_results = mixed[:target_mixed] + non_mixed[:target_non_mixed]
logger.info(
f"After mixed-bias selection: {len(job_results)} jobs "
f"({target_mixed} mixed, {target_non_mixed} non-mixed)"
)
else:
job_results = job_results[: args.limit]
# Step 4: Print report
report = build_report(job_results)
print(report)
# Step 5: Optionally write JSON
if args.output:
with open(args.output, "w") as f:
json.dump(job_results, f, indent=2)
logger.info(f"Raw results written to {args.output}")
if __name__ == "__main__":
main()
File diff suppressed because it is too large. Load diff
+1198
View File
File diff suppressed because it is too large. Load diff
View File
Whitespace-only changes.
+257
View File
@@ -0,0 +1,257 @@
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,
TranscriptionData,
TranscriptionResult,
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 == {}
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
# 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"]
def test_corrector_keeps_all_relevant_sources(self, tmp_path):
"""Sources that match the transcription should all be kept."""
from karaoke_gen.lyrics_transcriber.correction.corrector import LyricsCorrector
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",
)
# Both sources match the transcription
source_a = _make_lyrics_data([["hello", "world", "foo", "bar"]], "source_a")
source_b = _make_lyrics_data([["hello", "world", "foo", "bar"]], "source_b")
corrector = LyricsCorrector(cache_dir=str(tmp_path))
result = corrector.run(
transcription_results=[
TranscriptionResult(name="test", priority=1, result=transcription)
],
lyrics_results={"source_a": source_a, "source_b": source_b},
)
assert "source_a" in result.reference_lyrics
assert "source_b" in result.reference_lyrics
assert "rejected_sources" not in result.metadata
def test_corrector_handles_all_sources_filtered_out(self, tmp_path):
"""When ALL sources fail relevance, corrector returns empty references and no corrections."""
from karaoke_gen.lyrics_transcriber.correction.corrector import LyricsCorrector
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",
)
# All sources have completely different words — all will be filtered
bad_a = _make_lyrics_data([["alpha", "beta", "gamma", "delta"]], "bad_a")
bad_b = _make_lyrics_data([["uno", "dos", "tres", "cuatro"]], "bad_b")
bad_c = _make_lyrics_data([["eins", "zwei", "drei", "vier"]], "bad_c")
corrector = LyricsCorrector(cache_dir=str(tmp_path))
result = corrector.run(
transcription_results=[
TranscriptionResult(name="test", priority=1, result=transcription)
],
lyrics_results={"bad_a": bad_a, "bad_b": bad_b, "bad_c": bad_c},
)
# All sources should be rejected
assert len(result.reference_lyrics) == 0
assert "rejected_sources" in result.metadata
assert len(result.metadata["rejected_sources"]) == 3
# No corrections should have been made (no references to correct against)
assert result.corrections_made == 0
# Original segments should be preserved
assert len(result.original_segments) == 1