fix: patch device_info_plus iOS build for older Xcode SDKs

- Embed DownloadQueueLookup into DownloadQueueState; add updatedForIndices() for O(changed) incremental updates during frequent progress ticks instead of full O(n) rebuild
- downloadQueueLookupProvider now reads pre-computed lookup from state directly
- Replace sync file deletion in DownloadedEmbeddedCoverResolver with unawaited async cleanup to avoid blocking the main thread
- Parse JSON payloads on iOS native side (parseJsonPayload) so event sinks and method channel responses return native objects, avoiding redundant Dart-side JSON decode
- Use .cast<String, dynamic>() instead of Map.from() in _decodeMapResult for zero-copy map handling

.fvmrc

@@ -1,3 +1,3 @@
 {
-  "flutter": "3.41.4"
+  "flutter": "3.41.5"
 }

.github/ISSUE_TEMPLATE/config.yml

@@ -4,5 +4,5 @@ contact_links:
     url: https://github.com/zarzet/SpotiFLAC-Mobile#readme
     about: Check the README for setup instructions and FAQ
   - name: Extension Development Guide
-    url: https://zarz.moe/docs
+    url: https://spotiflac.zarz.moe/docs
     about: Documentation for building SpotiFLAC extensions

.github/workflows/release.yml

@@ -71,7 +71,7 @@ jobs:
       - name: Setup Go
         uses: actions/setup-go@v6
         with:
-          go-version: "1.25.7"
+          go-version: "1.25.8"
           cache-dependency-path: go_backend/go.sum
 
       # Cache Gradle for faster builds
@@ -93,12 +93,12 @@ jobs:
           # Accept licenses
           yes | $ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager --licenses || true
 
-          # Install NDK r27d LTS (required for 16KB page size support on Android 15+)
+          # Install NDK r29 (supports 16KB page size for Android 15+)
           # Platform android-36 and build-tools 36.0.0 for targetSdk 36 (Android 16)
-          $ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager "ndk;27.3.13750724" "platforms;android-36" "build-tools;36.0.0"
+          $ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager "ndk;29.0.14206865" "platforms;android-36" "build-tools;36.0.0"
 
           # Set NDK path
-          echo "ANDROID_NDK_HOME=$ANDROID_HOME/ndk/27.3.13750724" >> $GITHUB_ENV
+          echo "ANDROID_NDK_HOME=$ANDROID_HOME/ndk/29.0.14206865" >> $GITHUB_ENV
 
       - name: Install gomobile
         run: |
@@ -174,7 +174,7 @@ jobs:
       - name: Setup Go
         uses: actions/setup-go@v6
         with:
-          go-version: "1.25.7"
+          go-version: "1.25.8"
           cache-dependency-path: go_backend/go.sum
 
       # Cache CocoaPods

.gitignore

@@ -77,6 +77,7 @@ flutter_*.log
 # Development tools
 tool/
 .claude/settings.local.json
+.playwright-mcp/
 
 # FVM Version Cache
 .fvm/

README.md

@@ -170,5 +170,18 @@ Interested in contributing? Check out the [Contributing Guide](CONTRIBUTING.md)
 | [dabmusic.xyz](https://dabmusic.xyz) | [AfkarXYZ](https://github.com/afkarxyz) | [LRCLib](https://lrclib.net) | [Paxsenix](https://lyrics.paxsenix.org) | [Cobalt](https://cobalt.tools) |
 | [qwkuns.me](https://qwkuns.me) | [SpotubeDL](https://spotubedl.com) | [Song.link](https://song.link) | [IDHS](https://github.com/sjdonado/idonthavespotify) | |
 
+---
+
+## Disclaimer
+
+This repository and its contents are provided strictly for educational and research purposes. The software is provided "as-is" without warranty of any kind, express or implied, as stated in the [MIT License](LICENSE).
+
+- No copyrighted content is hosted, stored, mirrored, or distributed by this repository.
+- Users must ensure that their use of this software is properly authorized and complies with all applicable laws, regulations, and third-party terms of service.
+- This software is provided free of charge by the maintainer. If you paid a third party for access to this software in its original form from this repository, you may have been misled or scammed. Any redistribution or commercial use by third parties must comply with the terms of the repository license. No affiliation, endorsement, or support by the maintainer is implied unless explicitly stated in writing.
+- SpotiFLAC Mobile is an independent project. It is not affiliated with, endorsed by, or connected to any other project or version on other platforms that may share a similar name. The maintainer of this repository has no control over or responsibility for third-party projects.
+- The author(s) disclaim all liability for any direct, indirect, incidental, or consequential damages arising from the use or misuse of this software. Users assume all risk associated with its use.
+- If you are a copyright holder or authorized representative and believe this repository infringes upon your rights, please contact the maintainer with sufficient detail (including relevant URLs and proof of ownership). The matter will be promptly investigated and appropriate action will be taken, which may include removal of the referenced material.
+
 > [!TIP]
 > **Star the repo** to get notified about all new releases directly from GitHub.

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

@@ -40,7 +40,8 @@ class MainActivity: FlutterFragmentActivity() {
         "com.zarz.spotiflac/download_progress_stream"
     private val LIBRARY_SCAN_PROGRESS_STREAM_CHANNEL =
         "com.zarz.spotiflac/library_scan_progress_stream"
-    private val STREAM_POLLING_INTERVAL_MS = 1200L
+    private val DOWNLOAD_PROGRESS_STREAM_POLLING_INTERVAL_MS = 1200L
+    private val LIBRARY_SCAN_PROGRESS_STREAM_POLLING_INTERVAL_MS = 200L
     private val scope = CoroutineScope(SupervisorJob() + Dispatchers.Main)
     private var pendingSafTreeResult: MethodChannel.Result? = null
     private val safScanLock = Any()
@@ -55,6 +56,8 @@ class MainActivity: FlutterFragmentActivity() {
     private var flutterBackCallback: OnBackPressedCallback? = null
     @Volatile private var safScanCancel = false
     @Volatile private var safScanActive = false
+    /** Tri-state: null = untested, true = works, false = fails (Samsung SELinux). */
+    @Volatile private var procSelfFdReadable: Boolean? = null
     private val safTreeLauncher = registerForActivityResult(
         ActivityResultContracts.StartActivityForResult()
     ) { activityResult ->
@@ -160,10 +163,6 @@ class MainActivity: FlutterFragmentActivity() {
             "sm-t225",
             "hammerhead",
         )
-        /**
-         * Check if device should use Skia instead of Impeller.
-         * Returns true for devices with old/problematic GPUs or old Android versions.
-         */
         private fun shouldDisableImpeller(): Boolean {
             val hardware = Build.HARDWARE.lowercase(Locale.ROOT)
             val board = Build.BOARD.lowercase(Locale.ROOT)
@@ -212,7 +211,6 @@ class MainActivity: FlutterFragmentActivity() {
         }
 
     /**
-     * Try to get GPU renderer string.
      * Note: This may return empty on some devices before OpenGL context is created.
      */
         private fun getGpuRenderer(): String {
@@ -374,6 +372,8 @@ class MainActivity: FlutterFragmentActivity() {
         synchronized(safScanLock) {
             safScanProgress = SafScanProgress()
         }
+        // Allow re-probing /proc/self/fd readability on every new scan session.
+        procSelfFdReadable = null
     }
 
     private fun updateSafScanProgress(block: (SafScanProgress) -> Unit) {
@@ -454,7 +454,7 @@ class MainActivity: FlutterFragmentActivity() {
                         "Download progress stream poll failed: ${e.message}",
                     )
                 }
-                delay(STREAM_POLLING_INTERVAL_MS)
+                delay(DOWNLOAD_PROGRESS_STREAM_POLLING_INTERVAL_MS)
             }
         }
     }
@@ -471,6 +471,18 @@ class MainActivity: FlutterFragmentActivity() {
         libraryScanProgressEventSink = sink
         lastLibraryScanProgressPayload = null
         libraryScanProgressStreamJob = scope.launch {
+            try {
+                val initialPayload = withContext(Dispatchers.IO) {
+                    readLibraryScanProgressJsonForStream()
+                }
+                lastLibraryScanProgressPayload = initialPayload
+                sink.success(parseJsonPayload(initialPayload))
+            } catch (e: Exception) {
+                android.util.Log.w(
+                    "SpotiFLAC",
+                    "Library scan progress initial poll failed: ${e.message}",
+                )
+            }
             while (isActive && libraryScanProgressEventSink === sink) {
                 try {
                     val payload = withContext(Dispatchers.IO) {
@@ -486,7 +498,7 @@ class MainActivity: FlutterFragmentActivity() {
                         "Library scan progress stream poll failed: ${e.message}",
                     )
                 }
-                delay(STREAM_POLLING_INTERVAL_MS)
+                delay(LIBRARY_SCAN_PROGRESS_STREAM_POLLING_INTERVAL_MS)
             }
         }
     }
@@ -777,29 +789,59 @@ class MainActivity: FlutterFragmentActivity() {
         return if (ext.isNullOrBlank()) "audio" else "audio$ext"
     }
 
+    private fun buildLibraryCoverCacheKey(stablePath: String, lastModified: Long): String {
+        val normalizedPath = stablePath.trim()
+        if (normalizedPath.isEmpty()) return ""
+        return if (lastModified > 0L) "$normalizedPath|$lastModified" else normalizedPath
+    }
+
     private fun readAudioMetadataFromUri(
         uri: Uri,
         displayNameHint: String? = null,
         fallbackExt: String? = null,
+        coverCacheKey: String = "",
     ): JSONObject? {
         val displayName = buildUriDisplayName(uri, displayNameHint, fallbackExt)
 
-        try {
-            contentResolver.openFileDescriptor(uri, "r")?.use { pfd ->
-                val directPath = "/proc/self/fd/${pfd.fd}"
-                val metadataJson = Gobackend.readAudioMetadataWithHintJSON(directPath, displayName)
-                if (metadataJson.isNotBlank()) {
-                    val obj = JSONObject(metadataJson)
-                    if (!obj.has("error")) {
-                        return obj
+        // Skip /proc/self/fd/ attempt when known to fail (e.g. Samsung SELinux).
+        if (procSelfFdReadable != false) {
+            try {
+                contentResolver.openFileDescriptor(uri, "r")?.use { pfd ->
+                    val directPath = "/proc/self/fd/${pfd.fd}"
+                    val metadataJson = Gobackend.readAudioMetadataWithHintAndCoverCacheKeyJSON(
+                        directPath,
+                        displayName,
+                        coverCacheKey,
+                    )
+                    if (metadataJson.isNotBlank()) {
+                        val obj = JSONObject(metadataJson)
+                        val filenameFallback = obj.optBoolean("metadataFromFilename", false)
+                        if (!obj.has("error") && !filenameFallback) {
+                            procSelfFdReadable = true
+                            return obj
+                        }
+                        // Go could not read real metadata from the fd path –
+                        // remember so we skip the attempt for remaining files.
+                        if (procSelfFdReadable == null) {
+                            procSelfFdReadable = false
+                            android.util.Log.d(
+                                "SpotiFLAC",
+                                "Direct /proc/self/fd read not usable on this device, " +
+                                    "using temp-file fallback for remaining files",
+                            )
+                        }
                     }
                 }
+            } catch (e: Exception) {
+                if (procSelfFdReadable == null) {
+                    procSelfFdReadable = false
+                    android.util.Log.d(
+                        "SpotiFLAC",
+                        "Direct /proc/self/fd read not usable on this device, " +
+                            "using temp-file fallback for remaining files",
+                    )
+                }
             }
-        } catch (e: Exception) {
-            android.util.Log.d(
-                "SpotiFLAC",
-                "Direct SAF metadata read fallback for $uri: ${e.message}",
-            )
         }
 
         val tempPath = try {
@@ -813,7 +855,11 @@ class MainActivity: FlutterFragmentActivity() {
         } ?: return null
 
         try {
-            val metadataJson = Gobackend.readAudioMetadataWithHintJSON(tempPath, displayName)
+            val metadataJson = Gobackend.readAudioMetadataWithHintAndCoverCacheKeyJSON(
+                tempPath,
+                displayName,
+                coverCacheKey,
+            )
             if (metadataJson.isBlank()) return null
             val obj = JSONObject(metadataJson)
             return if (obj.has("error")) null else obj
@@ -1190,6 +1236,11 @@ class MainActivity: FlutterFragmentActivity() {
                 val audioName = try { audioDoc.name ?: "audio.flac" } catch (_: Exception) { "audio.flac" }
                 val audioExt = audioName.substringAfterLast('.', "").lowercase(Locale.ROOT)
                 val fallbackAudioExt = if (audioExt.isNotBlank()) ".$audioExt" else null
+                val audioLastModified = try { audioDoc.lastModified() } catch (_: Exception) { cueDoc.lastModified() }
+                val coverCacheKey = buildLibraryCoverCacheKey(
+                    audioDoc.uri.toString(),
+                    audioLastModified,
+                )
 
                 tempAudioPath = copyUriToTemp(audioDoc.uri, fallbackAudioExt)
                 if (tempAudioPath == null) {
@@ -1208,11 +1259,12 @@ class MainActivity: FlutterFragmentActivity() {
 
                 val cueLastModified = try { cueDoc.lastModified() } catch (_: Exception) { 0L }
 
-                val cueResultsJson = Gobackend.scanCueSheetForLibrary(
+                val cueResultsJson = Gobackend.scanCueSheetForLibraryWithCoverCacheKey(
                     tempCuePath,
                     tempDir,
                     cueDoc.uri.toString(),
-                    cueLastModified
+                    cueLastModified,
+                    coverCacheKey,
                 )
 
                 val cueArray = JSONArray(cueResultsJson)
@@ -1264,13 +1316,19 @@ class MainActivity: FlutterFragmentActivity() {
 
             val ext = name.substringAfterLast('.', "").lowercase(Locale.ROOT)
             val fallbackExt = if (ext.isNotBlank()) ".${ext}" else null
-            val metadataObj = readAudioMetadataFromUri(doc.uri, name, fallbackExt)
+            val lastModified = try { doc.lastModified() } catch (_: Exception) { 0L }
+            val stableUri = doc.uri.toString()
+            val coverCacheKey = buildLibraryCoverCacheKey(stableUri, lastModified)
+            val metadataObj = readAudioMetadataFromUri(
+                doc.uri,
+                name,
+                fallbackExt,
+                coverCacheKey,
+            )
             if (metadataObj == null) {
                 errors++
             } else {
                 try {
-                    val lastModified = try { doc.lastModified() } catch (_: Exception) { 0L }
-                    val stableUri = doc.uri.toString()
                     metadataObj.put("id", buildStableLibraryId(stableUri))
                     metadataObj.put("filePath", stableUri)
                     metadataObj.put("fileModTime", lastModified)
@@ -1538,6 +1596,11 @@ class MainActivity: FlutterFragmentActivity() {
                 val audioName = try { audioDoc.name ?: "audio.flac" } catch (_: Exception) { "audio.flac" }
                 val audioExt = audioName.substringAfterLast('.', "").lowercase(Locale.ROOT)
                 val fallbackAudioExt = if (audioExt.isNotBlank()) ".$audioExt" else null
+                val audioLastModified = try { audioDoc.lastModified() } catch (_: Exception) { cueLastModified }
+                val coverCacheKey = buildLibraryCoverCacheKey(
+                    audioDoc.uri.toString(),
+                    audioLastModified,
+                )
 
                 tempAudioPath = copyUriToTemp(audioDoc.uri, fallbackAudioExt)
                 if (tempAudioPath == null) {
@@ -1554,11 +1617,12 @@ class MainActivity: FlutterFragmentActivity() {
                     tempAudioPath = renamedAudio.absolutePath
                 }
 
-                val cueResultsJson = Gobackend.scanCueSheetForLibrary(
+                val cueResultsJson = Gobackend.scanCueSheetForLibraryWithCoverCacheKey(
                     tempCuePath,
                     tempDir,
                     cueDoc.uri.toString(),
-                    cueLastModified
+                    cueLastModified,
+                    coverCacheKey,
                 )
 
                 val cueArray = JSONArray(cueResultsJson)
@@ -1655,13 +1719,19 @@ class MainActivity: FlutterFragmentActivity() {
 
             val ext = name.substringAfterLast('.', "").lowercase(Locale.ROOT)
             val fallbackExt = if (ext.isNotBlank()) ".${ext}" else null
-            val metadataObj = readAudioMetadataFromUri(doc.uri, name, fallbackExt)
+            val safeLastModified = try { doc.lastModified() } catch (_: Exception) { lastModified }
+            val stableUri = doc.uri.toString()
+            val coverCacheKey = buildLibraryCoverCacheKey(stableUri, safeLastModified)
+            val metadataObj = readAudioMetadataFromUri(
+                doc.uri,
+                name,
+                fallbackExt,
+                coverCacheKey,
+            )
             if (metadataObj == null) {
                 errors++
             } else {
                 try {
-                    val safeLastModified = try { doc.lastModified() } catch (_: Exception) { lastModified }
-                    val stableUri = doc.uri.toString()
                     metadataObj.put("id", buildStableLibraryId(stableUri))
                     metadataObj.put("filePath", stableUri)
                     metadataObj.put("fileModTime", safeLastModified)
@@ -2309,6 +2379,41 @@ class MainActivity: FlutterFragmentActivity() {
                             }
                             result.success(response)
                         }
+                        "rewriteSplitArtistTags" -> {
+                            val filePath = call.argument<String>("file_path") ?: ""
+                            val artist = call.argument<String>("artist") ?: ""
+                            val albumArtist = call.argument<String>("album_artist") ?: ""
+                            val response = withContext(Dispatchers.IO) {
+                                if (filePath.startsWith("content://")) {
+                                    val uri = Uri.parse(filePath)
+                                    val tempPath = copyUriToTemp(uri, ".flac")
+                                        ?: return@withContext errorJson("Failed to copy SAF file to temp")
+                                    try {
+                                        val raw = Gobackend.rewriteSplitArtistTagsExport(tempPath, artist, albumArtist)
+                                        val obj = JSONObject(raw)
+                                        if (!obj.optBoolean("success", false)) {
+                                            return@withContext raw
+                                        }
+
+                                        if (!writeUriFromPath(uri, tempPath)) {
+                                            return@withContext errorJson("Failed to write rewritten tags back to SAF file")
+                                        }
+
+                                        obj.put("file_path", filePath)
+                                        obj.toString()
+                                    } catch (e: Exception) {
+                                        errorJson("Failed to rewrite split artist tags in SAF file: ${e.message}")
+                                    } finally {
+                                        try {
+                                            File(tempPath).delete()
+                                        } catch (_: Exception) {}
+                                    }
+                                } else {
+                                    Gobackend.rewriteSplitArtistTagsExport(filePath, artist, albumArtist)
+                                }
+                            }
+                            result.success(response)
+                        }
                         "cleanupConnections" -> {
                             withContext(Dispatchers.IO) {
                                 Gobackend.cleanupConnections()
@@ -2358,11 +2463,13 @@ class MainActivity: FlutterFragmentActivity() {
                                                 return@withContext obj.toString()
                                                 // Note: temp file NOT deleted here - Dart will clean up after FFmpeg + writeTempToSaf
                                             }
-                                            // FLAC: Go wrote directly to temp, copy back now
-                                            if (!writeUriFromPath(uri, tempPath)) {
-                                                return@withContext """{"error":"Failed to write metadata back to SAF file"}"""
-                                            }
-                                            raw
+                            // FLAC: Go wrote directly to temp, copy back now
+                            if (!writeUriFromPath(uri, tempPath)) {
+                                try { File(tempPath).delete() } catch (_: Exception) {}
+                                return@withContext """{"error":"Failed to write metadata back to SAF file"}"""
+                            }
+                            try { File(tempPath).delete() } catch (_: Exception) {}
+                            raw
                                         } catch (e: Exception) {
                                             try { File(tempPath).delete() } catch (_: Exception) {}
                                             throw e
@@ -2439,12 +2546,27 @@ class MainActivity: FlutterFragmentActivity() {
                             val spotifyId = call.argument<String>("spotify_id") ?: ""
                             val durationMs = call.argument<Number>("duration_ms")?.toLong() ?: 0L
                             val outputPath = call.argument<String>("output_path") ?: ""
+                            val rawAudioFilePath = call.argument<String>("audio_file_path") ?: ""
                             val response = withContext(Dispatchers.IO) {
+                                var safAudioTemp: String? = null
                                 try {
-                                    Gobackend.fetchAndSaveLyrics(trackName, artistName, spotifyId, durationMs, outputPath)
+                                    // Resolve SAF content:// URI to a temp file the Go backend can read
+                                    val audioFilePath = if (rawAudioFilePath.startsWith("content://")) {
+                                        val uri = Uri.parse(rawAudioFilePath)
+                                        val tempPath = copyUriToTemp(uri)
+                                        safAudioTemp = tempPath
+                                        tempPath ?: ""
+                                    } else {
+                                        rawAudioFilePath
+                                    }
+                                    Gobackend.fetchAndSaveLyrics(trackName, artistName, spotifyId, durationMs, outputPath, audioFilePath)
                                     """{"success":true}"""
                                 } catch (e: Exception) {
                                     """{"success":false,"error":"${e.message?.replace("\"", "'")}"}"""
+                                } finally {
+                                    if (safAudioTemp != null) {
+                                        try { File(safAudioTemp).delete() } catch (_: Exception) {}
+                                    }
                                 }
                             }
                             result.success(response)

android/gradle/wrapper/gradle-wrapper.properties

@@ -2,4 +2,4 @@ distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-9.3.1-all.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-9.4.1-all.zip

android/settings.gradle.kts

@@ -20,7 +20,7 @@ pluginManagement {
 plugins {
     id("dev.flutter.flutter-plugin-loader") version "1.0.0"
     id("com.android.application") version "8.13.2" apply false
-    id("org.jetbrains.kotlin.android") version "2.2.21" apply false
+    id("org.jetbrains.kotlin.android") version "2.3.20" apply false
 }
 
 include(":app")

go_backend/ape_tags.go

@@ -0,0 +1,609 @@
+package gobackend
+
+import (
+	"encoding/binary"
+	"fmt"
+	"io"
+	"os"
+	"strconv"
+	"strings"
+)
+
+// APEv2 tag format constants.
+const (
+	apeTagPreamble     = "APETAGEX"
+	apeTagHeaderSize   = 32
+	apeTagVersion2     = 2000
+	apeTagFlagHeader   = 1 << 29 // bit 29: this is the header, not the footer
+	apeTagFlagReadOnly = 1 << 0
+	// Item flags: bits 1-2 encode content type
+	apeItemFlagUTF8   = 0 << 1 // 00: UTF-8 text
+	apeItemFlagBinary = 1 << 1 // 01: binary data
+	apeItemFlagLink   = 2 << 1 // 10: external link
+)
+
+// APETagItem represents a single key-value item in an APEv2 tag.
+type APETagItem struct {
+	Key   string
+	Value string
+	Flags uint32
+}
+
+// APETag represents a complete APEv2 tag block.
+type APETag struct {
+	Version  uint32
+	Items    []APETagItem
+	ReadOnly bool
+}
+
+// ReadAPETags reads APEv2 tags from a file.
+// APEv2 tags are typically appended at the end of the file.
+// The layout is: [audio data] [APEv2 header (optional)] [items...] [APEv2 footer]
+// We locate the footer first (last 32 bytes), then read the tag block.
+func ReadAPETags(filePath string) (*APETag, error) {
+	f, err := os.Open(filePath)
+	if err != nil {
+		return nil, fmt.Errorf("failed to open file: %w", err)
+	}
+	defer f.Close()
+
+	fi, err := f.Stat()
+	if err != nil {
+		return nil, fmt.Errorf("failed to stat file: %w", err)
+	}
+	fileSize := fi.Size()
+
+	if fileSize < apeTagHeaderSize {
+		return nil, fmt.Errorf("file too small for APE tag")
+	}
+
+	// Try to find APE tag footer at the end of file.
+	// The footer is the last 32 bytes before any ID3v1 tag (128 bytes).
+	tag, err := readAPETagAtOffset(f, fileSize, fileSize-apeTagHeaderSize)
+	if err == nil {
+		return tag, nil
+	}
+
+	// Retry: skip ID3v1 tag (128 bytes) if present
+	if fileSize > apeTagHeaderSize+128 {
+		tag, err = readAPETagAtOffset(f, fileSize, fileSize-apeTagHeaderSize-128)
+		if err == nil {
+			return tag, nil
+		}
+	}
+
+	return nil, fmt.Errorf("no APEv2 tag found")
+}
+
+func readAPETagAtOffset(f *os.File, fileSize, footerOffset int64) (*APETag, error) {
+	if footerOffset < 0 || footerOffset+apeTagHeaderSize > fileSize {
+		return nil, fmt.Errorf("invalid footer offset")
+	}
+
+	footer := make([]byte, apeTagHeaderSize)
+	if _, err := f.ReadAt(footer, footerOffset); err != nil {
+		return nil, fmt.Errorf("failed to read APE footer: %w", err)
+	}
+
+	if string(footer[0:8]) != apeTagPreamble {
+		return nil, fmt.Errorf("APE preamble not found")
+	}
+
+	version := binary.LittleEndian.Uint32(footer[8:12])
+	tagSize := binary.LittleEndian.Uint32(footer[12:16]) // size of items + footer (32 bytes)
+	itemCount := binary.LittleEndian.Uint32(footer[16:20])
+	flags := binary.LittleEndian.Uint32(footer[20:24])
+
+	if version != apeTagVersion2 && version != 1000 {
+		return nil, fmt.Errorf("unsupported APE tag version: %d", version)
+	}
+	if tagSize < apeTagHeaderSize {
+		return nil, fmt.Errorf("APE tag size too small: %d", tagSize)
+	}
+	if itemCount > 1000 {
+		return nil, fmt.Errorf("APE tag item count too large: %d", itemCount)
+	}
+
+	// This should be the footer (bit 29 clear)
+	isHeader := (flags & apeTagFlagHeader) != 0
+	if isHeader {
+		return nil, fmt.Errorf("expected APE footer but found header")
+	}
+
+	// tagSize includes items + footer (32 bytes), but NOT the header.
+	itemsSize := int64(tagSize) - apeTagHeaderSize
+	if itemsSize < 0 {
+		return nil, fmt.Errorf("invalid APE tag: items size negative")
+	}
+
+	itemsOffset := footerOffset - itemsSize
+	if itemsOffset < 0 {
+		return nil, fmt.Errorf("APE tag items extend before file start")
+	}
+
+	itemsData := make([]byte, itemsSize)
+	if _, err := f.ReadAt(itemsData, itemsOffset); err != nil {
+		return nil, fmt.Errorf("failed to read APE items: %w", err)
+	}
+
+	items, err := parseAPEItems(itemsData, int(itemCount))
+	if err != nil {
+		return nil, fmt.Errorf("failed to parse APE items: %w", err)
+	}
+
+	return &APETag{
+		Version:  version,
+		Items:    items,
+		ReadOnly: (flags & apeTagFlagReadOnly) != 0,
+	}, nil
+}
+
+func parseAPEItems(data []byte, count int) ([]APETagItem, error) {
+	items := make([]APETagItem, 0, count)
+	pos := 0
+
+	for i := 0; i < count && pos < len(data); i++ {
+		if pos+8 > len(data) {
+			break
+		}
+
+		valueSize := int(binary.LittleEndian.Uint32(data[pos : pos+4]))
+		itemFlags := binary.LittleEndian.Uint32(data[pos+4 : pos+8])
+		pos += 8
+
+		// Key is null-terminated ASCII (2-255 bytes, case-insensitive)
+		keyEnd := pos
+		for keyEnd < len(data) && data[keyEnd] != 0 {
+			keyEnd++
+		}
+		if keyEnd >= len(data) {
+			break
+		}
+
+		key := string(data[pos:keyEnd])
+		pos = keyEnd + 1
+
+		if pos+valueSize > len(data) {
+			break
+		}
+		value := string(data[pos : pos+valueSize])
+		pos += valueSize
+
+		items = append(items, APETagItem{
+			Key:   key,
+			Value: value,
+			Flags: itemFlags,
+		})
+	}
+
+	return items, nil
+}
+
+// WriteAPETags writes APEv2 tags to the end of a file.
+// If the file already has APEv2 tags, they are replaced.
+// The tag is written with both header and footer.
+func WriteAPETags(filePath string, tag *APETag) error {
+	existingSize, err := findExistingAPETagSize(filePath)
+	if err != nil {
+		return fmt.Errorf("failed to check existing APE tag: %w", err)
+	}
+
+	tagData, err := marshalAPETag(tag)
+	if err != nil {
+		return fmt.Errorf("failed to marshal APE tag: %w", err)
+	}
+
+	if existingSize > 0 {
+		fi, err := os.Stat(filePath)
+		if err != nil {
+			return fmt.Errorf("failed to stat file: %w", err)
+		}
+		newSize := fi.Size() - int64(existingSize)
+		if err := os.Truncate(filePath, newSize); err != nil {
+			return fmt.Errorf("failed to truncate existing APE tag: %w", err)
+		}
+	}
+
+	f, err := os.OpenFile(filePath, os.O_WRONLY|os.O_APPEND, 0644)
+	if err != nil {
+		return fmt.Errorf("failed to open file for writing: %w", err)
+	}
+	defer f.Close()
+
+	if _, err := f.Write(tagData); err != nil {
+		return fmt.Errorf("failed to write APE tag: %w", err)
+	}
+
+	return nil
+}
+
+// findExistingAPETagSize returns the total size of an existing APE tag
+// (header + items + footer) at the end of the file, or 0 if none exists.
+func findExistingAPETagSize(filePath string) (int64, error) {
+	f, err := os.Open(filePath)
+	if err != nil {
+		return 0, err
+	}
+	defer f.Close()
+
+	fi, err := f.Stat()
+	if err != nil {
+		return 0, err
+	}
+	fileSize := fi.Size()
+
+	offsets := []int64{fileSize - apeTagHeaderSize}
+	if fileSize > apeTagHeaderSize+128 {
+		offsets = append(offsets, fileSize-apeTagHeaderSize-128)
+	}
+
+	for _, offset := range offsets {
+		if offset < 0 {
+			continue
+		}
+		footer := make([]byte, apeTagHeaderSize)
+		if _, err := f.ReadAt(footer, offset); err != nil {
+			continue
+		}
+		if string(footer[0:8]) != apeTagPreamble {
+			continue
+		}
+
+		flags := binary.LittleEndian.Uint32(footer[20:24])
+		if (flags & apeTagFlagHeader) != 0 {
+			continue
+		}
+
+		tagSize := int64(binary.LittleEndian.Uint32(footer[12:16]))
+
+		// Check if there's also a header (tagSize only covers items + footer)
+		hasHeader := (flags & (1 << 31)) != 0 // bit 31 = tag contains header
+		totalSize := tagSize
+		if hasHeader {
+			totalSize += apeTagHeaderSize
+		}
+
+		// Include any trailing data after the footer (e.g. ID3v1 128-byte tag).
+		// When truncating, we must remove the APE tag AND everything after it.
+		trailingBytes := fileSize - (offset + apeTagHeaderSize)
+		totalSize += trailingBytes
+
+		return totalSize, nil
+	}
+
+	return 0, nil
+}
+
+// marshalAPETag serializes an APETag into bytes (header + items + footer).
+func marshalAPETag(tag *APETag) ([]byte, error) {
+	if tag == nil || len(tag.Items) == 0 {
+		return nil, fmt.Errorf("empty APE tag")
+	}
+
+	var itemsData []byte
+	for _, item := range tag.Items {
+		keyBytes := []byte(item.Key)
+		valueBytes := []byte(item.Value)
+
+		// 4 bytes: value size (LE)
+		sizeBuf := make([]byte, 4)
+		binary.LittleEndian.PutUint32(sizeBuf, uint32(len(valueBytes)))
+
+		// 4 bytes: item flags (LE)
+		flagsBuf := make([]byte, 4)
+		binary.LittleEndian.PutUint32(flagsBuf, item.Flags)
+
+		itemsData = append(itemsData, sizeBuf...)
+		itemsData = append(itemsData, flagsBuf...)
+		itemsData = append(itemsData, keyBytes...)
+		itemsData = append(itemsData, 0)
+		itemsData = append(itemsData, valueBytes...)
+	}
+
+	// tagSize = items data + footer (32 bytes)
+	tagSize := uint32(len(itemsData) + apeTagHeaderSize)
+	itemCount := uint32(len(tag.Items))
+
+	version := uint32(apeTagVersion2)
+	if tag.Version != 0 {
+		version = tag.Version
+	}
+
+	// flags: bit 29 = 1 (is header), bit 31 = 1 (contains header)
+	headerFlags := uint32(apeTagFlagHeader | (1 << 31))
+	header := buildAPEHeaderFooter(version, tagSize, itemCount, headerFlags)
+
+	// flags: bit 29 = 0 (is footer), bit 31 = 1 (contains header)
+	footerFlags := uint32(1 << 31)
+	footer := buildAPEHeaderFooter(version, tagSize, itemCount, footerFlags)
+
+	// Final layout: header + items + footer
+	result := make([]byte, 0, len(header)+len(itemsData)+len(footer))
+	result = append(result, header...)
+	result = append(result, itemsData...)
+	result = append(result, footer...)
+
+	return result, nil
+}
+
+func buildAPEHeaderFooter(version, tagSize, itemCount, flags uint32) []byte {
+	buf := make([]byte, apeTagHeaderSize)
+	copy(buf[0:8], apeTagPreamble)
+	binary.LittleEndian.PutUint32(buf[8:12], version)
+	binary.LittleEndian.PutUint32(buf[12:16], tagSize)
+	binary.LittleEndian.PutUint32(buf[16:20], itemCount)
+	binary.LittleEndian.PutUint32(buf[20:24], flags)
+	// bytes 24-31 are reserved (zeros)
+	return buf
+}
+
+// APETagToAudioMetadata converts an APETag to our unified AudioMetadata struct.
+func APETagToAudioMetadata(tag *APETag) *AudioMetadata {
+	if tag == nil {
+		return nil
+	}
+
+	metadata := &AudioMetadata{}
+	for _, item := range tag.Items {
+		key := strings.ToUpper(strings.TrimSpace(item.Key))
+		value := strings.TrimSpace(item.Value)
+		if value == "" {
+			continue
+		}
+
+		switch key {
+		case "TITLE":
+			metadata.Title = value
+		case "ARTIST":
+			metadata.Artist = value
+		case "ALBUM":
+			metadata.Album = value
+		case "ALBUMARTIST", "ALBUM ARTIST":
+			metadata.AlbumArtist = value
+		case "GENRE":
+			metadata.Genre = value
+		case "YEAR":
+			metadata.Year = value
+		case "DATE":
+			metadata.Date = value
+		case "TRACK", "TRACKNUMBER":
+			// APE track format can be "3" or "3/12"
+			trackNum, _ := strconv.Atoi(strings.Split(value, "/")[0])
+			metadata.TrackNumber = trackNum
+		case "DISC", "DISCNUMBER":
+			discNum, _ := strconv.Atoi(strings.Split(value, "/")[0])
+			metadata.DiscNumber = discNum
+		case "ISRC":
+			metadata.ISRC = value
+		case "LYRICS", "UNSYNCEDLYRICS":
+			if metadata.Lyrics == "" {
+				metadata.Lyrics = value
+			}
+		case "LABEL", "PUBLISHER":
+			metadata.Label = value
+		case "COPYRIGHT":
+			metadata.Copyright = value
+		case "COMPOSER":
+			metadata.Composer = value
+		case "COMMENT":
+			metadata.Comment = value
+		case "REPLAYGAIN_TRACK_GAIN":
+			metadata.ReplayGainTrackGain = value
+		case "REPLAYGAIN_TRACK_PEAK":
+			metadata.ReplayGainTrackPeak = value
+		case "REPLAYGAIN_ALBUM_GAIN":
+			metadata.ReplayGainAlbumGain = value
+		case "REPLAYGAIN_ALBUM_PEAK":
+			metadata.ReplayGainAlbumPeak = value
+		}
+	}
+
+	return metadata
+}
+
+// AudioMetadataToAPEItems converts metadata fields to APE tag items.
+func AudioMetadataToAPEItems(metadata *AudioMetadata) []APETagItem {
+	if metadata == nil {
+		return nil
+	}
+
+	var items []APETagItem
+	addItem := func(key, value string) {
+		if value != "" {
+			items = append(items, APETagItem{Key: key, Value: value})
+		}
+	}
+
+	addItem("Title", metadata.Title)
+	addItem("Artist", metadata.Artist)
+	addItem("Album", metadata.Album)
+	addItem("Album Artist", metadata.AlbumArtist)
+	addItem("Genre", metadata.Genre)
+	if metadata.Date != "" {
+		addItem("Year", metadata.Date)
+	} else if metadata.Year != "" {
+		addItem("Year", metadata.Year)
+	}
+	if metadata.TrackNumber > 0 {
+		addItem("Track", strconv.Itoa(metadata.TrackNumber))
+	}
+	if metadata.DiscNumber > 0 {
+		addItem("Disc", strconv.Itoa(metadata.DiscNumber))
+	}
+	addItem("ISRC", metadata.ISRC)
+	addItem("Lyrics", metadata.Lyrics)
+	addItem("Label", metadata.Label)
+	addItem("Copyright", metadata.Copyright)
+	addItem("Composer", metadata.Composer)
+	addItem("Comment", metadata.Comment)
+	addItem("REPLAYGAIN_TRACK_GAIN", metadata.ReplayGainTrackGain)
+	addItem("REPLAYGAIN_TRACK_PEAK", metadata.ReplayGainTrackPeak)
+	addItem("REPLAYGAIN_ALBUM_GAIN", metadata.ReplayGainAlbumGain)
+	addItem("REPLAYGAIN_ALBUM_PEAK", metadata.ReplayGainAlbumPeak)
+
+	return items
+}
+
+// apeKeysFromFields builds a set of upper-case APE tag keys corresponding to
+// the metadata fields map sent by the editor.  This is used during merge to
+// ensure that even empty (cleared) fields override old values.
+func apeKeysFromFields(fields map[string]string) map[string]struct{} {
+	mapping := map[string]string{
+		"title":                 "TITLE",
+		"artist":                "ARTIST",
+		"album":                 "ALBUM",
+		"album_artist":          "ALBUM ARTIST",
+		"date":                  "YEAR",
+		"genre":                 "GENRE",
+		"track_number":          "TRACK",
+		"disc_number":           "DISC",
+		"isrc":                  "ISRC",
+		"lyrics":                "LYRICS",
+		"label":                 "LABEL",
+		"copyright":             "COPYRIGHT",
+		"composer":              "COMPOSER",
+		"comment":               "COMMENT",
+		"replaygain_track_gain": "REPLAYGAIN_TRACK_GAIN",
+		"replaygain_track_peak": "REPLAYGAIN_TRACK_PEAK",
+		"replaygain_album_gain": "REPLAYGAIN_ALBUM_GAIN",
+		"replaygain_album_peak": "REPLAYGAIN_ALBUM_PEAK",
+	}
+	result := make(map[string]struct{})
+	for fk, apeKey := range mapping {
+		if _, present := fields[fk]; present {
+			result[strings.ToUpper(apeKey)] = struct{}{}
+		}
+	}
+	// Some fields have reader aliases that must also be cleared when the
+	// canonical key is updated (e.g. "Year" writer ↔ DATE/YEAR reader,
+	// DISC ↔ DISCNUMBER, TRACK ↔ TRACKNUMBER, "ALBUM ARTIST" ↔ ALBUMARTIST,
+	// LABEL ↔ PUBLISHER, LYRICS ↔ UNSYNCEDLYRICS).
+	if _, present := fields["date"]; present {
+		result["DATE"] = struct{}{}
+	}
+	if _, present := fields["disc_number"]; present {
+		result["DISCNUMBER"] = struct{}{}
+	}
+	if _, present := fields["track_number"]; present {
+		result["TRACKNUMBER"] = struct{}{}
+	}
+	if _, present := fields["album_artist"]; present {
+		result["ALBUMARTIST"] = struct{}{}
+	}
+	if _, present := fields["label"]; present {
+		result["PUBLISHER"] = struct{}{}
+	}
+	if _, present := fields["lyrics"]; present {
+		result["UNSYNCEDLYRICS"] = struct{}{}
+	}
+	return result
+}
+
+// MergeAPEItems overlays newItems on top of existing items.
+// For each new item, if a matching key exists (case-insensitive) in existing,
+// it is replaced. New keys are appended. Existing items whose keys are NOT
+// in newItems are preserved (cover art, ReplayGain, custom tags, etc.).
+//
+// overrideKeys is an optional set of upper-case keys that should be removed
+// from existing even if they do not appear in newItems.  This handles field
+// deletion: the caller sends an empty value which is not serialized into
+// newItems, but the old value must still be dropped.
+func MergeAPEItems(existing, newItems []APETagItem, overrideKeys map[string]struct{}) []APETagItem {
+	// Build a set of keys being updated (upper-case for case-insensitive match)
+	combined := make(map[string]struct{}, len(newItems)+len(overrideKeys))
+	for k := range overrideKeys {
+		combined[strings.ToUpper(k)] = struct{}{}
+	}
+	for _, item := range newItems {
+		combined[strings.ToUpper(item.Key)] = struct{}{}
+	}
+
+	var merged []APETagItem
+	for _, item := range existing {
+		if _, overwritten := combined[strings.ToUpper(item.Key)]; !overwritten {
+			merged = append(merged, item)
+		}
+	}
+
+	merged = append(merged, newItems...)
+
+	return merged
+}
+
+// ReadAPETagsFromReader reads APEv2 tags from an io.ReaderAt + size.
+// This is useful for reading APE tags from files opened via SAF or other abstractions.
+func ReadAPETagsFromReader(r io.ReaderAt, fileSize int64) (*APETag, error) {
+	if fileSize < apeTagHeaderSize {
+		return nil, fmt.Errorf("file too small for APE tag")
+	}
+
+	// Try footer at end of file
+	footer := make([]byte, apeTagHeaderSize)
+	if _, err := r.ReadAt(footer, fileSize-apeTagHeaderSize); err != nil {
+		return nil, fmt.Errorf("failed to read APE footer: %w", err)
+	}
+
+	if string(footer[0:8]) == apeTagPreamble {
+		tag, err := parseAPETagFromFooter(r, fileSize, fileSize-apeTagHeaderSize, footer)
+		if err == nil {
+			return tag, nil
+		}
+	}
+
+	// Retry: skip ID3v1 tag (128 bytes)
+	if fileSize > apeTagHeaderSize+128 {
+		offset := fileSize - apeTagHeaderSize - 128
+		if _, err := r.ReadAt(footer, offset); err == nil {
+			if string(footer[0:8]) == apeTagPreamble {
+				tag, err := parseAPETagFromFooter(r, fileSize, offset, footer)
+				if err == nil {
+					return tag, nil
+				}
+			}
+		}
+	}
+
+	return nil, fmt.Errorf("no APEv2 tag found")
+}
+
+func parseAPETagFromFooter(r io.ReaderAt, fileSize, footerOffset int64, footer []byte) (*APETag, error) {
+	version := binary.LittleEndian.Uint32(footer[8:12])
+	tagSize := binary.LittleEndian.Uint32(footer[12:16])
+	itemCount := binary.LittleEndian.Uint32(footer[16:20])
+	flags := binary.LittleEndian.Uint32(footer[20:24])
+
+	if version != apeTagVersion2 && version != 1000 {
+		return nil, fmt.Errorf("unsupported APE tag version: %d", version)
+	}
+	if tagSize < apeTagHeaderSize {
+		return nil, fmt.Errorf("APE tag size too small: %d", tagSize)
+	}
+	if itemCount > 1000 {
+		return nil, fmt.Errorf("APE tag item count too large: %d", itemCount)
+	}
+	if (flags & apeTagFlagHeader) != 0 {
+		return nil, fmt.Errorf("expected footer, found header")
+	}
+
+	itemsSize := int64(tagSize) - apeTagHeaderSize
+	itemsOffset := footerOffset - itemsSize
+	if itemsOffset < 0 {
+		return nil, fmt.Errorf("APE items extend before file start")
+	}
+
+	itemsData := make([]byte, itemsSize)
+	if _, err := r.ReadAt(itemsData, itemsOffset); err != nil {
+		return nil, fmt.Errorf("failed to read APE items: %w", err)
+	}
+
+	items, err := parseAPEItems(itemsData, int(itemCount))
+	if err != nil {
+		return nil, fmt.Errorf("failed to parse APE items: %w", err)
+	}
+
+	return &APETag{
+		Version:  version,
+		Items:    items,
+		ReadOnly: (flags & apeTagFlagReadOnly) != 0,
+	}, nil
+}

go_backend/audio_metadata.go

@@ -28,6 +28,11 @@ type AudioMetadata struct {
 	Copyright   string
 	Composer    string
 	Comment     string
+	// ReplayGain fields (text values, e.g. "-6.50 dB", "0.988831")
+	ReplayGainTrackGain string
+	ReplayGainTrackPeak string
+	ReplayGainAlbumGain string
+	ReplayGainAlbumPeak string
 }
 
 type MP3Quality struct {
@@ -311,6 +316,17 @@ func parseID3v23Frames(data []byte, metadata *AudioMetadata, version byte, tagUn
 			if isLyricsDescription(desc) && userValue != "" && metadata.Lyrics == "" {
 				metadata.Lyrics = userValue
 			}
+			upperDesc := strings.ToUpper(desc)
+			switch upperDesc {
+			case "REPLAYGAIN_TRACK_GAIN":
+				metadata.ReplayGainTrackGain = userValue
+			case "REPLAYGAIN_TRACK_PEAK":
+				metadata.ReplayGainTrackPeak = userValue
+			case "REPLAYGAIN_ALBUM_GAIN":
+				metadata.ReplayGainAlbumGain = userValue
+			case "REPLAYGAIN_ALBUM_PEAK":
+				metadata.ReplayGainAlbumPeak = userValue
+			}
 		}
 
 		pos += 10 + frameSize
@@ -338,7 +354,6 @@ func readID3v1(file *os.File) (*AudioMetadata, error) {
 		Year:   strings.TrimRight(string(tag[93:97]), " \x00"),
 	}
 
-	// ID3v1.1 track number (if byte 125 is 0 and byte 126 is not)
 	if tag[125] == 0 && tag[126] != 0 {
 		metadata.TrackNumber = int(tag[126])
 	}
@@ -373,27 +388,23 @@ func extractTextFrame(data []byte) string {
 	}
 }
 
-// extractCommentFrame parses an ID3v2 COMM frame.
-// Format: encoding(1) + language(3) + description(null-terminated) + text
 func extractCommentFrame(data []byte) string {
 	if len(data) < 5 {
 		return ""
 	}
 	encoding := data[0]
-	// skip 3-byte language code
 	rest := data[4:]
 
-	// find null terminator separating description from text
 	var text []byte
 	switch encoding {
-	case 1, 2: // UTF-16 variants use double-null terminator
+	case 1, 2:
 		for i := 0; i+1 < len(rest); i += 2 {
 			if rest[i] == 0 && rest[i+1] == 0 {
 				text = rest[i+2:]
 				break
 			}
 		}
-	default: // ISO-8859-1 or UTF-8
+	default:
 		idx := bytes.IndexByte(rest, 0)
 		if idx >= 0 && idx+1 < len(rest) {
 			text = rest[idx+1:]
@@ -406,33 +417,30 @@ func extractCommentFrame(data []byte) string {
 		return ""
 	}
 
-	// re-prepend encoding byte so extractTextFrame can decode properly
 	framed := make([]byte, 1+len(text))
 	framed[0] = encoding
 	copy(framed[1:], text)
 	return extractTextFrame(framed)
 }
 
-// extractLyricsFrame parses ID3 unsynchronized lyrics frames (USLT/ULT).
-// Format: encoding(1) + language(3) + description(null-terminated) + lyrics text.
 func extractLyricsFrame(data []byte) string {
 	if len(data) < 5 {
 		return ""
 	}
 
 	encoding := data[0]
-	rest := data[4:] // skip 3-byte language code
+	rest := data[4:]
 
 	var text []byte
 	switch encoding {
-	case 1, 2: // UTF-16 variants use double-null terminator
+	case 1, 2:
 		for i := 0; i+1 < len(rest); i += 2 {
 			if rest[i] == 0 && rest[i+1] == 0 {
 				text = rest[i+2:]
 				break
 			}
 		}
-	default: // ISO-8859-1 or UTF-8
+	default:
 		idx := bytes.IndexByte(rest, 0)
 		if idx >= 0 && idx+1 < len(rest) {
 			text = rest[idx+1:]
@@ -451,8 +459,6 @@ func extractLyricsFrame(data []byte) string {
 	return extractTextFrame(framed)
 }
 
-// extractUserTextFrame parses ID3 TXXX/TXX user text frame:
-// encoding(1) + description + separator + value.
 func extractUserTextFrame(data []byte) (string, string) {
 	if len(data) < 2 {
 		return "", ""
@@ -463,7 +469,7 @@ func extractUserTextFrame(data []byte) (string, string) {
 
 	var descRaw, valueRaw []byte
 	switch encoding {
-	case 1, 2: // UTF-16 variants
+	case 1, 2:
 		for i := 0; i+1 < len(payload); i += 2 {
 			if payload[i] == 0 && payload[i+1] == 0 {
 				descRaw = payload[:i]
@@ -471,7 +477,7 @@ func extractUserTextFrame(data []byte) (string, string) {
 				break
 			}
 		}
-	default: // ISO-8859-1 or UTF-8
+	default:
 		idx := bytes.IndexByte(payload, 0)
 		if idx >= 0 {
 			descRaw = payload[:idx]
@@ -665,7 +671,6 @@ func GetMP3Quality(filePath string) (*MP3Quality, error) {
 
 	file.Seek(audioStart, io.SeekStart)
 
-	// Find first valid MP3 frame sync
 	frameHeader := make([]byte, 4)
 	var frameStart int64 = -1
 	for i := 0; i < 10000; i++ {
@@ -692,8 +697,6 @@ func GetMP3Quality(filePath string) (*MP3Quality, error) {
 	sampleRateIdx := (frameHeader[2] >> 2) & 0x03
 	channelMode := (frameHeader[3] >> 6) & 0x03
 
-	// Sample rate tables: [version][index]
-	// version: 0=MPEG2.5, 1=reserved, 2=MPEG2, 3=MPEG1
 	sampleRates := [][]int{
 		{11025, 12000, 8000},
 		{0, 0, 0},
@@ -704,15 +707,12 @@ func GetMP3Quality(filePath string) (*MP3Quality, error) {
 		quality.SampleRate = sampleRates[version][sampleRateIdx]
 	}
 
-	// Bitrate tables for all MPEG versions and layers
-	// MPEG1 Layer III
 	if version == 3 && layer == 1 {
 		bitrates := []int{0, 32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320, 0}
 		if bitrateIdx < 16 {
 			quality.Bitrate = bitrates[bitrateIdx] * 1000
 		}
 	}
-	// MPEG2/2.5 Layer III
 	if (version == 0 || version == 2) && layer == 1 {
 		bitrates := []int{0, 8, 16, 24, 32, 40, 48, 56, 64, 80, 96, 112, 128, 144, 160, 0}
 		if bitrateIdx < 16 {
@@ -720,14 +720,11 @@ func GetMP3Quality(filePath string) (*MP3Quality, error) {
 		}
 	}
 
-	// Determine samples per frame for duration calculation
 	samplesPerFrame := 1152 // MPEG1 Layer III
 	if version == 0 || version == 2 {
 		samplesPerFrame = 576 // MPEG2/2.5 Layer III
 	}
 
-	// Try to read Xing/VBRI header from the first frame for VBR info
-	// Xing header offset depends on MPEG version and channel mode
 	var xingOffset int
 	if version == 3 { // MPEG1
 		if channelMode == 3 { // Mono
@@ -743,7 +740,6 @@ func GetMP3Quality(filePath string) (*MP3Quality, error) {
 		}
 	}
 
-	// Read enough of the first frame to find Xing/VBRI header
 	xingBuf := make([]byte, 200)
 	file.Seek(frameStart+4, io.SeekStart)
 	n, _ := io.ReadFull(file, xingBuf)
@@ -753,7 +749,6 @@ func GetMP3Quality(filePath string) (*MP3Quality, error) {
 	vbrBytes := int64(0)
 	isVBR := false
 
-	// Check for Xing/Info header
 	if xingOffset+8 <= n {
 		tag := string(xingBuf[xingOffset : xingOffset+4])
 		if tag == "Xing" || tag == "Info" {
@@ -772,7 +767,6 @@ func GetMP3Quality(filePath string) (*MP3Quality, error) {
 		}
 	}
 
-	// Check for VBRI header (always at offset 32 from frame start + 4)
 	if !isVBR && 36+26 <= n {
 		if string(xingBuf[32:36]) == "VBRI" {
 			vbrBytes = int64(binary.BigEndian.Uint32(xingBuf[36+6 : 36+10]))
@@ -784,11 +778,9 @@ func GetMP3Quality(filePath string) (*MP3Quality, error) {
 	}
 
 	if isVBR && vbrFrames > 0 && quality.SampleRate > 0 {
-		// Accurate duration from total frames
 		totalSamples := int64(vbrFrames) * int64(samplesPerFrame)
 		quality.Duration = int(totalSamples / int64(quality.SampleRate))
 
-		// Accurate average bitrate
 		if vbrBytes > 0 && quality.Duration > 0 {
 			quality.Bitrate = int(vbrBytes * 8 / int64(quality.Duration))
 		} else if quality.Duration > 0 {
@@ -796,7 +788,6 @@ func GetMP3Quality(filePath string) (*MP3Quality, error) {
 			quality.Bitrate = int(audioSize * 8 / int64(quality.Duration))
 		}
 	} else if quality.Bitrate > 0 {
-		// CBR fallback: estimate duration from file size and frame bitrate
 		audioSize := fileSize - audioStart - 128 // subtract possible ID3v1 tag
 		if audioSize > 0 {
 			quality.Duration = int(audioSize * 8 / int64(quality.Bitrate))
@@ -980,8 +971,9 @@ func parseVorbisComments(data []byte, metadata *AudioMetadata) {
 	}
 
 	reader := bytes.NewReader(data)
+	artistValues := make([]string, 0, 1)
+	albumArtistValues := make([]string, 0, 1)
 
-	// Read vendor string length
 	var vendorLen uint32
 	if err := binary.Read(reader, binary.LittleEndian, &vendorLen); err != nil {
 		return
@@ -1010,8 +1002,6 @@ func parseVorbisComments(data []byte, metadata *AudioMetadata) {
 		if commentLen > remaining {
 			break
 		}
-		// Large comment entries are typically METADATA_BLOCK_PICTURE.
-		// Skip them so we can continue parsing normal text tags after/before.
 		if commentLen > 512*1024 {
 			reader.Seek(int64(commentLen), io.SeekCurrent)
 			continue
@@ -1034,9 +1024,9 @@ func parseVorbisComments(data []byte, metadata *AudioMetadata) {
 		case "TITLE":
 			metadata.Title = value
 		case "ARTIST":
-			metadata.Artist = value
+			artistValues = append(artistValues, value)
 		case "ALBUMARTIST", "ALBUM_ARTIST", "ALBUM ARTIST":
-			metadata.AlbumArtist = value
+			albumArtistValues = append(albumArtistValues, value)
 		case "ALBUM":
 			metadata.Album = value
 		case "DATE", "YEAR":
@@ -1064,8 +1054,23 @@ func parseVorbisComments(data []byte, metadata *AudioMetadata) {
 			metadata.Label = value
 		case "COPYRIGHT":
 			metadata.Copyright = value
+		case "REPLAYGAIN_TRACK_GAIN":
+			metadata.ReplayGainTrackGain = value
+		case "REPLAYGAIN_TRACK_PEAK":
+			metadata.ReplayGainTrackPeak = value
+		case "REPLAYGAIN_ALBUM_GAIN":
+			metadata.ReplayGainAlbumGain = value
+		case "REPLAYGAIN_ALBUM_PEAK":
+			metadata.ReplayGainAlbumPeak = value
 		}
 	}
+
+	if len(artistValues) > 0 {
+		metadata.Artist = joinVorbisCommentValues(artistValues)
+	}
+	if len(albumArtistValues) > 0 {
+		metadata.AlbumArtist = joinVorbisCommentValues(albumArtistValues)
+	}
 }
 
 func GetOggQuality(filePath string) (*OggQuality, error) {
@@ -1114,7 +1119,6 @@ func GetOggQuality(filePath string) (*OggQuality, error) {
 		}
 	}
 
-	// Read granule position from the last Ogg page for accurate duration
 	stat, err := file.Stat()
 	if err != nil {
 		return quality, nil
@@ -1124,7 +1128,6 @@ func GetOggQuality(filePath string) (*OggQuality, error) {
 	granule := readLastOggGranulePosition(file, fileSize)
 	if granule > 0 {
 		if isOpus {
-			// Opus always uses 48kHz granule position internally
 			totalSamples := granule - int64(preSkip)
 			if totalSamples > 0 {
 				durationSec := float64(totalSamples) / 48000.0
@@ -1142,11 +1145,9 @@ func GetOggQuality(filePath string) (*OggQuality, error) {
 		}
 	}
 
-	// Fallback bitrate estimate if duration exists but bitrate couldn't be derived.
 	if quality.Bitrate <= 0 && quality.Duration > 0 {
 		quality.Bitrate = int(fileSize * 8 / int64(quality.Duration))
 	}
-	// Guard against obviously invalid values from corrupted/unreliable granule reads.
 	if quality.Duration > 24*60*60 {
 		quality.Duration = 0
 		quality.Bitrate = 0
@@ -1158,10 +1159,7 @@ func GetOggQuality(filePath string) (*OggQuality, error) {
 	return quality, nil
 }
 
-// readLastOggGranulePosition seeks to the end of the file and scans backwards
-// to find the last Ogg page, then reads its granule position (bytes 6-13).
 func readLastOggGranulePosition(file *os.File, fileSize int64) int64 {
-	// Read the last chunk of the file to find the last OggS sync
 	searchSize := int64(65536)
 	if searchSize > fileSize {
 		searchSize = fileSize
@@ -1185,7 +1183,6 @@ func readLastOggGranulePosition(file *os.File, fileSize int64) int64 {
 		if i+27 > n {
 			continue
 		}
-		// Validate minimal header fields to avoid false positives inside payload bytes.
 		version := buf[i+4]
 		headerType := buf[i+5]
 		if version != 0 || headerType > 0x07 {
@@ -1203,7 +1200,6 @@ func readLastOggGranulePosition(file *os.File, fileSize int64) int64 {
 		if i+headerLen+payloadLen > n {
 			continue
 		}
-		// Granule position is at bytes 6-13 of the Ogg page header (little-endian int64).
 		return int64(binary.LittleEndian.Uint64(buf[i+6 : i+14]))
 	}
 	return 0
@@ -1263,7 +1259,6 @@ func extractMP3CoverArt(filePath string) ([]byte, string, error) {
 		return nil, "", err
 	}
 
-	// Parse frames looking for APIC (Attached Picture)
 	pos := 0
 	var frameIDLen, headerLen int
 	if majorVersion == 2 {
@@ -1294,7 +1289,6 @@ func extractMP3CoverArt(filePath string) ([]byte, string, error) {
 			break
 		}
 
-		// Check for APIC (ID3v2.3/2.4) or PIC (ID3v2.2)
 		if (frameIDLen == 4 && frameID == "APIC") || (frameIDLen == 3 && frameID == "PIC") {
 			frameData := tagData[pos+headerLen : pos+headerLen+frameSize]
 			imageData, mimeType := parseAPICFrame(frameData, majorVersion)
@@ -1620,14 +1614,28 @@ func extractAnyCoverArtWithHint(filePath, displayNameHint string) ([]byte, strin
 }
 
 func SaveCoverToCache(filePath, cacheDir string) (string, error) {
-	return SaveCoverToCacheWithHint(filePath, "", cacheDir)
+	return SaveCoverToCacheWithHintAndKey(filePath, "", cacheDir, "")
 }
 
 func SaveCoverToCacheWithHint(filePath, displayNameHint, cacheDir string) (string, error) {
+	return SaveCoverToCacheWithHintAndKey(filePath, displayNameHint, cacheDir, "")
+}
+
+func resolveLibraryCoverCacheKey(filePath, explicitKey string) string {
+	explicitKey = strings.TrimSpace(explicitKey)
+	if explicitKey != "" {
+		return explicitKey
+	}
+
 	cacheKey := filePath
 	if stat, err := os.Stat(filePath); err == nil {
 		cacheKey = fmt.Sprintf("%s|%d|%d", filePath, stat.Size(), stat.ModTime().UnixNano())
 	}
+	return cacheKey
+}
+
+func SaveCoverToCacheWithHintAndKey(filePath, displayNameHint, cacheDir, coverCacheKey string) (string, error) {
+	cacheKey := resolveLibraryCoverCacheKey(filePath, coverCacheKey)
 	hash := hashString(cacheKey)
 
 	jpgPath := filepath.Join(cacheDir, fmt.Sprintf("cover_%x.jpg", hash))

go_backend/audio_metadata_cache_test.go

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

go_backend/cue_parser.go

@@ -11,7 +11,6 @@ import (
 	"strings"
 )
 
-// CueSheet represents a parsed .cue file
 type CueSheet struct {
 	Performer string     `json:"performer"`
 	Title     string     `json:"title"`
@@ -24,18 +23,16 @@ type CueSheet struct {
 	Tracks    []CueTrack `json:"tracks"`
 }
 
-// CueTrack represents a single track in a cue sheet
 type CueTrack struct {
-	Number    int    `json:"number"`
-	Title     string `json:"title"`
-	Performer string `json:"performer"`
-	ISRC      string `json:"isrc,omitempty"`
-	Composer  string `json:"composer,omitempty"`
+	Number    int     `json:"number"`
+	Title     string  `json:"title"`
+	Performer string  `json:"performer"`
+	ISRC      string  `json:"isrc,omitempty"`
+	Composer  string  `json:"composer,omitempty"`
 	StartTime float64 `json:"start_time"` // INDEX 01 in seconds
 	PreGap    float64 `json:"pre_gap"`    // INDEX 00 in seconds (or -1 if not present)
 }
 
-// CueSplitInfo represents the information needed to split a CUE+audio file
 type CueSplitInfo struct {
 	CuePath   string          `json:"cue_path"`
 	AudioPath string          `json:"audio_path"`
@@ -46,7 +43,6 @@ type CueSplitInfo struct {
 	Tracks    []CueSplitTrack `json:"tracks"`
 }
 
-// CueSplitTrack has the FFmpeg split parameters for a single track
 type CueSplitTrack struct {
 	Number   int     `json:"number"`
 	Title    string  `json:"title"`
@@ -62,7 +58,6 @@ var (
 	reQuoted     = regexp.MustCompile(`"([^"]*)"`)
 )
 
-// ParseCueFile parses a .cue file and returns a CueSheet
 func ParseCueFile(cuePath string) (*CueSheet, error) {
 	f, err := os.Open(cuePath)
 	if err != nil {
@@ -202,7 +197,6 @@ func ParseCueFile(cuePath string) (*CueSheet, error) {
 	return sheet, nil
 }
 
-// parseCueTimestamp converts MM:SS:FF (frames at 75fps) to seconds
 func parseCueTimestamp(ts string) float64 {
 	parts := strings.Split(ts, ":")
 	if len(parts) != 3 {
@@ -216,7 +210,6 @@ func parseCueTimestamp(ts string) float64 {
 	return float64(minutes)*60 + float64(seconds) + float64(frames)/75.0
 }
 
-// formatCueTimestamp converts seconds to HH:MM:SS.mmm format for FFmpeg
 func formatCueTimestamp(seconds float64) string {
 	if seconds < 0 {
 		return "0"
@@ -227,7 +220,6 @@ func formatCueTimestamp(seconds float64) string {
 	return fmt.Sprintf("%02d:%02d:%06.3f", hours, mins, secs)
 }
 
-// unquoteCue removes surrounding quotes from a CUE value
 func unquoteCue(s string) string {
 	s = strings.TrimSpace(s)
 	if matches := reQuoted.FindStringSubmatch(s); len(matches) == 2 {
@@ -236,14 +228,12 @@ func unquoteCue(s string) string {
 	return s
 }
 
-// parseCueFileLine parses the FILE command's filename and type
 func parseCueFileLine(rest string) (string, string) {
 	rest = strings.TrimSpace(rest)
 
 	var filename, ftype string
 
 	if strings.HasPrefix(rest, "\"") {
-		// Quoted filename
 		endQuote := strings.Index(rest[1:], "\"")
 		if endQuote >= 0 {
 			filename = rest[1 : endQuote+1]
@@ -253,7 +243,6 @@ func parseCueFileLine(rest string) (string, string) {
 			filename = rest
 		}
 	} else {
-		// Unquoted filename - last word is the type
 		parts := strings.Fields(rest)
 		if len(parts) >= 2 {
 			ftype = parts[len(parts)-1]
@@ -266,18 +255,14 @@ func parseCueFileLine(rest string) (string, string) {
 	return filename, strings.TrimSpace(ftype)
 }
 
-// ResolveCueAudioPath finds the actual audio file referenced by a .cue sheet.
-// It checks relative to the cue file's directory.
 func ResolveCueAudioPath(cuePath string, cueFileName string) string {
 	cueDir := filepath.Dir(cuePath)
 
-	// 1. Try the exact filename from the .cue
 	candidate := filepath.Join(cueDir, cueFileName)
 	if _, err := os.Stat(candidate); err == nil {
 		return candidate
 	}
 
-	// 2. Try common case variations
 	baseName := strings.TrimSuffix(cueFileName, filepath.Ext(cueFileName))
 	commonExts := []string{".flac", ".wav", ".ape", ".mp3", ".ogg", ".wv", ".m4a"}
 	for _, ext := range commonExts {
@@ -285,14 +270,12 @@ func ResolveCueAudioPath(cuePath string, cueFileName string) string {
 		if _, err := os.Stat(candidate); err == nil {
 			return candidate
 		}
-		// Try uppercase ext
 		candidate = filepath.Join(cueDir, baseName+strings.ToUpper(ext))
 		if _, err := os.Stat(candidate); err == nil {
 			return candidate
 		}
 	}
 
-	// 3. Try to find any audio file with the same base name as the .cue file
 	cueBase := strings.TrimSuffix(filepath.Base(cuePath), filepath.Ext(cuePath))
 	for _, ext := range commonExts {
 		candidate = filepath.Join(cueDir, cueBase+ext)
@@ -301,7 +284,6 @@ func ResolveCueAudioPath(cuePath string, cueFileName string) string {
 		}
 	}
 
-	// 4. If there's only one audio file in the directory, use that
 	entries, err := os.ReadDir(cueDir)
 	if err == nil {
 		audioExts := map[string]bool{
@@ -326,13 +308,9 @@ func ResolveCueAudioPath(cuePath string, cueFileName string) string {
 	return ""
 }
 
-// BuildCueSplitInfo creates the split information from a parsed CUE sheet.
-// This is returned to the Dart side so FFmpeg can perform the splitting.
-// audioDir, if non-empty, overrides the directory for audio file resolution.
 func BuildCueSplitInfo(cuePath string, sheet *CueSheet, audioDir string) (*CueSplitInfo, error) {
 	resolveDir := cuePath
 	if audioDir != "" {
-		// Create a virtual path in audioDir so ResolveCueAudioPath looks there
 		resolveDir = filepath.Join(audioDir, filepath.Base(cuePath))
 	}
 	audioPath := ResolveCueAudioPath(resolveDir, sheet.FileName)
@@ -360,11 +338,9 @@ func BuildCueSplitInfo(cuePath string, sheet *CueSheet, audioDir string) (*CueSp
 			composer = sheet.Composer
 		}
 
-		// End time is the start of the next track, or -1 for the last track
 		endSec := float64(-1)
 		if i+1 < len(sheet.Tracks) {
 			nextTrack := sheet.Tracks[i+1]
-			// Use pre-gap of next track if available, otherwise its start time
 			if nextTrack.PreGap >= 0 {
 				endSec = nextTrack.PreGap
 			} else {
@@ -386,11 +362,6 @@ func BuildCueSplitInfo(cuePath string, sheet *CueSheet, audioDir string) (*CueSp
 	return info, nil
 }
 
-// ParseCueFileJSON parses a .cue file and returns JSON with split info.
-// This is the main entry point called from Dart via the platform bridge.
-// audioDir, if non-empty, overrides the directory used for resolving the
-// referenced audio file (useful when the .cue was copied to a temp dir
-// but the audio still lives in the original location, e.g. SAF).
 func ParseCueFileJSON(cuePath string, audioDir string) (string, error) {
 	sheet, err := ParseCueFile(cuePath)
 	if err != nil {
@@ -410,9 +381,6 @@ func ParseCueFileJSON(cuePath string, audioDir string) (string, error) {
 	return string(jsonBytes), nil
 }
 
-// ScanCueFileForLibrary parses a .cue file and returns multiple LibraryScanResult
-// entries, one per track. This is used by the library scanner to populate the
-// library with individual track entries from a single CUE+FLAC album.
 func ScanCueFileForLibrary(cuePath string, scanTime string) ([]LibraryScanResult, error) {
 	sheet, err := ParseCueFile(cuePath)
 	if err != nil {
@@ -422,17 +390,21 @@ func ScanCueFileForLibrary(cuePath string, scanTime string) ([]LibraryScanResult
 	if err != nil {
 		return nil, err
 	}
-	return scanCueSheetForLibrary(cuePath, sheet, audioPath, "", 0, scanTime)
+	return scanCueSheetForLibrary(cuePath, sheet, audioPath, "", 0, "", scanTime)
 }
 
-// ScanCueFileForLibraryExt is like ScanCueFileForLibrary but with extra parameters
-// for SAF (Storage Access Framework) scenarios:
-//   - audioDir: if non-empty, overrides the directory used to find the audio file
-//   - virtualPathPrefix: if non-empty, used instead of cuePath as the base for
-//     virtual file paths (e.g. a content:// URI). IDs are also based on this.
-//   - fileModTime: if > 0, used as the FileModTime for all results instead of
-//     stat-ing the cuePath on disk (useful when the real file lives behind SAF)
 func ScanCueFileForLibraryExt(cuePath, audioDir, virtualPathPrefix string, fileModTime int64, scanTime string) ([]LibraryScanResult, error) {
+	return ScanCueFileForLibraryExtWithCoverCacheKey(
+		cuePath,
+		audioDir,
+		virtualPathPrefix,
+		fileModTime,
+		"",
+		scanTime,
+	)
+}
+
+func ScanCueFileForLibraryExtWithCoverCacheKey(cuePath, audioDir, virtualPathPrefix string, fileModTime int64, coverCacheKey, scanTime string) ([]LibraryScanResult, error) {
 	sheet, err := ParseCueFile(cuePath)
 	if err != nil {
 		return nil, err
@@ -441,7 +413,15 @@ func ScanCueFileForLibraryExt(cuePath, audioDir, virtualPathPrefix string, fileM
 	if err != nil {
 		return nil, err
 	}
-	return scanCueSheetForLibrary(cuePath, sheet, audioPath, virtualPathPrefix, fileModTime, scanTime)
+	return scanCueSheetForLibrary(
+		cuePath,
+		sheet,
+		audioPath,
+		virtualPathPrefix,
+		fileModTime,
+		coverCacheKey,
+		scanTime,
+	)
 }
 
 func resolveCueAudioPathForLibrary(cuePath string, sheet *CueSheet, audioDir string) (string, error) {
@@ -459,12 +439,11 @@ func resolveCueAudioPathForLibrary(cuePath string, sheet *CueSheet, audioDir str
 	return audioPath, nil
 }
 
-func scanCueSheetForLibrary(cuePath string, sheet *CueSheet, audioPath, virtualPathPrefix string, fileModTime int64, scanTime string) ([]LibraryScanResult, error) {
+func scanCueSheetForLibrary(cuePath string, sheet *CueSheet, audioPath, virtualPathPrefix string, fileModTime int64, coverCacheKey, scanTime string) ([]LibraryScanResult, error) {
 	if sheet == nil {
 		return nil, fmt.Errorf("cue sheet is nil for %s", cuePath)
 	}
 
-	// Try to get quality info from the audio file
 	var bitDepth, sampleRate int
 	var totalDurationSec float64
 	audioExt := strings.ToLower(filepath.Ext(audioPath))
@@ -486,25 +465,27 @@ func scanCueSheetForLibrary(cuePath string, sheet *CueSheet, audioPath, virtualP
 		}
 	}
 
-	// Extract cover from audio file for all tracks
 	var coverPath string
 	libraryCoverCacheMu.RLock()
 	coverCacheDir := libraryCoverCacheDir
 	libraryCoverCacheMu.RUnlock()
 	if coverCacheDir != "" {
-		cp, err := SaveCoverToCache(audioPath, coverCacheDir)
+		cp, err := SaveCoverToCacheWithHintAndKey(
+			audioPath,
+			"",
+			coverCacheDir,
+			coverCacheKey,
+		)
 		if err == nil && cp != "" {
 			coverPath = cp
 		}
 	}
 
-	// Determine the base path for virtual paths and IDs
 	pathBase := cuePath
 	if virtualPathPrefix != "" {
 		pathBase = virtualPathPrefix
 	}
 
-	// Determine fileModTime
 	modTime := fileModTime
 	if modTime <= 0 {
 		if info, err := os.Stat(cuePath); err == nil {
@@ -532,7 +513,6 @@ func scanCueSheetForLibrary(cuePath string, sheet *CueSheet, audioPath, virtualP
 			album = "Unknown Album"
 		}
 
-		// Calculate duration for this track
 		var duration int
 		if i+1 < len(sheet.Tracks) {
 			nextStart := sheet.Tracks[i+1].StartTime
@@ -546,9 +526,6 @@ func scanCueSheetForLibrary(cuePath string, sheet *CueSheet, audioPath, virtualP
 
 		id := generateLibraryID(fmt.Sprintf("%s#track%d", pathBase, track.Number))
 
-		// Use a virtual file path that includes the track number to ensure
-		// uniqueness in the database (file_path has a UNIQUE constraint).
-		// Format: /path/to/album.cue#track01 or content://...album.cue#track01
 		virtualFilePath := fmt.Sprintf("%s#track%02d", pathBase, track.Number)
 
 		result := LibraryScanResult{

go_backend/deezer.go

@@ -196,15 +196,22 @@ type deezerAlbumSimple struct {
 	RecordType  string `json:"record_type"`
 }
 
-func (c *DeezerClient) convertTrack(track deezerTrack) TrackMetadata {
-	artistName := track.Artist.Name
+// deezerTrackArtistDisplay returns the display artist string for a track,
+// preferring the Contributors list (comma-joined) when available, falling
+// back to the primary Artist.Name.
+func deezerTrackArtistDisplay(track deezerTrack) string {
 	if len(track.Contributors) > 0 {
 		names := make([]string, len(track.Contributors))
 		for i, a := range track.Contributors {
 			names[i] = a.Name
 		}
-		artistName = strings.Join(names, ", ")
+		return strings.Join(names, ", ")
 	}
+	return track.Artist.Name
+}
+
+func (c *DeezerClient) convertTrack(track deezerTrack) TrackMetadata {
+	artistName := deezerTrackArtistDisplay(track)
 
 	albumImage := track.Album.CoverXL
 	if albumImage == "" {
@@ -641,7 +648,7 @@ func (c *DeezerClient) GetAlbum(ctx context.Context, albumID string) (*AlbumResp
 
 		tracks = append(tracks, AlbumTrackMetadata{
 			SpotifyID:   fmt.Sprintf("deezer:%d", track.ID),
-			Artists:     track.Artist.Name,
+			Artists:     deezerTrackArtistDisplay(track),
 			Name:        track.Title,
 			AlbumName:   album.Title,
 			AlbumArtist: artistName,
@@ -741,6 +748,10 @@ func (c *DeezerClient) GetArtist(ctx context.Context, artistID string) (*ArtistR
 				Artists:     artist.Name,
 			})
 		}
+
+		// The Deezer /artist/{id}/albums endpoint does not return nb_tracks.
+		// Fetch track counts in parallel from individual /album/{id} endpoints.
+		c.fetchAlbumTrackCounts(ctx, albums)
 	}
 
 	result := &ArtistResponsePayload{
@@ -760,6 +771,63 @@ func (c *DeezerClient) GetArtist(ctx context.Context, artistID string) (*ArtistR
 	return result, nil
 }
 
+// fetchAlbumTrackCounts fetches nb_tracks for each album in parallel using
+// individual /album/{id} calls, since the /artist/{id}/albums endpoint does
+// not include this field. Albums whose track count is already known (non-zero)
+// are skipped.
+func (c *DeezerClient) fetchAlbumTrackCounts(ctx context.Context, albums []ArtistAlbumMetadata) {
+	// Find albums that need track counts
+	type indexedID struct {
+		idx     int
+		albumID string
+	}
+	var toFetch []indexedID
+	for i, a := range albums {
+		if a.TotalTracks == 0 {
+			rawID := strings.TrimPrefix(a.ID, "deezer:")
+			if rawID != "" {
+				toFetch = append(toFetch, indexedID{idx: i, albumID: rawID})
+			}
+		}
+	}
+	if len(toFetch) == 0 {
+		return
+	}
+
+	const maxParallel = 10
+	sem := make(chan struct{}, maxParallel)
+	var mu sync.Mutex
+	var wg sync.WaitGroup
+
+	for _, item := range toFetch {
+		wg.Add(1)
+		go func(it indexedID) {
+			defer wg.Done()
+
+			select {
+			case sem <- struct{}{}:
+				defer func() { <-sem }()
+			case <-ctx.Done():
+				return
+			}
+
+			albumURL := fmt.Sprintf(deezerAlbumURL, it.albumID)
+			var resp struct {
+				NbTracks int `json:"nb_tracks"`
+			}
+			if err := c.getJSON(ctx, albumURL, &resp); err != nil {
+				return
+			}
+
+			mu.Lock()
+			albums[it.idx].TotalTracks = resp.NbTracks
+			mu.Unlock()
+		}(item)
+	}
+
+	wg.Wait()
+}
+
 func (c *DeezerClient) GetRelatedArtists(ctx context.Context, artistID string, limit int) ([]SearchArtistResult, error) {
 	normalizedArtistID := strings.TrimSpace(strings.TrimPrefix(artistID, "deezer:"))
 	if normalizedArtistID == "" {
@@ -892,7 +960,7 @@ func (c *DeezerClient) GetPlaylist(ctx context.Context, playlistID string) (*Pla
 
 		tracks = append(tracks, AlbumTrackMetadata{
 			SpotifyID:   fmt.Sprintf("deezer:%d", track.ID),
-			Artists:     track.Artist.Name,
+			Artists:     deezerTrackArtistDisplay(track),
 			Name:        track.Title,
 			AlbumName:   track.Album.Title,
 			AlbumArtist: track.Artist.Name,

go_backend/deezer_download.go

@@ -14,14 +14,7 @@ import (
 	"strings"
 )
 
-const deezerYoinkifyURL = "https://yoinkify.lol/api/download"
-const deezerMusicDLURL = "https://www.musicdl.me/api/download"
-
-type YoinkifyRequest struct {
-	URL         string `json:"url"`
-	Format      string `json:"format"`
-	GenreSource string `json:"genreSource"`
-}
+const deezerMusicDLURL = "https://api.zarz.moe/v1/dzr"
 
 type DeezerDownloadResult struct {
 	FilePath    string
@@ -37,41 +30,6 @@ type DeezerDownloadResult struct {
 	LyricsLRC   string
 }
 
-func resolveSpotifyURLForYoinkify(req DownloadRequest) (string, error) {
-	rawSpotify := strings.TrimSpace(req.SpotifyID)
-	if rawSpotify != "" {
-		if isLikelySpotifyTrackID(rawSpotify) {
-			return fmt.Sprintf("https://open.spotify.com/track/%s", rawSpotify), nil
-		}
-
-		if parsed, err := parseSpotifyURI(rawSpotify); err == nil && parsed.Type == "track" && parsed.ID != "" {
-			return fmt.Sprintf("https://open.spotify.com/track/%s", parsed.ID), nil
-		}
-	}
-
-	deezerID := strings.TrimSpace(req.DeezerID)
-	if deezerID == "" {
-		if prefixed, found := strings.CutPrefix(rawSpotify, "deezer:"); found {
-			deezerID = strings.TrimSpace(prefixed)
-		}
-	}
-
-	if deezerID != "" {
-		songlink := NewSongLinkClient()
-		spotifyID, err := songlink.GetSpotifyIDFromDeezer(deezerID)
-		if err != nil {
-			return "", fmt.Errorf("failed to map deezer:%s to Spotify ID: %w", deezerID, err)
-		}
-		spotifyID = strings.TrimSpace(spotifyID)
-		if spotifyID == "" {
-			return "", fmt.Errorf("SongLink returned empty Spotify ID for deezer:%s", deezerID)
-		}
-		return fmt.Sprintf("https://open.spotify.com/track/%s", spotifyID), nil
-	}
-
-	return "", fmt.Errorf("missing Spotify track ID for Deezer Yoinkify")
-}
-
 func isLikelySpotifyTrackID(value string) bool {
 	if len(value) != 22 {
 		return false
@@ -88,113 +46,6 @@ func isLikelySpotifyTrackID(value string) bool {
 	return true
 }
 
-func (c *DeezerClient) DownloadFromYoinkify(spotifyURL, outputPath string, outputFD int, itemID string) error {
-	payload := YoinkifyRequest{
-		URL:         spotifyURL,
-		Format:      "flac",
-		GenreSource: "spotify",
-	}
-
-	jsonData, err := json.Marshal(payload)
-	if err != nil {
-		return fmt.Errorf("failed to encode Yoinkify request: %w", err)
-	}
-
-	ctx := context.Background()
-	if itemID != "" {
-		StartItemProgress(itemID)
-		defer CompleteItemProgress(itemID)
-		ctx = initDownloadCancel(itemID)
-		defer clearDownloadCancel(itemID)
-	}
-
-	if isDownloadCancelled(itemID) {
-		return ErrDownloadCancelled
-	}
-
-	req, err := http.NewRequestWithContext(ctx, http.MethodPost, deezerYoinkifyURL, bytes.NewBuffer(jsonData))
-	if err != nil {
-		return fmt.Errorf("failed to create Yoinkify request: %w", err)
-	}
-	req.Header.Set("Content-Type", "application/json")
-	req.Header.Set("Accept", "*/*")
-	req.Header.Set("User-Agent", getRandomUserAgent())
-
-	resp, err := GetDownloadClient().Do(req)
-	if err != nil {
-		if isDownloadCancelled(itemID) {
-			return ErrDownloadCancelled
-		}
-		return fmt.Errorf("failed to call Yoinkify: %w", err)
-	}
-	defer resp.Body.Close()
-
-	contentType := strings.ToLower(strings.TrimSpace(resp.Header.Get("Content-Type")))
-	if resp.StatusCode != http.StatusOK {
-		bodyBytes, _ := io.ReadAll(io.LimitReader(resp.Body, 4096))
-		bodyText := strings.TrimSpace(string(bodyBytes))
-		if bodyText != "" {
-			return fmt.Errorf("Yoinkify returned status %d: %s", resp.StatusCode, bodyText)
-		}
-		return fmt.Errorf("Yoinkify returned status %d", resp.StatusCode)
-	}
-
-	if strings.Contains(contentType, "application/json") {
-		bodyBytes, _ := io.ReadAll(io.LimitReader(resp.Body, 4096))
-		bodyText := strings.TrimSpace(string(bodyBytes))
-		if bodyText == "" {
-			bodyText = "empty JSON payload"
-		}
-		return fmt.Errorf("Yoinkify returned JSON instead of audio: %s", bodyText)
-	}
-
-	expectedSize := resp.ContentLength
-	if expectedSize > 0 && itemID != "" {
-		SetItemBytesTotal(itemID, expectedSize)
-	}
-
-	out, err := openOutputForWrite(outputPath, outputFD)
-	if err != nil {
-		return err
-	}
-
-	bufWriter := bufio.NewWriterSize(out, 256*1024)
-	var written int64
-	if itemID != "" {
-		pw := NewItemProgressWriter(bufWriter, itemID)
-		written, err = io.Copy(pw, resp.Body)
-	} else {
-		written, err = io.Copy(bufWriter, resp.Body)
-	}
-
-	flushErr := bufWriter.Flush()
-	closeErr := out.Close()
-
-	if err != nil {
-		cleanupOutputOnError(outputPath, outputFD)
-		if isDownloadCancelled(itemID) {
-			return ErrDownloadCancelled
-		}
-		return fmt.Errorf("download interrupted: %w", err)
-	}
-	if flushErr != nil {
-		cleanupOutputOnError(outputPath, outputFD)
-		return fmt.Errorf("failed to flush output: %w", flushErr)
-	}
-	if closeErr != nil {
-		cleanupOutputOnError(outputPath, outputFD)
-		return fmt.Errorf("failed to close output: %w", closeErr)
-	}
-
-	if expectedSize > 0 && written != expectedSize {
-		cleanupOutputOnError(outputPath, outputFD)
-		return fmt.Errorf("incomplete download: expected %d bytes, got %d bytes", expectedSize, written)
-	}
-
-	GoLog("[Deezer] Downloaded via Yoinkify: %.2f MB\n", float64(written)/(1024*1024))
-	return nil
-}
-
 func resolveDeezerTrackURL(req DownloadRequest) (string, error) {
 	deezerID := strings.TrimSpace(req.DeezerID)
 	if deezerID == "" {
@@ -211,7 +62,6 @@ func resolveDeezerTrackURL(req DownloadRequest) (string, error) {
 		return trackURL, nil
 	}
 
-	// Try SongLink
 	spotifyID := strings.TrimSpace(req.SpotifyID)
 	if spotifyID != "" && isLikelySpotifyTrackID(spotifyID) {
 		songlink := NewSongLinkClient()
@@ -231,7 +81,6 @@ func resolveDeezerTrackURL(req DownloadRequest) (string, error) {
 		}
 	}
 
-	// Try ISRC
 	isrc := strings.TrimSpace(req.ISRC)
 	if isrc != "" {
 		ctx, cancel := context.WithTimeout(context.Background(), SongLinkTimeout)
@@ -294,7 +143,6 @@ func (c *DeezerClient) GetMusicDLDownloadURL(deezerTrackURL string) (string, err
 		return "", fmt.Errorf("failed to create MusicDL request: %w", err)
 	}
 	req.Header.Set("Content-Type", "application/json")
-	req.Header.Set("X-Debug-Key", getQobuzDebugKey())
 	req.Header.Set("User-Agent", getRandomUserAgent())
 
 	resp, err := c.httpClient.Do(req)
@@ -479,41 +327,29 @@ func downloadFromDeezer(req DownloadRequest) (DeezerDownloadResult, error) {
 		)
 	}()
 
-	// Try MusicDL first (better quality), fallback to Yoinkify
-	var downloadErr error
 	deezerTrackURL, deezerURLErr := resolveDeezerTrackURL(req)
-	if deezerURLErr == nil {
-		GoLog("[Deezer] Trying MusicDL for: %s\n", deezerTrackURL)
-		downloadErr = deezerClient.DownloadFromMusicDL(deezerTrackURL, outputPath, req.OutputFD, req.ItemID)
-		if downloadErr != nil {
-			if errors.Is(downloadErr, ErrDownloadCancelled) {
-				return DeezerDownloadResult{}, ErrDownloadCancelled
-			}
-			GoLog("[Deezer] MusicDL failed: %v, falling back to Yoinkify\n", downloadErr)
-		}
-	} else {
-		GoLog("[Deezer] Could not resolve Deezer URL: %v, using Yoinkify directly\n", deezerURLErr)
+	if deezerURLErr != nil {
+		return DeezerDownloadResult{}, fmt.Errorf(
+			"deezer download failed: could not resolve Deezer URL: %w",
+			deezerURLErr,
+		)
 	}
 
-	if downloadErr != nil || deezerURLErr != nil {
-		spotifyURL, err := resolveSpotifyURLForYoinkify(req)
-		if err != nil {
-			if deezerURLErr != nil {
-				return DeezerDownloadResult{}, fmt.Errorf(
-					"deezer download failed: direct Deezer resolution error: %v; Yoinkify fallback error: %w",
-					deezerURLErr,
-					err,
-				)
-			}
-			return DeezerDownloadResult{}, err
-		}
-		downloadErr = deezerClient.DownloadFromYoinkify(spotifyURL, outputPath, req.OutputFD, req.ItemID)
-		if downloadErr != nil {
-			if errors.Is(downloadErr, ErrDownloadCancelled) {
-				return DeezerDownloadResult{}, ErrDownloadCancelled
-			}
-			return DeezerDownloadResult{}, fmt.Errorf("deezer download failed (MusicDL + Yoinkify): %w", downloadErr)
+	GoLog("[Deezer] Trying MusicDL for: %s\n", deezerTrackURL)
+	downloadErr := deezerClient.DownloadFromMusicDL(
+		deezerTrackURL,
+		outputPath,
+		req.OutputFD,
+		req.ItemID,
+	)
+	if downloadErr != nil {
+		if errors.Is(downloadErr, ErrDownloadCancelled) {
+			return DeezerDownloadResult{}, ErrDownloadCancelled
 		}
+		return DeezerDownloadResult{}, fmt.Errorf(
+			"deezer download failed via MusicDL: %w",
+			downloadErr,
+		)
 	}
 
 	<-parallelDone
@@ -524,18 +360,19 @@ func downloadFromDeezer(req DownloadRequest) (DeezerDownloadResult, error) {
 	}
 
 	metadata := Metadata{
-		Title:       req.TrackName,
-		Artist:      req.ArtistName,
-		Album:       req.AlbumName,
-		AlbumArtist: req.AlbumArtist,
-		Date:        req.ReleaseDate,
-		TrackNumber: req.TrackNumber,
-		TotalTracks: req.TotalTracks,
-		DiscNumber:  req.DiscNumber,
-		ISRC:        req.ISRC,
-		Genre:       req.Genre,
-		Label:       req.Label,
-		Copyright:   req.Copyright,
+		Title:         req.TrackName,
+		Artist:        req.ArtistName,
+		Album:         req.AlbumName,
+		AlbumArtist:   req.AlbumArtist,
+		ArtistTagMode: req.ArtistTagMode,
+		Date:          req.ReleaseDate,
+		TrackNumber:   req.TrackNumber,
+		TotalTracks:   req.TotalTracks,
+		DiscNumber:    req.DiscNumber,
+		ISRC:          req.ISRC,
+		Genre:         req.Genre,
+		Label:         req.Label,
+		Copyright:     req.Copyright,
 	}
 
 	var coverData []byte

go_backend/duplicate.go

@@ -25,7 +25,6 @@ var (
 )
 
 func GetISRCIndex(outputDir string) *ISRCIndex {
-	// Fast path: check cache first
 	isrcIndexCacheMu.RLock()
 	idx, exists := isrcIndexCache[outputDir]
 	isrcIndexCacheMu.RUnlock()
@@ -34,13 +33,11 @@ func GetISRCIndex(outputDir string) *ISRCIndex {
 		return idx
 	}
 
-	// Use per-directory mutex to prevent multiple goroutines from building simultaneously
 	buildLock, _ := isrcBuildingMu.LoadOrStore(outputDir, &sync.Mutex{})
 	mu := buildLock.(*sync.Mutex)
 	mu.Lock()
 	defer mu.Unlock()
 
-	// Double-check cache after acquiring lock (another goroutine may have built it)
 	isrcIndexCacheMu.RLock()
 	idx, exists = isrcIndexCache[outputDir]
 	isrcIndexCacheMu.RUnlock()

go_backend/exports.go

@@ -49,6 +49,7 @@ type DownloadRequest struct {
 	FilenameFormat       string `json:"filename_format"`
 	Quality              string `json:"quality"`
 	EmbedMetadata        bool   `json:"embed_metadata"`
+	ArtistTagMode        string `json:"artist_tag_mode,omitempty"`
 	EmbedLyrics          bool   `json:"embed_lyrics"`
 	EmbedMaxQualityCover bool   `json:"embed_max_quality_cover"`
 	TrackNumber          int    `json:"track_number"`
@@ -117,24 +118,40 @@ type DownloadResult struct {
 }
 
 type reEnrichRequest struct {
-	FilePath     string `json:"file_path"`
-	CoverURL     string `json:"cover_url"`
-	MaxQuality   bool   `json:"max_quality"`
-	EmbedLyrics  bool   `json:"embed_lyrics"`
-	SpotifyID    string `json:"spotify_id"`
-	TrackName    string `json:"track_name"`
-	ArtistName   string `json:"artist_name"`
-	AlbumName    string `json:"album_name"`
-	AlbumArtist  string `json:"album_artist"`
-	TrackNumber  int    `json:"track_number"`
-	DiscNumber   int    `json:"disc_number"`
-	ReleaseDate  string `json:"release_date"`
-	ISRC         string `json:"isrc"`
-	Genre        string `json:"genre"`
-	Label        string `json:"label"`
-	Copyright    string `json:"copyright"`
-	DurationMs   int64  `json:"duration_ms"`
-	SearchOnline bool   `json:"search_online"`
+	FilePath      string   `json:"file_path"`
+	CoverURL      string   `json:"cover_url"`
+	MaxQuality    bool     `json:"max_quality"`
+	EmbedLyrics   bool     `json:"embed_lyrics"`
+	ArtistTagMode string   `json:"artist_tag_mode,omitempty"`
+	SpotifyID     string   `json:"spotify_id"`
+	TrackName     string   `json:"track_name"`
+	ArtistName    string   `json:"artist_name"`
+	AlbumName     string   `json:"album_name"`
+	AlbumArtist   string   `json:"album_artist"`
+	TrackNumber   int      `json:"track_number"`
+	DiscNumber    int      `json:"disc_number"`
+	ReleaseDate   string   `json:"release_date"`
+	ISRC          string   `json:"isrc"`
+	Genre         string   `json:"genre"`
+	Label         string   `json:"label"`
+	Copyright     string   `json:"copyright"`
+	DurationMs    int64    `json:"duration_ms"`
+	SearchOnline  bool     `json:"search_online"`
+	UpdateFields  []string `json:"update_fields,omitempty"`
+}
+
+// shouldUpdateField returns true if the given field group should be updated.
+// When UpdateFields is empty/nil, all fields are updated (backward compatible).
+func (r *reEnrichRequest) shouldUpdateField(field string) bool {
+	if len(r.UpdateFields) == 0 {
+		return true
+	}
+	for _, f := range r.UpdateFields {
+		if f == field {
+			return true
+		}
+	}
+	return false
 }
 
 func applyReEnrichTrackMetadata(req *reEnrichRequest, track ExtTrackMetadata) {
@@ -154,52 +171,109 @@ func applyReEnrichTrackMetadata(req *reEnrichRequest, track ExtTrackMetadata) {
 		req.SpotifyID = track.ID
 	}
 
-	if track.AlbumName != "" {
-		req.AlbumName = track.AlbumName
+	if req.shouldUpdateField("basic_tags") {
+		if track.AlbumName != "" {
+			req.AlbumName = track.AlbumName
+		}
+		if track.AlbumArtist != "" {
+			req.AlbumArtist = track.AlbumArtist
+		}
 	}
-	if track.AlbumArtist != "" {
-		req.AlbumArtist = track.AlbumArtist
+	if req.shouldUpdateField("track_info") {
+		if track.TrackNumber > 0 {
+			req.TrackNumber = track.TrackNumber
+		}
+		if track.DiscNumber > 0 {
+			req.DiscNumber = track.DiscNumber
+		}
 	}
-	if track.TrackNumber > 0 {
-		req.TrackNumber = track.TrackNumber
+	if req.shouldUpdateField("release_info") {
+		if track.ReleaseDate != "" {
+			req.ReleaseDate = track.ReleaseDate
+		}
+		if track.ISRC != "" {
+			req.ISRC = track.ISRC
+		}
 	}
-	if track.DiscNumber > 0 {
-		req.DiscNumber = track.DiscNumber
-	}
-	if track.ReleaseDate != "" {
-		req.ReleaseDate = track.ReleaseDate
-	}
-	if track.ISRC != "" {
-		req.ISRC = track.ISRC
-	}
-	if coverURL := track.ResolvedCoverURL(); coverURL != "" {
-		req.CoverURL = coverURL
+	if req.shouldUpdateField("cover") {
+		if coverURL := track.ResolvedCoverURL(); coverURL != "" {
+			req.CoverURL = coverURL
+		}
 	}
 	if track.DurationMS > 0 {
 		req.DurationMs = int64(track.DurationMS)
 	}
-	if track.Genre != "" {
-		req.Genre = track.Genre
-	}
-	if track.Label != "" {
-		req.Label = track.Label
-	}
-	if track.Copyright != "" {
-		req.Copyright = track.Copyright
+	if req.shouldUpdateField("extra") {
+		if track.Genre != "" {
+			req.Genre = track.Genre
+		}
+		if track.Label != "" {
+			req.Label = track.Label
+		}
+		if track.Copyright != "" {
+			req.Copyright = track.Copyright
+		}
 	}
 }
 
 func reEnrichDownloadRequest(req reEnrichRequest) DownloadRequest {
 	return DownloadRequest{
-		TrackName:   req.TrackName,
-		ArtistName:  req.ArtistName,
-		AlbumName:   req.AlbumName,
-		ReleaseDate: req.ReleaseDate,
-		ISRC:        req.ISRC,
-		DurationMS:  int(req.DurationMs),
+		TrackName:     req.TrackName,
+		ArtistName:    req.ArtistName,
+		AlbumName:     req.AlbumName,
+		ReleaseDate:   req.ReleaseDate,
+		ISRC:          req.ISRC,
+		DurationMS:    int(req.DurationMs),
+		ArtistTagMode: req.ArtistTagMode,
 	}
 }
 
+func buildReEnrichFFmpegMetadata(req *reEnrichRequest, lyricsLRC string) map[string]string {
+	metadata := map[string]string{}
+	if req.shouldUpdateField("basic_tags") {
+		if req.AlbumName != "" {
+			metadata["ALBUM"] = req.AlbumName
+		}
+		if req.AlbumArtist != "" {
+			metadata["ALBUMARTIST"] = req.AlbumArtist
+		}
+	}
+	if req.shouldUpdateField("release_info") {
+		if req.ReleaseDate != "" {
+			metadata["DATE"] = req.ReleaseDate
+		}
+		if req.ISRC != "" {
+			metadata["ISRC"] = req.ISRC
+		}
+	}
+	if req.shouldUpdateField("extra") {
+		if req.Genre != "" {
+			metadata["GENRE"] = req.Genre
+		}
+		if req.Label != "" {
+			metadata["ORGANIZATION"] = req.Label
+		}
+		if req.Copyright != "" {
+			metadata["COPYRIGHT"] = req.Copyright
+		}
+	}
+	if req.shouldUpdateField("track_info") {
+		if req.TrackNumber > 0 {
+			metadata["TRACKNUMBER"] = fmt.Sprintf("%d", req.TrackNumber)
+		}
+		if req.DiscNumber > 0 {
+			metadata["DISCNUMBER"] = fmt.Sprintf("%d", req.DiscNumber)
+		}
+	}
+	if req.shouldUpdateField("lyrics") {
+		if lyricsLRC != "" {
+			metadata["LYRICS"] = lyricsLRC
+			metadata["UNSYNCEDLYRICS"] = lyricsLRC
+		}
+	}
+	return metadata
+}
+
 func selectBestReEnrichTrack(req reEnrichRequest, tracks []ExtTrackMetadata) *ExtTrackMetadata {
 	if len(tracks) == 0 {
 		return nil
@@ -690,8 +764,7 @@ func DownloadTrack(requestJSON string) (string, error) {
 	return string(jsonBytes), nil
 }
 
-// DownloadByStrategy routes a unified download request to the appropriate flow.
-// Routing priority: YouTube service > extension fallback > built-in fallback > direct service.
+// DownloadByStrategy routes download requests with priority: YouTube > extension fallback > built-in fallback > direct service.
 func DownloadByStrategy(requestJSON string) (string, error) {
 	var req DownloadRequest
 	if err := json.Unmarshal([]byte(requestJSON), &req); err != nil {
@@ -921,6 +994,9 @@ func ReadFileMetadata(filePath string) (string, error) {
 	isM4A := strings.HasSuffix(lower, ".m4a") || strings.HasSuffix(lower, ".aac")
 	isMp3 := strings.HasSuffix(lower, ".mp3")
 	isOgg := strings.HasSuffix(lower, ".opus") || strings.HasSuffix(lower, ".ogg")
+	isApe := strings.HasSuffix(lower, ".ape")
+	isWv := strings.HasSuffix(lower, ".wv")
+	isMpc := strings.HasSuffix(lower, ".mpc")
 
 	result := map[string]interface{}{
 		"title":        "",
@@ -986,6 +1062,10 @@ func ReadFileMetadata(filePath string) (string, error) {
 			result["copyright"] = metadata.Copyright
 			result["composer"] = metadata.Composer
 			result["comment"] = metadata.Comment
+			result["replaygain_track_gain"] = metadata.ReplayGainTrackGain
+			result["replaygain_track_peak"] = metadata.ReplayGainTrackPeak
+			result["replaygain_album_gain"] = metadata.ReplayGainAlbumGain
+			result["replaygain_album_peak"] = metadata.ReplayGainAlbumPeak
 
 			quality, qualityErr := GetAudioQuality(filePath)
 			if qualityErr == nil {
@@ -1016,6 +1096,10 @@ func ReadFileMetadata(filePath string) (string, error) {
 			result["copyright"] = meta.Copyright
 			result["composer"] = meta.Composer
 			result["comment"] = meta.Comment
+			result["replaygain_track_gain"] = meta.ReplayGainTrackGain
+			result["replaygain_track_peak"] = meta.ReplayGainTrackPeak
+			result["replaygain_album_gain"] = meta.ReplayGainAlbumGain
+			result["replaygain_album_peak"] = meta.ReplayGainAlbumPeak
 		}
 		quality, qualityErr := GetM4AQuality(filePath)
 		if qualityErr == nil {
@@ -1038,8 +1122,14 @@ func ReadFileMetadata(filePath string) (string, error) {
 			result["isrc"] = meta.ISRC
 			result["lyrics"] = meta.Lyrics
 			result["genre"] = meta.Genre
+			result["label"] = meta.Label
+			result["copyright"] = meta.Copyright
 			result["composer"] = meta.Composer
 			result["comment"] = meta.Comment
+			result["replaygain_track_gain"] = meta.ReplayGainTrackGain
+			result["replaygain_track_peak"] = meta.ReplayGainTrackPeak
+			result["replaygain_album_gain"] = meta.ReplayGainAlbumGain
+			result["replaygain_album_peak"] = meta.ReplayGainAlbumPeak
 		}
 		quality, qualityErr := GetMP3Quality(filePath)
 		if qualityErr == nil {
@@ -1063,14 +1153,49 @@ func ReadFileMetadata(filePath string) (string, error) {
 			result["isrc"] = meta.ISRC
 			result["lyrics"] = meta.Lyrics
 			result["genre"] = meta.Genre
+			result["label"] = meta.Label
+			result["copyright"] = meta.Copyright
 			result["composer"] = meta.Composer
 			result["comment"] = meta.Comment
+			result["replaygain_track_gain"] = meta.ReplayGainTrackGain
+			result["replaygain_track_peak"] = meta.ReplayGainTrackPeak
+			result["replaygain_album_gain"] = meta.ReplayGainAlbumGain
+			result["replaygain_album_peak"] = meta.ReplayGainAlbumPeak
 		}
 		quality, qualityErr := GetOggQuality(filePath)
 		if qualityErr == nil {
 			result["sample_rate"] = quality.SampleRate
 			result["duration"] = quality.Duration
 		}
+	} else if isApe || isWv || isMpc {
+		// APE, WavPack, Musepack: read APEv2 tags
+		apeTag, apeErr := ReadAPETags(filePath)
+		if apeErr == nil && apeTag != nil {
+			meta := APETagToAudioMetadata(apeTag)
+			if meta != nil {
+				result["title"] = meta.Title
+				result["artist"] = meta.Artist
+				result["album"] = meta.Album
+				result["album_artist"] = meta.AlbumArtist
+				result["date"] = meta.Date
+				if meta.Date == "" {
+					result["date"] = meta.Year
+				}
+				result["track_number"] = meta.TrackNumber
+				result["disc_number"] = meta.DiscNumber
+				result["isrc"] = meta.ISRC
+				result["lyrics"] = meta.Lyrics
+				result["genre"] = meta.Genre
+				result["label"] = meta.Label
+				result["copyright"] = meta.Copyright
+				result["composer"] = meta.Composer
+				result["comment"] = meta.Comment
+				result["replaygain_track_gain"] = meta.ReplayGainTrackGain
+				result["replaygain_track_peak"] = meta.ReplayGainTrackPeak
+				result["replaygain_album_gain"] = meta.ReplayGainAlbumGain
+				result["replaygain_album_peak"] = meta.ReplayGainAlbumPeak
+			}
+		}
 	} else {
 		return "", fmt.Errorf("unsupported file format: %s", filePath)
 	}
@@ -1083,8 +1208,7 @@ func ReadFileMetadata(filePath string) (string, error) {
 	return string(jsonBytes), nil
 }
 
-// ParseCueSheet parses a .cue file and returns JSON with split information.
-// This is called from Dart to get track listing and timing data for CUE splitting.
+// ParseCueSheet is called from Dart to get track listing and timing data for CUE splitting.
 // audioDir, if non-empty, overrides the directory used for resolving the
 // referenced audio file (useful for SAF temp file scenarios).
 func ParseCueSheet(cuePath string, audioDir string) (string, error) {
@@ -1109,9 +1233,27 @@ func ScanCueSheetForLibrary(cuePath, audioDir, virtualPathPrefix string, fileMod
 	return string(jsonBytes), nil
 }
 
-// EditFileMetadata writes metadata to an audio file.
-// For FLAC files, uses native Go FLAC library.
-// For MP3/Opus, returns the metadata map so Dart can use FFmpeg.
+func ScanCueSheetForLibraryWithCoverCacheKey(cuePath, audioDir, virtualPathPrefix string, fileModTime int64, coverCacheKey string) (string, error) {
+	scanTime := time.Now().UTC().Format(time.RFC3339)
+	results, err := ScanCueFileForLibraryExtWithCoverCacheKey(
+		cuePath,
+		audioDir,
+		virtualPathPrefix,
+		fileModTime,
+		coverCacheKey,
+		scanTime,
+	)
+	if err != nil {
+		return "[]", err
+	}
+	jsonBytes, err := json.Marshal(results)
+	if err != nil {
+		return "[]", fmt.Errorf("failed to marshal cue scan results: %w", err)
+	}
+	return string(jsonBytes), nil
+}
+
+// EditFileMetadata writes audio file tags: FLAC via native Go library, MP3/Opus returns map for Dart/FFmpeg.
 func EditFileMetadata(filePath, metadataJSON string) (string, error) {
 	var fields map[string]string
 	if err := json.Unmarshal([]byte(metadataJSON), &fields); err != nil {
@@ -1120,9 +1262,24 @@ func EditFileMetadata(filePath, metadataJSON string) (string, error) {
 
 	lower := strings.ToLower(filePath)
 	isFlac := strings.HasSuffix(lower, ".flac")
+	isApeFile := strings.HasSuffix(lower, ".ape") || strings.HasSuffix(lower, ".wv") || strings.HasSuffix(lower, ".mpc")
 	coverPath := strings.TrimSpace(fields["cover_path"])
 
 	if isFlac {
+		if err := EditFlacFields(filePath, fields); err != nil {
+			return "", fmt.Errorf("failed to write FLAC metadata: %w", err)
+		}
+
+		resp := map[string]any{
+			"success": true,
+			"method":  "native",
+		}
+		jsonBytes, _ := json.Marshal(resp)
+		return string(jsonBytes), nil
+	}
+
+	// APE/WV/MPC: write APEv2 tags natively
+	if isApeFile {
 		trackNum := 0
 		discNum := 0
 		if v, ok := fields["track_number"]; ok && v != "" {
@@ -1132,29 +1289,76 @@ func EditFileMetadata(filePath, metadataJSON string) (string, error) {
 			fmt.Sscanf(v, "%d", &discNum)
 		}
 
-		meta := Metadata{
-			Title:       fields["title"],
-			Artist:      fields["artist"],
-			Album:       fields["album"],
-			AlbumArtist: fields["album_artist"],
-			Date:        fields["date"],
-			TrackNumber: trackNum,
-			DiscNumber:  discNum,
-			ISRC:        fields["isrc"],
-			Genre:       fields["genre"],
-			Label:       fields["label"],
-			Copyright:   fields["copyright"],
-			Composer:    fields["composer"],
-			Comment:     fields["comment"],
+		meta := &AudioMetadata{
+			Title:               fields["title"],
+			Artist:              fields["artist"],
+			Album:               fields["album"],
+			AlbumArtist:         fields["album_artist"],
+			Date:                fields["date"],
+			TrackNumber:         trackNum,
+			DiscNumber:          discNum,
+			ISRC:                fields["isrc"],
+			Genre:               fields["genre"],
+			Label:               fields["label"],
+			Copyright:           fields["copyright"],
+			Composer:            fields["composer"],
+			Comment:             fields["comment"],
+			ReplayGainTrackGain: fields["replaygain_track_gain"],
+			ReplayGainTrackPeak: fields["replaygain_track_peak"],
+			ReplayGainAlbumGain: fields["replaygain_album_gain"],
+			ReplayGainAlbumPeak: fields["replaygain_album_peak"],
 		}
 
-		if err := EmbedMetadata(filePath, meta, coverPath); err != nil {
-			return "", fmt.Errorf("failed to write FLAC metadata: %w", err)
+		newItems := AudioMetadataToAPEItems(meta)
+
+		// If a cover image was provided, embed it as a binary APE item.
+		// APEv2 cover format: "cover.jpg\0<binary image data>", flagged binary.
+		if coverPath != "" {
+			coverData, coverErr := os.ReadFile(coverPath)
+			if coverErr == nil && len(coverData) > 0 {
+				// The value is "filename\0" + raw bytes.  We store the
+				// description as the Value field, but since the item is
+				// flagged binary, the writer serializes it verbatim.
+				desc := "cover.jpg\x00"
+				binaryValue := desc + string(coverData)
+				newItems = append(newItems, APETagItem{
+					Key:   "Cover Art (Front)",
+					Value: binaryValue,
+					Flags: apeItemFlagBinary,
+				})
+			}
+		}
+
+		// Build the set of APE keys that the edit explicitly controls.
+		// Even if the value is empty (user cleared the field), the old
+		// value must be removed during merge.
+		overrideKeys := apeKeysFromFields(fields)
+		if coverPath != "" {
+			overrideKeys["COVER ART (FRONT)"] = struct{}{}
+		}
+
+		// Read existing tags so we can merge rather than replace.
+		// This preserves cover art and custom items not in the edit set.
+		existingTag, _ := ReadAPETags(filePath)
+		var finalItems []APETagItem
+		if existingTag != nil && len(existingTag.Items) > 0 {
+			finalItems = MergeAPEItems(existingTag.Items, newItems, overrideKeys)
+		} else {
+			finalItems = newItems
+		}
+
+		tag := &APETag{
+			Version: apeTagVersion2,
+			Items:   finalItems,
+		}
+
+		if err := WriteAPETags(filePath, tag); err != nil {
+			return "", fmt.Errorf("failed to write APE tags: %w", err)
 		}
 
 		resp := map[string]any{
 			"success": true,
-			"method":  "native",
+			"method":  "native_ape",
 		}
 		jsonBytes, _ := json.Marshal(resp)
 		return string(jsonBytes), nil
@@ -1343,6 +1547,25 @@ func EmbedLyricsToFile(filePath, lyrics string) (string, error) {
 	return string(jsonBytes), nil
 }
 
+// RewriteSplitArtistTagsExport rewrites ARTIST and ALBUMARTIST Vorbis
+// comments in a FLAC file as multiple separate entries (one per artist).
+// Call this after FFmpeg metadata embedding to fix split artist tags,
+// since FFmpeg deduplicates -metadata keys and only keeps the last value.
+func RewriteSplitArtistTagsExport(filePath, artist, albumArtist string) (string, error) {
+	err := RewriteSplitArtistTags(filePath, artist, albumArtist)
+	if err != nil {
+		return errorResponse("Failed to rewrite artist tags: " + err.Error())
+	}
+
+	resp := map[string]interface{}{
+		"success": true,
+		"message": "Split artist tags written successfully",
+	}
+
+	jsonBytes, _ := json.Marshal(resp)
+	return string(jsonBytes), nil
+}
+
 func PreWarmTrackCacheJSON(tracksJSON string) (string, error) {
 	var tracks []struct {
 		ISRC       string `json:"isrc"`
@@ -1867,7 +2090,7 @@ func DownloadCoverToFile(coverURL string, outputPath string, maxQuality bool) er
 		return fmt.Errorf("failed to write cover file: %w", err)
 	}
 
-	GoLog("[Cover] Saved cover art to: %s (%d KB)\n", outputPath, len(data)/1024)
+	GoLog("[Cover] Downloaded cover to: %s (%d KB)\n", outputPath, len(data)/1024)
 	return nil
 }
 
@@ -1901,7 +2124,20 @@ func ExtractCoverToFile(audioPath string, outputPath string) error {
 	return nil
 }
 
-func FetchAndSaveLyrics(trackName, artistName, spotifyID string, durationMs int64, outputPath string) error {
+func FetchAndSaveLyrics(trackName, artistName, spotifyID string, durationMs int64, outputPath string, audioFilePath string) error {
+	// If the audio file already has embedded lyrics or a sidecar .lrc,
+	// use those directly instead of making redundant network requests.
+	if audioFilePath != "" {
+		existing, err := ExtractLyrics(audioFilePath)
+		if err == nil && strings.TrimSpace(existing) != "" {
+			if err := os.WriteFile(outputPath, []byte(existing), 0644); err != nil {
+				return fmt.Errorf("failed to write LRC file: %w", err)
+			}
+			GoLog("[Lyrics] Saved LRC from embedded/sidecar to: %s\n", outputPath)
+			return nil
+		}
+	}
+
 	client := NewLyricsClient()
 	durationSec := float64(durationMs) / 1000.0
 
@@ -2023,7 +2259,7 @@ func ReEnrichFile(requestJSON string) (string, error) {
 		}
 
 		// Try to get extended metadata from Deezer if not already set
-		if found && req.ISRC != "" && (req.Genre == "" || req.Label == "" || req.Copyright == "") {
+		if found && req.ISRC != "" && req.shouldUpdateField("extra") && (req.Genre == "" || req.Label == "" || req.Copyright == "") {
 			ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
 			extMeta, err := deezerClient.GetExtendedMetadataByISRC(ctx, req.ISRC)
 			cancel()
@@ -2057,7 +2293,7 @@ func ReEnrichFile(requestJSON string) (string, error) {
 	// Download cover art to temp file
 	var coverTempPath string
 	var coverDataBytes []byte
-	if req.CoverURL != "" {
+	if req.CoverURL != "" && req.shouldUpdateField("cover") {
 		coverData, err := downloadCoverToMemory(req.CoverURL, req.MaxQuality)
 		if err != nil {
 			GoLog("[ReEnrich] Failed to download cover: %v\n", err)
@@ -2107,14 +2343,16 @@ func ReEnrichFile(requestJSON string) (string, error) {
 
 	// Preserve existing lyrics when online enrichment does not return a replacement.
 	var lyricsLRC string
-	existingLyrics, existingLyricsErr := ExtractLyrics(req.FilePath)
-	if existingLyricsErr == nil && strings.TrimSpace(existingLyrics) != "" {
-		lyricsLRC = existingLyrics
-		GoLog("[ReEnrich] Preserving existing embedded/sidecar lyrics\n")
+	if req.shouldUpdateField("lyrics") {
+		existingLyrics, existingLyricsErr := ExtractLyrics(req.FilePath)
+		if existingLyricsErr == nil && strings.TrimSpace(existingLyrics) != "" {
+			lyricsLRC = existingLyrics
+			GoLog("[ReEnrich] Preserving existing embedded/sidecar lyrics\n")
+		}
 	}
 
 	// Fetch lyrics
-	if req.EmbedLyrics {
+	if req.EmbedLyrics && req.shouldUpdateField("lyrics") {
 		client := NewLyricsClient()
 		durationSec := float64(req.DurationMs) / 1000.0
 		lyrics, err := client.FetchLyricsAllSources(req.SpotifyID, req.TrackName, req.ArtistName, durationSec)
@@ -2128,38 +2366,61 @@ func ReEnrichFile(requestJSON string) (string, error) {
 		}
 	}
 
+	// Build enrichedMeta map: only include fields from selected update groups
+	// so that the caller (Dart) does not overwrite non-selected metadata in its
+	// local library database with potentially stale cached values.
 	enrichedMeta := map[string]interface{}{
-		"track_name":   req.TrackName,
-		"artist_name":  req.ArtistName,
-		"album_name":   req.AlbumName,
-		"album_artist": req.AlbumArtist,
-		"release_date": req.ReleaseDate,
-		"track_number": req.TrackNumber,
-		"disc_number":  req.DiscNumber,
-		"isrc":         req.ISRC,
-		"genre":        req.Genre,
-		"label":        req.Label,
-		"copyright":    req.Copyright,
-		"cover_url":    req.CoverURL,
-		"spotify_id":   req.SpotifyID,
-		"duration_ms":  req.DurationMs,
+		"spotify_id":  req.SpotifyID,
+		"duration_ms": req.DurationMs,
+	}
+	if req.shouldUpdateField("basic_tags") {
+		enrichedMeta["album_name"] = req.AlbumName
+		enrichedMeta["album_artist"] = req.AlbumArtist
+	}
+	if req.shouldUpdateField("track_info") {
+		enrichedMeta["track_number"] = req.TrackNumber
+		enrichedMeta["disc_number"] = req.DiscNumber
+	}
+	if req.shouldUpdateField("release_info") {
+		enrichedMeta["release_date"] = req.ReleaseDate
+		enrichedMeta["isrc"] = req.ISRC
+	}
+	if req.shouldUpdateField("cover") {
+		enrichedMeta["cover_url"] = req.CoverURL
+	}
+	if req.shouldUpdateField("extra") {
+		enrichedMeta["genre"] = req.Genre
+		enrichedMeta["label"] = req.Label
+		enrichedMeta["copyright"] = req.Copyright
 	}
 
 	if isFlac {
-		// Native Go FLAC metadata embedding
+		// Native Go FLAC metadata embedding.
+		// Only populate Metadata fields for selected update groups; empty/zero
+		// values cause EmbedMetadata's setComment() to skip those tags,
+		// preserving whatever is already in the file.
 		metadata := Metadata{
-			Title:       req.TrackName,
-			Artist:      req.ArtistName,
-			Album:       req.AlbumName,
-			AlbumArtist: req.AlbumArtist,
-			Date:        req.ReleaseDate,
-			TrackNumber: req.TrackNumber,
-			DiscNumber:  req.DiscNumber,
-			ISRC:        req.ISRC,
-			Genre:       req.Genre,
-			Label:       req.Label,
-			Copyright:   req.Copyright,
-			Lyrics:      lyricsLRC,
+			ArtistTagMode: req.ArtistTagMode,
+		}
+		if req.shouldUpdateField("basic_tags") {
+			metadata.Album = req.AlbumName
+			metadata.AlbumArtist = req.AlbumArtist
+		}
+		if req.shouldUpdateField("track_info") {
+			metadata.TrackNumber = req.TrackNumber
+			metadata.DiscNumber = req.DiscNumber
+		}
+		if req.shouldUpdateField("release_info") {
+			metadata.Date = req.ReleaseDate
+			metadata.ISRC = req.ISRC
+		}
+		if req.shouldUpdateField("lyrics") {
+			metadata.Lyrics = lyricsLRC
+		}
+		if req.shouldUpdateField("extra") {
+			metadata.Genre = req.Genre
+			metadata.Label = req.Label
+			metadata.Copyright = req.Copyright
 		}
 
 		if len(coverDataBytes) > 0 {
@@ -2195,36 +2456,14 @@ func ReEnrichFile(requestJSON string) (string, error) {
 
 	// Don't cleanup cover temp — Dart needs it for FFmpeg embed
 	cleanupCover = false
+	ffmpegMetadata := buildReEnrichFFmpegMetadata(&req, lyricsLRC)
+
 	result := map[string]interface{}{
 		"method":            "ffmpeg",
 		"cover_path":        coverTempPath,
 		"lyrics":            lyricsLRC,
 		"enriched_metadata": enrichedMeta,
-		"metadata": map[string]string{
-			"TITLE":       req.TrackName,
-			"ARTIST":      req.ArtistName,
-			"ALBUM":       req.AlbumName,
-			"ALBUMARTIST": req.AlbumArtist,
-			"DATE":        req.ReleaseDate,
-			"ISRC":        req.ISRC,
-			"GENRE":       req.Genre,
-		},
-	}
-	if req.TrackNumber > 0 {
-		result["metadata"].(map[string]string)["TRACKNUMBER"] = fmt.Sprintf("%d", req.TrackNumber)
-	}
-	if req.DiscNumber > 0 {
-		result["metadata"].(map[string]string)["DISCNUMBER"] = fmt.Sprintf("%d", req.DiscNumber)
-	}
-	if req.Label != "" {
-		result["metadata"].(map[string]string)["ORGANIZATION"] = req.Label
-	}
-	if req.Copyright != "" {
-		result["metadata"].(map[string]string)["COPYRIGHT"] = req.Copyright
-	}
-	if lyricsLRC != "" {
-		result["metadata"].(map[string]string)["LYRICS"] = lyricsLRC
-		result["metadata"].(map[string]string)["UNSYNCEDLYRICS"] = lyricsLRC
+		"metadata":          ffmpegMetadata,
 	}
 
 	jsonBytes, _ := json.Marshal(result)
@@ -2668,7 +2907,7 @@ func CustomSearchWithExtensionJSON(extensionID, query string, optionsJSON string
 			"album_name":   track.AlbumName,
 			"album_artist": track.AlbumArtist,
 			"duration_ms":  track.DurationMS,
-			"images":       track.ResolvedCoverURL(), // Use helper to get cover URL from either field
+			"images":       track.ResolvedCoverURL(),
 			"release_date": track.ReleaseDate,
 			"track_number": track.TrackNumber,
 			"disc_number":  track.DiscNumber,
@@ -2963,8 +3202,15 @@ func GetPlaylistWithExtensionJSON(extensionID, playlistID string) (string, error
 	if !ext.Manifest.IsMetadataProvider() {
 		return "", fmt.Errorf("extension '%s' is not a metadata provider", extensionID)
 	}
+	if !ext.Enabled {
+		return "", fmt.Errorf("extension '%s' is disabled", extensionID)
+	}
 
-	provider := NewExtensionProviderWrapper(ext)
+	vm, err := ext.lockReadyVM()
+	if err != nil {
+		return "", err
+	}
+	defer ext.VMMu.Unlock()
 
 	script := fmt.Sprintf(`
 		(function() {
@@ -2978,7 +3224,7 @@ func GetPlaylistWithExtensionJSON(extensionID, playlistID string) (string, error
 		})()
 	`, playlistID, playlistID)
 
-	result, err := RunWithTimeoutAndRecover(provider.vm, script, DefaultJSTimeout)
+	result, err := RunWithTimeoutAndRecover(vm, script, DefaultJSTimeout)
 	if err != nil {
 		return "", fmt.Errorf("getPlaylist failed: %w", err)
 	}
@@ -3468,3 +3714,7 @@ func ReadAudioMetadataJSON(filePath string) (string, error) {
 func ReadAudioMetadataWithHintJSON(filePath, displayName string) (string, error) {
 	return ReadAudioMetadataWithDisplayName(filePath, displayName)
 }
+
+func ReadAudioMetadataWithHintAndCoverCacheKeyJSON(filePath, displayName, coverCacheKey string) (string, error) {
+	return ReadAudioMetadataWithDisplayNameAndCoverCacheKey(filePath, displayName, coverCacheKey)
+}

go_backend/exports_test.go

@@ -177,3 +177,50 @@ func TestSelectBestReEnrichTrackPrefersCandidateWithReleaseDate(t *testing.T) {
 		t.Fatalf("selected track = %q, want candidate with release date", best.ID)
 	}
 }
+
+func TestBuildReEnrichFFmpegMetadataOmitsEmptyFields(t *testing.T) {
+	req := reEnrichRequest{
+		TrackName:   "Song",
+		ArtistName:  "Artist",
+		AlbumName:   "Album",
+		AlbumArtist: "",
+		ReleaseDate: "",
+		TrackNumber: 0,
+		DiscNumber:  0,
+		ISRC:        "",
+		Genre:       "",
+		Label:       "",
+		Copyright:   "",
+	}
+
+	metadata := buildReEnrichFFmpegMetadata(&req, "")
+
+	// Title and Artist are never written by re-enrich (they are search keys
+	// preserved as-is from the file).
+	if _, exists := metadata["TITLE"]; exists {
+		t.Fatalf("TITLE should not be in metadata: %#v", metadata)
+	}
+	if _, exists := metadata["ARTIST"]; exists {
+		t.Fatalf("ARTIST should not be in metadata: %#v", metadata)
+	}
+	if metadata["ALBUM"] != "Album" {
+		t.Fatalf("album = %q", metadata["ALBUM"])
+	}
+
+	for _, key := range []string{
+		"ALBUMARTIST",
+		"DATE",
+		"TRACKNUMBER",
+		"DISCNUMBER",
+		"ISRC",
+		"GENRE",
+		"ORGANIZATION",
+		"COPYRIGHT",
+		"LYRICS",
+		"UNSYNCEDLYRICS",
+	} {
+		if _, exists := metadata[key]; exists {
+			t.Fatalf("did not expect key %s in metadata: %#v", key, metadata)
+		}
+	}
+}

go_backend/extension_manager.go

@@ -908,6 +908,7 @@ func (m *ExtensionManager) GetInstalledExtensionsJSON() (string, error) {
 		HasDownloadProvider    bool                   `json:"has_download_provider"`
 		HasLyricsProvider      bool                   `json:"has_lyrics_provider"`
 		SkipMetadataEnrichment bool                   `json:"skip_metadata_enrichment"`
+		SkipLyrics             bool                   `json:"skip_lyrics"`
 		SearchBehavior         *SearchBehaviorConfig  `json:"search_behavior,omitempty"`
 		TrackMatching          *TrackMatchingConfig   `json:"track_matching,omitempty"`
 		PostProcessing         *PostProcessingConfig  `json:"post_processing,omitempty"`
@@ -965,6 +966,7 @@ func (m *ExtensionManager) GetInstalledExtensionsJSON() (string, error) {
 			HasDownloadProvider:    ext.Manifest.IsDownloadProvider(),
 			HasLyricsProvider:      ext.Manifest.IsLyricsProvider(),
 			SkipMetadataEnrichment: ext.Manifest.SkipMetadataEnrichment,
+			SkipLyrics:             ext.Manifest.SkipLyrics,
 			SearchBehavior:         ext.Manifest.SearchBehavior,
 			TrackMatching:          ext.Manifest.TrackMatching,
 			PostProcessing:         ext.Manifest.PostProcessing,
@@ -1044,13 +1046,14 @@ func (m *ExtensionManager) InvokeAction(extensionID string, actionName string) (
 		return nil, fmt.Errorf("extension not found: %s", extensionID)
 	}
 
-	if err := ext.ensureRuntimeReady(); err != nil {
-		return nil, err
-	}
-
 	if !ext.Enabled {
 		return nil, fmt.Errorf("extension is disabled")
 	}
+	vm, err := ext.lockReadyVM()
+	if err != nil {
+		return nil, err
+	}
+	defer ext.VMMu.Unlock()
 
 	script := fmt.Sprintf(`
 		(function() {
@@ -1070,7 +1073,7 @@ func (m *ExtensionManager) InvokeAction(extensionID string, actionName string) (
 		})()
 	`, actionName, actionName, actionName)
 
-	result, err := RunWithTimeoutAndRecover(ext.VM, script, DefaultJSTimeout)
+	result, err := RunWithTimeoutAndRecover(vm, script, DefaultJSTimeout)
 	if err != nil {
 		GoLog("[Extension] InvokeAction error for %s.%s: %v\n", extensionID, actionName, err)
 		return nil, fmt.Errorf("action failed: %v", err)

go_backend/extension_manifest.go

@@ -115,6 +115,7 @@ type ExtensionManifest struct {
 	QualityOptions         []QualityOption        `json:"qualityOptions,omitempty"`
 	MinAppVersion          string                 `json:"minAppVersion,omitempty"`
 	SkipMetadataEnrichment bool                   `json:"skipMetadataEnrichment,omitempty"`
+	SkipLyrics             bool                   `json:"skipLyrics,omitempty"`
 	SkipBuiltInFallback    bool                   `json:"skipBuiltInFallback,omitempty"`
 	SearchBehavior         *SearchBehaviorConfig  `json:"searchBehavior,omitempty"`
 	URLHandler             *URLHandlerConfig      `json:"urlHandler,omitempty"`

go_backend/extension_providers.go

@@ -1037,13 +1037,18 @@ func DownloadWithExtensionFallback(req DownloadRequest) (*DownloadResponse, erro
 					GoLog("[DownloadWithExtensionFallback] ReleaseDate from enrichment: %s\n", enrichedTrack.ReleaseDate)
 					req.ReleaseDate = enrichedTrack.ReleaseDate
 				}
+				if enrichedTrack.TrackNumber > 0 && req.TrackNumber == 0 {
+					GoLog("[DownloadWithExtensionFallback] TrackNumber from enrichment: %d\n", enrichedTrack.TrackNumber)
+					req.TrackNumber = enrichedTrack.TrackNumber
+				}
+				if enrichedTrack.DiscNumber > 0 && req.DiscNumber == 0 {
+					GoLog("[DownloadWithExtensionFallback] DiscNumber from enrichment: %d\n", enrichedTrack.DiscNumber)
+					req.DiscNumber = enrichedTrack.DiscNumber
+				}
 			}
 		}
 	}
 
-	// If key metadata is still missing after extension enrichment, search
-	// configured metadata providers (Spotify/Deezer/Tidal/Qobuz) — same
-	// logic that ReEnrichFile uses.
 	if req.Source != "" && !isBuiltInProvider(strings.ToLower(req.Source)) &&
 		req.TrackName != "" && req.ArtistName != "" &&
 		(req.AlbumName == "" || req.ReleaseDate == "" || req.ISRC == "") {
@@ -1091,7 +1096,6 @@ func DownloadWithExtensionFallback(req DownloadRequest) (*DownloadResponse, erro
 			GoLog("[DownloadWithExtensionFallback] Metadata provider search failed (non-fatal): %v\n", searchErr)
 		}
 
-		// Try Deezer extended metadata if we have ISRC
 		if req.ISRC != "" &&
 			(req.Genre == "" || req.Label == "" || req.Copyright == "") {
 			ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
@@ -1205,8 +1209,6 @@ func DownloadWithExtensionFallback(req DownloadRequest) (*DownloadResponse, erro
 					}
 				}
 
-				// Always pass enriched metadata from req so Flutter can
-				// embed it — fills gaps from metadata provider search.
 				if req.AlbumName != "" && resp.Album == "" {
 					resp.Album = req.AlbumName
 				}
@@ -1433,6 +1435,28 @@ func DownloadWithExtensionFallback(req DownloadRequest) (*DownloadResponse, erro
 					}
 				}
 
+				if req.AlbumName != "" && resp.Album == "" {
+					resp.Album = req.AlbumName
+				}
+				if req.AlbumArtist != "" && resp.AlbumArtist == "" {
+					resp.AlbumArtist = req.AlbumArtist
+				}
+				if req.ReleaseDate != "" && resp.ReleaseDate == "" {
+					resp.ReleaseDate = req.ReleaseDate
+				}
+				if req.ISRC != "" && resp.ISRC == "" {
+					resp.ISRC = req.ISRC
+				}
+				if req.TrackNumber > 0 && resp.TrackNumber == 0 {
+					resp.TrackNumber = req.TrackNumber
+				}
+				if req.DiscNumber > 0 && resp.DiscNumber == 0 {
+					resp.DiscNumber = req.DiscNumber
+				}
+				if req.CoverURL != "" && resp.CoverURL == "" {
+					resp.CoverURL = req.CoverURL
+				}
+
 				return resp, nil
 			}
 
@@ -1609,7 +1633,6 @@ func buildOutputPathForExtension(req DownloadRequest, ext *LoadedExtension) stri
 		return buildOutputPath(req)
 	}
 
-	// SAF mode: use extension's data dir as writable temp location
 	tempDir := filepath.Join(ext.DataDir, "downloads")
 	os.MkdirAll(tempDir, 0755)
 	AddAllowedDownloadDir(tempDir)
@@ -2267,7 +2290,6 @@ func (p *ExtensionProviderWrapper) FetchLyrics(trackName, artistName, albumName
 		return nil, fmt.Errorf("failed to parse lyrics result: %w", err)
 	}
 
-	// Convert ExtLyricsResult to LyricsResponse
 	response := &LyricsResponse{
 		SyncType:     extResult.SyncType,
 		Instrumental: extResult.Instrumental,
@@ -2288,7 +2310,6 @@ func (p *ExtensionProviderWrapper) FetchLyrics(trackName, artistName, albumName
 		})
 	}
 
-	// If the extension provided plainLyrics but no lines, parse them as unsynced
 	if len(response.Lines) == 0 && response.PlainLyrics != "" && !response.Instrumental {
 		response.SyncType = "UNSYNCED"
 		for _, line := range strings.Split(response.PlainLyrics, "\n") {
@@ -2316,7 +2337,6 @@ func (m *ExtensionManager) GetLyricsProviders() []*ExtensionProviderWrapper {
 		}
 	}
 
-	// Keep a deterministic order so provider selection is stable across runs.
 	sort.Slice(providers, func(i, j int) bool {
 		return providers[i].extension.ID < providers[j].extension.ID
 	})

go_backend/extension_runtime_auth.go

@@ -201,7 +201,6 @@ func (r *ExtensionRuntime) authGetTokens(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(result)
 }
 
-// Length should be between 43-128 characters (RFC 7636)
 func generatePKCEVerifier(length int) (string, error) {
 	if length < 43 {
 		length = 43
@@ -226,7 +225,6 @@ func generatePKCEVerifier(length int) (string, error) {
 
 func generatePKCEChallenge(verifier string) string {
 	hash := sha256.Sum256([]byte(verifier))
-	// Base64url encode without padding (RFC 7636)
 	return base64.RawURLEncoding.EncodeToString(hash[:])
 }
 
@@ -283,7 +281,6 @@ func (r *ExtensionRuntime) authGetPKCE(call goja.FunctionCall) goja.Value {
 	})
 }
 
-// config: { authUrl, clientId, redirectUri, scope, extraParams }
 func (r *ExtensionRuntime) authStartOAuthWithPKCE(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue(map[string]interface{}{
@@ -388,7 +385,6 @@ func (r *ExtensionRuntime) authStartOAuthWithPKCE(call goja.FunctionCall) goja.V
 	})
 }
 
-// config: { tokenUrl, clientId, redirectUri, code, extraParams }
 func (r *ExtensionRuntime) authExchangeCodeWithPKCE(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue(map[string]interface{}{

go_backend/extension_runtime_http.go

@@ -118,6 +118,7 @@ func (r *ExtensionRuntime) httpGet(call goja.FunctionCall) goja.Value {
 		"statusCode": resp.StatusCode,
 		"status":     resp.StatusCode,
 		"ok":         resp.StatusCode >= 200 && resp.StatusCode < 300,
+		"url":        resp.Request.URL.String(),
 		"body":       string(body),
 		"headers":    respHeaders,
 	})
@@ -214,6 +215,7 @@ func (r *ExtensionRuntime) httpPost(call goja.FunctionCall) goja.Value {
 		"statusCode": resp.StatusCode,
 		"status":     resp.StatusCode,
 		"ok":         resp.StatusCode >= 200 && resp.StatusCode < 300,
+		"url":        resp.Request.URL.String(),
 		"body":       string(body),
 		"headers":    respHeaders,
 	})
@@ -322,6 +324,7 @@ func (r *ExtensionRuntime) httpRequest(call goja.FunctionCall) goja.Value {
 		"statusCode": resp.StatusCode,
 		"status":     resp.StatusCode,
 		"ok":         resp.StatusCode >= 200 && resp.StatusCode < 300,
+		"url":        resp.Request.URL.String(),
 		"body":       string(body),
 		"headers":    respHeaders,
 	})
@@ -446,6 +449,7 @@ func (r *ExtensionRuntime) httpMethodShortcut(method string, call goja.FunctionC
 		"statusCode": resp.StatusCode,
 		"status":     resp.StatusCode,
 		"ok":         resp.StatusCode >= 200 && resp.StatusCode < 300,
+		"url":        resp.Request.URL.String(),
 		"body":       string(body),
 		"headers":    respHeaders,
 	})

go_backend/extension_runtime_polyfills.go

@@ -12,10 +12,6 @@ import (
 	"github.com/dop251/goja"
 )
 
-// These polyfills make porting browser/Node.js libraries easier
-// without compromising sandbox security.
-
-// Returns a Promise-like object with json(), text() methods.
 func (r *ExtensionRuntime) fetchPolyfill(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.createFetchError("URL is required")
@@ -38,7 +34,6 @@ func (r *ExtensionRuntime) fetchPolyfill(call goja.FunctionCall) goja.Value {
 				method = strings.ToUpper(m)
 			}
 
-			// Body - support string, object (auto-stringify), or nil
 			if bodyArg, ok := opts["body"]; ok && bodyArg != nil {
 				switch v := bodyArg.(type) {
 				case string:
@@ -110,7 +105,7 @@ func (r *ExtensionRuntime) fetchPolyfill(call goja.FunctionCall) goja.Value {
 	responseObj.Set("status", resp.StatusCode)
 	responseObj.Set("statusText", http.StatusText(resp.StatusCode))
 	responseObj.Set("headers", respHeaders)
-	responseObj.Set("url", urlStr)
+	responseObj.Set("url", resp.Request.URL.String())
 
 	bodyString := string(body)
 
@@ -197,7 +192,6 @@ func (r *ExtensionRuntime) registerTextEncoderDecoder(vm *goja.Runtime) {
 		})
 
 		encoder.Set("encodeInto", func(call goja.FunctionCall) goja.Value {
-			// Simplified implementation
 			if len(call.Arguments) < 2 {
 				return vm.ToValue(map[string]interface{}{"read": 0, "written": 0})
 			}
@@ -422,7 +416,6 @@ func (r *ExtensionRuntime) registerURLClass(vm *goja.Runtime) {
 	})
 }
 
-// JSON is already built-in to Goja; this ensures a fallback exists.
 func (r *ExtensionRuntime) registerJSONGlobal(vm *goja.Runtime) {
 	jsonScript := `
 		if (typeof JSON === 'undefined') {

go_backend/extension_store.go

@@ -145,7 +145,7 @@ func initExtensionStore(cacheDir string) *extensionStore {
 
 	if globalExtensionStore == nil {
 		globalExtensionStore = &extensionStore{
-			registryURL: "", // No default - user must provide a registry URL
+			registryURL: "",
 			cacheDir:    cacheDir,
 			cacheTTL:    cacheTTL,
 		}
@@ -154,8 +154,6 @@ func initExtensionStore(cacheDir string) *extensionStore {
 	return globalExtensionStore
 }
 
-// SetRegistryURL updates the registry URL and clears the in-memory cache
-// so the next fetch will use the new URL. Disk cache is also cleared.
 func (s *extensionStore) setRegistryURL(registryURL string) {
 	s.cacheMu.Lock()
 	defer s.cacheMu.Unlock()
@@ -168,7 +166,6 @@ func (s *extensionStore) setRegistryURL(registryURL string) {
 	s.cache = nil
 	s.cacheTime = time.Time{}
 
-	// Clear disk cache since it's from a different registry
 	if s.cacheDir != "" {
 		cachePath := filepath.Join(s.cacheDir, cacheFileName)
 		os.Remove(cachePath)
@@ -177,7 +174,6 @@ func (s *extensionStore) setRegistryURL(registryURL string) {
 	LogInfo("ExtensionStore", "Registry URL updated to: %s", registryURL)
 }
 
-// GetRegistryURL returns the currently configured registry URL.
 func (s *extensionStore) getRegistryURL() string {
 	s.cacheMu.RLock()
 	defer s.cacheMu.RUnlock()
@@ -378,32 +374,22 @@ func (s *extensionStore) downloadExtension(extensionID string, destPath string)
 	return nil
 }
 
-// ResolveRegistryURL normalises a user-supplied URL into a direct registry.json URL.
-//
-// Accepted formats:
-//   - https://raw.githubusercontent.com/owner/repo/<branch>/registry.json  → returned as-is
-//   - https://github.com/owner/repo  (with optional trailing path / .git)  → resolved via
-//     the GitHub API to discover the default branch, then converted to the raw URL
-//   - Any other HTTPS URL  → returned as-is (assumed to be a direct link)
 func resolveRegistryURL(input string) (string, error) {
 	input = strings.TrimSpace(input)
 	if input == "" {
 		return "", fmt.Errorf("registry URL is empty")
 	}
 
-	// Already a fully-qualified raw URL – keep it.
 	if strings.Contains(input, "raw.githubusercontent.com") {
 		return input, nil
 	}
 
 	const ghPrefix = "https://github.com/"
 	if !strings.HasPrefix(input, ghPrefix) {
-		// Also accept http:// and upgrade silently.
 		const ghPrefixHTTP = "http://github.com/"
 		if strings.HasPrefix(input, ghPrefixHTTP) {
 			input = "https://github.com/" + input[len(ghPrefixHTTP):]
 		} else {
-			// Not a GitHub URL – return as-is.
 			return input, nil
 		}
 	}
@@ -423,8 +409,6 @@ func resolveRegistryURL(input string) (string, error) {
 	return resolved, nil
 }
 
-// resolveGitHubDefaultBranch calls the GitHub API to discover the repository's
-// default branch.  Falls back to "main" on any error.
 func resolveGitHubDefaultBranch(owner, repo string) string {
 	apiURL := fmt.Sprintf("https://api.github.com/repos/%s/%s", owner, repo)
 	client := NewHTTPClientWithTimeout(10 * time.Second)

go_backend/extension_timeout.go

@@ -20,6 +20,10 @@ func (e *JSExecutionError) Error() string {
 }
 
 func RunWithTimeout(vm *goja.Runtime, script string, timeout time.Duration) (goja.Value, error) {
+	if vm == nil {
+		return nil, fmt.Errorf("extension runtime unavailable")
+	}
+
 	if timeout <= 0 {
 		timeout = DefaultJSTimeout
 	}
@@ -69,6 +73,11 @@ func RunWithTimeout(vm *goja.Runtime, script string, timeout time.Duration) (goj
 
 		vm.Interrupt("execution timeout")
 
+		// MUST wait for the goroutine to finish before returning.
+		// The Goja VM is NOT thread-safe — if we return while the goroutine
+		// is still executing JS (e.g. blocked on an HTTP call), the next
+		// caller will access the VM concurrently and crash with a nil
+		// pointer dereference.
 		select {
 		case res := <-resultCh:
 			if res.err != nil {
@@ -78,7 +87,10 @@ func RunWithTimeout(vm *goja.Runtime, script string, timeout time.Duration) (goj
 				Message:   "execution timeout exceeded",
 				IsTimeout: true,
 			}
-		case <-time.After(1 * time.Second):
+		case <-time.After(60 * time.Second):
+			// Goroutine is truly stuck (e.g. HTTP read with no timeout).
+			// Log a warning — the VM should NOT be reused after this.
+			GoLog("[ExtensionRuntime] WARNING: JS goroutine did not exit within 60s after interrupt, VM may be unsafe\n")
 			return nil, &JSExecutionError{
 				Message:   "execution timeout exceeded (force)",
 				IsTimeout: true,
@@ -92,8 +104,9 @@ func RunWithTimeout(vm *goja.Runtime, script string, timeout time.Duration) (goj
 func RunWithTimeoutAndRecover(vm *goja.Runtime, script string, timeout time.Duration) (goja.Value, error) {
 	result, err := RunWithTimeout(vm, script, timeout)
 
-	// Clear any interrupt state so VM can be reused
-	vm.ClearInterrupt()
+	if vm != nil {
+		vm.ClearInterrupt()
+	}
 
 	return result, err
 }

go_backend/go.mod

@@ -2,28 +2,28 @@ module github.com/zarz/spotiflac_android/go_backend
 
 go 1.25.0
 
-toolchain go1.25.7
+toolchain go1.25.8
 
 require (
-	github.com/dop251/goja v0.0.0-20260216154549-8b74ce4618c5
+	github.com/dop251/goja v0.0.0-20260311135729-065cd970411c
 	github.com/go-flac/flacpicture/v2 v2.0.2
 	github.com/go-flac/flacvorbis/v2 v2.0.2
 	github.com/go-flac/go-flac/v2 v2.0.4
 	github.com/refraction-networking/utls v1.8.2
-	golang.org/x/mobile v0.0.0-20260211191516-dcd2a3258864
-	golang.org/x/net v0.50.0
-	golang.org/x/text v0.34.0
+	golang.org/x/mobile v0.0.0-20260312152759-81488f6aeb60
+	golang.org/x/net v0.52.0
+	golang.org/x/text v0.35.0
 )
 
 require (
-	github.com/andybalholm/brotli v1.0.6 // indirect
-	github.com/dlclark/regexp2 v1.11.4 // indirect
-	github.com/go-sourcemap/sourcemap v2.1.3+incompatible // indirect
-	github.com/google/pprof v0.0.0-20230207041349-798e818bf904 // indirect
-	github.com/klauspost/compress v1.17.4 // indirect
-	golang.org/x/crypto v0.48.0 // indirect
-	golang.org/x/mod v0.33.0 // indirect
-	golang.org/x/sync v0.19.0 // indirect
-	golang.org/x/sys v0.41.0 // indirect
-	golang.org/x/tools v0.42.0 // indirect
+	github.com/andybalholm/brotli v1.2.0 // indirect
+	github.com/dlclark/regexp2 v1.11.5 // indirect
+	github.com/go-sourcemap/sourcemap v2.1.4+incompatible // indirect
+	github.com/google/pprof v0.0.0-20260302011040-a15ffb7f9dcc // indirect
+	github.com/klauspost/compress v1.18.5 // indirect
+	golang.org/x/crypto v0.49.0 // indirect
+	golang.org/x/mod v0.34.0 // indirect
+	golang.org/x/sync v0.20.0 // indirect
+	golang.org/x/sys v0.42.0 // indirect
+	golang.org/x/tools v0.43.0 // indirect
 )

go_backend/go.sum

@@ -1,49 +1,51 @@
 github.com/Masterminds/semver/v3 v3.2.1 h1:RN9w6+7QoMeJVGyfmbcgs28Br8cvmnucEXnY0rYXWg0=
 github.com/Masterminds/semver/v3 v3.2.1/go.mod h1:qvl/7zhW3nngYb5+80sSMF+FG2BjYrf8m9wsX0PNOMQ=
-github.com/andybalholm/brotli v1.0.6 h1:Yf9fFpf49Zrxb9NlQaluyE92/+X7UVHlhMNJN2sxfOI=
-github.com/andybalholm/brotli v1.0.6/go.mod h1:fO7iG3H7G2nSZ7m0zPUDn85XEX2GTukHGRSepvi9Eig=
+github.com/andybalholm/brotli v1.2.0 h1:ukwgCxwYrmACq68yiUqwIWnGY0cTPox/M94sVwToPjQ=
+github.com/andybalholm/brotli v1.2.0/go.mod h1:rzTDkvFWvIrjDXZHkuS16NPggd91W3kUSvPlQ1pLaKY=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
-github.com/dlclark/regexp2 v1.11.4 h1:rPYF9/LECdNymJufQKmri9gV604RvvABwgOA8un7yAo=
-github.com/dlclark/regexp2 v1.11.4/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8=
-github.com/dop251/goja v0.0.0-20260216154549-8b74ce4618c5 h1:QckvTXtu55YMopmVeDrPQ/r+T6xjw8KMCmE3UgUldkw=
-github.com/dop251/goja v0.0.0-20260216154549-8b74ce4618c5/go.mod h1:MxLav0peU43GgvwVgNbLAj1s/bSGboKkhuULvq/7hx4=
+github.com/dlclark/regexp2 v1.11.5 h1:Q/sSnsKerHeCkc/jSTNq1oCm7KiVgUMZRDUoRu0JQZQ=
+github.com/dlclark/regexp2 v1.11.5/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8=
+github.com/dop251/goja v0.0.0-20260311135729-065cd970411c h1:OcLmPfx1T1RmZVHHFwWMPaZDdRf0DBMZOFMVWJa7Pdk=
+github.com/dop251/goja v0.0.0-20260311135729-065cd970411c/go.mod h1:MxLav0peU43GgvwVgNbLAj1s/bSGboKkhuULvq/7hx4=
 github.com/go-flac/flacpicture/v2 v2.0.2 h1:HCaJIVZpxnpdWs6G3ECEVRelzqS5xOi1Ba1AGmtXbzE=
 github.com/go-flac/flacpicture/v2 v2.0.2/go.mod h1:DMZBPWPAmdLqNhqFSy5ZBs9wyBzOekXutGfP7/TFCuo=
 github.com/go-flac/flacvorbis/v2 v2.0.2 h1:xCL3OhxrxWkHrbWUBvGNe+6FQ03yLmBbz0v5z4V2PoQ=
 github.com/go-flac/flacvorbis/v2 v2.0.2/go.mod h1:SwTB5gs13VaM/N7rstwPoUsPibiMKklgwybYP9dYo2g=
 github.com/go-flac/go-flac/v2 v2.0.4 h1:atf/kFa8U9idtkA//NO22XGr+MzQLeXZecnmP9sYBf0=
 github.com/go-flac/go-flac/v2 v2.0.4/go.mod h1:sYOlTKxutMW0RDYF+KlD6Zn+VOCZlIFQG/r/usPveCs=
-github.com/go-sourcemap/sourcemap v2.1.3+incompatible h1:W1iEw64niKVGogNgBN3ePyLFfuisuzeidWPMPWmECqU=
-github.com/go-sourcemap/sourcemap v2.1.3+incompatible/go.mod h1:F8jJfvm2KbVjc5NqelyYJmf/v5J0dwNLS2mL4sNA1Jg=
+github.com/go-sourcemap/sourcemap v2.1.4+incompatible h1:a+iTbH5auLKxaNwQFg0B+TCYl6lbukKPc7b5x0n1s6Q=
+github.com/go-sourcemap/sourcemap v2.1.4+incompatible/go.mod h1:F8jJfvm2KbVjc5NqelyYJmf/v5J0dwNLS2mL4sNA1Jg=
 github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
 github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
-github.com/google/pprof v0.0.0-20230207041349-798e818bf904 h1:4/hN5RUoecvl+RmJRE2YxKWtnnQls6rQjjW5oV7qg2U=
-github.com/google/pprof v0.0.0-20230207041349-798e818bf904/go.mod h1:uglQLonpP8qtYCYyzA+8c/9qtqgA3qsXGYqCPKARAFg=
-github.com/klauspost/compress v1.17.4 h1:Ej5ixsIri7BrIjBkRZLTo6ghwrEtHFk7ijlczPW4fZ4=
-github.com/klauspost/compress v1.17.4/go.mod h1:/dCuZOvVtNoHsyb+cuJD3itjs3NbnF6KH9zAO4BDxPM=
+github.com/google/pprof v0.0.0-20260302011040-a15ffb7f9dcc h1:VBbFa1lDYWEeV5FZKUiYKYT0VxCp9twUmmaq9eb8sXw=
+github.com/google/pprof v0.0.0-20260302011040-a15ffb7f9dcc/go.mod h1:MxpfABSjhmINe3F1It9d+8exIHFvUqtLIRCdOGNXqiI=
+github.com/klauspost/compress v1.18.5 h1:/h1gH5Ce+VWNLSWqPzOVn6XBO+vJbCNGvjoaGBFW2IE=
+github.com/klauspost/compress v1.18.5/go.mod h1:cwPg85FWrGar70rWktvGQj8/hthj3wpl0PGDogxkrSQ=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/refraction-networking/utls v1.8.2 h1:j4Q1gJj0xngdeH+Ox/qND11aEfhpgoEvV+S9iJ2IdQo=
 github.com/refraction-networking/utls v1.8.2/go.mod h1:jkSOEkLqn+S/jtpEHPOsVv/4V4EVnelwbMQl4vCWXAM=
 github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA=
 github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
-golang.org/x/crypto v0.48.0 h1:/VRzVqiRSggnhY7gNRxPauEQ5Drw9haKdM0jqfcCFts=
-golang.org/x/crypto v0.48.0/go.mod h1:r0kV5h3qnFPlQnBSrULhlsRfryS2pmewsg+XfMgkVos=
-golang.org/x/mobile v0.0.0-20260211191516-dcd2a3258864 h1:cTVynMSsMYgbUrtia2HB1jrhdUwQNtQti91vUCyjMp4=
-golang.org/x/mobile v0.0.0-20260211191516-dcd2a3258864/go.mod h1:4OGHIUSBiIqyFAQDaX1tpY0BVnO20DvNDeATBu8aeFQ=
-golang.org/x/mod v0.33.0 h1:tHFzIWbBifEmbwtGz65eaWyGiGZatSrT9prnU8DbVL8=
-golang.org/x/mod v0.33.0/go.mod h1:swjeQEj+6r7fODbD2cqrnje9PnziFuw4bmLbBZFrQ5w=
-golang.org/x/net v0.50.0 h1:ucWh9eiCGyDR3vtzso0WMQinm2Dnt8cFMuQa9K33J60=
-golang.org/x/net v0.50.0/go.mod h1:UgoSli3F/pBgdJBHCTc+tp3gmrU4XswgGRgtnwWTfyM=
-golang.org/x/sync v0.19.0 h1:vV+1eWNmZ5geRlYjzm2adRgW2/mcpevXNg50YZtPCE4=
-golang.org/x/sync v0.19.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
-golang.org/x/sys v0.41.0 h1:Ivj+2Cp/ylzLiEU89QhWblYnOE9zerudt9Ftecq2C6k=
-golang.org/x/sys v0.41.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
-golang.org/x/text v0.34.0 h1:oL/Qq0Kdaqxa1KbNeMKwQq0reLCCaFtqu2eNuSeNHbk=
-golang.org/x/text v0.34.0/go.mod h1:homfLqTYRFyVYemLBFl5GgL/DWEiH5wcsQ5gSh1yziA=
-golang.org/x/tools v0.42.0 h1:uNgphsn75Tdz5Ji2q36v/nsFSfR/9BRFvqhGBaJGd5k=
-golang.org/x/tools v0.42.0/go.mod h1:Ma6lCIwGZvHK6XtgbswSoWroEkhugApmsXyrUmBhfr0=
+github.com/xyproto/randomstring v1.0.5 h1:YtlWPoRdgMu3NZtP45drfy1GKoojuR7hmRcnhZqKjWU=
+github.com/xyproto/randomstring v1.0.5/go.mod h1:rgmS5DeNXLivK7YprL0pY+lTuhNQW3iGxZ18UQApw/E=
+golang.org/x/crypto v0.49.0 h1:+Ng2ULVvLHnJ/ZFEq4KdcDd/cfjrrjjNSXNzxg0Y4U4=
+golang.org/x/crypto v0.49.0/go.mod h1:ErX4dUh2UM+CFYiXZRTcMpEcN8b/1gxEuv3nODoYtCA=
+golang.org/x/mobile v0.0.0-20260312152759-81488f6aeb60 h1:MOzyaj0wu2xneBkzkg9LHNYjDBB4W5vP043A2SYQRPA=
+golang.org/x/mobile v0.0.0-20260312152759-81488f6aeb60/go.mod h1:th6VJvzjMbrYF8SduQY5rpD0HG0GleGxjadkqSxFs3k=
+golang.org/x/mod v0.34.0 h1:xIHgNUUnW6sYkcM5Jleh05DvLOtwc6RitGHbDk4akRI=
+golang.org/x/mod v0.34.0/go.mod h1:ykgH52iCZe79kzLLMhyCUzhMci+nQj+0XkbXpNYtVjY=
+golang.org/x/net v0.52.0 h1:He/TN1l0e4mmR3QqHMT2Xab3Aj3L9qjbhRm78/6jrW0=
+golang.org/x/net v0.52.0/go.mod h1:R1MAz7uMZxVMualyPXb+VaqGSa3LIaUqk0eEt3w36Sw=
+golang.org/x/sync v0.20.0 h1:e0PTpb7pjO8GAtTs2dQ6jYa5BWYlMuX047Dco/pItO4=
+golang.org/x/sync v0.20.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
+golang.org/x/sys v0.42.0 h1:omrd2nAlyT5ESRdCLYdm3+fMfNFE/+Rf4bDIQImRJeo=
+golang.org/x/sys v0.42.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/text v0.35.0 h1:JOVx6vVDFokkpaq1AEptVzLTpDe9KGpj5tR4/X+ybL8=
+golang.org/x/text v0.35.0/go.mod h1:khi/HExzZJ2pGnjenulevKNX1W67CUy0AsXcNubPGCA=
+golang.org/x/tools v0.43.0 h1:12BdW9CeB3Z+J/I/wj34VMl8X+fEXBxVR90JeMX5E7s=
+golang.org/x/tools v0.43.0/go.mod h1:uHkMso649BX2cZK6+RpuIPXS3ho2hZo4FVwfoy1vIk0=
 gopkg.in/yaml.v2 v2.4.0 h1:D8xgwECY7CYvx+Y2n4sBz93Jn9JRvxdiyyo8CTfuKaY=
 gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=

go_backend/httputil.go

@@ -66,9 +66,6 @@ var sharedTransport = &http.Transport{
 	DisableCompression:    true,
 }
 
-// metadataTransport is a separate transport for metadata API calls (Deezer, Spotify, SongLink).
-// Isolated from download traffic so that download failures cannot poison
-// the connection pool used by metadata enrichment.
 var metadataTransport = &http.Transport{
 	DialContext: (&net.Dialer{
 		Timeout:   30 * time.Second,
@@ -104,8 +101,6 @@ func NewHTTPClientWithTimeout(timeout time.Duration) *http.Client {
 	}
 }
 
-// NewMetadataHTTPClient creates an HTTP client using the isolated metadata transport.
-// Use this for API calls that should not be affected by download traffic.
 func NewMetadataHTTPClient(timeout time.Duration) *http.Client {
 	return &http.Client{
 		Transport: newCompatibilityTransport(metadataTransport),
@@ -229,7 +224,6 @@ func cloneRequestWithHTTPScheme(req *http.Request, scheme string) (*http.Request
 	return reqCopy, nil
 }
 
-// Also checks for ISP blocking on errors
 func DoRequestWithUserAgent(client *http.Client, req *http.Request) (*http.Response, error) {
 	req.Header.Set("User-Agent", getRandomUserAgent())
 	resp, err := client.Do(req)
@@ -239,7 +233,6 @@ func DoRequestWithUserAgent(client *http.Client, req *http.Request) (*http.Respo
 	return resp, err
 }
 
-// RetryConfig holds configuration for retry logic
 type RetryConfig struct {
 	MaxRetries    int
 	InitialDelay  time.Duration

go_backend/httputil_ios.go

@@ -6,17 +6,10 @@ import (
 	"net/http"
 )
 
-// iOS version: uTLS is not supported on iOS due to cgo DNS resolver issues
-// Fall back to standard HTTP client
-
-// GetCloudflareBypassClient returns the standard HTTP client on iOS
-// uTLS is not available on iOS due to cgo DNS resolver compatibility issues
 func GetCloudflareBypassClient() *http.Client {
 	return sharedClient
 }
 
-// DoRequestWithCloudflareBypass on iOS just uses the standard client
-// uTLS Chrome fingerprint bypass is not available on iOS
 func DoRequestWithCloudflareBypass(req *http.Request) (*http.Response, error) {
 	req.Header.Set("User-Agent", getRandomUserAgent())
 	resp, err := sharedClient.Do(req)

go_backend/httputil_utls.go

@@ -16,8 +16,6 @@ import (
 	"golang.org/x/net/http2"
 )
 
-// uTLS transport that mimics Chrome's TLS fingerprint to bypass Cloudflare
-// Uses HTTP/2 for optimal performance as uTLS works best with HTTP/2
 type utlsTransport struct {
 	dialer       *net.Dialer
 	mu           sync.Mutex
@@ -98,15 +96,10 @@ var cloudflareBypassClient = &http.Client{
 	Timeout:   DefaultTimeout,
 }
 
-// GetCloudflareBypassClient returns an HTTP client that mimics Chrome's TLS fingerprint
-// Use this when requests are blocked by Cloudflare (common when using VPN)
 func GetCloudflareBypassClient() *http.Client {
 	return cloudflareBypassClient
 }
 
-// DoRequestWithCloudflareBypass attempts request with standard client first,
-// then retries with uTLS Chrome fingerprint if Cloudflare blocks it.
-// This is useful when using VPN as Cloudflare detects Go's default TLS fingerprint.
 func DoRequestWithCloudflareBypass(req *http.Request) (*http.Response, error) {
 	req.Header.Set("User-Agent", getRandomUserAgent())
 
@@ -142,7 +135,6 @@ func DoRequestWithCloudflareBypass(req *http.Request) (*http.Response, error) {
 				}
 			}
 
-			// Not Cloudflare, return original response (recreate body)
 			return &http.Response{
 				Status:     resp.Status,
 				StatusCode: resp.StatusCode,

go_backend/idhs.go

@@ -10,8 +10,6 @@ import (
 	"time"
 )
 
-// IDHSClient is a client for I Don't Have Spotify API
-// Used as fallback when SongLink fails or is rate limited
 type IDHSClient struct {
 	client *http.Client
 }
@@ -55,7 +53,6 @@ func NewIDHSClient() *IDHSClient {
 	return globalIDHSClient
 }
 
-// Search converts a music link to links on other platforms
 func (c *IDHSClient) Search(link string, adapters []string) (*IDHSSearchResponse, error) {
 	idhsRateLimiter.WaitForSlot()
 
@@ -109,7 +106,6 @@ func (c *IDHSClient) Search(link string, adapters []string) (*IDHSSearchResponse
 	return &result, nil
 }
 
-// GetAvailabilityFromSpotify checks track availability using IDHS as fallback
 func (c *IDHSClient) GetAvailabilityFromSpotify(spotifyTrackID string) (*TrackAvailability, error) {
 	spotifyURL := fmt.Sprintf("https://open.spotify.com/track/%s", spotifyTrackID)
 

go_backend/library_scan.go

@@ -13,25 +13,26 @@ import (
 )
 
 type LibraryScanResult struct {
-	ID          string `json:"id"`
-	TrackName   string `json:"trackName"`
-	ArtistName  string `json:"artistName"`
-	AlbumName   string `json:"albumName"`
-	AlbumArtist string `json:"albumArtist,omitempty"`
-	FilePath    string `json:"filePath"`
-	CoverPath   string `json:"coverPath,omitempty"`
-	ScannedAt   string `json:"scannedAt"`
-	FileModTime int64  `json:"fileModTime,omitempty"` // Unix timestamp in milliseconds
-	ISRC        string `json:"isrc,omitempty"`
-	TrackNumber int    `json:"trackNumber,omitempty"`
-	DiscNumber  int    `json:"discNumber,omitempty"`
-	Duration    int    `json:"duration,omitempty"`
-	ReleaseDate string `json:"releaseDate,omitempty"`
-	BitDepth    int    `json:"bitDepth,omitempty"`
-	SampleRate  int    `json:"sampleRate,omitempty"`
-	Bitrate     int    `json:"bitrate,omitempty"` // kbps, for lossy formats (MP3, Opus, Vorbis)
-	Genre       string `json:"genre,omitempty"`
-	Format      string `json:"format,omitempty"`
+	ID                   string `json:"id"`
+	TrackName            string `json:"trackName"`
+	ArtistName           string `json:"artistName"`
+	AlbumName            string `json:"albumName"`
+	AlbumArtist          string `json:"albumArtist,omitempty"`
+	FilePath             string `json:"filePath"`
+	CoverPath            string `json:"coverPath,omitempty"`
+	ScannedAt            string `json:"scannedAt"`
+	FileModTime          int64  `json:"fileModTime,omitempty"` // Unix timestamp in milliseconds
+	ISRC                 string `json:"isrc,omitempty"`
+	TrackNumber          int    `json:"trackNumber,omitempty"`
+	DiscNumber           int    `json:"discNumber,omitempty"`
+	Duration             int    `json:"duration,omitempty"`
+	ReleaseDate          string `json:"releaseDate,omitempty"`
+	BitDepth             int    `json:"bitDepth,omitempty"`
+	SampleRate           int    `json:"sampleRate,omitempty"`
+	Bitrate              int    `json:"bitrate,omitempty"` // kbps, for lossy formats (MP3, Opus, Vorbis)
+	Genre                string `json:"genre,omitempty"`
+	Format               string `json:"format,omitempty"`
+	MetadataFromFilename bool   `json:"metadataFromFilename,omitempty"`
 }
 
 type LibraryScanProgress struct {
@@ -65,6 +66,9 @@ var supportedAudioFormats = map[string]bool{
 	".mp3":  true,
 	".opus": true,
 	".ogg":  true,
+	".ape":  true,
+	".wv":   true,
+	".mpc":  true,
 	".cue":  true,
 }
 
@@ -169,11 +173,9 @@ func ScanLibraryFolder(folderPath string) (string, error) {
 	scanTime := time.Now().UTC().Format(time.RFC3339)
 	errorCount := 0
 
-	// Track audio files referenced by .cue sheets to avoid duplicates
 	cueReferencedAudioFiles := make(map[string]bool)
 	parsedCueFiles := make(map[string]scannedCueFileInfo)
 
-	// First pass: scan .cue files to collect referenced audio paths
 	for _, fileInfo := range audioFileInfos {
 		filePath := fileInfo.path
 		ext := strings.ToLower(filepath.Ext(filePath))
@@ -208,7 +210,6 @@ func ScanLibraryFolder(folderPath string) (string, error) {
 
 		ext := strings.ToLower(filepath.Ext(filePath))
 
-		// Handle .cue files: produce multiple track results
 		if ext == ".cue" {
 			var cueResults []LibraryScanResult
 			cueInfo, ok := parsedCueFiles[filePath]
@@ -219,6 +220,7 @@ func ScanLibraryFolder(folderPath string) (string, error) {
 					cueInfo.audioPath,
 					"",
 					fileInfo.modTime,
+					"",
 					scanTime,
 				)
 			} else {
@@ -269,10 +271,14 @@ func scanAudioFile(filePath, scanTime string) (*LibraryScanResult, error) {
 }
 
 func scanAudioFileWithKnownModTime(filePath, scanTime string, knownModTime int64) (*LibraryScanResult, error) {
-	return scanAudioFileWithKnownModTimeAndDisplayName(filePath, "", scanTime, knownModTime)
+	return scanAudioFileWithKnownModTimeAndDisplayNameAndCoverCacheKey(filePath, "", "", scanTime, knownModTime)
 }
 
 func scanAudioFileWithKnownModTimeAndDisplayName(filePath, displayNameHint, scanTime string, knownModTime int64) (*LibraryScanResult, error) {
+	return scanAudioFileWithKnownModTimeAndDisplayNameAndCoverCacheKey(filePath, displayNameHint, "", scanTime, knownModTime)
+}
+
+func scanAudioFileWithKnownModTimeAndDisplayNameAndCoverCacheKey(filePath, displayNameHint, coverCacheKey, scanTime string, knownModTime int64) (*LibraryScanResult, error) {
 	ext := resolveLibraryAudioExt(filePath, displayNameHint)
 
 	result := &LibraryScanResult{
@@ -292,7 +298,12 @@ func scanAudioFileWithKnownModTimeAndDisplayName(filePath, displayNameHint, scan
 	coverCacheDir := libraryCoverCacheDir
 	libraryCoverCacheMu.RUnlock()
 	if coverCacheDir != "" {
-		coverPath, err := SaveCoverToCacheWithHint(filePath, displayNameHint, coverCacheDir)
+		coverPath, err := SaveCoverToCacheWithHintAndKey(
+			filePath,
+			displayNameHint,
+			coverCacheDir,
+			coverCacheKey,
+		)
 		if err == nil && coverPath != "" {
 			result.CoverPath = coverPath
 		}
@@ -300,13 +311,15 @@ func scanAudioFileWithKnownModTimeAndDisplayName(filePath, displayNameHint, scan
 
 	switch ext {
 	case ".flac":
-		return scanFLACFile(filePath, result)
+		return scanFLACFile(filePath, result, displayNameHint)
 	case ".m4a":
-		return scanM4AFile(filePath, result)
+		return scanM4AFile(filePath, result, displayNameHint)
 	case ".mp3":
-		return scanMP3File(filePath, result)
+		return scanMP3File(filePath, result, displayNameHint)
 	case ".opus", ".ogg":
 		return scanOggFile(filePath, result, displayNameHint)
+	case ".ape", ".wv", ".mpc":
+		return scanAPEFile(filePath, result, displayNameHint)
 	default:
 		return scanFromFilename(filePath, displayNameHint, result)
 	}
@@ -340,10 +353,10 @@ func applyDefaultLibraryMetadata(filePath, displayNameHint string, result *Libra
 	}
 }
 
-func scanFLACFile(filePath string, result *LibraryScanResult) (*LibraryScanResult, error) {
+func scanFLACFile(filePath string, result *LibraryScanResult, displayNameHint string) (*LibraryScanResult, error) {
 	metadata, err := ReadMetadata(filePath)
 	if err != nil {
-		return scanFromFilename(filePath, "", result)
+		return scanFromFilename(filePath, displayNameHint, result)
 	}
 
 	result.TrackName = metadata.Title
@@ -365,14 +378,19 @@ func scanFLACFile(filePath string, result *LibraryScanResult) (*LibraryScanResul
 		}
 	}
 
-	applyDefaultLibraryMetadata(filePath, "", result)
+	applyDefaultLibraryMetadata(filePath, displayNameHint, result)
 
 	return result, nil
 }
 
-func scanM4AFile(filePath string, result *LibraryScanResult) (*LibraryScanResult, error) {
+func scanM4AFile(filePath string, result *LibraryScanResult, displayNameHint string) (*LibraryScanResult, error) {
 	metadata, err := ReadM4ATags(filePath)
-	if err == nil && metadata != nil {
+	if err != nil {
+		GoLog("[LibraryScan] M4A read error for %s: %v\n", filePath, err)
+		return scanFromFilename(filePath, displayNameHint, result)
+	}
+
+	if metadata != nil {
 		result.TrackName = metadata.Title
 		result.ArtistName = metadata.Artist
 		result.AlbumName = metadata.Album
@@ -393,15 +411,15 @@ func scanM4AFile(filePath string, result *LibraryScanResult) (*LibraryScanResult
 		result.SampleRate = quality.SampleRate
 	}
 
-	applyDefaultLibraryMetadata(filePath, "", result)
+	applyDefaultLibraryMetadata(filePath, displayNameHint, result)
 	return result, nil
 }
 
-func scanMP3File(filePath string, result *LibraryScanResult) (*LibraryScanResult, error) {
+func scanMP3File(filePath string, result *LibraryScanResult, displayNameHint string) (*LibraryScanResult, error) {
 	metadata, err := ReadID3Tags(filePath)
 	if err != nil {
 		GoLog("[LibraryScan] ID3 read error for %s: %v\n", filePath, err)
-		return scanFromFilename(filePath, "", result)
+		return scanFromFilename(filePath, displayNameHint, result)
 	}
 
 	result.TrackName = metadata.Title
@@ -428,7 +446,7 @@ func scanMP3File(filePath string, result *LibraryScanResult) (*LibraryScanResult
 		}
 	}
 
-	applyDefaultLibraryMetadata(filePath, "", result)
+	applyDefaultLibraryMetadata(filePath, displayNameHint, result)
 
 	return result, nil
 }
@@ -465,7 +483,39 @@ func scanOggFile(filePath string, result *LibraryScanResult, displayNameHint str
 	return result, nil
 }
 
+func scanAPEFile(filePath string, result *LibraryScanResult, displayNameHint string) (*LibraryScanResult, error) {
+	tag, err := ReadAPETags(filePath)
+	if err != nil {
+		GoLog("[LibraryScan] APE tag read error for %s: %v\n", filePath, err)
+		return scanFromFilename(filePath, displayNameHint, result)
+	}
+
+	metadata := APETagToAudioMetadata(tag)
+	if metadata == nil {
+		return scanFromFilename(filePath, displayNameHint, result)
+	}
+
+	result.TrackName = metadata.Title
+	result.ArtistName = metadata.Artist
+	result.AlbumName = metadata.Album
+	result.AlbumArtist = metadata.AlbumArtist
+	result.ISRC = metadata.ISRC
+	result.TrackNumber = metadata.TrackNumber
+	result.DiscNumber = metadata.DiscNumber
+	result.Genre = metadata.Genre
+	if metadata.Date != "" {
+		result.ReleaseDate = metadata.Date
+	} else {
+		result.ReleaseDate = metadata.Year
+	}
+
+	applyDefaultLibraryMetadata(filePath, displayNameHint, result)
+
+	return result, nil
+}
+
 func scanFromFilename(filePath, displayNameHint string, result *LibraryScanResult) (*LibraryScanResult, error) {
+	result.MetadataFromFilename = true
 	nameSource := libraryDisplayNameOrPath(filePath, displayNameHint)
 	filename := strings.TrimSuffix(filepath.Base(nameSource), filepath.Ext(nameSource))
 
@@ -541,8 +591,18 @@ func ReadAudioMetadata(filePath string) (string, error) {
 }
 
 func ReadAudioMetadataWithDisplayName(filePath, displayNameHint string) (string, error) {
+	return ReadAudioMetadataWithDisplayNameAndCoverCacheKey(filePath, displayNameHint, "")
+}
+
+func ReadAudioMetadataWithDisplayNameAndCoverCacheKey(filePath, displayNameHint, coverCacheKey string) (string, error) {
 	scanTime := time.Now().UTC().Format(time.RFC3339)
-	result, err := scanAudioFileWithKnownModTimeAndDisplayName(filePath, displayNameHint, scanTime, 0)
+	result, err := scanAudioFileWithKnownModTimeAndDisplayNameAndCoverCacheKey(
+		filePath,
+		displayNameHint,
+		coverCacheKey,
+		scanTime,
+		0,
+	)
 	if err != nil {
 		return "", err
 	}
@@ -746,6 +806,7 @@ func scanLibraryFolderIncrementalWithExistingFiles(folderPath string, existingFi
 					cueInfo.audioPath,
 					"",
 					f.modTime,
+					"",
 					scanTime,
 				)
 			} else {
@@ -799,9 +860,6 @@ func scanLibraryFolderIncrementalWithExistingFiles(folderPath string, existingFi
 	return string(jsonBytes), nil
 }
 
-// ScanLibraryFolderIncremental performs an incremental scan of the library folder
-// existingFilesJSON is a JSON object mapping filePath -> modTime (unix millis)
-// Only files that are new or have changed modification time will be scanned
 func ScanLibraryFolderIncremental(folderPath, existingFilesJSON string) (string, error) {
 	existingFiles := make(map[string]int64)
 	if existingFilesJSON != "" && existingFilesJSON != "{}" {

go_backend/library_scan_test.go

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

go_backend/logbuffer.go

@@ -25,7 +25,6 @@ type LogBuffer struct {
 
 const (
 	defaultLogBufferSize = 500
-	maxLogMessageLength  = 500
 )
 
 var (
@@ -52,20 +51,12 @@ func GetLogBuffer() *LogBuffer {
 		globalLogBuffer = &LogBuffer{
 			entries:        make([]LogEntry, 0, defaultLogBufferSize),
 			maxSize:        defaultLogBufferSize,
-			loggingEnabled: false, // Default: disabled for performance (user can enable in settings)
+			loggingEnabled: false,
 		}
 	})
 	return globalLogBuffer
 }
 
-func truncateLogMessage(message string) string {
-	runes := []rune(message)
-	if len(runes) <= maxLogMessageLength {
-		return message
-	}
-	return string(runes[:maxLogMessageLength]) + "...[truncated]"
-}
-
 func (lb *LogBuffer) SetLoggingEnabled(enabled bool) {
 	lb.mu.Lock()
 	defer lb.mu.Unlock()
@@ -87,7 +78,6 @@ func (lb *LogBuffer) Add(level, tag, message string) {
 	}
 
 	message = sanitizeSensitiveLogText(message)
-	message = truncateLogMessage(message)
 
 	entry := LogEntry{
 		Timestamp: time.Now().Format("15:04:05.000"),
@@ -155,13 +145,10 @@ func LogError(tag, format string, args ...interface{}) {
 	GetLogBuffer().Add("ERROR", tag, fmt.Sprintf(format, args...))
 }
 
-// GoLog is a drop-in replacement for fmt.Printf that also logs to buffer
-// It parses the tag from the format string if it starts with [Tag]
 func GoLog(format string, args ...interface{}) {
 	message := fmt.Sprintf(format, args...)
 	message = strings.TrimSuffix(message, "\n")
 
-	// Extract tag from message if present (e.g., "[Tidal] message")
 	tag := "Go"
 	level := "INFO"
 
@@ -173,7 +160,6 @@ func GoLog(format string, args ...interface{}) {
 		}
 	}
 
-	// Determine level from message content
 	msgLower := strings.ToLower(message)
 	if strings.Contains(msgLower, "error") || strings.Contains(msgLower, "failed") {
 		level = "ERROR"

go_backend/lyrics.go

@@ -3,7 +3,6 @@ package gobackend
 import (
 	"encoding/json"
 	"fmt"
-	"io"
 	"math"
 	"net/http"
 	"net/url"
@@ -21,9 +20,7 @@ const (
 	durationToleranceSec = 10.0
 )
 
-// Lyrics provider names (used in settings and cascade ordering)
 const (
-	LyricsProviderSpotifyAPI = "spotify_api"
 	LyricsProviderLRCLIB     = "lrclib"
 	LyricsProviderNetease    = "netease"
 	LyricsProviderMusixmatch = "musixmatch"
@@ -31,11 +28,8 @@ const (
 	LyricsProviderQQMusic    = "qqmusic"
 )
 
-// DefaultLyricsProviders is the default cascade order for lyrics fetching.
-// LRCLIB first (no proxy dependency), then the others.
 var DefaultLyricsProviders = []string{
 	LyricsProviderLRCLIB,
-	LyricsProviderSpotifyAPI,
 	LyricsProviderMusixmatch,
 	LyricsProviderNetease,
 	LyricsProviderAppleMusic,
@@ -47,12 +41,6 @@ var (
 	lyricsProviders   []string // ordered list of enabled providers
 )
 
-var (
-	spotifyLyricsRateLimitMu    sync.RWMutex
-	spotifyLyricsRateLimitedTil time.Time
-)
-
-// LyricsFetchOptions controls optional provider-specific enhancements.
 type LyricsFetchOptions struct {
 	IncludeTranslationNetease  bool   `json:"include_translation_netease"`
 	IncludeRomanizationNetease bool   `json:"include_romanization_netease"`
@@ -72,8 +60,6 @@ var (
 	lyricsFetchOptions   = defaultLyricsFetchOptions
 )
 
-// SetLyricsProviderOrder sets the ordered list of lyrics providers to try.
-// Providers not in the list are disabled. An empty list resets to defaults.
 func SetLyricsProviderOrder(providers []string) {
 	lyricsProvidersMu.Lock()
 	defer lyricsProvidersMu.Unlock()
@@ -84,7 +70,6 @@ func SetLyricsProviderOrder(providers []string) {
 	}
 
 	validNames := map[string]bool{
-		LyricsProviderSpotifyAPI: true,
 		LyricsProviderLRCLIB:     true,
 		LyricsProviderNetease:    true,
 		LyricsProviderMusixmatch: true,
@@ -119,7 +104,6 @@ func GetLyricsProviderOrder() []string {
 
 func GetAvailableLyricsProviders() []map[string]interface{} {
 	return []map[string]interface{}{
-		{"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": true, "description": "NetEase Cloud Music lyrics via Paxsenix"},
 		{"id": LyricsProviderMusixmatch, "name": "Musixmatch", "has_proxy_dependency": true, "description": "Musixmatch lyrics via Paxsenix"},
@@ -249,18 +233,6 @@ type LRCLibResponse struct {
 	SyncedLyrics string  `json:"syncedLyrics"`
 }
 
-type SpotifyLyricsLine struct {
-	TimeTag string `json:"timeTag"`
-	Words   string `json:"words"`
-}
-
-type SpotifyLyricsAPIResponse struct {
-	Error    bool                `json:"error"`
-	Message  string              `json:"message"`
-	SyncType string              `json:"syncType"`
-	Lines    []SpotifyLyricsLine `json:"lines"`
-}
-
 type LyricsLine struct {
 	StartTimeMs int64  `json:"startTimeMs"`
 	Words       string `json:"words"`
@@ -368,214 +340,6 @@ func (c *LyricsClient) FetchLyricsFromLRCLibSearch(query string, durationSec flo
 	return c.parseLRCLibResponse(&results[0]), nil
 }
 
-func parseSpotifyLyricsTimeTagToMs(tag string) int64 {
-	raw := strings.TrimSpace(tag)
-	raw = strings.TrimPrefix(raw, "[")
-	raw = strings.TrimSuffix(raw, "]")
-	if raw == "" {
-		return 0
-	}
-
-	if ms, err := strconv.ParseInt(raw, 10, 64); err == nil {
-		return ms
-	}
-
-	re := regexp.MustCompile(`^(\d{1,2}):(\d{2})\.(\d{1,3})$`)
-	matches := re.FindStringSubmatch(raw)
-	if len(matches) != 4 {
-		return 0
-	}
-
-	minutes, _ := strconv.ParseInt(matches[1], 10, 64)
-	seconds, _ := strconv.ParseInt(matches[2], 10, 64)
-	fraction := matches[3]
-	fractionInt, _ := strconv.ParseInt(fraction, 10, 64)
-	if len(fraction) == 2 {
-		fractionInt *= 10
-	} else if len(fraction) == 1 {
-		fractionInt *= 100
-	}
-	return minutes*60*1000 + seconds*1000 + fractionInt
-}
-
-func getSpotifyLyricsRateLimitUntil() time.Time {
-	spotifyLyricsRateLimitMu.RLock()
-	defer spotifyLyricsRateLimitMu.RUnlock()
-	return spotifyLyricsRateLimitedTil
-}
-
-func setSpotifyLyricsRateLimitUntil(until time.Time) {
-	spotifyLyricsRateLimitMu.Lock()
-	spotifyLyricsRateLimitedTil = until
-	spotifyLyricsRateLimitMu.Unlock()
-}
-
-func parseSpotifyRetryAfter(retryAfter string, now time.Time) time.Time {
-	raw := strings.TrimSpace(retryAfter)
-	if raw == "" {
-		return now.Add(10 * time.Minute)
-	}
-
-	if sec, err := strconv.Atoi(raw); err == nil && sec > 0 {
-		return now.Add(time.Duration(sec) * time.Second)
-	}
-
-	if when, err := http.ParseTime(raw); err == nil && when.After(now) {
-		return when
-	}
-
-	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) {
-		waitFor := int(math.Ceil(limitedUntil.Sub(now).Seconds()))
-		return nil, fmt.Errorf(
-			"Spotify Lyrics API cooldown active (%ds remaining after previous 429)",
-			waitFor,
-		)
-	}
-
-	spotifyID = strings.TrimSpace(spotifyID)
-	if spotifyID == "" {
-		return nil, fmt.Errorf("spotify ID is empty")
-	}
-	if parsed, err := parseSpotifyURI(spotifyID); err == nil && parsed.Type == "track" && parsed.ID != "" {
-		spotifyID = parsed.ID
-	}
-
-	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)
-	}
-	req.Header.Set("User-Agent", getRandomUserAgent())
-
-	resp, err := c.httpClient.Do(req)
-	if err != nil {
-		return nil, fmt.Errorf("failed to fetch from Spotify Lyrics API: %w", err)
-	}
-	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.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))
-			}
-			if msg, ok := payload["error"].(string); ok && strings.TrimSpace(msg) != "" {
-				return nil, fmt.Errorf("Spotify Lyrics API returned status %d: %s", resp.StatusCode, strings.TrimSpace(msg))
-			}
-		}
-		return nil, fmt.Errorf("Spotify Lyrics API returned status %d", resp.StatusCode)
-	}
-
-	return parseSpotifyLyricsResponseBody(bodyBytes)
-}
-
 func (c *LyricsClient) findBestMatch(results []LRCLibResponse, targetDurationSec float64) *LRCLibResponse {
 	var bestSynced *LRCLibResponse
 	var bestPlain *LRCLibResponse
@@ -600,6 +364,18 @@ func (c *LyricsClient) findBestMatch(results []LRCLibResponse, targetDurationSec
 	return bestPlain
 }
 
+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 (c *LyricsClient) durationMatches(lrcDuration, targetDuration float64) bool {
 	diff := math.Abs(lrcDuration - targetDuration)
 	return diff <= durationToleranceSec
@@ -669,9 +445,6 @@ func (c *LyricsClient) FetchLyricsAllSources(spotifyID, trackName, artistName st
 		var err error
 
 		switch providerName {
-		case LyricsProviderSpotifyAPI:
-			lyrics, err = c.FetchLyricsFromSpotifyAPI(spotifyID)
-
 		case LyricsProviderLRCLIB:
 			lyrics, err = c.tryLRCLIB(primaryArtist, artistName, trackName, simplifiedTrack, durationSec)
 
@@ -753,19 +526,16 @@ func (c *LyricsClient) FetchLyricsAllSources(spotifyID, trackName, artistName st
 	return nil, fmt.Errorf("lyrics not found from any source")
 }
 
-// tryLRCLIB attempts all LRCLIB search strategies (exact match, simplified, search).
 func (c *LyricsClient) tryLRCLIB(primaryArtist, artistName, trackName, simplifiedTrack string, durationSec float64) (*LyricsResponse, error) {
 	var lyrics *LyricsResponse
 	var err error
 
-	// 1. Exact match with primary artist
 	lyrics, err = c.FetchLyricsWithMetadata(primaryArtist, trackName)
 	if err == nil && lyrics != nil && (len(lyrics.Lines) > 0 || lyrics.Instrumental) {
 		lyrics.Source = "LRCLIB"
 		return lyrics, nil
 	}
 
-	// 2. Exact match with full artist name
 	if primaryArtist != artistName {
 		lyrics, err = c.FetchLyricsWithMetadata(artistName, trackName)
 		if err == nil && lyrics != nil && (len(lyrics.Lines) > 0 || lyrics.Instrumental) {
@@ -774,7 +544,6 @@ func (c *LyricsClient) tryLRCLIB(primaryArtist, artistName, trackName, simplifie
 		}
 	}
 
-	// 3. Simplified track name
 	if simplifiedTrack != trackName {
 		lyrics, err = c.FetchLyricsWithMetadata(primaryArtist, simplifiedTrack)
 		if err == nil && lyrics != nil && (len(lyrics.Lines) > 0 || lyrics.Instrumental) {
@@ -783,7 +552,6 @@ func (c *LyricsClient) tryLRCLIB(primaryArtist, artistName, trackName, simplifie
 		}
 	}
 
-	// 4. Search by query
 	query := primaryArtist + " " + trackName
 	lyrics, err = c.FetchLyricsFromLRCLibSearch(query, durationSec)
 	if err == nil && lyrics != nil && (len(lyrics.Lines) > 0 || lyrics.Instrumental) {
@@ -791,7 +559,6 @@ func (c *LyricsClient) tryLRCLIB(primaryArtist, artistName, trackName, simplifie
 		return lyrics, nil
 	}
 
-	// 5. Search with simplified track name
 	if simplifiedTrack != trackName {
 		query = primaryArtist + " " + simplifiedTrack
 		lyrics, err = c.FetchLyricsFromLRCLibSearch(query, durationSec)
@@ -909,8 +676,6 @@ func lyricsHasUsableText(lyrics *LyricsResponse) bool {
 	return false
 }
 
-// detectLyricsErrorPayload extracts human-readable error messages from
-// JSON payloads returned by lyrics proxies when no lyric is available.
 func detectLyricsErrorPayload(raw string) (string, bool) {
 	trimmed := strings.TrimSpace(raw)
 	if trimmed == "" || !strings.HasPrefix(trimmed, "{") {
@@ -982,7 +747,7 @@ func convertToLRCWithMetadata(lyrics *LyricsResponse, trackName, artistName stri
 
 	builder.WriteString(fmt.Sprintf("[ti:%s]\n", trackName))
 	builder.WriteString(fmt.Sprintf("[ar:%s]\n", artistName))
-	builder.WriteString("[by:SpotiFLAC-Mobile]\n")
+	builder.WriteString("[by:Implemented by SpotiFLAC-Mobile using Paxsenix API]\n")
 	builder.WriteString("\n")
 
 	if lyrics.SyncType == "LINE_SYNCED" {
@@ -1035,8 +800,6 @@ func simplifyTrackName(name string) string {
 		return result
 	}
 
-	// Add a loose fallback form for provider queries where punctuation
-	// and separators differ (e.g. "/" vs "_" vs spaces).
 	if loose := normalizeLooseTitle(result); loose != "" {
 		return loose
 	}

go_backend/lyrics_apple.go

@@ -11,8 +11,6 @@ import (
 	"time"
 )
 
-// AppleMusicClient fetches lyrics from Apple Music.
-// Uses Paxsenix endpoints for search and lyrics.
 type AppleMusicClient struct {
 	httpClient *http.Client
 }
@@ -25,7 +23,6 @@ type appleMusicSearchResult struct {
 	Duration   int    `json:"duration"`
 }
 
-// PaxResponse represents the lyrics proxy response for word-by-word / line lyrics
 type paxResponse struct {
 	Type    string      `json:"type"`    // "Syllable" or "Line"
 	Content []paxLyrics `json:"content"` // List of lyric lines
@@ -103,7 +100,6 @@ func selectBestAppleMusicSearchResult(results []appleMusicSearchResult, trackNam
 	return &results[bestIndex]
 }
 
-// SearchSong searches for a song on Apple Music and returns its ID.
 func (c *AppleMusicClient) SearchSong(trackName, artistName string, durationSec float64) (string, error) {
 	query := trackName + " " + artistName
 	if strings.TrimSpace(query) == "" {
@@ -144,7 +140,6 @@ func (c *AppleMusicClient) SearchSong(trackName, artistName string, durationSec
 	return strings.TrimSpace(best.ID), nil
 }
 
-// FetchLyricsByID fetches lyrics from the paxsenix proxy using Apple Music song ID.
 func (c *AppleMusicClient) FetchLyricsByID(songID string) (string, error) {
 	lyricsURL := fmt.Sprintf("https://lyrics.paxsenix.org/apple-music/lyrics?id=%s", songID)
 
@@ -252,7 +247,6 @@ func formatPaxContent(lyricsType string, content []paxLyrics, multiPersonWordByW
 	return strings.TrimSpace(sb.String())
 }
 
-// FetchLyrics searches Apple Music and returns parsed LyricsResponse.
 func (c *AppleMusicClient) FetchLyrics(
 	trackName,
 	artistName string,
@@ -272,10 +266,8 @@ func (c *AppleMusicClient) FetchLyrics(
 		return nil, fmt.Errorf("apple music proxy returned non-lyric payload: %s", errMsg)
 	}
 
-	// Try to parse as pax format (word-by-word or line)
 	lrcText, err := formatPaxLyricsToLRC(rawLyrics, multiPersonWordByWord)
 	if err != nil {
-		// If pax parsing fails, try to parse as direct LRC text
 		lrcText = rawLyrics
 	}
 
@@ -289,7 +281,6 @@ func (c *AppleMusicClient) FetchLyrics(
 		}, nil
 	}
 
-	// Fall back to plain text if no timestamps found
 	resultLines := plainTextLyricsLines(lrcText)
 
 	if len(resultLines) > 0 {

go_backend/lyrics_musixmatch.go

@@ -11,8 +11,6 @@ import (
 	"time"
 )
 
-// MusixmatchClient fetches lyrics from Musixmatch via a proxy server.
-// The proxy handles Musixmatch authentication internally.
 type MusixmatchClient struct {
 	httpClient *http.Client
 	baseURL    string
@@ -114,7 +112,6 @@ func (c *MusixmatchClient) fetchLyricsPayload(trackName, artistName string, dura
 	return "", fmt.Errorf("failed to decode musixmatch response")
 }
 
-// FetchLyricsInLanguage retrieves lyrics from Musixmatch for a specific language code.
 func (c *MusixmatchClient) FetchLyricsInLanguage(trackName, artistName string, durationSec float64, language string) (*LyricsResponse, error) {
 	lang := strings.ToLower(strings.TrimSpace(language))
 	if lang == "" {
@@ -151,7 +148,6 @@ func (c *MusixmatchClient) FetchLyricsInLanguage(trackName, artistName string, d
 	return nil, fmt.Errorf("no lyrics found on musixmatch for language %s", lang)
 }
 
-// FetchLyrics searches Musixmatch and returns parsed LyricsResponse.
 func (c *MusixmatchClient) FetchLyrics(trackName, artistName string, durationSec float64, preferredLanguage string) (*LyricsResponse, error) {
 	if preferred := strings.ToLower(strings.TrimSpace(preferredLanguage)); preferred != "" {
 		localized, localizedErr := c.FetchLyricsInLanguage(trackName, artistName, durationSec, preferred)

go_backend/lyrics_netease.go

@@ -9,7 +9,6 @@ import (
 	"time"
 )
 
-// NeteaseClient fetches lyrics through Paxsenix's NetEase endpoints.
 type NeteaseClient struct {
 	httpClient *http.Client
 }
@@ -51,7 +50,6 @@ func NewNeteaseClient() *NeteaseClient {
 	}
 }
 
-// SearchSong searches for a song on Netease and returns the song ID.
 func (c *NeteaseClient) SearchSong(trackName, artistName string) (int64, error) {
 	query := trackName + " " + artistName
 	if strings.TrimSpace(query) == "" {
@@ -96,7 +94,6 @@ func (c *NeteaseClient) SearchSong(trackName, artistName string) (int64, error)
 	return searchResp.Result.Songs[0].ID, nil
 }
 
-// FetchLyricsByID fetches synced lyrics for a given Netease song ID.
 func (c *NeteaseClient) FetchLyricsByID(songID int64, includeTranslation, includeRomanization bool) (string, error) {
 	lyricsURL := "https://lyrics.paxsenix.org/netease/lyrics"
 	params := url.Values{}
@@ -146,7 +143,6 @@ func (c *NeteaseClient) FetchLyricsByID(songID int64, includeTranslation, includ
 	return lyric, nil
 }
 
-// FetchLyrics searches for a track and returns parsed LyricsResponse.
 func (c *NeteaseClient) FetchLyrics(
 	trackName,
 	artistName string,
@@ -166,7 +162,6 @@ func (c *NeteaseClient) FetchLyrics(
 
 	lines := parseSyncedLyrics(lrcText)
 	if len(lines) == 0 {
-		// May be plain text lyrics without timestamps
 		plainLines := strings.Split(lrcText, "\n")
 		for _, line := range plainLines {
 			trimmed := strings.TrimSpace(line)

go_backend/lyrics_qqmusic.go

@@ -10,8 +10,6 @@ import (
 	"time"
 )
 
-// QQMusicClient fetches lyrics from QQ Music.
-// Uses Paxsenix metadata lookup for lyrics.
 type QQMusicClient struct {
 	httpClient *http.Client
 }
@@ -34,7 +32,6 @@ func NewQQMusicClient() *QQMusicClient {
 	}
 }
 
-// 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},
@@ -93,7 +90,6 @@ func formatQQLyricsMetadataToLRC(rawJSON string, multiPersonWordByWord bool) (st
 	return formatPaxContent("Syllable", response.Lyrics, multiPersonWordByWord), nil
 }
 
-// FetchLyrics searches QQ Music and returns parsed LyricsResponse.
 func (c *QQMusicClient) FetchLyrics(
 	trackName,
 	artistName string,

go_backend/metadata.go

@@ -11,6 +11,7 @@ import (
 	"io"
 	"os"
 	"path/filepath"
+	"regexp"
 	"strconv"
 	"strings"
 
@@ -19,6 +20,10 @@ import (
 	"github.com/go-flac/go-flac/v2"
 )
 
+const artistTagModeSplitVorbis = "split_vorbis"
+
+var artistTagSplitPattern = regexp.MustCompile(`\s*(?:,|&|\bx\b)\s*|\s+\b(?:feat(?:uring)?|ft|with)\.?\s*`)
+
 func detectCoverMIME(coverPath string, coverData []byte) string {
 	// Prefer magic-byte detection over file extension.
 	// Some providers return non-JPEG data behind .jpg URLs.
@@ -96,22 +101,29 @@ func buildPictureBlock(coverPath string, coverData []byte) (flac.MetaDataBlock,
 }
 
 type Metadata struct {
-	Title       string
-	Artist      string
-	Album       string
-	AlbumArtist string
-	Date        string
-	TrackNumber int
-	TotalTracks int
-	DiscNumber  int
-	ISRC        string
-	Description string
-	Lyrics      string
-	Genre       string
-	Label       string
-	Copyright   string
-	Composer    string
-	Comment     string
+	Title         string
+	Artist        string
+	Album         string
+	AlbumArtist   string
+	ArtistTagMode string
+	Date          string
+	TrackNumber   int
+	TotalTracks   int
+	DiscNumber    int
+	ISRC          string
+	Description   string
+	Lyrics        string
+	Genre         string
+	Label         string
+	Copyright     string
+	Composer      string
+	Comment       string
+
+	// ReplayGain fields (stored as Vorbis Comments in FLAC)
+	ReplayGainTrackGain string // e.g. "-6.50 dB"
+	ReplayGainTrackPeak string // e.g. "0.988831"
+	ReplayGainAlbumGain string // e.g. "-7.20 dB"
+	ReplayGainAlbumPeak string // e.g. "1.000000"
 }
 
 func EmbedMetadata(filePath string, metadata Metadata, coverPath string) error {
@@ -138,56 +150,7 @@ func EmbedMetadata(filePath string, metadata Metadata, coverPath string) error {
 		cmt = flacvorbis.New()
 	}
 
-	setComment(cmt, "TITLE", metadata.Title)
-	setComment(cmt, "ARTIST", metadata.Artist)
-	setComment(cmt, "ALBUM", metadata.Album)
-	setComment(cmt, "ALBUMARTIST", metadata.AlbumArtist)
-	setComment(cmt, "DATE", metadata.Date)
-
-	if metadata.TrackNumber > 0 {
-		if metadata.TotalTracks > 0 {
-			setComment(cmt, "TRACKNUMBER", fmt.Sprintf("%d/%d", metadata.TrackNumber, metadata.TotalTracks))
-		} else {
-			setComment(cmt, "TRACKNUMBER", strconv.Itoa(metadata.TrackNumber))
-		}
-	}
-
-	if metadata.DiscNumber > 0 {
-		setComment(cmt, "DISCNUMBER", strconv.Itoa(metadata.DiscNumber))
-	}
-
-	if metadata.ISRC != "" {
-		setComment(cmt, "ISRC", metadata.ISRC)
-	}
-
-	if metadata.Description != "" {
-		setComment(cmt, "DESCRIPTION", metadata.Description)
-	}
-
-	if metadata.Lyrics != "" {
-		setComment(cmt, "LYRICS", metadata.Lyrics)
-		setComment(cmt, "UNSYNCEDLYRICS", metadata.Lyrics)
-	}
-
-	if metadata.Genre != "" {
-		setComment(cmt, "GENRE", metadata.Genre)
-	}
-
-	if metadata.Label != "" {
-		setComment(cmt, "ORGANIZATION", metadata.Label)
-	}
-
-	if metadata.Copyright != "" {
-		setComment(cmt, "COPYRIGHT", metadata.Copyright)
-	}
-
-	if metadata.Composer != "" {
-		setComment(cmt, "COMPOSER", metadata.Composer)
-	}
-
-	if metadata.Comment != "" {
-		setComment(cmt, "COMMENT", metadata.Comment)
-	}
+	writeVorbisMetadata(cmt, metadata)
 
 	cmtBlock := cmt.Marshal()
 	if cmtIdx >= 0 {
@@ -247,10 +210,271 @@ func EmbedMetadataWithCoverData(filePath string, metadata Metadata, coverData []
 		cmt = flacvorbis.New()
 	}
 
+	writeVorbisMetadata(cmt, metadata)
+
+	cmtBlock := cmt.Marshal()
+	if cmtIdx >= 0 {
+		f.Meta[cmtIdx] = &cmtBlock
+	} else {
+		f.Meta = append(f.Meta, &cmtBlock)
+	}
+
+	if len(coverData) > 0 {
+		for i := len(f.Meta) - 1; i >= 0; i-- {
+			if f.Meta[i].Type == flac.Picture {
+				f.Meta = append(f.Meta[:i], f.Meta[i+1:]...)
+			}
+		}
+
+		picBlock, err := buildPictureBlock("", coverData)
+		if err != nil {
+			return fmt.Errorf("failed to create picture block: %w", err)
+		}
+		f.Meta = append(f.Meta, &picBlock)
+		fmt.Printf("[Metadata] Cover art embedded successfully (%d bytes)\n", len(coverData))
+	}
+
+	return f.Save(filePath)
+}
+
+func ReadMetadata(filePath string) (*Metadata, error) {
+	f, err := flac.ParseFile(filePath)
+	if err != nil {
+		return nil, fmt.Errorf("failed to parse FLAC file: %w", err)
+	}
+
+	metadata := &Metadata{}
+
+	for _, meta := range f.Meta {
+		if meta.Type == flac.VorbisComment {
+			cmt, err := flacvorbis.ParseFromMetaDataBlock(*meta)
+			if err != nil {
+				continue
+			}
+
+			metadata.Title = getComment(cmt, "TITLE")
+			metadata.Artist = getJoinedComment(cmt, "ARTIST")
+			metadata.Album = getComment(cmt, "ALBUM")
+			metadata.AlbumArtist = getJoinedComment(cmt, "ALBUMARTIST")
+			if metadata.AlbumArtist == "" {
+				metadata.AlbumArtist = getJoinedComment(cmt, "ALBUM ARTIST")
+			}
+			if metadata.AlbumArtist == "" {
+				metadata.AlbumArtist = getJoinedComment(cmt, "ALBUM_ARTIST")
+			}
+			metadata.Date = getComment(cmt, "DATE")
+			metadata.ISRC = getComment(cmt, "ISRC")
+			metadata.Description = getComment(cmt, "DESCRIPTION")
+
+			metadata.Lyrics = getComment(cmt, "LYRICS")
+			if metadata.Lyrics == "" {
+				metadata.Lyrics = getComment(cmt, "UNSYNCEDLYRICS")
+			}
+
+			trackNum := getComment(cmt, "TRACKNUMBER")
+			if trackNum != "" {
+				fmt.Sscanf(trackNum, "%d", &metadata.TrackNumber)
+			}
+			if metadata.TrackNumber == 0 {
+				trackNum = getComment(cmt, "TRACK")
+				if trackNum != "" {
+					fmt.Sscanf(trackNum, "%d", &metadata.TrackNumber)
+				}
+			}
+
+			discNum := getComment(cmt, "DISCNUMBER")
+			if discNum != "" {
+				fmt.Sscanf(discNum, "%d", &metadata.DiscNumber)
+			}
+			if metadata.DiscNumber == 0 {
+				discNum = getComment(cmt, "DISC")
+				if discNum != "" {
+					fmt.Sscanf(discNum, "%d", &metadata.DiscNumber)
+				}
+			}
+
+			if metadata.Date == "" {
+				metadata.Date = getComment(cmt, "YEAR")
+			}
+
+			metadata.Genre = getComment(cmt, "GENRE")
+			metadata.Label = getComment(cmt, "ORGANIZATION")
+			if metadata.Label == "" {
+				metadata.Label = getComment(cmt, "LABEL")
+			}
+			if metadata.Label == "" {
+				metadata.Label = getComment(cmt, "PUBLISHER")
+			}
+			metadata.Copyright = getComment(cmt, "COPYRIGHT")
+			metadata.Composer = getComment(cmt, "COMPOSER")
+			metadata.Comment = getComment(cmt, "COMMENT")
+
+			metadata.ReplayGainTrackGain = getComment(cmt, "REPLAYGAIN_TRACK_GAIN")
+			metadata.ReplayGainTrackPeak = getComment(cmt, "REPLAYGAIN_TRACK_PEAK")
+			metadata.ReplayGainAlbumGain = getComment(cmt, "REPLAYGAIN_ALBUM_GAIN")
+			metadata.ReplayGainAlbumPeak = getComment(cmt, "REPLAYGAIN_ALBUM_PEAK")
+
+			break
+		}
+	}
+
+	return metadata, nil
+}
+
+// EditFlacFields opens a FLAC file and updates only the Vorbis Comment keys
+// that are explicitly present in the fields map.  Keys present with a non-empty
+// value are set; keys present with an empty value are removed (cleared).  Keys
+// absent from the map are left untouched.  This is the correct function for
+// partial edits (e.g. writing only ReplayGain tags) and full editor saves alike.
+func EditFlacFields(filePath string, fields map[string]string) error {
+	f, err := flac.ParseFile(filePath)
+	if err != nil {
+		return fmt.Errorf("failed to parse FLAC file: %w", err)
+	}
+
+	var cmtIdx int = -1
+	var cmt *flacvorbis.MetaDataBlockVorbisComment
+
+	for idx, meta := range f.Meta {
+		if meta.Type == flac.VorbisComment {
+			cmtIdx = idx
+			cmt, err = flacvorbis.ParseFromMetaDataBlock(*meta)
+			if err != nil {
+				return fmt.Errorf("failed to parse vorbis comment: %w", err)
+			}
+			break
+		}
+	}
+	if cmt == nil {
+		cmt = flacvorbis.New()
+	}
+
+	artistMode := fields["artist_tag_mode"]
+
+	// Mapping from fields-map key → one or more Vorbis Comment keys.
+	// Each entry is handled with set-or-clear semantics.
+	simpleKeys := map[string]string{
+		"title":                 "TITLE",
+		"album":                 "ALBUM",
+		"date":                  "DATE",
+		"isrc":                  "ISRC",
+		"genre":                 "GENRE",
+		"label":                 "ORGANIZATION",
+		"copyright":             "COPYRIGHT",
+		"composer":              "COMPOSER",
+		"comment":               "COMMENT",
+		"replaygain_track_gain": "REPLAYGAIN_TRACK_GAIN",
+		"replaygain_track_peak": "REPLAYGAIN_TRACK_PEAK",
+		"replaygain_album_gain": "REPLAYGAIN_ALBUM_GAIN",
+		"replaygain_album_peak": "REPLAYGAIN_ALBUM_PEAK",
+	}
+
+	for fieldKey, vorbisKey := range simpleKeys {
+		if v, ok := fields[fieldKey]; ok {
+			setOrClearComment(cmt, vorbisKey, v)
+		}
+	}
+
+	// Remove known aliases for fields that were just written/cleared, so that
+	// tags from other taggers (e.g. LABEL, PUBLISHER, ALBUM ARTIST) don't
+	// conflict with the canonical keys we use.
+	aliasCleanup := map[string][]string{
+		"label":     {"LABEL", "PUBLISHER"}, // canonical: ORGANIZATION
+		"date":      {"YEAR"},               // canonical: DATE
+		"genre":     {},                     // no common aliases
+		"copyright": {},
+	}
+	for fieldKey, aliases := range aliasCleanup {
+		if _, ok := fields[fieldKey]; ok {
+			for _, alias := range aliases {
+				removeCommentKey(cmt, alias)
+			}
+		}
+	}
+
+	// Artist fields: use split-artist logic when mode is set.
+	if v, ok := fields["artist"]; ok {
+		setOrClearArtistComments(cmt, "ARTIST", v, artistMode)
+	}
+	if v, ok := fields["album_artist"]; ok {
+		setOrClearArtistComments(cmt, "ALBUMARTIST", v, artistMode)
+		// Remove aliases from other taggers.
+		removeCommentKey(cmt, "ALBUM ARTIST")
+		removeCommentKey(cmt, "ALBUM_ARTIST")
+	}
+
+	// Track/disc numbers: present + empty → clear; present + "0" → clear.
+	if v, ok := fields["track_number"]; ok {
+		trackNum := 0
+		if v != "" {
+			fmt.Sscanf(v, "%d", &trackNum)
+		}
+		if trackNum > 0 {
+			setOrClearComment(cmt, "TRACKNUMBER", strconv.Itoa(trackNum))
+		} else {
+			removeCommentKey(cmt, "TRACKNUMBER")
+		}
+		removeCommentKey(cmt, "TRACK") // alias
+	}
+	if v, ok := fields["disc_number"]; ok {
+		discNum := 0
+		if v != "" {
+			fmt.Sscanf(v, "%d", &discNum)
+		}
+		if discNum > 0 {
+			setOrClearComment(cmt, "DISCNUMBER", strconv.Itoa(discNum))
+		} else {
+			removeCommentKey(cmt, "DISCNUMBER")
+		}
+		removeCommentKey(cmt, "DISC") // alias
+	}
+
+	// Lyrics: set both LYRICS + UNSYNCEDLYRICS, or clear both.
+	if v, ok := fields["lyrics"]; ok {
+		if v != "" {
+			setOrClearComment(cmt, "LYRICS", v)
+			setOrClearComment(cmt, "UNSYNCEDLYRICS", v)
+		} else {
+			removeCommentKey(cmt, "LYRICS")
+			removeCommentKey(cmt, "UNSYNCEDLYRICS")
+		}
+	}
+
+	cmtBlock := cmt.Marshal()
+	if cmtIdx >= 0 {
+		f.Meta[cmtIdx] = &cmtBlock
+	} else {
+		f.Meta = append(f.Meta, &cmtBlock)
+	}
+
+	coverPath := strings.TrimSpace(fields["cover_path"])
+	if coverPath != "" && fileExists(coverPath) {
+		coverData, err := os.ReadFile(coverPath)
+		if err == nil && len(coverData) > 0 {
+			for i := len(f.Meta) - 1; i >= 0; i-- {
+				if f.Meta[i].Type == flac.Picture {
+					f.Meta = append(f.Meta[:i], f.Meta[i+1:]...)
+				}
+			}
+			picBlock, err := buildPictureBlock("", coverData)
+			if err == nil {
+				f.Meta = append(f.Meta, &picBlock)
+			}
+		}
+	}
+
+	return f.Save(filePath)
+}
+
+// writeVorbisMetadata writes all metadata fields to a Vorbis Comment block.
+// Empty/zero values are simply skipped (not written, not cleared).  This is
+// used by the download embedding path where absent fields should preserve any
+// existing values.  The editor path uses EditFlacFields() instead.
+func writeVorbisMetadata(cmt *flacvorbis.MetaDataBlockVorbisComment, metadata Metadata) {
 	setComment(cmt, "TITLE", metadata.Title)
-	setComment(cmt, "ARTIST", metadata.Artist)
+	setArtistComments(cmt, "ARTIST", metadata.Artist, metadata.ArtistTagMode)
 	setComment(cmt, "ALBUM", metadata.Album)
-	setComment(cmt, "ALBUMARTIST", metadata.AlbumArtist)
+	setArtistComments(cmt, "ALBUMARTIST", metadata.AlbumArtist, metadata.ArtistTagMode)
 	setComment(cmt, "DATE", metadata.Date)
 
 	if metadata.TrackNumber > 0 {
@@ -298,102 +522,122 @@ func EmbedMetadataWithCoverData(filePath string, metadata Metadata, coverData []
 		setComment(cmt, "COMMENT", metadata.Comment)
 	}
 
-	cmtBlock := cmt.Marshal()
-	if cmtIdx >= 0 {
-		f.Meta[cmtIdx] = &cmtBlock
-	} else {
-		f.Meta = append(f.Meta, &cmtBlock)
-	}
-
-	if len(coverData) > 0 {
-		for i := len(f.Meta) - 1; i >= 0; i-- {
-			if f.Meta[i].Type == flac.Picture {
-				f.Meta = append(f.Meta[:i], f.Meta[i+1:]...)
-			}
-		}
-
-		picBlock, err := buildPictureBlock("", coverData)
-		if err != nil {
-			return fmt.Errorf("failed to create picture block: %w", err)
-		}
-		f.Meta = append(f.Meta, &picBlock)
-		fmt.Printf("[Metadata] Cover art embedded successfully (%d bytes)\n", len(coverData))
-	}
-
-	return f.Save(filePath)
-}
-
-func ReadMetadata(filePath string) (*Metadata, error) {
-	f, err := flac.ParseFile(filePath)
-	if err != nil {
-		return nil, fmt.Errorf("failed to parse FLAC file: %w", err)
-	}
-
-	metadata := &Metadata{}
-
-	for _, meta := range f.Meta {
-		if meta.Type == flac.VorbisComment {
-			cmt, err := flacvorbis.ParseFromMetaDataBlock(*meta)
-			if err != nil {
-				continue
-			}
-
-			metadata.Title = getComment(cmt, "TITLE")
-			metadata.Artist = getComment(cmt, "ARTIST")
-			metadata.Album = getComment(cmt, "ALBUM")
-			metadata.AlbumArtist = getComment(cmt, "ALBUMARTIST")
-			metadata.Date = getComment(cmt, "DATE")
-			metadata.ISRC = getComment(cmt, "ISRC")
-			metadata.Description = getComment(cmt, "DESCRIPTION")
-
-			metadata.Lyrics = getComment(cmt, "LYRICS")
-			if metadata.Lyrics == "" {
-				metadata.Lyrics = getComment(cmt, "UNSYNCEDLYRICS")
-			}
-
-			trackNum := getComment(cmt, "TRACKNUMBER")
-			if trackNum != "" {
-				fmt.Sscanf(trackNum, "%d", &metadata.TrackNumber)
-			}
-			if metadata.TrackNumber == 0 {
-				trackNum = getComment(cmt, "TRACK")
-				if trackNum != "" {
-					fmt.Sscanf(trackNum, "%d", &metadata.TrackNumber)
-				}
-			}
-
-			discNum := getComment(cmt, "DISCNUMBER")
-			if discNum != "" {
-				fmt.Sscanf(discNum, "%d", &metadata.DiscNumber)
-			}
-			if metadata.DiscNumber == 0 {
-				discNum = getComment(cmt, "DISC")
-				if discNum != "" {
-					fmt.Sscanf(discNum, "%d", &metadata.DiscNumber)
-				}
-			}
-
-			if metadata.Date == "" {
-				metadata.Date = getComment(cmt, "YEAR")
-			}
-
-			metadata.Genre = getComment(cmt, "GENRE")
-			metadata.Label = getComment(cmt, "ORGANIZATION")
-			metadata.Copyright = getComment(cmt, "COPYRIGHT")
-			metadata.Composer = getComment(cmt, "COMPOSER")
-			metadata.Comment = getComment(cmt, "COMMENT")
-
-			break
-		}
-	}
-
-	return metadata, nil
+	setComment(cmt, "REPLAYGAIN_TRACK_GAIN", metadata.ReplayGainTrackGain)
+	setComment(cmt, "REPLAYGAIN_TRACK_PEAK", metadata.ReplayGainTrackPeak)
+	setComment(cmt, "REPLAYGAIN_ALBUM_GAIN", metadata.ReplayGainAlbumGain)
+	setComment(cmt, "REPLAYGAIN_ALBUM_PEAK", metadata.ReplayGainAlbumPeak)
 }
 
 func setComment(cmt *flacvorbis.MetaDataBlockVorbisComment, key, value string) {
 	if value == "" {
 		return
 	}
+	removeCommentKey(cmt, key)
+	cmt.Comments = append(cmt.Comments, key+"="+value)
+}
+
+// setOrClearComment writes a Vorbis Comment, or removes the key if value is
+// empty.  Used by the metadata editor path where empty means "delete this tag".
+func setOrClearComment(cmt *flacvorbis.MetaDataBlockVorbisComment, key, value string) {
+	if value == "" {
+		removeCommentKey(cmt, key)
+		return
+	}
+	removeCommentKey(cmt, key)
+	cmt.Comments = append(cmt.Comments, key+"="+value)
+}
+
+func setArtistComments(cmt *flacvorbis.MetaDataBlockVorbisComment, key, value, mode string) {
+	if value == "" {
+		return
+	}
+	values := []string{value}
+	if shouldSplitVorbisArtistTags(mode) {
+		values = splitArtistTagValues(value)
+	}
+	if len(values) == 0 {
+		return
+	}
+	removeCommentKey(cmt, key)
+	for _, artist := range values {
+		if strings.TrimSpace(artist) == "" {
+			continue
+		}
+		cmt.Comments = append(cmt.Comments, key+"="+artist)
+	}
+}
+
+// setOrClearArtistComments writes artist Vorbis Comments, or removes the key
+// if value is empty.  Used by the metadata editor path.
+func setOrClearArtistComments(cmt *flacvorbis.MetaDataBlockVorbisComment, key, value, mode string) {
+	if value == "" {
+		removeCommentKey(cmt, key)
+		return
+	}
+	values := []string{value}
+	if shouldSplitVorbisArtistTags(mode) {
+		values = splitArtistTagValues(value)
+	}
+	if len(values) == 0 {
+		removeCommentKey(cmt, key)
+		return
+	}
+	removeCommentKey(cmt, key)
+	for _, artist := range values {
+		if strings.TrimSpace(artist) == "" {
+			continue
+		}
+		cmt.Comments = append(cmt.Comments, key+"="+artist)
+	}
+}
+
+// RewriteSplitArtistTags opens a FLAC file and rewrites the ARTIST and
+// ALBUMARTIST Vorbis comments as multiple separate entries (one per artist).
+// This is needed because FFmpeg's -metadata flag deduplicates keys, so only
+// the last value survives when multiple -metadata ARTIST=X flags are used.
+// The native go-flac writer correctly handles multiple Vorbis comments.
+func RewriteSplitArtistTags(filePath, artist, albumArtist string) error {
+	if !shouldSplitVorbisArtistTags(artistTagModeSplitVorbis) {
+		return nil
+	}
+
+	f, err := flac.ParseFile(filePath)
+	if err != nil {
+		return fmt.Errorf("failed to parse FLAC file: %w", err)
+	}
+
+	var cmtIdx int = -1
+	var cmt *flacvorbis.MetaDataBlockVorbisComment
+
+	for idx, meta := range f.Meta {
+		if meta.Type == flac.VorbisComment {
+			cmtIdx = idx
+			cmt, err = flacvorbis.ParseFromMetaDataBlock(*meta)
+			if err != nil {
+				return fmt.Errorf("failed to parse vorbis comment: %w", err)
+			}
+			break
+		}
+	}
+
+	if cmt == nil {
+		cmt = flacvorbis.New()
+	}
+
+	setArtistComments(cmt, "ARTIST", artist, artistTagModeSplitVorbis)
+	setArtistComments(cmt, "ALBUMARTIST", albumArtist, artistTagModeSplitVorbis)
+
+	cmtMeta := cmt.Marshal()
+	if cmtIdx >= 0 {
+		f.Meta[cmtIdx] = &cmtMeta
+	} else {
+		f.Meta = append(f.Meta, &cmtMeta)
+	}
+
+	return f.Save(filePath)
+}
+
+func removeCommentKey(cmt *flacvorbis.MetaDataBlockVorbisComment, key string) {
 	keyUpper := strings.ToUpper(key)
 	for i := len(cmt.Comments) - 1; i >= 0; i-- {
 		comment := cmt.Comments[i]
@@ -405,20 +649,85 @@ func setComment(cmt *flacvorbis.MetaDataBlockVorbisComment, key, value string) {
 			}
 		}
 	}
-	cmt.Comments = append(cmt.Comments, key+"="+value)
 }
 
 func getComment(cmt *flacvorbis.MetaDataBlockVorbisComment, key string) string {
+	values := getCommentValues(cmt, key)
+	if len(values) == 0 {
+		return ""
+	}
+	return values[0]
+}
+
+func getJoinedComment(cmt *flacvorbis.MetaDataBlockVorbisComment, key string) string {
+	return joinVorbisCommentValues(getCommentValues(cmt, key))
+}
+
+func getCommentValues(cmt *flacvorbis.MetaDataBlockVorbisComment, key string) []string {
 	keyUpper := strings.ToUpper(key) + "="
+	values := make([]string, 0, 1)
 	for _, comment := range cmt.Comments {
 		if len(comment) > len(key) {
 			commentUpper := strings.ToUpper(comment[:len(key)+1])
 			if commentUpper == keyUpper {
-				return comment[len(key)+1:]
+				values = append(values, comment[len(key)+1:])
 			}
 		}
 	}
-	return ""
+	return values
+}
+
+func shouldSplitVorbisArtistTags(mode string) bool {
+	return strings.EqualFold(strings.TrimSpace(mode), artistTagModeSplitVorbis)
+}
+
+func splitArtistTagValues(rawArtists string) []string {
+	trimmed := strings.TrimSpace(rawArtists)
+	if trimmed == "" {
+		return nil
+	}
+
+	parts := artistTagSplitPattern.Split(trimmed, -1)
+	values := make([]string, 0, len(parts))
+	seen := make(map[string]struct{}, len(parts))
+	for _, part := range parts {
+		artist := strings.TrimSpace(part)
+		if artist == "" {
+			continue
+		}
+		key := strings.ToLower(artist)
+		if _, ok := seen[key]; ok {
+			continue
+		}
+		seen[key] = struct{}{}
+		values = append(values, artist)
+	}
+	if len(values) > 0 {
+		return values
+	}
+	return []string{trimmed}
+}
+
+func joinVorbisCommentValues(values []string) string {
+	if len(values) == 0 {
+		return ""
+	}
+
+	joined := make([]string, 0, len(values))
+	seen := make(map[string]struct{}, len(values))
+	for _, value := range values {
+		trimmed := strings.TrimSpace(value)
+		if trimmed == "" {
+			continue
+		}
+		key := strings.ToLower(trimmed)
+		if _, ok := seen[key]; ok {
+			continue
+		}
+		seen[key] = struct{}{}
+		joined = append(joined, trimmed)
+	}
+	return strings.Join(joined, ", ")
 }
 
 func fileExists(path string) bool {
@@ -671,6 +980,14 @@ func ReadM4ATags(filePath string) (*AudioMetadata, error) {
 					if metadata.Lyrics == "" {
 						metadata.Lyrics = value
 					}
+				case "REPLAYGAIN_TRACK_GAIN":
+					metadata.ReplayGainTrackGain = value
+				case "REPLAYGAIN_TRACK_PEAK":
+					metadata.ReplayGainTrackPeak = value
+				case "REPLAYGAIN_ALBUM_GAIN":
+					metadata.ReplayGainAlbumGain = value
+				case "REPLAYGAIN_ALBUM_PEAK":
+					metadata.ReplayGainAlbumPeak = value
 				}
 			}
 		}

go_backend/metadata_artist_tags_test.go

@@ -0,0 +1,67 @@
+package gobackend
+
+import (
+	"bytes"
+	"encoding/binary"
+	"slices"
+	"testing"
+
+	"github.com/go-flac/flacvorbis/v2"
+)
+
+func TestSplitArtistTagValues(t *testing.T) {
+	got := splitArtistTagValues("Artist A, Artist B feat. Artist C & Artist B")
+	want := []string{"Artist A", "Artist B", "Artist C"}
+	if !slices.Equal(got, want) {
+		t.Fatalf("splitArtistTagValues() = %#v, want %#v", got, want)
+	}
+}
+
+func TestSetArtistCommentsSplitVorbis(t *testing.T) {
+	cmt := flacvorbis.New()
+	setArtistComments(cmt, "ARTIST", "Artist A, Artist B", artistTagModeSplitVorbis)
+
+	got := getCommentValues(cmt, "ARTIST")
+	want := []string{"Artist A", "Artist B"}
+	if !slices.Equal(got, want) {
+		t.Fatalf("getCommentValues(ARTIST) = %#v, want %#v", got, want)
+	}
+}
+
+func TestParseVorbisCommentsJoinsRepeatedArtists(t *testing.T) {
+	metadata := &AudioMetadata{}
+	parseVorbisComments(
+		buildVorbisCommentPayload(
+			[]string{
+				"TITLE=Song",
+				"ARTIST=Artist A",
+				"ARTIST=Artist B",
+				"ALBUMARTIST=Album Artist A",
+				"ALBUMARTIST=Album Artist B",
+			},
+		),
+		metadata,
+	)
+
+	if metadata.Title != "Song" {
+		t.Fatalf("title = %q", metadata.Title)
+	}
+	if metadata.Artist != "Artist A, Artist B" {
+		t.Fatalf("artist = %q", metadata.Artist)
+	}
+	if metadata.AlbumArtist != "Album Artist A, Album Artist B" {
+		t.Fatalf("album artist = %q", metadata.AlbumArtist)
+	}
+}
+
+func buildVorbisCommentPayload(comments []string) []byte {
+	var buf bytes.Buffer
+	_ = binary.Write(&buf, binary.LittleEndian, uint32(len("spotiflac")))
+	buf.WriteString("spotiflac")
+	_ = binary.Write(&buf, binary.LittleEndian, uint32(len(comments)))
+	for _, comment := range comments {
+		_ = binary.Write(&buf, binary.LittleEndian, uint32(len(comment)))
+		buf.WriteString(comment)
+	}
+	return buf.Bytes()
+}

go_backend/metadata_types.go

@@ -0,0 +1,145 @@
+package gobackend
+
+import "time"
+
+type cacheEntry struct {
+	data      interface{}
+	expiresAt time.Time
+}
+
+func (e *cacheEntry) isExpired() bool {
+	return time.Now().After(e.expiresAt)
+}
+
+type TrackMetadata struct {
+	SpotifyID   string `json:"spotify_id,omitempty"`
+	Artists     string `json:"artists"`
+	Name        string `json:"name"`
+	AlbumName   string `json:"album_name"`
+	AlbumArtist string `json:"album_artist,omitempty"`
+	DurationMS  int    `json:"duration_ms"`
+	Images      string `json:"images"`
+	ReleaseDate string `json:"release_date"`
+	TrackNumber int    `json:"track_number"`
+	TotalTracks int    `json:"total_tracks,omitempty"`
+	DiscNumber  int    `json:"disc_number,omitempty"`
+	ExternalURL string `json:"external_urls"`
+	ISRC        string `json:"isrc"`
+	AlbumID     string `json:"album_id,omitempty"`
+	ArtistID    string `json:"artist_id,omitempty"`
+	AlbumType   string `json:"album_type,omitempty"`
+}
+
+type AlbumTrackMetadata struct {
+	SpotifyID   string `json:"spotify_id,omitempty"`
+	Artists     string `json:"artists"`
+	Name        string `json:"name"`
+	AlbumName   string `json:"album_name"`
+	AlbumArtist string `json:"album_artist,omitempty"`
+	DurationMS  int    `json:"duration_ms"`
+	Images      string `json:"images"`
+	ReleaseDate string `json:"release_date"`
+	TrackNumber int    `json:"track_number"`
+	TotalTracks int    `json:"total_tracks,omitempty"`
+	DiscNumber  int    `json:"disc_number,omitempty"`
+	ExternalURL string `json:"external_urls"`
+	ISRC        string `json:"isrc"`
+	AlbumID     string `json:"album_id,omitempty"`
+	AlbumURL    string `json:"album_url,omitempty"`
+	AlbumType   string `json:"album_type,omitempty"`
+}
+
+type AlbumInfoMetadata struct {
+	TotalTracks int    `json:"total_tracks"`
+	Name        string `json:"name"`
+	ReleaseDate string `json:"release_date"`
+	Artists     string `json:"artists"`
+	ArtistId    string `json:"artist_id,omitempty"`
+	Images      string `json:"images"`
+	Genre       string `json:"genre,omitempty"`
+	Label       string `json:"label,omitempty"`
+	Copyright   string `json:"copyright,omitempty"`
+}
+
+type AlbumResponsePayload struct {
+	AlbumInfo AlbumInfoMetadata    `json:"album_info"`
+	TrackList []AlbumTrackMetadata `json:"track_list"`
+}
+
+type PlaylistInfoMetadata struct {
+	Name   string `json:"name,omitempty"`
+	Images string `json:"images,omitempty"`
+	Tracks struct {
+		Total int `json:"total"`
+	} `json:"tracks"`
+	Owner struct {
+		DisplayName string `json:"display_name"`
+		Name        string `json:"name"`
+		Images      string `json:"images"`
+	} `json:"owner"`
+}
+
+type PlaylistResponsePayload struct {
+	PlaylistInfo PlaylistInfoMetadata `json:"playlist_info"`
+	TrackList    []AlbumTrackMetadata `json:"track_list"`
+}
+
+type ArtistInfoMetadata struct {
+	ID         string `json:"id"`
+	Name       string `json:"name"`
+	Images     string `json:"images"`
+	Followers  int    `json:"followers"`
+	Popularity int    `json:"popularity"`
+}
+
+type ArtistAlbumMetadata struct {
+	ID          string `json:"id"`
+	Name        string `json:"name"`
+	ReleaseDate string `json:"release_date"`
+	TotalTracks int    `json:"total_tracks"`
+	Images      string `json:"images"`
+	AlbumType   string `json:"album_type"`
+	Artists     string `json:"artists"`
+}
+
+type ArtistResponsePayload struct {
+	ArtistInfo ArtistInfoMetadata    `json:"artist_info"`
+	Albums     []ArtistAlbumMetadata `json:"albums"`
+}
+
+type TrackResponse struct {
+	Track TrackMetadata `json:"track"`
+}
+
+type SearchArtistResult struct {
+	ID         string `json:"id"`
+	Name       string `json:"name"`
+	Images     string `json:"images"`
+	Followers  int    `json:"followers"`
+	Popularity int    `json:"popularity"`
+}
+
+type SearchAlbumResult struct {
+	ID          string `json:"id"`
+	Name        string `json:"name"`
+	Artists     string `json:"artists"`
+	Images      string `json:"images"`
+	ReleaseDate string `json:"release_date"`
+	TotalTracks int    `json:"total_tracks"`
+	AlbumType   string `json:"album_type"`
+}
+
+type SearchPlaylistResult struct {
+	ID          string `json:"id"`
+	Name        string `json:"name"`
+	Owner       string `json:"owner"`
+	Images      string `json:"images"`
+	TotalTracks int    `json:"total_tracks"`
+}
+
+type SearchAllResult struct {
+	Tracks    []TrackMetadata        `json:"tracks"`
+	Artists   []SearchArtistResult   `json:"artists"`
+	Albums    []SearchAlbumResult    `json:"albums"`
+	Playlists []SearchPlaylistResult `json:"playlists"`
+}

go_backend/qobuz.go

@@ -13,6 +13,7 @@ import (
 	"os"
 	"path/filepath"
 	"regexp"
+	"sort"
 	"strconv"
 	"strings"
 	"sync"
@@ -43,11 +44,12 @@ var (
 )
 
 const (
-	qobuzTrackGetBaseURL    = "https://www.qobuz.com/api.json/0.2/track/get?track_id="
-	qobuzTrackSearchBaseURL = "https://www.qobuz.com/api.json/0.2/track/search?query="
-	qobuzAlbumGetBaseURL    = "https://www.qobuz.com/api.json/0.2/album/get?album_id="
-	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="
+	qobuzAPIBaseURL         = "https://api.zarz.moe/v1/qbz/"
+	qobuzTrackGetBaseURL    = qobuzAPIBaseURL + "track/get?track_id="
+	qobuzTrackSearchBaseURL = qobuzAPIBaseURL + "track/search?query="
+	qobuzAlbumGetBaseURL    = qobuzAPIBaseURL + "album/get?album_id="
+	qobuzArtistGetBaseURL   = qobuzAPIBaseURL + "artist/get?artist_id="
+	qobuzPlaylistGetBaseURL = qobuzAPIBaseURL + "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/"
@@ -57,21 +59,19 @@ const (
 	qobuzDeebAPIURL         = "https://dab.yeet.su/api/stream?trackId="
 	qobuzAfkarAPIURL        = "https://qbz.afkarxyz.qzz.io/api/track/"
 	qobuzSquidAPIURL        = "https://qobuz.squid.wtf/api/download-music?country=US&track_id="
-	qobuzDebugKeyXORMask    = byte(0x5A)
+
+	qobuzFallbackAPIBaseURL         = "https://api.zarz.moe/v1/qbz2/"
+	qobuzFallbackTrackGetBaseURL    = qobuzFallbackAPIBaseURL + "track/get?track_id="
+	qobuzFallbackTrackSearchBaseURL = qobuzFallbackAPIBaseURL + "track/search?query="
+	qobuzFallbackAlbumGetBaseURL    = qobuzFallbackAPIBaseURL + "album/get?album_id="
+	qobuzFallbackArtistGetBaseURL   = qobuzFallbackAPIBaseURL + "artist/get?artist_id="
+	qobuzFallbackPlaylistGetBaseURL = qobuzFallbackAPIBaseURL + "playlist/get?playlist_id="
 )
 
 var qobuzStoreTrackIDRegex = regexp.MustCompile(`/v4/ajax/popin-add-cart/track/([0-9]+)`)
 var qobuzArtistAlbumIDRegex = regexp.MustCompile(`data-itemtype="album"\s+data-itemId="([A-Za-z0-9]+)"`)
 var qobuzLocaleSegmentRegex = regexp.MustCompile(`^[a-z]{2}-[a-z]{2}$`)
 
-var qobuzDebugKeyObfuscated = []byte{
-	0x69, 0x3b, 0x38, 0x3e, 0x36, 0x37, 0x35, 0x2f, 0x36, 0x3b,
-	0x33, 0x29, 0x2e, 0x32, 0x3f, 0x3d, 0x35, 0x3b, 0x2e, 0x3b,
-	0x34, 0x3e, 0x34, 0x35, 0x35, 0x34, 0x3f, 0x39, 0x35, 0x37,
-	0x3f, 0x29, 0x3f, 0x2c, 0x3f, 0x34, 0x39, 0x36, 0x35, 0x29,
-	0x3f,
-}
-
 type QobuzTrack struct {
 	ID                  int64   `json:"id"`
 	Title               string  `json:"title"`
@@ -785,12 +785,21 @@ func (q *QobuzDownloader) GetTrackByID(trackID int64) (*QobuzTrack, error) {
 
 	resp, err := DoRequestWithUserAgent(q.client, req)
 	if err != nil {
+		if isQobuzPrimaryUnavailable(err) {
+			GoLog("[Qobuz] Primary API unavailable for track %d, trying qbz2 fallback: %v\n", trackID, err)
+			return q.getTrackByIDViaMusicDL(trackID)
+		}
 		return nil, err
 	}
 	defer resp.Body.Close()
 
 	if resp.StatusCode != 200 {
-		return nil, fmt.Errorf("get track failed: HTTP %d", resp.StatusCode)
+		primaryErr := fmt.Errorf("get track failed: HTTP %d", resp.StatusCode)
+		if isQobuzPrimaryUnavailable(primaryErr) {
+			GoLog("[Qobuz] Primary API unavailable for track %d, trying qbz2 fallback: %v\n", trackID, primaryErr)
+			return q.getTrackByIDViaMusicDL(trackID)
+		}
+		return nil, primaryErr
 	}
 
 	var track QobuzTrack
@@ -801,6 +810,16 @@ func (q *QobuzDownloader) GetTrackByID(trackID int64) (*QobuzTrack, error) {
 	return &track, nil
 }
 
+func (q *QobuzDownloader) getTrackByIDViaMusicDL(trackID int64) (*QobuzTrack, error) {
+	requestURL := fmt.Sprintf("%s%d", qobuzFallbackTrackGetBaseURL, trackID)
+	var track QobuzTrack
+	if err := q.getQobuzJSON(requestURL, &track); err != nil {
+		return nil, fmt.Errorf("qbz2 fallback also failed for track %d: %w", trackID, err)
+	}
+	GoLog("[Qobuz] qbz2 fallback succeeded for track %d\n", trackID)
+	return &track, nil
+}
+
 func (q *QobuzDownloader) getQobuzJSON(requestURL string, target interface{}) error {
 	req, err := http.NewRequest("GET", requestURL, nil)
 	if err != nil {
@@ -841,6 +860,25 @@ func (q *QobuzDownloader) getQobuzBody(requestURL string) ([]byte, error) {
 	return io.ReadAll(resp.Body)
 }
 
+func isQobuzPrimaryUnavailable(err error) bool {
+	if err == nil {
+		return false
+	}
+	errStr := err.Error()
+	return strings.Contains(errStr, "HTTP 429") ||
+		strings.Contains(errStr, "HTTP 5") ||
+		strings.Contains(errStr, "rate limit") ||
+		strings.Contains(errStr, "connection refused") ||
+		strings.Contains(errStr, "no such host") ||
+		strings.Contains(errStr, "i/o timeout") ||
+		strings.Contains(errStr, "deadline exceeded") ||
+		strings.Contains(errStr, "EOF") ||
+		strings.Contains(errStr, "connection reset") ||
+		strings.Contains(errStr, "TLS handshake") ||
+		strings.Contains(errStr, "server misbehaving") ||
+		strings.Contains(errStr, "network is unreachable")
+}
+
 func extractQobuzAlbumIDsFromArtistHTML(body []byte) []string {
 	matches := qobuzArtistAlbumIDRegex.FindAllSubmatch(body, -1)
 	if len(matches) == 0 {
@@ -870,20 +908,48 @@ func (q *QobuzDownloader) getAlbumDetails(albumID string) (*qobuzAlbumDetails, e
 	requestURL := fmt.Sprintf("%s%s&app_id=%s", qobuzAlbumGetBaseURL, url.QueryEscape(strings.TrimSpace(albumID)), q.appID)
 	var album qobuzAlbumDetails
 	if err := q.getQobuzJSON(requestURL, &album); err != nil {
+		if isQobuzPrimaryUnavailable(err) {
+			GoLog("[Qobuz] Primary API unavailable for album %s, trying qbz2 fallback: %v\n", albumID, err)
+			return q.getAlbumDetailsViaMusicDL(albumID)
+		}
 		return nil, err
 	}
 	return &album, nil
 }
 
+func (q *QobuzDownloader) getAlbumDetailsViaMusicDL(albumID string) (*qobuzAlbumDetails, error) {
+	requestURL := fmt.Sprintf("%s%s", qobuzFallbackAlbumGetBaseURL, url.QueryEscape(strings.TrimSpace(albumID)))
+	var album qobuzAlbumDetails
+	if err := q.getQobuzJSON(requestURL, &album); err != nil {
+		return nil, fmt.Errorf("qbz2 fallback also failed for album %s: %w", albumID, err)
+	}
+	GoLog("[Qobuz] qbz2 fallback succeeded for album %s\n", albumID)
+	return &album, nil
+}
+
 func (q *QobuzDownloader) getArtistDetails(artistID string) (*qobuzArtistDetails, error) {
 	requestURL := fmt.Sprintf("%s%s&app_id=%s", qobuzArtistGetBaseURL, url.QueryEscape(strings.TrimSpace(artistID)), q.appID)
 	var artist qobuzArtistDetails
 	if err := q.getQobuzJSON(requestURL, &artist); err != nil {
+		if isQobuzPrimaryUnavailable(err) {
+			GoLog("[Qobuz] Primary API unavailable for artist %s, trying qbz2 fallback: %v\n", artistID, err)
+			return q.getArtistDetailsViaMusicDL(artistID)
+		}
 		return nil, err
 	}
 	return &artist, nil
 }
 
+func (q *QobuzDownloader) getArtistDetailsViaMusicDL(artistID string) (*qobuzArtistDetails, error) {
+	requestURL := fmt.Sprintf("%s%s", qobuzFallbackArtistGetBaseURL, url.QueryEscape(strings.TrimSpace(artistID)))
+	var artist qobuzArtistDetails
+	if err := q.getQobuzJSON(requestURL, &artist); err != nil {
+		return nil, fmt.Errorf("qbz2 fallback also failed for artist %s: %w", artistID, err)
+	}
+	GoLog("[Qobuz] qbz2 fallback succeeded for artist %s\n", artistID)
+	return &artist, nil
+}
+
 func (q *QobuzDownloader) getPlaylistDetailsPage(playlistID string, limit, offset int) (*qobuzPlaylistDetails, error) {
 	requestURL := fmt.Sprintf(
 		"%s%s&extra=tracks&limit=%d&offset=%d&app_id=%s",
@@ -895,11 +961,31 @@ func (q *QobuzDownloader) getPlaylistDetailsPage(playlistID string, limit, offse
 	)
 	var playlist qobuzPlaylistDetails
 	if err := q.getQobuzJSON(requestURL, &playlist); err != nil {
+		if isQobuzPrimaryUnavailable(err) {
+			GoLog("[Qobuz] Primary API unavailable for playlist %s, trying qbz2 fallback: %v\n", playlistID, err)
+			return q.getPlaylistDetailsPageViaMusicDL(playlistID, limit, offset)
+		}
 		return nil, err
 	}
 	return &playlist, nil
 }
 
+func (q *QobuzDownloader) getPlaylistDetailsPageViaMusicDL(playlistID string, limit, offset int) (*qobuzPlaylistDetails, error) {
+	requestURL := fmt.Sprintf(
+		"%s%s&limit=%d&offset=%d",
+		qobuzFallbackPlaylistGetBaseURL,
+		url.QueryEscape(strings.TrimSpace(playlistID)),
+		limit,
+		offset,
+	)
+	var playlist qobuzPlaylistDetails
+	if err := q.getQobuzJSON(requestURL, &playlist); err != nil {
+		return nil, fmt.Errorf("qbz2 fallback also failed for playlist %s: %w", playlistID, err)
+	}
+	GoLog("[Qobuz] qbz2 fallback succeeded for playlist %s (offset=%d)\n", playlistID, offset)
+	return &playlist, nil
+}
+
 func (q *QobuzDownloader) getArtistAlbumIDs(artistID string) ([]string, error) {
 	artist, err := q.getArtistDetails(artistID)
 	if err != nil {
@@ -1062,9 +1148,7 @@ func (q *QobuzDownloader) GetAvailableProviders() []qobuzAPIProvider {
 	return []qobuzAPIProvider{
 		{Name: "musicdl", URL: qobuzDownloadAPIURL, Kind: qobuzAPIKindMusicDL},
 		{Name: "dabmusic", URL: qobuzDabMusicAPIURL, Kind: qobuzAPIKindStandard},
-		// "deeb" is mapped from the legacy reference fallback endpoint.
 		{Name: "deeb", URL: qobuzDeebAPIURL, Kind: qobuzAPIKindStandard},
-		// "qbz" comes from the desktop reference app and uses /api/track/{id}?quality=...
 		{Name: "qbz", URL: qobuzAfkarAPIURL, Kind: qobuzAPIKindStandard},
 		{Name: "squid", URL: qobuzSquidAPIURL, Kind: qobuzAPIKindStandard},
 	}
@@ -1215,14 +1299,6 @@ func mapQobuzQualityCodeToAPI(qualityCode string) string {
 	}
 }
 
-func getQobuzDebugKey() string {
-	decoded := make([]byte, len(qobuzDebugKeyObfuscated))
-	for i, b := range qobuzDebugKeyObfuscated {
-		decoded[i] = b ^ qobuzDebugKeyXORMask
-	}
-	return string(decoded)
-}
-
 func (q *QobuzDownloader) SearchTrackByISRC(isrc string) (*QobuzTrack, error) {
 	candidates, err := q.searchQobuzTracksWithFallback(isrc, 50)
 	if err != nil {
@@ -1375,9 +1451,10 @@ func (q *QobuzDownloader) SearchAll(query string, trackLimit, artistLimit int, f
 	}
 
 	if artistLimit > 0 {
-		searchURL := fmt.Sprintf("https://www.qobuz.com/api.json/0.2/artist/search?query=%s&limit=%d&app_id=%s",
-			url.QueryEscape(cleanQuery), artistLimit, q.appID)
+		searchURL := fmt.Sprintf("%sartist/search?query=%s&limit=%d&app_id=%s",
+			qobuzAPIBaseURL, url.QueryEscape(cleanQuery), artistLimit, q.appID)
 		req, err := http.NewRequest("GET", searchURL, nil)
+		artistSearchDone := false
 		if err == nil {
 			resp, reqErr := DoRequestWithUserAgent(q.client, req)
 			if reqErr == nil {
@@ -1402,20 +1479,30 @@ func (q *QobuzDownloader) SearchAll(query string, trackLimit, artistLimit int, f
 								Images: imageURL,
 							})
 						}
+						artistSearchDone = true
 					} else {
 						GoLog("[Qobuz] Artist search decode failed: %v\n", decErr)
 					}
+				} else if isQobuzPrimaryUnavailable(fmt.Errorf("HTTP %d", resp.StatusCode)) {
+					GoLog("[Qobuz] Artist search primary API returned HTTP %d, will try qbz2 fallback\n", resp.StatusCode)
 				}
 			} else {
 				GoLog("[Qobuz] Artist search request failed: %v\n", reqErr)
+				if isQobuzPrimaryUnavailable(reqErr) {
+					GoLog("[Qobuz] Primary API unavailable for artist search, will try qbz2 fallback\n")
+				}
 			}
 		}
+		if !artistSearchDone {
+			q.searchAllArtistsViaMusicDL(cleanQuery, artistLimit, result)
+		}
 	}
 
 	if albumLimit > 0 {
-		searchURL := fmt.Sprintf("https://www.qobuz.com/api.json/0.2/album/search?query=%s&limit=%d&app_id=%s",
-			url.QueryEscape(cleanQuery), albumLimit, q.appID)
+		searchURL := fmt.Sprintf("%salbum/search?query=%s&limit=%d&app_id=%s",
+			qobuzAPIBaseURL, url.QueryEscape(cleanQuery), albumLimit, q.appID)
 		req, err := http.NewRequest("GET", searchURL, nil)
+		albumSearchDone := false
 		if err == nil {
 			resp, reqErr := DoRequestWithUserAgent(q.client, req)
 			if reqErr == nil {
@@ -1440,20 +1527,81 @@ func (q *QobuzDownloader) SearchAll(query string, trackLimit, artistLimit int, f
 								AlbumType:   qobuzNormalizeAlbumType(album.ReleaseType, album.ProductType, album.TracksCount),
 							})
 						}
+						albumSearchDone = true
 					} else {
 						GoLog("[Qobuz] Album search decode failed: %v\n", decErr)
 					}
+				} else if isQobuzPrimaryUnavailable(fmt.Errorf("HTTP %d", resp.StatusCode)) {
+					GoLog("[Qobuz] Album search primary API returned HTTP %d, will try qbz2 fallback\n", resp.StatusCode)
 				}
 			} else {
 				GoLog("[Qobuz] Album search request failed: %v\n", reqErr)
+				if isQobuzPrimaryUnavailable(reqErr) {
+					GoLog("[Qobuz] Primary API unavailable for album search, will try qbz2 fallback\n")
+				}
 			}
 		}
+		if !albumSearchDone {
+			q.searchAllAlbumsViaMusicDL(cleanQuery, albumLimit, result)
+		}
 	}
 
 	GoLog("[Qobuz] SearchAll complete: %d tracks, %d artists, %d albums\n", len(result.Tracks), len(result.Artists), len(result.Albums))
 	return result, nil
 }
 
+func (q *QobuzDownloader) searchAllArtistsViaMusicDL(query string, limit int, result *SearchAllResult) {
+	requestURL := fmt.Sprintf("%sartist/search?query=%s&limit=%d", qobuzFallbackAPIBaseURL, url.QueryEscape(query), limit)
+	var searchResp struct {
+		Artists struct {
+			Items []struct {
+				ID    int64         `json:"id"`
+				Name  string        `json:"name"`
+				Image qobuzImageSet `json:"image"`
+			} `json:"items"`
+		} `json:"artists"`
+	}
+	if err := q.getQobuzJSON(requestURL, &searchResp); err != nil {
+		GoLog("[Qobuz] qbz2 fallback artist search also failed: %v\n", err)
+		return
+	}
+	GoLog("[Qobuz] qbz2 fallback artist search succeeded: %d artists\n", len(searchResp.Artists.Items))
+	for _, artist := range searchResp.Artists.Items {
+		imageURL := qobuzFirstNonEmpty(artist.Image.Large, artist.Image.Small, artist.Image.Thumbnail)
+		result.Artists = append(result.Artists, SearchArtistResult{
+			ID:     qobuzPrefixedNumericID(artist.ID),
+			Name:   strings.TrimSpace(artist.Name),
+			Images: imageURL,
+		})
+	}
+}
+
+func (q *QobuzDownloader) searchAllAlbumsViaMusicDL(query string, limit int, result *SearchAllResult) {
+	requestURL := fmt.Sprintf("%salbum/search?query=%s&limit=%d", qobuzFallbackAPIBaseURL, url.QueryEscape(query), limit)
+	var searchResp struct {
+		Albums struct {
+			Items []qobuzAlbumDetails `json:"items"`
+		} `json:"albums"`
+	}
+	if err := q.getQobuzJSON(requestURL, &searchResp); err != nil {
+		GoLog("[Qobuz] qbz2 fallback album search also failed: %v\n", err)
+		return
+	}
+	GoLog("[Qobuz] qbz2 fallback album search succeeded: %d albums\n", len(searchResp.Albums.Items))
+	for i := range searchResp.Albums.Items {
+		album := &searchResp.Albums.Items[i]
+		result.Albums = append(result.Albums, SearchAlbumResult{
+			ID:          qobuzPrefixedID(album.ID),
+			Name:        strings.TrimSpace(album.Title),
+			Artists:     qobuzArtistsDisplayName(album.Artists, album.Artist.Name),
+			Images:      qobuzAlbumImage(album),
+			ReleaseDate: qobuzNormalizeReleaseDate(album.ReleaseDateOriginal),
+			TotalTracks: album.TracksCount,
+			AlbumType:   qobuzNormalizeAlbumType(album.ReleaseType, album.ProductType, album.TracksCount),
+		})
+	}
+}
+
 func (q *QobuzDownloader) SearchTrackByMetadataWithDuration(trackName, artistName string, expectedDurationSec int) (*QobuzTrack, error) {
 	queries := []string{}
 
@@ -1645,12 +1793,22 @@ func (q *QobuzDownloader) searchQobuzTracksViaAPI(query string, limit int) ([]Qo
 
 	resp, err := DoRequestWithUserAgent(q.client, req)
 	if err != nil {
+		if isQobuzPrimaryUnavailable(err) {
+			GoLog("[Qobuz] Primary API unavailable for track search, trying qbz2 fallback: %v\n", err)
+			return q.searchQobuzTracksViaMusicDL(query, limit)
+		}
 		return nil, err
 	}
 	defer resp.Body.Close()
 
 	if resp.StatusCode != 200 {
-		return nil, fmt.Errorf("search failed: HTTP %d", resp.StatusCode)
+		body, _ := io.ReadAll(io.LimitReader(resp.Body, 512))
+		primaryErr := fmt.Errorf("search failed: HTTP %d (%s)", resp.StatusCode, strings.TrimSpace(string(body)))
+		if isQobuzPrimaryUnavailable(primaryErr) {
+			GoLog("[Qobuz] Primary API unavailable for track search, trying qbz2 fallback: %v\n", primaryErr)
+			return q.searchQobuzTracksViaMusicDL(query, limit)
+		}
+		return nil, primaryErr
 	}
 
 	var result struct {
@@ -1664,6 +1822,277 @@ func (q *QobuzDownloader) searchQobuzTracksViaAPI(query string, limit int) ([]Qo
 	return result.Tracks.Items, nil
 }
 
+func (q *QobuzDownloader) searchQobuzTracksViaMusicDL(query string, limit int) ([]QobuzTrack, error) {
+	requestURL := fmt.Sprintf("%s%s&limit=%d", qobuzFallbackTrackSearchBaseURL, url.QueryEscape(query), limit)
+	var result struct {
+		Tracks struct {
+			Items []QobuzTrack `json:"items"`
+		} `json:"tracks"`
+	}
+	if err := q.getQobuzJSON(requestURL, &result); err != nil {
+		return nil, fmt.Errorf("qbz2 fallback search also failed: %w", err)
+	}
+	GoLog("[Qobuz] qbz2 fallback search succeeded: %d tracks for '%s'\n", len(result.Tracks.Items), query)
+	return result.Tracks.Items, nil
+}
+
+type qobuzTrackSearchCandidate struct {
+	score int
+	track QobuzTrack
+}
+
+func qobuzNormalizedSearchText(value string) string {
+	return normalizeLooseArtistName(value)
+}
+
+func qobuzSearchTokens(value string) []string {
+	normalized := qobuzNormalizedSearchText(value)
+	if normalized == "" {
+		return nil
+	}
+
+	parts := strings.Fields(normalized)
+	tokens := make([]string, 0, len(parts))
+	seen := make(map[string]struct{}, len(parts))
+	for _, part := range parts {
+		if len(part) < 2 {
+			continue
+		}
+		if _, ok := seen[part]; ok {
+			continue
+		}
+		seen[part] = struct{}{}
+		tokens = append(tokens, part)
+	}
+	return tokens
+}
+
+func qobuzScoreTrackSearchCandidate(query string, track *QobuzTrack) int {
+	if track == nil {
+		return 0
+	}
+
+	queryNorm := qobuzNormalizedSearchText(query)
+	if queryNorm == "" {
+		return 0
+	}
+
+	titleNorm := qobuzNormalizedSearchText(track.Title)
+	displayNorm := qobuzNormalizedSearchText(qobuzTrackDisplayTitle(track))
+	artistNorm := qobuzNormalizedSearchText(qobuzTrackArtistName(track))
+	albumNorm := qobuzNormalizedSearchText(strings.TrimSpace(track.Album.Title))
+
+	score := 0
+
+	if qobuzTitlesMatch(query, track.Title) || qobuzTitlesMatch(query, qobuzTrackDisplayTitle(track)) {
+		score += 900
+	}
+
+	switch {
+	case queryNorm == titleNorm, queryNorm == displayNorm:
+		score += 1200
+	case (titleNorm != "" && strings.Contains(titleNorm, queryNorm)) ||
+		(displayNorm != "" && strings.Contains(displayNorm, queryNorm)):
+		score += 420
+	case (titleNorm != "" && strings.Contains(queryNorm, titleNorm)) ||
+		(displayNorm != "" && strings.Contains(queryNorm, displayNorm)):
+		score += 260
+	}
+
+	if artistNorm != "" && strings.Contains(queryNorm, artistNorm) {
+		score += 180
+	}
+	if albumNorm != "" && strings.Contains(queryNorm, albumNorm) {
+		score += 100
+	}
+
+	for _, token := range qobuzSearchTokens(query) {
+		switch {
+		case strings.Contains(titleNorm, token), strings.Contains(displayNorm, token):
+			score += 180
+		case strings.Contains(artistNorm, token):
+			score += 70
+		case strings.Contains(albumNorm, token):
+			score += 35
+		}
+	}
+
+	if track.ISRC != "" {
+		score += 15
+	}
+	if track.MaximumBitDepth >= 24 {
+		score += 10
+	}
+	if track.MaximumSamplingRate >= 88.2 {
+		score += 10
+	}
+
+	return score
+}
+
+func selectQobuzTracksFromAlbumSearchResults(
+	query string,
+	limit int,
+	albumSummaries []qobuzAlbumDetails,
+	loadAlbum func(string) (*qobuzAlbumDetails, error),
+) ([]QobuzTrack, error) {
+	if strings.TrimSpace(query) == "" {
+		return nil, fmt.Errorf("empty qobuz album-search fallback query")
+	}
+	if len(albumSummaries) == 0 {
+		return nil, fmt.Errorf("album search returned no albums")
+	}
+
+	candidates := make([]qobuzTrackSearchCandidate, 0, limit)
+	seenTrackIDs := make(map[int64]struct{})
+
+	for _, summary := range albumSummaries {
+		albumID := strings.TrimSpace(summary.ID)
+		if albumID == "" {
+			continue
+		}
+
+		album, err := loadAlbum(albumID)
+		if err != nil || album == nil {
+			continue
+		}
+
+		for i := range album.Tracks.Items {
+			track := album.Tracks.Items[i]
+			track.Album.ID = album.ID
+			track.Album.QobuzID = album.QobuzID
+			track.Album.Title = album.Title
+			track.Album.ReleaseDate = album.ReleaseDateOriginal
+			track.Album.TracksCount = album.TracksCount
+			track.Album.ProductType = album.ProductType
+			track.Album.ReleaseType = album.ReleaseType
+			track.Album.Artist.ID = album.Artist.ID
+			track.Album.Artist.Name = album.Artist.Name
+			track.Album.Artists = album.Artists
+			track.Album.Image = album.Image
+
+			if track.ID > 0 {
+				if _, ok := seenTrackIDs[track.ID]; ok {
+					continue
+				}
+				seenTrackIDs[track.ID] = struct{}{}
+			}
+
+			score := qobuzScoreTrackSearchCandidate(query, &track)
+			if score <= 0 {
+				continue
+			}
+
+			candidates = append(candidates, qobuzTrackSearchCandidate{
+				score: score,
+				track: track,
+			})
+		}
+	}
+
+	if len(candidates) == 0 {
+		return nil, fmt.Errorf("album-search fallback returned no scored track candidates")
+	}
+
+	sort.SliceStable(candidates, func(i, j int) bool {
+		if candidates[i].score != candidates[j].score {
+			return candidates[i].score > candidates[j].score
+		}
+		if candidates[i].track.MaximumBitDepth != candidates[j].track.MaximumBitDepth {
+			return candidates[i].track.MaximumBitDepth > candidates[j].track.MaximumBitDepth
+		}
+		return candidates[i].track.ID < candidates[j].track.ID
+	})
+
+	if limit > 0 && len(candidates) > limit {
+		candidates = candidates[:limit]
+	}
+
+	tracks := make([]QobuzTrack, 0, len(candidates))
+	for _, candidate := range candidates {
+		tracks = append(tracks, candidate.track)
+	}
+	return tracks, nil
+}
+
+func (q *QobuzDownloader) searchQobuzTracksViaAlbumSearch(query string, limit int) ([]QobuzTrack, error) {
+	albumLimit := limit
+	if albumLimit < 3 {
+		albumLimit = 3
+	}
+	if albumLimit > 8 {
+		albumLimit = 8
+	}
+
+	searchURL := fmt.Sprintf(
+		"%salbum/search?query=%s&limit=%d&app_id=%s",
+		qobuzAPIBaseURL,
+		url.QueryEscape(strings.TrimSpace(query)),
+		albumLimit,
+		q.appID,
+	)
+
+	req, err := http.NewRequest("GET", searchURL, nil)
+	if err != nil {
+		return nil, err
+	}
+
+	resp, err := DoRequestWithUserAgent(q.client, req)
+	if err != nil {
+		if isQobuzPrimaryUnavailable(err) {
+			GoLog("[Qobuz] Primary API unavailable for album search fallback, trying qbz2: %v\n", err)
+			return q.searchQobuzTracksViaAlbumSearchMusicDL(query, limit, albumLimit)
+		}
+		return nil, err
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != 200 {
+		body, _ := io.ReadAll(io.LimitReader(resp.Body, 512))
+		primaryErr := fmt.Errorf("album search failed: HTTP %d (%s)", resp.StatusCode, strings.TrimSpace(string(body)))
+		if isQobuzPrimaryUnavailable(primaryErr) {
+			GoLog("[Qobuz] Primary API unavailable for album search fallback, trying qbz2: %v\n", primaryErr)
+			return q.searchQobuzTracksViaAlbumSearchMusicDL(query, limit, albumLimit)
+		}
+		return nil, primaryErr
+	}
+
+	var albumResp struct {
+		Albums struct {
+			Items []qobuzAlbumDetails `json:"items"`
+		} `json:"albums"`
+	}
+	if err := json.NewDecoder(resp.Body).Decode(&albumResp); err != nil {
+		return nil, err
+	}
+
+	return selectQobuzTracksFromAlbumSearchResults(
+		query,
+		limit,
+		albumResp.Albums.Items,
+		q.getAlbumDetails,
+	)
+}
+
+func (q *QobuzDownloader) searchQobuzTracksViaAlbumSearchMusicDL(query string, limit, albumLimit int) ([]QobuzTrack, error) {
+	requestURL := fmt.Sprintf("%salbum/search?query=%s&limit=%d", qobuzFallbackAPIBaseURL, url.QueryEscape(strings.TrimSpace(query)), albumLimit)
+	var searchResp struct {
+		Albums struct {
+			Items []qobuzAlbumDetails `json:"items"`
+		} `json:"albums"`
+	}
+	if err := q.getQobuzJSON(requestURL, &searchResp); err != nil {
+		return nil, fmt.Errorf("qbz2 fallback album search also failed: %w", err)
+	}
+	GoLog("[Qobuz] qbz2 fallback album search returned %d albums\n", len(searchResp.Albums.Items))
+	return selectQobuzTracksFromAlbumSearchResults(
+		query,
+		limit,
+		searchResp.Albums.Items,
+		q.getAlbumDetails,
+	)
+}
+
 func extractQobuzTrackIDsFromStoreSearchHTML(body []byte) []int64 {
 	matches := qobuzStoreTrackIDRegex.FindAllSubmatch(body, -1)
 	if len(matches) == 0 {
@@ -1741,9 +2170,18 @@ func (q *QobuzDownloader) searchQobuzTracksWithFallback(query string, limit int)
 		if len(apiTracks) > 0 {
 			return apiTracks, nil
 		}
-		GoLog("[Qobuz] API search returned 0 results for '%s', trying store fallback\n", query)
+		GoLog("[Qobuz] API search returned 0 results for '%s', trying album-search fallback\n", query)
 	} else {
-		GoLog("[Qobuz] API search failed for '%s': %v. Trying store fallback.\n", query, apiErr)
+		GoLog("[Qobuz] API search failed for '%s': %v. Trying album-search fallback.\n", query, apiErr)
+	}
+
+	albumTracks, albumErr := q.searchQobuzTracksViaAlbumSearch(query, limit)
+	if albumErr == nil && len(albumTracks) > 0 {
+		GoLog("[Qobuz] Album-search fallback returned %d candidate tracks for '%s'\n", len(albumTracks), query)
+		return albumTracks, nil
+	}
+	if albumErr != nil {
+		GoLog("[Qobuz] Album-search fallback failed for '%s': %v. Trying store fallback.\n", query, albumErr)
 	}
 
 	storeTracks, storeErr := q.searchQobuzTracksViaStore(query, limit)
@@ -1752,10 +2190,21 @@ func (q *QobuzDownloader) searchQobuzTracksWithFallback(query string, limit int)
 		return storeTracks, nil
 	}
 
-	if apiErr != nil && storeErr != nil {
-		return nil, fmt.Errorf("api search failed (%v); store fallback failed (%v)", apiErr, storeErr)
+	if apiErr != nil && albumErr != nil && storeErr != nil {
+		return nil, fmt.Errorf(
+			"api search failed (%v); album-search fallback failed (%v); store fallback failed (%v)",
+			apiErr,
+			albumErr,
+			storeErr,
+		)
+	}
+	if albumErr == nil && len(albumTracks) == 0 && storeErr != nil {
+		return nil, storeErr
 	}
 	if storeErr != nil {
+		if albumErr != nil {
+			return nil, albumErr
+		}
 		return nil, storeErr
 	}
 	return nil, fmt.Errorf("no tracks found for query: %s", query)
@@ -2335,18 +2784,19 @@ func downloadFromQobuz(req DownloadRequest) (QobuzDownloadResult, error) {
 	}
 
 	metadata := Metadata{
-		Title:       track.Title,
-		Artist:      track.Performer.Name,
-		Album:       albumName,
-		AlbumArtist: req.AlbumArtist,
-		Date:        releaseDate,
-		TrackNumber: actualTrackNumber,
-		TotalTracks: req.TotalTracks,
-		DiscNumber:  req.DiscNumber,
-		ISRC:        track.ISRC,
-		Genre:       req.Genre,
-		Label:       req.Label,
-		Copyright:   req.Copyright,
+		Title:         track.Title,
+		Artist:        req.ArtistName,
+		Album:         albumName,
+		AlbumArtist:   req.AlbumArtist,
+		ArtistTagMode: req.ArtistTagMode,
+		Date:          releaseDate,
+		TrackNumber:   actualTrackNumber,
+		TotalTracks:   req.TotalTracks,
+		DiscNumber:    req.DiscNumber,
+		ISRC:          track.ISRC,
+		Genre:         req.Genre,
+		Label:         req.Label,
+		Copyright:     req.Copyright,
 	}
 
 	var coverData []byte
@@ -2411,6 +2861,15 @@ func downloadFromQobuz(req DownloadRequest) (QobuzDownloadResult, error) {
 		req.DiscNumber,
 	)
 
+	// Prefer the cover URL the frontend sent (user-selected album) over the
+	// track's default album cover returned by the Qobuz track/get API, which
+	// may belong to a different album when the same track appears on multiple
+	// releases.
+	resultCoverURL := strings.TrimSpace(req.CoverURL)
+	if resultCoverURL == "" {
+		resultCoverURL = strings.TrimSpace(qobuzTrackAlbumImage(track))
+	}
+
 	return QobuzDownloadResult{
 		FilePath:    outputPath,
 		BitDepth:    actualBitDepth,
@@ -2422,7 +2881,7 @@ func downloadFromQobuz(req DownloadRequest) (QobuzDownloadResult, error) {
 		TrackNumber: resultTrackNumber,
 		DiscNumber:  resultDiscNumber,
 		ISRC:        track.ISRC,
-		CoverURL:    strings.TrimSpace(qobuzTrackAlbumImage(track)),
+		CoverURL:    resultCoverURL,
 		LyricsLRC:   lyricsLRC,
 	}, nil
 }

go_backend/qobuz_test.go

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

go_backend/romaji.go

@@ -16,16 +16,13 @@ var hiraganaToRomaji = map[rune]string{
 	'や': "ya", 'ゆ': "yu", 'よ': "yo",
 	'ら': "ra", 'り': "ri", 'る': "ru", 'れ': "re", 'ろ': "ro",
 	'わ': "wa", 'を': "wo", 'ん': "n",
-	// Dakuten (voiced)
 	'が': "ga", 'ぎ': "gi", 'ぐ': "gu", 'げ': "ge", 'ご': "go",
 	'ざ': "za", 'じ': "ji", 'ず': "zu", 'ぜ': "ze", 'ぞ': "zo",
 	'だ': "da", 'ぢ': "ji", 'づ': "zu", 'で': "de", 'ど': "do",
 	'ば': "ba", 'び': "bi", 'ぶ': "bu", 'べ': "be", 'ぼ': "bo",
-	// Handakuten (semi-voiced)
 	'ぱ': "pa", 'ぴ': "pi", 'ぷ': "pu", 'ぺ': "pe", 'ぽ': "po",
-	// Small characters
 	'ゃ': "ya", 'ゅ': "yu", 'ょ': "yo",
-	'っ': "", // Double consonant marker
+	'っ': "",
 	'ぁ': "a", 'ぃ': "i", 'ぅ': "u", 'ぇ': "e", 'ぉ': "o",
 }
 
@@ -40,19 +37,15 @@ var katakanaToRomaji = map[rune]string{
 	'ヤ': "ya", 'ユ': "yu", 'ヨ': "yo",
 	'ラ': "ra", 'リ': "ri", 'ル': "ru", 'レ': "re", 'ロ': "ro",
 	'ワ': "wa", 'ヲ': "wo", 'ン': "n",
-	// Dakuten (voiced)
 	'ガ': "ga", 'ギ': "gi", 'グ': "gu", 'ゲ': "ge", 'ゴ': "go",
 	'ザ': "za", 'ジ': "ji", 'ズ': "zu", 'ゼ': "ze", 'ゾ': "zo",
 	'ダ': "da", 'ヂ': "ji", 'ヅ': "zu", 'デ': "de", 'ド': "do",
 	'バ': "ba", 'ビ': "bi", 'ブ': "bu", 'ベ': "be", 'ボ': "bo",
-	// Handakuten (semi-voiced)
 	'パ': "pa", 'ピ': "pi", 'プ': "pu", 'ペ': "pe", 'ポ': "po",
-	// Small characters
 	'ャ': "ya", 'ュ': "yu", 'ョ': "yo",
-	'ッ': "", // Double consonant marker
+	'ッ': "",
 	'ァ': "a", 'ィ': "i", 'ゥ': "u", 'ェ': "e", 'ォ': "o",
-	// Extended katakana
-	'ー': "", // Long vowel mark
+	'ー': "",
 	'ヴ': "vu",
 }
 
@@ -82,7 +75,6 @@ var combinationKatakana = map[string]string{
 	"ジャ": "ja", "ジュ": "ju", "ジョ": "jo",
 	"ビャ": "bya", "ビュ": "byu", "ビョ": "byo",
 	"ピャ": "pya", "ピュ": "pyu", "ピョ": "pyo",
-	// Extended combinations
 	"ティ": "ti", "ディ": "di", "トゥ": "tu", "ドゥ": "du",
 	"ファ": "fa", "フィ": "fi", "フェ": "fe", "フォ": "fo",
 	"ウィ": "wi", "ウェ": "we", "ウォ": "wo",
@@ -120,7 +112,6 @@ func JapaneseToRomaji(text string) string {
 	i := 0
 
 	for i < len(runes) {
-		// Check for っ/ッ (double consonant)
 		if i < len(runes)-1 && (runes[i] == 'っ' || runes[i] == 'ッ') {
 			nextRomaji := ""
 			if romaji, ok := hiraganaToRomaji[runes[i+1]]; ok {
@@ -129,13 +120,12 @@ func JapaneseToRomaji(text string) string {
 				nextRomaji = romaji
 			}
 			if len(nextRomaji) > 0 {
-				result.WriteByte(nextRomaji[0]) // Double the first consonant
+				result.WriteByte(nextRomaji[0])
 			}
 			i++
 			continue
 		}
 
-		// Check for two-character combinations
 		if i < len(runes)-1 {
 			combo := string(runes[i : i+2])
 			if romaji, ok := combinationHiragana[combo]; ok {
@@ -150,17 +140,14 @@ func JapaneseToRomaji(text string) string {
 			}
 		}
 
-		// Single character conversion
 		r := runes[i]
 		if romaji, ok := hiraganaToRomaji[r]; ok {
 			result.WriteString(romaji)
 		} else if romaji, ok := katakanaToRomaji[r]; ok {
 			result.WriteString(romaji)
 		} else if isKanji(r) {
-			// Keep kanji as-is (would need dictionary for proper conversion)
 			result.WriteRune(r)
 		} else {
-			// Keep other characters (punctuation, spaces, etc.)
 			result.WriteRune(r)
 		}
 		i++

go_backend/songlink.go

@@ -87,38 +87,210 @@ func GetSongLinkRegion() string {
 	return region
 }
 
+const resolveAPIURL = "https://api.zarz.moe/v1/resolve"
+
 func songLinkBaseURL() string {
-	opts := GetNetworkCompatibilityOptions()
-	if opts.AllowHTTP {
-		return "http://api.song.link/v1-alpha.1/links"
-	}
 	return "https://api.song.link/v1-alpha.1/links"
 }
 
-func buildSongLinkURLFromTarget(targetURL string, userCountry string) string {
-	if userCountry == "" {
-		userCountry = GetSongLinkRegion()
+// resolveTrackPlatforms resolves a music URL to all platforms.
+// Spotify URLs use the resolve API; if that fails, falls back to SongLink.
+// All other URLs go directly to SongLink.
+func (s *SongLinkClient) resolveTrackPlatforms(inputURL string) (map[string]songLinkPlatformLink, error) {
+	if isSpotifyURL(inputURL) {
+		payload, err := json.Marshal(map[string]string{"url": inputURL})
+		if err != nil {
+			return nil, fmt.Errorf("failed to encode resolve request: %w", err)
+		}
+		links, err := s.doResolveRequest(payload)
+		if err == nil {
+			return links, nil
+		}
+		GoLog("[SongLink] Resolve proxy failed for %s: %v, falling back to SongLink", inputURL, err)
+		return s.songLinkByTargetURL(inputURL)
 	}
-	apiURL := fmt.Sprintf("%s?url=%s", songLinkBaseURL(), url.QueryEscape(targetURL))
-	if userCountry != "" {
-		apiURL = fmt.Sprintf("%s&userCountry=%s", apiURL, url.QueryEscape(userCountry))
-	}
-	return apiURL
+	return s.songLinkByTargetURL(inputURL)
 }
 
-func buildSongLinkURLByPlatform(platform, entityType, entityID, userCountry string) string {
-	if userCountry == "" {
-		userCountry = GetSongLinkRegion()
+// resolveTrackPlatformsByPlatform resolves using platform + type + id.
+// Spotify uses the resolve API with SongLink fallback; all other platforms use SongLink directly.
+func (s *SongLinkClient) resolveTrackPlatformsByPlatform(platform, entityType, entityID string) (map[string]songLinkPlatformLink, error) {
+	if strings.EqualFold(platform, "spotify") {
+		payload, err := json.Marshal(map[string]string{
+			"platform": platform,
+			"type":     entityType,
+			"id":       entityID,
+		})
+		if err != nil {
+			return nil, fmt.Errorf("failed to encode resolve request: %w", err)
+		}
+		links, err := s.doResolveRequest(payload)
+		if err == nil {
+			return links, nil
+		}
+		GoLog("[SongLink] Resolve proxy failed for %s/%s/%s: %v, falling back to SongLink", platform, entityType, entityID, err)
+		return s.songLinkByPlatform(platform, entityType, entityID)
 	}
-	apiURL := fmt.Sprintf("%s?platform=%s&type=%s&id=%s",
+	return s.songLinkByPlatform(platform, entityType, entityID)
+}
+
+func isSpotifyURL(u string) bool {
+	lower := strings.ToLower(u)
+	return strings.Contains(lower, "spotify.com/") || strings.Contains(lower, "spotify:")
+}
+
+// doResolveRequest sends a JSON payload to the resolve API (api.zarz.moe)
+// and parses the response into a platform link map.
+func (s *SongLinkClient) doResolveRequest(payload []byte) (map[string]songLinkPlatformLink, error) {
+	req, err := http.NewRequest("POST", resolveAPIURL, bytes.NewReader(payload))
+	if err != nil {
+		return nil, fmt.Errorf("failed to create resolve request: %w", err)
+	}
+	req.Header.Set("Content-Type", "application/json")
+
+	resp, err := s.client.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("resolve API request failed: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != 200 {
+		return nil, fmt.Errorf("resolve API returned status %d", resp.StatusCode)
+	}
+
+	body, err := ReadResponseBody(resp)
+	if err != nil {
+		return nil, fmt.Errorf("failed to read resolve response: %w", err)
+	}
+
+	var resolveResp struct {
+		Success  bool                           `json:"success"`
+		ISRC     string                         `json:"isrc"`
+		SongUrls map[string]json.RawMessage     `json:"songUrls"`
+	}
+	if err := json.Unmarshal(body, &resolveResp); err != nil {
+		return nil, fmt.Errorf("failed to decode resolve response: %w", err)
+	}
+	if !resolveResp.Success {
+		return nil, fmt.Errorf("resolve API returned success=false")
+	}
+
+	keyMap := map[string]string{
+		"Spotify":      "spotify",
+		"Deezer":       "deezer",
+		"Tidal":        "tidal",
+		"YouTubeMusic": "youtubeMusic",
+		"YouTube":      "youtube",
+		"AmazonMusic":  "amazonMusic",
+		"Qobuz":        "qobuz",
+		"AppleMusic":   "appleMusic",
+	}
+
+	links := make(map[string]songLinkPlatformLink)
+	for resolveKey, platformKey := range keyMap {
+		rawValue, ok := resolveResp.SongUrls[resolveKey]
+		if !ok {
+			continue
+		}
+		if u := extractResolveURLValue(rawValue); u != "" {
+			links[platformKey] = songLinkPlatformLink{URL: u}
+		}
+	}
+
+	if len(links) == 0 {
+		return nil, fmt.Errorf("resolve API returned no platform links")
+	}
+
+	return links, nil
+}
+
+func extractResolveURLValue(raw json.RawMessage) string {
+	trimmed := bytes.TrimSpace(raw)
+	if len(trimmed) == 0 || bytes.Equal(trimmed, []byte("null")) {
+		return ""
+	}
+
+	var direct string
+	if err := json.Unmarshal(trimmed, &direct); err == nil {
+		return strings.TrimSpace(direct)
+	}
+
+	var list []string
+	if err := json.Unmarshal(trimmed, &list); err == nil {
+		for _, candidate := range list {
+			if cleaned := strings.TrimSpace(candidate); cleaned != "" {
+				return cleaned
+			}
+		}
+	}
+
+	return ""
+}
+
+// songLinkByTargetURL calls the SongLink API with a target URL (for non-Spotify URLs).
+func (s *SongLinkClient) songLinkByTargetURL(targetURL string) (map[string]songLinkPlatformLink, error) {
+	songLinkRateLimiter.WaitForSlot()
+
+	apiURL := fmt.Sprintf("%s?url=%s&userCountry=%s",
+		songLinkBaseURL(),
+		url.QueryEscape(targetURL),
+		url.QueryEscape(GetSongLinkRegion()))
+
+	return s.doSongLinkRequest(apiURL)
+}
+
+// songLinkByPlatform calls the SongLink API with platform + type + id (for non-Spotify platforms).
+func (s *SongLinkClient) songLinkByPlatform(platform, entityType, entityID string) (map[string]songLinkPlatformLink, error) {
+	songLinkRateLimiter.WaitForSlot()
+
+	apiURL := fmt.Sprintf("%s?platform=%s&type=%s&id=%s&userCountry=%s",
 		songLinkBaseURL(),
 		url.QueryEscape(platform),
 		url.QueryEscape(entityType),
-		url.QueryEscape(entityID))
-	if userCountry != "" {
-		apiURL = fmt.Sprintf("%s&userCountry=%s", apiURL, url.QueryEscape(userCountry))
+		url.QueryEscape(entityID),
+		url.QueryEscape(GetSongLinkRegion()))
+
+	return s.doSongLinkRequest(apiURL)
+}
+
+// doSongLinkRequest calls the SongLink API and parses the response.
+func (s *SongLinkClient) doSongLinkRequest(apiURL string) (map[string]songLinkPlatformLink, error) {
+	req, err := http.NewRequest("GET", apiURL, nil)
+	if err != nil {
+		return nil, fmt.Errorf("failed to create SongLink request: %w", err)
 	}
-	return apiURL
+
+	retryConfig := songLinkRetryConfig()
+	resp, err := DoRequestWithRetry(s.client, req, retryConfig)
+	if err != nil {
+		return nil, fmt.Errorf("SongLink request failed: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode == 429 {
+		return nil, fmt.Errorf("SongLink rate limit exceeded")
+	}
+	if resp.StatusCode != 200 {
+		return nil, fmt.Errorf("SongLink returned status %d", resp.StatusCode)
+	}
+
+	body, err := ReadResponseBody(resp)
+	if err != nil {
+		return nil, fmt.Errorf("failed to read SongLink response: %w", err)
+	}
+
+	var songLinkResp struct {
+		LinksByPlatform map[string]songLinkPlatformLink `json:"linksByPlatform"`
+	}
+	if err := json.Unmarshal(body, &songLinkResp); err != nil {
+		return nil, fmt.Errorf("failed to decode SongLink response: %w", err)
+	}
+
+	if len(songLinkResp.LinksByPlatform) == 0 {
+		return nil, fmt.Errorf("SongLink returned no platform links")
+	}
+
+	return songLinkResp.LinksByPlatform, nil
 }
 
 func (s *SongLinkClient) CheckTrackAvailability(spotifyTrackID string, isrc string) (*TrackAvailability, error) {
@@ -136,145 +308,12 @@ func (s *SongLinkClient) CheckTrackAvailability(spotifyTrackID string, isrc stri
 }
 
 func (s *SongLinkClient) checkTrackAvailabilityFromSpotify(spotifyTrackID string) (*TrackAvailability, error) {
-	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, "")
-
-	req, err := http.NewRequest("GET", apiURL, nil)
+	links, err := s.resolveTrackPlatforms(spotifyURL)
 	if err != nil {
-		return nil, fmt.Errorf("failed to create request: %w", err)
+		return nil, fmt.Errorf("resolve proxy failed for Spotify %s: %w", spotifyTrackID, err)
 	}
-
-	retryConfig := songLinkRetryConfig()
-	resp, err := DoRequestWithRetry(s.client, req, retryConfig)
-	if err != nil {
-		return nil, fmt.Errorf("song.link page lookup failed: %w; SongLink API lookup failed: %w", pageErr, err)
-	}
-	defer resp.Body.Close()
-
-	if resp.StatusCode == 400 {
-		return nil, fmt.Errorf("track not found on SongLink (invalid Spotify ID or track unavailable)")
-	}
-	if resp.StatusCode == 404 {
-		return nil, fmt.Errorf("track not found on any streaming platform")
-	}
-	if resp.StatusCode == 429 {
-		return nil, fmt.Errorf("song.link page lookup failed: %w; SongLink API rate limit exceeded", pageErr)
-	}
-	if resp.StatusCode != 200 {
-		return nil, fmt.Errorf("song.link page lookup failed: %w; SongLink API returned status %d", pageErr, resp.StatusCode)
-	}
-
-	body, err := ReadResponseBody(resp)
-	if err != nil {
-		return nil, fmt.Errorf("failed to read response: %w", err)
-	}
-
-	var songLinkResp struct {
-		LinksByPlatform map[string]songLinkPlatformLink `json:"linksByPlatform"`
-	}
-
-	if err := json.Unmarshal(body, &songLinkResp); err != nil {
-		return nil, fmt.Errorf("failed to decode response: %w", err)
-	}
-
-	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)
-	}
-
-	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)
-	}
-
-	body, err := ReadResponseBody(resp)
-	if err != nil {
-		return nil, fmt.Errorf("failed to read song.link page: %w", err)
-	}
-
-	nextDataJSON, err := extractSongLinkNextDataJSON(body)
-	if err != nil {
-		return nil, err
-	}
-
-	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)
-	}
-
-	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}
-		}
-	}
-
-	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
+	return buildTrackAvailabilityFromSongLinkLinks(spotifyTrackID, links), nil
 }
 
 func (s *SongLinkClient) checkTrackAvailabilityFromISRC(isrc string) (*TrackAvailability, error) {
@@ -469,8 +508,6 @@ func extractYouTubeIDFromURL(youtubeURL string) string {
 	return ""
 }
 
-// isNumeric is defined in library_scan.go
-
 func (s *SongLinkClient) GetDeezerIDFromSpotify(spotifyTrackID string) (string, error) {
 	availability, err := s.CheckTrackAvailability(spotifyTrackID, "")
 	if err != nil {
@@ -505,47 +542,17 @@ type AlbumAvailability struct {
 }
 
 func (s *SongLinkClient) CheckAlbumAvailability(spotifyAlbumID string) (*AlbumAvailability, error) {
-	songLinkRateLimiter.WaitForSlot()
-
 	spotifyURL := fmt.Sprintf("https://open.spotify.com/album/%s", spotifyAlbumID)
-	apiURL := buildSongLinkURLFromTarget(spotifyURL, "")
-
-	req, err := http.NewRequest("GET", apiURL, nil)
+	links, err := s.resolveTrackPlatforms(spotifyURL)
 	if err != nil {
-		return nil, fmt.Errorf("failed to create request: %w", err)
-	}
-
-	retryConfig := songLinkRetryConfig()
-	resp, err := DoRequestWithRetry(s.client, req, retryConfig)
-	if err != nil {
-		return nil, fmt.Errorf("failed to check album availability: %w", err)
-	}
-	defer resp.Body.Close()
-
-	if resp.StatusCode != 200 {
-		return nil, fmt.Errorf("API returned status %d", resp.StatusCode)
-	}
-
-	body, err := ReadResponseBody(resp)
-	if err != nil {
-		return nil, fmt.Errorf("failed to read response: %w", err)
-	}
-
-	var songLinkResp struct {
-		LinksByPlatform map[string]struct {
-			URL string `json:"url"`
-		} `json:"linksByPlatform"`
-	}
-
-	if err := json.Unmarshal(body, &songLinkResp); err != nil {
-		return nil, fmt.Errorf("failed to decode response: %w", err)
+		return nil, fmt.Errorf("resolve proxy failed for album %s: %w", spotifyAlbumID, err)
 	}
 
 	availability := &AlbumAvailability{
 		SpotifyID: spotifyAlbumID,
 	}
 
-	if deezerLink, ok := songLinkResp.LinksByPlatform["deezer"]; ok && deezerLink.URL != "" {
+	if deezerLink, ok := links["deezer"]; ok && deezerLink.URL != "" {
 		availability.Deezer = true
 		availability.DeezerURL = deezerLink.URL
 		availability.DeezerID = extractDeezerIDFromURL(deezerLink.URL)
@@ -588,101 +595,19 @@ func (s *SongLinkClient) CheckAvailabilityFromDeezer(deezerTrackID string) (*Tra
 }
 
 func (s *SongLinkClient) checkAvailabilityFromDeezerSongLink(deezerTrackID string) (*TrackAvailability, error) {
-	songLinkRateLimiter.WaitForSlot()
-
 	deezerURL := fmt.Sprintf("https://www.deezer.com/track/%s", deezerTrackID)
-	apiURL := buildSongLinkURLFromTarget(deezerURL, "")
-
-	req, err := http.NewRequest("GET", apiURL, nil)
+	links, err := s.resolveTrackPlatforms(deezerURL)
 	if err != nil {
-		return nil, fmt.Errorf("failed to create request: %w", err)
+		return nil, fmt.Errorf("resolve failed for Deezer %s: %w", deezerTrackID, err)
 	}
 
-	retryConfig := songLinkRetryConfig()
-	resp, err := DoRequestWithRetry(s.client, req, retryConfig)
-	if err != nil {
-		return nil, fmt.Errorf("failed to check availability: %w", err)
+	availability := buildTrackAvailabilityFromSongLinkLinks("", links)
+	// Ensure Deezer is always marked available since we started from a Deezer URL
+	availability.Deezer = true
+	availability.DeezerID = deezerTrackID
+	if availability.DeezerURL == "" {
+		availability.DeezerURL = deezerURL
 	}
-	defer resp.Body.Close()
-
-	if resp.StatusCode == 400 {
-		return nil, fmt.Errorf("track not found on SongLink (invalid Deezer ID)")
-	}
-	if resp.StatusCode == 404 {
-		return nil, fmt.Errorf("track not found on any streaming platform")
-	}
-	if resp.StatusCode == 429 {
-		return nil, fmt.Errorf("SongLink rate limit exceeded")
-	}
-	if resp.StatusCode != 200 {
-		return nil, fmt.Errorf("SongLink API returned status %d", resp.StatusCode)
-	}
-
-	body, err := ReadResponseBody(resp)
-	if err != nil {
-		return nil, fmt.Errorf("failed to read response: %w", err)
-	}
-
-	var songLinkResp struct {
-		LinksByPlatform map[string]struct {
-			URL string `json:"url"`
-		} `json:"linksByPlatform"`
-		EntitiesByUniqueId map[string]struct {
-			ID         string `json:"id"`
-			Type       string `json:"type"`
-			Title      string `json:"title"`
-			ArtistName string `json:"artistName"`
-		} `json:"entitiesByUniqueId"`
-	}
-
-	if err := json.Unmarshal(body, &songLinkResp); err != nil {
-		return nil, fmt.Errorf("failed to decode response: %w", err)
-	}
-
-	availability := &TrackAvailability{
-		Deezer:   true,
-		DeezerID: deezerTrackID,
-	}
-
-	if spotifyLink, ok := songLinkResp.LinksByPlatform["spotify"]; ok && spotifyLink.URL != "" {
-		availability.SpotifyID = extractSpotifyIDFromURL(spotifyLink.URL)
-	}
-
-	if tidalLink, ok := songLinkResp.LinksByPlatform["tidal"]; ok && tidalLink.URL != "" {
-		availability.Tidal = true
-		availability.TidalURL = tidalLink.URL
-		availability.TidalID = extractTidalIDFromURL(tidalLink.URL)
-	}
-
-	if amazonLink, ok := songLinkResp.LinksByPlatform["amazonMusic"]; ok && amazonLink.URL != "" {
-		availability.Amazon = true
-		availability.AmazonURL = amazonLink.URL
-	}
-
-	if qobuzLink, ok := songLinkResp.LinksByPlatform["qobuz"]; ok && qobuzLink.URL != "" {
-		availability.Qobuz = true
-		availability.QobuzURL = qobuzLink.URL
-		availability.QobuzID = extractQobuzIDFromURL(qobuzLink.URL)
-	}
-
-	if deezerLink, ok := songLinkResp.LinksByPlatform["deezer"]; ok && deezerLink.URL != "" {
-		availability.DeezerURL = deezerLink.URL
-	}
-
-	// Prefer youtubeMusic URLs — they are usually closer to music catalog matches.
-	if ytMusicLink, ok := songLinkResp.LinksByPlatform["youtubeMusic"]; ok && ytMusicLink.URL != "" {
-		availability.YouTube = true
-		availability.YouTubeURL = ytMusicLink.URL
-		availability.YouTubeID = extractYouTubeIDFromURL(ytMusicLink.URL)
-	}
-	if !availability.YouTube {
-		if youtubeLink, ok := songLinkResp.LinksByPlatform["youtube"]; ok && youtubeLink.URL != "" {
-			availability.YouTube = true
-			availability.YouTubeURL = youtubeLink.URL
-			availability.YouTubeID = extractYouTubeIDFromURL(youtubeLink.URL)
-		}
-	}
-
 	return availability, nil
 }
 
@@ -694,94 +619,12 @@ func (s *SongLinkClient) CheckAvailabilityByPlatform(platform, entityType, entit
 		return nil, fmt.Errorf("%s ID is empty", platform)
 	}
 
-	songLinkRateLimiter.WaitForSlot()
-
-	apiURL := buildSongLinkURLByPlatform(platform, entityType, entityID, "")
-
-	req, err := http.NewRequest("GET", apiURL, nil)
+	links, err := s.resolveTrackPlatformsByPlatform(platform, entityType, entityID)
 	if err != nil {
-		return nil, fmt.Errorf("failed to create request: %w", err)
+		return nil, fmt.Errorf("resolve failed for %s %s: %w", platform, entityID, err)
 	}
 
-	retryConfig := songLinkRetryConfig()
-	resp, err := DoRequestWithRetry(s.client, req, retryConfig)
-	if err != nil {
-		return nil, fmt.Errorf("failed to check availability: %w", err)
-	}
-	defer resp.Body.Close()
-
-	if resp.StatusCode == 400 {
-		return nil, fmt.Errorf("track not found on SongLink (invalid %s ID)", platform)
-	}
-	if resp.StatusCode == 404 {
-		return nil, fmt.Errorf("track not found on any streaming platform")
-	}
-	if resp.StatusCode == 429 {
-		return nil, fmt.Errorf("SongLink rate limit exceeded")
-	}
-	if resp.StatusCode != 200 {
-		return nil, fmt.Errorf("SongLink API returned status %d", resp.StatusCode)
-	}
-
-	body, err := ReadResponseBody(resp)
-	if err != nil {
-		return nil, fmt.Errorf("failed to read response: %w", err)
-	}
-
-	var songLinkResp struct {
-		LinksByPlatform map[string]struct {
-			URL string `json:"url"`
-		} `json:"linksByPlatform"`
-	}
-
-	if err := json.Unmarshal(body, &songLinkResp); err != nil {
-		return nil, fmt.Errorf("failed to decode response: %w", err)
-	}
-
-	availability := &TrackAvailability{}
-
-	if spotifyLink, ok := songLinkResp.LinksByPlatform["spotify"]; ok && spotifyLink.URL != "" {
-		availability.SpotifyID = extractSpotifyIDFromURL(spotifyLink.URL)
-	}
-
-	if tidalLink, ok := songLinkResp.LinksByPlatform["tidal"]; ok && tidalLink.URL != "" {
-		availability.Tidal = true
-		availability.TidalURL = tidalLink.URL
-		availability.TidalID = extractTidalIDFromURL(tidalLink.URL)
-	}
-
-	if amazonLink, ok := songLinkResp.LinksByPlatform["amazonMusic"]; ok && amazonLink.URL != "" {
-		availability.Amazon = true
-		availability.AmazonURL = amazonLink.URL
-	}
-
-	if qobuzLink, ok := songLinkResp.LinksByPlatform["qobuz"]; ok && qobuzLink.URL != "" {
-		availability.Qobuz = true
-		availability.QobuzURL = qobuzLink.URL
-		availability.QobuzID = extractQobuzIDFromURL(qobuzLink.URL)
-	}
-
-	if deezerLink, ok := songLinkResp.LinksByPlatform["deezer"]; ok && deezerLink.URL != "" {
-		availability.Deezer = true
-		availability.DeezerURL = deezerLink.URL
-		availability.DeezerID = extractDeezerIDFromURL(deezerLink.URL)
-	}
-
-	// Prefer youtubeMusic URLs — they are usually closer to music catalog matches.
-	if ytMusicLink, ok := songLinkResp.LinksByPlatform["youtubeMusic"]; ok && ytMusicLink.URL != "" {
-		availability.YouTube = true
-		availability.YouTubeURL = ytMusicLink.URL
-		availability.YouTubeID = extractYouTubeIDFromURL(ytMusicLink.URL)
-	}
-	if !availability.YouTube {
-		if youtubeLink, ok := songLinkResp.LinksByPlatform["youtube"]; ok && youtubeLink.URL != "" {
-			availability.YouTube = true
-			availability.YouTubeURL = youtubeLink.URL
-			availability.YouTubeID = extractYouTubeIDFromURL(youtubeLink.URL)
-		}
-	}
-
-	return availability, nil
+	return buildTrackAvailabilityFromSongLinkLinks("", links), nil
 }
 
 func buildTrackAvailabilityFromSongLinkLinks(spotifyTrackID string, links map[string]songLinkPlatformLink) *TrackAvailability {
@@ -894,85 +737,10 @@ func (s *SongLinkClient) GetYouTubeURLFromDeezer(deezerTrackID string) (string,
 }
 
 func (s *SongLinkClient) CheckAvailabilityFromURL(inputURL string) (*TrackAvailability, error) {
-	songLinkRateLimiter.WaitForSlot()
-
-	apiURL := buildSongLinkURLFromTarget(inputURL, "")
-
-	req, err := http.NewRequest("GET", apiURL, nil)
+	links, err := s.resolveTrackPlatforms(inputURL)
 	if err != nil {
-		return nil, fmt.Errorf("failed to create request: %w", err)
+		return nil, fmt.Errorf("resolve failed for URL %s: %w", inputURL, err)
 	}
 
-	retryConfig := songLinkRetryConfig()
-	resp, err := DoRequestWithRetry(s.client, req, retryConfig)
-	if err != nil {
-		return nil, fmt.Errorf("failed to check availability: %w", err)
-	}
-	defer resp.Body.Close()
-
-	if resp.StatusCode == 400 || resp.StatusCode == 404 {
-		return nil, fmt.Errorf("track not found on SongLink")
-	}
-	if resp.StatusCode == 429 {
-		return nil, fmt.Errorf("SongLink rate limit exceeded")
-	}
-	if resp.StatusCode != 200 {
-		return nil, fmt.Errorf("SongLink API returned status %d", resp.StatusCode)
-	}
-
-	body, err := ReadResponseBody(resp)
-	if err != nil {
-		return nil, fmt.Errorf("failed to read response: %w", err)
-	}
-
-	var songLinkResp struct {
-		LinksByPlatform map[string]struct {
-			URL      string `json:"url"`
-			EntityID string `json:"entityUniqueId"`
-		} `json:"linksByPlatform"`
-	}
-
-	if err := json.Unmarshal(body, &songLinkResp); err != nil {
-		return nil, fmt.Errorf("failed to decode response: %w", err)
-	}
-
-	availability := &TrackAvailability{}
-
-	if spotifyLink, ok := songLinkResp.LinksByPlatform["spotify"]; ok && spotifyLink.URL != "" {
-		availability.SpotifyID = extractSpotifyIDFromURL(spotifyLink.URL)
-	}
-	if tidalLink, ok := songLinkResp.LinksByPlatform["tidal"]; ok && tidalLink.URL != "" {
-		availability.Tidal = true
-		availability.TidalURL = tidalLink.URL
-		availability.TidalID = extractTidalIDFromURL(tidalLink.URL)
-	}
-	if amazonLink, ok := songLinkResp.LinksByPlatform["amazonMusic"]; ok && amazonLink.URL != "" {
-		availability.Amazon = true
-		availability.AmazonURL = amazonLink.URL
-	}
-	if qobuzLink, ok := songLinkResp.LinksByPlatform["qobuz"]; ok && qobuzLink.URL != "" {
-		availability.Qobuz = true
-		availability.QobuzURL = qobuzLink.URL
-		availability.QobuzID = extractQobuzIDFromURL(qobuzLink.URL)
-	}
-	if deezerLink, ok := songLinkResp.LinksByPlatform["deezer"]; ok && deezerLink.URL != "" {
-		availability.Deezer = true
-		availability.DeezerURL = deezerLink.URL
-		availability.DeezerID = extractDeezerIDFromURL(deezerLink.URL)
-	}
-	// Prefer youtubeMusic URLs — they are usually closer to music catalog matches.
-	if ytMusicLink, ok := songLinkResp.LinksByPlatform["youtubeMusic"]; ok && ytMusicLink.URL != "" {
-		availability.YouTube = true
-		availability.YouTubeURL = ytMusicLink.URL
-		availability.YouTubeID = extractYouTubeIDFromURL(ytMusicLink.URL)
-	}
-	if !availability.YouTube {
-		if youtubeLink, ok := songLinkResp.LinksByPlatform["youtube"]; ok && youtubeLink.URL != "" {
-			availability.YouTube = true
-			availability.YouTubeURL = youtubeLink.URL
-			availability.YouTubeID = extractYouTubeIDFromURL(youtubeLink.URL)
-		}
-	}
-
-	return availability, nil
+	return buildTrackAvailabilityFromSongLinkLinks("", links), nil
 }

go_backend/songlink_test.go

@@ -23,26 +23,24 @@ func TestGetRetryAfterDurationMissingHeaderReturnsZero(t *testing.T) {
 	}
 }
 
-func TestCheckTrackAvailabilityFromSpotifyPrefersSongLinkPage(t *testing.T) {
+func TestCheckTrackAvailabilityFromSpotifyViaResolveAPI(t *testing.T) {
+	origRetryConfig := songLinkRetryConfig
+	defer func() { songLinkRetryConfig = origRetryConfig }()
+
 	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>`
+				if req.URL.Host == "api.zarz.moe" && req.URL.Path == "/v1/resolve" && req.Method == "POST" {
+					body := `{"success":true,"isrc":"USRC12345678","songUrls":{"Spotify":"https://open.spotify.com/track/testspotifyid","Deezer":"https://www.deezer.com/track/908604612","AmazonMusic":"https://music.amazon.com/albums/B086Q2QNLH?trackAsin=B086Q41M9C","Tidal":"https://listen.tidal.com/track/134858527","Qobuz":"https://open.qobuz.com/track/195125822","YouTubeMusic":"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
 				}
+				t.Fatalf("unexpected request: %s %s", req.Method, req.URL.String())
+				return nil, nil
 			}),
 		},
 	}
@@ -66,62 +64,136 @@ func TestCheckTrackAvailabilityFromSpotifyPrefersSongLinkPage(t *testing.T) {
 	}
 }
 
-func TestCheckTrackAvailabilityFromSpotifyFallsBackToAPIWhenPageFails(t *testing.T) {
+func TestCheckTrackAvailabilityFromSpotifyResolveAPIFailure(t *testing.T) {
 	origRetryConfig := songLinkRetryConfig
 	songLinkRetryConfig = func() RetryConfig {
-		return RetryConfig{
-			MaxRetries:    0,
-			InitialDelay:  0,
-			MaxDelay:      0,
-			BackoffFactor: 1,
-		}
+		return RetryConfig{MaxRetries: 0, InitialDelay: 0, MaxDelay: 0, BackoffFactor: 1}
 	}
-	defer func() {
-		songLinkRetryConfig = origRetryConfig
-	}()
+	defer func() { songLinkRetryConfig = origRetryConfig }()
+
+	var hitSongLink bool
 
 	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":
+				// Resolve proxy returns 500
+				if req.URL.Host == "api.zarz.moe" && req.URL.Path == "/v1/resolve" {
 					return &http.Response{
 						StatusCode: 500,
 						Header:     make(http.Header),
-						Body:       io.NopCloser(strings.NewReader("page failure")),
+						Body:       io.NopCloser(strings.NewReader("internal error")),
 						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"}}}`
+				}
+				// SongLink fallback should be called
+				if req.URL.Host == "api.song.link" {
+					hitSongLink = true
+					body := `{"linksByPlatform":{"spotify":{"url":"https://open.spotify.com/track/testspotifyid"},"deezer":{"url":"https://www.deezer.com/track/908604612"},"tidal":{"url":"https://listen.tidal.com/track/134858527"}}}`
 					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
 				}
+				t.Fatalf("unexpected request: %s %s", req.Method, req.URL.String())
+				return nil, nil
 			}),
 		},
 	}
 
 	availability, err := client.CheckTrackAvailability("testspotifyid", "")
+	if err != nil {
+		t.Fatalf("expected SongLink fallback to succeed, got error: %v", err)
+	}
+	if !hitSongLink {
+		t.Fatal("expected fallback request to SongLink API, but it was never called")
+	}
+	if !availability.Deezer || availability.DeezerID != "908604612" {
+		t.Fatalf("Deezer availability via fallback = %+v, want DeezerID 908604612", availability)
+	}
+}
+
+func TestCheckTrackAvailabilityFromSpotifyViaResolveAPIMixedSongURLShapes(t *testing.T) {
+	origRetryConfig := songLinkRetryConfig
+	defer func() { songLinkRetryConfig = origRetryConfig }()
+
+	client := &SongLinkClient{
+		client: &http.Client{
+			Transport: roundTripFunc(func(req *http.Request) (*http.Response, error) {
+				if req.URL.Host == "api.zarz.moe" && req.URL.Path == "/v1/resolve" && req.Method == "POST" {
+					body := `{"success":true,"isrc":"TCAHA2367688","songUrls":{"Spotify":"https://open.spotify.com/track/5glgyj6zH0irbNGfukHacv","Deezer":"https://www.deezer.com/track/2248583177","Tidal":"https://tidal.com/browse/track/290565315","AppleMusic":"https://geo.music.apple.com/us/album/example?i=1","YouTubeMusic":null,"YouTube":"https://www.youtube.com/watch?v=wD_e59XUNdQ","AmazonMusic":"https://music.amazon.com/tracks/B0C35TG38Y/?ref=dm_ff_amazonmusic_3p","Beatport":null,"BeatSource":null,"SoundCloud":null,"Qobuz":null,"Other":[]}}`
+					return &http.Response{
+						StatusCode: 200,
+						Header:     make(http.Header),
+						Body:       io.NopCloser(strings.NewReader(body)),
+						Request:    req,
+					}, nil
+				}
+				t.Fatalf("unexpected request: %s %s", req.Method, req.URL.String())
+				return nil, nil
+			}),
+		},
+	}
+
+	availability, err := client.CheckTrackAvailability("5glgyj6zH0irbNGfukHacv", "")
 	if err != nil {
 		t.Fatalf("CheckTrackAvailability() error = %v", err)
 	}
 
-	if availability.SpotifyID != "testspotifyid" {
-		t.Fatalf("SpotifyID = %q, want %q", availability.SpotifyID, "testspotifyid")
+	if availability.SpotifyID != "5glgyj6zH0irbNGfukHacv" {
+		t.Fatalf("SpotifyID = %q, want %q", availability.SpotifyID, "5glgyj6zH0irbNGfukHacv")
 	}
-	if !availability.Deezer || availability.DeezerID != "908604612" {
-		t.Fatalf("Deezer availability = %+v, want DeezerID 908604612", availability)
+	if !availability.Deezer || availability.DeezerID != "2248583177" {
+		t.Fatalf("Deezer availability = %+v, want DeezerID 2248583177", availability)
 	}
-	if !availability.Amazon || !availability.Tidal || !availability.Qobuz || !availability.YouTube {
-		t.Fatalf("availability flags = %+v, want Amazon/Tidal/Qobuz/YouTube true", availability)
+	if !availability.Tidal || availability.TidalID != "290565315" {
+		t.Fatalf("Tidal availability = %+v, want TidalID 290565315", availability)
 	}
-	if availability.YouTubeID != "testvideoid1" {
-		t.Fatalf("YouTubeID = %q, want %q", availability.YouTubeID, "testvideoid1")
+	if availability.Qobuz {
+		t.Fatalf("Qobuz should remain false when resolve response contains null, got %+v", availability)
+	}
+}
+
+func TestCheckAvailabilityFromDeezerUsesSongLink(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) {
+				// Non-Spotify should go to SongLink, not resolve API
+				if req.URL.Host == "api.zarz.moe" {
+					t.Fatalf("non-Spotify URL should not hit resolve API, got: %s", req.URL.String())
+					return nil, nil
+				}
+				if req.URL.Host == "api.song.link" {
+					body := `{"linksByPlatform":{"spotify":{"url":"https://open.spotify.com/track/testid"},"deezer":{"url":"https://www.deezer.com/track/908604612"},"tidal":{"url":"https://listen.tidal.com/track/134858527"},"qobuz":{"url":"https://open.qobuz.com/track/195125822"},"youtubeMusic":{"url":"https://music.youtube.com/watch?v=testvid"}}}`
+					return &http.Response{
+						StatusCode: 200,
+						Header:     make(http.Header),
+						Body:       io.NopCloser(strings.NewReader(body)),
+						Request:    req,
+					}, nil
+				}
+				t.Fatalf("unexpected request: %s %s", req.Method, req.URL.String())
+				return nil, nil
+			}),
+		},
+	}
+
+	availability, err := client.checkAvailabilityFromDeezerSongLink("908604612")
+	if err != nil {
+		t.Fatalf("checkAvailabilityFromDeezerSongLink() error = %v", err)
+	}
+
+	if !availability.Deezer || availability.DeezerID != "908604612" {
+		t.Fatalf("Deezer = %+v, want DeezerID 908604612", availability)
+	}
+	if availability.SpotifyID != "testid" {
+		t.Fatalf("SpotifyID = %q, want %q", availability.SpotifyID, "testid")
 	}
 }

go_backend/tidal.go

@@ -875,8 +875,6 @@ func (t *TidalDownloader) SearchTracks(query string, limit int) ([]ExtTrackMetad
 	return results, nil
 }
 
-// SearchAll searches Tidal for tracks, artists, and albums matching the query.
-// Returns results in the same SearchAllResult format as Deezer's SearchAll.
 func (t *TidalDownloader) SearchAll(query string, trackLimit, artistLimit int, filter string) (*SearchAllResult, error) {
 	GoLog("[Tidal] SearchAll: query=%q, trackLimit=%d, artistLimit=%d, filter=%q\n", query, trackLimit, artistLimit, filter)
 
@@ -1165,7 +1163,6 @@ type tidalAPIResult struct {
 	duration time.Duration
 }
 
-// Mobile networks are more unstable, so we use longer timeouts
 const (
 	tidalAPITimeoutMobile = 25 * time.Second
 	tidalMaxRetries       = 2
@@ -1211,7 +1208,6 @@ func fetchTidalURLWithRetry(api string, trackID int64, quality string, timeout t
 			continue
 		}
 
-		// 429 rate limit - wait and retry
 		if resp.StatusCode == 429 {
 			io.Copy(io.Discard, resp.Body)
 			resp.Body.Close()
@@ -1233,7 +1229,6 @@ func fetchTidalURLWithRetry(api string, trackID int64, quality string, timeout t
 			continue
 		}
 
-		// Try V2 response format (with manifest)
 		var v2Response TidalAPIResponseV2
 		if err := json.Unmarshal(body, &v2Response); err == nil && v2Response.Data.Manifest != "" {
 			if v2Response.Data.AssetPresentation == "PREVIEW" {
@@ -1247,7 +1242,6 @@ func fetchTidalURLWithRetry(api string, trackID int64, quality string, timeout t
 			}, nil
 		}
 
-		// Try V1 response format
 		var v1Responses []struct {
 			OriginalTrackURL string `json:"OriginalTrackUrl"`
 		}
@@ -1602,10 +1596,6 @@ func (t *TidalDownloader) downloadFromManifest(ctx context.Context, manifestB64,
 		return nil
 	}
 
-	// For DASH format, determine correct M4A path
-	// If outputPath already ends with .m4a, use it directly.
-	// If outputPath ends with .flac, convert .flac to .m4a.
-	// Otherwise (e.g., SAF /proc/self/fd/*), use outputPath as-is.
 	var m4aPath string
 	if strings.HasSuffix(outputPath, ".m4a") {
 		m4aPath = outputPath
@@ -1879,8 +1869,6 @@ func titlesMatch(expectedTitle, foundTitle string) bool {
 		}
 	}
 
-	// Emoji/symbol-only titles must be matched strictly to avoid false positives
-	// like mapping "🪐" to "Higher Power".
 	if (!hasAlphaNumericRunes(expectedTitle) || !hasAlphaNumericRunes(foundTitle)) &&
 		strings.TrimSpace(expectedTitle) != "" &&
 		strings.TrimSpace(foundTitle) != "" {
@@ -2111,7 +2099,6 @@ func resolveTidalTrackForRequest(req DownloadRequest, downloader *TidalDownloade
 			}
 		}
 
-		// Prefer Deezer-based SongLink lookup when DeezerID is available.
 		if req.DeezerID != "" {
 			GoLog("[%s] Using Deezer ID for SongLink lookup: %s\n", logPrefix, req.DeezerID)
 			songlink := NewSongLinkClient()
@@ -2150,11 +2137,9 @@ func resolveTidalTrackForRequest(req DownloadRequest, downloader *TidalDownloade
 		return nil, fmt.Errorf("failed to find tidal track id from request/cache/songlink")
 	}
 
-	// Verify the resolved track matches the request.
 	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.
 	} else {
 		providerArtist := actualTrack.Artist.Name
 		if providerArtist == "" && len(actualTrack.Artists) > 0 {
@@ -2168,7 +2153,6 @@ func resolveTidalTrackForRequest(req DownloadRequest, downloader *TidalDownloade
 			SkipNameVerification: resolvedViaSongLink,
 		}
 		if !trackMatchesRequest(req, resolved, logPrefix) {
-			// Invalidate the cached ID so future requests don't reuse it.
 			if req.ISRC != "" {
 				GetTrackIDCache().SetTidal(req.ISRC, 0)
 			}
@@ -2178,13 +2162,26 @@ func resolveTidalTrackForRequest(req DownloadRequest, downloader *TidalDownloade
 		GoLog("[%s] Track %d verified: '%s - %s' ✓\n", logPrefix, trackID, resolved.ArtistName, resolved.Title)
 	}
 
+	// Use track_number / disc_number from the actual Tidal API data when the
+	// request doesn't carry them (e.g. downloads from search results / popular).
+	resolvedTrackNumber := req.TrackNumber
+	resolvedDiscNumber := req.DiscNumber
+	if actualTrack != nil {
+		if resolvedTrackNumber == 0 && actualTrack.TrackNumber > 0 {
+			resolvedTrackNumber = actualTrack.TrackNumber
+		}
+		if resolvedDiscNumber == 0 && actualTrack.VolumeNumber > 0 {
+			resolvedDiscNumber = actualTrack.VolumeNumber
+		}
+	}
+
 	track := &TidalTrack{
 		ID:           trackID,
 		Title:        strings.TrimSpace(req.TrackName),
 		ISRC:         strings.TrimSpace(req.ISRC),
 		Duration:     expectedDurationSec,
-		TrackNumber:  req.TrackNumber,
-		VolumeNumber: req.DiscNumber,
+		TrackNumber:  resolvedTrackNumber,
+		VolumeNumber: resolvedDiscNumber,
 	}
 	track.Artist.Name = strings.TrimSpace(req.ArtistName)
 	track.Album.Title = strings.TrimSpace(req.AlbumName)
@@ -2354,18 +2351,19 @@ func downloadFromTidal(req DownloadRequest) (TidalDownloadResult, error) {
 	}
 
 	metadata := Metadata{
-		Title:       req.TrackName,
-		Artist:      req.ArtistName,
-		Album:       req.AlbumName,
-		AlbumArtist: req.AlbumArtist,
-		Date:        releaseDate,
-		TrackNumber: actualTrackNumber,
-		TotalTracks: req.TotalTracks,
-		DiscNumber:  actualDiscNumber,
-		ISRC:        track.ISRC,
-		Genre:       req.Genre,
-		Label:       req.Label,
-		Copyright:   req.Copyright,
+		Title:         req.TrackName,
+		Artist:        req.ArtistName,
+		Album:         req.AlbumName,
+		AlbumArtist:   req.AlbumArtist,
+		ArtistTagMode: req.ArtistTagMode,
+		Date:          releaseDate,
+		TrackNumber:   actualTrackNumber,
+		TotalTracks:   req.TotalTracks,
+		DiscNumber:    actualDiscNumber,
+		ISRC:          track.ISRC,
+		Genre:         req.Genre,
+		Label:         req.Label,
+		Copyright:     req.Copyright,
 	}
 
 	var coverData []byte
@@ -2496,7 +2494,6 @@ func parseTidalURL(input string) (string, string, error) {
 
 	parts := strings.Split(strings.Trim(parsed.Path, "/"), "/")
 
-	// Handle /browse/track/123 format
 	if len(parts) > 0 && parts[0] == "browse" {
 		parts = parts[1:]
 	}

go_backend/title_match_utils.go

@@ -22,8 +22,6 @@ func writeNormalizedArtistRune(b *strings.Builder, r rune) {
 	}
 }
 
-// normalizeLooseTitle collapses separators/punctuation so titles like
-// "Doctor / Cops" and "Doctor _ Cops" can still match.
 func normalizeLooseTitle(title string) string {
 	trimmed := strings.TrimSpace(strings.ToLower(title))
 	if trimmed == "" {
@@ -48,8 +46,6 @@ func normalizeLooseTitle(title string) string {
 	return strings.Join(strings.Fields(b.String()), " ")
 }
 
-// normalizeLooseArtistName folds diacritics and common separators so artist
-// verification is resilient to variants like "Özkent" vs "Ozkent".
 func normalizeLooseArtistName(name string) string {
 	trimmed := strings.TrimSpace(strings.ToLower(name))
 	if trimmed == "" {
@@ -87,9 +83,6 @@ func hasAlphaNumericRunes(value string) bool {
 	return false
 }
 
-// normalizeSymbolOnlyTitle keeps symbol/emoji runes while dropping letters,
-// digits, spaces and punctuation. This is useful for emoji-only titles such as
-// "🪐", "🌎" etc, so we can compare them strictly and avoid false matches.
 func normalizeSymbolOnlyTitle(title string) string {
 	trimmed := strings.TrimSpace(strings.ToLower(title))
 	if trimmed == "" {
@@ -114,7 +107,6 @@ func normalizeSymbolOnlyTitle(title string) string {
 	return b.String()
 }
 
-// resolvedTrackInfo holds the metadata fetched from a provider for verification.
 type resolvedTrackInfo struct {
 	Title                string
 	ArtistName           string
@@ -123,8 +115,6 @@ type resolvedTrackInfo struct {
 	SkipNameVerification bool
 }
 
-// trackMatchesRequest checks whether a resolved track from a provider matches
-// the original download request. Returns true if the track is a plausible match.
 func trackMatchesRequest(req DownloadRequest, resolved resolvedTrackInfo, logPrefix string) bool {
 	exactISRCMatch := req.ISRC != "" &&
 		resolved.ISRC != "" &&

ios/Podfile

@@ -27,6 +27,37 @@ require File.expand_path(File.join('packages', 'flutter_tools', 'bin', 'podhelpe
 
 flutter_ios_podfile_setup
 
+def patch_device_info_plus_vision_selector
+  plugin_file = File.join(
+    __dir__,
+    '.symlinks',
+    'plugins',
+    'device_info_plus',
+    'ios',
+    'device_info_plus',
+    'Sources',
+    'device_info_plus',
+    'FPPDeviceInfoPlusPlugin.m'
+  )
+  return unless File.exist?(plugin_file)
+
+  source = File.read(plugin_file)
+  return if source.include?('FPPDeviceInfoPlusVisionCompat')
+
+  marker = "#import <sys/utsname.h>\n"
+  declaration = <<~OBJC
+
+    // Older Xcode SDKs do not declare this selector yet, but device_info_plus
+    // only calls it behind an availability check.
+    @interface NSProcessInfo (FPPDeviceInfoPlusVisionCompat)
+    - (BOOL)isiOSAppOnVision;
+    @end
+  OBJC
+
+  patched = source.sub(marker, "#{marker}#{declaration}\n")
+  File.write(plugin_file, patched) if patched != source
+end
+
 target 'Runner' do
   use_frameworks!
   use_modular_headers!
@@ -42,6 +73,8 @@ target 'RunnerTests' do
 end
 
 post_install do |installer|
+  patch_device_info_plus_vision_selector
+
   installer.pods_project.targets.each do |target|
     flutter_additional_ios_build_settings(target)
     target.build_configurations.each do |config|

ios/Runner/AppDelegate.swift

@@ -89,7 +89,7 @@ import Gobackend  // Import Go framework
             }
             self.lastDownloadProgressPayload = payload
             DispatchQueue.main.async { [weak self] in
-                self?.downloadProgressEventSink?(payload)
+                self?.downloadProgressEventSink?(self?.parseJsonPayload(payload))
             }
         }
         downloadProgressTimer = timer
@@ -119,7 +119,7 @@ import Gobackend  // Import Go framework
             }
             self.lastLibraryScanProgressPayload = payload
             DispatchQueue.main.async { [weak self] in
-                self?.libraryScanProgressEventSink?(payload)
+                self?.libraryScanProgressEventSink?(self?.parseJsonPayload(payload))
             }
         }
         libraryScanProgressTimer = timer
@@ -133,6 +133,17 @@ import Gobackend  // Import Go framework
         libraryScanProgressEventSink = nil
         lastLibraryScanProgressPayload = nil
     }
+
+    private func parseJsonPayload(_ payload: String) -> Any {
+        guard let data = payload.data(using: .utf8) else {
+            return payload
+        }
+        do {
+            return try JSONSerialization.jsonObject(with: data, options: [.fragmentsAllowed])
+        } catch {
+            return payload
+        }
+    }
     
     private func handleMethodCall(call: FlutterMethodCall, result: @escaping FlutterResult) {
         DispatchQueue.global(qos: .userInitiated).async {
@@ -169,11 +180,11 @@ import Gobackend  // Import Go framework
 
         case "getDownloadProgress":
             let response = GobackendGetDownloadProgress()
-            return response
+            return parseJsonPayload(response as String? ?? "{}")
             
         case "getAllDownloadProgress":
             let response = GobackendGetAllDownloadProgress()
-            return response
+            return parseJsonPayload(response as String? ?? "{}")
             
         case "initItemProgress":
             let args = call.arguments as! [String: Any]
@@ -296,6 +307,15 @@ import Gobackend  // Import Go framework
             if let error = error { throw error }
             return response
             
+        case "rewriteSplitArtistTags":
+            let args = call.arguments as! [String: Any]
+            let filePath = args["file_path"] as! String
+            let artist = args["artist"] as! String
+            let albumArtist = args["album_artist"] as! String
+            let response = GobackendRewriteSplitArtistTagsExport(filePath, artist, albumArtist, &error)
+            if let error = error { throw error }
+            return response
+            
         case "cleanupConnections":
             GobackendCleanupConnections()
             return nil
@@ -324,7 +344,8 @@ import Gobackend  // Import Go framework
             let spotifyId = args["spotify_id"] as! String
             let durationMs = args["duration_ms"] as? Int64 ?? 0
             let outputPath = args["output_path"] as! String
-            GobackendFetchAndSaveLyrics(trackName, artistName, spotifyId, durationMs, outputPath, &error)
+            let audioFilePath = args["audio_file_path"] as? String ?? ""
+            GobackendFetchAndSaveLyrics(trackName, artistName, spotifyId, durationMs, outputPath, audioFilePath, &error)
             if let error = error { throw error }
             return "{\"success\":true}"
 
@@ -923,7 +944,7 @@ import Gobackend  // Import Go framework
             
         case "getLibraryScanProgress":
             let response = GobackendGetLibraryScanProgressJSON()
-            return response
+            return parseJsonPayload(response as String? ?? "{}")
             
         case "cancelLibraryScan":
             GobackendCancelLibraryScanJSON()

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 = '4.1.2';
-  static const String buildNumber = '119';
+  static const String version = '4.2.0';
+  static const String buildNumber = '121';
   static const String fullVersion = '$version+$buildNumber';
 
   /// Shows "Internal" in debug builds, actual version in release.

lib/l10n/app_localizations.dart

@@ -256,6 +256,18 @@ abstract class AppLocalizations {
   /// **'Filename Format'**
   String get downloadFilenameFormat;
 
+  /// Setting for output filename pattern for singles/EPs
+  ///
+  /// In en, this message translates to:
+  /// **'Single Filename Format'**
+  String get downloadSingleFilenameFormat;
+
+  /// Subtitle description for single filename format setting
+  ///
+  /// In en, this message translates to:
+  /// **'Filename pattern for singles and EPs. Uses the same tags as the album format.'**
+  String get downloadSingleFilenameFormatDescription;
+
   /// Title of the folder organization picker bottom sheet
   ///
   /// In en, this message translates to:
@@ -400,6 +412,60 @@ abstract class AppLocalizations {
   /// **'Download highest resolution cover art'**
   String get optionsMaxQualityCoverSubtitle;
 
+  /// Title for ReplayGain setting toggle
+  ///
+  /// In en, this message translates to:
+  /// **'ReplayGain'**
+  String get optionsReplayGain;
+
+  /// Subtitle when ReplayGain is enabled
+  ///
+  /// In en, this message translates to:
+  /// **'Scan loudness and embed ReplayGain tags (EBU R128)'**
+  String get optionsReplayGainSubtitleOn;
+
+  /// Subtitle when ReplayGain is disabled
+  ///
+  /// In en, this message translates to:
+  /// **'Disabled: no loudness normalization tags'**
+  String get optionsReplayGainSubtitleOff;
+
+  /// Setting title for how artist metadata is written into files
+  ///
+  /// In en, this message translates to:
+  /// **'Artist Tag Mode'**
+  String get optionsArtistTagMode;
+
+  /// Bottom-sheet description for artist tag mode setting
+  ///
+  /// In en, this message translates to:
+  /// **'Choose how multiple artists are written into embedded tags.'**
+  String get optionsArtistTagModeDescription;
+
+  /// Artist tag mode option that joins multiple artists into one value
+  ///
+  /// In en, this message translates to:
+  /// **'Single joined value'**
+  String get optionsArtistTagModeJoined;
+
+  /// Subtitle for joined artist tag mode
+  ///
+  /// In en, this message translates to:
+  /// **'Write one ARTIST value like \"Artist A, Artist B\" for maximum player compatibility.'**
+  String get optionsArtistTagModeJoinedSubtitle;
+
+  /// Artist tag mode option that writes repeated ARTIST tags for Vorbis formats
+  ///
+  /// In en, this message translates to:
+  /// **'Split tags for FLAC/Opus'**
+  String get optionsArtistTagModeSplitVorbis;
+
+  /// Subtitle for split Vorbis artist tag mode
+  ///
+  /// In en, this message translates to:
+  /// **'Write one artist tag per artist for FLAC and Opus; MP3 and M4A stay joined.'**
+  String get optionsArtistTagModeSplitVorbisSubtitle;
+
   /// Number of parallel downloads
   ///
   /// In en, this message translates to:
@@ -2182,6 +2248,18 @@ abstract class AppLocalizations {
   /// **'Lyrics not available for this track'**
   String get trackLyricsNotAvailable;
 
+  /// Message when no embedded lyrics in audio file
+  ///
+  /// In en, this message translates to:
+  /// **'No lyrics found in this file'**
+  String get trackLyricsNotInFile;
+
+  /// Action - fetch lyrics from online providers
+  ///
+  /// In en, this message translates to:
+  /// **'Fetch from Online'**
+  String get trackFetchOnlineLyrics;
+
   /// Message when lyrics request times out
   ///
   /// In en, this message translates to:
@@ -3334,6 +3412,12 @@ abstract class AppLocalizations {
   /// **'{count, plural, =1{track} other{tracks}}'**
   String libraryTracksUnit(int count);
 
+  /// Unit label for files count during library scanning
+  ///
+  /// In en, this message translates to:
+  /// **'{count, plural, =1{file} other{files}}'**
+  String libraryFilesUnit(int count);
+
   /// Last scan time display
   ///
   /// In en, this message translates to:
@@ -3352,6 +3436,12 @@ abstract class AppLocalizations {
   /// **'Scanning...'**
   String get libraryScanning;
 
+  /// Status shown after file scanning finishes but library persistence is still running
+  ///
+  /// In en, this message translates to:
+  /// **'Finalizing library...'**
+  String get libraryScanFinalizing;
+
   /// Scan progress display
   ///
   /// In en, this message translates to:
@@ -3478,6 +3568,42 @@ abstract class AppLocalizations {
   /// **'Format'**
   String get libraryFilterFormat;
 
+  /// Filter section - metadata completeness
+  ///
+  /// In en, this message translates to:
+  /// **'Metadata'**
+  String get libraryFilterMetadata;
+
+  /// Filter option - items with complete metadata
+  ///
+  /// In en, this message translates to:
+  /// **'Complete metadata'**
+  String get libraryFilterMetadataComplete;
+
+  /// Filter option - items missing any tracked metadata field
+  ///
+  /// In en, this message translates to:
+  /// **'Missing any metadata'**
+  String get libraryFilterMetadataMissingAny;
+
+  /// Filter option - items missing release year/date
+  ///
+  /// In en, this message translates to:
+  /// **'Missing year'**
+  String get libraryFilterMetadataMissingYear;
+
+  /// Filter option - items missing genre
+  ///
+  /// In en, this message translates to:
+  /// **'Missing genre'**
+  String get libraryFilterMetadataMissingGenre;
+
+  /// Filter option - items missing album artist
+  ///
+  /// In en, this message translates to:
+  /// **'Missing album artist'**
+  String get libraryFilterMetadataMissingAlbumArtist;
+
   /// Filter section - sort order
   ///
   /// In en, this message translates to:
@@ -3496,6 +3622,30 @@ abstract class AppLocalizations {
   /// **'Oldest'**
   String get libraryFilterSortOldest;
 
+  /// Sort option - album ascending
+  ///
+  /// In en, this message translates to:
+  /// **'Album (A-Z)'**
+  String get libraryFilterSortAlbumAsc;
+
+  /// Sort option - album descending
+  ///
+  /// In en, this message translates to:
+  /// **'Album (Z-A)'**
+  String get libraryFilterSortAlbumDesc;
+
+  /// Sort option - genre ascending
+  ///
+  /// In en, this message translates to:
+  /// **'Genre (A-Z)'**
+  String get libraryFilterSortGenreAsc;
+
+  /// Sort option - genre descending
+  ///
+  /// In en, this message translates to:
+  /// **'Genre (Z-A)'**
+  String get libraryFilterSortGenreDesc;
+
   /// Relative time - less than a minute ago
   ///
   /// In en, this message translates to:
@@ -3940,6 +4090,54 @@ abstract class AppLocalizations {
   /// **'Search metadata online and embed into file'**
   String get trackReEnrichOnlineSubtitle;
 
+  /// Section title for field selection in re-enrich dialog
+  ///
+  /// In en, this message translates to:
+  /// **'Fields to update'**
+  String get trackReEnrichFieldsTitle;
+
+  /// Checkbox label for cover art field in re-enrich
+  ///
+  /// In en, this message translates to:
+  /// **'Cover Art'**
+  String get trackReEnrichFieldCover;
+
+  /// Checkbox label for lyrics field in re-enrich
+  ///
+  /// In en, this message translates to:
+  /// **'Lyrics'**
+  String get trackReEnrichFieldLyrics;
+
+  /// Checkbox label for basic tags in re-enrich (title/artist are never overwritten)
+  ///
+  /// In en, this message translates to:
+  /// **'Album, Album Artist'**
+  String get trackReEnrichFieldBasicTags;
+
+  /// Checkbox label for track info in re-enrich
+  ///
+  /// In en, this message translates to:
+  /// **'Track & Disc Number'**
+  String get trackReEnrichFieldTrackInfo;
+
+  /// Checkbox label for release info in re-enrich
+  ///
+  /// In en, this message translates to:
+  /// **'Date & ISRC'**
+  String get trackReEnrichFieldReleaseInfo;
+
+  /// Checkbox label for extra metadata in re-enrich
+  ///
+  /// In en, this message translates to:
+  /// **'Genre, Label, Copyright'**
+  String get trackReEnrichFieldExtra;
+
+  /// Select all fields checkbox in re-enrich
+  ///
+  /// In en, this message translates to:
+  /// **'Select All'**
+  String get trackReEnrichSelectAll;
+
   /// Menu action - edit embedded metadata
   ///
   /// In en, this message translates to:
@@ -4539,12 +4737,6 @@ abstract class AppLocalizations {
   /// **'You have unsaved changes that will be lost.'**
   String get lyricsProvidersDiscardContent;
 
-  /// Description for Spotify Lyrics API provider
-  ///
-  /// In en, this message translates to:
-  /// **'Spotify-sourced synced lyrics via community API'**
-  String get lyricsProviderSpotifyApiDesc;
-
   /// Description for LRCLIB provider
   ///
   /// In en, this message translates to:

lib/l10n/app_localizations_de.dart

@@ -76,6 +76,13 @@ class AppLocalizationsDe extends AppLocalizations {
   @override
   String get downloadFilenameFormat => 'Dateinamenformat';
 
+  @override
+  String get downloadSingleFilenameFormat => 'Single Filename Format';
+
+  @override
+  String get downloadSingleFilenameFormatDescription =>
+      'Filename pattern for singles and EPs. Uses the same tags as the album format.';
+
   @override
   String get downloadFolderOrganization => 'Ordnerstruktur';
 
@@ -158,6 +165,38 @@ class AppLocalizationsDe extends AppLocalizations {
   String get optionsMaxQualityCoverSubtitle =>
       'Cover in höchster Auflösung herunterladen';
 
+  @override
+  String get optionsReplayGain => 'ReplayGain';
+
+  @override
+  String get optionsReplayGainSubtitleOn =>
+      'Scan loudness and embed ReplayGain tags (EBU R128)';
+
+  @override
+  String get optionsReplayGainSubtitleOff =>
+      'Disabled: no loudness normalization tags';
+
+  @override
+  String get optionsArtistTagMode => 'Artist Tag Mode';
+
+  @override
+  String get optionsArtistTagModeDescription =>
+      'Choose how multiple artists are written into embedded tags.';
+
+  @override
+  String get optionsArtistTagModeJoined => 'Single joined value';
+
+  @override
+  String get optionsArtistTagModeJoinedSubtitle =>
+      'Write one ARTIST value like \"Artist A, Artist B\" for maximum player compatibility.';
+
+  @override
+  String get optionsArtistTagModeSplitVorbis => 'Split tags for FLAC/Opus';
+
+  @override
+  String get optionsArtistTagModeSplitVorbisSubtitle =>
+      'Write one artist tag per artist for FLAC and Opus; MP3 and M4A stay joined.';
+
   @override
   String get optionsConcurrentDownloads => 'Parallele Downloads';
 
@@ -1180,6 +1219,12 @@ class AppLocalizationsDe extends AppLocalizations {
   String get trackLyricsNotAvailable =>
       'Lyrics sind für diesen Titel nicht verfügbar';
 
+  @override
+  String get trackLyricsNotInFile => 'No lyrics found in this file';
+
+  @override
+  String get trackFetchOnlineLyrics => 'Fetch from Online';
+
   @override
   String get trackLyricsTimeout =>
       'Anfrage Timeout. Versuche es später erneut.';
@@ -1851,6 +1896,17 @@ class AppLocalizationsDe extends AppLocalizations {
     return '$_temp0';
   }
 
+  @override
+  String libraryFilesUnit(int count) {
+    String _temp0 = intl.Intl.pluralLogic(
+      count,
+      locale: localeName,
+      other: 'files',
+      one: 'file',
+    );
+    return '$_temp0';
+  }
+
   @override
   String libraryLastScanned(String time) {
     return 'Zuletzt gescannt: $time';
@@ -1862,6 +1918,9 @@ class AppLocalizationsDe extends AppLocalizations {
   @override
   String get libraryScanning => 'Scannen...';
 
+  @override
+  String get libraryScanFinalizing => 'Finalizing library...';
+
   @override
   String libraryScanProgress(String progress, int total) {
     return '$progress% von $total Dateien';
@@ -1930,6 +1989,24 @@ class AppLocalizationsDe extends AppLocalizations {
   @override
   String get libraryFilterFormat => 'Format';
 
+  @override
+  String get libraryFilterMetadata => 'Metadata';
+
+  @override
+  String get libraryFilterMetadataComplete => 'Complete metadata';
+
+  @override
+  String get libraryFilterMetadataMissingAny => 'Missing any metadata';
+
+  @override
+  String get libraryFilterMetadataMissingYear => 'Missing year';
+
+  @override
+  String get libraryFilterMetadataMissingGenre => 'Missing genre';
+
+  @override
+  String get libraryFilterMetadataMissingAlbumArtist => 'Missing album artist';
+
   @override
   String get libraryFilterSort => 'Sortieren';
 
@@ -1939,6 +2016,18 @@ class AppLocalizationsDe extends AppLocalizations {
   @override
   String get libraryFilterSortOldest => 'Älteste';
 
+  @override
+  String get libraryFilterSortAlbumAsc => 'Album (A-Z)';
+
+  @override
+  String get libraryFilterSortAlbumDesc => 'Album (Z-A)';
+
+  @override
+  String get libraryFilterSortGenreAsc => 'Genre (A-Z)';
+
+  @override
+  String get libraryFilterSortGenreDesc => 'Genre (Z-A)';
+
   @override
   String get timeJustNow => 'Gerade eben';
 
@@ -2225,6 +2314,30 @@ class AppLocalizationsDe extends AppLocalizations {
   String get trackReEnrichOnlineSubtitle =>
       'Metadaten online suchen und in Datei einbinden';
 
+  @override
+  String get trackReEnrichFieldsTitle => 'Fields to update';
+
+  @override
+  String get trackReEnrichFieldCover => 'Cover Art';
+
+  @override
+  String get trackReEnrichFieldLyrics => 'Lyrics';
+
+  @override
+  String get trackReEnrichFieldBasicTags => 'Album, Album Artist';
+
+  @override
+  String get trackReEnrichFieldTrackInfo => 'Track & Disc Number';
+
+  @override
+  String get trackReEnrichFieldReleaseInfo => 'Date & ISRC';
+
+  @override
+  String get trackReEnrichFieldExtra => 'Genre, Label, Copyright';
+
+  @override
+  String get trackReEnrichSelectAll => 'Select All';
+
   @override
   String get trackEditMetadata => 'Metadaten bearbeiten';
 
@@ -2641,10 +2754,6 @@ class AppLocalizationsDe extends AppLocalizations {
   String get lyricsProvidersDiscardContent =>
       'You have unsaved changes that will be lost.';
 
-  @override
-  String get lyricsProviderSpotifyApiDesc =>
-      'Spotify-sourced synced lyrics via community API';
-
   @override
   String get lyricsProviderLrclibDesc => 'Open-source synced lyrics database';
 

lib/l10n/app_localizations_en.dart

@@ -75,6 +75,13 @@ class AppLocalizationsEn extends AppLocalizations {
   @override
   String get downloadFilenameFormat => 'Filename Format';
 
+  @override
+  String get downloadSingleFilenameFormat => 'Single Filename Format';
+
+  @override
+  String get downloadSingleFilenameFormatDescription =>
+      'Filename pattern for singles and EPs. Uses the same tags as the album format.';
+
   @override
   String get downloadFolderOrganization => 'Folder Organization';
 
@@ -154,6 +161,38 @@ class AppLocalizationsEn extends AppLocalizations {
   String get optionsMaxQualityCoverSubtitle =>
       'Download highest resolution cover art';
 
+  @override
+  String get optionsReplayGain => 'ReplayGain';
+
+  @override
+  String get optionsReplayGainSubtitleOn =>
+      'Scan loudness and embed ReplayGain tags (EBU R128)';
+
+  @override
+  String get optionsReplayGainSubtitleOff =>
+      'Disabled: no loudness normalization tags';
+
+  @override
+  String get optionsArtistTagMode => 'Artist Tag Mode';
+
+  @override
+  String get optionsArtistTagModeDescription =>
+      'Choose how multiple artists are written into embedded tags.';
+
+  @override
+  String get optionsArtistTagModeJoined => 'Single joined value';
+
+  @override
+  String get optionsArtistTagModeJoinedSubtitle =>
+      'Write one ARTIST value like \"Artist A, Artist B\" for maximum player compatibility.';
+
+  @override
+  String get optionsArtistTagModeSplitVorbis => 'Split tags for FLAC/Opus';
+
+  @override
+  String get optionsArtistTagModeSplitVorbisSubtitle =>
+      'Write one artist tag per artist for FLAC and Opus; MP3 and M4A stay joined.';
+
   @override
   String get optionsConcurrentDownloads => 'Concurrent Downloads';
 
@@ -1161,6 +1200,12 @@ class AppLocalizationsEn extends AppLocalizations {
   @override
   String get trackLyricsNotAvailable => 'Lyrics not available for this track';
 
+  @override
+  String get trackLyricsNotInFile => 'No lyrics found in this file';
+
+  @override
+  String get trackFetchOnlineLyrics => 'Fetch from Online';
+
   @override
   String get trackLyricsTimeout => 'Request timed out. Try again later.';
 
@@ -1823,6 +1868,17 @@ class AppLocalizationsEn extends AppLocalizations {
     return '$_temp0';
   }
 
+  @override
+  String libraryFilesUnit(int count) {
+    String _temp0 = intl.Intl.pluralLogic(
+      count,
+      locale: localeName,
+      other: 'files',
+      one: 'file',
+    );
+    return '$_temp0';
+  }
+
   @override
   String libraryLastScanned(String time) {
     return 'Last scanned: $time';
@@ -1834,6 +1890,9 @@ class AppLocalizationsEn extends AppLocalizations {
   @override
   String get libraryScanning => 'Scanning...';
 
+  @override
+  String get libraryScanFinalizing => 'Finalizing library...';
+
   @override
   String libraryScanProgress(String progress, int total) {
     return '$progress% of $total files';
@@ -1902,6 +1961,24 @@ class AppLocalizationsEn extends AppLocalizations {
   @override
   String get libraryFilterFormat => 'Format';
 
+  @override
+  String get libraryFilterMetadata => 'Metadata';
+
+  @override
+  String get libraryFilterMetadataComplete => 'Complete metadata';
+
+  @override
+  String get libraryFilterMetadataMissingAny => 'Missing any metadata';
+
+  @override
+  String get libraryFilterMetadataMissingYear => 'Missing year';
+
+  @override
+  String get libraryFilterMetadataMissingGenre => 'Missing genre';
+
+  @override
+  String get libraryFilterMetadataMissingAlbumArtist => 'Missing album artist';
+
   @override
   String get libraryFilterSort => 'Sort';
 
@@ -1911,6 +1988,18 @@ class AppLocalizationsEn extends AppLocalizations {
   @override
   String get libraryFilterSortOldest => 'Oldest';
 
+  @override
+  String get libraryFilterSortAlbumAsc => 'Album (A-Z)';
+
+  @override
+  String get libraryFilterSortAlbumDesc => 'Album (Z-A)';
+
+  @override
+  String get libraryFilterSortGenreAsc => 'Genre (A-Z)';
+
+  @override
+  String get libraryFilterSortGenreDesc => 'Genre (Z-A)';
+
   @override
   String get timeJustNow => 'Just now';
 
@@ -2195,6 +2284,30 @@ class AppLocalizationsEn extends AppLocalizations {
   String get trackReEnrichOnlineSubtitle =>
       'Search metadata online and embed into file';
 
+  @override
+  String get trackReEnrichFieldsTitle => 'Fields to update';
+
+  @override
+  String get trackReEnrichFieldCover => 'Cover Art';
+
+  @override
+  String get trackReEnrichFieldLyrics => 'Lyrics';
+
+  @override
+  String get trackReEnrichFieldBasicTags => 'Album, Album Artist';
+
+  @override
+  String get trackReEnrichFieldTrackInfo => 'Track & Disc Number';
+
+  @override
+  String get trackReEnrichFieldReleaseInfo => 'Date & ISRC';
+
+  @override
+  String get trackReEnrichFieldExtra => 'Genre, Label, Copyright';
+
+  @override
+  String get trackReEnrichSelectAll => 'Select All';
+
   @override
   String get trackEditMetadata => 'Edit Metadata';
 
@@ -2609,10 +2722,6 @@ class AppLocalizationsEn extends AppLocalizations {
   String get lyricsProvidersDiscardContent =>
       'You have unsaved changes that will be lost.';
 
-  @override
-  String get lyricsProviderSpotifyApiDesc =>
-      'Spotify-sourced synced lyrics via community API';
-
   @override
   String get lyricsProviderLrclibDesc => 'Open-source synced lyrics database';
 

lib/l10n/app_localizations_es.dart

@@ -75,6 +75,13 @@ class AppLocalizationsEs extends AppLocalizations {
   @override
   String get downloadFilenameFormat => 'Filename Format';
 
+  @override
+  String get downloadSingleFilenameFormat => 'Single Filename Format';
+
+  @override
+  String get downloadSingleFilenameFormatDescription =>
+      'Filename pattern for singles and EPs. Uses the same tags as the album format.';
+
   @override
   String get downloadFolderOrganization => 'Folder Organization';
 
@@ -154,6 +161,38 @@ class AppLocalizationsEs extends AppLocalizations {
   String get optionsMaxQualityCoverSubtitle =>
       'Download highest resolution cover art';
 
+  @override
+  String get optionsReplayGain => 'ReplayGain';
+
+  @override
+  String get optionsReplayGainSubtitleOn =>
+      'Scan loudness and embed ReplayGain tags (EBU R128)';
+
+  @override
+  String get optionsReplayGainSubtitleOff =>
+      'Disabled: no loudness normalization tags';
+
+  @override
+  String get optionsArtistTagMode => 'Artist Tag Mode';
+
+  @override
+  String get optionsArtistTagModeDescription =>
+      'Choose how multiple artists are written into embedded tags.';
+
+  @override
+  String get optionsArtistTagModeJoined => 'Single joined value';
+
+  @override
+  String get optionsArtistTagModeJoinedSubtitle =>
+      'Write one ARTIST value like \"Artist A, Artist B\" for maximum player compatibility.';
+
+  @override
+  String get optionsArtistTagModeSplitVorbis => 'Split tags for FLAC/Opus';
+
+  @override
+  String get optionsArtistTagModeSplitVorbisSubtitle =>
+      'Write one artist tag per artist for FLAC and Opus; MP3 and M4A stay joined.';
+
   @override
   String get optionsConcurrentDownloads => 'Concurrent Downloads';
 
@@ -1161,6 +1200,12 @@ class AppLocalizationsEs extends AppLocalizations {
   @override
   String get trackLyricsNotAvailable => 'Lyrics not available for this track';
 
+  @override
+  String get trackLyricsNotInFile => 'No lyrics found in this file';
+
+  @override
+  String get trackFetchOnlineLyrics => 'Fetch from Online';
+
   @override
   String get trackLyricsTimeout => 'Request timed out. Try again later.';
 
@@ -1823,6 +1868,17 @@ class AppLocalizationsEs extends AppLocalizations {
     return '$_temp0';
   }
 
+  @override
+  String libraryFilesUnit(int count) {
+    String _temp0 = intl.Intl.pluralLogic(
+      count,
+      locale: localeName,
+      other: 'files',
+      one: 'file',
+    );
+    return '$_temp0';
+  }
+
   @override
   String libraryLastScanned(String time) {
     return 'Last scanned: $time';
@@ -1834,6 +1890,9 @@ class AppLocalizationsEs extends AppLocalizations {
   @override
   String get libraryScanning => 'Scanning...';
 
+  @override
+  String get libraryScanFinalizing => 'Finalizing library...';
+
   @override
   String libraryScanProgress(String progress, int total) {
     return '$progress% of $total files';
@@ -1902,6 +1961,24 @@ class AppLocalizationsEs extends AppLocalizations {
   @override
   String get libraryFilterFormat => 'Format';
 
+  @override
+  String get libraryFilterMetadata => 'Metadata';
+
+  @override
+  String get libraryFilterMetadataComplete => 'Complete metadata';
+
+  @override
+  String get libraryFilterMetadataMissingAny => 'Missing any metadata';
+
+  @override
+  String get libraryFilterMetadataMissingYear => 'Missing year';
+
+  @override
+  String get libraryFilterMetadataMissingGenre => 'Missing genre';
+
+  @override
+  String get libraryFilterMetadataMissingAlbumArtist => 'Missing album artist';
+
   @override
   String get libraryFilterSort => 'Sort';
 
@@ -1911,6 +1988,18 @@ class AppLocalizationsEs extends AppLocalizations {
   @override
   String get libraryFilterSortOldest => 'Oldest';
 
+  @override
+  String get libraryFilterSortAlbumAsc => 'Album (A-Z)';
+
+  @override
+  String get libraryFilterSortAlbumDesc => 'Album (Z-A)';
+
+  @override
+  String get libraryFilterSortGenreAsc => 'Genre (A-Z)';
+
+  @override
+  String get libraryFilterSortGenreDesc => 'Genre (Z-A)';
+
   @override
   String get timeJustNow => 'Just now';
 
@@ -2195,6 +2284,30 @@ class AppLocalizationsEs extends AppLocalizations {
   String get trackReEnrichOnlineSubtitle =>
       'Search metadata online and embed into file';
 
+  @override
+  String get trackReEnrichFieldsTitle => 'Fields to update';
+
+  @override
+  String get trackReEnrichFieldCover => 'Cover Art';
+
+  @override
+  String get trackReEnrichFieldLyrics => 'Lyrics';
+
+  @override
+  String get trackReEnrichFieldBasicTags => 'Album, Album Artist';
+
+  @override
+  String get trackReEnrichFieldTrackInfo => 'Track & Disc Number';
+
+  @override
+  String get trackReEnrichFieldReleaseInfo => 'Date & ISRC';
+
+  @override
+  String get trackReEnrichFieldExtra => 'Genre, Label, Copyright';
+
+  @override
+  String get trackReEnrichSelectAll => 'Select All';
+
   @override
   String get trackEditMetadata => 'Edit Metadata';
 
@@ -2609,10 +2722,6 @@ class AppLocalizationsEs extends AppLocalizations {
   String get lyricsProvidersDiscardContent =>
       'You have unsaved changes that will be lost.';
 
-  @override
-  String get lyricsProviderSpotifyApiDesc =>
-      'Spotify-sourced synced lyrics via community API';
-
   @override
   String get lyricsProviderLrclibDesc => 'Open-source synced lyrics database';
 

lib/l10n/app_localizations_fr.dart

@@ -75,6 +75,13 @@ class AppLocalizationsFr extends AppLocalizations {
   @override
   String get downloadFilenameFormat => 'Nom du fichier';
 
+  @override
+  String get downloadSingleFilenameFormat => 'Single Filename Format';
+
+  @override
+  String get downloadSingleFilenameFormatDescription =>
+      'Filename pattern for singles and EPs. Uses the same tags as the album format.';
+
   @override
   String get downloadFolderOrganization => 'Organisation du dossier';
 
@@ -156,6 +163,38 @@ class AppLocalizationsFr extends AppLocalizations {
   String get optionsMaxQualityCoverSubtitle =>
       'Download highest resolution cover art';
 
+  @override
+  String get optionsReplayGain => 'ReplayGain';
+
+  @override
+  String get optionsReplayGainSubtitleOn =>
+      'Scan loudness and embed ReplayGain tags (EBU R128)';
+
+  @override
+  String get optionsReplayGainSubtitleOff =>
+      'Disabled: no loudness normalization tags';
+
+  @override
+  String get optionsArtistTagMode => 'Artist Tag Mode';
+
+  @override
+  String get optionsArtistTagModeDescription =>
+      'Choose how multiple artists are written into embedded tags.';
+
+  @override
+  String get optionsArtistTagModeJoined => 'Single joined value';
+
+  @override
+  String get optionsArtistTagModeJoinedSubtitle =>
+      'Write one ARTIST value like \"Artist A, Artist B\" for maximum player compatibility.';
+
+  @override
+  String get optionsArtistTagModeSplitVorbis => 'Split tags for FLAC/Opus';
+
+  @override
+  String get optionsArtistTagModeSplitVorbisSubtitle =>
+      'Write one artist tag per artist for FLAC and Opus; MP3 and M4A stay joined.';
+
   @override
   String get optionsConcurrentDownloads => 'Concurrent Downloads';
 
@@ -1163,6 +1202,12 @@ class AppLocalizationsFr extends AppLocalizations {
   @override
   String get trackLyricsNotAvailable => 'Lyrics not available for this track';
 
+  @override
+  String get trackLyricsNotInFile => 'No lyrics found in this file';
+
+  @override
+  String get trackFetchOnlineLyrics => 'Fetch from Online';
+
   @override
   String get trackLyricsTimeout => 'Request timed out. Try again later.';
 
@@ -1825,6 +1870,17 @@ class AppLocalizationsFr extends AppLocalizations {
     return '$_temp0';
   }
 
+  @override
+  String libraryFilesUnit(int count) {
+    String _temp0 = intl.Intl.pluralLogic(
+      count,
+      locale: localeName,
+      other: 'files',
+      one: 'file',
+    );
+    return '$_temp0';
+  }
+
   @override
   String libraryLastScanned(String time) {
     return 'Last scanned: $time';
@@ -1836,6 +1892,9 @@ class AppLocalizationsFr extends AppLocalizations {
   @override
   String get libraryScanning => 'Scanning...';
 
+  @override
+  String get libraryScanFinalizing => 'Finalizing library...';
+
   @override
   String libraryScanProgress(String progress, int total) {
     return '$progress% of $total files';
@@ -1904,6 +1963,24 @@ class AppLocalizationsFr extends AppLocalizations {
   @override
   String get libraryFilterFormat => 'Format';
 
+  @override
+  String get libraryFilterMetadata => 'Metadata';
+
+  @override
+  String get libraryFilterMetadataComplete => 'Complete metadata';
+
+  @override
+  String get libraryFilterMetadataMissingAny => 'Missing any metadata';
+
+  @override
+  String get libraryFilterMetadataMissingYear => 'Missing year';
+
+  @override
+  String get libraryFilterMetadataMissingGenre => 'Missing genre';
+
+  @override
+  String get libraryFilterMetadataMissingAlbumArtist => 'Missing album artist';
+
   @override
   String get libraryFilterSort => 'Sort';
 
@@ -1913,6 +1990,18 @@ class AppLocalizationsFr extends AppLocalizations {
   @override
   String get libraryFilterSortOldest => 'Oldest';
 
+  @override
+  String get libraryFilterSortAlbumAsc => 'Album (A-Z)';
+
+  @override
+  String get libraryFilterSortAlbumDesc => 'Album (Z-A)';
+
+  @override
+  String get libraryFilterSortGenreAsc => 'Genre (A-Z)';
+
+  @override
+  String get libraryFilterSortGenreDesc => 'Genre (Z-A)';
+
   @override
   String get timeJustNow => 'Just now';
 
@@ -2197,6 +2286,30 @@ class AppLocalizationsFr extends AppLocalizations {
   String get trackReEnrichOnlineSubtitle =>
       'Search metadata online and embed into file';
 
+  @override
+  String get trackReEnrichFieldsTitle => 'Fields to update';
+
+  @override
+  String get trackReEnrichFieldCover => 'Cover Art';
+
+  @override
+  String get trackReEnrichFieldLyrics => 'Lyrics';
+
+  @override
+  String get trackReEnrichFieldBasicTags => 'Album, Album Artist';
+
+  @override
+  String get trackReEnrichFieldTrackInfo => 'Track & Disc Number';
+
+  @override
+  String get trackReEnrichFieldReleaseInfo => 'Date & ISRC';
+
+  @override
+  String get trackReEnrichFieldExtra => 'Genre, Label, Copyright';
+
+  @override
+  String get trackReEnrichSelectAll => 'Select All';
+
   @override
   String get trackEditMetadata => 'Edit Metadata';
 
@@ -2610,10 +2723,6 @@ class AppLocalizationsFr extends AppLocalizations {
   String get lyricsProvidersDiscardContent =>
       'You have unsaved changes that will be lost.';
 
-  @override
-  String get lyricsProviderSpotifyApiDesc =>
-      'Spotify-sourced synced lyrics via community API';
-
   @override
   String get lyricsProviderLrclibDesc => 'Open-source synced lyrics database';
 

lib/l10n/app_localizations_hi.dart

@@ -75,6 +75,13 @@ class AppLocalizationsHi extends AppLocalizations {
   @override
   String get downloadFilenameFormat => 'Filename Format';
 
+  @override
+  String get downloadSingleFilenameFormat => 'Single Filename Format';
+
+  @override
+  String get downloadSingleFilenameFormatDescription =>
+      'Filename pattern for singles and EPs. Uses the same tags as the album format.';
+
   @override
   String get downloadFolderOrganization => 'Folder Organization';
 
@@ -154,6 +161,38 @@ class AppLocalizationsHi extends AppLocalizations {
   String get optionsMaxQualityCoverSubtitle =>
       'Download highest resolution cover art';
 
+  @override
+  String get optionsReplayGain => 'ReplayGain';
+
+  @override
+  String get optionsReplayGainSubtitleOn =>
+      'Scan loudness and embed ReplayGain tags (EBU R128)';
+
+  @override
+  String get optionsReplayGainSubtitleOff =>
+      'Disabled: no loudness normalization tags';
+
+  @override
+  String get optionsArtistTagMode => 'Artist Tag Mode';
+
+  @override
+  String get optionsArtistTagModeDescription =>
+      'Choose how multiple artists are written into embedded tags.';
+
+  @override
+  String get optionsArtistTagModeJoined => 'Single joined value';
+
+  @override
+  String get optionsArtistTagModeJoinedSubtitle =>
+      'Write one ARTIST value like \"Artist A, Artist B\" for maximum player compatibility.';
+
+  @override
+  String get optionsArtistTagModeSplitVorbis => 'Split tags for FLAC/Opus';
+
+  @override
+  String get optionsArtistTagModeSplitVorbisSubtitle =>
+      'Write one artist tag per artist for FLAC and Opus; MP3 and M4A stay joined.';
+
   @override
   String get optionsConcurrentDownloads => 'Concurrent Downloads';
 
@@ -1161,6 +1200,12 @@ class AppLocalizationsHi extends AppLocalizations {
   @override
   String get trackLyricsNotAvailable => 'Lyrics not available for this track';
 
+  @override
+  String get trackLyricsNotInFile => 'No lyrics found in this file';
+
+  @override
+  String get trackFetchOnlineLyrics => 'Fetch from Online';
+
   @override
   String get trackLyricsTimeout => 'Request timed out. Try again later.';
 
@@ -1823,6 +1868,17 @@ class AppLocalizationsHi extends AppLocalizations {
     return '$_temp0';
   }
 
+  @override
+  String libraryFilesUnit(int count) {
+    String _temp0 = intl.Intl.pluralLogic(
+      count,
+      locale: localeName,
+      other: 'files',
+      one: 'file',
+    );
+    return '$_temp0';
+  }
+
   @override
   String libraryLastScanned(String time) {
     return 'Last scanned: $time';
@@ -1834,6 +1890,9 @@ class AppLocalizationsHi extends AppLocalizations {
   @override
   String get libraryScanning => 'Scanning...';
 
+  @override
+  String get libraryScanFinalizing => 'Finalizing library...';
+
   @override
   String libraryScanProgress(String progress, int total) {
     return '$progress% of $total files';
@@ -1902,6 +1961,24 @@ class AppLocalizationsHi extends AppLocalizations {
   @override
   String get libraryFilterFormat => 'Format';
 
+  @override
+  String get libraryFilterMetadata => 'Metadata';
+
+  @override
+  String get libraryFilterMetadataComplete => 'Complete metadata';
+
+  @override
+  String get libraryFilterMetadataMissingAny => 'Missing any metadata';
+
+  @override
+  String get libraryFilterMetadataMissingYear => 'Missing year';
+
+  @override
+  String get libraryFilterMetadataMissingGenre => 'Missing genre';
+
+  @override
+  String get libraryFilterMetadataMissingAlbumArtist => 'Missing album artist';
+
   @override
   String get libraryFilterSort => 'Sort';
 
@@ -1911,6 +1988,18 @@ class AppLocalizationsHi extends AppLocalizations {
   @override
   String get libraryFilterSortOldest => 'Oldest';
 
+  @override
+  String get libraryFilterSortAlbumAsc => 'Album (A-Z)';
+
+  @override
+  String get libraryFilterSortAlbumDesc => 'Album (Z-A)';
+
+  @override
+  String get libraryFilterSortGenreAsc => 'Genre (A-Z)';
+
+  @override
+  String get libraryFilterSortGenreDesc => 'Genre (Z-A)';
+
   @override
   String get timeJustNow => 'Just now';
 
@@ -2195,6 +2284,30 @@ class AppLocalizationsHi extends AppLocalizations {
   String get trackReEnrichOnlineSubtitle =>
       'Search metadata online and embed into file';
 
+  @override
+  String get trackReEnrichFieldsTitle => 'Fields to update';
+
+  @override
+  String get trackReEnrichFieldCover => 'Cover Art';
+
+  @override
+  String get trackReEnrichFieldLyrics => 'Lyrics';
+
+  @override
+  String get trackReEnrichFieldBasicTags => 'Album, Album Artist';
+
+  @override
+  String get trackReEnrichFieldTrackInfo => 'Track & Disc Number';
+
+  @override
+  String get trackReEnrichFieldReleaseInfo => 'Date & ISRC';
+
+  @override
+  String get trackReEnrichFieldExtra => 'Genre, Label, Copyright';
+
+  @override
+  String get trackReEnrichSelectAll => 'Select All';
+
   @override
   String get trackEditMetadata => 'Edit Metadata';
 
@@ -2608,10 +2721,6 @@ class AppLocalizationsHi extends AppLocalizations {
   String get lyricsProvidersDiscardContent =>
       'You have unsaved changes that will be lost.';
 
-  @override
-  String get lyricsProviderSpotifyApiDesc =>
-      'Spotify-sourced synced lyrics via community API';
-
   @override
   String get lyricsProviderLrclibDesc => 'Open-source synced lyrics database';
 

lib/l10n/app_localizations_id.dart

@@ -76,6 +76,13 @@ class AppLocalizationsId extends AppLocalizations {
   @override
   String get downloadFilenameFormat => 'Format Nama File';
 
+  @override
+  String get downloadSingleFilenameFormat => 'Single Filename Format';
+
+  @override
+  String get downloadSingleFilenameFormatDescription =>
+      'Filename pattern for singles and EPs. Uses the same tags as the album format.';
+
   @override
   String get downloadFolderOrganization => 'Organisasi Folder';
 
@@ -158,6 +165,38 @@ class AppLocalizationsId extends AppLocalizations {
   String get optionsMaxQualityCoverSubtitle =>
       'Unduh cover art resolusi tertinggi';
 
+  @override
+  String get optionsReplayGain => 'ReplayGain';
+
+  @override
+  String get optionsReplayGainSubtitleOn =>
+      'Scan loudness and embed ReplayGain tags (EBU R128)';
+
+  @override
+  String get optionsReplayGainSubtitleOff =>
+      'Disabled: no loudness normalization tags';
+
+  @override
+  String get optionsArtistTagMode => 'Artist Tag Mode';
+
+  @override
+  String get optionsArtistTagModeDescription =>
+      'Choose how multiple artists are written into embedded tags.';
+
+  @override
+  String get optionsArtistTagModeJoined => 'Single joined value';
+
+  @override
+  String get optionsArtistTagModeJoinedSubtitle =>
+      'Write one ARTIST value like \"Artist A, Artist B\" for maximum player compatibility.';
+
+  @override
+  String get optionsArtistTagModeSplitVorbis => 'Split tags for FLAC/Opus';
+
+  @override
+  String get optionsArtistTagModeSplitVorbisSubtitle =>
+      'Write one artist tag per artist for FLAC and Opus; MP3 and M4A stay joined.';
+
   @override
   String get optionsConcurrentDownloads => 'Unduhan Bersamaan';
 
@@ -1168,6 +1207,12 @@ class AppLocalizationsId extends AppLocalizations {
   @override
   String get trackLyricsNotAvailable => 'Lirik tidak tersedia untuk lagu ini';
 
+  @override
+  String get trackLyricsNotInFile => 'No lyrics found in this file';
+
+  @override
+  String get trackFetchOnlineLyrics => 'Fetch from Online';
+
   @override
   String get trackLyricsTimeout => 'Permintaan timeout. Coba lagi nanti.';
 
@@ -1833,6 +1878,17 @@ class AppLocalizationsId extends AppLocalizations {
     return '$_temp0';
   }
 
+  @override
+  String libraryFilesUnit(int count) {
+    String _temp0 = intl.Intl.pluralLogic(
+      count,
+      locale: localeName,
+      other: 'files',
+      one: 'file',
+    );
+    return '$_temp0';
+  }
+
   @override
   String libraryLastScanned(String time) {
     return 'Last scanned: $time';
@@ -1844,6 +1900,9 @@ class AppLocalizationsId extends AppLocalizations {
   @override
   String get libraryScanning => 'Scanning...';
 
+  @override
+  String get libraryScanFinalizing => 'Finalizing library...';
+
   @override
   String libraryScanProgress(String progress, int total) {
     return '$progress% of $total files';
@@ -1912,6 +1971,24 @@ class AppLocalizationsId extends AppLocalizations {
   @override
   String get libraryFilterFormat => 'Format';
 
+  @override
+  String get libraryFilterMetadata => 'Metadata';
+
+  @override
+  String get libraryFilterMetadataComplete => 'Complete metadata';
+
+  @override
+  String get libraryFilterMetadataMissingAny => 'Missing any metadata';
+
+  @override
+  String get libraryFilterMetadataMissingYear => 'Missing year';
+
+  @override
+  String get libraryFilterMetadataMissingGenre => 'Missing genre';
+
+  @override
+  String get libraryFilterMetadataMissingAlbumArtist => 'Missing album artist';
+
   @override
   String get libraryFilterSort => 'Sort';
 
@@ -1921,6 +1998,18 @@ class AppLocalizationsId extends AppLocalizations {
   @override
   String get libraryFilterSortOldest => 'Oldest';
 
+  @override
+  String get libraryFilterSortAlbumAsc => 'Album (A-Z)';
+
+  @override
+  String get libraryFilterSortAlbumDesc => 'Album (Z-A)';
+
+  @override
+  String get libraryFilterSortGenreAsc => 'Genre (A-Z)';
+
+  @override
+  String get libraryFilterSortGenreDesc => 'Genre (Z-A)';
+
   @override
   String get timeJustNow => 'Just now';
 
@@ -2205,6 +2294,30 @@ class AppLocalizationsId extends AppLocalizations {
   String get trackReEnrichOnlineSubtitle =>
       'Search metadata online and embed into file';
 
+  @override
+  String get trackReEnrichFieldsTitle => 'Fields to update';
+
+  @override
+  String get trackReEnrichFieldCover => 'Cover Art';
+
+  @override
+  String get trackReEnrichFieldLyrics => 'Lyrics';
+
+  @override
+  String get trackReEnrichFieldBasicTags => 'Album, Album Artist';
+
+  @override
+  String get trackReEnrichFieldTrackInfo => 'Track & Disc Number';
+
+  @override
+  String get trackReEnrichFieldReleaseInfo => 'Date & ISRC';
+
+  @override
+  String get trackReEnrichFieldExtra => 'Genre, Label, Copyright';
+
+  @override
+  String get trackReEnrichSelectAll => 'Select All';
+
   @override
   String get trackEditMetadata => 'Edit Metadata';
 
@@ -2619,10 +2732,6 @@ class AppLocalizationsId extends AppLocalizations {
   String get lyricsProvidersDiscardContent =>
       'You have unsaved changes that will be lost.';
 
-  @override
-  String get lyricsProviderSpotifyApiDesc =>
-      'Spotify-sourced synced lyrics via community API';
-
   @override
   String get lyricsProviderLrclibDesc => 'Open-source synced lyrics database';
 

lib/l10n/app_localizations_ja.dart

@@ -75,6 +75,13 @@ class AppLocalizationsJa extends AppLocalizations {
   @override
   String get downloadFilenameFormat => 'ファイル名の形式';
 
+  @override
+  String get downloadSingleFilenameFormat => 'Single Filename Format';
+
+  @override
+  String get downloadSingleFilenameFormatDescription =>
+      'Filename pattern for singles and EPs. Uses the same tags as the album format.';
+
   @override
   String get downloadFolderOrganization => 'フォルダ構成';
 
@@ -152,6 +159,38 @@ class AppLocalizationsJa extends AppLocalizations {
   @override
   String get optionsMaxQualityCoverSubtitle => '最高解像度のカバーアートをダウンロード';
 
+  @override
+  String get optionsReplayGain => 'ReplayGain';
+
+  @override
+  String get optionsReplayGainSubtitleOn =>
+      'Scan loudness and embed ReplayGain tags (EBU R128)';
+
+  @override
+  String get optionsReplayGainSubtitleOff =>
+      'Disabled: no loudness normalization tags';
+
+  @override
+  String get optionsArtistTagMode => 'Artist Tag Mode';
+
+  @override
+  String get optionsArtistTagModeDescription =>
+      'Choose how multiple artists are written into embedded tags.';
+
+  @override
+  String get optionsArtistTagModeJoined => 'Single joined value';
+
+  @override
+  String get optionsArtistTagModeJoinedSubtitle =>
+      'Write one ARTIST value like \"Artist A, Artist B\" for maximum player compatibility.';
+
+  @override
+  String get optionsArtistTagModeSplitVorbis => 'Split tags for FLAC/Opus';
+
+  @override
+  String get optionsArtistTagModeSplitVorbisSubtitle =>
+      'Write one artist tag per artist for FLAC and Opus; MP3 and M4A stay joined.';
+
   @override
   String get optionsConcurrentDownloads => '同時ダウンロード';
 
@@ -1155,6 +1194,12 @@ class AppLocalizationsJa extends AppLocalizations {
   @override
   String get trackLyricsNotAvailable => 'このトラックの歌詞は利用できません';
 
+  @override
+  String get trackLyricsNotInFile => 'No lyrics found in this file';
+
+  @override
+  String get trackFetchOnlineLyrics => 'Fetch from Online';
+
   @override
   String get trackLyricsTimeout => 'リクエストがタイムアウトしました。後ほどお試しください。';
 
@@ -1810,6 +1855,17 @@ class AppLocalizationsJa extends AppLocalizations {
     return '$_temp0';
   }
 
+  @override
+  String libraryFilesUnit(int count) {
+    String _temp0 = intl.Intl.pluralLogic(
+      count,
+      locale: localeName,
+      other: 'files',
+      one: 'file',
+    );
+    return '$_temp0';
+  }
+
   @override
   String libraryLastScanned(String time) {
     return '最終スキャン: $time';
@@ -1821,6 +1877,9 @@ class AppLocalizationsJa extends AppLocalizations {
   @override
   String get libraryScanning => 'スキャン中...';
 
+  @override
+  String get libraryScanFinalizing => 'Finalizing library...';
+
   @override
   String libraryScanProgress(String progress, int total) {
     return '$progress% of $total files';
@@ -1889,6 +1948,24 @@ class AppLocalizationsJa extends AppLocalizations {
   @override
   String get libraryFilterFormat => '形式';
 
+  @override
+  String get libraryFilterMetadata => 'Metadata';
+
+  @override
+  String get libraryFilterMetadataComplete => 'Complete metadata';
+
+  @override
+  String get libraryFilterMetadataMissingAny => 'Missing any metadata';
+
+  @override
+  String get libraryFilterMetadataMissingYear => 'Missing year';
+
+  @override
+  String get libraryFilterMetadataMissingGenre => 'Missing genre';
+
+  @override
+  String get libraryFilterMetadataMissingAlbumArtist => 'Missing album artist';
+
   @override
   String get libraryFilterSort => 'Sort';
 
@@ -1898,6 +1975,18 @@ class AppLocalizationsJa extends AppLocalizations {
   @override
   String get libraryFilterSortOldest => 'Oldest';
 
+  @override
+  String get libraryFilterSortAlbumAsc => 'Album (A-Z)';
+
+  @override
+  String get libraryFilterSortAlbumDesc => 'Album (Z-A)';
+
+  @override
+  String get libraryFilterSortGenreAsc => 'Genre (A-Z)';
+
+  @override
+  String get libraryFilterSortGenreDesc => 'Genre (Z-A)';
+
   @override
   String get timeJustNow => 'Just now';
 
@@ -2182,6 +2271,30 @@ class AppLocalizationsJa extends AppLocalizations {
   String get trackReEnrichOnlineSubtitle =>
       'Search metadata online and embed into file';
 
+  @override
+  String get trackReEnrichFieldsTitle => 'Fields to update';
+
+  @override
+  String get trackReEnrichFieldCover => 'Cover Art';
+
+  @override
+  String get trackReEnrichFieldLyrics => 'Lyrics';
+
+  @override
+  String get trackReEnrichFieldBasicTags => 'Album, Album Artist';
+
+  @override
+  String get trackReEnrichFieldTrackInfo => 'Track & Disc Number';
+
+  @override
+  String get trackReEnrichFieldReleaseInfo => 'Date & ISRC';
+
+  @override
+  String get trackReEnrichFieldExtra => 'Genre, Label, Copyright';
+
+  @override
+  String get trackReEnrichSelectAll => 'Select All';
+
   @override
   String get trackEditMetadata => 'メタデータを編集';
 
@@ -2595,10 +2708,6 @@ class AppLocalizationsJa extends AppLocalizations {
   String get lyricsProvidersDiscardContent =>
       'You have unsaved changes that will be lost.';
 
-  @override
-  String get lyricsProviderSpotifyApiDesc =>
-      'Spotify-sourced synced lyrics via community API';
-
   @override
   String get lyricsProviderLrclibDesc => 'Open-source synced lyrics database';
 

lib/l10n/app_localizations_ko.dart

@@ -74,6 +74,13 @@ class AppLocalizationsKo extends AppLocalizations {
   @override
   String get downloadFilenameFormat => '파일 이름 형식';
 
+  @override
+  String get downloadSingleFilenameFormat => 'Single Filename Format';
+
+  @override
+  String get downloadSingleFilenameFormatDescription =>
+      'Filename pattern for singles and EPs. Uses the same tags as the album format.';
+
   @override
   String get downloadFolderOrganization => '폴더 분류 형식';
 
@@ -148,6 +155,38 @@ class AppLocalizationsKo extends AppLocalizations {
   @override
   String get optionsMaxQualityCoverSubtitle => '최고 품질의 커버 이미지를 다운로드';
 
+  @override
+  String get optionsReplayGain => 'ReplayGain';
+
+  @override
+  String get optionsReplayGainSubtitleOn =>
+      'Scan loudness and embed ReplayGain tags (EBU R128)';
+
+  @override
+  String get optionsReplayGainSubtitleOff =>
+      'Disabled: no loudness normalization tags';
+
+  @override
+  String get optionsArtistTagMode => 'Artist Tag Mode';
+
+  @override
+  String get optionsArtistTagModeDescription =>
+      'Choose how multiple artists are written into embedded tags.';
+
+  @override
+  String get optionsArtistTagModeJoined => 'Single joined value';
+
+  @override
+  String get optionsArtistTagModeJoinedSubtitle =>
+      'Write one ARTIST value like \"Artist A, Artist B\" for maximum player compatibility.';
+
+  @override
+  String get optionsArtistTagModeSplitVorbis => 'Split tags for FLAC/Opus';
+
+  @override
+  String get optionsArtistTagModeSplitVorbisSubtitle =>
+      'Write one artist tag per artist for FLAC and Opus; MP3 and M4A stay joined.';
+
   @override
   String get optionsConcurrentDownloads => '동시 다운로드';
 
@@ -1141,6 +1180,12 @@ class AppLocalizationsKo extends AppLocalizations {
   @override
   String get trackLyricsNotAvailable => 'Lyrics not available for this track';
 
+  @override
+  String get trackLyricsNotInFile => 'No lyrics found in this file';
+
+  @override
+  String get trackFetchOnlineLyrics => 'Fetch from Online';
+
   @override
   String get trackLyricsTimeout => 'Request timed out. Try again later.';
 
@@ -1803,6 +1848,17 @@ class AppLocalizationsKo extends AppLocalizations {
     return '$_temp0';
   }
 
+  @override
+  String libraryFilesUnit(int count) {
+    String _temp0 = intl.Intl.pluralLogic(
+      count,
+      locale: localeName,
+      other: 'files',
+      one: 'file',
+    );
+    return '$_temp0';
+  }
+
   @override
   String libraryLastScanned(String time) {
     return 'Last scanned: $time';
@@ -1814,6 +1870,9 @@ class AppLocalizationsKo extends AppLocalizations {
   @override
   String get libraryScanning => 'Scanning...';
 
+  @override
+  String get libraryScanFinalizing => 'Finalizing library...';
+
   @override
   String libraryScanProgress(String progress, int total) {
     return '$progress% of $total files';
@@ -1882,6 +1941,24 @@ class AppLocalizationsKo extends AppLocalizations {
   @override
   String get libraryFilterFormat => 'Format';
 
+  @override
+  String get libraryFilterMetadata => 'Metadata';
+
+  @override
+  String get libraryFilterMetadataComplete => 'Complete metadata';
+
+  @override
+  String get libraryFilterMetadataMissingAny => 'Missing any metadata';
+
+  @override
+  String get libraryFilterMetadataMissingYear => 'Missing year';
+
+  @override
+  String get libraryFilterMetadataMissingGenre => 'Missing genre';
+
+  @override
+  String get libraryFilterMetadataMissingAlbumArtist => 'Missing album artist';
+
   @override
   String get libraryFilterSort => 'Sort';
 
@@ -1891,6 +1968,18 @@ class AppLocalizationsKo extends AppLocalizations {
   @override
   String get libraryFilterSortOldest => 'Oldest';
 
+  @override
+  String get libraryFilterSortAlbumAsc => 'Album (A-Z)';
+
+  @override
+  String get libraryFilterSortAlbumDesc => 'Album (Z-A)';
+
+  @override
+  String get libraryFilterSortGenreAsc => 'Genre (A-Z)';
+
+  @override
+  String get libraryFilterSortGenreDesc => 'Genre (Z-A)';
+
   @override
   String get timeJustNow => 'Just now';
 
@@ -2175,6 +2264,30 @@ class AppLocalizationsKo extends AppLocalizations {
   String get trackReEnrichOnlineSubtitle =>
       'Search metadata online and embed into file';
 
+  @override
+  String get trackReEnrichFieldsTitle => 'Fields to update';
+
+  @override
+  String get trackReEnrichFieldCover => 'Cover Art';
+
+  @override
+  String get trackReEnrichFieldLyrics => 'Lyrics';
+
+  @override
+  String get trackReEnrichFieldBasicTags => 'Album, Album Artist';
+
+  @override
+  String get trackReEnrichFieldTrackInfo => 'Track & Disc Number';
+
+  @override
+  String get trackReEnrichFieldReleaseInfo => 'Date & ISRC';
+
+  @override
+  String get trackReEnrichFieldExtra => 'Genre, Label, Copyright';
+
+  @override
+  String get trackReEnrichSelectAll => 'Select All';
+
   @override
   String get trackEditMetadata => 'Edit Metadata';
 
@@ -2588,10 +2701,6 @@ class AppLocalizationsKo extends AppLocalizations {
   String get lyricsProvidersDiscardContent =>
       'You have unsaved changes that will be lost.';
 
-  @override
-  String get lyricsProviderSpotifyApiDesc =>
-      'Spotify-sourced synced lyrics via community API';
-
   @override
   String get lyricsProviderLrclibDesc => 'Open-source synced lyrics database';
 

lib/l10n/app_localizations_nl.dart

@@ -75,6 +75,13 @@ class AppLocalizationsNl extends AppLocalizations {
   @override
   String get downloadFilenameFormat => 'Filename Format';
 
+  @override
+  String get downloadSingleFilenameFormat => 'Single Filename Format';
+
+  @override
+  String get downloadSingleFilenameFormatDescription =>
+      'Filename pattern for singles and EPs. Uses the same tags as the album format.';
+
   @override
   String get downloadFolderOrganization => 'Folder Organization';
 
@@ -154,6 +161,38 @@ class AppLocalizationsNl extends AppLocalizations {
   String get optionsMaxQualityCoverSubtitle =>
       'Download highest resolution cover art';
 
+  @override
+  String get optionsReplayGain => 'ReplayGain';
+
+  @override
+  String get optionsReplayGainSubtitleOn =>
+      'Scan loudness and embed ReplayGain tags (EBU R128)';
+
+  @override
+  String get optionsReplayGainSubtitleOff =>
+      'Disabled: no loudness normalization tags';
+
+  @override
+  String get optionsArtistTagMode => 'Artist Tag Mode';
+
+  @override
+  String get optionsArtistTagModeDescription =>
+      'Choose how multiple artists are written into embedded tags.';
+
+  @override
+  String get optionsArtistTagModeJoined => 'Single joined value';
+
+  @override
+  String get optionsArtistTagModeJoinedSubtitle =>
+      'Write one ARTIST value like \"Artist A, Artist B\" for maximum player compatibility.';
+
+  @override
+  String get optionsArtistTagModeSplitVorbis => 'Split tags for FLAC/Opus';
+
+  @override
+  String get optionsArtistTagModeSplitVorbisSubtitle =>
+      'Write one artist tag per artist for FLAC and Opus; MP3 and M4A stay joined.';
+
   @override
   String get optionsConcurrentDownloads => 'Concurrent Downloads';
 
@@ -1161,6 +1200,12 @@ class AppLocalizationsNl extends AppLocalizations {
   @override
   String get trackLyricsNotAvailable => 'Lyrics not available for this track';
 
+  @override
+  String get trackLyricsNotInFile => 'No lyrics found in this file';
+
+  @override
+  String get trackFetchOnlineLyrics => 'Fetch from Online';
+
   @override
   String get trackLyricsTimeout => 'Request timed out. Try again later.';
 
@@ -1823,6 +1868,17 @@ class AppLocalizationsNl extends AppLocalizations {
     return '$_temp0';
   }
 
+  @override
+  String libraryFilesUnit(int count) {
+    String _temp0 = intl.Intl.pluralLogic(
+      count,
+      locale: localeName,
+      other: 'files',
+      one: 'file',
+    );
+    return '$_temp0';
+  }
+
   @override
   String libraryLastScanned(String time) {
     return 'Last scanned: $time';
@@ -1834,6 +1890,9 @@ class AppLocalizationsNl extends AppLocalizations {
   @override
   String get libraryScanning => 'Scanning...';
 
+  @override
+  String get libraryScanFinalizing => 'Finalizing library...';
+
   @override
   String libraryScanProgress(String progress, int total) {
     return '$progress% of $total files';
@@ -1902,6 +1961,24 @@ class AppLocalizationsNl extends AppLocalizations {
   @override
   String get libraryFilterFormat => 'Format';
 
+  @override
+  String get libraryFilterMetadata => 'Metadata';
+
+  @override
+  String get libraryFilterMetadataComplete => 'Complete metadata';
+
+  @override
+  String get libraryFilterMetadataMissingAny => 'Missing any metadata';
+
+  @override
+  String get libraryFilterMetadataMissingYear => 'Missing year';
+
+  @override
+  String get libraryFilterMetadataMissingGenre => 'Missing genre';
+
+  @override
+  String get libraryFilterMetadataMissingAlbumArtist => 'Missing album artist';
+
   @override
   String get libraryFilterSort => 'Sort';
 
@@ -1911,6 +1988,18 @@ class AppLocalizationsNl extends AppLocalizations {
   @override
   String get libraryFilterSortOldest => 'Oldest';
 
+  @override
+  String get libraryFilterSortAlbumAsc => 'Album (A-Z)';
+
+  @override
+  String get libraryFilterSortAlbumDesc => 'Album (Z-A)';
+
+  @override
+  String get libraryFilterSortGenreAsc => 'Genre (A-Z)';
+
+  @override
+  String get libraryFilterSortGenreDesc => 'Genre (Z-A)';
+
   @override
   String get timeJustNow => 'Just now';
 
@@ -2195,6 +2284,30 @@ class AppLocalizationsNl extends AppLocalizations {
   String get trackReEnrichOnlineSubtitle =>
       'Search metadata online and embed into file';
 
+  @override
+  String get trackReEnrichFieldsTitle => 'Fields to update';
+
+  @override
+  String get trackReEnrichFieldCover => 'Cover Art';
+
+  @override
+  String get trackReEnrichFieldLyrics => 'Lyrics';
+
+  @override
+  String get trackReEnrichFieldBasicTags => 'Album, Album Artist';
+
+  @override
+  String get trackReEnrichFieldTrackInfo => 'Track & Disc Number';
+
+  @override
+  String get trackReEnrichFieldReleaseInfo => 'Date & ISRC';
+
+  @override
+  String get trackReEnrichFieldExtra => 'Genre, Label, Copyright';
+
+  @override
+  String get trackReEnrichSelectAll => 'Select All';
+
   @override
   String get trackEditMetadata => 'Edit Metadata';
 
@@ -2608,10 +2721,6 @@ class AppLocalizationsNl extends AppLocalizations {
   String get lyricsProvidersDiscardContent =>
       'You have unsaved changes that will be lost.';
 
-  @override
-  String get lyricsProviderSpotifyApiDesc =>
-      'Spotify-sourced synced lyrics via community API';
-
   @override
   String get lyricsProviderLrclibDesc => 'Open-source synced lyrics database';
 

lib/l10n/app_localizations_pt.dart

@@ -75,6 +75,13 @@ class AppLocalizationsPt extends AppLocalizations {
   @override
   String get downloadFilenameFormat => 'Filename Format';
 
+  @override
+  String get downloadSingleFilenameFormat => 'Single Filename Format';
+
+  @override
+  String get downloadSingleFilenameFormatDescription =>
+      'Filename pattern for singles and EPs. Uses the same tags as the album format.';
+
   @override
   String get downloadFolderOrganization => 'Folder Organization';
 
@@ -154,6 +161,38 @@ class AppLocalizationsPt extends AppLocalizations {
   String get optionsMaxQualityCoverSubtitle =>
       'Download highest resolution cover art';
 
+  @override
+  String get optionsReplayGain => 'ReplayGain';
+
+  @override
+  String get optionsReplayGainSubtitleOn =>
+      'Scan loudness and embed ReplayGain tags (EBU R128)';
+
+  @override
+  String get optionsReplayGainSubtitleOff =>
+      'Disabled: no loudness normalization tags';
+
+  @override
+  String get optionsArtistTagMode => 'Artist Tag Mode';
+
+  @override
+  String get optionsArtistTagModeDescription =>
+      'Choose how multiple artists are written into embedded tags.';
+
+  @override
+  String get optionsArtistTagModeJoined => 'Single joined value';
+
+  @override
+  String get optionsArtistTagModeJoinedSubtitle =>
+      'Write one ARTIST value like \"Artist A, Artist B\" for maximum player compatibility.';
+
+  @override
+  String get optionsArtistTagModeSplitVorbis => 'Split tags for FLAC/Opus';
+
+  @override
+  String get optionsArtistTagModeSplitVorbisSubtitle =>
+      'Write one artist tag per artist for FLAC and Opus; MP3 and M4A stay joined.';
+
   @override
   String get optionsConcurrentDownloads => 'Concurrent Downloads';
 
@@ -1161,6 +1200,12 @@ class AppLocalizationsPt extends AppLocalizations {
   @override
   String get trackLyricsNotAvailable => 'Lyrics not available for this track';
 
+  @override
+  String get trackLyricsNotInFile => 'No lyrics found in this file';
+
+  @override
+  String get trackFetchOnlineLyrics => 'Fetch from Online';
+
   @override
   String get trackLyricsTimeout => 'Request timed out. Try again later.';
 
@@ -1823,6 +1868,17 @@ class AppLocalizationsPt extends AppLocalizations {
     return '$_temp0';
   }
 
+  @override
+  String libraryFilesUnit(int count) {
+    String _temp0 = intl.Intl.pluralLogic(
+      count,
+      locale: localeName,
+      other: 'files',
+      one: 'file',
+    );
+    return '$_temp0';
+  }
+
   @override
   String libraryLastScanned(String time) {
     return 'Last scanned: $time';
@@ -1834,6 +1890,9 @@ class AppLocalizationsPt extends AppLocalizations {
   @override
   String get libraryScanning => 'Scanning...';
 
+  @override
+  String get libraryScanFinalizing => 'Finalizing library...';
+
   @override
   String libraryScanProgress(String progress, int total) {
     return '$progress% of $total files';
@@ -1902,6 +1961,24 @@ class AppLocalizationsPt extends AppLocalizations {
   @override
   String get libraryFilterFormat => 'Format';
 
+  @override
+  String get libraryFilterMetadata => 'Metadata';
+
+  @override
+  String get libraryFilterMetadataComplete => 'Complete metadata';
+
+  @override
+  String get libraryFilterMetadataMissingAny => 'Missing any metadata';
+
+  @override
+  String get libraryFilterMetadataMissingYear => 'Missing year';
+
+  @override
+  String get libraryFilterMetadataMissingGenre => 'Missing genre';
+
+  @override
+  String get libraryFilterMetadataMissingAlbumArtist => 'Missing album artist';
+
   @override
   String get libraryFilterSort => 'Sort';
 
@@ -1911,6 +1988,18 @@ class AppLocalizationsPt extends AppLocalizations {
   @override
   String get libraryFilterSortOldest => 'Oldest';
 
+  @override
+  String get libraryFilterSortAlbumAsc => 'Album (A-Z)';
+
+  @override
+  String get libraryFilterSortAlbumDesc => 'Album (Z-A)';
+
+  @override
+  String get libraryFilterSortGenreAsc => 'Genre (A-Z)';
+
+  @override
+  String get libraryFilterSortGenreDesc => 'Genre (Z-A)';
+
   @override
   String get timeJustNow => 'Just now';
 
@@ -2195,6 +2284,30 @@ class AppLocalizationsPt extends AppLocalizations {
   String get trackReEnrichOnlineSubtitle =>
       'Search metadata online and embed into file';
 
+  @override
+  String get trackReEnrichFieldsTitle => 'Fields to update';
+
+  @override
+  String get trackReEnrichFieldCover => 'Cover Art';
+
+  @override
+  String get trackReEnrichFieldLyrics => 'Lyrics';
+
+  @override
+  String get trackReEnrichFieldBasicTags => 'Album, Album Artist';
+
+  @override
+  String get trackReEnrichFieldTrackInfo => 'Track & Disc Number';
+
+  @override
+  String get trackReEnrichFieldReleaseInfo => 'Date & ISRC';
+
+  @override
+  String get trackReEnrichFieldExtra => 'Genre, Label, Copyright';
+
+  @override
+  String get trackReEnrichSelectAll => 'Select All';
+
   @override
   String get trackEditMetadata => 'Edit Metadata';
 
@@ -2609,10 +2722,6 @@ class AppLocalizationsPt extends AppLocalizations {
   String get lyricsProvidersDiscardContent =>
       'You have unsaved changes that will be lost.';
 
-  @override
-  String get lyricsProviderSpotifyApiDesc =>
-      'Spotify-sourced synced lyrics via community API';
-
   @override
   String get lyricsProviderLrclibDesc => 'Open-source synced lyrics database';
 

lib/l10n/app_localizations_ru.dart

@@ -76,6 +76,13 @@ class AppLocalizationsRu extends AppLocalizations {
   @override
   String get downloadFilenameFormat => 'Формат имени файла';
 
+  @override
+  String get downloadSingleFilenameFormat => 'Single Filename Format';
+
+  @override
+  String get downloadSingleFilenameFormatDescription =>
+      'Filename pattern for singles and EPs. Uses the same tags as the album format.';
+
   @override
   String get downloadFolderOrganization => 'Организация папок';
 
@@ -159,6 +166,38 @@ class AppLocalizationsRu extends AppLocalizations {
   String get optionsMaxQualityCoverSubtitle =>
       'Скачивать обложку в макс. разрешении';
 
+  @override
+  String get optionsReplayGain => 'ReplayGain';
+
+  @override
+  String get optionsReplayGainSubtitleOn =>
+      'Scan loudness and embed ReplayGain tags (EBU R128)';
+
+  @override
+  String get optionsReplayGainSubtitleOff =>
+      'Disabled: no loudness normalization tags';
+
+  @override
+  String get optionsArtistTagMode => 'Artist Tag Mode';
+
+  @override
+  String get optionsArtistTagModeDescription =>
+      'Choose how multiple artists are written into embedded tags.';
+
+  @override
+  String get optionsArtistTagModeJoined => 'Single joined value';
+
+  @override
+  String get optionsArtistTagModeJoinedSubtitle =>
+      'Write one ARTIST value like \"Artist A, Artist B\" for maximum player compatibility.';
+
+  @override
+  String get optionsArtistTagModeSplitVorbis => 'Split tags for FLAC/Opus';
+
+  @override
+  String get optionsArtistTagModeSplitVorbisSubtitle =>
+      'Write one artist tag per artist for FLAC and Opus; MP3 and M4A stay joined.';
+
   @override
   String get optionsConcurrentDownloads => 'Одновременные загрузки';
 
@@ -1181,6 +1220,12 @@ class AppLocalizationsRu extends AppLocalizations {
   String get trackLyricsNotAvailable =>
       'Текст песни недоступен для этого трека';
 
+  @override
+  String get trackLyricsNotInFile => 'No lyrics found in this file';
+
+  @override
+  String get trackFetchOnlineLyrics => 'Fetch from Online';
+
   @override
   String get trackLyricsTimeout =>
       'Время ожидания запроса истекло. Повторите попытку позже.';
@@ -1861,6 +1906,17 @@ class AppLocalizationsRu extends AppLocalizations {
     return '$_temp0';
   }
 
+  @override
+  String libraryFilesUnit(int count) {
+    String _temp0 = intl.Intl.pluralLogic(
+      count,
+      locale: localeName,
+      other: 'files',
+      one: 'file',
+    );
+    return '$_temp0';
+  }
+
   @override
   String libraryLastScanned(String time) {
     return 'Последнее сканирование: $time';
@@ -1872,6 +1928,9 @@ class AppLocalizationsRu extends AppLocalizations {
   @override
   String get libraryScanning => 'Сканирование...';
 
+  @override
+  String get libraryScanFinalizing => 'Finalizing library...';
+
   @override
   String libraryScanProgress(String progress, int total) {
     return '$progress% из $total файлов';
@@ -1948,6 +2007,24 @@ class AppLocalizationsRu extends AppLocalizations {
   @override
   String get libraryFilterFormat => 'Формат';
 
+  @override
+  String get libraryFilterMetadata => 'Metadata';
+
+  @override
+  String get libraryFilterMetadataComplete => 'Complete metadata';
+
+  @override
+  String get libraryFilterMetadataMissingAny => 'Missing any metadata';
+
+  @override
+  String get libraryFilterMetadataMissingYear => 'Missing year';
+
+  @override
+  String get libraryFilterMetadataMissingGenre => 'Missing genre';
+
+  @override
+  String get libraryFilterMetadataMissingAlbumArtist => 'Missing album artist';
+
   @override
   String get libraryFilterSort => 'Сортировка';
 
@@ -1957,6 +2034,18 @@ class AppLocalizationsRu extends AppLocalizations {
   @override
   String get libraryFilterSortOldest => 'Старые';
 
+  @override
+  String get libraryFilterSortAlbumAsc => 'Album (A-Z)';
+
+  @override
+  String get libraryFilterSortAlbumDesc => 'Album (Z-A)';
+
+  @override
+  String get libraryFilterSortGenreAsc => 'Genre (A-Z)';
+
+  @override
+  String get libraryFilterSortGenreDesc => 'Genre (Z-A)';
+
   @override
   String get timeJustNow => 'Только что';
 
@@ -2247,6 +2336,30 @@ class AppLocalizationsRu extends AppLocalizations {
   String get trackReEnrichOnlineSubtitle =>
       'Поиск в сети метаданных и встраивание в файл';
 
+  @override
+  String get trackReEnrichFieldsTitle => 'Fields to update';
+
+  @override
+  String get trackReEnrichFieldCover => 'Cover Art';
+
+  @override
+  String get trackReEnrichFieldLyrics => 'Lyrics';
+
+  @override
+  String get trackReEnrichFieldBasicTags => 'Album, Album Artist';
+
+  @override
+  String get trackReEnrichFieldTrackInfo => 'Track & Disc Number';
+
+  @override
+  String get trackReEnrichFieldReleaseInfo => 'Date & ISRC';
+
+  @override
+  String get trackReEnrichFieldExtra => 'Genre, Label, Copyright';
+
+  @override
+  String get trackReEnrichSelectAll => 'Select All';
+
   @override
   String get trackEditMetadata => 'Редактировать метаданные';
 
@@ -2668,10 +2781,6 @@ class AppLocalizationsRu extends AppLocalizations {
   String get lyricsProvidersDiscardContent =>
       'You have unsaved changes that will be lost.';
 
-  @override
-  String get lyricsProviderSpotifyApiDesc =>
-      'Spotify-sourced synced lyrics via community API';
-
   @override
   String get lyricsProviderLrclibDesc => 'Open-source synced lyrics database';
 

lib/l10n/app_localizations_tr.dart

@@ -76,6 +76,13 @@ class AppLocalizationsTr extends AppLocalizations {
   @override
   String get downloadFilenameFormat => 'Dosya adı formatı';
 
+  @override
+  String get downloadSingleFilenameFormat => 'Single Filename Format';
+
+  @override
+  String get downloadSingleFilenameFormatDescription =>
+      'Filename pattern for singles and EPs. Uses the same tags as the album format.';
+
   @override
   String get downloadFolderOrganization => 'Dosya Organizasyonu';
 
@@ -157,6 +164,38 @@ class AppLocalizationsTr extends AppLocalizations {
   String get optionsMaxQualityCoverSubtitle =>
       'En yüksek kalitedeki albüm kapaklarını indir';
 
+  @override
+  String get optionsReplayGain => 'ReplayGain';
+
+  @override
+  String get optionsReplayGainSubtitleOn =>
+      'Scan loudness and embed ReplayGain tags (EBU R128)';
+
+  @override
+  String get optionsReplayGainSubtitleOff =>
+      'Disabled: no loudness normalization tags';
+
+  @override
+  String get optionsArtistTagMode => 'Artist Tag Mode';
+
+  @override
+  String get optionsArtistTagModeDescription =>
+      'Choose how multiple artists are written into embedded tags.';
+
+  @override
+  String get optionsArtistTagModeJoined => 'Single joined value';
+
+  @override
+  String get optionsArtistTagModeJoinedSubtitle =>
+      'Write one ARTIST value like \"Artist A, Artist B\" for maximum player compatibility.';
+
+  @override
+  String get optionsArtistTagModeSplitVorbis => 'Split tags for FLAC/Opus';
+
+  @override
+  String get optionsArtistTagModeSplitVorbisSubtitle =>
+      'Write one artist tag per artist for FLAC and Opus; MP3 and M4A stay joined.';
+
   @override
   String get optionsConcurrentDownloads => 'Eş Zamanlı İndirmeler';
 
@@ -1167,6 +1206,12 @@ class AppLocalizationsTr extends AppLocalizations {
   @override
   String get trackLyricsNotAvailable => 'Lyrics not available for this track';
 
+  @override
+  String get trackLyricsNotInFile => 'No lyrics found in this file';
+
+  @override
+  String get trackFetchOnlineLyrics => 'Fetch from Online';
+
   @override
   String get trackLyricsTimeout => 'Request timed out. Try again later.';
 
@@ -1829,6 +1874,17 @@ class AppLocalizationsTr extends AppLocalizations {
     return '$_temp0';
   }
 
+  @override
+  String libraryFilesUnit(int count) {
+    String _temp0 = intl.Intl.pluralLogic(
+      count,
+      locale: localeName,
+      other: 'files',
+      one: 'file',
+    );
+    return '$_temp0';
+  }
+
   @override
   String libraryLastScanned(String time) {
     return 'Last scanned: $time';
@@ -1840,6 +1896,9 @@ class AppLocalizationsTr extends AppLocalizations {
   @override
   String get libraryScanning => 'Scanning...';
 
+  @override
+  String get libraryScanFinalizing => 'Finalizing library...';
+
   @override
   String libraryScanProgress(String progress, int total) {
     return '$progress% of $total files';
@@ -1908,6 +1967,24 @@ class AppLocalizationsTr extends AppLocalizations {
   @override
   String get libraryFilterFormat => 'Format';
 
+  @override
+  String get libraryFilterMetadata => 'Metadata';
+
+  @override
+  String get libraryFilterMetadataComplete => 'Complete metadata';
+
+  @override
+  String get libraryFilterMetadataMissingAny => 'Missing any metadata';
+
+  @override
+  String get libraryFilterMetadataMissingYear => 'Missing year';
+
+  @override
+  String get libraryFilterMetadataMissingGenre => 'Missing genre';
+
+  @override
+  String get libraryFilterMetadataMissingAlbumArtist => 'Missing album artist';
+
   @override
   String get libraryFilterSort => 'Sort';
 
@@ -1917,6 +1994,18 @@ class AppLocalizationsTr extends AppLocalizations {
   @override
   String get libraryFilterSortOldest => 'Oldest';
 
+  @override
+  String get libraryFilterSortAlbumAsc => 'Album (A-Z)';
+
+  @override
+  String get libraryFilterSortAlbumDesc => 'Album (Z-A)';
+
+  @override
+  String get libraryFilterSortGenreAsc => 'Genre (A-Z)';
+
+  @override
+  String get libraryFilterSortGenreDesc => 'Genre (Z-A)';
+
   @override
   String get timeJustNow => 'Just now';
 
@@ -2201,6 +2290,30 @@ class AppLocalizationsTr extends AppLocalizations {
   String get trackReEnrichOnlineSubtitle =>
       'Search metadata online and embed into file';
 
+  @override
+  String get trackReEnrichFieldsTitle => 'Fields to update';
+
+  @override
+  String get trackReEnrichFieldCover => 'Cover Art';
+
+  @override
+  String get trackReEnrichFieldLyrics => 'Lyrics';
+
+  @override
+  String get trackReEnrichFieldBasicTags => 'Album, Album Artist';
+
+  @override
+  String get trackReEnrichFieldTrackInfo => 'Track & Disc Number';
+
+  @override
+  String get trackReEnrichFieldReleaseInfo => 'Date & ISRC';
+
+  @override
+  String get trackReEnrichFieldExtra => 'Genre, Label, Copyright';
+
+  @override
+  String get trackReEnrichSelectAll => 'Select All';
+
   @override
   String get trackEditMetadata => 'Edit Metadata';
 
@@ -2614,10 +2727,6 @@ class AppLocalizationsTr extends AppLocalizations {
   String get lyricsProvidersDiscardContent =>
       'You have unsaved changes that will be lost.';
 
-  @override
-  String get lyricsProviderSpotifyApiDesc =>
-      'Spotify-sourced synced lyrics via community API';
-
   @override
   String get lyricsProviderLrclibDesc => 'Open-source synced lyrics database';
 

lib/l10n/app_localizations_zh.dart

@@ -75,6 +75,13 @@ class AppLocalizationsZh extends AppLocalizations {
   @override
   String get downloadFilenameFormat => 'Filename Format';
 
+  @override
+  String get downloadSingleFilenameFormat => 'Single Filename Format';
+
+  @override
+  String get downloadSingleFilenameFormatDescription =>
+      'Filename pattern for singles and EPs. Uses the same tags as the album format.';
+
   @override
   String get downloadFolderOrganization => 'Folder Organization';
 
@@ -154,6 +161,38 @@ class AppLocalizationsZh extends AppLocalizations {
   String get optionsMaxQualityCoverSubtitle =>
       'Download highest resolution cover art';
 
+  @override
+  String get optionsReplayGain => 'ReplayGain';
+
+  @override
+  String get optionsReplayGainSubtitleOn =>
+      'Scan loudness and embed ReplayGain tags (EBU R128)';
+
+  @override
+  String get optionsReplayGainSubtitleOff =>
+      'Disabled: no loudness normalization tags';
+
+  @override
+  String get optionsArtistTagMode => 'Artist Tag Mode';
+
+  @override
+  String get optionsArtistTagModeDescription =>
+      'Choose how multiple artists are written into embedded tags.';
+
+  @override
+  String get optionsArtistTagModeJoined => 'Single joined value';
+
+  @override
+  String get optionsArtistTagModeJoinedSubtitle =>
+      'Write one ARTIST value like \"Artist A, Artist B\" for maximum player compatibility.';
+
+  @override
+  String get optionsArtistTagModeSplitVorbis => 'Split tags for FLAC/Opus';
+
+  @override
+  String get optionsArtistTagModeSplitVorbisSubtitle =>
+      'Write one artist tag per artist for FLAC and Opus; MP3 and M4A stay joined.';
+
   @override
   String get optionsConcurrentDownloads => 'Concurrent Downloads';
 
@@ -1161,6 +1200,12 @@ class AppLocalizationsZh extends AppLocalizations {
   @override
   String get trackLyricsNotAvailable => 'Lyrics not available for this track';
 
+  @override
+  String get trackLyricsNotInFile => 'No lyrics found in this file';
+
+  @override
+  String get trackFetchOnlineLyrics => 'Fetch from Online';
+
   @override
   String get trackLyricsTimeout => 'Request timed out. Try again later.';
 
@@ -1823,6 +1868,17 @@ class AppLocalizationsZh extends AppLocalizations {
     return '$_temp0';
   }
 
+  @override
+  String libraryFilesUnit(int count) {
+    String _temp0 = intl.Intl.pluralLogic(
+      count,
+      locale: localeName,
+      other: 'files',
+      one: 'file',
+    );
+    return '$_temp0';
+  }
+
   @override
   String libraryLastScanned(String time) {
     return 'Last scanned: $time';
@@ -1834,6 +1890,9 @@ class AppLocalizationsZh extends AppLocalizations {
   @override
   String get libraryScanning => 'Scanning...';
 
+  @override
+  String get libraryScanFinalizing => 'Finalizing library...';
+
   @override
   String libraryScanProgress(String progress, int total) {
     return '$progress% of $total files';
@@ -1902,6 +1961,24 @@ class AppLocalizationsZh extends AppLocalizations {
   @override
   String get libraryFilterFormat => 'Format';
 
+  @override
+  String get libraryFilterMetadata => 'Metadata';
+
+  @override
+  String get libraryFilterMetadataComplete => 'Complete metadata';
+
+  @override
+  String get libraryFilterMetadataMissingAny => 'Missing any metadata';
+
+  @override
+  String get libraryFilterMetadataMissingYear => 'Missing year';
+
+  @override
+  String get libraryFilterMetadataMissingGenre => 'Missing genre';
+
+  @override
+  String get libraryFilterMetadataMissingAlbumArtist => 'Missing album artist';
+
   @override
   String get libraryFilterSort => 'Sort';
 
@@ -1911,6 +1988,18 @@ class AppLocalizationsZh extends AppLocalizations {
   @override
   String get libraryFilterSortOldest => 'Oldest';
 
+  @override
+  String get libraryFilterSortAlbumAsc => 'Album (A-Z)';
+
+  @override
+  String get libraryFilterSortAlbumDesc => 'Album (Z-A)';
+
+  @override
+  String get libraryFilterSortGenreAsc => 'Genre (A-Z)';
+
+  @override
+  String get libraryFilterSortGenreDesc => 'Genre (Z-A)';
+
   @override
   String get timeJustNow => 'Just now';
 
@@ -2195,6 +2284,30 @@ class AppLocalizationsZh extends AppLocalizations {
   String get trackReEnrichOnlineSubtitle =>
       'Search metadata online and embed into file';
 
+  @override
+  String get trackReEnrichFieldsTitle => 'Fields to update';
+
+  @override
+  String get trackReEnrichFieldCover => 'Cover Art';
+
+  @override
+  String get trackReEnrichFieldLyrics => 'Lyrics';
+
+  @override
+  String get trackReEnrichFieldBasicTags => 'Album, Album Artist';
+
+  @override
+  String get trackReEnrichFieldTrackInfo => 'Track & Disc Number';
+
+  @override
+  String get trackReEnrichFieldReleaseInfo => 'Date & ISRC';
+
+  @override
+  String get trackReEnrichFieldExtra => 'Genre, Label, Copyright';
+
+  @override
+  String get trackReEnrichSelectAll => 'Select All';
+
   @override
   String get trackEditMetadata => 'Edit Metadata';
 
@@ -2609,10 +2722,6 @@ class AppLocalizationsZh extends AppLocalizations {
   String get lyricsProvidersDiscardContent =>
       'You have unsaved changes that will be lost.';
 
-  @override
-  String get lyricsProviderSpotifyApiDesc =>
-      'Spotify-sourced synced lyrics via community API';
-
   @override
   String get lyricsProviderLrclibDesc => 'Open-source synced lyrics database';
 

lib/l10n/arb/app_en.arb

@@ -89,6 +89,14 @@
   "@downloadFilenameFormat": {
     "description": "Setting for output filename pattern"
   },
+  "downloadSingleFilenameFormat": "Single Filename Format",
+  "@downloadSingleFilenameFormat": {
+    "description": "Setting for output filename pattern for singles/EPs"
+  },
+  "downloadSingleFilenameFormatDescription": "Filename pattern for singles and EPs. Uses the same tags as the album format.",
+  "@downloadSingleFilenameFormatDescription": {
+    "description": "Subtitle description for single filename format setting"
+  },
   "downloadFolderOrganization": "Folder Organization",
   "@downloadFolderOrganization": {
     "description": "Setting for folder structure"
@@ -190,6 +198,42 @@
   "@optionsMaxQualityCoverSubtitle": {
     "description": "Subtitle for max quality cover"
   },
+  "optionsReplayGain": "ReplayGain",
+  "@optionsReplayGain": {
+    "description": "Title for ReplayGain setting toggle"
+  },
+  "optionsReplayGainSubtitleOn": "Scan loudness and embed ReplayGain tags (EBU R128)",
+  "@optionsReplayGainSubtitleOn": {
+    "description": "Subtitle when ReplayGain is enabled"
+  },
+  "optionsReplayGainSubtitleOff": "Disabled: no loudness normalization tags",
+  "@optionsReplayGainSubtitleOff": {
+    "description": "Subtitle when ReplayGain is disabled"
+  },
+  "optionsArtistTagMode": "Artist Tag Mode",
+  "@optionsArtistTagMode": {
+    "description": "Setting title for how artist metadata is written into files"
+  },
+  "optionsArtistTagModeDescription": "Choose how multiple artists are written into embedded tags.",
+  "@optionsArtistTagModeDescription": {
+    "description": "Bottom-sheet description for artist tag mode setting"
+  },
+  "optionsArtistTagModeJoined": "Single joined value",
+  "@optionsArtistTagModeJoined": {
+    "description": "Artist tag mode option that joins multiple artists into one value"
+  },
+  "optionsArtistTagModeJoinedSubtitle": "Write one ARTIST value like \"Artist A, Artist B\" for maximum player compatibility.",
+  "@optionsArtistTagModeJoinedSubtitle": {
+    "description": "Subtitle for joined artist tag mode"
+  },
+  "optionsArtistTagModeSplitVorbis": "Split tags for FLAC/Opus",
+  "@optionsArtistTagModeSplitVorbis": {
+    "description": "Artist tag mode option that writes repeated ARTIST tags for Vorbis formats"
+  },
+  "optionsArtistTagModeSplitVorbisSubtitle": "Write one artist tag per artist for FLAC and Opus; MP3 and M4A stay joined.",
+  "@optionsArtistTagModeSplitVorbisSubtitle": {
+    "description": "Subtitle for split Vorbis artist tag mode"
+  },
   "optionsConcurrentDownloads": "Concurrent Downloads",
   "@optionsConcurrentDownloads": {
     "description": "Number of parallel downloads"
@@ -1519,6 +1563,14 @@
   "@trackLyricsNotAvailable": {
     "description": "Message when lyrics not found"
   },
+  "trackLyricsNotInFile": "No lyrics found in this file",
+  "@trackLyricsNotInFile": {
+    "description": "Message when no embedded lyrics in audio file"
+  },
+  "trackFetchOnlineLyrics": "Fetch from Online",
+  "@trackFetchOnlineLyrics": {
+    "description": "Action - fetch lyrics from online providers"
+  },
   "trackLyricsTimeout": "Request timed out. Try again later.",
   "@trackLyricsTimeout": {
     "description": "Message when lyrics request times out"
@@ -2399,6 +2451,15 @@
       }
     }
   },
+  "libraryFilesUnit": "{count, plural, =1{file} other{files}}",
+  "@libraryFilesUnit": {
+    "description": "Unit label for files count during library scanning",
+    "placeholders": {
+      "count": {
+        "type": "int"
+      }
+    }
+  },
   "libraryLastScanned": "Last scanned: {time}",
   "@libraryLastScanned": {
     "description": "Last scan time display",
@@ -2416,6 +2477,10 @@
   "@libraryScanning": {
     "description": "Status during scan"
   },
+  "libraryScanFinalizing": "Finalizing library...",
+  "@libraryScanFinalizing": {
+    "description": "Status shown after file scanning finishes but library persistence is still running"
+  },
   "libraryScanProgress": "{progress}% of {total} files",
   "@libraryScanProgress": {
     "description": "Scan progress display",
@@ -2513,6 +2578,30 @@
   "@libraryFilterFormat": {
     "description": "Filter section - file format"
   },
+  "libraryFilterMetadata": "Metadata",
+  "@libraryFilterMetadata": {
+    "description": "Filter section - metadata completeness"
+  },
+  "libraryFilterMetadataComplete": "Complete metadata",
+  "@libraryFilterMetadataComplete": {
+    "description": "Filter option - items with complete metadata"
+  },
+  "libraryFilterMetadataMissingAny": "Missing any metadata",
+  "@libraryFilterMetadataMissingAny": {
+    "description": "Filter option - items missing any tracked metadata field"
+  },
+  "libraryFilterMetadataMissingYear": "Missing year",
+  "@libraryFilterMetadataMissingYear": {
+    "description": "Filter option - items missing release year/date"
+  },
+  "libraryFilterMetadataMissingGenre": "Missing genre",
+  "@libraryFilterMetadataMissingGenre": {
+    "description": "Filter option - items missing genre"
+  },
+  "libraryFilterMetadataMissingAlbumArtist": "Missing album artist",
+  "@libraryFilterMetadataMissingAlbumArtist": {
+    "description": "Filter option - items missing album artist"
+  },
   "libraryFilterSort": "Sort",
   "@libraryFilterSort": {
     "description": "Filter section - sort order"
@@ -2525,6 +2614,22 @@
   "@libraryFilterSortOldest": {
     "description": "Sort option - oldest first"
   },
+  "libraryFilterSortAlbumAsc": "Album (A-Z)",
+  "@libraryFilterSortAlbumAsc": {
+    "description": "Sort option - album ascending"
+  },
+  "libraryFilterSortAlbumDesc": "Album (Z-A)",
+  "@libraryFilterSortAlbumDesc": {
+    "description": "Sort option - album descending"
+  },
+  "libraryFilterSortGenreAsc": "Genre (A-Z)",
+  "@libraryFilterSortGenreAsc": {
+    "description": "Sort option - genre ascending"
+  },
+  "libraryFilterSortGenreDesc": "Genre (Z-A)",
+  "@libraryFilterSortGenreDesc": {
+    "description": "Sort option - genre descending"
+  },
   "timeJustNow": "Just now",
   "@timeJustNow": {
     "description": "Relative time - less than a minute ago"
@@ -2877,6 +2982,38 @@
   "@trackReEnrichOnlineSubtitle": {
     "description": "Subtitle for re-enrich metadata action for local items"
   },
+  "trackReEnrichFieldsTitle": "Fields to update",
+  "@trackReEnrichFieldsTitle": {
+    "description": "Section title for field selection in re-enrich dialog"
+  },
+  "trackReEnrichFieldCover": "Cover Art",
+  "@trackReEnrichFieldCover": {
+    "description": "Checkbox label for cover art field in re-enrich"
+  },
+  "trackReEnrichFieldLyrics": "Lyrics",
+  "@trackReEnrichFieldLyrics": {
+    "description": "Checkbox label for lyrics field in re-enrich"
+  },
+  "trackReEnrichFieldBasicTags": "Album, Album Artist",
+  "@trackReEnrichFieldBasicTags": {
+    "description": "Checkbox label for basic tags in re-enrich (title/artist are never overwritten)"
+  },
+  "trackReEnrichFieldTrackInfo": "Track & Disc Number",
+  "@trackReEnrichFieldTrackInfo": {
+    "description": "Checkbox label for track info in re-enrich"
+  },
+  "trackReEnrichFieldReleaseInfo": "Date & ISRC",
+  "@trackReEnrichFieldReleaseInfo": {
+    "description": "Checkbox label for release info in re-enrich"
+  },
+  "trackReEnrichFieldExtra": "Genre, Label, Copyright",
+  "@trackReEnrichFieldExtra": {
+    "description": "Checkbox label for extra metadata in re-enrich"
+  },
+  "trackReEnrichSelectAll": "Select All",
+  "@trackReEnrichSelectAll": {
+    "description": "Select all fields checkbox in re-enrich"
+  },
   "trackEditMetadata": "Edit Metadata",
   "@trackEditMetadata": {
     "description": "Menu action - edit embedded metadata"
@@ -3474,10 +3611,6 @@
   "@lyricsProvidersDiscardContent": {
     "description": "Body text of the discard-changes dialog on lyrics provider page"
   },
-  "lyricsProviderSpotifyApiDesc": "Spotify-sourced synced lyrics via community API",
-  "@lyricsProviderSpotifyApiDesc": {
-    "description": "Description for Spotify Lyrics API provider"
-  },
   "lyricsProviderLrclibDesc": "Open-source synced lyrics database",
   "@lyricsProviderLrclibDesc": {
     "description": "Description for LRCLIB provider"

lib/main.dart

@@ -82,7 +82,6 @@ class _RuntimeProfile {
   });
 }
 
-/// Widget to eagerly initialize providers that need to load data on startup
 class _EagerInitialization extends ConsumerStatefulWidget {
   const _EagerInitialization({required this.child});
   final Widget child;
@@ -170,10 +169,8 @@ class _EagerInitializationState extends ConsumerState<_EagerInitialization>
       const Duration(milliseconds: 1600),
       () {
         ref.read(localLibraryProvider);
-        // Trigger auto-scan after initial warmup on first app launch.
         if (!_autoScanTriggeredOnLaunch) {
           _autoScanTriggeredOnLaunch = true;
-          // Give the provider a moment to load existing data before scanning.
           Future.delayed(const Duration(milliseconds: 500), () {
             if (mounted) _maybeAutoScanLocalLibrary();
           });
@@ -182,8 +179,6 @@ class _EagerInitializationState extends ConsumerState<_EagerInitialization>
     );
   }
 
-  /// Checks whether an automatic incremental scan should be triggered based on
-  /// the user's auto-scan preference and the time since the last scan.
   Future<void> _maybeAutoScanLocalLibrary() async {
     if (!mounted) return;
 
@@ -204,7 +199,6 @@ class _EagerInitializationState extends ConsumerState<_EagerInitialization>
 
       switch (settings.localLibraryAutoScan) {
         case 'on_open':
-          // Cooldown of 10 minutes to prevent rapid re-scans.
           if (elapsed.inMinutes < 10) return;
           break;
         case 'daily':

lib/models/settings.dart

@@ -1,4 +1,5 @@
 import 'package:json_annotation/json_annotation.dart';
+import 'package:spotiflac_android/utils/artist_utils.dart';
 
 part 'settings.g.dart';
 
@@ -12,7 +13,10 @@ class AppSettings {
   final String downloadTreeUri; // SAF persistable tree URI
   final bool autoFallback;
   final bool embedMetadata; // Master switch for metadata/cover/lyrics embedding
+  final String
+  artistTagMode; // 'joined' or 'split_vorbis' for Vorbis-based formats
   final bool embedLyrics;
+  final bool embedReplayGain; // Calculate and embed ReplayGain tags
   final bool maxQualityCover;
   final bool isFirstLaunch;
   final int concurrentDownloads;
@@ -27,15 +31,12 @@ class AppSettings {
   final String historyViewMode;
   final String historyFilterMode;
   final bool askQualityBeforeDownload;
-  final String spotifyClientId;
-  final String spotifyClientSecret;
-  final bool useCustomSpotifyCredentials;
-  final String metadataSource;
   final bool enableLogging;
   final bool useExtensionProviders;
   final String? searchProvider;
   final String? homeFeedProvider;
   final bool separateSingles;
+  final String singleFilenameFormat;
   final String albumFolderStructure;
   final bool showExtensionStore;
   final String locale;
@@ -88,7 +89,9 @@ class AppSettings {
     this.downloadTreeUri = '',
     this.autoFallback = true,
     this.embedMetadata = true,
+    this.artistTagMode = artistTagModeJoined,
     this.embedLyrics = true,
+    this.embedReplayGain = false,
     this.maxQualityCover = true,
     this.isFirstLaunch = true,
     this.concurrentDownloads = 1,
@@ -103,15 +106,12 @@ class AppSettings {
     this.historyViewMode = 'grid',
     this.historyFilterMode = 'all',
     this.askQualityBeforeDownload = true,
-    this.spotifyClientId = '',
-    this.spotifyClientSecret = '',
-    this.useCustomSpotifyCredentials = false,
-    this.metadataSource = 'deezer',
     this.enableLogging = false,
     this.useExtensionProviders = true,
     this.searchProvider,
     this.homeFeedProvider,
     this.separateSingles = false,
+    this.singleFilenameFormat = '{title} - {artist}',
     this.albumFolderStructure = 'artist_album',
     this.showExtensionStore = true,
     this.locale = 'system',
@@ -130,7 +130,6 @@ class AppSettings {
     this.hasCompletedTutorial = false,
     this.lyricsProviders = const [
       'lrclib',
-      'spotify_api',
       'musixmatch',
       'netease',
       'apple_music',
@@ -152,7 +151,9 @@ class AppSettings {
     String? downloadTreeUri,
     bool? autoFallback,
     bool? embedMetadata,
+    String? artistTagMode,
     bool? embedLyrics,
+    bool? embedReplayGain,
     bool? maxQualityCover,
     bool? isFirstLaunch,
     int? concurrentDownloads,
@@ -167,10 +168,6 @@ class AppSettings {
     String? historyViewMode,
     String? historyFilterMode,
     bool? askQualityBeforeDownload,
-    String? spotifyClientId,
-    String? spotifyClientSecret,
-    bool? useCustomSpotifyCredentials,
-    String? metadataSource,
     bool? enableLogging,
     bool? useExtensionProviders,
     String? searchProvider,
@@ -178,6 +175,7 @@ class AppSettings {
     String? homeFeedProvider,
     bool clearHomeFeedProvider = false,
     bool? separateSingles,
+    String? singleFilenameFormat,
     String? albumFolderStructure,
     bool? showExtensionStore,
     String? locale,
@@ -210,7 +208,9 @@ class AppSettings {
       downloadTreeUri: downloadTreeUri ?? this.downloadTreeUri,
       autoFallback: autoFallback ?? this.autoFallback,
       embedMetadata: embedMetadata ?? this.embedMetadata,
+      artistTagMode: artistTagMode ?? this.artistTagMode,
       embedLyrics: embedLyrics ?? this.embedLyrics,
+      embedReplayGain: embedReplayGain ?? this.embedReplayGain,
       maxQualityCover: maxQualityCover ?? this.maxQualityCover,
       isFirstLaunch: isFirstLaunch ?? this.isFirstLaunch,
       concurrentDownloads: concurrentDownloads ?? this.concurrentDownloads,
@@ -229,11 +229,6 @@ class AppSettings {
       historyFilterMode: historyFilterMode ?? this.historyFilterMode,
       askQualityBeforeDownload:
           askQualityBeforeDownload ?? this.askQualityBeforeDownload,
-      spotifyClientId: spotifyClientId ?? this.spotifyClientId,
-      spotifyClientSecret: spotifyClientSecret ?? this.spotifyClientSecret,
-      useCustomSpotifyCredentials:
-          useCustomSpotifyCredentials ?? this.useCustomSpotifyCredentials,
-      metadataSource: metadataSource ?? this.metadataSource,
       enableLogging: enableLogging ?? this.enableLogging,
       useExtensionProviders:
           useExtensionProviders ?? this.useExtensionProviders,
@@ -244,6 +239,7 @@ class AppSettings {
           ? null
           : (homeFeedProvider ?? this.homeFeedProvider),
       separateSingles: separateSingles ?? this.separateSingles,
+      singleFilenameFormat: singleFilenameFormat ?? this.singleFilenameFormat,
       albumFolderStructure: albumFolderStructure ?? this.albumFolderStructure,
       showExtensionStore: showExtensionStore ?? this.showExtensionStore,
       locale: locale ?? this.locale,

lib/models/settings.g.dart

@@ -15,7 +15,9 @@ AppSettings _$AppSettingsFromJson(Map<String, dynamic> json) => AppSettings(
   downloadTreeUri: json['downloadTreeUri'] as String? ?? '',
   autoFallback: json['autoFallback'] as bool? ?? true,
   embedMetadata: json['embedMetadata'] as bool? ?? true,
+  artistTagMode: json['artistTagMode'] as String? ?? artistTagModeJoined,
   embedLyrics: json['embedLyrics'] as bool? ?? true,
+  embedReplayGain: json['embedReplayGain'] as bool? ?? false,
   maxQualityCover: json['maxQualityCover'] as bool? ?? true,
   isFirstLaunch: json['isFirstLaunch'] as bool? ?? true,
   concurrentDownloads: (json['concurrentDownloads'] as num?)?.toInt() ?? 1,
@@ -31,16 +33,13 @@ AppSettings _$AppSettingsFromJson(Map<String, dynamic> json) => AppSettings(
   historyViewMode: json['historyViewMode'] as String? ?? 'grid',
   historyFilterMode: json['historyFilterMode'] as String? ?? 'all',
   askQualityBeforeDownload: json['askQualityBeforeDownload'] as bool? ?? true,
-  spotifyClientId: json['spotifyClientId'] as String? ?? '',
-  spotifyClientSecret: json['spotifyClientSecret'] as String? ?? '',
-  useCustomSpotifyCredentials:
-      json['useCustomSpotifyCredentials'] as bool? ?? false,
-  metadataSource: json['metadataSource'] as String? ?? 'deezer',
   enableLogging: json['enableLogging'] as bool? ?? false,
   useExtensionProviders: json['useExtensionProviders'] as bool? ?? true,
   searchProvider: json['searchProvider'] as String?,
   homeFeedProvider: json['homeFeedProvider'] as String?,
   separateSingles: json['separateSingles'] as bool? ?? false,
+  singleFilenameFormat:
+      json['singleFilenameFormat'] as String? ?? '{title} - {artist}',
   albumFolderStructure:
       json['albumFolderStructure'] as String? ?? 'artist_album',
   showExtensionStore: json['showExtensionStore'] as bool? ?? true,
@@ -64,14 +63,7 @@ AppSettings _$AppSettingsFromJson(Map<String, dynamic> json) => AppSettings(
       (json['lyricsProviders'] as List<dynamic>?)
           ?.map((e) => e as String)
           .toList() ??
-      const [
-        'lrclib',
-        'spotify_api',
-        'musixmatch',
-        'netease',
-        'apple_music',
-        'qqmusic',
-      ],
+      const ['lrclib', 'musixmatch', 'netease', 'apple_music', 'qqmusic'],
   lyricsIncludeTranslationNetease:
       json['lyricsIncludeTranslationNetease'] as bool? ?? false,
   lyricsIncludeRomanizationNetease:
@@ -93,7 +85,9 @@ Map<String, dynamic> _$AppSettingsToJson(
   'downloadTreeUri': instance.downloadTreeUri,
   'autoFallback': instance.autoFallback,
   'embedMetadata': instance.embedMetadata,
+  'artistTagMode': instance.artistTagMode,
   'embedLyrics': instance.embedLyrics,
+  'embedReplayGain': instance.embedReplayGain,
   'maxQualityCover': instance.maxQualityCover,
   'isFirstLaunch': instance.isFirstLaunch,
   'concurrentDownloads': instance.concurrentDownloads,
@@ -109,15 +103,12 @@ Map<String, dynamic> _$AppSettingsToJson(
   'historyViewMode': instance.historyViewMode,
   'historyFilterMode': instance.historyFilterMode,
   'askQualityBeforeDownload': instance.askQualityBeforeDownload,
-  'spotifyClientId': instance.spotifyClientId,
-  'spotifyClientSecret': instance.spotifyClientSecret,
-  'useCustomSpotifyCredentials': instance.useCustomSpotifyCredentials,
-  'metadataSource': instance.metadataSource,
   'enableLogging': instance.enableLogging,
   'useExtensionProviders': instance.useExtensionProviders,
   'searchProvider': instance.searchProvider,
   'homeFeedProvider': instance.homeFeedProvider,
   'separateSingles': instance.separateSingles,
+  'singleFilenameFormat': instance.singleFilenameFormat,
   'albumFolderStructure': instance.albumFolderStructure,
   'showExtensionStore': instance.showExtensionStore,
   'locale': instance.locale,

lib/models/track.dart

@@ -49,26 +49,24 @@ class Track {
   bool get isSingle {
     switch (albumType?.toLowerCase()) {
       case 'single':
-        return true;
       case 'ep':
-        final count = totalTracks;
-        return count == null || count <= 1;
+        return true;
       default:
         return false;
     }
   }
-  
+
   bool get isAlbumItem => itemType == 'album';
-  
+
   bool get isPlaylistItem => itemType == 'playlist';
-  
+
   bool get isArtistItem => itemType == 'artist';
-  
+
   bool get isCollection => isAlbumItem || isPlaylistItem || isArtistItem;
 
   factory Track.fromJson(Map<String, dynamic> json) => _$TrackFromJson(json);
   Map<String, dynamic> toJson() => _$TrackToJson(this);
-  
+
   bool get isFromExtension => source != null && source!.isNotEmpty;
 }
 

lib/providers/explore_provider.dart

@@ -1,4 +1,5 @@
 import 'dart:convert';
+import 'package:flutter/foundation.dart';
 import 'package:flutter_riverpod/flutter_riverpod.dart';
 import 'package:shared_preferences/shared_preferences.dart';
 import 'package:spotiflac_android/services/platform_bridge.dart';
@@ -19,6 +20,7 @@ class ExploreItem {
   final String? providerId;
   final String? albumId;
   final String? albumName;
+  final String? releaseDate;
   final int durationMs;
 
   const ExploreItem({
@@ -32,6 +34,7 @@ class ExploreItem {
     this.providerId,
     this.albumId,
     this.albumName,
+    this.releaseDate,
     this.durationMs = 0,
   });
 
@@ -47,6 +50,7 @@ class ExploreItem {
       providerId: json['provider_id'] as String?,
       albumId: json['album_id'] as String?,
       albumName: json['album_name'] as String?,
+      releaseDate: json['release_date']?.toString(),
       durationMs: json['duration_ms'] as int? ?? 0,
     );
   }
@@ -62,6 +66,7 @@ class ExploreItem {
     'provider_id': providerId,
     'album_id': albumId,
     'album_name': albumName,
+    'release_date': releaseDate,
     'duration_ms': durationMs,
   };
 }
@@ -158,6 +163,52 @@ bool _isYTMusicQuickPicksItems(List<ExploreItem> items) {
   return true;
 }
 
+List<Map<String, Object?>> _normalizeExploreSectionsPayload(
+  dynamic rawSections,
+) {
+  if (rawSections is! List) return const [];
+  final sections = <Map<String, Object?>>[];
+  for (final rawSection in rawSections) {
+    if (rawSection is! Map) continue;
+    final section = Map<Object?, Object?>.from(rawSection);
+    final rawItems = section['items'];
+    final items = <Map<String, Object?>>[];
+    if (rawItems is List) {
+      for (final rawItem in rawItems) {
+        if (rawItem is! Map) continue;
+        items.add(Map<String, Object?>.from(rawItem));
+      }
+    }
+    sections.add({
+      'uri': section['uri']?.toString() ?? '',
+      'title': section['title']?.toString() ?? '',
+      'items': items,
+    });
+  }
+  return sections;
+}
+
+List<Map<String, Object?>> _decodeExploreCacheSections(String rawCache) {
+  final decoded = jsonDecode(rawCache);
+  if (decoded is! Map) return const [];
+  return _normalizeExploreSectionsPayload(decoded['sections']);
+}
+
+String _encodeExploreCacheSections(List<Map<String, Object?>> sections) {
+  return jsonEncode({'sections': sections});
+}
+
+List<ExploreSection> _buildExploreSectionsFromNormalizedPayload(
+  List<Map<String, Object?>> normalizedSections,
+) {
+  return normalizedSections
+      .map(
+        (section) =>
+            ExploreSection.fromJson(Map<String, dynamic>.from(section)),
+      )
+      .toList(growable: false);
+}
+
 class ExploreNotifier extends Notifier<ExploreState> {
   static const _cacheKey = 'explore_home_feed_cache';
   static const _cacheTsKey = 'explore_home_feed_ts';
@@ -175,11 +226,13 @@ class ExploreNotifier extends Notifier<ExploreState> {
       final cachedTs = prefs.getInt(_cacheTsKey);
       if (cached == null || cached.isEmpty) return;
 
-      final data = jsonDecode(cached) as Map<String, dynamic>;
-      final sectionsData = data['sections'] as List<dynamic>? ?? [];
-      final sections = sectionsData
-          .map((s) => ExploreSection.fromJson(s as Map<String, dynamic>))
-          .toList();
+      final normalizedSections = await compute(
+        _decodeExploreCacheSections,
+        cached,
+      );
+      final sections = _buildExploreSectionsFromNormalizedPayload(
+        normalizedSections,
+      );
 
       if (sections.isEmpty) return;
 
@@ -198,13 +251,18 @@ class ExploreNotifier extends Notifier<ExploreState> {
     }
   }
 
-  Future<void> _saveToCache(List<ExploreSection> sections) async {
+  Future<void> _saveToCache(
+    List<Map<String, Object?>> normalizedSections,
+  ) async {
     try {
       final prefs = await SharedPreferences.getInstance();
-      final data = {'sections': sections.map((s) => s.toJson()).toList()};
-      await prefs.setString(_cacheKey, jsonEncode(data));
+      final encoded = await compute(
+        _encodeExploreCacheSections,
+        normalizedSections,
+      );
+      await prefs.setString(_cacheKey, encoded);
       await prefs.setInt(_cacheTsKey, DateTime.now().millisecondsSinceEpoch);
-      _log.d('Saved ${sections.length} explore sections to cache');
+      _log.d('Saved ${normalizedSections.length} explore sections to cache');
     } catch (e) {
       _log.w('Failed to save explore cache: $e');
     }
@@ -286,10 +344,13 @@ class ExploreNotifier extends Notifier<ExploreState> {
 
       final greeting = result['greeting'] as String?;
       final sectionsData = result['sections'] as List<dynamic>? ?? [];
-
-      final sections = sectionsData
-          .map((s) => ExploreSection.fromJson(s as Map<String, dynamic>))
-          .toList();
+      final normalizedSections = await compute(
+        _normalizeExploreSectionsPayload,
+        sectionsData,
+      );
+      final sections = _buildExploreSectionsFromNormalizedPayload(
+        normalizedSections,
+      );
 
       _log.i('Fetched ${sections.length} sections');
 
@@ -310,7 +371,7 @@ class ExploreNotifier extends Notifier<ExploreState> {
         lastFetched: DateTime.now(),
       );
 
-      _saveToCache(sections);
+      _saveToCache(normalizedSections);
     } catch (e, stack) {
       _log.e('Error fetching home feed: $e', e, stack);
       state = state.copyWith(isLoading: false, error: e.toString());

lib/providers/extension_provider.dart

@@ -33,6 +33,7 @@ class Extension {
   final bool hasDownloadProvider;
   final bool hasLyricsProvider;
   final bool skipMetadataEnrichment;
+  final bool skipLyrics;
   final SearchBehavior? searchBehavior;
   final URLHandler? urlHandler;
   final TrackMatching? trackMatching;
@@ -57,6 +58,7 @@ class Extension {
     this.hasDownloadProvider = false,
     this.hasLyricsProvider = false,
     this.skipMetadataEnrichment = false,
+    this.skipLyrics = false,
     this.searchBehavior,
     this.urlHandler,
     this.trackMatching,
@@ -94,6 +96,7 @@ class Extension {
       hasLyricsProvider: json['has_lyrics_provider'] as bool? ?? false,
       skipMetadataEnrichment:
           json['skip_metadata_enrichment'] as bool? ?? false,
+      skipLyrics: json['skip_lyrics'] as bool? ?? false,
       searchBehavior: json['search_behavior'] != null
           ? SearchBehavior.fromJson(
               json['search_behavior'] as Map<String, dynamic>,
@@ -134,6 +137,7 @@ class Extension {
     bool? hasDownloadProvider,
     bool? hasLyricsProvider,
     bool? skipMetadataEnrichment,
+    bool? skipLyrics,
     SearchBehavior? searchBehavior,
     URLHandler? urlHandler,
     TrackMatching? trackMatching,
@@ -159,6 +163,7 @@ class Extension {
       hasLyricsProvider: hasLyricsProvider ?? this.hasLyricsProvider,
       skipMetadataEnrichment:
           skipMetadataEnrichment ?? this.skipMetadataEnrichment,
+      skipLyrics: skipLyrics ?? this.skipLyrics,
       searchBehavior: searchBehavior ?? this.searchBehavior,
       urlHandler: urlHandler ?? this.urlHandler,
       trackMatching: trackMatching ?? this.trackMatching,
@@ -662,9 +667,8 @@ class ExtensionNotifier extends Notifier<ExtensionState> {
 
         if (settings.searchProvider == extensionId) {
           ref.read(settingsProvider.notifier).setSearchProvider(null);
-          ref.read(settingsProvider.notifier).setMetadataSource('deezer');
           _log.d(
-            'Cleared search provider and reset to Deezer because extension $extensionId was disabled',
+            'Cleared search provider because extension $extensionId was disabled',
           );
         }
 

lib/providers/library_collections_provider.dart

@@ -1,6 +1,7 @@
 import 'dart:convert';
 import 'dart:io';
 
+import 'package:flutter/foundation.dart';
 import 'package:flutter_riverpod/flutter_riverpod.dart';
 import 'package:path/path.dart' as p;
 import 'package:path_provider/path_provider.dart';
@@ -127,6 +128,54 @@ class UserPlaylistCollection {
   }
 }
 
+class PlaylistPickerSummary {
+  final String id;
+  final String name;
+  final String? coverImagePath;
+  final String? previewCover;
+  final DateTime createdAt;
+  final DateTime updatedAt;
+  final int trackCount;
+  final bool containsAllRequestedTracks;
+
+  const PlaylistPickerSummary({
+    required this.id,
+    required this.name,
+    this.coverImagePath,
+    this.previewCover,
+    required this.createdAt,
+    required this.updatedAt,
+    required this.trackCount,
+    required this.containsAllRequestedTracks,
+  });
+}
+
+class PlaylistPickerSummaryRequest {
+  final List<String> trackKeys;
+
+  PlaylistPickerSummaryRequest._(this.trackKeys);
+
+  factory PlaylistPickerSummaryRequest.fromTracks(Iterable<Track> tracks) {
+    final keys =
+        tracks
+            .map(trackCollectionKey)
+            .where((key) => key.trim().isNotEmpty)
+            .toSet()
+            .toList(growable: false)
+          ..sort();
+    return PlaylistPickerSummaryRequest._(keys);
+  }
+
+  @override
+  bool operator ==(Object other) =>
+      identical(this, other) ||
+      other is PlaylistPickerSummaryRequest &&
+          listEquals(trackKeys, other.trackKeys);
+
+  @override
+  int get hashCode => Object.hashAll(trackKeys);
+}
+
 class LibraryCollectionsState {
   final List<CollectionTrackEntry> wishlist;
   final List<CollectionTrackEntry> loved;
@@ -280,6 +329,10 @@ class LibraryCollectionsNotifier extends Notifier<LibraryCollectionsState> {
   final LibraryCollectionsDatabase _db = LibraryCollectionsDatabase.instance;
   Future<void>? _loadFuture;
 
+  void _invalidatePlaylistPickerSummaries() {
+    ref.invalidate(libraryPlaylistPickerSummariesProvider);
+  }
+
   @override
   LibraryCollectionsState build() {
     _loadFuture = _load();
@@ -494,6 +547,7 @@ class LibraryCollectionsNotifier extends Notifier<LibraryCollectionsState> {
       updatedAt: now.toIso8601String(),
     );
     state = state.copyWith(playlists: [playlist, ...state.playlists]);
+    _invalidatePlaylistPickerSummaries();
     return id;
   }
 
@@ -513,6 +567,7 @@ class LibraryCollectionsNotifier extends Notifier<LibraryCollectionsState> {
     _replacePlaylistById(playlistId, (playlist) {
       return playlist.copyWith(name: trimmed, updatedAt: now);
     });
+    _invalidatePlaylistPickerSummaries();
   }
 
   Future<void> deletePlaylist(String playlistId) async {
@@ -523,6 +578,7 @@ class LibraryCollectionsNotifier extends Notifier<LibraryCollectionsState> {
     await _db.deletePlaylist(playlistId);
     final updatedPlaylists = [...state.playlists]..removeAt(playlistIndex);
     state = state.copyWith(playlists: updatedPlaylists);
+    _invalidatePlaylistPickerSummaries();
   }
 
   Future<bool> addTrackToPlaylist(String playlistId, Track track) async {
@@ -550,6 +606,7 @@ class LibraryCollectionsNotifier extends Notifier<LibraryCollectionsState> {
       );
     });
     if (!changed) return false;
+    _invalidatePlaylistPickerSummaries();
     return true;
   }
 
@@ -615,6 +672,7 @@ class LibraryCollectionsNotifier extends Notifier<LibraryCollectionsState> {
         alreadyInPlaylistCount: alreadyInPlaylistCount,
       );
     }
+    _invalidatePlaylistPickerSummaries();
     return PlaylistAddBatchResult(
       addedCount: entriesToAdd.length,
       alreadyInPlaylistCount: alreadyInPlaylistCount,
@@ -642,6 +700,7 @@ class LibraryCollectionsNotifier extends Notifier<LibraryCollectionsState> {
       if (nextTracks.length == playlist.tracks.length) return playlist;
       return playlist.copyWith(tracks: nextTracks, updatedAt: now);
     });
+    _invalidatePlaylistPickerSummaries();
   }
 
   Future<Directory> _playlistCoversDir() async {
@@ -678,6 +737,7 @@ class LibraryCollectionsNotifier extends Notifier<LibraryCollectionsState> {
       if (playlist.coverImagePath == destPath) return playlist;
       return playlist.copyWith(coverImagePath: () => destPath, updatedAt: now);
     });
+    _invalidatePlaylistPickerSummaries();
   }
 
   Future<void> removePlaylistCover(String playlistId) async {
@@ -703,6 +763,7 @@ class LibraryCollectionsNotifier extends Notifier<LibraryCollectionsState> {
       if (playlist.coverImagePath == null) return playlist;
       return playlist.copyWith(coverImagePath: () => null, updatedAt: now);
     });
+    _invalidatePlaylistPickerSummaries();
   }
 }
 
@@ -710,3 +771,27 @@ final libraryCollectionsProvider =
     NotifierProvider<LibraryCollectionsNotifier, LibraryCollectionsState>(
       LibraryCollectionsNotifier.new,
     );
+
+final libraryPlaylistPickerSummariesProvider =
+    FutureProvider.family<
+      List<PlaylistPickerSummary>,
+      PlaylistPickerSummaryRequest
+    >((ref, request) async {
+      final db = LibraryCollectionsDatabase.instance;
+      await db.migrateFromSharedPreferences();
+      final rows = await db.loadPlaylistPickerSummaries(request.trackKeys);
+      return rows
+          .map(
+            (row) => PlaylistPickerSummary(
+              id: row.id,
+              name: row.name,
+              coverImagePath: row.coverImagePath,
+              previewCover: row.previewCover,
+              createdAt: row.createdAt,
+              updatedAt: row.updatedAt,
+              trackCount: row.trackCount,
+              containsAllRequestedTracks: row.containsAllRequestedTracks,
+            ),
+          )
+          .toList(growable: false);
+    });

lib/providers/local_library_provider.dart

@@ -20,6 +20,7 @@ final _prefs = SharedPreferences.getInstance();
 class LocalLibraryState {
   final List<LocalLibraryItem> items;
   final bool isScanning;
+  final bool scanIsFinalizing;
   final double scanProgress;
   final String? scanCurrentFile;
   final int scanTotalFiles;
@@ -35,6 +36,7 @@ class LocalLibraryState {
   LocalLibraryState({
     this.items = const [],
     this.isScanning = false,
+    this.scanIsFinalizing = false,
     this.scanProgress = 0,
     this.scanCurrentFile,
     this.scanTotalFiles = 0,
@@ -85,6 +87,7 @@ class LocalLibraryState {
   LocalLibraryState copyWith({
     List<LocalLibraryItem>? items,
     bool? isScanning,
+    bool? scanIsFinalizing,
     double? scanProgress,
     String? scanCurrentFile,
     int? scanTotalFiles,
@@ -100,6 +103,7 @@ class LocalLibraryState {
     return LocalLibraryState(
       items: nextItems,
       isScanning: isScanning ?? this.isScanning,
+      scanIsFinalizing: scanIsFinalizing ?? this.scanIsFinalizing,
       scanProgress: scanProgress ?? this.scanProgress,
       scanCurrentFile: scanCurrentFile ?? this.scanCurrentFile,
       scanTotalFiles: scanTotalFiles ?? this.scanTotalFiles,
@@ -120,7 +124,8 @@ class LocalLibraryNotifier extends Notifier<LocalLibraryState> {
   final LibraryDatabase _db = LibraryDatabase.instance;
   final HistoryDatabase _historyDb = HistoryDatabase.instance;
   final NotificationService _notificationService = NotificationService();
-  static const _progressPollingInterval = Duration(milliseconds: 1200);
+  static const _progressPollingInterval = Duration(milliseconds: 350);
+  static const _progressStreamBootstrapTimeout = Duration(milliseconds: 900);
   Timer? _progressTimer;
   Timer? _progressStreamBootstrapTimer;
   StreamSubscription<Map<String, dynamic>>? _progressStreamSub;
@@ -220,6 +225,7 @@ class LocalLibraryNotifier extends Notifier<LocalLibraryState> {
     );
     state = state.copyWith(
       isScanning: true,
+      scanIsFinalizing: false,
       scanProgress: 0,
       scanCurrentFile: null,
       scanTotalFiles: 0,
@@ -297,11 +303,21 @@ class LocalLibraryNotifier extends Notifier<LocalLibraryState> {
             ? await PlatformBridge.scanSafTree(effectiveFolderPath)
             : await PlatformBridge.scanLibraryFolder(effectiveFolderPath);
         if (_scanCancelRequested) {
-          state = state.copyWith(isScanning: false, scanWasCancelled: true);
+          state = state.copyWith(
+            isScanning: false,
+            scanIsFinalizing: false,
+            scanWasCancelled: true,
+          );
           await _showScanCancelledNotification();
           return;
         }
 
+        state = state.copyWith(
+          scanIsFinalizing: true,
+          scanProgress: state.scanProgress >= 99 ? state.scanProgress : 99,
+          scanCurrentFile: null,
+        );
+
         final items = <LocalLibraryItem>[];
         int skippedDownloads = 0;
         for (final json in results) {
@@ -334,11 +350,13 @@ class LocalLibraryNotifier extends Notifier<LocalLibraryState> {
         state = state.copyWith(
           items: persistedItems,
           isScanning: false,
+          scanIsFinalizing: false,
           scanProgress: 100,
           lastScannedAt: now,
           scanWasCancelled: false,
           excludedDownloadedCount: skippedDownloads,
         );
+        await _pruneLibraryCoverCache(persistedItems);
 
         _log.i(
           'Full scan complete: ${persistedItems.length} tracks found, '
@@ -403,11 +421,21 @@ class LocalLibraryNotifier extends Notifier<LocalLibraryState> {
         }
 
         if (_scanCancelRequested) {
-          state = state.copyWith(isScanning: false, scanWasCancelled: true);
+          state = state.copyWith(
+            isScanning: false,
+            scanIsFinalizing: false,
+            scanWasCancelled: true,
+          );
           await _showScanCancelledNotification();
           return;
         }
 
+        state = state.copyWith(
+          scanIsFinalizing: true,
+          scanProgress: state.scanProgress >= 99 ? state.scanProgress : 99,
+          scanCurrentFile: null,
+        );
+
         final scannedList =
             (result['files'] as List<dynamic>?) ??
             (result['scanned'] as List<dynamic>?) ??
@@ -497,6 +525,7 @@ class LocalLibraryNotifier extends Notifier<LocalLibraryState> {
         state = state.copyWith(
           items: items,
           isScanning: false,
+          scanIsFinalizing: false,
           scanProgress: 100,
           lastScannedAt: now,
           scanWasCancelled: false,
@@ -516,7 +545,11 @@ class LocalLibraryNotifier extends Notifier<LocalLibraryState> {
       }
     } catch (e, stack) {
       _log.e('Library scan failed: $e', e, stack);
-      state = state.copyWith(isScanning: false, scanWasCancelled: false);
+      state = state.copyWith(
+        isScanning: false,
+        scanIsFinalizing: false,
+        scanWasCancelled: false,
+      );
       await _showScanFailedNotification(e.toString());
     } finally {
       if (didStartSecurityAccess) {
@@ -573,16 +606,21 @@ class LocalLibraryNotifier extends Notifier<LocalLibraryState> {
         cancelOnError: false,
       );
 
-      _progressStreamBootstrapTimer = Timer(const Duration(seconds: 3), () {
-        if (_hasReceivedProgressStreamEvent) {
-          return;
-        }
-        _log.w('Library scan progress stream timeout, fallback to polling');
-        _progressStreamSub?.cancel();
-        _progressStreamSub = null;
-        _usingProgressStream = false;
-        _startProgressPollingTimer();
-      });
+      Future<void>.microtask(_requestProgressSnapshot);
+
+      _progressStreamBootstrapTimer = Timer(
+        _progressStreamBootstrapTimeout,
+        () {
+          if (_hasReceivedProgressStreamEvent) {
+            return;
+          }
+          _log.w('Library scan progress stream timeout, fallback to polling');
+          _progressStreamSub?.cancel();
+          _progressStreamSub = null;
+          _usingProgressStream = false;
+          _startProgressPollingTimer();
+        },
+      );
       return;
     }
 
@@ -609,20 +647,41 @@ class LocalLibraryNotifier extends Notifier<LocalLibraryState> {
     });
   }
 
+  Future<void> _requestProgressSnapshot() async {
+    if (_isProgressPollingInFlight) return;
+    _isProgressPollingInFlight = true;
+    try {
+      final progress = await PlatformBridge.getLibraryScanProgress();
+      await _handleLibraryScanProgress(progress);
+      _progressPollingErrorCount = 0;
+    } catch (e) {
+      _progressPollingErrorCount++;
+      if (_progressPollingErrorCount <= 3) {
+        _log.w('Initial library scan progress fetch failed: $e');
+      }
+    } finally {
+      _isProgressPollingInFlight = false;
+    }
+  }
+
   Future<void> _handleLibraryScanProgress(Map<String, dynamic> progress) async {
     final nextProgress = (progress['progress_pct'] as num?)?.toDouble() ?? 0;
     final normalizedProgress = ((nextProgress * 10).round() / 10).clamp(
       0.0,
       100.0,
     );
+    final isComplete = progress['is_complete'] == true;
+    final displayProgress = isComplete
+        ? 99.0
+        : (normalizedProgress >= 100.0 ? 99.0 : normalizedProgress);
     final currentFile = progress['current_file'] as String?;
     final totalFiles = (progress['total_files'] as num?)?.toInt() ?? 0;
     final scannedFiles = (progress['scanned_files'] as num?)?.toInt() ?? 0;
     final errorCount = (progress['error_count'] as num?)?.toInt() ?? 0;
-    final isComplete = progress['is_complete'] == true;
 
     final shouldUpdateState =
-        state.scanProgress != normalizedProgress ||
+        state.scanProgress != displayProgress ||
+        state.scanIsFinalizing != isComplete ||
         state.scanCurrentFile != currentFile ||
         state.scanTotalFiles != totalFiles ||
         state.scannedFiles != scannedFiles ||
@@ -630,8 +689,9 @@ class LocalLibraryNotifier extends Notifier<LocalLibraryState> {
 
     if (shouldUpdateState) {
       state = state.copyWith(
-        scanProgress: normalizedProgress,
-        scanCurrentFile: currentFile,
+        scanIsFinalizing: isComplete,
+        scanProgress: displayProgress,
+        scanCurrentFile: isComplete ? null : currentFile,
         scanTotalFiles: totalFiles,
         scannedFiles: scannedFiles,
         scanErrorCount: errorCount,
@@ -704,7 +764,11 @@ class LocalLibraryNotifier extends Notifier<LocalLibraryState> {
     _log.i('Cancelling library scan');
     _scanCancelRequested = true;
     await PlatformBridge.cancelLibraryScan();
-    state = state.copyWith(isScanning: false, scanWasCancelled: true);
+    state = state.copyWith(
+      isScanning: false,
+      scanIsFinalizing: false,
+      scanWasCancelled: true,
+    );
     _stopProgressPolling();
     await _showScanCancelledNotification();
   }
@@ -815,6 +879,46 @@ class LocalLibraryNotifier extends Notifier<LocalLibraryState> {
     _log.i('Library cleared');
   }
 
+  Future<void> _pruneLibraryCoverCache(Iterable<LocalLibraryItem> items) async {
+    try {
+      final appSupportDir = await getApplicationSupportDirectory();
+      final libraryCoverDir = Directory('${appSupportDir.path}/library_covers');
+      if (!await libraryCoverDir.exists()) {
+        return;
+      }
+
+      final referencedCoverPaths = items
+          .map((item) => item.coverPath)
+          .whereType<String>()
+          .where((path) => path.isNotEmpty)
+          .toSet();
+
+      var deletedCount = 0;
+      await for (final entity in libraryCoverDir.list(
+        recursive: true,
+        followLinks: false,
+      )) {
+        if (entity is! File || referencedCoverPaths.contains(entity.path)) {
+          continue;
+        }
+        try {
+          await entity.delete();
+          deletedCount++;
+        } catch (e) {
+          _log.w(
+            'Failed deleting stale library cover cache ${entity.path}: $e',
+          );
+        }
+      }
+
+      if (deletedCount > 0) {
+        _log.i('Pruned $deletedCount stale library cover cache files');
+      }
+    } catch (e) {
+      _log.w('Failed pruning library cover cache: $e');
+    }
+  }
+
   Future<void> removeItem(String id) async {
     await _db.delete(id);
     state = state.copyWith(

lib/providers/settings_provider.dart

@@ -6,12 +6,13 @@ import 'package:flutter_secure_storage/flutter_secure_storage.dart';
 import 'package:spotiflac_android/models/settings.dart';
 import 'package:spotiflac_android/constants/app_info.dart';
 import 'package:spotiflac_android/services/platform_bridge.dart';
+import 'package:spotiflac_android/utils/artist_utils.dart';
 import 'package:spotiflac_android/utils/file_access.dart';
 import 'package:spotiflac_android/utils/logger.dart';
 
 const _settingsKey = 'app_settings';
 const _migrationVersionKey = 'settings_migration_version';
-const _currentMigrationVersion = 7;
+const _currentMigrationVersion = 9;
 const _spotifyClientSecretKey = 'spotify_client_secret';
 final _log = AppLogger('SettingsProvider');
 
@@ -43,7 +44,7 @@ class SettingsNotifier extends Notifier<AppSettings> {
       await _normalizeSongLinkRegionIfNeeded();
     }
 
-    await _retireBuiltInSpotifyProvider();
+    await _cleanupRetiredSpotifySettings();
 
     LogBuffer.loggingEnabled = state.enableLogging;
 
@@ -85,13 +86,6 @@ class SettingsNotifier extends Notifier<AppSettings> {
   Future<void> _runMigrations(SharedPreferences prefs) async {
     final lastMigration = prefs.getInt(_migrationVersionKey) ?? 0;
 
-    if (lastMigration < 1) {
-      if (!state.useCustomSpotifyCredentials) {
-        state = state.copyWith(metadataSource: 'deezer');
-        await _saveSettings();
-      }
-    }
-
     if (lastMigration < _currentMigrationVersion) {
       if (state.downloadTreeUri.isNotEmpty && state.storageMode != 'saf') {
         state = state.copyWith(storageMode: 'saf');
@@ -100,26 +94,20 @@ class SettingsNotifier extends Notifier<AppSettings> {
       if (!state.isFirstLaunch && !state.hasCompletedTutorial) {
         state = state.copyWith(hasCompletedTutorial: true);
       }
-      // Migration 4: include Spotify Lyrics API in provider order for existing users
-      if (!state.lyricsProviders.contains('spotify_api')) {
-        final updatedProviders = List<String>.from(state.lyricsProviders);
-        final lrclibIndex = updatedProviders.indexOf('lrclib');
-        if (lrclibIndex >= 0) {
-          updatedProviders.insert(lrclibIndex + 1, 'spotify_api');
-        } else {
-          updatedProviders.add('spotify_api');
-        }
-        state = state.copyWith(lyricsProviders: updatedProviders);
-      }
-      if (state.metadataSource != 'deezer' ||
-          state.spotifyClientId.isNotEmpty ||
-          state.spotifyClientSecret.isNotEmpty ||
-          state.useCustomSpotifyCredentials) {
+      if (state.lyricsProviders.contains('spotify_api')) {
+        final updatedProviders = state.lyricsProviders
+            .where((provider) => provider != 'spotify_api')
+            .toList();
         state = state.copyWith(
-          metadataSource: 'deezer',
-          spotifyClientId: '',
-          spotifyClientSecret: '',
-          useCustomSpotifyCredentials: false,
+          lyricsProviders: updatedProviders.isEmpty
+              ? const [
+                  'lrclib',
+                  'musixmatch',
+                  'netease',
+                  'apple_music',
+                  'qqmusic',
+                ]
+              : updatedProviders,
         );
       }
       state = state.copyWith(lastSeenVersion: AppInfo.version);
@@ -133,8 +121,7 @@ class SettingsNotifier extends Notifier<AppSettings> {
   }
 
   Future<void> _saveSettings() async {
-    final settingsToSave = state.copyWith(spotifyClientSecret: '');
-    _pendingSettingsJson = jsonEncode(settingsToSave.toJson());
+    _pendingSettingsJson = jsonEncode(state.toJson());
 
     if (_isSavingSettings) {
       _saveQueued = true;
@@ -185,28 +172,13 @@ class SettingsNotifier extends Notifier<AppSettings> {
     await _saveSettings();
   }
 
-  Future<void> _retireBuiltInSpotifyProvider() async {
+  Future<void> _cleanupRetiredSpotifySettings() async {
     final storedSecret = await _secureStorage.read(
       key: _spotifyClientSecretKey,
     );
     if (storedSecret != null && storedSecret.isNotEmpty) {
       await _secureStorage.delete(key: _spotifyClientSecretKey);
     }
-
-    if (state.metadataSource == 'deezer' &&
-        state.spotifyClientId.isEmpty &&
-        state.spotifyClientSecret.isEmpty &&
-        !state.useCustomSpotifyCredentials) {
-      return;
-    }
-
-    state = state.copyWith(
-      metadataSource: 'deezer',
-      spotifyClientId: '',
-      spotifyClientSecret: '',
-      useCustomSpotifyCredentials: false,
-    );
-    await _saveSettings();
   }
 
   void setDefaultService(String service) {
@@ -224,6 +196,11 @@ class SettingsNotifier extends Notifier<AppSettings> {
     _saveSettings();
   }
 
+  void setSingleFilenameFormat(String format) {
+    state = state.copyWith(singleFilenameFormat: format);
+    _saveSettings();
+  }
+
   void setDownloadDirectory(String directory) {
     state = state.copyWith(downloadDirectory: directory);
     _saveSettings();
@@ -255,11 +232,23 @@ class SettingsNotifier extends Notifier<AppSettings> {
     _saveSettings();
   }
 
+  void setEmbedReplayGain(bool enabled) {
+    state = state.copyWith(embedReplayGain: enabled);
+    _saveSettings();
+  }
+
   void setEmbedMetadata(bool enabled) {
     state = state.copyWith(embedMetadata: enabled);
     _saveSettings();
   }
 
+  void setArtistTagMode(String mode) {
+    if (mode == artistTagModeJoined || mode == artistTagModeSplitVorbis) {
+      state = state.copyWith(artistTagMode: mode);
+      _saveSettings();
+    }
+  }
+
   void setLyricsMode(String mode) {
     if (mode == 'embed' || mode == 'external' || mode == 'both') {
       state = state.copyWith(lyricsMode: mode);
@@ -372,11 +361,6 @@ class SettingsNotifier extends Notifier<AppSettings> {
     _saveSettings();
   }
 
-  void setMetadataSource(String source) {
-    state = state.copyWith(metadataSource: source);
-    _saveSettings();
-  }
-
   void setSearchProvider(String? provider) {
     if (provider == null || provider.isEmpty) {
       state = state.copyWith(clearSearchProvider: true);

lib/providers/store_provider.dart

@@ -146,7 +146,6 @@ class StoreState {
     this.registryUrl = '',
   });
 
-  /// Whether a registry URL has been configured by the user.
   bool get hasRegistryUrl => registryUrl.isNotEmpty;
 
   StoreState copyWith({
@@ -218,7 +217,6 @@ class StoreNotifier extends Notifier<StoreState> {
   Future<void> initialize(String cacheDir) async {
     if (state.isInitialized) return;
 
-    // Load saved registry URL early to avoid UI flash (empty → setup screen)
     final prefs = await SharedPreferences.getInstance();
     final savedUrl = prefs.getString(_registryUrlPrefKey) ?? '';
 
@@ -246,8 +244,6 @@ class StoreNotifier extends Notifier<StoreState> {
     }
   }
 
-  /// Sets the registry URL, saves it, and refreshes the store.
-  /// The Go backend handles URL normalisation (GitHub repo → raw URL, branch detection).
   Future<void> setRegistryUrl(String url) async {
     final trimmed = url.trim();
     if (trimmed.isEmpty) {
@@ -258,10 +254,8 @@ class StoreNotifier extends Notifier<StoreState> {
     state = state.copyWith(isLoading: true, clearError: true);
 
     try {
-      // Go backend resolves GitHub URLs (detects default branch) and validates HTTPS.
       await PlatformBridge.setStoreRegistryUrl(trimmed);
 
-      // Read back the resolved URL (may differ from input after normalisation).
       final resolvedUrl = await PlatformBridge.getStoreRegistryUrl();
 
       final prefs = await SharedPreferences.getInstance();
@@ -280,13 +274,11 @@ class StoreNotifier extends Notifier<StoreState> {
     }
   }
 
-  /// Removes the saved registry URL and fully detaches the repo from backend.
   Future<void> removeRegistryUrl() async {
     try {
       final prefs = await SharedPreferences.getInstance();
       await prefs.remove(_registryUrlPrefKey);
 
-      // Reset the URL in Go backend memory AND clear its cache
       await PlatformBridge.clearStoreRegistryUrl();
 
       state = state.copyWith(

lib/screens/album_screen.dart

@@ -11,6 +11,7 @@ import 'package:spotiflac_android/providers/local_library_provider.dart';
 import 'package:spotiflac_android/providers/playback_provider.dart';
 import 'package:spotiflac_android/services/platform_bridge.dart';
 import 'package:spotiflac_android/utils/file_access.dart';
+import 'package:spotiflac_android/utils/image_cache_utils.dart';
 import 'package:spotiflac_android/utils/string_utils.dart';
 import 'package:spotiflac_android/widgets/track_collection_quick_actions.dart';
 import 'package:spotiflac_android/widgets/download_service_picker.dart';
@@ -138,14 +139,11 @@ class _AlbumScreenState extends ConsumerState<AlbumScreen> {
     return (mediaSize.height * 0.55).clamp(360.0, 520.0);
   }
 
-  /// Upgrade cover URL to a higher resolution for full-screen display.
   String? _highResCoverUrl(String? url) {
     if (url == null) return null;
-    // Spotify CDN: upgrade 300 → 640 only (no intermediate between 640 and 2000)
     if (url.contains('ab67616d00001e02')) {
       return url.replaceAll('ab67616d00001e02', 'ab67616d0000b273');
     }
-    // Deezer CDN: upgrade to 1000x1000
     final deezerRegex = RegExp(r'/(\d+)x(\d+)-(\d+)-(\d+)-(\d+)-(\d+)\.jpg$');
     if (url.contains('cdn-images.dzcdn.net') && deezerRegex.hasMatch(url)) {
       return url.replaceAllMapped(
@@ -393,6 +391,7 @@ class _AlbumScreenState extends ConsumerState<AlbumScreen> {
               (constraints.maxHeight - kToolbarHeight) /
               (expandedHeight - kToolbarHeight);
           final showContent = collapseRatio > 0.3;
+          final cacheWidth = coverCacheWidthForViewport(context);
 
           return FlexibleSpaceBar(
             collapseMode: CollapseMode.pin,
@@ -404,6 +403,7 @@ class _AlbumScreenState extends ConsumerState<AlbumScreen> {
                     imageUrl:
                         _highResCoverUrl(widget.coverUrl) ?? widget.coverUrl!,
                     fit: BoxFit.cover,
+                    memCacheWidth: cacheWidth,
                     cacheManager: CoverCacheManager.instance,
                     placeholder: (_, _) =>
                         Container(color: colorScheme.surface),

lib/screens/artist_screen.dart

@@ -228,7 +228,6 @@ class _ArtistScreenState extends ConsumerState<ArtistScreen> {
   }
 
   void _onScroll() {
-    // Show title when scrolled past the header (280px trigger)
     final shouldShow = _scrollController.offset > 280;
     if (shouldShow != _showTitleInAppBar) {
       setState(() => _showTitleInAppBar = shouldShow);
@@ -2013,7 +2012,6 @@ class _ArtistScreenState extends ConsumerState<ArtistScreen> {
   }
 }
 
-/// Option tile for discography download bottom sheet
 class _DiscographyOptionTile extends StatelessWidget {
   final IconData icon;
   final String title;
@@ -2051,7 +2049,6 @@ class _DiscographyOptionTile extends StatelessWidget {
   }
 }
 
-/// Progress dialog shown while fetching album tracks
 class _FetchingProgressDialog extends StatefulWidget {
   final int totalAlbums;
   final VoidCallback onCancel;

lib/screens/downloaded_album_screen.dart

@@ -11,6 +11,7 @@ import 'package:spotiflac_android/services/platform_bridge.dart';
 import 'package:spotiflac_android/services/history_database.dart';
 import 'package:spotiflac_android/l10n/l10n.dart';
 import 'package:spotiflac_android/utils/file_access.dart';
+import 'package:spotiflac_android/utils/image_cache_utils.dart';
 import 'package:spotiflac_android/utils/lyrics_metadata_helper.dart';
 import 'package:spotiflac_android/providers/download_queue_provider.dart';
 import 'package:spotiflac_android/widgets/batch_progress_dialog.dart';
@@ -95,7 +96,6 @@ class _DownloadedAlbumScreenState extends ConsumerState<DownloadedAlbumScreen> {
     return (mediaSize.height * 0.55).clamp(360.0, 520.0);
   }
 
-  /// Upgrade cover URL to a reasonable resolution for full-screen display.
   String? _highResCoverUrl(String? url) {
     if (url == null) return null;
     if (url.contains('ab67616d00001e02')) {
@@ -111,7 +111,6 @@ class _DownloadedAlbumScreenState extends ConsumerState<DownloadedAlbumScreen> {
     return url;
   }
 
-  /// Get tracks for this album from history provider (reactive)
   List<DownloadHistoryItem> _getAlbumTracks(
     List<DownloadHistoryItem> allItems,
   ) {
@@ -464,6 +463,7 @@ class _DownloadedAlbumScreenState extends ConsumerState<DownloadedAlbumScreen> {
               (constraints.maxHeight - kToolbarHeight) /
               (expandedHeight - kToolbarHeight);
           final showContent = collapseRatio > 0.3;
+          final cacheWidth = coverCacheWidthForViewport(context);
 
           return FlexibleSpaceBar(
             collapseMode: CollapseMode.pin,
@@ -474,6 +474,9 @@ class _DownloadedAlbumScreenState extends ConsumerState<DownloadedAlbumScreen> {
                   Image.file(
                     File(embeddedCoverPath),
                     fit: BoxFit.cover,
+                    cacheWidth: cacheWidth,
+                    gaplessPlayback: true,
+                    filterQuality: FilterQuality.low,
                     errorBuilder: (_, _, _) =>
                         Container(color: colorScheme.surface),
                   )
@@ -482,6 +485,7 @@ class _DownloadedAlbumScreenState extends ConsumerState<DownloadedAlbumScreen> {
                     imageUrl:
                         _highResCoverUrl(widget.coverUrl) ?? widget.coverUrl!,
                     fit: BoxFit.cover,
+                    memCacheWidth: cacheWidth,
                     cacheManager: CoverCacheManager.instance,
                     placeholder: (_, _) =>
                         Container(color: colorScheme.surface),
@@ -641,7 +645,6 @@ class _DownloadedAlbumScreenState extends ConsumerState<DownloadedAlbumScreen> {
     ColorScheme colorScheme,
     List<DownloadHistoryItem> tracks,
   ) {
-    // Info is now displayed in the full-screen cover overlay
     return const SliverToBoxAdapter(child: SizedBox.shrink());
   }
 
@@ -848,7 +851,6 @@ class _DownloadedAlbumScreenState extends ConsumerState<DownloadedAlbumScreen> {
     );
   }
 
-  /// Share selected tracks via system share sheet
   Future<void> _shareSelected(List<DownloadHistoryItem> allTracks) async {
     final tracksById = {for (final t in allTracks) t.id: t};
     final safUris = <String>[];
@@ -1091,7 +1093,6 @@ class _DownloadedAlbumScreenState extends ConsumerState<DownloadedAlbumScreen> {
     for (final id in _selectedIds) {
       final item = tracksById[id];
       if (item == null) continue;
-      // For SAF items, use safFileName to detect format (filePath is content:// URI)
       final nameToCheck =
           (item.safFileName != null && item.safFileName!.isNotEmpty)
           ? item.safFileName!.toLowerCase()
@@ -1235,6 +1236,7 @@ class _DownloadedAlbumScreenState extends ConsumerState<DownloadedAlbumScreen> {
           bitrate: bitrate,
           metadata: metadata,
           coverPath: coverPath,
+          artistTagMode: settings.artistTagMode,
           deleteOriginal: !isSaf,
         );
 

lib/screens/home_tab.dart

@@ -258,6 +258,20 @@ class _HomeTabState extends ConsumerState<HomeTab>
   List<Track>? _searchBucketsSourceTracks;
   _SearchResultBuckets? _searchBucketsCache;
   _SearchSortOption _searchSortOption = _SearchSortOption.defaultOrder;
+  List<SearchArtist>? _sortedArtistsSource;
+  _SearchSortOption? _sortedArtistsMode;
+  List<SearchArtist>? _sortedArtistsCache;
+  List<SearchAlbum>? _sortedAlbumsSource;
+  _SearchSortOption? _sortedAlbumsMode;
+  List<SearchAlbum>? _sortedAlbumsCache;
+  List<SearchPlaylist>? _sortedPlaylistsSource;
+  _SearchSortOption? _sortedPlaylistsMode;
+  List<SearchPlaylist>? _sortedPlaylistsCache;
+  List<Track>? _sortedTracksSource;
+  List<int>? _sortedTrackIndexesSource;
+  _SearchSortOption? _sortedTracksMode;
+  List<Track>? _sortedTracksCache;
+  List<int>? _sortedTrackIndexesCache;
 
   double _responsiveScale({
     required BuildContext context,
@@ -476,6 +490,23 @@ class _HomeTabState extends ConsumerState<HomeTab>
     return buckets;
   }
 
+  void _invalidateSearchSortCaches() {
+    _sortedArtistsSource = null;
+    _sortedArtistsMode = null;
+    _sortedArtistsCache = null;
+    _sortedAlbumsSource = null;
+    _sortedAlbumsMode = null;
+    _sortedAlbumsCache = null;
+    _sortedPlaylistsSource = null;
+    _sortedPlaylistsMode = null;
+    _sortedPlaylistsCache = null;
+    _sortedTracksSource = null;
+    _sortedTrackIndexesSource = null;
+    _sortedTracksMode = null;
+    _sortedTracksCache = null;
+    _sortedTrackIndexesCache = null;
+  }
+
   void _onSearchFocusChanged() {
     if (mounted) {
       setState(() {});
@@ -496,7 +527,6 @@ class _HomeTabState extends ConsumerState<HomeTab>
     }
   }
 
-  /// Check if live search is available (extension is set as search provider)
   bool _isLiveSearchEnabled() {
     final settings = ref.read(settingsProvider);
     final extState = ref.read(extensionProvider);
@@ -564,7 +594,6 @@ class _HomeTabState extends ConsumerState<HomeTab>
     }
   }
 
-  /// Built-in search providers that are not extensions
   static const _builtInSearchProviders = {'tidal', 'qobuz'};
 
   Future<void> _performSearch(String query, {String? filterOverride}) async {
@@ -579,6 +608,7 @@ class _HomeTabState extends ConsumerState<HomeTab>
     if (_lastSearchQuery == searchKey) return;
     _lastSearchQuery = searchKey;
     _searchSortOption = _SearchSortOption.defaultOrder;
+    _invalidateSearchSortCaches();
 
     final isBuiltInProvider =
         searchProvider != null &&
@@ -599,7 +629,6 @@ class _HomeTabState extends ConsumerState<HomeTab>
           .read(trackProvider.notifier)
           .customSearch(searchProvider, query, options: options);
     } else if (isBuiltInProvider) {
-      // Use built-in Tidal or Qobuz search
       await ref
           .read(trackProvider.notifier)
           .search(
@@ -757,7 +786,8 @@ class _HomeTabState extends ConsumerState<HomeTab>
           trackName: track.name,
           artistName: track.artistName,
           coverUrl: track.coverUrl,
-          recommendedService: trackState.searchSource,
+          recommendedService:
+              trackState.searchExtensionId ?? trackState.searchSource,
           onSelect: (quality, service) {
             ref
                 .read(downloadQueueProvider.notifier)
@@ -1121,7 +1151,7 @@ class _HomeTabState extends ConsumerState<HomeTab>
                       title: Text(
                         context.l10n.homeTitle,
                         style: TextStyle(
-                          fontSize: 20 + (14 * expandRatio), // 20 -> 34
+                          fontSize: 20 + (14 * expandRatio),
                           fontWeight: FontWeight.bold,
                           color: colorScheme.onSurface,
                         ),
@@ -1407,10 +1437,6 @@ class _HomeTabState extends ConsumerState<HomeTab>
             itemCount: itemCount,
             itemBuilder: (context, index) {
               final item = items[index];
-              final embeddedCoverPath = DownloadedEmbeddedCoverResolver.resolve(
-                item.filePath,
-                onChanged: _onEmbeddedCoverChanged,
-              );
               return KeyedSubtree(
                 key: ValueKey(item.id),
                 child: Semantics(
@@ -1423,48 +1449,15 @@ class _HomeTabState extends ConsumerState<HomeTab>
                       margin: const EdgeInsets.only(right: 12),
                       child: Column(
                         children: [
-                          ClipRRect(
+                          _DownloadedOrRemoteCover(
+                            downloadedFilePath: item.filePath,
+                            imageUrl: item.coverUrl,
+                            width: coverSize,
+                            height: coverSize,
                             borderRadius: BorderRadius.circular(12),
-                            child: embeddedCoverPath != null
-                                ? Image.file(
-                                    File(embeddedCoverPath),
-                                    width: coverSize,
-                                    height: coverSize,
-                                    fit: BoxFit.cover,
-                                    cacheWidth: (coverSize * 2).round(),
-                                    cacheHeight: (coverSize * 2).round(),
-                                    errorBuilder: (_, _, _) => Container(
-                                      width: coverSize,
-                                      height: coverSize,
-                                      color:
-                                          colorScheme.surfaceContainerHighest,
-                                      child: Icon(
-                                        Icons.music_note,
-                                        color: colorScheme.onSurfaceVariant,
-                                        size: 32,
-                                      ),
-                                    ),
-                                  )
-                                : item.coverUrl != null
-                                ? CachedNetworkImage(
-                                    imageUrl: item.coverUrl!,
-                                    width: coverSize,
-                                    height: coverSize,
-                                    fit: BoxFit.cover,
-                                    memCacheWidth: (coverSize * 2).round(),
-                                    memCacheHeight: (coverSize * 2).round(),
-                                    cacheManager: CoverCacheManager.instance,
-                                  )
-                                : Container(
-                                    width: coverSize,
-                                    height: coverSize,
-                                    color: colorScheme.surfaceContainerHighest,
-                                    child: Icon(
-                                      Icons.music_note,
-                                      color: colorScheme.onSurfaceVariant,
-                                      size: 32,
-                                    ),
-                                  ),
+                            fallbackIcon: Icons.music_note,
+                            fallbackIconSize: 32,
+                            colorScheme: colorScheme,
                           ),
                           const SizedBox(height: 6),
                           Text(
@@ -1495,7 +1488,7 @@ class _HomeTabState extends ConsumerState<HomeTab>
   ) {
     final hasGreeting = greeting != null && greeting.isNotEmpty;
     final sectionOffset = hasGreeting ? 1 : 0;
-    final totalCount = sections.length + sectionOffset + 1; // + bottom padding
+    final totalCount = sections.length + sectionOffset + 1;
 
     return [
       SliverList(
@@ -1845,10 +1838,10 @@ class _HomeTabState extends ConsumerState<HomeTab>
       albumName: item.albumName ?? '',
       albumId: item.albumId,
       duration: item.durationMs ~/ 1000,
-      trackNumber: 1,
-      discNumber: 1,
+      trackNumber: null,
+      discNumber: null,
       isrc: null,
-      releaseDate: null,
+      releaseDate: item.releaseDate,
       coverUrl: item.coverUrl,
       source: item.providerId ?? 'spotify-web',
     );
@@ -1997,12 +1990,6 @@ class _HomeTabState extends ConsumerState<HomeTab>
     IconData typeIcon;
     String typeLabel;
     final isDownloaded = item.providerId == 'download';
-    final embeddedCoverPath = isDownloaded
-        ? DownloadedEmbeddedCoverResolver.resolve(
-            downloadFilePathByRecentKey['${item.type.name}:${item.id}'],
-            onChanged: _onEmbeddedCoverChanged,
-          )
-        : null;
 
     switch (item.type) {
       case RecentAccessType.artist:
@@ -2028,55 +2015,18 @@ class _HomeTabState extends ConsumerState<HomeTab>
           padding: const EdgeInsets.symmetric(horizontal: 4, vertical: 8),
           child: Row(
             children: [
-              ClipRRect(
+              _DownloadedOrRemoteCover(
+                downloadedFilePath: isDownloaded
+                    ? downloadFilePathByRecentKey['${item.type.name}:${item.id}']
+                    : null,
+                imageUrl: item.imageUrl,
+                width: 56,
+                height: 56,
                 borderRadius: BorderRadius.circular(
                   item.type == RecentAccessType.artist ? 28 : 4,
                 ),
-                child: embeddedCoverPath != null
-                    ? Image.file(
-                        File(embeddedCoverPath),
-                        width: 56,
-                        height: 56,
-                        fit: BoxFit.cover,
-                        cacheWidth: 112,
-                        cacheHeight: 112,
-                        errorBuilder: (context, error, stackTrace) => Container(
-                          width: 56,
-                          height: 56,
-                          color: colorScheme.surfaceContainerHighest,
-                          child: Icon(
-                            typeIcon,
-                            color: colorScheme.onSurfaceVariant,
-                          ),
-                        ),
-                      )
-                    : item.imageUrl != null && item.imageUrl!.isNotEmpty
-                    ? CachedNetworkImage(
-                        imageUrl: item.imageUrl!,
-                        width: 56,
-                        height: 56,
-                        fit: BoxFit.cover,
-                        memCacheWidth: 112,
-                        cacheManager: CoverCacheManager.instance,
-                        errorWidget: (context, url, error) => Container(
-                          width: 56,
-                          height: 56,
-                          color: colorScheme.surfaceContainerHighest,
-                          child: Icon(
-                            typeIcon,
-                            color: colorScheme.onSurfaceVariant,
-                          ),
-                        ),
-                      )
-                    : Container(
-                        width: 56,
-                        height: 56,
-                        color: colorScheme.surfaceContainerHighest,
-                        child: Icon(
-                          typeIcon,
-                          color: colorScheme.onSurfaceVariant,
-                        ),
-                      ),
+                fallbackIcon: typeIcon,
+                colorScheme: colorScheme,
               ),
               const SizedBox(width: 12),
               Expanded(
@@ -2412,8 +2362,6 @@ class _HomeTabState extends ConsumerState<HomeTab>
     );
   }
 
-  // ── Search result sorting ──────────────────────────────────────────────
-
   String _sortOptionLabel(_SearchSortOption option) {
     switch (option) {
       case _SearchSortOption.defaultOrder:
@@ -2574,6 +2522,114 @@ class _HomeTabState extends ConsumerState<HomeTab>
     return sorted;
   }
 
+  List<SearchArtist>? _sortSearchArtists(List<SearchArtist>? artists) {
+    if (artists == null ||
+        artists.isEmpty ||
+        _searchSortOption == _SearchSortOption.defaultOrder) {
+      return artists;
+    }
+    if (identical(artists, _sortedArtistsSource) &&
+        _sortedArtistsMode == _searchSortOption &&
+        _sortedArtistsCache != null) {
+      return _sortedArtistsCache;
+    }
+    final sorted = _applySortToList<SearchArtist>(
+      artists,
+      (a) => a.name,
+      (a) => a.name,
+      (a) => 0,
+      (a) => null,
+    );
+    _sortedArtistsSource = artists;
+    _sortedArtistsMode = _searchSortOption;
+    _sortedArtistsCache = sorted;
+    return sorted;
+  }
+
+  List<SearchAlbum>? _sortSearchAlbums(List<SearchAlbum>? albums) {
+    if (albums == null ||
+        albums.isEmpty ||
+        _searchSortOption == _SearchSortOption.defaultOrder) {
+      return albums;
+    }
+    if (identical(albums, _sortedAlbumsSource) &&
+        _sortedAlbumsMode == _searchSortOption &&
+        _sortedAlbumsCache != null) {
+      return _sortedAlbumsCache;
+    }
+    final sorted = _applySortToList<SearchAlbum>(
+      albums,
+      (a) => a.name,
+      (a) => a.artists,
+      (a) => 0,
+      (a) => a.releaseDate,
+    );
+    _sortedAlbumsSource = albums;
+    _sortedAlbumsMode = _searchSortOption;
+    _sortedAlbumsCache = sorted;
+    return sorted;
+  }
+
+  List<SearchPlaylist>? _sortSearchPlaylists(List<SearchPlaylist>? playlists) {
+    if (playlists == null ||
+        playlists.isEmpty ||
+        _searchSortOption == _SearchSortOption.defaultOrder) {
+      return playlists;
+    }
+    if (identical(playlists, _sortedPlaylistsSource) &&
+        _sortedPlaylistsMode == _searchSortOption &&
+        _sortedPlaylistsCache != null) {
+      return _sortedPlaylistsCache;
+    }
+    final sorted = _applySortToList<SearchPlaylist>(
+      playlists,
+      (p) => p.name,
+      (p) => p.owner,
+      (p) => 0,
+      (p) => null,
+    );
+    _sortedPlaylistsSource = playlists;
+    _sortedPlaylistsMode = _searchSortOption;
+    _sortedPlaylistsCache = sorted;
+    return sorted;
+  }
+
+  ({List<Track> tracks, List<int> indexes}) _sortTrackResults(
+    List<Track> tracks,
+    List<int> indexes,
+  ) {
+    if (tracks.isEmpty || _searchSortOption == _SearchSortOption.defaultOrder) {
+      return (tracks: tracks, indexes: indexes);
+    }
+    if (identical(tracks, _sortedTracksSource) &&
+        identical(indexes, _sortedTrackIndexesSource) &&
+        _sortedTracksMode == _searchSortOption &&
+        _sortedTracksCache != null &&
+        _sortedTrackIndexesCache != null) {
+      return (tracks: _sortedTracksCache!, indexes: _sortedTrackIndexesCache!);
+    }
+    final paired = List.generate(
+      tracks.length,
+      (i) => (tracks[i], indexes[i]),
+      growable: false,
+    );
+    final sortedPairs = _applySortToList<(Track, int)>(
+      paired,
+      (p) => p.$1.name,
+      (p) => p.$1.artistName,
+      (p) => p.$1.duration,
+      (p) => p.$1.releaseDate,
+    );
+    final sortedTracks = sortedPairs.map((p) => p.$1).toList(growable: false);
+    final sortedIndexes = sortedPairs.map((p) => p.$2).toList(growable: false);
+    _sortedTracksSource = tracks;
+    _sortedTrackIndexesSource = indexes;
+    _sortedTracksMode = _searchSortOption;
+    _sortedTracksCache = sortedTracks;
+    _sortedTrackIndexesCache = sortedIndexes;
+    return (tracks: sortedTracks, indexes: sortedIndexes);
+  }
+
   List<Widget> _buildSearchResults({
     required List<Track> tracks,
     required List<SearchArtist>? searchArtists,
@@ -2607,58 +2663,12 @@ class _HomeTabState extends ConsumerState<HomeTab>
     final playlistItems = buckets.playlistItems;
     final artistItems = buckets.artistItems;
 
-    final sortedArtists = searchArtists != null && searchArtists.isNotEmpty
-        ? _applySortToList<SearchArtist>(
-            searchArtists,
-            (a) => a.name,
-            (a) => a.name,
-            (a) => 0,
-            (a) => null,
-          )
-        : searchArtists;
-
-    final sortedAlbums = searchAlbums != null && searchAlbums.isNotEmpty
-        ? _applySortToList<SearchAlbum>(
-            searchAlbums,
-            (a) => a.name,
-            (a) => a.artists,
-            (a) => 0,
-            (a) => a.releaseDate,
-          )
-        : searchAlbums;
-
-    final sortedPlaylists =
-        searchPlaylists != null && searchPlaylists.isNotEmpty
-        ? _applySortToList<SearchPlaylist>(
-            searchPlaylists,
-            (p) => p.name,
-            (p) => p.owner,
-            (p) => 0,
-            (p) => null,
-          )
-        : searchPlaylists;
-
-    List<Track> sortedTracks;
-    List<int> sortedTrackIndexes;
-    if (realTracks.isNotEmpty &&
-        _searchSortOption != _SearchSortOption.defaultOrder) {
-      final paired = List.generate(
-        realTracks.length,
-        (i) => (realTracks[i], realTrackIndexes[i]),
-      );
-      final sortedPairs = _applySortToList<(Track, int)>(
-        paired,
-        (p) => p.$1.name,
-        (p) => p.$1.artistName,
-        (p) => p.$1.duration,
-        (p) => p.$1.releaseDate,
-      );
-      sortedTracks = sortedPairs.map((p) => p.$1).toList();
-      sortedTrackIndexes = sortedPairs.map((p) => p.$2).toList();
-    } else {
-      sortedTracks = realTracks;
-      sortedTrackIndexes = realTrackIndexes;
-    }
+    final sortedArtists = _sortSearchArtists(searchArtists);
+    final sortedAlbums = _sortSearchAlbums(searchAlbums);
+    final sortedPlaylists = _sortSearchPlaylists(searchPlaylists);
+    final sortedTrackResults = _sortTrackResults(realTracks, realTrackIndexes);
+    final sortedTracks = sortedTrackResults.tracks;
+    final sortedTrackIndexes = sortedTrackResults.indexes;
 
     final slivers = <Widget>[
       if (error != null)
@@ -2940,7 +2950,7 @@ class _HomeTabState extends ConsumerState<HomeTab>
           albumId: album.id,
           albumName: album.name,
           coverUrl: album.imageUrl,
-          tracks: const [], // Will be fetched by AlbumScreen
+          tracks: const [],
         ),
       ),
     );
@@ -2966,7 +2976,7 @@ class _HomeTabState extends ConsumerState<HomeTab>
         builder: (context) => PlaylistScreen(
           playlistName: playlist.name,
           coverUrl: playlist.imageUrl,
-          tracks: const [], // Will be fetched
+          tracks: const [],
           playlistId: playlist.id,
         ),
       ),
@@ -3693,9 +3703,7 @@ class _TrackItemWithStatus extends ConsumerWidget {
           Divider(
             height: 1,
             thickness: 1,
-            indent:
-                thumbWidth +
-                24, // Adjust divider indent based on thumbnail width
+            indent: thumbWidth + 24,
             endIndent: 12,
             color: colorScheme.outlineVariant.withValues(alpha: 0.3),
           ),
@@ -4165,6 +4173,126 @@ class _SearchPlaylistItemWidget extends StatelessWidget {
   }
 }
 
+class _DownloadedOrRemoteCover extends StatefulWidget {
+  final String? downloadedFilePath;
+  final String? imageUrl;
+  final double width;
+  final double height;
+  final BorderRadius borderRadius;
+  final IconData fallbackIcon;
+  final double fallbackIconSize;
+  final ColorScheme colorScheme;
+
+  const _DownloadedOrRemoteCover({
+    required this.downloadedFilePath,
+    required this.imageUrl,
+    required this.width,
+    required this.height,
+    required this.borderRadius,
+    required this.fallbackIcon,
+    required this.colorScheme,
+    this.fallbackIconSize = 24,
+  });
+
+  @override
+  State<_DownloadedOrRemoteCover> createState() =>
+      _DownloadedOrRemoteCoverState();
+}
+
+class _DownloadedOrRemoteCoverState extends State<_DownloadedOrRemoteCover> {
+  String? _embeddedCoverPath;
+  bool _refreshScheduled = false;
+
+  @override
+  void initState() {
+    super.initState();
+    _embeddedCoverPath = _resolveEmbeddedCoverPath();
+  }
+
+  @override
+  void didUpdateWidget(covariant _DownloadedOrRemoteCover oldWidget) {
+    super.didUpdateWidget(oldWidget);
+    if (oldWidget.downloadedFilePath != widget.downloadedFilePath ||
+        oldWidget.imageUrl != widget.imageUrl) {
+      final nextPath = _resolveEmbeddedCoverPath();
+      if (nextPath != _embeddedCoverPath) {
+        setState(() => _embeddedCoverPath = nextPath);
+      }
+    }
+  }
+
+  String? _resolveEmbeddedCoverPath() {
+    final filePath = widget.downloadedFilePath;
+    if (filePath == null || filePath.isEmpty) return null;
+    return DownloadedEmbeddedCoverResolver.resolve(
+      filePath,
+      onChanged: _onEmbeddedCoverChanged,
+    );
+  }
+
+  void _onEmbeddedCoverChanged() {
+    if (!mounted || _refreshScheduled) return;
+    _refreshScheduled = true;
+    WidgetsBinding.instance.addPostFrameCallback((_) {
+      _refreshScheduled = false;
+      if (!mounted) return;
+      final nextPath = _resolveEmbeddedCoverPath();
+      if (nextPath != _embeddedCoverPath) {
+        setState(() => _embeddedCoverPath = nextPath);
+      }
+    });
+  }
+
+  Widget _fallback() {
+    return Container(
+      width: widget.width,
+      height: widget.height,
+      color: widget.colorScheme.surfaceContainerHighest,
+      child: Icon(
+        widget.fallbackIcon,
+        color: widget.colorScheme.onSurfaceVariant,
+        size: widget.fallbackIconSize,
+      ),
+    );
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    final cacheWidth = (widget.width * 2).round();
+    final cacheHeight = (widget.height * 2).round();
+
+    Widget child;
+    if (_embeddedCoverPath != null) {
+      child = Image.file(
+        File(_embeddedCoverPath!),
+        width: widget.width,
+        height: widget.height,
+        fit: BoxFit.cover,
+        cacheWidth: cacheWidth,
+        cacheHeight: cacheHeight,
+        gaplessPlayback: true,
+        filterQuality: FilterQuality.low,
+        errorBuilder: (_, _, _) => _fallback(),
+      );
+    } else if (widget.imageUrl != null && widget.imageUrl!.isNotEmpty) {
+      child = CachedNetworkImage(
+        imageUrl: widget.imageUrl!,
+        width: widget.width,
+        height: widget.height,
+        fit: BoxFit.cover,
+        memCacheWidth: cacheWidth,
+        memCacheHeight: cacheHeight,
+        cacheManager: CoverCacheManager.instance,
+        errorWidget: (_, _, _) => _fallback(),
+      );
+    } else {
+      child = _fallback();
+    }
+
+    return ClipRRect(borderRadius: widget.borderRadius, child: child);
+  }
+}
+
 class ExtensionAlbumScreen extends ConsumerStatefulWidget {
   final String extensionId;
   final String albumId;
@@ -4274,6 +4402,8 @@ class _ExtensionAlbumScreenState extends ConsumerState<ExtensionAlbumScreen> {
       isrc: data['isrc']?.toString(),
       duration: (durationMs / 1000).round(),
       trackNumber: data['track_number'] as int?,
+      discNumber: data['disc_number'] as int?,
+      releaseDate: data['release_date']?.toString(),
       source: widget.extensionId,
     );
   }
@@ -4431,6 +4561,8 @@ class _ExtensionPlaylistScreenState
       isrc: data['isrc']?.toString(),
       duration: (durationMs / 1000).round(),
       trackNumber: data['track_number'] as int?,
+      discNumber: data['disc_number'] as int?,
+      releaseDate: data['release_date']?.toString(),
       source: widget.extensionId,
     );
   }

lib/screens/library_tracks_folder_screen.dart

@@ -16,7 +16,6 @@ import 'package:spotiflac_android/providers/settings_provider.dart';
 import 'package:spotiflac_android/services/cover_cache_manager.dart';
 import 'package:spotiflac_android/screens/track_metadata_screen.dart';
 import 'package:spotiflac_android/widgets/download_service_picker.dart';
-import 'package:spotiflac_android/widgets/bottom_sheet_option_tile.dart';
 import 'package:spotiflac_android/widgets/playlist_picker_sheet.dart';
 import 'package:spotiflac_android/widgets/animation_utils.dart';
 
@@ -598,7 +597,6 @@ class _LibraryTracksFolderScreenState
     final customCoverPath = playlist?.coverImagePath;
     final isLovedMode = widget.mode == LibraryTracksFolderMode.loved;
     final isPlaylistMode = widget.mode == LibraryTracksFolderMode.playlist;
-    // Loved always shows the heart icon (like Spotify's Liked Songs)
     final coverUrl = isLovedMode ? null : _firstCoverUrl(entries, localState);
     final hasCustomCover =
         customCoverPath != null && customCoverPath.isNotEmpty;
@@ -668,7 +666,6 @@ class _LibraryTracksFolderScreenState
             background: Stack(
               fit: StackFit.expand,
               children: [
-                // Cover background: custom > first track URL > icon
                 if (hasCustomCover)
                   Image.file(
                     File(customCoverPath),
@@ -1238,23 +1235,19 @@ class _CollectionTrackTile extends ConsumerWidget {
           trailing: isSelectionMode
               ? null
               : historyItem != null || localItem != null
-                  ? IconButton(
-                      tooltip: context.l10n.tooltipPlay,
-                      onPressed: () {
-                        ref
-                            .read(playbackProvider.notifier)
-                            .playTrackList([track]);
-                      },
-                      icon: Icon(
-                        Icons.play_arrow,
-                        color: colorScheme.primary,
-                      ),
-                      style: IconButton.styleFrom(
-                        backgroundColor: colorScheme.primaryContainer
-                            .withValues(alpha: 0.3),
-                      ),
-                    )
-                  : null,
+              ? IconButton(
+                  tooltip: context.l10n.tooltipPlay,
+                  onPressed: () {
+                    ref.read(playbackProvider.notifier).playTrackList([track]);
+                  },
+                  icon: Icon(Icons.play_arrow, color: colorScheme.primary),
+                  style: IconButton.styleFrom(
+                    backgroundColor: colorScheme.primaryContainer.withValues(
+                      alpha: 0.3,
+                    ),
+                  ),
+                )
+              : null,
           onTap: isSelectionMode
               ? onTap
               : () {
@@ -1333,155 +1326,6 @@ class _CollectionTrackTile extends ConsumerWidget {
     );
   }
 
-  void _showTrackOptionsSheet(BuildContext context, WidgetRef ref) {
-    final track = entry.track;
-    final effectiveCoverUrl = _resolveCoverUrl(track);
-    final colorScheme = Theme.of(context).colorScheme;
-    final historyState = ref.read(downloadHistoryProvider);
-    final isDownloaded =
-        historyState.isDownloaded(track.id) ||
-        (track.isrc != null &&
-            track.isrc!.isNotEmpty &&
-            historyState.getByIsrc(track.isrc!) != null) ||
-        historyState.findByTrackAndArtist(track.name, track.artistName) != null;
-    // Wishlist: only show "Add to Playlist" if track is already downloaded
-    final showAddToPlaylist =
-        mode != LibraryTracksFolderMode.wishlist || isDownloaded;
-
-    showModalBottomSheet<void>(
-      context: context,
-      useRootNavigator: true,
-      backgroundColor: colorScheme.surfaceContainerHigh,
-      shape: const RoundedRectangleBorder(
-        borderRadius: BorderRadius.vertical(top: Radius.circular(28)),
-      ),
-      builder: (sheetContext) => SafeArea(
-        child: Column(
-          mainAxisSize: MainAxisSize.min,
-          children: [
-            Column(
-              children: [
-                const SizedBox(height: 8),
-                Container(
-                  width: 40,
-                  height: 4,
-                  decoration: BoxDecoration(
-                    color: colorScheme.onSurfaceVariant.withValues(alpha: 0.4),
-                    borderRadius: BorderRadius.circular(2),
-                  ),
-                ),
-                Padding(
-                  padding: const EdgeInsets.fromLTRB(16, 12, 16, 12),
-                  child: Row(
-                    children: [
-                      ClipRRect(
-                        borderRadius: BorderRadius.circular(8),
-                        child:
-                            effectiveCoverUrl != null &&
-                                effectiveCoverUrl.isNotEmpty
-                            ? _buildTrackCover(context, effectiveCoverUrl, 56)
-                            : Container(
-                                width: 56,
-                                height: 56,
-                                color: colorScheme.surfaceContainerHighest,
-                                child: Icon(
-                                  Icons.music_note,
-                                  color: colorScheme.onSurfaceVariant,
-                                ),
-                              ),
-                      ),
-                      const SizedBox(width: 12),
-                      Expanded(
-                        child: Column(
-                          crossAxisAlignment: CrossAxisAlignment.start,
-                          children: [
-                            Text(
-                              track.name,
-                              style: Theme.of(context).textTheme.titleMedium
-                                  ?.copyWith(fontWeight: FontWeight.w600),
-                              maxLines: 1,
-                              overflow: TextOverflow.ellipsis,
-                            ),
-                            const SizedBox(height: 2),
-                            Text(
-                              track.artistName,
-                              style: Theme.of(context).textTheme.bodyMedium
-                                  ?.copyWith(
-                                    color: colorScheme.onSurfaceVariant,
-                                  ),
-                              maxLines: 1,
-                              overflow: TextOverflow.ellipsis,
-                            ),
-                          ],
-                        ),
-                      ),
-                    ],
-                  ),
-                ),
-              ],
-            ),
-            Divider(
-              height: 1,
-              color: colorScheme.outlineVariant.withValues(alpha: 0.5),
-            ),
-
-            if (showAddToPlaylist)
-              BottomSheetOptionTile(
-                icon: Icons.playlist_add,
-                title: context.l10n.collectionAddToPlaylist,
-                onTap: () {
-                  Navigator.pop(sheetContext);
-                  showAddTrackToPlaylistSheet(context, ref, track);
-                },
-              ),
-
-            BottomSheetOptionTile(
-              icon: Icons.remove_circle_outline,
-              iconColor: colorScheme.error,
-              title: mode == LibraryTracksFolderMode.playlist
-                  ? context.l10n.collectionRemoveFromPlaylist
-                  : context.l10n.collectionRemoveFromFolder,
-              onTap: () {
-                Navigator.pop(sheetContext);
-                _removeFromCurrentFolder(context, ref);
-              },
-            ),
-
-            const SizedBox(height: 16),
-          ],
-        ),
-      ),
-    );
-  }
-
-  Future<void> _removeFromCurrentFolder(
-    BuildContext context,
-    WidgetRef ref,
-  ) async {
-    final notifier = ref.read(libraryCollectionsProvider.notifier);
-    final key = entry.key;
-
-    switch (mode) {
-      case LibraryTracksFolderMode.wishlist:
-        await notifier.removeFromWishlist(key);
-        break;
-      case LibraryTracksFolderMode.loved:
-        await notifier.removeFromLoved(key);
-        break;
-      case LibraryTracksFolderMode.playlist:
-        if (playlistId != null) {
-          await notifier.removeTrackFromPlaylist(playlistId!, key);
-        }
-        break;
-    }
-
-    if (!context.mounted) return;
-
-    ScaffoldMessenger.of(context).showSnackBar(
-      SnackBar(content: Text(context.l10n.collectionRemoved(entry.track.name))),
-    );
-  }
-
   void _downloadTrack(BuildContext context, WidgetRef ref) {
     final track = entry.track;
     final settings = ref.read(settingsProvider);
@@ -1518,15 +1362,12 @@ class _CollectionTrackTile extends ConsumerWidget {
     final track = entry.track;
     final historyState = ref.read(downloadHistoryProvider);
 
-    // 1. Download history by Spotify ID
     var historyItem = historyState.getBySpotifyId(track.id);
 
-    // 2. Download history by ISRC
     if (historyItem == null && track.isrc != null && track.isrc!.isNotEmpty) {
       historyItem = historyState.getByIsrc(track.isrc!);
     }
 
-    // 3. Download history by track name + artist (handles ID/ISRC mismatch)
     historyItem ??= historyState.findByTrackAndArtist(
       track.name,
       track.artistName,
@@ -1539,14 +1380,12 @@ class _CollectionTrackTile extends ConsumerWidget {
       return;
     }
 
-    // 4. Local library by ISRC
     final localState = ref.read(localLibraryProvider);
     LocalLibraryItem? localItem;
     if (track.isrc != null && track.isrc!.isNotEmpty) {
       localItem = localState.getByIsrc(track.isrc!);
     }
 
-    // 5. Local library by track name + artist
     localItem ??= localState.findByTrackAndArtist(track.name, track.artistName);
 
     if (localItem != null) {
@@ -1556,7 +1395,6 @@ class _CollectionTrackTile extends ConsumerWidget {
       return;
     }
 
-    // 6. Not found anywhere — offer to download
     _downloadTrack(context, ref);
   }
 }

lib/screens/local_album_screen.dart

@@ -9,11 +9,13 @@ import 'package:spotiflac_android/providers/download_queue_provider.dart';
 import 'package:spotiflac_android/providers/extension_provider.dart';
 import 'package:spotiflac_android/providers/settings_provider.dart';
 import 'package:spotiflac_android/utils/file_access.dart';
+import 'package:spotiflac_android/utils/image_cache_utils.dart';
 import 'package:spotiflac_android/utils/lyrics_metadata_helper.dart';
 import 'package:spotiflac_android/services/library_database.dart';
 import 'package:spotiflac_android/services/ffmpeg_service.dart';
 import 'package:spotiflac_android/services/local_track_redownload_service.dart';
 import 'package:spotiflac_android/widgets/batch_progress_dialog.dart';
+import 'package:spotiflac_android/widgets/re_enrich_field_dialog.dart';
 import 'package:spotiflac_android/services/platform_bridge.dart';
 import 'package:spotiflac_android/providers/local_library_provider.dart';
 import 'package:spotiflac_android/providers/playback_provider.dart';
@@ -335,6 +337,7 @@ class _LocalAlbumScreenState extends ConsumerState<LocalAlbumScreen> {
               (constraints.maxHeight - kToolbarHeight) /
               (expandedHeight - kToolbarHeight);
           final showContent = collapseRatio > 0.3;
+          final cacheWidth = coverCacheWidthForViewport(context);
 
           return FlexibleSpaceBar(
             collapseMode: CollapseMode.pin,
@@ -345,6 +348,9 @@ class _LocalAlbumScreenState extends ConsumerState<LocalAlbumScreen> {
                   Image.file(
                     File(widget.coverPath!),
                     fit: BoxFit.cover,
+                    cacheWidth: cacheWidth,
+                    gaplessPlayback: true,
+                    filterQuality: FilterQuality.low,
                     errorBuilder: (_, _, _) =>
                         Container(color: colorScheme.surface),
                   )
@@ -525,7 +531,6 @@ class _LocalAlbumScreenState extends ConsumerState<LocalAlbumScreen> {
     ColorScheme colorScheme,
     List<LocalLibraryItem> tracks,
   ) {
-    // Info is now displayed in the full-screen cover overlay
     return const SliverToBoxAdapter(child: SizedBox.shrink());
   }
 
@@ -817,24 +822,29 @@ class _LocalAlbumScreenState extends ConsumerState<LocalAlbumScreen> {
         lowerPath.endsWith('.opus') ||
         lowerPath.endsWith('.ogg');
 
+    final artistTagMode = ref.read(settingsProvider).artistTagMode;
     String? ffmpegResult;
     if (isMp3) {
       ffmpegResult = await FFmpegService.embedMetadataToMp3(
         mp3Path: ffmpegTarget,
         coverPath: effectiveCoverPath,
         metadata: metadata,
+        preserveMetadata: true,
       );
     } else if (isM4A) {
       ffmpegResult = await FFmpegService.embedMetadataToM4a(
         m4aPath: ffmpegTarget,
         coverPath: effectiveCoverPath,
         metadata: metadata,
+        preserveMetadata: true,
       );
     } else if (isOpus) {
       ffmpegResult = await FFmpegService.embedMetadataToOpus(
         opusPath: ffmpegTarget,
         coverPath: effectiveCoverPath,
         metadata: metadata,
+        artistTagMode: artistTagMode,
+        preserveMetadata: true,
       );
     }
 
@@ -865,13 +875,18 @@ class _LocalAlbumScreenState extends ConsumerState<LocalAlbumScreen> {
     return ffmpegResult != null;
   }
 
-  Future<bool> _reEnrichLocalTrack(LocalLibraryItem item) async {
+  Future<bool> _reEnrichLocalTrack(
+    LocalLibraryItem item, {
+    List<String>? updateFields,
+  }) async {
     final durationMs = (item.duration ?? 0) * 1000;
+    final artistTagMode = ref.read(settingsProvider).artistTagMode;
     final request = <String, dynamic>{
       'file_path': item.filePath,
       'cover_url': '',
       'max_quality': true,
       'embed_lyrics': true,
+      'artist_tag_mode': artistTagMode,
       'spotify_id': '',
       'track_name': item.trackName,
       'artist_name': item.artistName,
@@ -886,6 +901,8 @@ class _LocalAlbumScreenState extends ConsumerState<LocalAlbumScreen> {
       'copyright': '',
       'duration_ms': durationMs,
       'search_online': true,
+      // ignore: use_null_aware_elements
+      if (updateFields != null) 'update_fields': updateFields,
     };
 
     final result = await PlatformBridge.reEnrichFile(request);
@@ -1044,31 +1061,24 @@ class _LocalAlbumScreenState extends ConsumerState<LocalAlbumScreen> {
       return;
     }
 
-    final confirmed = await showDialog<bool>(
-      context: context,
-      builder: (ctx) => AlertDialog(
-        title: Text(context.l10n.trackReEnrich),
-        content: Text(
-          '${context.l10n.trackReEnrichOnlineSubtitle}\n\n'
-          '${context.l10n.downloadedAlbumSelectedCount(selected.length)}',
-        ),
-        actions: [
-          TextButton(
-            onPressed: () => Navigator.pop(ctx, false),
-            child: Text(context.l10n.dialogCancel),
-          ),
-          FilledButton(
-            onPressed: () => Navigator.pop(ctx, true),
-            child: Text(context.l10n.trackReEnrich),
-          ),
-        ],
-      ),
+    // The bar uses AnimatedPositioned (250ms), so wait for the slide-out.
+    setState(() => _isSelectionMode = false);
+    await Future<void>.delayed(const Duration(milliseconds: 300));
+    if (!mounted) return;
+
+    final selection = await showReEnrichFieldDialog(
+      context,
+      selectedCount: selected.length,
     );
 
-    if (confirmed != true || !mounted) {
+    if (selection == null || !mounted) {
+      // Cancelled — restore selection mode (IDs are still intact).
+      if (mounted) setState(() => _isSelectionMode = true);
       return;
     }
 
+    final updateFields = selection.isAll ? null : selection.fields;
+
     var successCount = 0;
     final total = selected.length;
 
@@ -1094,7 +1104,7 @@ class _LocalAlbumScreenState extends ConsumerState<LocalAlbumScreen> {
       );
 
       try {
-        final ok = await _reEnrichLocalTrack(item);
+        final ok = await _reEnrichLocalTrack(item, updateFields: updateFields);
         if (ok) {
           successCount++;
         }
@@ -1510,6 +1520,7 @@ class _LocalAlbumScreenState extends ConsumerState<LocalAlbumScreen> {
           bitrate: bitrate,
           metadata: metadata,
           coverPath: coverPath,
+          artistTagMode: settings.artistTagMode,
           deleteOriginal: !isSaf,
         );
 

lib/screens/main_shell.dart

@@ -329,6 +329,8 @@ class _MainShellState extends ConsumerState<MainShell>
       return;
     }
 
+    if (!mounted) return;
+
     final trackState = ref.read(trackProvider);
 
     final isKeyboardVisible = MediaQuery.of(context).viewInsets.bottom > 0;
@@ -346,7 +348,6 @@ class _MainShellState extends ConsumerState<MainShell>
         trackState.isShowingRecentAccess &&
         !trackState.isLoading &&
         (trackState.hasSearchText || trackState.hasContent)) {
-      // Has recent access AND search content — clear everything at once
       _log.i(
         'Back: step 3a - dismiss recent access + clear search/content '
         '(hasSearchText=${trackState.hasSearchText}, hasContent=${trackState.hasContent})',
@@ -358,7 +359,6 @@ class _MainShellState extends ConsumerState<MainShell>
     }
 
     if (_currentIndex == 0 && trackState.isShowingRecentAccess) {
-      // Recent access overlay only (no search content) — just dismiss it
       _log.i('Back: step 3b - dismiss recent access only');
       ref.read(trackProvider.notifier).setShowingRecentAccess(false);
       FocusManager.instance.primaryFocus?.unfocus();

lib/screens/playlist_screen.dart

@@ -8,6 +8,7 @@ import 'package:spotiflac_android/models/track.dart';
 import 'package:spotiflac_android/providers/download_queue_provider.dart';
 import 'package:spotiflac_android/providers/library_collections_provider.dart';
 import 'package:spotiflac_android/utils/file_access.dart';
+import 'package:spotiflac_android/utils/image_cache_utils.dart';
 import 'package:spotiflac_android/utils/string_utils.dart';
 import 'package:spotiflac_android/providers/settings_provider.dart';
 import 'package:spotiflac_android/providers/local_library_provider.dart';
@@ -117,7 +118,6 @@ class _PlaylistScreenState extends ConsumerState<PlaylistScreen> {
       final playlistInfo = result['playlist_info'] as Map<String, dynamic>?;
       final owner = playlistInfo?['owner'] as Map<String, dynamic>?;
 
-      // Go backend returns 'track_list' not 'tracks'
       final trackList = result['track_list'] as List<dynamic>? ?? [];
       final tracks = trackList
           .map((t) => _parseTrack(t as Map<String, dynamic>))
@@ -182,14 +182,11 @@ class _PlaylistScreenState extends ConsumerState<PlaylistScreen> {
     return (mediaSize.height * 0.55).clamp(360.0, 520.0);
   }
 
-  /// Upgrade cover URL to a reasonable resolution for full-screen display.
   String? _highResCoverUrl(String? url) {
     if (url == null) return null;
-    // Spotify CDN: upgrade 300 → 640 only
     if (url.contains('ab67616d00001e02')) {
       return url.replaceAll('ab67616d00001e02', 'ab67616d0000b273');
     }
-    // Deezer CDN: upgrade to 1000x1000
     final deezerRegex = RegExp(r'/(\d+)x(\d+)-(\d+)-(\d+)-(\d+)-(\d+)\.jpg$');
     if (url.contains('cdn-images.dzcdn.net') && deezerRegex.hasMatch(url)) {
       return url.replaceAllMapped(
@@ -246,6 +243,7 @@ class _PlaylistScreenState extends ConsumerState<PlaylistScreen> {
               (constraints.maxHeight - kToolbarHeight) /
               (expandedHeight - kToolbarHeight);
           final showContent = collapseRatio > 0.3;
+          final cacheWidth = coverCacheWidthForViewport(context);
 
           return FlexibleSpaceBar(
             collapseMode: CollapseMode.pin,
@@ -256,6 +254,7 @@ class _PlaylistScreenState extends ConsumerState<PlaylistScreen> {
                   CachedNetworkImage(
                     imageUrl: _highResCoverUrl(_coverUrl) ?? _coverUrl!,
                     fit: BoxFit.cover,
+                    memCacheWidth: cacheWidth,
                     cacheManager: CoverCacheManager.instance,
                     placeholder: (_, _) =>
                         Container(color: colorScheme.surface),
@@ -729,7 +728,6 @@ class _PlaylistScreenState extends ConsumerState<PlaylistScreen> {
   }
 }
 
-/// Separate Consumer widget for each track - only rebuilds when this specific track's status changes
 class _PlaylistTrackItem extends ConsumerWidget {
   final Track track;
   final VoidCallback onDownload;

lib/screens/settings/donate_page.dart

@@ -164,13 +164,7 @@ class _RecentDonorsCard extends StatelessWidget {
   @override
   Widget build(BuildContext context) {
     final isDark = Theme.of(context).brightness == Brightness.dark;
-    const donorNames = <String>[
-      'McNuggets Jimmy',
-      'zcc09',
-      'micahRichie',
-      'a fan',
-      'CJBGR',
-    ];
+    const donorNames = <String>['R4ND0MIZ3D', 'Isra', 'bigJr48'];
 
     // Match SettingsGroup color logic
     final cardColor = isDark

lib/screens/settings/download_settings_page.dart

@@ -592,6 +592,22 @@ class _DownloadSettingsPageState extends ConsumerState<DownloadSettingsPage> {
                       settings.filenameFormat,
                     ),
                   ),
+                  SettingsItem(
+                    icon: Icons.music_note_outlined,
+                    title: context.l10n.downloadSingleFilenameFormat,
+                    subtitle: settings.singleFilenameFormat,
+                    onTap: () => _showFormatEditor(
+                      context,
+                      ref,
+                      settings.singleFilenameFormat,
+                      onSave: ref
+                          .read(settingsProvider.notifier)
+                          .setSingleFilenameFormat,
+                      title: context.l10n.downloadSingleFilenameFormat,
+                      description:
+                          context.l10n.downloadSingleFilenameFormatDescription,
+                    ),
+                  ),
                   SettingsItem(
                     icon: Icons.folder_outlined,
                     title: context.l10n.downloadDirectory,
@@ -952,7 +968,14 @@ class _DownloadSettingsPageState extends ConsumerState<DownloadSettingsPage> {
     );
   }
 
-  void _showFormatEditor(BuildContext context, WidgetRef ref, String current) {
+  void _showFormatEditor(
+    BuildContext context,
+    WidgetRef ref,
+    String current, {
+    void Function(String)? onSave,
+    String? title,
+    String? description,
+  }) {
     final controller = TextEditingController(text: current);
     final colorScheme = Theme.of(context).colorScheme;
 
@@ -1035,14 +1058,14 @@ class _DownloadSettingsPageState extends ConsumerState<DownloadSettingsPage> {
                       ),
                     ),
                     Text(
-                      context.l10n.filenameFormat,
+                      title ?? context.l10n.filenameFormat,
                       style: Theme.of(context).textTheme.headlineSmall
                           ?.copyWith(fontWeight: FontWeight.bold),
                       textAlign: TextAlign.center,
                     ),
                     const SizedBox(height: 8),
                     Text(
-                      context.l10n.downloadFilenameDescription,
+                      description ?? context.l10n.downloadFilenameDescription,
                       style: Theme.of(context).textTheme.bodyMedium?.copyWith(
                         color: colorScheme.onSurfaceVariant,
                       ),
@@ -1149,9 +1172,12 @@ class _DownloadSettingsPageState extends ConsumerState<DownloadSettingsPage> {
                           flex: 2,
                           child: FilledButton(
                             onPressed: () {
-                              ref
-                                  .read(settingsProvider.notifier)
-                                  .setFilenameFormat(controller.text);
+                              final save =
+                                  onSave ??
+                                  ref
+                                      .read(settingsProvider.notifier)
+                                      .setFilenameFormat;
+                              save(controller.text);
                               Navigator.pop(context);
                             },
                             style: FilledButton.styleFrom(
@@ -1563,7 +1589,6 @@ class _DownloadSettingsPageState extends ConsumerState<DownloadSettingsPage> {
   }
 
   static const _providerDisplayNames = <String, String>{
-    'spotify_api': 'Spotify Lyrics API',
     'lrclib': 'LRCLIB',
     'netease': 'Netease',
     'musixmatch': 'Musixmatch',

lib/screens/settings/library_settings_page.dart

@@ -53,10 +53,8 @@ class _LibrarySettingsPageState extends ConsumerState<LibrarySettingsPage> {
       if (mounted) {
         setState(() {
           _androidSdkVersion = sdkVersion;
-          // SAF doesn't need storage permission on Android 10+
           _hasStoragePermission = sdkVersion >= 29 ? true : false;
         });
-        // For older Android, check legacy storage permission
         if (sdkVersion < 29) {
           final hasPermission = await Permission.storage.isGranted;
           if (mounted) {
@@ -65,7 +63,6 @@ class _LibrarySettingsPageState extends ConsumerState<LibrarySettingsPage> {
         }
       }
     } else if (Platform.isIOS) {
-      // iOS doesn't need explicit storage permission for app documents
       setState(() => _hasStoragePermission = true);
     } else {
       setState(() => _hasStoragePermission = true);
@@ -74,7 +71,6 @@ class _LibrarySettingsPageState extends ConsumerState<LibrarySettingsPage> {
 
   Future<bool> _requestStoragePermission() async {
     if (!Platform.isAndroid) return true;
-    // SAF on Android 10+ doesn't need MANAGE_EXTERNAL_STORAGE
     if (_androidSdkVersion >= 29) return true;
 
     final status = await Permission.storage.request();
@@ -125,12 +121,9 @@ class _LibrarySettingsPageState extends ConsumerState<LibrarySettingsPage> {
         final granted = await _requestStoragePermission();
         if (!granted) return;
       }
-      // Fallback for older devices
       final result = await FilePicker.platform.getDirectoryPath();
       if (result != null) {
         if (Platform.isIOS) {
-          // On iOS, create a security-scoped bookmark so we can access
-          // this folder across app restarts and from the Go backend.
           final bookmark = await PlatformBridge.createIosBookmarkFromPath(
             result,
           );
@@ -139,8 +132,6 @@ class _LibrarySettingsPageState extends ConsumerState<LibrarySettingsPage> {
                 .read(settingsProvider.notifier)
                 .setLocalLibraryPathAndBookmark(result, bookmark);
           } else {
-            // Bookmark creation failed; save path anyway (works for
-            // app-internal folders like Documents/).
             ref.read(settingsProvider.notifier).setLocalLibraryPath(result);
           }
         } else {
@@ -162,13 +153,7 @@ class _LibrarySettingsPageState extends ConsumerState<LibrarySettingsPage> {
       return;
     }
 
-    // On iOS with a bookmark, try resolving the bookmark first to validate
-    // access instead of checking the path directly (which may fail outside
-    // the app sandbox).
     if (Platform.isIOS && iosBookmark.isNotEmpty) {
-      // Bookmark will be resolved inside startScan; skip Directory.exists
-      // check since security-scoped paths are not accessible without the
-      // bookmark being activated.
     } else if (!libraryPath.startsWith('content://') &&
         !await Directory(libraryPath).exists()) {
       if (mounted) {
@@ -392,6 +377,7 @@ class _LibrarySettingsPageState extends ConsumerState<LibrarySettingsPage> {
               itemCount: libraryState.items.length,
               excludedDownloadedCount: libraryState.excludedDownloadedCount,
               isScanning: libraryState.isScanning,
+              scanIsFinalizing: libraryState.scanIsFinalizing,
               scanProgress: libraryState.scanProgress,
               scanCurrentFile: libraryState.scanCurrentFile,
               scanTotalFiles: libraryState.scanTotalFiles,
@@ -466,7 +452,6 @@ class _LibrarySettingsPageState extends ConsumerState<LibrarySettingsPage> {
             ),
           ),
 
-          // Scan Actions Section
           if (settings.localLibraryEnabled) ...[
             SliverToBoxAdapter(
               child: SettingsSectionHeader(title: context.l10n.libraryActions),
@@ -528,8 +513,10 @@ class _LibrarySettingsPageState extends ConsumerState<LibrarySettingsPage> {
                 children: [
                   if (libraryState.isScanning)
                     _ScanProgressTile(
+                      isFinalizing: libraryState.scanIsFinalizing,
                       progress: libraryState.scanProgress,
                       currentFile: libraryState.scanCurrentFile,
+                      scannedFiles: libraryState.scannedFiles,
                       totalFiles: libraryState.scanTotalFiles,
                       onCancel: _cancelScan,
                     )
@@ -646,6 +633,7 @@ class _LibraryHeroCard extends StatelessWidget {
   final int itemCount;
   final int excludedDownloadedCount;
   final bool isScanning;
+  final bool scanIsFinalizing;
   final double scanProgress;
   final String? scanCurrentFile;
   final int scanTotalFiles;
@@ -656,6 +644,7 @@ class _LibraryHeroCard extends StatelessWidget {
     required this.itemCount,
     required this.excludedDownloadedCount,
     required this.isScanning,
+    required this.scanIsFinalizing,
     required this.scanProgress,
     this.scanCurrentFile,
     required this.scanTotalFiles,
@@ -680,6 +669,11 @@ class _LibraryHeroCard extends StatelessWidget {
   Widget build(BuildContext context) {
     final colorScheme = Theme.of(context).colorScheme;
     final isDark = Theme.of(context).brightness == Brightness.dark;
+    final showIndeterminateProgress =
+        isScanning &&
+        (scanIsFinalizing ||
+            scanTotalFiles <= 0 ||
+            (scannedFiles <= 0 && scanProgress <= 0));
     final displayCount = isScanning
         ? scannedFiles
         : itemCount + excludedDownloadedCount;
@@ -798,7 +792,7 @@ class _LibraryHeroCard extends StatelessWidget {
                 const SizedBox(height: 4),
                 Text(
                   isScanning
-                      ? context.l10n.libraryTracksUnit(scannedFiles)
+                      ? context.l10n.libraryFilesUnit(scannedFiles)
                       : context.l10n.libraryTracksUnit(displayCount),
                   style: TextStyle(
                     fontSize: 16,
@@ -821,14 +815,49 @@ class _LibraryHeroCard extends StatelessWidget {
                     ),
                   ),
                 ],
-                if (isScanning && scanCurrentFile != null) ...[
+                if (isScanning) ...[
                   const SizedBox(height: 16),
                   LinearProgressIndicator(
-                    value: scanProgress / 100,
+                    value: showIndeterminateProgress
+                        ? null
+                        : scanProgress / 100,
                     backgroundColor: colorScheme.surfaceContainerHighest,
                     color: colorScheme.primary,
                     borderRadius: BorderRadius.circular(4),
                   ),
+                  const SizedBox(height: 8),
+                  Text(
+                    scanIsFinalizing
+                        ? context.l10n.libraryScanFinalizing
+                        : scanTotalFiles > 0
+                        ? context.l10n.libraryScanProgress(
+                            scanProgress.toStringAsFixed(0),
+                            scanTotalFiles,
+                          )
+                        : context.l10n.libraryScanning,
+                    style: TextStyle(
+                      fontSize: 12,
+                      color: colorScheme.onSurfaceVariant.withValues(
+                        alpha: 0.8,
+                      ),
+                    ),
+                  ),
+                  if (!scanIsFinalizing &&
+                      scanCurrentFile != null &&
+                      scanCurrentFile!.trim().isNotEmpty) ...[
+                    const SizedBox(height: 4),
+                    Text(
+                      scanCurrentFile!,
+                      maxLines: 1,
+                      overflow: TextOverflow.ellipsis,
+                      style: TextStyle(
+                        fontSize: 12,
+                        color: colorScheme.onSurfaceVariant.withValues(
+                          alpha: 0.7,
+                        ),
+                      ),
+                    ),
+                  ],
                 ] else ...[
                   const SizedBox(height: 8),
                   Row(
@@ -865,14 +894,18 @@ class _LibraryHeroCard extends StatelessWidget {
 }
 
 class _ScanProgressTile extends StatelessWidget {
+  final bool isFinalizing;
   final double progress;
   final String? currentFile;
+  final int scannedFiles;
   final int totalFiles;
   final VoidCallback onCancel;
 
   const _ScanProgressTile({
+    required this.isFinalizing,
     required this.progress,
     this.currentFile,
+    required this.scannedFiles,
     required this.totalFiles,
     required this.onCancel,
   });
@@ -880,6 +913,8 @@ class _ScanProgressTile extends StatelessWidget {
   @override
   Widget build(BuildContext context) {
     final colorScheme = Theme.of(context).colorScheme;
+    final showIndeterminateProgress =
+        isFinalizing || totalFiles <= 0 || (scannedFiles <= 0 && progress <= 0);
 
     return Padding(
       padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 12),
@@ -901,10 +936,14 @@ class _ScanProgressTile extends StatelessWidget {
                       ),
                     ),
                     Text(
-                      context.l10n.libraryScanProgress(
-                        progress.toStringAsFixed(0),
-                        totalFiles,
-                      ),
+                      isFinalizing
+                          ? context.l10n.libraryScanFinalizing
+                          : totalFiles > 0
+                          ? context.l10n.libraryScanProgress(
+                              progress.toStringAsFixed(0),
+                              totalFiles,
+                            )
+                          : context.l10n.libraryScanning,
                       style: Theme.of(context).textTheme.bodySmall?.copyWith(
                         color: colorScheme.onSurfaceVariant,
                       ),
@@ -920,12 +959,14 @@ class _ScanProgressTile extends StatelessWidget {
           ),
           const SizedBox(height: 8),
           LinearProgressIndicator(
-            value: progress / 100,
+            value: showIndeterminateProgress ? null : progress / 100,
             backgroundColor: colorScheme.surfaceContainerHighest,
             color: colorScheme.primary,
             borderRadius: BorderRadius.circular(4),
           ),
-          if (currentFile != null) ...[
+          if (!isFinalizing &&
+              currentFile != null &&
+              currentFile!.trim().isNotEmpty) ...[
             const SizedBox(height: 4),
             Text(
               currentFile!,

lib/screens/settings/log_screen.dart

@@ -519,7 +519,7 @@ class _LogEntryTile extends StatelessWidget {
               ),
               const SizedBox(height: 6),
               Text(
-                entry.message,
+                entry.previewMessage,
                 style: TextStyle(
                   fontSize: 13,
                   fontFamily: 'monospace',
@@ -527,10 +527,10 @@ class _LogEntryTile extends StatelessWidget {
                   height: 1.4,
                 ),
               ),
-              if (entry.error != null) ...[
+              if (entry.previewError != null) ...[
                 const SizedBox(height: 4),
                 Text(
-                  entry.error!,
+                  entry.previewError!,
                   style: TextStyle(
                     fontSize: 12,
                     fontFamily: 'monospace',

lib/screens/settings/lyrics_provider_priority_page.dart

@@ -17,7 +17,6 @@ class _LyricsProviderPriorityPageState
     extends ConsumerState<LyricsProviderPriorityPage> {
   static const _allProviderIds = [
     'lrclib',
-    'spotify_api',
     'netease',
     'musixmatch',
     'apple_music',
@@ -133,9 +132,7 @@ class _LyricsProviderPriorityPageState
   void _disableProvider(String id) {
     if (_enabledProviders.length <= 1) {
       ScaffoldMessenger.of(context).showSnackBar(
-        SnackBar(
-          content: Text(context.l10n.lyricsProvidersAtLeastOne),
-        ),
+        SnackBar(content: Text(context.l10n.lyricsProvidersAtLeastOne)),
       );
       return;
     }
@@ -184,12 +181,6 @@ class _LyricsProviderPriorityPageState
     BuildContext context,
   ) {
     switch (id) {
-      case 'spotify_api':
-        return _LyricsProviderInfo(
-          name: 'Spotify Lyrics API',
-          description: context.l10n.lyricsProviderSpotifyApiDesc,
-          icon: Icons.music_note_outlined,
-        );
       case 'lrclib':
         return _LyricsProviderInfo(
           name: 'LRCLIB',

lib/screens/settings/options_settings_page.dart

@@ -2,9 +2,10 @@ import 'package:flutter/material.dart';
 import 'package:flutter_riverpod/flutter_riverpod.dart';
 import 'package:spotiflac_android/l10n/l10n.dart';
 import 'package:spotiflac_android/providers/download_queue_provider.dart';
-import 'package:spotiflac_android/providers/settings_provider.dart';
 import 'package:spotiflac_android/providers/extension_provider.dart';
+import 'package:spotiflac_android/providers/settings_provider.dart';
 import 'package:spotiflac_android/utils/app_bar_layout.dart';
+import 'package:spotiflac_android/utils/artist_utils.dart';
 import 'package:spotiflac_android/widgets/settings_group.dart';
 
 class OptionsSettingsPage extends ConsumerWidget {
@@ -69,15 +70,7 @@ class OptionsSettingsPage extends ConsumerWidget {
               ),
             ),
             SliverToBoxAdapter(
-              child: SettingsGroup(
-                children: [
-                  _MetadataSourceSelector(
-                    onChanged: (v) => ref
-                        .read(settingsProvider.notifier)
-                        .setMetadataSource(v),
-                  ),
-                ],
-              ),
+              child: SettingsGroup(children: [const _MetadataSourceSelector()]),
             ),
 
             SliverToBoxAdapter(
@@ -115,7 +108,22 @@ class OptionsSettingsPage extends ConsumerWidget {
                     value: settings.embedMetadata,
                     onChanged: (v) =>
                         ref.read(settingsProvider.notifier).setEmbedMetadata(v),
+                    showDivider: settings.embedMetadata,
                   ),
+                  if (settings.embedMetadata)
+                    SettingsItem(
+                      icon: Icons.people_alt_outlined,
+                      title: context.l10n.optionsArtistTagMode,
+                      subtitle: _getArtistTagModeLabel(
+                        context,
+                        settings.artistTagMode,
+                      ),
+                      onTap: () => _showArtistTagModePicker(
+                        context,
+                        ref,
+                        settings.artistTagMode,
+                      ),
+                    ),
                   SettingsSwitchItem(
                     icon: Icons.image,
                     title: context.l10n.optionsMaxQualityCover,
@@ -127,6 +135,18 @@ class OptionsSettingsPage extends ConsumerWidget {
                     onChanged: (v) => ref
                         .read(settingsProvider.notifier)
                         .setMaxQualityCover(v),
+                  ),
+                  SettingsSwitchItem(
+                    icon: Icons.graphic_eq,
+                    title: context.l10n.optionsReplayGain,
+                    subtitle: settings.embedReplayGain
+                        ? context.l10n.optionsReplayGainSubtitleOn
+                        : context.l10n.optionsReplayGainSubtitleOff,
+                    value: settings.embedReplayGain,
+                    enabled: settings.embedMetadata,
+                    onChanged: (v) => ref
+                        .read(settingsProvider.notifier)
+                        .setEmbedReplayGain(v),
                     showDivider: false,
                   ),
                 ],
@@ -236,6 +256,88 @@ class OptionsSettingsPage extends ConsumerWidget {
     );
   }
 
+  String _getArtistTagModeLabel(BuildContext context, String mode) {
+    switch (mode) {
+      case artistTagModeSplitVorbis:
+        return context.l10n.optionsArtistTagModeSplitVorbis;
+      default:
+        return context.l10n.optionsArtistTagModeJoined;
+    }
+  }
+
+  void _showArtistTagModePicker(
+    BuildContext context,
+    WidgetRef ref,
+    String currentMode,
+  ) {
+    final colorScheme = Theme.of(context).colorScheme;
+    showModalBottomSheet<void>(
+      context: context,
+      useRootNavigator: true,
+      backgroundColor: colorScheme.surfaceContainerHigh,
+      shape: const RoundedRectangleBorder(
+        borderRadius: BorderRadius.vertical(top: Radius.circular(28)),
+      ),
+      builder: (context) => SafeArea(
+        child: Column(
+          mainAxisSize: MainAxisSize.min,
+          crossAxisAlignment: CrossAxisAlignment.start,
+          children: [
+            Padding(
+              padding: const EdgeInsets.fromLTRB(24, 24, 24, 8),
+              child: Text(
+                context.l10n.optionsArtistTagMode,
+                style: Theme.of(
+                  context,
+                ).textTheme.titleLarge?.copyWith(fontWeight: FontWeight.bold),
+              ),
+            ),
+            Padding(
+              padding: const EdgeInsets.fromLTRB(24, 0, 24, 16),
+              child: Text(
+                context.l10n.optionsArtistTagModeDescription,
+                style: Theme.of(context).textTheme.bodyMedium?.copyWith(
+                  color: colorScheme.onSurfaceVariant,
+                ),
+              ),
+            ),
+            ListTile(
+              leading: const Icon(Icons.segment_outlined),
+              title: Text(context.l10n.optionsArtistTagModeJoined),
+              subtitle: Text(context.l10n.optionsArtistTagModeJoinedSubtitle),
+              trailing: currentMode == artistTagModeJoined
+                  ? const Icon(Icons.check)
+                  : null,
+              onTap: () {
+                ref
+                    .read(settingsProvider.notifier)
+                    .setArtistTagMode(artistTagModeJoined);
+                Navigator.pop(context);
+              },
+            ),
+            ListTile(
+              leading: const Icon(Icons.library_music_outlined),
+              title: Text(context.l10n.optionsArtistTagModeSplitVorbis),
+              subtitle: Text(
+                context.l10n.optionsArtistTagModeSplitVorbisSubtitle,
+              ),
+              trailing: currentMode == artistTagModeSplitVorbis
+                  ? const Icon(Icons.check)
+                  : null,
+              onTap: () {
+                ref
+                    .read(settingsProvider.notifier)
+                    .setArtistTagMode(artistTagModeSplitVorbis);
+                Navigator.pop(context);
+              },
+            ),
+            const SizedBox(height: 16),
+          ],
+        ),
+      ),
+    );
+  }
+
   void _showClearHistoryDialog(
     BuildContext context,
     WidgetRef ref,
@@ -608,8 +710,7 @@ class _ChannelChip extends StatelessWidget {
 }
 
 class _MetadataSourceSelector extends ConsumerWidget {
-  final ValueChanged<String> onChanged;
-  const _MetadataSourceSelector({required this.onChanged});
+  const _MetadataSourceSelector();
 
   static const _builtInProviders = {'tidal': 'Tidal', 'qobuz': 'Qobuz'};
 
@@ -672,7 +773,6 @@ class _MetadataSourceSelector extends ConsumerWidget {
                   if (hasNonDefaultProvider) {
                     ref.read(settingsProvider.notifier).setSearchProvider(null);
                   }
-                  onChanged('deezer');
                 },
               ),
               const SizedBox(width: 8),
@@ -684,7 +784,6 @@ class _MetadataSourceSelector extends ConsumerWidget {
                   ref
                       .read(settingsProvider.notifier)
                       .setSearchProvider('tidal');
-                  onChanged('tidal');
                 },
               ),
               const SizedBox(width: 8),
@@ -696,7 +795,6 @@ class _MetadataSourceSelector extends ConsumerWidget {
                   ref
                       .read(settingsProvider.notifier)
                       .setSearchProvider('qobuz');
-                  onChanged('qobuz');
                 },
               ),
             ],

lib/screens/setup_screen.dart

@@ -426,7 +426,6 @@ class _SetupScreenState extends ConsumerState<SetupScreen> {
             );
       }
 
-      ref.read(settingsProvider.notifier).setMetadataSource('deezer');
       ref.read(settingsProvider.notifier).setFirstLaunchComplete();
 
       if (mounted) context.go('/tutorial');

lib/screens/tutorial_screen.dart

@@ -707,10 +707,6 @@ class _TutorialPage extends StatelessWidget {
     final contentGap = (56 * scale) + ((textScale - 1) * 10);
     final bottomGap = (32 * scale).clamp(20.0, 32.0);
 
-    // Parallax effect logic (simplified for StatelessWidget)
-    // In a real advanced implementation we'd pass the Controller's listenable
-    // But for now, let's use entrance animations based on currentIndex == index
-
     final isActive = currentIndex == index;
 
     return SingleChildScrollView(

lib/services/cover_cache_manager.dart

@@ -21,7 +21,6 @@ class CoverCacheManager {
 
   static CacheManager get instance {
     if (!_initialized || _instance == null) {
-      // Fallback to default cache manager if not initialized
       debugPrint('CoverCacheManager: Not initialized, using DefaultCacheManager');
       return DefaultCacheManager();
     }
@@ -36,13 +35,13 @@ class CoverCacheManager {
     try {
       final appDir = await getApplicationSupportDirectory();
       _cachePath = p.join(appDir.path, 'cover_cache');
-      
+
       await Directory(_cachePath!).create(recursive: true);
-      
+
       debugPrint('CoverCacheManager: Initializing at $_cachePath');
 
       _instance = _createManager(_cachePath!);
-      
+
       _initialized = true;
       debugPrint('CoverCacheManager: Initialized successfully');
     } catch (e) {
@@ -60,22 +59,18 @@ class CoverCacheManager {
 
     if (instance == null || cachePath == null) return;
 
-    // Ask cache manager to clear indexed entries first.
     try {
       await instance.emptyCache();
     } catch (e) {
       debugPrint('CoverCacheManager: emptyCache failed, fallback to wipe: $e');
     }
 
-    // Then wipe the directory to remove orphaned files/metadata leftovers.
     await _wipeDirectory(cachePath);
 
-    // Clear in-memory image cache so cleared covers are not retained in RAM.
     final imageCache = PaintingBinding.instance.imageCache;
     imageCache.clear();
     imageCache.clearLiveImages();
 
-    // Reset manager memory/index state after on-disk wipe.
     instance.store.emptyMemoryCache();
     _instance = _createManager(cachePath);
     _initialized = true;
@@ -124,7 +119,6 @@ class CoverCacheManager {
         _cacheKey,
         stalePeriod: _maxCacheAge,
         maxNrOfCacheObjects: _maxCacheObjects,
-        // Use path only (not databaseName) to store database in persistent directory
         repo: JsonCacheInfoRepository(path: cachePath),
         fileSystem: IOFileSystem(cachePath),
         fileService: HttpFileService(),

lib/services/download_request_payload.dart

@@ -11,6 +11,7 @@ class DownloadRequestPayload {
   final String filenameFormat;
   final String quality;
   final bool embedMetadata;
+  final String artistTagMode;
   final bool embedLyrics;
   final bool embedMaxQualityCover;
   final int trackNumber;
@@ -49,10 +50,11 @@ class DownloadRequestPayload {
     required this.filenameFormat,
     this.quality = 'LOSSLESS',
     this.embedMetadata = true,
+    this.artistTagMode = 'joined',
     this.embedLyrics = true,
     this.embedMaxQualityCover = true,
-    this.trackNumber = 1,
-    this.discNumber = 1,
+    this.trackNumber = 0,
+    this.discNumber = 0,
     this.totalTracks = 1,
     this.releaseDate = '',
     this.itemId = '',
@@ -89,6 +91,7 @@ class DownloadRequestPayload {
       'filename_format': filenameFormat,
       'quality': quality,
       'embed_metadata': embedMetadata,
+      'artist_tag_mode': artistTagMode,
       'embed_lyrics': embedLyrics,
       'embed_max_quality_cover': embedMaxQualityCover,
       'track_number': trackNumber,
@@ -133,6 +136,7 @@ class DownloadRequestPayload {
       filenameFormat: filenameFormat,
       quality: quality,
       embedMetadata: embedMetadata,
+      artistTagMode: artistTagMode,
       embedLyrics: embedLyrics,
       embedMaxQualityCover: embedMaxQualityCover,
       trackNumber: trackNumber,

lib/services/downloaded_embedded_cover_resolver.dart

@@ -1,3 +1,4 @@
+import 'dart:async';
 import 'dart:collection';
 import 'dart:io';
 
@@ -107,7 +108,7 @@ class DownloadedEmbeddedCoverResolver {
     _pendingPreviewValidation.remove(cleanPath);
     _failedExtract.remove(cleanPath);
     if (cached != null) {
-      _cleanupTempCoverPathSync(cached.previewPath);
+      _scheduleTempCoverCleanup(cached.previewPath);
     }
   }
 
@@ -139,7 +140,7 @@ class DownloadedEmbeddedCoverResolver {
       final oldestKey = _cache.keys.first;
       final removed = _cache.remove(oldestKey);
       if (removed != null) {
-        _cleanupTempCoverPathSync(removed.previewPath);
+        _scheduleTempCoverCleanup(removed.previewPath);
       }
       _pendingExtract.remove(oldestKey);
       _pendingRefresh.remove(oldestKey);
@@ -165,7 +166,7 @@ class DownloadedEmbeddedCoverResolver {
             _failedExtract.remove(cleanPath);
             onChanged?.call();
           }
-          _cleanupTempCoverPathSync(entry.previewPath);
+          _scheduleTempCoverCleanup(entry.previewPath);
         }
       } finally {
         _pendingPreviewValidation.remove(cleanPath);
@@ -203,7 +204,7 @@ class DownloadedEmbeddedCoverResolver {
             result['error'] == null && await File(outputPath).exists();
         if (!hasCover) {
           _failedExtract.add(cleanPath);
-          _cleanupTempCoverPathSync(outputPath);
+          _scheduleTempCoverCleanup(outputPath);
           return;
         }
 
@@ -217,29 +218,32 @@ class DownloadedEmbeddedCoverResolver {
         _trimCacheIfNeeded();
 
         if (previous != null && previous.previewPath != outputPath) {
-          _cleanupTempCoverPathSync(previous.previewPath);
+          _scheduleTempCoverCleanup(previous.previewPath);
         }
         onChanged?.call();
       } catch (_) {
         _failedExtract.add(cleanPath);
-        _cleanupTempCoverPathSync(outputPath);
+        _scheduleTempCoverCleanup(outputPath);
       } finally {
         _pendingExtract.remove(cleanPath);
       }
     });
   }
 
-  static void _cleanupTempCoverPathSync(String? coverPath) {
+  static void _scheduleTempCoverCleanup(String? coverPath) {
+    unawaited(_cleanupTempCoverPath(coverPath));
+  }
+
+  static Future<void> _cleanupTempCoverPath(String? coverPath) async {
     if (coverPath == null || coverPath.isEmpty) return;
     try {
       final file = File(coverPath);
-      if (file.existsSync()) {
-        file.deleteSync();
-      }
-      final parent = file.parent;
-      if (parent.existsSync()) {
-        parent.deleteSync(recursive: true);
-      }
+      try {
+        await file.delete();
+      } catch (_) {}
+      try {
+        await file.parent.delete(recursive: true);
+      } catch (_) {}
     } catch (_) {}
   }
 }