feat: enable Tidal ISRC and metadata search

- Fix setMetadataSource always returning 'deezer' regardless of input parameter
- Remove self-evident doc comments that restate method/class names across
  app_theme, dynamic_color_wrapper, cover_cache_manager, history_database,
  library_database, and download_service_picker
- Remove stale migration inline notes (// 12 -> 16, // 20 -> 16, etc.) from app_theme
- Remove trivial section-label comments in queue_tab batch conversion method
- Remove duplicate 'wait up to 5 seconds' comment in main_shell

android/app/src/main/kotlin/com/zarz/spotiflac/MainActivity.kt

@@ -30,6 +30,7 @@ import org.json.JSONObject
 import java.io.File
 import java.io.FileInputStream
 import java.io.FileOutputStream
+import java.security.MessageDigest
 import java.util.Locale
 
 class MainActivity: FlutterFragmentActivity() {
@@ -111,6 +112,13 @@ class MainActivity: FlutterFragmentActivity() {
         }
     }
 
+    private fun buildStableLibraryId(filePath: String): String {
+        val digest = MessageDigest.getInstance("SHA-1")
+        val bytes = digest.digest(filePath.toByteArray(Charsets.UTF_8))
+        val hex = bytes.joinToString("") { "%02x".format(it) }
+        return "lib_$hex"
+    }
+
     data class SafScanProgress(
         var totalFiles: Int = 0,
         var scannedFiles: Int = 0,
@@ -1263,7 +1271,9 @@ class MainActivity: FlutterFragmentActivity() {
             } else {
                 try {
                     val lastModified = try { doc.lastModified() } catch (_: Exception) { 0L }
-                    metadataObj.put("filePath", doc.uri.toString())
+                    val stableUri = doc.uri.toString()
+                    metadataObj.put("id", buildStableLibraryId(stableUri))
+                    metadataObj.put("filePath", stableUri)
                     metadataObj.put("fileModTime", lastModified)
                     results.put(metadataObj)
                 } catch (_: Exception) {
@@ -1680,7 +1690,9 @@ class MainActivity: FlutterFragmentActivity() {
             } else {
                 try {
                     val safeLastModified = try { doc.lastModified() } catch (_: Exception) { lastModified }
-                    metadataObj.put("filePath", doc.uri.toString())
+                    val stableUri = doc.uri.toString()
+                    metadataObj.put("id", buildStableLibraryId(stableUri))
+                    metadataObj.put("filePath", stableUri)
                     metadataObj.put("fileModTime", safeLastModified)
                     metadataObj.put("lastModified", safeLastModified)
                     results.put(metadataObj)

go_backend/extension_runtime.go

@@ -81,13 +81,14 @@ func SetExtensionTokens(extensionID string, accessToken, refreshToken string, ex
 }
 
 type ExtensionRuntime struct {
-	extensionID string
-	manifest    *ExtensionManifest
-	settings    map[string]interface{}
-	httpClient  *http.Client
-	cookieJar   http.CookieJar
-	dataDir     string
-	vm          *goja.Runtime
+	extensionID    string
+	manifest       *ExtensionManifest
+	settings       map[string]interface{}
+	httpClient     *http.Client
+	downloadClient *http.Client
+	cookieJar      http.CookieJar
+	dataDir        string
+	vm             *goja.Runtime
 
 	storageMu      sync.RWMutex
 	storageCache   map[string]interface{}
@@ -132,13 +133,20 @@ func NewExtensionRuntime(ext *LoadedExtension) *ExtensionRuntime {
 		storageFlushDelay: defaultStorageFlushDelay,
 	}
 
+	runtime.httpClient = newExtensionHTTPClient(ext, jar, 30*time.Second)
+	runtime.downloadClient = newExtensionHTTPClient(ext, jar, DownloadTimeout)
+
+	return runtime
+}
+
+func newExtensionHTTPClient(ext *LoadedExtension, jar http.CookieJar, timeout time.Duration) *http.Client {
 	// Extension sandbox enforces HTTPS-only domains. Do not apply global
 	// allow_http scheme downgrade here, because some extension APIs (e.g.
 	// spotify-web) will redirect http -> https and can end up in 301 loops.
 	// We still reuse sharedTransport so insecure TLS compatibility mode remains effective.
 	client := &http.Client{
 		Transport: sharedTransport,
-		Timeout:   30 * time.Second,
+		Timeout:   timeout,
 		Jar:       jar,
 	}
 	client.CheckRedirect = func(req *http.Request, via []*http.Request) error {
@@ -165,9 +173,7 @@ func NewExtensionRuntime(ext *LoadedExtension) *ExtensionRuntime {
 		}
 		return nil
 	}
-	runtime.httpClient = client
-
-	return runtime
+	return client
 }
 
 type RedirectBlockedError struct {

go_backend/extension_runtime_file.go

@@ -174,7 +174,12 @@ func (r *ExtensionRuntime) fileDownload(call goja.FunctionCall) goja.Value {
 		req.Header.Set("User-Agent", "SpotiFLAC-Extension/1.0")
 	}
 
-	resp, err := r.httpClient.Do(req)
+	client := r.downloadClient
+	if client == nil {
+		client = r.httpClient
+	}
+
+	resp, err := client.Do(req)
 	if err != nil {
 		return r.vm.ToValue(map[string]interface{}{
 			"success": false,

go_backend/httputil.go

@@ -346,11 +346,12 @@ func calculateNextDelay(currentDelay time.Duration, config RetryConfig) time.Dur
 	return min(nextDelay, config.MaxDelay)
 }
 
-// Returns 60 seconds as default if header is missing or invalid
+// Returns 0 if the header is missing or invalid so callers can keep their
+// normal exponential backoff instead of stalling for an arbitrary minute.
 func getRetryAfterDuration(resp *http.Response) time.Duration {
 	retryAfter := resp.Header.Get("Retry-After")
 	if retryAfter == "" {
-		return 60 * time.Second
+		return 0
 	}
 
 	if seconds, err := strconv.Atoi(retryAfter); err == nil {
@@ -364,7 +365,7 @@ func getRetryAfterDuration(resp *http.Response) time.Duration {
 		}
 	}
 
-	return 60 * time.Second
+	return 0
 }
 
 func ReadResponseBody(resp *http.Response) ([]byte, error) {

go_backend/lyrics.go

@@ -3,6 +3,7 @@ package gobackend
 import (
 	"encoding/json"
 	"fmt"
+	"io"
 	"math"
 	"net/http"
 	"net/url"
@@ -121,12 +122,12 @@ func GetLyricsProviderOrder() []string {
 // GetAvailableLyricsProviders returns metadata about all available providers.
 func GetAvailableLyricsProviders() []map[string]interface{} {
 	return []map[string]interface{}{
-		{"id": LyricsProviderSpotifyAPI, "name": "Spotify Lyrics API", "has_proxy_dependency": true, "description": "Spotify-sourced synced lyrics via community API"},
+		{"id": LyricsProviderSpotifyAPI, "name": "Spotify Lyrics API", "has_proxy_dependency": true, "description": "Spotify-sourced lyrics via Paxsenix"},
 		{"id": LyricsProviderLRCLIB, "name": "LRCLIB", "has_proxy_dependency": false, "description": "Open-source synced lyrics database"},
-		{"id": LyricsProviderNetease, "name": "Netease", "has_proxy_dependency": false, "description": "NetEase Cloud Music (good for Asian songs)"},
-		{"id": LyricsProviderMusixmatch, "name": "Musixmatch", "has_proxy_dependency": true, "description": "Largest lyrics database (multi-language)"},
-		{"id": LyricsProviderAppleMusic, "name": "Apple Music", "has_proxy_dependency": true, "description": "Word-by-word synced lyrics"},
-		{"id": LyricsProviderQQMusic, "name": "QQ Music", "has_proxy_dependency": true, "description": "QQ Music lyrics (good for Chinese songs)"},
+		{"id": LyricsProviderNetease, "name": "Netease", "has_proxy_dependency": true, "description": "NetEase Cloud Music lyrics via Paxsenix"},
+		{"id": LyricsProviderMusixmatch, "name": "Musixmatch", "has_proxy_dependency": true, "description": "Musixmatch lyrics via Paxsenix"},
+		{"id": LyricsProviderAppleMusic, "name": "Apple Music", "has_proxy_dependency": true, "description": "Apple Music synced lyrics via Paxsenix"},
+		{"id": LyricsProviderQQMusic, "name": "QQ Music", "has_proxy_dependency": true, "description": "QQ Music lyrics via Paxsenix"},
 	}
 }
 
@@ -431,6 +432,99 @@ func parseSpotifyRetryAfter(retryAfter string, now time.Time) time.Time {
 	return now.Add(10 * time.Minute)
 }
 
+func buildSpotifyLyricsResponse(lines []LyricsLine, syncType, plainLyrics string) (*LyricsResponse, error) {
+	if len(lines) == 0 {
+		return nil, fmt.Errorf("Spotify Lyrics API returned empty lines")
+	}
+	if syncType == "" {
+		if len(lines) > 0 && lines[0].StartTimeMs > 0 {
+			syncType = "LINE_SYNCED"
+		} else {
+			syncType = "UNSYNCED"
+		}
+	}
+	return &LyricsResponse{
+		Lines:        lines,
+		SyncType:     syncType,
+		Instrumental: false,
+		PlainLyrics:  plainLyrics,
+		Provider:     "Spotify Lyrics API",
+		Source:       "Spotify Lyrics API",
+	}, nil
+}
+
+func plainLyricsFromTimedLines(lines []LyricsLine) string {
+	parts := make([]string, 0, len(lines))
+	for _, line := range lines {
+		words := strings.TrimSpace(line.Words)
+		if words == "" {
+			continue
+		}
+		parts = append(parts, words)
+	}
+	return strings.Join(parts, "\n")
+}
+
+func parseSpotifyLyricsResponseBody(body []byte) (*LyricsResponse, error) {
+	var lrcPayload string
+	if err := json.Unmarshal(body, &lrcPayload); err == nil {
+		trimmed := strings.TrimSpace(lrcPayload)
+		if trimmed == "" {
+			return nil, fmt.Errorf("Spotify Lyrics API returned empty payload")
+		}
+
+		lines := parseSyncedLyrics(trimmed)
+		if len(lines) > 0 {
+			return buildSpotifyLyricsResponse(lines, "LINE_SYNCED", plainLyricsFromTimedLines(lines))
+		}
+
+		plainLines := plainTextLyricsLines(trimmed)
+		return buildSpotifyLyricsResponse(plainLines, "UNSYNCED", trimmed)
+	}
+
+	var apiResp SpotifyLyricsAPIResponse
+	if err := json.Unmarshal(body, &apiResp); err != nil {
+		return nil, fmt.Errorf("failed to parse Spotify Lyrics API response: %w", err)
+	}
+
+	if apiResp.Error {
+		msg := strings.TrimSpace(apiResp.Message)
+		if msg == "" {
+			msg = "Spotify Lyrics API returned error"
+		}
+		return nil, fmt.Errorf("%s", msg)
+	}
+
+	lines := make([]LyricsLine, 0, len(apiResp.Lines))
+	for _, line := range apiResp.Lines {
+		words := strings.TrimSpace(line.Words)
+		if words == "" {
+			continue
+		}
+		startMs := parseSpotifyLyricsTimeTagToMs(line.TimeTag)
+		lines = append(lines, LyricsLine{
+			StartTimeMs: startMs,
+			Words:       words,
+			EndTimeMs:   0,
+		})
+	}
+
+	for i := 0; i < len(lines)-1; i++ {
+		nextStart := lines[i+1].StartTimeMs
+		if nextStart > lines[i].StartTimeMs {
+			lines[i].EndTimeMs = nextStart
+		}
+	}
+	if len(lines) > 0 {
+		last := len(lines) - 1
+		if lines[last].EndTimeMs == 0 {
+			lines[last].EndTimeMs = lines[last].StartTimeMs + 5000
+		}
+	}
+
+	return buildSpotifyLyricsResponse(lines, apiResp.SyncType, plainLyricsFromTimedLines(lines))
+}
+
 func (c *LyricsClient) FetchLyricsFromSpotifyAPI(spotifyID string) (*LyricsResponse, error) {
 	now := time.Now()
 	if limitedUntil := getSpotifyLyricsRateLimitUntil(); limitedUntil.After(now) {
@@ -449,7 +543,7 @@ func (c *LyricsClient) FetchLyricsFromSpotifyAPI(spotifyID string) (*LyricsRespo
 		spotifyID = parsed.ID
 	}
 
-	apiURL := fmt.Sprintf("https://spotify-lyrics-api-pi.vercel.app/?trackid=%s&format=lrc", url.QueryEscape(spotifyID))
+	apiURL := fmt.Sprintf("https://lyrics.paxsenix.org/spotify/lyrics?id=%s", url.QueryEscape(spotifyID))
 	req, err := http.NewRequest("GET", apiURL, nil)
 	if err != nil {
 		return nil, fmt.Errorf("failed to create request: %w", err)
@@ -462,13 +556,18 @@ func (c *LyricsClient) FetchLyricsFromSpotifyAPI(spotifyID string) (*LyricsRespo
 	}
 	defer resp.Body.Close()
 
+	bodyBytes, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("failed to read Spotify Lyrics API response: %w", err)
+	}
+
 	if resp.StatusCode != 200 {
 		if resp.StatusCode == http.StatusTooManyRequests {
 			retryUntil := parseSpotifyRetryAfter(resp.Header.Get("Retry-After"), now)
 			setSpotifyLyricsRateLimitUntil(retryUntil)
 		}
 		var payload map[string]interface{}
-		if err := json.NewDecoder(resp.Body).Decode(&payload); err == nil {
+		if err := json.Unmarshal(bodyBytes, &payload); err == nil {
 			if msg, ok := payload["message"].(string); ok && strings.TrimSpace(msg) != "" {
 				return nil, fmt.Errorf("Spotify Lyrics API returned status %d: %s", resp.StatusCode, strings.TrimSpace(msg))
 			}
@@ -479,63 +578,7 @@ func (c *LyricsClient) FetchLyricsFromSpotifyAPI(spotifyID string) (*LyricsRespo
 		return nil, fmt.Errorf("Spotify Lyrics API returned status %d", resp.StatusCode)
 	}
 
-	var apiResp SpotifyLyricsAPIResponse
-	if err := json.NewDecoder(resp.Body).Decode(&apiResp); err != nil {
-		return nil, fmt.Errorf("failed to parse Spotify Lyrics API response: %w", err)
-	}
-
-	if apiResp.Error {
-		msg := strings.TrimSpace(apiResp.Message)
-		if msg == "" {
-			msg = "Spotify Lyrics API returned error"
-		}
-		return nil, fmt.Errorf("%s", msg)
-	}
-
-	result := &LyricsResponse{
-		Lines:        make([]LyricsLine, 0, len(apiResp.Lines)),
-		SyncType:     apiResp.SyncType,
-		Instrumental: false,
-		PlainLyrics:  "",
-		Provider:     "Spotify Lyrics API",
-		Source:       "Spotify Lyrics API",
-	}
-
-	for _, line := range apiResp.Lines {
-		words := strings.TrimSpace(line.Words)
-		if words == "" {
-			continue
-		}
-		startMs := parseSpotifyLyricsTimeTagToMs(line.TimeTag)
-		result.Lines = append(result.Lines, LyricsLine{
-			StartTimeMs: startMs,
-			Words:       words,
-			EndTimeMs:   0,
-		})
-	}
-
-	if len(result.Lines) > 1 {
-		for i := 0; i < len(result.Lines)-1; i++ {
-			nextStart := result.Lines[i+1].StartTimeMs
-			if nextStart > result.Lines[i].StartTimeMs {
-				result.Lines[i].EndTimeMs = nextStart
-			}
-		}
-		last := len(result.Lines) - 1
-		if result.Lines[last].EndTimeMs == 0 {
-			result.Lines[last].EndTimeMs = result.Lines[last].StartTimeMs + 5000
-		}
-	}
-
-	if len(result.Lines) == 0 {
-		return nil, fmt.Errorf("Spotify Lyrics API returned empty lines")
-	}
-
-	if result.SyncType == "" {
-		result.SyncType = "LINE_SYNCED"
-	}
-
-	return result, nil
+	return parseSpotifyLyricsResponseBody(bodyBytes)
 }
 
 func (c *LyricsClient) findBestMatch(results []LRCLibResponse, targetDurationSec float64) *LRCLibResponse {

go_backend/lyrics_apple.go

@@ -4,121 +4,25 @@ import (
 	"encoding/json"
 	"fmt"
 	"io"
+	"math"
 	"net/http"
 	"net/url"
-	"regexp"
 	"strings"
-	"sync"
 	"time"
 )
 
 // AppleMusicClient fetches lyrics from Apple Music.
-// Uses a scraped JWT token for search and a proxy for lyrics.
+// Uses Paxsenix endpoints for search and lyrics.
 type AppleMusicClient struct {
 	httpClient *http.Client
 }
 
-// Apple Music token manager — singleton with mutex for thread safety
-type appleTokenManager struct {
-	mu    sync.Mutex
-	token string
-}
-
-var globalAppleTokenManager = &appleTokenManager{}
-
-func (m *appleTokenManager) getToken(client *http.Client) (string, error) {
-	m.mu.Lock()
-	defer m.mu.Unlock()
-
-	if m.token != "" {
-		return m.token, nil
-	}
-
-	// Step 1: Fetch the Apple Music beta page
-	req, err := http.NewRequest("GET", "https://beta.music.apple.com", nil)
-	if err != nil {
-		return "", fmt.Errorf("failed to create request: %w", err)
-	}
-	req.Header.Set("User-Agent", getRandomUserAgent())
-
-	resp, err := client.Do(req)
-	if err != nil {
-		return "", fmt.Errorf("failed to fetch Apple Music page: %w", err)
-	}
-	defer resp.Body.Close()
-
-	body, err := io.ReadAll(resp.Body)
-	if err != nil {
-		return "", fmt.Errorf("failed to read Apple Music page: %w", err)
-	}
-
-	// Step 2: Find the index JS file URL
-	indexJsRegex := regexp.MustCompile(`/assets/index~[^/]+\.js`)
-	match := indexJsRegex.Find(body)
-	if match == nil {
-		return "", fmt.Errorf("could not find index JS script URL on Apple Music page")
-	}
-
-	indexJsURL := "https://beta.music.apple.com" + string(match)
-
-	// Step 3: Fetch the JS file
-	jsReq, err := http.NewRequest("GET", indexJsURL, nil)
-	if err != nil {
-		return "", fmt.Errorf("failed to create JS request: %w", err)
-	}
-	jsReq.Header.Set("User-Agent", getRandomUserAgent())
-
-	jsResp, err := client.Do(jsReq)
-	if err != nil {
-		return "", fmt.Errorf("failed to fetch Apple Music JS: %w", err)
-	}
-	defer jsResp.Body.Close()
-
-	jsBody, err := io.ReadAll(jsResp.Body)
-	if err != nil {
-		return "", fmt.Errorf("failed to read Apple Music JS: %w", err)
-	}
-
-	// Step 4: Extract JWT token (starts with eyJh)
-	tokenRegex := regexp.MustCompile(`eyJh[^"]*`)
-	tokenMatch := tokenRegex.Find(jsBody)
-	if tokenMatch == nil {
-		return "", fmt.Errorf("could not find JWT token in Apple Music JS")
-	}
-
-	m.token = string(tokenMatch)
-	GoLog("[AppleMusic] Token obtained successfully (length: %d)\n", len(m.token))
-	return m.token, nil
-}
-
-func (m *appleTokenManager) clearToken() {
-	m.mu.Lock()
-	defer m.mu.Unlock()
-	m.token = ""
-}
-
-type appleMusicSearchResponse struct {
-	Results struct {
-		Songs *struct {
-			Data []struct {
-				ID   string `json:"id"`
-				Type string `json:"type"`
-			} `json:"data"`
-		} `json:"songs"`
-	} `json:"results"`
-	Resources *struct {
-		Songs map[string]struct {
-			Attributes struct {
-				Name       string `json:"name"`
-				ArtistName string `json:"artistName"`
-				AlbumName  string `json:"albumName"`
-				URL        string `json:"url"`
-				Artwork    struct {
-					URL string `json:"url"`
-				} `json:"artwork"`
-			} `json:"attributes"`
-		} `json:"songs"`
-	} `json:"resources"`
+type appleMusicSearchResult struct {
+	ID         string `json:"id"`
+	SongName   string `json:"songName"`
+	ArtistName string `json:"artistName"`
+	AlbumName  string `json:"albumName"`
+	Duration   int    `json:"duration"`
 }
 
 // PaxResponse represents the lyrics proxy response for word-by-word / line lyrics
@@ -149,32 +53,71 @@ func NewAppleMusicClient() *AppleMusicClient {
 	}
 }
 
+func selectBestAppleMusicSearchResult(results []appleMusicSearchResult, trackName, artistName string, durationSec float64) *appleMusicSearchResult {
+	if len(results) == 0 {
+		return nil
+	}
+
+	normalizedTrack := strings.ToLower(strings.TrimSpace(simplifyTrackName(trackName)))
+	normalizedArtist := strings.ToLower(strings.TrimSpace(normalizeArtistName(artistName)))
+	if normalizedArtist == "" {
+		normalizedArtist = strings.ToLower(strings.TrimSpace(artistName))
+	}
+
+	bestIndex := 0
+	bestScore := -1
+	for i := range results {
+		result := &results[i]
+		score := 0
+
+		candidateTrack := strings.ToLower(strings.TrimSpace(simplifyTrackName(result.SongName)))
+		candidateArtist := strings.ToLower(strings.TrimSpace(normalizeArtistName(result.ArtistName)))
+
+		switch {
+		case candidateTrack == normalizedTrack:
+			score += 50
+		case strings.Contains(candidateTrack, normalizedTrack) || strings.Contains(normalizedTrack, candidateTrack):
+			score += 25
+		}
+
+		switch {
+		case candidateArtist == normalizedArtist:
+			score += 60
+		case strings.Contains(candidateArtist, normalizedArtist) || strings.Contains(normalizedArtist, candidateArtist):
+			score += 30
+		}
+
+		if durationSec > 0 && result.Duration > 0 {
+			diff := math.Abs(float64(result.Duration)/1000.0 - durationSec)
+			if diff <= durationToleranceSec {
+				score += 20
+			}
+		}
+
+		if score > bestScore {
+			bestScore = score
+			bestIndex = i
+		}
+	}
+
+	return &results[bestIndex]
+}
+
 // SearchSong searches for a song on Apple Music and returns its ID.
-func (c *AppleMusicClient) SearchSong(trackName, artistName string) (string, error) {
+func (c *AppleMusicClient) SearchSong(trackName, artistName string, durationSec float64) (string, error) {
 	query := trackName + " " + artistName
 	if strings.TrimSpace(query) == "" {
 		return "", fmt.Errorf("empty search query")
 	}
 
-	token, err := globalAppleTokenManager.getToken(c.httpClient)
-	if err != nil {
-		return "", fmt.Errorf("apple music token error: %w", err)
-	}
-
 	encodedQuery := url.QueryEscape(query)
-	searchURL := fmt.Sprintf(
-		"https://amp-api.music.apple.com/v1/catalog/us/search?term=%s&types=songs&limit=5&l=en-US&platform=web&format[resources]=map&include[songs]=artists&extend=artistUrl",
-		encodedQuery,
-	)
+	searchURL := fmt.Sprintf("https://lyrics.paxsenix.org/apple-music/search?q=%s", encodedQuery)
 
 	req, err := http.NewRequest("GET", searchURL, nil)
 	if err != nil {
 		return "", fmt.Errorf("failed to create request: %w", err)
 	}
 
-	req.Header.Set("Authorization", "Bearer "+token)
-	req.Header.Set("Origin", "https://music.apple.com")
-	req.Header.Set("Referer", "https://music.apple.com/")
 	req.Header.Set("User-Agent", getRandomUserAgent())
 	req.Header.Set("Accept", "application/json")
 
@@ -184,25 +127,21 @@ func (c *AppleMusicClient) SearchSong(trackName, artistName string) (string, err
 	}
 	defer resp.Body.Close()
 
-	if resp.StatusCode == 401 {
-		globalAppleTokenManager.clearToken()
-		return "", fmt.Errorf("apple music token expired")
-	}
-
 	if resp.StatusCode != 200 {
 		return "", fmt.Errorf("apple music search returned HTTP %d", resp.StatusCode)
 	}
 
-	var searchResp appleMusicSearchResponse
+	var searchResp []appleMusicSearchResult
 	if err := json.NewDecoder(resp.Body).Decode(&searchResp); err != nil {
 		return "", fmt.Errorf("failed to decode apple music response: %w", err)
 	}
 
-	if searchResp.Results.Songs == nil || len(searchResp.Results.Songs.Data) == 0 {
+	best := selectBestAppleMusicSearchResult(searchResp, trackName, artistName, durationSec)
+	if best == nil || strings.TrimSpace(best.ID) == "" {
 		return "", fmt.Errorf("no songs found on apple music")
 	}
 
-	return searchResp.Results.Songs.Data[0].ID, nil
+	return strings.TrimSpace(best.ID), nil
 }
 
 // FetchLyricsByID fetches lyrics from the paxsenix proxy using Apple Music song ID.
@@ -320,7 +259,7 @@ func (c *AppleMusicClient) FetchLyrics(
 	durationSec float64,
 	multiPersonWordByWord bool,
 ) (*LyricsResponse, error) {
-	songID, err := c.SearchSong(trackName, artistName)
+	songID, err := c.SearchSong(trackName, artistName, durationSec)
 	if err != nil {
 		return nil, err
 	}

go_backend/lyrics_musixmatch.go

@@ -3,6 +3,8 @@ package gobackend
 import (
 	"encoding/json"
 	"fmt"
+	"io"
+	"math"
 	"net/http"
 	"net/url"
 	"strings"
@@ -45,100 +47,105 @@ type musixmatchLyricsResponse struct {
 func NewMusixmatchClient() *MusixmatchClient {
 	return &MusixmatchClient{
 		httpClient: NewMetadataHTTPClient(15 * time.Second),
-		baseURL:    "http://158.180.60.95",
+		baseURL:    "https://lyrics.paxsenix.org/musixmatch/lyrics",
 	}
 }
 
-// searchAndGetLyrics searches for a song and retrieves its lyrics in one call.
-// The Musixmatch proxy returns both search result and lyrics in a single response.
-func (c *MusixmatchClient) searchAndGetLyrics(trackName, artistName string) (*musixmatchSearchResponse, error) {
+func (c *MusixmatchClient) fetchLyricsPayload(trackName, artistName string, durationSec float64, lyricsType, language string) (string, error) {
 	if strings.TrimSpace(trackName) == "" || strings.TrimSpace(artistName) == "" {
-		return nil, fmt.Errorf("empty track or artist name")
+		return "", fmt.Errorf("empty track or artist name")
 	}
 
-	encodedArtist := url.QueryEscape(artistName)
-	encodedTrack := url.QueryEscape(trackName)
-
-	fullURL := fmt.Sprintf("%s/v2/full?artist=%s&track=%s", c.baseURL, encodedArtist, encodedTrack)
+	params := url.Values{}
+	params.Set("t", trackName)
+	params.Set("a", artistName)
+	params.Set("type", lyricsType)
+	params.Set("format", "lrc")
+	if durationSec > 0 {
+		params.Set("d", fmt.Sprintf("%d", int(math.Round(durationSec))))
+	}
+	if strings.TrimSpace(language) != "" {
+		params.Set("l", strings.ToLower(strings.TrimSpace(language)))
+	}
+	fullURL := c.baseURL + "?" + params.Encode()
 
 	req, err := http.NewRequest("GET", fullURL, nil)
 	if err != nil {
-		return nil, fmt.Errorf("failed to create request: %w", err)
+		return "", fmt.Errorf("failed to create request: %w", err)
 	}
+	req.Header.Set("Accept", "application/json")
 	req.Header.Set("User-Agent", getRandomUserAgent())
 
 	resp, err := c.httpClient.Do(req)
 	if err != nil {
-		return nil, fmt.Errorf("musixmatch search failed: %w", err)
+		return "", fmt.Errorf("musixmatch request failed: %w", err)
 	}
 	defer resp.Body.Close()
 
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return "", fmt.Errorf("failed to read musixmatch response: %w", err)
+	}
+
 	if resp.StatusCode != 200 {
-		return nil, fmt.Errorf("musixmatch proxy returned HTTP %d", resp.StatusCode)
+		trimmed := strings.TrimSpace(string(body))
+		if errMsg, isErrorPayload := detectLyricsErrorPayload(trimmed); isErrorPayload {
+			return "", fmt.Errorf("musixmatch proxy returned HTTP %d: %s", resp.StatusCode, errMsg)
+		}
+		return "", fmt.Errorf("musixmatch proxy returned HTTP %d", resp.StatusCode)
 	}
 
-	var result musixmatchSearchResponse
-	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
-		return nil, fmt.Errorf("failed to decode musixmatch response: %w", err)
+	var lrcPayload string
+	if err := json.Unmarshal(body, &lrcPayload); err == nil {
+		lrcPayload = strings.TrimSpace(lrcPayload)
+		if lrcPayload == "" {
+			return "", fmt.Errorf("empty musixmatch lyrics payload")
+		}
+		return lrcPayload, nil
 	}
 
-	return &result, nil
+	trimmed := strings.TrimSpace(string(body))
+	if errMsg, isErrorPayload := detectLyricsErrorPayload(trimmed); isErrorPayload {
+		return "", fmt.Errorf("%s", errMsg)
+	}
+	if trimmed != "" && !strings.HasPrefix(trimmed, "{") {
+		return trimmed, nil
+	}
+	return "", fmt.Errorf("failed to decode musixmatch response")
 }
 
 // FetchLyricsInLanguage retrieves lyrics from Musixmatch for a specific language code.
-func (c *MusixmatchClient) FetchLyricsInLanguage(songID int64, language string) (*LyricsResponse, error) {
+func (c *MusixmatchClient) FetchLyricsInLanguage(trackName, artistName string, durationSec float64, language string) (*LyricsResponse, error) {
 	lang := strings.ToLower(strings.TrimSpace(language))
-	if songID <= 0 || lang == "" {
-		return nil, fmt.Errorf("invalid song id or language")
+	if lang == "" {
+		return nil, fmt.Errorf("invalid language")
 	}
 
-	fullURL := fmt.Sprintf("%s/v2/full?id=%d&lang=%s", c.baseURL, songID, url.QueryEscape(lang))
-
-	req, err := http.NewRequest("GET", fullURL, nil)
+	lrcText, err := c.fetchLyricsPayload(trackName, artistName, durationSec, "translate", lang)
 	if err != nil {
-		return nil, fmt.Errorf("failed to create request: %w", err)
-	}
-	req.Header.Set("User-Agent", getRandomUserAgent())
-
-	resp, err := c.httpClient.Do(req)
-	if err != nil {
-		return nil, fmt.Errorf("musixmatch language fetch failed: %w", err)
-	}
-	defer resp.Body.Close()
-
-	if resp.StatusCode != 200 {
-		return nil, fmt.Errorf("musixmatch language endpoint returned HTTP %d", resp.StatusCode)
+		return nil, err
 	}
 
-	var result musixmatchSearchResponse
-	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
-		return nil, fmt.Errorf("failed to decode musixmatch language response: %w", err)
+	lines := parseSyncedLyrics(lrcText)
+	if len(lines) > 0 {
+		return &LyricsResponse{
+			Lines:       lines,
+			SyncType:    "LINE_SYNCED",
+			PlainLyrics: plainLyricsFromTimedLines(lines),
+			Provider:    "Musixmatch",
+			Source:      fmt.Sprintf("Musixmatch (%s)", lang),
+		}, nil
 	}
 
-	if result.SyncedLyrics != nil && strings.TrimSpace(result.SyncedLyrics.Lyrics) != "" {
-		lines := parseSyncedLyrics(result.SyncedLyrics.Lyrics)
-		if len(lines) > 0 {
-			return &LyricsResponse{
-				Lines:    lines,
-				SyncType: "LINE_SYNCED",
-				Provider: "Musixmatch",
-				Source:   fmt.Sprintf("Musixmatch (%s)", lang),
-			}, nil
-		}
-	}
-
-	if result.UnsyncedLyrics != nil && strings.TrimSpace(result.UnsyncedLyrics.Lyrics) != "" {
-		lines := plainTextLyricsLines(result.UnsyncedLyrics.Lyrics)
-
-		if len(lines) > 0 {
-			return &LyricsResponse{
-				Lines:       lines,
-				SyncType:    "UNSYNCED",
-				PlainLyrics: result.UnsyncedLyrics.Lyrics,
-				Provider:    "Musixmatch",
-				Source:      fmt.Sprintf("Musixmatch (%s)", lang),
-			}, nil
-		}
+	plainLines := plainTextLyricsLines(lrcText)
+	if len(plainLines) > 0 {
+		return &LyricsResponse{
+			Lines:       plainLines,
+			SyncType:    "UNSYNCED",
+			PlainLyrics: lrcText,
+			Provider:    "Musixmatch",
+			Source:      fmt.Sprintf("Musixmatch (%s)", lang),
+		}, nil
 	}
 
 	return nil, fmt.Errorf("no lyrics found on musixmatch for language %s", lang)
@@ -146,43 +153,39 @@ func (c *MusixmatchClient) FetchLyricsInLanguage(songID int64, language string)
 
 // FetchLyrics searches Musixmatch and returns parsed LyricsResponse.
 func (c *MusixmatchClient) FetchLyrics(trackName, artistName string, durationSec float64, preferredLanguage string) (*LyricsResponse, error) {
-	result, err := c.searchAndGetLyrics(trackName, artistName)
-	if err != nil {
-		return nil, err
-	}
-
-	if preferred := strings.ToLower(strings.TrimSpace(preferredLanguage)); preferred != "" && result.ID > 0 {
-		localized, localizedErr := c.FetchLyricsInLanguage(result.ID, preferred)
+	if preferred := strings.ToLower(strings.TrimSpace(preferredLanguage)); preferred != "" {
+		localized, localizedErr := c.FetchLyricsInLanguage(trackName, artistName, durationSec, preferred)
 		if localizedErr == nil {
 			return localized, nil
 		}
 		GoLog("[Musixmatch] Language override '%s' failed: %v\n", preferred, localizedErr)
 	}
 
-	if result.SyncedLyrics != nil && strings.TrimSpace(result.SyncedLyrics.Lyrics) != "" {
-		lines := parseSyncedLyrics(result.SyncedLyrics.Lyrics)
-		if len(lines) > 0 {
-			return &LyricsResponse{
-				Lines:    lines,
-				SyncType: "LINE_SYNCED",
-				Provider: "Musixmatch",
-				Source:   "Musixmatch",
-			}, nil
-		}
+	lrcText, err := c.fetchLyricsPayload(trackName, artistName, durationSec, "word", "")
+	if err != nil {
+		return nil, err
 	}
 
-	if result.UnsyncedLyrics != nil && strings.TrimSpace(result.UnsyncedLyrics.Lyrics) != "" {
-		lines := plainTextLyricsLines(result.UnsyncedLyrics.Lyrics)
+	lines := parseSyncedLyrics(lrcText)
+	if len(lines) > 0 {
+		return &LyricsResponse{
+			Lines:       lines,
+			SyncType:    "LINE_SYNCED",
+			PlainLyrics: plainLyricsFromTimedLines(lines),
+			Provider:    "Musixmatch",
+			Source:      "Musixmatch",
+		}, nil
+	}
 
-		if len(lines) > 0 {
-			return &LyricsResponse{
-				Lines:       lines,
-				SyncType:    "UNSYNCED",
-				PlainLyrics: result.UnsyncedLyrics.Lyrics,
-				Provider:    "Musixmatch",
-				Source:      "Musixmatch",
-			}, nil
-		}
+	plainLines := plainTextLyricsLines(lrcText)
+	if len(plainLines) > 0 {
+		return &LyricsResponse{
+			Lines:       plainLines,
+			SyncType:    "UNSYNCED",
+			PlainLyrics: lrcText,
+			Provider:    "Musixmatch",
+			Source:      "Musixmatch",
+		}, nil
 	}
 
 	return nil, fmt.Errorf("no lyrics found on musixmatch")

go_backend/lyrics_netease.go

@@ -9,8 +9,7 @@ import (
 	"time"
 )
 
-// NeteaseClient fetches lyrics from NetEase Cloud Music (music.163.com).
-// This is a direct public API — no proxy dependency.
+// NeteaseClient fetches lyrics through Paxsenix's NetEase endpoints.
 type NeteaseClient struct {
 	httpClient *http.Client
 }
@@ -59,12 +58,9 @@ func (c *NeteaseClient) SearchSong(trackName, artistName string) (int64, error)
 		return 0, fmt.Errorf("empty search query")
 	}
 
-	searchURL := "http://music.163.com/api/search/pc"
+	searchURL := "https://lyrics.paxsenix.org/netease/search"
 	params := url.Values{}
-	params.Set("s", query)
-	params.Set("type", "1")
-	params.Set("limit", "1")
-	params.Set("offset", "0")
+	params.Set("q", query)
 
 	fullURL := searchURL + "?" + params.Encode()
 
@@ -102,12 +98,9 @@ func (c *NeteaseClient) SearchSong(trackName, artistName string) (int64, error)
 
 // FetchLyricsByID fetches synced lyrics for a given Netease song ID.
 func (c *NeteaseClient) FetchLyricsByID(songID int64, includeTranslation, includeRomanization bool) (string, error) {
-	lyricsURL := "http://music.163.com/api/song/lyric"
+	lyricsURL := "https://lyrics.paxsenix.org/netease/lyrics"
 	params := url.Values{}
 	params.Set("id", fmt.Sprintf("%d", songID))
-	params.Set("lv", "1")
-	params.Set("tv", "1")
-	params.Set("rv", "1")
 
 	fullURL := lyricsURL + "?" + params.Encode()
 

go_backend/lyrics_qqmusic.go

@@ -1,45 +1,31 @@
 package gobackend
 
 import (
-	"bytes"
 	"encoding/json"
 	"fmt"
 	"io"
+	"math"
 	"net/http"
-	"net/url"
 	"strings"
 	"time"
 )
 
 // QQMusicClient fetches lyrics from QQ Music.
-// Search uses public QQ Music API, lyrics use the paxsenix proxy.
+// Uses Paxsenix metadata lookup for lyrics.
 type QQMusicClient struct {
 	httpClient *http.Client
 }
 
-type qqMusicSearchResponse struct {
-	Data struct {
-		Song struct {
-			List []struct {
-				Title  string `json:"title"`
-				Singer []struct {
-					Name string `json:"name"`
-				} `json:"singer"`
-				Album struct {
-					Name string `json:"name"`
-				} `json:"album"`
-				ID int64 `json:"id"`
-			} `json:"list"`
-		} `json:"song"`
-	} `json:"data"`
+type qqLyricsMetadataRequest struct {
+	Artist   []string `json:"artist"`
+	Album    string   `json:"album,omitempty"`
+	SongID   int64    `json:"songid,omitempty"`
+	Title    string   `json:"title"`
+	Duration int64    `json:"duration,omitempty"`
 }
 
-// QQ Music lyrics request payload for paxsenix proxy
-type qqLyricsPayload struct {
-	Artist []string `json:"artist"`
-	Album  string   `json:"album"`
-	ID     int64    `json:"id"`
-	Title  string   `json:"title"`
+type qqLyricsMetadataResponse struct {
+	Lyrics []paxLyrics `json:"lyrics"`
 }
 
 func NewQQMusicClient() *QQMusicClient {
@@ -48,79 +34,29 @@ func NewQQMusicClient() *QQMusicClient {
 	}
 }
 
-// searchSong searches QQ Music and returns the song info needed for lyrics fetch.
-func (c *QQMusicClient) searchSong(trackName, artistName string) (*qqLyricsPayload, error) {
-	query := trackName + " " + artistName
-	if strings.TrimSpace(query) == "" {
-		return nil, fmt.Errorf("empty search query")
+// fetchLyricsByMetadata asks Paxsenix to resolve and return QQ lyrics using track metadata.
+func (c *QQMusicClient) fetchLyricsByMetadata(trackName, artistName string, durationSec float64) (string, error) {
+	payload := qqLyricsMetadataRequest{
+		Artist: []string{artistName},
+		Title:  trackName,
+	}
+	if durationSec > 0 {
+		payload.Duration = int64(math.Round(durationSec))
 	}
 
-	searchURL := "https://c.y.qq.com/soso/fcgi-bin/client_search_cp"
-	params := url.Values{}
-	params.Set("format", "json")
-	params.Set("inCharset", "utf8")
-	params.Set("outCharset", "utf8")
-	params.Set("platform", "yqq.json")
-	params.Set("new_json", "1")
-	params.Set("w", query)
-
-	fullURL := searchURL + "?" + params.Encode()
-
-	req, err := http.NewRequest("GET", fullURL, nil)
-	if err != nil {
-		return nil, fmt.Errorf("failed to create request: %w", err)
-	}
-	req.Header.Set("Content-Type", "application/json")
-	req.Header.Set("User-Agent", getRandomUserAgent())
-
-	resp, err := c.httpClient.Do(req)
-	if err != nil {
-		return nil, fmt.Errorf("qqmusic search failed: %w", err)
-	}
-	defer resp.Body.Close()
-
-	if resp.StatusCode != 200 {
-		return nil, fmt.Errorf("qqmusic search returned HTTP %d", resp.StatusCode)
-	}
-
-	var searchResp qqMusicSearchResponse
-	if err := json.NewDecoder(resp.Body).Decode(&searchResp); err != nil {
-		return nil, fmt.Errorf("failed to decode qqmusic response: %w", err)
-	}
-
-	if len(searchResp.Data.Song.List) == 0 {
-		return nil, fmt.Errorf("no songs found on qqmusic")
-	}
-
-	song := searchResp.Data.Song.List[0]
-
-	var artists []string
-	for _, singer := range song.Singer {
-		artists = append(artists, singer.Name)
-	}
-
-	return &qqLyricsPayload{
-		Artist: artists,
-		Album:  song.Album.Name,
-		ID:     song.ID,
-		Title:  song.Title,
-	}, nil
-}
-
-// fetchLyricsByPayload fetches lyrics from the paxsenix proxy using QQ Music song info.
-func (c *QQMusicClient) fetchLyricsByPayload(payload *qqLyricsPayload) (string, error) {
-	lyricsURL := "https://paxsenix.alwaysdata.net/getQQLyrics.php"
+	lyricsURL := "https://lyrics.paxsenix.org/qq/lyrics-metadata"
 
 	payloadBytes, err := json.Marshal(payload)
 	if err != nil {
 		return "", fmt.Errorf("failed to marshal payload: %w", err)
 	}
 
-	req, err := http.NewRequest("POST", lyricsURL, bytes.NewReader(payloadBytes))
+	req, err := http.NewRequest("POST", lyricsURL, strings.NewReader(string(payloadBytes)))
 	if err != nil {
 		return "", fmt.Errorf("failed to create request: %w", err)
 	}
 	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Accept", "application/json")
 	req.Header.Set("User-Agent", getRandomUserAgent())
 
 	resp, err := c.httpClient.Do(req)
@@ -146,6 +82,17 @@ func (c *QQMusicClient) fetchLyricsByPayload(payload *qqLyricsPayload) (string,
 	return bodyStr, nil
 }
 
+func formatQQLyricsMetadataToLRC(rawJSON string, multiPersonWordByWord bool) (string, error) {
+	var response qqLyricsMetadataResponse
+	if err := json.Unmarshal([]byte(rawJSON), &response); err != nil {
+		return "", fmt.Errorf("failed to parse qq metadata lyrics response")
+	}
+	if len(response.Lyrics) == 0 {
+		return "", fmt.Errorf("qq metadata lyrics response was empty")
+	}
+	return formatPaxContent("Syllable", response.Lyrics, multiPersonWordByWord), nil
+}
+
 // FetchLyrics searches QQ Music and returns parsed LyricsResponse.
 func (c *QQMusicClient) FetchLyrics(
 	trackName,
@@ -153,12 +100,7 @@ func (c *QQMusicClient) FetchLyrics(
 	durationSec float64,
 	multiPersonWordByWord bool,
 ) (*LyricsResponse, error) {
-	payload, err := c.searchSong(trackName, artistName)
-	if err != nil {
-		return nil, err
-	}
-
-	rawLyrics, err := c.fetchLyricsByPayload(payload)
+	rawLyrics, err := c.fetchLyricsByMetadata(trackName, artistName, durationSec)
 	if err != nil {
 		return nil, err
 	}
@@ -166,11 +108,13 @@ func (c *QQMusicClient) FetchLyrics(
 		return nil, fmt.Errorf("qqmusic proxy returned non-lyric payload: %s", errMsg)
 	}
 
-	// Try to parse as pax format (word-by-word or line)
-	lrcText, err := formatPaxLyricsToLRC(rawLyrics, multiPersonWordByWord)
+	lrcText, err := formatQQLyricsMetadataToLRC(rawLyrics, multiPersonWordByWord)
 	if err != nil {
-		// If pax parsing fails, try to use as direct LRC text
-		lrcText = rawLyrics
+		if fallback, fallbackErr := formatPaxLyricsToLRC(rawLyrics, multiPersonWordByWord); fallbackErr == nil {
+			lrcText = fallback
+		} else {
+			lrcText = rawLyrics
+		}
 	}
 
 	lines := parseSyncedLyrics(lrcText)

go_backend/qobuz.go

@@ -49,9 +49,10 @@ const (
 	qobuzArtistGetBaseURL   = "https://www.qobuz.com/api.json/0.2/artist/get?artist_id="
 	qobuzPlaylistGetBaseURL = "https://www.qobuz.com/api.json/0.2/playlist/get?playlist_id="
 	qobuzStoreSearchBaseURL = "https://www.qobuz.com/us-en/search/tracks/"
+	qobuzTrackOpenBaseURL   = "https://open.qobuz.com/track/"
 	qobuzTrackPlayBaseURL   = "https://play.qobuz.com/track/"
 	qobuzStoreBaseURL       = "https://www.qobuz.com/us-en"
-	qobuzDownloadAPIURL     = "https://www.musicdl.me/api/qobuz/download"
+	qobuzDownloadAPIURL     = "https://dl.musicdl.me/qobuz/download"
 	qobuzDabMusicAPIURL     = "https://dabmusic.xyz/api/stream?trackId="
 	qobuzDeebAPIURL         = "https://dab.yeet.su/api/stream?trackId="
 	qobuzAfkarAPIURL        = "https://qbz.afkarxyz.qzz.io/api/track/"
@@ -1631,19 +1632,23 @@ func fetchQobuzURLWithRetry(provider qobuzAPIProvider, trackID int64, quality st
 	return fetchQobuzURLSingleAttempt(provider, trackID, quality, timeout, "")
 }
 
+func buildQobuzMusicDLPayload(trackID int64, quality string) ([]byte, error) {
+	requestQuality := mapQobuzQualityCodeToAPI(quality)
+	payload := map[string]any{
+		"quality":      requestQuality,
+		"upload_to_r2": false,
+		"url":          fmt.Sprintf("%s%d", qobuzTrackOpenBaseURL, trackID),
+	}
+	return json.Marshal(payload)
+}
+
 func fetchQobuzURLSingleAttempt(provider qobuzAPIProvider, trackID int64, quality string, timeout time.Duration, country string) (qobuzDownloadInfo, error) {
 	var lastErr error
 	retryDelay := qobuzRetryDelay
 	var payloadBytes []byte
 	if provider.Kind == qobuzAPIKindMusicDL {
-		requestQuality := mapQobuzQualityCodeToAPI(quality)
-		payload := map[string]any{
-			"quality":      requestQuality,
-			"upload_to_r2": false,
-			"url":          fmt.Sprintf("%s%d", qobuzTrackPlayBaseURL, trackID),
-		}
 		var err error
-		payloadBytes, err = json.Marshal(payload)
+		payloadBytes, err = buildQobuzMusicDLPayload(trackID, quality)
 		if err != nil {
 			return qobuzDownloadInfo{}, fmt.Errorf("failed to encode qobuz request: %w", err)
 		}
@@ -1688,7 +1693,6 @@ func fetchQobuzURLSingleAttempt(provider qobuzAPIProvider, trackID int64, qualit
 		}
 		if provider.Kind == qobuzAPIKindMusicDL {
 			req.Header.Set("Content-Type", "application/json")
-			req.Header.Set("X-Debug-Key", getQobuzDebugKey())
 		}
 
 		resp, err := DoRequestWithUserAgent(client, req)

go_backend/qobuz_test.go

@@ -1,6 +1,9 @@
 package gobackend
 
-import "testing"
+import (
+	"encoding/json"
+	"testing"
+)
 
 func TestParseQobuzURL(t *testing.T) {
 	tests := []struct {
@@ -195,6 +198,28 @@ func TestGetQobuzDebugKey(t *testing.T) {
 	}
 }
 
+func TestBuildQobuzMusicDLPayloadUsesOpenTrackURL(t *testing.T) {
+	payloadBytes, err := buildQobuzMusicDLPayload(374610875, "7")
+	if err != nil {
+		t.Fatalf("buildQobuzMusicDLPayload returned error: %v", err)
+	}
+
+	var payload map[string]any
+	if err := json.Unmarshal(payloadBytes, &payload); err != nil {
+		t.Fatalf("payload is not valid JSON: %v", err)
+	}
+
+	if got := payload["url"]; got != "https://open.qobuz.com/track/374610875" {
+		t.Fatalf("payload url = %v, want open.qobuz.com track URL", got)
+	}
+	if got := payload["quality"]; got != "hi-res" {
+		t.Fatalf("payload quality = %v, want hi-res", got)
+	}
+	if got := payload["upload_to_r2"]; got != false {
+		t.Fatalf("payload upload_to_r2 = %v, want false", got)
+	}
+}
+
 func TestExtractQobuzAlbumIDsFromArtistHTML(t *testing.T) {
 	body := []byte(`
 		<button data-itemtype="album" data-itemId="0886446451985"></button>

go_backend/songlink.go

@@ -1,6 +1,7 @@
 package gobackend
 
 import (
+	"bytes"
 	"context"
 	"encoding/json"
 	"fmt"
@@ -14,6 +15,10 @@ type SongLinkClient struct {
 	client *http.Client
 }
 
+type songLinkPlatformLink struct {
+	URL string `json:"url"`
+}
+
 type TrackAvailability struct {
 	SpotifyID  string `json:"spotify_id"`
 	Tidal      bool   `json:"tidal"`
@@ -43,6 +48,7 @@ var (
 	songLinkCheckAvailabilityFromDeezer = func(s *SongLinkClient, deezerTrackID string) (*TrackAvailability, error) {
 		return s.CheckAvailabilityFromDeezer(deezerTrackID)
 	}
+	songLinkRetryConfig = DefaultRetryConfig
 )
 
 func NewSongLinkClient() *SongLinkClient {
@@ -130,7 +136,14 @@ func (s *SongLinkClient) CheckTrackAvailability(spotifyTrackID string, isrc stri
 }
 
 func (s *SongLinkClient) checkTrackAvailabilityFromSpotify(spotifyTrackID string) (*TrackAvailability, error) {
-	songLinkRateLimiter.WaitForSlot()
+	availability, pageErr := s.checkTrackAvailabilityFromSpotifyPage(spotifyTrackID)
+	if pageErr == nil {
+		return availability, nil
+	}
+
+	if !songLinkRateLimiter.TryAcquire() {
+		return nil, fmt.Errorf("song.link page lookup failed: %w (SongLink local rate limit exceeded)", pageErr)
+	}
 
 	spotifyURL := fmt.Sprintf("https://open.spotify.com/track/%s", spotifyTrackID)
 	apiURL := buildSongLinkURLFromTarget(spotifyURL, "")
@@ -140,10 +153,10 @@ func (s *SongLinkClient) checkTrackAvailabilityFromSpotify(spotifyTrackID string
 		return nil, fmt.Errorf("failed to create request: %w", err)
 	}
 
-	retryConfig := DefaultRetryConfig()
+	retryConfig := songLinkRetryConfig()
 	resp, err := DoRequestWithRetry(s.client, req, retryConfig)
 	if err != nil {
-		return nil, fmt.Errorf("failed to check availability: %w", err)
+		return nil, fmt.Errorf("song.link page lookup failed: %w; SongLink API lookup failed: %w", pageErr, err)
 	}
 	defer resp.Body.Close()
 
@@ -154,10 +167,10 @@ func (s *SongLinkClient) checkTrackAvailabilityFromSpotify(spotifyTrackID string
 		return nil, fmt.Errorf("track not found on any streaming platform")
 	}
 	if resp.StatusCode == 429 {
-		return nil, fmt.Errorf("SongLink rate limit exceeded")
+		return nil, fmt.Errorf("song.link page lookup failed: %w; SongLink API rate limit exceeded", pageErr)
 	}
 	if resp.StatusCode != 200 {
-		return nil, fmt.Errorf("SongLink API returned status %d", resp.StatusCode)
+		return nil, fmt.Errorf("song.link page lookup failed: %w; SongLink API returned status %d", pageErr, resp.StatusCode)
 	}
 
 	body, err := ReadResponseBody(resp)
@@ -166,59 +179,102 @@ func (s *SongLinkClient) checkTrackAvailabilityFromSpotify(spotifyTrackID string
 	}
 
 	var songLinkResp struct {
-		LinksByPlatform map[string]struct {
-			URL string `json:"url"`
-		} `json:"linksByPlatform"`
+		LinksByPlatform map[string]songLinkPlatformLink `json:"linksByPlatform"`
 	}
 
 	if err := json.Unmarshal(body, &songLinkResp); err != nil {
 		return nil, fmt.Errorf("failed to decode response: %w", err)
 	}
 
-	availability := &TrackAvailability{
-		SpotifyID: spotifyTrackID,
+	LogWarn("SongLink", "Spotify %s resolved via SongLink API after song.link page failure: %v", spotifyTrackID, pageErr)
+	return buildTrackAvailabilityFromSongLinkLinks(spotifyTrackID, songLinkResp.LinksByPlatform), nil
+}
+
+func (s *SongLinkClient) checkTrackAvailabilityFromSpotifyPage(spotifyTrackID string) (*TrackAvailability, error) {
+	pageURL := fmt.Sprintf("https://song.link/s/%s", spotifyTrackID)
+	req, err := http.NewRequest("GET", pageURL, nil)
+	if err != nil {
+		return nil, fmt.Errorf("failed to create song.link page request: %w", err)
 	}
 
-	if tidalLink, ok := songLinkResp.LinksByPlatform["tidal"]; ok && tidalLink.URL != "" {
-		availability.Tidal = true
-		availability.TidalURL = tidalLink.URL
-		availability.TidalID = extractTidalIDFromURL(tidalLink.URL)
+	req.Header.Set("Accept", "text/html,application/xhtml+xml")
+	req.Header.Set("User-Agent", getRandomUserAgent())
+
+	resp, err := s.client.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("failed to fetch song.link page: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode == 404 {
+		return nil, fmt.Errorf("track not found on song.link page")
+	}
+	if resp.StatusCode != 200 {
+		return nil, fmt.Errorf("song.link page returned status %d", resp.StatusCode)
 	}
 
-	if amazonLink, ok := songLinkResp.LinksByPlatform["amazonMusic"]; ok && amazonLink.URL != "" {
-		availability.Amazon = true
-		availability.AmazonURL = amazonLink.URL
+	body, err := ReadResponseBody(resp)
+	if err != nil {
+		return nil, fmt.Errorf("failed to read song.link page: %w", err)
 	}
 
-	if deezerLink, ok := songLinkResp.LinksByPlatform["deezer"]; ok && deezerLink.URL != "" {
-		availability.Deezer = true
-		availability.DeezerURL = deezerLink.URL
-		availability.DeezerID = extractDeezerIDFromURL(deezerLink.URL)
+	nextDataJSON, err := extractSongLinkNextDataJSON(body)
+	if err != nil {
+		return nil, err
 	}
 
-	if qobuzLink, ok := songLinkResp.LinksByPlatform["qobuz"]; ok && qobuzLink.URL != "" {
-		availability.Qobuz = true
-		availability.QobuzURL = qobuzLink.URL
-		availability.QobuzID = extractQobuzIDFromURL(qobuzLink.URL)
+	var pageData struct {
+		Props struct {
+			PageProps struct {
+				PageData struct {
+					Sections []struct {
+						Links []struct {
+							Platform string `json:"platform"`
+							URL      string `json:"url"`
+							Show     bool   `json:"show"`
+						} `json:"links"`
+					} `json:"sections"`
+				} `json:"pageData"`
+			} `json:"pageProps"`
+		} `json:"props"`
+	}
+	if err := json.Unmarshal(nextDataJSON, &pageData); err != nil {
+		return nil, fmt.Errorf("failed to decode song.link page data: %w", err)
 	}
 
-	// Prefer youtubeMusic URLs — they bypass Cobalt login requirements
-	if ytMusicLink, ok := songLinkResp.LinksByPlatform["youtubeMusic"]; ok && ytMusicLink.URL != "" {
-		availability.YouTube = true
-		availability.YouTubeURL = ytMusicLink.URL
-		availability.YouTubeID = extractYouTubeIDFromURL(ytMusicLink.URL)
-	}
-
-	// Fallback to regular youtube if youtubeMusic not available
-	if !availability.YouTube {
-		if youtubeLink, ok := songLinkResp.LinksByPlatform["youtube"]; ok && youtubeLink.URL != "" {
-			availability.YouTube = true
-			availability.YouTubeURL = youtubeLink.URL
-			availability.YouTubeID = extractYouTubeIDFromURL(youtubeLink.URL)
+	linksByPlatform := make(map[string]songLinkPlatformLink)
+	for _, section := range pageData.Props.PageProps.PageData.Sections {
+		for _, link := range section.Links {
+			if !link.Show || strings.TrimSpace(link.URL) == "" {
+				continue
+			}
+			linksByPlatform[link.Platform] = songLinkPlatformLink{URL: link.URL}
 		}
 	}
 
-	return availability, nil
+	if len(linksByPlatform) == 0 {
+		return nil, fmt.Errorf("song.link page contained no usable platform links")
+	}
+
+	return buildTrackAvailabilityFromSongLinkLinks(spotifyTrackID, linksByPlatform), nil
+}
+
+func extractSongLinkNextDataJSON(body []byte) ([]byte, error) {
+	const startMarker = `<script id="__NEXT_DATA__" type="application/json">`
+	const endMarker = `</script>`
+
+	start := bytes.Index(body, []byte(startMarker))
+	if start < 0 {
+		return nil, fmt.Errorf("song.link page missing __NEXT_DATA__")
+	}
+	start += len(startMarker)
+
+	end := bytes.Index(body[start:], []byte(endMarker))
+	if end < 0 {
+		return nil, fmt.Errorf("song.link page has unterminated __NEXT_DATA__")
+	}
+
+	return body[start : start+end], nil
 }
 
 func (s *SongLinkClient) checkTrackAvailabilityFromISRC(isrc string) (*TrackAvailability, error) {
@@ -459,7 +515,7 @@ func (s *SongLinkClient) CheckAlbumAvailability(spotifyAlbumID string) (*AlbumAv
 		return nil, fmt.Errorf("failed to create request: %w", err)
 	}
 
-	retryConfig := DefaultRetryConfig()
+	retryConfig := songLinkRetryConfig()
 	resp, err := DoRequestWithRetry(s.client, req, retryConfig)
 	if err != nil {
 		return nil, fmt.Errorf("failed to check album availability: %w", err)
@@ -542,7 +598,7 @@ func (s *SongLinkClient) checkAvailabilityFromDeezerSongLink(deezerTrackID strin
 		return nil, fmt.Errorf("failed to create request: %w", err)
 	}
 
-	retryConfig := DefaultRetryConfig()
+	retryConfig := songLinkRetryConfig()
 	resp, err := DoRequestWithRetry(s.client, req, retryConfig)
 	if err != nil {
 		return nil, fmt.Errorf("failed to check availability: %w", err)
@@ -647,7 +703,7 @@ func (s *SongLinkClient) CheckAvailabilityByPlatform(platform, entityType, entit
 		return nil, fmt.Errorf("failed to create request: %w", err)
 	}
 
-	retryConfig := DefaultRetryConfig()
+	retryConfig := songLinkRetryConfig()
 	resp, err := DoRequestWithRetry(s.client, req, retryConfig)
 	if err != nil {
 		return nil, fmt.Errorf("failed to check availability: %w", err)
@@ -728,6 +784,51 @@ func (s *SongLinkClient) CheckAvailabilityByPlatform(platform, entityType, entit
 	return availability, nil
 }
 
+func buildTrackAvailabilityFromSongLinkLinks(spotifyTrackID string, links map[string]songLinkPlatformLink) *TrackAvailability {
+	availability := &TrackAvailability{
+		SpotifyID: spotifyTrackID,
+	}
+
+	if availability.SpotifyID == "" {
+		if spotifyLink, ok := links["spotify"]; ok && spotifyLink.URL != "" {
+			availability.SpotifyID = extractSpotifyIDFromURL(spotifyLink.URL)
+		}
+	}
+	if tidalLink, ok := links["tidal"]; ok && tidalLink.URL != "" {
+		availability.Tidal = true
+		availability.TidalURL = tidalLink.URL
+		availability.TidalID = extractTidalIDFromURL(tidalLink.URL)
+	}
+	if amazonLink, ok := links["amazonMusic"]; ok && amazonLink.URL != "" {
+		availability.Amazon = true
+		availability.AmazonURL = amazonLink.URL
+	}
+	if qobuzLink, ok := links["qobuz"]; ok && qobuzLink.URL != "" {
+		availability.Qobuz = true
+		availability.QobuzURL = qobuzLink.URL
+		availability.QobuzID = extractQobuzIDFromURL(qobuzLink.URL)
+	}
+	if deezerLink, ok := links["deezer"]; ok && deezerLink.URL != "" {
+		availability.Deezer = true
+		availability.DeezerURL = deezerLink.URL
+		availability.DeezerID = extractDeezerIDFromURL(deezerLink.URL)
+	}
+	if ytMusicLink, ok := links["youtubeMusic"]; ok && ytMusicLink.URL != "" {
+		availability.YouTube = true
+		availability.YouTubeURL = ytMusicLink.URL
+		availability.YouTubeID = extractYouTubeIDFromURL(ytMusicLink.URL)
+	}
+	if !availability.YouTube {
+		if youtubeLink, ok := links["youtube"]; ok && youtubeLink.URL != "" {
+			availability.YouTube = true
+			availability.YouTubeURL = youtubeLink.URL
+			availability.YouTubeID = extractYouTubeIDFromURL(youtubeLink.URL)
+		}
+	}
+
+	return availability
+}
+
 func extractSpotifyIDFromURL(spotifyURL string) string {
 	parts := strings.Split(spotifyURL, "/track/")
 	if len(parts) > 1 {
@@ -802,7 +903,7 @@ func (s *SongLinkClient) CheckAvailabilityFromURL(inputURL string) (*TrackAvaila
 		return nil, fmt.Errorf("failed to create request: %w", err)
 	}
 
-	retryConfig := DefaultRetryConfig()
+	retryConfig := songLinkRetryConfig()
 	resp, err := DoRequestWithRetry(s.client, req, retryConfig)
 	if err != nil {
 		return nil, fmt.Errorf("failed to check availability: %w", err)

go_backend/songlink_test.go

@@ -0,0 +1,127 @@
+package gobackend
+
+import (
+	"io"
+	"net/http"
+	"strings"
+	"testing"
+)
+
+type roundTripFunc func(*http.Request) (*http.Response, error)
+
+func (fn roundTripFunc) RoundTrip(req *http.Request) (*http.Response, error) {
+	return fn(req)
+}
+
+func TestGetRetryAfterDurationMissingHeaderReturnsZero(t *testing.T) {
+	resp := &http.Response{
+		Header: make(http.Header),
+	}
+
+	if got := getRetryAfterDuration(resp); got != 0 {
+		t.Fatalf("getRetryAfterDuration() = %v, want 0", got)
+	}
+}
+
+func TestCheckTrackAvailabilityFromSpotifyPrefersSongLinkPage(t *testing.T) {
+	client := &SongLinkClient{
+		client: &http.Client{
+			Transport: roundTripFunc(func(req *http.Request) (*http.Response, error) {
+				switch {
+				case req.URL.Host == "api.song.link":
+					t.Fatalf("api.song.link should not be called when song.link page succeeds")
+					return nil, nil
+				case req.URL.Host == "song.link" && req.URL.Path == "/s/testspotifyid":
+					body := `<!DOCTYPE html><html><body><script id="__NEXT_DATA__" type="application/json">{"props":{"pageProps":{"pageData":{"sections":[{"displayName":"Listen","links":[{"platform":"spotify","url":"https://open.spotify.com/track/testspotifyid","show":true},{"platform":"deezer","url":"https://www.deezer.com/track/908604612","show":true},{"platform":"amazonMusic","url":"https://music.amazon.com/albums/B086Q2QNLH?trackAsin=B086Q41M9C","show":true},{"platform":"tidal","url":"https://listen.tidal.com/track/134858527","show":true},{"platform":"qobuz","url":"https://open.qobuz.com/track/195125822","show":true},{"platform":"youtubeMusic","url":"https://music.youtube.com/watch?v=testvideoid1","show":true}]}]}}}}</script></body></html>`
+					return &http.Response{
+						StatusCode: 200,
+						Header:     make(http.Header),
+						Body:       io.NopCloser(strings.NewReader(body)),
+						Request:    req,
+					}, nil
+				default:
+					t.Fatalf("unexpected request: %s", req.URL.String())
+					return nil, nil
+				}
+			}),
+		},
+	}
+
+	availability, err := client.CheckTrackAvailability("testspotifyid", "")
+	if err != nil {
+		t.Fatalf("CheckTrackAvailability() error = %v", err)
+	}
+
+	if availability.SpotifyID != "testspotifyid" {
+		t.Fatalf("SpotifyID = %q, want %q", availability.SpotifyID, "testspotifyid")
+	}
+	if !availability.Deezer || availability.DeezerID != "908604612" {
+		t.Fatalf("Deezer availability = %+v, want DeezerID 908604612", availability)
+	}
+	if !availability.Amazon || !availability.Tidal || !availability.Qobuz || !availability.YouTube {
+		t.Fatalf("availability flags = %+v, want Amazon/Tidal/Qobuz/YouTube true", availability)
+	}
+	if availability.YouTubeID != "testvideoid1" {
+		t.Fatalf("YouTubeID = %q, want %q", availability.YouTubeID, "testvideoid1")
+	}
+}
+
+func TestCheckTrackAvailabilityFromSpotifyFallsBackToAPIWhenPageFails(t *testing.T) {
+	origRetryConfig := songLinkRetryConfig
+	songLinkRetryConfig = func() RetryConfig {
+		return RetryConfig{
+			MaxRetries:    0,
+			InitialDelay:  0,
+			MaxDelay:      0,
+			BackoffFactor: 1,
+		}
+	}
+	defer func() {
+		songLinkRetryConfig = origRetryConfig
+	}()
+
+	client := &SongLinkClient{
+		client: &http.Client{
+			Transport: roundTripFunc(func(req *http.Request) (*http.Response, error) {
+				switch {
+				case req.URL.Host == "song.link" && req.URL.Path == "/s/testspotifyid":
+					return &http.Response{
+						StatusCode: 500,
+						Header:     make(http.Header),
+						Body:       io.NopCloser(strings.NewReader("page failure")),
+						Request:    req,
+					}, nil
+				case req.URL.Host == "api.song.link":
+					body := `{"linksByPlatform":{"spotify":{"url":"https://open.spotify.com/track/testspotifyid"},"deezer":{"url":"https://www.deezer.com/track/908604612"},"amazonMusic":{"url":"https://music.amazon.com/albums/B086Q2QNLH?trackAsin=B086Q41M9C"},"tidal":{"url":"https://listen.tidal.com/track/134858527"},"qobuz":{"url":"https://open.qobuz.com/track/195125822"},"youtubeMusic":{"url":"https://music.youtube.com/watch?v=testvideoid1"}}}`
+					return &http.Response{
+						StatusCode: 200,
+						Header:     make(http.Header),
+						Body:       io.NopCloser(strings.NewReader(body)),
+						Request:    req,
+					}, nil
+				default:
+					t.Fatalf("unexpected request: %s", req.URL.String())
+					return nil, nil
+				}
+			}),
+		},
+	}
+
+	availability, err := client.CheckTrackAvailability("testspotifyid", "")
+	if err != nil {
+		t.Fatalf("CheckTrackAvailability() error = %v", err)
+	}
+
+	if availability.SpotifyID != "testspotifyid" {
+		t.Fatalf("SpotifyID = %q, want %q", availability.SpotifyID, "testspotifyid")
+	}
+	if !availability.Deezer || availability.DeezerID != "908604612" {
+		t.Fatalf("Deezer availability = %+v, want DeezerID 908604612", availability)
+	}
+	if !availability.Amazon || !availability.Tidal || !availability.Qobuz || !availability.YouTube {
+		t.Fatalf("availability flags = %+v, want Amazon/Tidal/Qobuz/YouTube true", availability)
+	}
+	if availability.YouTubeID != "testvideoid1" {
+		t.Fatalf("YouTubeID = %q, want %q", availability.YouTubeID, "testvideoid1")
+	}
+}

go_backend/tidal.go

@@ -26,8 +26,14 @@ type TidalDownloader struct {
 }
 
 var (
-	globalTidalDownloader *TidalDownloader
-	tidalDownloaderOnce   sync.Once
+	globalTidalDownloader       *TidalDownloader
+	tidalDownloaderOnce         sync.Once
+	tidalGetTrackSearchPageFunc = func(t *TidalDownloader, query string, limit int) (*tidalPublicTrackSearchResponse, error) {
+		return t.getTrackSearchPage(query, limit)
+	}
+	tidalGetPublicTrackFunc = func(t *TidalDownloader, resourceID string) (*TidalTrack, error) {
+		return t.getPublicTrack(resourceID)
+	}
 )
 
 const (
@@ -758,15 +764,101 @@ func (t *TidalDownloader) GetTrackInfoByID(trackID int64) (*TidalTrack, error) {
 }
 
 func (t *TidalDownloader) SearchTrackByISRC(isrc string) (*TidalTrack, error) {
-	return nil, fmt.Errorf("tidal ISRC search API disabled: no client credentials mode")
+	normalizedISRC := strings.ToUpper(strings.TrimSpace(isrc))
+	if normalizedISRC == "" {
+		return nil, fmt.Errorf("empty tidal ISRC")
+	}
+
+	page, err := tidalGetTrackSearchPageFunc(t, normalizedISRC, 20)
+	if err != nil {
+		return nil, err
+	}
+
+	for i := range page.Items {
+		if strings.EqualFold(strings.TrimSpace(page.Items[i].ISRC), normalizedISRC) {
+			return &page.Items[i], nil
+		}
+	}
+
+	return nil, fmt.Errorf("no exact tidal ISRC match found for %s", normalizedISRC)
 }
 
 func (t *TidalDownloader) SearchTrackByMetadataWithISRC(trackName, artistName, albumName, spotifyISRC string, expectedDuration int) (*TidalTrack, error) {
-	return nil, fmt.Errorf("tidal metadata search API disabled: no client credentials mode")
+	queryParts := make([]string, 0, 3)
+	if trimmed := strings.TrimSpace(trackName); trimmed != "" {
+		queryParts = append(queryParts, trimmed)
+	}
+	if trimmed := strings.TrimSpace(artistName); trimmed != "" {
+		queryParts = append(queryParts, trimmed)
+	}
+	if len(queryParts) == 0 {
+		return nil, fmt.Errorf("tidal metadata search requires track or artist name")
+	}
+
+	queries := []string{strings.Join(queryParts, " ")}
+	if trimmedAlbum := strings.TrimSpace(albumName); trimmedAlbum != "" {
+		queries = append(queries, strings.Join(append(queryParts, trimmedAlbum), " "))
+	}
+
+	req := DownloadRequest{
+		TrackName:  strings.TrimSpace(trackName),
+		ArtistName: strings.TrimSpace(artistName),
+		AlbumName:  strings.TrimSpace(albumName),
+		ISRC:       strings.ToUpper(strings.TrimSpace(spotifyISRC)),
+		DurationMS: expectedDuration * 1000,
+	}
+
+	seenQueries := make(map[string]struct{}, len(queries))
+	for _, query := range queries {
+		if _, seen := seenQueries[query]; seen {
+			continue
+		}
+		seenQueries[query] = struct{}{}
+
+		page, err := tidalGetTrackSearchPageFunc(t, query, 20)
+		if err != nil {
+			return nil, err
+		}
+
+		var candidates []*TidalTrack
+		for i := range page.Items {
+			track := &page.Items[i]
+			if req.ISRC != "" && !strings.EqualFold(strings.TrimSpace(track.ISRC), req.ISRC) {
+				continue
+			}
+			resolved := resolvedTrackInfo{
+				Title:      strings.TrimSpace(track.Title),
+				ArtistName: tidalTrackArtistsDisplay(track),
+				Duration:   track.Duration,
+			}
+			if trackMatchesRequest(req, resolved, "Tidal search") {
+				candidates = append(candidates, track)
+			}
+		}
+
+		if len(candidates) == 0 {
+			continue
+		}
+
+		if req.AlbumName != "" {
+			for _, candidate := range candidates {
+				if titlesMatch(req.AlbumName, candidate.Album.Title) {
+					return candidate, nil
+				}
+			}
+		}
+
+		return candidates[0], nil
+	}
+
+	if req.ISRC != "" {
+		return nil, fmt.Errorf("no tidal metadata match found for exact ISRC %s", req.ISRC)
+	}
+	return nil, fmt.Errorf("no tidal metadata match found")
 }
 
 func (t *TidalDownloader) SearchTrackByMetadata(trackName, artistName string) (*TidalTrack, error) {
-	return nil, fmt.Errorf("tidal metadata search API disabled: no client credentials mode")
+	return t.SearchTrackByMetadataWithISRC(trackName, artistName, "", "", 0)
 }
 
 func (t *TidalDownloader) SearchTracks(query string, limit int) ([]ExtTrackMetadata, error) {
@@ -1847,6 +1939,36 @@ func resolveTidalTrackForRequest(req DownloadRequest, downloader *TidalDownloade
 		}
 	}
 
+	if !gotTidalID && req.ISRC != "" {
+		GoLog("[%s] Trying direct Tidal ISRC search: %s\n", logPrefix, req.ISRC)
+		directTrack, directErr := downloader.SearchTrackByISRC(req.ISRC)
+		if directErr == nil && directTrack != nil && directTrack.ID > 0 {
+			trackID = directTrack.ID
+			gotTidalID = true
+			GoLog("[%s] Got Tidal ID %d from direct ISRC search\n", logPrefix, trackID)
+		} else if directErr != nil {
+			GoLog("[%s] Direct Tidal ISRC search failed: %v\n", logPrefix, directErr)
+		}
+	}
+
+	if !gotTidalID && req.ISRC != "" && req.TrackName != "" && req.ArtistName != "" {
+		GoLog("[%s] Trying Tidal public metadata search with ISRC\n", logPrefix)
+		searchTrack, searchErr := downloader.SearchTrackByMetadataWithISRC(
+			req.TrackName,
+			req.ArtistName,
+			req.AlbumName,
+			req.ISRC,
+			expectedDurationSec,
+		)
+		if searchErr == nil && searchTrack != nil && searchTrack.ID > 0 {
+			trackID = searchTrack.ID
+			gotTidalID = true
+			GoLog("[%s] Got Tidal ID %d from public metadata search\n", logPrefix, trackID)
+		} else if searchErr != nil {
+			GoLog("[%s] Tidal public metadata search failed: %v\n", logPrefix, searchErr)
+		}
+	}
+
 	if !gotTidalID && (req.SpotifyID != "" || req.DeezerID != "") {
 		GoLog("[%s] Trying SongLink for Tidal ID...\n", logPrefix)
 
@@ -1912,7 +2034,7 @@ func resolveTidalTrackForRequest(req DownloadRequest, downloader *TidalDownloade
 	}
 
 	// Verify the resolved track matches the request.
-	actualTrack, fetchErr := downloader.getPublicTrack(strconv.FormatInt(trackID, 10))
+	actualTrack, fetchErr := tidalGetPublicTrackFunc(downloader, strconv.FormatInt(trackID, 10))
 	if fetchErr != nil {
 		GoLog("[%s] Warning: could not fetch Tidal track %d for verification: %v\n", logPrefix, trackID, fetchErr)
 		// Continue without verification — better than failing entirely.

lib/constants/app_info.dart

@@ -3,8 +3,8 @@ import 'package:flutter/foundation.dart';
 /// App version and info constants
 /// Update version here only - all other files will reference this
 class AppInfo {
-  static const String version = '3.8.6';
-  static const String buildNumber = '112';
+  static const String version = '3.8.8';
+  static const String buildNumber = '114';
   static const String fullVersion = '$version+$buildNumber';
 
   /// Shows "Internal" in debug builds, actual version in release.

lib/main.dart

@@ -14,6 +14,7 @@ import 'package:spotiflac_android/providers/settings_provider.dart';
 import 'package:spotiflac_android/services/notification_service.dart';
 import 'package:spotiflac_android/services/share_intent_service.dart';
 import 'package:spotiflac_android/services/cover_cache_manager.dart';
+import 'package:spotiflac_android/utils/local_library_scan_prefs.dart';
 
 void main() async {
   WidgetsFlutterBinding.ensureInitialized();
@@ -100,8 +101,6 @@ class _EagerInitializationState extends ConsumerState<_EagerInitialization>
   bool _localLibraryWarmupScheduled = false;
   bool _autoScanTriggeredOnLaunch = false;
 
-  static const _lastScannedAtKey = 'local_library_last_scanned_at';
-
   @override
   void initState() {
     super.initState();
@@ -200,10 +199,9 @@ class _EagerInitializationState extends ConsumerState<_EagerInitialization>
     // Determine cooldown based on auto-scan mode.
     final now = DateTime.now();
     final prefs = await SharedPreferences.getInstance();
-    final lastScannedMs = prefs.getInt(_lastScannedAtKey);
+    final lastScanned = readLocalLibraryLastScannedAt(prefs);
 
-    if (lastScannedMs != null) {
-      final lastScanned = DateTime.fromMillisecondsSinceEpoch(lastScannedMs);
+    if (lastScanned != null) {
       final elapsed = now.difference(lastScanned);
 
       switch (settings.localLibraryAutoScan) {

lib/providers/download_queue_provider.dart

@@ -1005,6 +1005,7 @@ class DownloadQueueNotifier extends Notifier<DownloadQueueState> {
   int _lastNotifPercent = -1;
   int _lastNotifQueueCount = -1;
   final Set<String> _locallyCancelledItemIds = {};
+  final Set<String> _pausePendingItemIds = {};
 
   double _normalizeProgressForUi(double value) {
     final clamped = value.clamp(0.0, 1.0).toDouble();
@@ -1324,6 +1325,10 @@ class DownloadQueueNotifier extends Notifier<DownloadQueueState> {
       if (localItem == null) {
         continue;
       }
+      if (_isPausePending(itemId)) {
+        PlatformBridge.clearItemProgress(itemId).catchError((_) {});
+        continue;
+      }
       if (localItem.status == DownloadStatus.skipped) {
         PlatformBridge.clearItemProgress(itemId).catchError((_) {});
         continue;
@@ -2123,12 +2128,42 @@ class DownloadQueueNotifier extends Notifier<DownloadQueueState> {
     return resolved?.status == DownloadStatus.skipped;
   }
 
+  bool _isPausePending(String id) => _pausePendingItemIds.contains(id);
+
+  void _requeueItemForPause(String id) {
+    final updatedItems = state.items
+        .map((item) {
+          if (item.id != id) return item;
+          if (item.status == DownloadStatus.completed ||
+              item.status == DownloadStatus.failed ||
+              item.status == DownloadStatus.skipped) {
+            return item;
+          }
+          return item.copyWith(
+            status: DownloadStatus.queued,
+            progress: 0,
+            speedMBps: 0,
+            bytesReceived: 0,
+          );
+        })
+        .toList(growable: false);
+
+    final currentDownload = state.currentDownload?.id == id
+        ? null
+        : state.currentDownload;
+    state = state.copyWith(
+      items: updatedItems,
+      currentDownload: currentDownload,
+    );
+  }
+
   void _requestNativeCancel(String id) {
     PlatformBridge.cancelDownload(id).catchError((_) {});
     PlatformBridge.clearItemProgress(id).catchError((_) {});
   }
 
   void cancelItem(String id) {
+    _pausePendingItemIds.remove(id);
     _locallyCancelledItemIds.add(id);
     updateItemStatus(id, DownloadStatus.skipped);
     _requestNativeCancel(id);
@@ -2161,6 +2196,7 @@ class DownloadQueueNotifier extends Notifier<DownloadQueueState> {
         .toList(growable: false);
 
     if (activeIds.isNotEmpty) {
+      _pausePendingItemIds.addAll(activeIds);
       _locallyCancelledItemIds.addAll(activeIds);
       for (final id in activeIds) {
         _requestNativeCancel(id);
@@ -2173,11 +2209,29 @@ class DownloadQueueNotifier extends Notifier<DownloadQueueState> {
     if (!wasProcessing) {
       _locallyCancelledItemIds.clear();
     }
+    _pausePendingItemIds.clear();
   }
 
   void pauseQueue() {
     if (state.isProcessing && !state.isPaused) {
-      state = state.copyWith(isPaused: true);
+      final activeIds = state.items
+          .where(
+            (item) =>
+                item.status == DownloadStatus.downloading ||
+                item.status == DownloadStatus.finalizing,
+          )
+          .map((item) => item.id)
+          .toSet();
+
+      if (activeIds.isNotEmpty) {
+        _pausePendingItemIds.addAll(activeIds);
+        for (final id in activeIds) {
+          _requestNativeCancel(id);
+          _requeueItemForPause(id);
+        }
+      }
+
+      state = state.copyWith(isPaused: true, currentDownload: null);
       _notificationService.cancelDownloadNotification();
       _log.i('Queue paused');
     }
@@ -2379,7 +2433,11 @@ class DownloadQueueNotifier extends Notifier<DownloadQueueState> {
     }
   }
 
+  /// Deezer CDN cover size pattern: /WxH-0-0-0-0.jpg
+  static final _deezerSizeRegex = RegExp(r'/(\d+)x(\d+)-\d+-\d+-\d+-\d+\.jpg$');
+
   String _upgradeToMaxQualityCover(String coverUrl) {
+    // Spotify CDN upgrade (hash-based size identifiers)
     const spotifySize300 = 'ab67616d00001e02';
     const spotifySize640 = 'ab67616d0000b273';
     const spotifySizeMax = 'ab67616d000082c1';
@@ -2388,11 +2446,29 @@ class DownloadQueueNotifier extends Notifier<DownloadQueueState> {
     if (result.contains(spotifySize300)) {
       result = result.replaceFirst(spotifySize300, spotifySize640);
     }
-
     if (result.contains(spotifySize640)) {
       result = result.replaceFirst(spotifySize640, spotifySizeMax);
     }
 
+    // Deezer CDN upgrade (1000x1000 → 1800x1800)
+    if (result.contains('cdn-images.dzcdn.net')) {
+      final upgraded = result.replaceFirst(
+        _deezerSizeRegex,
+        '/1800x1800-000000-80-0-0.jpg',
+      );
+      if (upgraded != result) {
+        _log.d('Cover URL upgraded (Deezer): 1800x1800');
+        result = upgraded;
+      }
+    }
+
+    // Tidal CDN upgrade (1280x1280 → origin)
+    if (result.contains('resources.tidal.com') &&
+        result.contains('/1280x1280.jpg')) {
+      result = result.replaceFirst('/1280x1280.jpg', '/origin.jpg');
+      _log.d('Cover URL upgraded (Tidal): origin');
+    }
+
     return result;
   }
 
@@ -3172,6 +3248,7 @@ class DownloadQueueNotifier extends Notifier<DownloadQueueState> {
     }
     _log.d('Concurrent downloads: ${state.concurrentDownloads}');
     await _processQueueParallel();
+    final stoppedWhilePaused = state.isPaused;
 
     _stopProgressPolling();
 
@@ -3197,7 +3274,7 @@ class DownloadQueueNotifier extends Notifier<DownloadQueueState> {
     _log.i(
       'Queue stats - completed: $_completedInSession, failed: $_failedInSession, totalAtStart: $_totalQueuedAtStart',
     );
-    if (_totalQueuedAtStart > 0) {
+    if (!stoppedWhilePaused && _totalQueuedAtStart > 0) {
       await _notificationService.showQueueComplete(
         completedCount: _completedInSession,
         failedCount: _failedInSession,
@@ -3212,13 +3289,17 @@ class DownloadQueueNotifier extends Notifier<DownloadQueueState> {
       }
     }
 
-    _log.i('Queue processing finished');
+    if (stoppedWhilePaused) {
+      _log.i('Queue processing paused');
+    } else {
+      _log.i('Queue processing finished');
+    }
     state = state.copyWith(isProcessing: false, currentDownload: null);
 
     final hasQueuedItems = state.items.any(
       (item) => item.status == DownloadStatus.queued,
     );
-    if (hasQueuedItems) {
+    if (hasQueuedItems && !state.isPaused) {
       _log.i(
         'Found queued items after processing finished, restarting queue...',
       );
@@ -3234,8 +3315,15 @@ class DownloadQueueNotifier extends Notifier<DownloadQueueState> {
 
     while (true) {
       if (state.isPaused) {
+        if (activeDownloads.isEmpty) {
+          _log.d('Queue is paused and no active downloads remain');
+          break;
+        }
         _log.d('Queue is paused, waiting for active downloads...');
-        await Future.delayed(_queueSchedulingInterval);
+        await Future.any([
+          Future.wait(activeDownloads.values),
+          Future.delayed(_queueSchedulingInterval),
+        ]);
         continue;
       }
 
@@ -3246,7 +3334,11 @@ class DownloadQueueNotifier extends Notifier<DownloadQueueState> {
       }
 
       final queuedItems = state.items
-          .where((item) => item.status == DownloadStatus.queued)
+          .where(
+            (item) =>
+                item.status == DownloadStatus.queued &&
+                !_pausePendingItemIds.contains(item.id),
+          )
           .toList();
 
       if (queuedItems.isEmpty && activeDownloads.isEmpty) {
@@ -3291,11 +3383,13 @@ class DownloadQueueNotifier extends Notifier<DownloadQueueState> {
     _stopProgressPolling();
     final remainingIds = state.items.map((item) => item.id).toSet();
     _locallyCancelledItemIds.removeWhere((id) => !remainingIds.contains(id));
+    _pausePendingItemIds.removeWhere((id) => !remainingIds.contains(id));
   }
 
   Future<void> _downloadSingleItem(DownloadItem item) async {
     _log.d('Processing: ${item.track.name} by ${item.track.artistName}');
     _log.d('Cover URL: ${item.track.coverUrl}');
+    var pausedDuringThisRun = false;
 
     final currentItem = _findItemById(item.id) ?? item;
     if (_isLocallyCancelled(item.id, item: currentItem)) {
@@ -3303,11 +3397,33 @@ class DownloadQueueNotifier extends Notifier<DownloadQueueState> {
       return;
     }
 
+    if (_isPausePending(item.id)) {
+      pausedDuringThisRun = true;
+      _requeueItemForPause(item.id);
+      _log.i('Download is pause-pending before start, skipping');
+      return;
+    }
+
     state = state.copyWith(currentDownload: item);
 
     updateItemStatus(item.id, DownloadStatus.downloading);
 
     try {
+      bool shouldAbortWork(String stage) {
+        final current = _findItemById(item.id);
+        if (_isLocallyCancelled(item.id, item: current)) {
+          _log.i('Download was cancelled $stage, skipping');
+          return true;
+        }
+        if (_isPausePending(item.id)) {
+          pausedDuringThisRun = true;
+          _requeueItemForPause(item.id);
+          _log.i('Download pause requested $stage, re-queueing');
+          return true;
+        }
+        return false;
+      }
+
       final settings = ref.read(settingsProvider);
       final metadataEmbeddingEnabled = settings.embedMetadata;
 
@@ -3388,6 +3504,10 @@ class DownloadQueueNotifier extends Notifier<DownloadQueueState> {
           _log.w('Failed to enrich metadata: $e');
           _log.w('Stack trace: $stack');
         }
+
+        if (shouldAbortWork('during metadata enrichment')) {
+          return;
+        }
       }
 
       _log.d('Track coverUrl after enrichment: ${trackToDownload.coverUrl}');
@@ -3474,6 +3594,15 @@ class DownloadQueueNotifier extends Notifier<DownloadQueueState> {
       String? genre;
       String? label;
       String? copyright;
+      final extensionState = ref.read(extensionProvider);
+      final selectedExtensionDownloadProvider =
+          settings.useExtensionProviders &&
+          extensionState.extensions.any(
+            (e) =>
+                e.enabled &&
+                e.hasDownloadProvider &&
+                e.id.toLowerCase() == item.service.toLowerCase(),
+          );
 
       String? deezerTrackId = trackToDownload.deezerId;
       if (deezerTrackId == null && trackToDownload.id.startsWith('deezer:')) {
@@ -3501,10 +3630,15 @@ class DownloadQueueNotifier extends Notifier<DownloadQueueState> {
         } catch (e) {
           _log.w('Failed to search Deezer by ISRC: $e');
         }
+
+        if (shouldAbortWork('during Deezer ISRC lookup')) {
+          return;
+        }
       }
 
       // Fallback: Use SongLink to convert Spotify ID to Deezer ID
-      if (deezerTrackId == null &&
+      if (!selectedExtensionDownloadProvider &&
+          deezerTrackId == null &&
           trackToDownload.id.isNotEmpty &&
           !trackToDownload.id.startsWith('deezer:') &&
           !trackToDownload.id.startsWith('extension:')) {
@@ -3601,6 +3735,14 @@ class DownloadQueueNotifier extends Notifier<DownloadQueueState> {
         } catch (e) {
           _log.w('Failed to convert Spotify to Deezer via SongLink: $e');
         }
+
+        if (shouldAbortWork('during SongLink availability lookup')) {
+          return;
+        }
+      } else if (selectedExtensionDownloadProvider && deezerTrackId == null) {
+        _log.d(
+          'Skipping Flutter SongLink Deezer prelookup for extension provider: ${item.service}',
+        );
       }
 
       if (deezerTrackId != null && deezerTrackId.isNotEmpty) {
@@ -3620,11 +3762,14 @@ class DownloadQueueNotifier extends Notifier<DownloadQueueState> {
         } catch (e) {
           _log.w('Failed to fetch extended metadata from Deezer: $e');
         }
+
+        if (shouldAbortWork('during extended metadata lookup')) {
+          return;
+        }
       }
 
       Map<String, dynamic> result;
 
-      final extensionState = ref.read(extensionProvider);
       final hasActiveExtensions = extensionState.extensions.any(
         (e) => e.enabled,
       );
@@ -3738,8 +3883,7 @@ class DownloadQueueNotifier extends Notifier<DownloadQueueState> {
         );
       }
 
-      if (_isLocallyCancelled(item.id)) {
-        _log.i('Download was cancelled before native download start, skipping');
+      if (shouldAbortWork('before native download start')) {
         return;
       }
 
@@ -3781,10 +3925,8 @@ class DownloadQueueNotifier extends Notifier<DownloadQueueState> {
       _log.d('Result: $result');
 
       final itemAfterResult = _findItemById(item.id);
-      final cancelledAfterResult =
-          itemAfterResult == null ||
-          _isLocallyCancelled(item.id, item: itemAfterResult);
-      if (cancelledAfterResult) {
+      if (itemAfterResult == null ||
+          _isLocallyCancelled(item.id, item: itemAfterResult)) {
         _log.i('Download was cancelled, skipping result processing');
         final filePath = result['file_path'] as String?;
         if (filePath != null && result['success'] == true) {
@@ -3794,6 +3936,18 @@ class DownloadQueueNotifier extends Notifier<DownloadQueueState> {
         return;
       }
 
+      if (_isPausePending(item.id)) {
+        pausedDuringThisRun = true;
+        final filePath = result['file_path'] as String?;
+        if (filePath != null && result['success'] == true) {
+          await deleteFile(filePath);
+          _log.d('Deleted paused download file: $filePath');
+        }
+        _requeueItemForPause(item.id);
+        _log.i('Download pause requested after result, re-queueing');
+        return;
+      }
+
       if (result['success'] == true) {
         var filePath = result['file_path'] as String?;
         final reportedFileName = result['file_name'] as String?;
@@ -4327,6 +4481,19 @@ class DownloadQueueNotifier extends Notifier<DownloadQueueState> {
           return;
         }
 
+        if (_isPausePending(item.id)) {
+          pausedDuringThisRun = true;
+          if (filePath != null) {
+            await deleteFile(filePath);
+            _log.d(
+              'Deleted paused download file during finalization: $filePath',
+            );
+          }
+          _requeueItemForPause(item.id);
+          _log.i('Download pause requested during finalization, re-queueing');
+          return;
+        }
+
         // SAF downloads should end with content URI. If we still have a
         // transient FD path, recover URI from SAF metadata to keep history
         // dedup/exclusion stable.
@@ -4594,11 +4761,26 @@ class DownloadQueueNotifier extends Notifier<DownloadQueueState> {
           return;
         }
 
+        if (_isPausePending(item.id)) {
+          pausedDuringThisRun = true;
+          _requeueItemForPause(item.id);
+          _log.i('Download pause requested after backend failure, re-queueing');
+          return;
+        }
+
         final errorMsg = result['error'] as String? ?? 'Download failed';
         final errorTypeStr = result['error_type'] as String? ?? 'unknown';
         if (errorTypeStr == 'cancelled') {
-          _log.i('Download was cancelled by backend, skipping error handling');
-          updateItemStatus(item.id, DownloadStatus.skipped);
+          if (_isPausePending(item.id)) {
+            pausedDuringThisRun = true;
+            _requeueItemForPause(item.id);
+            _log.i('Download was paused by backend cancellation, re-queueing');
+          } else {
+            _log.i(
+              'Download was cancelled by backend, skipping error handling',
+            );
+            updateItemStatus(item.id, DownloadStatus.skipped);
+          }
           return;
         }
 
@@ -4657,6 +4839,13 @@ class DownloadQueueNotifier extends Notifier<DownloadQueueState> {
         return;
       }
 
+      if (_isPausePending(item.id)) {
+        pausedDuringThisRun = true;
+        _requeueItemForPause(item.id);
+        _log.i('Download pause requested after exception, re-queueing');
+        return;
+      }
+
       _log.e('Exception: $e', e, stackTrace);
 
       String errorMsg = e.toString();
@@ -4682,6 +4871,10 @@ class DownloadQueueNotifier extends Notifier<DownloadQueueState> {
       } catch (cleanupErr) {
         _log.e('Post-exception connection cleanup failed: $cleanupErr');
       }
+    } finally {
+      if (pausedDuringThisRun) {
+        _pausePendingItemIds.remove(item.id);
+      }
     }
   }
 }

lib/providers/local_library_provider.dart

@@ -9,11 +9,11 @@ import 'package:spotiflac_android/services/library_database.dart';
 import 'package:spotiflac_android/services/notification_service.dart';
 import 'package:spotiflac_android/services/platform_bridge.dart';
 import 'package:spotiflac_android/utils/logger.dart';
+import 'package:spotiflac_android/utils/local_library_scan_prefs.dart';
 import 'package:spotiflac_android/utils/path_match_keys.dart';
 
 final _log = AppLogger('LocalLibrary');
 
-const _lastScannedAtKey = 'local_library_last_scanned_at';
 const _excludedDownloadedCountKey = 'local_library_excluded_downloaded_count';
 final _prefs = SharedPreferences.getInstance();
 
@@ -165,10 +165,7 @@ class LocalLibraryNotifier extends Notifier<LocalLibraryState> {
       var excludedDownloadedCount = 0;
       try {
         final prefs = await prefsFuture;
-        final lastScannedAtStr = prefs.getString(_lastScannedAtKey);
-        if (lastScannedAtStr != null && lastScannedAtStr.isNotEmpty) {
-          lastScannedAt = DateTime.tryParse(lastScannedAtStr);
-        }
+        lastScannedAt = readLocalLibraryLastScannedAt(prefs);
         excludedDownloadedCount =
             prefs.getInt(_excludedDownloadedCountKey) ?? 0;
       } catch (e) {
@@ -332,11 +329,16 @@ class LocalLibraryNotifier extends Notifier<LocalLibraryState> {
         if (items.isNotEmpty) {
           await _db.upsertBatch(items.map((e) => e.toJson()).toList());
         }
+        final persistedItems =
+            (await _db.getAll())
+                .map(LocalLibraryItem.fromJson)
+                .toList(growable: false)
+              ..sort(_compareLibraryItems);
 
         final now = DateTime.now();
         try {
           final prefs = await SharedPreferences.getInstance();
-          await prefs.setString(_lastScannedAtKey, now.toIso8601String());
+          await writeLocalLibraryLastScannedAt(prefs, now);
           await prefs.setInt(_excludedDownloadedCountKey, skippedDownloads);
           _log.d('Saved lastScannedAt: $now');
         } catch (e) {
@@ -344,7 +346,7 @@ class LocalLibraryNotifier extends Notifier<LocalLibraryState> {
         }
 
         state = state.copyWith(
-          items: items,
+          items: persistedItems,
           isScanning: false,
           scanProgress: 100,
           lastScannedAt: now,
@@ -353,11 +355,11 @@ class LocalLibraryNotifier extends Notifier<LocalLibraryState> {
         );
 
         _log.i(
-          'Full scan complete: ${items.length} tracks found, '
+          'Full scan complete: ${persistedItems.length} tracks found, '
           '$skippedDownloads already in downloads',
         );
         await _showScanCompleteNotification(
-          totalTracks: items.length,
+          totalTracks: persistedItems.length,
           excludedDownloadedCount: skippedDownloads,
           errorCount: state.scanErrorCount,
         );
@@ -442,8 +444,14 @@ class LocalLibraryNotifier extends Notifier<LocalLibraryState> {
           '$skippedCount skipped, ${deletedPaths.length} deleted, $totalFiles total',
         );
 
+        // Build the incremental merge base from SQLite, not the current
+        // provider state. Startup auto-scan can fire before `state.items` has
+        // finished loading, which would otherwise drop unchanged rows from the
+        // in-memory library until a manual full rescan.
+        final existingJson = await _db.getAll();
         final currentByPath = <String, LocalLibraryItem>{
-          for (final item in state.items) item.filePath: item,
+          for (final item in existingJson.map(LocalLibraryItem.fromJson))
+            item.filePath: item,
         };
         final existingDownloadedPaths = <String>[];
         currentByPath.removeWhere((path, _) {
@@ -494,13 +502,16 @@ class LocalLibraryNotifier extends Notifier<LocalLibraryState> {
           _log.i('Deleted $deleteCount items from database');
         }
 
-        final items = currentByPath.values.toList(growable: false)
-          ..sort(_compareLibraryItems);
+        final items =
+            (await _db.getAll())
+                .map(LocalLibraryItem.fromJson)
+                .toList(growable: false)
+              ..sort(_compareLibraryItems);
 
         final now = DateTime.now();
         try {
           final prefs = await SharedPreferences.getInstance();
-          await prefs.setString(_lastScannedAtKey, now.toIso8601String());
+          await writeLocalLibraryLastScannedAt(prefs, now);
           await prefs.setInt(_excludedDownloadedCountKey, skippedDownloads);
           _log.d('Saved lastScannedAt: $now');
         } catch (e) {
@@ -818,7 +829,7 @@ class LocalLibraryNotifier extends Notifier<LocalLibraryState> {
 
     try {
       final prefs = await SharedPreferences.getInstance();
-      await prefs.remove(_lastScannedAtKey);
+      await clearLocalLibraryLastScannedAt(prefs);
       await prefs.remove(_excludedDownloadedCountKey);
     } catch (e) {
       _log.w('Failed to clear lastScannedAt: $e');

lib/providers/settings_provider.dart

@@ -406,8 +406,7 @@ class SettingsNotifier extends Notifier<AppSettings> {
   }
 
   void setMetadataSource(String source) {
-    final normalized = source == 'deezer' ? 'deezer' : 'deezer';
-    state = state.copyWith(metadataSource: normalized);
+    state = state.copyWith(metadataSource: source);
     _saveSettings();
   }
 

lib/providers/track_provider.dart

@@ -958,9 +958,16 @@ class TrackNotifier extends Notifier<TrackState> {
     final durationMs = _extractDurationMs(data);
 
     final itemType = data['item_type']?.toString();
+    final effectiveSource =
+        source ?? data['source']?.toString() ?? data['provider_id']?.toString();
+    final spotifyId = (data['spotify_id'] ?? '').toString();
+    final nativeId = (data['id'] ?? '').toString();
+    final preferredId = effectiveSource != null && effectiveSource.isNotEmpty
+        ? (nativeId.isNotEmpty ? nativeId : spotifyId)
+        : (spotifyId.isNotEmpty ? spotifyId : nativeId);
 
     return Track(
-      id: (data['spotify_id'] ?? data['id'] ?? '').toString(),
+      id: preferredId,
       name: (data['name'] ?? '').toString(),
       artistName: (data['artists'] ?? data['artist'] ?? '').toString(),
       albumName: (data['album_name'] ?? data['album'] ?? '').toString(),
@@ -974,10 +981,7 @@ class TrackNotifier extends Notifier<TrackState> {
       discNumber: data['disc_number'] as int?,
       releaseDate: data['release_date']?.toString(),
       totalTracks: data['total_tracks'] as int?,
-      source:
-          source ??
-          data['source']?.toString() ??
-          data['provider_id']?.toString(),
+      source: effectiveSource,
       albumType: data['album_type']?.toString(),
       itemType: itemType,
     );

lib/screens/library_tracks_folder_screen.dart

@@ -872,12 +872,54 @@ class _LibraryTracksFolderScreenState
 
   void _downloadAll(List<Track> tracks) {
     if (tracks.isEmpty) return;
+    final historyState = ref.read(downloadHistoryProvider);
     final settings = ref.read(settingsProvider);
-    final playlistName = widget.mode == LibraryTracksFolderMode.playlist ? playlist?.name ?? context.l10n.collectionPlaylist : null;
+    final localLibState =
+        (settings.localLibraryEnabled && settings.localLibraryShowDuplicates)
+        ? ref.read(localLibraryProvider)
+        : null;
+    final playlistName = widget.mode == LibraryTracksFolderMode.playlist
+        ? playlist?.name ?? context.l10n.collectionPlaylist
+        : null;
+    final tracksToQueue = <Track>[];
+    var skippedCount = 0;
+
+    for (final track in tracks) {
+      final isInHistory =
+          historyState.isDownloaded(track.id) ||
+          (track.isrc != null && historyState.getByIsrc(track.isrc!) != null) ||
+          historyState.findByTrackAndArtist(track.name, track.artistName) !=
+              null;
+      final isInLocal =
+          localLibState?.existsInLibrary(
+            isrc: track.isrc,
+            trackName: track.name,
+            artistName: track.artistName,
+          ) ??
+          false;
+
+      if (isInHistory || isInLocal) {
+        skippedCount++;
+      } else {
+        tracksToQueue.add(track);
+      }
+    }
+
+    if (tracksToQueue.isEmpty) {
+      ScaffoldMessenger.of(context).showSnackBar(
+        SnackBar(
+          content: Text(
+            context.l10n.discographySkippedDownloaded(0, skippedCount),
+          ),
+        ),
+      );
+      return;
+    }
+
     if (settings.askQualityBeforeDownload) {
       DownloadServicePicker.show(
         context,
-        trackName: '${tracks.length} tracks',
+        trackName: '${tracksToQueue.length} tracks',
         artistName: switch (widget.mode) {
           LibraryTracksFolderMode.wishlist => context.l10n.collectionWishlist,
           LibraryTracksFolderMode.loved => context.l10n.collectionLoved,
@@ -886,12 +928,24 @@ class _LibraryTracksFolderScreenState
         onSelect: (quality, service) {
           ref
               .read(downloadQueueProvider.notifier)
-              .addMultipleToQueue(tracks, service, qualityOverride: quality, playlistName: playlistName);
+              .addMultipleToQueue(
+                tracksToQueue,
+                service,
+                qualityOverride: quality,
+                playlistName: playlistName,
+              );
           if (!mounted) return;
           ScaffoldMessenger.of(context).showSnackBar(
             SnackBar(
               content: Text(
-                context.l10n.snackbarAddedTracksToQueue(tracks.length),
+                skippedCount > 0
+                    ? context.l10n.discographySkippedDownloaded(
+                        tracksToQueue.length,
+                        skippedCount,
+                      )
+                    : context.l10n.snackbarAddedTracksToQueue(
+                        tracksToQueue.length,
+                      ),
               ),
             ),
           );
@@ -900,10 +954,21 @@ class _LibraryTracksFolderScreenState
     } else {
       ref
           .read(downloadQueueProvider.notifier)
-          .addMultipleToQueue(tracks, settings.defaultService, playlistName: playlistName);
+          .addMultipleToQueue(
+            tracksToQueue,
+            settings.defaultService,
+            playlistName: playlistName,
+          );
       ScaffoldMessenger.of(context).showSnackBar(
         SnackBar(
-          content: Text(context.l10n.snackbarAddedTracksToQueue(tracks.length)),
+          content: Text(
+            skippedCount > 0
+                ? context.l10n.discographySkippedDownloaded(
+                    tracksToQueue.length,
+                    skippedCount,
+                  )
+                : context.l10n.snackbarAddedTracksToQueue(tracksToQueue.length),
+          ),
         ),
       );
     }

lib/screens/local_album_screen.dart

@@ -626,11 +626,13 @@ class _LocalAlbumScreenState extends ConsumerState<LocalAlbumScreen> {
 
       slivers.add(
         SliverList(
-          delegate: SliverChildBuilderDelegate(
-            (context, index) =>
-                _buildTrackItem(context, colorScheme, discTracks[index]),
-            childCount: discTracks.length,
-          ),
+          delegate: SliverChildBuilderDelegate((context, index) {
+            final track = discTracks[index];
+            return KeyedSubtree(
+              key: ValueKey(track.id),
+              child: _buildTrackItem(context, colorScheme, track),
+            );
+          }, childCount: discTracks.length),
         ),
       );
     }
@@ -900,16 +902,19 @@ class _LocalAlbumScreenState extends ConsumerState<LocalAlbumScreen> {
     return false;
   }
 
-  Future<void> _queueSelectedAsFlac(List<LocalLibraryItem> allTracks) async {
+  List<LocalLibraryItem> _selectedFlacEligibleItems(
+    List<LocalLibraryItem> allTracks,
+  ) {
     final tracksById = {for (final t in allTracks) t.id: t};
-    final selected = <LocalLibraryItem>[];
+    return _selectedIds
+        .map((id) => tracksById[id])
+        .whereType<LocalLibraryItem>()
+        .where(LocalTrackRedownloadService.isFlacUpgradeEligible)
+        .toList(growable: false);
+  }
 
-    for (final id in _selectedIds) {
-      final item = tracksById[id];
-      if (item != null) {
-        selected.add(item);
-      }
-    }
+  Future<void> _queueSelectedAsFlac(List<LocalLibraryItem> allTracks) async {
+    final selected = _selectedFlacEligibleItems(allTracks);
 
     if (selected.isEmpty) {
       return;
@@ -962,9 +967,7 @@ class _LocalAlbumScreenState extends ConsumerState<LocalAlbumScreen> {
       ScaffoldMessenger.of(context).clearSnackBars();
       ScaffoldMessenger.of(context).showSnackBar(
         SnackBar(
-          content: Text(
-            context.l10n.queueFlacFindingProgress(i + 1, total),
-          ),
+          content: Text(context.l10n.queueFlacFindingProgress(i + 1, total)),
           duration: const Duration(seconds: 30),
         ),
       );
@@ -1177,8 +1180,9 @@ class _LocalAlbumScreenState extends ConsumerState<LocalAlbumScreen> {
     String selectedFormat = formats.first;
     bool isLosslessTarget =
         selectedFormat == 'ALAC' || selectedFormat == 'FLAC';
-    String selectedBitrate =
-        isLosslessTarget ? '320k' : (selectedFormat == 'Opus' ? '128k' : '320k');
+    String selectedBitrate = isLosslessTarget
+        ? '320k'
+        : (selectedFormat == 'Opus' ? '128k' : '320k');
 
     showModalBottomSheet(
       context: context,
@@ -1240,8 +1244,9 @@ class _LocalAlbumScreenState extends ConsumerState<LocalAlbumScreen> {
                                 isLosslessTarget =
                                     format == 'ALAC' || format == 'FLAC';
                                 if (!isLosslessTarget) {
-                                  selectedBitrate =
-                                      format == 'Opus' ? '128k' : '320k';
+                                  selectedBitrate = format == 'Opus'
+                                      ? '128k'
+                                      : '320k';
                                 }
                               });
                             }
@@ -1286,11 +1291,8 @@ class _LocalAlbumScreenState extends ConsumerState<LocalAlbumScreen> {
                           const SizedBox(width: 6),
                           Text(
                             context.l10n.trackConvertLosslessHint,
-                            style: Theme.of(
-                              context,
-                            ).textTheme.bodySmall?.copyWith(
-                              color: colorScheme.primary,
-                            ),
+                            style: Theme.of(context).textTheme.bodySmall
+                                ?.copyWith(color: colorScheme.primary),
                           ),
                         ],
                       ),
@@ -1371,7 +1373,8 @@ class _LocalAlbumScreenState extends ConsumerState<LocalAlbumScreen> {
       if (currentFormat == null || currentFormat == targetFormat) continue;
       // Skip lossy sources when target is lossless (pointless re-encoding)
       final isLosslessTarget = targetFormat == 'ALAC' || targetFormat == 'FLAC';
-      final isLosslessSource = currentFormat == 'FLAC' || currentFormat == 'M4A';
+      final isLosslessSource =
+          currentFormat == 'FLAC' || currentFormat == 'M4A';
       if (isLosslessTarget && !isLosslessSource) continue;
       selected.add(item);
     }
@@ -1656,6 +1659,7 @@ class _LocalAlbumScreenState extends ConsumerState<LocalAlbumScreen> {
     double bottomPadding,
   ) {
     final selectedCount = _selectedIds.length;
+    final flacEligibleCount = _selectedFlacEligibleItems(tracks).length;
     final allSelected = selectedCount == tracks.length && tracks.isNotEmpty;
 
     return Container(
@@ -1747,17 +1751,18 @@ class _LocalAlbumScreenState extends ConsumerState<LocalAlbumScreen> {
 
               Row(
                 children: [
-                  Expanded(
-                    child: _LocalAlbumSelectionActionButton(
-                      icon: Icons.download_for_offline_outlined,
-                      label: '${context.l10n.queueFlacAction} ($selectedCount)',
-                      onPressed: selectedCount > 0
-                          ? () => _queueSelectedAsFlac(tracks)
-                          : null,
-                      colorScheme: colorScheme,
+                  if (flacEligibleCount > 0) ...[
+                    Expanded(
+                      child: _LocalAlbumSelectionActionButton(
+                        icon: Icons.download_for_offline_outlined,
+                        label:
+                            '${context.l10n.queueFlacAction} ($flacEligibleCount)',
+                        onPressed: () => _queueSelectedAsFlac(tracks),
+                        colorScheme: colorScheme,
+                      ),
                     ),
-                  ),
-                  const SizedBox(width: 8),
+                    const SizedBox(width: 8),
+                  ],
                   Expanded(
                     child: _LocalAlbumSelectionActionButton(
                       icon: Icons.auto_fix_high_outlined,

lib/screens/main_shell.dart

@@ -83,7 +83,6 @@ class _MainShellState extends ConsumerState<MainShell> {
     final extState = ref.read(extensionProvider);
     if (!extState.isInitialized) {
       _log.d('Waiting for extensions to initialize before handling URL...');
-      // Wait up to 5 seconds for extensions to initialize
       for (int i = 0; i < 50; i++) {
         await Future.delayed(const Duration(milliseconds: 100));
         if (!mounted) return;

lib/screens/queue_tab.dart

@@ -4484,14 +4484,21 @@ class _QueueTabState extends ConsumerState<QueueTab> {
     return false;
   }
 
+  List<LocalLibraryItem> _selectedFlacEligibleLocalItems(
+    List<UnifiedLibraryItem> allItems,
+  ) {
+    final selectedItems = _selectedItemsFromAll(allItems);
+    return selectedItems
+        .map((item) => item.localItem)
+        .whereType<LocalLibraryItem>()
+        .where(LocalTrackRedownloadService.isFlacUpgradeEligible)
+        .toList(growable: false);
+  }
+
   Future<void> _queueSelectedLocalAsFlac(
     List<UnifiedLibraryItem> allItems,
   ) async {
-    final selectedItems = _selectedItemsFromAll(allItems);
-    final selectedLocalItems = selectedItems
-        .map((item) => item.localItem)
-        .whereType<LocalLibraryItem>()
-        .toList(growable: false);
+    final selectedLocalItems = _selectedFlacEligibleLocalItems(allItems);
 
     if (selectedLocalItems.isEmpty) {
       return;
@@ -4546,9 +4553,7 @@ class _QueueTabState extends ConsumerState<QueueTab> {
       ScaffoldMessenger.of(context).clearSnackBars();
       ScaffoldMessenger.of(context).showSnackBar(
         SnackBar(
-          content: Text(
-            context.l10n.queueFlacFindingProgress(i + 1, total),
-          ),
+          content: Text(context.l10n.queueFlacFindingProgress(i + 1, total)),
           duration: const Duration(seconds: 30),
         ),
       );
@@ -4797,8 +4802,9 @@ class _QueueTabState extends ConsumerState<QueueTab> {
     String selectedFormat = formats.first;
     bool isLosslessTarget =
         selectedFormat == 'ALAC' || selectedFormat == 'FLAC';
-    String selectedBitrate =
-        isLosslessTarget ? '320k' : (selectedFormat == 'Opus' ? '128k' : '320k');
+    String selectedBitrate = isLosslessTarget
+        ? '320k'
+        : (selectedFormat == 'Opus' ? '128k' : '320k');
     var didStartConversion = false;
 
     _hideSelectionOverlay();
@@ -4864,8 +4870,9 @@ class _QueueTabState extends ConsumerState<QueueTab> {
                                 isLosslessTarget =
                                     format == 'ALAC' || format == 'FLAC';
                                 if (!isLosslessTarget) {
-                                  selectedBitrate =
-                                      format == 'Opus' ? '128k' : '320k';
+                                  selectedBitrate = format == 'Opus'
+                                      ? '128k'
+                                      : '320k';
                                 }
                               });
                             }
@@ -4910,11 +4917,8 @@ class _QueueTabState extends ConsumerState<QueueTab> {
                           const SizedBox(width: 6),
                           Text(
                             context.l10n.trackConvertLosslessHint,
-                            style: Theme.of(
-                              context,
-                            ).textTheme.bodySmall?.copyWith(
-                              color: colorScheme.primary,
-                            ),
+                            style: Theme.of(context).textTheme.bodySmall
+                                ?.copyWith(color: colorScheme.primary),
                           ),
                         ],
                       ),
@@ -5054,7 +5058,8 @@ class _QueueTabState extends ConsumerState<QueueTab> {
     int successCount = 0;
     final total = selectedItems.length;
     final historyDb = HistoryDatabase.instance;
-    final newQuality = (targetFormat.toUpperCase() == 'ALAC' ||
+    final newQuality =
+        (targetFormat.toUpperCase() == 'ALAC' ||
             targetFormat.toUpperCase() == 'FLAC')
         ? '${targetFormat.toUpperCase()} Lossless'
         : '${targetFormat.toUpperCase()} ${bitrate.trim().toLowerCase()}';
@@ -5077,7 +5082,6 @@ class _QueueTabState extends ConsumerState<QueueTab> {
       );
 
       try {
-        // Read metadata from file
         final metadata = <String, String>{
           'TITLE': item.trackName,
           'ARTIST': item.artistName,
@@ -5106,7 +5110,6 @@ class _QueueTabState extends ConsumerState<QueueTab> {
               1000,
         );
 
-        // Extract cover art
         String? coverPath;
         try {
           final tempDir = await getTemporaryDirectory();
@@ -5121,7 +5124,6 @@ class _QueueTabState extends ConsumerState<QueueTab> {
           }
         } catch (_) {}
 
-        // Handle SAF vs regular file
         String workingPath = item.filePath;
         final isSaf = isContentUri(item.filePath);
         String? safTempPath;
@@ -5134,7 +5136,6 @@ class _QueueTabState extends ConsumerState<QueueTab> {
           workingPath = safTempPath;
         }
 
-        // Convert
         final newPath = await FFmpegService.convertAudioFormat(
           inputPath: workingPath,
           targetFormat: targetFormat.toLowerCase(),
@@ -5144,7 +5145,6 @@ class _QueueTabState extends ConsumerState<QueueTab> {
           deleteOriginal: !isSaf,
         );
 
-        // Cleanup cover temp
         if (coverPath != null) {
           try {
             await File(coverPath).delete();
@@ -5375,6 +5375,9 @@ class _QueueTabState extends ConsumerState<QueueTab> {
     final allSelected =
         selectedCount == unifiedItems.length && unifiedItems.isNotEmpty;
     final localOnlySelection = _isLocalOnlySelection(unifiedItems);
+    final flacEligibleCount = _selectedFlacEligibleLocalItems(
+      unifiedItems,
+    ).length;
 
     return Container(
       decoration: BoxDecoration(
@@ -5464,15 +5467,13 @@ class _QueueTabState extends ConsumerState<QueueTab> {
               // Action buttons row: Share/Re-enrich, Convert, Delete
               Row(
                 children: [
-                  if (localOnlySelection) ...[
+                  if (localOnlySelection && flacEligibleCount > 0) ...[
                     Expanded(
                       child: _SelectionActionButton(
                         icon: Icons.download_for_offline_outlined,
                         label:
-                            '${context.l10n.queueFlacAction} ($selectedCount)',
-                        onPressed: selectedCount > 0
-                            ? () => _queueSelectedLocalAsFlac(unifiedItems)
-                            : null,
+                            '${context.l10n.queueFlacAction} ($flacEligibleCount)',
+                        onPressed: () => _queueSelectedLocalAsFlac(unifiedItems),
                         colorScheme: colorScheme,
                       ),
                     ),

lib/screens/settings/donate_page.dart

@@ -164,7 +164,7 @@ class _RecentDonorsCard extends StatelessWidget {
   @override
   Widget build(BuildContext context) {
     final isDark = Theme.of(context).brightness == Brightness.dark;
-    const donorNames = <String>['micahRichie', 'a fan', 'mc nuggets jimmy', 'CJBGR'];
+    const donorNames = <String>['McNuggets Jimmy', 'zcc09', 'micahRichie', 'a fan', 'CJBGR'];
 
     // Match SettingsGroup color logic
     final cardColor = isDark
@@ -480,7 +480,7 @@ int _cr(String v) {
 }
 
 // Highlighted supporters (hashes of names).
-const _cv = <int>{1211573191};
+const _cv = <int>{1211573191, 1003219236, 560908930};
 
 class _SupporterChip extends StatelessWidget {
   final String name;

lib/services/cover_cache_manager.dart

@@ -37,7 +37,6 @@ class CoverCacheManager {
       final appDir = await getApplicationSupportDirectory();
       _cachePath = p.join(appDir.path, 'cover_cache');
       
-      // Ensure cache directory exists
       await Directory(_cachePath!).create(recursive: true);
       
       debugPrint('CoverCacheManager: Initializing at $_cachePath');
@@ -48,7 +47,6 @@ class CoverCacheManager {
       debugPrint('CoverCacheManager: Initialized successfully');
     } catch (e) {
       debugPrint('CoverCacheManager: Failed to initialize: $e');
-      // Will fallback to DefaultCacheManager
     }
   }
 

lib/services/history_database.dart

@@ -12,7 +12,6 @@ final Future<SharedPreferences> _prefs = SharedPreferences.getInstance();
 /// Cached current iOS container path for path normalization
 String? _currentContainerPath;
 
-/// SQLite database service for download history
 /// Provides O(1) lookups by spotify_id and isrc with proper indexing
 class HistoryDatabase {
   static final HistoryDatabase instance = HistoryDatabase._init();
@@ -78,7 +77,6 @@ class HistoryDatabase {
       )
     ''');
 
-    // Indexes for fast lookups
     await db.execute('CREATE INDEX idx_spotify_id ON history(spotify_id)');
     await db.execute('CREATE INDEX idx_isrc ON history(isrc)');
     await db.execute(
@@ -171,7 +169,6 @@ class HistoryDatabase {
     try {
       final db = await database;
 
-      // Get all items with iOS paths
       final rows = await db.query('history', columns: ['id', 'file_path']);
       int updatedCount = 0;
       final batch = db.batch();
@@ -198,7 +195,6 @@ class HistoryDatabase {
         await batch.commit(noResult: true);
       }
 
-      // Save current container path
       await prefs.setString('ios_last_container_path', _currentContainerPath!);
 
       _log.i('iOS path migration complete: $updatedCount paths updated');
@@ -323,7 +319,6 @@ class HistoryDatabase {
     };
   }
 
-  /// Insert or update a history item
   Future<void> upsert(Map<String, dynamic> json) async {
     final db = await database;
     await db.insert(
@@ -345,7 +340,6 @@ class HistoryDatabase {
     return rows.map(_dbRowToJson).toList();
   }
 
-  /// Get item by ID
   Future<Map<String, dynamic>?> getById(String id) async {
     final db = await database;
     final rows = await db.query(
@@ -403,26 +397,22 @@ class HistoryDatabase {
     return rows.map((r) => r['spotify_id'] as String).toSet();
   }
 
-  /// Delete by ID
   Future<void> deleteById(String id) async {
     final db = await database;
     await db.delete('history', where: 'id = ?', whereArgs: [id]);
   }
 
-  /// Delete by Spotify ID
   Future<void> deleteBySpotifyId(String spotifyId) async {
     final db = await database;
     await db.delete('history', where: 'spotify_id = ?', whereArgs: [spotifyId]);
   }
 
-  /// Clear all history
   Future<void> clearAll() async {
     final db = await database;
     await db.delete('history');
     _log.i('Cleared all history');
   }
 
-  /// Get total count
   Future<int> getCount() async {
     final db = await database;
     final result = await db.rawQuery('SELECT COUNT(*) as count FROM history');
@@ -459,7 +449,6 @@ class HistoryDatabase {
     return null;
   }
 
-  /// Close database
   Future<void> close() async {
     final db = await database;
     await db.close();

lib/services/library_database.dart

@@ -123,7 +123,7 @@ class LibraryDatabase {
 
     return await openDatabase(
       path,
-      version: 4, // Bumped version for bitrate column
+      version: 4,
       onConfigure: (db) async {
         await db.rawQuery('PRAGMA journal_mode = WAL');
         await db.execute('PRAGMA synchronous = NORMAL');
@@ -331,13 +331,11 @@ class LibraryDatabase {
     String? trackName,
     String? artistName,
   }) async {
-    // First try ISRC if available
     if (isrc != null && isrc.isNotEmpty) {
       final byIsrc = await getByIsrc(isrc);
       if (byIsrc != null) return byIsrc;
     }
 
-    // Then try name matching
     if (trackName != null && artistName != null) {
       final matches = await findByTrackAndArtist(trackName, artistName);
       if (matches.isNotEmpty) return matches.first;
@@ -523,7 +521,6 @@ class LibraryDatabase {
     return rows.map((r) => r['file_path'] as String).toSet();
   }
 
-  /// Delete multiple items by their file paths
   Future<int> deleteByPaths(List<String> filePaths) async {
     if (filePaths.isEmpty) return 0;
     final db = await database;

lib/services/local_track_redownload_service.dart

@@ -23,6 +23,15 @@ class LocalTrackRedownloadService {
   static const int _minimumConfidenceScore = 85;
   static const int _ambiguousScoreGap = 8;
 
+  static bool isFlacUpgradeEligible(LocalLibraryItem item) {
+    final format = item.format?.trim().toLowerCase();
+    if (format == 'flac') {
+      return false;
+    }
+
+    return !item.filePath.toLowerCase().endsWith('.flac');
+  }
+
   static Future<LocalTrackRedownloadResolution> resolveBestMatch(
     LocalLibraryItem item, {
     required bool includeExtensions,

lib/theme/app_theme.dart

@@ -35,7 +35,6 @@ class AppTheme {
     );
   }
 
-  /// Create dark theme
   static ThemeData dark({
     ColorScheme? dynamicScheme,
     Color? seedColor,
@@ -88,12 +87,11 @@ class AppTheme {
     ),
   );
 
-  /// Card theme
   static CardThemeData _cardTheme(ColorScheme scheme) => CardThemeData(
     elevation: 0,
     shape: RoundedRectangleBorder(
       borderRadius: BorderRadius.circular(16),
-    ), // 12 -> 16
+    ),
     color: scheme.surfaceContainerLow,
     surfaceTintColor: scheme.surfaceTint,
   );
@@ -104,18 +102,17 @@ class AppTheme {
           elevation: 1,
           shape: RoundedRectangleBorder(
             borderRadius: BorderRadius.circular(16),
-          ), // 20 -> 16
+          ),
           padding: const EdgeInsets.symmetric(horizontal: 24, vertical: 12),
         ),
       );
 
-  /// Filled button theme
   static FilledButtonThemeData _filledButtonTheme(ColorScheme scheme) =>
       FilledButtonThemeData(
         style: FilledButton.styleFrom(
           shape: RoundedRectangleBorder(
             borderRadius: BorderRadius.circular(16),
-          ), // 20 -> 16
+          ),
           padding: const EdgeInsets.symmetric(horizontal: 24, vertical: 12),
         ),
       );
@@ -125,18 +122,17 @@ class AppTheme {
         style: OutlinedButton.styleFrom(
           shape: RoundedRectangleBorder(
             borderRadius: BorderRadius.circular(16),
-          ), // 20 -> 16
+          ),
           padding: const EdgeInsets.symmetric(horizontal: 24, vertical: 12),
         ),
       );
 
-  /// Text button theme
   static TextButtonThemeData _textButtonTheme(ColorScheme scheme) =>
       TextButtonThemeData(
         style: TextButton.styleFrom(
           shape: RoundedRectangleBorder(
             borderRadius: BorderRadius.circular(16),
-          ), // 20 -> 16
+          ),
           padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 8),
         ),
       );
@@ -149,40 +145,39 @@ class AppTheme {
         foregroundColor: scheme.onPrimaryContainer,
       );
 
-  /// Input decoration theme
   static InputDecorationTheme _inputDecorationTheme(ColorScheme scheme) =>
       InputDecorationTheme(
         filled: true,
         fillColor: scheme.surfaceContainerHighest.withValues(
           alpha: 0.3,
-        ), // Added transparency
+        ),
         border: OutlineInputBorder(
-          borderRadius: BorderRadius.circular(16), // 12 -> 16
+          borderRadius: BorderRadius.circular(16),
           borderSide: BorderSide.none,
         ),
         enabledBorder: OutlineInputBorder(
-          borderRadius: BorderRadius.circular(16), // 12 -> 16
+          borderRadius: BorderRadius.circular(16),
           borderSide: BorderSide.none,
         ),
         focusedBorder: OutlineInputBorder(
-          borderRadius: BorderRadius.circular(16), // 12 -> 16
+          borderRadius: BorderRadius.circular(16),
           borderSide: BorderSide(color: scheme.primary, width: 2),
         ),
         errorBorder: OutlineInputBorder(
-          borderRadius: BorderRadius.circular(16), // 12 -> 16
+          borderRadius: BorderRadius.circular(16),
           borderSide: BorderSide(color: scheme.error, width: 1),
         ),
         contentPadding: const EdgeInsets.symmetric(
           horizontal: 20,
           vertical: 16,
-        ), // consistent padding
+        ),
       );
 
   static ListTileThemeData _listTileTheme(ColorScheme scheme) =>
       ListTileThemeData(
         shape: RoundedRectangleBorder(
           borderRadius: BorderRadius.circular(16),
-        ), // 12 -> 16
+        ),
         contentPadding: const EdgeInsets.symmetric(horizontal: 16, vertical: 4),
       );
 
@@ -193,7 +188,6 @@ class AppTheme {
     surfaceTintColor: scheme.surfaceTint,
   );
 
-  /// Navigation bar theme
   static NavigationBarThemeData _navigationBarTheme(
     ColorScheme scheme, {
     bool isAmoled = false,
@@ -213,7 +207,6 @@ class AppTheme {
         contentTextStyle: TextStyle(color: scheme.onInverseSurface),
       );
 
-  /// Progress indicator theme
   static ProgressIndicatorThemeData _progressIndicatorTheme(
     ColorScheme scheme,
   ) => ProgressIndicatorThemeData(
@@ -243,7 +236,6 @@ class AppTheme {
     }),
   );
 
-  /// Chip theme
   static ChipThemeData _chipTheme(ColorScheme scheme) => ChipThemeData(
     shape: RoundedRectangleBorder(borderRadius: BorderRadius.circular(8)),
     backgroundColor: scheme.surfaceContainerLow,

lib/theme/dynamic_color_wrapper.dart

@@ -4,7 +4,6 @@ import 'package:dynamic_color/dynamic_color.dart';
 import 'package:spotiflac_android/providers/theme_provider.dart';
 import 'package:spotiflac_android/theme/app_theme.dart';
 
-/// Wrapper widget that provides dynamic color support from device wallpaper
 class DynamicColorWrapper extends ConsumerWidget {
   final Widget Function(ThemeData light, ThemeData dark, ThemeMode mode) builder;
 
@@ -23,7 +22,6 @@ class DynamicColorWrapper extends ConsumerWidget {
         ColorScheme darkScheme;
 
         if (themeSettings.useDynamicColor && lightDynamic != null && darkDynamic != null) {
-          // Use dynamic colors from wallpaper (Android 12+)
           lightScheme = lightDynamic;
           darkScheme = darkDynamic;
         } else {
@@ -38,7 +36,6 @@ class DynamicColorWrapper extends ConsumerWidget {
           );
         }
 
-        // Apply AMOLED mode if enabled (pure black background)
         if (themeSettings.useAmoled) {
           darkScheme = _applyAmoledColors(darkScheme);
         }

lib/utils/local_library_scan_prefs.dart

@@ -0,0 +1,29 @@
+import 'package:shared_preferences/shared_preferences.dart';
+
+const localLibraryLastScannedAtKey = 'local_library_last_scanned_at';
+
+DateTime? readLocalLibraryLastScannedAt(SharedPreferences prefs) {
+  final lastScannedAtStr = prefs.getString(localLibraryLastScannedAtKey);
+  if (lastScannedAtStr != null && lastScannedAtStr.isNotEmpty) {
+    return DateTime.tryParse(lastScannedAtStr);
+  }
+
+  // Backward compatibility for older builds that may have stored epoch millis.
+  final lastScannedAtMs = prefs.getInt(localLibraryLastScannedAtKey);
+  if (lastScannedAtMs != null) {
+    return DateTime.fromMillisecondsSinceEpoch(lastScannedAtMs);
+  }
+
+  return null;
+}
+
+Future<void> writeLocalLibraryLastScannedAt(
+  SharedPreferences prefs,
+  DateTime value,
+) {
+  return prefs.setString(localLibraryLastScannedAtKey, value.toIso8601String());
+}
+
+Future<void> clearLocalLibraryLastScannedAt(SharedPreferences prefs) {
+  return prefs.remove(localLibraryLastScannedAtKey);
+}

lib/widgets/download_service_picker.dart

@@ -22,7 +22,6 @@ class BuiltInService {
   });
 }
 
-/// Default quality options for built-in services
 /// Default quality options for each built-in service
 const _builtInServices = [
   BuiltInService(
@@ -98,7 +97,6 @@ const _builtInServices = [
   ),
 ];
 
-/// A reusable widget for selecting download service (built-in + extensions)
 class DownloadServicePicker extends ConsumerStatefulWidget {
   final String? trackName;
   final String? artistName;

pubspec.yaml

@@ -1,7 +1,7 @@
 name: spotiflac_android
 description: Download Spotify tracks in FLAC from Tidal, Qobuz & Deezer
 publish_to: "none"
-version: 3.8.6+112
+version: 3.8.8+114
 
 environment:
   sdk: ^3.10.0