feat: add stable cover cache keys, Qobuz album-search fallback, metadata filters and extended sort options

- Introduce coverCacheKey parameter through Go backend and Kotlin bridge for stable SAF cover caching
- Add MetadataFromFilename flag to skip filename-only metadata and retry via temp-file copy
- Add Qobuz album-search fallback between API search and store scraping
- Extract buildReEnrichFFmpegMetadata to skip empty metadata fields
- Add metadata completeness filter (complete, missing year/genre/album artist)
- Add sort modes: artist, album, release date, genre (asc/desc)
- Prune stale library cover cache files after full scan
- Skip empty values and zero track/disc numbers in FFmpeg metadata
- Add new l10n keys for metadata filter and sort options

go_backend/audio_metadata.go

@@ -1620,14 +1620,28 @@ func extractAnyCoverArtWithHint(filePath, displayNameHint string) ([]byte, strin
 }
 
 func SaveCoverToCache(filePath, cacheDir string) (string, error) {
-	return SaveCoverToCacheWithHint(filePath, "", cacheDir)
+	return SaveCoverToCacheWithHintAndKey(filePath, "", cacheDir, "")
 }
 
 func SaveCoverToCacheWithHint(filePath, displayNameHint, cacheDir string) (string, error) {
+	return SaveCoverToCacheWithHintAndKey(filePath, displayNameHint, cacheDir, "")
+}
+
+func resolveLibraryCoverCacheKey(filePath, explicitKey string) string {
+	explicitKey = strings.TrimSpace(explicitKey)
+	if explicitKey != "" {
+		return explicitKey
+	}
+
 	cacheKey := filePath
 	if stat, err := os.Stat(filePath); err == nil {
 		cacheKey = fmt.Sprintf("%s|%d|%d", filePath, stat.Size(), stat.ModTime().UnixNano())
 	}
+	return cacheKey
+}
+
+func SaveCoverToCacheWithHintAndKey(filePath, displayNameHint, cacheDir, coverCacheKey string) (string, error) {
+	cacheKey := resolveLibraryCoverCacheKey(filePath, coverCacheKey)
 	hash := hashString(cacheKey)
 
 	jpgPath := filepath.Join(cacheDir, fmt.Sprintf("cover_%x.jpg", hash))

go_backend/audio_metadata_cache_test.go

@@ -0,0 +1,34 @@
+package gobackend
+
+import (
+	"os"
+	"strings"
+	"testing"
+)
+
+func TestResolveLibraryCoverCacheKeyUsesExplicitKey(t *testing.T) {
+	t.Parallel()
+
+	const explicitKey = "content://media/external/audio/media/42|123456"
+	got := resolveLibraryCoverCacheKey("/tmp/saf_random.flac", explicitKey)
+	if got != explicitKey {
+		t.Fatalf("expected explicit cache key %q, got %q", explicitKey, got)
+	}
+}
+
+func TestResolveLibraryCoverCacheKeyUsesFilePathAndStatWhenNoExplicitKey(t *testing.T) {
+	t.Parallel()
+
+	tempFile, err := os.CreateTemp("", "cover-cache-*.flac")
+	if err != nil {
+		t.Fatalf("CreateTemp failed: %v", err)
+	}
+	tempPath := tempFile.Name()
+	tempFile.Close()
+	defer os.Remove(tempPath)
+
+	got := resolveLibraryCoverCacheKey(tempPath, "")
+	if !strings.HasPrefix(got, tempPath+"|") {
+		t.Fatalf("expected stat-based cache key to start with %q, got %q", tempPath+"|", got)
+	}
+}

go_backend/cue_parser.go

@@ -26,11 +26,11 @@ type CueSheet struct {
 
 // CueTrack represents a single track in a cue sheet
 type CueTrack struct {
-	Number    int    `json:"number"`
-	Title     string `json:"title"`
-	Performer string `json:"performer"`
-	ISRC      string `json:"isrc,omitempty"`
-	Composer  string `json:"composer,omitempty"`
+	Number    int     `json:"number"`
+	Title     string  `json:"title"`
+	Performer string  `json:"performer"`
+	ISRC      string  `json:"isrc,omitempty"`
+	Composer  string  `json:"composer,omitempty"`
 	StartTime float64 `json:"start_time"` // INDEX 01 in seconds
 	PreGap    float64 `json:"pre_gap"`    // INDEX 00 in seconds (or -1 if not present)
 }
@@ -422,7 +422,7 @@ func ScanCueFileForLibrary(cuePath string, scanTime string) ([]LibraryScanResult
 	if err != nil {
 		return nil, err
 	}
-	return scanCueSheetForLibrary(cuePath, sheet, audioPath, "", 0, scanTime)
+	return scanCueSheetForLibrary(cuePath, sheet, audioPath, "", 0, "", scanTime)
 }
 
 // ScanCueFileForLibraryExt is like ScanCueFileForLibrary but with extra parameters
@@ -433,6 +433,17 @@ func ScanCueFileForLibrary(cuePath string, scanTime string) ([]LibraryScanResult
 //   - fileModTime: if > 0, used as the FileModTime for all results instead of
 //     stat-ing the cuePath on disk (useful when the real file lives behind SAF)
 func ScanCueFileForLibraryExt(cuePath, audioDir, virtualPathPrefix string, fileModTime int64, scanTime string) ([]LibraryScanResult, error) {
+	return ScanCueFileForLibraryExtWithCoverCacheKey(
+		cuePath,
+		audioDir,
+		virtualPathPrefix,
+		fileModTime,
+		"",
+		scanTime,
+	)
+}
+
+func ScanCueFileForLibraryExtWithCoverCacheKey(cuePath, audioDir, virtualPathPrefix string, fileModTime int64, coverCacheKey, scanTime string) ([]LibraryScanResult, error) {
 	sheet, err := ParseCueFile(cuePath)
 	if err != nil {
 		return nil, err
@@ -441,7 +452,15 @@ func ScanCueFileForLibraryExt(cuePath, audioDir, virtualPathPrefix string, fileM
 	if err != nil {
 		return nil, err
 	}
-	return scanCueSheetForLibrary(cuePath, sheet, audioPath, virtualPathPrefix, fileModTime, scanTime)
+	return scanCueSheetForLibrary(
+		cuePath,
+		sheet,
+		audioPath,
+		virtualPathPrefix,
+		fileModTime,
+		coverCacheKey,
+		scanTime,
+	)
 }
 
 func resolveCueAudioPathForLibrary(cuePath string, sheet *CueSheet, audioDir string) (string, error) {
@@ -459,7 +478,7 @@ func resolveCueAudioPathForLibrary(cuePath string, sheet *CueSheet, audioDir str
 	return audioPath, nil
 }
 
-func scanCueSheetForLibrary(cuePath string, sheet *CueSheet, audioPath, virtualPathPrefix string, fileModTime int64, scanTime string) ([]LibraryScanResult, error) {
+func scanCueSheetForLibrary(cuePath string, sheet *CueSheet, audioPath, virtualPathPrefix string, fileModTime int64, coverCacheKey, scanTime string) ([]LibraryScanResult, error) {
 	if sheet == nil {
 		return nil, fmt.Errorf("cue sheet is nil for %s", cuePath)
 	}
@@ -492,7 +511,12 @@ func scanCueSheetForLibrary(cuePath string, sheet *CueSheet, audioPath, virtualP
 	coverCacheDir := libraryCoverCacheDir
 	libraryCoverCacheMu.RUnlock()
 	if coverCacheDir != "" {
-		cp, err := SaveCoverToCache(audioPath, coverCacheDir)
+		cp, err := SaveCoverToCacheWithHintAndKey(
+			audioPath,
+			"",
+			coverCacheDir,
+			coverCacheKey,
+		)
 		if err == nil && cp != "" {
 			coverPath = cp
 		}

go_backend/exports.go

@@ -200,6 +200,48 @@ func reEnrichDownloadRequest(req reEnrichRequest) DownloadRequest {
 	}
 }
 
+func buildReEnrichFFmpegMetadata(req reEnrichRequest, lyricsLRC string) map[string]string {
+	metadata := map[string]string{}
+	if req.TrackName != "" {
+		metadata["TITLE"] = req.TrackName
+	}
+	if req.ArtistName != "" {
+		metadata["ARTIST"] = req.ArtistName
+	}
+	if req.AlbumName != "" {
+		metadata["ALBUM"] = req.AlbumName
+	}
+	if req.AlbumArtist != "" {
+		metadata["ALBUMARTIST"] = req.AlbumArtist
+	}
+	if req.ReleaseDate != "" {
+		metadata["DATE"] = req.ReleaseDate
+	}
+	if req.ISRC != "" {
+		metadata["ISRC"] = req.ISRC
+	}
+	if req.Genre != "" {
+		metadata["GENRE"] = req.Genre
+	}
+	if req.TrackNumber > 0 {
+		metadata["TRACKNUMBER"] = fmt.Sprintf("%d", req.TrackNumber)
+	}
+	if req.DiscNumber > 0 {
+		metadata["DISCNUMBER"] = fmt.Sprintf("%d", req.DiscNumber)
+	}
+	if req.Label != "" {
+		metadata["ORGANIZATION"] = req.Label
+	}
+	if req.Copyright != "" {
+		metadata["COPYRIGHT"] = req.Copyright
+	}
+	if lyricsLRC != "" {
+		metadata["LYRICS"] = lyricsLRC
+		metadata["UNSYNCEDLYRICS"] = lyricsLRC
+	}
+	return metadata
+}
+
 func selectBestReEnrichTrack(req reEnrichRequest, tracks []ExtTrackMetadata) *ExtTrackMetadata {
 	if len(tracks) == 0 {
 		return nil
@@ -1109,6 +1151,26 @@ func ScanCueSheetForLibrary(cuePath, audioDir, virtualPathPrefix string, fileMod
 	return string(jsonBytes), nil
 }
 
+func ScanCueSheetForLibraryWithCoverCacheKey(cuePath, audioDir, virtualPathPrefix string, fileModTime int64, coverCacheKey string) (string, error) {
+	scanTime := time.Now().UTC().Format(time.RFC3339)
+	results, err := ScanCueFileForLibraryExtWithCoverCacheKey(
+		cuePath,
+		audioDir,
+		virtualPathPrefix,
+		fileModTime,
+		coverCacheKey,
+		scanTime,
+	)
+	if err != nil {
+		return "[]", err
+	}
+	jsonBytes, err := json.Marshal(results)
+	if err != nil {
+		return "[]", fmt.Errorf("failed to marshal cue scan results: %w", err)
+	}
+	return string(jsonBytes), nil
+}
+
 // EditFileMetadata writes metadata to an audio file.
 // For FLAC files, uses native Go FLAC library.
 // For MP3/Opus, returns the metadata map so Dart can use FFmpeg.
@@ -2195,36 +2257,14 @@ func ReEnrichFile(requestJSON string) (string, error) {
 
 	// Don't cleanup cover temp — Dart needs it for FFmpeg embed
 	cleanupCover = false
+	ffmpegMetadata := buildReEnrichFFmpegMetadata(req, lyricsLRC)
+
 	result := map[string]interface{}{
 		"method":            "ffmpeg",
 		"cover_path":        coverTempPath,
 		"lyrics":            lyricsLRC,
 		"enriched_metadata": enrichedMeta,
-		"metadata": map[string]string{
-			"TITLE":       req.TrackName,
-			"ARTIST":      req.ArtistName,
-			"ALBUM":       req.AlbumName,
-			"ALBUMARTIST": req.AlbumArtist,
-			"DATE":        req.ReleaseDate,
-			"ISRC":        req.ISRC,
-			"GENRE":       req.Genre,
-		},
-	}
-	if req.TrackNumber > 0 {
-		result["metadata"].(map[string]string)["TRACKNUMBER"] = fmt.Sprintf("%d", req.TrackNumber)
-	}
-	if req.DiscNumber > 0 {
-		result["metadata"].(map[string]string)["DISCNUMBER"] = fmt.Sprintf("%d", req.DiscNumber)
-	}
-	if req.Label != "" {
-		result["metadata"].(map[string]string)["ORGANIZATION"] = req.Label
-	}
-	if req.Copyright != "" {
-		result["metadata"].(map[string]string)["COPYRIGHT"] = req.Copyright
-	}
-	if lyricsLRC != "" {
-		result["metadata"].(map[string]string)["LYRICS"] = lyricsLRC
-		result["metadata"].(map[string]string)["UNSYNCEDLYRICS"] = lyricsLRC
+		"metadata":          ffmpegMetadata,
 	}
 
 	jsonBytes, _ := json.Marshal(result)
@@ -3468,3 +3508,7 @@ func ReadAudioMetadataJSON(filePath string) (string, error) {
 func ReadAudioMetadataWithHintJSON(filePath, displayName string) (string, error) {
 	return ReadAudioMetadataWithDisplayName(filePath, displayName)
 }
+
+func ReadAudioMetadataWithHintAndCoverCacheKeyJSON(filePath, displayName, coverCacheKey string) (string, error) {
+	return ReadAudioMetadataWithDisplayNameAndCoverCacheKey(filePath, displayName, coverCacheKey)
+}

go_backend/exports_test.go

@@ -177,3 +177,48 @@ func TestSelectBestReEnrichTrackPrefersCandidateWithReleaseDate(t *testing.T) {
 		t.Fatalf("selected track = %q, want candidate with release date", best.ID)
 	}
 }
+
+func TestBuildReEnrichFFmpegMetadataOmitsEmptyFields(t *testing.T) {
+	req := reEnrichRequest{
+		TrackName:   "Song",
+		ArtistName:  "Artist",
+		AlbumName:   "Album",
+		AlbumArtist: "",
+		ReleaseDate: "",
+		TrackNumber: 0,
+		DiscNumber:  0,
+		ISRC:        "",
+		Genre:       "",
+		Label:       "",
+		Copyright:   "",
+	}
+
+	metadata := buildReEnrichFFmpegMetadata(req, "")
+
+	if metadata["TITLE"] != "Song" {
+		t.Fatalf("title = %q", metadata["TITLE"])
+	}
+	if metadata["ARTIST"] != "Artist" {
+		t.Fatalf("artist = %q", metadata["ARTIST"])
+	}
+	if metadata["ALBUM"] != "Album" {
+		t.Fatalf("album = %q", metadata["ALBUM"])
+	}
+
+	for _, key := range []string{
+		"ALBUMARTIST",
+		"DATE",
+		"TRACKNUMBER",
+		"DISCNUMBER",
+		"ISRC",
+		"GENRE",
+		"ORGANIZATION",
+		"COPYRIGHT",
+		"LYRICS",
+		"UNSYNCEDLYRICS",
+	} {
+		if _, exists := metadata[key]; exists {
+			t.Fatalf("did not expect key %s in metadata: %#v", key, metadata)
+		}
+	}
+}

go_backend/library_scan.go

@@ -13,25 +13,26 @@ import (
 )
 
 type LibraryScanResult struct {
-	ID          string `json:"id"`
-	TrackName   string `json:"trackName"`
-	ArtistName  string `json:"artistName"`
-	AlbumName   string `json:"albumName"`
-	AlbumArtist string `json:"albumArtist,omitempty"`
-	FilePath    string `json:"filePath"`
-	CoverPath   string `json:"coverPath,omitempty"`
-	ScannedAt   string `json:"scannedAt"`
-	FileModTime int64  `json:"fileModTime,omitempty"` // Unix timestamp in milliseconds
-	ISRC        string `json:"isrc,omitempty"`
-	TrackNumber int    `json:"trackNumber,omitempty"`
-	DiscNumber  int    `json:"discNumber,omitempty"`
-	Duration    int    `json:"duration,omitempty"`
-	ReleaseDate string `json:"releaseDate,omitempty"`
-	BitDepth    int    `json:"bitDepth,omitempty"`
-	SampleRate  int    `json:"sampleRate,omitempty"`
-	Bitrate     int    `json:"bitrate,omitempty"` // kbps, for lossy formats (MP3, Opus, Vorbis)
-	Genre       string `json:"genre,omitempty"`
-	Format      string `json:"format,omitempty"`
+	ID                   string `json:"id"`
+	TrackName            string `json:"trackName"`
+	ArtistName           string `json:"artistName"`
+	AlbumName            string `json:"albumName"`
+	AlbumArtist          string `json:"albumArtist,omitempty"`
+	FilePath             string `json:"filePath"`
+	CoverPath            string `json:"coverPath,omitempty"`
+	ScannedAt            string `json:"scannedAt"`
+	FileModTime          int64  `json:"fileModTime,omitempty"` // Unix timestamp in milliseconds
+	ISRC                 string `json:"isrc,omitempty"`
+	TrackNumber          int    `json:"trackNumber,omitempty"`
+	DiscNumber           int    `json:"discNumber,omitempty"`
+	Duration             int    `json:"duration,omitempty"`
+	ReleaseDate          string `json:"releaseDate,omitempty"`
+	BitDepth             int    `json:"bitDepth,omitempty"`
+	SampleRate           int    `json:"sampleRate,omitempty"`
+	Bitrate              int    `json:"bitrate,omitempty"` // kbps, for lossy formats (MP3, Opus, Vorbis)
+	Genre                string `json:"genre,omitempty"`
+	Format               string `json:"format,omitempty"`
+	MetadataFromFilename bool   `json:"metadataFromFilename,omitempty"`
 }
 
 type LibraryScanProgress struct {
@@ -219,6 +220,7 @@ func ScanLibraryFolder(folderPath string) (string, error) {
 					cueInfo.audioPath,
 					"",
 					fileInfo.modTime,
+					"",
 					scanTime,
 				)
 			} else {
@@ -269,10 +271,14 @@ func scanAudioFile(filePath, scanTime string) (*LibraryScanResult, error) {
 }
 
 func scanAudioFileWithKnownModTime(filePath, scanTime string, knownModTime int64) (*LibraryScanResult, error) {
-	return scanAudioFileWithKnownModTimeAndDisplayName(filePath, "", scanTime, knownModTime)
+	return scanAudioFileWithKnownModTimeAndDisplayNameAndCoverCacheKey(filePath, "", "", scanTime, knownModTime)
 }
 
 func scanAudioFileWithKnownModTimeAndDisplayName(filePath, displayNameHint, scanTime string, knownModTime int64) (*LibraryScanResult, error) {
+	return scanAudioFileWithKnownModTimeAndDisplayNameAndCoverCacheKey(filePath, displayNameHint, "", scanTime, knownModTime)
+}
+
+func scanAudioFileWithKnownModTimeAndDisplayNameAndCoverCacheKey(filePath, displayNameHint, coverCacheKey, scanTime string, knownModTime int64) (*LibraryScanResult, error) {
 	ext := resolveLibraryAudioExt(filePath, displayNameHint)
 
 	result := &LibraryScanResult{
@@ -292,7 +298,12 @@ func scanAudioFileWithKnownModTimeAndDisplayName(filePath, displayNameHint, scan
 	coverCacheDir := libraryCoverCacheDir
 	libraryCoverCacheMu.RUnlock()
 	if coverCacheDir != "" {
-		coverPath, err := SaveCoverToCacheWithHint(filePath, displayNameHint, coverCacheDir)
+		coverPath, err := SaveCoverToCacheWithHintAndKey(
+			filePath,
+			displayNameHint,
+			coverCacheDir,
+			coverCacheKey,
+		)
 		if err == nil && coverPath != "" {
 			result.CoverPath = coverPath
 		}
@@ -466,6 +477,7 @@ func scanOggFile(filePath string, result *LibraryScanResult, displayNameHint str
 }
 
 func scanFromFilename(filePath, displayNameHint string, result *LibraryScanResult) (*LibraryScanResult, error) {
+	result.MetadataFromFilename = true
 	nameSource := libraryDisplayNameOrPath(filePath, displayNameHint)
 	filename := strings.TrimSuffix(filepath.Base(nameSource), filepath.Ext(nameSource))
 
@@ -541,8 +553,18 @@ func ReadAudioMetadata(filePath string) (string, error) {
 }
 
 func ReadAudioMetadataWithDisplayName(filePath, displayNameHint string) (string, error) {
+	return ReadAudioMetadataWithDisplayNameAndCoverCacheKey(filePath, displayNameHint, "")
+}
+
+func ReadAudioMetadataWithDisplayNameAndCoverCacheKey(filePath, displayNameHint, coverCacheKey string) (string, error) {
 	scanTime := time.Now().UTC().Format(time.RFC3339)
-	result, err := scanAudioFileWithKnownModTimeAndDisplayName(filePath, displayNameHint, scanTime, 0)
+	result, err := scanAudioFileWithKnownModTimeAndDisplayNameAndCoverCacheKey(
+		filePath,
+		displayNameHint,
+		coverCacheKey,
+		scanTime,
+		0,
+	)
 	if err != nil {
 		return "", err
 	}
@@ -746,6 +768,7 @@ func scanLibraryFolderIncrementalWithExistingFiles(folderPath string, existingFi
 					cueInfo.audioPath,
 					"",
 					f.modTime,
+					"",
 					scanTime,
 				)
 			} else {

go_backend/library_scan_test.go

@@ -0,0 +1,25 @@
+package gobackend
+
+import "testing"
+
+func TestScanFromFilenameMarksMetadataFallback(t *testing.T) {
+	result := &LibraryScanResult{}
+
+	scanned, err := scanFromFilename(
+		"/proc/self/fd/209",
+		"189.mp3",
+		result,
+	)
+	if err != nil {
+		t.Fatalf("scanFromFilename returned error: %v", err)
+	}
+	if !scanned.MetadataFromFilename {
+		t.Fatal("expected filename fallback marker to be set")
+	}
+	if scanned.TrackName != "189" {
+		t.Fatalf("unexpected track name: %q", scanned.TrackName)
+	}
+	if scanned.ArtistName != "Unknown Artist" {
+		t.Fatalf("unexpected artist name: %q", scanned.ArtistName)
+	}
+}

go_backend/qobuz.go

@@ -13,6 +13,7 @@ import (
 	"os"
 	"path/filepath"
 	"regexp"
+	"sort"
 	"strconv"
 	"strings"
 	"sync"
@@ -1650,7 +1651,8 @@ func (q *QobuzDownloader) searchQobuzTracksViaAPI(query string, limit int) ([]Qo
 	defer resp.Body.Close()
 
 	if resp.StatusCode != 200 {
-		return nil, fmt.Errorf("search failed: HTTP %d", resp.StatusCode)
+		body, _ := io.ReadAll(io.LimitReader(resp.Body, 512))
+		return nil, fmt.Errorf("search failed: HTTP %d (%s)", resp.StatusCode, strings.TrimSpace(string(body)))
 	}
 
 	var result struct {
@@ -1664,6 +1666,234 @@ func (q *QobuzDownloader) searchQobuzTracksViaAPI(query string, limit int) ([]Qo
 	return result.Tracks.Items, nil
 }
 
+type qobuzTrackSearchCandidate struct {
+	score int
+	track QobuzTrack
+}
+
+func qobuzNormalizedSearchText(value string) string {
+	return normalizeLooseArtistName(value)
+}
+
+func qobuzSearchTokens(value string) []string {
+	normalized := qobuzNormalizedSearchText(value)
+	if normalized == "" {
+		return nil
+	}
+
+	parts := strings.Fields(normalized)
+	tokens := make([]string, 0, len(parts))
+	seen := make(map[string]struct{}, len(parts))
+	for _, part := range parts {
+		if len(part) < 2 {
+			continue
+		}
+		if _, ok := seen[part]; ok {
+			continue
+		}
+		seen[part] = struct{}{}
+		tokens = append(tokens, part)
+	}
+	return tokens
+}
+
+func qobuzScoreTrackSearchCandidate(query string, track *QobuzTrack) int {
+	if track == nil {
+		return 0
+	}
+
+	queryNorm := qobuzNormalizedSearchText(query)
+	if queryNorm == "" {
+		return 0
+	}
+
+	titleNorm := qobuzNormalizedSearchText(track.Title)
+	displayNorm := qobuzNormalizedSearchText(qobuzTrackDisplayTitle(track))
+	artistNorm := qobuzNormalizedSearchText(qobuzTrackArtistName(track))
+	albumNorm := qobuzNormalizedSearchText(strings.TrimSpace(track.Album.Title))
+
+	score := 0
+
+	if qobuzTitlesMatch(query, track.Title) || qobuzTitlesMatch(query, qobuzTrackDisplayTitle(track)) {
+		score += 900
+	}
+
+	switch {
+	case queryNorm == titleNorm, queryNorm == displayNorm:
+		score += 1200
+	case (titleNorm != "" && strings.Contains(titleNorm, queryNorm)) ||
+		(displayNorm != "" && strings.Contains(displayNorm, queryNorm)):
+		score += 420
+	case (titleNorm != "" && strings.Contains(queryNorm, titleNorm)) ||
+		(displayNorm != "" && strings.Contains(queryNorm, displayNorm)):
+		score += 260
+	}
+
+	if artistNorm != "" && strings.Contains(queryNorm, artistNorm) {
+		score += 180
+	}
+	if albumNorm != "" && strings.Contains(queryNorm, albumNorm) {
+		score += 100
+	}
+
+	for _, token := range qobuzSearchTokens(query) {
+		switch {
+		case strings.Contains(titleNorm, token), strings.Contains(displayNorm, token):
+			score += 180
+		case strings.Contains(artistNorm, token):
+			score += 70
+		case strings.Contains(albumNorm, token):
+			score += 35
+		}
+	}
+
+	if track.ISRC != "" {
+		score += 15
+	}
+	if track.MaximumBitDepth >= 24 {
+		score += 10
+	}
+	if track.MaximumSamplingRate >= 88.2 {
+		score += 10
+	}
+
+	return score
+}
+
+func selectQobuzTracksFromAlbumSearchResults(
+	query string,
+	limit int,
+	albumSummaries []qobuzAlbumDetails,
+	loadAlbum func(string) (*qobuzAlbumDetails, error),
+) ([]QobuzTrack, error) {
+	if strings.TrimSpace(query) == "" {
+		return nil, fmt.Errorf("empty qobuz album-search fallback query")
+	}
+	if len(albumSummaries) == 0 {
+		return nil, fmt.Errorf("album search returned no albums")
+	}
+
+	candidates := make([]qobuzTrackSearchCandidate, 0, limit)
+	seenTrackIDs := make(map[int64]struct{})
+
+	for _, summary := range albumSummaries {
+		albumID := strings.TrimSpace(summary.ID)
+		if albumID == "" {
+			continue
+		}
+
+		album, err := loadAlbum(albumID)
+		if err != nil || album == nil {
+			continue
+		}
+
+		for i := range album.Tracks.Items {
+			track := album.Tracks.Items[i]
+			track.Album.ID = album.ID
+			track.Album.QobuzID = album.QobuzID
+			track.Album.Title = album.Title
+			track.Album.ReleaseDate = album.ReleaseDateOriginal
+			track.Album.TracksCount = album.TracksCount
+			track.Album.ProductType = album.ProductType
+			track.Album.ReleaseType = album.ReleaseType
+			track.Album.Artist.ID = album.Artist.ID
+			track.Album.Artist.Name = album.Artist.Name
+			track.Album.Artists = album.Artists
+			track.Album.Image = album.Image
+
+			if track.ID > 0 {
+				if _, ok := seenTrackIDs[track.ID]; ok {
+					continue
+				}
+				seenTrackIDs[track.ID] = struct{}{}
+			}
+
+			score := qobuzScoreTrackSearchCandidate(query, &track)
+			if score <= 0 {
+				continue
+			}
+
+			candidates = append(candidates, qobuzTrackSearchCandidate{
+				score: score,
+				track: track,
+			})
+		}
+	}
+
+	if len(candidates) == 0 {
+		return nil, fmt.Errorf("album-search fallback returned no scored track candidates")
+	}
+
+	sort.SliceStable(candidates, func(i, j int) bool {
+		if candidates[i].score != candidates[j].score {
+			return candidates[i].score > candidates[j].score
+		}
+		if candidates[i].track.MaximumBitDepth != candidates[j].track.MaximumBitDepth {
+			return candidates[i].track.MaximumBitDepth > candidates[j].track.MaximumBitDepth
+		}
+		return candidates[i].track.ID < candidates[j].track.ID
+	})
+
+	if limit > 0 && len(candidates) > limit {
+		candidates = candidates[:limit]
+	}
+
+	tracks := make([]QobuzTrack, 0, len(candidates))
+	for _, candidate := range candidates {
+		tracks = append(tracks, candidate.track)
+	}
+	return tracks, nil
+}
+
+func (q *QobuzDownloader) searchQobuzTracksViaAlbumSearch(query string, limit int) ([]QobuzTrack, error) {
+	albumLimit := limit
+	if albumLimit < 3 {
+		albumLimit = 3
+	}
+	if albumLimit > 8 {
+		albumLimit = 8
+	}
+
+	searchURL := fmt.Sprintf(
+		"https://www.qobuz.com/api.json/0.2/album/search?query=%s&limit=%d&app_id=%s",
+		url.QueryEscape(strings.TrimSpace(query)),
+		albumLimit,
+		q.appID,
+	)
+
+	req, err := http.NewRequest("GET", searchURL, nil)
+	if err != nil {
+		return nil, err
+	}
+
+	resp, err := DoRequestWithUserAgent(q.client, req)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != 200 {
+		body, _ := io.ReadAll(io.LimitReader(resp.Body, 512))
+		return nil, fmt.Errorf("album search failed: HTTP %d (%s)", resp.StatusCode, strings.TrimSpace(string(body)))
+	}
+
+	var albumResp struct {
+		Albums struct {
+			Items []qobuzAlbumDetails `json:"items"`
+		} `json:"albums"`
+	}
+	if err := json.NewDecoder(resp.Body).Decode(&albumResp); err != nil {
+		return nil, err
+	}
+
+	return selectQobuzTracksFromAlbumSearchResults(
+		query,
+		limit,
+		albumResp.Albums.Items,
+		q.getAlbumDetails,
+	)
+}
+
 func extractQobuzTrackIDsFromStoreSearchHTML(body []byte) []int64 {
 	matches := qobuzStoreTrackIDRegex.FindAllSubmatch(body, -1)
 	if len(matches) == 0 {
@@ -1741,9 +1971,18 @@ func (q *QobuzDownloader) searchQobuzTracksWithFallback(query string, limit int)
 		if len(apiTracks) > 0 {
 			return apiTracks, nil
 		}
-		GoLog("[Qobuz] API search returned 0 results for '%s', trying store fallback\n", query)
+		GoLog("[Qobuz] API search returned 0 results for '%s', trying album-search fallback\n", query)
 	} else {
-		GoLog("[Qobuz] API search failed for '%s': %v. Trying store fallback.\n", query, apiErr)
+		GoLog("[Qobuz] API search failed for '%s': %v. Trying album-search fallback.\n", query, apiErr)
+	}
+
+	albumTracks, albumErr := q.searchQobuzTracksViaAlbumSearch(query, limit)
+	if albumErr == nil && len(albumTracks) > 0 {
+		GoLog("[Qobuz] Album-search fallback returned %d candidate tracks for '%s'\n", len(albumTracks), query)
+		return albumTracks, nil
+	}
+	if albumErr != nil {
+		GoLog("[Qobuz] Album-search fallback failed for '%s': %v. Trying store fallback.\n", query, albumErr)
 	}
 
 	storeTracks, storeErr := q.searchQobuzTracksViaStore(query, limit)
@@ -1752,10 +1991,21 @@ func (q *QobuzDownloader) searchQobuzTracksWithFallback(query string, limit int)
 		return storeTracks, nil
 	}
 
-	if apiErr != nil && storeErr != nil {
-		return nil, fmt.Errorf("api search failed (%v); store fallback failed (%v)", apiErr, storeErr)
+	if apiErr != nil && albumErr != nil && storeErr != nil {
+		return nil, fmt.Errorf(
+			"api search failed (%v); album-search fallback failed (%v); store fallback failed (%v)",
+			apiErr,
+			albumErr,
+			storeErr,
+		)
+	}
+	if albumErr == nil && len(albumTracks) == 0 && storeErr != nil {
+		return nil, storeErr
 	}
 	if storeErr != nil {
+		if albumErr != nil {
+			return nil, albumErr
+		}
 		return nil, storeErr
 	}
 	return nil, fmt.Errorf("no tracks found for query: %s", query)

go_backend/qobuz_test.go

@@ -5,6 +5,21 @@ import (
 	"testing"
 )
 
+func buildTestQobuzAlbum(id, title, artist string, tracks ...QobuzTrack) *qobuzAlbumDetails {
+	album := &qobuzAlbumDetails{
+		ID:                  id,
+		Title:               title,
+		ReleaseDateOriginal: "2013-05-20",
+		TracksCount:         len(tracks),
+		ProductType:         "album",
+		ReleaseType:         "album",
+	}
+	album.Artist = qobuzArtistRef{ID: 1, Name: artist}
+	album.Artists = []qobuzArtistRef{{ID: 1, Name: artist}}
+	album.Tracks.Items = tracks
+	return album
+}
+
 func TestParseQobuzURL(t *testing.T) {
 	tests := []struct {
 		name      string
@@ -276,6 +291,68 @@ func testQobuzTrack(id int64, title, artist string, duration int) *QobuzTrack {
 	return track
 }
 
+func TestSelectQobuzTracksFromAlbumSearchResultsPrefersMatchingTrack(t *testing.T) {
+	summaries := []qobuzAlbumDetails{
+		{ID: "album-a"},
+		{ID: "album-b"},
+	}
+
+	match := *testQobuzTrack(1, "Get Lucky", "Daft Punk", 369)
+	other := *testQobuzTrack(2, "Fragments of Time", "Daft Punk", 280)
+	fallback := *testQobuzTrack(3, "Da Funk", "Daft Punk", 330)
+
+	albums := map[string]*qobuzAlbumDetails{
+		"album-a": buildTestQobuzAlbum("album-a", "Random Access Memories", "Daft Punk", match, other),
+		"album-b": buildTestQobuzAlbum("album-b", "Homework", "Daft Punk", fallback),
+	}
+
+	tracks, err := selectQobuzTracksFromAlbumSearchResults(
+		"daft punk get lucky",
+		3,
+		summaries,
+		func(id string) (*qobuzAlbumDetails, error) { return albums[id], nil },
+	)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(tracks) == 0 {
+		t.Fatal("expected tracks, got none")
+	}
+	if tracks[0].ID != 1 {
+		t.Fatalf("expected Get Lucky to rank first, got track id %d", tracks[0].ID)
+	}
+}
+
+func TestSelectQobuzTracksFromAlbumSearchResultsDedupesTracks(t *testing.T) {
+	summaries := []qobuzAlbumDetails{
+		{ID: "album-a"},
+		{ID: "album-b"},
+	}
+
+	shared := *testQobuzTrack(42, "Get Lucky", "Daft Punk", 369)
+
+	albums := map[string]*qobuzAlbumDetails{
+		"album-a": buildTestQobuzAlbum("album-a", "Random Access Memories", "Daft Punk", shared),
+		"album-b": buildTestQobuzAlbum("album-b", "Random Access Memories Deluxe", "Daft Punk", shared),
+	}
+
+	tracks, err := selectQobuzTracksFromAlbumSearchResults(
+		"daft punk get lucky",
+		5,
+		summaries,
+		func(id string) (*qobuzAlbumDetails, error) { return albums[id], nil },
+	)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(tracks) != 1 {
+		t.Fatalf("expected 1 deduped track, got %d", len(tracks))
+	}
+	if tracks[0].ID != 42 {
+		t.Fatalf("unexpected deduped track id: %d", tracks[0].ID)
+	}
+}
+
 func TestResolveQobuzTrackForRequestRejectsSongLinkMismatch(t *testing.T) {
 	origGetTrackByID := qobuzGetTrackByIDFunc
 	origSearchISRC := qobuzSearchTrackByISRCWithDurationFunc