lirics+testing

Dockerfile

@@ -3,6 +3,7 @@ FROM python:3.11-slim
 # Системные зависимости
 RUN apt-get update && apt-get install -y --no-install-recommends \
     ffmpeg \
+    libchromaprint-tools \
     libsndfile1 \
     curl \
     && rm -rf /var/lib/apt/lists/*

README.md

@@ -156,8 +156,10 @@ Hello world' \
 
 Repeated fields, a comma-separated value, or a JSON array are accepted for
 `requested_representations`. With no field, both audio representations are calculated,
-plus `lyrics.global` only when non-empty lyrics are supplied. Explicitly requesting
-`lyrics.global` without lyrics is an error.
+plus `lyrics.global` when lyrics are supplied or resolved by the fallback pipeline.
+Optional `title`, `artist`, `album` and `isrc` fields improve automatic lookup. Explicitly
+requesting `lyrics.global` fails with `fallback_errors` only when every enabled source
+is exhausted.
 
 Abbreviated response:
 
@@ -204,6 +206,66 @@ Errors never contain stack traces:
 {"error": {"code": "AUDIO_DECODE_FAILED", "message": "The uploaded audio could not be decoded."}}
 ```
 
+### Rank tracks by audio similarity
+
+`POST /v1/tracks/rank-similar` accepts one `target_audio` file and repeated `tracks`
+files. Every file is embedded with `audio.global`; candidates are returned in descending
+cosine-similarity order. Optional repeated `track_ids` must correspond to `tracks` in
+the same order. Lyrics are resolved independently for the target and every candidate;
+they do not affect the audio ranking.
+
+```bash
+curl -X POST http://localhost:7860/v1/tracks/rank-similar \
+  -F 'target_audio=@target.flac' \
+  -F 'target_track_id=target' \
+  -F 'target_title=Target song' -F 'target_artist=Target artist' \
+  -F 'tracks=@candidate-a.flac' -F 'track_ids=a' \
+  -F 'track_titles=Candidate A' -F 'track_artists=Artist A' \
+  -F 'tracks=@candidate-b.flac' -F 'track_ids=b' \
+  -F 'track_titles=Candidate B' -F 'track_artists=Artist B'
+```
+
+The response preserves each candidate's original index and filename:
+
+```json
+{
+  "schema_version": "1",
+  "representation": "audio.global",
+  "target": {
+    "track_id": "target",
+    "filename": "target.flac",
+    "lyrics": {"text": "...", "source": "lrclib", "metadata": {}, "errors": []}
+  },
+  "tracks": [
+    {
+      "track_id": "b",
+      "filename": "candidate-b.flac",
+      "original_index": 1,
+      "similarity": 0.91,
+      "lyrics": {
+        "text": "...",
+        "source": "asr.openai",
+        "metadata": {"title": "Candidate B", "artist": "Artist B"},
+        "errors": [
+          {"source": "lrclib", "code": "LYRICS_NOT_FOUND",
+            "message": "LRCLIB request failed with HTTP 404."}
+        ]
+      }
+    }
+  ]
+}
+```
+
+Repeated optional fields `track_lyrics`, `track_titles`, `track_artists`, `track_albums`
+and `track_isrcs` must contain exactly one value per `tracks` file when present. Use an
+empty value to request fallback resolution for a particular candidate.
+
+Lyrics fallback order is: request field, embedded audio tags, LRCLIB, Musixmatch,
+AcoustID/Chromaprint identification followed by another provider lookup, and finally
+ASR. Disabled sources are skipped; attempted failures are returned in `lyrics.errors`.
+ASR is disabled by default because it can incur cost and singing transcription is less
+reliable than catalog lyrics.
+
 `GET /v1/status` reports the selected device and loaded/available representations without
 environment details. `GET /health` is a lightweight container probe.
 
@@ -218,7 +280,22 @@ environment details. `GET /health` is a lightweight container probe.
 | `OPENMUSIC_TEMPORAL_MAX_SEGMENTS` | `24` |
 | `OPENMUSIC_CLAP_BATCH_SIZE` | `4` |
 | `OPENMUSIC_LYRICS_CHUNK_TOKENS` | `512` |
+| `OPENMUSIC_LYRICS_FALLBACK_ENABLED` | `true` |
+| `OPENMUSIC_LRCLIB_ENABLED` | `true` |
+| `OPENMUSIC_LRCLIB_MIN_INTERVAL_SECONDS` | `0.25` |
+| `OPENMUSIC_MUSIXMATCH_API_KEY` | unset |
+| `OPENMUSIC_ACOUSTID_API_KEY` | unset |
+| `OPENMUSIC_FPCALC` | `fpcalc` |
+| `OPENMUSIC_LYRICS_ASR_PROVIDER` | `none` |
+| `OPENMUSIC_OPENAI_API_KEY` | unset |
+| `OPENMUSIC_OPENAI_TRANSCRIPTION_MODEL` | `gpt-4o-mini-transcribe` |
+| `OPENMUSIC_LYRICS_ASR_COMMAND` | unset |
+| `OPENMUSIC_VOCAL_SEPARATOR_COMMAND` | unset |
+| `OPENMUSIC_HTTP_USER_AGENT` | project URL user agent |
+| `OPENMUSIC_LYRICS_FALLBACK_TIMEOUT` | `30` |
 | `OPENMUSIC_MAX_UPLOAD_BYTES` | `104857600` |
+| `OPENMUSIC_MAX_SIMILARITY_REQUEST_BYTES` | `524288000` |
+| `OPENMUSIC_MAX_SIMILARITY_TRACKS` | `50` |
 | `OPENMUSIC_MAX_LYRICS_CHARACTERS` | `100000` |
 | `OPENMUSIC_MAX_AUDIO_SECONDS` | `1800` |
 | `OPENMUSIC_REQUEST_TIMEOUT_SECONDS` | `300` |
@@ -226,6 +303,13 @@ environment details. `GET /health` is a lightweight container probe.
 Changing result-affecting representation configuration changes its generated
 `preprocessing_version` and benchmark cache key.
 
+Set `OPENMUSIC_LYRICS_ASR_PROVIDER=openai` together with `OPENMUSIC_OPENAI_API_KEY`
+to enable cloud transcription. For a self-hosted engine, use `command` and configure
+`OPENMUSIC_LYRICS_ASR_COMMAND`; `{input}` is replaced with a prepared mono MP3 path and
+the command must write only recognized text to stdout. An optional separator command
+receives `{input}` and `{output}` placeholders and must write a vocal-only WAV to
+`{output}`. Commands are parsed as argument lists and are never executed through a shell.
+
 ## Benchmark tools
 
 Place optional UTF-8 lyrics beside audio using the same stem (`song.flac` + `song.txt`).

openmusic_analysis/api.py

@@ -14,8 +14,15 @@ from fastapi.exceptions import RequestValidationError
 from fastapi.responses import JSONResponse
 
 from openmusic_analysis.application import MusicAnalysisService, build_service
-from openmusic_analysis.domain import AnalysisResponse, ModelsResponse
+from openmusic_analysis.domain import (
+    AnalysisResponse,
+    ModelsResponse,
+    SimilarityMatch,
+    SimilarityResponse,
+    SimilarityTrackReference,
+)
 from openmusic_analysis.errors import AnalysisError
+from openmusic_analysis.lyrics_resolution import LyricsLookupInput
 from openmusic_analysis.settings import Settings
 
 
@@ -48,11 +55,14 @@ def create_app(
     @app.middleware("http")
     async def request_limits(request: Request, call_next: Any):
         content_length = request.headers.get("content-length")
-        request_limit = (
-            settings.limits.max_upload_bytes
-            + settings.limits.max_lyrics_characters * 4
-            + 1024 * 1024
-        )
+        if request.url.path == "/v1/tracks/rank-similar":
+            request_limit = settings.limits.max_similarity_request_bytes
+        else:
+            request_limit = (
+                settings.limits.max_upload_bytes
+                + settings.limits.max_lyrics_characters * 4
+                + 1024 * 1024
+            )
         if content_length:
             try:
                 if int(content_length) > request_limit:
@@ -115,6 +125,10 @@ def create_app(
         track_id: Annotated[str | None, Form()] = None,
         content_identity: Annotated[str | None, Form()] = None,
         requested_representations: Annotated[list[str] | None, Form()] = None,
+        title: Annotated[str | None, Form()] = None,
+        artist: Annotated[str | None, Form()] = None,
+        album: Annotated[str | None, Form()] = None,
+        isrc: Annotated[str | None, Form()] = None,
     ) -> AnalysisResponse:
         if lyrics is not None and len(lyrics) > settings.limits.max_lyrics_characters:
             raise AnalysisError(
@@ -122,13 +136,8 @@ def create_app(
                 "Lyrics exceed the configured character limit.",
                 status_code=413,
             )
+        _validate_audio_extension(audio)
         suffix = Path(audio.filename or "").suffix.lower()
-        if suffix not in SUPPORTED_EXTENSIONS:
-            raise AnalysisError(
-                "UNSUPPORTED_AUDIO_FORMAT",
-                f"Supported extensions: {', '.join(sorted(SUPPORTED_EXTENSIONS))}.",
-                status_code=415,
-            )
         representations = _parse_representations(requested_representations)
         temp_path = await _store_upload(audio, suffix, settings.limits.max_upload_bytes)
         try:
@@ -138,6 +147,13 @@ def create_app(
                 requested_representations=representations,
                 track_id=track_id,
                 content_identity=content_identity,
+                lyrics_metadata=LyricsLookupInput(
+                    title=title,
+                    artist=artist,
+                    album=album,
+                    isrc=isrc,
+                    filename=audio.filename,
+                ),
             )
         finally:
             try:
@@ -145,9 +161,185 @@ def create_app(
             except FileNotFoundError:
                 pass
 
+    @app.post("/v1/tracks/rank-similar", response_model=SimilarityResponse)
+    async def rank_similar_tracks(
+        target_audio: Annotated[UploadFile, File(description="Target audio file")],
+        tracks: Annotated[list[UploadFile], File(description="Candidate audio files")],
+        target_track_id: Annotated[str | None, Form()] = None,
+        track_ids: Annotated[list[str] | None, Form()] = None,
+        target_lyrics: Annotated[str | None, Form()] = None,
+        track_lyrics: Annotated[list[str] | None, Form()] = None,
+        target_title: Annotated[str | None, Form()] = None,
+        target_artist: Annotated[str | None, Form()] = None,
+        target_album: Annotated[str | None, Form()] = None,
+        target_isrc: Annotated[str | None, Form()] = None,
+        track_titles: Annotated[list[str] | None, Form()] = None,
+        track_artists: Annotated[list[str] | None, Form()] = None,
+        track_albums: Annotated[list[str] | None, Form()] = None,
+        track_isrcs: Annotated[list[str] | None, Form()] = None,
+    ) -> SimilarityResponse:
+        if not tracks:
+            raise AnalysisError(
+                "MISSING_CANDIDATE_TRACKS",
+                "At least one candidate track is required.",
+                status_code=422,
+            )
+        if len(tracks) > settings.limits.max_similarity_tracks:
+            raise AnalysisError(
+                "TOO_MANY_CANDIDATE_TRACKS",
+                f"At most {settings.limits.max_similarity_tracks} candidate tracks are allowed.",
+                status_code=413,
+            )
+        aligned_fields = {
+            "track_ids": track_ids,
+            "track_lyrics": track_lyrics,
+            "track_titles": track_titles,
+            "track_artists": track_artists,
+            "track_albums": track_albums,
+            "track_isrcs": track_isrcs,
+        }
+        for field_name, values in aligned_fields.items():
+            _validate_aligned_field(field_name, values, len(tracks))
+        if target_lyrics is not None:
+            _validate_lyrics_size(
+                target_lyrics,
+                settings.limits.max_lyrics_characters,
+                field="target_lyrics",
+            )
+        for index, value in enumerate(track_lyrics or []):
+            _validate_lyrics_size(
+                value,
+                settings.limits.max_lyrics_characters,
+                field="track_lyrics",
+                index=index,
+            )
+
+        _validate_audio_extension(target_audio)
+        for track in tracks:
+            _validate_audio_extension(track)
+
+        temp_paths: list[str] = []
+        try:
+            target_path = await _store_upload(
+                target_audio,
+                Path(target_audio.filename or "").suffix.lower(),
+                settings.limits.max_upload_bytes,
+            )
+            temp_paths.append(target_path)
+            candidate_paths: list[str] = []
+            for track in tracks:
+                path = await _store_upload(
+                    track,
+                    Path(track.filename or "").suffix.lower(),
+                    settings.limits.max_upload_bytes,
+                )
+                candidate_paths.append(path)
+                temp_paths.append(path)
+
+            ranked = await service.rank_similar_audio(target_path, candidate_paths)
+            target_lyrics_resolution = await service.resolve_lyrics(
+                target_path,
+                provided_lyrics=target_lyrics,
+                supplied_metadata=LyricsLookupInput(
+                    title=target_title,
+                    artist=target_artist,
+                    album=target_album,
+                    isrc=target_isrc,
+                    filename=target_audio.filename,
+                ),
+            )
+            candidate_lyrics = []
+            for index, path in enumerate(candidate_paths):
+                candidate_lyrics.append(
+                    await service.resolve_lyrics(
+                        path,
+                        provided_lyrics=_optional_at(track_lyrics, index),
+                        supplied_metadata=LyricsLookupInput(
+                            title=_optional_at(track_titles, index),
+                            artist=_optional_at(track_artists, index),
+                            album=_optional_at(track_albums, index),
+                            isrc=_optional_at(track_isrcs, index),
+                            filename=tracks[index].filename,
+                        ),
+                    )
+                )
+            return SimilarityResponse(
+                target=SimilarityTrackReference(
+                    track_id=target_track_id,
+                    filename=target_audio.filename or "target",
+                    lyrics=target_lyrics_resolution,
+                ),
+                tracks=[
+                    SimilarityMatch(
+                        original_index=index,
+                        track_id=track_ids[index] if track_ids is not None else None,
+                        filename=tracks[index].filename or f"track-{index}",
+                        similarity=similarity,
+                        lyrics=candidate_lyrics[index],
+                    )
+                    for index, similarity in ranked
+                ],
+            )
+        finally:
+            for path in temp_paths:
+                try:
+                    os.unlink(path)
+                except FileNotFoundError:
+                    pass
+
     return app
 
 
+def _validate_audio_extension(upload: UploadFile) -> None:
+    suffix = Path(upload.filename or "").suffix.lower()
+    if suffix not in SUPPORTED_EXTENSIONS:
+        raise AnalysisError(
+            "UNSUPPORTED_AUDIO_FORMAT",
+            f"Supported extensions: {', '.join(sorted(SUPPORTED_EXTENSIONS))}.",
+            status_code=415,
+        )
+
+
+def _validate_aligned_field(
+    field_name: str, values: list[str] | None, expected_count: int
+) -> None:
+    if values is not None and len(values) != expected_count:
+        code = "INVALID_TRACK_IDS" if field_name == "track_ids" else "INVALID_TRACK_FIELDS"
+        raise AnalysisError(
+            code,
+            f"{field_name} count must match the number of candidate tracks.",
+            status_code=422,
+            details={"field": field_name, "expected": expected_count, "actual": len(values)},
+        )
+
+
+def _optional_at(values: list[str] | None, index: int) -> str | None:
+    if values is None:
+        return None
+    value = values[index].strip()
+    return value or None
+
+
+def _validate_lyrics_size(
+    value: str,
+    max_characters: int,
+    *,
+    field: str,
+    index: int | None = None,
+) -> None:
+    if len(value) <= max_characters:
+        return
+    details: dict[str, Any] = {"field": field, "max_characters": max_characters}
+    if index is not None:
+        details["index"] = index
+    raise AnalysisError(
+        "LYRICS_TOO_LARGE",
+        "Lyrics exceed the configured character limit.",
+        status_code=413,
+        details=details,
+    )
+
+
 async def _store_upload(upload: UploadFile, suffix: str, max_bytes: int) -> str:
     size = 0
     path: str | None = None

openmusic_analysis/application.py

@@ -2,6 +2,8 @@ from __future__ import annotations
 
 from pathlib import Path
 
+import numpy as np
+
 from openmusic_analysis.analyzers import (
     BGEM3LyricsAnalyzer,
     BGEM3TextEncoder,
@@ -11,8 +13,14 @@ from openmusic_analysis.analyzers import (
     LyricsPreprocessor,
 )
 from openmusic_analysis.audio import AnalysisContext, AudioDecoder
-from openmusic_analysis.domain import AnalysisResponse, TrackReference
+from openmusic_analysis.domain import (
+    AnalysisResponse,
+    LyricsResolution,
+    ResolvedTrackMetadata,
+    TrackReference,
+)
 from openmusic_analysis.errors import AnalysisError
+from openmusic_analysis.lyrics_resolution import LyricsLookupInput, LyricsResolver
 from openmusic_analysis.registry import ModelRegistry
 from openmusic_analysis.runtime import DeviceManager, InferenceGate
 from openmusic_analysis.settings import Settings
@@ -28,10 +36,12 @@ class MusicAnalysisService:
         registry: ModelRegistry,
         decoder: AudioDecoder,
         device: str,
+        lyrics_resolver: LyricsResolver | None = None,
     ) -> None:
         self.registry = registry
         self.decoder = decoder
         self.device = device
+        self.lyrics_resolver = lyrics_resolver
 
     async def analyze(
         self,
@@ -41,12 +51,28 @@ class MusicAnalysisService:
         requested_representations: list[str] | None,
         track_id: str | None,
         content_identity: str | None,
+        lyrics_metadata: LyricsLookupInput | None = None,
     ) -> AnalysisResponse:
         if lyrics is not None and not lyrics.strip():
             raise AnalysisError(
                 "INVALID_LYRICS", "Lyrics must contain non-whitespace text.", status_code=422
             )
-        requested = self._resolve_representations(requested_representations, lyrics)
+        should_resolve_lyrics = requested_representations is None or (
+            "lyrics.global" in requested_representations
+        )
+        lyrics_resolution: LyricsResolution | None = None
+        effective_lyrics = lyrics
+        if lyrics is not None or should_resolve_lyrics:
+            lyrics_resolution = await self.resolve_lyrics(
+                source_path,
+                provided_lyrics=lyrics,
+                supplied_metadata=lyrics_metadata,
+            )
+            effective_lyrics = lyrics_resolution.text
+
+        requested = self._resolve_representations(
+            requested_representations, effective_lyrics
+        )
         context = AnalysisContext(source_path, self.decoder)
         results = {}
         for representation in requested:
@@ -54,19 +80,28 @@ class MusicAnalysisService:
             if analyzer.input_kind == "audio":
                 result = await analyzer.analyze(context)
             elif analyzer.input_kind == "lyrics":
-                if lyrics is None:
+                if effective_lyrics is None:
                     raise AnalysisError(
                         "LYRICS_REQUIRED",
                         f"Representation '{representation}' requires lyrics.",
                         status_code=422,
+                        details={
+                            "fallback_errors": [
+                                error.model_dump()
+                                for error in (
+                                    lyrics_resolution.errors if lyrics_resolution else []
+                                )
+                            ]
+                        },
                     )
-                result = await analyzer.analyze(lyrics)
+                result = await analyzer.analyze(effective_lyrics)
             else:
                 raise RuntimeError(f"Unknown analyzer input kind: {analyzer.input_kind}")
             results[representation] = result
         return AnalysisResponse(
             track=TrackReference(track_id=track_id, content_identity=content_identity),
             representations=results,
+            lyrics=lyrics_resolution,
         )
 
     def _resolve_representations(
@@ -103,6 +138,53 @@ class MusicAnalysisService:
                 seen.add(id(encoder))
                 await encoder.ready()
 
+    async def rank_similar_audio(
+        self,
+        target_source_path: str | Path,
+        candidate_source_paths: list[str | Path],
+    ) -> list[tuple[int, float]]:
+        """Rank candidates by cosine similarity in the global CLAP space."""
+        analyzer = self.registry.analyzer("audio.global")
+        target = await analyzer.analyze(AnalysisContext(target_source_path, self.decoder))
+        target_embedding = np.asarray(target.embedding, dtype=np.float32)
+
+        scores: list[tuple[int, float]] = []
+        for index, source_path in enumerate(candidate_source_paths):
+            candidate = await analyzer.analyze(AnalysisContext(source_path, self.decoder))
+            candidate_embedding = np.asarray(candidate.embedding, dtype=np.float32)
+            similarity = float(np.dot(target_embedding, candidate_embedding))
+            scores.append((index, float(np.clip(similarity, -1.0, 1.0))))
+
+        return sorted(scores, key=lambda item: (-item[1], item[0]))
+
+    async def resolve_lyrics(
+        self,
+        source_path: str | Path,
+        *,
+        provided_lyrics: str | None = None,
+        supplied_metadata: LyricsLookupInput | None = None,
+    ) -> LyricsResolution:
+        metadata = supplied_metadata or LyricsLookupInput()
+        if provided_lyrics and provided_lyrics.strip():
+            return LyricsResolution(
+                text=provided_lyrics,
+                source="request",
+                metadata=ResolvedTrackMetadata(
+                    title=metadata.title,
+                    artist=metadata.artist,
+                    album=metadata.album,
+                    isrc=metadata.isrc,
+                    duration_seconds=metadata.duration_seconds,
+                ),
+            )
+        if self.lyrics_resolver is None:
+            return LyricsResolution()
+        return await self.lyrics_resolver.resolve(
+            source_path,
+            provided_lyrics=provided_lyrics,
+            supplied_metadata=metadata,
+        )
+
 
 def build_service(settings: Settings | None = None) -> MusicAnalysisService:
     settings = settings or Settings.from_env()
@@ -125,4 +207,14 @@ def build_service(settings: Settings | None = None) -> MusicAnalysisService:
         max_audio_seconds=settings.limits.max_audio_seconds,
         timeout_seconds=settings.limits.decode_timeout_seconds,
     )
-    return MusicAnalysisService(registry=registry, decoder=decoder, device=device)
+    lyrics_resolver = LyricsResolver(
+        settings.lyrics_fallback,
+        ffmpeg_binary=settings.ffmpeg_binary,
+        ffprobe_binary=settings.ffprobe_binary,
+    )
+    return MusicAnalysisService(
+        registry=registry,
+        decoder=decoder,
+        device=device,
+        lyrics_resolver=lyrics_resolver,
+    )

openmusic_analysis/domain.py

@@ -100,15 +100,55 @@ class TrackReference(StrictModel):
     content_identity: str | None = None
 
 
+class ModelsResponse(StrictModel):
+    schema_version: str = "1"
+    models: list[ModelMetadata]
+
+
+class LyricsSourceError(StrictModel):
+    source: str
+    code: str
+    message: str
+
+
+class ResolvedTrackMetadata(StrictModel):
+    title: str | None = None
+    artist: str | None = None
+    album: str | None = None
+    isrc: str | None = None
+    duration_seconds: FiniteFloat | None = Field(default=None, gt=0)
+
+
+class LyricsResolution(StrictModel):
+    text: str | None = None
+    source: str | None = None
+    metadata: ResolvedTrackMetadata = Field(default_factory=ResolvedTrackMetadata)
+    errors: list[LyricsSourceError] = Field(default_factory=list)
+
+
 class AnalysisResponse(StrictModel):
     schema_version: str = "1"
     track: TrackReference
     representations: dict[str, RepresentationResult]
+    lyrics: LyricsResolution | None = None
 
 
-class ModelsResponse(StrictModel):
+class SimilarityTrackReference(StrictModel):
+    track_id: str | None = None
+    filename: str
+    lyrics: LyricsResolution = Field(default_factory=LyricsResolution)
+
+
+class SimilarityMatch(SimilarityTrackReference):
+    original_index: int = Field(ge=0)
+    similarity: FiniteFloat = Field(ge=-1.0, le=1.0)
+
+
+class SimilarityResponse(StrictModel):
     schema_version: str = "1"
-    models: list[ModelMetadata]
+    representation: str = "audio.global"
+    target: SimilarityTrackReference
+    tracks: list[SimilarityMatch]
 
 
 class ErrorBody(StrictModel):

openmusic_analysis/lyrics_resolution.py

@@ -0,0 +1,744 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import math
+import os
+import shlex
+import subprocess
+import tempfile
+import threading
+import time
+import uuid
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlencode
+from urllib.request import Request, urlopen
+
+from openmusic_analysis.domain import (
+    LyricsResolution,
+    LyricsSourceError,
+    ResolvedTrackMetadata,
+)
+from openmusic_analysis.settings import LyricsFallbackConfig
+
+
+log = logging.getLogger(__name__)
+_LYRICS_TAGS = ("lyrics", "unsyncedlyrics", "syncedlyrics", "uslt", "sylt", "©lyr")
+
+
+@dataclass(frozen=True)
+class LyricsLookupInput:
+    title: str | None = None
+    artist: str | None = None
+    album: str | None = None
+    isrc: str | None = None
+    duration_seconds: float | None = None
+    filename: str | None = None
+
+
+@dataclass(frozen=True)
+class _ProviderResult:
+    text: str | None
+    error: LyricsSourceError | None
+
+
+@dataclass(frozen=True)
+class _TranscriptionResult:
+    text: str | None
+    source: str | None
+    errors: list[LyricsSourceError]
+
+
+class LyricsResolver:
+    """Resolve lyrics through deterministic fallbacks without hiding failed sources."""
+
+    def __init__(
+        self,
+        config: LyricsFallbackConfig,
+        *,
+        ffmpeg_binary: str = "ffmpeg",
+        ffprobe_binary: str = "ffprobe",
+    ) -> None:
+        self.config = config
+        self.ffmpeg_binary = ffmpeg_binary
+        self.ffprobe_binary = ffprobe_binary
+        self._lrclib_lock = threading.Lock()
+        self._last_lrclib_request = 0.0
+
+    async def resolve(
+        self,
+        source_path: str | Path,
+        *,
+        provided_lyrics: str | None = None,
+        supplied_metadata: LyricsLookupInput | None = None,
+    ) -> LyricsResolution:
+        try:
+            return await asyncio.to_thread(
+                self._resolve_sync,
+                Path(source_path),
+                provided_lyrics,
+                supplied_metadata or LyricsLookupInput(),
+            )
+        except Exception:
+            log.exception("Unexpected lyrics resolution failure")
+            return LyricsResolution(
+                errors=[
+                    _source_error(
+                        "resolver",
+                        "INTERNAL_ERROR",
+                        "Lyrics resolution failed unexpectedly.",
+                    )
+                ]
+            )
+
+    def _resolve_sync(
+        self,
+        source_path: Path,
+        provided_lyrics: str | None,
+        supplied_metadata: LyricsLookupInput,
+    ) -> LyricsResolution:
+        errors: list[LyricsSourceError] = []
+        supplied_metadata = _clean_metadata(supplied_metadata)
+        if provided_lyrics and provided_lyrics.strip():
+            return _resolution(provided_lyrics, "request", supplied_metadata, errors)
+
+        embedded_text, embedded_metadata, embedded_error = self._embedded(source_path)
+        metadata = _merge_metadata(supplied_metadata, embedded_metadata)
+        filename_path = Path(supplied_metadata.filename or source_path.name)
+        metadata = _merge_metadata(metadata, _metadata_from_filename(filename_path))
+        if embedded_error:
+            errors.append(embedded_error)
+        if embedded_text:
+            return _resolution(embedded_text, "embedded", metadata, errors)
+        if embedded_error is None:
+            errors.append(
+                _source_error(
+                    "embedded",
+                    "LYRICS_NOT_FOUND",
+                    "Audio tags contain no lyrics.",
+                )
+            )
+        if not self.config.enabled:
+            return _resolution(None, None, metadata, errors)
+
+        text = self._lookup_providers(metadata, errors, suffix="")
+        if text:
+            return _resolution(text[0], text[1], metadata, errors)
+
+        fingerprint_metadata = self._fingerprint(source_path, errors)
+        if fingerprint_metadata is not None:
+            enriched = _merge_metadata(fingerprint_metadata, metadata)
+            if enriched != metadata:
+                metadata = enriched
+                text = self._lookup_providers(metadata, errors, suffix="_after_fingerprint")
+                if text:
+                    return _resolution(text[0], text[1], metadata, errors)
+
+        asr = self._transcribe(source_path)
+        errors.extend(asr.errors)
+        if asr.text:
+            return _resolution(asr.text, asr.source, metadata, errors)
+        return _resolution(None, None, metadata, errors)
+
+    def _embedded(
+        self, source_path: Path
+    ) -> tuple[str | None, LyricsLookupInput, LyricsSourceError | None]:
+        command = [
+            self.ffprobe_binary,
+            "-v",
+            "error",
+            "-show_entries",
+            "format=duration:stream=duration:format_tags:stream_tags",
+            "-of",
+            "json",
+            str(source_path),
+        ]
+        try:
+            completed = subprocess.run(
+                command,
+                check=False,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                timeout=self.config.timeout_seconds,
+                text=True,
+            )
+            if completed.returncode != 0:
+                raise RuntimeError("ffprobe could not read audio tags")
+            payload = json.loads(completed.stdout)
+        except (OSError, subprocess.TimeoutExpired, json.JSONDecodeError, RuntimeError) as exc:
+            log.info("Embedded lyrics lookup failed: %s", exc)
+            return None, LyricsLookupInput(), _source_error(
+                "embedded", "METADATA_READ_FAILED", "Audio tags could not be read."
+            )
+
+        tags: dict[str, str] = {}
+        if not isinstance(payload, dict):
+            return None, LyricsLookupInput(), _source_error(
+                "embedded", "INVALID_METADATA", "ffprobe returned invalid metadata."
+            )
+        streams = payload.get("streams")
+        containers = [payload.get("format") or {}]
+        if isinstance(streams, list):
+            containers.extend(item for item in streams if isinstance(item, dict))
+        for container in containers:
+            for name, value in (container.get("tags") or {}).items():
+                if value is not None:
+                    tags.setdefault(str(name).lower(), str(value).strip())
+        duration = _positive_float((payload.get("format") or {}).get("duration"))
+        if duration is None and isinstance(streams, list) and streams:
+            first_stream = streams[0] if isinstance(streams[0], dict) else {}
+            duration = _positive_float(first_stream.get("duration"))
+        metadata = LyricsLookupInput(
+            title=_first(tags, "title"),
+            artist=_first(tags, "artist", "album_artist", "albumartist"),
+            album=_first(tags, "album"),
+            isrc=_first(tags, "isrc", "tsrc"),
+            duration_seconds=duration,
+        )
+        text = _first_lyrics(tags)
+        return _clean_lyrics(text), metadata, None
+
+    def _lookup_providers(
+        self,
+        metadata: LyricsLookupInput,
+        errors: list[LyricsSourceError],
+        *,
+        suffix: str,
+    ) -> tuple[str, str] | None:
+        if self.config.lrclib_enabled:
+            result = self._lrclib(metadata, source=f"lrclib{suffix}")
+            if result.error:
+                errors.append(result.error)
+            if result.text:
+                return result.text, "lrclib"
+        if self.config.musixmatch_api_key:
+            result = self._musixmatch(metadata, source=f"musixmatch{suffix}")
+            if result.error:
+                errors.append(result.error)
+            if result.text:
+                return result.text, "musixmatch"
+        return None
+
+    def _lrclib(self, metadata: LyricsLookupInput, *, source: str) -> _ProviderResult:
+        if not metadata.title or not metadata.artist:
+            return _ProviderResult(
+                None,
+                _source_error(
+                    source,
+                    "METADATA_REQUIRED",
+                    "Title and artist are required for LRCLIB lookup.",
+                ),
+            )
+        query: dict[str, str] = {
+            "track_name": metadata.title,
+            "artist_name": metadata.artist,
+        }
+        if metadata.album:
+            query["album_name"] = metadata.album
+        if metadata.duration_seconds:
+            query["duration"] = str(int(round(metadata.duration_seconds)))
+        try:
+            with self._lrclib_lock:
+                elapsed = time.monotonic() - self._last_lrclib_request
+                remaining = self.config.lrclib_min_interval_seconds - elapsed
+                if remaining > 0:
+                    time.sleep(remaining)
+                try:
+                    payload = self._json_request(
+                        f"{self.config.lrclib_base_url.rstrip('/')}/api/get?{urlencode(query)}"
+                    )
+                finally:
+                    self._last_lrclib_request = time.monotonic()
+            text = _clean_lyrics(payload.get("plainLyrics"))
+            if not text:
+                return _ProviderResult(
+                    None,
+                    _source_error(source, "LYRICS_NOT_FOUND", "LRCLIB returned no lyrics."),
+                )
+            return _ProviderResult(text, None)
+        except HTTPError as exc:
+            code = "LYRICS_NOT_FOUND" if exc.code == 404 else "HTTP_ERROR"
+            return _ProviderResult(
+                None, _source_error(source, code, f"LRCLIB request failed with HTTP {exc.code}.")
+            )
+        except (
+            OSError,
+            URLError,
+            ValueError,
+            TypeError,
+            AttributeError,
+            json.JSONDecodeError,
+        ):
+            return _ProviderResult(
+                None,
+                _source_error(source, "REQUEST_FAILED", "LRCLIB request failed."),
+            )
+
+    def _musixmatch(self, metadata: LyricsLookupInput, *, source: str) -> _ProviderResult:
+        if not metadata.isrc and not (metadata.title and metadata.artist):
+            return _ProviderResult(
+                None,
+                _source_error(
+                    source,
+                    "METADATA_REQUIRED",
+                    "ISRC or title and artist are required for Musixmatch lookup.",
+                ),
+            )
+        query = {"apikey": self.config.musixmatch_api_key or ""}
+        if metadata.isrc:
+            query["track_isrc"] = metadata.isrc
+        else:
+            query["q_track"] = metadata.title or ""
+            query["q_artist"] = metadata.artist or ""
+        url = (
+            f"{self.config.musixmatch_base_url.rstrip('/')}/matcher.lyrics.get?"
+            f"{urlencode(query)}"
+        )
+        try:
+            payload = self._json_request(url)
+            header = ((payload.get("message") or {}).get("header") or {})
+            status = int(header.get("status_code", 0))
+            lyrics = (
+                (((payload.get("message") or {}).get("body") or {}).get("lyrics") or {})
+                .get("lyrics_body")
+            )
+            text = _clean_lyrics(lyrics)
+            if status != 200 or not text:
+                return _ProviderResult(
+                    None,
+                    _source_error(
+                        source,
+                        "LYRICS_NOT_FOUND" if status in {0, 404} else "HTTP_ERROR",
+                        f"Musixmatch returned status {status}.",
+                    ),
+                )
+            return _ProviderResult(text, None)
+        except (
+            OSError,
+            URLError,
+            ValueError,
+            TypeError,
+            AttributeError,
+            json.JSONDecodeError,
+            HTTPError,
+        ):
+            return _ProviderResult(
+                None,
+                _source_error(source, "REQUEST_FAILED", "Musixmatch request failed."),
+            )
+
+    def _fingerprint(
+        self, source_path: Path, errors: list[LyricsSourceError]
+    ) -> LyricsLookupInput | None:
+        if not self.config.acoustid_api_key:
+            return None
+        try:
+            completed = subprocess.run(
+                [self.config.fpcalc_binary, "-json", str(source_path)],
+                check=False,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                timeout=self.config.timeout_seconds,
+                text=True,
+            )
+            if completed.returncode != 0:
+                raise RuntimeError("fpcalc failed")
+            fingerprint = json.loads(completed.stdout)
+            body = urlencode(
+                {
+                    "client": self.config.acoustid_api_key,
+                    "duration": fingerprint["duration"],
+                    "fingerprint": fingerprint["fingerprint"],
+                    "meta": "recordings releasegroups compress",
+                }
+            ).encode("ascii")
+            payload = self._json_request(
+                f"{self.config.acoustid_base_url.rstrip('/')}/lookup",
+                data=body,
+                content_type="application/x-www-form-urlencoded",
+            )
+            results = payload.get("results") or []
+            best_result = (
+                max(results, key=lambda item: float(item.get("score", 0)))
+                if results
+                else {}
+            )
+            recordings = best_result.get("recordings")
+            if not recordings:
+                errors.append(
+                    _source_error(
+                        "acoustid", "TRACK_NOT_IDENTIFIED", "AcoustID found no recording."
+                    )
+                )
+                return None
+            recording = recordings[0]
+            artists = recording.get("artists") or []
+            releasegroups = recording.get("releasegroups") or []
+            return LyricsLookupInput(
+                title=_clean_value(recording.get("title")),
+                artist=_clean_value(artists[0].get("name")) if artists else None,
+                album=_clean_value(releasegroups[0].get("title")) if releasegroups else None,
+                duration_seconds=_positive_float(fingerprint.get("duration")),
+            )
+        except (
+            OSError,
+            subprocess.TimeoutExpired,
+            RuntimeError,
+            KeyError,
+            ValueError,
+            TypeError,
+            AttributeError,
+            IndexError,
+        ):
+            errors.append(
+                _source_error("acoustid", "IDENTIFICATION_FAILED", "AcoustID lookup failed.")
+            )
+            return None
+
+    def _transcribe(self, source_path: Path) -> _TranscriptionResult:
+        if self.config.asr_provider == "none":
+            return _TranscriptionResult(None, None, [])
+        prepared_paths: list[Path] = []
+        errors: list[LyricsSourceError] = []
+        input_path = source_path
+        if self.config.vocal_separator_command:
+            try:
+                input_path = self._run_vocal_separator(source_path)
+                prepared_paths.append(input_path)
+            except Exception:
+                errors.append(
+                    _source_error(
+                        "vocal_separator",
+                        "SEPARATION_FAILED",
+                        "Vocal separation failed; ASR will use the original audio.",
+                    )
+                )
+        try:
+            compressed = self._compress_for_asr(input_path)
+            prepared_paths.append(compressed)
+            if self.config.asr_provider == "openai":
+                result = self._openai_transcribe(compressed)
+            else:
+                result = self._command_transcribe(compressed)
+            if result.error:
+                errors.append(result.error)
+            return _TranscriptionResult(
+                result.text,
+                f"asr.{self.config.asr_provider}" if result.text else None,
+                errors,
+            )
+        except (OSError, subprocess.TimeoutExpired, RuntimeError, KeyError, ValueError):
+            errors.append(
+                _source_error(
+                    "asr.prepare",
+                    "AUDIO_PREPARATION_FAILED",
+                    "Audio could not be prepared for transcription.",
+                )
+            )
+            return _TranscriptionResult(
+                None,
+                None,
+                errors,
+            )
+        finally:
+            for path in prepared_paths:
+                try:
+                    os.unlink(path)
+                except FileNotFoundError:
+                    pass
+
+    def _run_vocal_separator(self, source_path: Path) -> Path:
+        descriptor, output_name = tempfile.mkstemp(prefix="openmusic-vocals-", suffix=".wav")
+        os.close(descriptor)
+        output_path = Path(output_name)
+        os.unlink(output_path)
+        try:
+            command = _configured_command(
+                self.config.vocal_separator_command or "",
+                input_path=source_path,
+                output_path=output_path,
+            )
+            completed = subprocess.run(
+                command,
+                check=False,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                timeout=max(self.config.timeout_seconds, 300.0),
+            )
+        except Exception:
+            try:
+                os.unlink(output_path)
+            except FileNotFoundError:
+                pass
+            raise
+        invalid_output = (
+            completed.returncode != 0
+            or not output_path.exists()
+            or output_path.stat().st_size == 0
+        )
+        if invalid_output:
+            try:
+                os.unlink(output_path)
+            except FileNotFoundError:
+                pass
+            raise RuntimeError("Vocal separator failed")
+        return output_path
+
+    def _compress_for_asr(self, source_path: Path) -> Path:
+        descriptor, output_name = tempfile.mkstemp(prefix="openmusic-asr-", suffix=".mp3")
+        os.close(descriptor)
+        output_path = Path(output_name)
+        try:
+            completed = subprocess.run(
+                [
+                    self.ffmpeg_binary,
+                    "-v",
+                    "error",
+                    "-nostdin",
+                    "-i",
+                    str(source_path),
+                    "-vn",
+                    "-ac",
+                    "1",
+                    "-ar",
+                    "16000",
+                    "-b:a",
+                    "64k",
+                    "-y",
+                    str(output_path),
+                ],
+                check=False,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                timeout=max(self.config.timeout_seconds, 120.0),
+            )
+        except Exception:
+            try:
+                os.unlink(output_path)
+            except FileNotFoundError:
+                pass
+            raise
+        invalid_output = (
+            completed.returncode != 0
+            or not output_path.exists()
+            or output_path.stat().st_size == 0
+        )
+        if invalid_output:
+            try:
+                os.unlink(output_path)
+            except FileNotFoundError:
+                pass
+            raise RuntimeError("ASR audio preparation failed")
+        return output_path
+
+    def _openai_transcribe(self, source_path: Path) -> _ProviderResult:
+        boundary = f"openmusic-{uuid.uuid4().hex}"
+        file_data = source_path.read_bytes()
+        body = b"".join(
+            [
+                _multipart_field(boundary, "model", self.config.openai_transcription_model),
+                _multipart_file(boundary, "file", source_path.name, "audio/mpeg", file_data),
+                f"--{boundary}--\r\n".encode("ascii"),
+            ]
+        )
+        request = Request(
+            f"{self.config.openai_base_url.rstrip('/')}/audio/transcriptions",
+            data=body,
+            headers={
+                "Authorization": f"Bearer {self.config.openai_api_key}",
+                "Content-Type": f"multipart/form-data; boundary={boundary}",
+                "User-Agent": self.config.http_user_agent,
+            },
+            method="POST",
+        )
+        try:
+            with urlopen(request, timeout=max(self.config.timeout_seconds, 120.0)) as response:
+                payload = json.loads(response.read().decode("utf-8"))
+            text = _clean_lyrics(payload.get("text"))
+            if not text:
+                return _ProviderResult(
+                    None,
+                    _source_error("asr.openai", "EMPTY_TRANSCRIPTION", "ASR returned no text."),
+                )
+            return _ProviderResult(text, None)
+        except (
+            HTTPError,
+            URLError,
+            OSError,
+            TypeError,
+            AttributeError,
+            json.JSONDecodeError,
+        ):
+            return _ProviderResult(
+                None,
+                _source_error("asr.openai", "REQUEST_FAILED", "OpenAI ASR request failed."),
+            )
+
+    def _command_transcribe(self, source_path: Path) -> _ProviderResult:
+        command = _configured_command(
+            self.config.local_asr_command or "",
+            input_path=source_path,
+            output_path=None,
+        )
+        completed = subprocess.run(
+            command,
+            check=False,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            timeout=max(self.config.timeout_seconds, 300.0),
+            text=True,
+        )
+        text = _clean_lyrics(completed.stdout)
+        if completed.returncode != 0 or not text:
+            return _ProviderResult(
+                None,
+                _source_error("asr.command", "COMMAND_FAILED", "Local ASR command failed."),
+            )
+        return _ProviderResult(text, None)
+
+    def _json_request(
+        self,
+        url: str,
+        *,
+        data: bytes | None = None,
+        content_type: str | None = None,
+    ) -> dict[str, Any]:
+        headers = {"User-Agent": self.config.http_user_agent, "Accept": "application/json"}
+        if content_type:
+            headers["Content-Type"] = content_type
+        request = Request(url, data=data, headers=headers, method="POST" if data else "GET")
+        with urlopen(request, timeout=self.config.timeout_seconds) as response:
+            return json.loads(response.read().decode("utf-8"))
+
+
+def _resolution(
+    text: str | None,
+    source: str | None,
+    metadata: LyricsLookupInput,
+    errors: list[LyricsSourceError],
+) -> LyricsResolution:
+    return LyricsResolution(
+        text=_clean_lyrics(text),
+        source=source,
+        metadata=ResolvedTrackMetadata(
+            title=metadata.title,
+            artist=metadata.artist,
+            album=metadata.album,
+            isrc=metadata.isrc,
+            duration_seconds=metadata.duration_seconds,
+        ),
+        errors=errors,
+    )
+
+
+def _merge_metadata(primary: LyricsLookupInput, fallback: LyricsLookupInput) -> LyricsLookupInput:
+    return LyricsLookupInput(
+        title=primary.title or fallback.title,
+        artist=primary.artist or fallback.artist,
+        album=primary.album or fallback.album,
+        isrc=primary.isrc or fallback.isrc,
+        duration_seconds=primary.duration_seconds or fallback.duration_seconds,
+        filename=primary.filename or fallback.filename,
+    )
+
+
+def _clean_metadata(metadata: LyricsLookupInput) -> LyricsLookupInput:
+    return LyricsLookupInput(
+        title=_clean_value(metadata.title),
+        artist=_clean_value(metadata.artist),
+        album=_clean_value(metadata.album),
+        isrc=_clean_value(metadata.isrc),
+        duration_seconds=_positive_float(metadata.duration_seconds),
+        filename=_clean_value(metadata.filename),
+    )
+
+
+def _source_error(source: str, code: str, message: str) -> LyricsSourceError:
+    return LyricsSourceError(source=source, code=code, message=message)
+
+
+def _first(values: dict[str, str], *names: str) -> str | None:
+    for name in names:
+        value = _clean_value(values.get(name))
+        if value:
+            return value
+    return None
+
+
+def _first_lyrics(values: dict[str, str]) -> str | None:
+    direct = _first(values, *_LYRICS_TAGS)
+    if direct:
+        return direct
+    for name, value in values.items():
+        if name.startswith(("lyrics-", "uslt-", "sylt-")):
+            cleaned = _clean_value(value)
+            if cleaned:
+                return cleaned
+    return None
+
+
+def _metadata_from_filename(source_path: Path) -> LyricsLookupInput:
+    parts = source_path.stem.split(" - ", maxsplit=1)
+    if len(parts) != 2:
+        return LyricsLookupInput()
+    artist, title = (part.strip() for part in parts)
+    if not artist or not title:
+        return LyricsLookupInput()
+    return LyricsLookupInput(title=title, artist=artist)
+
+
+def _clean_value(value: object) -> str | None:
+    if value is None:
+        return None
+    cleaned = str(value).strip()
+    return cleaned or None
+
+
+def _clean_lyrics(value: object) -> str | None:
+    cleaned = _clean_value(value)
+    if not cleaned:
+        return None
+    return cleaned.replace("\r\n", "\n").replace("\r", "\n")
+
+
+def _positive_float(value: object) -> float | None:
+    try:
+        result = float(value)
+    except (TypeError, ValueError):
+        return None
+    return result if math.isfinite(result) and result > 0 else None
+
+
+def _configured_command(
+    template: str,
+    *,
+    input_path: Path,
+    output_path: Path | None,
+) -> list[str]:
+    values = {"input": str(input_path), "output": str(output_path) if output_path else ""}
+    return [part.format_map(values) for part in shlex.split(template)]
+
+
+def _multipart_field(boundary: str, name: str, value: str) -> bytes:
+    return (
+        f'--{boundary}\r\nContent-Disposition: form-data; name="{name}"\r\n\r\n'
+        f"{value}\r\n"
+    ).encode("utf-8")
+
+
+def _multipart_file(
+    boundary: str,
+    name: str,
+    filename: str,
+    content_type: str,
+    value: bytes,
+) -> bytes:
+    header = (
+        f'--{boundary}\r\nContent-Disposition: form-data; name="{name}"; '
+        f'filename="{filename}"\r\nContent-Type: {content_type}\r\n\r\n'
+    ).encode("utf-8")
+    return header + value + b"\r\n"

openmusic_analysis/settings.py

@@ -99,6 +99,8 @@ class LyricsConfig:
 @dataclass(frozen=True)
 class LimitConfig:
     max_upload_bytes: int = 100 * 1024 * 1024
+    max_similarity_request_bytes: int = 500 * 1024 * 1024
+    max_similarity_tracks: int = 50
     max_lyrics_characters: int = 100_000
     max_audio_seconds: float = 30 * 60
     request_timeout_seconds: float = 300.0
@@ -107,6 +109,8 @@ class LimitConfig:
     def __post_init__(self) -> None:
         if min(
             self.max_upload_bytes,
+            self.max_similarity_request_bytes,
+            self.max_similarity_tracks,
             self.max_lyrics_characters,
             self.max_audio_seconds,
             self.request_timeout_seconds,
@@ -115,6 +119,40 @@ class LimitConfig:
             raise ValueError("All service limits must be positive")
 
 
+@dataclass(frozen=True)
+class LyricsFallbackConfig:
+    enabled: bool = True
+    lrclib_enabled: bool = True
+    lrclib_base_url: str = "https://lrclib.net"
+    lrclib_min_interval_seconds: float = 0.25
+    musixmatch_api_key: str | None = None
+    musixmatch_base_url: str = "https://api.musixmatch.com/ws/1.1"
+    acoustid_api_key: str | None = None
+    acoustid_base_url: str = "https://api.acoustid.org/v2"
+    fpcalc_binary: str = "fpcalc"
+    asr_provider: str = "none"
+    openai_api_key: str | None = None
+    openai_base_url: str = "https://api.openai.com/v1"
+    openai_transcription_model: str = "gpt-4o-mini-transcribe"
+    local_asr_command: str | None = None
+    vocal_separator_command: str | None = None
+    http_user_agent: str = (
+        "OpenMusicAnalysis/1.0 "
+        "(https://huggingface.co/spaces/kxmWebwe/trackembeddingapi)"
+    )
+    timeout_seconds: float = 30.0
+
+    def __post_init__(self) -> None:
+        if self.asr_provider not in {"none", "openai", "command"}:
+            raise ValueError("Lyrics ASR provider must be none, openai or command")
+        if self.timeout_seconds <= 0 or self.lrclib_min_interval_seconds < 0:
+            raise ValueError("Lyrics fallback time values are invalid")
+        if self.asr_provider == "openai" and not self.openai_api_key:
+            raise ValueError("OPENMUSIC_OPENAI_API_KEY is required for OpenAI ASR")
+        if self.asr_provider == "command" and not self.local_asr_command:
+            raise ValueError("OPENMUSIC_LYRICS_ASR_COMMAND is required for command ASR")
+
+
 @dataclass(frozen=True)
 class Settings:
     device: str = "auto"
@@ -125,6 +163,7 @@ class Settings:
     global_audio: GlobalAudioConfig = GlobalAudioConfig()
     temporal_audio: TemporalAudioConfig = TemporalAudioConfig()
     lyrics: LyricsConfig = LyricsConfig()
+    lyrics_fallback: LyricsFallbackConfig = LyricsFallbackConfig()
     limits: LimitConfig = LimitConfig()
 
     def __post_init__(self) -> None:
@@ -153,11 +192,51 @@ class Settings:
         )
         limits = LimitConfig(
             max_upload_bytes=int(os.getenv("OPENMUSIC_MAX_UPLOAD_BYTES", str(100 * 1024 * 1024))),
+            max_similarity_request_bytes=int(
+                os.getenv(
+                    "OPENMUSIC_MAX_SIMILARITY_REQUEST_BYTES", str(500 * 1024 * 1024)
+                )
+            ),
+            max_similarity_tracks=int(os.getenv("OPENMUSIC_MAX_SIMILARITY_TRACKS", "50")),
             max_lyrics_characters=int(os.getenv("OPENMUSIC_MAX_LYRICS_CHARACTERS", "100000")),
             max_audio_seconds=float(os.getenv("OPENMUSIC_MAX_AUDIO_SECONDS", "1800")),
             request_timeout_seconds=float(os.getenv("OPENMUSIC_REQUEST_TIMEOUT_SECONDS", "300")),
             decode_timeout_seconds=float(os.getenv("OPENMUSIC_DECODE_TIMEOUT_SECONDS", "120")),
         )
+        lyrics_fallback = LyricsFallbackConfig(
+            enabled=_env_bool("OPENMUSIC_LYRICS_FALLBACK_ENABLED", True),
+            lrclib_enabled=_env_bool("OPENMUSIC_LRCLIB_ENABLED", True),
+            lrclib_base_url=os.getenv("OPENMUSIC_LRCLIB_BASE_URL", "https://lrclib.net"),
+            lrclib_min_interval_seconds=float(
+                os.getenv("OPENMUSIC_LRCLIB_MIN_INTERVAL_SECONDS", "0.25")
+            ),
+            musixmatch_api_key=os.getenv("OPENMUSIC_MUSIXMATCH_API_KEY"),
+            musixmatch_base_url=os.getenv(
+                "OPENMUSIC_MUSIXMATCH_BASE_URL",
+                "https://api.musixmatch.com/ws/1.1",
+            ),
+            acoustid_api_key=os.getenv("OPENMUSIC_ACOUSTID_API_KEY"),
+            acoustid_base_url=os.getenv(
+                "OPENMUSIC_ACOUSTID_BASE_URL", "https://api.acoustid.org/v2"
+            ),
+            fpcalc_binary=os.getenv("OPENMUSIC_FPCALC", "fpcalc"),
+            asr_provider=os.getenv("OPENMUSIC_LYRICS_ASR_PROVIDER", "none"),
+            openai_api_key=os.getenv("OPENMUSIC_OPENAI_API_KEY"),
+            openai_base_url=os.getenv(
+                "OPENMUSIC_OPENAI_BASE_URL", "https://api.openai.com/v1"
+            ),
+            openai_transcription_model=os.getenv(
+                "OPENMUSIC_OPENAI_TRANSCRIPTION_MODEL", "gpt-4o-mini-transcribe"
+            ),
+            local_asr_command=os.getenv("OPENMUSIC_LYRICS_ASR_COMMAND"),
+            vocal_separator_command=os.getenv("OPENMUSIC_VOCAL_SEPARATOR_COMMAND"),
+            http_user_agent=os.getenv(
+                "OPENMUSIC_HTTP_USER_AGENT",
+                "OpenMusicAnalysis/1.0 "
+                "(https://huggingface.co/spaces/kxmWebwe/trackembeddingapi)",
+            ),
+            timeout_seconds=float(os.getenv("OPENMUSIC_LYRICS_FALLBACK_TIMEOUT", "30")),
+        )
         return cls(
             device=os.getenv("OPENMUSIC_DEVICE", "auto"),
             inference_concurrency=max(1, int(os.getenv("OPENMUSIC_INFERENCE_CONCURRENCY", "1"))),
@@ -167,6 +246,7 @@ class Settings:
             global_audio=global_audio,
             temporal_audio=temporal_audio,
             lyrics=lyrics,
+            lyrics_fallback=lyrics_fallback,
             limits=limits,
         )
 

tests/test_api.py

@@ -1,10 +1,14 @@
 from __future__ import annotations
 
+from pathlib import Path
+
 import numpy as np
 from fastapi.testclient import TestClient
 
 from openmusic_analysis.api import create_app
-from openmusic_analysis.settings import Settings, TemporalAudioConfig
+from openmusic_analysis.audio.decoder import AudioMetadata, DecodedAudio
+from openmusic_analysis.domain import LyricsResolution, LyricsSourceError
+from openmusic_analysis.settings import LimitConfig, Settings, TemporalAudioConfig
 
 from .conftest import FailingAudioEncoder, make_service
 
@@ -138,3 +142,139 @@ def test_temporal_api_response_uses_adjacent_transition_index():
     assert len(temporal["segments"]) == 15
     assert temporal["summary"]["number_of_segments"] == 15
     assert 0 <= temporal["summary"]["largest_transition_index"] <= 13
+
+
+class ContentDecoder:
+    canonical_sample_rate = 10
+
+    def __init__(self) -> None:
+        self.calls = 0
+
+    def decode(self, source_path) -> DecodedAudio:
+        self.calls += 1
+        content = source_path.read_bytes()
+        if content in {b"target", b"same"}:
+            waveform = np.linspace(-1.0, 1.0, 95, dtype=np.float32)
+        elif content == b"reversed":
+            waveform = np.linspace(1.0, -1.0, 95, dtype=np.float32)
+        else:
+            waveform = np.full(95, 3.0, dtype=np.float32)
+        return DecodedAudio(
+            waveform=waveform,
+            sample_rate=self.canonical_sample_rate,
+            metadata=AudioMetadata(
+                duration_ms=9500,
+                source_sample_rate=10,
+                source_channels=1,
+                source_format="fake",
+            ),
+        )
+
+
+class FakeLyricsResolver:
+    async def resolve(self, source_path, *, provided_lyrics=None, supplied_metadata=None):
+        content = Path(source_path).read_bytes()
+        if content == b"same":
+            return LyricsResolution(
+                text="Resolved candidate lyrics",
+                source="lrclib",
+                errors=[
+                    LyricsSourceError(
+                        source="embedded",
+                        code="LYRICS_NOT_FOUND",
+                        message="No embedded lyrics.",
+                    )
+                ],
+            )
+        return LyricsResolution(
+            errors=[
+                LyricsSourceError(
+                    source="lrclib",
+                    code="LYRICS_NOT_FOUND",
+                    message="No provider match.",
+                )
+            ]
+        )
+
+
+def test_rank_similar_tracks_returns_descending_global_audio_similarity(service_bundle):
+    service, _, encoder = service_bundle
+    decoder = ContentDecoder()
+    service.decoder = decoder
+    service.lyrics_resolver = FakeLyricsResolver()
+    response = client_for(service).post(
+        "/v1/tracks/rank-similar",
+        files=[
+            ("target_audio", ("target.mp3", b"target", "audio/mpeg")),
+            ("tracks", ("different.mp3", b"different", "audio/mpeg")),
+            ("tracks", ("same.mp3", b"same", "audio/mpeg")),
+            ("tracks", ("reversed.mp3", b"reversed", "audio/mpeg")),
+        ],
+        data={
+            "target_track_id": "target-id",
+            "target_lyrics": "Lyrics supplied for target",
+            "track_ids": ["different-id", "same-id", "reversed-id"],
+        },
+    )
+    assert response.status_code == 200
+    body = response.json()
+    assert body["representation"] == "audio.global"
+    assert body["target"]["track_id"] == "target-id"
+    assert body["target"]["filename"] == "target.mp3"
+    assert body["target"]["lyrics"]["text"] == "Lyrics supplied for target"
+    assert body["target"]["lyrics"]["source"] == "request"
+    assert body["tracks"][0]["track_id"] == "same-id"
+    assert body["tracks"][0]["similarity"] == 1.0
+    assert body["tracks"][0]["lyrics"]["text"] == "Resolved candidate lyrics"
+    assert body["tracks"][0]["lyrics"]["source"] == "lrclib"
+    assert body["tracks"][0]["lyrics"]["errors"][0]["source"] == "embedded"
+    assert [item["similarity"] for item in body["tracks"]] == sorted(
+        [item["similarity"] for item in body["tracks"]], reverse=True
+    )
+    assert decoder.calls == 4
+    assert len(encoder.calls) == 4
+
+
+def test_analyze_automatically_adds_lyrics_representation(service_bundle):
+    service, _, _ = service_bundle
+    service.lyrics_resolver = FakeLyricsResolver()
+    response = client_for(service).post(
+        "/v1/tracks/analyze",
+        files=upload(b"same"),
+        data={"title": "Candidate", "artist": "Artist"},
+    )
+    assert response.status_code == 200
+    body = response.json()
+    assert "lyrics.global" in body["representations"]
+    assert body["lyrics"]["text"] == "Resolved candidate lyrics"
+    assert body["lyrics"]["source"] == "lrclib"
+
+
+def test_rank_similar_tracks_validates_track_id_count(service_bundle):
+    service, _, _ = service_bundle
+    response = client_for(service).post(
+        "/v1/tracks/rank-similar",
+        files=[
+            ("target_audio", ("target.mp3", b"target", "audio/mpeg")),
+            ("tracks", ("one.mp3", b"one", "audio/mpeg")),
+            ("tracks", ("two.mp3", b"two", "audio/mpeg")),
+        ],
+        data={"track_ids": ["only-one-id"]},
+    )
+    assert response.status_code == 422
+    assert response.json()["error"]["code"] == "INVALID_TRACK_IDS"
+
+
+def test_rank_similar_tracks_respects_candidate_limit(service_bundle):
+    service, _, _ = service_bundle
+    settings = Settings(limits=LimitConfig(max_similarity_tracks=1))
+    response = TestClient(create_app(service=service, settings=settings)).post(
+        "/v1/tracks/rank-similar",
+        files=[
+            ("target_audio", ("target.mp3", b"target", "audio/mpeg")),
+            ("tracks", ("one.mp3", b"one", "audio/mpeg")),
+            ("tracks", ("two.mp3", b"two", "audio/mpeg")),
+        ],
+    )
+    assert response.status_code == 413
+    assert response.json()["error"]["code"] == "TOO_MANY_CANDIDATE_TRACKS"

tests/test_lyrics_resolution.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from openmusic_analysis.domain import LyricsSourceError
+from openmusic_analysis.lyrics_resolution import (
+    LyricsLookupInput,
+    LyricsResolver,
+    _ProviderResult,
+)
+from openmusic_analysis.settings import LyricsFallbackConfig
+
+
+class PipelineResolver(LyricsResolver):
+    def __init__(self) -> None:
+        super().__init__(
+            LyricsFallbackConfig(
+                lrclib_enabled=True,
+                musixmatch_api_key="test-key",
+                acoustid_api_key="test-key",
+                asr_provider="command",
+                local_asr_command="fake {input}",
+            )
+        )
+
+    def _embedded(self, source_path):
+        return (
+            None,
+            LyricsLookupInput(duration_seconds=180),
+            LyricsSourceError(
+                source="embedded",
+                code="LYRICS_NOT_FOUND",
+                message="No embedded lyrics.",
+            ),
+        )
+
+    def _lrclib(self, metadata, *, source):
+        if metadata.title == "Identified title":
+            return _ProviderResult("Resolved lyrics", None)
+        return _ProviderResult(
+            None,
+            LyricsSourceError(
+                source=source,
+                code="METADATA_REQUIRED",
+                message="Metadata missing.",
+            ),
+        )
+
+    def _musixmatch(self, metadata, *, source):
+        return _ProviderResult(
+            None,
+            LyricsSourceError(
+                source=source,
+                code="LYRICS_NOT_FOUND",
+                message="No Musixmatch result.",
+            ),
+        )
+
+    def _fingerprint(self, source_path, errors):
+        return LyricsLookupInput(title="Identified title", artist="Identified artist")
+
+    def _transcribe(self, source_path):
+        raise AssertionError("ASR must not run after provider resolution")
+
+
+def test_provided_lyrics_short_circuit_every_fallback(tmp_path: Path):
+    source = tmp_path / "track.mp3"
+    source.write_bytes(b"audio")
+    resolver = PipelineResolver()
+    result = resolver._resolve_sync(
+        source,
+        "Provided lyrics",
+        LyricsLookupInput(title="Title", artist="Artist"),
+    )
+    assert result.text == "Provided lyrics"
+    assert result.source == "request"
+    assert result.errors == []
+
+
+def test_fingerprint_enriches_metadata_and_provider_errors_are_preserved(tmp_path: Path):
+    source = tmp_path / "track.mp3"
+    source.write_bytes(b"audio")
+    result = PipelineResolver()._resolve_sync(source, None, LyricsLookupInput())
+    assert result.text == "Resolved lyrics"
+    assert result.source == "lrclib"
+    assert result.metadata.title == "Identified title"
+    assert result.metadata.artist == "Identified artist"
+    assert [error.source for error in result.errors] == [
+        "embedded",
+        "lrclib",
+        "musixmatch",
+    ]