feat: enable Tidal ISRC and metadata search

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

.fvmrc

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

.gitattributes

@@ -0,0 +1,20 @@
+* text=auto eol=lf
+
+# Windows scripts
+*.bat text eol=crlf
+*.cmd text eol=crlf
+*.ps1 text eol=crlf
+
+# Binary files
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.webp binary
+*.ico binary
+*.pdf binary
+*.zip binary
+*.jar binary
+*.aar binary
+*.keystore binary
+*.jks binary

.github/workflows/release.yml

@@ -71,7 +71,7 @@ jobs:
       - name: Setup Go
         uses: actions/setup-go@v6
         with:
-          go-version: "1.26"
+          go-version: "1.25.7"
           cache-dependency-path: go_backend/go.sum
 
       # Cache Gradle for faster builds
@@ -174,7 +174,7 @@ jobs:
       - name: Setup Go
         uses: actions/setup-go@v6
         with:
-          go-version: "1.26"
+          go-version: "1.25.7"
           cache-dependency-path: go_backend/go.sum
 
       # Cache CocoaPods
@@ -309,32 +309,22 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@v6
+        with:
+          fetch-depth: 0  # Full history needed for git-cliff
 
-      - name: Extract changelog for version
+      - name: Generate changelog with git-cliff
         id: changelog
+        uses: orhun/git-cliff-action@v4
+        with:
+          config: cliff.toml
+          args: --latest --strip header
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          OUTPUT: /tmp/changelog.txt
+
+      - name: Show generated changelog
         run: |
-          VERSION=${{ needs.get-version.outputs.version }}
-          VERSION_NUM=${VERSION#v}  # Remove 'v' prefix
-
-          echo "Looking for version: $VERSION_NUM"
-
-          # Extract changelog section for this version using sed
-          # Find the line with version, then print until next version header or end
-          CHANGELOG=$(sed -n "/^## \[$VERSION_NUM\]/,/^## \[/{ /^## \[$VERSION_NUM\]/d; /^## \[/d; p; }" CHANGELOG.md)
-
-          # If no changelog found, use default message
-          if [ -z "$CHANGELOG" ]; then
-            echo "No changelog found for version $VERSION_NUM"
-            CHANGELOG="See CHANGELOG.md for details."
-          else
-            echo "Found changelog content"
-            # Remove trailing --- separator if present (CHANGELOG uses --- between versions)
-            CHANGELOG=$(echo "$CHANGELOG" | sed '/^---$/d')
-          fi
-
-          # Save to file for multiline support
-          echo "$CHANGELOG" > /tmp/changelog.txt
-          echo "Extracted changelog:"
+          echo "Generated changelog:"
           cat /tmp/changelog.txt
 
       - name: Download Android APK
@@ -352,15 +342,22 @@ jobs:
       - name: Prepare release body
         run: |
           VERSION=${{ needs.get-version.outputs.version }}
-          cat > /tmp/release_body.txt << 'HEADER'
-          ### What's New
-          HEADER
-
-          cat /tmp/changelog.txt >> /tmp/release_body.txt
-
           REPO_OWNER="${{ github.repository_owner }}"
           REPO_NAME="${{ github.event.repository.name }}"
-          
+          CURRENT_REF=$(git rev-list -n 1 "$VERSION" 2>/dev/null || git rev-parse HEAD)
+          PREVIOUS_TAG=$(git describe --tags --abbrev=0 "${CURRENT_REF}^" 2>/dev/null || true)
+
+          # Start with git-cliff changelog, but replace its compare footer with a
+          # deterministic previous-tag lookup from git.
+          sed '/^## [0-9][0-9.[:alpha:]-]*$/d; /^\*\*Full Changelog\*\*/d' /tmp/changelog.txt > /tmp/release_body.txt
+
+          if [ -n "$PREVIOUS_TAG" ]; then
+            printf '\n**Full Changelog**: [%s...%s](https://github.com/%s/%s/compare/%s...%s)\n' \
+              "$PREVIOUS_TAG" "$VERSION" "$REPO_OWNER" "$REPO_NAME" "$PREVIOUS_TAG" "$VERSION" \
+              >> /tmp/release_body.txt
+          fi
+
+          # Append download section
           cat >> /tmp/release_body.txt << FOOTER
 
           ---
@@ -396,6 +393,63 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
+  update-altstore:
+    runs-on: ubuntu-latest
+    needs: [get-version, build-ios, create-release]
+    if: ${{ needs.get-version.outputs.is_prerelease != 'true' }}
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout main branch
+        uses: actions/checkout@v6
+        with:
+          ref: main
+
+      - name: Download iOS IPA
+        uses: actions/download-artifact@v7
+        with:
+          name: ios-ipa
+          path: ./release
+
+      - name: Update apps.json
+        run: |
+          VERSION="${{ needs.get-version.outputs.version }}"
+          VERSION_NUM="${VERSION#v}"
+          DATE=$(date -u +%Y-%m-%d)
+          IPA_FILE=$(find ./release -name "*ios*.ipa" | head -1)
+
+          if [ -z "$IPA_FILE" ]; then
+            echo "WARNING: IPA file not found, skipping apps.json update"
+            exit 0
+          fi
+
+          IPA_SIZE=$(stat -c%s "$IPA_FILE" 2>/dev/null || stat -f%z "$IPA_FILE")
+
+          if [ ! -f apps.json ]; then
+            echo "WARNING: apps.json not found on main, skipping"
+            exit 0
+          fi
+
+          jq --arg ver "$VERSION_NUM" \
+             --arg date "$DATE" \
+             --arg url "https://github.com/zarzet/SpotiFLAC-Mobile/releases/download/${VERSION}/SpotiFLAC-${VERSION}-ios-unsigned.ipa" \
+             --argjson size "$IPA_SIZE" \
+             '.apps[0].version = $ver | .apps[0].versionDate = $date | .apps[0].downloadURL = $url | .apps[0].size = $size' \
+             apps.json > apps.json.tmp && mv apps.json.tmp apps.json
+
+          echo "Updated apps.json:"
+          cat apps.json
+
+      - name: Commit and push
+        run: |
+          VERSION="${{ needs.get-version.outputs.version }}"
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add apps.json
+          git diff --cached --quiet && echo "No changes to commit" || \
+            (git commit -m "chore: update AltStore source to ${VERSION}" && git push)
+
   notify-telegram:
     runs-on: ubuntu-latest
     needs: [get-version, create-release]
@@ -404,6 +458,8 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
 
       - name: Download Android APK
         uses: actions/download-artifact@v7
@@ -417,52 +473,43 @@ jobs:
           name: ios-ipa
           path: ./release
 
-      - name: Extract changelog for version
+      - name: Generate changelog with git-cliff for Telegram
+        uses: orhun/git-cliff-action@v4
+        with:
+          config: cliff.toml
+          args: --latest --strip all
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          OUTPUT: /tmp/cliff_tg.txt
+
+      - name: Convert changelog for Telegram
         id: changelog
         run: |
-          VERSION=${{ needs.get-version.outputs.version }}
-          VERSION_NUM=${VERSION#v}
-
-          # Extract changelog, limit to ~2500 chars for Telegram (4096 limit minus message overhead)
-          # Use tr -d '\r' to handle CRLF line endings from Windows
-          FULL_CHANGELOG=$(cat CHANGELOG.md | tr -d '\r' | sed -n "/^## \[$VERSION_NUM\]/,/^## \[/{ /^## \[$VERSION_NUM\]/d; /^## \[/d; p; }" | sed '/^---$/d')
-          
-          echo "DEBUG: Extracted changelog length: ${#FULL_CHANGELOG}"
-          echo "DEBUG: First 200 chars: ${FULL_CHANGELOG:0:200}"
-          
-          if [ -z "$FULL_CHANGELOG" ]; then
-            CHANGELOG="See release notes on GitHub for details."
+          if [ ! -s /tmp/cliff_tg.txt ]; then
+            echo "See release notes on GitHub for details." > /tmp/changelog.txt
           else
-            # Convert GitHub Markdown to Telegram HTML:
-            # - **text** → <b>text</b>
-            # - `code` → <code>code</code>
-            # - ### Header → <b>Header</b>
-            # - Escape HTML special chars first
-            # - Remove > blockquote prefix
-            CHANGELOG=$(echo "$FULL_CHANGELOG" | \
-              sed 's/^> //' | \
+            # Convert Markdown to Telegram HTML
+            CHANGELOG=$(cat /tmp/cliff_tg.txt | \
+              sed '/^## [0-9][0-9.[:alpha:]-]*$/d' | \
+              sed '/^\*\*Full Changelog\*\*/d' | \
+              sed 's/ by \[@[^]]*\](https:\/\/github\.com\/[^)]*)//g' | \
+              sed 's/ by @[A-Za-z0-9_-]\+//g' | \
+              sed 's/\[#\([0-9]*\)\]([^)]*)/#\1/g' | \
+              sed 's/\[@\([^]]*\)\]([^)]*)/@\1/g' | \
               sed 's/&/\&amp;/g' | \
               sed 's/</\&lt;/g' | \
               sed 's/>/\&gt;/g' | \
-              sed 's/`\([^`]*\)`/<code>\1<\/code>/g' | \
               sed 's/\*\*\([^*]*\)\*\*/<b>\1<\/b>/g' | \
               sed 's/^### \(.*\)$/<b>\1<\/b>/g' | \
               sed 's/^## \(.*\)$/<b>\1<\/b>/g' | \
-              sed 's/^- /• /g' | \
-              sed 's/^  - /  ◦ /g')
-            
-            # Take first 2500 characters, then cut at last complete line
+              sed 's/^- /• /g')
+
+            # Truncate for Telegram 4096 char limit
             CHANGELOG=$(echo "$CHANGELOG" | head -c 2500 | sed '$d')
-            
-            # Check if truncated
-            FULL_LEN=${#FULL_CHANGELOG}
-            if [ $FULL_LEN -gt 2500 ]; then
-              CHANGELOG="${CHANGELOG}"$'\n\n... (see full changelog on GitHub)'
-            fi
+            echo "$CHANGELOG" > /tmp/changelog.txt
           fi
 
-          echo "$CHANGELOG" > /tmp/changelog.txt
-          echo "DEBUG: Final changelog:"
+          echo "Telegram changelog:"
           cat /tmp/changelog.txt
 
       - name: Send to Telegram Channel

.gitignore

@@ -12,6 +12,9 @@ Thumbs.db
 # Kiro specs (development only)
 .kiro/
 
+# Design assets (banners, mockups)
+design/
+
 # Reference folder (development only)
 referensi/
 
@@ -64,6 +67,7 @@ AGENTS.md
 
 # Temp/misc
 nul
+network_requests.txt
 
 # Log files
 *.log
@@ -73,3 +77,6 @@ flutter_*.log
 # Development tools
 tool/
 .claude/settings.local.json
+
+# FVM Version Cache
+.fvm/

CHANGELOG.md

@@ -1,5 +1,187 @@
 # Changelog
 
+## [3.7.2] - 2026-03-07
+
+### Changed
+
+- **Amazon Music is now an Extension**: Amazon Music has been moved from a built-in service to a separate installable extension. Install the "Amazon Music" extension from the Store to continue using it.
+
+### Fixed
+
+- **Deezer Downloads Timing Out**: Deezer downloads were failing with "context deadline exceeded" on larger files. Now uses the proper download timeout, matching Tidal and Qobuz.
+- **iOS Local Library Scan Fails**: Local library scanning was failing on iOS because the app lost access to user-picked folders after the FilePicker session ended. Implemented iOS security-scoped bookmark system:
+  - When a library folder is picked on iOS, a security-scoped bookmark is created and persisted in settings (`localLibraryBookmark`)
+  - Before each scan, the bookmark is resolved and security-scoped access is started; access is released in `finally` block after scan completes
+  - `cleanupMissingFiles` also activates the bookmark before checking file existence on iOS
+  - New `AppDelegate.swift` method channel handlers: `createIosBookmarkFromPath`, `startAccessingIosBookmark`, `stopAccessingIosBookmark`, `resolveIosBookmark`
+  - New `PlatformBridge` methods: `createIosBookmarkFromPath()`, `startAccessingIosBookmark()`, `stopAccessingIosBookmark()`
+  - All scan call-sites (Library Settings, Queue tab, Local Album screen) now pass the iOS bookmark to `startScan()`
+
+### Added
+
+- **Amazon Music Extension**: Available in `extension/Amazon-SpotiFLAC/` — same functionality as before, now as an installable extension.
+- **Accessibility Tooltips**: Added localized tooltips to all `IconButton` and `PopupMenuButton` widgets across the entire UI for screen reader and long-press discoverability
+  - Back buttons use `MaterialLocalizations.backButtonTooltip`
+  - Close buttons use `MaterialLocalizations.closeButtonTooltip`
+  - Menu buttons use `MaterialLocalizations.showMenuTooltip`
+  - Search buttons use `MaterialLocalizations.searchFieldLabel`
+  - Contextual actions use descriptive labels: "Play track", "Dismiss", "Clear search", "Change folder", "Refresh"
+  - Screens affected: Album, Artist, Playlist, Downloaded Album, Local Album, Home, Search, Queue, Library Playlists, Library Tracks Folder, Setup, Tutorial, Track Metadata, Store, Extension Store Details, and all Settings sub-pages (About, Appearance, Cache Management, Donate, Download, Extensions, Extension Detail, Library, Log, Options, Provider Priority)
+- **Semantics Wrappers**: Added `Semantics` widgets to interactive elements that previously had no accessibility information
+  - Album tiles in Artist screen: announces selection state and album name
+  - Recently downloaded track tiles in Home tab: announces track name and artist
+  - Explore items (albums/artists/playlists) in Home tab: announces item type and name
+  - Color palette picker in Appearance settings: announces selected state and color hex value
+  - Download button demo in Tutorial screen: added `ExcludeSemantics` on icon to prevent duplicate screen reader announcements
+  - Queue tab playlist cards: announces playlist name and item count
+  - Queue tab downloaded album cards: announces album name, artist, and track count
+  - Queue tab local album cards: announces album name, artist, and track count
+  - Queue tab play button on completed downloads: announces track name and artist with `ExcludeSemantics` on icon
+  - Queue tab download status indicators: "Finalizing download", "Download completed", "Downloaded file missing" labels with `ExcludeSemantics` on icons
+
+### Improved
+
+- **Code Formatting**: Reformatted and corrected indentation across multiple files to comply with Dart style guidelines
+  - `extension_detail_page.dart`: Fixed `SliverAppBar` and all subsequent slivers indentation (was 2 spaces short)
+  - `log_screen.dart`: Fixed `SliverAppBar` indentation alignment
+  - `donate_page.dart`: Reformatted ternary expressions and `_cr` function body
+  - `library_tracks_folder_screen.dart`: Minor line-break formatting
+
+---
+
+## [3.7.1] - 2026-03-06
+
+### Added
+
+- **Deezer Download Service**: Deezer is now available as a built-in download service (FLAC CD Quality).
+- **Smarter YouTube Downloads**: If the YouTube Music extension is installed, the app now uses it first to find the correct song — more accurate than SongLink, especially for new releases.
+- **Songs-Only Search Filter**: YouTube Music extension search now filters results server-side, so you only get actual songs — no music videos or covers mixed in.
+- **Qobuz Squid.wtf Fallback**: Added Squid.wtf as an additional Qobuz download provider.
+- **Qobuz Search Fallback**: If Qobuz API search returns nothing, the app now tries the Qobuz web store as a backup to find the track.
+- **Better ISRC Lookup**: Tracks can now be resolved via ISRC even without a Spotify ID, using Deezer as an intermediary.
+
+### Fixed
+
+- **Download Queue Stability**: Fixed duplicate queue item IDs, cancel not working reliably, and "Clear All" not properly stopping active downloads.
+- **Queue Restore on Restart**: Duplicate or broken queue item IDs are now auto-fixed when the app restarts.
+
+### Changed
+
+- **Update Checker**: The app can now detect updates across all versions, not just within the same major version.
+- **Localization Cleanup**: Cleaned up and consolidated translation files across all 13 supported languages.
+
+---
+
+## [3.7.0] - 2026-03-04
+
+Hey everyone, thank you so much for sticking with SpotiFLAC Mobile.
+
+Starting from this release, we're rolling the version back from **v4.x to v3.x**.
+
+### Removed
+
+- **Internal Audio Player** — Removed `just_audio`, `audio_service`, and `audio_session` dependencies entirely. The internal playback engine (smart queue, media notification, shuffle/repeat, lyrics sync, prefetch, playback state persistence) has been completely removed. Playback now delegates to the system's external player.
+- **PlaybackItem Model** — No longer needed without internal playback.
+- **MiniPlayerBar Widget** — Removed the in-app mini player UI.
+- **Media Notification Controls** — Removed notification drawables (`ic_stat_favorite`, `ic_stat_favorite_border`) and the `keep.xml` resource file.
+- **Player Mode Setting** — The `playerMode` setting has been removed since external player is now the only mode.
+- **Online Playback Feature** — Online streaming mode, DASH pipeline, and related components introduced in v4.0.0 are gone from the main branch.
+
+### Changed
+
+- **MainActivity** now extends `FlutterFragmentActivity` directly (previously `AudioServiceFragmentActivity`).
+- **PlaybackController** simplified from ~1200 lines to ~87 lines — now only resolves local file paths and opens them via external player.
+- **ProGuard rules** cleaned up — removed audio_service/just_audio/audio_session rules.
+- **Qobuz** migrated to MusicDL API (Thanks @Ruubiiiii for Hosting the API).
+
+### Note
+There are three main reasons behind this decision:
+
+   1. **Respecting the API providers** — After giving it some thought, we realized that the streaming feature was indirectly hurting the API providers who have been generous enough to make their services available. They already offer streaming directly on their own websites, and it only feels right to direct streaming usage back to their platforms.
+
+   2. **Long-term sustainability** — We want SpotiFLAC to be around for as long as possible. Keeping certain features in the app could attract unwanted attention and put the project's continued existence at risk. Removing them is a proactive step to keep things running smoothly for everyone.
+
+**Still want online playback? Check out these services:**
+- [DabMusic](https://dabmusic.xyz)
+- [SquidWTF](https://tidal.squid.wtf)
+
+Thank you for your understanding and continued support. This decision was made to ensure the long-term sustainability of the app and to respect the ecosystem that has been supporting SpotiFLAC all along. You guys are the best, and we truly appreciate each and every one of you!
+
+---
+
+## [3.6.0] - 2026-02-19
+
+### Added
+
+- **Library Tab Redesign**: Wishlist, Loved, and individual Playlist collections now appear as unified list/grid items in the "All" tab alongside tracks, replacing the old "My Folders" horizontal card section
+- **Drag-and-Drop Track Categorization**: Long-press-drag tracks onto playlist items to add them to that playlist; when multiple tracks are selected and one is dragged, all selected tracks are added to the target playlist
+  - Drag feedback widget displays multi-select count badge
+- **Playlist Multi-Select Deletion**: Long-press playlists to enter selection mode, select multiple playlists, and batch-delete all selected at once via a dedicated selection bottom bar
+- **Track Categorization System**: Tracks added to any playlist are automatically hidden from the main tracks list; removing a track from a playlist or deleting the playlist makes the track reappear — no actual file deletion ever occurs
+- **Create Playlist Button**: New "+" `TextButton.icon` in Library tab header with dynamic theme colors, replacing the old "Select" button
+- **Track Options Bottom Sheet**: Rewrote `TrackCollectionQuickActions` from inline action buttons to a single styled bottom sheet with track header (cover, title, artist), divider, and option tiles matching `DownloadServicePicker` visual style
+- **Library Tracks Folder SliverAppBar**: Wishlist, Loved, and Playlist detail screens now feature a collapsible SliverAppBar with cover art (45% viewport height, parallax, gradient overlay), mode-specific icons (bookmark/heart/queue_music), title, and track count badge
+- **Custom Playlist Cover Images**: Users can set custom cover images for playlists via long-press menu or camera icon in SliverAppBar
+  - Covers stored locally in app support directory with priority: custom cover > first track URL > icon fallback
+  - Cover options bottom sheet with change/remove actions
+  - Playlist list screen shows cover thumbnails
+- **Long-Press Context Menus**: Track tiles in library folders and playlist list items now use long-press for styled bottom sheet context menus instead of trailing icon buttons, matching platform conventions
+- **Wishlist Quick Download**: Tapping a track in Wishlist opens quality picker (respects "Ask quality before download" setting) and starts download
+- **Playlist Track Playback**: Tapping a downloaded track in a Playlist opens it in the device's external music player via `openFile()` with file existence check
+- **Collapsible AppBar on Playlist List Screen**: Playlist list screen now uses a collapsible SliverAppBar matching Settings sub-page style (animated title size 20→28px, animated left padding 56→24px) for visual consistency
+- **`UnifiedLibraryItem.collectionKey` Getter**: Efficient playlist membership checking without constructing a full `Track` object
+- **Multi-select Share**: Share multiple downloaded/local tracks at once from the selection bottom bar
+  - Supports SAF content URIs via native `ACTION_SEND_MULTIPLE` intent
+  - Supports regular file paths via SharePlus
+  - Available in Downloaded Album, Local Album, and Queue tab screens
+- **Multi-select Batch Convert**: Convert multiple selected tracks to MP3 or Opus in one operation
+  - Bottom sheet UI with format (MP3 / Opus) and bitrate (128k / 192k / 256k / 320k) selection
+  - Full SAF support: copies to temp, converts, writes back, deletes original, updates history
+  - Progress and result snackbar feedback during conversion
+  - Available in Downloaded Album, Local Album, and Queue tab screens
+- **Native `shareMultipleContentUris`**: New Android `ACTION_SEND_MULTIPLE` handler in `MainActivity` for sharing multiple SAF content URIs
+- **Localization**: Added selection share/convert strings to all 13 supported locales (`selectionShareCount`, `selectionShareNoFiles`, `selectionConvertCount`, `selectionConvertNoConvertible`, `selectionBatchConvertConfirmTitle`, `selectionBatchConvertConfirmMessage`, `selectionBatchConvertProgress`, `selectionBatchConvertSuccess`)
+- **Localization**: Added library collection l10n keys (`trackOptionAddToLoved`, `trackOptionRemoveFromLoved`, `trackOptionAddToWishlist`, `trackOptionRemoveFromWishlist`, `libraryTracksUnit`, `collectionPlaylistChangeCover`, `collectionPlaylistRemoveCover`)
+- **Global Network Compatibility Mode**: New Download settings toggle to help restricted/ISP-filtered networks
+  - Applies to backend API requests (not SongLink-only)
+  - Enables HTTP scheme fallback and optional insecure TLS behavior in one switch
+  - Synced end-to-end across Flutter settings, platform channel (Android/iOS), and Go backend
+
+### Changed
+
+- **Removed "My Folders" Section**: Horizontal card section removed from Library tab header; collections are now inline items in the unified main list/grid
+- **Playlist Subtitle Simplified**: Playlist items now show "N tracks" instead of "Playlist • N tracks"
+- **Pinned App Bar on All Detail Screens**: `SliverAppBar` changed from `pinned: false` to `pinned: true` in 6 detail screens (album, downloaded album, local album, playlist, track metadata, library tracks folder) so the app bar stays visible when scrolling
+- **Local Album Multi-select Action Updated**: Replaced batch `Share` action with batch `Re-enrich`
+  - Local album selection bar now uses `Re-enrich` + `Convert` actions
+  - Added batch re-enrich processing for local tracks (FLAC native path and MP3/Opus FFmpeg path, including SAF write-back flow)
+  - After batch re-enrich completes, local library is refreshed via incremental scan so updated metadata appears in UI immediately
+- **Queue Multi-select Local Action Updated**: Queue selection bar now switches the first action to `Re-enrich` when selected items are local-only
+  - If selection contains downloaded or mixed items, action remains `Share`
+  - Local-only selection now supports batch re-enrich with the same native/FFmpeg + SAF flow and auto-refreshes local library metadata after completion
+- **SongLink Network Option Scope Expanded**: The previous SongLink compatibility path now routes through global network compatibility controls so all supported backend API clients can benefit under problematic networks
+- **Removed Per-Track Action Buttons**: Album, playlist, home, artist, and search screens no longer show individual download/add buttons on each track tile; all actions accessed via `TrackCollectionQuickActions` bottom sheet
+- **Loved SliverAppBar Always Shows Heart Icon**: Loved tracks folder always displays the heart icon as cover, never uses first track's cover art (like Spotify's Liked Songs)
+- **Wishlist Long-Press Menu Conditional Actions**: "Add to Playlist" option only appears when the track is already downloaded
+- **Loved Track Tap Disabled**: Tapping a track in the Loved folder performs no action (long-press for options only)
+- **Removed Duplicate Create Playlist Button**: Removed `+` IconButton from playlist list screen AppBar since the FAB already serves the same purpose
+- **`coverImagePath` Field on `UserPlaylistCollection`**: Model now supports nullable custom cover path with `copyWith` using `String? Function()?` pattern for explicit null assignment
+
+### Fixed
+
+- **Local Cover Path Handling**: All cover image renderers (Library tab, playlist detail screen hero cover, per-track tiles, options bottom sheet) now detect whether `coverUrl` is a URL or local file path and use `Image.file` for local paths instead of `CachedNetworkImage`
+- **Empty Playlists Now Clickable**: Empty playlist items in Library tab can now be tapped to navigate to their detail screen
+- **RenderFlex Overflow**: Fixed overflow in unified library item Row layout when track metadata text was too long
+- **SAF FD Permission Denied on Tidal Downloads**: Fixed `failed to create file: open /proc/self/fd/*: permission denied` on some devices/providers
+  - Android SAF bridge now hands off detached raw FD (`output_fd`) to Go instead of forcing procfs path reopen
+  - Go output writer includes safer procfs fallback behavior for providers that reject truncate semantics
+- **Batch Convert Lyrics Embedding Gap**: Batch convert in Downloaded Album, Local Album, and Queue now preserves/adds lyrics consistently like single convert
+  - Reuses embedded lyrics when available
+  - Falls back to sidecar `.lrc` when present
+  - Falls back to online lyrics fetch and injects into conversion metadata when embedding is enabled
+
+---
+
 ## [3.6.9] - 2026-02-17
 
 ### Added
@@ -152,7 +334,7 @@
   - Routing priority: YouTube service -> extension fallback -> built-in fallback -> direct service
 - New Android method channel handler: `"downloadByStrategy"` -> `Gobackend.downloadByStrategy(...)`
 - SpotFetch metadata fallback integration for Spotify-blocked regions
-  - New backend client for `spotify.afkarxyz.fun/api`
+  - New backend client for `sp.afkarxyz.qzz.io/api`
   - Automatic fallback in Spotify metadata fetch path when primary source fails
 - Lyrics extraction now supports MP3 (ID3v2) and Opus/OGG (Vorbis comments) in addition to FLAC
   - Includes heuristic detection of lyrics stored in Comment fields
@@ -167,7 +349,7 @@
 - Legacy Dart bridge methods (`downloadTrack`, `downloadWithFallback`, `downloadWithExtensions`, `downloadFromYouTube`) are now thin wrappers and marked `@Deprecated`
 - Qobuz downloader updated to latest Jumo API contract (`/get` endpoint, required headers)
 - Amazon download flow now returns `decryption_key` from Go and performs decryption in Flutter (local file + SAF paths)
-- Amazon now uses the new `amazon.afkarxyz.fun` API flow (ASIN-based track endpoint + legacy fallback) with encrypted stream support
+- Amazon now uses the new `amzn.afkarxyz.qzz.io` API flow (ASIN-based track endpoint + legacy fallback) with encrypted stream support
 - Amazon ASIN extraction rewritten with robust URL/query-param parsing and regex fallback
 - Amazon provider re-enabled in download service picker and download settings (alongside Tidal, Qobuz, and YouTube picker flow)
 - Track Metadata cover UI now refreshes from the embedded file after Edit Metadata/Re-enrich, so the displayed art matches actual file tags

CONTRIBUTING.md

@@ -86,17 +86,31 @@ Translation files are located in `lib/l10n/arb/`.
    git remote add upstream https://github.com/zarzet/SpotiFLAC-Mobile.git
    ```
 
-3. **Install dependencies**
+3. **Use FVM (Flutter Version: 3.38.1)**
+   ```bash
+   fvm use
+   ```
+
+4. **Install dependencies**
    ```bash
    flutter pub get
    ```
 
-4. **Generate code** (for Riverpod, JSON serialization, etc.)
+5. **Generate code** (for Riverpod, JSON serialization, etc.)
    ```bash
    dart run build_runner build --delete-conflicting-outputs
    ```
 
-5. **Run the app**
+6. **Set up Go environment (Go Version: 1.25.7)**
+   ```bash
+   cd go_backend 
+   mkdir -p ../android/app/libs
+   gomobile init
+   gomobile bind -target=android -androidapi 24 -o ../android/app/libs/gobackend.aar .
+   cd ..
+   ```
+
+7. **Run the app**
    ```bash
    flutter run
    ```

README.md

@@ -1,20 +1,19 @@
-[![GitHub All Releases](https://img.shields.io/github/downloads/zarzet/SpotiFLAC-Mobile/total?style=for-the-badge&refresh=1)](https://github.com/zarzet/SpotiFLAC-Mobile/releases)
-[![VirusTotal](https://img.shields.io/badge/VirusTotal-Safe-brightgreen?style=for-the-badge&logo=virustotal)](https://www.virustotal.com/gui/file/40f8f1914287dea317122a837f98b0ddf7af3205adc2f84a350d767e0a6a345c)
-[![Crowdin](https://img.shields.io/badge/HELP%20TRANSLATE%20ON-CROWDIN-%2321252b?style=for-the-badge&logo=crowdin)](https://crowdin.com/project/spotiflac-mobile)
-
 <div align="center">
 
-<img src="icon.png" width="128" />
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="assets/images/banner-readme-dark.png">
+  <source media="(prefers-color-scheme: light)" srcset="assets/images/banner-readme-light.png">
+  <img alt="SpotiFLAC Mobile" src="assets/images/banner-readme-light.png" width="650" height="auto">
+</picture>
 
-Download music in true lossless FLAC from Tidal, Qobuz & Amazon Music — no account required.
-
-![Android](https://img.shields.io/badge/Android-7.0%2B-3DDC84?style=for-the-badge&logo=android&logoColor=white)
-![iOS](https://img.shields.io/badge/iOS-14.0%2B-000000?style=for-the-badge&logo=apple&logoColor=white)
+<p align="center">
+  <a href="https://trendshift.io/repositories/17247">
+    <img src="https://trendshift.io/api/badge/repositories/17247" alt="zarzet%2FSpotiFLAC-Mobile | Trendshift" width="250" height="55">
+  </a>
+</p>
 
 </div>
 
-### [Download](https://github.com/zarzet/SpotiFLAC-Mobile/releases)
-
 ## Screenshots
 
 <p align="center">
@@ -24,37 +23,47 @@ Download music in true lossless FLAC from Tidal, Qobuz & Amazon Music — no acc
   <img src="assets/images/4.jpg?v=2" width="200" />
 </p>
 
+<div align="center">
+
+[![GitHub Release](https://img.shields.io/github/v/release/zarzet/SpotiFLAC-Mobile?style=for-the-badge&logo=github)](https://github.com/zarzet/SpotiFLAC-Mobile/releases)
+[![VirusTotal](https://img.shields.io/badge/VirusTotal-Safe-brightgreen?style=for-the-badge&logo=virustotal)](https://www.virustotal.com/gui/file/63a445a956fa71ea347ad3695a62d543e14e341933326b9dbb9a15d79614ef58)
+[![Crowdin](https://img.shields.io/badge/HELP%20TRANSLATE%20ON-CROWDIN-%2321252b?style=for-the-badge&logo=crowdin)](https://crowdin.com/project/spotiflac-mobile)
+
+[![Telegram Channel](https://img.shields.io/badge/CHANNEL-2CA5E0?style=for-the-badge&logo=telegram&logoColor=white)](https://t.me/spotiflac)
+[![Telegram Community](https://img.shields.io/badge/COMMUNITY-2CA5E0?style=for-the-badge&logo=telegram&logoColor=white)](https://t.me/spotiflac_chat)
+
+</div>
+
 ## Extensions
 
 Extensions allow the community to add new music sources and features without waiting for app updates. When a streaming service API changes or a new source becomes available, extensions can be updated independently.
 
 ### Installing Extensions
 1. Go to **Store** tab in the app
-2. Browse and install extensions with one tap
-3. Or download a `.spotiflac-ext` file and install manually via **Settings > Extensions**
-4. Configure extension settings if needed
-5. Set provider priority in **Settings > Extensions > Provider Priority**
+2. When opening the Store for the first time, you will be asked to enter an **Extension Repository URL**
+3. Browse and install extensions with one tap
+4. Or download a `.spotiflac-ext` file and install manually via **Settings > Extensions**
+5. Configure extension settings if needed
+6. Set provider priority in **Settings > Extensions > Provider Priority**
 
 ### Developing Extensions
-Want to create your own extension? Check out the [Extension Development Guide](https://zarz.moe/docs) for complete documentation.
+Want to create your own extension? Check out the [Extension Development Guide](https://zarzet.github.io/SpotiFLAC-Mobile/docs) for complete documentation.
 
 ## Other project
 
 ### [SpotiFLAC (Desktop)](https://github.com/afkarxyz/SpotiFLAC)
 Download music in true lossless FLAC from Tidal, Qobuz & Amazon Music for Windows, macOS & Linux
 
-## Telegram
-
-[![Telegram Channel](https://img.shields.io/badge/CHANNEL-2CA5E0?style=for-the-badge&logo=telegram&logoColor=white)](https://t.me/spotiflac)
-[![Telegram Community](https://img.shields.io/badge/COMMUNITY-2CA5E0?style=for-the-badge&logo=telegram&logoColor=white)](https://t.me/spotiflac_chat)
-
 ## FAQ
 
+**Q: Why does the Store tab ask me to enter a URL?**  
+A: Starting from version 3.8.0, SpotiFLAC uses a decentralized extension repository system — extensions are hosted on GitHub repositories rather than a built-in server, so anyone can create and host their own. Enter a repository URL in the Store tab to browse and install extensions.
+
 **Q: Why is my download failing with "Song not found"?**  
-A: The track may not be available on Tidal, Qobuz, or Amazon Music. Try enabling more download services in Settings > Download > Provider Priority, or install additional extensions from the Store.
+A: The track may not be available on the streaming services. Try enabling more download services in Settings > Download > Provider Priority, or install additional extensions like Amazon Music from the Store.
 
 **Q: Why are some tracks downloading in lower quality?**  
-A: Quality depends on what's available from the streaming service. Tidal offers up to 24-bit/192kHz, Qobuz up to 24-bit/192kHz, and Amazon up to 24-bit/48kHz. The app automatically selects the best available quality.
+A: Quality depends on what's available from the streaming service and extensions. Built-in providers: Tidal offers up to 24-bit/192kHz, Qobuz up to 24-bit/192kHz, and Deezer up to 16-bit/44.1kHz.
 
 **Q: Can I download playlists?**  
 A: Yes! Just paste the playlist URL in the search bar. The app will fetch all tracks and queue them for download.
@@ -68,6 +77,11 @@ A: Yes, the app is open source and you can verify the code yourself. Each releas
 **Q: Why is download not working in my country?**  
 A: Some countries have restricted access to certain streaming service APIs. If downloads are failing, try using a VPN to connect through a different region.
 
+**Q: Can I add SpotiFLAC to AltStore or SideStore?**
+A: Yes! You can add the official source to receive updates directly within the app. Just copy this link:
+https://raw.githubusercontent.com/zarzet/SpotiFLAC-Mobile/refs/heads/main/apps.json
+In AltStore/SideStore, go to the Browse tab, tap Sources at the top, then tap the + icon and paste the link.
+
 
 ### Want to support SpotiFLAC-Mobile?
 
@@ -75,33 +89,23 @@ _If this software is useful and brings you value, consider supporting the projec
 
 [![Ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/zarzet)
 
+## Contributors
 
-## Disclaimer
+Thanks to all the amazing people who have contributed to SpotiFLAC Mobile!
 
-This project is for **educational and private use only**. The developer does not condone or encourage copyright infringement.
+<a href="https://github.com/zarzet/SpotiFLAC-Mobile/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=zarzet/SpotiFLAC-Mobile" />
+</a>
 
-**SpotiFLAC** is a third-party tool and is not affiliated with, endorsed by, or connected to Tidal, Qobuz, Amazon Music, Deezer, or any other streaming service.
-
-The application is purely a user interface that facilitates communication between your device and existing third-party services.
-
-You are solely responsible for:
-1. Ensuring your use of this software complies with your local laws.
-2. Reading and adhering to the Terms of Service of the respective platforms.
-3. Any legal consequences resulting from the misuse of this tool.
-
-The software is provided "as is", without warranty of any kind. The author assumes no liability for any bans, damages, or legal issues arising from its use.
+We also appreciate everyone who has helped with [translations on Crowdin](https://crowdin.com/project/spotiflac-mobile), reported bugs, suggested features, and spread the word about SpotiFLAC Mobile.
 
+Interested in contributing? Check out our [Contributing Guide](CONTRIBUTING.md) to get started!
 
 ## API Credits
 
-- **Tidal**: [hifi-api](https://github.com/binimum/hifi-api), [music.binimum.org](https://music.binimum.org), [qqdl.site](https://qqdl.site), [squid.wtf](https://squid.wtf), [spotisaver.net](https://spotisaver.net)
-- **Qobuz**: [dabmusic.xyz](https://dabmusic.xyz), [squid.wtf](https://squid.wtf), [jumo-dl](https://jumo-dl.pages.dev)
-- **Amazon**: [AfkarXYZ](https://github.com/afkarxyz)
-- **Lyrics**: [LRCLib](https://lrclib.net), [Paxsenix](https://lyrics.paxsenix.org) (Apple Music/QQ Music lyrics proxy)
-- **YouTube Audio**: [Cobalt](https://cobalt.tools) via [qwkuns.me](https://qwkuns.me), [SpotubeDL](https://spotubedl.com)
-- **Track Linking**: [SongLink / Odesli](https://odesli.co), [IDHS](https://github.com/sjdonado/idonthavespotify)
+[hifi-api](https://github.com/binimum/hifi-api) · [music.binimum.org](https://music.binimum.org) · [qqdl.site](https://qqdl.site) · [squid.wtf](https://squid.wtf) · [spotisaver.net](https://spotisaver.net) · [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)
 
 
 > [!TIP]
 >
-> **Star Us**, You will receive all release notifications from GitHub without any delay ~
+> **Star Us**, You will receive all release notifications from GitHub without any delay 

android/app/src/main/AndroidManifest.xml

@@ -12,6 +12,7 @@
     <uses-permission android:name="android.permission.READ_MEDIA_AUDIO" />
     <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
     <uses-permission android:name="android.permission.FOREGROUND_SERVICE_DATA_SYNC" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />
     <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
     <uses-permission android:name="android.permission.REQUEST_INSTALL_PACKAGES" />
     <uses-permission android:name="android.permission.WAKE_LOCK" />
@@ -21,6 +22,7 @@
         android:name="${applicationName}"
         android:icon="@mipmap/ic_launcher"
         android:usesCleartextTraffic="false"
+        android:networkSecurityConfig="@xml/network_security_config"
         android:enableOnBackInvokedCallback="true"
         android:localeConfig="@xml/locale_config">
 
@@ -92,6 +94,24 @@
             android:exported="false"
             android:foregroundServiceType="dataSync" />
 
+        <!-- Audio playback service for media notification / background audio -->
+        <service
+            android:name="com.ryanheise.audioservice.AudioService"
+            android:exported="true"
+            android:foregroundServiceType="mediaPlayback">
+            <intent-filter>
+                <action android:name="android.media.browse.MediaBrowserService" />
+            </intent-filter>
+        </service>
+
+        <receiver
+            android:name="com.ryanheise.audioservice.MediaButtonReceiver"
+            android:exported="true">
+            <intent-filter>
+                <action android:name="android.intent.action.MEDIA_BUTTON" />
+            </intent-filter>
+        </receiver>
+
         <!-- flutter_local_notifications receivers -->
         <receiver android:exported="false" android:name="com.dexterous.flutterlocalnotifications.ScheduledNotificationReceiver" />
         <receiver android:exported="false" android:name="com.dexterous.flutterlocalnotifications.ScheduledNotificationBootReceiver">

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

@@ -115,10 +115,8 @@ class DownloadService : Service() {
      * We must call stopSelf() within a few seconds to avoid a crash.
      */
     override fun onTimeout(startId: Int, fgsType: Int) {
-        // Log the timeout for debugging
         android.util.Log.w("DownloadService", "Foreground service timeout reached (6 hours limit). Stopping service.")
         
-        // Gracefully stop the service
         stopForegroundService()
     }
     

android/app/src/main/res/xml/network_security_config.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="utf-8"?>
+<network-security-config>
+    <base-config cleartextTrafficPermitted="false" />
+
+    <!-- Allow local loopback cleartext for FFmpeg live decrypt tunnel only. -->
+    <domain-config cleartextTrafficPermitted="true">
+        <domain includeSubdomains="true">localhost</domain>
+        <domain includeSubdomains="true">127.0.0.1</domain>
+    </domain-config>
+</network-security-config>

apps.json

@@ -0,0 +1,18 @@
+{
+  "name": "SpotiFLAC Source",
+  "identifier": "com.zarzet.spotiflac.source",
+  "subtitle": "FLAC Downloader for iOS",
+  "apps": [
+    {
+      "name": "SpotiFLAC",
+      "bundleIdentifier": "com.zarzet.spotiflac",
+      "developerName": "zarzet",
+      "version": "3.8.6",
+      "versionDate": "2026-03-16",
+      "downloadURL": "https://github.com/zarzet/SpotiFLAC-Mobile/releases/download/v3.8.6/SpotiFLAC-v3.8.6-ios-unsigned.ipa",
+      "localizedDescription": "Mobile version of SpotiFLAC written in Flutter. Download Tracks in true FLAC from Tidal, Qobuz, & Amazon Music.",
+      "iconURL": "https://raw.githubusercontent.com/zarzet/SpotiFLAC-Mobile/main/assets/images/logo.png",
+      "size": 33676960
+    }
+  ]
+}

cliff.toml

@@ -0,0 +1,103 @@
+# git-cliff configuration for SpotiFLAC Mobile
+# https://git-cliff.org/docs/configuration
+
+[changelog]
+# Template for the changelog body
+body = """
+{%- macro remote_url() -%}
+  https://github.com/zarzet/SpotiFLAC-Mobile
+{%- endmacro -%}
+
+{% if version %}\
+    ## {{ version | trim_start_matches(pat="v") }}
+{% else %}\
+    ## Unreleased
+{% endif %}\
+
+{% for group, commits in commits | group_by(attribute="group") %}
+    ### {{ group | striptags | trim | upper_first }}
+    {% for commit in commits %}
+        - {% if commit.scope %}**{{ commit.scope }}**: {% endif %}\
+            {{ commit.message | upper_first }}\
+            {% if commit.github.pr_number %} \
+                ([#{{ commit.github.pr_number }}]({{ self::remote_url() }}/pull/{{ commit.github.pr_number }}))\
+            {% endif %}\
+            {%- if commit.github.username and commit.github.username != "zarzet" %} by [@{{ commit.github.username }}](https://github.com/{{ commit.github.username }}){%- endif %}
+    {%- endfor %}
+{% endfor %}
+
+{%- if github.contributors | filter(attribute="is_first_time", value=true) | length != 0 %}
+
+  ### New Contributors
+{%- for contributor in github.contributors | filter(attribute="is_first_time", value=true) %}
+  * @{{ contributor.username }} made their first contribution
+    {%- if contributor.pr_number %} in \
+      [#{{ contributor.pr_number }}]({{ self::remote_url() }}/pull/{{ contributor.pr_number }}) \
+    {%- endif %}
+{%- endfor %}
+{%- endif -%}
+
+{% if version %}
+    {% if previous.version %}
+      **Full Changelog**: [{{ previous.version }}...{{ version }}]({{ self::remote_url() }}/compare/{{ previous.version }}...{{ version }})
+    {% endif %}
+{% else -%}
+    {% raw %}\n{% endraw %}
+{% endif %}
+"""
+# Remove leading and trailing whitespace
+trim = true
+
+[git]
+# Parse conventional commits
+conventional_commits = true
+filter_unconventional = true
+
+# Process each line of a commit as an individual commit
+split_commits = false
+
+# Regex for preprocessing the commit messages
+commit_preprocessors = [
+  # Strip conventional commit prefix for cleaner messages
+  # (group header already shows the type)
+]
+
+# Regex for parsing and grouping commits
+commit_parsers = [
+  # Skip noise: translation commits from Crowdin
+  { message = "^New translations", skip = true },
+  { message = "^Update source file", skip = true },
+  # Skip merge commits
+  { message = "^Merge", skip = true },
+  # Skip version bump commits
+  { message = "^v\\d+", skip = true },
+  { message = "^chore: update VirusTotal", skip = true },
+
+  # Group by conventional commit type
+  { message = "^feat", group = "<!-- 0 -->New Features" },
+  { message = "^fix", group = "<!-- 1 -->Bug Fixes" },
+  { message = "^perf", group = "<!-- 2 -->Performance" },
+  { message = "^refactor", group = "<!-- 3 -->Refactoring" },
+  { message = "^doc", group = "<!-- 4 -->Documentation" },
+  { message = "^style", group = "<!-- 5 -->Styling" },
+  { message = "^test", group = "<!-- 6 -->Testing" },
+  { message = "^chore\\(deps\\)", group = "<!-- 7 -->Dependencies" },
+  { message = "^chore\\(l10n\\)", skip = true },
+  { message = "^chore|^ci", group = "<!-- 8 -->Chores" },
+]
+
+# Protect breaking changes from being skipped
+protect_breaking_commits = true
+
+# Filter out commits by matching patterns
+filter_commits = false
+
+# Tag pattern for version detection
+tag_pattern = "v[0-9].*"
+
+# Sort commits by newest first
+sort_commits = "newest"
+
+[remote.github]
+owner = "zarzet"
+repo = "SpotiFLAC-Mobile"

go_backend/amazon.go

@@ -1,662 +0,0 @@
-package gobackend
-
-import (
-	"bufio"
-	"context"
-	"encoding/json"
-	"errors"
-	"fmt"
-	"io"
-	"net/http"
-	"net/url"
-	"os"
-	"path/filepath"
-	"regexp"
-	"strings"
-	"sync"
-	"time"
-)
-
-// Amazon API timeout and retry configuration for mobile networks
-const (
-	amazonAPITimeoutMobile = 30 * time.Second // Longer timeout for unstable mobile networks
-	amazonMaxRetries       = 2                // Number of retry attempts
-	amazonRetryDelay       = 500 * time.Millisecond
-)
-
-type AmazonDownloader struct {
-	client *http.Client
-}
-
-var (
-	globalAmazonDownloader *AmazonDownloader
-	amazonDownloaderOnce   sync.Once
-	amazonASINRegex        = regexp.MustCompile(`(?i)^B[0-9A-Z]{9}$`)
-	amazonASINFindRegex    = regexp.MustCompile(`(?i)B[0-9A-Z]{9}`)
-)
-
-// AfkarXYZResponse is the response from AfkarXYZ API
-type AfkarXYZResponse struct {
-	Success bool `json:"success"`
-	Data    struct {
-		DirectLink string `json:"direct_link"`
-		FileName   string `json:"file_name"`
-		FileSize   int64  `json:"file_size"`
-	} `json:"data"`
-}
-
-// AmazonStreamResponse is the new response format from amazon.afkarxyz.fun/api/track/{asin}
-type AmazonStreamResponse struct {
-	StreamURL     string `json:"streamUrl"`
-	DecryptionKey string `json:"decryptionKey"`
-}
-
-func NewAmazonDownloader() *AmazonDownloader {
-	amazonDownloaderOnce.Do(func() {
-		globalAmazonDownloader = &AmazonDownloader{
-			client: NewHTTPClientWithTimeout(120 * time.Second),
-		}
-	})
-	return globalAmazonDownloader
-}
-
-// fetchAmazonURLWithRetry fetches from AfkarXYZ API with retry logic for mobile networks.
-// Returns downloadURL, suggested fileName, optional decryptionKey.
-func (a *AmazonDownloader) fetchAmazonURLWithRetry(amazonURL string) (string, string, string, error) {
-	var lastErr error
-	for attempt := 0; attempt <= amazonMaxRetries; attempt++ {
-		if attempt > 0 {
-			delay := amazonRetryDelay * time.Duration(1<<(attempt-1)) // Exponential backoff
-			GoLog("[Amazon] Retry %d/%d after %v...\n", attempt, amazonMaxRetries, delay)
-			time.Sleep(delay)
-		}
-
-		downloadURL, fileName, decryptionKey, err := a.doAfkarXYZRequest(amazonURL)
-		if err == nil {
-			return downloadURL, fileName, decryptionKey, nil
-		}
-
-		lastErr = err
-		errStr := strings.ToLower(err.Error())
-
-		// Check if error is retryable
-		isRetryable := strings.Contains(errStr, "timeout") ||
-			strings.Contains(errStr, "connection reset") ||
-			strings.Contains(errStr, "connection refused") ||
-			strings.Contains(errStr, "eof") ||
-			strings.Contains(errStr, "status 5") ||
-			strings.Contains(errStr, "status 429") ||
-			strings.Contains(errStr, "http 429")
-
-		if !isRetryable {
-			return "", "", "", err
-		}
-
-		GoLog("[Amazon] Attempt %d failed (retryable): %v\n", attempt+1, err)
-	}
-
-	return "", "", "", fmt.Errorf("all %d attempts failed: %w", amazonMaxRetries+1, lastErr)
-}
-
-func normalizeAmazonASIN(candidate string) string {
-	trimmed := strings.TrimSpace(candidate)
-	if trimmed == "" {
-		return ""
-	}
-
-	if decoded, err := url.QueryUnescape(trimmed); err == nil {
-		trimmed = decoded
-	}
-
-	trimmed = strings.ToUpper(trimmed)
-	if idx := strings.IndexAny(trimmed, "?#&/"); idx >= 0 {
-		trimmed = trimmed[:idx]
-	}
-
-	if amazonASINRegex.MatchString(trimmed) {
-		return trimmed
-	}
-
-	return ""
-}
-
-func extractAmazonASIN(amazonURL string) string {
-	raw := strings.TrimSpace(amazonURL)
-	if raw == "" {
-		return ""
-	}
-
-	parsed, err := url.Parse(raw)
-	if err == nil {
-		query := parsed.Query()
-
-		// Prefer track-level ASIN when URL also contains albumAsin.
-		for _, key := range []string{"trackAsin", "trackasin", "trackASIN", "asin", "ASIN", "i"} {
-			if asin := normalizeAmazonASIN(query.Get(key)); asin != "" {
-				return asin
-			}
-		}
-
-		path := strings.Trim(parsed.Path, "/")
-		if path != "" {
-			segments := strings.Split(path, "/")
-
-			for i := 0; i < len(segments)-1; i++ {
-				segment := strings.ToLower(strings.TrimSpace(segments[i]))
-				if segment == "track" || segment == "tracks" {
-					if asin := normalizeAmazonASIN(segments[i+1]); asin != "" {
-						return asin
-					}
-				}
-			}
-
-			if asin := normalizeAmazonASIN(segments[len(segments)-1]); asin != "" {
-				return asin
-			}
-		}
-	}
-
-	match := amazonASINFindRegex.FindString(strings.ToUpper(raw))
-	return normalizeAmazonASIN(match)
-}
-
-// doAfkarXYZRequest performs a single request to Amazon API.
-// It tries new endpoint first, then falls back to legacy /convert endpoint.
-func (a *AmazonDownloader) doAfkarXYZRequest(amazonURL string) (string, string, string, error) {
-	asin := extractAmazonASIN(amazonURL)
-	if asin != "" {
-		GoLog("[Amazon] Using ASIN: %s\n", asin)
-		downloadURL, fileName, decryptKey, err := a.doAfkarXYZRequestNew(asin)
-		if err == nil {
-			return downloadURL, fileName, decryptKey, nil
-		}
-		GoLog("[Amazon] New API failed for ASIN %s, trying legacy endpoint: %v\n", asin, err)
-	}
-	return a.doAfkarXYZRequestLegacy(amazonURL)
-}
-
-func (a *AmazonDownloader) doAfkarXYZRequestNew(asin string) (string, string, string, error) {
-	ctx, cancel := context.WithTimeout(context.Background(), amazonAPITimeoutMobile)
-	defer cancel()
-
-	apiURL := fmt.Sprintf("https://amazon.afkarxyz.fun/api/track/%s", asin)
-	req, err := http.NewRequestWithContext(ctx, "GET", apiURL, nil)
-	if err != nil {
-		return "", "", "", fmt.Errorf("failed to create request: %w", err)
-	}
-
-	req.Header.Set("User-Agent", "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/144.0.0.0 Safari/537.36")
-
-	resp, err := a.client.Do(req)
-	if err != nil {
-		return "", "", "", fmt.Errorf("failed to call Amazon API: %w", err)
-	}
-	defer resp.Body.Close()
-
-	if resp.StatusCode != 200 {
-		return "", "", "", fmt.Errorf("Amazon API returned status %d", resp.StatusCode)
-	}
-
-	body, err := io.ReadAll(resp.Body)
-	if err != nil {
-		return "", "", "", fmt.Errorf("failed to read response: %w", err)
-	}
-
-	var apiResp AmazonStreamResponse
-	if err := json.Unmarshal(body, &apiResp); err != nil {
-		return "", "", "", fmt.Errorf("failed to decode response: %w", err)
-	}
-
-	if strings.TrimSpace(apiResp.StreamURL) == "" {
-		return "", "", "", fmt.Errorf("Amazon API returned empty stream URL")
-	}
-
-	fileName := asin + ".m4a"
-	return apiResp.StreamURL, fileName, strings.TrimSpace(apiResp.DecryptionKey), nil
-}
-
-func (a *AmazonDownloader) doAfkarXYZRequestLegacy(amazonURL string) (string, string, string, error) {
-	ctx, cancel := context.WithTimeout(context.Background(), amazonAPITimeoutMobile)
-	defer cancel()
-
-	apiURL := "https://amazon.afkarxyz.fun/convert?url=" + url.QueryEscape(amazonURL)
-	req, err := http.NewRequestWithContext(ctx, "GET", apiURL, nil)
-	if err != nil {
-		return "", "", "", fmt.Errorf("failed to create legacy request: %w", err)
-	}
-
-	req.Header.Set("User-Agent", getRandomUserAgent())
-
-	resp, err := a.client.Do(req)
-	if err != nil {
-		return "", "", "", fmt.Errorf("failed to call legacy AfkarXYZ API: %w", err)
-	}
-	defer resp.Body.Close()
-
-	if resp.StatusCode != 200 {
-		return "", "", "", fmt.Errorf("legacy AfkarXYZ API returned status %d", resp.StatusCode)
-	}
-
-	body, err := io.ReadAll(resp.Body)
-	if err != nil {
-		return "", "", "", fmt.Errorf("failed to read legacy response: %w", err)
-	}
-
-	var apiResp AfkarXYZResponse
-	if err := json.Unmarshal(body, &apiResp); err != nil {
-		return "", "", "", fmt.Errorf("failed to decode legacy response: %w", err)
-	}
-
-	if !apiResp.Success || strings.TrimSpace(apiResp.Data.DirectLink) == "" {
-		return "", "", "", fmt.Errorf("legacy AfkarXYZ API failed or no download link found")
-	}
-
-	fileName := apiResp.Data.FileName
-	if fileName == "" {
-		fileName = "track.flac"
-	}
-
-	reg := regexp.MustCompile(`[<>:"/\\|?*]`)
-	fileName = reg.ReplaceAllString(fileName, "")
-
-	return apiResp.Data.DirectLink, fileName, "", nil
-}
-
-func (a *AmazonDownloader) downloadFromAfkarXYZ(amazonURL string) (string, string, string, error) {
-	GoLog("[Amazon] Fetching from AfkarXYZ API...\n")
-
-	downloadURL, fileName, decryptionKey, err := a.fetchAmazonURLWithRetry(amazonURL)
-	if err != nil {
-		return "", "", "", err
-	}
-
-	if decryptionKey != "" {
-		GoLog("[Amazon] AfkarXYZ returned encrypted stream (decryption key available)\n")
-	}
-	GoLog("[Amazon] AfkarXYZ returned: %s\n", fileName)
-	return downloadURL, fileName, decryptionKey, nil
-}
-
-func (a *AmazonDownloader) DownloadFile(downloadURL, outputPath string, outputFD int, itemID string) error {
-	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, "GET", downloadURL, nil)
-	if err != nil {
-		return fmt.Errorf("failed to create request: %w", err)
-	}
-
-	req.Header.Set("User-Agent", getRandomUserAgent())
-
-	resp, err := a.client.Do(req)
-	if err != nil {
-		if isDownloadCancelled(itemID) {
-			return ErrDownloadCancelled
-		}
-		return err
-	}
-	defer resp.Body.Close()
-
-	if resp.StatusCode != 200 {
-		return fmt.Errorf("download failed: HTTP %d", resp.StatusCode)
-	}
-
-	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 buffer: %w", flushErr)
-	}
-	if closeErr != nil {
-		cleanupOutputOnError(outputPath, outputFD)
-		return fmt.Errorf("failed to close file: %w", closeErr)
-	}
-
-	if expectedSize > 0 && written != expectedSize {
-		cleanupOutputOnError(outputPath, outputFD)
-		return fmt.Errorf("incomplete download: expected %d bytes, got %d bytes", expectedSize, written)
-	}
-
-	GoLog("[Amazon] Downloaded: %.2f MB (Complete)\n", float64(written)/(1024*1024))
-	return nil
-}
-
-// AmazonDownloadResult contains download result with quality info
-type AmazonDownloadResult struct {
-	FilePath      string
-	BitDepth      int
-	SampleRate    int
-	Title         string
-	Artist        string
-	Album         string
-	ReleaseDate   string
-	TrackNumber   int
-	DiscNumber    int
-	ISRC          string
-	LyricsLRC     string
-	DecryptionKey string
-}
-
-func downloadFromAmazon(req DownloadRequest) (AmazonDownloadResult, error) {
-	downloader := NewAmazonDownloader()
-
-	isSafOutput := isFDOutput(req.OutputFD) || strings.TrimSpace(req.OutputPath) != ""
-	if !isSafOutput {
-		if existingFile, exists := checkISRCExistsInternal(req.OutputDir, req.ISRC); exists {
-			return AmazonDownloadResult{FilePath: "EXISTS:" + existingFile}, nil
-		}
-	}
-
-	amazonURL := ""
-	if req.ISRC != "" {
-		if cached := GetTrackIDCache().Get(req.ISRC); cached != nil && cached.AmazonURL != "" {
-			amazonURL = cached.AmazonURL
-			GoLog("[Amazon] Cache hit! Using cached Amazon URL for ISRC %s\n", req.ISRC)
-		}
-	}
-
-	songlink := NewSongLinkClient()
-	var availability *TrackAvailability
-	var err error
-
-	if amazonURL == "" {
-		if deezerID, found := strings.CutPrefix(req.SpotifyID, "deezer:"); found {
-			GoLog("[Amazon] Using Deezer ID for SongLink lookup: %s\n", deezerID)
-			availability, err = songlink.CheckAvailabilityFromDeezer(deezerID)
-		} else if req.SpotifyID != "" {
-			availability, err = songlink.CheckTrackAvailability(req.SpotifyID, req.ISRC)
-		} else {
-			return AmazonDownloadResult{}, fmt.Errorf("no valid Spotify or Deezer ID provided for Amazon lookup")
-		}
-
-		if err != nil {
-			return AmazonDownloadResult{}, fmt.Errorf("failed to check Amazon availability via SongLink: %w", err)
-		}
-
-		if !availability.Amazon || availability.AmazonURL == "" {
-			return AmazonDownloadResult{}, fmt.Errorf("track not available on Amazon Music (SongLink returned no Amazon URL)")
-		}
-
-		amazonURL = availability.AmazonURL
-		if req.ISRC != "" {
-			GetTrackIDCache().SetAmazonURL(req.ISRC, amazonURL)
-		}
-	}
-
-	if !isSafOutput && req.OutputDir != "." {
-		if err := os.MkdirAll(req.OutputDir, 0755); err != nil {
-			return AmazonDownloadResult{}, fmt.Errorf("failed to create output directory: %w", err)
-		}
-	}
-
-	// Download using AfkarXYZ API
-	downloadURL, afkarFileName, decryptionKey, err := downloader.downloadFromAfkarXYZ(amazonURL)
-	if err != nil {
-		return AmazonDownloadResult{}, fmt.Errorf("failed to get download URL from AfkarXYZ: %w", err)
-	}
-
-	GoLog("[Amazon] Match found: '%s' by '%s'\n", req.TrackName, req.ArtistName)
-
-	filename := buildFilenameFromTemplate(req.FilenameFormat, map[string]any{
-		"title":  req.TrackName,
-		"artist": req.ArtistName,
-		"album":  req.AlbumName,
-		"track":  req.TrackNumber,
-		"year":   extractYear(req.ReleaseDate),
-		"date":   req.ReleaseDate,
-		"disc":   req.DiscNumber,
-	})
-	var outputPath string
-	if isSafOutput {
-		outputPath = strings.TrimSpace(req.OutputPath)
-		if outputPath == "" && isFDOutput(req.OutputFD) {
-			outputPath = fmt.Sprintf("/proc/self/fd/%d", req.OutputFD)
-		}
-	} else {
-		outputExt := strings.ToLower(filepath.Ext(afkarFileName))
-		if outputExt == "" {
-			outputExt = ".flac"
-		}
-		filename = sanitizeFilename(filename) + outputExt
-		outputPath = filepath.Join(req.OutputDir, filename)
-		if fileInfo, statErr := os.Stat(outputPath); statErr == nil && fileInfo.Size() > 0 {
-			return AmazonDownloadResult{FilePath: "EXISTS:" + outputPath}, nil
-		}
-	}
-
-	// START PARALLEL: Fetch cover and lyrics while downloading audio
-	var parallelResult *ParallelDownloadResult
-	parallelDone := make(chan struct{})
-	go func() {
-		defer close(parallelDone)
-		parallelResult = FetchCoverAndLyricsParallel(
-			req.CoverURL,
-			req.EmbedMaxQualityCover,
-			req.SpotifyID,
-			req.TrackName,
-			req.ArtistName,
-			req.EmbedLyrics,
-			int64(req.DurationMS),
-		)
-	}()
-
-	// Download audio file with item ID for progress tracking
-	if err := downloader.DownloadFile(downloadURL, outputPath, req.OutputFD, req.ItemID); err != nil {
-		if errors.Is(err, ErrDownloadCancelled) {
-			return AmazonDownloadResult{}, ErrDownloadCancelled
-		}
-		return AmazonDownloadResult{}, fmt.Errorf("download failed: %w", err)
-	}
-
-	actualOutputPath := outputPath
-	needsDecryption := strings.TrimSpace(decryptionKey) != ""
-	if needsDecryption {
-		GoLog("[Amazon] Download requires decryption; deferring decrypt to Flutter FFmpeg path\n")
-	}
-
-	// Wait for parallel operations to complete
-	<-parallelDone
-
-	if req.ItemID != "" {
-		SetItemProgress(req.ItemID, 1.0, 0, 0)
-		SetItemFinalizing(req.ItemID)
-	}
-
-	actualTrackNum := req.TrackNumber
-	actualDiscNum := req.DiscNumber
-	actualDate := req.ReleaseDate
-	actualAlbum := req.AlbumName
-	actualTitle := req.TrackName
-	actualArtist := req.ArtistName
-
-	if !needsDecryption {
-		existingMeta, metaErr := ReadMetadata(actualOutputPath)
-		if metaErr == nil && existingMeta != nil {
-			if existingMeta.TrackNumber > 0 && (req.TrackNumber == 0 || req.TrackNumber == 1) {
-				actualTrackNum = existingMeta.TrackNumber
-				GoLog("[Amazon] Using track number from file: %d (request had: %d)\n", actualTrackNum, req.TrackNumber)
-			}
-			if existingMeta.DiscNumber > 0 && (req.DiscNumber == 0 || req.DiscNumber == 1) {
-				actualDiscNum = existingMeta.DiscNumber
-				GoLog("[Amazon] Using disc number from file: %d (request had: %d)\n", actualDiscNum, req.DiscNumber)
-			}
-			if existingMeta.Date != "" && req.ReleaseDate == "" {
-				actualDate = existingMeta.Date
-				GoLog("[Amazon] Using release date from file: %s\n", actualDate)
-			}
-			if existingMeta.Album != "" && req.AlbumName == "" {
-				actualAlbum = existingMeta.Album
-				GoLog("[Amazon] Using album from file: %s\n", actualAlbum)
-			}
-			GoLog("[Amazon] Existing metadata - Title: %s, Artist: %s, Album: %s, Date: %s\n",
-				existingMeta.Title, existingMeta.Artist, existingMeta.Album, existingMeta.Date)
-		}
-	}
-
-	metadata := Metadata{
-		Title:       actualTitle,
-		Artist:      actualArtist,
-		Album:       actualAlbum,
-		AlbumArtist: req.AlbumArtist,
-		Date:        actualDate,
-		TrackNumber: actualTrackNum,
-		TotalTracks: req.TotalTracks,
-		DiscNumber:  actualDiscNum,
-		ISRC:        req.ISRC,
-		Genre:       req.Genre,
-		Label:       req.Label,
-		Copyright:   req.Copyright,
-	}
-
-	var coverData []byte
-	if parallelResult != nil && parallelResult.CoverData != nil && len(parallelResult.CoverData) > 0 {
-		coverData = parallelResult.CoverData
-		GoLog("[Amazon] Using parallel-fetched cover (%d bytes)\n", len(coverData))
-	} else {
-		existingCover, coverErr := ExtractCoverArt(actualOutputPath)
-		if coverErr == nil && len(existingCover) > 0 {
-			coverData = existingCover
-			GoLog("[Amazon] Using existing cover from Amazon file (%d bytes)\n", len(coverData))
-		} else {
-			GoLog("[Amazon] No cover available (parallel fetch failed and no existing cover)\n")
-		}
-	}
-
-	if isSafOutput || needsDecryption {
-		GoLog("[Amazon] SAF output detected - skipping in-backend metadata/lyrics embedding (handled in Flutter)\n")
-	} else {
-		isFlacOutput := strings.HasSuffix(strings.ToLower(actualOutputPath), ".flac")
-		if isFlacOutput {
-			if err := EmbedMetadataWithCoverData(actualOutputPath, metadata, coverData); err != nil {
-				GoLog("[Amazon] Warning: failed to embed metadata: %v\n", err)
-			}
-		} else {
-			GoLog("[Amazon] Non-FLAC output detected (%s), skipping native metadata embedding\n", filepath.Ext(actualOutputPath))
-		}
-
-		if req.EmbedLyrics && parallelResult != nil && parallelResult.LyricsLRC != "" {
-			lyricsMode := req.LyricsMode
-			if lyricsMode == "" {
-				lyricsMode = "embed"
-			}
-
-			if lyricsMode == "external" || lyricsMode == "both" {
-				GoLog("[Amazon] Saving external LRC file...\n")
-				if lrcPath, lrcErr := SaveLRCFile(actualOutputPath, parallelResult.LyricsLRC); lrcErr != nil {
-					GoLog("[Amazon] Warning: failed to save LRC file: %v\n", lrcErr)
-				} else {
-					GoLog("[Amazon] LRC file saved: %s\n", lrcPath)
-				}
-			}
-
-			if (lyricsMode == "embed" || lyricsMode == "both") && isFlacOutput {
-				GoLog("[Amazon] Embedding parallel-fetched lyrics (%d lines)...\n", len(parallelResult.LyricsData.Lines))
-				if embedErr := EmbedLyrics(actualOutputPath, parallelResult.LyricsLRC); embedErr != nil {
-					GoLog("[Amazon] Warning: failed to embed lyrics: %v\n", embedErr)
-				} else {
-					GoLog("[Amazon] Lyrics embedded successfully\n")
-				}
-			} else if (lyricsMode == "embed" || lyricsMode == "both") && !isFlacOutput {
-				GoLog("[Amazon] Skipping embedded lyrics for non-FLAC output\n")
-			}
-		} else if req.EmbedLyrics {
-			GoLog("[Amazon] No lyrics available from parallel fetch\n")
-		}
-	}
-
-	GoLog("[Amazon] Downloaded successfully from Amazon Music\n")
-
-	quality := AudioQuality{}
-	if isSafOutput || needsDecryption {
-		GoLog("[Amazon] SAF output detected - skipping post-write file inspection in backend\n")
-	} else {
-		quality, err = GetAudioQuality(actualOutputPath)
-		if err != nil {
-			GoLog("[Amazon] Warning: couldn't read quality from file: %v\n", err)
-		} else {
-			GoLog("[Amazon] Actual quality: %d-bit/%dHz\n", quality.BitDepth, quality.SampleRate)
-		}
-
-		finalMeta, metaReadErr := ReadMetadata(actualOutputPath)
-		if metaReadErr == nil && finalMeta != nil {
-			GoLog("[Amazon] Final metadata from file - Track: %d, Disc: %d, Date: %s\n",
-				finalMeta.TrackNumber, finalMeta.DiscNumber, finalMeta.Date)
-			actualTrackNum = finalMeta.TrackNumber
-			actualDiscNum = finalMeta.DiscNumber
-			if finalMeta.Date != "" {
-				req.ReleaseDate = finalMeta.Date
-			}
-		}
-	}
-
-	// Add to ISRC index for fast duplicate checking.
-	// When decryption is pending in Flutter, postpone indexing until final file is settled.
-	if !isSafOutput && !needsDecryption {
-		AddToISRCIndex(req.OutputDir, req.ISRC, actualOutputPath)
-	}
-
-	bitDepth := 0
-	sampleRate := 0
-	if err == nil {
-		bitDepth = quality.BitDepth
-		sampleRate = quality.SampleRate
-	}
-
-	lyricsLRC := ""
-	if req.EmbedLyrics && parallelResult != nil && parallelResult.LyricsLRC != "" {
-		lyricsLRC = parallelResult.LyricsLRC
-	}
-
-	return AmazonDownloadResult{
-		FilePath:      outputPath,
-		BitDepth:      bitDepth,
-		SampleRate:    sampleRate,
-		Title:         req.TrackName,
-		Artist:        req.ArtistName,
-		Album:         req.AlbumName,
-		ReleaseDate:   req.ReleaseDate,
-		TrackNumber:   actualTrackNum,
-		DiscNumber:    actualDiscNum,
-		ISRC:          req.ISRC,
-		LyricsLRC:     lyricsLRC,
-		DecryptionKey: decryptionKey,
-	}, nil
-}

go_backend/amazon_asin_test.go

@@ -1,46 +0,0 @@
-package gobackend
-
-import "testing"
-
-func TestExtractAmazonASIN(t *testing.T) {
-	tests := []struct {
-		name string
-		url  string
-		want string
-	}{
-		{
-			name: "prefers trackAsin over albumAsin",
-			url:  "https://music.amazon.com/albums/B0ALBUM123?trackAsin=B0TRACK456&musicTerritory=US",
-			want: "B0TRACK456",
-		},
-		{
-			name: "extract from tracks path",
-			url:  "https://music.amazon.com/tracks/B0CYQHGWZJ?musicTerritory=US",
-			want: "B0CYQHGWZJ",
-		},
-		{
-			name: "extract from plain query asin",
-			url:  "https://example.com/?asin=B0CYQHGWZJ",
-			want: "B0CYQHGWZJ",
-		},
-		{
-			name: "fallback regex",
-			url:  "https://example.com/path/B0CYQHGWZJ",
-			want: "B0CYQHGWZJ",
-		},
-		{
-			name: "invalid url",
-			url:  "https://music.amazon.com/tracks/not-valid",
-			want: "",
-		},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			got := extractAmazonASIN(tt.url)
-			if got != tt.want {
-				t.Fatalf("extractAmazonASIN() = %q, want %q", got, tt.want)
-			}
-		})
-	}
-}

go_backend/audio_metadata.go

@@ -5,13 +5,13 @@ import (
 	"encoding/binary"
 	"fmt"
 	"io"
+	"math"
 	"os"
 	"path/filepath"
 	"strconv"
 	"strings"
 )
 
-// AudioMetadata represents common audio file metadata
 type AudioMetadata struct {
 	Title       string
 	Artist      string
@@ -30,7 +30,6 @@ type AudioMetadata struct {
 	Comment     string
 }
 
-// MP3Quality represents MP3 specific quality info
 type MP3Quality struct {
 	SampleRate int
 	BitDepth   int
@@ -38,7 +37,6 @@ type MP3Quality struct {
 	Bitrate    int
 }
 
-// OggQuality represents Ogg/Opus specific quality info
 type OggQuality struct {
 	SampleRate int
 	BitDepth   int
@@ -46,10 +44,6 @@ type OggQuality struct {
 	Bitrate    int // estimated bitrate in bps
 }
 
-// =============================================================================
-// ID3 Tag Reading (MP3)
-// =============================================================================
-
 func ReadID3Tags(filePath string) (*AudioMetadata, error) {
 	file, err := os.Open(filePath)
 	if err != nil {
@@ -1127,17 +1121,33 @@ func GetOggQuality(filePath string) (*OggQuality, error) {
 			// Opus always uses 48kHz granule position internally
 			totalSamples := granule - int64(preSkip)
 			if totalSamples > 0 {
-				quality.Duration = int(totalSamples / 48000)
+				durationSec := float64(totalSamples) / 48000.0
+				if durationSec > 0 {
+					quality.Duration = int(math.Round(durationSec))
+					quality.Bitrate = int(float64(fileSize*8) / durationSec)
+				}
 			}
 		} else if quality.SampleRate > 0 {
-			quality.Duration = int(granule / int64(quality.SampleRate))
+			durationSec := float64(granule) / float64(quality.SampleRate)
+			if durationSec > 0 {
+				quality.Duration = int(math.Round(durationSec))
+				quality.Bitrate = int(float64(fileSize*8) / durationSec)
+			}
 		}
 	}
 
-	// Calculate average bitrate from file size and actual duration
-	if quality.Duration > 0 {
+	// 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
+	}
+	if quality.Bitrate > 0 && quality.Bitrate < 8000 {
+		quality.Bitrate = 0
+	}
 
 	return quality, nil
 }
@@ -1162,27 +1172,37 @@ func readLastOggGranulePosition(file *os.File, fileSize int64) int64 {
 	}
 	buf = buf[:n]
 
-	// Scan backwards for "OggS" magic
-	lastPageOffset := -1
 	for i := n - 4; i >= 0; i-- {
-		if buf[i] == 'O' && buf[i+1] == 'g' && buf[i+2] == 'g' && buf[i+3] == 'S' {
-			lastPageOffset = i
-			break
+		if buf[i] != 'O' || buf[i+1] != 'g' || buf[i+2] != 'g' || buf[i+3] != 'S' {
+			continue
 		}
+		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 {
+			continue
+		}
+		segmentCount := int(buf[i+26])
+		headerLen := 27 + segmentCount
+		if i+headerLen > n {
+			continue
+		}
+		payloadLen := 0
+		for s := 0; s < segmentCount; s++ {
+			payloadLen += int(buf[i+27+s])
+		}
+		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]))
 	}
-
-	if lastPageOffset < 0 || lastPageOffset+14 > n {
-		return 0
-	}
-
-	// Granule position is at bytes 6-13 of the Ogg page header (little-endian int64)
-	return int64(binary.LittleEndian.Uint64(buf[lastPageOffset+6 : lastPageOffset+14]))
+	return 0
 }
 
-// =============================================================================
-// ID3v1 Genre List
-// =============================================================================
-
 var id3v1Genres = []string{
 	"Blues", "Classic Rock", "Country", "Dance", "Disco", "Funk", "Grunge",
 	"Hip-Hop", "Jazz", "Metal", "New Age", "Oldies", "Other", "Pop", "R&B",
@@ -1213,10 +1233,6 @@ var id3v1Genres = []string{
 	"Thrash Metal", "Anime", "J-Pop", "Synthpop",
 }
 
-// =============================================================================
-// Cover Art Extraction
-// =============================================================================
-
 func extractMP3CoverArt(filePath string) ([]byte, string, error) {
 	file, err := os.Open(filePath)
 	if err != nil {
@@ -1550,7 +1566,14 @@ func base64StdDecode(dst, src []byte) (int, error) {
 }
 
 func extractAnyCoverArt(filePath string) ([]byte, string, error) {
+	return extractAnyCoverArtWithHint(filePath, "")
+}
+
+func extractAnyCoverArtWithHint(filePath, displayNameHint string) ([]byte, string, error) {
 	ext := strings.ToLower(filepath.Ext(filePath))
+	if ext == "" {
+		ext = strings.ToLower(filepath.Ext(displayNameHint))
+	}
 
 	switch ext {
 	case ".flac":
@@ -1579,6 +1602,10 @@ func extractAnyCoverArt(filePath string) ([]byte, string, error) {
 }
 
 func SaveCoverToCache(filePath, cacheDir string) (string, error) {
+	return SaveCoverToCacheWithHint(filePath, "", cacheDir)
+}
+
+func SaveCoverToCacheWithHint(filePath, displayNameHint, cacheDir string) (string, error) {
 	cacheKey := filePath
 	if stat, err := os.Stat(filePath); err == nil {
 		cacheKey = fmt.Sprintf("%s|%d|%d", filePath, stat.Size(), stat.ModTime().UnixNano())
@@ -1595,7 +1622,7 @@ func SaveCoverToCache(filePath, cacheDir string) (string, error) {
 		return pngPath, nil
 	}
 
-	imageData, mimeType, err := extractAnyCoverArt(filePath)
+	imageData, mimeType, err := extractAnyCoverArtWithHint(filePath, displayNameHint)
 	if err != nil {
 		return "", err
 	}

go_backend/cover.go

@@ -104,7 +104,6 @@ func upgradeDeezerCover(coverURL string) string {
 		return coverURL
 	}
 
-	// Replace any size pattern with 1800x1800
 	upgraded := deezerSizeRegex.ReplaceAllString(coverURL, "/1800x1800-000000-80-0-0.jpg")
 	if upgraded != coverURL {
 		GoLog("[Cover] Deezer: upgraded to 1800x1800")

go_backend/cue_parser.go

@@ -0,0 +1,590 @@
+package gobackend
+
+import (
+	"bufio"
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strconv"
+	"strings"
+)
+
+// CueSheet represents a parsed .cue file
+type CueSheet struct {
+	// Album-level metadata
+	Performer string     `json:"performer"`
+	Title     string     `json:"title"`
+	FileName  string     `json:"file_name"`
+	FileType  string     `json:"file_type"` // WAVE, FLAC, MP3, AIFF, etc.
+	Genre     string     `json:"genre,omitempty"`
+	Date      string     `json:"date,omitempty"`
+	Comment   string     `json:"comment,omitempty"`
+	Composer  string     `json:"composer,omitempty"`
+	Tracks    []CueTrack `json:"tracks"`
+}
+
+// CueTrack represents a single track in a cue sheet
+type CueTrack struct {
+	Number    int    `json:"number"`
+	Title     string `json:"title"`
+	Performer string `json:"performer"`
+	ISRC      string `json:"isrc,omitempty"`
+	Composer  string `json:"composer,omitempty"`
+	// Index positions in seconds (fractional)
+	StartTime float64 `json:"start_time"` // INDEX 01 in seconds
+	PreGap    float64 `json:"pre_gap"`    // INDEX 00 in seconds (or -1 if not present)
+}
+
+// CueSplitInfo represents the information needed to split a CUE+audio file
+type CueSplitInfo struct {
+	CuePath   string          `json:"cue_path"`
+	AudioPath string          `json:"audio_path"`
+	Album     string          `json:"album"`
+	Artist    string          `json:"artist"`
+	Genre     string          `json:"genre,omitempty"`
+	Date      string          `json:"date,omitempty"`
+	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"`
+	Artist   string  `json:"artist"`
+	ISRC     string  `json:"isrc,omitempty"`
+	Composer string  `json:"composer,omitempty"`
+	StartSec float64 `json:"start_sec"`
+	EndSec   float64 `json:"end_sec"` // -1 means until end of file
+}
+
+var (
+	reRemCommand = regexp.MustCompile(`^REM\s+(\S+)\s+(.+)$`)
+	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 {
+		return nil, fmt.Errorf("failed to open cue file: %w", err)
+	}
+	defer f.Close()
+
+	sheet := &CueSheet{}
+	var currentTrack *CueTrack
+
+	scanner := bufio.NewScanner(f)
+	for scanner.Scan() {
+		line := strings.TrimSpace(scanner.Text())
+		if line == "" {
+			continue
+		}
+
+		// Handle BOM at start of file
+		if strings.HasPrefix(line, "\xef\xbb\xbf") {
+			line = strings.TrimPrefix(line, "\xef\xbb\xbf")
+			line = strings.TrimSpace(line)
+		}
+
+		upper := strings.ToUpper(line)
+
+		// REM commands (album-level metadata)
+		if strings.HasPrefix(upper, "REM ") {
+			matches := reRemCommand.FindStringSubmatch(line)
+			if len(matches) == 3 {
+				key := strings.ToUpper(matches[1])
+				value := unquoteCue(matches[2])
+				switch key {
+				case "GENRE":
+					sheet.Genre = value
+				case "DATE":
+					sheet.Date = value
+				case "COMMENT":
+					sheet.Comment = value
+				case "COMPOSER":
+					if currentTrack != nil {
+						currentTrack.Composer = value
+					} else {
+						sheet.Composer = value
+					}
+				}
+			}
+			continue
+		}
+
+		if strings.HasPrefix(upper, "PERFORMER ") {
+			value := unquoteCue(line[len("PERFORMER "):])
+			if currentTrack != nil {
+				currentTrack.Performer = value
+			} else {
+				sheet.Performer = value
+			}
+			continue
+		}
+
+		if strings.HasPrefix(upper, "TITLE ") {
+			value := unquoteCue(line[len("TITLE "):])
+			if currentTrack != nil {
+				currentTrack.Title = value
+			} else {
+				sheet.Title = value
+			}
+			continue
+		}
+
+		if strings.HasPrefix(upper, "FILE ") {
+			rest := line[len("FILE "):]
+			// Extract filename and type
+			// Format: FILE "filename.flac" WAVE
+			// or: FILE filename.flac WAVE
+			fname, ftype := parseCueFileLine(rest)
+			sheet.FileName = fname
+			sheet.FileType = ftype
+			continue
+		}
+
+		if strings.HasPrefix(upper, "TRACK ") {
+			// Save previous track
+			if currentTrack != nil {
+				sheet.Tracks = append(sheet.Tracks, *currentTrack)
+			}
+
+			parts := strings.Fields(line)
+			trackNum := 0
+			if len(parts) >= 2 {
+				trackNum, _ = strconv.Atoi(parts[1])
+			}
+
+			currentTrack = &CueTrack{
+				Number: trackNum,
+				PreGap: -1,
+			}
+			continue
+		}
+
+		if strings.HasPrefix(upper, "INDEX ") && currentTrack != nil {
+			parts := strings.Fields(line)
+			if len(parts) >= 3 {
+				indexNum, _ := strconv.Atoi(parts[1])
+				timeSec := parseCueTimestamp(parts[2])
+				switch indexNum {
+				case 0:
+					currentTrack.PreGap = timeSec
+				case 1:
+					currentTrack.StartTime = timeSec
+				}
+			}
+			continue
+		}
+
+		if strings.HasPrefix(upper, "ISRC ") && currentTrack != nil {
+			currentTrack.ISRC = strings.TrimSpace(line[len("ISRC "):])
+			continue
+		}
+
+		// SONGWRITER (used as composer sometimes)
+		if strings.HasPrefix(upper, "SONGWRITER ") {
+			value := unquoteCue(line[len("SONGWRITER "):])
+			if currentTrack != nil {
+				currentTrack.Composer = value
+			} else {
+				sheet.Composer = value
+			}
+			continue
+		}
+	}
+
+	// Don't forget the last track
+	if currentTrack != nil {
+		sheet.Tracks = append(sheet.Tracks, *currentTrack)
+	}
+
+	if err := scanner.Err(); err != nil {
+		return nil, fmt.Errorf("error reading cue file: %w", err)
+	}
+
+	if len(sheet.Tracks) == 0 {
+		return nil, fmt.Errorf("no tracks found in cue file")
+	}
+
+	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 {
+		return 0
+	}
+
+	minutes, _ := strconv.Atoi(parts[0])
+	seconds, _ := strconv.Atoi(parts[1])
+	frames, _ := strconv.Atoi(parts[2])
+
+	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"
+	}
+	hours := int(seconds) / 3600
+	mins := (int(seconds) % 3600) / 60
+	secs := seconds - float64(hours*3600) - float64(mins*60)
+	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 {
+		return matches[1]
+	}
+	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]
+			remaining := strings.TrimSpace(rest[endQuote+2:])
+			ftype = remaining
+		} else {
+			filename = rest
+		}
+	} else {
+		// Unquoted filename - last word is the type
+		parts := strings.Fields(rest)
+		if len(parts) >= 2 {
+			ftype = parts[len(parts)-1]
+			filename = strings.Join(parts[:len(parts)-1], " ")
+		} else if len(parts) == 1 {
+			filename = parts[0]
+		}
+	}
+
+	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 {
+		candidate = filepath.Join(cueDir, baseName+ext)
+		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)
+		if _, err := os.Stat(candidate); err == nil {
+			return candidate
+		}
+	}
+
+	// 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{
+			".flac": true, ".wav": true, ".ape": true, ".mp3": true,
+			".ogg": true, ".wv": true, ".m4a": true, ".aiff": true,
+		}
+		var audioFiles []string
+		for _, entry := range entries {
+			if entry.IsDir() {
+				continue
+			}
+			ext := strings.ToLower(filepath.Ext(entry.Name()))
+			if audioExts[ext] {
+				audioFiles = append(audioFiles, filepath.Join(cueDir, entry.Name()))
+			}
+		}
+		if len(audioFiles) == 1 {
+			return audioFiles[0]
+		}
+	}
+
+	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)
+	if audioPath == "" {
+		return nil, fmt.Errorf("audio file not found for cue sheet: %s (referenced: %s)", cuePath, sheet.FileName)
+	}
+
+	info := &CueSplitInfo{
+		CuePath:   cuePath,
+		AudioPath: audioPath,
+		Album:     sheet.Title,
+		Artist:    sheet.Performer,
+		Genre:     sheet.Genre,
+		Date:      sheet.Date,
+	}
+
+	for i, track := range sheet.Tracks {
+		performer := track.Performer
+		if performer == "" {
+			performer = sheet.Performer
+		}
+
+		composer := track.Composer
+		if composer == "" {
+			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 {
+				endSec = nextTrack.StartTime
+			}
+		}
+
+		info.Tracks = append(info.Tracks, CueSplitTrack{
+			Number:   track.Number,
+			Title:    track.Title,
+			Artist:   performer,
+			ISRC:     track.ISRC,
+			Composer: composer,
+			StartSec: track.StartTime,
+			EndSec:   endSec,
+		})
+	}
+
+	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 {
+		return "", fmt.Errorf("failed to parse cue file: %w", err)
+	}
+
+	info, err := BuildCueSplitInfo(cuePath, sheet, audioDir)
+	if err != nil {
+		return "", err
+	}
+
+	jsonBytes, err := json.Marshal(info)
+	if err != nil {
+		return "", fmt.Errorf("failed to marshal cue split info: %w", err)
+	}
+
+	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 {
+		return nil, err
+	}
+	audioPath, err := resolveCueAudioPathForLibrary(cuePath, sheet, "")
+	if err != nil {
+		return nil, err
+	}
+	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) {
+	sheet, err := ParseCueFile(cuePath)
+	if err != nil {
+		return nil, err
+	}
+	audioPath, err := resolveCueAudioPathForLibrary(cuePath, sheet, audioDir)
+	if err != nil {
+		return nil, err
+	}
+	return scanCueSheetForLibrary(cuePath, sheet, audioPath, virtualPathPrefix, fileModTime, scanTime)
+}
+
+func resolveCueAudioPathForLibrary(cuePath string, sheet *CueSheet, audioDir string) (string, error) {
+	if sheet == nil {
+		return "", fmt.Errorf("cue sheet is nil for %s", cuePath)
+	}
+	resolveBase := cuePath
+	if audioDir != "" {
+		resolveBase = filepath.Join(audioDir, filepath.Base(cuePath))
+	}
+	audioPath := ResolveCueAudioPath(resolveBase, sheet.FileName)
+	if audioPath == "" {
+		return "", fmt.Errorf("audio file not found for cue: %s (referenced: %s)", cuePath, sheet.FileName)
+	}
+	return audioPath, nil
+}
+
+func scanCueSheetForLibrary(cuePath string, sheet *CueSheet, audioPath, virtualPathPrefix string, fileModTime int64, scanTime string) ([]LibraryScanResult, error) {
+	if sheet == nil {
+		return nil, fmt.Errorf("cue sheet is nil for %s", cuePath)
+	}
+
+	// Try to get quality info from the audio file
+	var bitDepth, sampleRate int
+	var totalDurationSec float64
+	audioExt := strings.ToLower(filepath.Ext(audioPath))
+	switch audioExt {
+	case ".flac":
+		quality, qErr := GetAudioQuality(audioPath)
+		if qErr == nil {
+			bitDepth = quality.BitDepth
+			sampleRate = quality.SampleRate
+			if quality.SampleRate > 0 && quality.TotalSamples > 0 {
+				totalDurationSec = float64(quality.TotalSamples) / float64(quality.SampleRate)
+			}
+		}
+	case ".mp3":
+		quality, qErr := GetMP3Quality(audioPath)
+		if qErr == nil {
+			sampleRate = quality.SampleRate
+			totalDurationSec = float64(quality.Duration)
+		}
+	}
+
+	// Extract cover from audio file for all tracks
+	var coverPath string
+	libraryCoverCacheMu.RLock()
+	coverCacheDir := libraryCoverCacheDir
+	libraryCoverCacheMu.RUnlock()
+	if coverCacheDir != "" {
+		cp, err := SaveCoverToCache(audioPath, coverCacheDir)
+		if err == nil && cp != "" {
+			coverPath = cp
+		}
+	}
+
+	// Determine the base path for virtual paths and IDs
+	pathBase := cuePath
+	if virtualPathPrefix != "" {
+		pathBase = virtualPathPrefix
+	}
+
+	// Determine fileModTime
+	modTime := fileModTime
+	if modTime <= 0 {
+		if info, err := os.Stat(cuePath); err == nil {
+			modTime = info.ModTime().UnixMilli()
+		}
+	}
+
+	var results []LibraryScanResult
+	for i, track := range sheet.Tracks {
+		performer := track.Performer
+		if performer == "" {
+			performer = sheet.Performer
+		}
+		if performer == "" {
+			performer = "Unknown Artist"
+		}
+
+		title := track.Title
+		if title == "" {
+			title = fmt.Sprintf("Track %02d", track.Number)
+		}
+
+		album := sheet.Title
+		if album == "" {
+			album = "Unknown Album"
+		}
+
+		// Calculate duration for this track
+		var duration int
+		if i+1 < len(sheet.Tracks) {
+			nextStart := sheet.Tracks[i+1].StartTime
+			if sheet.Tracks[i+1].PreGap >= 0 {
+				nextStart = sheet.Tracks[i+1].PreGap
+			}
+			duration = int(nextStart - track.StartTime)
+		} else if totalDurationSec > 0 {
+			duration = int(totalDurationSec - track.StartTime)
+		}
+
+		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{
+			ID:          id,
+			TrackName:   title,
+			ArtistName:  performer,
+			AlbumName:   album,
+			AlbumArtist: sheet.Performer,
+			FilePath:    virtualFilePath,
+			CoverPath:   coverPath,
+			ScannedAt:   scanTime,
+			ISRC:        track.ISRC,
+			TrackNumber: track.Number,
+			DiscNumber:  1,
+			Duration:    duration,
+			ReleaseDate: sheet.Date,
+			BitDepth:    bitDepth,
+			SampleRate:  sampleRate,
+			Genre:       sheet.Genre,
+			Format:      "cue+" + strings.TrimPrefix(audioExt, "."),
+		}
+
+		result.FileModTime = modTime
+
+		results = append(results, result)
+	}
+
+	return results, nil
+}

go_backend/deezer.go

@@ -13,12 +13,13 @@ import (
 )
 
 const (
-	deezerBaseURL     = "https://api.deezer.com/2.0"
-	deezerSearchURL   = deezerBaseURL + "/search"
-	deezerTrackURL    = deezerBaseURL + "/track/%s"
-	deezerAlbumURL    = deezerBaseURL + "/album/%s"
-	deezerArtistURL   = deezerBaseURL + "/artist/%s"
-	deezerPlaylistURL = deezerBaseURL + "/playlist/%s"
+	deezerBaseURL          = "https://api.deezer.com/2.0"
+	deezerSearchURL        = deezerBaseURL + "/search"
+	deezerTrackURL         = deezerBaseURL + "/track/%s"
+	deezerAlbumURL         = deezerBaseURL + "/album/%s"
+	deezerArtistURL        = deezerBaseURL + "/artist/%s"
+	deezerArtistRelatedURL = deezerBaseURL + "/artist/%s/related"
+	deezerPlaylistURL      = deezerBaseURL + "/playlist/%s"
 
 	deezerCacheTTL = 10 * time.Minute
 
@@ -234,6 +235,8 @@ func (c *DeezerClient) convertTrack(track deezerTrack) TrackMetadata {
 		DiscNumber:  track.DiskNumber,
 		ExternalURL: track.Link,
 		ISRC:        track.ISRC,
+		AlbumID:     fmt.Sprintf("deezer:%d", track.Album.ID),
+		ArtistID:    fmt.Sprintf("deezer:%d", track.Artist.ID),
 	}
 }
 
@@ -253,6 +256,7 @@ type deezerAlbumFull struct {
 	NbTracks    int    `json:"nb_tracks"`
 	RecordType  string `json:"record_type"`
 	Label       string `json:"label"`
+	Copyright   string `json:"copyright"`
 	Genres      struct {
 		Data []deezerGenre `json:"data"`
 	} `json:"genres"`
@@ -756,6 +760,66 @@ func (c *DeezerClient) GetArtist(ctx context.Context, artistID string) (*ArtistR
 	return result, nil
 }
 
+func (c *DeezerClient) GetRelatedArtists(ctx context.Context, artistID string, limit int) ([]SearchArtistResult, error) {
+	normalizedArtistID := strings.TrimSpace(strings.TrimPrefix(artistID, "deezer:"))
+	if normalizedArtistID == "" {
+		return nil, fmt.Errorf("invalid Deezer artist ID")
+	}
+
+	effectiveLimit := limit
+	if effectiveLimit <= 0 {
+		effectiveLimit = 12
+	}
+
+	relatedURL := fmt.Sprintf("%s?limit=%d", fmt.Sprintf(deezerArtistRelatedURL, normalizedArtistID), effectiveLimit)
+	var relatedResp struct {
+		Data []struct {
+			ID            int64  `json:"id"`
+			Name          string `json:"name"`
+			Picture       string `json:"picture"`
+			PictureMedium string `json:"picture_medium"`
+			PictureBig    string `json:"picture_big"`
+			PictureXL     string `json:"picture_xl"`
+			NbFan         int    `json:"nb_fan"`
+		} `json:"data"`
+		Error *struct {
+			Type    string `json:"type"`
+			Message string `json:"message"`
+			Code    int    `json:"code"`
+		} `json:"error,omitempty"`
+	}
+
+	if err := c.getJSON(ctx, relatedURL, &relatedResp); err != nil {
+		return nil, err
+	}
+	if relatedResp.Error != nil {
+		return nil, fmt.Errorf("deezer related artists error: %s", relatedResp.Error.Message)
+	}
+
+	result := make([]SearchArtistResult, 0, len(relatedResp.Data))
+	for _, artist := range relatedResp.Data {
+		imageURL := artist.PictureXL
+		if imageURL == "" {
+			imageURL = artist.PictureBig
+		}
+		if imageURL == "" {
+			imageURL = artist.PictureMedium
+		}
+		if imageURL == "" {
+			imageURL = artist.Picture
+		}
+
+		result = append(result, SearchArtistResult{
+			ID:         fmt.Sprintf("deezer:%d", artist.ID),
+			Name:       artist.Name,
+			Images:     imageURL,
+			Followers:  artist.NbFan,
+			Popularity: 0,
+		})
+	}
+	return result, nil
+}
+
 func (c *DeezerClient) GetPlaylist(ctx context.Context, playlistID string) (*PlaylistResponsePayload, error) {
 	playlistURL := fmt.Sprintf(deezerPlaylistURL, playlistID)
 
@@ -1021,8 +1085,9 @@ func (c *DeezerClient) getBestAlbumImage(album deezerAlbumFull) string {
 }
 
 type AlbumExtendedMetadata struct {
-	Genre string
-	Label string
+	Genre     string
+	Label     string
+	Copyright string
 }
 
 func (c *DeezerClient) GetAlbumExtendedMetadata(ctx context.Context, albumID string) (*AlbumExtendedMetadata, error) {
@@ -1053,8 +1118,9 @@ func (c *DeezerClient) GetAlbumExtendedMetadata(ctx context.Context, albumID str
 	}
 
 	result := &AlbumExtendedMetadata{
-		Genre: strings.Join(genres, ", "),
-		Label: album.Label,
+		Genre:     strings.Join(genres, ", "),
+		Label:     album.Label,
+		Copyright: album.Copyright,
 	}
 
 	c.cacheMu.Lock()
@@ -1066,7 +1132,7 @@ func (c *DeezerClient) GetAlbumExtendedMetadata(ctx context.Context, albumID str
 	c.maybeCleanupCachesLocked(now)
 	c.cacheMu.Unlock()
 
-	GoLog("[Deezer] Album metadata fetched - Genre: %s, Label: %s\n", result.Genre, result.Label)
+	GoLog("[Deezer] Album metadata fetched - Genre: %s, Label: %s, Copyright: %s\n", result.Genre, result.Label, result.Copyright)
 
 	return result, nil
 }

go_backend/deezer_download.go

@@ -0,0 +1,606 @@
+package gobackend
+
+import (
+	"bufio"
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"path/filepath"
+	"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"`
+}
+
+type DeezerDownloadResult struct {
+	FilePath    string
+	BitDepth    int
+	SampleRate  int
+	Title       string
+	Artist      string
+	Album       string
+	ReleaseDate string
+	TrackNumber int
+	DiscNumber  int
+	ISRC        string
+	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
+	}
+	for _, r := range value {
+		switch {
+		case r >= 'A' && r <= 'Z':
+		case r >= 'a' && r <= 'z':
+		case r >= '0' && r <= '9':
+		default:
+			return false
+		}
+	}
+	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 == "" {
+		if prefixed, found := strings.CutPrefix(strings.TrimSpace(req.SpotifyID), "deezer:"); found {
+			deezerID = strings.TrimSpace(prefixed)
+		}
+	}
+	if deezerID != "" {
+		trackURL := fmt.Sprintf("https://www.deezer.com/track/%s", deezerID)
+		if err := verifyDeezerTrack(req, deezerID); err != nil {
+			GoLog("[Deezer] Direct ID %s verification failed: %v\n", deezerID, err)
+			// Don't reject direct IDs from request payload — they're presumably correct.
+		}
+		return trackURL, nil
+	}
+
+	// Try SongLink
+	spotifyID := strings.TrimSpace(req.SpotifyID)
+	if spotifyID != "" && isLikelySpotifyTrackID(spotifyID) {
+		songlink := NewSongLinkClient()
+		availability, err := songlink.CheckTrackAvailability(spotifyID, "")
+		if err == nil && availability.Deezer && availability.DeezerURL != "" {
+			resolvedID := extractDeezerIDFromURL(availability.DeezerURL)
+			if resolvedID != "" {
+				if verifyErr := verifyDeezerTrack(req, resolvedID); verifyErr != nil {
+					GoLog("[Deezer] SongLink ID %s rejected: %v\n", resolvedID, verifyErr)
+					// Fall through to ISRC search instead of using wrong track.
+				} else {
+					return availability.DeezerURL, nil
+				}
+			} else {
+				return availability.DeezerURL, nil
+			}
+		}
+	}
+
+	// Try ISRC
+	isrc := strings.TrimSpace(req.ISRC)
+	if isrc != "" {
+		ctx, cancel := context.WithTimeout(context.Background(), SongLinkTimeout)
+		defer cancel()
+		track, err := GetDeezerClient().SearchByISRC(ctx, isrc)
+		if err == nil && track != nil {
+			resolvedID := songLinkExtractDeezerTrackID(track)
+			if resolvedID != "" {
+				if verifyErr := verifyDeezerTrack(req, resolvedID); verifyErr != nil {
+					GoLog("[Deezer] ISRC-resolved ID %s rejected: %v\n", resolvedID, verifyErr)
+					return "", fmt.Errorf("deezer track resolved via ISRC does not match: %w", verifyErr)
+				}
+				return fmt.Sprintf("https://www.deezer.com/track/%s", resolvedID), nil
+			}
+		}
+	}
+
+	return "", fmt.Errorf("could not resolve Deezer track URL")
+}
+
+func verifyDeezerTrack(req DownloadRequest, deezerID string) error {
+	ctx, cancel := context.WithTimeout(context.Background(), SongLinkTimeout)
+	defer cancel()
+	trackResp, err := GetDeezerClient().GetTrack(ctx, deezerID)
+	if err != nil {
+		return nil // Can't verify — don't block the download.
+	}
+	resolved := resolvedTrackInfo{
+		Title:      trackResp.Track.Name,
+		ArtistName: trackResp.Track.Artists,
+		Duration:   trackResp.Track.DurationMS / 1000,
+	}
+	if !trackMatchesRequest(req, resolved, "Deezer") {
+		return fmt.Errorf("expected '%s - %s', got '%s - %s'",
+			req.ArtistName, req.TrackName, resolved.ArtistName, resolved.Title)
+	}
+	GoLog("[Deezer] Track %s verified: '%s - %s' ✓\n", deezerID, resolved.ArtistName, resolved.Title)
+	return nil
+}
+
+type deezerMusicDLRequest struct {
+	Platform string `json:"platform"`
+	URL      string `json:"url"`
+}
+
+func (c *DeezerClient) GetMusicDLDownloadURL(deezerTrackURL string) (string, error) {
+	payload := deezerMusicDLRequest{
+		Platform: "deezer",
+		URL:      deezerTrackURL,
+	}
+	jsonData, err := json.Marshal(payload)
+	if err != nil {
+		return "", fmt.Errorf("failed to encode MusicDL request: %w", err)
+	}
+
+	req, err := http.NewRequest(http.MethodPost, deezerMusicDLURL, bytes.NewReader(jsonData))
+	if err != nil {
+		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)
+	if err != nil {
+		return "", fmt.Errorf("MusicDL request failed: %w", err)
+	}
+	defer resp.Body.Close()
+
+	body, err := io.ReadAll(io.LimitReader(resp.Body, 64*1024))
+	if err != nil {
+		return "", fmt.Errorf("failed to read MusicDL response: %w", err)
+	}
+
+	if resp.StatusCode != http.StatusOK {
+		return "", fmt.Errorf("MusicDL returned HTTP %d: %s", resp.StatusCode, strings.TrimSpace(string(body)))
+	}
+
+	var raw map[string]any
+	if err := json.Unmarshal(body, &raw); err != nil {
+		return "", fmt.Errorf("invalid MusicDL JSON: %w", err)
+	}
+
+	if errMsg, ok := raw["error"].(string); ok && strings.TrimSpace(errMsg) != "" {
+		return "", fmt.Errorf("MusicDL error: %s", errMsg)
+	}
+
+	// Try various response fields for download URL
+	for _, key := range []string{"download_url", "url", "link"} {
+		if urlVal, ok := raw[key].(string); ok && strings.TrimSpace(urlVal) != "" {
+			return strings.TrimSpace(urlVal), nil
+		}
+	}
+	if data, ok := raw["data"].(map[string]any); ok {
+		for _, key := range []string{"download_url", "url", "link"} {
+			if urlVal, ok := data[key].(string); ok && strings.TrimSpace(urlVal) != "" {
+				return strings.TrimSpace(urlVal), nil
+			}
+		}
+	}
+
+	return "", fmt.Errorf("no download URL found in MusicDL response")
+}
+
+func (c *DeezerClient) DownloadFromMusicDL(deezerTrackURL, outputPath string, outputFD int, itemID string) error {
+	GoLog("[Deezer] Resolving download URL via MusicDL for: %s\n", deezerTrackURL)
+
+	downloadURL, err := c.GetMusicDLDownloadURL(deezerTrackURL)
+	if err != nil {
+		return err
+	}
+	GoLog("[Deezer] MusicDL returned download URL, starting download...\n")
+
+	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, "GET", downloadURL, nil)
+	if err != nil {
+		return fmt.Errorf("failed to create download request: %w", err)
+	}
+	req.Header.Set("User-Agent", getRandomUserAgent())
+
+	resp, err := GetDownloadClient().Do(req)
+	if err != nil {
+		if isDownloadCancelled(itemID) {
+			return ErrDownloadCancelled
+		}
+		return fmt.Errorf("download request failed: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		return fmt.Errorf("download returned HTTP %d", resp.StatusCode)
+	}
+
+	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 MusicDL: %.2f MB\n", float64(written)/(1024*1024))
+	return nil
+}
+
+func downloadFromDeezer(req DownloadRequest) (DeezerDownloadResult, error) {
+	deezerClient := GetDeezerClient()
+	isSafOutput := isFDOutput(req.OutputFD) || strings.TrimSpace(req.OutputPath) != ""
+
+	if !isSafOutput {
+		if existingFile, exists := checkISRCExistsInternal(req.OutputDir, req.ISRC); exists {
+			return DeezerDownloadResult{FilePath: "EXISTS:" + existingFile}, nil
+		}
+	}
+
+	filename := buildFilenameFromTemplate(req.FilenameFormat, map[string]interface{}{
+		"title":  req.TrackName,
+		"artist": req.ArtistName,
+		"album":  req.AlbumName,
+		"track":  req.TrackNumber,
+		"year":   extractYear(req.ReleaseDate),
+		"date":   req.ReleaseDate,
+		"disc":   req.DiscNumber,
+	})
+
+	var outputPath string
+	if isSafOutput {
+		outputPath = strings.TrimSpace(req.OutputPath)
+		if outputPath == "" && isFDOutput(req.OutputFD) {
+			outputPath = fmt.Sprintf("/proc/self/fd/%d", req.OutputFD)
+		}
+	} else {
+		filename = sanitizeFilename(filename) + ".flac"
+		outputPath = filepath.Join(req.OutputDir, filename)
+		if fileInfo, statErr := os.Stat(outputPath); statErr == nil && fileInfo.Size() > 0 {
+			return DeezerDownloadResult{FilePath: "EXISTS:" + outputPath}, nil
+		}
+	}
+
+	var parallelResult *ParallelDownloadResult
+	parallelDone := make(chan struct{})
+	go func() {
+		defer close(parallelDone)
+		coverURL := req.CoverURL
+		embedLyrics := req.EmbedLyrics
+		if !req.EmbedMetadata {
+			coverURL = ""
+			embedLyrics = false
+		}
+		parallelResult = FetchCoverAndLyricsParallel(
+			coverURL,
+			req.EmbedMaxQualityCover,
+			req.SpotifyID,
+			req.TrackName,
+			req.ArtistName,
+			embedLyrics,
+			int64(req.DurationMS),
+		)
+	}()
+
+	// 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 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)
+		}
+	}
+
+	<-parallelDone
+
+	if req.ItemID != "" {
+		SetItemProgress(req.ItemID, 1.0, 0, 0)
+		SetItemFinalizing(req.ItemID)
+	}
+
+	metadata := Metadata{
+		Title:       req.TrackName,
+		Artist:      req.ArtistName,
+		Album:       req.AlbumName,
+		AlbumArtist: req.AlbumArtist,
+		Date:        req.ReleaseDate,
+		TrackNumber: req.TrackNumber,
+		TotalTracks: req.TotalTracks,
+		DiscNumber:  req.DiscNumber,
+		ISRC:        req.ISRC,
+		Genre:       req.Genre,
+		Label:       req.Label,
+		Copyright:   req.Copyright,
+	}
+
+	var coverData []byte
+	if parallelResult != nil && parallelResult.CoverData != nil {
+		coverData = parallelResult.CoverData
+	}
+
+	if isSafOutput || !req.EmbedMetadata {
+		if !req.EmbedMetadata {
+			GoLog("[Deezer] Metadata embedding disabled by settings, skipping in-backend metadata/lyrics embedding\n")
+		} else {
+			GoLog("[Deezer] SAF output detected - skipping in-backend metadata/lyrics embedding (handled in Flutter)\n")
+		}
+	} else {
+		if err := EmbedMetadataWithCoverData(outputPath, metadata, coverData); err != nil {
+			GoLog("[Deezer] Warning: failed to embed metadata: %v\n", err)
+		}
+
+		if req.EmbedLyrics && parallelResult != nil && parallelResult.LyricsLRC != "" {
+			lyricsMode := req.LyricsMode
+			if lyricsMode == "" {
+				lyricsMode = "embed"
+			}
+
+			if lyricsMode == "external" || lyricsMode == "both" {
+				if lrcPath, lrcErr := SaveLRCFile(outputPath, parallelResult.LyricsLRC); lrcErr != nil {
+					GoLog("[Deezer] Warning: failed to save LRC file: %v\n", lrcErr)
+				} else {
+					GoLog("[Deezer] LRC file saved: %s\n", lrcPath)
+				}
+			}
+
+			if lyricsMode == "embed" || lyricsMode == "both" {
+				if embedErr := EmbedLyrics(outputPath, parallelResult.LyricsLRC); embedErr != nil {
+					GoLog("[Deezer] Warning: failed to embed lyrics: %v\n", embedErr)
+				}
+			}
+		}
+	}
+
+	if !isSafOutput {
+		AddToISRCIndex(req.OutputDir, req.ISRC, outputPath)
+	}
+
+	bitDepth, sampleRate := 0, 0
+	if quality, qErr := GetAudioQuality(outputPath); qErr == nil {
+		bitDepth = quality.BitDepth
+		sampleRate = quality.SampleRate
+	}
+
+	lyricsLRC := ""
+	if req.EmbedMetadata && req.EmbedLyrics && parallelResult != nil && parallelResult.LyricsLRC != "" {
+		lyricsLRC = parallelResult.LyricsLRC
+	}
+
+	return DeezerDownloadResult{
+		FilePath:    outputPath,
+		BitDepth:    bitDepth,
+		SampleRate:  sampleRate,
+		Title:       req.TrackName,
+		Artist:      req.ArtistName,
+		Album:       req.AlbumName,
+		ReleaseDate: req.ReleaseDate,
+		TrackNumber: req.TrackNumber,
+		DiscNumber:  req.DiscNumber,
+		ISRC:        req.ISRC,
+		LyricsLRC:   lyricsLRC,
+	}, nil
+}

go_backend/duplicate.go

@@ -34,7 +34,6 @@ func GetISRCIndex(outputDir string) *ISRCIndex {
 		return idx
 	}
 
-	// Slow path: need to build index
 	// Use per-directory mutex to prevent multiple goroutines from building simultaneously
 	buildLock, _ := isrcBuildingMu.LoadOrStore(outputDir, &sync.Mutex{})
 	mu := buildLock.(*sync.Mutex)

go_backend/exports_deezer_metadata_test.go

@@ -0,0 +1,59 @@
+package gobackend
+
+import "testing"
+
+func TestBuildDeezerExtendedMetadataResultHandlesNil(t *testing.T) {
+	result := buildDeezerExtendedMetadataResult(nil)
+
+	if result["genre"] != "" {
+		t.Fatalf("expected empty genre, got %q", result["genre"])
+	}
+	if result["label"] != "" {
+		t.Fatalf("expected empty label, got %q", result["label"])
+	}
+	if result["copyright"] != "" {
+		t.Fatalf("expected empty copyright, got %q", result["copyright"])
+	}
+}
+
+func TestBuildDeezerExtendedMetadataResultIncludesCopyright(t *testing.T) {
+	result := buildDeezerExtendedMetadataResult(&AlbumExtendedMetadata{
+		Genre:     "Rock",
+		Label:     "EMI",
+		Copyright: "(C) Queen",
+	})
+
+	if result["genre"] != "Rock" {
+		t.Fatalf("unexpected genre: %q", result["genre"])
+	}
+	if result["label"] != "EMI" {
+		t.Fatalf("unexpected label: %q", result["label"])
+	}
+	if result["copyright"] != "(C) Queen" {
+		t.Fatalf("unexpected copyright: %q", result["copyright"])
+	}
+}
+
+func TestBuildDeezerISRCSearchResultAddsCompatibilityIDs(t *testing.T) {
+	result := buildDeezerISRCSearchResult(&TrackMetadata{
+		SpotifyID:   "deezer:3135556",
+		Name:        "Love Of My Life",
+		Artists:     "Queen",
+		AlbumName:   "A Night at the Opera",
+		ISRC:        "GBUM71029604",
+		ReleaseDate: "1975-11-21",
+	})
+
+	if result["spotify_id"] != "deezer:3135556" {
+		t.Fatalf("unexpected spotify_id: %v", result["spotify_id"])
+	}
+	if result["id"] != "3135556" {
+		t.Fatalf("unexpected id: %v", result["id"])
+	}
+	if result["track_id"] != "3135556" {
+		t.Fatalf("unexpected track_id: %v", result["track_id"])
+	}
+	if result["success"] != true {
+		t.Fatalf("expected success=true, got %v", result["success"])
+	}
+}

go_backend/exports_test.go

@@ -0,0 +1,86 @@
+package gobackend
+
+import "testing"
+
+func TestBuildDownloadSuccessResponsePrefersRequestedAlbumMetadata(t *testing.T) {
+	req := DownloadRequest{
+		TrackName:   "Bonus Track",
+		ArtistName:  "Artist",
+		AlbumName:   "Album (Deluxe)",
+		AlbumArtist: "Artist",
+		ReleaseDate: "2024-01-01",
+		TrackNumber: 14,
+		DiscNumber:  1,
+		ISRC:        "REQ123",
+		CoverURL:    "https://example.com/cover.jpg",
+		Genre:       "Pop",
+		Label:       "Label",
+		Copyright:   "Copyright",
+	}
+
+	result := DownloadResult{
+		Title:       "Bonus Track",
+		Artist:      "Artist",
+		Album:       "Album",
+		ReleaseDate: "2023-12-01",
+		TrackNumber: 2,
+		DiscNumber:  9,
+		ISRC:        "RES456",
+	}
+
+	resp := buildDownloadSuccessResponse(
+		req,
+		result,
+		"tidal",
+		"ok",
+		"/tmp/test.flac",
+		false,
+	)
+
+	if resp.Album != req.AlbumName {
+		t.Fatalf("album = %q, want %q", resp.Album, req.AlbumName)
+	}
+	if resp.ReleaseDate != req.ReleaseDate {
+		t.Fatalf("release date = %q, want %q", resp.ReleaseDate, req.ReleaseDate)
+	}
+	if resp.TrackNumber != req.TrackNumber {
+		t.Fatalf("track number = %d, want %d", resp.TrackNumber, req.TrackNumber)
+	}
+	if resp.DiscNumber != req.DiscNumber {
+		t.Fatalf("disc number = %d, want %d", resp.DiscNumber, req.DiscNumber)
+	}
+	if resp.Artist != result.Artist {
+		t.Fatalf("artist = %q, want provider artist %q", resp.Artist, result.Artist)
+	}
+	if resp.ISRC != result.ISRC {
+		t.Fatalf("isrc = %q, want provider isrc %q", resp.ISRC, result.ISRC)
+	}
+}
+
+func TestPreferredReleaseMetadataPrefersRequestValues(t *testing.T) {
+	album, releaseDate, trackNumber, discNumber := preferredReleaseMetadata(
+		DownloadRequest{
+			AlbumName:   "Album (Deluxe Edition)",
+			ReleaseDate: "2024-01-01",
+			TrackNumber: 13,
+			DiscNumber:  2,
+		},
+		"Album",
+		"2023-01-01",
+		3,
+		1,
+	)
+
+	if album != "Album (Deluxe Edition)" {
+		t.Fatalf("album = %q", album)
+	}
+	if releaseDate != "2024-01-01" {
+		t.Fatalf("release date = %q", releaseDate)
+	}
+	if trackNumber != 13 {
+		t.Fatalf("track number = %d", trackNumber)
+	}
+	if discNumber != 2 {
+		t.Fatalf("disc number = %d", discNumber)
+	}
+}

go_backend/extension_manager.go

@@ -48,11 +48,12 @@ type LoadedExtension struct {
 	Manifest  *ExtensionManifest `json:"manifest"`
 	VM        *goja.Runtime      `json:"-"`
 	VMMu      sync.Mutex         `json:"-"`
-	Enabled   bool               `json:"enabled"`
-	Error     string             `json:"error,omitempty"`
-	DataDir   string             `json:"data_dir"`
-	SourceDir string             `json:"source_dir"`
-	IconPath  string             `json:"icon_path"`
+	runtime   *ExtensionRuntime
+	Enabled   bool   `json:"enabled"`
+	Error     string `json:"error,omitempty"`
+	DataDir   string `json:"data_dir"`
+	SourceDir string `json:"source_dir"`
+	IconPath  string `json:"icon_path"`
 }
 
 type ExtensionManager struct {
@@ -150,7 +151,6 @@ func (m *ExtensionManager) LoadExtensionFromFile(filePath string) (*LoadedExtens
 	if exists {
 		versionCompare := compareVersions(manifest.Version, existingVersion)
 		if versionCompare > 0 {
-			// This is an upgrade - call UpgradeExtension
 			return m.UpgradeExtension(filePath)
 		} else if versionCompare == 0 {
 			return nil, fmt.Errorf("Extension '%s' v%s is already installed", existingDisplayName, existingVersion)
@@ -243,6 +243,7 @@ func (m *ExtensionManager) initializeVM(ext *LoadedExtension) error {
 	}
 
 	runtime := NewExtensionRuntime(ext)
+	ext.runtime = runtime
 	runtime.RegisterAPIs(vm)
 	runtime.RegisterGoBackendAPIs(vm)
 
@@ -295,6 +296,13 @@ func (m *ExtensionManager) UnloadExtension(extensionID string) error {
 			GoLog("[Extension] Cleanup called for %s\n", extensionID)
 		}
 	}
+	if ext.runtime != nil {
+		if err := ext.runtime.flushStorageNow(); err != nil {
+			GoLog("[Extension] Failed to flush storage for %s: %v\n", extensionID, err)
+		}
+		ext.runtime.closeStorageFlusher()
+		ext.runtime = nil
+	}
 
 	delete(m.extensions, extensionID)
 	GoLog("[Extension] Unloaded extension: %s\n", extensionID)
@@ -392,7 +400,6 @@ func (m *ExtensionManager) loadExtensionFromDirectory(dirPath string) (*LoadedEx
 		return nil, fmt.Errorf("failed to read manifest.json: %w", err)
 	}
 
-	// Parse and validate manifest
 	manifest, err := ParseManifest(manifestData)
 	if err != nil {
 		return nil, fmt.Errorf("Invalid extension manifest: %w", err)
@@ -421,7 +428,6 @@ func (m *ExtensionManager) loadExtensionFromDirectory(dirPath string) (*LoadedEx
 		SourceDir: dirPath,
 	}
 
-	// Restore enabled state from settings store
 	store := GetExtensionSettingsStore()
 	if enabledVal, err := store.Get(manifest.Name, "_enabled"); err == nil {
 		if enabled, ok := enabledVal.(bool); ok {
@@ -458,17 +464,11 @@ func (m *ExtensionManager) RemoveExtension(extensionID string) error {
 		}
 	}
 
-	// Optionally remove data directory (keep for now to preserve settings)
-	// if ext.DataDir != "" {
-	//     os.RemoveAll(ext.DataDir)
-	// }
-
 	return nil
 }
 
 // Only allows upgrades (new version > current version), not downgrades
 func (m *ExtensionManager) UpgradeExtension(filePath string) (*LoadedExtension, error) {
-	// Validate file extension
 	if !strings.HasSuffix(strings.ToLower(filePath), ".spotiflac-ext") {
 		return nil, fmt.Errorf("Invalid file format. Please select a .spotiflac-ext file")
 	}
@@ -520,7 +520,6 @@ func (m *ExtensionManager) UpgradeExtension(filePath string) (*LoadedExtension,
 		return nil, fmt.Errorf("Extension '%s' is not installed. Use install instead of upgrade.", newManifest.DisplayName)
 	}
 
-	// Compare versions - only allow upgrade, not downgrade
 	versionCompare := compareVersions(newManifest.Version, existing.Manifest.Version)
 	if versionCompare < 0 {
 		return nil, fmt.Errorf("Cannot downgrade extension. Current version: %s, New version: %s", existing.Manifest.Version, newManifest.Version)
@@ -531,12 +530,10 @@ func (m *ExtensionManager) UpgradeExtension(filePath string) (*LoadedExtension,
 
 	GoLog("[Extension] Upgrading %s from v%s to v%s\n", newManifest.DisplayName, existing.Manifest.Version, newManifest.Version)
 
-	// Save data directory path and enabled state (we want to preserve them)
 	extDataDir := existing.DataDir
 	extDir := existing.SourceDir
 	wasEnabled := existing.Enabled
 
-	m.CleanupExtension(existing.ID)
 	m.UnloadExtension(existing.ID)
 
 	if extDir != "" {
@@ -593,7 +590,6 @@ func (m *ExtensionManager) UpgradeExtension(filePath string) (*LoadedExtension,
 		SourceDir: extDir,
 	}
 
-	// Initialize Goja VM
 	if err := m.initializeVM(ext); err != nil {
 		ext.Error = err.Error()
 		ext.Enabled = false
@@ -618,7 +614,6 @@ type ExtensionUpgradeInfo struct {
 }
 
 func (m *ExtensionManager) checkExtensionUpgradeInternal(filePath string) (*ExtensionUpgradeInfo, error) {
-	// Validate file extension
 	if !strings.HasSuffix(strings.ToLower(filePath), ".spotiflac-ext") {
 		return nil, fmt.Errorf("Invalid file format. Please select a .spotiflac-ext file")
 	}
@@ -667,7 +662,6 @@ func (m *ExtensionManager) checkExtensionUpgradeInternal(filePath string) (*Exte
 	}
 
 	if !exists {
-		// Not installed - this is a new install, not upgrade
 		info.CurrentVersion = ""
 		info.CanUpgrade = false
 	} else {
@@ -731,7 +725,6 @@ func (m *ExtensionManager) GetInstalledExtensionsJSON() (string, error) {
 			permissions = append(permissions, "storage:enabled")
 		}
 
-		// Determine status
 		status := "loaded"
 		if ext.Error != "" {
 			status = "error"
@@ -909,7 +902,6 @@ func (m *ExtensionManager) UnloadAllExtensions() {
 	m.mu.Unlock()
 
 	for _, id := range extensionIDs {
-		m.CleanupExtension(id)
 		m.UnloadExtension(id)
 	}
 
@@ -933,7 +925,6 @@ func (m *ExtensionManager) InvokeAction(extensionID string, actionName string) (
 		return nil, fmt.Errorf("extension is disabled")
 	}
 
-	// Call the action function on the extension object
 	script := fmt.Sprintf(`
 		(function() {
 			if (typeof extension !== 'undefined' && typeof extension.%s === 'function') {

go_backend/extension_manifest.go

@@ -1,4 +1,3 @@
-// Package gobackend provides extension manifest parsing and validation
 package gobackend
 
 import (

go_backend/extension_providers.go

@@ -1,4 +1,3 @@
-// Package gobackend provides extension provider interfaces
 package gobackend
 
 import (
@@ -6,6 +5,7 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"os"
 	"path/filepath"
 	"sort"
 	"strings"
@@ -15,9 +15,6 @@ import (
 	"github.com/dop251/goja"
 )
 
-// ==================== Metadata Types ====================
-
-// ExtTrackMetadata represents track metadata from an extension
 type ExtTrackMetadata struct {
 	ID          string `json:"id"`
 	Name        string `json:"name"`
@@ -73,6 +70,7 @@ type ExtArtistMetadata struct {
 	HeaderImage string             `json:"header_image,omitempty"`
 	Listeners   int                `json:"listeners,omitempty"`
 	Albums      []ExtAlbumMetadata `json:"albums,omitempty"`
+	Releases    []ExtAlbumMetadata `json:"releases,omitempty"`
 	TopTracks   []ExtTrackMetadata `json:"top_tracks,omitempty"`
 	ProviderID  string             `json:"provider_id"`
 }
@@ -103,15 +101,16 @@ type ExtDownloadResult struct {
 	ErrorMessage string `json:"error_message,omitempty"`
 	ErrorType    string `json:"error_type,omitempty"`
 
-	Title       string `json:"title,omitempty"`
-	Artist      string `json:"artist,omitempty"`
-	Album       string `json:"album,omitempty"`
-	AlbumArtist string `json:"album_artist,omitempty"`
-	TrackNumber int    `json:"track_number,omitempty"`
-	DiscNumber  int    `json:"disc_number,omitempty"`
-	ReleaseDate string `json:"release_date,omitempty"`
-	CoverURL    string `json:"cover_url,omitempty"`
-	ISRC        string `json:"isrc,omitempty"`
+	Title         string `json:"title,omitempty"`
+	Artist        string `json:"artist,omitempty"`
+	Album         string `json:"album,omitempty"`
+	AlbumArtist   string `json:"album_artist,omitempty"`
+	TrackNumber   int    `json:"track_number,omitempty"`
+	DiscNumber    int    `json:"disc_number,omitempty"`
+	ReleaseDate   string `json:"release_date,omitempty"`
+	CoverURL      string `json:"cover_url,omitempty"`
+	ISRC          string `json:"isrc,omitempty"`
+	DecryptionKey string `json:"decryption_key,omitempty"`
 }
 
 type ExtensionProviderWrapper struct {
@@ -329,6 +328,12 @@ func (p *ExtensionProviderWrapper) GetArtist(artistID string) (*ExtArtistMetadat
 	}
 
 	artist.ProviderID = p.extension.ID
+	for i := range artist.Releases {
+		artist.Releases[i].ProviderID = p.extension.ID
+		for j := range artist.Releases[i].Tracks {
+			artist.Releases[i].Tracks[j].ProviderID = p.extension.ID
+		}
+	}
 	return &artist, nil
 }
 
@@ -392,7 +397,7 @@ func (p *ExtensionProviderWrapper) EnrichTrack(track *ExtTrackMetadata) (*ExtTra
 	return &enrichedTrack, nil
 }
 
-func (p *ExtensionProviderWrapper) CheckAvailability(isrc, trackName, artistName string) (*ExtAvailabilityResult, error) {
+func (p *ExtensionProviderWrapper) CheckAvailability(isrc, trackName, artistName, spotifyID, deezerID string) (*ExtAvailabilityResult, error) {
 	if !p.extension.Manifest.IsDownloadProvider() {
 		return nil, fmt.Errorf("extension '%s' is not a download provider", p.extension.ID)
 	}
@@ -407,11 +412,11 @@ func (p *ExtensionProviderWrapper) CheckAvailability(isrc, trackName, artistName
 	script := fmt.Sprintf(`
 		(function() {
 			if (typeof extension !== 'undefined' && typeof extension.checkAvailability === 'function') {
-				return extension.checkAvailability(%q, %q, %q);
+				return extension.checkAvailability(%q, %q, %q, {spotify_id: %q, deezer_id: %q});
 			}
 			return null;
 		})()
-	`, isrc, trackName, artistName)
+	`, isrc, trackName, artistName, spotifyID, deezerID)
 
 	result, err := RunWithTimeoutAndRecover(p.vm, script, DefaultJSTimeout)
 	if err != nil {
@@ -486,7 +491,7 @@ func (p *ExtensionProviderWrapper) GetDownloadURL(trackID, quality string) (*Ext
 	return &urlResult, nil
 }
 
-const ExtDownloadTimeout = 5 * time.Minute
+const ExtDownloadTimeout = DownloadTimeout
 
 func (p *ExtensionProviderWrapper) Download(trackID, quality, outputPath string, onProgress func(percent int)) (*ExtDownloadResult, error) {
 	if !p.extension.Manifest.IsDownloadProvider() {
@@ -602,8 +607,30 @@ func (m *ExtensionManager) SearchTracksWithExtensions(query string, limit int) (
 		return nil, nil
 	}
 
-	var allTracks []ExtTrackMetadata
+	providerByID := make(map[string]*ExtensionProviderWrapper, len(providers))
+	orderedProviders := make([]*ExtensionProviderWrapper, 0, len(providers))
 	for _, provider := range providers {
+		providerByID[provider.extension.ID] = provider
+	}
+	for _, providerID := range GetMetadataProviderPriority() {
+		if provider := providerByID[providerID]; provider != nil {
+			orderedProviders = append(orderedProviders, provider)
+			delete(providerByID, providerID)
+		}
+	}
+	if len(providerByID) > 0 {
+		remainingIDs := make([]string, 0, len(providerByID))
+		for providerID := range providerByID {
+			remainingIDs = append(remainingIDs, providerID)
+		}
+		sort.Strings(remainingIDs)
+		for _, providerID := range remainingIDs {
+			orderedProviders = append(orderedProviders, providerByID[providerID])
+		}
+	}
+
+	var allTracks []ExtTrackMetadata
+	for _, provider := range orderedProviders {
 		result, err := provider.SearchTracks(query, limit)
 		if err != nil {
 			GoLog("[Extension] Search error from %s: %v\n", provider.extension.ID, err)
@@ -623,6 +650,8 @@ var providerPriorityMu sync.RWMutex
 var metadataProviderPriority []string
 var metadataProviderPriorityMu sync.RWMutex
 
+var searchBuiltInMetadataTracksFunc = searchBuiltInMetadataTracks
+
 func SetProviderPriority(providerIDs []string) {
 	providerPriorityMu.Lock()
 	defer providerPriorityMu.Unlock()
@@ -635,7 +664,7 @@ func GetProviderPriority() []string {
 	defer providerPriorityMu.RUnlock()
 
 	if len(providerPriority) == 0 {
-		return []string{"tidal", "qobuz", "amazon"}
+		return []string{"tidal", "qobuz", "deezer"}
 	}
 
 	result := make([]string, len(providerPriority))
@@ -646,8 +675,30 @@ func GetProviderPriority() []string {
 func SetMetadataProviderPriority(providerIDs []string) {
 	metadataProviderPriorityMu.Lock()
 	defer metadataProviderPriorityMu.Unlock()
-	metadataProviderPriority = providerIDs
-	GoLog("[Extension] Metadata provider priority set: %v\n", providerIDs)
+
+	sanitized := make([]string, 0, len(providerIDs)+3)
+	seen := map[string]struct{}{}
+	for _, providerID := range providerIDs {
+		providerID = strings.TrimSpace(providerID)
+		if providerID == "" || providerID == "spotify" {
+			continue
+		}
+		if _, exists := seen[providerID]; exists {
+			continue
+		}
+		seen[providerID] = struct{}{}
+		sanitized = append(sanitized, providerID)
+	}
+	for _, providerID := range []string{"deezer", "qobuz", "tidal"} {
+		if _, exists := seen[providerID]; exists {
+			continue
+		}
+		seen[providerID] = struct{}{}
+		sanitized = append(sanitized, providerID)
+	}
+
+	metadataProviderPriority = sanitized
+	GoLog("[Extension] Metadata provider priority set: %v\n", sanitized)
 }
 
 func GetMetadataProviderPriority() []string {
@@ -655,7 +706,7 @@ func GetMetadataProviderPriority() []string {
 	defer metadataProviderPriorityMu.RUnlock()
 
 	if len(metadataProviderPriority) == 0 {
-		return []string{"deezer", "spotify"}
+		return []string{"deezer", "qobuz", "tidal"}
 	}
 
 	result := make([]string, len(metadataProviderPriority))
@@ -665,18 +716,189 @@ func GetMetadataProviderPriority() []string {
 
 func isBuiltInProvider(providerID string) bool {
 	switch providerID {
-	case "tidal", "qobuz", "amazon", "deezer":
+	case "tidal", "qobuz", "deezer":
 		return true
 	default:
 		return false
 	}
 }
 
+func normalizeBuiltInMetadataTrack(track TrackMetadata, providerID string) ExtTrackMetadata {
+	deezerID := ""
+	tidalID := ""
+	qobuzID := ""
+	prefixedID := strings.TrimSpace(track.SpotifyID)
+
+	switch providerID {
+	case "deezer":
+		deezerID = strings.TrimPrefix(prefixedID, "deezer:")
+	case "tidal":
+		tidalID = strings.TrimPrefix(prefixedID, "tidal:")
+	case "qobuz":
+		qobuzID = strings.TrimPrefix(prefixedID, "qobuz:")
+	}
+
+	return ExtTrackMetadata{
+		ID:          prefixedID,
+		Name:        track.Name,
+		Artists:     track.Artists,
+		AlbumName:   track.AlbumName,
+		AlbumArtist: track.AlbumArtist,
+		DurationMS:  track.DurationMS,
+		CoverURL:    track.Images,
+		Images:      track.Images,
+		ReleaseDate: track.ReleaseDate,
+		TrackNumber: track.TrackNumber,
+		DiscNumber:  track.DiscNumber,
+		ISRC:        track.ISRC,
+		ProviderID:  providerID,
+		SpotifyID:   prefixedID,
+		DeezerID:    deezerID,
+		TidalID:     tidalID,
+		QobuzID:     qobuzID,
+		AlbumType:   track.AlbumType,
+	}
+}
+
+func metadataTrackDedupKey(track ExtTrackMetadata) string {
+	if isrc := strings.TrimSpace(track.ISRC); isrc != "" {
+		return "isrc:" + strings.ToUpper(isrc)
+	}
+	if spotifyID := strings.TrimSpace(track.SpotifyID); spotifyID != "" {
+		return "spotify:" + spotifyID
+	}
+	if providerID := strings.TrimSpace(track.ProviderID); providerID != "" && strings.TrimSpace(track.ID) != "" {
+		return providerID + ":" + strings.TrimSpace(track.ID)
+	}
+	return strings.TrimSpace(track.Name) + "|" + strings.TrimSpace(track.Artists)
+}
+
+func searchBuiltInMetadataTracks(providerID, query string, limit int) ([]ExtTrackMetadata, error) {
+	switch providerID {
+	case "deezer":
+		ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
+		defer cancel()
+
+		results, err := GetDeezerClient().SearchAll(ctx, query, limit, 0, "track")
+		if err != nil {
+			return nil, err
+		}
+
+		tracks := make([]ExtTrackMetadata, 0, len(results.Tracks))
+		for _, track := range results.Tracks {
+			tracks = append(tracks, normalizeBuiltInMetadataTrack(track, "deezer"))
+		}
+		return tracks, nil
+	case "qobuz":
+		return NewQobuzDownloader().SearchTracks(query, limit)
+	case "tidal":
+		return NewTidalDownloader().SearchTracks(query, limit)
+	default:
+		return nil, fmt.Errorf("unsupported built-in metadata provider: %s", providerID)
+	}
+}
+
+func (m *ExtensionManager) SearchTracksWithMetadataProviders(query string, limit int, includeExtensions bool) ([]ExtTrackMetadata, error) {
+	priority := GetMetadataProviderPriority()
+	if limit <= 0 {
+		limit = 20
+	}
+
+	extensionProviders := make(map[string]*ExtensionProviderWrapper)
+	if includeExtensions {
+		for _, provider := range m.GetMetadataProviders() {
+			extensionProviders[provider.extension.ID] = provider
+		}
+	}
+
+	orderedProviderIDs := make([]string, 0, len(priority)+len(extensionProviders))
+	seenProviderIDs := make(map[string]struct{}, len(priority)+len(extensionProviders))
+	for _, providerID := range priority {
+		providerID = strings.TrimSpace(providerID)
+		if providerID == "" {
+			continue
+		}
+		orderedProviderIDs = append(orderedProviderIDs, providerID)
+		seenProviderIDs[providerID] = struct{}{}
+	}
+	if includeExtensions {
+		remainingIDs := make([]string, 0, len(extensionProviders))
+		for providerID := range extensionProviders {
+			if _, exists := seenProviderIDs[providerID]; exists {
+				continue
+			}
+			remainingIDs = append(remainingIDs, providerID)
+		}
+		sort.Strings(remainingIDs)
+		orderedProviderIDs = append(orderedProviderIDs, remainingIDs...)
+	}
+
+	tracks := make([]ExtTrackMetadata, 0, limit)
+	seenTracks := make(map[string]struct{})
+	for _, providerID := range orderedProviderIDs {
+		var (
+			providerTracks []ExtTrackMetadata
+			err            error
+		)
+
+		if isBuiltInProvider(providerID) {
+			providerTracks, err = searchBuiltInMetadataTracksFunc(providerID, query, limit)
+		} else {
+			if !includeExtensions {
+				continue
+			}
+			provider := extensionProviders[providerID]
+			if provider == nil {
+				continue
+			}
+			var result *ExtSearchResult
+			result, err = provider.SearchTracks(query, limit)
+			if result != nil {
+				providerTracks = result.Tracks
+			}
+		}
+
+		if err != nil {
+			GoLog("[MetadataSearch] Search error from %s: %v\n", providerID, err)
+			continue
+		}
+
+		for _, track := range providerTracks {
+			key := metadataTrackDedupKey(track)
+			if key == "" {
+				continue
+			}
+			if _, exists := seenTracks[key]; exists {
+				continue
+			}
+			seenTracks[key] = struct{}{}
+			tracks = append(tracks, track)
+			if len(tracks) >= limit {
+				return tracks, nil
+			}
+		}
+	}
+
+	return tracks, nil
+}
+
 func DownloadWithExtensionFallback(req DownloadRequest) (*DownloadResponse, error) {
 	priority := GetProviderPriority()
 	extManager := GetExtensionManager()
+	strictMode := !req.UseFallback
+	selectedProvider := strings.TrimSpace(req.Service)
 
-	if req.Service != "" && isBuiltInProvider(req.Service) {
+	if strictMode {
+		if selectedProvider == "" {
+			selectedProvider = strings.TrimSpace(req.Source)
+		}
+		if selectedProvider != "" {
+			priority = []string{selectedProvider}
+			GoLog("[DownloadWithExtensionFallback] Strict mode enabled, provider locked to: %s\n", selectedProvider)
+		}
+	}
+
+	if !strictMode && req.Service != "" && isBuiltInProvider(strings.ToLower(req.Service)) {
 		GoLog("[DownloadWithExtensionFallback] User selected service: %s, prioritizing it first\n", req.Service)
 		newPriority := []string{req.Service}
 		for _, p := range priority {
@@ -686,12 +908,33 @@ func DownloadWithExtensionFallback(req DownloadRequest) (*DownloadResponse, erro
 		}
 		priority = newPriority
 		GoLog("[DownloadWithExtensionFallback] New priority order: %v\n", priority)
+	} else if !strictMode && req.Service != "" && !isBuiltInProvider(strings.ToLower(req.Service)) {
+		found := false
+		for _, p := range priority {
+			if strings.EqualFold(p, req.Service) {
+				found = true
+				break
+			}
+		}
+		newPriority := []string{req.Service}
+		for _, p := range priority {
+			if !strings.EqualFold(p, req.Service) {
+				newPriority = append(newPriority, p)
+			}
+		}
+		priority = newPriority
+		if !found {
+			GoLog("[DownloadWithExtensionFallback] Extension service '%s' added to priority front\n", req.Service)
+		} else {
+			GoLog("[DownloadWithExtensionFallback] Extension service '%s' moved to priority front\n", req.Service)
+		}
+		GoLog("[DownloadWithExtensionFallback] New priority order: %v\n", priority)
 	}
 
 	var lastErr error
 	var skipBuiltIn bool
 
-	if req.Source != "" && !isBuiltInProvider(req.Source) {
+	if req.Source != "" && !isBuiltInProvider(strings.ToLower(req.Source)) {
 		ext, err := extManager.GetExtension(req.Source)
 		if err == nil && ext.Enabled && ext.Error == "" && ext.Manifest.IsMetadataProvider() {
 			GoLog("[DownloadWithExtensionFallback] Enriching track from extension '%s'...\n", req.Source)
@@ -734,6 +977,24 @@ func DownloadWithExtensionFallback(req DownloadRequest) (*DownloadResponse, erro
 				if enrichedTrack.Artists != "" {
 					req.ArtistName = enrichedTrack.Artists
 				}
+				if enrichedTrack.AlbumName != "" && req.AlbumName == "" {
+					GoLog("[DownloadWithExtensionFallback] AlbumName from enrichment: %s\n", enrichedTrack.AlbumName)
+					req.AlbumName = enrichedTrack.AlbumName
+				}
+				if enrichedTrack.AlbumArtist != "" && req.AlbumArtist == "" {
+					req.AlbumArtist = enrichedTrack.AlbumArtist
+				}
+				if enrichedTrack.DurationMS > 0 && req.DurationMS == 0 {
+					GoLog("[DownloadWithExtensionFallback] DurationMS from enrichment: %d\n", enrichedTrack.DurationMS)
+					req.DurationMS = enrichedTrack.DurationMS
+				}
+				if enrichedTrack.CoverURL != "" && req.CoverURL == "" {
+					req.CoverURL = enrichedTrack.CoverURL
+				}
+				if enrichedTrack.ID != "" && req.SpotifyID == "" {
+					GoLog("[DownloadWithExtensionFallback] Track ID from enrichment: %s\n", enrichedTrack.ID)
+					req.SpotifyID = enrichedTrack.ID
+				}
 				if enrichedTrack.Label != "" && req.Label == "" {
 					GoLog("[DownloadWithExtensionFallback] Label from enrichment: %s\n", enrichedTrack.Label)
 					req.Label = enrichedTrack.Label
@@ -754,7 +1015,80 @@ func DownloadWithExtensionFallback(req DownloadRequest) (*DownloadResponse, erro
 		}
 	}
 
-	if req.Source != "" && !isBuiltInProvider(req.Source) {
+	// 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 == "") {
+
+		searchQuery := req.TrackName + " " + req.ArtistName
+		GoLog("[DownloadWithExtensionFallback] Metadata incomplete, searching providers for: %s\n", searchQuery)
+
+		tracks, searchErr := extManager.SearchTracksWithMetadataProviders(searchQuery, 5, true)
+		if searchErr == nil && len(tracks) > 0 {
+			track := tracks[0]
+			GoLog("[DownloadWithExtensionFallback] Metadata match (%s): %s - %s (album: %s, date: %s, isrc: %s)\n",
+				track.ProviderID, track.Name, track.Artists, track.AlbumName, track.ReleaseDate, track.ISRC)
+
+			if track.AlbumName != "" && req.AlbumName == "" {
+				req.AlbumName = track.AlbumName
+			}
+			if track.AlbumArtist != "" && req.AlbumArtist == "" {
+				req.AlbumArtist = track.AlbumArtist
+			}
+			if track.ReleaseDate != "" && req.ReleaseDate == "" {
+				req.ReleaseDate = track.ReleaseDate
+			}
+			if track.ISRC != "" && req.ISRC == "" {
+				req.ISRC = track.ISRC
+			}
+			if track.TrackNumber > 0 && req.TrackNumber == 0 {
+				req.TrackNumber = track.TrackNumber
+			}
+			if track.DiscNumber > 0 && req.DiscNumber == 0 {
+				req.DiscNumber = track.DiscNumber
+			}
+			if track.CoverURL != "" && req.CoverURL == "" {
+				req.CoverURL = track.CoverURL
+			}
+			if track.Genre != "" && req.Genre == "" {
+				req.Genre = track.Genre
+			}
+			if track.Label != "" && req.Label == "" {
+				req.Label = track.Label
+			}
+			if track.Copyright != "" && req.Copyright == "" {
+				req.Copyright = track.Copyright
+			}
+		} else if searchErr != nil {
+			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)
+			extMeta, err := GetDeezerClient().GetExtendedMetadataByISRC(ctx, req.ISRC)
+			cancel()
+			if err == nil && extMeta != nil {
+				if req.Genre == "" && extMeta.Genre != "" {
+					req.Genre = extMeta.Genre
+				}
+				if req.Label == "" && extMeta.Label != "" {
+					req.Label = extMeta.Label
+				}
+				if req.Copyright == "" && extMeta.Copyright != "" {
+					req.Copyright = extMeta.Copyright
+				}
+				GoLog("[DownloadWithExtensionFallback] Extended metadata from Deezer: genre=%s, label=%s, copyright=%s\n", req.Genre, req.Label, req.Copyright)
+			}
+		}
+	}
+
+	if req.Source != "" &&
+		!isBuiltInProvider(strings.ToLower(req.Source)) &&
+		(!strictMode || selectedProvider == "" || strings.EqualFold(selectedProvider, req.Source)) {
 		GoLog("[DownloadWithExtensionFallback] Track source is extension '%s', trying it first\n", req.Source)
 
 		ext, err := extManager.GetExtension(req.Source)
@@ -767,13 +1101,30 @@ func DownloadWithExtensionFallback(req DownloadRequest) (*DownloadResponse, erro
 
 			GoLog("[DownloadWithExtensionFallback] Downloading from source extension with trackID: %s (skipBuiltInFallback: %v)\n", trackID, skipBuiltIn)
 
-			outputPath := buildOutputPath(req)
+			outputPath := buildOutputPathForExtension(req, ext)
+			if req.ItemID != "" {
+				StartItemProgress(req.ItemID)
+			}
 
 			result, err := provider.Download(trackID, req.Quality, outputPath, func(percent int) {
 				if req.ItemID != "" {
-					SetItemProgress(req.ItemID, float64(percent), 0, 0)
+					normalized := float64(percent) / 100.0
+					if normalized < 0 {
+						normalized = 0
+					}
+					if normalized > 1 {
+						normalized = 1
+					}
+					SetItemProgress(req.ItemID, normalized, 0, 0)
 				}
 			})
+			if req.ItemID != "" {
+				if err == nil && result != nil && result.Success {
+					CompleteItemProgress(req.ItemID)
+				} else {
+					RemoveItemProgress(req.ItemID)
+				}
+			}
 
 			if err == nil && result.Success {
 				resp := &DownloadResponse{
@@ -786,9 +1137,10 @@ func DownloadWithExtensionFallback(req DownloadRequest) (*DownloadResponse, erro
 					Genre:            req.Genre,
 					Label:            req.Label,
 					Copyright:        req.Copyright,
+					DecryptionKey:    result.DecryptionKey,
 				}
 
-				if req.Genre != "" || req.Label != "" {
+				if req.EmbedMetadata && (req.Genre != "" || req.Label != "") {
 					if err := EmbedGenreLabel(result.FilePath, req.Genre, req.Label); err != nil {
 						GoLog("[DownloadWithExtensionFallback] Warning: failed to embed genre/label: %v\n", err)
 					} else {
@@ -827,6 +1179,30 @@ 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
+				}
+				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
 			}
 
@@ -860,19 +1236,25 @@ func DownloadWithExtensionFallback(req DownloadRequest) (*DownloadResponse, erro
 	}
 
 	for _, providerID := range priority {
+		providerID = strings.TrimSpace(providerID)
+		if providerID == "" {
+			continue
+		}
+		providerIDNormalized := strings.ToLower(providerID)
 		if providerID == req.Source {
 			continue
 		}
 
-		if skipBuiltIn && isBuiltInProvider(providerID) {
+		if skipBuiltIn && isBuiltInProvider(providerIDNormalized) {
 			GoLog("[DownloadWithExtensionFallback] Skipping built-in provider %s (skipBuiltInFallback)\n", providerID)
 			continue
 		}
 
 		GoLog("[DownloadWithExtensionFallback] Trying provider: %s\n", providerID)
 
-		if isBuiltInProvider(providerID) {
-			if (req.Genre == "" || req.Label == "") && req.ISRC != "" {
+		if isBuiltInProvider(providerIDNormalized) {
+			if (req.Genre == "" || req.Label == "" || req.Copyright == "") &&
+				req.ISRC != "" {
 				GoLog("[DownloadWithExtensionFallback] Enriching extended metadata from Deezer for ISRC: %s\n", req.ISRC)
 				ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
 				deezerClient := GetDeezerClient()
@@ -887,14 +1269,18 @@ func DownloadWithExtensionFallback(req DownloadRequest) (*DownloadResponse, erro
 						req.Label = extMeta.Label
 						GoLog("[DownloadWithExtensionFallback] Label from Deezer: %s\n", req.Label)
 					}
+					if req.Copyright == "" && extMeta.Copyright != "" {
+						req.Copyright = extMeta.Copyright
+						GoLog("[DownloadWithExtensionFallback] Copyright from Deezer: %s\n", req.Copyright)
+					}
 				} else if err != nil {
 					GoLog("[DownloadWithExtensionFallback] Failed to get extended metadata from Deezer: %v\n", err)
 				}
 			}
 
-			result, err := tryBuiltInProvider(providerID, req)
+			result, err := tryBuiltInProvider(providerIDNormalized, req)
 			if err == nil && result.Success {
-				result.Service = providerID
+				result.Service = providerIDNormalized
 				if req.Label != "" {
 					result.Label = req.Label
 				}
@@ -915,11 +1301,11 @@ func DownloadWithExtensionFallback(req DownloadRequest) (*DownloadResponse, erro
 						Success:   false,
 						Error:     "Download cancelled",
 						ErrorType: "cancelled",
-						Service:   providerID,
+						Service:   providerIDNormalized,
 					}, nil
 				}
 				lastErr = err
-				GoLog("[DownloadWithExtensionFallback] %s failed: %v\n", providerID, err)
+				GoLog("[DownloadWithExtensionFallback] %s failed: %v\n", providerIDNormalized, err)
 			}
 		} else {
 			ext, err := extManager.GetExtension(providerID)
@@ -934,7 +1320,7 @@ func DownloadWithExtensionFallback(req DownloadRequest) (*DownloadResponse, erro
 
 			provider := NewExtensionProviderWrapper(ext)
 
-			availability, err := provider.CheckAvailability(req.ISRC, req.TrackName, req.ArtistName)
+			availability, err := provider.CheckAvailability(req.ISRC, req.TrackName, req.ArtistName, req.SpotifyID, req.DeezerID)
 			if err != nil || !availability.Available {
 				GoLog("[DownloadWithExtensionFallback] %s: not available\n", providerID)
 				if err != nil {
@@ -943,13 +1329,30 @@ func DownloadWithExtensionFallback(req DownloadRequest) (*DownloadResponse, erro
 				continue
 			}
 
-			outputPath := buildOutputPath(req)
+			outputPath := buildOutputPathForExtension(req, ext)
+			if req.ItemID != "" {
+				StartItemProgress(req.ItemID)
+			}
 
 			result, err := provider.Download(availability.TrackID, req.Quality, outputPath, func(percent int) {
 				if req.ItemID != "" {
-					SetItemProgress(req.ItemID, float64(percent), 0, 0)
+					normalized := float64(percent) / 100.0
+					if normalized < 0 {
+						normalized = 0
+					}
+					if normalized > 1 {
+						normalized = 1
+					}
+					SetItemProgress(req.ItemID, normalized, 0, 0)
 				}
 			})
+			if req.ItemID != "" {
+				if err == nil && result != nil && result.Success {
+					CompleteItemProgress(req.ItemID)
+				} else {
+					RemoveItemProgress(req.ItemID)
+				}
+			}
 
 			if err == nil && result.Success {
 				resp := &DownloadResponse{
@@ -962,9 +1365,10 @@ func DownloadWithExtensionFallback(req DownloadRequest) (*DownloadResponse, erro
 					Genre:            req.Genre,
 					Label:            req.Label,
 					Copyright:        req.Copyright,
+					DecryptionKey:    result.DecryptionKey,
 				}
 
-				if req.Genre != "" || req.Label != "" {
+				if req.EmbedMetadata && (req.Genre != "" || req.Label != "") {
 					if err := EmbedGenreLabel(result.FilePath, req.Genre, req.Label); err != nil {
 						GoLog("[DownloadWithExtensionFallback] Warning: failed to embed genre/label: %v\n", err)
 					} else {
@@ -1079,25 +1483,24 @@ func tryBuiltInProvider(providerID string, req DownloadRequest) (*DownloadRespon
 			}
 		}
 		err = qobuzErr
-	case "amazon":
-		amazonResult, amazonErr := downloadFromAmazon(req)
-		if amazonErr == nil {
+	case "deezer":
+		deezerResult, deezerErr := downloadFromDeezer(req)
+		if deezerErr == nil {
 			result = DownloadResult{
-				FilePath:      amazonResult.FilePath,
-				BitDepth:      amazonResult.BitDepth,
-				SampleRate:    amazonResult.SampleRate,
-				Title:         amazonResult.Title,
-				Artist:        amazonResult.Artist,
-				Album:         amazonResult.Album,
-				ReleaseDate:   amazonResult.ReleaseDate,
-				TrackNumber:   amazonResult.TrackNumber,
-				DiscNumber:    amazonResult.DiscNumber,
-				ISRC:          amazonResult.ISRC,
-				LyricsLRC:     amazonResult.LyricsLRC,
-				DecryptionKey: amazonResult.DecryptionKey,
+				FilePath:    deezerResult.FilePath,
+				BitDepth:    deezerResult.BitDepth,
+				SampleRate:  deezerResult.SampleRate,
+				Title:       deezerResult.Title,
+				Artist:      deezerResult.Artist,
+				Album:       deezerResult.Album,
+				ReleaseDate: deezerResult.ReleaseDate,
+				TrackNumber: deezerResult.TrackNumber,
+				DiscNumber:  deezerResult.DiscNumber,
+				ISRC:        deezerResult.ISRC,
+				LyricsLRC:   deezerResult.LyricsLRC,
 			}
 		}
-		err = amazonErr
+		err = deezerErr
 	default:
 		return nil, fmt.Errorf("unknown built-in provider: %s", providerID)
 	}
@@ -1159,7 +1562,58 @@ func buildOutputPath(req DownloadRequest) string {
 		ext = "." + ext
 	}
 
-	return fmt.Sprintf("%s/%s%s", req.OutputDir, filename, ext)
+	outputDir := req.OutputDir
+	if strings.TrimSpace(outputDir) == "" {
+		outputDir = filepath.Join(os.TempDir(), "spotiflac-downloads")
+		os.MkdirAll(outputDir, 0755)
+		AddAllowedDownloadDir(outputDir)
+	}
+
+	return filepath.Join(outputDir, filename+ext)
+}
+
+func buildOutputPathForExtension(req DownloadRequest, ext *LoadedExtension) string {
+	if strings.TrimSpace(req.OutputPath) != "" {
+		return strings.TrimSpace(req.OutputPath)
+	}
+
+	if strings.TrimSpace(req.OutputDir) != "" {
+		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)
+
+	metadata := map[string]interface{}{
+		"title":        req.TrackName,
+		"artist":       req.ArtistName,
+		"album":        req.AlbumName,
+		"album_artist": req.AlbumArtist,
+		"track":        req.TrackNumber,
+		"track_number": req.TrackNumber,
+		"disc":         req.DiscNumber,
+		"disc_number":  req.DiscNumber,
+		"year":         extractYear(req.ReleaseDate),
+		"date":         req.ReleaseDate,
+		"release_date": req.ReleaseDate,
+		"isrc":         req.ISRC,
+	}
+
+	filename := buildFilenameFromTemplate(req.FilenameFormat, metadata)
+	if filename == "" {
+		filename = sanitizeFilename(fmt.Sprintf("%s - %s", req.ArtistName, req.TrackName))
+	}
+
+	outputExt := strings.TrimSpace(req.OutputExt)
+	if outputExt == "" {
+		outputExt = ".flac"
+	} else if !strings.HasPrefix(outputExt, ".") {
+		outputExt = "." + outputExt
+	}
+
+	return filepath.Join(tempDir, filename+outputExt)
 }
 
 func (p *ExtensionProviderWrapper) CustomSearch(query string, options map[string]interface{}) ([]ExtTrackMetadata, error) {
@@ -1307,6 +1761,12 @@ func (p *ExtensionProviderWrapper) HandleURL(url string) (*ExtURLHandleResult, e
 				handleResult.Artist.Albums[i].Tracks[j].ProviderID = p.extension.ID
 			}
 		}
+		for i := range handleResult.Artist.Releases {
+			handleResult.Artist.Releases[i].ProviderID = p.extension.ID
+			for j := range handleResult.Artist.Releases[i].Tracks {
+				handleResult.Artist.Releases[i].Tracks[j].ProviderID = p.extension.ID
+			}
+		}
 		for i := range handleResult.Artist.TopTracks {
 			handleResult.Artist.TopTracks[i].ProviderID = p.extension.ID
 		}
@@ -1586,7 +2046,6 @@ func (m *ExtensionManager) HandleURLWithExtension(url string) (*ExtURLHandleResu
 	}, nil
 }
 
-// GetPostProcessingProviders returns all extensions that provide post-processing
 func (m *ExtensionManager) GetPostProcessingProviders() []*ExtensionProviderWrapper {
 	m.mu.RLock()
 	defer m.mu.RUnlock()
@@ -1600,7 +2059,6 @@ func (m *ExtensionManager) GetPostProcessingProviders() []*ExtensionProviderWrap
 	return providers
 }
 
-// RunPostProcessing runs all enabled post-processing hooks on a file
 func (m *ExtensionManager) RunPostProcessing(filePath string, metadata map[string]interface{}) (*PostProcessResult, error) {
 	providers := m.GetPostProcessingProviders()
 	if len(providers) == 0 {
@@ -1646,7 +2104,6 @@ func (m *ExtensionManager) RunPostProcessing(filePath string, metadata map[strin
 	return &PostProcessResult{Success: true, NewFilePath: currentPath}, nil
 }
 
-// RunPostProcessingV2 runs all enabled post-processing hooks on a file input.
 func (m *ExtensionManager) RunPostProcessingV2(input PostProcessInput, metadata map[string]interface{}) (*PostProcessResult, error) {
 	providers := m.GetPostProcessingProviders()
 	if len(providers) == 0 {
@@ -1701,9 +2158,6 @@ func (m *ExtensionManager) RunPostProcessingV2(input PostProcessInput, metadata
 	return &PostProcessResult{Success: true, NewFilePath: currentInput.Path, NewFileURI: currentInput.URI}, nil
 }
 
-// ==================== Lyrics Provider ====================
-
-// ExtLyricsResult represents lyrics data returned from an extension
 type ExtLyricsResult struct {
 	Lines        []ExtLyricsLine `json:"lines"`
 	SyncType     string          `json:"syncType"`
@@ -1718,7 +2172,6 @@ type ExtLyricsLine struct {
 	EndTimeMs   int64  `json:"endTimeMs"`
 }
 
-// FetchLyrics calls the extension's fetchLyrics function
 func (p *ExtensionProviderWrapper) FetchLyrics(trackName, artistName, albumName string, durationSec float64) (*LyricsResponse, error) {
 	if !p.extension.Manifest.IsLyricsProvider() {
 		return nil, fmt.Errorf("extension '%s' is not a lyrics provider", p.extension.ID)
@@ -1818,7 +2271,6 @@ func (p *ExtensionProviderWrapper) FetchLyrics(trackName, artistName, albumName
 	return response, nil
 }
 
-// GetLyricsProviders returns all enabled extensions that provide lyrics
 func (m *ExtensionManager) GetLyricsProviders() []*ExtensionProviderWrapper {
 	m.mu.RLock()
 	defer m.mu.RUnlock()

go_backend/extension_providers_test.go

@@ -0,0 +1,68 @@
+package gobackend
+
+import "testing"
+
+func TestSetMetadataProviderPriorityAddsBuiltIns(t *testing.T) {
+	original := GetMetadataProviderPriority()
+	defer SetMetadataProviderPriority(original)
+
+	SetMetadataProviderPriority([]string{"tidal"})
+	got := GetMetadataProviderPriority()
+	want := []string{"tidal", "deezer", "qobuz"}
+	if len(got) != len(want) {
+		t.Fatalf("unexpected priority length: got %v want %v", got, want)
+	}
+	for i := range want {
+		if got[i] != want[i] {
+			t.Fatalf("unexpected priority at %d: got %v want %v", i, got, want)
+		}
+	}
+}
+
+func TestSearchTracksWithMetadataProvidersUsesPriorityAndDedupes(t *testing.T) {
+	originalPriority := GetMetadataProviderPriority()
+	originalSearch := searchBuiltInMetadataTracksFunc
+	defer func() {
+		SetMetadataProviderPriority(originalPriority)
+		searchBuiltInMetadataTracksFunc = originalSearch
+	}()
+
+	SetMetadataProviderPriority([]string{"qobuz", "tidal", "deezer"})
+
+	var calls []string
+	searchBuiltInMetadataTracksFunc = func(providerID, query string, limit int) ([]ExtTrackMetadata, error) {
+		calls = append(calls, providerID)
+		switch providerID {
+		case "qobuz":
+			return []ExtTrackMetadata{
+				{ProviderID: "qobuz", SpotifyID: "qobuz:1", ISRC: "AAA111", Name: "First"},
+			}, nil
+		case "tidal":
+			return []ExtTrackMetadata{
+				{ProviderID: "tidal", SpotifyID: "tidal:2", ISRC: "AAA111", Name: "Duplicate"},
+				{ProviderID: "tidal", SpotifyID: "tidal:3", ISRC: "BBB222", Name: "Second"},
+			}, nil
+		case "deezer":
+			return []ExtTrackMetadata{
+				{ProviderID: "deezer", SpotifyID: "deezer:4", ISRC: "CCC333", Name: "Third"},
+			}, nil
+		default:
+			return nil, nil
+		}
+	}
+
+	manager := GetExtensionManager()
+	tracks, err := manager.SearchTracksWithMetadataProviders("query", 3, false)
+	if err != nil {
+		t.Fatalf("SearchTracksWithMetadataProviders returned error: %v", err)
+	}
+	if len(tracks) != 3 {
+		t.Fatalf("unexpected track count: got %d want 3", len(tracks))
+	}
+	if tracks[0].ProviderID != "qobuz" || tracks[1].ProviderID != "tidal" || tracks[2].ProviderID != "deezer" {
+		t.Fatalf("unexpected track provider order: %+v", tracks)
+	}
+	if len(calls) != 3 || calls[0] != "qobuz" || calls[1] != "tidal" || calls[2] != "deezer" {
+		t.Fatalf("unexpected provider call order: %v", calls)
+	}
+}

go_backend/extension_runtime.go

@@ -81,60 +81,101 @@ func SetExtensionTokens(extensionID string, accessToken, refreshToken string, ex
 }
 
 type ExtensionRuntime struct {
-	extensionID string
-	manifest    *ExtensionManifest
-	settings    map[string]interface{}
-	httpClient  *http.Client
-	cookieJar   http.CookieJar
-	dataDir     string
-	vm          *goja.Runtime
+	extensionID    string
+	manifest       *ExtensionManifest
+	settings       map[string]interface{}
+	httpClient     *http.Client
+	downloadClient *http.Client
+	cookieJar      http.CookieJar
+	dataDir        string
+	vm             *goja.Runtime
+
+	storageMu      sync.RWMutex
+	storageCache   map[string]interface{}
+	storageLoaded  bool
+	storageDirty   bool
+	storageClosed  bool
+	storageTimer   *time.Timer
+	storageWriteMu sync.Mutex
+
+	credentialsMu     sync.RWMutex
+	credentialsCache  map[string]interface{}
+	credentialsLoaded bool
+	storageFlushDelay time.Duration
 }
 
+type privateIPCacheEntry struct {
+	isPrivate bool
+	expiresAt time.Time
+}
+
+const (
+	privateIPCacheTTL      = 5 * time.Minute
+	privateIPErrorCacheTTL = 30 * time.Second
+	maxPrivateIPCacheSize  = 1024
+)
+
+var (
+	privateIPCache   = make(map[string]privateIPCacheEntry)
+	privateIPCacheMu sync.RWMutex
+)
+
 func NewExtensionRuntime(ext *LoadedExtension) *ExtensionRuntime {
 	jar, _ := newSimpleCookieJar()
 
 	runtime := &ExtensionRuntime{
-		extensionID: ext.ID,
-		manifest:    ext.Manifest,
-		settings:    make(map[string]interface{}),
-		cookieJar:   jar,
-		dataDir:     ext.DataDir,
-		vm:          ext.VM,
+		extensionID:       ext.ID,
+		manifest:          ext.Manifest,
+		settings:          make(map[string]interface{}),
+		cookieJar:         jar,
+		dataDir:           ext.DataDir,
+		vm:                ext.VM,
+		storageFlushDelay: defaultStorageFlushDelay,
 	}
 
-	client := &http.Client{
-		Timeout: 30 * time.Second,
-		Jar:     jar,
-		CheckRedirect: func(req *http.Request, via []*http.Request) error {
-			if req.URL.Scheme != "https" {
-				GoLog("[Extension:%s] Redirect blocked: non-https scheme '%s'\n", ext.ID, req.URL.Scheme)
-				return fmt.Errorf("redirect blocked: only https is allowed")
-			}
-
-			domain := req.URL.Hostname()
-			if domain == "" {
-				GoLog("[Extension:%s] Redirect blocked: missing hostname\n", ext.ID)
-				return fmt.Errorf("redirect blocked: hostname is required")
-			}
-			if !ext.Manifest.IsDomainAllowed(domain) {
-				GoLog("[Extension:%s] Redirect blocked: domain '%s' not in allowed list\n", ext.ID, domain)
-				return &RedirectBlockedError{Domain: domain}
-			}
-			if isPrivateIP(domain) {
-				GoLog("[Extension:%s] Redirect blocked: private IP '%s'\n", ext.ID, domain)
-				return &RedirectBlockedError{Domain: domain, IsPrivate: true}
-			}
-			if len(via) >= 10 {
-				return http.ErrUseLastResponse
-			}
-			return nil
-		},
-	}
-	runtime.httpClient = client
+	runtime.httpClient = newExtensionHTTPClient(ext, jar, 30*time.Second)
+	runtime.downloadClient = newExtensionHTTPClient(ext, jar, DownloadTimeout)
 
 	return runtime
 }
 
+func newExtensionHTTPClient(ext *LoadedExtension, jar http.CookieJar, timeout time.Duration) *http.Client {
+	// Extension sandbox enforces HTTPS-only domains. Do not apply global
+	// allow_http scheme downgrade here, because some extension APIs (e.g.
+	// spotify-web) will redirect http -> https and can end up in 301 loops.
+	// We still reuse sharedTransport so insecure TLS compatibility mode remains effective.
+	client := &http.Client{
+		Transport: sharedTransport,
+		Timeout:   timeout,
+		Jar:       jar,
+	}
+	client.CheckRedirect = func(req *http.Request, via []*http.Request) error {
+		if req.URL.Scheme != "https" {
+			GoLog("[Extension:%s] Redirect blocked: non-https scheme '%s'\n", ext.ID, req.URL.Scheme)
+			return fmt.Errorf("redirect blocked: only https is allowed")
+		}
+
+		domain := req.URL.Hostname()
+		if domain == "" {
+			GoLog("[Extension:%s] Redirect blocked: missing hostname\n", ext.ID)
+			return fmt.Errorf("redirect blocked: hostname is required")
+		}
+		if !ext.Manifest.IsDomainAllowed(domain) {
+			GoLog("[Extension:%s] Redirect blocked: domain '%s' not in allowed list\n", ext.ID, domain)
+			return &RedirectBlockedError{Domain: domain}
+		}
+		if isPrivateIP(domain) {
+			GoLog("[Extension:%s] Redirect blocked: private IP '%s'\n", ext.ID, domain)
+			return &RedirectBlockedError{Domain: domain, IsPrivate: true}
+		}
+		if len(via) >= 10 {
+			return http.ErrUseLastResponse
+		}
+		return nil
+	}
+	return client
+}
+
 type RedirectBlockedError struct {
 	Domain    string
 	IsPrivate bool
@@ -147,7 +188,6 @@ func (e *RedirectBlockedError) Error() string {
 	return "redirect blocked: domain '" + e.Domain + "' not in allowed list"
 }
 
-// isPrivateIP checks if a hostname resolves to a private/local IP address
 func isPrivateIP(host string) bool {
 	hostLower := strings.ToLower(strings.TrimSpace(host))
 	if hostLower == "" {
@@ -162,18 +202,68 @@ func isPrivateIP(host string) bool {
 		return isPrivateIPAddr(ip)
 	}
 
+	if cached, ok := getPrivateIPCache(hostLower); ok {
+		return cached
+	}
+
 	ips, err := net.LookupIP(hostLower)
 	if err != nil {
+		setPrivateIPCache(hostLower, false, privateIPErrorCacheTTL)
 		return false
 	}
 
+	isPrivate := false
 	for _, ip := range ips {
 		if isPrivateIPAddr(ip) {
-			return true
+			isPrivate = true
+			break
 		}
 	}
 
-	return false
+	setPrivateIPCache(hostLower, isPrivate, privateIPCacheTTL)
+	return isPrivate
+}
+
+func getPrivateIPCache(host string) (bool, bool) {
+	now := time.Now()
+
+	privateIPCacheMu.RLock()
+	entry, exists := privateIPCache[host]
+	privateIPCacheMu.RUnlock()
+	if !exists {
+		return false, false
+	}
+
+	if now.Before(entry.expiresAt) {
+		return entry.isPrivate, true
+	}
+
+	privateIPCacheMu.Lock()
+	delete(privateIPCache, host)
+	privateIPCacheMu.Unlock()
+	return false, false
+}
+
+func setPrivateIPCache(host string, isPrivate bool, ttl time.Duration) {
+	expiresAt := time.Now().Add(ttl)
+
+	privateIPCacheMu.Lock()
+	if len(privateIPCache) >= maxPrivateIPCacheSize {
+		now := time.Now()
+		for key, entry := range privateIPCache {
+			if now.After(entry.expiresAt) {
+				delete(privateIPCache, key)
+			}
+		}
+		if len(privateIPCache) >= maxPrivateIPCacheSize {
+			privateIPCache = make(map[string]privateIPCacheEntry)
+		}
+	}
+	privateIPCache[host] = privateIPCacheEntry{
+		isPrivate: isPrivate,
+		expiresAt: expiresAt,
+	}
+	privateIPCacheMu.Unlock()
 }
 
 func isPrivateIPAddr(ip net.IP) bool {

go_backend/extension_runtime_auth.go

@@ -1,4 +1,3 @@
-// Package gobackend provides Auth API and PKCE support for extension runtime
 package gobackend
 
 import (
@@ -16,8 +15,6 @@ import (
 	"github.com/dop251/goja"
 )
 
-// ==================== Auth API (OAuth Support) ====================
-
 func validateExtensionAuthURL(urlStr string) error {
 	parsed, err := url.Parse(urlStr)
 	if err != nil {
@@ -204,9 +201,6 @@ func (r *ExtensionRuntime) authGetTokens(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(result)
 }
 
-// ==================== PKCE Support ====================
-
-// generatePKCEVerifier generates a cryptographically random code verifier
 // Length should be between 43-128 characters (RFC 7636)
 func generatePKCEVerifier(length int) (string, error) {
 	if length < 43 {
@@ -394,9 +388,7 @@ func (r *ExtensionRuntime) authStartOAuthWithPKCE(call goja.FunctionCall) goja.V
 	})
 }
 
-// authExchangeCodeWithPKCE exchanges auth code for tokens using PKCE
 // config: { tokenUrl, clientId, redirectUri, code, extraParams }
-// Uses the stored PKCE verifier automatically
 func (r *ExtensionRuntime) authExchangeCodeWithPKCE(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue(map[string]interface{}{
@@ -414,7 +406,6 @@ func (r *ExtensionRuntime) authExchangeCodeWithPKCE(call goja.FunctionCall) goja
 		})
 	}
 
-	// Required fields
 	tokenURL, _ := config["tokenUrl"].(string)
 	clientID, _ := config["clientId"].(string)
 	redirectURI, _ := config["redirectUri"].(string)

go_backend/extension_runtime_ffmpeg.go

@@ -1,4 +1,3 @@
-// Package gobackend provides FFmpeg API for extension runtime
 package gobackend
 
 import (
@@ -10,9 +9,7 @@ import (
 	"github.com/dop251/goja"
 )
 
-// ==================== FFmpeg API (Post-Processing) ====================
-
-// FFmpegCommand holds a pending FFmpeg command for Flutter to execute
+// FFmpegCommand holds a pending FFmpeg command for Flutter to execute.
 type FFmpegCommand struct {
 	ExtensionID string
 	Command     string
@@ -24,7 +21,6 @@ type FFmpegCommand struct {
 	Output      string
 }
 
-// Global FFmpeg command queue
 var (
 	ffmpegCommands   = make(map[string]*FFmpegCommand)
 	ffmpegCommandsMu sync.RWMutex

go_backend/extension_runtime_file.go

@@ -1,4 +1,3 @@
-// Package gobackend provides File API for extension runtime
 package gobackend
 
 import (
@@ -13,8 +12,6 @@ import (
 	"github.com/dop251/goja"
 )
 
-// ==================== File API (Sandboxed) ====================
-
 var (
 	allowedDownloadDirs   []string
 	allowedDownloadDirsMu sync.RWMutex
@@ -177,7 +174,12 @@ func (r *ExtensionRuntime) fileDownload(call goja.FunctionCall) goja.Value {
 		req.Header.Set("User-Agent", "SpotiFLAC-Extension/1.0")
 	}
 
-	resp, err := r.httpClient.Do(req)
+	client := r.downloadClient
+	if client == nil {
+		client = r.httpClient
+	}
+
+	resp, err := client.Do(req)
 	if err != nil {
 		return r.vm.ToValue(map[string]interface{}{
 			"success": false,
@@ -396,13 +398,14 @@ func (r *ExtensionRuntime) fileCopy(call goja.FunctionCall) goja.Value {
 		})
 	}
 
-	data, err := os.ReadFile(fullSrc)
+	srcFile, err := os.Open(fullSrc)
 	if err != nil {
 		return r.vm.ToValue(map[string]interface{}{
 			"success": false,
 			"error":   fmt.Sprintf("failed to read source: %v", err),
 		})
 	}
+	defer srcFile.Close()
 
 	dir := filepath.Dir(fullDst)
 	if err := os.MkdirAll(dir, 0755); err != nil {
@@ -412,10 +415,26 @@ func (r *ExtensionRuntime) fileCopy(call goja.FunctionCall) goja.Value {
 		})
 	}
 
-	if err := os.WriteFile(fullDst, data, 0644); err != nil {
+	dstFile, err := os.OpenFile(fullDst, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, 0644)
+	if err != nil {
 		return r.vm.ToValue(map[string]interface{}{
 			"success": false,
-			"error":   fmt.Sprintf("failed to write destination: %v", err),
+			"error":   fmt.Sprintf("failed to open destination: %v", err),
+		})
+	}
+
+	if _, err := io.Copy(dstFile, srcFile); err != nil {
+		_ = dstFile.Close()
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   fmt.Sprintf("failed to copy file: %v", err),
+		})
+	}
+
+	if err := dstFile.Close(); err != nil {
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   fmt.Sprintf("failed to finalize destination: %v", err),
 		})
 	}
 

go_backend/extension_runtime_http.go

@@ -1,4 +1,3 @@
-// Package gobackend provides HTTP API for extension runtime
 package gobackend
 
 import (
@@ -12,8 +11,6 @@ import (
 	"github.com/dop251/goja"
 )
 
-// ==================== HTTP API (Sandboxed) ====================
-
 type HTTPResponse struct {
 	StatusCode int               `json:"statusCode"`
 	Body       string            `json:"body"`

go_backend/extension_runtime_matching.go

@@ -1,4 +1,3 @@
-// Package gobackend provides Track Matching API for extension runtime
 package gobackend
 
 import (
@@ -7,8 +6,6 @@ import (
 	"github.com/dop251/goja"
 )
 
-// ==================== Track Matching API ====================
-
 func (r *ExtensionRuntime) matchingCompareStrings(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 2 {
 		return r.vm.ToValue(0.0)

go_backend/extension_runtime_polyfills.go

@@ -1,4 +1,3 @@
-// Package gobackend provides Browser-like Polyfills for extension runtime
 package gobackend
 
 import (
@@ -13,12 +12,10 @@ import (
 	"github.com/dop251/goja"
 )
 
-// ==================== Browser-like Polyfills ====================
 // These polyfills make porting browser/Node.js libraries easier
-// without compromising sandbox security
+// without compromising sandbox security.
 
-// fetchPolyfill implements browser-compatible fetch() API
-// Returns a Promise-like object with json(), text() methods
+// 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")
@@ -141,7 +138,6 @@ func (r *ExtensionRuntime) fetchPolyfill(call goja.FunctionCall) goja.Value {
 	return responseObj
 }
 
-// createFetchError creates a fetch error response
 func (r *ExtensionRuntime) createFetchError(message string) goja.Value {
 	errorObj := r.vm.NewObject()
 	errorObj.Set("ok", false)
@@ -157,7 +153,6 @@ func (r *ExtensionRuntime) createFetchError(message string) goja.Value {
 	return errorObj
 }
 
-// atobPolyfill implements browser atob() - decode base64 to string
 func (r *ExtensionRuntime) atobPolyfill(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue("")
@@ -174,7 +169,6 @@ func (r *ExtensionRuntime) atobPolyfill(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(string(decoded))
 }
 
-// btoaPolyfill implements browser btoa() - encode string to base64
 func (r *ExtensionRuntime) btoaPolyfill(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue("")
@@ -183,7 +177,6 @@ func (r *ExtensionRuntime) btoaPolyfill(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(base64.StdEncoding.EncodeToString([]byte(input)))
 }
 
-// registerTextEncoderDecoder registers TextEncoder and TextDecoder classes
 func (r *ExtensionRuntime) registerTextEncoderDecoder(vm *goja.Runtime) {
 	vm.Set("TextEncoder", func(call goja.ConstructorCall) *goja.Object {
 		encoder := call.This
@@ -429,9 +422,8 @@ func (r *ExtensionRuntime) registerURLClass(vm *goja.Runtime) {
 	})
 }
 
-// registerJSONGlobal ensures JSON global is properly set up
+// JSON is already built-in to Goja; this ensures a fallback exists.
 func (r *ExtensionRuntime) registerJSONGlobal(vm *goja.Runtime) {
-	// JSON is already built-in to Goja, but we can enhance it
 	jsonScript := `
 		if (typeof JSON === 'undefined') {
 			var JSON = {

go_backend/extension_runtime_storage.go

@@ -1,4 +1,3 @@
-// Package gobackend provides Storage and Credentials API for extension runtime
 package gobackend
 
 import (
@@ -11,42 +10,162 @@ import (
 	"io"
 	"os"
 	"path/filepath"
+	"reflect"
+	"time"
 
 	"github.com/dop251/goja"
 )
 
-// ==================== Storage API ====================
+const (
+	defaultStorageFlushDelay = 400 * time.Millisecond
+	storageFlushRetryDelay   = 2 * time.Second
+)
 
 func (r *ExtensionRuntime) getStoragePath() string {
 	return filepath.Join(r.dataDir, "storage.json")
 }
 
-func (r *ExtensionRuntime) loadStorage() (map[string]interface{}, error) {
+func cloneInterfaceMap(src map[string]interface{}) map[string]interface{} {
+	if len(src) == 0 {
+		return make(map[string]interface{})
+	}
+	dst := make(map[string]interface{}, len(src))
+	for k, v := range src {
+		dst[k] = v
+	}
+	return dst
+}
+
+func (r *ExtensionRuntime) ensureStorageLoaded() error {
+	r.storageMu.RLock()
+	if r.storageLoaded {
+		r.storageMu.RUnlock()
+		return nil
+	}
+	r.storageMu.RUnlock()
+
+	r.storageMu.Lock()
+	defer r.storageMu.Unlock()
+	if r.storageLoaded {
+		return nil
+	}
+
 	storagePath := r.getStoragePath()
 	data, err := os.ReadFile(storagePath)
 	if err != nil {
 		if os.IsNotExist(err) {
-			return make(map[string]interface{}), nil
+			r.storageCache = make(map[string]interface{})
+			r.storageLoaded = true
+			return nil
 		}
-		return nil, err
+		return err
 	}
 
 	var storage map[string]interface{}
 	if err := json.Unmarshal(data, &storage); err != nil {
+		return err
+	}
+	if storage == nil {
+		storage = make(map[string]interface{})
+	}
+
+	r.storageCache = storage
+	r.storageLoaded = true
+	return nil
+}
+
+func (r *ExtensionRuntime) loadStorage() (map[string]interface{}, error) {
+	if err := r.ensureStorageLoaded(); err != nil {
 		return nil, err
 	}
 
-	return storage, nil
+	r.storageMu.RLock()
+	defer r.storageMu.RUnlock()
+	return cloneInterfaceMap(r.storageCache), nil
 }
 
-func (r *ExtensionRuntime) saveStorage(storage map[string]interface{}) error {
-	storagePath := r.getStoragePath()
-	data, err := json.MarshalIndent(storage, "", "  ")
+func (r *ExtensionRuntime) queueStorageFlushLocked(delay time.Duration) {
+	if r.storageClosed {
+		return
+	}
+	if r.storageTimer != nil {
+		return
+	}
+	r.storageTimer = time.AfterFunc(delay, r.flushStorageDirtyAsync)
+}
+
+func (r *ExtensionRuntime) persistStorageSnapshot(storage map[string]interface{}) error {
+	data, err := json.Marshal(storage)
 	if err != nil {
 		return err
 	}
 
-	return os.WriteFile(storagePath, data, 0600)
+	r.storageWriteMu.Lock()
+	defer r.storageWriteMu.Unlock()
+
+	return os.WriteFile(r.getStoragePath(), data, 0600)
+}
+
+func (r *ExtensionRuntime) flushStorageDirtyAsync() {
+	if err := r.flushStorageDirty(); err != nil {
+		GoLog("[Extension:%s] Storage flush error: %v\n", r.extensionID, err)
+	}
+}
+
+func (r *ExtensionRuntime) flushStorageDirty() error {
+	r.storageMu.Lock()
+	if r.storageClosed {
+		r.storageTimer = nil
+		r.storageMu.Unlock()
+		return nil
+	}
+	if !r.storageDirty {
+		r.storageTimer = nil
+		r.storageMu.Unlock()
+		return nil
+	}
+	snapshot := cloneInterfaceMap(r.storageCache)
+	r.storageDirty = false
+	r.storageTimer = nil
+	r.storageMu.Unlock()
+
+	if err := r.persistStorageSnapshot(snapshot); err != nil {
+		r.storageMu.Lock()
+		r.storageDirty = true
+		r.queueStorageFlushLocked(storageFlushRetryDelay)
+		r.storageMu.Unlock()
+		return err
+	}
+
+	return nil
+}
+
+func (r *ExtensionRuntime) flushStorageNow() error {
+	r.storageMu.Lock()
+	if r.storageTimer != nil {
+		r.storageTimer.Stop()
+		r.storageTimer = nil
+	}
+	if !r.storageLoaded || r.storageClosed {
+		r.storageMu.Unlock()
+		return nil
+	}
+	snapshot := cloneInterfaceMap(r.storageCache)
+	r.storageDirty = false
+	r.storageMu.Unlock()
+
+	return r.persistStorageSnapshot(snapshot)
+}
+
+func (r *ExtensionRuntime) closeStorageFlusher() {
+	r.storageMu.Lock()
+	r.storageClosed = true
+	r.storageDirty = false
+	if r.storageTimer != nil {
+		r.storageTimer.Stop()
+		r.storageTimer = nil
+	}
+	r.storageMu.Unlock()
 }
 
 func (r *ExtensionRuntime) storageGet(call goja.FunctionCall) goja.Value {
@@ -56,13 +175,14 @@ func (r *ExtensionRuntime) storageGet(call goja.FunctionCall) goja.Value {
 
 	key := call.Arguments[0].String()
 
-	storage, err := r.loadStorage()
-	if err != nil {
+	if err := r.ensureStorageLoaded(); err != nil {
 		GoLog("[Extension:%s] Storage load error: %v\n", r.extensionID, err)
 		return goja.Undefined()
 	}
 
-	value, exists := storage[key]
+	r.storageMu.RLock()
+	value, exists := r.storageCache[key]
+	r.storageMu.RUnlock()
 	if !exists {
 		if len(call.Arguments) > 1 {
 			return call.Arguments[1]
@@ -81,18 +201,26 @@ func (r *ExtensionRuntime) storageSet(call goja.FunctionCall) goja.Value {
 	key := call.Arguments[0].String()
 	value := call.Arguments[1].Export()
 
-	storage, err := r.loadStorage()
-	if err != nil {
+	if err := r.ensureStorageLoaded(); err != nil {
 		GoLog("[Extension:%s] Storage load error: %v\n", r.extensionID, err)
 		return r.vm.ToValue(false)
 	}
 
-	storage[key] = value
-
-	if err := r.saveStorage(storage); err != nil {
-		GoLog("[Extension:%s] Storage save error: %v\n", r.extensionID, err)
+	r.storageMu.Lock()
+	if r.storageClosed {
+		r.storageMu.Unlock()
 		return r.vm.ToValue(false)
 	}
+	if existing, exists := r.storageCache[key]; exists {
+		if reflect.DeepEqual(existing, value) {
+			r.storageMu.Unlock()
+			return r.vm.ToValue(true)
+		}
+	}
+	r.storageCache[key] = value
+	r.storageDirty = true
+	r.queueStorageFlushLocked(r.storageFlushDelay)
+	r.storageMu.Unlock()
 
 	return r.vm.ToValue(true)
 }
@@ -104,18 +232,24 @@ func (r *ExtensionRuntime) storageRemove(call goja.FunctionCall) goja.Value {
 
 	key := call.Arguments[0].String()
 
-	storage, err := r.loadStorage()
-	if err != nil {
+	if err := r.ensureStorageLoaded(); err != nil {
 		GoLog("[Extension:%s] Storage load error: %v\n", r.extensionID, err)
 		return r.vm.ToValue(false)
 	}
 
-	delete(storage, key)
-
-	if err := r.saveStorage(storage); err != nil {
-		GoLog("[Extension:%s] Storage save error: %v\n", r.extensionID, err)
+	r.storageMu.Lock()
+	if r.storageClosed {
+		r.storageMu.Unlock()
 		return r.vm.ToValue(false)
 	}
+	if _, exists := r.storageCache[key]; !exists {
+		r.storageMu.Unlock()
+		return r.vm.ToValue(true)
+	}
+	delete(r.storageCache, key)
+	r.storageDirty = true
+	r.queueStorageFlushLocked(r.storageFlushDelay)
+	r.storageMu.Unlock()
 
 	return r.vm.ToValue(true)
 }
@@ -159,31 +293,61 @@ func (r *ExtensionRuntime) getEncryptionKey() ([]byte, error) {
 	return hash[:], nil
 }
 
-func (r *ExtensionRuntime) loadCredentials() (map[string]interface{}, error) {
+func (r *ExtensionRuntime) ensureCredentialsLoaded() error {
+	r.credentialsMu.RLock()
+	if r.credentialsLoaded {
+		r.credentialsMu.RUnlock()
+		return nil
+	}
+	r.credentialsMu.RUnlock()
+
+	r.credentialsMu.Lock()
+	defer r.credentialsMu.Unlock()
+	if r.credentialsLoaded {
+		return nil
+	}
+
 	credPath := r.getCredentialsPath()
 	data, err := os.ReadFile(credPath)
 	if err != nil {
 		if os.IsNotExist(err) {
-			return make(map[string]interface{}), nil
+			r.credentialsCache = make(map[string]interface{})
+			r.credentialsLoaded = true
+			return nil
 		}
-		return nil, err
+		return err
 	}
 
 	key, err := r.getEncryptionKey()
 	if err != nil {
-		return nil, fmt.Errorf("failed to get encryption key: %w", err)
+		return fmt.Errorf("failed to get encryption key: %w", err)
 	}
 	decrypted, err := decryptAES(data, key)
 	if err != nil {
-		return nil, fmt.Errorf("failed to decrypt credentials: %w", err)
+		return fmt.Errorf("failed to decrypt credentials: %w", err)
 	}
 
 	var creds map[string]interface{}
 	if err := json.Unmarshal(decrypted, &creds); err != nil {
+		return err
+	}
+	if creds == nil {
+		creds = make(map[string]interface{})
+	}
+
+	r.credentialsCache = creds
+	r.credentialsLoaded = true
+	return nil
+}
+
+func (r *ExtensionRuntime) loadCredentials() (map[string]interface{}, error) {
+	if err := r.ensureCredentialsLoaded(); err != nil {
 		return nil, err
 	}
 
-	return creds, nil
+	r.credentialsMu.RLock()
+	defer r.credentialsMu.RUnlock()
+	return cloneInterfaceMap(r.credentialsCache), nil
 }
 
 func (r *ExtensionRuntime) saveCredentials(creds map[string]interface{}) error {
@@ -202,7 +366,15 @@ func (r *ExtensionRuntime) saveCredentials(creds map[string]interface{}) error {
 	}
 
 	credPath := r.getCredentialsPath()
-	return os.WriteFile(credPath, encrypted, 0600)
+	if err := os.WriteFile(credPath, encrypted, 0600); err != nil {
+		return err
+	}
+
+	r.credentialsMu.Lock()
+	r.credentialsCache = cloneInterfaceMap(creds)
+	r.credentialsLoaded = true
+	r.credentialsMu.Unlock()
+	return nil
 }
 
 func (r *ExtensionRuntime) credentialsStore(call goja.FunctionCall) goja.Value {
@@ -216,8 +388,7 @@ func (r *ExtensionRuntime) credentialsStore(call goja.FunctionCall) goja.Value {
 	key := call.Arguments[0].String()
 	value := call.Arguments[1].Export()
 
-	creds, err := r.loadCredentials()
-	if err != nil {
+	if err := r.ensureCredentialsLoaded(); err != nil {
 		GoLog("[Extension:%s] Credentials load error: %v\n", r.extensionID, err)
 		return r.vm.ToValue(map[string]interface{}{
 			"success": false,
@@ -225,9 +396,12 @@ func (r *ExtensionRuntime) credentialsStore(call goja.FunctionCall) goja.Value {
 		})
 	}
 
-	creds[key] = value
+	r.credentialsMu.RLock()
+	nextCreds := cloneInterfaceMap(r.credentialsCache)
+	r.credentialsMu.RUnlock()
+	nextCreds[key] = value
 
-	if err := r.saveCredentials(creds); err != nil {
+	if err := r.saveCredentials(nextCreds); err != nil {
 		GoLog("[Extension:%s] Credentials save error: %v\n", r.extensionID, err)
 		return r.vm.ToValue(map[string]interface{}{
 			"success": false,
@@ -247,13 +421,14 @@ func (r *ExtensionRuntime) credentialsGet(call goja.FunctionCall) goja.Value {
 
 	key := call.Arguments[0].String()
 
-	creds, err := r.loadCredentials()
-	if err != nil {
+	if err := r.ensureCredentialsLoaded(); err != nil {
 		GoLog("[Extension:%s] Credentials load error: %v\n", r.extensionID, err)
 		return goja.Undefined()
 	}
 
-	value, exists := creds[key]
+	r.credentialsMu.RLock()
+	value, exists := r.credentialsCache[key]
+	r.credentialsMu.RUnlock()
 	if !exists {
 		if len(call.Arguments) > 1 {
 			return call.Arguments[1]
@@ -271,15 +446,17 @@ func (r *ExtensionRuntime) credentialsRemove(call goja.FunctionCall) goja.Value
 
 	key := call.Arguments[0].String()
 
-	creds, err := r.loadCredentials()
-	if err != nil {
+	if err := r.ensureCredentialsLoaded(); err != nil {
 		GoLog("[Extension:%s] Credentials load error: %v\n", r.extensionID, err)
 		return r.vm.ToValue(false)
 	}
 
-	delete(creds, key)
+	r.credentialsMu.RLock()
+	nextCreds := cloneInterfaceMap(r.credentialsCache)
+	r.credentialsMu.RUnlock()
+	delete(nextCreds, key)
 
-	if err := r.saveCredentials(creds); err != nil {
+	if err := r.saveCredentials(nextCreds); err != nil {
 		GoLog("[Extension:%s] Credentials save error: %v\n", r.extensionID, err)
 		return r.vm.ToValue(false)
 	}
@@ -294,12 +471,13 @@ func (r *ExtensionRuntime) credentialsHas(call goja.FunctionCall) goja.Value {
 
 	key := call.Arguments[0].String()
 
-	creds, err := r.loadCredentials()
-	if err != nil {
+	if err := r.ensureCredentialsLoaded(); err != nil {
 		return r.vm.ToValue(false)
 	}
 
-	_, exists := creds[key]
+	r.credentialsMu.RLock()
+	_, exists := r.credentialsCache[key]
+	r.credentialsMu.RUnlock()
 	return r.vm.ToValue(exists)
 }
 

go_backend/extension_runtime_storage_test.go

@@ -0,0 +1,120 @@
+package gobackend
+
+import (
+	"bytes"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/dop251/goja"
+)
+
+func setStorageValue(t *testing.T, runtime *ExtensionRuntime, key string, value interface{}) {
+	t.Helper()
+	result := runtime.storageSet(goja.FunctionCall{
+		Arguments: []goja.Value{
+			runtime.vm.ToValue(key),
+			runtime.vm.ToValue(value),
+		},
+	})
+	if !result.ToBoolean() {
+		t.Fatalf("storage.set(%q) returned false", key)
+	}
+}
+
+func readStorageMap(t *testing.T, storagePath string) map[string]interface{} {
+	t.Helper()
+	data, err := os.ReadFile(storagePath)
+	if err != nil {
+		t.Fatalf("failed to read storage file: %v", err)
+	}
+
+	var parsed map[string]interface{}
+	if err := json.Unmarshal(data, &parsed); err != nil {
+		t.Fatalf("failed to unmarshal storage file: %v", err)
+	}
+	return parsed
+}
+
+func TestExtensionRuntimeStorage_DebouncedWriteCompactJSON(t *testing.T) {
+	ext := &LoadedExtension{
+		ID: "storage-test",
+		Manifest: &ExtensionManifest{
+			Name: "storage-test",
+		},
+		DataDir: t.TempDir(),
+	}
+
+	runtime := NewExtensionRuntime(ext)
+	runtime.storageFlushDelay = 25 * time.Millisecond
+	runtime.RegisterAPIs(goja.New())
+
+	setStorageValue(t, runtime, "k1", "v1")
+	setStorageValue(t, runtime, "k2", 2)
+
+	storagePath := filepath.Join(ext.DataDir, "storage.json")
+	deadline := time.Now().Add(1500 * time.Millisecond)
+
+	var raw []byte
+	for time.Now().Before(deadline) {
+		data, err := os.ReadFile(storagePath)
+		if err == nil {
+			raw = data
+			break
+		}
+		time.Sleep(20 * time.Millisecond)
+	}
+	if len(raw) == 0 {
+		t.Fatalf("storage.json was not written within timeout")
+	}
+
+	var parsed map[string]interface{}
+	if err := json.Unmarshal(raw, &parsed); err != nil {
+		t.Fatalf("failed to unmarshal storage file: %v", err)
+	}
+	if parsed["k1"] != "v1" {
+		t.Fatalf("expected k1=v1, got %v", parsed["k1"])
+	}
+	if parsed["k2"] != float64(2) {
+		t.Fatalf("expected k2=2, got %v", parsed["k2"])
+	}
+	if bytes.Contains(raw, []byte("\n")) {
+		t.Fatalf("expected compact JSON without indentation, got: %q", string(raw))
+	}
+}
+
+func TestUnloadExtension_FlushesPendingStorage(t *testing.T) {
+	ext := &LoadedExtension{
+		ID: "unload-storage-test",
+		Manifest: &ExtensionManifest{
+			Name: "unload-storage-test",
+		},
+		DataDir: t.TempDir(),
+		VM:      goja.New(),
+	}
+
+	runtime := NewExtensionRuntime(ext)
+	runtime.storageFlushDelay = time.Hour
+	runtime.RegisterAPIs(ext.VM)
+	ext.runtime = runtime
+
+	manager := &ExtensionManager{
+		extensions: map[string]*LoadedExtension{
+			ext.ID: ext,
+		},
+	}
+
+	setStorageValue(t, runtime, "persist_on_unload", true)
+
+	if err := manager.UnloadExtension(ext.ID); err != nil {
+		t.Fatalf("UnloadExtension failed: %v", err)
+	}
+
+	storagePath := filepath.Join(ext.DataDir, "storage.json")
+	parsed := readStorageMap(t, storagePath)
+	if parsed["persist_on_unload"] != true {
+		t.Fatalf("expected pending storage value to be flushed on unload, got %v", parsed["persist_on_unload"])
+	}
+}

go_backend/extension_runtime_utils.go

@@ -1,4 +1,3 @@
-// Package gobackend provides Utility functions for extension runtime
 package gobackend
 
 import (
@@ -17,8 +16,6 @@ import (
 	"github.com/dop251/goja"
 )
 
-// ==================== Utility Functions ====================
-
 func (r *ExtensionRuntime) base64Encode(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue("")

go_backend/extension_settings.go

@@ -1,4 +1,3 @@
-// Package gobackend provides extension settings storage
 package gobackend
 
 import (

go_backend/extension_store.go

@@ -8,6 +8,7 @@ import (
 	"net/url"
 	"os"
 	"path/filepath"
+	"strings"
 	"sync"
 	"time"
 )
@@ -77,7 +78,6 @@ type StoreRegistry struct {
 	Extensions []StoreExtension `json:"extensions"`
 }
 
-// StoreExtensionResponse is the normalized response sent to Flutter
 type StoreExtensionResponse struct {
 	ID               string   `json:"id"`
 	Name             string   `json:"name"`
@@ -130,9 +130,8 @@ var (
 )
 
 const (
-	defaultRegistryURL = "https://raw.githubusercontent.com/zarzet/SpotiFLAC-Extension/main/registry.json"
-	cacheTTL           = 30 * time.Minute
-	cacheFileName      = "store_cache.json"
+	cacheTTL      = 30 * time.Minute
+	cacheFileName = "store_cache.json"
 )
 
 func InitExtensionStore(cacheDir string) *ExtensionStore {
@@ -141,7 +140,7 @@ func InitExtensionStore(cacheDir string) *ExtensionStore {
 
 	if extensionStore == nil {
 		extensionStore = &ExtensionStore{
-			registryURL: defaultRegistryURL,
+			registryURL: "", // No default - user must provide a registry URL
 			cacheDir:    cacheDir,
 			cacheTTL:    cacheTTL,
 		}
@@ -150,6 +149,36 @@ func InitExtensionStore(cacheDir string) *ExtensionStore {
 	return extensionStore
 }
 
+// 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()
+
+	if s.registryURL == registryURL {
+		return
+	}
+
+	s.registryURL = registryURL
+	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)
+	}
+
+	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()
+	return s.registryURL
+}
+
 func GetExtensionStore() *ExtensionStore {
 	extensionStoreMu.Lock()
 	defer extensionStoreMu.Unlock()
@@ -207,6 +236,11 @@ func (s *ExtensionStore) FetchRegistry(forceRefresh bool) (*StoreRegistry, error
 	s.cacheMu.Lock()
 	defer s.cacheMu.Unlock()
 
+	// Check if a registry URL has been configured
+	if s.registryURL == "" {
+		return nil, fmt.Errorf("no registry URL configured. Please add a repository URL first")
+	}
+
 	if !forceRefresh && s.cache != nil && time.Since(s.cacheTime) < s.cacheTTL {
 		LogDebug("ExtensionStore", "Using cached registry (%d extensions)", len(s.cache.Extensions))
 		return s.cache, nil
@@ -218,7 +252,7 @@ func (s *ExtensionStore) FetchRegistry(forceRefresh bool) (*StoreRegistry, error
 
 	LogInfo("ExtensionStore", "Fetching registry from %s", s.registryURL)
 
-	client := &http.Client{Timeout: 30 * time.Second}
+	client := NewHTTPClientWithTimeout(30 * time.Second)
 	resp, err := client.Get(s.registryURL)
 	if err != nil {
 		if s.cache != nil {
@@ -310,7 +344,7 @@ func (s *ExtensionStore) DownloadExtension(extensionID string, destPath string)
 
 	LogInfo("ExtensionStore", "Downloading %s from %s", ext.getDisplayName(), ext.getDownloadURL())
 
-	client := &http.Client{Timeout: 5 * time.Minute}
+	client := NewHTTPClientWithTimeout(5 * time.Minute)
 	resp, err := client.Get(ext.getDownloadURL())
 	if err != nil {
 		return fmt.Errorf("failed to download: %w", err)
@@ -337,6 +371,81 @@ 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
+	}
+
+	// Try to match https://github.com/<owner>/<repo>[/...]
+	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
+		}
+	}
+
+	path := input[len(ghPrefix):]
+	parts := strings.SplitN(path, "/", 3) // owner, repo, [rest]
+	if len(parts) < 2 || parts[0] == "" || parts[1] == "" {
+		return "", fmt.Errorf("invalid GitHub URL: expected github.com/<owner>/<repo>")
+	}
+	owner := parts[0]
+	repo := strings.TrimSuffix(parts[1], ".git")
+
+	branch := resolveGitHubDefaultBranch(owner, repo)
+
+	resolved := fmt.Sprintf("https://raw.githubusercontent.com/%s/%s/%s/registry.json", owner, repo, branch)
+	LogInfo("ExtensionStore", "Resolved %s → %s (branch: %s)", input, resolved, branch)
+	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)
+
+	resp, err := client.Get(apiURL)
+	if err != nil {
+		LogWarn("ExtensionStore", "GitHub API request failed for %s/%s: %v – falling back to main", owner, repo, err)
+		return "main"
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		LogWarn("ExtensionStore", "GitHub API returned %d for %s/%s – falling back to main", resp.StatusCode, owner, repo)
+		return "main"
+	}
+
+	var info struct {
+		DefaultBranch string `json:"default_branch"`
+	}
+	if err := json.NewDecoder(resp.Body).Decode(&info); err != nil || info.DefaultBranch == "" {
+		LogWarn("ExtensionStore", "Could not parse default_branch for %s/%s – falling back to main", owner, repo)
+		return "main"
+	}
+
+	return info.DefaultBranch
+}
+
 func requireHTTPSURL(rawURL string, context string) error {
 	if rawURL == "" {
 		return fmt.Errorf("%s URL is empty", context)
@@ -375,12 +484,10 @@ func (s *ExtensionStore) SearchExtensions(query string, category string) ([]Stor
 	queryLower := toLower(query)
 
 	for _, ext := range extensions {
-		// Filter by category
 		if category != "" && ext.Category != category {
 			continue
 		}
 
-		// Filter by query
 		if query != "" {
 			if !containsIgnoreCase(ext.Name, queryLower) &&
 				!containsIgnoreCase(ext.DisplayName, queryLower) &&
@@ -421,7 +528,6 @@ func (s *ExtensionStore) ClearCache() {
 	LogInfo("ExtensionStore", "Cache cleared")
 }
 
-// Helper: case-insensitive contains
 func containsIgnoreCase(s, substr string) bool {
 	return containsStr(toLower(s), substr)
 }

go_backend/extension_timeout.go

@@ -1,4 +1,3 @@
-// Package gobackend provides timeout execution for extension JS code
 package gobackend
 
 import (

go_backend/go.mod

@@ -2,7 +2,7 @@ module github.com/zarz/spotiflac_android/go_backend
 
 go 1.25.0
 
-toolchain go1.26.0
+toolchain go1.25.7
 
 require (
 	github.com/dop251/goja v0.0.0-20260216154549-8b74ce4618c5

go_backend/httputil.go

@@ -11,6 +11,7 @@ import (
 	"net/url"
 	"strconv"
 	"strings"
+	"sync"
 	"syscall"
 	"time"
 )
@@ -30,13 +31,23 @@ func getRandomUserAgent() string {
 
 const (
 	DefaultTimeout    = 60 * time.Second
-	DownloadTimeout   = 120 * time.Second
+	DownloadTimeout   = 24 * time.Hour
 	SongLinkTimeout   = 30 * time.Second
 	DefaultMaxRetries = 3
 	DefaultRetryDelay = 1 * time.Second
 	Second            = time.Second
 )
 
+type NetworkCompatibilityOptions struct {
+	AllowHTTP   bool
+	InsecureTLS bool
+}
+
+var (
+	networkCompatibilityMu      sync.RWMutex
+	networkCompatibilityOptions NetworkCompatibilityOptions
+)
+
 var sharedTransport = &http.Transport{
 	DialContext: (&net.Dialer{
 		Timeout:   30 * time.Second,
@@ -77,18 +88,18 @@ var metadataTransport = &http.Transport{
 }
 
 var sharedClient = &http.Client{
-	Transport: sharedTransport,
+	Transport: newCompatibilityTransport(sharedTransport),
 	Timeout:   DefaultTimeout,
 }
 
 var downloadClient = &http.Client{
-	Transport: sharedTransport,
+	Transport: newCompatibilityTransport(sharedTransport),
 	Timeout:   DownloadTimeout,
 }
 
 func NewHTTPClientWithTimeout(timeout time.Duration) *http.Client {
 	return &http.Client{
-		Transport: sharedTransport,
+		Transport: newCompatibilityTransport(sharedTransport),
 		Timeout:   timeout,
 	}
 }
@@ -97,7 +108,7 @@ func NewHTTPClientWithTimeout(timeout time.Duration) *http.Client {
 // Use this for API calls that should not be affected by download traffic.
 func NewMetadataHTTPClient(timeout time.Duration) *http.Client {
 	return &http.Client{
-		Transport: metadataTransport,
+		Transport: newCompatibilityTransport(metadataTransport),
 		Timeout:   timeout,
 	}
 }
@@ -115,6 +126,109 @@ func CloseIdleConnections() {
 	metadataTransport.CloseIdleConnections()
 }
 
+func SetNetworkCompatibilityOptions(allowHTTP, insecureTLS bool) {
+	networkCompatibilityMu.Lock()
+	networkCompatibilityOptions = NetworkCompatibilityOptions{
+		AllowHTTP:   allowHTTP,
+		InsecureTLS: insecureTLS,
+	}
+	networkCompatibilityMu.Unlock()
+
+	applyTLSCompatibility(sharedTransport, insecureTLS)
+	applyTLSCompatibility(metadataTransport, insecureTLS)
+	CloseIdleConnections()
+
+	GoLog("[HTTP] Network compatibility options updated: allow_http=%v insecure_tls=%v\n", allowHTTP, insecureTLS)
+}
+
+func GetNetworkCompatibilityOptions() NetworkCompatibilityOptions {
+	networkCompatibilityMu.RLock()
+	defer networkCompatibilityMu.RUnlock()
+	return networkCompatibilityOptions
+}
+
+func applyTLSCompatibility(transport *http.Transport, insecureTLS bool) {
+	if insecureTLS {
+		cfg := &tls.Config{InsecureSkipVerify: true}
+		if transport.TLSClientConfig != nil {
+			cfg = transport.TLSClientConfig.Clone()
+			cfg.InsecureSkipVerify = true
+		}
+		transport.TLSClientConfig = cfg
+		return
+	}
+
+	transport.TLSClientConfig = nil
+}
+
+type compatibilityTransport struct {
+	base http.RoundTripper
+}
+
+func newCompatibilityTransport(base http.RoundTripper) http.RoundTripper {
+	return &compatibilityTransport{base: base}
+}
+
+func (t *compatibilityTransport) RoundTrip(req *http.Request) (*http.Response, error) {
+	if req == nil || req.URL == nil {
+		return t.base.RoundTrip(req)
+	}
+
+	opts := GetNetworkCompatibilityOptions()
+	if !opts.AllowHTTP || req.URL.Scheme != "https" {
+		return t.base.RoundTrip(req)
+	}
+
+	// Compatibility mode should prefer HTTPS and only fallback to HTTP on
+	// transport-level failures. Forcing HTTP unconditionally can trigger
+	// redirect loops (http -> https) on providers that enforce HTTPS.
+	resp, err := t.base.RoundTrip(req)
+	if err == nil {
+		return resp, nil
+	}
+
+	if !canFallbackToHTTP(req) {
+		return nil, err
+	}
+
+	fallbackReq, cloneErr := cloneRequestWithHTTPScheme(req, "http")
+	if cloneErr != nil {
+		return nil, err
+	}
+
+	GoLog("[HTTP] HTTPS request failed for %s, retrying over HTTP: %v\n", req.URL.Host, err)
+	return t.base.RoundTrip(fallbackReq)
+}
+
+func canFallbackToHTTP(req *http.Request) bool {
+	if req == nil {
+		return false
+	}
+
+	switch strings.ToUpper(req.Method) {
+	case http.MethodGet, http.MethodHead, http.MethodOptions, http.MethodDelete:
+		return true
+	default:
+		return req.GetBody != nil
+	}
+}
+
+func cloneRequestWithHTTPScheme(req *http.Request, scheme string) (*http.Request, error) {
+	reqCopy := req.Clone(req.Context())
+	if req.Body != nil && req.GetBody != nil {
+		bodyCopy, err := req.GetBody()
+		if err != nil {
+			return nil, err
+		}
+		reqCopy.Body = bodyCopy
+	}
+
+	urlCopy := *req.URL
+	urlCopy.Scheme = scheme
+	reqCopy.URL = &urlCopy
+	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())
@@ -145,7 +259,6 @@ func DefaultRetryConfig() RetryConfig {
 func DoRequestWithRetry(client *http.Client, req *http.Request, config RetryConfig) (*http.Response, error) {
 	var lastErr error
 	delay := config.InitialDelay
-	requestURL := req.URL.String()
 
 	for attempt := 0; attempt <= config.MaxRetries; attempt++ {
 		reqCopy := req.Clone(req.Context())
@@ -155,8 +268,8 @@ func DoRequestWithRetry(client *http.Client, req *http.Request, config RetryConf
 		if err != nil {
 			lastErr = err
 
-			if CheckAndLogISPBlocking(err, requestURL, "HTTP") {
-				return nil, WrapErrorWithISPCheck(err, requestURL, "HTTP")
+			if CheckAndLogISPBlocking(err, reqCopy.URL.String(), "HTTP") {
+				return nil, WrapErrorWithISPCheck(err, reqCopy.URL.String(), "HTTP")
 			}
 
 			if attempt < config.MaxRetries {
@@ -233,11 +346,12 @@ func calculateNextDelay(currentDelay time.Duration, config RetryConfig) time.Dur
 	return min(nextDelay, config.MaxDelay)
 }
 
-// Returns 60 seconds as default if header is missing or invalid
+// Returns 0 if the header is missing or invalid so callers can keep their
+// normal exponential backoff instead of stalling for an arbitrary minute.
 func getRetryAfterDuration(resp *http.Response) time.Duration {
 	retryAfter := resp.Header.Get("Retry-After")
 	if retryAfter == "" {
-		return 60 * time.Second // Default wait time
+		return 0
 	}
 
 	if seconds, err := strconv.Atoi(retryAfter); err == nil {
@@ -251,7 +365,7 @@ func getRetryAfterDuration(resp *http.Response) time.Duration {
 		}
 	}
 
-	return 60 * time.Second // Default
+	return 0
 }
 
 func ReadResponseBody(resp *http.Response) ([]byte, error) {
@@ -376,7 +490,6 @@ func IsISPBlocking(err error, requestURL string) *ISPBlockingError {
 		}
 	}
 
-	// Check error message patterns for common ISP blocking indicators
 	blockingPatterns := []struct {
 		pattern string
 		reason  string
@@ -419,7 +532,6 @@ func CheckAndLogISPBlocking(err error, requestURL string, tag string) bool {
 	return false
 }
 
-// extractDomain extracts the domain from a URL string
 func extractDomain(rawURL string) string {
 	if rawURL == "" {
 		return "unknown"

go_backend/httputil_utls.go

@@ -91,7 +91,6 @@ func (t *utlsTransport) getPort(u *url.URL) string {
 	return "80"
 }
 
-// Cloudflare bypass client using uTLS Chrome fingerprint
 var cloudflareBypassTransport = newUTLSTransport()
 
 var cloudflareBypassClient = &http.Client{
@@ -111,7 +110,6 @@ func GetCloudflareBypassClient() *http.Client {
 func DoRequestWithCloudflareBypass(req *http.Request) (*http.Response, error) {
 	req.Header.Set("User-Agent", getRandomUserAgent())
 
-	// Try with standard client first
 	resp, err := sharedClient.Do(req)
 	if err == nil {
 		// Check for Cloudflare challenge page (403 with specific markers)
@@ -138,11 +136,9 @@ func DoRequestWithCloudflareBypass(req *http.Request) (*http.Response, error) {
 				if isCloudflare {
 					LogDebug("HTTP", "Cloudflare detected, retrying with Chrome TLS fingerprint...")
 
-					// Clone request for retry
 					reqCopy := req.Clone(req.Context())
 					reqCopy.Header.Set("User-Agent", getRandomUserAgent())
 
-					// Retry with uTLS Chrome fingerprint
 					return cloudflareBypassClient.Do(reqCopy)
 				}
 			}
@@ -168,11 +164,9 @@ func DoRequestWithCloudflareBypass(req *http.Request) (*http.Response, error) {
 	if tlsRelated {
 		LogDebug("HTTP", "TLS error detected, retrying with Chrome TLS fingerprint: %v", err)
 
-		// Clone request for retry
 		reqCopy := req.Clone(req.Context())
 		reqCopy.Header.Set("User-Agent", getRandomUserAgent())
 
-		// Retry with uTLS Chrome fingerprint
 		return cloudflareBypassClient.Do(reqCopy)
 	}
 

go_backend/idhs.go

@@ -22,13 +22,11 @@ var (
 	idhsRateLimiter  = NewRateLimiter(8, time.Minute) // 8 req/min (below 10 limit)
 )
 
-// IDHSSearchRequest represents the request body for IDHS API
 type IDHSSearchRequest struct {
 	Link     string   `json:"link"`
 	Adapters []string `json:"adapters,omitempty"`
 }
 
-// IDHSSearchResponse represents the response from IDHS API
 type IDHSSearchResponse struct {
 	ID            string     `json:"id"`
 	Type          string     `json:"type"` // song, album, artist, podcast, show
@@ -41,7 +39,6 @@ type IDHSSearchResponse struct {
 	Links         []IDHSLink `json:"links"`
 }
 
-// IDHSLink represents a link to a streaming platform
 type IDHSLink struct {
 	Type         string `json:"type"` // spotify, youTube, appleMusic, deezer, soundCloud, tidal
 	URL          string `json:"url"`
@@ -49,7 +46,6 @@ type IDHSLink struct {
 	NotAvailable bool   `json:"notAvailable,omitempty"`
 }
 
-// NewIDHSClient creates a new IDHS client
 func NewIDHSClient() *IDHSClient {
 	idhsClientOnce.Do(func() {
 		globalIDHSClient = &IDHSClient{
@@ -117,7 +113,6 @@ func (c *IDHSClient) Search(link string, adapters []string) (*IDHSSearchResponse
 func (c *IDHSClient) GetAvailabilityFromSpotify(spotifyTrackID string) (*TrackAvailability, error) {
 	spotifyURL := fmt.Sprintf("https://open.spotify.com/track/%s", spotifyTrackID)
 
-	// Request only the platforms we need
 	adapters := []string{"tidal", "deezer"}
 
 	result, err := c.Search(spotifyURL, adapters)
@@ -151,11 +146,9 @@ func (c *IDHSClient) GetAvailabilityFromSpotify(spotifyTrackID string) (*TrackAv
 	return availability, nil
 }
 
-// GetAvailabilityFromDeezer checks track availability using IDHS
 func (c *IDHSClient) GetAvailabilityFromDeezer(deezerTrackID string) (*TrackAvailability, error) {
 	deezerURL := fmt.Sprintf("https://www.deezer.com/track/%s", deezerTrackID)
 
-	// Request only the platforms we need
 	adapters := []string{"spotify", "tidal"}
 
 	result, err := c.Search(deezerURL, adapters)

go_backend/library_scan.go

@@ -1,16 +1,17 @@
 package gobackend
 
 import (
+	"bufio"
 	"encoding/json"
 	"fmt"
 	"os"
 	"path/filepath"
+	"strconv"
 	"strings"
 	"sync"
 	"time"
 )
 
-// LibraryScanResult represents metadata from a scanned audio file
 type LibraryScanResult struct {
 	ID          string `json:"id"`
 	TrackName   string `json:"trackName"`
@@ -42,7 +43,6 @@ type LibraryScanProgress struct {
 	IsComplete   bool    `json:"is_complete"`
 }
 
-// IncrementalScanResult contains results of an incremental library scan
 type IncrementalScanResult struct {
 	Scanned      []LibraryScanResult `json:"scanned"`      // New or updated files
 	DeletedPaths []string            `json:"deletedPaths"` // Files that no longer exist
@@ -65,6 +65,54 @@ var supportedAudioFormats = map[string]bool{
 	".mp3":  true,
 	".opus": true,
 	".ogg":  true,
+	".cue":  true,
+}
+
+type libraryAudioFileInfo struct {
+	path    string
+	modTime int64
+}
+
+type scannedCueFileInfo struct {
+	sheet     *CueSheet
+	audioPath string
+}
+
+func collectLibraryAudioFiles(folderPath string, cancelCh <-chan struct{}) ([]libraryAudioFileInfo, error) {
+	var files []libraryAudioFileInfo
+
+	err := filepath.Walk(folderPath, func(path string, info os.FileInfo, err error) error {
+		if err != nil {
+			return nil
+		}
+
+		select {
+		case <-cancelCh:
+			return fmt.Errorf("scan cancelled")
+		default:
+		}
+
+		if info.IsDir() {
+			return nil
+		}
+
+		ext := strings.ToLower(filepath.Ext(path))
+		if !supportedAudioFormats[ext] {
+			return nil
+		}
+
+		files = append(files, libraryAudioFileInfo{
+			path:    path,
+			modTime: info.ModTime().UnixMilli(),
+		})
+		return nil
+	})
+
+	if err != nil {
+		return nil, err
+	}
+
+	return files, nil
 }
 
 func SetLibraryCoverCacheDir(cacheDir string) {
@@ -98,32 +146,12 @@ func ScanLibraryFolder(folderPath string) (string, error) {
 	cancelCh := libraryScanCancel
 	libraryScanCancelMu.Unlock()
 
-	var audioFiles []string
-	err = filepath.Walk(folderPath, func(path string, info os.FileInfo, err error) error {
-		if err != nil {
-			return nil
-		}
-
-		select {
-		case <-cancelCh:
-			return fmt.Errorf("scan cancelled")
-		default:
-		}
-
-		if !info.IsDir() {
-			ext := strings.ToLower(filepath.Ext(path))
-			if supportedAudioFormats[ext] {
-				audioFiles = append(audioFiles, path)
-			}
-		}
-		return nil
-	})
-
+	audioFileInfos, err := collectLibraryAudioFiles(folderPath, cancelCh)
 	if err != nil {
 		return "[]", err
 	}
 
-	totalFiles := len(audioFiles)
+	totalFiles := len(audioFileInfos)
 	libraryScanProgressMu.Lock()
 	libraryScanProgress.TotalFiles = totalFiles
 	libraryScanProgressMu.Unlock()
@@ -141,7 +169,31 @@ func ScanLibraryFolder(folderPath string) (string, error) {
 	scanTime := time.Now().UTC().Format(time.RFC3339)
 	errorCount := 0
 
-	for i, filePath := range audioFiles {
+	// 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))
+		if ext == ".cue" {
+			sheet, err := ParseCueFile(filePath)
+			if err == nil && sheet.FileName != "" {
+				audioPath := ResolveCueAudioPath(filePath, sheet.FileName)
+				if audioPath != "" {
+					parsedCueFiles[filePath] = scannedCueFileInfo{
+						sheet:     sheet,
+						audioPath: audioPath,
+					}
+					cueReferencedAudioFiles[audioPath] = true
+				}
+			}
+		}
+	}
+
+	for i, fileInfo := range audioFileInfos {
+		filePath := fileInfo.path
 		select {
 		case <-cancelCh:
 			return "[]", fmt.Errorf("scan cancelled")
@@ -154,7 +206,42 @@ func ScanLibraryFolder(folderPath string) (string, error) {
 		libraryScanProgress.ProgressPct = float64(i+1) / float64(totalFiles) * 100
 		libraryScanProgressMu.Unlock()
 
-		result, err := scanAudioFile(filePath, scanTime)
+		ext := strings.ToLower(filepath.Ext(filePath))
+
+		// Handle .cue files: produce multiple track results
+		if ext == ".cue" {
+			var cueResults []LibraryScanResult
+			cueInfo, ok := parsedCueFiles[filePath]
+			if ok {
+				cueResults, err = scanCueSheetForLibrary(
+					filePath,
+					cueInfo.sheet,
+					cueInfo.audioPath,
+					"",
+					fileInfo.modTime,
+					scanTime,
+				)
+			} else {
+				cueResults, err = ScanCueFileForLibrary(filePath, scanTime)
+			}
+			if err != nil {
+				errorCount++
+				GoLog("[LibraryScan] Error scanning cue %s: %v\n", filePath, err)
+				continue
+			}
+			results = append(results, cueResults...)
+			GoLog("[LibraryScan] CUE sheet %s: %d tracks\n", filepath.Base(filePath), len(cueResults))
+			continue
+		}
+
+		// Skip audio files that are referenced by a .cue sheet
+		// (they will be represented by the cue sheet's track entries instead)
+		if cueReferencedAudioFiles[filePath] {
+			GoLog("[LibraryScan] Skipping %s (referenced by .cue sheet)\n", filepath.Base(filePath))
+			continue
+		}
+
+		result, err := scanAudioFileWithKnownModTime(filePath, scanTime, fileInfo.modTime)
 		if err != nil {
 			errorCount++
 			GoLog("[LibraryScan] Error scanning %s: %v\n", filePath, err)
@@ -180,7 +267,15 @@ func ScanLibraryFolder(folderPath string) (string, error) {
 }
 
 func scanAudioFile(filePath, scanTime string) (*LibraryScanResult, error) {
-	ext := strings.ToLower(filepath.Ext(filePath))
+	return scanAudioFileWithKnownModTimeAndDisplayName(filePath, "", scanTime, 0)
+}
+
+func scanAudioFileWithKnownModTime(filePath, scanTime string, knownModTime int64) (*LibraryScanResult, error) {
+	return scanAudioFileWithKnownModTimeAndDisplayName(filePath, "", scanTime, knownModTime)
+}
+
+func scanAudioFileWithKnownModTimeAndDisplayName(filePath, displayNameHint, scanTime string, knownModTime int64) (*LibraryScanResult, error) {
+	ext := resolveLibraryAudioExt(filePath, displayNameHint)
 
 	result := &LibraryScanResult{
 		ID:        generateLibraryID(filePath),
@@ -189,8 +284,9 @@ func scanAudioFile(filePath, scanTime string) (*LibraryScanResult, error) {
 		Format:    strings.TrimPrefix(ext, "."),
 	}
 
-	// Get file modification time
-	if info, err := os.Stat(filePath); err == nil {
+	if knownModTime > 0 {
+		result.FileModTime = knownModTime
+	} else if info, err := os.Stat(filePath); err == nil {
 		result.FileModTime = info.ModTime().UnixMilli()
 	}
 
@@ -198,7 +294,7 @@ func scanAudioFile(filePath, scanTime string) (*LibraryScanResult, error) {
 	coverCacheDir := libraryCoverCacheDir
 	libraryCoverCacheMu.RUnlock()
 	if coverCacheDir != "" && ext != ".m4a" {
-		coverPath, err := SaveCoverToCache(filePath, coverCacheDir)
+		coverPath, err := SaveCoverToCacheWithHint(filePath, displayNameHint, coverCacheDir)
 		if err == nil && coverPath != "" {
 			result.CoverPath = coverPath
 		}
@@ -212,16 +308,44 @@ func scanAudioFile(filePath, scanTime string) (*LibraryScanResult, error) {
 	case ".mp3":
 		return scanMP3File(filePath, result)
 	case ".opus", ".ogg":
-		return scanOggFile(filePath, result)
+		return scanOggFile(filePath, result, displayNameHint)
 	default:
-		return scanFromFilename(filePath, result)
+		return scanFromFilename(filePath, displayNameHint, result)
+	}
+}
+
+func resolveLibraryAudioExt(filePath, displayNameHint string) string {
+	ext := strings.ToLower(filepath.Ext(filePath))
+	if ext != "" {
+		return ext
+	}
+	return strings.ToLower(filepath.Ext(displayNameHint))
+}
+
+func libraryDisplayNameOrPath(filePath, displayNameHint string) string {
+	if displayNameHint != "" {
+		return displayNameHint
+	}
+	return filePath
+}
+
+func applyDefaultLibraryMetadata(filePath, displayNameHint string, result *LibraryScanResult) {
+	nameSource := libraryDisplayNameOrPath(filePath, displayNameHint)
+	if result.TrackName == "" {
+		result.TrackName = strings.TrimSuffix(filepath.Base(nameSource), filepath.Ext(nameSource))
+	}
+	if result.ArtistName == "" {
+		result.ArtistName = "Unknown Artist"
+	}
+	if result.AlbumName == "" {
+		result.AlbumName = "Unknown Album"
 	}
 }
 
 func scanFLACFile(filePath string, result *LibraryScanResult) (*LibraryScanResult, error) {
 	metadata, err := ReadMetadata(filePath)
 	if err != nil {
-		return scanFromFilename(filePath, result)
+		return scanFromFilename(filePath, "", result)
 	}
 
 	result.TrackName = metadata.Title
@@ -243,15 +367,7 @@ func scanFLACFile(filePath string, result *LibraryScanResult) (*LibraryScanResul
 		}
 	}
 
-	if result.TrackName == "" {
-		result.TrackName = strings.TrimSuffix(filepath.Base(filePath), filepath.Ext(filePath))
-	}
-	if result.ArtistName == "" {
-		result.ArtistName = "Unknown Artist"
-	}
-	if result.AlbumName == "" {
-		result.AlbumName = "Unknown Album"
-	}
+	applyDefaultLibraryMetadata(filePath, "", result)
 
 	return result, nil
 }
@@ -263,14 +379,14 @@ func scanM4AFile(filePath string, result *LibraryScanResult) (*LibraryScanResult
 		result.SampleRate = quality.SampleRate
 	}
 
-	return scanFromFilename(filePath, result)
+	return scanFromFilename(filePath, "", result)
 }
 
 func scanMP3File(filePath string, result *LibraryScanResult) (*LibraryScanResult, error) {
 	metadata, err := ReadID3Tags(filePath)
 	if err != nil {
 		GoLog("[LibraryScan] ID3 read error for %s: %v\n", filePath, err)
-		return scanFromFilename(filePath, result)
+		return scanFromFilename(filePath, "", result)
 	}
 
 	result.TrackName = metadata.Title
@@ -297,24 +413,16 @@ func scanMP3File(filePath string, result *LibraryScanResult) (*LibraryScanResult
 		}
 	}
 
-	if result.TrackName == "" {
-		result.TrackName = strings.TrimSuffix(filepath.Base(filePath), filepath.Ext(filePath))
-	}
-	if result.ArtistName == "" {
-		result.ArtistName = "Unknown Artist"
-	}
-	if result.AlbumName == "" {
-		result.AlbumName = "Unknown Album"
-	}
+	applyDefaultLibraryMetadata(filePath, "", result)
 
 	return result, nil
 }
 
-func scanOggFile(filePath string, result *LibraryScanResult) (*LibraryScanResult, error) {
+func scanOggFile(filePath string, result *LibraryScanResult, displayNameHint string) (*LibraryScanResult, error) {
 	metadata, err := ReadOggVorbisComments(filePath)
 	if err != nil {
 		GoLog("[LibraryScan] Ogg/Opus read error for %s: %v\n", filePath, err)
-		return scanFromFilename(filePath, result)
+		return scanFromFilename(filePath, displayNameHint, result)
 	}
 
 	result.TrackName = metadata.Title
@@ -337,21 +445,14 @@ func scanOggFile(filePath string, result *LibraryScanResult) (*LibraryScanResult
 		}
 	}
 
-	if result.TrackName == "" {
-		result.TrackName = strings.TrimSuffix(filepath.Base(filePath), filepath.Ext(filePath))
-	}
-	if result.ArtistName == "" {
-		result.ArtistName = "Unknown Artist"
-	}
-	if result.AlbumName == "" {
-		result.AlbumName = "Unknown Album"
-	}
+	applyDefaultLibraryMetadata(filePath, displayNameHint, result)
 
 	return result, nil
 }
 
-func scanFromFilename(filePath string, result *LibraryScanResult) (*LibraryScanResult, error) {
-	filename := strings.TrimSuffix(filepath.Base(filePath), filepath.Ext(filePath))
+func scanFromFilename(filePath, displayNameHint string, result *LibraryScanResult) (*LibraryScanResult, error) {
+	nameSource := libraryDisplayNameOrPath(filePath, displayNameHint)
+	filename := strings.TrimSuffix(filepath.Base(nameSource), filepath.Ext(nameSource))
 
 	parts := strings.SplitN(filename, " - ", 2)
 	if len(parts) == 2 {
@@ -374,7 +475,7 @@ func scanFromFilename(filePath string, result *LibraryScanResult) (*LibraryScanR
 
 	dir := filepath.Dir(filePath)
 	result.AlbumName = filepath.Base(dir)
-	if result.AlbumName == "." || result.AlbumName == "" {
+	if result.AlbumName == "." || result.AlbumName == "" || result.AlbumName == "fd" || result.AlbumName == "self" {
 		result.AlbumName = "Unknown Album"
 	}
 
@@ -421,8 +522,12 @@ func CancelLibraryScan() {
 }
 
 func ReadAudioMetadata(filePath string) (string, error) {
+	return ReadAudioMetadataWithDisplayName(filePath, "")
+}
+
+func ReadAudioMetadataWithDisplayName(filePath, displayNameHint string) (string, error) {
 	scanTime := time.Now().UTC().Format(time.RFC3339)
-	result, err := scanAudioFile(filePath, scanTime)
+	result, err := scanAudioFileWithKnownModTimeAndDisplayName(filePath, displayNameHint, scanTime, 0)
 	if err != nil {
 		return "", err
 	}
@@ -438,7 +543,43 @@ func ReadAudioMetadata(filePath string) (string, error) {
 // 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) {
+func loadExistingFilesSnapshot(snapshotPath string) (map[string]int64, error) {
+	existingFiles := make(map[string]int64)
+	if snapshotPath == "" {
+		return existingFiles, nil
+	}
+
+	file, err := os.Open(snapshotPath)
+	if err != nil {
+		return nil, err
+	}
+	defer file.Close()
+
+	scanner := bufio.NewScanner(file)
+	for scanner.Scan() {
+		line := scanner.Text()
+		if line == "" {
+			continue
+		}
+		parts := strings.SplitN(line, "\t", 2)
+		if len(parts) != 2 {
+			continue
+		}
+		modTime, err := strconv.ParseInt(parts[0], 10, 64)
+		if err != nil {
+			continue
+		}
+		existingFiles[parts[1]] = modTime
+	}
+
+	if err := scanner.Err(); err != nil {
+		return nil, err
+	}
+
+	return existingFiles, nil
+}
+
+func scanLibraryFolderIncrementalWithExistingFiles(folderPath string, existingFiles map[string]int64) (string, error) {
 	if folderPath == "" {
 		return "{}", fmt.Errorf("folder path is empty")
 	}
@@ -451,22 +592,12 @@ func ScanLibraryFolderIncremental(folderPath, existingFilesJSON string) (string,
 		return "{}", fmt.Errorf("path is not a folder: %s", folderPath)
 	}
 
-	// Parse existing files map
-	existingFiles := make(map[string]int64)
-	if existingFilesJSON != "" && existingFilesJSON != "{}" {
-		if err := json.Unmarshal([]byte(existingFilesJSON), &existingFiles); err != nil {
-			GoLog("[LibraryScan] Warning: failed to parse existing files JSON: %v\n", err)
-		}
-	}
-
 	GoLog("[LibraryScan] Incremental scan starting, %d existing files in database\n", len(existingFiles))
 
-	// Reset progress
 	libraryScanProgressMu.Lock()
 	libraryScanProgress = LibraryScanProgress{}
 	libraryScanProgressMu.Unlock()
 
-	// Setup cancellation
 	libraryScanCancelMu.Lock()
 	if libraryScanCancel != nil {
 		close(libraryScanCancel)
@@ -475,41 +606,14 @@ func ScanLibraryFolderIncremental(folderPath, existingFilesJSON string) (string,
 	cancelCh := libraryScanCancel
 	libraryScanCancelMu.Unlock()
 
-	// Collect all audio files with their mod times
-	type fileInfo struct {
-		path    string
-		modTime int64
-	}
-	var currentFiles []fileInfo
-	currentPathSet := make(map[string]bool)
-
-	err = filepath.Walk(folderPath, func(path string, info os.FileInfo, err error) error {
-		if err != nil {
-			return nil
-		}
-
-		select {
-		case <-cancelCh:
-			return fmt.Errorf("scan cancelled")
-		default:
-		}
-
-		if !info.IsDir() {
-			ext := strings.ToLower(filepath.Ext(path))
-			if supportedAudioFormats[ext] {
-				currentFiles = append(currentFiles, fileInfo{
-					path:    path,
-					modTime: info.ModTime().UnixMilli(),
-				})
-				currentPathSet[path] = true
-			}
-		}
-		return nil
-	})
-
+	currentFiles, err := collectLibraryAudioFiles(folderPath, cancelCh)
 	if err != nil {
 		return "{}", err
 	}
+	currentPathSet := make(map[string]bool, len(currentFiles))
+	for _, fileInfo := range currentFiles {
+		currentPathSet[fileInfo.path] = true
+	}
 
 	totalFiles := len(currentFiles)
 	libraryScanProgressMu.Lock()
@@ -517,27 +621,53 @@ func ScanLibraryFolderIncremental(folderPath, existingFilesJSON string) (string,
 	libraryScanProgressMu.Unlock()
 
 	// Find files to scan (new or modified)
-	var filesToScan []fileInfo
+	var filesToScan []libraryAudioFileInfo
 	skippedCount := 0
+	existingCueTrackModTimes := make(map[string]int64)
+	for existingPath, modTime := range existingFiles {
+		if idx := strings.LastIndex(existingPath, "#track"); idx > 0 {
+			baseCuePath := existingPath[:idx]
+			if _, exists := existingCueTrackModTimes[baseCuePath]; !exists {
+				existingCueTrackModTimes[baseCuePath] = modTime
+			}
+		}
+	}
 
 	for _, f := range currentFiles {
 		existingModTime, exists := existingFiles[f.path]
 		if !exists {
-			// New file
+			// For .cue files, also check if any virtual path entries exist
+			if strings.ToLower(filepath.Ext(f.path)) == ".cue" {
+				if cueTrackModTime, hasCueTracks := existingCueTrackModTimes[f.path]; hasCueTracks {
+					// CUE file exists in DB via virtual paths; check if modTime changed
+					if f.modTime == cueTrackModTime {
+						skippedCount++
+					} else {
+						filesToScan = append(filesToScan, f)
+					}
+					continue
+				}
+			}
 			filesToScan = append(filesToScan, f)
 		} else if f.modTime != existingModTime {
-			// Modified file
 			filesToScan = append(filesToScan, f)
 		} else {
-			// Unchanged file - skip
 			skippedCount++
 		}
 	}
 
-	// Find deleted files
 	var deletedPaths []string
 	for existingPath := range existingFiles {
-		if !currentPathSet[existingPath] {
+		// For CUE virtual paths (e.g. "/path/album.cue#track01"),
+		// check if the base .cue file still exists on disk
+		if idx := strings.LastIndex(existingPath, "#track"); idx > 0 {
+			baseCuePath := existingPath[:idx]
+			if currentPathSet[baseCuePath] {
+				continue // Base .cue file still exists, not deleted
+			}
+			// Base CUE file is gone, mark virtual path as deleted
+			deletedPaths = append(deletedPaths, existingPath)
+		} else if !currentPathSet[existingPath] {
 			deletedPaths = append(deletedPaths, existingPath)
 		}
 	}
@@ -562,11 +692,30 @@ func ScanLibraryFolderIncremental(folderPath, existingFilesJSON string) (string,
 		return string(jsonBytes), nil
 	}
 
-	// Scan the files that need scanning
 	results := make([]LibraryScanResult, 0, len(filesToScan))
 	scanTime := time.Now().UTC().Format(time.RFC3339)
 	errorCount := 0
 
+	// Track audio files referenced by .cue sheets to avoid duplicates (incremental)
+	cueReferencedAudioFilesInc := make(map[string]bool)
+	parsedCueFiles := make(map[string]scannedCueFileInfo)
+	for _, f := range filesToScan {
+		ext := strings.ToLower(filepath.Ext(f.path))
+		if ext == ".cue" {
+			sheet, err := ParseCueFile(f.path)
+			if err == nil && sheet.FileName != "" {
+				audioPath := ResolveCueAudioPath(f.path, sheet.FileName)
+				if audioPath != "" {
+					parsedCueFiles[f.path] = scannedCueFileInfo{
+						sheet:     sheet,
+						audioPath: audioPath,
+					}
+					cueReferencedAudioFilesInc[audioPath] = true
+				}
+			}
+		}
+	}
+
 	for i, f := range filesToScan {
 		select {
 		case <-cancelCh:
@@ -580,7 +729,39 @@ func ScanLibraryFolderIncremental(folderPath, existingFilesJSON string) (string,
 		libraryScanProgress.ProgressPct = float64(skippedCount+i+1) / float64(totalFiles) * 100
 		libraryScanProgressMu.Unlock()
 
-		result, err := scanAudioFile(f.path, scanTime)
+		ext := strings.ToLower(filepath.Ext(f.path))
+
+		// Handle .cue files: produce multiple track results
+		if ext == ".cue" {
+			var cueResults []LibraryScanResult
+			cueInfo, ok := parsedCueFiles[f.path]
+			if ok {
+				cueResults, err = scanCueSheetForLibrary(
+					f.path,
+					cueInfo.sheet,
+					cueInfo.audioPath,
+					"",
+					f.modTime,
+					scanTime,
+				)
+			} else {
+				cueResults, err = ScanCueFileForLibrary(f.path, scanTime)
+			}
+			if err != nil {
+				errorCount++
+				GoLog("[LibraryScan] Error scanning cue %s: %v\n", f.path, err)
+				continue
+			}
+			results = append(results, cueResults...)
+			continue
+		}
+
+		// Skip audio files referenced by .cue sheets
+		if cueReferencedAudioFilesInc[f.path] {
+			continue
+		}
+
+		result, err := scanAudioFileWithKnownModTime(f.path, scanTime, f.modTime)
 		if err != nil {
 			errorCount++
 			GoLog("[LibraryScan] Error scanning %s: %v\n", f.path, err)
@@ -614,3 +795,24 @@ func ScanLibraryFolderIncremental(folderPath, existingFilesJSON string) (string,
 
 	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 != "{}" {
+		if err := json.Unmarshal([]byte(existingFilesJSON), &existingFiles); err != nil {
+			GoLog("[LibraryScan] Warning: failed to parse existing files JSON: %v\n", err)
+		}
+	}
+	return scanLibraryFolderIncrementalWithExistingFiles(folderPath, existingFiles)
+}
+
+func ScanLibraryFolderIncrementalFromSnapshot(folderPath, snapshotPath string) (string, error) {
+	existingFiles, err := loadExistingFilesSnapshot(snapshotPath)
+	if err != nil {
+		return "{}", fmt.Errorf("failed to load incremental snapshot: %w", err)
+	}
+	return scanLibraryFolderIncrementalWithExistingFiles(folderPath, existingFiles)
+}

go_backend/lyrics.go

@@ -3,6 +3,7 @@ package gobackend
 import (
 	"encoding/json"
 	"fmt"
+	"io"
 	"math"
 	"net/http"
 	"net/url"
@@ -22,6 +23,7 @@ const (
 
 // Lyrics provider names (used in settings and cascade ordering)
 const (
+	LyricsProviderSpotifyAPI = "spotify_api"
 	LyricsProviderLRCLIB     = "lrclib"
 	LyricsProviderNetease    = "netease"
 	LyricsProviderMusixmatch = "musixmatch"
@@ -33,18 +35,23 @@ const (
 // LRCLIB first (no proxy dependency), then the others.
 var DefaultLyricsProviders = []string{
 	LyricsProviderLRCLIB,
+	LyricsProviderSpotifyAPI,
 	LyricsProviderMusixmatch,
 	LyricsProviderNetease,
 	LyricsProviderAppleMusic,
 	LyricsProviderQQMusic,
 }
 
-// Global lyrics provider configuration
 var (
 	lyricsProvidersMu sync.RWMutex
 	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"`
@@ -78,6 +85,7 @@ func SetLyricsProviderOrder(providers []string) {
 
 	// Validate provider names
 	validNames := map[string]bool{
+		LyricsProviderSpotifyAPI: true,
 		LyricsProviderLRCLIB:     true,
 		LyricsProviderNetease:    true,
 		LyricsProviderMusixmatch: true,
@@ -114,11 +122,12 @@ func GetLyricsProviderOrder() []string {
 // GetAvailableLyricsProviders returns metadata about all available providers.
 func GetAvailableLyricsProviders() []map[string]interface{} {
 	return []map[string]interface{}{
+		{"id": LyricsProviderSpotifyAPI, "name": "Spotify Lyrics API", "has_proxy_dependency": true, "description": "Spotify-sourced lyrics via Paxsenix"},
 		{"id": LyricsProviderLRCLIB, "name": "LRCLIB", "has_proxy_dependency": false, "description": "Open-source synced lyrics database"},
-		{"id": LyricsProviderNetease, "name": "Netease", "has_proxy_dependency": false, "description": "NetEase Cloud Music (good for Asian songs)"},
-		{"id": LyricsProviderMusixmatch, "name": "Musixmatch", "has_proxy_dependency": true, "description": "Largest lyrics database (multi-language)"},
-		{"id": LyricsProviderAppleMusic, "name": "Apple Music", "has_proxy_dependency": true, "description": "Word-by-word synced lyrics"},
-		{"id": LyricsProviderQQMusic, "name": "QQ Music", "has_proxy_dependency": true, "description": "QQ Music lyrics (good for Chinese songs)"},
+		{"id": LyricsProviderNetease, "name": "Netease", "has_proxy_dependency": true, "description": "NetEase Cloud Music lyrics via Paxsenix"},
+		{"id": LyricsProviderMusixmatch, "name": "Musixmatch", "has_proxy_dependency": true, "description": "Musixmatch lyrics via Paxsenix"},
+		{"id": LyricsProviderAppleMusic, "name": "Apple Music", "has_proxy_dependency": true, "description": "Apple Music synced lyrics via Paxsenix"},
+		{"id": LyricsProviderQQMusic, "name": "QQ Music", "has_proxy_dependency": true, "description": "QQ Music lyrics via Paxsenix"},
 	}
 }
 
@@ -245,6 +254,18 @@ 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"`
@@ -352,6 +373,214 @@ 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
@@ -411,7 +640,6 @@ func (c *LyricsClient) FetchLyricsAllSources(spotifyID, trackName, artistName st
 		return lyricsHasUsableText(l)
 	}
 
-	// Try extension lyrics providers first
 	if len(extensionProviders) > 0 {
 		for _, provider := range extensionProviders {
 			GoLog("[Lyrics] Trying extension lyrics provider: %s\n", provider.extension.ID)
@@ -434,7 +662,6 @@ func (c *LyricsClient) FetchLyricsAllSources(spotifyID, trackName, artistName st
 		return &cachedCopy, nil
 	}
 
-	// Get configured provider order
 	providerOrder := GetLyricsProviderOrder()
 	simplifiedTrack := simplifyTrackName(trackName)
 
@@ -448,6 +675,9 @@ 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)
 
@@ -651,6 +881,22 @@ func parseSyncedLyrics(syncedLyrics string) []LyricsLine {
 	return lines
 }
 
+func plainTextLyricsLines(rawLyrics string) []LyricsLine {
+	var lines []LyricsLine
+	for _, line := range strings.Split(rawLyrics, "\n") {
+		trimmed := strings.TrimSpace(line)
+		if trimmed == "" {
+			continue
+		}
+		lines = append(lines, LyricsLine{
+			StartTimeMs: 0,
+			Words:       trimmed,
+			EndTimeMs:   0,
+		})
+	}
+	return lines
+}
+
 func lyricsHasUsableText(lyrics *LyricsResponse) bool {
 	if lyrics == nil {
 		return false

go_backend/lyrics_apple.go

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

go_backend/lyrics_musixmatch.go

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

go_backend/lyrics_netease.go

@@ -9,13 +9,11 @@ import (
 	"time"
 )
 
-// NeteaseClient fetches lyrics from NetEase Cloud Music (music.163.com).
-// This is a direct public API — no proxy dependency.
+// NeteaseClient fetches lyrics through Paxsenix's NetEase endpoints.
 type NeteaseClient struct {
 	httpClient *http.Client
 }
 
-// Netease API response models
 type neteaseSearchResponse struct {
 	Result struct {
 		Songs []struct {
@@ -60,12 +58,9 @@ func (c *NeteaseClient) SearchSong(trackName, artistName string) (int64, error)
 		return 0, fmt.Errorf("empty search query")
 	}
 
-	searchURL := "http://music.163.com/api/search/pc"
+	searchURL := "https://lyrics.paxsenix.org/netease/search"
 	params := url.Values{}
-	params.Set("s", query)
-	params.Set("type", "1")
-	params.Set("limit", "1")
-	params.Set("offset", "0")
+	params.Set("q", query)
 
 	fullURL := searchURL + "?" + params.Encode()
 
@@ -103,12 +98,9 @@ func (c *NeteaseClient) SearchSong(trackName, artistName string) (int64, error)
 
 // FetchLyricsByID fetches synced lyrics for a given Netease song ID.
 func (c *NeteaseClient) FetchLyricsByID(songID int64, includeTranslation, includeRomanization bool) (string, error) {
-	lyricsURL := "http://music.163.com/api/song/lyric"
+	lyricsURL := "https://lyrics.paxsenix.org/netease/lyrics"
 	params := url.Values{}
 	params.Set("id", fmt.Sprintf("%d", songID))
-	params.Set("lv", "1")
-	params.Set("tv", "1")
-	params.Set("rv", "1")
 
 	fullURL := lyricsURL + "?" + params.Encode()
 
@@ -172,7 +164,6 @@ func (c *NeteaseClient) FetchLyrics(
 		return nil, err
 	}
 
-	// Parse the LRC text into LyricsResponse
 	lines := parseSyncedLyrics(lrcText)
 	if len(lines) == 0 {
 		// May be plain text lyrics without timestamps

go_backend/lyrics_qqmusic.go

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

go_backend/metadata.go

@@ -545,38 +545,215 @@ func ExtractLyrics(filePath string) (string, error) {
 	lower := strings.ToLower(filePath)
 
 	if strings.HasSuffix(lower, ".flac") {
-		return extractLyricsFromFlac(filePath)
+		lyrics, err := extractLyricsFromFlac(filePath)
+		if err == nil && strings.TrimSpace(lyrics) != "" {
+			return lyrics, nil
+		}
+		return extractLyricsFromSidecarLRC(filePath)
+	}
+
+	if strings.HasSuffix(lower, ".m4a") || strings.HasSuffix(lower, ".aac") {
+		lyrics, err := extractLyricsFromM4A(filePath)
+		if err == nil && strings.TrimSpace(lyrics) != "" {
+			return lyrics, nil
+		}
+		return extractLyricsFromSidecarLRC(filePath)
 	}
 
 	if strings.HasSuffix(lower, ".mp3") {
 		meta, err := ReadID3Tags(filePath)
-		if err != nil || meta == nil {
-			return "", fmt.Errorf("no lyrics found in file")
+		if err == nil && meta != nil {
+			if strings.TrimSpace(meta.Lyrics) != "" {
+				return meta.Lyrics, nil
+			}
+			if looksLikeEmbeddedLyrics(meta.Comment) {
+				return meta.Comment, nil
+			}
 		}
-		if strings.TrimSpace(meta.Lyrics) != "" {
-			return meta.Lyrics, nil
-		}
-		if looksLikeEmbeddedLyrics(meta.Comment) {
-			return meta.Comment, nil
-		}
-		return "", fmt.Errorf("no lyrics found in file")
+		return extractLyricsFromSidecarLRC(filePath)
 	}
 
 	if strings.HasSuffix(lower, ".opus") || strings.HasSuffix(lower, ".ogg") {
 		meta, err := ReadOggVorbisComments(filePath)
-		if err != nil || meta == nil {
-			return "", fmt.Errorf("no lyrics found in file")
-		}
-		if strings.TrimSpace(meta.Lyrics) != "" {
-			return meta.Lyrics, nil
-		}
-		if looksLikeEmbeddedLyrics(meta.Comment) {
-			return meta.Comment, nil
+		if err == nil && meta != nil {
+			if strings.TrimSpace(meta.Lyrics) != "" {
+				return meta.Lyrics, nil
+			}
+			if looksLikeEmbeddedLyrics(meta.Comment) {
+				return meta.Comment, nil
+			}
 		}
+		return extractLyricsFromSidecarLRC(filePath)
+	}
+
+	return extractLyricsFromSidecarLRC(filePath)
+}
+
+func extractLyricsFromM4A(filePath string) (string, error) {
+	f, err := os.Open(filePath)
+	if err != nil {
+		return "", err
+	}
+	defer f.Close()
+
+	fi, err := f.Stat()
+	if err != nil {
+		return "", err
+	}
+	fileSize := fi.Size()
+
+	moov, found, err := findAtomInRange(f, 0, fileSize, "moov", fileSize)
+	if err != nil || !found {
+		return "", fmt.Errorf("moov not found")
+	}
+
+	bodyStart := moov.offset + moov.headerSize
+	bodySize := moov.size - moov.headerSize
+
+	udta, found, err := findAtomInRange(f, bodyStart, bodySize, "udta", fileSize)
+	if err != nil || !found {
+		return "", fmt.Errorf("udta not found")
+	}
+
+	bodyStart = udta.offset + udta.headerSize
+	bodySize = udta.size - udta.headerSize
+
+	meta, found, err := findAtomInRange(f, bodyStart, bodySize, "meta", fileSize)
+	if err != nil || !found {
+		return "", fmt.Errorf("meta not found")
+	}
+
+	// meta atom has 4-byte version/flags after the header
+	bodyStart = meta.offset + meta.headerSize + 4
+	bodySize = meta.size - meta.headerSize - 4
+
+	ilst, found, err := findAtomInRange(f, bodyStart, bodySize, "ilst", fileSize)
+	if err != nil || !found {
+		return "", fmt.Errorf("ilst not found")
+	}
+
+	bodyStart = ilst.offset + ilst.headerSize
+	bodySize = ilst.size - ilst.headerSize
+
+	lyr, found, err := findAtomInRange(f, bodyStart, bodySize, "\xa9lyr", fileSize)
+	if err != nil || !found {
+		return "", fmt.Errorf("lyrics atom not found")
+	}
+
+	dataStart := lyr.offset + lyr.headerSize
+	dataSize := lyr.size - lyr.headerSize
+
+	dataAtom, found, err := findAtomInRange(f, dataStart, dataSize, "data", fileSize)
+	if err != nil || !found {
+		return "", fmt.Errorf("data atom not found in lyrics")
+	}
+
+	// data atom: 8 bytes header + 4 bytes type indicator + 4 bytes locale = skip 8
+	textStart := dataAtom.offset + dataAtom.headerSize + 8
+	textLen := dataAtom.size - dataAtom.headerSize - 8
+	if textLen <= 0 {
+		return "", fmt.Errorf("empty lyrics")
+	}
+
+	buf := make([]byte, textLen)
+	if _, err := f.ReadAt(buf, textStart); err != nil {
+		return "", err
+	}
+
+	return string(buf), nil
+}
+
+func extractCoverFromM4A(filePath string) ([]byte, error) {
+	f, err := os.Open(filePath)
+	if err != nil {
+		return nil, err
+	}
+	defer f.Close()
+
+	fi, err := f.Stat()
+	if err != nil {
+		return nil, err
+	}
+	fileSize := fi.Size()
+
+	moov, found, err := findAtomInRange(f, 0, fileSize, "moov", fileSize)
+	if err != nil || !found {
+		return nil, fmt.Errorf("moov not found")
+	}
+
+	bodyStart := moov.offset + moov.headerSize
+	bodySize := moov.size - moov.headerSize
+
+	udta, found, err := findAtomInRange(f, bodyStart, bodySize, "udta", fileSize)
+	if err != nil || !found {
+		return nil, fmt.Errorf("udta not found")
+	}
+
+	bodyStart = udta.offset + udta.headerSize
+	bodySize = udta.size - udta.headerSize
+
+	meta, found, err := findAtomInRange(f, bodyStart, bodySize, "meta", fileSize)
+	if err != nil || !found {
+		return nil, fmt.Errorf("meta not found")
+	}
+
+	bodyStart = meta.offset + meta.headerSize + 4
+	bodySize = meta.size - meta.headerSize - 4
+
+	ilst, found, err := findAtomInRange(f, bodyStart, bodySize, "ilst", fileSize)
+	if err != nil || !found {
+		return nil, fmt.Errorf("ilst not found")
+	}
+
+	bodyStart = ilst.offset + ilst.headerSize
+	bodySize = ilst.size - ilst.headerSize
+
+	covr, found, err := findAtomInRange(f, bodyStart, bodySize, "covr", fileSize)
+	if err != nil || !found {
+		return nil, fmt.Errorf("cover atom not found")
+	}
+
+	dataStart := covr.offset + covr.headerSize
+	dataSize := covr.size - covr.headerSize
+
+	dataAtom, found, err := findAtomInRange(f, dataStart, dataSize, "data", fileSize)
+	if err != nil || !found {
+		return nil, fmt.Errorf("data atom not found in cover")
+	}
+
+	// data atom: header + 4 bytes type indicator + 4 bytes locale
+	imgStart := dataAtom.offset + dataAtom.headerSize + 8
+	imgLen := dataAtom.size - dataAtom.headerSize - 8
+	if imgLen <= 0 {
+		return nil, fmt.Errorf("empty cover data")
+	}
+
+	buf := make([]byte, imgLen)
+	if _, err := f.ReadAt(buf, imgStart); err != nil {
+		return nil, err
+	}
+
+	return buf, nil
+}
+
+func extractLyricsFromSidecarLRC(filePath string) (string, error) {
+	ext := filepath.Ext(filePath)
+	base := strings.TrimSuffix(filePath, ext)
+	if strings.TrimSpace(base) == "" {
 		return "", fmt.Errorf("no lyrics found in file")
 	}
 
-	return "", fmt.Errorf("unsupported file format for lyrics extraction")
+	lrcPath := base + ".lrc"
+	data, err := os.ReadFile(lrcPath)
+	if err != nil {
+		return "", fmt.Errorf("no lyrics found in file")
+	}
+
+	lyrics := strings.TrimSpace(string(data))
+	if lyrics == "" {
+		return "", fmt.Errorf("no lyrics found in file")
+	}
+	return lyrics, nil
 }
 
 func extractLyricsFromFlac(filePath string) (string, error) {
@@ -721,15 +898,28 @@ func GetM4AQuality(filePath string) (AudioQuality, error) {
 		return AudioQuality{}, err
 	}
 
-	buf := make([]byte, 24)
+	buf := make([]byte, 32)
 	if _, err := f.ReadAt(buf, sampleOffset); err != nil {
 		return AudioQuality{}, fmt.Errorf("failed to read audio sample entry: %w", err)
 	}
 
-	sampleRate := int(buf[22])<<8 | int(buf[23])
-	bitDepth := 16
-	if atomType == "alac" {
-		bitDepth = 24
+	// AudioSampleEntry layout from the box type field:
+	//   [0:4]   type ("mp4a"/"alac")
+	//   [4:10]  SampleEntry.reserved
+	//   [10:12] data_reference_index
+	//   [12:20] reserved[8]
+	//   [20:22] channelcount
+	//   [22:24] samplesize (bit depth)
+	//   [24:26] pre_defined
+	//   [26:28] reserved
+	//   [28:32] samplerate (16.16 fixed-point)
+	sampleRate := int(buf[28])<<8 | int(buf[29])
+	bitDepth := int(buf[22])<<8 | int(buf[23])
+	if bitDepth <= 0 {
+		bitDepth = 16
+		if atomType == "alac" {
+			bitDepth = 24
+		}
 	}
 
 	return AudioQuality{BitDepth: bitDepth, SampleRate: sampleRate}, nil
@@ -852,7 +1042,7 @@ func findAudioSampleEntry(f *os.File, start, end, fileSize int64) (int64, string
 
 		if bestIdx >= 0 {
 			absolute := readPos - int64(len(tail)) + int64(bestIdx)
-			if absolute+24 > fileSize {
+			if absolute+32 > fileSize {
 				return 0, "", fmt.Errorf("audio info not found in M4A file")
 			}
 			return absolute, bestType, nil

go_backend/mobile_deps.go

@@ -1,10 +1,8 @@
-// mobile_deps.go
 // This file ensures gomobile dependencies are not removed by go mod tidy.
 // These packages are required by gomobile bind but not directly imported in code.
 
 package gobackend
 
 import (
-	// Required for gomobile bind to work
 	_ "golang.org/x/mobile/bind"
 )

go_backend/output_fd.go

@@ -12,11 +12,68 @@ func isFDOutput(outputFD int) bool {
 
 func openOutputForWrite(outputPath string, outputFD int) (*os.File, error) {
 	if isFDOutput(outputFD) {
-		return os.NewFile(uintptr(outputFD), fmt.Sprintf("saf_fd_%d", outputFD)), nil
+		// Never hand the original detached FD directly to a provider attempt.
+		// Fallback chains may retry with another provider after a failure.
+		// If the first attempt closes the original FD, its numeric ID can be
+		// reused by unrelated resources and a later close may trigger fdsan abort.
+		dupFD, err := dupOutputFD(outputFD)
+		if err != nil {
+			return nil, fmt.Errorf("failed to duplicate output fd %d: %w", outputFD, err)
+		}
+		if err := prepareDupFDForWrite(dupFD, outputFD); err != nil {
+			_ = closeFD(dupFD)
+			return nil, err
+		}
+		return os.NewFile(uintptr(dupFD), fmt.Sprintf("saf_fd_%d_dup_%d", outputFD, dupFD)), nil
 	}
+
+	path := strings.TrimSpace(outputPath)
+	if strings.HasPrefix(path, "/proc/self/fd/") {
+		// Re-open procfs fd path instead of taking ownership of raw detached fd.
+		// Some SAF providers reject O_TRUNC on these descriptors with EACCES/EPERM.
+		file, err := os.OpenFile(path, os.O_WRONLY|os.O_TRUNC, 0)
+		if err == nil {
+			return file, nil
+		}
+		if strings.Contains(strings.ToLower(err.Error()), "permission denied") {
+			return os.OpenFile(path, os.O_WRONLY, 0)
+		}
+		return nil, err
+	}
+
 	return os.Create(outputPath)
 }
 
+func prepareDupFDForWrite(dupFD, originalFD int) error {
+	// Best-effort reset so retries start writing from byte 0.
+	if err := truncateFD(dupFD); err != nil {
+		if isBestEffortTruncateError(err) {
+			GoLog("[OutputFD] truncate not supported on fd %d (dup of %d): %v\n", dupFD, originalFD, err)
+		} else {
+			return fmt.Errorf("failed to truncate output fd %d (dup of %d): %w", dupFD, originalFD, err)
+		}
+	}
+	if err := seekFDStart(dupFD); err != nil {
+		GoLog("[OutputFD] seek reset failed on fd %d (dup of %d): %v\n", dupFD, originalFD, err)
+	}
+	return nil
+}
+
+func closeOwnedOutputFD(outputFD int) {
+	if !isFDOutput(outputFD) {
+		return
+	}
+
+	if err := closeFD(outputFD); err != nil {
+		if !isBadFD(err) {
+			GoLog("[OutputFD] failed to close detached fd %d: %v\n", outputFD, err)
+		}
+		return
+	}
+
+	GoLog("[OutputFD] closed detached fd %d\n", outputFD)
+}
+
 func cleanupOutputOnError(outputPath string, outputFD int) {
 	if isFDOutput(outputFD) {
 		return

go_backend/output_fd_unix.go

@@ -0,0 +1,35 @@
+//go:build !windows
+
+package gobackend
+
+import "syscall"
+
+func dupOutputFD(fd int) (int, error) {
+	return syscall.Dup(fd)
+}
+
+func truncateFD(fd int) error {
+	return syscall.Ftruncate(fd, 0)
+}
+
+func seekFDStart(fd int) error {
+	_, err := syscall.Seek(fd, 0, 0)
+	return err
+}
+
+func closeFD(fd int) error {
+	return syscall.Close(fd)
+}
+
+func isBestEffortTruncateError(err error) bool {
+	switch err {
+	case syscall.EPERM, syscall.EACCES, syscall.EINVAL, syscall.ESPIPE, syscall.ENOSYS:
+		return true
+	default:
+		return false
+	}
+}
+
+func isBadFD(err error) bool {
+	return err == syscall.EBADF
+}

go_backend/output_fd_windows.go

@@ -0,0 +1,29 @@
+//go:build windows
+
+package gobackend
+
+func dupOutputFD(fd int) (int, error) {
+	// Windows build is primarily for local tooling/tests.
+	// Android runtime uses the !windows implementation.
+	return fd, nil
+}
+
+func truncateFD(fd int) error {
+	return nil
+}
+
+func seekFDStart(fd int) error {
+	return nil
+}
+
+func closeFD(fd int) error {
+	return nil
+}
+
+func isBestEffortTruncateError(err error) bool {
+	return true
+}
+
+func isBadFD(err error) bool {
+	return false
+}

go_backend/parallel.go

@@ -10,7 +10,6 @@ import (
 type TrackIDCacheEntry struct {
 	TidalTrackID  int64
 	QobuzTrackID  int64
-	AmazonURL     string
 	ExpiresAt     time.Time
 }
 
@@ -107,25 +106,6 @@ func (c *TrackIDCache) SetQobuz(isrc string, trackID int64) {
 	}
 }
 
-func (c *TrackIDCache) SetAmazonURL(isrc string, amazonURL string) {
-	c.mu.Lock()
-	defer c.mu.Unlock()
-
-	entry, exists := c.cache[isrc]
-	if !exists {
-		entry = &TrackIDCacheEntry{}
-		c.cache[isrc] = entry
-	}
-	entry.AmazonURL = amazonURL
-	now := time.Now()
-	entry.ExpiresAt = now.Add(c.ttl)
-
-	if c.cleanupInterval > 0 && (c.lastCleanup.IsZero() || now.Sub(c.lastCleanup) >= c.cleanupInterval) {
-		c.pruneExpiredLocked(now)
-		c.lastCleanup = now
-	}
-}
-
 func (c *TrackIDCache) Clear() {
 	c.mu.Lock()
 	defer c.mu.Unlock()
@@ -235,8 +215,6 @@ func PreWarmTrackCache(requests []PreWarmCacheRequest) {
 				preWarmTidalCache(r.ISRC, r.TrackName, r.ArtistName)
 			case "qobuz":
 				preWarmQobuzCache(r.ISRC, r.SpotifyID)
-			case "amazon":
-				preWarmAmazonCache(r.ISRC, r.SpotifyID)
 			}
 		}(req)
 	}
@@ -256,12 +234,10 @@ func preWarmTidalCache(isrc, _, _ string) {
 // 1. From SongLink (fast, no Qobuz API call needed)
 // 2. Direct ISRC search on Qobuz API (slower, may fail if ISRC not in Qobuz database)
 func preWarmQobuzCache(isrc, spotifyID string) {
-	// First, try to get QobuzID from SongLink - this is faster and more reliable
 	if spotifyID != "" {
 		client := NewSongLinkClient()
 		availability, err := client.CheckTrackAvailability(spotifyID, isrc)
 		if err == nil && availability != nil && availability.QobuzID != "" {
-			// Parse QobuzID to int64
 			var trackID int64
 			if _, parseErr := fmt.Sscanf(availability.QobuzID, "%d", &trackID); parseErr == nil && trackID > 0 {
 				GoLog("[Qobuz] Pre-warm cache: Got Qobuz ID %d from SongLink for ISRC %s\n", trackID, isrc)
@@ -271,7 +247,6 @@ func preWarmQobuzCache(isrc, spotifyID string) {
 		}
 	}
 
-	// Fallback: Direct ISRC search on Qobuz API
 	downloader := NewQobuzDownloader()
 	track, err := downloader.SearchTrackByISRC(isrc)
 	if err == nil && track != nil {
@@ -280,14 +255,6 @@ func preWarmQobuzCache(isrc, spotifyID string) {
 	}
 }
 
-func preWarmAmazonCache(isrc, spotifyID string) {
-	client := NewSongLinkClient()
-	availability, err := client.CheckTrackAvailability(spotifyID, isrc)
-	if err == nil && availability != nil && availability.AmazonURL != "" {
-		GetTrackIDCache().SetAmazonURL(isrc, availability.AmazonURL)
-	}
-}
-
 func PreWarmCache(tracksJSON string) error {
 	var tracks []struct {
 		ISRC       string `json:"isrc"`

go_backend/progress.go

@@ -34,10 +34,16 @@ var (
 	downloadDir   string
 	downloadDirMu sync.RWMutex
 
-	multiProgress = MultiProgress{Items: make(map[string]*ItemProgress)}
-	multiMu       sync.RWMutex
+	multiProgress       = MultiProgress{Items: make(map[string]*ItemProgress)}
+	multiMu             sync.RWMutex
+	multiProgressDirty  = true
+	cachedMultiProgress = "{\"items\":{}}"
 )
 
+func markMultiProgressDirtyLocked() {
+	multiProgressDirty = true
+}
+
 func getProgress() DownloadProgress {
 	multiMu.RLock()
 	defer multiMu.RUnlock()
@@ -58,13 +64,25 @@ func getProgress() DownloadProgress {
 
 func GetMultiProgress() string {
 	multiMu.RLock()
-	defer multiMu.RUnlock()
+	if !multiProgressDirty {
+		cached := cachedMultiProgress
+		multiMu.RUnlock()
+		return cached
+	}
+	multiMu.RUnlock()
 
+	multiMu.Lock()
+	defer multiMu.Unlock()
+	if !multiProgressDirty {
+		return cachedMultiProgress
+	}
 	jsonBytes, err := json.Marshal(multiProgress)
 	if err != nil {
 		return "{\"items\":{}}"
 	}
-	return string(jsonBytes)
+	cachedMultiProgress = string(jsonBytes)
+	multiProgressDirty = false
+	return cachedMultiProgress
 }
 
 func GetItemProgress(itemID string) string {
@@ -90,6 +108,7 @@ func StartItemProgress(itemID string) {
 		IsDownloading: true,
 		Status:        "downloading",
 	}
+	markMultiProgressDirtyLocked()
 }
 
 func SetItemBytesTotal(itemID string, total int64) {
@@ -98,6 +117,7 @@ func SetItemBytesTotal(itemID string, total int64) {
 
 	if item, ok := multiProgress.Items[itemID]; ok {
 		item.BytesTotal = total
+		markMultiProgressDirtyLocked()
 	}
 }
 
@@ -110,6 +130,7 @@ func SetItemBytesReceived(itemID string, received int64) {
 		if item.BytesTotal > 0 {
 			item.Progress = float64(received) / float64(item.BytesTotal)
 		}
+		markMultiProgressDirtyLocked()
 	}
 }
 
@@ -123,6 +144,7 @@ func SetItemBytesReceivedWithSpeed(itemID string, received int64, speedMBps floa
 		if item.BytesTotal > 0 {
 			item.Progress = float64(received) / float64(item.BytesTotal)
 		}
+		markMultiProgressDirtyLocked()
 	}
 }
 
@@ -134,6 +156,7 @@ func CompleteItemProgress(itemID string) {
 		item.Progress = 1.0
 		item.IsDownloading = false
 		item.Status = "completed"
+		markMultiProgressDirtyLocked()
 	}
 }
 
@@ -149,6 +172,7 @@ func SetItemProgress(itemID string, progress float64, bytesReceived, bytesTotal
 		if bytesTotal > 0 {
 			item.BytesTotal = bytesTotal
 		}
+		markMultiProgressDirtyLocked()
 	}
 }
 
@@ -159,6 +183,7 @@ func SetItemFinalizing(itemID string) {
 	if item, ok := multiProgress.Items[itemID]; ok {
 		item.Progress = 1.0
 		item.Status = "finalizing"
+		markMultiProgressDirtyLocked()
 	}
 }
 
@@ -167,6 +192,7 @@ func RemoveItemProgress(itemID string) {
 	defer multiMu.Unlock()
 
 	delete(multiProgress.Items, itemID)
+	markMultiProgressDirtyLocked()
 }
 
 func ClearAllItemProgress() {
@@ -174,6 +200,7 @@ func ClearAllItemProgress() {
 	defer multiMu.Unlock()
 
 	multiProgress.Items = make(map[string]*ItemProgress)
+	markMultiProgressDirtyLocked()
 }
 
 func setDownloadDir(path string) error {

go_backend/qobuz_test.go

@@ -1,8 +1,118 @@
 package gobackend
 
-import "testing"
+import (
+	"encoding/json"
+	"testing"
+)
+
+func TestParseQobuzURL(t *testing.T) {
+	tests := []struct {
+		name      string
+		input     string
+		wantType  string
+		wantID    string
+		expectErr bool
+	}{
+		{
+			name:     "store album url",
+			input:    "https://www.qobuz.com/us-en/album/harry-styles-harry-styles/0886446451985",
+			wantType: "album",
+			wantID:   "0886446451985",
+		},
+		{
+			name:     "store playlist url",
+			input:    "https://www.qobuz.com/us-en/playlists/new-releases/2049430",
+			wantType: "playlist",
+			wantID:   "2049430",
+		},
+		{
+			name:     "store artist url",
+			input:    "https://www.qobuz.com/us-en/interpreter/harry-styles/729886",
+			wantType: "artist",
+			wantID:   "729886",
+		},
+		{
+			name:     "play track url",
+			input:    "https://play.qobuz.com/track/40681594",
+			wantType: "track",
+			wantID:   "40681594",
+		},
+		{
+			name:     "custom scheme playlist url",
+			input:    "qobuzapp://playlist/2049430",
+			wantType: "playlist",
+			wantID:   "2049430",
+		},
+		{
+			name:      "unsupported url",
+			input:     "https://example.com/not-qobuz",
+			expectErr: true,
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			gotType, gotID, err := parseQobuzURL(test.input)
+			if test.expectErr {
+				if err == nil {
+					t.Fatalf("expected error, got none")
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("expected no error, got %v", err)
+			}
+			if gotType != test.wantType || gotID != test.wantID {
+				t.Fatalf("parseQobuzURL(%q) = (%q, %q), want (%q, %q)", test.input, gotType, gotID, test.wantType, test.wantID)
+			}
+		})
+	}
+}
+
+func TestExtractQobuzArtistAlbumIDs(t *testing.T) {
+	body := []byte(`
+<div class="product__item">
+  <button data-itemtype="album" data-itemId="yrpbt0lwm3g0y"></button>
+</div>
+<div class="product__item">
+  <button data-itemtype="album" data-itemId="yrpbt0lwm3g0y"></button>
+</div>
+<div class="product__item">
+  <button data-itemtype="album" data-itemId="0886446451985"></button>
+</div>
+`)
+
+	matches := qobuzArtistAlbumIDRegex.FindAllSubmatch(body, -1)
+	if len(matches) != 3 {
+		t.Fatalf("expected 3 regex matches, got %d", len(matches))
+	}
+	if string(matches[0][1]) != "yrpbt0lwm3g0y" {
+		t.Fatalf("unexpected first album id: %q", matches[0][1])
+	}
+	if string(matches[2][1]) != "0886446451985" {
+		t.Fatalf("unexpected last album id: %q", matches[2][1])
+	}
+}
 
 func TestExtractQobuzDownloadURLFromBody(t *testing.T) {
+	t.Run("reads top-level download_url and quality metadata", func(t *testing.T) {
+		body := []byte(`{"success":true,"download_url":"https://example.test/new.flac","bit_depth":24,"sampling_rate":96}`)
+
+		info, err := extractQobuzDownloadInfoFromBody(body)
+		if err != nil {
+			t.Fatalf("expected no error, got %v", err)
+		}
+		if info.DownloadURL != "https://example.test/new.flac" {
+			t.Fatalf("unexpected URL: %q", info.DownloadURL)
+		}
+		if info.BitDepth != 24 {
+			t.Fatalf("unexpected bit depth: %d", info.BitDepth)
+		}
+		if info.SampleRate != 96000 {
+			t.Fatalf("unexpected sample rate: %d", info.SampleRate)
+		}
+	})
+
 	t.Run("reads nested data.url", func(t *testing.T) {
 		body := []byte(`{"success":true,"data":{"url":"https://example.test/audio.flac"}}`)
 
@@ -44,4 +154,285 @@ func TestExtractQobuzDownloadURLFromBody(t *testing.T) {
 			t.Fatalf("expected blocked error, got %v", err)
 		}
 	})
+
+	t.Run("returns detail error", func(t *testing.T) {
+		body := []byte(`{"detail":"Invalid quality 'lossless'. Choose from: ['mp3', 'cd', 'hi-res', 'hi-res-max']"}`)
+
+		_, err := extractQobuzDownloadURLFromBody(body)
+		if err == nil || err.Error() != "Invalid quality 'lossless'. Choose from: ['mp3', 'cd', 'hi-res', 'hi-res-max']" {
+			t.Fatalf("expected detail error, got %v", err)
+		}
+	})
+}
+
+func TestNormalizeQobuzQualityCode(t *testing.T) {
+	tests := map[string]string{
+		"":           "6",
+		"5":          "6",
+		"6":          "6",
+		"cd":         "6",
+		"lossless":   "6",
+		"7":          "7",
+		"hi-res":     "7",
+		"27":         "27",
+		"hi-res-max": "27",
+		"unexpected": "6",
+	}
+
+	for input, want := range tests {
+		if got := normalizeQobuzQualityCode(input); got != want {
+			t.Fatalf("normalizeQobuzQualityCode(%q) = %q, want %q", input, got, want)
+		}
+	}
+}
+
+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 {
+		t.Fatalf("buildQobuzMusicDLPayload returned error: %v", err)
+	}
+
+	var payload map[string]any
+	if err := json.Unmarshal(payloadBytes, &payload); err != nil {
+		t.Fatalf("payload is not valid JSON: %v", err)
+	}
+
+	if got := payload["url"]; got != "https://open.qobuz.com/track/374610875" {
+		t.Fatalf("payload url = %v, want open.qobuz.com track URL", got)
+	}
+	if got := payload["quality"]; got != "hi-res" {
+		t.Fatalf("payload quality = %v, want hi-res", got)
+	}
+	if got := payload["upload_to_r2"]; got != false {
+		t.Fatalf("payload upload_to_r2 = %v, want false", got)
+	}
+}
+
+func TestExtractQobuzAlbumIDsFromArtistHTML(t *testing.T) {
+	body := []byte(`
+		<button data-itemtype="album" data-itemId="0886446451985"></button>
+		<button data-itemtype="album" data-itemId="0886446451985"></button>
+		<button data-itemtype="album" data-itemId="pvv406bth40ya"></button>
+	`)
+
+	got := extractQobuzAlbumIDsFromArtistHTML(body)
+	if len(got) != 2 {
+		t.Fatalf("expected 2 unique album IDs, got %d (%v)", len(got), got)
+	}
+	if got[0] != "0886446451985" || got[1] != "pvv406bth40ya" {
+		t.Fatalf("unexpected album IDs: %v", got)
+	}
+}
+
+func TestQobuzAvailableProviders(t *testing.T) {
+	providers := NewQobuzDownloader().GetAvailableProviders()
+	if len(providers) != 5 {
+		t.Fatalf("expected 5 Qobuz providers, got %d", len(providers))
+	}
+
+	want := map[string]string{
+		"musicdl":  qobuzAPIKindMusicDL,
+		"dabmusic": qobuzAPIKindStandard,
+		"deeb":     qobuzAPIKindStandard,
+		"qbz":      qobuzAPIKindStandard,
+		"squid":    qobuzAPIKindStandard,
+	}
+
+	for _, provider := range providers {
+		wantKind, ok := want[provider.Name]
+		if !ok {
+			t.Fatalf("unexpected provider %q", provider.Name)
+		}
+		if provider.Kind != wantKind {
+			t.Fatalf("provider %q has kind %q, want %q", provider.Name, provider.Kind, wantKind)
+		}
+		delete(want, provider.Name)
+	}
+
+	if len(want) != 0 {
+		t.Fatalf("missing providers: %v", want)
+	}
+}
+
+func testQobuzTrack(id int64, title, artist string, duration int) *QobuzTrack {
+	track := &QobuzTrack{
+		ID:       id,
+		Title:    title,
+		Duration: duration,
+	}
+	track.Performer.Name = artist
+	return track
+}
+
+func TestResolveQobuzTrackForRequestRejectsSongLinkMismatch(t *testing.T) {
+	origGetTrackByID := qobuzGetTrackByIDFunc
+	origSearchISRC := qobuzSearchTrackByISRCWithDurationFunc
+	origSearchMetadata := qobuzSearchTrackByMetadataWithDurationFunc
+	origSongLinkCheck := songLinkCheckTrackAvailabilityFunc
+	t.Cleanup(func() {
+		qobuzGetTrackByIDFunc = origGetTrackByID
+		qobuzSearchTrackByISRCWithDurationFunc = origSearchISRC
+		qobuzSearchTrackByMetadataWithDurationFunc = origSearchMetadata
+		songLinkCheckTrackAvailabilityFunc = origSongLinkCheck
+		GetTrackIDCache().Clear()
+	})
+	GetTrackIDCache().Clear()
+
+	qobuzGetTrackByIDFunc = func(_ *QobuzDownloader, trackID int64) (*QobuzTrack, error) {
+		if trackID != 111 {
+			t.Fatalf("unexpected track ID lookup: %d", trackID)
+		}
+		return testQobuzTrack(111, "Aperture", "Harry Styles", 180), nil
+	}
+	qobuzSearchTrackByISRCWithDurationFunc = func(_ *QobuzDownloader, isrc string, expectedDurationSec int) (*QobuzTrack, error) {
+		if isrc != "TESTISRC1" {
+			t.Fatalf("unexpected ISRC lookup: %q", isrc)
+		}
+		if expectedDurationSec != 180 {
+			t.Fatalf("unexpected duration: %d", expectedDurationSec)
+		}
+		return testQobuzTrack(222, "Taste Back", "Harry Styles", 180), nil
+	}
+	qobuzSearchTrackByMetadataWithDurationFunc = func(_ *QobuzDownloader, _, _ string, _ int) (*QobuzTrack, error) {
+		t.Fatal("metadata fallback should not run when ISRC fallback succeeds")
+		return nil, nil
+	}
+	songLinkCheckTrackAvailabilityFunc = func(_ *SongLinkClient, spotifyTrackID string, isrc string) (*TrackAvailability, error) {
+		if spotifyTrackID != "spotify-track-id" {
+			t.Fatalf("unexpected spotify ID: %q", spotifyTrackID)
+		}
+		if isrc != "TESTISRC1" {
+			t.Fatalf("unexpected SongLink ISRC: %q", isrc)
+		}
+		return &TrackAvailability{QobuzID: "111"}, nil
+	}
+
+	req := DownloadRequest{
+		ISRC:       "TESTISRC1",
+		SpotifyID:  "spotify-track-id",
+		TrackName:  "Taste Back",
+		ArtistName: "Harry Styles",
+		DurationMS: 180000,
+	}
+
+	track, err := resolveQobuzTrackForRequest(req, &QobuzDownloader{}, "Test")
+	if err != nil {
+		t.Fatalf("expected no error, got %v", err)
+	}
+	if track == nil || track.ID != 222 || track.Title != "Taste Back" {
+		t.Fatalf("unexpected resolved track: %+v", track)
+	}
+
+	cached := GetTrackIDCache().Get(req.ISRC)
+	if cached == nil || cached.QobuzTrackID != 222 {
+		t.Fatalf("expected validated fallback track to be cached, got %+v", cached)
+	}
+}
+
+func TestResolveQobuzTrackForRequestRejectsOdesliMismatch(t *testing.T) {
+	origGetTrackByID := qobuzGetTrackByIDFunc
+	origSearchISRC := qobuzSearchTrackByISRCWithDurationFunc
+	origSearchMetadata := qobuzSearchTrackByMetadataWithDurationFunc
+	origSongLinkCheck := songLinkCheckTrackAvailabilityFunc
+	t.Cleanup(func() {
+		qobuzGetTrackByIDFunc = origGetTrackByID
+		qobuzSearchTrackByISRCWithDurationFunc = origSearchISRC
+		qobuzSearchTrackByMetadataWithDurationFunc = origSearchMetadata
+		songLinkCheckTrackAvailabilityFunc = origSongLinkCheck
+	})
+
+	qobuzGetTrackByIDFunc = func(_ *QobuzDownloader, trackID int64) (*QobuzTrack, error) {
+		if trackID != 333 {
+			t.Fatalf("unexpected track ID lookup: %d", trackID)
+		}
+		return testQobuzTrack(333, "American Girls", "Harry Styles", 181), nil
+	}
+	qobuzSearchTrackByISRCWithDurationFunc = func(_ *QobuzDownloader, _ string, _ int) (*QobuzTrack, error) {
+		t.Fatal("ISRC fallback should not run without an ISRC")
+		return nil, nil
+	}
+	qobuzSearchTrackByMetadataWithDurationFunc = func(_ *QobuzDownloader, trackName, artistName string, expectedDurationSec int) (*QobuzTrack, error) {
+		if trackName != "Taste Back" || artistName != "Harry Styles" || expectedDurationSec != 181 {
+			t.Fatalf("unexpected metadata fallback arguments: %q / %q / %d", trackName, artistName, expectedDurationSec)
+		}
+		return testQobuzTrack(444, "Taste Back", "Harry Styles", 181), nil
+	}
+	songLinkCheckTrackAvailabilityFunc = func(_ *SongLinkClient, _, _ string) (*TrackAvailability, error) {
+		t.Fatal("SongLink should not run when Odesli QobuzID is provided")
+		return nil, nil
+	}
+
+	req := DownloadRequest{
+		QobuzID:    "333",
+		TrackName:  "Taste Back",
+		ArtistName: "Harry Styles",
+		DurationMS: 181000,
+	}
+
+	track, err := resolveQobuzTrackForRequest(req, &QobuzDownloader{}, "Test")
+	if err != nil {
+		t.Fatalf("expected no error, got %v", err)
+	}
+	if track == nil || track.ID != 444 || track.Title != "Taste Back" {
+		t.Fatalf("unexpected resolved track: %+v", track)
+	}
+}
+
+func TestResolveQobuzTrackForRequestUsesPrefixedQobuzIDWithoutSongLink(t *testing.T) {
+	origGetTrackByID := qobuzGetTrackByIDFunc
+	origSearchISRC := qobuzSearchTrackByISRCWithDurationFunc
+	origSearchMetadata := qobuzSearchTrackByMetadataWithDurationFunc
+	origSongLinkCheck := songLinkCheckTrackAvailabilityFunc
+	t.Cleanup(func() {
+		qobuzGetTrackByIDFunc = origGetTrackByID
+		qobuzSearchTrackByISRCWithDurationFunc = origSearchISRC
+		qobuzSearchTrackByMetadataWithDurationFunc = origSearchMetadata
+		songLinkCheckTrackAvailabilityFunc = origSongLinkCheck
+	})
+
+	qobuzGetTrackByIDFunc = func(_ *QobuzDownloader, trackID int64) (*QobuzTrack, error) {
+		if trackID != 40681594 {
+			t.Fatalf("unexpected track ID lookup: %d", trackID)
+		}
+		return testQobuzTrack(40681594, "Sign of the Times", "Harry Styles", 341), nil
+	}
+	qobuzSearchTrackByISRCWithDurationFunc = func(_ *QobuzDownloader, _ string, _ int) (*QobuzTrack, error) {
+		t.Fatal("ISRC fallback should not run when request qobuz id succeeds")
+		return nil, nil
+	}
+	qobuzSearchTrackByMetadataWithDurationFunc = func(_ *QobuzDownloader, _, _ string, _ int) (*QobuzTrack, error) {
+		t.Fatal("metadata fallback should not run when request qobuz id succeeds")
+		return nil, nil
+	}
+	songLinkCheckTrackAvailabilityFunc = func(_ *SongLinkClient, _, _ string) (*TrackAvailability, error) {
+		t.Fatal("SongLink should not run when request qobuz id is provided")
+		return nil, nil
+	}
+
+	req := DownloadRequest{
+		QobuzID:    "qobuz:40681594",
+		TrackName:  "Sign of the Times",
+		ArtistName: "Harry Styles",
+		DurationMS: 341000,
+	}
+
+	track, err := resolveQobuzTrackForRequest(req, &QobuzDownloader{}, "Test")
+	if err != nil {
+		t.Fatalf("expected no error, got %v", err)
+	}
+	if track == nil || track.ID != 40681594 {
+		t.Fatalf("unexpected resolved track: %+v", track)
+	}
 }

go_backend/ratelimit.go

@@ -48,7 +48,6 @@ func (r *RateLimiter) WaitForSlot() {
 	r.timestamps = append(r.timestamps, time.Now())
 }
 
-// cleanOldTimestamps removes timestamps that are outside the current window
 func (r *RateLimiter) cleanOldTimestamps(now time.Time) {
 	cutoff := now.Add(-r.window)
 	validStart := 0

go_backend/romaji.go

@@ -170,11 +170,9 @@ func JapaneseToRomaji(text string) string {
 }
 
 func BuildSearchQuery(trackName, artistName string) string {
-	// Convert Japanese to romaji
 	trackRomaji := JapaneseToRomaji(trackName)
 	artistRomaji := JapaneseToRomaji(artistName)
 
-	// Clean up the query - remove special characters that might interfere with search
 	trackClean := cleanSearchQuery(trackRomaji)
 	artistClean := cleanSearchQuery(artistRomaji)
 
@@ -196,16 +194,13 @@ func cleanSearchQuery(s string) string {
 func CleanToASCII(s string) string {
 	var result strings.Builder
 	for _, r := range s {
-		// Keep only ASCII letters, numbers, spaces, and basic punctuation
 		if (r >= 'a' && r <= 'z') || (r >= 'A' && r <= 'Z') ||
 			(r >= '0' && r <= '9') || r == ' ' || r == '-' || r == '\'' {
 			result.WriteRune(r)
 		} else if r == ',' || r == '.' {
-			// Convert punctuation to space
 			result.WriteRune(' ')
 		}
 	}
-	// Clean up multiple spaces
 	cleaned := strings.Join(strings.Fields(result.String()), " ")
 	return strings.TrimSpace(cleaned)
 }

go_backend/songlink.go

@@ -1,7 +1,8 @@
 package gobackend
 
 import (
-	"encoding/base64"
+	"bytes"
+	"context"
 	"encoding/json"
 	"fmt"
 	"net/http"
@@ -14,6 +15,10 @@ type SongLinkClient struct {
 	client *http.Client
 }
 
+type songLinkPlatformLink struct {
+	URL string `json:"url"`
+}
+
 type TrackAvailability struct {
 	SpotifyID  string `json:"spotify_id"`
 	Tidal      bool   `json:"tidal"`
@@ -35,6 +40,15 @@ type TrackAvailability struct {
 var (
 	globalSongLinkClient *SongLinkClient
 	songLinkClientOnce   sync.Once
+	songLinkRegion       = "US"
+	songLinkRegionMu     sync.RWMutex
+	songLinkSearchByISRC = func(ctx context.Context, isrc string) (*TrackMetadata, error) {
+		return GetDeezerClient().SearchByISRC(ctx, isrc)
+	}
+	songLinkCheckAvailabilityFromDeezer = func(s *SongLinkClient, deezerTrackID string) (*TrackAvailability, error) {
+		return s.CheckAvailabilityFromDeezer(deezerTrackID)
+	}
+	songLinkRetryConfig = DefaultRetryConfig
 )
 
 func NewSongLinkClient() *SongLinkClient {
@@ -46,24 +60,103 @@ func NewSongLinkClient() *SongLinkClient {
 	return globalSongLinkClient
 }
 
+func normalizeSongLinkRegion(region string) string {
+	normalized := strings.ToUpper(strings.TrimSpace(region))
+	if len(normalized) != 2 {
+		return "US"
+	}
+	for _, ch := range normalized {
+		if ch < 'A' || ch > 'Z' {
+			return "US"
+		}
+	}
+	return normalized
+}
+
+func SetSongLinkRegion(region string) {
+	normalized := normalizeSongLinkRegion(region)
+	songLinkRegionMu.Lock()
+	songLinkRegion = normalized
+	songLinkRegionMu.Unlock()
+}
+
+func GetSongLinkRegion() string {
+	songLinkRegionMu.RLock()
+	region := songLinkRegion
+	songLinkRegionMu.RUnlock()
+	return region
+}
+
+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()
+	}
+	apiURL := fmt.Sprintf("%s?url=%s", songLinkBaseURL(), url.QueryEscape(targetURL))
+	if userCountry != "" {
+		apiURL = fmt.Sprintf("%s&userCountry=%s", apiURL, url.QueryEscape(userCountry))
+	}
+	return apiURL
+}
+
+func buildSongLinkURLByPlatform(platform, entityType, entityID, userCountry string) string {
+	if userCountry == "" {
+		userCountry = GetSongLinkRegion()
+	}
+	apiURL := fmt.Sprintf("%s?platform=%s&type=%s&id=%s",
+		songLinkBaseURL(),
+		url.QueryEscape(platform),
+		url.QueryEscape(entityType),
+		url.QueryEscape(entityID))
+	if userCountry != "" {
+		apiURL = fmt.Sprintf("%s&userCountry=%s", apiURL, url.QueryEscape(userCountry))
+	}
+	return apiURL
+}
+
 func (s *SongLinkClient) CheckTrackAvailability(spotifyTrackID string, isrc string) (*TrackAvailability, error) {
-	songLinkRateLimiter.WaitForSlot()
+	spotifyTrackID = strings.TrimSpace(spotifyTrackID)
+	isrc = strings.ToUpper(strings.TrimSpace(isrc))
 
-	spotifyBase, _ := base64.StdEncoding.DecodeString("aHR0cHM6Ly9vcGVuLnNwb3RpZnkuY29tL3RyYWNrLw==")
-	spotifyURL := fmt.Sprintf("%s%s", string(spotifyBase), spotifyTrackID)
+	switch {
+	case spotifyTrackID != "":
+		return s.checkTrackAvailabilityFromSpotify(spotifyTrackID)
+	case isrc != "":
+		return s.checkTrackAvailabilityFromISRC(isrc)
+	default:
+		return nil, fmt.Errorf("spotify track ID and ISRC are empty")
+	}
+}
 
-	apiBase, _ := base64.StdEncoding.DecodeString("aHR0cHM6Ly9hcGkuc29uZy5saW5rL3YxLWFscGhhLjEvbGlua3M/dXJsPQ==")
-	apiURL := fmt.Sprintf("%s%s", string(apiBase), url.QueryEscape(spotifyURL))
+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)
 	if err != nil {
 		return nil, fmt.Errorf("failed to create request: %w", err)
 	}
 
-	retryConfig := DefaultRetryConfig()
+	retryConfig := songLinkRetryConfig()
 	resp, err := DoRequestWithRetry(s.client, req, retryConfig)
 	if err != nil {
-		return nil, fmt.Errorf("failed to check availability: %w", err)
+		return nil, fmt.Errorf("song.link page lookup failed: %w; SongLink API lookup failed: %w", pageErr, err)
 	}
 	defer resp.Body.Close()
 
@@ -74,10 +167,10 @@ func (s *SongLinkClient) CheckTrackAvailability(spotifyTrackID string, isrc stri
 		return nil, fmt.Errorf("track not found on any streaming platform")
 	}
 	if resp.StatusCode == 429 {
-		return nil, fmt.Errorf("SongLink rate limit exceeded")
+		return nil, fmt.Errorf("song.link page lookup failed: %w; SongLink API rate limit exceeded", pageErr)
 	}
 	if resp.StatusCode != 200 {
-		return nil, fmt.Errorf("SongLink API returned status %d", resp.StatusCode)
+		return nil, fmt.Errorf("song.link page lookup failed: %w; SongLink API returned status %d", pageErr, resp.StatusCode)
 	}
 
 	body, err := ReadResponseBody(resp)
@@ -86,61 +179,145 @@ func (s *SongLinkClient) CheckTrackAvailability(spotifyTrackID string, isrc stri
 	}
 
 	var songLinkResp struct {
-		LinksByPlatform map[string]struct {
-			URL string `json:"url"`
-		} `json:"linksByPlatform"`
+		LinksByPlatform map[string]songLinkPlatformLink `json:"linksByPlatform"`
 	}
 
 	if err := json.Unmarshal(body, &songLinkResp); err != nil {
 		return nil, fmt.Errorf("failed to decode response: %w", err)
 	}
 
-	availability := &TrackAvailability{
-		SpotifyID: spotifyTrackID,
+	LogWarn("SongLink", "Spotify %s resolved via SongLink API after song.link page failure: %v", spotifyTrackID, pageErr)
+	return buildTrackAvailabilityFromSongLinkLinks(spotifyTrackID, songLinkResp.LinksByPlatform), nil
+}
+
+func (s *SongLinkClient) checkTrackAvailabilityFromSpotifyPage(spotifyTrackID string) (*TrackAvailability, error) {
+	pageURL := fmt.Sprintf("https://song.link/s/%s", spotifyTrackID)
+	req, err := http.NewRequest("GET", pageURL, nil)
+	if err != nil {
+		return nil, fmt.Errorf("failed to create song.link page request: %w", err)
 	}
 
-	if tidalLink, ok := songLinkResp.LinksByPlatform["tidal"]; ok && tidalLink.URL != "" {
-		availability.Tidal = true
-		availability.TidalURL = tidalLink.URL
-		availability.TidalID = extractTidalIDFromURL(tidalLink.URL)
+	req.Header.Set("Accept", "text/html,application/xhtml+xml")
+	req.Header.Set("User-Agent", getRandomUserAgent())
+
+	resp, err := s.client.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("failed to fetch song.link page: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode == 404 {
+		return nil, fmt.Errorf("track not found on song.link page")
+	}
+	if resp.StatusCode != 200 {
+		return nil, fmt.Errorf("song.link page returned status %d", resp.StatusCode)
 	}
 
-	if amazonLink, ok := songLinkResp.LinksByPlatform["amazonMusic"]; ok && amazonLink.URL != "" {
-		availability.Amazon = true
-		availability.AmazonURL = amazonLink.URL
+	body, err := ReadResponseBody(resp)
+	if err != nil {
+		return nil, fmt.Errorf("failed to read song.link page: %w", err)
 	}
 
-	if deezerLink, ok := songLinkResp.LinksByPlatform["deezer"]; ok && deezerLink.URL != "" {
-		availability.Deezer = true
-		availability.DeezerURL = deezerLink.URL
-		availability.DeezerID = extractDeezerIDFromURL(deezerLink.URL)
+	nextDataJSON, err := extractSongLinkNextDataJSON(body)
+	if err != nil {
+		return nil, err
 	}
 
-	if qobuzLink, ok := songLinkResp.LinksByPlatform["qobuz"]; ok && qobuzLink.URL != "" {
-		availability.Qobuz = true
-		availability.QobuzURL = qobuzLink.URL
-		availability.QobuzID = extractQobuzIDFromURL(qobuzLink.URL)
+	var pageData struct {
+		Props struct {
+			PageProps struct {
+				PageData struct {
+					Sections []struct {
+						Links []struct {
+							Platform string `json:"platform"`
+							URL      string `json:"url"`
+							Show     bool   `json:"show"`
+						} `json:"links"`
+					} `json:"sections"`
+				} `json:"pageData"`
+			} `json:"pageProps"`
+		} `json:"props"`
+	}
+	if err := json.Unmarshal(nextDataJSON, &pageData); err != nil {
+		return nil, fmt.Errorf("failed to decode song.link page data: %w", err)
 	}
 
-	// Prefer youtubeMusic URLs — they bypass Cobalt login requirements
-	if ytMusicLink, ok := songLinkResp.LinksByPlatform["youtubeMusic"]; ok && ytMusicLink.URL != "" {
-		availability.YouTube = true
-		availability.YouTubeURL = ytMusicLink.URL
-		availability.YouTubeID = extractYouTubeIDFromURL(ytMusicLink.URL)
-	}
-
-	// Fallback to regular youtube if youtubeMusic not available
-	if !availability.YouTube {
-		if youtubeLink, ok := songLinkResp.LinksByPlatform["youtube"]; ok && youtubeLink.URL != "" {
-			availability.YouTube = true
-			availability.YouTubeURL = youtubeLink.URL
-			availability.YouTubeID = extractYouTubeIDFromURL(youtubeLink.URL)
+	linksByPlatform := make(map[string]songLinkPlatformLink)
+	for _, section := range pageData.Props.PageProps.PageData.Sections {
+		for _, link := range section.Links {
+			if !link.Show || strings.TrimSpace(link.URL) == "" {
+				continue
+			}
+			linksByPlatform[link.Platform] = songLinkPlatformLink{URL: link.URL}
 		}
 	}
 
+	if len(linksByPlatform) == 0 {
+		return nil, fmt.Errorf("song.link page contained no usable platform links")
+	}
+
+	return buildTrackAvailabilityFromSongLinkLinks(spotifyTrackID, linksByPlatform), nil
+}
+
+func extractSongLinkNextDataJSON(body []byte) ([]byte, error) {
+	const startMarker = `<script id="__NEXT_DATA__" type="application/json">`
+	const endMarker = `</script>`
+
+	start := bytes.Index(body, []byte(startMarker))
+	if start < 0 {
+		return nil, fmt.Errorf("song.link page missing __NEXT_DATA__")
+	}
+	start += len(startMarker)
+
+	end := bytes.Index(body[start:], []byte(endMarker))
+	if end < 0 {
+		return nil, fmt.Errorf("song.link page has unterminated __NEXT_DATA__")
+	}
+
+	return body[start : start+end], nil
+}
+
+func (s *SongLinkClient) checkTrackAvailabilityFromISRC(isrc string) (*TrackAvailability, error) {
+	ctx, cancel := context.WithTimeout(context.Background(), SongLinkTimeout)
+	defer cancel()
+
+	track, err := songLinkSearchByISRC(ctx, isrc)
+	if err != nil {
+		return nil, fmt.Errorf("failed to resolve Deezer track from ISRC %s: %w", isrc, err)
+	}
+
+	deezerTrackID := songLinkExtractDeezerTrackID(track)
+	if deezerTrackID == "" {
+		return nil, fmt.Errorf("failed to resolve Deezer track ID from ISRC %s", isrc)
+	}
+
+	availability, err := songLinkCheckAvailabilityFromDeezer(s, deezerTrackID)
+	if err != nil {
+		return nil, fmt.Errorf("failed to resolve SongLink availability from ISRC %s via Deezer %s: %w", isrc, deezerTrackID, err)
+	}
+
 	return availability, nil
 }
 
+func songLinkExtractDeezerTrackID(track *TrackMetadata) string {
+	if track == nil {
+		return ""
+	}
+
+	if deezerID, ok := strings.CutPrefix(strings.TrimSpace(track.SpotifyID), "deezer:"); ok {
+		deezerID = strings.TrimSpace(deezerID)
+		if deezerID != "" {
+			return deezerID
+		}
+	}
+
+	if deezerID := extractDeezerIDFromURL(strings.TrimSpace(track.ExternalURL)); deezerID != "" {
+		return deezerID
+	}
+
+	return ""
+}
+
 func (s *SongLinkClient) GetStreamingURLs(spotifyTrackID string) (map[string]string, error) {
 	availability, err := s.CheckTrackAvailability(spotifyTrackID, "")
 	if err != nil {
@@ -158,7 +335,6 @@ func (s *SongLinkClient) GetStreamingURLs(spotifyTrackID string) (map[string]str
 	return urls, nil
 }
 
-// extractDeezerIDFromURL extracts Deezer track/album/artist ID from URL
 func extractDeezerIDFromURL(deezerURL string) string {
 	parts := strings.Split(deezerURL, "/")
 	if len(parts) > 0 {
@@ -171,7 +347,7 @@ func extractDeezerIDFromURL(deezerURL string) string {
 	return ""
 }
 
-// extractQobuzIDFromURL extracts Qobuz track ID from URL
+// extractQobuzIDFromURL extracts Qobuz track ID from URL.
 // URL formats:
 //   - https://www.qobuz.com/us-en/album/.../12345678 (album page with track highlight)
 //   - https://open.qobuz.com/track/12345678
@@ -182,29 +358,24 @@ func extractQobuzIDFromURL(qobuzURL string) string {
 		return ""
 	}
 
-	// Try to find /track/ID pattern first
 	if strings.Contains(qobuzURL, "/track/") {
 		parts := strings.Split(qobuzURL, "/track/")
 		if len(parts) > 1 {
 			idPart := parts[1]
-			// Remove query parameters
 			if idx := strings.Index(idPart, "?"); idx > 0 {
 				idPart = idPart[:idx]
 			}
-			// Remove trailing slash or path
 			if idx := strings.Index(idPart, "/"); idx > 0 {
 				idPart = idPart[:idx]
 			}
 			idPart = strings.TrimSpace(idPart)
-			// Validate it's a number
 			if idPart != "" && isNumeric(idPart) {
 				return idPart
 			}
 		}
 	}
 
-	// Try to extract from album URL with track highlight
-	// Format: /album/albumname/trackid or ?trackId=12345678
+	// Try to extract from album URL with track highlight (e.g. ?trackId=12345678)
 	if strings.Contains(qobuzURL, "trackId=") {
 		parts := strings.Split(qobuzURL, "trackId=")
 		if len(parts) > 1 {
@@ -223,7 +394,6 @@ func extractQobuzIDFromURL(qobuzURL string) string {
 	parts := strings.Split(qobuzURL, "/")
 	for i := len(parts) - 1; i >= 0; i-- {
 		part := parts[i]
-		// Remove query parameters
 		if idx := strings.Index(part, "?"); idx > 0 {
 			part = part[:idx]
 		}
@@ -236,10 +406,6 @@ func extractQobuzIDFromURL(qobuzURL string) string {
 	return ""
 }
 
-// extractTidalIDFromURL extracts Tidal track ID from URL
-// URL formats:
-//   - https://tidal.com/browse/track/12345678
-//   - https://listen.tidal.com/track/12345678
 func extractTidalIDFromURL(tidalURL string) string {
 	if tidalURL == "" {
 		return ""
@@ -265,17 +431,11 @@ func extractTidalIDFromURL(tidalURL string) string {
 	return ""
 }
 
-// extractYouTubeIDFromURL extracts YouTube video ID from URL
-// URL formats:
-//   - https://www.youtube.com/watch?v=VIDEO_ID
-//   - https://youtu.be/VIDEO_ID
-//   - https://music.youtube.com/watch?v=VIDEO_ID
 func extractYouTubeIDFromURL(youtubeURL string) string {
 	if youtubeURL == "" {
 		return ""
 	}
 
-	// Handle youtu.be short URLs
 	if strings.Contains(youtubeURL, "youtu.be/") {
 		parts := strings.Split(youtubeURL, "youtu.be/")
 		if len(parts) >= 2 {
@@ -290,7 +450,6 @@ func extractYouTubeIDFromURL(youtubeURL string) string {
 		}
 	}
 
-	// Handle youtube.com URLs with ?v= parameter
 	parsed, err := url.Parse(youtubeURL)
 	if err != nil {
 		return ""
@@ -300,7 +459,6 @@ func extractYouTubeIDFromURL(youtubeURL string) string {
 		return v
 	}
 
-	// Handle /embed/ format
 	if strings.Contains(parsed.Path, "/embed/") {
 		parts := strings.Split(parsed.Path, "/embed/")
 		if len(parts) >= 2 {
@@ -326,7 +484,6 @@ func (s *SongLinkClient) GetDeezerIDFromSpotify(spotifyTrackID string) (string,
 	return availability.DeezerID, nil
 }
 
-// GetYouTubeURLFromSpotify converts a Spotify track ID to YouTube URL using SongLink
 func (s *SongLinkClient) GetYouTubeURLFromSpotify(spotifyTrackID string) (string, error) {
 	availability, err := s.CheckTrackAvailability(spotifyTrackID, "")
 	if err != nil {
@@ -340,7 +497,6 @@ func (s *SongLinkClient) GetYouTubeURLFromSpotify(spotifyTrackID string) (string
 	return availability.YouTubeURL, nil
 }
 
-// AlbumAvailability represents album availability on different platforms
 type AlbumAvailability struct {
 	SpotifyID string `json:"spotify_id"`
 	Deezer    bool   `json:"deezer"`
@@ -351,18 +507,15 @@ type AlbumAvailability struct {
 func (s *SongLinkClient) CheckAlbumAvailability(spotifyAlbumID string) (*AlbumAvailability, error) {
 	songLinkRateLimiter.WaitForSlot()
 
-	spotifyBase, _ := base64.StdEncoding.DecodeString("aHR0cHM6Ly9vcGVuLnNwb3RpZnkuY29tL2FsYnVtLw==")
-	spotifyURL := fmt.Sprintf("%s%s", string(spotifyBase), spotifyAlbumID)
-
-	apiBase, _ := base64.StdEncoding.DecodeString("aHR0cHM6Ly9hcGkuc29uZy5saW5rL3YxLWFscGhhLjEvbGlua3M/dXJsPQ==")
-	apiURL := fmt.Sprintf("%s%s", string(apiBase), url.QueryEscape(spotifyURL))
+	spotifyURL := fmt.Sprintf("https://open.spotify.com/album/%s", spotifyAlbumID)
+	apiURL := buildSongLinkURLFromTarget(spotifyURL, "")
 
 	req, err := http.NewRequest("GET", apiURL, nil)
 	if err != nil {
 		return nil, fmt.Errorf("failed to create request: %w", err)
 	}
 
-	retryConfig := DefaultRetryConfig()
+	retryConfig := songLinkRetryConfig()
 	resp, err := DoRequestWithRetry(s.client, req, retryConfig)
 	if err != nil {
 		return nil, fmt.Errorf("failed to check album availability: %w", err)
@@ -401,7 +554,6 @@ func (s *SongLinkClient) CheckAlbumAvailability(spotifyAlbumID string) (*AlbumAv
 	return availability, nil
 }
 
-// GetDeezerAlbumIDFromSpotify converts a Spotify album ID to Deezer album ID using SongLink
 func (s *SongLinkClient) GetDeezerAlbumIDFromSpotify(spotifyAlbumID string) (string, error) {
 	availability, err := s.CheckAlbumAvailability(spotifyAlbumID)
 	if err != nil {
@@ -435,21 +587,18 @@ func (s *SongLinkClient) CheckAvailabilityFromDeezer(deezerTrackID string) (*Tra
 	return availability, nil
 }
 
-// checkAvailabilityFromDeezerSongLink is the original SongLink implementation for Deezer
 func (s *SongLinkClient) checkAvailabilityFromDeezerSongLink(deezerTrackID string) (*TrackAvailability, error) {
 	songLinkRateLimiter.WaitForSlot()
 
 	deezerURL := fmt.Sprintf("https://www.deezer.com/track/%s", deezerTrackID)
-
-	apiBase, _ := base64.StdEncoding.DecodeString("aHR0cHM6Ly9hcGkuc29uZy5saW5rL3YxLWFscGhhLjEvbGlua3M/dXJsPQ==")
-	apiURL := fmt.Sprintf("%s%s&userCountry=US", string(apiBase), url.QueryEscape(deezerURL))
+	apiURL := buildSongLinkURLFromTarget(deezerURL, "")
 
 	req, err := http.NewRequest("GET", apiURL, nil)
 	if err != nil {
 		return nil, fmt.Errorf("failed to create request: %w", err)
 	}
 
-	retryConfig := DefaultRetryConfig()
+	retryConfig := songLinkRetryConfig()
 	resp, err := DoRequestWithRetry(s.client, req, retryConfig)
 	if err != nil {
 		return nil, fmt.Errorf("failed to check availability: %w", err)
@@ -520,16 +669,17 @@ func (s *SongLinkClient) checkAvailabilityFromDeezerSongLink(deezerTrackID strin
 		availability.DeezerURL = deezerLink.URL
 	}
 
-	if youtubeLink, ok := songLinkResp.LinksByPlatform["youtube"]; ok && youtubeLink.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 = youtubeLink.URL
-		availability.YouTubeID = extractYouTubeIDFromURL(youtubeLink.URL)
+		availability.YouTubeURL = ytMusicLink.URL
+		availability.YouTubeID = extractYouTubeIDFromURL(ytMusicLink.URL)
 	}
 	if !availability.YouTube {
-		if ytMusicLink, ok := songLinkResp.LinksByPlatform["youtubeMusic"]; ok && ytMusicLink.URL != "" {
+		if youtubeLink, ok := songLinkResp.LinksByPlatform["youtube"]; ok && youtubeLink.URL != "" {
 			availability.YouTube = true
-			availability.YouTubeURL = ytMusicLink.URL
-			availability.YouTubeID = extractYouTubeIDFromURL(ytMusicLink.URL)
+			availability.YouTubeURL = youtubeLink.URL
+			availability.YouTubeID = extractYouTubeIDFromURL(youtubeLink.URL)
 		}
 	}
 
@@ -546,17 +696,14 @@ func (s *SongLinkClient) CheckAvailabilityByPlatform(platform, entityType, entit
 
 	songLinkRateLimiter.WaitForSlot()
 
-	apiURL := fmt.Sprintf("https://api.song.link/v1-alpha.1/links?platform=%s&type=%s&id=%s&userCountry=US",
-		url.QueryEscape(platform),
-		url.QueryEscape(entityType),
-		url.QueryEscape(entityID))
+	apiURL := buildSongLinkURLByPlatform(platform, entityType, entityID, "")
 
 	req, err := http.NewRequest("GET", apiURL, nil)
 	if err != nil {
 		return nil, fmt.Errorf("failed to create request: %w", err)
 	}
 
-	retryConfig := DefaultRetryConfig()
+	retryConfig := songLinkRetryConfig()
 	resp, err := DoRequestWithRetry(s.client, req, retryConfig)
 	if err != nil {
 		return nil, fmt.Errorf("failed to check availability: %w", err)
@@ -620,23 +767,68 @@ func (s *SongLinkClient) CheckAvailabilityByPlatform(platform, entityType, entit
 		availability.DeezerID = extractDeezerIDFromURL(deezerLink.URL)
 	}
 
-	if youtubeLink, ok := songLinkResp.LinksByPlatform["youtube"]; ok && youtubeLink.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 = youtubeLink.URL
-		availability.YouTubeID = extractYouTubeIDFromURL(youtubeLink.URL)
+		availability.YouTubeURL = ytMusicLink.URL
+		availability.YouTubeID = extractYouTubeIDFromURL(ytMusicLink.URL)
 	}
 	if !availability.YouTube {
-		if ytMusicLink, ok := songLinkResp.LinksByPlatform["youtubeMusic"]; ok && ytMusicLink.URL != "" {
+		if youtubeLink, ok := songLinkResp.LinksByPlatform["youtube"]; ok && youtubeLink.URL != "" {
 			availability.YouTube = true
-			availability.YouTubeURL = ytMusicLink.URL
-			availability.YouTubeID = extractYouTubeIDFromURL(ytMusicLink.URL)
+			availability.YouTubeURL = youtubeLink.URL
+			availability.YouTubeID = extractYouTubeIDFromURL(youtubeLink.URL)
 		}
 	}
 
 	return availability, nil
 }
 
-// extractSpotifyIDFromURL extracts Spotify track ID from URL
+func buildTrackAvailabilityFromSongLinkLinks(spotifyTrackID string, links map[string]songLinkPlatformLink) *TrackAvailability {
+	availability := &TrackAvailability{
+		SpotifyID: spotifyTrackID,
+	}
+
+	if availability.SpotifyID == "" {
+		if spotifyLink, ok := links["spotify"]; ok && spotifyLink.URL != "" {
+			availability.SpotifyID = extractSpotifyIDFromURL(spotifyLink.URL)
+		}
+	}
+	if tidalLink, ok := links["tidal"]; ok && tidalLink.URL != "" {
+		availability.Tidal = true
+		availability.TidalURL = tidalLink.URL
+		availability.TidalID = extractTidalIDFromURL(tidalLink.URL)
+	}
+	if amazonLink, ok := links["amazonMusic"]; ok && amazonLink.URL != "" {
+		availability.Amazon = true
+		availability.AmazonURL = amazonLink.URL
+	}
+	if qobuzLink, ok := links["qobuz"]; ok && qobuzLink.URL != "" {
+		availability.Qobuz = true
+		availability.QobuzURL = qobuzLink.URL
+		availability.QobuzID = extractQobuzIDFromURL(qobuzLink.URL)
+	}
+	if deezerLink, ok := links["deezer"]; ok && deezerLink.URL != "" {
+		availability.Deezer = true
+		availability.DeezerURL = deezerLink.URL
+		availability.DeezerID = extractDeezerIDFromURL(deezerLink.URL)
+	}
+	if ytMusicLink, ok := links["youtubeMusic"]; ok && ytMusicLink.URL != "" {
+		availability.YouTube = true
+		availability.YouTubeURL = ytMusicLink.URL
+		availability.YouTubeID = extractYouTubeIDFromURL(ytMusicLink.URL)
+	}
+	if !availability.YouTube {
+		if youtubeLink, ok := links["youtube"]; ok && youtubeLink.URL != "" {
+			availability.YouTube = true
+			availability.YouTubeURL = youtubeLink.URL
+			availability.YouTubeID = extractYouTubeIDFromURL(youtubeLink.URL)
+		}
+	}
+
+	return availability
+}
+
 func extractSpotifyIDFromURL(spotifyURL string) string {
 	parts := strings.Split(spotifyURL, "/track/")
 	if len(parts) > 1 {
@@ -662,7 +854,6 @@ func (s *SongLinkClient) GetSpotifyIDFromDeezer(deezerTrackID string) (string, e
 	return availability.SpotifyID, nil
 }
 
-// GetTidalURLFromDeezer converts a Deezer track ID to Tidal URL using SongLink
 func (s *SongLinkClient) GetTidalURLFromDeezer(deezerTrackID string) (string, error) {
 	availability, err := s.CheckAvailabilityFromDeezer(deezerTrackID)
 	if err != nil {
@@ -689,7 +880,6 @@ func (s *SongLinkClient) GetAmazonURLFromDeezer(deezerTrackID string) (string, e
 	return availability.AmazonURL, nil
 }
 
-// GetYouTubeURLFromDeezer converts a Deezer track ID to YouTube URL using SongLink
 func (s *SongLinkClient) GetYouTubeURLFromDeezer(deezerTrackID string) (string, error) {
 	availability, err := s.CheckAvailabilityFromDeezer(deezerTrackID)
 	if err != nil {
@@ -706,15 +896,14 @@ func (s *SongLinkClient) GetYouTubeURLFromDeezer(deezerTrackID string) (string,
 func (s *SongLinkClient) CheckAvailabilityFromURL(inputURL string) (*TrackAvailability, error) {
 	songLinkRateLimiter.WaitForSlot()
 
-	apiBase, _ := base64.StdEncoding.DecodeString("aHR0cHM6Ly9hcGkuc29uZy5saW5rL3YxLWFscGhhLjEvbGlua3M/dXJsPQ==")
-	apiURL := fmt.Sprintf("%s%s", string(apiBase), url.QueryEscape(inputURL))
+	apiURL := buildSongLinkURLFromTarget(inputURL, "")
 
 	req, err := http.NewRequest("GET", apiURL, nil)
 	if err != nil {
 		return nil, fmt.Errorf("failed to create request: %w", err)
 	}
 
-	retryConfig := DefaultRetryConfig()
+	retryConfig := songLinkRetryConfig()
 	resp, err := DoRequestWithRetry(s.client, req, retryConfig)
 	if err != nil {
 		return nil, fmt.Errorf("failed to check availability: %w", err)
@@ -771,16 +960,17 @@ func (s *SongLinkClient) CheckAvailabilityFromURL(inputURL string) (*TrackAvaila
 		availability.DeezerURL = deezerLink.URL
 		availability.DeezerID = extractDeezerIDFromURL(deezerLink.URL)
 	}
-	if youtubeLink, ok := songLinkResp.LinksByPlatform["youtube"]; ok && youtubeLink.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 = youtubeLink.URL
-		availability.YouTubeID = extractYouTubeIDFromURL(youtubeLink.URL)
+		availability.YouTubeURL = ytMusicLink.URL
+		availability.YouTubeID = extractYouTubeIDFromURL(ytMusicLink.URL)
 	}
 	if !availability.YouTube {
-		if ytMusicLink, ok := songLinkResp.LinksByPlatform["youtubeMusic"]; ok && ytMusicLink.URL != "" {
+		if youtubeLink, ok := songLinkResp.LinksByPlatform["youtube"]; ok && youtubeLink.URL != "" {
 			availability.YouTube = true
-			availability.YouTubeURL = ytMusicLink.URL
-			availability.YouTubeID = extractYouTubeIDFromURL(ytMusicLink.URL)
+			availability.YouTubeURL = youtubeLink.URL
+			availability.YouTubeID = extractYouTubeIDFromURL(youtubeLink.URL)
 		}
 	}
 

go_backend/songlink_test.go

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

go_backend/spotfetch_api.go

@@ -10,7 +10,7 @@ import (
 	"time"
 )
 
-const DefaultSpotFetchAPIBaseURL = "https://spotify.afkarxyz.fun/api"
+const DefaultSpotFetchAPIBaseURL = "https://sp.afkarxyz.qzz.io/api"
 
 // GetSpotifyDataWithAPI fetches Spotify metadata through SpotFetch-compatible API.
 // This is used as a fallback when direct Spotify API access is blocked/limited.

go_backend/spotify.go

@@ -9,20 +9,20 @@ import (
 	"math/rand"
 	"net/http"
 	"net/url"
-	"os"
 	"strings"
 	"sync"
 	"time"
 )
 
 const (
-	spotifyTokenURL = "https://accounts.spotify.com/api/token"
-	playlistBaseURL = "https://api.spotify.com/v1/playlists/%s"
-	albumBaseURL    = "https://api.spotify.com/v1/albums/%s"
-	trackBaseURL    = "https://api.spotify.com/v1/tracks/%s"
-	artistBaseURL   = "https://api.spotify.com/v1/artists/%s"
-	artistAlbumsURL = "https://api.spotify.com/v1/artists/%s/albums"
-	searchBaseURL   = "https://api.spotify.com/v1/search"
+	spotifyTokenURL  = "https://accounts.spotify.com/api/token"
+	playlistBaseURL  = "https://api.spotify.com/v1/playlists/%s"
+	albumBaseURL     = "https://api.spotify.com/v1/albums/%s"
+	trackBaseURL     = "https://api.spotify.com/v1/tracks/%s"
+	artistBaseURL    = "https://api.spotify.com/v1/artists/%s"
+	artistAlbumsURL  = "https://api.spotify.com/v1/artists/%s/albums"
+	artistRelatedURL = "https://api.spotify.com/v1/artists/%s/related-artists"
+	searchBaseURL    = "https://api.spotify.com/v1/search"
 
 	artistCacheTTL = 10 * time.Minute
 	searchCacheTTL = 5 * time.Minute
@@ -63,45 +63,20 @@ var (
 	credentialsMu      sync.RWMutex
 )
 
-var ErrNoSpotifyCredentials = errors.New("Spotify credentials not configured. Please set your own Client ID and Secret in Settings, or use Deezer as metadata source (free, no credentials required)")
+var ErrNoSpotifyCredentials = errors.New("built-in Spotify API metadata provider has been removed; use Deezer or the spotify-web extension instead")
 
 func SetSpotifyCredentials(clientID, clientSecret string) {
 	credentialsMu.Lock()
 	defer credentialsMu.Unlock()
-	customClientID = clientID
-	customClientSecret = clientSecret
+	customClientID = ""
+	customClientSecret = ""
 }
 
 func HasSpotifyCredentials() bool {
-	credentialsMu.RLock()
-	defer credentialsMu.RUnlock()
-
-	if customClientID != "" && customClientSecret != "" {
-		return true
-	}
-
-	if os.Getenv("SPOTIFY_CLIENT_ID") != "" && os.Getenv("SPOTIFY_CLIENT_SECRET") != "" {
-		return true
-	}
-
 	return false
 }
 
 func getCredentials() (string, string, error) {
-	credentialsMu.RLock()
-	defer credentialsMu.RUnlock()
-
-	if customClientID != "" && customClientSecret != "" {
-		return customClientID, customClientSecret, nil
-	}
-
-	clientID := os.Getenv("SPOTIFY_CLIENT_ID")
-	clientSecret := os.Getenv("SPOTIFY_CLIENT_SECRET")
-
-	if clientID != "" && clientSecret != "" {
-		return clientID, clientSecret, nil
-	}
-
 	return "", "", ErrNoSpotifyCredentials
 }
 
@@ -140,6 +115,8 @@ type TrackMetadata struct {
 	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"`
 }
 
@@ -180,6 +157,8 @@ type AlbumResponsePayload struct {
 }
 
 type PlaylistInfoMetadata struct {
+	Name   string `json:"name,omitempty"`
+	Images string `json:"images,omitempty"`
 	Tracks struct {
 		Total int `json:"total"`
 	} `json:"tracks"`
@@ -361,6 +340,10 @@ func (c *SpotifyMetadataClient) SearchTracks(ctx context.Context, query string,
 	}
 
 	for _, track := range response.Tracks.Items {
+		var firstArtistID string
+		if len(track.Artists) > 0 {
+			firstArtistID = track.Artists[0].ID
+		}
 		result.Tracks = append(result.Tracks, TrackMetadata{
 			SpotifyID:   track.ID,
 			Artists:     joinArtists(track.Artists),
@@ -375,6 +358,8 @@ func (c *SpotifyMetadataClient) SearchTracks(ctx context.Context, query string,
 			DiscNumber:  track.DiscNumber,
 			ExternalURL: track.ExternalURL.Spotify,
 			ISRC:        track.ExternalID.ISRC,
+			AlbumID:     track.Album.ID,
+			ArtistID:    firstArtistID,
 			AlbumType:   track.Album.AlbumType,
 		})
 	}
@@ -426,6 +411,10 @@ func (c *SpotifyMetadataClient) SearchAll(ctx context.Context, query string, tra
 	}
 
 	for _, track := range response.Tracks.Items {
+		var firstArtistID string
+		if len(track.Artists) > 0 {
+			firstArtistID = track.Artists[0].ID
+		}
 		result.Tracks = append(result.Tracks, TrackMetadata{
 			SpotifyID:   track.ID,
 			Artists:     joinArtists(track.Artists),
@@ -440,6 +429,8 @@ func (c *SpotifyMetadataClient) SearchAll(ctx context.Context, query string, tra
 			DiscNumber:  track.DiscNumber,
 			ExternalURL: track.ExternalURL.Spotify,
 			ISRC:        track.ExternalID.ISRC,
+			AlbumID:     track.Album.ID,
+			ArtistID:    firstArtistID,
 			AlbumType:   track.Album.AlbumType,
 		})
 	}
@@ -838,6 +829,47 @@ func (c *SpotifyMetadataClient) fetchArtist(ctx context.Context, artistID, token
 	return result, nil
 }
 
+func (c *SpotifyMetadataClient) GetRelatedArtists(ctx context.Context, artistID string, limit int) ([]SearchArtistResult, error) {
+	token, err := c.getAccessToken(ctx)
+	if err != nil {
+		return nil, err
+	}
+
+	var data struct {
+		Artists []struct {
+			ID        string  `json:"id"`
+			Name      string  `json:"name"`
+			Images    []image `json:"images"`
+			Followers struct {
+				Total int `json:"total"`
+			} `json:"followers"`
+			Popularity int `json:"popularity"`
+		} `json:"artists"`
+	}
+
+	if err := c.getJSON(ctx, fmt.Sprintf(artistRelatedURL, artistID), token, &data); err != nil {
+		return nil, err
+	}
+
+	maxItems := len(data.Artists)
+	if limit > 0 && limit < maxItems {
+		maxItems = limit
+	}
+
+	result := make([]SearchArtistResult, 0, maxItems)
+	for i := 0; i < maxItems; i++ {
+		artist := data.Artists[i]
+		result = append(result, SearchArtistResult{
+			ID:         artist.ID,
+			Name:       artist.Name,
+			Images:     firstImageURL(artist.Images),
+			Followers:  artist.Followers.Total,
+			Popularity: artist.Popularity,
+		})
+	}
+	return result, nil
+}
+
 func (c *SpotifyMetadataClient) fetchTrackISRC(ctx context.Context, trackID, token string) string {
 	var data struct {
 		ExternalID externalID `json:"external_ids"`

go_backend/tidal_test.go

@@ -0,0 +1,222 @@
+package gobackend
+
+import "testing"
+
+func TestParseTidalURL(t *testing.T) {
+	tests := []struct {
+		name      string
+		input     string
+		wantType  string
+		wantID    string
+		expectErr bool
+	}{
+		{
+			name:     "track url",
+			input:    "https://tidal.com/track/77616174",
+			wantType: "track",
+			wantID:   "77616174",
+		},
+		{
+			name:     "browse album url",
+			input:    "https://listen.tidal.com/browse/album/77616169",
+			wantType: "album",
+			wantID:   "77616169",
+		},
+		{
+			name:     "artist url",
+			input:    "https://www.tidal.com/artist/3852143",
+			wantType: "artist",
+			wantID:   "3852143",
+		},
+		{
+			name:     "playlist url",
+			input:    "https://tidal.com/playlist/edf3b7d2-cb42-41d7-93c0-afa2a395521b",
+			wantType: "playlist",
+			wantID:   "edf3b7d2-cb42-41d7-93c0-afa2a395521b",
+		},
+		{
+			name:      "unsupported host",
+			input:     "https://example.com/track/123",
+			expectErr: true,
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			gotType, gotID, err := parseTidalURL(test.input)
+			if test.expectErr {
+				if err == nil {
+					t.Fatalf("expected error, got none")
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("expected no error, got %v", err)
+			}
+			if gotType != test.wantType || gotID != test.wantID {
+				t.Fatalf("parseTidalURL(%q) = (%q, %q), want (%q, %q)", test.input, gotType, gotID, test.wantType, test.wantID)
+			}
+		})
+	}
+}
+
+func TestParseTidalRequestTrackID(t *testing.T) {
+	tests := []struct {
+		input string
+		want  int64
+		ok    bool
+	}{
+		{input: "40681594", want: 40681594, ok: true},
+		{input: "tidal:40681594", want: 40681594, ok: true},
+		{input: " tidal:40681594 ", want: 40681594, ok: true},
+		{input: "", want: 0, ok: false},
+		{input: "tidal:not-a-number", want: 0, ok: false},
+	}
+
+	for _, test := range tests {
+		got, ok := parseTidalRequestTrackID(test.input)
+		if got != test.want || ok != test.ok {
+			t.Fatalf("parseTidalRequestTrackID(%q) = (%d, %v), want (%d, %v)", test.input, got, ok, test.want, test.ok)
+		}
+	}
+}
+
+func TestTidalImageURL(t *testing.T) {
+	got := tidalImageURL("fc18a64b-d76b-4582-962a-224cb05193f3", "1280x1280")
+	want := "https://resources.tidal.com/images/fc18a64b/d76b/4582/962a/224cb05193f3/1280x1280.jpg"
+	if got != want {
+		t.Fatalf("tidalImageURL() = %q, want %q", got, want)
+	}
+}
+
+func TestTidalTrackToTrackMetadata(t *testing.T) {
+	track := &TidalTrack{
+		ID:           77616174,
+		Title:        "Bruckner: Symphony No. 5",
+		ISRC:         "GBUM71507433",
+		Duration:     1172,
+		TrackNumber:  5,
+		VolumeNumber: 1,
+		URL:          "http://www.tidal.com/track/77616174",
+	}
+	track.Artist.ID = 3852143
+	track.Artist.Name = "Staatskapelle Berlin"
+	track.Artists = []struct {
+		ID      int64  `json:"id"`
+		Name    string `json:"name"`
+		Type    string `json:"type"`
+		Picture string `json:"picture"`
+	}{
+		{ID: 3852143, Name: "Staatskapelle Berlin", Type: "MAIN"},
+		{ID: 12430, Name: "Daniel Barenboim", Type: "FEATURED"},
+	}
+	track.Album.ID = 77616169
+	track.Album.Title = "Bruckner: Symphonies 4-9"
+	track.Album.Cover = "fc18a64b-d76b-4582-962a-224cb05193f3"
+	track.Album.ReleaseDate = "2016-02-26"
+
+	got := tidalTrackToTrackMetadata(track)
+	if got.SpotifyID != "tidal:77616174" {
+		t.Fatalf("unexpected track ID: %q", got.SpotifyID)
+	}
+	if got.Artists != "Staatskapelle Berlin, Daniel Barenboim" {
+		t.Fatalf("unexpected artists: %q", got.Artists)
+	}
+	if got.AlbumID != "tidal:77616169" {
+		t.Fatalf("unexpected album ID: %q", got.AlbumID)
+	}
+	if got.ArtistID != "tidal:3852143" {
+		t.Fatalf("unexpected artist ID: %q", got.ArtistID)
+	}
+	if got.Images == "" || got.ExternalURL != "https://www.tidal.com/track/77616174" {
+		t.Fatalf("unexpected image/url: %q / %q", got.Images, got.ExternalURL)
+	}
+}
+
+func TestTidalAlbumToArtistAlbum(t *testing.T) {
+	album := &tidalPublicAlbum{
+		ID:             77616169,
+		Title:          "Bruckner: Symphonies 4-9",
+		Type:           "ALBUM",
+		Cover:          "fc18a64b-d76b-4582-962a-224cb05193f3",
+		ReleaseDate:    "2016-02-26",
+		NumberOfTracks: 23,
+		Artists: []tidalPublicArtist{
+			{ID: 3852143, Name: "Staatskapelle Berlin", Type: "MAIN"},
+			{ID: 12430, Name: "Daniel Barenboim", Type: "FEATURED"},
+		},
+	}
+
+	got := tidalAlbumToArtistAlbum(album)
+	if got.ID != "tidal:77616169" {
+		t.Fatalf("unexpected album ID: %q", got.ID)
+	}
+	if got.AlbumType != "album" {
+		t.Fatalf("unexpected album type: %q", got.AlbumType)
+	}
+	if got.Artists != "Staatskapelle Berlin, Daniel Barenboim" {
+		t.Fatalf("unexpected artists: %q", got.Artists)
+	}
+	if got.Images == "" {
+		t.Fatalf("expected image URL, got empty string")
+	}
+}
+
+func TestTidalAlbumToArtistAlbumWithFallbackType(t *testing.T) {
+	album := &tidalPublicAlbum{
+		ID:             490623904,
+		Title:          "LET 'EM KNOW",
+		Cover:          "fc18a64b-d76b-4582-962a-224cb05193f3",
+		NumberOfTracks: 1,
+	}
+
+	got := tidalAlbumToArtistAlbumWithType(album, "single")
+	if got.AlbumType != "single" {
+		t.Fatalf("unexpected fallback album type: %q", got.AlbumType)
+	}
+}
+
+func TestTidalArtistAlbumTypeFromModuleTitle(t *testing.T) {
+	tests := []struct {
+		title string
+		want  string
+	}{
+		{title: "Albums", want: "album"},
+		{title: "EP & Singles", want: "single"},
+		{title: "Compilations", want: "album"},
+		{title: "Appears On", want: "album"},
+		{title: "Unknown", want: ""},
+	}
+
+	for _, test := range tests {
+		if got := tidalArtistAlbumTypeFromModuleTitle(test.title); got != test.want {
+			t.Fatalf("tidalArtistAlbumTypeFromModuleTitle(%q) = %q, want %q", test.title, got, test.want)
+		}
+	}
+}
+
+func TestTidalPlaylistImageUsesOrigin(t *testing.T) {
+	got := tidalImageURL("e6b59fd3-6995-40f0-8a32-174db3a8f4f2", "origin")
+	want := "https://resources.tidal.com/images/e6b59fd3/6995/40f0/8a32/174db3a8f4f2/origin.jpg"
+	if got != want {
+		t.Fatalf("unexpected origin playlist image URL: %q", got)
+	}
+}
+
+func TestTidalPlaylistOwnerName(t *testing.T) {
+	editorial := &tidalPublicPlaylist{Type: "EDITORIAL"}
+	if got := tidalPlaylistOwnerName(editorial); got != "TIDAL" {
+		t.Fatalf("unexpected editorial owner: %q", got)
+	}
+
+	artist := &tidalPublicPlaylist{Type: "ARTIST"}
+	if got := tidalPlaylistOwnerName(artist); got != "Artist" {
+		t.Fatalf("unexpected artist owner: %q", got)
+	}
+
+	user := &tidalPublicPlaylist{}
+	user.Creator.Name = "djtest"
+	if got := tidalPlaylistOwnerName(user); got != "djtest" {
+		t.Fatalf("unexpected creator owner: %q", got)
+	}
+}

go_backend/title_match_utils.go

@@ -41,3 +41,72 @@ 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 == "" {
+		return ""
+	}
+
+	var b strings.Builder
+	b.Grow(len(trimmed))
+
+	for _, r := range trimmed {
+		switch {
+		case unicode.IsLetter(r), unicode.IsNumber(r), unicode.IsSpace(r), unicode.IsPunct(r):
+			continue
+		// Drop combining marks such as emoji variation selectors.
+		case unicode.Is(unicode.Mn, r), unicode.Is(unicode.Mc, r), unicode.Is(unicode.Me, r):
+			continue
+		default:
+			b.WriteRune(r)
+		}
+	}
+
+	return b.String()
+}
+
+// ==================== Shared Track Verification ====================
+
+// resolvedTrackInfo holds the metadata fetched from a provider for verification.
+type resolvedTrackInfo struct {
+	Title      string
+	ArtistName string
+	Duration   int // seconds
+}
+
+// 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 {
+	if req.ArtistName != "" && resolved.ArtistName != "" &&
+		!artistsMatch(req.ArtistName, resolved.ArtistName) {
+		GoLog("[%s] Verification failed: artist mismatch — expected '%s', got '%s'\n",
+			logPrefix, req.ArtistName, resolved.ArtistName)
+		return false
+	}
+
+	if req.TrackName != "" && resolved.Title != "" &&
+		!titlesMatch(req.TrackName, resolved.Title) {
+		GoLog("[%s] Verification failed: title mismatch — expected '%s', got '%s'\n",
+			logPrefix, req.TrackName, resolved.Title)
+		return false
+	}
+
+	expectedDurationSec := req.DurationMS / 1000
+	if expectedDurationSec > 0 && resolved.Duration > 0 {
+		diff := expectedDurationSec - resolved.Duration
+		if diff < 0 {
+			diff = -diff
+		}
+		if diff > 10 {
+			GoLog("[%s] Verification failed: duration mismatch — expected %ds, got %ds\n",
+				logPrefix, expectedDurationSec, resolved.Duration)
+			return false
+		}
+	}
+
+	return true
+}

go_backend/title_match_utils_test.go

@@ -27,8 +27,26 @@ func TestTitlesMatch_SeparatorVariants(t *testing.T) {
 	}
 }
 
+func TestTitlesMatch_EmojiStrict(t *testing.T) {
+	if titlesMatch("🪐", "Higher Power") {
+		t.Fatal("expected emoji title not to match unrelated textual title")
+	}
+	if !titlesMatch("🪐", "🪐") {
+		t.Fatal("expected identical emoji titles to match")
+	}
+}
+
 func TestQobuzTitlesMatch_SeparatorVariants(t *testing.T) {
 	if !qobuzTitlesMatch("Doctor / Cops", "Doctor _ Cops") {
 		t.Fatal("expected qobuzTitlesMatch to accept / vs _ variant")
 	}
 }
+
+func TestQobuzTitlesMatch_EmojiStrict(t *testing.T) {
+	if qobuzTitlesMatch("🪐", "Higher Power") {
+		t.Fatal("expected emoji title not to match unrelated textual title")
+	}
+	if !qobuzTitlesMatch("🪐", "🪐") {
+		t.Fatal("expected identical emoji titles to match")
+	}
+}

go_backend/youtube.go

@@ -1,4 +1,3 @@
-// Package gobackend - YouTube download via Cobalt API (lossy-only provider)
 package gobackend
 
 import (
@@ -12,7 +11,6 @@ import (
 	"strconv"
 	"strings"
 	"sync"
-	"time"
 )
 
 type YouTubeDownloader struct {
@@ -31,6 +29,7 @@ var (
 type YouTubeQuality string
 
 const (
+	YouTubeQualityOpus320 YouTubeQuality = "opus_320"
 	YouTubeQualityOpus256 YouTubeQuality = "opus_256"
 	YouTubeQualityOpus128 YouTubeQuality = "opus_128"
 	YouTubeQualityMP3128  YouTubeQuality = "mp3_128"
@@ -39,7 +38,7 @@ const (
 )
 
 var (
-	youtubeOpusSupportedBitrates = []int{128, 256}
+	youtubeOpusSupportedBitrates = []int{128, 256, 320}
 	youtubeMp3SupportedBitrates  = []int{128, 256, 320}
 )
 
@@ -83,7 +82,7 @@ type YouTubeDownloadResult struct {
 func NewYouTubeDownloader() *YouTubeDownloader {
 	youtubeDownloaderOnce.Do(func() {
 		globalYouTubeDownloader = &YouTubeDownloader{
-			client: NewHTTPClientWithTimeout(120 * time.Second),
+			client: NewHTTPClientWithTimeout(DownloadTimeout),
 			apiURL: "https://api.qwkuns.me",
 		}
 	})
@@ -148,6 +147,8 @@ func parseYouTubeQualityInput(raw string) (format string, bitrate int, normalize
 	switch normalizedRaw {
 	case "opus_256", "opus256", "opus":
 		return "opus", 256, YouTubeQualityOpus256
+	case "opus_320", "opus320":
+		return "opus", 320, YouTubeQualityOpus320
 	case "opus_128", "opus128":
 		return "opus", 128, YouTubeQualityOpus128
 	case "mp3_320", "mp3320", "mp3", "":
@@ -161,7 +162,6 @@ func parseYouTubeQualityInput(raw string) (format string, bitrate int, normalize
 	}
 }
 
-// SearchYouTube returns a YouTube Music search URL for the given track
 func (y *YouTubeDownloader) SearchYouTube(trackName, artistName string) (string, error) {
 	query := fmt.Sprintf("%s %s", artistName, trackName)
 	searchQuery := url.QueryEscape(query)
@@ -213,7 +213,6 @@ func (y *YouTubeDownloader) GetDownloadURL(youtubeURL string, quality YouTubeQua
 	return resp, nil
 }
 
-// requestCobaltDirect sends a download request to the primary Cobalt API.
 func (y *YouTubeDownloader) requestCobaltDirect(videoURL, audioFormat, audioBitrate string) (*CobaltResponse, error) {
 	reqBody := CobaltRequest{
 		URL:             videoURL,
@@ -276,11 +275,11 @@ func (y *YouTubeDownloader) requestCobaltDirect(videoURL, audioFormat, audioBitr
 }
 
 // requestSpotubeDL uses SpotubeDL as a Cobalt proxy (they handle auth to yt-dl.click instances).
-// Note: engine v2 currently serves MP3-oriented outputs, so we only use v2 for MP3 requests.
+// Engines v3/v2 are MP3-oriented outputs, so we only use them for MP3 requests.
 func (y *YouTubeDownloader) requestSpotubeDL(videoID, audioFormat, audioBitrate string) (*CobaltResponse, error) {
 	engines := []string{"v1"}
 	if strings.EqualFold(audioFormat, "mp3") {
-		engines = append(engines, "v2")
+		engines = append(engines, "v3", "v2")
 	}
 	var lastErr error
 
@@ -470,7 +469,6 @@ func BuildYouTubeWatchURL(videoID string) string {
 	return fmt.Sprintf("https://music.youtube.com/watch?v=%s", videoID)
 }
 
-// isYouTubeVideoID checks if s is an 11-char YouTube video ID
 func isYouTubeVideoID(s string) bool {
 	if len(s) != 11 {
 		return false
@@ -515,12 +513,10 @@ func ExtractYouTubeVideoID(urlStr string) (string, error) {
 		return "", fmt.Errorf("invalid URL: %w", err)
 	}
 
-	// /watch?v=
 	if v := parsed.Query().Get("v"); v != "" {
 		return v, nil
 	}
 
-	// /embed/
 	if strings.Contains(parsed.Path, "/embed/") {
 		parts := strings.Split(parsed.Path, "/embed/")
 		if len(parts) >= 2 {
@@ -528,7 +524,6 @@ func ExtractYouTubeVideoID(urlStr string) (string, error) {
 		}
 	}
 
-	// /v/
 	if strings.Contains(parsed.Path, "/v/") {
 		parts := strings.Split(parsed.Path, "/v/")
 		if len(parts) >= 2 {
@@ -539,12 +534,65 @@ func ExtractYouTubeVideoID(urlStr string) (string, error) {
 	return "", fmt.Errorf("could not extract video ID from URL")
 }
 
+// searchYouTubeMusicViaExtension uses the YT Music extension's customSearch
+// to find a track by artist + title. It filters for tracks only (not videos,
+// albums, or playlists) and returns the YouTube Music watch URL for the first
+// matching track, or "" if nothing was found.
+func searchYouTubeMusicViaExtension(artistName, trackName string) string {
+	extManager := GetExtensionManager()
+	searchProviders := extManager.GetSearchProviders()
+
+	// Find the ytmusic-spotiflac extension
+	var ytProvider *ExtensionProviderWrapper
+	for _, p := range searchProviders {
+		if p.extension.ID == "ytmusic-spotiflac" {
+			ytProvider = p
+			break
+		}
+	}
+	if ytProvider == nil {
+		GoLog("[YouTube] YT Music extension not found or not enabled, skipping fallback\n")
+		return ""
+	}
+
+	query := strings.TrimSpace(artistName + " " + trackName)
+	if query == "" {
+		return ""
+	}
+
+	GoLog("[YouTube] Searching YT Music extension for: %s\n", query)
+	results, err := ytProvider.CustomSearch(query, map[string]interface{}{
+		"filter": "tracks",
+	})
+	if err != nil {
+		GoLog("[YouTube] YT Music extension search failed: %v\n", err)
+		return ""
+	}
+
+	// Find the first track result (item_type == "track" with a valid video ID)
+	for _, track := range results {
+		if track.ItemType != "" && track.ItemType != "track" {
+			continue
+		}
+		videoID := strings.TrimSpace(track.ID)
+		if videoID == "" {
+			continue
+		}
+		if isYouTubeVideoID(videoID) {
+			return BuildYouTubeWatchURL(videoID)
+		}
+	}
+
+	GoLog("[YouTube] YT Music extension returned no matching tracks for: %s\n", query)
+	return ""
+}
+
 func downloadFromYouTube(req DownloadRequest) (YouTubeDownloadResult, error) {
 	downloader := NewYouTubeDownloader()
 
 	format, bitrate, quality := parseYouTubeQualityInput(req.Quality)
 
-	// URL lookup priority: YouTube video ID > Spotify ID > Deezer ID > ISRC
+	// URL lookup priority: YouTube video ID > YT Music extension > SongLink (Spotify/Deezer/ISRC)
 	var youtubeURL string
 	var lookupErr error
 
@@ -554,7 +602,15 @@ func downloadFromYouTube(req DownloadRequest) (YouTubeDownloadResult, error) {
 		GoLog("[YouTube] SpotifyID appears to be YouTube video ID, using directly: %s\n", youtubeURL)
 	}
 
-	// Try Spotify ID via SongLink
+	// Try YT Music extension search first (if installed) - more accurate, tracks only
+	if youtubeURL == "" && (req.TrackName != "" || req.ArtistName != "") {
+		youtubeURL = searchYouTubeMusicViaExtension(req.ArtistName, req.TrackName)
+		if youtubeURL != "" {
+			GoLog("[YouTube] Found YouTube URL via YT Music extension: %s\n", youtubeURL)
+		}
+	}
+
+	// Fallback: Try Spotify ID via SongLink
 	if youtubeURL == "" && req.SpotifyID != "" && !isYouTubeVideoID(req.SpotifyID) {
 		GoLog("[YouTube] Looking up YouTube URL via SongLink for Spotify ID: %s\n", req.SpotifyID)
 		songlink := NewSongLinkClient()
@@ -566,7 +622,7 @@ func downloadFromYouTube(req DownloadRequest) (YouTubeDownloadResult, error) {
 		}
 	}
 
-	// Try Deezer ID via SongLink
+	// Fallback: Try Deezer ID via SongLink
 	if youtubeURL == "" && req.DeezerID != "" {
 		GoLog("[YouTube] Looking up YouTube URL via SongLink for Deezer ID: %s\n", req.DeezerID)
 		songlink := NewSongLinkClient()
@@ -578,7 +634,7 @@ func downloadFromYouTube(req DownloadRequest) (YouTubeDownloadResult, error) {
 		}
 	}
 
-	// Try ISRC via SongLink
+	// Fallback: Try ISRC via SongLink
 	if youtubeURL == "" && req.ISRC != "" {
 		GoLog("[YouTube] Looking up YouTube URL via SongLink for ISRC: %s\n", req.ISRC)
 		songlink := NewSongLinkClient()
@@ -646,7 +702,6 @@ func downloadFromYouTube(req DownloadRequest) (YouTubeDownloadResult, error) {
 
 	GoLog("[YouTube] Downloading to: %s\n", outputPath)
 
-	// Parallel fetch cover art + lyrics
 	var parallelResult *ParallelDownloadResult
 	if req.EmbedLyrics || req.CoverURL != "" {
 		GoLog("[YouTube] Starting parallel fetch for cover and lyrics...\n")

go_backend/youtube_quality_test.go

@@ -30,8 +30,8 @@ func TestParseYouTubeQualityInput_Mp3NormalizesToSupportedBitrates(t *testing.T)
 
 func TestParseYouTubeQualityInput_PicksNearestSupportedBitrate(t *testing.T) {
 	_, opusBitrate, _ := parseYouTubeQualityInput("opus_999")
-	if opusBitrate != 256 {
-		t.Fatalf("expected opus normalization to 256, got %d", opusBitrate)
+	if opusBitrate != 320 {
+		t.Fatalf("expected opus normalization to 320, got %d", opusBitrate)
 	}
 
 	_, mp3Bitrate, _ := parseYouTubeQualityInput("mp3_1")
@@ -39,3 +39,16 @@ func TestParseYouTubeQualityInput_PicksNearestSupportedBitrate(t *testing.T) {
 		t.Fatalf("expected mp3 normalization to 128, got %d", mp3Bitrate)
 	}
 }
+
+func TestParseYouTubeQualityInput_Opus320(t *testing.T) {
+	format, bitrate, normalized := parseYouTubeQualityInput("opus_320")
+	if format != "opus" {
+		t.Fatalf("expected opus format, got %s", format)
+	}
+	if bitrate != 320 {
+		t.Fatalf("expected 320 bitrate, got %d", bitrate)
+	}
+	if normalized != YouTubeQualityOpus320 {
+		t.Fatalf("expected %s normalized, got %s", YouTubeQualityOpus320, normalized)
+	}
+}

ios/Runner/AppDelegate.swift

@@ -5,6 +5,18 @@ import Gobackend  // Import Go framework
 @main
 @objc class AppDelegate: FlutterAppDelegate {
     private let CHANNEL = "com.zarz.spotiflac/backend"
+    private let DOWNLOAD_PROGRESS_STREAM_CHANNEL = "com.zarz.spotiflac/download_progress_stream"
+    private let LIBRARY_SCAN_PROGRESS_STREAM_CHANNEL = "com.zarz.spotiflac/library_scan_progress_stream"
+    private let streamQueue = DispatchQueue(label: "com.zarz.spotiflac.progress_stream", qos: .utility)
+    private var downloadProgressTimer: DispatchSourceTimer?
+    private var downloadProgressEventSink: FlutterEventSink?
+    private var lastDownloadProgressPayload: String?
+    private var libraryScanProgressTimer: DispatchSourceTimer?
+    private var libraryScanProgressEventSink: FlutterEventSink?
+    private var lastLibraryScanProgressPayload: String?
+    
+    /// Currently accessed security-scoped URL for library folder
+    private var activeSecurityScopedURL: URL?
     
     override func application(
         _ application: UIApplication,
@@ -16,14 +28,111 @@ import Gobackend  // Import Go framework
             name: CHANNEL,
             binaryMessenger: controller.binaryMessenger
         )
+        let downloadProgressEvents = FlutterEventChannel(
+            name: DOWNLOAD_PROGRESS_STREAM_CHANNEL,
+            binaryMessenger: controller.binaryMessenger
+        )
+        let libraryScanProgressEvents = FlutterEventChannel(
+            name: LIBRARY_SCAN_PROGRESS_STREAM_CHANNEL,
+            binaryMessenger: controller.binaryMessenger
+        )
         
         channel.setMethodCallHandler { [weak self] call, result in
             self?.handleMethodCall(call: call, result: result)
         }
+        downloadProgressEvents.setStreamHandler(
+            ClosureStreamHandler(
+                onListen: { [weak self] _, events in
+                    self?.startDownloadProgressStream(events)
+                    return nil
+                },
+                onCancel: { [weak self] _ in
+                    self?.stopDownloadProgressStream()
+                    return nil
+                }
+            )
+        )
+        libraryScanProgressEvents.setStreamHandler(
+            ClosureStreamHandler(
+                onListen: { [weak self] _, events in
+                    self?.startLibraryScanProgressStream(events)
+                    return nil
+                },
+                onCancel: { [weak self] _ in
+                    self?.stopLibraryScanProgressStream()
+                    return nil
+                }
+            )
+        )
         
         GeneratedPluginRegistrant.register(with: self)
         return super.application(application, didFinishLaunchingWithOptions: launchOptions)
     }
+
+    deinit {
+        stopDownloadProgressStream()
+        stopLibraryScanProgressStream()
+    }
+
+    private func startDownloadProgressStream(_ eventSink: @escaping FlutterEventSink) {
+        stopDownloadProgressStream()
+        downloadProgressEventSink = eventSink
+        lastDownloadProgressPayload = nil
+
+        let timer = DispatchSource.makeTimerSource(queue: streamQueue)
+        timer.schedule(deadline: .now(), repeating: .milliseconds(800))
+        timer.setEventHandler { [weak self] in
+            guard let self else { return }
+            let payload = GobackendGetAllDownloadProgress() as String? ?? "{}"
+            if payload == self.lastDownloadProgressPayload {
+                return
+            }
+            self.lastDownloadProgressPayload = payload
+            DispatchQueue.main.async { [weak self] in
+                self?.downloadProgressEventSink?(payload)
+            }
+        }
+        downloadProgressTimer = timer
+        timer.resume()
+    }
+
+    private func stopDownloadProgressStream() {
+        downloadProgressTimer?.setEventHandler {}
+        downloadProgressTimer?.cancel()
+        downloadProgressTimer = nil
+        downloadProgressEventSink = nil
+        lastDownloadProgressPayload = nil
+    }
+
+    private func startLibraryScanProgressStream(_ eventSink: @escaping FlutterEventSink) {
+        stopLibraryScanProgressStream()
+        libraryScanProgressEventSink = eventSink
+        lastLibraryScanProgressPayload = nil
+
+        let timer = DispatchSource.makeTimerSource(queue: streamQueue)
+        timer.schedule(deadline: .now(), repeating: .milliseconds(800))
+        timer.setEventHandler { [weak self] in
+            guard let self else { return }
+            let payload = GobackendGetLibraryScanProgressJSON() as String? ?? "{}"
+            if payload == self.lastLibraryScanProgressPayload {
+                return
+            }
+            self.lastLibraryScanProgressPayload = payload
+            DispatchQueue.main.async { [weak self] in
+                self?.libraryScanProgressEventSink?(payload)
+            }
+        }
+        libraryScanProgressTimer = timer
+        timer.resume()
+    }
+
+    private func stopLibraryScanProgressStream() {
+        libraryScanProgressTimer?.setEventHandler {}
+        libraryScanProgressTimer?.cancel()
+        libraryScanProgressTimer = nil
+        libraryScanProgressEventSink = nil
+        lastLibraryScanProgressPayload = nil
+    }
     
     private func handleMethodCall(call: FlutterMethodCall, result: @escaping FlutterResult) {
         DispatchQueue.global(qos: .userInitiated).async {
@@ -51,30 +160,6 @@ import Gobackend  // Import Go framework
             if let error = error { throw error }
             return response
             
-        case "getSpotifyMetadata":
-            let args = call.arguments as! [String: Any]
-            let url = args["url"] as! String
-            let response = GobackendGetSpotifyMetadata(url, &error)
-            if let error = error { throw error }
-            return response
-            
-        case "searchSpotify":
-            let args = call.arguments as! [String: Any]
-            let query = args["query"] as! String
-            let limit = args["limit"] as? Int ?? 10
-            let response = GobackendSearchSpotify(query, Int(limit), &error)
-            if let error = error { throw error }
-            return response
-            
-        case "searchSpotifyAll":
-            let args = call.arguments as! [String: Any]
-            let query = args["query"] as! String
-            let trackLimit = args["track_limit"] as? Int ?? 15
-            let artistLimit = args["artist_limit"] as? Int ?? 3
-            let response = GobackendSearchSpotifyAll(query, Int(trackLimit), Int(artistLimit), &error)
-            if let error = error { throw error }
-            return response
-            
         case "checkAvailability":
             let args = call.arguments as! [String: Any]
             let spotifyId = args["spotify_id"] as! String
@@ -127,6 +212,13 @@ import Gobackend  // Import Go framework
             GobackendSetDownloadDirectory(path, &error)
             if let error = error { throw error }
             return nil
+
+        case "setNetworkCompatibilityOptions", "setSongLinkNetworkOptions":
+            let args = call.arguments as! [String: Any]
+            let allowHTTP = args["allow_http"] as? Bool ?? false
+            let insecureTLS = args["insecure_tls"] as? Bool ?? false
+            GobackendSetNetworkCompatibilityOptions(allowHTTP, insecureTLS)
+            return nil
             
         case "checkDuplicate":
             let args = call.arguments as! [String: Any]
@@ -275,6 +367,14 @@ import Gobackend  // Import Go framework
             if let error = error { throw error }
             return response
 
+        case "getDeezerRelatedArtists":
+            let args = call.arguments as! [String: Any]
+            let artistId = args["artist_id"] as! String
+            let limit = args["limit"] as? Int ?? 12
+            let response = GobackendGetDeezerRelatedArtists(artistId, Int(limit), &error)
+            if let error = error { throw error }
+            return response
+
         case "getDeezerMetadata":
             let args = call.arguments as! [String: Any]
             let resourceType = args["resource_type"] as! String
@@ -283,6 +383,22 @@ import Gobackend  // Import Go framework
             if let error = error { throw error }
             return response
 
+        case "getQobuzMetadata":
+            let args = call.arguments as! [String: Any]
+            let resourceType = args["resource_type"] as! String
+            let resourceId = args["resource_id"] as! String
+            let response = GobackendGetQobuzMetadata(resourceType, resourceId, &error)
+            if let error = error { throw error }
+            return response
+
+        case "getTidalMetadata":
+            let args = call.arguments as! [String: Any]
+            let resourceType = args["resource_type"] as! String
+            let resourceId = args["resource_id"] as! String
+            let response = GobackendGetTidalMetadata(resourceType, resourceId, &error)
+            if let error = error { throw error }
+            return response
+
         case "parseDeezerUrl":
             let args = call.arguments as! [String: Any]
             let url = args["url"] as! String
@@ -290,6 +406,13 @@ import Gobackend  // Import Go framework
             if let error = error { throw error }
             return response
 
+        case "parseQobuzUrl":
+            let args = call.arguments as! [String: Any]
+            let url = args["url"] as! String
+            let response = GobackendParseQobuzURLExport(url, &error)
+            if let error = error { throw error }
+            return response
+
         case "parseTidalUrl":
             let args = call.arguments as! [String: Any]
             let url = args["url"] as! String
@@ -363,13 +486,6 @@ import Gobackend  // Import Go framework
             if let error = error { throw error }
             return response
             
-        case "getAmazonURLFromDeezerTrack":
-            let args = call.arguments as! [String: Any]
-            let deezerTrackId = args["deezer_track_id"] as! String
-            let response = GobackendGetAmazonURLFromDeezerTrack(deezerTrackId, &error)
-            if let error = error { throw error }
-            return response
-            
         case "preWarmTrackCache":
             let args = call.arguments as! [String: Any]
             let tracksJson = args["tracks"] as! String
@@ -385,17 +501,6 @@ import Gobackend  // Import Go framework
             GobackendClearTrackCache()
             return nil
             
-        case "setSpotifyCredentials":
-            let args = call.arguments as! [String: Any]
-            let clientId = args["client_id"] as! String
-            let clientSecret = args["client_secret"] as! String
-            GobackendSetSpotifyAPICredentials(clientId, clientSecret)
-            return nil
-            
-        case "hasSpotifyCredentials":
-            let hasCredentials = GobackendCheckSpotifyCredentials()
-            return hasCredentials
-            
         // Log methods
         case "getLogs":
             let response = GobackendGetLogs()
@@ -518,6 +623,20 @@ import Gobackend  // Import Go framework
             let response = GobackendSearchTracksWithExtensionsJSON(query, Int(limit), &error)
             if let error = error { throw error }
             return response
+
+        case "searchTracksWithMetadataProviders":
+            let args = call.arguments as! [String: Any]
+            let query = args["query"] as! String
+            let limit = args["limit"] as? Int ?? 20
+            let includeExtensions = args["include_extensions"] as? Bool ?? true
+            let response = GobackendSearchTracksWithMetadataProvidersJSON(
+                query,
+                Int(limit),
+                includeExtensions,
+                &error
+            )
+            if let error = error { throw error }
+            return response
             
         case "enrichTrackWithExtension":
             let args = call.arguments as! [String: Any]
@@ -709,6 +828,23 @@ import Gobackend  // Import Go framework
             if let error = error { throw error }
             return nil
             
+        case "setStoreRegistryUrl":
+            let args = call.arguments as! [String: Any]
+            let registryUrl = args["registry_url"] as? String ?? ""
+            GobackendSetStoreRegistryURLJSON(registryUrl, &error)
+            if let error = error { throw error }
+            return nil
+            
+        case "getStoreRegistryUrl":
+            let response = GobackendGetStoreRegistryURLJSON(&error)
+            if let error = error { throw error }
+            return response
+            
+        case "clearStoreRegistryUrl":
+            GobackendClearStoreRegistryURLJSON(&error)
+            if let error = error { throw error }
+            return nil
+            
         case "getStoreExtensions":
             let args = call.arguments as! [String: Any]
             let forceRefresh = args["force_refresh"] as? Bool ?? false
@@ -793,6 +929,26 @@ import Gobackend  // Import Go framework
             let response = GobackendReadAudioMetadataJSON(filePath, &error)
             if let error = error { throw error }
             return response
+        
+        // iOS Security-Scoped Bookmark for Local Library
+        case "resolveIosBookmark":
+            let args = call.arguments as! [String: Any]
+            let bookmarkBase64 = args["bookmark"] as! String
+            return try resolveIosBookmark(bookmarkBase64)
+            
+        case "startAccessingIosBookmark":
+            let args = call.arguments as! [String: Any]
+            let bookmarkBase64 = args["bookmark"] as! String
+            return try startAccessingIosBookmark(bookmarkBase64)
+            
+        case "stopAccessingIosBookmark":
+            stopAccessingIosBookmark()
+            return nil
+            
+        case "createIosBookmarkFromPath":
+            let args = call.arguments as! [String: Any]
+            let path = args["path"] as! String
+            return try createIosBookmarkFromPath(path)
             
         // Lyrics Provider Settings
         case "setLyricsProviders":
@@ -824,6 +980,15 @@ import Gobackend  // Import Go framework
             if let error = error { throw error }
             return response
             
+        // CUE Sheet Parsing
+        case "parseCueSheet":
+            let args = call.arguments as! [String: Any]
+            let cuePath = args["cue_path"] as! String
+            let audioDir = args["audio_dir"] as? String ?? ""
+            let response = GobackendParseCueSheet(cuePath, audioDir, &error)
+            if let error = error { throw error }
+            return response
+            
         default:
             throw NSError(
                 domain: "SpotiFLAC",
@@ -832,4 +997,134 @@ import Gobackend  // Import Go framework
             )
         }
     }
+    
+    // MARK: - iOS Security-Scoped Bookmark Helpers
+    
+    /// Create a security-scoped bookmark from a filesystem path (e.g. from FilePicker).
+    /// The path must currently be accessible (within the same picker session).
+    /// Returns base64-encoded bookmark data.
+    private func createIosBookmarkFromPath(_ path: String) throws -> String {
+        let url = URL(fileURLWithPath: path)
+        do {
+            let bookmarkData = try url.bookmarkData(
+                options: .minimalBookmark,
+                includingResourceValuesForKeys: nil,
+                relativeTo: nil
+            )
+            return bookmarkData.base64EncodedString()
+        } catch {
+            throw NSError(
+                domain: "SpotiFLAC",
+                code: -1,
+                userInfo: [NSLocalizedDescriptionKey: "Failed to create bookmark for path \(path): \(error.localizedDescription)"]
+            )
+        }
+    }
+    
+    /// Resolve a base64-encoded security-scoped bookmark and return the resolved path.
+    /// Does NOT start accessing the resource.
+    private func resolveIosBookmark(_ bookmarkBase64: String) throws -> String {
+        guard let bookmarkData = Data(base64Encoded: bookmarkBase64) else {
+            throw NSError(
+                domain: "SpotiFLAC",
+                code: -1,
+                userInfo: [NSLocalizedDescriptionKey: "Invalid base64 bookmark data"]
+            )
+        }
+        
+        var isStale = false
+        let url: URL
+        do {
+            url = try URL(
+                resolvingBookmarkData: bookmarkData,
+                options: [],
+                relativeTo: nil,
+                bookmarkDataIsStale: &isStale
+            )
+        } catch {
+            throw NSError(
+                domain: "SpotiFLAC",
+                code: -1,
+                userInfo: [NSLocalizedDescriptionKey: "Failed to resolve bookmark: \(error.localizedDescription)"]
+            )
+        }
+        
+        return url.path
+    }
+    
+    /// Resolve a base64-encoded bookmark, start accessing the security-scoped resource,
+    /// and return the resolved filesystem path. The resource stays accessed until
+    /// `stopAccessingIosBookmark()` is called.
+    private func startAccessingIosBookmark(_ bookmarkBase64: String) throws -> String {
+        // Stop any previously accessed resource first
+        stopAccessingIosBookmark()
+        
+        guard let bookmarkData = Data(base64Encoded: bookmarkBase64) else {
+            throw NSError(
+                domain: "SpotiFLAC",
+                code: -1,
+                userInfo: [NSLocalizedDescriptionKey: "Invalid base64 bookmark data"]
+            )
+        }
+        
+        var isStale = false
+        let url: URL
+        do {
+            url = try URL(
+                resolvingBookmarkData: bookmarkData,
+                options: [],
+                relativeTo: nil,
+                bookmarkDataIsStale: &isStale
+            )
+        } catch {
+            throw NSError(
+                domain: "SpotiFLAC",
+                code: -1,
+                userInfo: [NSLocalizedDescriptionKey: "Failed to resolve bookmark: \(error.localizedDescription)"]
+            )
+        }
+        
+        guard url.startAccessingSecurityScopedResource() else {
+            throw NSError(
+                domain: "SpotiFLAC",
+                code: -1,
+                userInfo: [NSLocalizedDescriptionKey: "Failed to start accessing security-scoped resource at \(url.path)"]
+            )
+        }
+        
+        activeSecurityScopedURL = url
+        return url.path
+    }
+    
+    /// Stop accessing the currently active security-scoped resource, if any.
+    private func stopAccessingIosBookmark() {
+        if let url = activeSecurityScopedURL {
+            url.stopAccessingSecurityScopedResource()
+            activeSecurityScopedURL = nil
+        }
+    }
+}
+
+private final class ClosureStreamHandler: NSObject, FlutterStreamHandler {
+    typealias ListenHandler = (_ arguments: Any?, _ events: @escaping FlutterEventSink) -> FlutterError?
+    typealias CancelHandler = (_ arguments: Any?) -> FlutterError?
+
+    private let onListenHandler: ListenHandler
+    private let onCancelHandler: CancelHandler
+
+    init(
+        onListen: @escaping ListenHandler,
+        onCancel: @escaping CancelHandler = { _ in nil }
+    ) {
+        self.onListenHandler = onListen
+        self.onCancelHandler = onCancel
+    }
+
+    func onListen(withArguments arguments: Any?, eventSink events: @escaping FlutterEventSink) -> FlutterError? {
+        onListenHandler(arguments, events)
+    }
+
+    func onCancel(withArguments arguments: Any?) -> FlutterError? {
+        onCancelHandler(arguments)
+    }
 }

ios/Runner/Info.plist

@@ -105,5 +105,11 @@
 		<string>tidal</string>
 		<string>youtube-music</string>
 	</array>
+	
+	<!-- Background audio playback -->
+	<key>UIBackgroundModes</key>
+	<array>
+		<string>audio</string>
+	</array>
 </dict>
 </plist>

lib/app.dart

@@ -17,7 +17,6 @@ final _routerProvider = Provider<GoRouter>((ref) {
     settingsProvider.select((s) => s.hasCompletedTutorial),
   );
 
-  // Determine initial location based on app state
   String initialLocation;
   if (isFirstLaunch) {
     initialLocation = '/setup';
@@ -37,6 +36,9 @@ final _routerProvider = Provider<GoRouter>((ref) {
         builder: (context, state) => const TutorialScreen(),
       ),
     ],
+    // Safety net: if a deep link URL (e.g. Spotify/Deezer) somehow reaches
+    // GoRouter, redirect to home instead of showing "Page Not Found".
+    errorBuilder: (context, state) => const MainShell(),
   );
 });
 
@@ -54,10 +56,14 @@ class SpotiFLACApp extends ConsumerWidget {
         : null;
 
     Locale? locale;
-    if (localeString != 'system') {
+    if (localeString != 'system' && localeString.isNotEmpty) {
       if (localeString.contains('_')) {
         final parts = localeString.split('_');
-        locale = Locale(parts[0], parts[1]);
+        if (parts.length == 2) {
+          locale = Locale(parts[0], parts[1]);
+        } else {
+          locale = Locale(parts[0]);
+        }
       } else {
         locale = Locale(localeString);
       }
@@ -76,6 +82,25 @@ class SpotiFLACApp extends ConsumerWidget {
           themeAnimationCurve: Curves.easeInOut,
           routerConfig: router,
           locale: locale,
+          localeResolutionCallback: (deviceLocale, supportedLocales) {
+            if (locale != null) return locale;
+            if (deviceLocale == null) return supportedLocales.first;
+
+            for (var supportedLocale in supportedLocales) {
+              if (supportedLocale.languageCode == deviceLocale.languageCode &&
+                  supportedLocale.countryCode == deviceLocale.countryCode) {
+                return supportedLocale;
+              }
+            }
+
+            for (var supportedLocale in supportedLocales) {
+              if (supportedLocale.languageCode == deviceLocale.languageCode) {
+                return supportedLocale;
+              }
+            }
+
+            return supportedLocales.first;
+          },
           localizationsDelegates: const [
             AppLocalizations.delegate,
             GlobalMaterialLocalizations.delegate,

lib/constants/app_info.dart

@@ -1,9 +1,14 @@
+import 'package:flutter/foundation.dart';
+
 /// App version and info constants
 /// Update version here only - all other files will reference this
 class AppInfo {
-  static const String version = '3.6.9';
-  static const String buildNumber = '82';
+  static const String version = '3.8.8';
+  static const String buildNumber = '114';
   static const String fullVersion = '$version+$buildNumber';
+
+  /// Shows "Internal" in debug builds, actual version in release.
+  static String get displayVersion => kDebugMode ? 'Internal' : version;
   
   
   static const String appName = 'SpotiFLAC';