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

@@ -163,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)
@@ -215,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 {
@@ -2384,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()
@@ -2516,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))
@@ -983,7 +974,6 @@ func parseVorbisComments(data []byte, metadata *AudioMetadata) {
 	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
@@ -1012,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
@@ -1066,6 +1054,14 @@ 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
 		}
 	}
 
@@ -1123,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
@@ -1133,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
@@ -1151,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
@@ -1167,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
@@ -1194,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 {
@@ -1212,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
@@ -1272,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 {
@@ -1303,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)

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,7 +23,6 @@ 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"`
@@ -35,7 +33,6 @@ type CueTrack struct {
 	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 {
@@ -425,13 +393,6 @@ func ScanCueFileForLibrary(cuePath string, scanTime string) ([]LibraryScanResult
 	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,
@@ -483,7 +444,6 @@ func scanCueSheetForLibrary(cuePath string, sheet *CueSheet, audioPath, virtualP
 		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))
@@ -505,7 +465,6 @@ func scanCueSheetForLibrary(cuePath string, sheet *CueSheet, audioPath, virtualP
 		}
 	}
 
-	// Extract cover from audio file for all tracks
 	var coverPath string
 	libraryCoverCacheMu.RLock()
 	coverCacheDir := libraryCoverCacheDir
@@ -522,13 +481,11 @@ func scanCueSheetForLibrary(cuePath string, sheet *CueSheet, audioPath, virtualP
 		}
 	}
 
-	// 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 {
@@ -556,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
@@ -570,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

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

@@ -118,25 +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"`
-	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"`
+	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) {
@@ -156,38 +171,48 @@ 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
+		}
 	}
 }
 
@@ -203,44 +228,48 @@ func reEnrichDownloadRequest(req reEnrichRequest) DownloadRequest {
 	}
 }
 
-func buildReEnrichFFmpegMetadata(req reEnrichRequest, lyricsLRC string) map[string]string {
+func buildReEnrichFFmpegMetadata(req *reEnrichRequest, lyricsLRC string) map[string]string {
 	metadata := map[string]string{}
-	if req.TrackName != "" {
-		metadata["TITLE"] = req.TrackName
+	if req.shouldUpdateField("basic_tags") {
+		if req.AlbumName != "" {
+			metadata["ALBUM"] = req.AlbumName
+		}
+		if req.AlbumArtist != "" {
+			metadata["ALBUMARTIST"] = req.AlbumArtist
+		}
 	}
-	if req.ArtistName != "" {
-		metadata["ARTIST"] = req.ArtistName
+	if req.shouldUpdateField("release_info") {
+		if req.ReleaseDate != "" {
+			metadata["DATE"] = req.ReleaseDate
+		}
+		if req.ISRC != "" {
+			metadata["ISRC"] = req.ISRC
+		}
 	}
-	if req.AlbumName != "" {
-		metadata["ALBUM"] = req.AlbumName
+	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.AlbumArtist != "" {
-		metadata["ALBUMARTIST"] = req.AlbumArtist
+	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.ReleaseDate != "" {
-		metadata["DATE"] = req.ReleaseDate
-	}
-	if req.ISRC != "" {
-		metadata["ISRC"] = req.ISRC
-	}
-	if req.Genre != "" {
-		metadata["GENRE"] = req.Genre
-	}
-	if req.TrackNumber > 0 {
-		metadata["TRACKNUMBER"] = fmt.Sprintf("%d", req.TrackNumber)
-	}
-	if req.DiscNumber > 0 {
-		metadata["DISCNUMBER"] = fmt.Sprintf("%d", req.DiscNumber)
-	}
-	if req.Label != "" {
-		metadata["ORGANIZATION"] = req.Label
-	}
-	if req.Copyright != "" {
-		metadata["COPYRIGHT"] = req.Copyright
-	}
-	if lyricsLRC != "" {
-		metadata["LYRICS"] = lyricsLRC
-		metadata["UNSYNCEDLYRICS"] = lyricsLRC
+	if req.shouldUpdateField("lyrics") {
+		if lyricsLRC != "" {
+			metadata["LYRICS"] = lyricsLRC
+			metadata["UNSYNCEDLYRICS"] = lyricsLRC
+		}
 	}
 	return metadata
 }
@@ -735,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 {
@@ -966,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":        "",
@@ -1031,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 {
@@ -1061,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 {
@@ -1083,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 {
@@ -1108,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)
 	}
@@ -1128,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) {
@@ -1174,9 +1253,7 @@ func ScanCueSheetForLibraryWithCoverCacheKey(cuePath, audioDir, virtualPathPrefi
 	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.
+// 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 {
@@ -1185,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 != "" {
@@ -1197,30 +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"],
-			ArtistTagMode: fields["artist_tag_mode"],
-			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
@@ -1409,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"`
@@ -1933,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
 }
 
@@ -1967,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
 
@@ -2089,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()
@@ -2123,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)
@@ -2173,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)
@@ -2194,39 +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,
 			ArtistTagMode: req.ArtistTagMode,
-			Date:          req.ReleaseDate,
-			TrackNumber:   req.TrackNumber,
-			DiscNumber:    req.DiscNumber,
-			ISRC:          req.ISRC,
-			Genre:         req.Genre,
-			Label:         req.Label,
-			Copyright:     req.Copyright,
-			Lyrics:        lyricsLRC,
+		}
+		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 {
@@ -2262,7 +2456,7 @@ func ReEnrichFile(requestJSON string) (string, error) {
 
 	// Don't cleanup cover temp — Dart needs it for FFmpeg embed
 	cleanupCover = false
-	ffmpegMetadata := buildReEnrichFFmpegMetadata(req, lyricsLRC)
+	ffmpegMetadata := buildReEnrichFFmpegMetadata(&req, lyricsLRC)
 
 	result := map[string]interface{}{
 		"method":            "ffmpeg",
@@ -2713,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,
@@ -3008,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() {
@@ -3023,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)
 	}

go_backend/exports_test.go

@@ -193,13 +193,15 @@ func TestBuildReEnrichFFmpegMetadataOmitsEmptyFields(t *testing.T) {
 		Copyright:   "",
 	}
 
-	metadata := buildReEnrichFFmpegMetadata(req, "")
+	metadata := buildReEnrichFFmpegMetadata(&req, "")
 
-	if metadata["TITLE"] != "Song" {
-		t.Fatalf("title = %q", metadata["TITLE"])
+	// 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 metadata["ARTIST"] != "Artist" {
-		t.Fatalf("artist = %q", metadata["ARTIST"])
+	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"])

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

@@ -66,6 +66,9 @@ var supportedAudioFormats = map[string]bool{
 	".mp3":  true,
 	".opus": true,
 	".ogg":  true,
+	".ape":  true,
+	".wv":   true,
+	".mpc":  true,
 	".cue":  true,
 }
 
@@ -170,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))
@@ -209,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]
@@ -318,6 +318,8 @@ func scanAudioFileWithKnownModTimeAndDisplayNameAndCoverCacheKey(filePath, displ
 		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)
 	}
@@ -481,6 +483,37 @@ 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)
@@ -827,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/logbuffer.go

@@ -51,7 +51,7 @@ 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
@@ -145,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"
 
@@ -163,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, "{") {
@@ -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

@@ -118,6 +118,12 @@ type Metadata struct {
 	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 {
@@ -144,61 +150,7 @@ func EmbedMetadata(filePath string, metadata Metadata, coverPath string) error {
 		cmt = flacvorbis.New()
 	}
 
-	setComment(cmt, "TITLE", metadata.Title)
-	setArtistComments(cmt, "ARTIST", metadata.Artist, metadata.ArtistTagMode)
-	setComment(cmt, "ALBUM", metadata.Album)
-	setArtistComments(
-		cmt,
-		"ALBUMARTIST",
-		metadata.AlbumArtist,
-		metadata.ArtistTagMode,
-	)
-	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 {
@@ -258,15 +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)
 	setArtistComments(cmt, "ARTIST", metadata.Artist, metadata.ArtistTagMode)
 	setComment(cmt, "ALBUM", metadata.Album)
-	setArtistComments(
-		cmt,
-		"ALBUMARTIST",
-		metadata.AlbumArtist,
-		metadata.ArtistTagMode,
-	)
+	setArtistComments(cmt, "ALBUMARTIST", metadata.AlbumArtist, metadata.ArtistTagMode)
 	setComment(cmt, "DATE", metadata.Date)
 
 	if metadata.TrackNumber > 0 {
@@ -314,96 +522,10 @@ 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 = getJoinedComment(cmt, "ARTIST")
-			metadata.Album = getComment(cmt, "ALBUM")
-			metadata.AlbumArtist = getJoinedComment(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) {
@@ -414,7 +536,21 @@ func setComment(cmt *flacvorbis.MetaDataBlockVorbisComment, key, value string) {
 	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)
@@ -431,6 +567,76 @@ func setArtistComments(cmt *flacvorbis.MetaDataBlockVorbisComment, key, value, m
 	}
 }
 
+// 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-- {
@@ -774,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_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

@@ -44,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/"
@@ -58,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"`
@@ -786,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
@@ -802,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 {
@@ -842,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 {
@@ -871,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",
@@ -896,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 {
@@ -1063,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},
 	}
@@ -1216,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 {
@@ -1376,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 {
@@ -1403,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 {
@@ -1441,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{}
 
@@ -1646,13 +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 {
 		body, _ := io.ReadAll(io.LimitReader(resp.Body, 512))
-		return nil, fmt.Errorf("search failed: HTTP %d (%s)", resp.StatusCode, strings.TrimSpace(string(body)))
+		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 {
@@ -1666,6 +1822,20 @@ 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
@@ -1855,7 +2025,8 @@ func (q *QobuzDownloader) searchQobuzTracksViaAlbumSearch(query string, limit in
 	}
 
 	searchURL := fmt.Sprintf(
-		"https://www.qobuz.com/api.json/0.2/album/search?query=%s&limit=%d&app_id=%s",
+		"%salbum/search?query=%s&limit=%d&app_id=%s",
+		qobuzAPIBaseURL,
 		url.QueryEscape(strings.TrimSpace(query)),
 		albumLimit,
 		q.appID,
@@ -1868,13 +2039,22 @@ func (q *QobuzDownloader) searchQobuzTracksViaAlbumSearch(query string, limit in
 
 	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))
-		return nil, fmt.Errorf("album search failed: HTTP %d (%s)", resp.StatusCode, strings.TrimSpace(string(body)))
+		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 {
@@ -1894,6 +2074,25 @@ func (q *QobuzDownloader) searchQobuzTracksViaAlbumSearch(query string, limit in
 	)
 }
 
+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 {

go_backend/qobuz_test.go

@@ -201,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 {

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)
@@ -2497,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.3';
-  static const String buildNumber = '120';
+  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,24 @@ 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:
@@ -2218,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:
@@ -4048,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:
@@ -4647,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,17 @@ 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';
 
@@ -1201,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.';
@@ -2290,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';
 
@@ -2706,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,17 @@ 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';
 
@@ -1182,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.';
 
@@ -2260,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';
 
@@ -2674,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,17 @@ 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';
 
@@ -1182,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.';
 
@@ -2260,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';
 
@@ -2674,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,17 @@ 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';
 
@@ -1184,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.';
 
@@ -2262,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';
 
@@ -2675,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,17 @@ 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';
 
@@ -1182,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.';
 
@@ -2260,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';
 
@@ -2673,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,17 @@ 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';
 
@@ -1189,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.';
 
@@ -2270,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';
 
@@ -2684,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,17 @@ 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';
 
@@ -1176,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 => 'リクエストがタイムアウトしました。後ほどお試しください。';
 
@@ -2247,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 => 'メタデータを編集';
 
@@ -2660,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,17 @@ 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';
 
@@ -1162,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.';
 
@@ -2240,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';
 
@@ -2653,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,17 @@ 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';
 
@@ -1182,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.';
 
@@ -2260,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';
 
@@ -2673,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,17 @@ 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';
 
@@ -1182,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.';
 
@@ -2260,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';
 
@@ -2674,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,17 @@ 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';
 
@@ -1202,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 =>
       'Время ожидания запроса истекло. Повторите попытку позже.';
@@ -2312,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 => 'Редактировать метаданные';
 
@@ -2733,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,17 @@ 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';
 
@@ -1188,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.';
 
@@ -2266,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';
 
@@ -2679,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,17 @@ 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';
 
@@ -1182,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.';
 
@@ -2260,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';
 
@@ -2674,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,18 @@
   "@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"
@@ -1543,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"
@@ -2954,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"
@@ -3551,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

@@ -16,6 +16,7 @@ class AppSettings {
   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;
@@ -30,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;
@@ -93,6 +91,7 @@ class AppSettings {
     this.embedMetadata = true,
     this.artistTagMode = artistTagModeJoined,
     this.embedLyrics = true,
+    this.embedReplayGain = false,
     this.maxQualityCover = true,
     this.isFirstLaunch = true,
     this.concurrentDownloads = 1,
@@ -107,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',
@@ -134,7 +130,6 @@ class AppSettings {
     this.hasCompletedTutorial = false,
     this.lyricsProviders = const [
       'lrclib',
-      'spotify_api',
       'musixmatch',
       'netease',
       'apple_music',
@@ -158,6 +153,7 @@ class AppSettings {
     bool? embedMetadata,
     String? artistTagMode,
     bool? embedLyrics,
+    bool? embedReplayGain,
     bool? maxQualityCover,
     bool? isFirstLaunch,
     int? concurrentDownloads,
@@ -172,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,
@@ -183,6 +175,7 @@ class AppSettings {
     String? homeFeedProvider,
     bool clearHomeFeedProvider = false,
     bool? separateSingles,
+    String? singleFilenameFormat,
     String? albumFolderStructure,
     bool? showExtensionStore,
     String? locale,
@@ -217,6 +210,7 @@ class AppSettings {
       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,
@@ -235,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,
@@ -250,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,8 +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? ?? 'joined',
+  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,
@@ -32,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,
@@ -65,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:
@@ -96,6 +87,7 @@ Map<String, dynamic> _$AppSettingsToJson(
   'embedMetadata': instance.embedMetadata,
   'artistTagMode': instance.artistTagMode,
   'embedLyrics': instance.embedLyrics,
+  'embedReplayGain': instance.embedReplayGain,
   'maxQualityCover': instance.maxQualityCover,
   'isFirstLaunch': instance.isFirstLaunch,
   'concurrentDownloads': instance.concurrentDownloads,
@@ -111,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/settings_provider.dart

@@ -12,7 +12,7 @@ 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');
 
@@ -44,7 +44,7 @@ class SettingsNotifier extends Notifier<AppSettings> {
       await _normalizeSongLinkRegionIfNeeded();
     }
 
-    await _retireBuiltInSpotifyProvider();
+    await _cleanupRetiredSpotifySettings();
 
     LogBuffer.loggingEnabled = state.enableLogging;
 
@@ -86,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');
@@ -101,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);
@@ -134,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;
@@ -186,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) {
@@ -225,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();
@@ -256,6 +232,11 @@ 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();
@@ -380,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()

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());
   }
 
@@ -824,12 +829,14 @@ class _LocalAlbumScreenState extends ConsumerState<LocalAlbumScreen> {
         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(
@@ -837,6 +844,7 @@ class _LocalAlbumScreenState extends ConsumerState<LocalAlbumScreen> {
         coverPath: effectiveCoverPath,
         metadata: metadata,
         artistTagMode: artistTagMode,
+        preserveMetadata: true,
       );
     }
 
@@ -867,7 +875,10 @@ 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>{
@@ -890,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);
@@ -1048,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;
 
@@ -1098,7 +1104,7 @@ class _LocalAlbumScreenState extends ConsumerState<LocalAlbumScreen> {
       );
 
       try {
-        final ok = await _reEnrichLocalTrack(item);
+        final ok = await _reEnrichLocalTrack(item, updateFields: updateFields);
         if (ok) {
           successCount++;
         }

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/queue_tab.dart

@@ -28,6 +28,7 @@ import 'package:spotiflac_android/services/history_database.dart';
 import 'package:spotiflac_android/services/downloaded_embedded_cover_resolver.dart';
 import 'package:spotiflac_android/screens/track_metadata_screen.dart';
 import 'package:spotiflac_android/screens/downloaded_album_screen.dart';
+import 'package:spotiflac_android/widgets/re_enrich_field_dialog.dart';
 import 'package:spotiflac_android/widgets/batch_progress_dialog.dart';
 import 'package:spotiflac_android/screens/library_tracks_folder_screen.dart';
 import 'package:spotiflac_android/screens/local_album_screen.dart';
@@ -155,7 +156,6 @@ class UnifiedLibraryItem {
     return 'builtin:$id';
   }
 
-  /// Convert to a [Track] for adding to collections/playlists.
   Track toTrack() {
     if (historyItem != null) {
       final h = historyItem!;
@@ -359,6 +359,24 @@ class _QueueGroupedAlbumFilterRequest {
   );
 }
 
+class _QueueHistoryStatsMemoEntry {
+  final List<DownloadHistoryItem> historyItems;
+  final List<LocalLibraryItem> localItems;
+  final _HistoryStats stats;
+
+  const _QueueHistoryStatsMemoEntry({
+    required this.historyItems,
+    required this.localItems,
+    required this.stats,
+  });
+}
+
+_QueueHistoryStatsMemoEntry? _queueHistoryStatsMemo;
+
+String _queueHistoryAlbumKey(String albumName, String artistName) {
+  return '${albumName.toLowerCase()}|${artistName.toLowerCase()}';
+}
+
 String _queueFileExtLower(String filePath) {
   final slashIndex = filePath.lastIndexOf('/');
   final dotIndex = filePath.lastIndexOf('.');
@@ -558,21 +576,31 @@ _HistoryStats _buildQueueHistoryStats(
   List<DownloadHistoryItem> items, [
   List<LocalLibraryItem> localItems = const [],
 ]) {
+  final memo = _queueHistoryStatsMemo;
+  if (memo != null &&
+      identical(memo.historyItems, items) &&
+      identical(memo.localItems, localItems)) {
+    return memo.stats;
+  }
+
   final albumCounts = <String, int>{};
   final albumMap = <String, List<DownloadHistoryItem>>{};
   for (final item in items) {
-    final key =
-        '${item.albumName.toLowerCase()}|${(item.albumArtist ?? item.artistName).toLowerCase()}';
+    final key = _queueHistoryAlbumKey(
+      item.albumName,
+      item.albumArtist ?? item.artistName,
+    );
     albumCounts[key] = (albumCounts[key] ?? 0) + 1;
     albumMap.putIfAbsent(key, () => []).add(item);
   }
 
   var singleTracks = 0;
-  for (final item in items) {
-    final key =
-        '${item.albumName.toLowerCase()}|${(item.albumArtist ?? item.artistName).toLowerCase()}';
-    if ((albumCounts[key] ?? 0) <= 1) {
-      singleTracks++;
+  var albumCount = 0;
+  for (final count in albumCounts.values) {
+    if (count > 1) {
+      albumCount++;
+    } else {
+      singleTracks += count;
     }
   }
 
@@ -600,11 +628,6 @@ _HistoryStats _buildQueueHistoryStats(
   });
   groupedAlbums.sort((a, b) => b.latestDownload.compareTo(a.latestDownload));
 
-  var albumCount = 0;
-  for (final count in albumCounts.values) {
-    if (count > 1) albumCount++;
-  }
-
   final downloadedPathKeys = <String>{};
   for (final item in items) {
     downloadedPathKeys.addAll(buildPathMatchKeys(item.filePath));
@@ -620,8 +643,10 @@ _HistoryStats _buildQueueHistoryStats(
   final localAlbumCounts = <String, int>{};
   final localAlbumMap = <String, List<LocalLibraryItem>>{};
   for (final item in dedupedLocalItems) {
-    final key =
-        '${item.albumName.toLowerCase()}|${(item.albumArtist ?? item.artistName).toLowerCase()}';
+    final key = _queueHistoryAlbumKey(
+      item.albumName,
+      item.albumArtist ?? item.artistName,
+    );
     localAlbumCounts[key] = (localAlbumCounts[key] ?? 0) + 1;
     localAlbumMap.putIfAbsent(key, () => []).add(item);
   }
@@ -664,7 +689,7 @@ _HistoryStats _buildQueueHistoryStats(
   });
   groupedLocalAlbums.sort((a, b) => b.latestScanned.compareTo(a.latestScanned));
 
-  return _HistoryStats(
+  final stats = _HistoryStats(
     albumCounts: albumCounts,
     localAlbumCounts: localAlbumCounts,
     groupedAlbums: groupedAlbums,
@@ -674,6 +699,12 @@ _HistoryStats _buildQueueHistoryStats(
     localAlbumCount: localAlbumCount,
     localSingleTracks: localSingleTracks,
   );
+  _queueHistoryStatsMemo = _QueueHistoryStatsMemoEntry(
+    historyItems: items,
+    localItems: localItems,
+    stats: stats,
+  );
+  return stats;
 }
 
 List<_GroupedAlbum> _queueFilterGroupedAlbums(
@@ -1121,6 +1152,10 @@ class _QueueTabState extends ConsumerState<QueueTab> {
   List<UnifiedLibraryItem> _cachedUnifiedLocal = const [];
   List<DownloadHistoryItem>? _cachedDownloadedPathKeysSource;
   Set<String> _cachedDownloadedPathKeys = const <String>{};
+  final Map<String, List<String>> _localPathMatchKeysCache = {};
+  List<LocalLibraryItem>? _cachedLocalSinglesSource;
+  Map<String, int>? _cachedLocalSinglesAlbumCountsSource;
+  List<LocalLibraryItem> _cachedLocalSingles = const [];
   final Map<String, _FilterContentData> _filterContentDataCache = {};
   List<DownloadHistoryItem>? _filterCacheAllHistoryItems;
   _HistoryStats? _filterCacheHistoryStats;
@@ -1132,11 +1167,11 @@ class _QueueTabState extends ConsumerState<QueueTab> {
   String? _filterCacheFormat;
   String? _filterCacheMetadata;
   String _filterCacheSortMode = 'latest';
-  String? _filterSource; // null = all, 'downloaded', 'local'
-  String? _filterQuality; // null = all, 'hires', 'cd', 'lossy'
-  String? _filterFormat; // null = all, 'flac', 'mp3', 'm4a', 'opus', 'ogg'
-  String? _filterMetadata; // null = all, 'complete', 'missing-*'
-  String _sortMode = 'latest'; // 'latest', 'oldest', 'a-z', 'z-a'
+  String? _filterSource;
+  String? _filterQuality;
+  String? _filterFormat;
+  String? _filterMetadata;
+  String _sortMode = 'latest';
 
   double _effectiveTextScale() {
     final textScale = MediaQuery.textScalerOf(context).scale(1.0);
@@ -1264,9 +1299,13 @@ class _QueueTabState extends ConsumerState<QueueTab> {
     }
     if (localChanged) {
       _localSearchIndexCache.clear();
+      _localPathMatchKeysCache.clear();
       _localFilterItemsCache = null;
       _localFilterQueryCache = '';
       _filteredLocalItemsCache = const [];
+      _cachedLocalSinglesSource = null;
+      _cachedLocalSinglesAlbumCountsSource = null;
+      _cachedLocalSingles = const [];
       _cachedUnifiedLocalSource = null;
       _cachedUnifiedLocal = const [];
     }
@@ -1356,6 +1395,32 @@ class _QueueTabState extends ConsumerState<QueueTab> {
     return _cachedDownloadedPathKeys;
   }
 
+  List<String> _localPathMatchKeys(LocalLibraryItem item) {
+    final cached = _localPathMatchKeysCache[item.id];
+    if (cached != null) return cached;
+    final keys = buildPathMatchKeys(item.filePath).toList(growable: false);
+    _localPathMatchKeysCache[item.id] = keys;
+    return keys;
+  }
+
+  List<LocalLibraryItem> _localSingleItems(
+    List<LocalLibraryItem> items,
+    Map<String, int> localAlbumCounts,
+  ) {
+    if (identical(items, _cachedLocalSinglesSource) &&
+        identical(localAlbumCounts, _cachedLocalSinglesAlbumCountsSource)) {
+      return _cachedLocalSingles;
+    }
+
+    final singles = items
+        .where((item) => (localAlbumCounts[item.albumKey] ?? 0) == 1)
+        .toList(growable: false);
+    _cachedLocalSinglesSource = items;
+    _cachedLocalSinglesAlbumCountsSource = localAlbumCounts;
+    _cachedLocalSingles = singles;
+    return singles;
+  }
+
   List<LocalLibraryItem> _filterLocalItems(
     List<LocalLibraryItem> items,
     String query,
@@ -2036,7 +2101,6 @@ class _QueueTabState extends ConsumerState<QueueTab> {
       return quality.split('/').first;
     }
 
-    // Supports "MP3 320k", "Opus 256kbps", etc.
     final bitrateTextMatch = RegExp(
       r'(\d+)\s*k(?:bps)?',
       caseSensitive: false,
@@ -2045,7 +2109,6 @@ class _QueueTabState extends ConsumerState<QueueTab> {
       return '${bitrateTextMatch.group(1)}k';
     }
 
-    // Supports legacy quality IDs like "opus_256" / "mp3_320".
     final bitrateIdMatch = RegExp(r'_(\d+)$').firstMatch(q);
     if (bitrateIdMatch != null) {
       return '${bitrateIdMatch.group(1)}k';
@@ -2100,7 +2163,6 @@ class _QueueTabState extends ConsumerState<QueueTab> {
         }
       }
 
-      // Reload local library if we deleted any local items
       if (allItems.any(
         (i) =>
             _selectedIds.contains(i.id) && i.source == LibraryItemSource.local,
@@ -2120,7 +2182,6 @@ class _QueueTabState extends ConsumerState<QueueTab> {
     }
   }
 
-  /// Strip EXISTS: prefix from file path (legacy history items)
   String _cleanFilePath(String? filePath) {
     return DownloadedEmbeddedCoverResolver.cleanFilePath(filePath);
   }
@@ -2303,7 +2364,7 @@ class _QueueTabState extends ConsumerState<QueueTab> {
 
   List<UnifiedLibraryItem> _applySorting(List<UnifiedLibraryItem> items) {
     if (_sortMode == 'latest') {
-      return items; // Already sorted newest first from _getUnifiedItems
+      return items;
     }
     final sorted = List<UnifiedLibraryItem>.of(items);
     switch (_sortMode) {
@@ -2970,7 +3031,6 @@ class _QueueTabState extends ConsumerState<QueueTab> {
     }
   }
 
-  /// Navigate with unfocus pattern — unfocuses search before and after navigation.
   void _navigateWithUnfocus(Route<dynamic> route) {
     _searchFocusNode.unfocus();
     Navigator.of(context).push(route).then((_) => _searchFocusNode.unfocus());
@@ -3200,14 +3260,12 @@ class _QueueTabState extends ConsumerState<QueueTab> {
   }) async {
     final notifier = ref.read(libraryCollectionsProvider.notifier);
 
-    // If in selection mode and the dragged item is selected, add ALL selected
     if (_isSelectionMode &&
         _selectedIds.isNotEmpty &&
         _selectedIds.contains(item.id)) {
       final selectedItems = allItems
           .where((e) => _selectedIds.contains(e.id))
           .toList();
-      // Fallback: if allItems is empty or no match, at least add the dragged item
       if (selectedItems.isEmpty) {
         selectedItems.add(item);
       }
@@ -3246,8 +3304,6 @@ class _QueueTabState extends ConsumerState<QueueTab> {
     );
   }
 
-  /// Build a compact floating feedback widget shown while dragging a track.
-  /// Shows the count when multiple tracks are selected and being dragged.
   Widget _buildDragFeedback(
     BuildContext context,
     UnifiedLibraryItem item,
@@ -3371,7 +3427,6 @@ class _QueueTabState extends ConsumerState<QueueTab> {
     final selectionItems = getFilterData(
       historyFilterMode,
     ).filteredUnifiedItems;
-    // Only sync overlays when selection mode is active
     if (_isSelectionMode || _isPlaylistSelectionMode) {
       WidgetsBinding.instance.addPostFrameCallback((_) {
         if (_isSelectionMode) {
@@ -3627,12 +3682,10 @@ class _QueueTabState extends ConsumerState<QueueTab> {
     if (filterMode == 'all') {
       localItemsForMerge = _filterLocalItems(localLibraryItems, query);
     } else {
-      final localSingles = localLibraryItems
-          .where((item) {
-            final count = localAlbumCounts[item.albumKey] ?? 0;
-            return count == 1;
-          })
-          .toList(growable: false);
+      final localSingles = _localSingleItems(
+        localLibraryItems,
+        localAlbumCounts,
+      );
       localItemsForMerge = _filterLocalItems(localSingles, query);
     }
 
@@ -3641,7 +3694,10 @@ class _QueueTabState extends ConsumerState<QueueTab> {
 
     final dedupedUnifiedLocal = <UnifiedLibraryItem>[];
     for (final item in unifiedLocal) {
-      final localPathKeys = buildPathMatchKeys(item.filePath);
+      final localSource = item.localItem;
+      final localPathKeys = localSource != null
+          ? _localPathMatchKeys(localSource)
+          : buildPathMatchKeys(item.filePath);
       final overlapsDownloaded = localPathKeys.any(downloadedPathKeys.contains);
       if (!overlapsDownloaded) {
         dedupedUnifiedLocal.add(item);
@@ -3776,7 +3832,6 @@ class _QueueTabState extends ConsumerState<QueueTab> {
     );
   }
 
-  /// Build a Spotify-style collection list item (Wishlist, Loved, Playlists)
   Widget _buildCollectionListItem({
     required BuildContext context,
     required ColorScheme colorScheme,
@@ -3853,7 +3908,6 @@ class _QueueTabState extends ConsumerState<QueueTab> {
     );
   }
 
-  /// Build a collection grid item for grid view mode
   Widget _buildCollectionGridItem({
     required BuildContext context,
     required ColorScheme colorScheme,
@@ -3936,7 +3990,6 @@ class _QueueTabState extends ConsumerState<QueueTab> {
     return entries;
   }
 
-  /// Build a collection item for the unified "All" tab grid view.
   Widget _buildAllTabGridCollectionItem({
     required BuildContext context,
     required ColorScheme colorScheme,
@@ -4054,7 +4107,6 @@ class _QueueTabState extends ConsumerState<QueueTab> {
     }
   }
 
-  /// Build a collection item for the unified "All" tab list view.
   Widget _buildAllTabListCollectionItem({
     required BuildContext context,
     required ColorScheme colorScheme,
@@ -4207,8 +4259,6 @@ class _QueueTabState extends ConsumerState<QueueTab> {
             ),
           ),
 
-        // Collection folders as list items (Spotify-style) in "All" tab
-        // are now rendered inline with tracks below (unified sliver)
         if ((filteredGroupedAlbums.isNotEmpty ||
                 filteredGroupedLocalAlbums.isNotEmpty) &&
             filterMode == 'albums')
@@ -4695,7 +4745,6 @@ class _QueueTabState extends ConsumerState<QueueTab> {
     );
   }
 
-  /// Album grid item for local library albums
   Widget _buildLocalAlbumGridItem(
     BuildContext context,
     _GroupedLocalAlbum album,
@@ -4913,12 +4962,14 @@ class _QueueTabState extends ConsumerState<QueueTab> {
         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(
@@ -4926,6 +4977,7 @@ class _QueueTabState extends ConsumerState<QueueTab> {
         coverPath: effectiveCoverPath,
         metadata: metadata,
         artistTagMode: artistTagMode,
+        preserveMetadata: true,
       );
     }
 
@@ -4958,7 +5010,10 @@ class _QueueTabState extends ConsumerState<QueueTab> {
     return ffmpegResult != null;
   }
 
-  Future<bool> _reEnrichQueueLocalTrack(LocalLibraryItem item) async {
+  Future<bool> _reEnrichQueueLocalTrack(
+    LocalLibraryItem item, {
+    List<String>? updateFields,
+  }) async {
     final durationMs = (item.duration ?? 0) * 1000;
     final artistTagMode = ref.read(settingsProvider).artistTagMode;
     final request = <String, dynamic>{
@@ -4981,6 +5036,8 @@ class _QueueTabState extends ConsumerState<QueueTab> {
       'copyright': '',
       'duration_ms': durationMs,
       'search_online': true,
+      // ignore: use_null_aware_elements
+      if (updateFields != null) 'update_fields': updateFields,
     };
 
     final result = await PlatformBridge.reEnrichFile(request);
@@ -5144,31 +5201,25 @@ class _QueueTabState extends ConsumerState<QueueTab> {
       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(selectedLocalItems.length)}',
-        ),
-        actions: [
-          TextButton(
-            onPressed: () => Navigator.pop(ctx, false),
-            child: Text(context.l10n.dialogCancel),
-          ),
-          FilledButton(
-            onPressed: () => Navigator.pop(ctx, true),
-            child: Text(context.l10n.trackReEnrich),
-          ),
-        ],
-      ),
+    // Hide the selection overlay: set the flag (prevents build() from
+    // re-inserting via postFrameCallback) and remove the entry immediately.
+    setState(() => _isSelectionMode = false);
+    _hideSelectionOverlay();
+
+    final selection = await showReEnrichFieldDialog(
+      context,
+      selectedCount: selectedLocalItems.length,
     );
 
-    if (confirmed != true || !mounted) {
+    if (selection == null || !mounted) {
+      // Cancelled — restore selection mode; the next build cycle will
+      // re-create the overlay via _syncSelectionOverlay in postFrameCallback.
+      if (mounted) setState(() => _isSelectionMode = true);
       return;
     }
 
+    final updateFields = selection.isAll ? null : selection.fields;
+
     var successCount = 0;
     final total = selectedLocalItems.length;
 
@@ -5194,7 +5245,10 @@ class _QueueTabState extends ConsumerState<QueueTab> {
       );
 
       try {
-        final ok = await _reEnrichQueueLocalTrack(item);
+        final ok = await _reEnrichQueueLocalTrack(
+          item,
+          updateFields: updateFields,
+        );
         if (ok) {
           successCount++;
         }
@@ -5269,7 +5323,6 @@ class _QueueTabState extends ConsumerState<QueueTab> {
       return;
     }
 
-    // Share SAF content URIs via native intent
     if (safUris.isNotEmpty) {
       try {
         if (safUris.length == 1) {
@@ -5280,7 +5333,6 @@ class _QueueTabState extends ConsumerState<QueueTab> {
       } catch (_) {}
     }
 
-    // Share regular files via SharePlus
     if (filesToShare.isNotEmpty) {
       await SharePlus.instance.share(ShareParams(files: filesToShare));
     }
@@ -6394,7 +6446,6 @@ class _QueueTabState extends ConsumerState<QueueTab> {
     }
   }
 
-  /// Reusable filter button with badge showing active filter count.
   Widget _buildFilterButton(
     BuildContext context,
     List<UnifiedLibraryItem> unifiedItems,
@@ -6489,7 +6540,6 @@ class _QueueTabState extends ConsumerState<QueueTab> {
       }
     }
 
-    // Network URL cover (downloaded items)
     if (item.coverUrl != null) {
       return ClipRRect(
         borderRadius: BorderRadius.circular(8),
@@ -6507,7 +6557,6 @@ class _QueueTabState extends ConsumerState<QueueTab> {
       );
     }
 
-    // Local file cover (from library scan)
     if (item.localCoverPath != null && item.localCoverPath!.isNotEmpty) {
       return ClipRRect(
         borderRadius: BorderRadius.circular(8),
@@ -6524,7 +6573,6 @@ class _QueueTabState extends ConsumerState<QueueTab> {
       );
     }
 
-    // Placeholder (no cover)
     if (size != null) {
       return buildPlaceholder();
     }
@@ -6534,7 +6582,6 @@ class _QueueTabState extends ConsumerState<QueueTab> {
     );
   }
 
-  /// Build a unified library item (merged downloaded + local)
   Widget _buildUnifiedLibraryItem(
     BuildContext context,
     UnifiedLibraryItem item,
@@ -6742,7 +6789,6 @@ class _QueueTabState extends ConsumerState<QueueTab> {
     );
   }
 
-  /// Build unified grid item for grid view mode
   Widget _buildUnifiedGridItem(
     BuildContext context,
     UnifiedLibraryItem item,
@@ -7032,7 +7078,6 @@ class _FilterChip extends StatelessWidget {
   }
 }
 
-/// Reusable action button for selection mode bottom bar
 class _SelectionActionButton extends StatelessWidget {
   final IconData icon;
   final String label;

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) {
@@ -467,7 +452,6 @@ class _LibrarySettingsPageState extends ConsumerState<LibrarySettingsPage> {
             ),
           ),
 
-          // Scan Actions Section
           if (settings.localLibraryEnabled) ...[
             SliverToBoxAdapter(
               child: SettingsSectionHeader(title: context.l10n.libraryActions),

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

@@ -70,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(
@@ -143,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,
                   ),
                 ],
@@ -706,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'};
 
@@ -770,7 +773,6 @@ class _MetadataSourceSelector extends ConsumerWidget {
                   if (hasNonDefaultProvider) {
                     ref.read(settingsProvider.notifier).setSearchProvider(null);
                   }
-                  onChanged('deezer');
                 },
               ),
               const SizedBox(width: 8),
@@ -782,7 +784,6 @@ class _MetadataSourceSelector extends ConsumerWidget {
                   ref
                       .read(settingsProvider.notifier)
                       .setSearchProvider('tidal');
-                  onChanged('tidal');
                 },
               ),
               const SizedBox(width: 8),
@@ -794,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/track_metadata_screen.dart

@@ -22,6 +22,7 @@ import 'package:spotiflac_android/l10n/l10n.dart';
 import 'package:spotiflac_android/utils/logger.dart';
 import 'package:spotiflac_android/utils/lyrics_metadata_helper.dart';
 import 'package:spotiflac_android/utils/mime_utils.dart';
+import 'package:spotiflac_android/utils/image_cache_utils.dart';
 import 'package:spotiflac_android/utils/string_utils.dart';
 import 'package:spotiflac_android/widgets/audio_analysis_widget.dart';
 
@@ -29,11 +30,11 @@ final _log = AppLogger('TrackMetadata');
 
 class _EmbeddedCoverPreviewCacheEntry {
   final String previewPath;
-  final int? fileModTime;
+  final String? sourceValidationToken;
 
   const _EmbeddedCoverPreviewCacheEntry({
     required this.previewPath,
-    this.fileModTime,
+    this.sourceValidationToken,
   });
 }
 
@@ -69,6 +70,7 @@ class _TrackMetadataScreenState extends ConsumerState<TrackMetadataScreen> {
   bool _lyricsEmbedded = false;
   bool _isEmbedding = false;
   bool _isInstrumental = false;
+  bool _embeddedLyricsChecked = false;
   bool _isConverting = false;
   bool _hasMetadataChanges = false;
   bool _hasLoadedResolvedAudioMetadata = false;
@@ -118,70 +120,75 @@ class _TrackMetadataScreenState extends ConsumerState<TrackMetadataScreen> {
     );
   }
 
-  int? _readLocalFileModTimeMsSync(String path) {
+  Future<String?> _readLocalFileValidationToken(String path) async {
     if (path.isEmpty || isContentUri(path) || _isVolatileSafTempPath(path)) {
       return null;
     }
     try {
-      return File(path).statSync().modified.millisecondsSinceEpoch;
+      final stat = await fileStat(path);
+      if (stat == null) return null;
+      return '${stat.modified?.millisecondsSinceEpoch ?? 0}:${stat.size ?? 0}';
     } catch (_) {
       return null;
     }
   }
 
-  void _cacheEmbeddedCoverPreview(
+  Future<void> _cacheEmbeddedCoverPreview(
     String cacheKey,
     String sourcePath,
     String previewPath,
-  ) {
-    final fileModTime = _readLocalFileModTimeMsSync(sourcePath);
+  ) async {
+    final sourceValidationToken = await _readLocalFileValidationToken(
+      sourcePath,
+    );
     final existing = _embeddedCoverPreviewCache[cacheKey];
     _embeddedCoverPreviewCache[cacheKey] = _EmbeddedCoverPreviewCacheEntry(
       previewPath: previewPath,
-      fileModTime: fileModTime,
+      sourceValidationToken: sourceValidationToken,
     );
     if (existing != null && existing.previewPath != previewPath) {
-      _cleanupTempFileAndParentSyncIfNotCached(existing.previewPath);
+      await _cleanupTempFileAndParentIfNotCached(existing.previewPath);
     }
 
     while (_embeddedCoverPreviewCache.length > _maxCoverPreviewCacheEntries) {
       final oldestKey = _embeddedCoverPreviewCache.keys.first;
       final removed = _embeddedCoverPreviewCache.remove(oldestKey);
       if (removed != null) {
-        _cleanupTempFileAndParentSyncIfNotCached(removed.previewPath);
+        await _cleanupTempFileAndParentIfNotCached(removed.previewPath);
       }
     }
   }
 
-  void _invalidateEmbeddedCoverPreviewCacheForPath(String cacheKey) {
+  Future<void> _invalidateEmbeddedCoverPreviewCacheForPath(
+    String cacheKey,
+  ) async {
     if (cacheKey.isEmpty) return;
     final removed = _embeddedCoverPreviewCache.remove(cacheKey);
     if (removed != null) {
-      _cleanupTempFileAndParentSyncIfNotCached(removed.previewPath);
+      await _cleanupTempFileAndParentIfNotCached(removed.previewPath);
     }
   }
 
-  String? _getCachedEmbeddedCoverPreviewPathIfValid(
+  Future<String?> _getCachedEmbeddedCoverPreviewPathIfValid(
     String cacheKey,
     String sourcePath,
-  ) {
+  ) async {
     if (cacheKey.isEmpty) return null;
     final cached = _embeddedCoverPreviewCache[cacheKey];
     if (cached == null) return null;
 
-    final previewFile = File(cached.previewPath);
-    if (!previewFile.existsSync()) {
+    if (!await fileExists(cached.previewPath)) {
       _embeddedCoverPreviewCache.remove(cacheKey);
       return null;
     }
 
     if (!isContentUri(sourcePath) && !_isVolatileSafTempPath(sourcePath)) {
-      final currentModTime = _readLocalFileModTimeMsSync(sourcePath);
-      if (currentModTime != null &&
-          cached.fileModTime != null &&
-          currentModTime != cached.fileModTime) {
+      final currentToken = await _readLocalFileValidationToken(sourcePath);
+      if (currentToken != null &&
+          cached.sourceValidationToken != null &&
+          currentToken != cached.sourceValidationToken) {
         _embeddedCoverPreviewCache.remove(cacheKey);
-        _cleanupTempFileAndParentSyncIfNotCached(cached.previewPath);
+        await _cleanupTempFileAndParentIfNotCached(cached.previewPath);
         return null;
       }
     }
@@ -198,7 +205,7 @@ class _TrackMetadataScreenState extends ConsumerState<TrackMetadataScreen> {
 
   @override
   void dispose() {
-    _cleanupTempFileAndParentSyncIfNotCached(_embeddedCoverPreviewPath);
+    unawaited(_cleanupTempFileAndParentIfNotCached(_embeddedCoverPreviewPath));
     _scrollController.removeListener(_onScroll);
     _scrollController.dispose();
     super.dispose();
@@ -241,7 +248,7 @@ class _TrackMetadataScreenState extends ConsumerState<TrackMetadataScreen> {
     }
 
     if (mounted && exists && _lyrics == null && !_lyricsLoading) {
-      _fetchLyrics();
+      _checkEmbeddedLyrics();
     }
     if (mounted &&
         exists &&
@@ -250,7 +257,7 @@ class _TrackMetadataScreenState extends ConsumerState<TrackMetadataScreen> {
       unawaited(_refreshResolvedAudioMetadataFromFile());
     }
     if (mounted && exists && !_hasPath(_embeddedCoverPreviewPath)) {
-      final cachedPath = _getCachedEmbeddedCoverPreviewPathIfValid(
+      final cachedPath = await _getCachedEmbeddedCoverPreviewPathIfValid(
         _coverCacheKey,
         cleanFilePath,
       );
@@ -317,6 +324,19 @@ class _TrackMetadataScreenState extends ConsumerState<TrackMetadataScreen> {
           resolvedDuration > 0 &&
           (duration == null || duration == 0);
 
+      // Resolve label/copyright from file when the model doesn't carry them
+      // (e.g. local library items, or download history items without these fields).
+      final resolvedLabel = metadata['label']?.toString();
+      final resolvedCopyright = metadata['copyright']?.toString();
+      final needsLabel =
+          resolvedLabel != null &&
+          resolvedLabel.isNotEmpty &&
+          (label == null || label!.isEmpty);
+      final needsCopyright =
+          resolvedCopyright != null &&
+          resolvedCopyright.isNotEmpty &&
+          (copyright == null || copyright!.isEmpty);
+
       final shouldPersistResolvedAudioMetadata =
           resolvedBitDepth != null ||
           resolvedSampleRate != null ||
@@ -326,15 +346,21 @@ class _TrackMetadataScreenState extends ConsumerState<TrackMetadataScreen> {
               resolvedSampleRate != null ||
               needsAlbum ||
               needsDuration ||
+              needsLabel ||
+              needsCopyright ||
               isPlaceholderQualityLabel(_quality)) &&
           mounted) {
         setState(() {
           _editedMetadata = {
             ...?_editedMetadata,
+            // ignore: use_null_aware_elements
             if (resolvedBitDepth != null) 'bit_depth': resolvedBitDepth,
+            // ignore: use_null_aware_elements
             if (resolvedSampleRate != null) 'sample_rate': resolvedSampleRate,
             if (needsAlbum) 'album': resolvedAlbum,
             if (needsDuration) 'duration': resolvedDuration,
+            if (needsLabel) 'label': resolvedLabel,
+            if (needsCopyright) 'copyright': resolvedCopyright,
           };
         });
       }
@@ -354,32 +380,11 @@ class _TrackMetadataScreenState extends ConsumerState<TrackMetadataScreen> {
     }
   }
 
-  void _cleanupTempFileAndParentSync(String? path) {
-    if (!_hasPath(path)) return;
-    final file = File(path!);
-    try {
-      if (file.existsSync()) {
-        file.deleteSync();
-      }
-    } catch (_) {}
-    try {
-      final dir = file.parent;
-      if (dir.existsSync()) {
-        dir.deleteSync(recursive: true);
-      }
-    } catch (_) {}
-  }
-
-  void _cleanupTempFileAndParentSyncIfNotCached(String? path) {
-    if (_isCacheTrackedPath(path)) return;
-    _cleanupTempFileAndParentSync(path);
-  }
-
   Future<void> _refreshEmbeddedCoverPreview({bool force = false}) async {
     final cacheKey = _coverCacheKey;
     final sourcePath = cleanFilePath;
     if (!force) {
-      final cachedPath = _getCachedEmbeddedCoverPreviewPathIfValid(
+      final cachedPath = await _getCachedEmbeddedCoverPreviewPathIfValid(
         cacheKey,
         sourcePath,
       );
@@ -394,7 +399,7 @@ class _TrackMetadataScreenState extends ConsumerState<TrackMetadataScreen> {
     String? newPreviewPath;
     try {
       if (!_fileExists) {
-        _invalidateEmbeddedCoverPreviewCacheForPath(cacheKey);
+        await _invalidateEmbeddedCoverPreviewCacheForPath(cacheKey);
         await _cleanupTempFileAndParentIfNotCached(_embeddedCoverPreviewPath);
         if (mounted) {
           setState(() => _embeddedCoverPreviewPath = null);
@@ -402,7 +407,7 @@ class _TrackMetadataScreenState extends ConsumerState<TrackMetadataScreen> {
         return;
       }
       if (force) {
-        _invalidateEmbeddedCoverPreviewCacheForPath(cacheKey);
+        await _invalidateEmbeddedCoverPreviewCacheForPath(cacheKey);
       }
       final tempDir = await Directory.systemTemp.createTemp(
         'track_cover_preview_',
@@ -415,7 +420,7 @@ class _TrackMetadataScreenState extends ConsumerState<TrackMetadataScreen> {
       );
       if (result['error'] == null && await File(outputPath).exists()) {
         newPreviewPath = outputPath;
-        _cacheEmbeddedCoverPreview(cacheKey, sourcePath, outputPath);
+        await _cacheEmbeddedCoverPreview(cacheKey, sourcePath, outputPath);
       } else {
         try {
           await tempDir.delete(recursive: true);
@@ -491,9 +496,22 @@ class _TrackMetadataScreenState extends ConsumerState<TrackMetadataScreen> {
       (_isLocalItem
           ? _localLibraryItem!.releaseDate
           : _downloadItem!.releaseDate);
-  String? get isrc =>
-      _editedMetadata?['isrc']?.toString() ??
-      (_isLocalItem ? _localLibraryItem!.isrc : _downloadItem!.isrc);
+  String? get isrc {
+    final raw =
+        _editedMetadata?['isrc']?.toString() ??
+        (_isLocalItem ? _localLibraryItem!.isrc : _downloadItem!.isrc);
+    if (raw == null || raw.trim().isEmpty) return null;
+    final upper = raw.trim().toUpperCase();
+    // Only accept valid ISRC codes (CC-XXX-YY-NNNNN, 12 alphanumeric chars).
+    // Strip hyphens/spaces that some sources include.
+    final stripped = upper.replaceAll(RegExp(r'[-\s]'), '');
+    if (_isrcValidationPattern.hasMatch(stripped)) return stripped;
+    return null;
+  }
+
+  static final RegExp _isrcValidationPattern = RegExp(
+    r'^[A-Z]{2}[A-Z0-9]{3}\d{7}$',
+  );
   String? get genre =>
       _editedMetadata?['genre']?.toString() ??
       (_isLocalItem ? _localLibraryItem!.genre : _downloadItem!.genre);
@@ -550,6 +568,59 @@ class _TrackMetadataScreenState extends ConsumerState<TrackMetadataScreen> {
     return parsed;
   }
 
+  String _displayServiceTrackId(String value) {
+    final raw = value.trim();
+    if (raw.isEmpty) return raw;
+    final spotifyTrackIdPattern = RegExp(r'^[A-Za-z0-9]{22}$');
+
+    if (raw.startsWith('deezer:')) return raw.substring('deezer:'.length);
+    if (raw.startsWith('tidal:')) return raw.substring('tidal:'.length);
+    if (raw.startsWith('qobuz:')) return raw.substring('qobuz:'.length);
+    if (spotifyTrackIdPattern.hasMatch(raw)) return raw;
+
+    if (raw.startsWith('spotify:')) {
+      final last = raw.split(':').last.trim();
+      if (spotifyTrackIdPattern.hasMatch(last)) return last;
+      return raw;
+    }
+
+    final uri = Uri.tryParse(raw);
+    if (uri != null &&
+        uri.host.contains('spotify.com') &&
+        uri.pathSegments.length >= 2 &&
+        uri.pathSegments.first == 'track') {
+      final candidate = uri.pathSegments[1].trim();
+      if (spotifyTrackIdPattern.hasMatch(candidate)) {
+        return candidate;
+      }
+    }
+
+    return raw;
+  }
+
+  String _serviceForTrackId(String value, {required String fallbackService}) {
+    final raw = value.trim();
+    if (raw.isEmpty) return fallbackService;
+    final spotifyTrackIdPattern = RegExp(r'^[A-Za-z0-9]{22}$');
+
+    if (raw.startsWith('deezer:')) return 'deezer';
+    if (raw.startsWith('tidal:')) return 'tidal';
+    if (raw.startsWith('qobuz:')) return 'qobuz';
+    if (raw.startsWith('spotify:')) return 'spotify';
+    if (spotifyTrackIdPattern.hasMatch(raw)) return 'spotify';
+
+    final uri = Uri.tryParse(raw);
+    if (uri != null) {
+      final host = uri.host.toLowerCase();
+      if (host.contains('spotify.com')) return 'spotify';
+      if (host.contains('deezer.com')) return 'deezer';
+      if (host.contains('tidal.com')) return 'tidal';
+      if (host.contains('qobuz.com')) return 'qobuz';
+    }
+
+    return fallbackService;
+  }
+
   String? get _displayAudioQuality {
     final fileName = _extractFileNameFromPathOrUri(cleanFilePath);
     final fileExt = fileName.contains('.')
@@ -794,16 +865,21 @@ class _TrackMetadataScreenState extends ConsumerState<TrackMetadataScreen> {
     double expandedHeight,
     bool showContent,
   ) {
+    final cacheWidth = coverCacheWidthForViewport(context);
     final coverChild = _hasPath(_embeddedCoverPreviewPath)
         ? Image.file(
             File(_embeddedCoverPreviewPath!),
             fit: BoxFit.cover,
+            cacheWidth: cacheWidth,
+            gaplessPlayback: true,
+            filterQuality: FilterQuality.low,
             errorBuilder: (_, _, _) => Container(color: colorScheme.surface),
           )
         : _coverUrl != null
         ? CachedNetworkImage(
             imageUrl: _coverUrl!,
             fit: BoxFit.cover,
+            memCacheWidth: cacheWidth,
             cacheManager: CoverCacheManager.instance,
             placeholder: (_, _) => Container(color: colorScheme.surface),
             errorWidget: (_, _, _) => Container(color: colorScheme.surface),
@@ -812,6 +888,9 @@ class _TrackMetadataScreenState extends ConsumerState<TrackMetadataScreen> {
         ? Image.file(
             File(_localCoverPath!),
             fit: BoxFit.cover,
+            cacheWidth: cacheWidth,
+            gaplessPlayback: true,
+            filterQuality: FilterQuality.low,
             errorBuilder: (_, _, _) => Container(color: colorScheme.surface),
           )
         : Container(
@@ -1060,16 +1139,18 @@ class _TrackMetadataScreenState extends ConsumerState<TrackMetadataScreen> {
               const SizedBox(height: 8),
               Builder(
                 builder: (context) {
-                  final isDeezer = _spotifyId!.contains('deezer');
-                  final svc = _service.toLowerCase();
+                  final openService = _serviceForTrackId(
+                    _spotifyId!,
+                    fallbackService: _service.toLowerCase(),
+                  );
                   String buttonLabel;
-                  if (isDeezer) {
+                  if (openService == 'deezer') {
                     buttonLabel = context.l10n.trackOpenInDeezer;
-                  } else if (svc == 'amazon') {
+                  } else if (openService == 'amazon') {
                     buttonLabel = 'Open in Amazon Music';
-                  } else if (svc == 'tidal') {
+                  } else if (openService == 'tidal') {
                     buttonLabel = 'Open in Tidal';
-                  } else if (svc == 'qobuz') {
+                  } else if (openService == 'qobuz') {
                     buttonLabel = 'Open in Qobuz';
                   } else {
                     buttonLabel = context.l10n.trackOpenInSpotify;
@@ -1100,27 +1181,29 @@ class _TrackMetadataScreenState extends ConsumerState<TrackMetadataScreen> {
   Future<void> _openServiceUrl(BuildContext context) async {
     if (_spotifyId == null) return;
 
-    final isDeezer = _spotifyId!.contains('deezer');
-    final rawId = _spotifyId!.replaceAll('deezer:', '');
-    final svc = _service.toLowerCase();
+    final openService = _serviceForTrackId(
+      _spotifyId!,
+      fallbackService: _service.toLowerCase(),
+    );
+    final rawId = _displayServiceTrackId(_spotifyId!);
 
     String webUrl;
     Uri? appUri;
     String serviceName;
 
-    if (isDeezer) {
+    if (openService == 'deezer') {
       webUrl = 'https://www.deezer.com/track/$rawId';
       appUri = Uri.parse('deezer://www.deezer.com/track/$rawId');
       serviceName = 'Deezer';
-    } else if (svc == 'amazon') {
+    } else if (openService == 'amazon') {
       webUrl = 'https://music.amazon.com/search/$rawId';
       appUri = Uri.parse('amznm://search/$rawId');
       serviceName = 'Amazon Music';
-    } else if (svc == 'tidal') {
+    } else if (openService == 'tidal') {
       webUrl = 'https://listen.tidal.com/track/$rawId';
       appUri = Uri.parse('tidal://track/$rawId');
       serviceName = 'Tidal';
-    } else if (svc == 'qobuz') {
+    } else if (openService == 'qobuz') {
       webUrl = 'https://play.qobuz.com/track/$rawId';
       appUri = Uri.parse('qobuz://track/$rawId');
       serviceName = 'Qobuz';
@@ -1190,22 +1273,23 @@ class _TrackMetadataScreenState extends ConsumerState<TrackMetadataScreen> {
     ];
 
     if (!_isLocalItem && _spotifyId != null && _spotifyId!.isNotEmpty) {
-      final isDeezer = _spotifyId!.contains('deezer');
-      final cleanId = _spotifyId!.replaceAll('deezer:', '');
+      final idService = _serviceForTrackId(
+        _spotifyId!,
+        fallbackService: _service.toLowerCase(),
+      );
+      final cleanId = _displayServiceTrackId(_spotifyId!);
       String idLabel;
-      if (isDeezer) {
-        idLabel = 'Deezer ID';
-      } else {
-        switch (_service.toLowerCase()) {
-          case 'amazon':
-            idLabel = 'Amazon ASIN';
-          case 'tidal':
-            idLabel = 'Tidal ID';
-          case 'qobuz':
-            idLabel = 'Qobuz ID';
-          default:
-            idLabel = 'Spotify ID';
-        }
+      switch (idService) {
+        case 'deezer':
+          idLabel = 'Deezer ID';
+        case 'amazon':
+          idLabel = 'Amazon ASIN';
+        case 'tidal':
+          idLabel = 'Tidal ID';
+        case 'qobuz':
+          idLabel = 'Qobuz ID';
+        default:
+          idLabel = 'Spotify ID';
       }
       items.add(_MetadataItem(idLabel, cleanId));
     }
@@ -1574,7 +1658,7 @@ class _TrackMetadataScreenState extends ConsumerState<TrackMetadataScreen> {
                       ),
                     ),
                     TextButton(
-                      onPressed: _fetchLyrics,
+                      onPressed: _fetchOnlineLyrics,
                       child: Text(context.l10n.dialogRetry),
                     ),
                   ],
@@ -1642,6 +1726,46 @@ class _TrackMetadataScreenState extends ConsumerState<TrackMetadataScreen> {
                   ],
                 ],
               )
+            else if (_embeddedLyricsChecked && _fileExists)
+              Column(
+                children: [
+                  Container(
+                    padding: const EdgeInsets.all(16),
+                    decoration: BoxDecoration(
+                      color: colorScheme.surfaceContainerHighest.withValues(
+                        alpha: 0.5,
+                      ),
+                      borderRadius: BorderRadius.circular(12),
+                    ),
+                    child: Row(
+                      children: [
+                        Icon(
+                          Icons.lyrics_outlined,
+                          color: colorScheme.onSurfaceVariant,
+                          size: 20,
+                        ),
+                        const SizedBox(width: 12),
+                        Expanded(
+                          child: Text(
+                            context.l10n.trackLyricsNotInFile,
+                            style: TextStyle(
+                              color: colorScheme.onSurfaceVariant,
+                            ),
+                          ),
+                        ),
+                      ],
+                    ),
+                  ),
+                  const SizedBox(height: 12),
+                  Center(
+                    child: FilledButton.tonalIcon(
+                      onPressed: _fetchOnlineLyrics,
+                      icon: const Icon(Icons.cloud_download_outlined),
+                      label: Text(context.l10n.trackFetchOnlineLyrics),
+                    ),
+                  ),
+                ],
+              )
             else
               Center(
                 child: FilledButton.tonalIcon(
@@ -1656,6 +1780,134 @@ class _TrackMetadataScreenState extends ConsumerState<TrackMetadataScreen> {
     );
   }
 
+  /// Check for lyrics embedded in the audio file only (no network requests).
+  /// Called automatically when the screen opens.
+  Future<void> _checkEmbeddedLyrics() async {
+    if (_lyricsLoading || !_fileExists) return;
+
+    setState(() {
+      _lyricsLoading = true;
+      _lyricsError = null;
+      _isInstrumental = false;
+      _lyricsSource = null;
+    });
+
+    try {
+      final embeddedResult =
+          await PlatformBridge.getLyricsLRCWithSource(
+            '',
+            trackName,
+            artistName,
+            filePath: cleanFilePath,
+            durationMs: 0,
+          ).timeout(
+            const Duration(seconds: 5),
+            onTimeout: () => <String, dynamic>{'lyrics': '', 'source': ''},
+          );
+
+      final embeddedLyrics = embeddedResult['lyrics']?.toString() ?? '';
+      final embeddedSource = embeddedResult['source']?.toString() ?? '';
+
+      if (mounted) {
+        if (embeddedLyrics.isNotEmpty) {
+          final cleanLyrics = _cleanLrcForDisplay(embeddedLyrics);
+          setState(() {
+            _lyrics = cleanLyrics;
+            _rawLyrics = embeddedLyrics;
+            _lyricsSource = embeddedSource.isNotEmpty
+                ? embeddedSource
+                : 'Embedded';
+            _lyricsEmbedded = true;
+            _lyricsLoading = false;
+            _embeddedLyricsChecked = true;
+          });
+        } else {
+          setState(() {
+            _lyricsLoading = false;
+            _embeddedLyricsChecked = true;
+          });
+        }
+      }
+    } catch (e) {
+      if (mounted) {
+        setState(() {
+          _lyricsLoading = false;
+          _embeddedLyricsChecked = true;
+        });
+      }
+    }
+  }
+
+  /// Fetch lyrics from online providers. Only called by user action.
+  Future<void> _fetchOnlineLyrics() async {
+    if (_lyricsLoading) return;
+
+    setState(() {
+      _lyricsLoading = true;
+      _lyricsError = null;
+      _isInstrumental = false;
+      _lyricsSource = null;
+    });
+
+    try {
+      final durationMs = (duration ?? 0) * 1000;
+
+      final result = await PlatformBridge.getLyricsLRCWithSource(
+        _spotifyId ?? '',
+        trackName,
+        artistName,
+        filePath: null,
+        durationMs: durationMs,
+      ).timeout(const Duration(seconds: 20));
+
+      final lrcText = result['lyrics']?.toString() ?? '';
+      final source = result['source']?.toString() ?? '';
+      final instrumental =
+          (result['instrumental'] as bool? ?? false) ||
+          lrcText == '[instrumental:true]';
+
+      if (mounted) {
+        if (instrumental) {
+          setState(() {
+            _isInstrumental = true;
+            _lyricsSource = source.isNotEmpty ? source : null;
+            _lyricsLoading = false;
+          });
+        } else if (lrcText.isEmpty) {
+          setState(() {
+            _lyricsError = context.l10n.trackLyricsNotAvailable;
+            _lyricsLoading = false;
+          });
+        } else {
+          final cleanLyrics = _cleanLrcForDisplay(lrcText);
+          setState(() {
+            _lyrics = cleanLyrics;
+            _rawLyrics = lrcText;
+            _lyricsSource = source.isNotEmpty ? source : null;
+            _lyricsEmbedded = false;
+            _lyricsLoading = false;
+          });
+        }
+      }
+    } on TimeoutException {
+      if (mounted) {
+        setState(() {
+          _lyricsError = context.l10n.trackLyricsTimeout;
+          _lyricsLoading = false;
+        });
+      }
+    } catch (e) {
+      if (mounted) {
+        setState(() {
+          _lyricsError = context.l10n.trackLyricsLoadFailed;
+          _lyricsLoading = false;
+        });
+      }
+    }
+  }
+
+  /// Full lyrics fetch: check embedded first, then online.
+  /// Used by the "Load Lyrics" button when file doesn't exist (non-local items).
   Future<void> _fetchLyrics() async {
     if (_lyricsLoading) return;
 
@@ -1696,6 +1948,7 @@ class _TrackMetadataScreenState extends ConsumerState<TrackMetadataScreen> {
                   : 'Embedded';
               _lyricsEmbedded = true;
               _lyricsLoading = false;
+              _embeddedLyricsChecked = true;
             });
           }
           return;
@@ -1950,23 +2203,34 @@ class _TrackMetadataScreenState extends ConsumerState<TrackMetadataScreen> {
       final baseName = _buildSaveBaseName();
 
       if (_isSafFile) {
-        // SAF file: save to temp, then copy to SAF tree
         final tempDir = await Directory.systemTemp.createTemp('cover_');
         final tempOutput =
             '${tempDir.path}${Platform.pathSeparator}$baseName.jpg';
 
         Map<String, dynamic> result;
-        if (_coverUrl != null && _coverUrl!.isNotEmpty) {
+        if (_fileExists) {
+          // Prefer extracting cover from the already-downloaded file to avoid
+          // a redundant network request.
+          result = await PlatformBridge.extractCoverToFile(
+            cleanFilePath,
+            tempOutput,
+          );
+          // Fall back to downloading from URL if extraction failed.
+          if (result['error'] != null &&
+              _coverUrl != null &&
+              _coverUrl!.isNotEmpty) {
+            result = await PlatformBridge.downloadCoverToFile(
+              _coverUrl!,
+              tempOutput,
+              maxQuality: true,
+            );
+          }
+        } else if (_coverUrl != null && _coverUrl!.isNotEmpty) {
           result = await PlatformBridge.downloadCoverToFile(
             _coverUrl!,
             tempOutput,
             maxQuality: true,
           );
-        } else if (_fileExists) {
-          result = await PlatformBridge.extractCoverToFile(
-            cleanFilePath,
-            tempOutput,
-          );
         } else {
           if (mounted) {
             ScaffoldMessenger.of(context).showSnackBar(
@@ -2021,7 +2285,6 @@ class _TrackMetadataScreenState extends ConsumerState<TrackMetadataScreen> {
             }
           }
         } else {
-          // No SAF tree info, keep in temp
           try {
             await Directory(tempDir.path).delete(recursive: true);
           } catch (_) {}
@@ -2042,17 +2305,29 @@ class _TrackMetadataScreenState extends ConsumerState<TrackMetadataScreen> {
       final outputPath = '$dir${Platform.pathSeparator}$baseName.jpg';
 
       Map<String, dynamic> result;
-      if (_coverUrl != null && _coverUrl!.isNotEmpty) {
+      if (_fileExists) {
+        // Prefer extracting cover from the already-downloaded file to avoid
+        // a redundant network request.
+        result = await PlatformBridge.extractCoverToFile(
+          cleanFilePath,
+          outputPath,
+        );
+        // Fall back to downloading from URL if extraction failed.
+        if (result['error'] != null &&
+            _coverUrl != null &&
+            _coverUrl!.isNotEmpty) {
+          result = await PlatformBridge.downloadCoverToFile(
+            _coverUrl!,
+            outputPath,
+            maxQuality: true,
+          );
+        }
+      } else if (_coverUrl != null && _coverUrl!.isNotEmpty) {
         result = await PlatformBridge.downloadCoverToFile(
           _coverUrl!,
           outputPath,
           maxQuality: true,
         );
-      } else if (_fileExists) {
-        result = await PlatformBridge.extractCoverToFile(
-          cleanFilePath,
-          outputPath,
-        );
       } else {
         if (mounted) {
           ScaffoldMessenger.of(context).showSnackBar(
@@ -2110,6 +2385,7 @@ class _TrackMetadataScreenState extends ConsumerState<TrackMetadataScreen> {
           spotifyId: _spotifyId ?? '',
           durationMs: durationMs,
           outputPath: tempOutput,
+          audioFilePath: _fileExists ? cleanFilePath : '',
         );
 
         if (result['error'] != null) {
@@ -2194,6 +2470,7 @@ class _TrackMetadataScreenState extends ConsumerState<TrackMetadataScreen> {
         spotifyId: _spotifyId ?? '',
         durationMs: durationMs,
         outputPath: outputPath,
+        audioFilePath: _fileExists ? cleanFilePath : '',
       );
 
       if (mounted) {
@@ -3373,18 +3650,13 @@ class _TrackMetadataScreenState extends ConsumerState<TrackMetadataScreen> {
         for (final path in finalOutputPaths) {
           if (path.toLowerCase().endsWith('.flac')) {
             try {
-              final metadata = await PlatformBridge.readFileMetadata(path);
-              if (metadata['error'] == null) {
-                final fields = <String, String>{'cover_path': coverPath};
-                for (final entry in metadata.entries) {
-                  if (entry.key == 'error' || entry.value == null) continue;
-                  final v = entry.value.toString().trim();
-                  if (v.isNotEmpty) {
-                    fields[entry.key] = v;
-                  }
-                }
-                await PlatformBridge.editFileMetadata(path, fields);
-              }
+              // Only send the cover_path field — EditFlacFields uses
+              // field-presence semantics, so omitting artist/album_artist
+              // means those keys won't be rewritten.  This preserves any
+              // existing split artist Vorbis Comments.
+              await PlatformBridge.editFileMetadata(path, {
+                'cover_path': coverPath,
+              });
             } catch (e) {
               _log.w('Failed to embed cover to split track: $e');
             }
@@ -3823,6 +4095,11 @@ class _TrackMetadataScreenState extends ConsumerState<TrackMetadataScreen> {
                   } catch (e) {
                     debugPrint('Failed to delete file: $e');
                   }
+                  if (_localLibraryItem != null) {
+                    await ref
+                        .read(localLibraryProvider.notifier)
+                        .removeItem(_localLibraryItem!.id);
+                  }
                 }
               } else {
                 try {
@@ -4108,29 +4385,15 @@ class _EditMetadataSheetState extends State<_EditMetadataSheet> {
     } catch (_) {}
   }
 
-  void _cleanupSelectedCoverTempSync() {
-    final dirPath = _selectedCoverTempDir;
-    _selectedCoverPath = null;
-    _selectedCoverTempDir = null;
-    _selectedCoverName = null;
-    if (dirPath == null || dirPath.isEmpty) return;
-    try {
-      final dir = Directory(dirPath);
-      if (dir.existsSync()) {
-        dir.deleteSync(recursive: true);
-      }
-    } catch (_) {}
-  }
-
-  void _cleanupCurrentCoverTempSync() {
+  Future<void> _cleanupCurrentCoverTemp() async {
     final dirPath = _currentCoverTempDir;
     _currentCoverPath = null;
     _currentCoverTempDir = null;
     if (dirPath == null || dirPath.isEmpty) return;
     try {
       final dir = Directory(dirPath);
-      if (dir.existsSync()) {
-        dir.deleteSync(recursive: true);
+      if (await dir.exists()) {
+        await dir.delete(recursive: true);
       }
     } catch (_) {}
   }
@@ -4848,8 +5111,8 @@ class _EditMetadataSheetState extends State<_EditMetadataSheet> {
 
   @override
   void dispose() {
-    _cleanupSelectedCoverTempSync();
-    _cleanupCurrentCoverTempSync();
+    unawaited(_cleanupSelectedCoverTemp());
+    unawaited(_cleanupCurrentCoverTemp());
     _titleCtrl.dispose();
     _artistCtrl.dispose();
     _albumCtrl.dispose();
@@ -4906,7 +5169,6 @@ class _EditMetadataSheetState extends State<_EditMetadataSheet> {
       final method = result['method'] as String?;
 
       if (method == 'ffmpeg') {
-        // MP3/Opus: use FFmpeg to write metadata
         // For SAF files, Kotlin returns temp_path + saf_uri
         final tempPath = result['temp_path'] as String?;
         final safUri = result['saf_uri'] as String?;
@@ -4917,48 +5179,32 @@ class _EditMetadataSheetState extends State<_EditMetadataSheet> {
         final isOpus = lower.endsWith('.opus') || lower.endsWith('.ogg');
         final isM4A = lower.endsWith('.m4a') || lower.endsWith('.aac');
 
-        final vorbisMap = <String, String>{};
-        if (metadata['title']?.isNotEmpty == true) {
-          vorbisMap['TITLE'] = metadata['title']!;
-        }
-        if (metadata['artist']?.isNotEmpty == true) {
-          vorbisMap['ARTIST'] = metadata['artist']!;
-        }
-        if (metadata['album']?.isNotEmpty == true) {
-          vorbisMap['ALBUM'] = metadata['album']!;
-        }
-        if (metadata['album_artist']?.isNotEmpty == true) {
-          vorbisMap['ALBUMARTIST'] = metadata['album_artist']!;
-        }
-        if (metadata['date']?.isNotEmpty == true) {
-          vorbisMap['DATE'] = metadata['date']!;
-        }
-        if (metadata['track_number']?.isNotEmpty == true &&
-            metadata['track_number'] != '0') {
-          vorbisMap['TRACKNUMBER'] = metadata['track_number']!;
-        }
-        if (metadata['disc_number']?.isNotEmpty == true &&
-            metadata['disc_number'] != '0') {
-          vorbisMap['DISCNUMBER'] = metadata['disc_number']!;
-        }
-        if (metadata['genre']?.isNotEmpty == true) {
-          vorbisMap['GENRE'] = metadata['genre']!;
-        }
-        if (metadata['isrc']?.isNotEmpty == true) {
-          vorbisMap['ISRC'] = metadata['isrc']!;
-        }
-        if (metadata['label']?.isNotEmpty == true) {
-          vorbisMap['ORGANIZATION'] = metadata['label']!;
-        }
-        if (metadata['copyright']?.isNotEmpty == true) {
-          vorbisMap['COPYRIGHT'] = metadata['copyright']!;
-        }
-        if (metadata['composer']?.isNotEmpty == true) {
-          vorbisMap['COMPOSER'] = metadata['composer']!;
-        }
-        if (metadata['comment']?.isNotEmpty == true) {
-          vorbisMap['COMMENT'] = metadata['comment']!;
-        }
+        // Always include all known fields so -map_metadata 0 + explicit
+        // -metadata flags can both preserve custom tags AND clear fields
+        // the user emptied.
+        final vorbisMap = <String, String>{
+          'TITLE': metadata['title'] ?? '',
+          'ARTIST': metadata['artist'] ?? '',
+          'ALBUM': metadata['album'] ?? '',
+          'ALBUMARTIST': metadata['album_artist'] ?? '',
+          'DATE': metadata['date'] ?? '',
+          'TRACKNUMBER':
+              (metadata['track_number']?.isNotEmpty == true &&
+                  metadata['track_number'] != '0')
+              ? metadata['track_number']!
+              : '',
+          'DISCNUMBER':
+              (metadata['disc_number']?.isNotEmpty == true &&
+                  metadata['disc_number'] != '0')
+              ? metadata['disc_number']!
+              : '',
+          'GENRE': metadata['genre'] ?? '',
+          'ISRC': metadata['isrc'] ?? '',
+          'ORGANIZATION': metadata['label'] ?? '',
+          'COPYRIGHT': metadata['copyright'] ?? '',
+          'COMPOSER': metadata['composer'] ?? '',
+          'COMMENT': metadata['comment'] ?? '',
+        };
         try {
           final existingMetadata = await PlatformBridge.readFileMetadata(
             ffmpegTarget,
@@ -4968,8 +5214,25 @@ class _EditMetadataSheetState extends State<_EditMetadataSheet> {
             vorbisMap['LYRICS'] = existingLyrics;
             vorbisMap['UNSYNCEDLYRICS'] = existingLyrics;
           }
+          // Preserve ReplayGain tags if present — these are computed once
+          // during download and should survive manual metadata edits.
+          final rgFields = <String, String>{
+            'REPLAYGAIN_TRACK_GAIN':
+                existingMetadata['replaygain_track_gain']?.toString() ?? '',
+            'REPLAYGAIN_TRACK_PEAK':
+                existingMetadata['replaygain_track_peak']?.toString() ?? '',
+            'REPLAYGAIN_ALBUM_GAIN':
+                existingMetadata['replaygain_album_gain']?.toString() ?? '',
+            'REPLAYGAIN_ALBUM_PEAK':
+                existingMetadata['replaygain_album_peak']?.toString() ?? '',
+          };
+          rgFields.forEach((key, value) {
+            if (value.isNotEmpty) {
+              vorbisMap[key] = value;
+            }
+          });
         } catch (_) {
-          // Lyrics preservation is best-effort.
+          // Lyrics/ReplayGain preservation is best-effort.
         }
 
         String? existingCoverPath = _selectedCoverPath ?? _currentCoverPath;
@@ -4992,9 +5255,7 @@ class _EditMetadataSheetState extends State<_EditMetadataSheet> {
                 await tempDir.delete(recursive: true);
               } catch (_) {}
             }
-          } catch (_) {
-            // No cover to preserve, continue without
-          }
+          } catch (_) {}
         }
 
         String? ffmpegResult;
@@ -5003,12 +5264,14 @@ class _EditMetadataSheetState extends State<_EditMetadataSheet> {
             mp3Path: ffmpegTarget,
             coverPath: existingCoverPath,
             metadata: vorbisMap,
+            preserveMetadata: true,
           );
         } else if (isM4A) {
           ffmpegResult = await FFmpegService.embedMetadataToM4a(
             m4aPath: ffmpegTarget,
             coverPath: existingCoverPath,
             metadata: vorbisMap,
+            preserveMetadata: true,
           );
         } else if (isOpus) {
           ffmpegResult = await FFmpegService.embedMetadataToOpus(
@@ -5016,6 +5279,7 @@ class _EditMetadataSheetState extends State<_EditMetadataSheet> {
             coverPath: existingCoverPath,
             metadata: vorbisMap,
             artistTagMode: widget.artistTagMode,
+            preserveMetadata: true,
           );
         }
 

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

@@ -53,8 +53,8 @@ class DownloadRequestPayload {
     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 = '',

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 (_) {}
   }
 }

lib/services/ffmpeg_service.dart

@@ -1,5 +1,6 @@
 import 'dart:convert';
 import 'dart:io';
+import 'dart:math' as math;
 import 'dart:typed_data';
 import 'package:ffmpeg_kit_flutter_new_full/ffmpeg_kit.dart';
 import 'package:ffmpeg_kit_flutter_new_full/ffmpeg_kit_config.dart';
@@ -189,10 +190,10 @@ class FFmpegService {
     String command;
     if (format == 'opus') {
       command =
-          '-i "$inputPath" -codec:a libopus -b:a $bitrateValue -vbr on -compression_level 10 -map 0:a "$outputPath" -y';
+          '-v error -hide_banner -i "$inputPath" -codec:a libopus -b:a $bitrateValue -vbr on -compression_level 10 -map 0:a "$outputPath" -y';
     } else {
       command =
-          '-i "$inputPath" -codec:a libmp3lame -b:a $bitrateValue -map 0:a -id3v2_version 3 "$outputPath" -y';
+          '-v error -hide_banner -i "$inputPath" -codec:a libmp3lame -b:a $bitrateValue -map 0:a -id3v2_version 3 "$outputPath" -y';
     }
 
     final result = await _execute(command);
@@ -326,7 +327,7 @@ class FFmpegService {
     final outputPath = _buildOutputPath(inputPath, '.mp3');
 
     final command =
-        '-i "$inputPath" -codec:a libmp3lame -b:a $bitrate -map 0:a -map_metadata 0 -id3v2_version 3 "$outputPath" -y';
+        '-v error -hide_banner -i "$inputPath" -codec:a libmp3lame -b:a $bitrate -map 0:a -map_metadata 0 -id3v2_version 3 "$outputPath" -y';
 
     final result = await _execute(command);
 
@@ -778,7 +779,7 @@ class FFmpegService {
     final outputPath = _buildOutputPath(inputPath, '.opus');
 
     final command =
-        '-i "$inputPath" -codec:a libopus -b:a $bitrate -vbr on -compression_level 10 -map 0:a -map_metadata 0 "$outputPath" -y';
+        '-v error -hide_banner -i "$inputPath" -codec:a libopus -b:a $bitrate -vbr on -compression_level 10 -map 0:a -map_metadata 0 "$outputPath" -y';
 
     final result = await _execute(command);
 
@@ -851,10 +852,10 @@ class FFmpegService {
     String command;
     if (codec == 'alac') {
       command =
-          '-i "$inputPath" -codec:a alac -map 0:a -map_metadata 0 "$outputPath" -y';
+          '-v error -hide_banner -i "$inputPath" -codec:a alac -map 0:a -map_metadata 0 "$outputPath" -y';
     } else {
       command =
-          '-i "$inputPath" -codec:a aac -b:a $bitrate -map 0:a -map_metadata 0 "$outputPath" -y';
+          '-v error -hide_banner -i "$inputPath" -codec:a aac -b:a $bitrate -map 0:a -map_metadata 0 "$outputPath" -y';
     }
 
     final result = await _execute(command);
@@ -884,6 +885,157 @@ class FFmpegService {
     }
   }
 
+  /// Scan an audio file for EBU R128 loudness and compute ReplayGain values.
+  ///
+  /// Uses the FFmpeg `ebur128` audio filter to measure integrated loudness (LUFS)
+  /// and true peak. ReplayGain reference level is -18 LUFS (≈ 89 dB SPL).
+  ///
+  /// Returns a [ReplayGainResult] on success, or null if the scan fails.
+  static Future<ReplayGainResult?> scanReplayGain(String filePath) async {
+    // -nostats suppresses the interactive progress line.
+    // ebur128=peak=true prints integrated loudness + true peak.
+    // framelog=quiet suppresses per-frame measurements (very verbose),
+    // keeping only the final summary which we parse.
+    final command =
+        '-hide_banner -nostats -i "$filePath" -filter_complex ebur128=peak=true:framelog=quiet -f null -';
+
+    _log.d(
+      'Scanning ReplayGain for: ${filePath.split(Platform.pathSeparator).last}',
+    );
+    final result = await _execute(command);
+
+    // FFmpeg writes ebur128 stats to stderr, which ends up in the output.
+    // Even on "failure" return code, the output may contain valid data
+    // because -f null always "fails" on some FFmpeg builds.
+    final output = result.output;
+
+    // Parse integrated loudness: "I:        -14.0 LUFS"
+    final integratedMatch = RegExp(
+      r'I:\s+(-?\d+\.?\d*)\s+LUFS',
+    ).allMatches(output);
+    if (integratedMatch.isEmpty) {
+      _log.w('ReplayGain scan: could not parse integrated loudness');
+      return null;
+    }
+    // Take the last match (the summary, not per-segment values)
+    final integratedLufs = double.tryParse(integratedMatch.last.group(1) ?? '');
+    if (integratedLufs == null) {
+      _log.w('ReplayGain scan: invalid integrated loudness value');
+      return null;
+    }
+
+    // Parse true peak: "Peak:      0.9 dBFS" or "True peak:\n    Peak:    -0.3 dBFS"
+    // The ebur128 filter with peak=true outputs per-channel true peak.
+    // We want the highest (maximum) true peak across all channels.
+    double? truePeakDbfs;
+    final peakMatches = RegExp(
+      r'Peak:\s+(-?\d+\.?\d*)\s+dBFS',
+    ).allMatches(output);
+    for (final m in peakMatches) {
+      final val = double.tryParse(m.group(1) ?? '');
+      if (val != null) {
+        if (truePeakDbfs == null || val > truePeakDbfs) {
+          truePeakDbfs = val;
+        }
+      }
+    }
+
+    const replayGainReferenceLufs = -18.0;
+    final gainDb = replayGainReferenceLufs - integratedLufs;
+
+    // Convert true peak from dBFS to linear ratio.
+    // If no true peak was found, fall back to 1.0 (0 dBFS).
+    double peakLinear;
+    if (truePeakDbfs != null) {
+      peakLinear = math.pow(10, truePeakDbfs / 20.0).toDouble();
+    } else {
+      peakLinear = 1.0;
+    }
+
+    final trackGain =
+        '${gainDb >= 0 ? "+" : ""}${gainDb.toStringAsFixed(2)} dB';
+    final trackPeak = peakLinear.toStringAsFixed(6);
+
+    _log.i(
+      'ReplayGain scan result: gain=$trackGain, peak=$trackPeak (integrated=${integratedLufs.toStringAsFixed(1)} LUFS)',
+    );
+
+    return ReplayGainResult(
+      trackGain: trackGain,
+      trackPeak: trackPeak,
+      integratedLufs: integratedLufs,
+      truePeakLinear: peakLinear,
+    );
+  }
+
+  /// Write album ReplayGain tags to a non-FLAC file (MP3/Opus) using FFmpeg.
+  /// Preserves all existing metadata and adds/overwrites album gain fields.
+  /// Write album ReplayGain tags to a file via FFmpeg.
+  ///
+  /// For local files, replaces the file in-place and returns `true`.
+  /// When [returnTempPath] is `true` (for SAF content:// URIs), the method
+  /// skips the file replacement and returns the temp output path as a String
+  /// via [tempOutputPath].  The caller is responsible for writing the temp
+  /// file to the SAF URI and cleaning it up.
+  static Future<bool> writeAlbumReplayGainTags(
+    String filePath,
+    String albumGain,
+    String albumPeak, {
+    bool returnTempPath = false,
+    void Function(String tempPath)? onTempReady,
+  }) async {
+    final ext = filePath.contains('.')
+        ? '.${filePath.split('.').last}'
+        : '.tmp';
+    final tempDir = await getTemporaryDirectory();
+    final tempOutput = _nextTempEmbedPath(tempDir.path, ext);
+
+    final sanitizedGain = albumGain.replaceAll('"', '\\"');
+    final sanitizedPeak = albumPeak.replaceAll('"', '\\"');
+
+    // -map_metadata 0 preserves all existing metadata from the input.
+    // -metadata flags add/overwrite only the specified keys.
+    final command =
+        '-v error -hide_banner -i "$filePath" -map 0 -c copy -map_metadata 0 '
+        '-metadata REPLAYGAIN_ALBUM_GAIN="$sanitizedGain" '
+        '-metadata REPLAYGAIN_ALBUM_PEAK="$sanitizedPeak" '
+        '"$tempOutput" -y';
+
+    _log.d('Writing album ReplayGain tags via FFmpeg');
+    final result = await _execute(command);
+
+    if (result.success) {
+      try {
+        final tempFile = File(tempOutput);
+        if (await tempFile.exists()) {
+          if (returnTempPath) {
+            // Caller will handle SAF write-back and cleanup.
+            onTempReady?.call(tempOutput);
+            return true;
+          }
+          final originalFile = File(filePath);
+          if (await originalFile.exists()) {
+            await originalFile.delete();
+          }
+          await tempFile.copy(filePath);
+          await tempFile.delete();
+          _log.d('Album ReplayGain tags written successfully');
+          return true;
+        }
+      } catch (e) {
+        _log.w('Failed to replace file with album ReplayGain: $e');
+      }
+    }
+
+    // Cleanup temp file on failure
+    try {
+      final tempFile = File(tempOutput);
+      if (await tempFile.exists()) await tempFile.delete();
+    } catch (_) {}
+
+    return false;
+  }
+
   static Future<String?> embedMetadata({
     required String flacPath,
     String? coverPath,
@@ -894,6 +1046,7 @@ class FFmpegService {
     final tempOutput = _nextTempEmbedPath(tempDir.path, '.flac');
 
     final StringBuffer cmdBuffer = StringBuffer();
+    cmdBuffer.write('-v error -hide_banner ');
     cmdBuffer.write('-i "$flacPath" ');
 
     if (coverPath != null) {
@@ -967,11 +1120,13 @@ class FFmpegService {
     required String mp3Path,
     String? coverPath,
     Map<String, String>? metadata,
+    bool preserveMetadata = false,
   }) async {
     final tempDir = await getTemporaryDirectory();
     final tempOutput = _nextTempEmbedPath(tempDir.path, '.mp3');
 
     final StringBuffer cmdBuffer = StringBuffer();
+    cmdBuffer.write('-v error -hide_banner ');
     cmdBuffer.write('-i "$mp3Path" ');
 
     if (coverPath != null) {
@@ -979,7 +1134,9 @@ class FFmpegService {
     }
 
     cmdBuffer.write('-map 0:a ');
-    cmdBuffer.write('-map_metadata -1 ');
+    cmdBuffer.write(
+      preserveMetadata ? '-map_metadata 0 ' : '-map_metadata -1 ',
+    );
 
     if (coverPath != null) {
       cmdBuffer.write('-map 1:0 ');
@@ -1050,18 +1207,23 @@ class FFmpegService {
     String? coverPath,
     Map<String, String>? metadata,
     String artistTagMode = artistTagModeJoined,
+    bool preserveMetadata = false,
   }) async {
     final tempDir = await getTemporaryDirectory();
     final tempOutput = _nextTempEmbedPath(tempDir.path, '.opus');
+    final mapMetaValue = preserveMetadata ? '0' : '-1';
     final arguments = <String>[
+      '-v',
+      'error',
+      '-hide_banner',
       '-i',
       opusPath,
       '-map',
       '0:a',
       '-map_metadata',
-      '-1',
+      mapMetaValue,
       '-map_metadata:s:a',
-      '-1',
+      mapMetaValue,
       '-c:a',
       'copy',
     ];
@@ -1140,11 +1302,13 @@ class FFmpegService {
     required String m4aPath,
     String? coverPath,
     Map<String, String>? metadata,
+    bool preserveMetadata = false,
   }) async {
     final tempDir = await getTemporaryDirectory();
     final tempOutput = _nextTempEmbedPath(tempDir.path, '.m4a');
 
     final cmdBuffer = StringBuffer();
+    cmdBuffer.write('-v error -hide_banner ');
     cmdBuffer.write('-i "$m4aPath" ');
 
     final hasCover = coverPath != null && await File(coverPath).exists();
@@ -1153,7 +1317,9 @@ class FFmpegService {
     }
 
     cmdBuffer.write('-map 0:a ');
-    cmdBuffer.write('-map_metadata -1 ');
+    cmdBuffer.write(
+      preserveMetadata ? '-map_metadata 0 ' : '-map_metadata -1 ',
+    );
 
     // For M4A/MP4, cover art is mapped as a video stream and stored in the
     // 'covr' atom automatically by FFmpeg. The '-disposition attached_pic'
@@ -1342,7 +1508,6 @@ class FFmpegService {
       return null;
     }
 
-    // Lossless targets: dedicated single-pass methods
     if (format == 'alac') {
       return _convertToAlac(
         inputPath: inputPath,
@@ -1361,17 +1526,16 @@ class FFmpegService {
       );
     }
 
-    // Lossy targets: MP3 / Opus
     final extension = format == 'opus' ? '.opus' : '.mp3';
     final outputPath = _buildOutputPath(inputPath, extension);
 
     String command;
     if (format == 'opus') {
       command =
-          '-i "$inputPath" -codec:a libopus -b:a $bitrate -vbr on -compression_level 10 -map 0:a "$outputPath" -y';
+          '-v error -hide_banner -i "$inputPath" -codec:a libopus -b:a $bitrate -vbr on -compression_level 10 -map 0:a "$outputPath" -y';
     } else {
       command =
-          '-i "$inputPath" -codec:a libmp3lame -b:a $bitrate -map 0:a -id3v2_version 3 "$outputPath" -y';
+          '-v error -hide_banner -i "$inputPath" -codec:a libmp3lame -b:a $bitrate -map 0:a -id3v2_version 3 "$outputPath" -y';
     }
 
     _log.i(
@@ -1445,6 +1609,7 @@ class FFmpegService {
     final outputPath = _buildOutputPath(inputPath, '.m4a');
 
     final cmdBuffer = StringBuffer();
+    cmdBuffer.write('-v error -hide_banner ');
     cmdBuffer.write('-i "$inputPath" ');
 
     final hasCover =
@@ -1507,6 +1672,7 @@ class FFmpegService {
     final outputPath = _buildOutputPath(inputPath, '.flac');
 
     final cmdBuffer = StringBuffer();
+    cmdBuffer.write('-v error -hide_banner ');
     cmdBuffer.write('-i "$inputPath" ');
 
     final hasCover =
@@ -1568,7 +1734,6 @@ class FFmpegService {
     for (final entry in metadata.entries) {
       final key = entry.key.toUpperCase().replaceAll(RegExp(r'[^A-Z0-9]'), '');
       final value = entry.value;
-      if (value.trim().isEmpty) continue;
 
       switch (key) {
         case 'TITLE':
@@ -1622,6 +1787,18 @@ class FFmpegService {
           vorbis['LYRICS'] = value;
           vorbis['UNSYNCEDLYRICS'] = value;
           break;
+        case 'REPLAYGAINTRACKGAIN':
+          vorbis['REPLAYGAIN_TRACK_GAIN'] = value;
+          break;
+        case 'REPLAYGAINTRACKPEAK':
+          vorbis['REPLAYGAIN_TRACK_PEAK'] = value;
+          break;
+        case 'REPLAYGAINALBUMGAIN':
+          vorbis['REPLAYGAIN_ALBUM_GAIN'] = value;
+          break;
+        case 'REPLAYGAINALBUMPEAK':
+          vorbis['REPLAYGAIN_ALBUM_PEAK'] = value;
+          break;
       }
     }
 
@@ -1693,8 +1870,12 @@ class FFmpegService {
     String? rawValue, {
     String artistTagMode = artistTagModeJoined,
   }) {
-    final value = rawValue?.trim() ?? '';
+    if (rawValue == null) return;
+    final value = rawValue.trim();
     if (value.isEmpty) {
+      // Emit an empty entry so that with preserveMetadata the old tag is
+      // overridden (cleared) by FFmpeg's `-metadata key=""`.
+      entries.add(MapEntry(key, ''));
       return;
     }
 
@@ -1715,7 +1896,6 @@ class FFmpegService {
     for (final entry in metadata.entries) {
       final key = entry.key.toUpperCase().replaceAll(RegExp(r'[^A-Z0-9]'), '');
       final value = entry.value;
-      if (value.trim().isEmpty) continue;
 
       switch (key) {
         case 'TITLE':
@@ -1767,6 +1947,19 @@ class FFmpegService {
         case 'UNSYNCEDLYRICS':
           m4aMap['lyrics'] = value;
           break;
+        // ReplayGain as iTunes freeform atoms (com.apple.iTunes:replaygain_*)
+        case 'REPLAYGAINTRACKGAIN':
+          m4aMap['REPLAYGAIN_TRACK_GAIN'] = value;
+          break;
+        case 'REPLAYGAINTRACKPEAK':
+          m4aMap['REPLAYGAIN_TRACK_PEAK'] = value;
+          break;
+        case 'REPLAYGAINALBUMGAIN':
+          m4aMap['REPLAYGAIN_ALBUM_GAIN'] = value;
+          break;
+        case 'REPLAYGAINALBUMPEAK':
+          m4aMap['REPLAYGAIN_ALBUM_PEAK'] = value;
+          break;
       }
     }
 
@@ -1782,9 +1975,6 @@ class FFmpegService {
       final key = entry.key.toUpperCase();
       final normalizedKey = key.replaceAll(RegExp(r'[^A-Z0-9]'), '');
       final value = entry.value;
-      if (value.trim().isEmpty) {
-        continue;
-      }
 
       switch (normalizedKey) {
         case 'TITLE':
@@ -1830,6 +2020,20 @@ class FFmpegService {
         case 'COMMENT':
           id3Map['comment'] = value;
           break;
+        // ReplayGain as TXXX user-defined frames
+        // FFmpeg writes these as TXXX frames automatically with uppercase keys
+        case 'REPLAYGAINTRACKGAIN':
+          id3Map['REPLAYGAIN_TRACK_GAIN'] = value;
+          break;
+        case 'REPLAYGAINTRACKPEAK':
+          id3Map['REPLAYGAIN_TRACK_PEAK'] = value;
+          break;
+        case 'REPLAYGAINALBUMGAIN':
+          id3Map['REPLAYGAIN_ALBUM_GAIN'] = value;
+          break;
+        case 'REPLAYGAINALBUMPEAK':
+          id3Map['REPLAYGAIN_ALBUM_PEAK'] = value;
+          break;
         default:
           id3Map[key.toLowerCase()] = value;
       }
@@ -1881,6 +2085,7 @@ class FFmpegService {
       final outputPath = '$outputDir${Platform.pathSeparator}$outputFileName';
 
       final StringBuffer cmdBuffer = StringBuffer();
+      cmdBuffer.write('-v error -hide_banner ');
       cmdBuffer.write('-i "$audioPath" ');
 
       final startTime = _formatSecondsForFFmpeg(track.startSec);
@@ -1958,7 +2163,6 @@ class FFmpegService {
   }
 }
 
-/// Track info for CUE splitting, passed from the CUE parser
 class CueSplitTrackInfo {
   final int number;
   final String title;
@@ -2016,3 +2220,29 @@ class LiveDecryptedStreamResult {
     required this.session,
   });
 }
+
+/// Result of an EBU R128 loudness scan, used to compute ReplayGain tags.
+class ReplayGainResult {
+  /// Track gain in dB, e.g. "-6.50 dB"
+  final String trackGain;
+
+  /// Track peak as a linear ratio, e.g. "0.988831"
+  final String trackPeak;
+
+  /// Raw integrated loudness in LUFS (needed for album gain computation)
+  final double integratedLufs;
+
+  /// Raw true peak as linear ratio (needed for album peak computation)
+  final double truePeakLinear;
+
+  const ReplayGainResult({
+    required this.trackGain,
+    required this.trackPeak,
+    required this.integratedLufs,
+    required this.truePeakLinear,
+  });
+
+  @override
+  String toString() =>
+      'ReplayGainResult(trackGain: $trackGain, trackPeak: $trackPeak)';
+}

lib/services/history_database.dart

@@ -9,10 +9,8 @@ import 'package:spotiflac_android/utils/logger.dart';
 final _log = AppLogger('HistoryDatabase');
 final Future<SharedPreferences> _prefs = SharedPreferences.getInstance();
 
-/// Cached current iOS container path for path normalization
 String? _currentContainerPath;
 
-/// Provides O(1) lookups by spotify_id and isrc with proper indexing
 class HistoryDatabase {
   static final HistoryDatabase instance = HistoryDatabase._init();
   static Database? _database;
@@ -102,21 +100,16 @@ class HistoryDatabase {
     }
   }
 
-  /// Pattern to match iOS container paths
-  /// Example: /var/mobile/Containers/Data/Application/UUID-HERE/Documents/...
   static final _iosContainerPattern = RegExp(
     r'/var/mobile/Containers/Data/Application/[A-F0-9\-]+/',
     caseSensitive: false,
   );
 
-  /// Initialize and cache the current iOS container path
   Future<void> _initContainerPath() async {
     if (!Platform.isIOS || _currentContainerPath != null) return;
 
     try {
       final docDir = await getApplicationDocumentsDirectory();
-      // Extract container path up to and including the UUID folder
-      // e.g., /var/mobile/Containers/Data/Application/UUID/
       final match = _iosContainerPattern.firstMatch(docDir.path);
       if (match != null) {
         _currentContainerPath = match.group(0);
@@ -127,13 +120,10 @@ class HistoryDatabase {
     }
   }
 
-  /// Normalize iOS file path by replacing old container UUID with current one
-  /// This fixes the issue where iOS changes container UUID after app updates
   String _normalizeIosPath(String? filePath) {
     if (filePath == null || filePath.isEmpty) return filePath ?? '';
     if (!Platform.isIOS || _currentContainerPath == null) return filePath;
 
-    // Check if path contains an iOS container path
     if (_iosContainerPattern.hasMatch(filePath)) {
       final normalized = filePath.replaceFirst(
         _iosContainerPattern,
@@ -148,8 +138,6 @@ class HistoryDatabase {
     return filePath;
   }
 
-  /// Migrate iOS paths in database to use current container UUID
-  /// This is called once after app update if container changed
   Future<bool> migrateIosContainerPaths() async {
     if (!Platform.isIOS) return false;
 
@@ -205,8 +193,6 @@ class HistoryDatabase {
     }
   }
 
-  /// Migrate data from SharedPreferences to SQLite
-  /// Returns true if migration was performed, false if already migrated
   Future<bool> migrateFromSharedPreferences() async {
     final prefs = await _prefs;
     final migrationKey = 'history_migrated_to_sqlite';
@@ -243,7 +229,6 @@ class HistoryDatabase {
 
       await batch.commit(noResult: true);
 
-      // Mark as migrated but keep old data for safety
       await prefs.setBool(migrationKey, true);
       _log.i('Migration complete: ${jsonList.length} items');
 
@@ -254,7 +239,6 @@ class HistoryDatabase {
     }
   }
 
-  /// Convert JSON format (camelCase) to DB row (snake_case)
   Map<String, dynamic> _jsonToDbRow(Map<String, dynamic> json) {
     return {
       'id': json['id'],
@@ -286,8 +270,6 @@ class HistoryDatabase {
     };
   }
 
-  /// Convert DB row (snake_case) to JSON format (camelCase)
-  /// Also normalizes iOS paths if container UUID changed
   Map<String, dynamic> _dbRowToJson(Map<String, dynamic> row) {
     return {
       'id': row['id'],
@@ -342,7 +324,6 @@ class HistoryDatabase {
     await batch.commit(noResult: true);
   }
 
-  /// Get all history items ordered by download date (newest first)
   Future<List<Map<String, dynamic>>> getAll({int? limit, int? offset}) async {
     final db = await database;
     final rows = await db.query(
@@ -366,7 +347,6 @@ class HistoryDatabase {
     return _dbRowToJson(rows.first);
   }
 
-  /// Get item by Spotify ID - O(1) with index
   Future<Map<String, dynamic>?> getBySpotifyId(String spotifyId) async {
     final db = await database;
     final rows = await db.query(
@@ -379,7 +359,6 @@ class HistoryDatabase {
     return _dbRowToJson(rows.first);
   }
 
-  /// Get item by ISRC - O(1) with index
   Future<Map<String, dynamic>?> getByIsrc(String isrc) async {
     final db = await database;
     final rows = await db.query(
@@ -392,7 +371,6 @@ class HistoryDatabase {
     return _dbRowToJson(rows.first);
   }
 
-  /// Check if spotify_id exists - O(1) with index
   Future<bool> existsBySpotifyId(String spotifyId) async {
     final db = await database;
     final result = await db.rawQuery(
@@ -402,7 +380,6 @@ class HistoryDatabase {
     return result.isNotEmpty;
   }
 
-  /// Get all spotify_ids as Set for fast in-memory lookup
   Future<Set<String>> getAllSpotifyIds() async {
     final db = await database;
     final rows = await db.rawQuery(
@@ -433,7 +410,6 @@ class HistoryDatabase {
     return Sqflite.firstIntValue(result) ?? 0;
   }
 
-  /// Find existing item by spotify_id or isrc (for deduplication)
   Future<Map<String, dynamic>?> findExisting({
     String? spotifyId,
     String? isrc,
@@ -442,7 +418,6 @@ class HistoryDatabase {
       final bySpotify = await getBySpotifyId(spotifyId);
       if (bySpotify != null) return bySpotify;
 
-      // Check for deezer: prefix matching
       if (spotifyId.startsWith('deezer:')) {
         final deezerId = spotifyId.substring(7);
         final db = await database;
@@ -469,7 +444,6 @@ class HistoryDatabase {
     _database = null;
   }
 
-  /// Update file path for a history entry (e.g. after format conversion)
   Future<void> updateFilePath(
     String id,
     String newFilePath, {
@@ -524,8 +498,6 @@ class HistoryDatabase {
     await db.update('history', values, where: 'id = ?', whereArgs: [id]);
   }
 
-  /// Get all file paths from download history
-  /// Used to exclude downloaded files from local library scan
   Future<Set<String>> getAllFilePaths() async {
     final db = await database;
     final rows = await db.rawQuery(
@@ -534,8 +506,6 @@ class HistoryDatabase {
     return rows.map((r) => r['file_path'] as String).toSet();
   }
 
-  /// Get all entries with file paths for orphan detection
-  /// Returns list of (id, file_path, storage_mode, download_tree_uri, saf_relative_dir, saf_file_name)
   Future<List<Map<String, dynamic>>> getAllEntriesWithPaths() async {
     final db = await database;
     final rows = await db.rawQuery('''
@@ -569,7 +539,6 @@ class HistoryDatabase {
     return rows.map((r) => Map<String, dynamic>.from(r)).toList();
   }
 
-  /// Delete multiple entries by IDs
   Future<int> deleteByIds(List<String> ids) async {
     if (ids.isEmpty) return 0;
 

lib/services/library_collections_database.dart

@@ -33,6 +33,28 @@ class LibraryCollectionsSnapshot {
   });
 }
 
+class PlaylistPickerSummaryRow {
+  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 PlaylistPickerSummaryRow({
+    required this.id,
+    required this.name,
+    this.coverImagePath,
+    this.previewCover,
+    required this.createdAt,
+    required this.updatedAt,
+    required this.trackCount,
+    required this.containsAllRequestedTracks,
+  });
+}
+
 class LibraryCollectionsDatabase {
   static final LibraryCollectionsDatabase instance =
       LibraryCollectionsDatabase._init();
@@ -251,6 +273,119 @@ class LibraryCollectionsDatabase {
     );
   }
 
+  Future<List<PlaylistPickerSummaryRow>> loadPlaylistPickerSummaries(
+    List<String> requestedTrackKeys,
+  ) async {
+    final db = await database;
+    final uniqueTrackKeys = requestedTrackKeys
+        .where((key) => key.trim().isNotEmpty)
+        .toSet()
+        .toList(growable: false);
+
+    final playlistRows = await db.rawQuery('''
+      SELECT
+        p.id,
+        p.name,
+        p.cover_image_path,
+        p.created_at,
+        p.updated_at,
+        COUNT(pt.track_key) AS track_count
+      FROM $_tablePlaylists p
+      LEFT JOIN $_tablePlaylistTracks pt ON pt.playlist_id = p.id
+      GROUP BY p.id
+      ORDER BY p.created_at DESC, p.rowid DESC
+    ''');
+
+    final matchedCountsByPlaylistId = <String, int>{};
+    if (uniqueTrackKeys.isNotEmpty) {
+      final placeholders = List.filled(uniqueTrackKeys.length, '?').join(', ');
+      final matchedRows = await db.rawQuery('''
+          SELECT playlist_id, COUNT(*) AS matched_count
+          FROM $_tablePlaylistTracks
+          WHERE track_key IN ($placeholders)
+          GROUP BY playlist_id
+        ''', uniqueTrackKeys);
+      for (final row in matchedRows) {
+        final playlistId = row['playlist_id']?.toString();
+        if (playlistId == null || playlistId.isEmpty) continue;
+        matchedCountsByPlaylistId[playlistId] =
+            (row['matched_count'] as num?)?.toInt() ?? 0;
+      }
+    }
+
+    final playlistIdsNeedingPreview = playlistRows
+        .where((row) {
+          final coverPath = row['cover_image_path']?.toString();
+          return coverPath == null || coverPath.isEmpty;
+        })
+        .map((row) => row['id']?.toString() ?? '')
+        .where((id) => id.isNotEmpty)
+        .toList(growable: false);
+
+    final previewCoverByPlaylistId = <String, String?>{};
+    if (playlistIdsNeedingPreview.isNotEmpty) {
+      final placeholders = List.filled(
+        playlistIdsNeedingPreview.length,
+        '?',
+      ).join(', ');
+      final previewRows = await db.rawQuery('''
+          SELECT outer_tracks.playlist_id, outer_tracks.track_json
+          FROM $_tablePlaylistTracks outer_tracks
+          WHERE outer_tracks.playlist_id IN ($placeholders)
+            AND outer_tracks.rowid = (
+              SELECT inner_tracks.rowid
+              FROM $_tablePlaylistTracks inner_tracks
+              WHERE inner_tracks.playlist_id = outer_tracks.playlist_id
+              ORDER BY inner_tracks.added_at DESC, inner_tracks.rowid DESC
+              LIMIT 1
+            )
+        ''', playlistIdsNeedingPreview);
+
+      for (final row in previewRows) {
+        final playlistId = row['playlist_id']?.toString();
+        final trackJson = row['track_json'] as String?;
+        if (playlistId == null ||
+            playlistId.isEmpty ||
+            trackJson == null ||
+            trackJson.isEmpty) {
+          continue;
+        }
+        try {
+          final decoded = jsonDecode(trackJson);
+          if (decoded is! Map) continue;
+          final coverUrl = decoded['coverUrl']?.toString();
+          if (coverUrl != null && coverUrl.isNotEmpty) {
+            previewCoverByPlaylistId[playlistId] = coverUrl;
+          }
+        } catch (_) {}
+      }
+    }
+
+    return playlistRows
+        .map((row) {
+          final id = row['id']?.toString() ?? '';
+          final createdAt =
+              DateTime.tryParse(row['created_at']?.toString() ?? '') ??
+              DateTime.now();
+          final updatedAt =
+              DateTime.tryParse(row['updated_at']?.toString() ?? '') ??
+              createdAt;
+          return PlaylistPickerSummaryRow(
+            id: id,
+            name: row['name']?.toString() ?? '',
+            coverImagePath: row['cover_image_path'] as String?,
+            previewCover: previewCoverByPlaylistId[id],
+            createdAt: createdAt,
+            updatedAt: updatedAt,
+            trackCount: (row['track_count'] as num?)?.toInt() ?? 0,
+            containsAllRequestedTracks:
+                uniqueTrackKeys.isNotEmpty &&
+                matchedCountsByPlaylistId[id] == uniqueTrackKeys.length,
+          );
+        })
+        .toList(growable: false);
+  }
+
   Future<void> upsertWishlistEntry({
     required String trackKey,
     required String trackJson,

lib/services/library_database.dart

@@ -96,7 +96,6 @@ class LocalLibraryItem {
         format: json['format'] as String?,
       );
 
-  /// Create a unique key for matching tracks
   String get matchKey =>
       '${trackName.toLowerCase()}|${artistName.toLowerCase()}';
   String get albumKey =>
@@ -183,13 +182,11 @@ class LibraryDatabase {
     }
 
     if (oldVersion < 3) {
-      // Add file_mod_time column for incremental scanning
       await db.execute('ALTER TABLE library ADD COLUMN file_mod_time INTEGER');
       _log.i('Added file_mod_time column for incremental scanning');
     }
 
     if (oldVersion < 4) {
-      // Add bitrate column for lossy format quality info
       await db.execute('ALTER TABLE library ADD COLUMN bitrate INTEGER');
       _log.i('Added bitrate column for lossy format quality');
     }
@@ -475,8 +472,6 @@ class LibraryDatabase {
     _database = null;
   }
 
-  /// Get all file paths with their modification times for incremental scanning
-  /// Returns a map of filePath -> fileModTime (unix timestamp in milliseconds)
   Future<Map<String, int>> getFileModTimes() async {
     final db = await database;
     final rows = await db.rawQuery(
@@ -491,8 +486,6 @@ class LibraryDatabase {
     return result;
   }
 
-  /// Export file modification times to a compact line-based snapshot that
-  /// native code can read without receiving a large method-channel payload.
   Future<String> writeFileModTimesSnapshot() async {
     final db = await database;
     final rows = await db.rawQuery(
@@ -519,7 +512,6 @@ class LibraryDatabase {
     return file.path;
   }
 
-  /// Update file_mod_time for existing rows using file_path as key.
   Future<void> updateFileModTimes(Map<String, int> fileModTimes) async {
     if (fileModTimes.isEmpty) return;
     final db = await database;
@@ -535,7 +527,6 @@ class LibraryDatabase {
     await batch.commit(noResult: true);
   }
 
-  /// Get all file paths in the library (for detecting deleted files)
   Future<Set<String>> getAllFilePaths() async {
     final db = await database;
     final rows = await db.rawQuery('SELECT file_path FROM library');

lib/services/platform_bridge.dart

@@ -341,6 +341,7 @@ class PlatformBridge {
     required String spotifyId,
     required int durationMs,
     required String outputPath,
+    String audioFilePath = '',
   }) async {
     final result = await _channel.invokeMethod('fetchAndSaveLyrics', {
       'track_name': trackName,
@@ -348,11 +349,12 @@ class PlatformBridge {
       'spotify_id': spotifyId,
       'duration_ms': durationMs,
       'output_path': outputPath,
+      'audio_file_path': audioFilePath,
     });
     return jsonDecode(result as String) as Map<String, dynamic>;
   }
 
-  /// Sets the lyrics provider order. Providers not in the list are disabled.
+  /// Providers not in the list are disabled.
   static Future<void> setLyricsProviders(List<String> providers) async {
     final providersJSON = jsonEncode(providers);
     await _channel.invokeMethod('setLyricsProviders', {
@@ -360,14 +362,12 @@ class PlatformBridge {
     });
   }
 
-  /// Returns the current lyrics provider order.
   static Future<List<String>> getLyricsProviders() async {
     final result = await _channel.invokeMethod('getLyricsProviders');
     final List<dynamic> decoded = jsonDecode(result as String) as List<dynamic>;
     return decoded.cast<String>();
   }
 
-  /// Returns metadata about all available lyrics providers.
   static Future<List<Map<String, dynamic>>>
   getAvailableLyricsProviders() async {
     final result = await _channel.invokeMethod('getAvailableLyricsProviders');
@@ -385,7 +385,6 @@ class PlatformBridge {
     });
   }
 
-  /// Returns current advanced lyrics fetch options.
   static Future<Map<String, dynamic>> getLyricsFetchOptions() async {
     final result = await _channel.invokeMethod('getLyricsFetchOptions');
     return jsonDecode(result as String) as Map<String, dynamic>;
@@ -420,6 +419,21 @@ class PlatformBridge {
     return jsonDecode(result as String) as Map<String, dynamic>;
   }
 
+  /// Rewrites ARTIST/ALBUMARTIST Vorbis comments as multiple split entries
+  /// using the native Go FLAC writer, fixing FFmpeg's tag deduplication.
+  static Future<Map<String, dynamic>> rewriteSplitArtistTags(
+    String filePath,
+    String artist,
+    String albumArtist,
+  ) async {
+    final result = await _channel.invokeMethod('rewriteSplitArtistTags', {
+      'file_path': filePath,
+      'artist': artist,
+      'album_artist': albumArtist,
+    });
+    return jsonDecode(result as String) as Map<String, dynamic>;
+  }
+
   static Future<bool> writeTempToSaf(String tempPath, String safUri) async {
     final result = await _channel.invokeMethod('writeTempToSaf', {
       'temp_path': tempPath,
@@ -1167,13 +1181,13 @@ class PlatformBridge {
 
   static Map<String, dynamic> _decodeMapResult(dynamic result) {
     if (result is Map) {
-      return Map<String, dynamic>.from(result);
+      return result.cast<String, dynamic>();
     }
     if (result is String) {
       if (result.isEmpty) return const <String, dynamic>{};
       final decoded = jsonDecode(result);
       if (decoded is Map) {
-        return Map<String, dynamic>.from(decoded);
+        return decoded.cast<String, dynamic>();
       }
     }
     return const <String, dynamic>{};