fix(ios): remove stale built-in Spotify bridge handlers

docs: add centered Trendshift badge below README banner
Merge branch 'dev'
2026-07-02 19:05:57 +02:00 · 2026-03-11 17:08:46 +07:00 · 2026-03-11 17:08:45 +07:00 · 2026-03-11 16:42:09 +07:00 · 2026-03-11 16:27:13 +07:00 · 2026-03-11 15:56:42 +07:00
227 changed files with 84896 additions and 48810 deletions
@@ -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
@@ -1,4 +1,3 @@
 github: zarzet
 ko_fi: zarzet
-buy_me_a_coffee: zarzet

@@ -0,0 +1,44 @@
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'site/**'
+      - '.github/workflows/pages.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
@@ -71,7 +71,7 @@ jobs:
      - name: Setup Go
        uses: actions/setup-go@v6
        with:
-          go-version: "1.25"
+          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.25"
+          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,13 @@ 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 }}"
-          
+
+          # Start with git-cliff changelog
+          cp /tmp/changelog.txt /tmp/release_body.txt
+
+          # Append download section
          cat >> /tmp/release_body.txt << FOOTER

          ---
@@ -404,6 +392,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 +407,40 @@ 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 '/^\*\*Full Changelog\*\*/d' | \
+              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
@@ -12,6 +12,9 @@ Thumbs.db
 # Kiro specs (development only)
 .kiro/

+# Design assets (banners, mockups)
+design/
+
 # Reference folder (development only)
 referensi/

@@ -1,5 +1,569 @@
 # 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
+
+- **YouTube Bitrate Presets**: YouTube bitrate selection now uses supported presets only
+  - Opus: 128 / 256 kbps
+  - MP3: 128 / 256 / 320 kbps
+- **Go Test Coverage for YouTube Quality Parsing**: Added tests for supported-bitrate normalization behavior
+- **Localization for YouTube Bitrate UI**: Added localized strings (EN/ID) for YouTube bitrate titles and labels
+
+### Fixed
+
+- **Cover Image Cache Clear Not Working**: Clearing "Cover image cache" now performs a full on-disk wipe, clears in-memory image cache, and reinitializes cache manager state
+  - Prevents stale/orphaned cache files from keeping the same storage usage after clear
+- **YouTube Queue Fallback Quality Mismatch**: Queue fallback now normalizes YouTube quality IDs so conversion paths use valid bitrate format IDs
+
+### Changed
+
+- **Default Lyrics Behavior**: `Apple/QQ Multi-Person Word-by-Word` is now OFF by default for new installs
+- **Removed Dynamic YouTube Bitrate Mode**: Arbitrary values are now normalized to nearest supported Spotube preset across settings, picker, queue fallback, and Go backend parser
+- **Lyrics Embedding Control**: Users can now disable the embedded-lyrics process from settings (`Embed Lyrics` off)
+
+---
+
+## [3.6.8] - 2026-02-14
+
+### Added
+
+- **Lyrics Source Tracking**: Track Metadata screen now displays the source of loaded lyrics (LRCLIB, Musixmatch, Netease, Apple Music, QQ Music, Embedded, or Extension)
+  - New `getLyricsLRCWithSource` API returns lyrics with source metadata
+  - Source badge appears below lyrics section in Track Metadata screen
+- **Dedicated Lyrics Provider Priority Page**: Lyrics providers can now be configured from a dedicated settings page with full-screen reorderable list
+  - Replaced inline bottom sheet with `LyricsProviderPriorityPage`
+  - Cleaner UI with provider descriptions and priority ordering
+- **Paxsenix Integration**: Added Paxsenix API as official lyrics proxy partner for Apple Music, QQ Music, Musixmatch, and Netease sources
+  - Listed in About page and Partners page on project site
+  - README updated with partner attribution
+
+### Fixed
+
+- **LRC Background Vocal Preservation**: Apple Music/QQ Music `[bg:...]` background vocal tags are now preserved during LRC parsing instead of being stripped
+  - Background vocals attach to the previous timed line in exported LRC files
+- **LRC Display Improvements**:
+  - Inline word-by-word timestamps (`<mm:ss.xx>`) are stripped from lyrics display
+  - Speaker prefixes (`v1:`, `v2:`) are removed for cleaner display
+  - Multi-line background vocals converted to readable secondary vocal lines
+- **Apple Music Lyrics Case Sensitivity**: Fixed `lyricsType` comparison to use case-insensitive matching for "Syllable" type
+
+### Changed
+
+- Track Metadata lyrics fetching now uses `getLyricsLRCWithSource` for consistent source attribution across embedded and online lyrics
+
+---
+
+## [3.6.7] - 2026-02-13
+
+### Added
+
+- "Advanced Filename Templates" - new placeholders for custom track/disc formatting and date patterns
+  - `{track_raw}` and `{disc_raw}` - unpadded raw numbers
+  - `{track:N}` and `{disc:N}` - zero-padded to N digits (e.g. `{track:02}` → `01`)
+  - `{date}` - full release date from metadata
+  - `{date:%Y-%m-%d}` - date formatting with strftime patterns
+  - "Show advanced tags" toggle in Settings > Download > Filename Format to reveal these placeholders
+- Low-RAM / ARM32-only device profiling - detects constrained devices at startup and reduces image cache (120 items / 24 MiB) and disables overscroll effects for smoother performance
+- Responsive selection bar on artist screen - switches to compact stacked layout on narrow screens (< 430dp) or large text scale (> 1.15x)
+- Quality picker dialog before downloading individual tracks from artist screen (when "Ask quality before download" is enabled)
+- Project website with GitHub Pages deployment workflow
+  - Mobile burger menu navigation for all site pages
+- Go filename template test suite
+- "Lyrics Provider" extension type - extensions can now provide lyrics (synced or plain text) via `fetchLyrics()` function
+  - Lyrics provider extensions are called before built-in providers, giving extensions highest priority
+  - New `lyrics_provider` manifest type alongside `metadata_provider` and `download_provider`
+  - Shows "Lyrics Provider" capability badge on extension detail page
+- "Lyrics Providers" settings - configurable provider cascade order and per-provider options
+  - Reorderable provider list: LRCLIB, Musixmatch, Netease, Apple Music, QQ Music
+  - Netease: toggle translated/romanized lyrics appending
+  - Apple Music / QQ Music: multi-person word-by-word speaker tags
+  - Musixmatch: selectable language code for localized lyrics
+- "Documentation Search" - global search modal on all site pages
+  - Opens with Ctrl+K / Cmd+K / `/` keyboard shortcuts on every page
+  - Search button with bordered pill styling in desktop nav and mobile hamburger menu
+  - On non-docs pages, search results navigate to the docs page at the matching section
+  - Full keyboard navigation: arrow keys, Enter to select, Esc to close
+
+### Fixed
+
+- Fixed ICU plural syntax errors in DE, ES, PT, RU translations - incorrect `=1` clause was causing missing plural forms
+- Fixed featured-artist regex incorrectly splitting on `&` character (e.g. "Simon & Garfunkel" was being split) - removed `&` from separator pattern
+- Fixed `{date}` placeholder not working in filename templates - release date was not being passed to the template builder across all providers (Amazon, Qobuz, Tidal, YouTube, extensions)
+
+### Changed
+
+- Improved Go backend metadata handling - filename builder now supports fallback metadata keys and automatic type conversion for more robust template rendering
+- Extension providers now pass full metadata set to filename builder (track, disc, year, date, release_date)
+- Updated translations: added filename advanced tags strings (EN, ID), regenerated all locale dart files
+- Updated app screenshot assets
+
+---
+
+## [3.6.6] - 2026-02-12
+
+### Added
+
+- "Filter Contributing Artists in Album Artist" setting - strips featured/contributing artists from Album Artist metadata tag
+- Library scan notifications (Android and iOS) - shows progress, completion, failure, and cancellation status
+- Collapsible "Artist Name Filters" section in download settings UI
+
+### Fixed
+
+- Fixed downloads not working on iOS - missing `downloadByStrategy` and `downloadFromYouTube` method channel handlers in AppDelegate.swift
+- Fixed extended metadata (genre, label, copyright) lost during service fallback (e.g. Tidal unavailable, falls back to Qobuz) - Go backend now enriches metadata from Deezer by ISRC before download and preserves it through the fallback chain
+- Fixed local library showing incorrect "16-bit" quality label for lossy formats (MP3, Opus) - now displays actual bitrate (e.g. "MP3 320kbps")
+- Fixed inaccurate Opus/Vorbis duration calculation (e.g. 4:11 showing as 8:44) - now reads granule position from last Ogg page for precise duration
+- Fixed MP3 duration/bitrate inaccuracy for VBR files - added Xing/Info and VBRI header parsing with MPEG2/2.5 bitrate table support
+- Fixed Track Metadata screen showing scan date instead of file date for local library items
+- Fixed SAF content URI paths displayed as raw `content://` strings in Track Metadata - now shows human-readable paths
+
+### Changed
+
+- Removed legacy iOS download handlers (`downloadTrack`, `downloadWithFallback`, `downloadFromYouTube`) - iOS now uses `downloadByStrategy` only
+- Updated translations from Crowdin (all 14 languages)
+
+---
+
+## [3.6.5] - 2026-02-10
+
+### Highlights
+
+- **Audio Format Conversion**: Convert between FLAC, MP3, and Opus directly from Track Metadata screen with full metadata and cover art preservation
+- **PC v7.0.8 Backend Merge**: Adopts several Go backend improvements from SpotiFLAC PC v7.0.8 including Amazon encrypted stream support, SpotFetch metadata fallback, and Qobuz API update
+- **Amazon Music Re-enabled**: Amazon provider back in service with new API
+
+### Added
+
+- "Use Primary Artist Only" setting: strips featured artists from folder names (e.g. "Justin Bieber, Quavo" becomes "Justin Bieber") for cleaner folder organization
+  - Supports separators: `, ` `;` `&` `feat.` `ft.` `featuring` `with` `x`
+  - Available in Settings > Download > below "Use Album Artist for folders"
+- Audio format conversion from Track Metadata screen
+  - Convert between FLAC, MP3, and Opus formats (any direction)
+  - Selectable bitrate: 128k, 192k, 256k, 320k
+  - Full metadata and cover art preservation during conversion
+  - Confirmation dialog before converting (original file deleted after)
+  - SAF storage support: copies to temp, converts, writes back via SAF
+  - Download history automatically updated with new file path
+- Unified download request contract (`DownloadRequestPayload`) for all providers/flows
+  - Includes full superset fields: lyrics mode, genre/label/copyright, provider IDs, SAF params, cover/quality settings
+  - Added strategy flags in payload: `use_extensions`, `use_fallback`
+- New Go unified router entrypoint: `DownloadByStrategy(requestJSON)`
+  - 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`
+  - 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
+- Edit Metadata now supports manual cover selection (pick/replace cover image) and embeds it into audio tags on save
+- Save Lyrics now shows an immediate in-progress snackbar (`Saving lyrics...`) so users know the operation has started
+
+### Changed
+
+- Merged several Go backend improvements from SpotiFLAC PC v7.0.8: Amazon new API with encrypted stream/decryption support, SpotFetch metadata fallback for Spotify-blocked regions, multi-format lyrics extraction (MP3/Opus/OGG), Qobuz Jumo API update.
+- Download queue execution now builds one payload and uses a single bridge entrypoint (`PlatformBridge.downloadByStrategy`) instead of branching into multiple bridge methods
+- Dart `downloadByStrategy` now sends a single request to Go (`downloadByStrategy` channel); routing concern is centralized in Go backend
+- 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 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
+- Edit Metadata cover section moved to the top of the form and now previews current embedded cover before replacement (plus selected replacement preview)
+- Edit Metadata cover preview enlarged (120px to 160px) with shadow, side-by-side layout for current vs selected cover, and label repositioned below image
+
+### Fixed
+
+- Fixed lyrics mode "External .LRC" still embedding lyrics into metadata - `lyrics_mode` was not being sent to Go backend for single-service downloads and YouTube provider, causing Go to default to "embed"
+- Fixed `flutter_local_notifications` v20 breaking changes - migrated all `initialize()`, `show()`, and `cancel()` calls from positional parameters to named parameters
+- Fixed SAF duplicate folder bug: concurrent batch downloads creating empty folders with `(1)`, `(2)`, `(3)` suffixes - added synchronized lock to `ensureDocumentDir` in Kotlin with duplicate detection and cleanup
+- Track Metadata lyrics section now hides "Embed Lyrics" when lyrics are already embedded in file, preventing redundant embed attempts
+- Fixed lyrics embed path to support FLAC/MP3/Opus consistently (including SAF files) without forcing unsupported parser paths
+- Inconsistent parameter parity across download paths
+  - `downloadWithExtensions` now carries `copyright`
+  - YouTube path now carries `embed_max_quality_cover` and metadata parity fields
+- Inconsistent success response metadata between direct/fallback flows
+  - Added shared Go response builder for `DownloadTrack` and `DownloadWithFallback`
+  - Success responses now consistently include `genre`, `label`, `copyright`, and `lyrics_lrc`
+- YouTube success response now also includes extended metadata fields (`cover_url`, `genre`, `label`, `copyright`) for parity with other providers
+- Fixed `Save Lyrics` crash on Android (`java.lang.Integer cannot be cast to java.lang.Long`) by normalizing `duration_ms` channel argument as `Number -> Long`
+- Fixed FLAC Re-enrich cover edge case where metadata could be written without cover when temp cover file creation failed; FLAC cover embed now uses in-memory bytes and verifies cover after write
+- Fixed FLAC picture-block embed robustness by detecting image MIME via magic bytes (JPEG/PNG/GIF/WEBP) instead of relying on filename extension
+- Fixed MP3/Opus metadata rewrite flows to preserve existing embedded cover when no new cover is available
+- Fixed Library tab cover not updating after manual cover edit/re-embed for downloaded tracks
+  - Queue/Library now prefers embedded cover art extracted from local files (not just cached `coverUrl`)
+  - Added per-track extraction cache with file-modification invalidation so updated embedded art is reflected in Library
+  - Extraction is now on-demand for edited tracks only (not full-library reload)
+  - Returning from Track Metadata now refreshes cover cache only for the affected track
+  - Cover refresh is now skipped when file modification time is unchanged, removing unnecessary flash when simply opening/closing metadata screen
+- Fixed repeated cover preview extraction in Track Metadata screen (`track_cover_preview_*`) causing visible flash when reopening
+  - Added in-memory preview cache keyed by file path so reopening metadata reuses existing preview without re-extract
+  - Cache validation uses file modification time for filesystem paths; SAF paths are refreshed only after successful edit actions
+  - Queue/Library now also compares SAF file last-modified (`getSafFileModTimes`) before refreshing embedded-cover cache
+  - Preview cache key is now stable per track item (not volatile temp SAF path), eliminating false cache misses on SAF-backed files
+  - Track Metadata no longer auto-extracts cover preview on every screen open; extraction now runs only after actual edit/re-enrich changes (or when explicitly forced)
+- Track metadata edits/re-enrich now sync updated tags back into `downloadHistoryProvider` + SQLite history rows
+  - Non-Library screens that read download history (Home/album/history views) now reflect updated title/artist/album/tags without manual rescan
+  - Track Metadata back-navigation now returns an explicit update result after successful edits/re-enrich, enabling History-tab cover refresh fallback when SAF timestamps are unreliable
+
+### Performance
+
+- Configured Flutter image cache limits (240 entries / 60 MiB) and added `ResizeImage` wrappers for cover art precaching across all screens, reducing peak memory usage on cover-heavy pages
+- Added LRU eviction to Deezer cache with configurable max entries per cache type (search/album/artist/ISRC) and periodic expired-entry cleanup to prevent unbounded memory growth in long sessions
+- Download progress notifications are now normalized (2-decimal progress, 1-decimal speed, 0.1 MiB byte steps) and deduplicated by track/artist/percent/queue-count, reducing notification overhead during batch downloads
+- Each queue item now uses a dedicated `ConsumerWidget` with per-item `.select()` instead of rebuilding the entire list on any item change; items are wrapped in `RepaintBoundary` for paint isolation
+- Queue/Library search indexes are now built on-demand per item instead of upfront for all items, with bounded LRU caches (max 4000 entries)
+- `copyWith` now preserves derived lookup indexes (ISRC map, track key set) when items list is unchanged, avoiding O(n) rebuild on every scan progress update
+- Scan progress polling now compares values before calling `setState`, skipping unnecessary widget rebuilds when nothing changed
+- Added in-flight flag to download progress and library scan polling to prevent concurrent timer callbacks from overlapping
+- New `DownloadedEmbeddedCoverResolver` service replaces per-screen cover extraction logic with a shared bounded cache (160 entries), mod-time validation, and throttled refresh checks
+- Multiple embedded cover change callbacks are now coalesced into a single frame via `addPostFrameCallback`, preventing redundant rebuilds
+- Downloaded album screen now caches filtered/sorted track lists and reuses them when the source data reference is unchanged
+- Home tab recent downloads now use single-pass aggregation instead of building full per-album lists, and store only IDs instead of full item objects for the clear-all action
+- Removed duplicate `_downloadedSpotifyIds` Set and `_isrcSet` (both now use existing map lookups), removed unused `_isTyping` state in home tab
+- Track cache pre-warming is now capped at 80 tracks per request to avoid excessive backend calls on large playlists
+- About page contributor avatars now use `memCacheWidth`/`memCacheHeight` to decode at display size instead of full resolution
+- Orphaned download cleanup now checks file existence in parallel (chunk 16) instead of sequentially
+- Local library `findByTrackAndArtist` now uses O(1) map lookup (`_byTrackKey`) instead of O(n) linear scan
+- Local library database load and SharedPreferences fetch now run in parallel
+- Legacy mod-time backfill now uses chunked parallel `File.stat` (chunk 24) with per-chunk cancel check
+- Downloaded album screen now caches disc grouping, sorted disc numbers, common quality, and embedded cover path with reference-identity invalidation
+- Local album screen common quality is now computed once during cache rebuild instead of per-build
+- Batch delete in album screens now uses O(1) map lookup (`tracksById`) instead of `.where().firstOrNull`
+- Cache management page now fires all async init calls in parallel and uses chunked async directory deletion (chunk 24)
+- Cover resolver preview file existence check is now throttled (2.2s interval) to reduce synchronous I/O in build path
+- History and library database DELETE operations are now chunked (500 per batch) to stay within SQLite variable limits
+- Library database `cleanupMissingFiles` now checks file existence in parallel (chunk 16) and deletes in batched SQL
+
+### Security
+
+- All logs (Go and Dart) now automatically redact Bearer tokens, access/refresh tokens, client secrets, API keys, and passwords using regex-based sanitization before storage
+- Extension auth URLs are now validated for HTTPS-only, no embedded credentials, and no private/local network targets before opening
+- Auth URLs in logs are summarized to scheme+host+path only (query params stripped) to prevent token leakage; token exchange error bodies are truncated and sanitized
+- Extension HTTP requests now block URLs with embedded credentials (`user:pass@host`)
+- Extension storage files changed from `0644` to `0600` (owner-only read/write)
+- All SAF relative directory paths are now sanitized per-segment with `.`/`..` filtering; all user-provided file names pass through `sanitizeFilename()` before use
+- Extension ID is sanitized before building download destination path
+- Log export device info now shows Build ID and Security Patch level instead of masked Device ID
+
+### Technical
+
+- Centralized request serialization in `PlatformBridge` via shared invoke helper and unified payload model
+- Go strategy router normalizes incoming service casing before dispatch
+- Extension runtime: `customSearch` now passes query/options via VM globals instead of string interpolation, preventing parser edge cases on certain devices
+- Extension runtime: JS panic handler now logs full stack trace for easier debugging
+- `DownloadQueueLookup` expanded with `byItemId` map and `itemIds` list for O(1) queue item access from UI
+- Non-error/non-fatal log entries are now skipped entirely (not just hidden) when detailed logging is disabled, reducing buffer growth and Go log polling overhead
+
+### Removed
+
+- Buy Me a Coffee references removed from donate page, FUNDING.yml, README, and all localization files (account suspended)
+
+---
+
+## [3.6.0] - 2026-02-09
+
+### Highlights
+
+- **YouTube Provider (Lossy)**: New download option via Cobalt API for tracks not available on lossless services
+  - Opus 256kbps (recommended) or MP3 320kbps quality options
+  - Full metadata embedding: cover art, title, artist, album, track/disc number, year, ISRC
+  - Lyrics fetching from lrclib.net with embed and external .lrc support
+  - Works as fallback when Tidal/Qobuz/Amazon downloads fail
+- **Edit Metadata**: Edit embedded metadata directly from the Track Metadata screen (FLAC, MP3, Opus)
+  - Editable fields: Title, Artist, Album, Album Artist, Date, Track#, Disc#, Genre, ISRC
+  - Advanced fields: Label, Copyright, Composer, Comment
+  - FLAC: native Go writer, MP3/Opus: FFmpeg-based writer
+  - UI refreshes in-place after save without needing to re-open the screen
+  - iOS and Android support
+
+### Added
+
+- Save Cover Art: download high-quality album art as standalone .jpg from track metadata screen
+- Save Lyrics (.lrc): fetch and save lyrics as standalone .lrc file without downloading the song
+- Re-enrich Metadata: re-embed metadata, cover art, and lyrics into existing audio files without re-downloading (FLAC native, MP3/Opus via FFmpeg)
+- Re-enrich now supports local library items: searches Spotify/Deezer by track name + artist to fetch complete metadata from the internet, then embeds cover art, lyrics, genre, label, and all tags into the file
+- YouTube download provider using Cobalt API with SongLink/Odesli integration for Spotify/Deezer ID → YouTube URL conversion
+- SpotubeDL as fallback Cobalt proxy when primary API fails
+- YouTube video ID detection for YT Music extension compatibility
+- Parallel cover art and lyrics fetching during YouTube download
+- Queue progress now shows "X.X MB" instead of "0%" for streaming downloads where total size is unknown (Cobalt tunnel mode)
+- Full metadata pipeline for YouTube downloads: cover art, lyrics, title, artist, album, track#, disc#, year, ISRC
+
+### Changed
+
+- Removed Tidal HIGH (lossy AAC) quality option - use YouTube provider for lossy downloads instead
+- Simplified download service picker by removing dead lossy format code
+- Removed Amazon from download settings UI (now only used as automatic fallback)
+- Cleaned up dead disabled-chip code in download service selector
+
+### Fixed
+
+- Fixed `error.api.youtube.login` by using YouTube Music URLs instead of regular YouTube URLs for Cobalt requests
+- Fixed SongLink to prioritize `youtubeMusic` platform URL over `youtube` for Cobalt compatibility
+- Fixed YouTube metadata not being overwritten by setting `DisableMetadata: true` in Cobalt requests
+- Fixed ISRC validation in metadata enrichment flow - invalid ISRCs no longer trigger failed Deezer lookups
+- Fixed YouTube metadata enrichment to work like other providers (SongLink Deezer ID extraction, proper metadata embedding)
+- Go metadata parsers now read Composer, Comment, Label, Copyright from FLAC, MP3 (ID3v2.2/v2.3/v2.4), and Opus/OGG files
+- Added proper COMM frame parser for ID3v2 (handles language code + description prefix correctly)
+- Fixed Re-enrich Metadata failing on SAF storage files (`content://` URIs) - Kotlin now copies SAF file to temp, Go processes temp file, then writes back for FLAC or returns temp path for FFmpeg (MP3/Opus)
+- Fixed Save Cover Art and Save Lyrics crashing on SAF-stored download history items - now saves to temp then writes to SAF tree via `createSafFileFromPath`
+- Fixed `_getFileDirectory()` crash when called with `content://` URI by adding SAF guard
+- Fixed `readAudioMetadata` Kotlin handler not handling SAF URIs - now copies to temp for reading
+- Added metadata summary log in Re-enrich flow showing all fields before embedding (title, artist, album, track#, disc#, date, ISRC, genre, label)
+
+---
+
+## [3.5.3] - 2026-02-09
+
+### Added
+
+- CSV import flow now includes a new option: **Skip already downloaded songs** before enqueueing tracks
+- Added regression test suite for cross-script matching behavior in Go backend (`go_backend/matching_test.go`)
+
+### Changed
+
+- CSV import confirmation dialog now supports filtering out tracks already present in download history (matched by Spotify ID and ISRC)
+- CSV import enqueue feedback now reports added/skipped counts when duplicate downloads are skipped
+- Home search now prioritizes **Recent Access** when search field is focused with empty input, even if old search results still exist in memory
+- Search filter/result sections are now hidden while Recent Access mode is active to avoid stale-result overlap
+- Recent Access now shows a localized empty-state message when no recent items are available
+- Normalized collapsing AppBar top inset across iOS/Android so header height/animation stays visually consistent on Apple devices
+- Storage & Cache UX improved: `Clear all cache` now preserves web/runtime cache by default (optional), with explicit warnings/actions for runtime cache resets
+- Local library settings now include a display count for tracks excluded because they already exist in download history
+- Responsive layout tuning applied across key screens to reduce hardcoded-height overflow issues on smaller devices
+
+### Fixed
+
+- Fixed false-positive cross-script matching in Qobuz/Tidal where unrelated titles/artists in different scripts could be incorrectly accepted
+- Cross-script title/artist matching now requires transliteration-aware normalization and strict similarity checks instead of auto-accepting script differences
+- Qobuz metadata fallback no longer scans all results when zero title matches are found; title verification is now required
+- Qobuz metadata final validation now rejects results when title does not match expected track name
+- Fixed Home search regression where Recent Access panel could disappear after previous searches
+- Fixed Local Library card/layout crash caused by `Flex` usage under unbounded height constraints
+- Hardened FFmpeg metadata embedding temp-file naming to prevent rare collisions during parallel downloads/fallback flows (Qobuz → Tidal) that could cause missing embedded metadata
+- Fixed SAF external lyrics naming where some providers saved `.lrc` files as `.lrc.txt`; LRC export now uses neutral MIME to preserve `.lrc` extension
+
+## [3.5.2] - 2026-02-08
+
+### Performance
+
+- Home tab search result sections are now virtualized with `SliverList` (lazy item build) instead of eager `Column` rendering, reducing frame drops on large result sets
+- Home tab now narrows Riverpod subscriptions using field-level `select(...)` for search/provider state to reduce unnecessary full-tab rebuilds
+- Search provider dropdown now watches only required fields (`searchProvider`, `metadataSource`, `extensions`) instead of full provider states
+- Track row rendering in Home search now receives precomputed thumbnail sizing/local-library flags from parent to avoid repeated per-item provider watches
+- Removed thumbnail `debugPrint` calls inside track row `build()` to reduce runtime overhead during scrolling/rebuilds
+- Queue tab root subscription no longer watches full queue item list; it now watches only queue presence (`items.isNotEmpty`) to avoid full Library UI rebuilds on every progress tick
+- Queue download header/list rendering has been isolated into dedicated `Consumer` slivers; header now watches only queue length (`items.length`) while item list watches queue item updates
+- Queue filter/sort computations are now centralized and memoized per filter mode within a build pass (`all`/`albums`/`singles`), reducing repeated list transforms for chip counts and page content
+- Selection bottom bar content is now computed only when selection mode is active, removing hidden-state heavy list preparation
+- File existence checks in queue/library rows now use per-path `ValueNotifier` + `ValueListenableBuilder` updates instead of triggering global `setState`, reducing unnecessary whole-tab repaints
+
+### Changed
+
+- Replaced date range filter with sorting options in Library tab: Latest, Oldest, A-Z, Z-A
+- Sorting applies to all views: unified items, downloaded albums, and local library albums
+- Local library items now use file modification time (`fileModTime`) for sorting instead of scan time, providing more accurate chronological ordering
+- Removed redundant manual "Export Failed Downloads" button from Library UI (auto-export setting in Settings is sufficient)
+- Library filters (quality, format, source) now correctly apply to album tabs and update tab chip counts (All/Albums/Singles)
+
+### Fixed
+
+- Fixed local library scan crashing on Samsung One UI devices due to MediaStore URI mismatch in SAF tree traversal
+- Added MediaStore URI fallback in SAF file reader: when SAF permission is denied for Samsung-returned MediaStore URIs, automatically retries using READ_MEDIA_AUDIO permission
+- Hardened SAF scan with per-directory and per-file error handling: scan now skips problematic files instead of aborting entirely
+- Added visited directory tracking to prevent infinite loops from circular SAF references
+- Fixed metadata enrichment cascading failure after one queued download fails: metadata APIs (Deezer, SongLink, Spotify) now use isolated `metadataTransport` so failed download connections cannot poison metadata requests
+- Added immediate connection cleanup on every download failure path (error response and exception), not only periodic cleanup every N downloads
+- Fixed incremental SAF scan edge case where `lastModified()` failure could misclassify existing files as removed (`removedUris`)
+- Fixed tracks marked "In Library" still showing active download button - download button now shows as completed (checkmark) for local library tracks across all screens (album, playlist, artist, home/search)
+- Fixed FFmpeg M4A-to-FLAC conversion erroneously triggered on already-existing FLAC files when re-downloading duplicates via Tidal
+- Fixed SAF download creating empty artist/album folders when re-downloading duplicate tracks; directory is now only created after confirming the file does not already exist
+
 ## [3.5.1] - 2026-02-08

 ### Performance
@@ -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/f6ba8fa4a572d69f6196f980733089cb741088e3ceb49d0bd3ceda5a694a2466/)
-[![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,14 +23,16 @@ Download music in true lossless FLAC from Tidal, Qobuz & Amazon Music — no acc
  <img src="assets/images/4.jpg?v=2" width="200" />
 </p>

-## Search Source
+<div align="center">

-SpotiFLAC supports multiple search sources for finding music metadata:
+[![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/0a2bd2a033551983fc9fcd83f82fd912c83914fd1094cd8d1c7c6a68eb23233f)
+[![Crowdin](https://img.shields.io/badge/HELP%20TRANSLATE%20ON-CROWDIN-%2321252b?style=for-the-badge&logo=crowdin)](https://crowdin.com/project/spotiflac-mobile)

-| Source | Setup |
-|--------|-------|
-| **Deezer** (Default) | No setup required |
-| **Extensions** | Install additional search providers from the Store |
+[![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

@@ -52,25 +53,13 @@ Want to create your own extension? Check out the [Extension Development Guide](h
 ### [SpotiFLAC (Desktop)](https://github.com/afkarxyz/SpotiFLAC)
 Download music in true lossless FLAC from Tidal, Qobuz & Amazon Music for Windows, macOS & Linux

-## Telegram
-
-<p align="center">
-  <a href="https://t.me/spotiflac">
-    <img src="https://img.shields.io/badge/Telegram-Channel-2CA5E0?style=for-the-badge&logo=telegram&logoColor=white" alt="Telegram Channel">
-  </a>
-
-  <a href="https://t.me/spotiflac_chat">
-    <img src="https://img.shields.io/badge/Telegram-Community-2CA5E0?style=for-the-badge&logo=telegram&logoColor=white" alt="Telegram Community">
-  </a>
-</p>
-
 ## FAQ

 **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.
@@ -87,25 +76,13 @@ A: Some countries have restricted access to certain streaming service APIs. If d

 ### Want to support SpotiFLAC-Mobile?

-_If this software is useful and brings you value, consider supporting the project by buying me a coffee. Your support helps keep development going._
+_If this software is useful and brings you value, consider supporting the project. Your support helps keep development going._

-[![Ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/zarzet) <a href="https://www.buymeacoffee.com/zarzet" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" style="height: 40px !important;width: 150px !important;" ></a>
+[![Ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/zarzet)

+## API Credits

-## Disclaimer
-
-This project is for **educational and private use only**. The developer does not condone or encourage copyright infringement.
-
-**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.
+[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]
@@ -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">
@@ -1,4 +1,4 @@
 <?xml version="1.0" encoding="utf-8"?>
 <resources>
-    <color name="ic_launcher_background">#1a1a2e</color>
+    <color name="ic_launcher_background">#000000</color>
 </resources>
@@ -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>
@@ -0,0 +1,105 @@
+# 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 %} 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 = [
+  # Remove PR number from message (we add it back via GitHub integration)
+  { pattern = '\(#(\d+)\)', replace = '' },
+  # 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"
@@ -1,511 +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
-)
-
-// 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"`
-}
-
-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
-func (a *AmazonDownloader) fetchAmazonURLWithRetry(amazonURL string) (string, string, error) {
-	apiURL := "https://amazon.afkarxyz.fun/convert?url=" + url.QueryEscape(amazonURL)
-
-	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, err := a.doAfkarXYZRequest(apiURL)
-		if err == nil {
-			return downloadURL, fileName, nil
-		}
-
-		lastErr = err
-		errStr := 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")
-
-		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)
-}
-
-// doAfkarXYZRequest performs a single request to AfkarXYZ API
-func (a *AmazonDownloader) doAfkarXYZRequest(apiURL string) (string, string, error) {
-	ctx, cancel := context.WithTimeout(context.Background(), amazonAPITimeoutMobile)
-	defer cancel()
-
-	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", getRandomUserAgent())
-
-	resp, err := a.client.Do(req)
-	if err != nil {
-		return "", "", fmt.Errorf("failed to call AfkarXYZ API: %w", err)
-	}
-	defer resp.Body.Close()
-
-	if resp.StatusCode != 200 {
-		return "", "", fmt.Errorf("AfkarXYZ 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 AfkarXYZResponse
-	if err := json.Unmarshal(body, &apiResp); err != nil {
-		return "", "", fmt.Errorf("failed to decode response: %w", err)
-	}
-
-	if !apiResp.Success || apiResp.Data.DirectLink == "" {
-		return "", "", fmt.Errorf("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, error) {
-	GoLog("[Amazon] Fetching from AfkarXYZ API...\n")
-
-	downloadURL, fileName, err := a.fetchAmazonURLWithRetry(amazonURL)
-	if err != nil {
-		return "", "", err
-	}
-
-	GoLog("[Amazon] AfkarXYZ returned: %s\n", fileName)
-	return downloadURL, fileName, 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
-}
-
-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, _, 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),
-		"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 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)
-	}
-
-	// Wait for parallel operations to complete
-	<-parallelDone
-
-	if req.ItemID != "" {
-		SetItemProgress(req.ItemID, 1.0, 0, 0)
-		SetItemFinalizing(req.ItemID)
-	}
-
-	existingMeta, metaErr := ReadMetadata(outputPath)
-	actualTrackNum := req.TrackNumber
-	actualDiscNum := req.DiscNumber
-	actualDate := req.ReleaseDate
-	actualAlbum := req.AlbumName
-	actualTitle := req.TrackName
-	actualArtist := req.ArtistName
-
-	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(outputPath)
-		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 {
-		GoLog("[Amazon] SAF output detected - skipping in-backend metadata/lyrics embedding (handled in Flutter)\n")
-	} else {
-		if err := EmbedMetadataWithCoverData(outputPath, metadata, coverData); err != nil {
-			GoLog("[Amazon] 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" {
-				GoLog("[Amazon] Saving external LRC file...\n")
-				if lrcPath, lrcErr := SaveLRCFile(outputPath, 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" {
-				GoLog("[Amazon] Embedding parallel-fetched lyrics (%d lines)...\n", len(parallelResult.LyricsData.Lines))
-				if embedErr := EmbedLyrics(outputPath, parallelResult.LyricsLRC); embedErr != nil {
-					GoLog("[Amazon] Warning: failed to embed lyrics: %v\n", embedErr)
-				} else {
-					GoLog("[Amazon] Lyrics embedded successfully\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 {
-		GoLog("[Amazon] SAF output detected - skipping post-write file inspection in backend\n")
-	} else {
-		quality, err = GetAudioQuality(outputPath)
-		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(outputPath)
-		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
-	if !isSafOutput {
-		AddToISRCIndex(req.OutputDir, req.ISRC, outputPath)
-	}
-
-	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,
-	}, nil
-}
@@ -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
@@ -23,9 +23,13 @@ type AudioMetadata struct {
 	TrackNumber int
 	DiscNumber  int
 	ISRC        string
+	Lyrics      string
+	Label       string
+	Copyright   string
+	Composer    string
+	Comment     string
 }

-// MP3Quality represents MP3 specific quality info
 type MP3Quality struct {
 	SampleRate int
 	BitDepth   int
@@ -33,17 +37,13 @@ type MP3Quality struct {
 	Bitrate    int
 }

-// OggQuality represents Ogg/Opus specific quality info
 type OggQuality struct {
 	SampleRate int
 	BitDepth   int
 	Duration   int
+	Bitrate    int // estimated bitrate in bps
 }

-// =============================================================================
-// ID3 Tag Reading (MP3)
-// =============================================================================
-
 func ReadID3Tags(filePath string) (*AudioMetadata, error) {
 	file, err := os.Open(filePath)
 	if err != nil {
@@ -171,6 +171,21 @@ func parseID3v22Frames(data []byte, metadata *AudioMetadata, tagUnsync bool) {
 			metadata.TrackNumber = parseTrackNumber(value)
 		case "TPA":
 			metadata.DiscNumber = parseTrackNumber(value)
+		case "TCM":
+			metadata.Composer = value
+		case "TPB":
+			metadata.Label = value
+		case "TCR":
+			metadata.Copyright = value
+		case "ULT":
+			if v := extractLyricsFrame(frameData); v != "" && metadata.Lyrics == "" {
+				metadata.Lyrics = v
+			}
+		case "TXX":
+			desc, userValue := extractUserTextFrame(frameData)
+			if isLyricsDescription(desc) && userValue != "" && metadata.Lyrics == "" {
+				metadata.Lyrics = userValue
+			}
 		}

 		pos += 6 + frameSize
@@ -277,6 +292,25 @@ func parseID3v23Frames(data []byte, metadata *AudioMetadata, version byte, tagUn
 			metadata.DiscNumber = parseTrackNumber(value)
 		case "TSRC":
 			metadata.ISRC = value
+		case "TCOM":
+			metadata.Composer = value
+		case "TPUB":
+			metadata.Label = value
+		case "TCOP":
+			metadata.Copyright = value
+		case "COMM":
+			if v := extractCommentFrame(frameData); v != "" {
+				metadata.Comment = v
+			}
+		case "USLT":
+			if v := extractLyricsFrame(frameData); v != "" && metadata.Lyrics == "" {
+				metadata.Lyrics = v
+			}
+		case "TXXX":
+			desc, userValue := extractUserTextFrame(frameData)
+			if isLyricsDescription(desc) && userValue != "" && metadata.Lyrics == "" {
+				metadata.Lyrics = userValue
+			}
 		}

 		pos += 10 + frameSize
@@ -339,6 +373,138 @@ func extractTextFrame(data []byte) string {
 	}
 }

+// extractCommentFrame parses an ID3v2 COMM frame.
+// Format: encoding(1) + language(3) + description(null-terminated) + text
+func extractCommentFrame(data []byte) string {
+	if len(data) < 5 {
+		return ""
+	}
+	encoding := data[0]
+	// skip 3-byte language code
+	rest := data[4:]
+
+	// find null terminator separating description from text
+	var text []byte
+	switch encoding {
+	case 1, 2: // UTF-16 variants use double-null terminator
+		for i := 0; i+1 < len(rest); i += 2 {
+			if rest[i] == 0 && rest[i+1] == 0 {
+				text = rest[i+2:]
+				break
+			}
+		}
+	default: // ISO-8859-1 or UTF-8
+		idx := bytes.IndexByte(rest, 0)
+		if idx >= 0 && idx+1 < len(rest) {
+			text = rest[idx+1:]
+		} else {
+			text = rest
+		}
+	}
+
+	if len(text) == 0 {
+		return ""
+	}
+
+	// re-prepend encoding byte so extractTextFrame can decode properly
+	framed := make([]byte, 1+len(text))
+	framed[0] = encoding
+	copy(framed[1:], text)
+	return extractTextFrame(framed)
+}
+
+// extractLyricsFrame parses ID3 unsynchronized lyrics frames (USLT/ULT).
+// Format: encoding(1) + language(3) + description(null-terminated) + lyrics text.
+func extractLyricsFrame(data []byte) string {
+	if len(data) < 5 {
+		return ""
+	}
+
+	encoding := data[0]
+	rest := data[4:] // skip 3-byte language code
+
+	var text []byte
+	switch encoding {
+	case 1, 2: // UTF-16 variants use double-null terminator
+		for i := 0; i+1 < len(rest); i += 2 {
+			if rest[i] == 0 && rest[i+1] == 0 {
+				text = rest[i+2:]
+				break
+			}
+		}
+	default: // ISO-8859-1 or UTF-8
+		idx := bytes.IndexByte(rest, 0)
+		if idx >= 0 && idx+1 < len(rest) {
+			text = rest[idx+1:]
+		} else {
+			text = rest
+		}
+	}
+
+	if len(text) == 0 {
+		return ""
+	}
+
+	framed := make([]byte, 1+len(text))
+	framed[0] = encoding
+	copy(framed[1:], text)
+	return extractTextFrame(framed)
+}
+
+// extractUserTextFrame parses ID3 TXXX/TXX user text frame:
+// encoding(1) + description + separator + value.
+func extractUserTextFrame(data []byte) (string, string) {
+	if len(data) < 2 {
+		return "", ""
+	}
+
+	encoding := data[0]
+	payload := data[1:]
+
+	var descRaw, valueRaw []byte
+	switch encoding {
+	case 1, 2: // UTF-16 variants
+		for i := 0; i+1 < len(payload); i += 2 {
+			if payload[i] == 0 && payload[i+1] == 0 {
+				descRaw = payload[:i]
+				valueRaw = payload[i+2:]
+				break
+			}
+		}
+	default: // ISO-8859-1 or UTF-8
+		idx := bytes.IndexByte(payload, 0)
+		if idx >= 0 {
+			descRaw = payload[:idx]
+			if idx+1 <= len(payload) {
+				valueRaw = payload[idx+1:]
+			}
+		}
+	}
+
+	if len(valueRaw) == 0 {
+		return "", ""
+	}
+
+	descFramed := make([]byte, 1+len(descRaw))
+	descFramed[0] = encoding
+	copy(descFramed[1:], descRaw)
+
+	valueFramed := make([]byte, 1+len(valueRaw))
+	valueFramed[0] = encoding
+	copy(valueFramed[1:], valueRaw)
+
+	return strings.TrimSpace(extractTextFrame(descFramed)), strings.TrimSpace(extractTextFrame(valueFramed))
+}
+
+func isLyricsDescription(description string) bool {
+	switch strings.ToLower(strings.TrimSpace(description)) {
+	case "lyrics", "lyric", "unsyncedlyrics", "unsynced lyrics", "lrc":
+		return true
+	default:
+		return false
+	}
+}
+
 func decodeUTF16(data []byte) string {
 	if len(data) < 2 {
 		return ""
@@ -493,50 +659,144 @@ func GetMP3Quality(filePath string) (*MP3Quality, error) {

 	file.Seek(audioStart, io.SeekStart)

+	// Find first valid MP3 frame sync
 	frameHeader := make([]byte, 4)
-	for i := 0; i < 10000; i++ { // Search first 10KB
+	var frameStart int64 = -1
+	for i := 0; i < 10000; i++ {
 		if _, err := io.ReadFull(file, frameHeader); err != nil {
 			break
 		}

 		if frameHeader[0] == 0xFF && (frameHeader[1]&0xE0) == 0xE0 {
-			version := (frameHeader[1] >> 3) & 0x03
-			layer := (frameHeader[1] >> 1) & 0x03
-			bitrateIdx := (frameHeader[2] >> 4) & 0x0F
-			sampleRateIdx := (frameHeader[2] >> 2) & 0x03
-
-			sampleRates := [][]int{
-				{11025, 12000, 8000},
-				{0, 0, 0},
-				{22050, 24000, 16000},
-				{44100, 48000, 32000},
-			}
-			if version < 4 && sampleRateIdx < 3 {
-				quality.SampleRate = sampleRates[version][sampleRateIdx]
-			}
-
-			if version == 3 && layer == 1 {
-				bitrates := []int{0, 32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320, 0}
-				if bitrateIdx < 16 {
-					quality.Bitrate = bitrates[bitrateIdx] * 1000
-				}
-			}
-
-			quality.BitDepth = 16
-
-			if quality.Bitrate > 0 {
-				audioSize := fileSize - audioStart - 128
-				if audioSize > 0 {
-					quality.Duration = int(audioSize * 8 / int64(quality.Bitrate))
-				}
-			}
-
+			pos, _ := file.Seek(0, io.SeekCurrent)
+			frameStart = pos - 4
 			break
 		}

 		file.Seek(-3, io.SeekCurrent)
 	}

+	if frameStart < 0 {
+		return quality, nil
+	}
+
+	version := (frameHeader[1] >> 3) & 0x03
+	layer := (frameHeader[1] >> 1) & 0x03
+	bitrateIdx := (frameHeader[2] >> 4) & 0x0F
+	sampleRateIdx := (frameHeader[2] >> 2) & 0x03
+	channelMode := (frameHeader[3] >> 6) & 0x03
+
+	// Sample rate tables: [version][index]
+	// version: 0=MPEG2.5, 1=reserved, 2=MPEG2, 3=MPEG1
+	sampleRates := [][]int{
+		{11025, 12000, 8000},
+		{0, 0, 0},
+		{22050, 24000, 16000},
+		{44100, 48000, 32000},
+	}
+	if version < 4 && sampleRateIdx < 3 {
+		quality.SampleRate = sampleRates[version][sampleRateIdx]
+	}
+
+	// Bitrate tables for all MPEG versions and layers
+	// MPEG1 Layer III
+	if version == 3 && layer == 1 {
+		bitrates := []int{0, 32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320, 0}
+		if bitrateIdx < 16 {
+			quality.Bitrate = bitrates[bitrateIdx] * 1000
+		}
+	}
+	// MPEG2/2.5 Layer III
+	if (version == 0 || version == 2) && layer == 1 {
+		bitrates := []int{0, 8, 16, 24, 32, 40, 48, 56, 64, 80, 96, 112, 128, 144, 160, 0}
+		if bitrateIdx < 16 {
+			quality.Bitrate = bitrates[bitrateIdx] * 1000
+		}
+	}
+
+	// Determine samples per frame for duration calculation
+	samplesPerFrame := 1152 // MPEG1 Layer III
+	if version == 0 || version == 2 {
+		samplesPerFrame = 576 // MPEG2/2.5 Layer III
+	}
+
+	// Try to read Xing/VBRI header from the first frame for VBR info
+	// Xing header offset depends on MPEG version and channel mode
+	var xingOffset int
+	if version == 3 { // MPEG1
+		if channelMode == 3 { // Mono
+			xingOffset = 17
+		} else {
+			xingOffset = 32
+		}
+	} else { // MPEG2/2.5
+		if channelMode == 3 {
+			xingOffset = 9
+		} else {
+			xingOffset = 17
+		}
+	}
+
+	// Read enough of the first frame to find Xing/VBRI header
+	xingBuf := make([]byte, 200)
+	file.Seek(frameStart+4, io.SeekStart)
+	n, _ := io.ReadFull(file, xingBuf)
+	xingBuf = xingBuf[:n]
+
+	vbrFrames := 0
+	vbrBytes := int64(0)
+	isVBR := false
+
+	// Check for Xing/Info header
+	if xingOffset+8 <= n {
+		tag := string(xingBuf[xingOffset : xingOffset+4])
+		if tag == "Xing" || tag == "Info" {
+			flags := binary.BigEndian.Uint32(xingBuf[xingOffset+4 : xingOffset+8])
+			off := xingOffset + 8
+			if flags&0x01 != 0 && off+4 <= n { // Frames flag
+				vbrFrames = int(binary.BigEndian.Uint32(xingBuf[off : off+4]))
+				off += 4
+			}
+			if flags&0x02 != 0 && off+4 <= n { // Bytes flag
+				vbrBytes = int64(binary.BigEndian.Uint32(xingBuf[off : off+4]))
+			}
+			if vbrFrames > 0 {
+				isVBR = true
+			}
+		}
+	}
+
+	// Check for VBRI header (always at offset 32 from frame start + 4)
+	if !isVBR && 36+26 <= n {
+		if string(xingBuf[32:36]) == "VBRI" {
+			vbrBytes = int64(binary.BigEndian.Uint32(xingBuf[36+6 : 36+10]))
+			vbrFrames = int(binary.BigEndian.Uint32(xingBuf[36+10 : 36+14]))
+			if vbrFrames > 0 {
+				isVBR = true
+			}
+		}
+	}
+
+	if isVBR && vbrFrames > 0 && quality.SampleRate > 0 {
+		// Accurate duration from total frames
+		totalSamples := int64(vbrFrames) * int64(samplesPerFrame)
+		quality.Duration = int(totalSamples / int64(quality.SampleRate))
+
+		// Accurate average bitrate
+		if vbrBytes > 0 && quality.Duration > 0 {
+			quality.Bitrate = int(vbrBytes * 8 / int64(quality.Duration))
+		} else if quality.Duration > 0 {
+			audioSize := fileSize - audioStart
+			quality.Bitrate = int(audioSize * 8 / int64(quality.Duration))
+		}
+	} else if quality.Bitrate > 0 {
+		// CBR fallback: estimate duration from file size and frame bitrate
+		audioSize := fileSize - audioStart - 128 // subtract possible ID3v1 tag
+		if audioSize > 0 {
+			quality.Duration = int(audioSize * 8 / int64(quality.Bitrate))
+		}
+	}
+
 	return quality, nil
 }

@@ -740,9 +1000,16 @@ func parseVorbisComments(data []byte, metadata *AudioMetadata) {
 			break
 		}

-		if commentLen > 10000 {
+		remaining := uint32(reader.Len())
+		if commentLen > remaining {
 			break
 		}
+		// Large comment entries are typically METADATA_BLOCK_PICTURE.
+		// Skip them so we can continue parsing normal text tags after/before.
+		if commentLen > 512*1024 {
+			reader.Seek(int64(commentLen), io.SeekCurrent)
+			continue
+		}

 		comment := make([]byte, commentLen)
 		if _, err := reader.Read(comment); err != nil {
@@ -779,6 +1046,18 @@ func parseVorbisComments(data []byte, metadata *AudioMetadata) {
 			metadata.DiscNumber = parseTrackNumber(value)
 		case "ISRC":
 			metadata.ISRC = value
+		case "COMPOSER":
+			metadata.Composer = value
+		case "COMMENT", "DESCRIPTION":
+			metadata.Comment = value
+		case "LYRICS", "UNSYNCEDLYRICS":
+			if metadata.Lyrics == "" {
+				metadata.Lyrics = value
+			}
+		case "ORGANIZATION", "LABEL", "PUBLISHER":
+			metadata.Label = value
+		case "COPYRIGHT":
+			metadata.Copyright = value
 		}
 	}
 }
@@ -791,7 +1070,6 @@ func GetOggQuality(filePath string) (*OggQuality, error) {
 	defer file.Close()

 	quality := &OggQuality{}
-	isOpus := false

 	packets, err := collectOggPackets(file, 5, 10)
 	if err != nil && len(packets) == 0 {
@@ -807,15 +1085,17 @@ func GetOggQuality(filePath string) (*OggQuality, error) {
 		}
 	}

-	if streamType == oggStreamOpus {
-		isOpus = true
+	isOpus := streamType == oggStreamOpus
+	var preSkip int
+
+	if isOpus {
 		for _, pkt := range packets {
 			if len(pkt) >= 19 && string(pkt[0:8]) == "OpusHead" {
 				quality.SampleRate = int(binary.LittleEndian.Uint32(pkt[12:16]))
 				if quality.SampleRate == 0 {
 					quality.SampleRate = 48000
 				}
-				quality.BitDepth = 16
+				preSkip = int(binary.LittleEndian.Uint16(pkt[10:12]))
 				break
 			}
 		}
@@ -823,29 +1103,105 @@ func GetOggQuality(filePath string) (*OggQuality, error) {
 		for _, pkt := range packets {
 			if len(pkt) > 29 && pkt[0] == 0x01 && string(pkt[1:7]) == "vorbis" {
 				quality.SampleRate = int(binary.LittleEndian.Uint32(pkt[12:16]))
-				quality.BitDepth = 16
 				break
 			}
 		}
 	}

+	// Read granule position from the last Ogg page for accurate duration
 	stat, err := file.Stat()
-	if err == nil {
-		// Very rough duration estimate based on file size
-		// Assume ~128kbps average for Opus, ~160kbps for Vorbis
-		avgBitrate := 128000
-		if !isOpus {
-			avgBitrate = 160000
+	if err != nil {
+		return quality, nil
+	}
+	fileSize := stat.Size()
+
+	granule := readLastOggGranulePosition(file, fileSize)
+	if granule > 0 {
+		if isOpus {
+			// Opus always uses 48kHz granule position internally
+			totalSamples := granule - int64(preSkip)
+			if totalSamples > 0 {
+				durationSec := float64(totalSamples) / 48000.0
+				if durationSec > 0 {
+					quality.Duration = int(math.Round(durationSec))
+					quality.Bitrate = int(float64(fileSize*8) / durationSec)
+				}
+			}
+		} else if quality.SampleRate > 0 {
+			durationSec := float64(granule) / float64(quality.SampleRate)
+			if durationSec > 0 {
+				quality.Duration = int(math.Round(durationSec))
+				quality.Bitrate = int(float64(fileSize*8) / durationSec)
+			}
 		}
-		quality.Duration = int(stat.Size() * 8 / int64(avgBitrate))
+	}
+
+	// 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
 }

-// =============================================================================
-// ID3v1 Genre List
-// =============================================================================
+// readLastOggGranulePosition seeks to the end of the file and scans backwards
+// to find the last Ogg page, then reads its granule position (bytes 6-13).
+func readLastOggGranulePosition(file *os.File, fileSize int64) int64 {
+	// Read the last chunk of the file to find the last OggS sync
+	searchSize := int64(65536)
+	if searchSize > fileSize {
+		searchSize = fileSize
+	}
+
+	buf := make([]byte, searchSize)
+	offset := fileSize - searchSize
+	if offset < 0 {
+		offset = 0
+	}
+	n, err := file.ReadAt(buf, offset)
+	if err != nil && n == 0 {
+		return 0
+	}
+	buf = buf[:n]
+
+	for i := n - 4; i >= 0; i-- {
+		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]))
+	}
+	return 0
+}

 var id3v1Genres = []string{
 	"Blues", "Classic Rock", "Country", "Dance", "Disco", "Funk", "Grunge",
@@ -877,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 {
@@ -0,0 +1,577 @@
+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
+		}
+
+		// PERFORMER
+		if strings.HasPrefix(upper, "PERFORMER ") {
+			value := unquoteCue(line[len("PERFORMER "):])
+			if currentTrack != nil {
+				currentTrack.Performer = value
+			} else {
+				sheet.Performer = value
+			}
+			continue
+		}
+
+		// TITLE
+		if strings.HasPrefix(upper, "TITLE ") {
+			value := unquoteCue(line[len("TITLE "):])
+			if currentTrack != nil {
+				currentTrack.Title = value
+			} else {
+				sheet.Title = value
+			}
+			continue
+		}
+
+		// FILE
+		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
+		}
+
+		// TRACK
+		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
+		}
+
+		// INDEX
+		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
+		}
+
+		// ISRC
+		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) {
+	return scanCueFileForLibraryInternal(cuePath, "", "", 0, scanTime)
+}
+
+// ScanCueFileForLibraryExt is like ScanCueFileForLibrary but with extra parameters
+// for SAF (Storage Access Framework) scenarios:
+//   - audioDir: if non-empty, overrides the directory used to find the audio file
+//   - virtualPathPrefix: if non-empty, used instead of cuePath as the base for
+//     virtual file paths (e.g. a content:// URI). IDs are also based on this.
+//   - fileModTime: if > 0, used as the FileModTime for all results instead of
+//     stat-ing the cuePath on disk (useful when the real file lives behind SAF)
+func ScanCueFileForLibraryExt(cuePath, audioDir, virtualPathPrefix string, fileModTime int64, scanTime string) ([]LibraryScanResult, error) {
+	return scanCueFileForLibraryInternal(cuePath, audioDir, virtualPathPrefix, fileModTime, scanTime)
+}
+
+func scanCueFileForLibraryInternal(cuePath, audioDir, virtualPathPrefix string, fileModTime int64, scanTime string) ([]LibraryScanResult, error) {
+	sheet, err := ParseCueFile(cuePath)
+	if err != nil {
+		return nil, err
+	}
+
+	// Resolve audio file — optionally in an overridden directory
+	resolveBase := cuePath
+	if audioDir != "" {
+		resolveBase = filepath.Join(audioDir, filepath.Base(cuePath))
+	}
+	audioPath := ResolveCueAudioPath(resolveBase, sheet.FileName)
+	if audioPath == "" {
+		return nil, fmt.Errorf("audio file not found for cue: %s (referenced: %s)", cuePath, sheet.FileName)
+	}
+
+	// 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)
+		}
+
+		// Use a unique ID based on pathBase + track number
+		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
+}
@@ -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

@@ -28,15 +29,23 @@ const (
 	deezerAPITimeoutMobile = 25 * time.Second
 	deezerMaxRetries       = 2
 	deezerRetryDelay       = 500 * time.Millisecond
+
+	deezerMaxSearchCacheEntries = 300
+	deezerMaxAlbumCacheEntries  = 200
+	deezerMaxArtistCacheEntries = 200
+	deezerMaxISRCCacheEntries   = 4000
+	deezerCacheCleanupInterval  = 5 * time.Minute
 )

 type DeezerClient struct {
-	httpClient  *http.Client
-	searchCache map[string]*cacheEntry
-	albumCache  map[string]*cacheEntry
-	artistCache map[string]*cacheEntry
-	isrcCache   map[string]string
-	cacheMu     sync.RWMutex
+	httpClient           *http.Client
+	searchCache          map[string]*cacheEntry
+	albumCache           map[string]*cacheEntry
+	artistCache          map[string]*cacheEntry
+	isrcCache            map[string]string
+	cacheMu              sync.RWMutex
+	lastCacheCleanup     time.Time
+	cacheCleanupInterval time.Duration
 }

 var (
@@ -47,16 +56,111 @@ var (
 func GetDeezerClient() *DeezerClient {
 	deezerClientOnce.Do(func() {
 		deezerClient = &DeezerClient{
-			httpClient:  NewHTTPClientWithTimeout(deezerAPITimeoutMobile),
-			searchCache: make(map[string]*cacheEntry),
-			albumCache:  make(map[string]*cacheEntry),
-			artistCache: make(map[string]*cacheEntry),
-			isrcCache:   make(map[string]string),
+			httpClient:           NewMetadataHTTPClient(deezerAPITimeoutMobile),
+			searchCache:          make(map[string]*cacheEntry),
+			albumCache:           make(map[string]*cacheEntry),
+			artistCache:          make(map[string]*cacheEntry),
+			isrcCache:            make(map[string]string),
+			cacheCleanupInterval: deezerCacheCleanupInterval,
 		}
 	})
 	return deezerClient
 }

+func (c *DeezerClient) pruneExpiredCacheEntriesLocked(
+	cache map[string]*cacheEntry,
+	now time.Time,
+) {
+	for key, entry := range cache {
+		if entry == nil || now.After(entry.expiresAt) {
+			delete(cache, key)
+		}
+	}
+}
+
+func (c *DeezerClient) trimCacheEntriesLocked(
+	cache map[string]*cacheEntry,
+	maxEntries int,
+) {
+	if maxEntries <= 0 || len(cache) <= maxEntries {
+		return
+	}
+
+	for len(cache) > maxEntries {
+		var oldestKey string
+		var oldestExpiry time.Time
+		first := true
+		for key, entry := range cache {
+			expiry := time.Time{}
+			if entry != nil {
+				expiry = entry.expiresAt
+			}
+			if first || expiry.Before(oldestExpiry) {
+				first = false
+				oldestKey = key
+				oldestExpiry = expiry
+			}
+		}
+		if oldestKey == "" {
+			return
+		}
+		delete(cache, oldestKey)
+	}
+}
+
+func (c *DeezerClient) trimStringCacheEntriesLocked(
+	cache map[string]string,
+	maxEntries int,
+) {
+	if maxEntries <= 0 || len(cache) <= maxEntries {
+		return
+	}
+
+	toRemove := len(cache) - maxEntries
+	for key := range cache {
+		delete(cache, key)
+		toRemove--
+		if toRemove <= 0 {
+			return
+		}
+	}
+}
+
+func (c *DeezerClient) maybeCleanupCachesLocked(now time.Time) {
+	periodicCleanupDue := c.cacheCleanupInterval > 0 &&
+		(c.lastCacheCleanup.IsZero() ||
+			now.Sub(c.lastCacheCleanup) >= c.cacheCleanupInterval)
+
+	if periodicCleanupDue {
+		c.pruneExpiredCacheEntriesLocked(c.searchCache, now)
+		c.pruneExpiredCacheEntriesLocked(c.albumCache, now)
+		c.pruneExpiredCacheEntriesLocked(c.artistCache, now)
+		c.lastCacheCleanup = now
+	}
+
+	if len(c.searchCache) > deezerMaxSearchCacheEntries {
+		if !periodicCleanupDue {
+			c.pruneExpiredCacheEntriesLocked(c.searchCache, now)
+		}
+		c.trimCacheEntriesLocked(c.searchCache, deezerMaxSearchCacheEntries)
+	}
+	if len(c.albumCache) > deezerMaxAlbumCacheEntries {
+		if !periodicCleanupDue {
+			c.pruneExpiredCacheEntriesLocked(c.albumCache, now)
+		}
+		c.trimCacheEntriesLocked(c.albumCache, deezerMaxAlbumCacheEntries)
+	}
+	if len(c.artistCache) > deezerMaxArtistCacheEntries {
+		if !periodicCleanupDue {
+			c.pruneExpiredCacheEntriesLocked(c.artistCache, now)
+		}
+		c.trimCacheEntriesLocked(c.artistCache, deezerMaxArtistCacheEntries)
+	}
+	if len(c.isrcCache) > deezerMaxISRCCacheEntries {
+		c.trimStringCacheEntriesLocked(c.isrcCache, deezerMaxISRCCacheEntries)
+	}
+}
+
 type deezerTrack struct {
 	ID            int64             `json:"id"`
 	Title         string            `json:"title"`
@@ -131,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),
 	}
 }

@@ -414,10 +520,12 @@ func (c *DeezerClient) SearchAll(ctx context.Context, query string, trackLimit,
 	GoLog("[Deezer] SearchAll complete: %d tracks, %d artists, %d albums, %d playlists\n", len(result.Tracks), len(result.Artists), len(result.Albums), len(result.Playlists))

 	c.cacheMu.Lock()
+	now := time.Now()
 	c.searchCache[cacheKey] = &cacheEntry{
 		data:      result,
-		expiresAt: time.Now().Add(deezerCacheTTL),
+		expiresAt: now.Add(deezerCacheTTL),
 	}
+	c.maybeCleanupCachesLocked(now)
 	c.cacheMu.Unlock()

 	return result, nil
@@ -555,10 +663,12 @@ func (c *DeezerClient) GetAlbum(ctx context.Context, albumID string) (*AlbumResp
 	}

 	c.cacheMu.Lock()
+	now := time.Now()
 	c.albumCache[albumID] = &cacheEntry{
 		data:      result,
-		expiresAt: time.Now().Add(deezerCacheTTL),
+		expiresAt: now.Add(deezerCacheTTL),
 	}
+	c.maybeCleanupCachesLocked(now)
 	c.cacheMu.Unlock()

 	return result, nil
@@ -638,15 +748,77 @@ func (c *DeezerClient) GetArtist(ctx context.Context, artistID string) (*ArtistR
 	}

 	c.cacheMu.Lock()
+	now := time.Now()
 	c.artistCache[artistID] = &cacheEntry{
 		data:      result,
-		expiresAt: time.Now().Add(deezerCacheTTL),
+		expiresAt: now.Add(deezerCacheTTL),
 	}
+	c.maybeCleanupCachesLocked(now)
 	c.cacheMu.Unlock()

 	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)

@@ -807,6 +979,7 @@ func (c *DeezerClient) fetchISRCsParallel(ctx context.Context, tracks []deezerTr
 		for trackIDStr, isrc := range directISRCs {
 			c.isrcCache[trackIDStr] = isrc
 		}
+		c.maybeCleanupCachesLocked(time.Now())
 		c.cacheMu.Unlock()
 	}

@@ -841,6 +1014,7 @@ func (c *DeezerClient) fetchISRCsParallel(ctx context.Context, tracks []deezerTr

 			c.cacheMu.Lock()
 			c.isrcCache[trackIDStr] = fullTrack.ISRC
+			c.maybeCleanupCachesLocked(time.Now())
 			c.cacheMu.Unlock()
 		}(track)
 	}
@@ -864,6 +1038,7 @@ func (c *DeezerClient) GetTrackISRC(ctx context.Context, trackID string) (string

 	c.cacheMu.Lock()
 	c.isrcCache[trackID] = fullTrack.ISRC
+	c.maybeCleanupCachesLocked(time.Now())
 	c.cacheMu.Unlock()

 	return fullTrack.ISRC, nil
@@ -946,10 +1121,12 @@ func (c *DeezerClient) GetAlbumExtendedMetadata(ctx context.Context, albumID str
 	}

 	c.cacheMu.Lock()
+	now := time.Now()
 	c.searchCache[cacheKey] = &cacheEntry{
 		data:      result,
-		expiresAt: time.Now().Add(deezerCacheTTL),
+		expiresAt: now.Add(deezerCacheTTL),
 	}
+	c.maybeCleanupCachesLocked(now)
 	c.cacheMu.Unlock()

 	GoLog("[Deezer] Album metadata fetched - Genre: %s, Label: %s\n", result.Genre, result.Label)
@@ -0,0 +1,561 @@
+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 != "" {
+		return fmt.Sprintf("https://www.deezer.com/track/%s", deezerID), nil
+	}
+
+	// Try resolving Deezer ID from Spotify ID via SongLink
+	spotifyID := strings.TrimSpace(req.SpotifyID)
+	if spotifyID != "" && isLikelySpotifyTrackID(spotifyID) {
+		songlink := NewSongLinkClient()
+		availability, err := songlink.CheckTrackAvailability(spotifyID, "")
+		if err == nil && availability.Deezer && availability.DeezerURL != "" {
+			return availability.DeezerURL, nil
+		}
+	}
+
+	// Try resolving from 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 {
+			deezerID = songLinkExtractDeezerTrackID(track)
+			if deezerID != "" {
+				return fmt.Sprintf("https://www.deezer.com/track/%s", deezerID), nil
+			}
+		}
+	}
+
+	return "", fmt.Errorf("could not resolve Deezer track URL")
+}
+
+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
+		}
+	}
+
+	spotifyURL, err := resolveSpotifyURLForYoinkify(req)
+	if err != nil {
+		return DeezerDownloadResult{}, err
+	}
+
+	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 {
+		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
+}
@@ -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 {
@@ -243,6 +244,7 @@ func (m *ExtensionManager) initializeVM(ext *LoadedExtension) error {
 	}

 	runtime := NewExtensionRuntime(ext)
+	ext.runtime = runtime
 	runtime.RegisterAPIs(vm)
 	runtime.RegisterGoBackendAPIs(vm)

@@ -295,6 +297,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 +401,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)
@@ -458,17 +466,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 +522,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 +532,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 +592,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 +616,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 +664,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 {
@@ -713,6 +709,7 @@ func (m *ExtensionManager) GetInstalledExtensionsJSON() (string, error) {
 		Permissions            []string               `json:"permissions"`
 		HasMetadataProvider    bool                   `json:"has_metadata_provider"`
 		HasDownloadProvider    bool                   `json:"has_download_provider"`
+		HasLyricsProvider      bool                   `json:"has_lyrics_provider"`
 		SkipMetadataEnrichment bool                   `json:"skip_metadata_enrichment"`
 		SearchBehavior         *SearchBehaviorConfig  `json:"search_behavior,omitempty"`
 		TrackMatching          *TrackMatchingConfig   `json:"track_matching,omitempty"`
@@ -730,7 +727,6 @@ func (m *ExtensionManager) GetInstalledExtensionsJSON() (string, error) {
 			permissions = append(permissions, "storage:enabled")
 		}

-		// Determine status
 		status := "loaded"
 		if ext.Error != "" {
 			status = "error"
@@ -770,6 +766,7 @@ func (m *ExtensionManager) GetInstalledExtensionsJSON() (string, error) {
 			Permissions:            permissions,
 			HasMetadataProvider:    ext.Manifest.IsMetadataProvider(),
 			HasDownloadProvider:    ext.Manifest.IsDownloadProvider(),
+			HasLyricsProvider:      ext.Manifest.IsLyricsProvider(),
 			SkipMetadataEnrichment: ext.Manifest.SkipMetadataEnrichment,
 			SearchBehavior:         ext.Manifest.SearchBehavior,
 			TrackMatching:          ext.Manifest.TrackMatching,
@@ -907,7 +904,6 @@ func (m *ExtensionManager) UnloadAllExtensions() {
 	m.mu.Unlock()

 	for _, id := range extensionIDs {
-		m.CleanupExtension(id)
 		m.UnloadExtension(id)
 	}

@@ -931,7 +927,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') {
@@ -1,4 +1,3 @@
-// Package gobackend provides extension manifest parsing and validation
 package gobackend

 import (
@@ -12,6 +11,7 @@ type ExtensionType string
 const (
 	ExtensionTypeMetadataProvider ExtensionType = "metadata_provider"
 	ExtensionTypeDownloadProvider ExtensionType = "download_provider"
+	ExtensionTypeLyricsProvider   ExtensionType = "lyrics_provider"
 )

 type SettingType string
@@ -167,10 +167,10 @@ func (m *ExtensionManifest) Validate() error {
 	}

 	for _, t := range m.Types {
-		if t != ExtensionTypeMetadataProvider && t != ExtensionTypeDownloadProvider {
+		if t != ExtensionTypeMetadataProvider && t != ExtensionTypeDownloadProvider && t != ExtensionTypeLyricsProvider {
 			return &ManifestValidationError{
 				Field:   "type",
-				Message: fmt.Sprintf("invalid extension type: %s (must be 'metadata_provider' or 'download_provider')", t),
+				Message: fmt.Sprintf("invalid extension type: %s (must be 'metadata_provider', 'download_provider', or 'lyrics_provider')", t),
 			}
 		}
 	}
@@ -226,6 +226,10 @@ func (m *ExtensionManifest) IsDownloadProvider() bool {
 	return m.HasType(ExtensionTypeDownloadProvider)
 }

+func (m *ExtensionManifest) IsLyricsProvider() bool {
+	return m.HasType(ExtensionTypeLyricsProvider)
+}
+
 func (m *ExtensionManifest) IsDomainAllowed(domain string) bool {
 	domain = strings.ToLower(strings.TrimSpace(domain))
 	for _, allowed := range m.Permissions.Network {
@@ -1,4 +1,3 @@
-// Package gobackend provides extension provider interfaces
 package gobackend

 import (
@@ -6,7 +5,9 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"os"
 	"path/filepath"
+	"sort"
 	"strings"
 	"sync"
 	"time"
@@ -14,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"`
@@ -102,15 +100,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 {
@@ -391,7 +390,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)
 	}
@@ -406,11 +405,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 {
@@ -634,7 +633,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))
@@ -645,8 +644,26 @@ 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)+1)
+	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)
+	}
+	if _, exists := seen["deezer"]; !exists {
+		sanitized = append([]string{"deezer"}, sanitized...)
+	}
+
+	metadataProviderPriority = sanitized
+	GoLog("[Extension] Metadata provider priority set: %v\n", sanitized)
 }

 func GetMetadataProviderPriority() []string {
@@ -654,7 +671,7 @@ func GetMetadataProviderPriority() []string {
 	defer metadataProviderPriorityMu.RUnlock()

 	if len(metadataProviderPriority) == 0 {
-		return []string{"deezer", "spotify"}
+		return []string{"deezer"}
 	}

 	result := make([]string, len(metadataProviderPriority))
@@ -664,7 +681,7 @@ func GetMetadataProviderPriority() []string {

 func isBuiltInProvider(providerID string) bool {
 	switch providerID {
-	case "tidal", "qobuz", "amazon", "deezer":
+	case "tidal", "qobuz", "deezer":
 		return true
 	default:
 		return false
@@ -674,8 +691,20 @@ func isBuiltInProvider(providerID string) bool {
 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 {
@@ -685,12 +714,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)
@@ -753,7 +803,9 @@ func DownloadWithExtensionFallback(req DownloadRequest) (*DownloadResponse, erro
 		}
 	}

-	if req.Source != "" && !isBuiltInProvider(req.Source) {
+	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)
@@ -766,13 +818,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{
@@ -785,9 +854,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 {
@@ -859,18 +929,23 @@ 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 isBuiltInProvider(providerIDNormalized) {
 			if (req.Genre == "" || req.Label == "") && req.ISRC != "" {
 				GoLog("[DownloadWithExtensionFallback] Enriching extended metadata from Deezer for ISRC: %s\n", req.ISRC)
 				ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
@@ -891,9 +966,9 @@ func DownloadWithExtensionFallback(req DownloadRequest) (*DownloadResponse, erro
 				}
 			}

-			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
 				}
@@ -914,11 +989,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)
@@ -933,7 +1008,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 {
@@ -942,13 +1017,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{
@@ -961,9 +1053,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 {
@@ -1078,23 +1171,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,
+				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)
 	}
@@ -1119,6 +1213,8 @@ func tryBuiltInProvider(providerID string, req DownloadRequest) (*DownloadRespon
 		Genre:            req.Genre,
 		Label:            req.Label,
 		Copyright:        req.Copyright,
+		LyricsLRC:        result.LyricsLRC,
+		DecryptionKey:    result.DecryptionKey,
 	}, nil
 }

@@ -1132,8 +1228,13 @@ func buildOutputPath(req DownloadRequest) string {
 		"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,
 	}

@@ -1149,7 +1250,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) {
@@ -1164,16 +1316,30 @@ func (p *ExtensionProviderWrapper) CustomSearch(query string, options map[string
 	p.extension.VMMu.Lock()
 	defer p.extension.VMMu.Unlock()

-	optionsJSON, _ := json.Marshal(options)
+	if options == nil {
+		options = map[string]interface{}{}
+	}

-	script := fmt.Sprintf(`
+	// Avoid embedding user input directly into JS source. Some inputs can trigger
+	// parser/runtime edge cases on specific devices/Goja builds.
+	const queryVar = "__sf_custom_search_query"
+	const optionsVar = "__sf_custom_search_options"
+	global := p.vm.GlobalObject()
+	_ = global.Set(queryVar, query)
+	_ = global.Set(optionsVar, options)
+	defer func() {
+		global.Delete(queryVar)
+		global.Delete(optionsVar)
+	}()
+
+	const script = `
 		(function() {
 			if (typeof extension !== 'undefined' && typeof extension.customSearch === 'function') {
-				return extension.customSearch(%q, %s);
+				return extension.customSearch(__sf_custom_search_query, __sf_custom_search_options);
 			}
 			return null;
 		})()
-	`, query, string(optionsJSON))
+	`

 	result, err := RunWithTimeoutAndRecover(p.vm, script, DefaultJSTimeout)
 	if err != nil {
@@ -1358,12 +1524,12 @@ type PostProcessResult struct {
 }

 type PostProcessInput struct {
-	Path    string `json:"path,omitempty"`
-	URI     string `json:"uri,omitempty"`
-	Name    string `json:"name,omitempty"`
+	Path     string `json:"path,omitempty"`
+	URI      string `json:"uri,omitempty"`
+	Name     string `json:"name,omitempty"`
 	MimeType string `json:"mime_type,omitempty"`
-	Size    int64  `json:"size,omitempty"`
-	IsSAF   bool   `json:"is_saf,omitempty"`
+	Size     int64  `json:"size,omitempty"`
+	IsSAF    bool   `json:"is_saf,omitempty"`
 }

 const PostProcessTimeout = 2 * time.Minute
@@ -1562,7 +1728,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()
@@ -1576,7 +1741,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 {
@@ -1622,7 +1786,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 {
@@ -1676,3 +1839,135 @@ func (m *ExtensionManager) RunPostProcessingV2(input PostProcessInput, metadata

 	return &PostProcessResult{Success: true, NewFilePath: currentInput.Path, NewFileURI: currentInput.URI}, nil
 }
+
+type ExtLyricsResult struct {
+	Lines        []ExtLyricsLine `json:"lines"`
+	SyncType     string          `json:"syncType"`
+	Instrumental bool            `json:"instrumental"`
+	PlainLyrics  string          `json:"plainLyrics"`
+	Provider     string          `json:"provider"`
+}
+
+type ExtLyricsLine struct {
+	StartTimeMs int64  `json:"startTimeMs"`
+	Words       string `json:"words"`
+	EndTimeMs   int64  `json:"endTimeMs"`
+}
+
+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)
+	}
+
+	if !p.extension.Enabled {
+		return nil, fmt.Errorf("extension '%s' is disabled", p.extension.ID)
+	}
+
+	p.extension.VMMu.Lock()
+	defer p.extension.VMMu.Unlock()
+
+	// Use global variables to avoid JS injection issues with special characters in track/artist names
+	const trackVar = "__sf_lyrics_track"
+	const artistVar = "__sf_lyrics_artist"
+	const albumVar = "__sf_lyrics_album"
+	const durationVar = "__sf_lyrics_duration"
+	global := p.vm.GlobalObject()
+	_ = global.Set(trackVar, trackName)
+	_ = global.Set(artistVar, artistName)
+	_ = global.Set(albumVar, albumName)
+	_ = global.Set(durationVar, durationSec)
+	defer func() {
+		global.Delete(trackVar)
+		global.Delete(artistVar)
+		global.Delete(albumVar)
+		global.Delete(durationVar)
+	}()
+
+	const script = `
+		(function() {
+			if (typeof extension !== 'undefined' && typeof extension.fetchLyrics === 'function') {
+				return extension.fetchLyrics(__sf_lyrics_track, __sf_lyrics_artist, __sf_lyrics_album, __sf_lyrics_duration);
+			}
+			return null;
+		})()
+	`
+
+	result, err := RunWithTimeoutAndRecover(p.vm, script, DefaultJSTimeout)
+	if err != nil {
+		if IsTimeoutError(err) {
+			return nil, fmt.Errorf("fetchLyrics timeout: extension took too long to respond")
+		}
+		return nil, fmt.Errorf("fetchLyrics failed: %w", err)
+	}
+
+	if result == nil || goja.IsUndefined(result) || goja.IsNull(result) {
+		return nil, fmt.Errorf("fetchLyrics returned null")
+	}
+
+	exported := result.Export()
+	jsonBytes, err := json.Marshal(exported)
+	if err != nil {
+		return nil, fmt.Errorf("failed to marshal lyrics result: %w", err)
+	}
+
+	var extResult ExtLyricsResult
+	if err := json.Unmarshal(jsonBytes, &extResult); err != nil {
+		return nil, fmt.Errorf("failed to parse lyrics result: %w", err)
+	}
+
+	// Convert ExtLyricsResult to LyricsResponse
+	response := &LyricsResponse{
+		SyncType:     extResult.SyncType,
+		Instrumental: extResult.Instrumental,
+		PlainLyrics:  extResult.PlainLyrics,
+		Provider:     extResult.Provider,
+		Source:       "Extension: " + p.extension.ID,
+	}
+
+	if response.Provider == "" {
+		response.Provider = p.extension.Manifest.DisplayName
+	}
+
+	for _, line := range extResult.Lines {
+		response.Lines = append(response.Lines, LyricsLine{
+			StartTimeMs: line.StartTimeMs,
+			Words:       line.Words,
+			EndTimeMs:   line.EndTimeMs,
+		})
+	}
+
+	// If the extension provided plainLyrics but no lines, parse them as unsynced
+	if len(response.Lines) == 0 && response.PlainLyrics != "" && !response.Instrumental {
+		response.SyncType = "UNSYNCED"
+		for _, line := range strings.Split(response.PlainLyrics, "\n") {
+			if strings.TrimSpace(line) != "" {
+				response.Lines = append(response.Lines, LyricsLine{
+					StartTimeMs: 0,
+					Words:       line,
+					EndTimeMs:   0,
+				})
+			}
+		}
+	}
+
+	return response, nil
+}
+
+func (m *ExtensionManager) GetLyricsProviders() []*ExtensionProviderWrapper {
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+
+	var providers []*ExtensionProviderWrapper
+	for _, ext := range m.extensions {
+		if ext.Enabled && ext.Manifest.IsLyricsProvider() && ext.Error == "" {
+			providers = append(providers, NewExtensionProviderWrapper(ext))
+		}
+	}
+
+	// Keep a deterministic order so provider selection is stable across runs.
+	sort.Slice(providers, func(i, j int) bool {
+		return providers[i].extension.ID < providers[j].extension.ID
+	})
+
+	return providers
+}
@@ -88,47 +88,82 @@ type ExtensionRuntime struct {
 	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,
 	}

+	// 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{
-		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")
-			}
+		Transport: sharedTransport,
+		Timeout:   30 * time.Second,
+		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
-		},
+		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

@@ -147,7 +182,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 +196,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 {
@@ -1,4 +1,3 @@
-// Package gobackend provides Auth API and PKCE support for extension runtime
 package gobackend

 import (
@@ -16,7 +15,42 @@ import (
 	"github.com/dop251/goja"
 )

-// ==================== Auth API (OAuth Support) ====================
+func validateExtensionAuthURL(urlStr string) error {
+	parsed, err := url.Parse(urlStr)
+	if err != nil {
+		return fmt.Errorf("invalid auth URL: %w", err)
+	}
+
+	if parsed.Scheme != "https" {
+		return fmt.Errorf("invalid auth URL: only https is allowed")
+	}
+
+	host := parsed.Hostname()
+	if host == "" {
+		return fmt.Errorf("invalid auth URL: hostname is required")
+	}
+
+	if parsed.User != nil {
+		return fmt.Errorf("invalid auth URL: embedded credentials are not allowed")
+	}
+
+	if isPrivateIP(host) {
+		return fmt.Errorf("invalid auth URL: private/local network is not allowed")
+	}
+
+	return nil
+}
+
+func summarizeURLForLog(urlStr string) string {
+	parsed, err := url.Parse(urlStr)
+	if err != nil {
+		return urlStr
+	}
+	if parsed.Host == "" {
+		return parsed.Scheme + "://"
+	}
+	return fmt.Sprintf("%s://%s%s", parsed.Scheme, parsed.Host, parsed.Path)
+}

 func (r *ExtensionRuntime) authOpenUrl(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
@@ -32,6 +66,13 @@ func (r *ExtensionRuntime) authOpenUrl(call goja.FunctionCall) goja.Value {
 		callbackURL = call.Arguments[1].String()
 	}

+	if err := validateExtensionAuthURL(authURL); err != nil {
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   err.Error(),
+		})
+	}
+
 	pendingAuthRequestsMu.Lock()
 	pendingAuthRequests[r.extensionID] = &PendingAuthRequest{
 		ExtensionID: r.extensionID,
@@ -50,7 +91,7 @@ func (r *ExtensionRuntime) authOpenUrl(call goja.FunctionCall) goja.Value {
 	state.AuthCode = ""
 	extensionAuthStateMu.Unlock()

-	GoLog("[Extension:%s] Auth URL requested: %s\n", r.extensionID, authURL)
+	GoLog("[Extension:%s] Auth URL requested: %s\n", r.extensionID, summarizeURLForLog(authURL))

 	return r.vm.ToValue(map[string]interface{}{
 		"success": true,
@@ -160,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 {
@@ -273,6 +311,12 @@ func (r *ExtensionRuntime) authStartOAuthWithPKCE(call goja.FunctionCall) goja.V
 			"error":   "authUrl, clientId, and redirectUri are required",
 		})
 	}
+	if err := validateExtensionAuthURL(authURL); err != nil {
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   err.Error(),
+		})
+	}

 	scope, _ := config["scope"].(string)
 	extraParams, _ := config["extraParams"].(map[string]interface{})
@@ -331,7 +375,7 @@ func (r *ExtensionRuntime) authStartOAuthWithPKCE(call goja.FunctionCall) goja.V
 	}
 	pendingAuthRequestsMu.Unlock()

-	GoLog("[Extension:%s] PKCE OAuth started: %s\n", r.extensionID, fullAuthURL)
+	GoLog("[Extension:%s] PKCE OAuth started: %s\n", r.extensionID, summarizeURLForLog(fullAuthURL))

 	return r.vm.ToValue(map[string]interface{}{
 		"success": true,
@@ -344,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{}{
@@ -364,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)
@@ -441,13 +482,17 @@ func (r *ExtensionRuntime) authExchangeCodeWithPKCE(call goja.FunctionCall) goja
 			"error":   err.Error(),
 		})
 	}
+	bodyPreview := sanitizeSensitiveLogText(string(body))
+	if len(bodyPreview) > 1000 {
+		bodyPreview = bodyPreview[:1000] + "...[truncated]"
+	}

 	var tokenResp map[string]interface{}
 	if err := json.Unmarshal(body, &tokenResp); err != nil {
 		return r.vm.ToValue(map[string]interface{}{
 			"success": false,
 			"error":   fmt.Sprintf("failed to parse token response: %v", err),
-			"body":    string(body),
+			"body":    bodyPreview,
 		})
 	}

@@ -468,7 +513,7 @@ func (r *ExtensionRuntime) authExchangeCodeWithPKCE(call goja.FunctionCall) goja
 		return r.vm.ToValue(map[string]interface{}{
 			"success": false,
 			"error":   "no access_token in response",
-			"body":    string(body),
+			"body":    bodyPreview,
 		})
 	}

@@ -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
@@ -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
@@ -396,13 +393,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 +410,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),
 		})
 	}

@@ -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"`
@@ -32,6 +29,9 @@ func (r *ExtensionRuntime) validateDomain(urlStr string) error {
 	if parsed.Scheme != "https" {
 		return fmt.Errorf("network access denied: only https is allowed")
 	}
+	if parsed.User != nil {
+		return fmt.Errorf("invalid URL: embedded credentials are not allowed")
+	}

 	domain := parsed.Hostname()
 	if domain == "" {
@@ -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)
@@ -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 = {
@@ -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, 0644)
+	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)
 }

@@ -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"])
+	}
+}
@@ -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("")
@@ -1,4 +1,3 @@
-// Package gobackend provides extension settings storage
 package gobackend

 import (
@@ -77,7 +77,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"`
@@ -218,7 +217,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 +309,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)
@@ -421,7 +420,6 @@ func (s *ExtensionStore) ClearCache() {
 	LogInfo("ExtensionStore", "Cache cleared")
 }

-// Helper: case-insensitive contains
 func containsIgnoreCase(s, substr string) bool {
 	return containsStr(toLower(s), substr)
 }
@@ -1,9 +1,9 @@
-// Package gobackend provides timeout execution for extension JS code
 package gobackend

 import (
 	"context"
 	"fmt"
+	"runtime/debug"
 	"sync"
 	"time"

@@ -49,6 +49,7 @@ func RunWithTimeout(vm *goja.Runtime, script string, timeout time.Duration) (goj
 						IsTimeout: true,
 					}}
 				} else {
+					GoLog("[ExtensionRuntime] panic during JS execution: %v\n%s\n", r, string(debug.Stack()))
 					resultCh <- result{nil, fmt.Errorf("panic during execution: %v", r)}
 				}
 			}
@@ -3,28 +3,35 @@ package gobackend
 import (
 	"fmt"
 	"regexp"
+	"strconv"
 	"strings"
+	"time"
 )

-var invalidChars = regexp.MustCompile(`[<>:"/\\|?*\x00-\x1f]`)
+var (
+	invalidChars                   = regexp.MustCompile(`[<>:"/\\|?*\x00-\x1f]`)
+	multiUnderscore                = regexp.MustCompile(`_+`)
+	formattedNumberPlaceholderExpr = regexp.MustCompile(`\{(track|disc):([0-9]+)\}`)
+	dateFormatPlaceholderExpr      = regexp.MustCompile(`\{date:([^{}]+)\}`)
+	yearPattern                    = regexp.MustCompile(`\d{4}`)
+)

 func sanitizeFilename(filename string) string {
 	sanitized := invalidChars.ReplaceAllString(filename, "_")
-	
+
 	sanitized = strings.TrimSpace(sanitized)
 	sanitized = strings.Trim(sanitized, ".")
-	
-	multiUnderscore := regexp.MustCompile(`_+`)
+
 	sanitized = multiUnderscore.ReplaceAllString(sanitized, "_")
-	
+
 	if len(sanitized) > 200 {
 		sanitized = sanitized[:200]
 	}
-	
+
 	if sanitized == "" {
 		sanitized = "untitled"
 	}
-	
+
 	return sanitized
 }

@@ -32,45 +39,120 @@ func buildFilenameFromTemplate(template string, metadata map[string]interface{})
 	if template == "" {
 		template = "{artist} - {title}"
 	}
-	
-	result := template
-	
-	placeholders := map[string]string{
-		"{title}":  getString(metadata, "title"),
-		"{artist}": getString(metadata, "artist"),
-		"{album}":  getString(metadata, "album"),
-		"{track}":  formatTrackNumber(getInt(metadata, "track")),
-		"{year}":   getString(metadata, "year"),
-		"{disc}":   formatDiscNumber(getInt(metadata, "disc")),
+
+	result := replaceFormattedNumberPlaceholders(template, metadata)
+	result = replaceDateFormatPlaceholders(result, metadata)
+
+	dateValue := getDateValue(metadata)
+	yearValue := getString(metadata, "year")
+	if yearValue == "" {
+		yearValue = extractYear(dateValue)
 	}
-	
+
+	placeholders := map[string]string{
+		"{title}":     getString(metadata, "title"),
+		"{artist}":    getString(metadata, "artist"),
+		"{album}":     getString(metadata, "album"),
+		"{track}":     formatTrackNumber(getInt(metadata, "track")),
+		"{track_raw}": formatRawNumber(getInt(metadata, "track")),
+		"{year}":      yearValue,
+		"{date}":      dateValue,
+		"{disc}":      formatDiscNumber(getInt(metadata, "disc")),
+		"{disc_raw}":  formatRawNumber(getInt(metadata, "disc")),
+	}
+
 	for placeholder, value := range placeholders {
 		result = strings.ReplaceAll(result, placeholder, value)
 	}
-	
+
 	return result
 }

+func replaceFormattedNumberPlaceholders(template string, metadata map[string]interface{}) string {
+	return formattedNumberPlaceholderExpr.ReplaceAllStringFunc(template, func(match string) string {
+		parts := formattedNumberPlaceholderExpr.FindStringSubmatch(match)
+		if len(parts) != 3 {
+			return ""
+		}
+
+		number := getInt(metadata, parts[1])
+		width, err := strconv.Atoi(parts[2])
+		if err != nil {
+			return ""
+		}
+
+		return formatNumberWithWidth(number, width)
+	})
+}
+
+func replaceDateFormatPlaceholders(template string, metadata map[string]interface{}) string {
+	return dateFormatPlaceholderExpr.ReplaceAllStringFunc(template, func(match string) string {
+		parts := dateFormatPlaceholderExpr.FindStringSubmatch(match)
+		if len(parts) != 2 {
+			return ""
+		}
+
+		return formatDateWithPattern(getDateValue(metadata), parts[1])
+	})
+}
+
+func getDateValue(metadata map[string]interface{}) string {
+	date := getString(metadata, "date")
+	if date != "" {
+		return date
+	}
+
+	releaseDate := getString(metadata, "release_date")
+	if releaseDate != "" {
+		return releaseDate
+	}
+
+	return getString(metadata, "year")
+}
+
 func getString(m map[string]interface{}, key string) string {
 	if v, ok := m[key]; ok {
-		if s, ok := v.(string); ok {
-			return strings.TrimSpace(s)
+		switch value := v.(type) {
+		case string:
+			return strings.TrimSpace(value)
+		case int:
+			return strconv.Itoa(value)
+		case int64:
+			return strconv.FormatInt(value, 10)
+		case float64:
+			return strconv.Itoa(int(value))
 		}
 	}
 	return ""
 }

 func getInt(m map[string]interface{}, key string) int {
-	if v, ok := m[key]; ok {
-		switch n := v.(type) {
-		case int:
-			return n
-		case int64:
-			return int(n)
-		case float64:
-			return int(n)
+	candidateKeys := []string{key}
+	switch key {
+	case "track":
+		candidateKeys = append(candidateKeys, "track_number")
+	case "disc":
+		candidateKeys = append(candidateKeys, "disc_number")
+	}
+
+	for _, candidate := range candidateKeys {
+		if v, ok := m[candidate]; ok {
+			switch n := v.(type) {
+			case int:
+				return n
+			case int64:
+				return int(n)
+			case float64:
+				return int(n)
+			case string:
+				parsed, err := strconv.Atoi(strings.TrimSpace(n))
+				if err == nil {
+					return parsed
+				}
+			}
 		}
 	}
+
 	return 0
 }

@@ -88,6 +170,129 @@ func formatDiscNumber(n int) string {
 	return fmt.Sprintf("%d", n)
 }

+func formatRawNumber(n int) string {
+	if n <= 0 {
+		return ""
+	}
+	return fmt.Sprintf("%d", n)
+}
+
+func formatNumberWithWidth(n int, width int) string {
+	if n <= 0 || width <= 0 {
+		return ""
+	}
+	if width <= 1 {
+		return formatRawNumber(n)
+	}
+	return fmt.Sprintf("%0*d", width, n)
+}
+
+func formatDateWithPattern(rawDate string, strftimePattern string) string {
+	if rawDate == "" || strftimePattern == "" {
+		return ""
+	}
+
+	parsedDate, ok := parseMetadataDate(rawDate)
+	if !ok {
+		return ""
+	}
+
+	goLayout := convertStrftimeToGoLayout(strftimePattern)
+	if goLayout == "" {
+		return ""
+	}
+
+	return parsedDate.Format(goLayout)
+}
+
+func parseMetadataDate(rawDate string) (time.Time, bool) {
+	clean := strings.TrimSpace(rawDate)
+	if clean == "" {
+		return time.Time{}, false
+	}
+
+	layouts := []string{
+		time.RFC3339Nano,
+		time.RFC3339,
+		"2006-01-02",
+		"2006-01",
+		"2006",
+		"2006/01/02",
+		"2006/01",
+		"2006.01.02",
+		"2006.01",
+	}
+
+	for _, layout := range layouts {
+		parsed, err := time.Parse(layout, clean)
+		if err == nil {
+			return parsed, true
+		}
+	}
+
+	if len(clean) >= 10 {
+		parsed, err := time.Parse("2006-01-02", clean[:10])
+		if err == nil {
+			return parsed, true
+		}
+	}
+
+	yearMatch := yearPattern.FindString(clean)
+	if yearMatch == "" {
+		return time.Time{}, false
+	}
+
+	year, err := strconv.Atoi(yearMatch)
+	if err != nil || year <= 0 {
+		return time.Time{}, false
+	}
+
+	return time.Date(year, time.January, 1, 0, 0, 0, 0, time.UTC), true
+}
+
+func convertStrftimeToGoLayout(pattern string) string {
+	if pattern == "" {
+		return ""
+	}
+
+	var builder strings.Builder
+	for i := 0; i < len(pattern); i++ {
+		ch := pattern[i]
+		if ch != '%' {
+			builder.WriteByte(ch)
+			continue
+		}
+
+		if i+1 >= len(pattern) {
+			builder.WriteByte('%')
+			break
+		}
+
+		i++
+		switch pattern[i] {
+		case 'Y':
+			builder.WriteString("2006")
+		case 'y':
+			builder.WriteString("06")
+		case 'm':
+			builder.WriteString("01")
+		case 'd':
+			builder.WriteString("02")
+		case 'b':
+			builder.WriteString("Jan")
+		case 'B':
+			builder.WriteString("January")
+		case '%':
+			builder.WriteByte('%')
+		default:
+			builder.WriteByte('%')
+			builder.WriteByte(pattern[i])
+		}
+	}
+
+	return builder.String()
+}
+
 func extractYear(date string) string {
 	if len(date) >= 4 {
 		return date[:4]
@@ -0,0 +1,85 @@
+package gobackend
+
+import "testing"
+
+func TestBuildFilenameFromTemplate_WithRawTrackAndDisc(t *testing.T) {
+	metadata := map[string]interface{}{
+		"title":  "Song Name",
+		"artist": "Artist Name",
+		"album":  "Album Name",
+		"track":  1,
+		"disc":   2,
+		"year":   "2025",
+	}
+
+	formatted := buildFilenameFromTemplate(
+		"{artist} - {track} - {track_raw} - d{disc} - d{disc_raw} - {title}",
+		metadata,
+	)
+
+	expected := "Artist Name - 01 - 1 - d2 - d2 - Song Name"
+	if formatted != expected {
+		t.Fatalf("expected %q, got %q", expected, formatted)
+	}
+}
+
+func TestBuildFilenameFromTemplate_RawPlaceholdersEmptyWhenZero(t *testing.T) {
+	metadata := map[string]interface{}{
+		"title":  "Song Name",
+		"artist": "Artist Name",
+		"track":  0,
+		"disc":   0,
+	}
+
+	formatted := buildFilenameFromTemplate("{track_raw}-{disc_raw}-{title}", metadata)
+	expected := "--Song Name"
+	if formatted != expected {
+		t.Fatalf("expected %q, got %q", expected, formatted)
+	}
+}
+
+func TestBuildFilenameFromTemplate_InlineNumberFormatting(t *testing.T) {
+	metadata := map[string]interface{}{
+		"track": 3,
+		"disc":  2,
+	}
+
+	formatted := buildFilenameFromTemplate("{track:1}-{track:02}-{disc:03}", metadata)
+	expected := "3-03-002"
+	if formatted != expected {
+		t.Fatalf("expected %q, got %q", expected, formatted)
+	}
+}
+
+func TestBuildFilenameFromTemplate_DateStrftimeFormatting(t *testing.T) {
+	metadata := map[string]interface{}{
+		"artist":       "Artist Name",
+		"title":        "Song Name",
+		"release_date": "2024-03-09",
+		"track_number": 7,
+		"disc_number":  1,
+	}
+
+	formatted := buildFilenameFromTemplate(
+		"{artist} - {track:02} - {title} - {date:%Y-%m-%d} - {year}",
+		metadata,
+	)
+	expected := "Artist Name - 07 - Song Name - 2024-03-09 - 2024"
+	if formatted != expected {
+		t.Fatalf("expected %q, got %q", expected, formatted)
+	}
+}
+
+func TestBuildFilenameFromTemplate_DateStrftimeFormattingWithYearOnly(t *testing.T) {
+	metadata := map[string]interface{}{
+		"artist": "Artist Name",
+		"title":  "Song Name",
+		"date":   "2019",
+	}
+
+	formatted := buildFilenameFromTemplate("{date:%Y}-{date:%m}-{date:%d}", metadata)
+	expected := "2019-01-01"
+	if formatted != expected {
+		t.Fatalf("expected %q, got %q", expected, formatted)
+	}
+}
@@ -5,16 +5,13 @@ go 1.25.0
 toolchain go1.25.7

 require (
-	github.com/dop251/goja v0.0.0-20260106131823-651366fbe6e3
-	github.com/go-flac/flacpicture v0.3.0
+	github.com/dop251/goja v0.0.0-20260216154549-8b74ce4618c5
 	github.com/go-flac/flacpicture/v2 v2.0.2
-	github.com/go-flac/flacvorbis v0.2.0
 	github.com/go-flac/flacvorbis/v2 v2.0.2
-	github.com/go-flac/go-flac v1.0.0
 	github.com/go-flac/go-flac/v2 v2.0.4
 	github.com/refraction-networking/utls v1.8.2
-	golang.org/x/mobile v0.0.0-20260204172633-1dceadbbeea3
-	golang.org/x/net v0.49.0
+	golang.org/x/mobile v0.0.0-20260211191516-dcd2a3258864
+	golang.org/x/net v0.50.0
 )

 require (
@@ -23,10 +20,10 @@ require (
 	github.com/go-sourcemap/sourcemap v2.1.3+incompatible // indirect
 	github.com/google/pprof v0.0.0-20230207041349-798e818bf904 // indirect
 	github.com/klauspost/compress v1.17.4 // indirect
-	golang.org/x/crypto v0.47.0 // indirect
-	golang.org/x/mod v0.32.0 // indirect
+	golang.org/x/crypto v0.48.0 // indirect
+	golang.org/x/mod v0.33.0 // indirect
 	golang.org/x/sync v0.19.0 // indirect
-	golang.org/x/sys v0.40.0 // indirect
-	golang.org/x/text v0.33.0 // indirect
-	golang.org/x/tools v0.41.0 // indirect
+	golang.org/x/sys v0.41.0 // indirect
+	golang.org/x/text v0.34.0 // indirect
+	golang.org/x/tools v0.42.0 // indirect
 )
@@ -2,18 +2,19 @@ github.com/Masterminds/semver/v3 v3.2.1 h1:RN9w6+7QoMeJVGyfmbcgs28Br8cvmnucEXnY0
 github.com/Masterminds/semver/v3 v3.2.1/go.mod h1:qvl/7zhW3nngYb5+80sSMF+FG2BjYrf8m9wsX0PNOMQ=
 github.com/andybalholm/brotli v1.0.6 h1:Yf9fFpf49Zrxb9NlQaluyE92/+X7UVHlhMNJN2sxfOI=
 github.com/andybalholm/brotli v1.0.6/go.mod h1:fO7iG3H7G2nSZ7m0zPUDn85XEX2GTukHGRSepvi9Eig=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/dlclark/regexp2 v1.11.4 h1:rPYF9/LECdNymJufQKmri9gV604RvvABwgOA8un7yAo=
 github.com/dlclark/regexp2 v1.11.4/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8=
 github.com/dop251/goja v0.0.0-20260106131823-651366fbe6e3 h1:bVp3yUzvSAJzu9GqID+Z96P+eu5TKnIMJSV4QaZMauM=
 github.com/dop251/goja v0.0.0-20260106131823-651366fbe6e3/go.mod h1:MxLav0peU43GgvwVgNbLAj1s/bSGboKkhuULvq/7hx4=
-github.com/go-flac/flacpicture v0.3.0 h1:LkmTxzFLIynwfhHiZsX0s8xcr3/u33MzvV89u+zOT8I=
-github.com/go-flac/flacpicture v0.3.0/go.mod h1:DPbrzVYQ3fJcvSgLFp9HXIrEQEdfdk/+m0nQCzwodZI=
+github.com/dop251/goja v0.0.0-20260216154549-8b74ce4618c5 h1:QckvTXtu55YMopmVeDrPQ/r+T6xjw8KMCmE3UgUldkw=
+github.com/dop251/goja v0.0.0-20260216154549-8b74ce4618c5/go.mod h1:MxLav0peU43GgvwVgNbLAj1s/bSGboKkhuULvq/7hx4=
+github.com/go-flac/flacpicture/v2 v2.0.2 h1:HCaJIVZpxnpdWs6G3ECEVRelzqS5xOi1Ba1AGmtXbzE=
 github.com/go-flac/flacpicture/v2 v2.0.2/go.mod h1:DMZBPWPAmdLqNhqFSy5ZBs9wyBzOekXutGfP7/TFCuo=
-github.com/go-flac/flacvorbis v0.2.0 h1:KH0xjpkNTXFER4cszH4zeJxYcrHbUobz/RticWGOESs=
-github.com/go-flac/flacvorbis v0.2.0/go.mod h1:uIysHOtuU7OLGoCRG92bvnkg7QEqHx19qKRV6K1pBrI=
+github.com/go-flac/flacvorbis/v2 v2.0.2 h1:xCL3OhxrxWkHrbWUBvGNe+6FQ03yLmBbz0v5z4V2PoQ=
 github.com/go-flac/flacvorbis/v2 v2.0.2/go.mod h1:SwTB5gs13VaM/N7rstwPoUsPibiMKklgwybYP9dYo2g=
-github.com/go-flac/go-flac v1.0.0 h1:6qI9XOVLcO50xpzm3nXvO31BgDgHhnr/p/rER/K/doY=
-github.com/go-flac/go-flac v1.0.0/go.mod h1:WnZhcpmq4u1UdZMNn9LYSoASpWOCMOoxXxcWEHSzkW8=
+github.com/go-flac/go-flac/v2 v2.0.4 h1:atf/kFa8U9idtkA//NO22XGr+MzQLeXZecnmP9sYBf0=
 github.com/go-flac/go-flac/v2 v2.0.4/go.mod h1:sYOlTKxutMW0RDYF+KlD6Zn+VOCZlIFQG/r/usPveCs=
 github.com/go-sourcemap/sourcemap v2.1.3+incompatible h1:W1iEw64niKVGogNgBN3ePyLFfuisuzeidWPMPWmECqU=
 github.com/go-sourcemap/sourcemap v2.1.3+incompatible/go.mod h1:F8jJfvm2KbVjc5NqelyYJmf/v5J0dwNLS2mL4sNA1Jg=
@@ -23,25 +24,45 @@ github.com/google/pprof v0.0.0-20230207041349-798e818bf904 h1:4/hN5RUoecvl+RmJRE
 github.com/google/pprof v0.0.0-20230207041349-798e818bf904/go.mod h1:uglQLonpP8qtYCYyzA+8c/9qtqgA3qsXGYqCPKARAFg=
 github.com/klauspost/compress v1.17.4 h1:Ej5ixsIri7BrIjBkRZLTo6ghwrEtHFk7ijlczPW4fZ4=
 github.com/klauspost/compress v1.17.4/go.mod h1:/dCuZOvVtNoHsyb+cuJD3itjs3NbnF6KH9zAO4BDxPM=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/refraction-networking/utls v1.8.2 h1:j4Q1gJj0xngdeH+Ox/qND11aEfhpgoEvV+S9iJ2IdQo=
 github.com/refraction-networking/utls v1.8.2/go.mod h1:jkSOEkLqn+S/jtpEHPOsVv/4V4EVnelwbMQl4vCWXAM=
+github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA=
+github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
 golang.org/x/crypto v0.47.0 h1:V6e3FRj+n4dbpw86FJ8Fv7XVOql7TEwpHapKoMJ/GO8=
 golang.org/x/crypto v0.47.0/go.mod h1:ff3Y9VzzKbwSSEzWqJsJVBnWmRwRSHt/6Op5n9bQc4A=
-golang.org/x/mobile v0.0.0-20260120165949-40bd9ace6ce4 h1:C3JuLOLhdaE75vk5m7u18NvZciRk+lnO34xcXl3NPTU=
-golang.org/x/mobile v0.0.0-20260120165949-40bd9ace6ce4/go.mod h1:yHJY0EGzMJ0i5ONrrhdpDSSnoyres5LO7D2hSIbJJ5I=
+golang.org/x/crypto v0.48.0 h1:/VRzVqiRSggnhY7gNRxPauEQ5Drw9haKdM0jqfcCFts=
+golang.org/x/crypto v0.48.0/go.mod h1:r0kV5h3qnFPlQnBSrULhlsRfryS2pmewsg+XfMgkVos=
 golang.org/x/mobile v0.0.0-20260204172633-1dceadbbeea3 h1:NiJtT7g4ncNFVjVZMAYNBrPSNhIjFYPj8UKA8MEw2A4=
 golang.org/x/mobile v0.0.0-20260204172633-1dceadbbeea3/go.mod h1:wReH3Q1agKmmLapipWFnd4NSs8KPz3fK6mSEZjXLkrg=
+golang.org/x/mobile v0.0.0-20260209203831-923679eb55af h1:VqXrZNyqFISxo0rNDFZQlRDRIp7RXSJDeh/LbrK+W1k=
+golang.org/x/mobile v0.0.0-20260209203831-923679eb55af/go.mod h1:tbwefIr7RlQD1OpZ0KEZ9nux/uiihAOGdafgZfJkmII=
+golang.org/x/mobile v0.0.0-20260211191516-dcd2a3258864 h1:cTVynMSsMYgbUrtia2HB1jrhdUwQNtQti91vUCyjMp4=
+golang.org/x/mobile v0.0.0-20260211191516-dcd2a3258864/go.mod h1:4OGHIUSBiIqyFAQDaX1tpY0BVnO20DvNDeATBu8aeFQ=
 golang.org/x/mod v0.32.0 h1:9F4d3PHLljb6x//jOyokMv3eX+YDeepZSEo3mFJy93c=
 golang.org/x/mod v0.32.0/go.mod h1:SgipZ/3h2Ci89DlEtEXWUk/HteuRin+HHhN+WbNhguU=
+golang.org/x/mod v0.33.0 h1:tHFzIWbBifEmbwtGz65eaWyGiGZatSrT9prnU8DbVL8=
+golang.org/x/mod v0.33.0/go.mod h1:swjeQEj+6r7fODbD2cqrnje9PnziFuw4bmLbBZFrQ5w=
 golang.org/x/net v0.49.0 h1:eeHFmOGUTtaaPSGNmjBKpbng9MulQsJURQUAfUwY++o=
 golang.org/x/net v0.49.0/go.mod h1:/ysNB2EvaqvesRkuLAyjI1ycPZlQHM3q01F02UY/MV8=
+golang.org/x/net v0.50.0 h1:ucWh9eiCGyDR3vtzso0WMQinm2Dnt8cFMuQa9K33J60=
+golang.org/x/net v0.50.0/go.mod h1:UgoSli3F/pBgdJBHCTc+tp3gmrU4XswgGRgtnwWTfyM=
 golang.org/x/sync v0.19.0 h1:vV+1eWNmZ5geRlYjzm2adRgW2/mcpevXNg50YZtPCE4=
 golang.org/x/sync v0.19.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
 golang.org/x/sys v0.40.0 h1:DBZZqJ2Rkml6QMQsZywtnjnnGvHza6BTfYFWY9kjEWQ=
 golang.org/x/sys v0.40.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
+golang.org/x/sys v0.41.0 h1:Ivj+2Cp/ylzLiEU89QhWblYnOE9zerudt9Ftecq2C6k=
+golang.org/x/sys v0.41.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
 golang.org/x/text v0.33.0 h1:B3njUFyqtHDUI5jMn1YIr5B0IE2U0qck04r6d4KPAxE=
 golang.org/x/text v0.33.0/go.mod h1:LuMebE6+rBincTi9+xWTY8TztLzKHc/9C1uBCG27+q8=
+golang.org/x/text v0.34.0 h1:oL/Qq0Kdaqxa1KbNeMKwQq0reLCCaFtqu2eNuSeNHbk=
+golang.org/x/text v0.34.0/go.mod h1:homfLqTYRFyVYemLBFl5GgL/DWEiH5wcsQ5gSh1yziA=
 golang.org/x/tools v0.41.0 h1:a9b8iMweWG+S0OBnlU36rzLp20z1Rp10w+IY2czHTQc=
 golang.org/x/tools v0.41.0/go.mod h1:XSY6eDqxVNiYgezAVqqCeihT4j1U2CCsqvH3WhQpnlg=
+golang.org/x/tools v0.42.0 h1:uNgphsn75Tdz5Ji2q36v/nsFSfR/9BRFvqhGBaJGd5k=
+golang.org/x/tools v0.42.0/go.mod h1:Ma6lCIwGZvHK6XtgbswSoWroEkhugApmsXyrUmBhfr0=
 gopkg.in/yaml.v2 v2.4.0 h1:D8xgwECY7CYvx+Y2n4sBz93Jn9JRvxdiyyo8CTfuKaY=
 gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
@@ -11,6 +11,7 @@ import (
 	"net/url"
 	"strconv"
 	"strings"
+	"sync"
 	"syscall"
 	"time"
 )
@@ -37,6 +38,16 @@ const (
 	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,
@@ -55,19 +66,49 @@ var sharedTransport = &http.Transport{
 	DisableCompression:    true,
 }

+// metadataTransport is a separate transport for metadata API calls (Deezer, Spotify, SongLink).
+// Isolated from download traffic so that download failures cannot poison
+// the connection pool used by metadata enrichment.
+var metadataTransport = &http.Transport{
+	DialContext: (&net.Dialer{
+		Timeout:   30 * time.Second,
+		KeepAlive: 30 * time.Second,
+	}).DialContext,
+	MaxIdleConns:          30,
+	MaxIdleConnsPerHost:   5,
+	MaxConnsPerHost:       10,
+	IdleConnTimeout:       90 * time.Second,
+	TLSHandshakeTimeout:   10 * time.Second,
+	ExpectContinueTimeout: 1 * time.Second,
+	DisableKeepAlives:     false,
+	ForceAttemptHTTP2:     true,
+	WriteBufferSize:       32 * 1024,
+	ReadBufferSize:        32 * 1024,
+	DisableCompression:    true,
+}
+
 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,
+	}
+}
+
+// NewMetadataHTTPClient creates an HTTP client using the isolated metadata transport.
+// Use this for API calls that should not be affected by download traffic.
+func NewMetadataHTTPClient(timeout time.Duration) *http.Client {
+	return &http.Client{
+		Transport: newCompatibilityTransport(metadataTransport),
 		Timeout:   timeout,
 	}
 }
@@ -82,6 +123,110 @@ func GetDownloadClient() *http.Client {

 func CloseIdleConnections() {
 	sharedTransport.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
@@ -114,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())
@@ -124,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 {
@@ -345,7 +489,6 @@ func IsISPBlocking(err error, requestURL string) *ISPBlockingError {
 		}
 	}

-	// Check error message patterns for common ISP blocking indicators
 	blockingPatterns := []struct {
 		pattern string
 		reason  string
@@ -388,7 +531,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"
@@ -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)
 	}

@@ -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)
@@ -10,7 +10,6 @@ import (
 	"time"
 )

-// LibraryScanResult represents metadata from a scanned audio file
 type LibraryScanResult struct {
 	ID          string `json:"id"`
 	TrackName   string `json:"trackName"`
@@ -28,6 +27,7 @@ type LibraryScanResult struct {
 	ReleaseDate string `json:"releaseDate,omitempty"`
 	BitDepth    int    `json:"bitDepth,omitempty"`
 	SampleRate  int    `json:"sampleRate,omitempty"`
+	Bitrate     int    `json:"bitrate,omitempty"` // kbps, for lossy formats (MP3, Opus, Vorbis)
 	Genre       string `json:"genre,omitempty"`
 	Format      string `json:"format,omitempty"`
 }
@@ -41,7 +41,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
@@ -64,6 +63,49 @@ var supportedAudioFormats = map[string]bool{
 	".mp3":  true,
 	".opus": true,
 	".ogg":  true,
+	".cue":  true,
+}
+
+type libraryAudioFileInfo struct {
+	path    string
+	modTime int64
+}
+
+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) {
@@ -97,31 +139,16 @@ 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
 	}

+	audioFiles := make([]string, 0, len(audioFileInfos))
+	for _, fileInfo := range audioFileInfos {
+		audioFiles = append(audioFiles, fileInfo.path)
+	}
+
 	totalFiles := len(audioFiles)
 	libraryScanProgressMu.Lock()
 	libraryScanProgress.TotalFiles = totalFiles
@@ -140,6 +167,23 @@ func ScanLibraryFolder(folderPath string) (string, error) {
 	scanTime := time.Now().UTC().Format(time.RFC3339)
 	errorCount := 0

+	// Track audio files referenced by .cue sheets to avoid duplicates
+	cueReferencedAudioFiles := make(map[string]bool)
+
+	// First pass: scan .cue files to collect referenced audio paths
+	for _, filePath := range audioFiles {
+		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 != "" {
+					cueReferencedAudioFiles[audioPath] = true
+				}
+			}
+		}
+	}
+
 	for i, filePath := range audioFiles {
 		select {
 		case <-cancelCh:
@@ -153,6 +197,28 @@ func ScanLibraryFolder(folderPath string) (string, error) {
 		libraryScanProgress.ProgressPct = float64(i+1) / float64(totalFiles) * 100
 		libraryScanProgressMu.Unlock()

+		ext := strings.ToLower(filepath.Ext(filePath))
+
+		// Handle .cue files: produce multiple track results
+		if ext == ".cue" {
+			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 := scanAudioFile(filePath, scanTime)
 		if err != nil {
 			errorCount++
@@ -188,7 +254,6 @@ func scanAudioFile(filePath, scanTime string) (*LibraryScanResult, error) {
 		Format:    strings.TrimPrefix(ext, "."),
 	}

-	// Get file modification time
 	if info, err := os.Stat(filePath); err == nil {
 		result.FileModTime = info.ModTime().UnixMilli()
 	}
@@ -217,6 +282,18 @@ func scanAudioFile(filePath, scanTime string) (*LibraryScanResult, error) {
 	}
 }

+func applyDefaultLibraryMetadata(filePath string, result *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"
+	}
+}
+
 func scanFLACFile(filePath string, result *LibraryScanResult) (*LibraryScanResult, error) {
 	metadata, err := ReadMetadata(filePath)
 	if err != nil {
@@ -242,15 +319,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
 }
@@ -289,19 +358,14 @@ func scanMP3File(filePath string, result *LibraryScanResult) (*LibraryScanResult
 	quality, err := GetMP3Quality(filePath)
 	if err == nil {
 		result.SampleRate = quality.SampleRate
-		result.BitDepth = quality.BitDepth
+		result.BitDepth = quality.BitDepth // 0 for lossy
 		result.Duration = quality.Duration
+		if quality.Bitrate > 0 {
+			result.Bitrate = quality.Bitrate / 1000 // convert bps to kbps
+		}
 	}

-	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
 }
@@ -326,19 +390,14 @@ func scanOggFile(filePath string, result *LibraryScanResult) (*LibraryScanResult
 	quality, err := GetOggQuality(filePath)
 	if err == nil {
 		result.SampleRate = quality.SampleRate
-		result.BitDepth = quality.BitDepth
+		result.BitDepth = quality.BitDepth // 0 for lossy
 		result.Duration = quality.Duration
+		if quality.Bitrate > 0 {
+			result.Bitrate = quality.Bitrate / 1000 // convert bps to kbps
+		}
 	}

-	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
 }
@@ -444,7 +503,6 @@ 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 {
@@ -454,12 +512,10 @@ func ScanLibraryFolderIncremental(folderPath, existingFilesJSON string) (string,

 	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)
@@ -468,41 +524,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()
@@ -510,27 +539,67 @@ func ScanLibraryFolderIncremental(folderPath, existingFilesJSON string) (string,
 	libraryScanProgressMu.Unlock()

 	// Find files to scan (new or modified)
-	var filesToScan []fileInfo
+	var filesToScan []libraryAudioFileInfo
 	skippedCount := 0

+	// Build a set of existing CUE virtual path base files for incremental matching.
+	// CUE tracks are stored with virtual paths like "/path/album.cue#track01".
+	// We need to match these against the actual .cue file's modTime.
+	cueBaseModTimes := make(map[string]int64) // base cue path -> modTime from disk
+	for _, f := range currentFiles {
+		if strings.ToLower(filepath.Ext(f.path)) == ".cue" {
+			cueBaseModTimes[f.path] = f.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" {
+				hasCueTracks := false
+				for existingPath := range existingFiles {
+					if strings.HasPrefix(existingPath, f.path+"#track") {
+						hasCueTracks = true
+						break
+					}
+				}
+				if hasCueTracks {
+					// CUE file exists in DB via virtual paths; check if modTime changed
+					// Use modTime from any virtual path (they all share the same .cue modTime)
+					for existingPath, modTime := range existingFiles {
+						if strings.HasPrefix(existingPath, f.path+"#track") {
+							if f.modTime == modTime {
+								skippedCount++
+							} else {
+								filesToScan = append(filesToScan, f)
+							}
+							break
+						}
+					}
+					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)
 		}
 	}
@@ -555,11 +624,25 @@ 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)
+	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 != "" {
+					cueReferencedAudioFilesInc[audioPath] = true
+				}
+			}
+		}
+	}
+
 	for i, f := range filesToScan {
 		select {
 		case <-cancelCh:
@@ -573,6 +656,25 @@ func ScanLibraryFolderIncremental(folderPath, existingFilesJSON string) (string,
 		libraryScanProgress.ProgressPct = float64(skippedCount+i+1) / float64(totalFiles) * 100
 		libraryScanProgressMu.Unlock()

+		ext := strings.ToLower(filepath.Ext(f.path))
+
+		// Handle .cue files: produce multiple track results
+		if ext == ".cue" {
+			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 := scanAudioFile(f.path, scanTime)
 		if err != nil {
 			errorCount++
@@ -3,6 +3,7 @@ package gobackend
 import (
 	"encoding/json"
 	"fmt"
+	"regexp"
 	"strings"
 	"sync"
 	"time"
@@ -30,8 +31,22 @@ const (
 var (
 	globalLogBuffer *LogBuffer
 	logBufferOnce   sync.Once
+
+	authorizationBearerPattern = regexp.MustCompile(`(?i)\bAuthorization\b\s*[:=]\s*Bearer\s+[A-Za-z0-9._~+/\-]+=*`)
+	genericKeyValuePattern     = regexp.MustCompile(`(?i)\b(access[_\s-]?token|refresh[_\s-]?token|id[_\s-]?token|client[_\s-]?secret|authorization|password|api[_\s-]?key)\b(\s*[:=]\s*)([^\s,;]+)`)
+	queryTokenPattern          = regexp.MustCompile(`(?i)([?&](?:access_token|refresh_token|id_token|token|client_secret|api_key|apikey|password)=)[^&\s]+`)
+	bearerTokenPattern         = regexp.MustCompile(`(?i)\bBearer\s+[A-Za-z0-9._~+/\-]+=*`)
 )

+func sanitizeSensitiveLogText(message string) string {
+	redacted := message
+	redacted = authorizationBearerPattern.ReplaceAllString(redacted, "Authorization: Bearer [REDACTED]")
+	redacted = genericKeyValuePattern.ReplaceAllString(redacted, `${1}${2}[REDACTED]`)
+	redacted = queryTokenPattern.ReplaceAllString(redacted, `${1}[REDACTED]`)
+	redacted = bearerTokenPattern.ReplaceAllString(redacted, "Bearer [REDACTED]")
+	return redacted
+}
+
 func GetLogBuffer() *LogBuffer {
 	logBufferOnce.Do(func() {
 		globalLogBuffer = &LogBuffer{
@@ -71,6 +86,7 @@ func (lb *LogBuffer) Add(level, tag, message string) {
 		return
 	}

+	message = sanitizeSensitiveLogText(message)
 	message = truncateLogMessage(message)

 	entry := LogEntry{
@@ -20,6 +20,148 @@ const (
 	durationToleranceSec = 10.0
 )

+// Lyrics provider names (used in settings and cascade ordering)
+const (
+	LyricsProviderSpotifyAPI = "spotify_api"
+	LyricsProviderLRCLIB     = "lrclib"
+	LyricsProviderNetease    = "netease"
+	LyricsProviderMusixmatch = "musixmatch"
+	LyricsProviderAppleMusic = "apple_music"
+	LyricsProviderQQMusic    = "qqmusic"
+)
+
+// DefaultLyricsProviders is the default cascade order for lyrics fetching.
+// LRCLIB first (no proxy dependency), then the others.
+var DefaultLyricsProviders = []string{
+	LyricsProviderLRCLIB,
+	LyricsProviderSpotifyAPI,
+	LyricsProviderMusixmatch,
+	LyricsProviderNetease,
+	LyricsProviderAppleMusic,
+	LyricsProviderQQMusic,
+}
+
+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"`
+	IncludeRomanizationNetease bool   `json:"include_romanization_netease"`
+	MultiPersonWordByWord      bool   `json:"multi_person_word_by_word"`
+	MusixmatchLanguage         string `json:"musixmatch_language,omitempty"`
+}
+
+var defaultLyricsFetchOptions = LyricsFetchOptions{
+	IncludeTranslationNetease:  false,
+	IncludeRomanizationNetease: false,
+	MultiPersonWordByWord:      true,
+	MusixmatchLanguage:         "",
+}
+
+var (
+	lyricsFetchOptionsMu sync.RWMutex
+	lyricsFetchOptions   = defaultLyricsFetchOptions
+)
+
+// SetLyricsProviderOrder sets the ordered list of lyrics providers to try.
+// Providers not in the list are disabled. An empty list resets to defaults.
+func SetLyricsProviderOrder(providers []string) {
+	lyricsProvidersMu.Lock()
+	defer lyricsProvidersMu.Unlock()
+
+	if len(providers) == 0 {
+		lyricsProviders = nil
+		return
+	}
+
+	// Validate provider names
+	validNames := map[string]bool{
+		LyricsProviderSpotifyAPI: true,
+		LyricsProviderLRCLIB:     true,
+		LyricsProviderNetease:    true,
+		LyricsProviderMusixmatch: true,
+		LyricsProviderAppleMusic: true,
+		LyricsProviderQQMusic:    true,
+	}
+
+	var valid []string
+	for _, p := range providers {
+		normalized := strings.ToLower(strings.TrimSpace(p))
+		if validNames[normalized] {
+			valid = append(valid, normalized)
+		}
+	}
+
+	lyricsProviders = valid
+	GoLog("[Lyrics] Provider order set to: %v\n", valid)
+}
+
+// GetLyricsProviderOrder returns the current lyrics provider order.
+func GetLyricsProviderOrder() []string {
+	lyricsProvidersMu.RLock()
+	defer lyricsProvidersMu.RUnlock()
+
+	if len(lyricsProviders) == 0 {
+		return DefaultLyricsProviders
+	}
+
+	result := make([]string, len(lyricsProviders))
+	copy(result, lyricsProviders)
+	return result
+}
+
+// GetAvailableLyricsProviders returns metadata about all available providers.
+func GetAvailableLyricsProviders() []map[string]interface{} {
+	return []map[string]interface{}{
+		{"id": LyricsProviderSpotifyAPI, "name": "Spotify Lyrics API", "has_proxy_dependency": true, "description": "Spotify-sourced synced lyrics via community API"},
+		{"id": 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)"},
+	}
+}
+
+func normalizeLyricsFetchOptions(opts LyricsFetchOptions) LyricsFetchOptions {
+	opts.MusixmatchLanguage = strings.ToLower(strings.TrimSpace(opts.MusixmatchLanguage))
+	opts.MusixmatchLanguage = regexp.MustCompile(`[^a-z0-9\-_]`).ReplaceAllString(opts.MusixmatchLanguage, "")
+	if len(opts.MusixmatchLanguage) > 16 {
+		opts.MusixmatchLanguage = opts.MusixmatchLanguage[:16]
+	}
+	return opts
+}
+
+// SetLyricsFetchOptions sets provider-specific lyric fetch behavior.
+func SetLyricsFetchOptions(opts LyricsFetchOptions) {
+	normalized := normalizeLyricsFetchOptions(opts)
+
+	lyricsFetchOptionsMu.Lock()
+	defer lyricsFetchOptionsMu.Unlock()
+	lyricsFetchOptions = normalized
+
+	GoLog("[Lyrics] Fetch options set: translation=%v romanization=%v multi_person=%v musixmatch_lang=%q\n",
+		normalized.IncludeTranslationNetease,
+		normalized.IncludeRomanizationNetease,
+		normalized.MultiPersonWordByWord,
+		normalized.MusixmatchLanguage,
+	)
+}
+
+// GetLyricsFetchOptions returns current provider-specific lyric fetch behavior.
+func GetLyricsFetchOptions() LyricsFetchOptions {
+	lyricsFetchOptionsMu.RLock()
+	defer lyricsFetchOptionsMu.RUnlock()
+	return lyricsFetchOptions
+}
+
 type lyricsCacheEntry struct {
 	response  *LyricsResponse
 	expiresAt time.Time
@@ -90,6 +232,15 @@ func (c *lyricsCache) Size() int {
 	return len(c.cache)
 }

+func (c *lyricsCache) ClearAll() int {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+
+	cleared := len(c.cache)
+	c.cache = make(map[string]*lyricsCacheEntry)
+	return cleared
+}
+
 type LRCLibResponse struct {
 	ID           int     `json:"id"`
 	Name         string  `json:"name"`
@@ -102,6 +253,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"`
@@ -139,7 +302,7 @@ func (c *LyricsClient) FetchLyricsWithMetadata(artist, track string) (*LyricsRes
 	if err != nil {
 		return nil, fmt.Errorf("failed to create request: %w", err)
 	}
-	req.Header.Set("User-Agent", "SpotiFLAC-Android/1.0")
+	req.Header.Set("User-Agent", getRandomUserAgent())

 	resp, err := c.httpClient.Do(req)
 	if err != nil {
@@ -174,7 +337,7 @@ func (c *LyricsClient) FetchLyricsFromLRCLibSearch(query string, durationSec flo
 	if err != nil {
 		return nil, fmt.Errorf("failed to create request: %w", err)
 	}
-	req.Header.Set("User-Agent", "SpotiFLAC-Android/1.0")
+	req.Header.Set("User-Agent", getRandomUserAgent())

 	resp, err := c.httpClient.Do(req)
 	if err != nil {
@@ -209,6 +372,172 @@ 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 (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://spotify-lyrics-api-pi.vercel.app/?trackid=%s&format=lrc", 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()
+
+	if resp.StatusCode != 200 {
+		if resp.StatusCode == http.StatusTooManyRequests {
+			retryUntil := parseSpotifyRetryAfter(resp.Header.Get("Retry-After"), now)
+			setSpotifyLyricsRateLimitUntil(retryUntil)
+		}
+		var payload map[string]interface{}
+		if err := json.NewDecoder(resp.Body).Decode(&payload); err == nil {
+			if 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)
+	}
+
+	var apiResp SpotifyLyricsAPIResponse
+	if err := json.NewDecoder(resp.Body).Decode(&apiResp); err != nil {
+		return nil, fmt.Errorf("failed to parse Spotify Lyrics API response: %w", err)
+	}
+
+	if apiResp.Error {
+		msg := strings.TrimSpace(apiResp.Message)
+		if msg == "" {
+			msg = "Spotify Lyrics API returned error"
+		}
+		return nil, fmt.Errorf("%s", msg)
+	}
+
+	result := &LyricsResponse{
+		Lines:        make([]LyricsLine, 0, len(apiResp.Lines)),
+		SyncType:     apiResp.SyncType,
+		Instrumental: false,
+		PlainLyrics:  "",
+		Provider:     "Spotify Lyrics API",
+		Source:       "Spotify Lyrics API",
+	}
+
+	for _, line := range apiResp.Lines {
+		words := strings.TrimSpace(line.Words)
+		if words == "" {
+			continue
+		}
+		startMs := parseSpotifyLyricsTimeTagToMs(line.TimeTag)
+		result.Lines = append(result.Lines, LyricsLine{
+			StartTimeMs: startMs,
+			Words:       words,
+			EndTimeMs:   0,
+		})
+	}
+
+	if len(result.Lines) > 1 {
+		for i := 0; i < len(result.Lines)-1; i++ {
+			nextStart := result.Lines[i+1].StartTimeMs
+			if nextStart > result.Lines[i].StartTimeMs {
+				result.Lines[i].EndTimeMs = nextStart
+			}
+		}
+		last := len(result.Lines) - 1
+		if result.Lines[last].EndTimeMs == 0 {
+			result.Lines[last].EndTimeMs = result.Lines[last].StartTimeMs + 5000
+		}
+	}
+
+	if len(result.Lines) == 0 {
+		return nil, fmt.Errorf("Spotify Lyrics API returned empty lines")
+	}
+
+	if result.SyncType == "" {
+		result.SyncType = "LINE_SYNCED"
+	}
+
+	return result, nil
+}
+
 func (c *LyricsClient) findBestMatch(results []LRCLibResponse, targetDurationSec float64) *LRCLibResponse {
 	var bestSynced *LRCLibResponse
 	var bestPlain *LRCLibResponse
@@ -240,68 +569,204 @@ func (c *LyricsClient) durationMatches(lrcDuration, targetDuration float64) bool

 func (c *LyricsClient) FetchLyricsAllSources(spotifyID, trackName, artistName string, durationSec float64) (*LyricsResponse, error) {
 	primaryArtist := normalizeArtistName(artistName)
+	fetchOptions := GetLyricsFetchOptions()

+	extManager := GetExtensionManager()
+	var extensionProviders []*ExtensionProviderWrapper
+	if extManager != nil {
+		extensionProviders = extManager.GetLyricsProviders()
+	}
+
+	var cachedNonExtension *LyricsResponse
 	if cached, found := globalLyricsCache.Get(artistName, trackName, durationSec); found {
-		fmt.Printf("[Lyrics] Cache hit for: %s - %s\n", artistName, trackName)
-		cachedCopy := *cached
-		cachedCopy.Source = cached.Source + " (cached)"
+		isExtensionCache := strings.HasPrefix(cached.Source, "Extension:")
+		if len(extensionProviders) == 0 || isExtensionCache {
+			fmt.Printf("[Lyrics] Cache hit for: %s - %s\n", artistName, trackName)
+			cachedCopy := *cached
+			cachedCopy.Source = cached.Source + " (cached)"
+			return &cachedCopy, nil
+		}
+
+		// If extension providers are currently enabled, don't let stale built-in cache
+		// mask newly installed/activated extensions.
+		cachedNonExtension = cached
+		GoLog("[Lyrics] Ignoring cached non-extension lyrics because extension providers are available\n")
+	}
+
+	isValidResult := func(l *LyricsResponse) bool {
+		return lyricsHasUsableText(l)
+	}
+
+	if len(extensionProviders) > 0 {
+		for _, provider := range extensionProviders {
+			GoLog("[Lyrics] Trying extension lyrics provider: %s\n", provider.extension.ID)
+			lyrics, err := provider.FetchLyrics(trackName, artistName, "", durationSec)
+			if err == nil && isValidResult(lyrics) {
+				GoLog("[Lyrics] Got lyrics from extension: %s\n", provider.extension.ID)
+				globalLyricsCache.Set(artistName, trackName, durationSec, lyrics)
+				return lyrics, nil
+			}
+			if err != nil {
+				GoLog("[Lyrics] Extension %s failed: %v\n", provider.extension.ID, err)
+			}
+		}
+	}
+
+	if cachedNonExtension != nil {
+		cachedCopy := *cachedNonExtension
+		cachedCopy.Source = cachedNonExtension.Source + " (cached fallback)"
+		GoLog("[Lyrics] Extension providers unavailable for this track, using cached built-in lyrics\n")
 		return &cachedCopy, nil
 	}

-	var lyrics *LyricsResponse
-	var err error
-
-	isValidResult := func(l *LyricsResponse) bool {
-		return l != nil && (len(l.Lines) > 0 || l.Instrumental)
-	}
-
-	lyrics, err = c.FetchLyricsWithMetadata(primaryArtist, trackName)
-	if err == nil && isValidResult(lyrics) {
-		lyrics.Source = "LRCLIB"
-		globalLyricsCache.Set(artistName, trackName, durationSec, lyrics)
-		return lyrics, nil
-	}
-
-	if primaryArtist != artistName {
-		lyrics, err = c.FetchLyricsWithMetadata(artistName, trackName)
-		if err == nil && isValidResult(lyrics) {
-			lyrics.Source = "LRCLIB"
-			globalLyricsCache.Set(artistName, trackName, durationSec, lyrics)
-			return lyrics, nil
-		}
-	}
-
+	providerOrder := GetLyricsProviderOrder()
 	simplifiedTrack := simplifyTrackName(trackName)
-	if simplifiedTrack != trackName {
-		lyrics, err = c.FetchLyricsWithMetadata(primaryArtist, simplifiedTrack)
+
+	GoLog("[Lyrics] Searching for: %s - %s (providers: %v)\n", artistName, trackName, providerOrder)
+
+	// Cascade through all configured built-in providers
+	for _, providerName := range providerOrder {
+		GoLog("[Lyrics] Trying provider: %s\n", providerName)
+
+		var lyrics *LyricsResponse
+		var err error
+
+		switch providerName {
+		case LyricsProviderSpotifyAPI:
+			lyrics, err = c.FetchLyricsFromSpotifyAPI(spotifyID)
+
+		case LyricsProviderLRCLIB:
+			lyrics, err = c.tryLRCLIB(primaryArtist, artistName, trackName, simplifiedTrack, durationSec)
+
+		case LyricsProviderNetease:
+			neteaseClient := NewNeteaseClient()
+			lyrics, err = neteaseClient.FetchLyrics(
+				trackName,
+				primaryArtist,
+				durationSec,
+				fetchOptions.IncludeTranslationNetease,
+				fetchOptions.IncludeRomanizationNetease,
+			)
+			if err != nil && primaryArtist != artistName {
+				lyrics, err = neteaseClient.FetchLyrics(
+					trackName,
+					artistName,
+					durationSec,
+					fetchOptions.IncludeTranslationNetease,
+					fetchOptions.IncludeRomanizationNetease,
+				)
+			}
+			if err != nil && simplifiedTrack != trackName {
+				lyrics, err = neteaseClient.FetchLyrics(
+					simplifiedTrack,
+					primaryArtist,
+					durationSec,
+					fetchOptions.IncludeTranslationNetease,
+					fetchOptions.IncludeRomanizationNetease,
+				)
+			}
+
+		case LyricsProviderMusixmatch:
+			musixmatchClient := NewMusixmatchClient()
+			lyrics, err = musixmatchClient.FetchLyrics(
+				trackName,
+				primaryArtist,
+				durationSec,
+				fetchOptions.MusixmatchLanguage,
+			)
+			if err != nil && primaryArtist != artistName {
+				lyrics, err = musixmatchClient.FetchLyrics(
+					trackName,
+					artistName,
+					durationSec,
+					fetchOptions.MusixmatchLanguage,
+				)
+			}
+
+		case LyricsProviderAppleMusic:
+			appleClient := NewAppleMusicClient()
+			lyrics, err = appleClient.FetchLyrics(trackName, primaryArtist, durationSec, fetchOptions.MultiPersonWordByWord)
+			if err != nil && primaryArtist != artistName {
+				lyrics, err = appleClient.FetchLyrics(trackName, artistName, durationSec, fetchOptions.MultiPersonWordByWord)
+			}
+
+		case LyricsProviderQQMusic:
+			qqClient := NewQQMusicClient()
+			lyrics, err = qqClient.FetchLyrics(trackName, primaryArtist, durationSec, fetchOptions.MultiPersonWordByWord)
+			if err != nil && primaryArtist != artistName {
+				lyrics, err = qqClient.FetchLyrics(trackName, artistName, durationSec, fetchOptions.MultiPersonWordByWord)
+			}
+
+		default:
+			GoLog("[Lyrics] Unknown provider: %s, skipping\n", providerName)
+			continue
+		}
+
 		if err == nil && isValidResult(lyrics) {
-			lyrics.Source = "LRCLIB (simplified)"
+			GoLog("[Lyrics] Got lyrics from: %s\n", providerName)
 			globalLyricsCache.Set(artistName, trackName, durationSec, lyrics)
 			return lyrics, nil
 		}
-	}

-	query := primaryArtist + " " + trackName
-	lyrics, err = c.FetchLyricsFromLRCLibSearch(query, durationSec)
-	if err == nil && isValidResult(lyrics) {
-		lyrics.Source = "LRCLIB Search"
-		globalLyricsCache.Set(artistName, trackName, durationSec, lyrics)
-		return lyrics, nil
-	}
-
-	if simplifiedTrack != trackName {
-		query = primaryArtist + " " + simplifiedTrack
-		lyrics, err = c.FetchLyricsFromLRCLibSearch(query, durationSec)
-		if err == nil && isValidResult(lyrics) {
-			lyrics.Source = "LRCLIB Search (simplified)"
-			globalLyricsCache.Set(artistName, trackName, durationSec, lyrics)
-			return lyrics, nil
+		if err != nil {
+			GoLog("[Lyrics] Provider %s failed: %v\n", providerName, err)
 		}
 	}

 	return nil, fmt.Errorf("lyrics not found from any source")
 }

+// tryLRCLIB attempts all LRCLIB search strategies (exact match, simplified, search).
+func (c *LyricsClient) tryLRCLIB(primaryArtist, artistName, trackName, simplifiedTrack string, durationSec float64) (*LyricsResponse, error) {
+	var lyrics *LyricsResponse
+	var err error
+
+	// 1. Exact match with primary artist
+	lyrics, err = c.FetchLyricsWithMetadata(primaryArtist, trackName)
+	if err == nil && lyrics != nil && (len(lyrics.Lines) > 0 || lyrics.Instrumental) {
+		lyrics.Source = "LRCLIB"
+		return lyrics, nil
+	}
+
+	// 2. Exact match with full artist name
+	if primaryArtist != artistName {
+		lyrics, err = c.FetchLyricsWithMetadata(artistName, trackName)
+		if err == nil && lyrics != nil && (len(lyrics.Lines) > 0 || lyrics.Instrumental) {
+			lyrics.Source = "LRCLIB"
+			return lyrics, nil
+		}
+	}
+
+	// 3. Simplified track name
+	if simplifiedTrack != trackName {
+		lyrics, err = c.FetchLyricsWithMetadata(primaryArtist, simplifiedTrack)
+		if err == nil && lyrics != nil && (len(lyrics.Lines) > 0 || lyrics.Instrumental) {
+			lyrics.Source = "LRCLIB (simplified)"
+			return lyrics, nil
+		}
+	}
+
+	// 4. Search by query
+	query := primaryArtist + " " + trackName
+	lyrics, err = c.FetchLyricsFromLRCLibSearch(query, durationSec)
+	if err == nil && lyrics != nil && (len(lyrics.Lines) > 0 || lyrics.Instrumental) {
+		lyrics.Source = "LRCLIB Search"
+		return lyrics, nil
+	}
+
+	// 5. Search with simplified track name
+	if simplifiedTrack != trackName {
+		query = primaryArtist + " " + simplifiedTrack
+		lyrics, err = c.FetchLyricsFromLRCLibSearch(query, durationSec)
+		if err == nil && lyrics != nil && (len(lyrics.Lines) > 0 || lyrics.Instrumental) {
+			lyrics.Source = "LRCLIB Search (simplified)"
+			return lyrics, nil
+		}
+	}
+
+	return nil, fmt.Errorf("LRCLIB: no lyrics found")
+}
+
 func (c *LyricsClient) parseLRCLibResponse(resp *LRCLibResponse) *LyricsResponse {
 	result := &LyricsResponse{
 		Instrumental: resp.Instrumental,
@@ -339,10 +804,20 @@ func parseSyncedLyrics(syncedLyrics string) []LyricsLine {
 			continue
 		}

+		// Preserve Apple/QQ background vocal tags by attaching them to
+		// the previous timed line. This keeps [bg:...] in final exported LRC.
+		if strings.HasPrefix(line, "[bg:") && len(lines) > 0 {
+			lines[len(lines)-1].Words = strings.TrimSpace(lines[len(lines)-1].Words + "\n" + line)
+			continue
+		}
+
 		matches := lrcPattern.FindStringSubmatch(line)
 		if len(matches) == 5 {
 			startMs := lrcTimestampToMs(matches[1], matches[2], matches[3])
 			words := strings.TrimSpace(matches[4])
+			if words == "" {
+				continue
+			}

 			lines = append(lines, LyricsLine{
 				StartTimeMs: startMs,
@@ -363,6 +838,79 @@ 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
+	}
+	if lyrics.Instrumental {
+		return true
+	}
+	if strings.TrimSpace(lyrics.PlainLyrics) != "" {
+		return true
+	}
+	for _, line := range lyrics.Lines {
+		if strings.TrimSpace(line.Words) != "" {
+			return true
+		}
+	}
+	return false
+}
+
+// detectLyricsErrorPayload extracts human-readable error messages from
+// JSON payloads returned by lyrics proxies when no lyric is available.
+func detectLyricsErrorPayload(raw string) (string, bool) {
+	trimmed := strings.TrimSpace(raw)
+	if trimmed == "" || !strings.HasPrefix(trimmed, "{") {
+		return "", false
+	}
+
+	var payload map[string]interface{}
+	if err := json.Unmarshal([]byte(trimmed), &payload); err != nil {
+		return "", false
+	}
+
+	lyricsKeys := []string{"lyrics", "lyric", "lrc", "content", "lines", "syncedLyrics", "unsyncedLyrics"}
+	hasLyricsKey := false
+	for _, key := range lyricsKeys {
+		if _, ok := payload[key]; ok {
+			hasLyricsKey = true
+			break
+		}
+	}
+
+	errorKeys := []string{"message", "error", "detail", "reason"}
+	for _, key := range errorKeys {
+		if msg, ok := payload[key].(string); ok {
+			msg = strings.TrimSpace(msg)
+			if msg != "" && !hasLyricsKey {
+				return msg, true
+			}
+		}
+	}
+
+	if success, ok := payload["success"].(bool); ok && !success && !hasLyricsKey {
+		return "request unsuccessful", true
+	}
+
+	return "", false
+}
+
 func lrcTimestampToMs(minutes, seconds, centiseconds string) int64 {
 	min, _ := strconv.ParseInt(minutes, 10, 64)
 	sec, _ := strconv.ParseInt(seconds, 10, 64)
@@ -376,12 +924,16 @@ func lrcTimestampToMs(minutes, seconds, centiseconds string) int64 {
 }

 func msToLRCTimestamp(ms int64) string {
+	return fmt.Sprintf("[%s]", msToLRCTimestampInline(ms))
+}
+
+func msToLRCTimestampInline(ms int64) string {
 	totalSeconds := ms / 1000
 	minutes := totalSeconds / 60
 	seconds := totalSeconds % 60
 	centiseconds := (ms % 1000) / 10

-	return fmt.Sprintf("[%02d:%02d.%02d]", minutes, seconds, centiseconds)
+	return fmt.Sprintf("%02d:%02d.%02d", minutes, seconds, centiseconds)
 }

 func convertToLRCWithMetadata(lyrics *LyricsResponse, trackName, artistName string) string {
@@ -441,8 +993,18 @@ func simplifyTrackName(name string) string {
 		re := regexp.MustCompile("(?i)" + pattern)
 		result = re.ReplaceAllString(result, "")
 	}
+	result = strings.TrimSpace(result)
+	if result == "" {
+		return result
+	}

-	return strings.TrimSpace(result)
+	// Add a loose fallback form for provider queries where punctuation
+	// and separators differ (e.g. "/" vs "_" vs spaces).
+	if loose := normalizeLooseTitle(result); loose != "" {
+		return loose
+	}
+
+	return result
 }

 func normalizeArtistName(name string) string {
@@ -0,0 +1,366 @@
+package gobackend
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"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.
+type AppleMusicClient struct {
+	httpClient *http.Client
+}
+
+// Apple Music token manager — singleton with mutex for thread safety
+type appleTokenManager struct {
+	mu    sync.Mutex
+	token string
+}
+
+var globalAppleTokenManager = &appleTokenManager{}
+
+func (m *appleTokenManager) getToken(client *http.Client) (string, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+
+	if m.token != "" {
+		return m.token, nil
+	}
+
+	// Step 1: Fetch the Apple Music beta page
+	req, err := http.NewRequest("GET", "https://beta.music.apple.com", nil)
+	if err != nil {
+		return "", fmt.Errorf("failed to create request: %w", err)
+	}
+	req.Header.Set("User-Agent", getRandomUserAgent())
+
+	resp, err := client.Do(req)
+	if err != nil {
+		return "", fmt.Errorf("failed to fetch Apple Music page: %w", err)
+	}
+	defer resp.Body.Close()
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return "", fmt.Errorf("failed to read Apple Music page: %w", err)
+	}
+
+	// Step 2: Find the index JS file URL
+	indexJsRegex := regexp.MustCompile(`/assets/index~[^/]+\.js`)
+	match := indexJsRegex.Find(body)
+	if match == nil {
+		return "", fmt.Errorf("could not find index JS script URL on Apple Music page")
+	}
+
+	indexJsURL := "https://beta.music.apple.com" + string(match)
+
+	// Step 3: Fetch the JS file
+	jsReq, err := http.NewRequest("GET", indexJsURL, nil)
+	if err != nil {
+		return "", fmt.Errorf("failed to create JS request: %w", err)
+	}
+	jsReq.Header.Set("User-Agent", getRandomUserAgent())
+
+	jsResp, err := client.Do(jsReq)
+	if err != nil {
+		return "", fmt.Errorf("failed to fetch Apple Music JS: %w", err)
+	}
+	defer jsResp.Body.Close()
+
+	jsBody, err := io.ReadAll(jsResp.Body)
+	if err != nil {
+		return "", fmt.Errorf("failed to read Apple Music JS: %w", err)
+	}
+
+	// Step 4: Extract JWT token (starts with eyJh)
+	tokenRegex := regexp.MustCompile(`eyJh[^"]*`)
+	tokenMatch := tokenRegex.Find(jsBody)
+	if tokenMatch == nil {
+		return "", fmt.Errorf("could not find JWT token in Apple Music JS")
+	}
+
+	m.token = string(tokenMatch)
+	GoLog("[AppleMusic] Token obtained successfully (length: %d)\n", len(m.token))
+	return m.token, nil
+}
+
+func (m *appleTokenManager) clearToken() {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	m.token = ""
+}
+
+type appleMusicSearchResponse struct {
+	Results struct {
+		Songs *struct {
+			Data []struct {
+				ID   string `json:"id"`
+				Type string `json:"type"`
+			} `json:"data"`
+		} `json:"songs"`
+	} `json:"results"`
+	Resources *struct {
+		Songs map[string]struct {
+			Attributes struct {
+				Name       string `json:"name"`
+				ArtistName string `json:"artistName"`
+				AlbumName  string `json:"albumName"`
+				URL        string `json:"url"`
+				Artwork    struct {
+					URL string `json:"url"`
+				} `json:"artwork"`
+			} `json:"attributes"`
+		} `json:"songs"`
+	} `json:"resources"`
+}
+
+// PaxResponse represents the lyrics proxy response for word-by-word / line lyrics
+type paxResponse struct {
+	Type    string      `json:"type"`    // "Syllable" or "Line"
+	Content []paxLyrics `json:"content"` // List of lyric lines
+}
+
+type paxLyrics struct {
+	Text           []paxLyricDetail `json:"text"`
+	Timestamp      int              `json:"timestamp"`
+	OppositeTurn   bool             `json:"oppositeTurn"`
+	Background     bool             `json:"background"`
+	BackgroundText []paxLyricDetail `json:"backgroundText"`
+	EndTime        int              `json:"endtime"`
+}
+
+type paxLyricDetail struct {
+	Text      string `json:"text"`
+	Part      bool   `json:"part"`
+	Timestamp *int   `json:"timestamp"`
+	EndTime   *int   `json:"endtime"`
+}
+
+func NewAppleMusicClient() *AppleMusicClient {
+	return &AppleMusicClient{
+		httpClient: NewMetadataHTTPClient(20 * time.Second),
+	}
+}
+
+// SearchSong searches for a song on Apple Music and returns its ID.
+func (c *AppleMusicClient) SearchSong(trackName, artistName string) (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,
+	)
+
+	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")
+
+	resp, err := c.httpClient.Do(req)
+	if err != nil {
+		return "", fmt.Errorf("apple music search failed: %w", 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
+	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 {
+		return "", fmt.Errorf("no songs found on apple music")
+	}
+
+	return searchResp.Results.Songs.Data[0].ID, nil
+}
+
+// FetchLyricsByID fetches lyrics from the paxsenix proxy using Apple Music song ID.
+func (c *AppleMusicClient) FetchLyricsByID(songID string) (string, error) {
+	lyricsURL := fmt.Sprintf("https://lyrics.paxsenix.org/apple-music/lyrics?id=%s", songID)
+
+	req, err := http.NewRequest("GET", lyricsURL, nil)
+	if err != nil {
+		return "", fmt.Errorf("failed to create request: %w", err)
+	}
+	req.Header.Set("User-Agent", getRandomUserAgent())
+
+	resp, err := c.httpClient.Do(req)
+	if err != nil {
+		return "", fmt.Errorf("apple music lyrics fetch failed: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != 200 {
+		return "", fmt.Errorf("apple music lyrics proxy returned HTTP %d", resp.StatusCode)
+	}
+
+	bodyBytes, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return "", fmt.Errorf("failed to read lyrics response: %w", err)
+	}
+
+	bodyStr := strings.TrimSpace(string(bodyBytes))
+	if bodyStr == "" {
+		return "", fmt.Errorf("empty lyrics response from apple music")
+	}
+
+	return bodyStr, nil
+}
+
+func formatPaxLyricsToLRC(rawJSON string, multiPersonWordByWord bool) (string, error) {
+	var paxResp paxResponse
+	if err := json.Unmarshal([]byte(rawJSON), &paxResp); err == nil && paxResp.Content != nil {
+		return formatPaxContent(paxResp.Type, paxResp.Content, multiPersonWordByWord), nil
+	}
+
+	var directLyrics []paxLyrics
+	if err := json.Unmarshal([]byte(rawJSON), &directLyrics); err == nil && len(directLyrics) > 0 {
+		return formatPaxContent("Syllable", directLyrics, multiPersonWordByWord), nil
+	}
+
+	return "", fmt.Errorf("failed to parse pax lyrics response")
+}
+
+func appendPaxLyricDetail(builder *strings.Builder, details []paxLyricDetail) {
+	lastStart := ""
+
+	for _, syllable := range details {
+		if syllable.Timestamp != nil {
+			start := fmt.Sprintf("<%s>", msToLRCTimestampInline(int64(*syllable.Timestamp)))
+			if start != lastStart {
+				builder.WriteString(start)
+				lastStart = start
+			}
+		}
+
+		builder.WriteString(syllable.Text)
+		if !syllable.Part {
+			builder.WriteString(" ")
+		}
+
+		if syllable.EndTime != nil {
+			builder.WriteString(fmt.Sprintf("<%s>", msToLRCTimestampInline(int64(*syllable.EndTime))))
+		}
+	}
+}
+
+func formatPaxContent(lyricsType string, content []paxLyrics, multiPersonWordByWord bool) string {
+	var sb strings.Builder
+
+	for i, line := range content {
+		if i > 0 {
+			sb.WriteString("\n")
+		}
+
+		timestamp := msToLRCTimestamp(int64(line.Timestamp))
+
+		if strings.EqualFold(lyricsType, "Syllable") {
+			sb.WriteString(timestamp)
+			if multiPersonWordByWord {
+				if line.OppositeTurn {
+					sb.WriteString("v2:")
+				} else {
+					sb.WriteString("v1:")
+				}
+			}
+
+			appendPaxLyricDetail(&sb, line.Text)
+
+			if line.Background && multiPersonWordByWord && len(line.BackgroundText) > 0 {
+				sb.WriteString("\n[bg:")
+				appendPaxLyricDetail(&sb, line.BackgroundText)
+				sb.WriteString("]")
+			}
+		} else {
+			if len(line.Text) > 0 {
+				sb.WriteString(timestamp)
+				sb.WriteString(line.Text[0].Text)
+			}
+		}
+	}
+
+	return strings.TrimSpace(sb.String())
+}
+
+// FetchLyrics searches Apple Music and returns parsed LyricsResponse.
+func (c *AppleMusicClient) FetchLyrics(
+	trackName,
+	artistName string,
+	durationSec float64,
+	multiPersonWordByWord bool,
+) (*LyricsResponse, error) {
+	songID, err := c.SearchSong(trackName, artistName)
+	if err != nil {
+		return nil, err
+	}
+
+	rawLyrics, err := c.FetchLyricsByID(songID)
+	if err != nil {
+		return nil, err
+	}
+	if errMsg, isErrorPayload := detectLyricsErrorPayload(rawLyrics); isErrorPayload {
+		return nil, fmt.Errorf("apple music proxy returned non-lyric payload: %s", errMsg)
+	}
+
+	// Try to parse as pax format (word-by-word or line)
+	lrcText, err := formatPaxLyricsToLRC(rawLyrics, multiPersonWordByWord)
+	if err != nil {
+		// If pax parsing fails, try to parse as direct LRC text
+		lrcText = rawLyrics
+	}
+
+	lines := parseSyncedLyrics(lrcText)
+	if len(lines) > 0 {
+		return &LyricsResponse{
+			Lines:    lines,
+			SyncType: "LINE_SYNCED",
+			Provider: "Apple Music",
+			Source:   "Apple Music",
+		}, nil
+	}
+
+	// Fall back to plain text if no timestamps found
+	resultLines := plainTextLyricsLines(lrcText)
+
+	if len(resultLines) > 0 {
+		return &LyricsResponse{
+			Lines:    resultLines,
+			SyncType: "UNSYNCED",
+			Provider: "Apple Music",
+			Source:   "Apple Music",
+		}, nil
+	}
+
+	return nil, fmt.Errorf("no lyrics found on apple music")
+}
@@ -0,0 +1,189 @@
+package gobackend
+
+import (
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/url"
+	"strings"
+	"time"
+)
+
+// MusixmatchClient fetches lyrics from Musixmatch via a proxy server.
+// The proxy handles Musixmatch authentication internally.
+type MusixmatchClient struct {
+	httpClient *http.Client
+	baseURL    string
+}
+
+type musixmatchSearchResponse struct {
+	ID                 int64                     `json:"id"`
+	SongName           string                    `json:"songName"`
+	ArtistName         string                    `json:"artistName"`
+	AlbumName          string                    `json:"albumName"`
+	Artwork            string                    `json:"artwork"`
+	ReleaseDate        string                    `json:"releaseDate"`
+	Duration           int                       `json:"duration"`
+	URL                string                    `json:"url"`
+	AlbumID            int64                     `json:"albumId"`
+	HasSyncedLyrics    bool                      `json:"hasSyncedLyrics"`
+	HasUnsyncedLyrics  bool                      `json:"hasUnsyncedLyrics"`
+	AvailableLanguages []string                  `json:"availableLanguages"`
+	OriginalLanguage   string                    `json:"originalLanguage"`
+	SyncedLyrics       *musixmatchLyricsResponse `json:"syncedLyrics"`
+	UnsyncedLyrics     *musixmatchLyricsResponse `json:"unsyncedLyrics"`
+}
+
+type musixmatchLyricsResponse struct {
+	ID          int64  `json:"id"`
+	Duration    int    `json:"duration"`
+	Language    string `json:"language"`
+	UpdatedTime string `json:"updatedTime"`
+	Lyrics      string `json:"lyrics"`
+}
+
+func NewMusixmatchClient() *MusixmatchClient {
+	return &MusixmatchClient{
+		httpClient: NewMetadataHTTPClient(15 * time.Second),
+		baseURL:    "http://158.180.60.95",
+	}
+}
+
+// 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) {
+	if strings.TrimSpace(trackName) == "" || strings.TrimSpace(artistName) == "" {
+		return nil, 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)
+
+	req, err := http.NewRequest("GET", fullURL, 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("musixmatch search failed: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != 200 {
+		return nil, 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)
+	}
+
+	return &result, nil
+}
+
+// FetchLyricsInLanguage retrieves lyrics from Musixmatch for a specific language code.
+func (c *MusixmatchClient) FetchLyricsInLanguage(songID int64, language string) (*LyricsResponse, error) {
+	lang := strings.ToLower(strings.TrimSpace(language))
+	if songID <= 0 || lang == "" {
+		return nil, fmt.Errorf("invalid song id or language")
+	}
+
+	fullURL := fmt.Sprintf("%s/v2/full?id=%d&lang=%s", c.baseURL, songID, url.QueryEscape(lang))
+
+	req, err := http.NewRequest("GET", fullURL, 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("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)
+	}
+
+	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)
+	}
+
+	if result.SyncedLyrics != nil && strings.TrimSpace(result.SyncedLyrics.Lyrics) != "" {
+		lines := parseSyncedLyrics(result.SyncedLyrics.Lyrics)
+		if len(lines) > 0 {
+			return &LyricsResponse{
+				Lines:    lines,
+				SyncType: "LINE_SYNCED",
+				Provider: "Musixmatch",
+				Source:   fmt.Sprintf("Musixmatch (%s)", lang),
+			}, nil
+		}
+	}
+
+	if result.UnsyncedLyrics != nil && strings.TrimSpace(result.UnsyncedLyrics.Lyrics) != "" {
+		lines := plainTextLyricsLines(result.UnsyncedLyrics.Lyrics)
+
+		if len(lines) > 0 {
+			return &LyricsResponse{
+				Lines:       lines,
+				SyncType:    "UNSYNCED",
+				PlainLyrics: result.UnsyncedLyrics.Lyrics,
+				Provider:    "Musixmatch",
+				Source:      fmt.Sprintf("Musixmatch (%s)", lang),
+			}, nil
+		}
+	}
+
+	return nil, fmt.Errorf("no lyrics found on musixmatch for language %s", lang)
+}
+
+// FetchLyrics searches Musixmatch and returns parsed LyricsResponse.
+func (c *MusixmatchClient) FetchLyrics(trackName, artistName string, durationSec float64, preferredLanguage string) (*LyricsResponse, error) {
+	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 localizedErr == nil {
+			return localized, nil
+		}
+		GoLog("[Musixmatch] Language override '%s' failed: %v\n", preferred, localizedErr)
+	}
+
+	if result.SyncedLyrics != nil && strings.TrimSpace(result.SyncedLyrics.Lyrics) != "" {
+		lines := parseSyncedLyrics(result.SyncedLyrics.Lyrics)
+		if len(lines) > 0 {
+			return &LyricsResponse{
+				Lines:    lines,
+				SyncType: "LINE_SYNCED",
+				Provider: "Musixmatch",
+				Source:   "Musixmatch",
+			}, nil
+		}
+	}
+
+	if result.UnsyncedLyrics != nil && strings.TrimSpace(result.UnsyncedLyrics.Lyrics) != "" {
+		lines := plainTextLyricsLines(result.UnsyncedLyrics.Lyrics)
+
+		if len(lines) > 0 {
+			return &LyricsResponse{
+				Lines:       lines,
+				SyncType:    "UNSYNCED",
+				PlainLyrics: result.UnsyncedLyrics.Lyrics,
+				Provider:    "Musixmatch",
+				Source:      "Musixmatch",
+			}, nil
+		}
+	}
+
+	return nil, fmt.Errorf("no lyrics found on musixmatch")
+}
@@ -0,0 +1,207 @@
+package gobackend
+
+import (
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/url"
+	"strings"
+	"time"
+)
+
+// NeteaseClient fetches lyrics from NetEase Cloud Music (music.163.com).
+// This is a direct public API — no proxy dependency.
+type NeteaseClient struct {
+	httpClient *http.Client
+}
+
+type neteaseSearchResponse struct {
+	Result struct {
+		Songs []struct {
+			Name    string `json:"name"`
+			ID      int64  `json:"id"`
+			Artists []struct {
+				Name string `json:"name"`
+			} `json:"artists"`
+		} `json:"songs"`
+		SongCount int `json:"songCount"`
+	} `json:"result"`
+	Code int `json:"code"`
+}
+
+type neteaseLyricsResponse struct {
+	LRC     *neteaseLyricField `json:"lrc"`
+	TLyric  *neteaseLyricField `json:"tlyric"`
+	RomaLRC *neteaseLyricField `json:"romalrc"`
+	Code    int                `json:"code"`
+}
+
+type neteaseLyricField struct {
+	Lyric string `json:"lyric"`
+}
+
+var neteaseHeaders = map[string]string{
+	"Accept":          "application/json",
+	"Accept-Language": "en-US,en;q=0.9",
+	"Cache-Control":   "max-age=0",
+}
+
+func NewNeteaseClient() *NeteaseClient {
+	return &NeteaseClient{
+		httpClient: NewMetadataHTTPClient(15 * time.Second),
+	}
+}
+
+// SearchSong searches for a song on Netease and returns the song ID.
+func (c *NeteaseClient) SearchSong(trackName, artistName string) (int64, error) {
+	query := trackName + " " + artistName
+	if strings.TrimSpace(query) == "" {
+		return 0, fmt.Errorf("empty search query")
+	}
+
+	searchURL := "http://music.163.com/api/search/pc"
+	params := url.Values{}
+	params.Set("s", query)
+	params.Set("type", "1")
+	params.Set("limit", "1")
+	params.Set("offset", "0")
+
+	fullURL := searchURL + "?" + params.Encode()
+
+	req, err := http.NewRequest("GET", fullURL, nil)
+	if err != nil {
+		return 0, fmt.Errorf("failed to create request: %w", err)
+	}
+
+	for k, v := range neteaseHeaders {
+		req.Header.Set(k, v)
+	}
+	req.Header.Set("User-Agent", getRandomUserAgent())
+
+	resp, err := c.httpClient.Do(req)
+	if err != nil {
+		return 0, fmt.Errorf("netease search failed: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != 200 {
+		return 0, fmt.Errorf("netease search returned HTTP %d", resp.StatusCode)
+	}
+
+	var searchResp neteaseSearchResponse
+	if err := json.NewDecoder(resp.Body).Decode(&searchResp); err != nil {
+		return 0, fmt.Errorf("failed to decode netease search: %w", err)
+	}
+
+	if searchResp.Result.SongCount == 0 || len(searchResp.Result.Songs) == 0 {
+		return 0, fmt.Errorf("no songs found on netease")
+	}
+
+	return searchResp.Result.Songs[0].ID, nil
+}
+
+// FetchLyricsByID fetches synced lyrics for a given Netease song ID.
+func (c *NeteaseClient) FetchLyricsByID(songID int64, includeTranslation, includeRomanization bool) (string, error) {
+	lyricsURL := "http://music.163.com/api/song/lyric"
+	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()
+
+	req, err := http.NewRequest("GET", fullURL, nil)
+	if err != nil {
+		return "", fmt.Errorf("failed to create request: %w", err)
+	}
+
+	for k, v := range neteaseHeaders {
+		req.Header.Set(k, v)
+	}
+	req.Header.Set("User-Agent", getRandomUserAgent())
+
+	resp, err := c.httpClient.Do(req)
+	if err != nil {
+		return "", fmt.Errorf("netease lyrics fetch failed: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != 200 {
+		return "", fmt.Errorf("netease lyrics returned HTTP %d", resp.StatusCode)
+	}
+
+	var lyricsResp neteaseLyricsResponse
+	if err := json.NewDecoder(resp.Body).Decode(&lyricsResp); err != nil {
+		return "", fmt.Errorf("failed to decode netease lyrics: %w", err)
+	}
+
+	if lyricsResp.LRC == nil || strings.TrimSpace(lyricsResp.LRC.Lyric) == "" {
+		return "", fmt.Errorf("no lyrics available on netease")
+	}
+
+	lyric := lyricsResp.LRC.Lyric
+
+	if includeTranslation && lyricsResp.TLyric != nil && strings.TrimSpace(lyricsResp.TLyric.Lyric) != "" {
+		lyric += "\n\n" + lyricsResp.TLyric.Lyric
+	}
+
+	if includeRomanization && lyricsResp.RomaLRC != nil && strings.TrimSpace(lyricsResp.RomaLRC.Lyric) != "" {
+		lyric += "\n\n" + lyricsResp.RomaLRC.Lyric
+	}
+
+	return lyric, nil
+}
+
+// FetchLyrics searches for a track and returns parsed LyricsResponse.
+func (c *NeteaseClient) FetchLyrics(
+	trackName,
+	artistName string,
+	durationSec float64,
+	includeTranslation,
+	includeRomanization bool,
+) (*LyricsResponse, error) {
+	songID, err := c.SearchSong(trackName, artistName)
+	if err != nil {
+		return nil, err
+	}
+
+	lrcText, err := c.FetchLyricsByID(songID, includeTranslation, includeRomanization)
+	if err != nil {
+		return nil, err
+	}
+
+	lines := parseSyncedLyrics(lrcText)
+	if len(lines) == 0 {
+		// May be plain text lyrics without timestamps
+		plainLines := strings.Split(lrcText, "\n")
+		for _, line := range plainLines {
+			trimmed := strings.TrimSpace(line)
+			if trimmed != "" {
+				lines = append(lines, LyricsLine{
+					StartTimeMs: 0,
+					Words:       trimmed,
+					EndTimeMs:   0,
+				})
+			}
+		}
+
+		if len(lines) == 0 {
+			return nil, fmt.Errorf("netease returned empty lyrics")
+		}
+
+		return &LyricsResponse{
+			Lines:    lines,
+			SyncType: "UNSYNCED",
+			Provider: "Netease",
+			Source:   "Netease",
+		}, nil
+	}
+
+	return &LyricsResponse{
+		Lines:    lines,
+		SyncType: "LINE_SYNCED",
+		Provider: "Netease",
+		Source:   "Netease",
+	}, nil
+}
@@ -0,0 +1,198 @@
+package gobackend
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"strings"
+	"time"
+)
+
+// QQMusicClient fetches lyrics from QQ Music.
+// Search uses public QQ Music API, lyrics use the paxsenix proxy.
+type QQMusicClient struct {
+	httpClient *http.Client
+}
+
+type qqMusicSearchResponse struct {
+	Data struct {
+		Song struct {
+			List []struct {
+				Title  string `json:"title"`
+				Singer []struct {
+					Name string `json:"name"`
+				} `json:"singer"`
+				Album struct {
+					Name string `json:"name"`
+				} `json:"album"`
+				ID int64 `json:"id"`
+			} `json:"list"`
+		} `json:"song"`
+	} `json:"data"`
+}
+
+// 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"`
+}
+
+func NewQQMusicClient() *QQMusicClient {
+	return &QQMusicClient{
+		httpClient: NewMetadataHTTPClient(15 * time.Second),
+	}
+}
+
+// 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")
+	}
+
+	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"
+
+	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))
+	if err != nil {
+		return "", 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 "", fmt.Errorf("qqmusic lyrics fetch failed: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != 200 {
+		return "", fmt.Errorf("qqmusic lyrics proxy returned HTTP %d", resp.StatusCode)
+	}
+
+	bodyBytes, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return "", fmt.Errorf("failed to read lyrics response: %w", err)
+	}
+
+	bodyStr := strings.TrimSpace(string(bodyBytes))
+	if bodyStr == "" {
+		return "", fmt.Errorf("empty lyrics response from qqmusic")
+	}
+
+	return bodyStr, nil
+}
+
+// FetchLyrics searches QQ Music and returns parsed LyricsResponse.
+func (c *QQMusicClient) FetchLyrics(
+	trackName,
+	artistName string,
+	durationSec float64,
+	multiPersonWordByWord bool,
+) (*LyricsResponse, error) {
+	payload, err := c.searchSong(trackName, artistName)
+	if err != nil {
+		return nil, err
+	}
+
+	rawLyrics, err := c.fetchLyricsByPayload(payload)
+	if err != nil {
+		return nil, err
+	}
+	if errMsg, isErrorPayload := detectLyricsErrorPayload(rawLyrics); isErrorPayload {
+		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)
+	if err != nil {
+		// If pax parsing fails, try to use as direct LRC text
+		lrcText = rawLyrics
+	}
+
+	lines := parseSyncedLyrics(lrcText)
+	if len(lines) > 0 {
+		return &LyricsResponse{
+			Lines:    lines,
+			SyncType: "LINE_SYNCED",
+			Provider: "QQ Music",
+			Source:   "QQ Music",
+		}, nil
+	}
+
+	resultLines := plainTextLyricsLines(lrcText)
+
+	if len(resultLines) > 0 {
+		return &LyricsResponse{
+			Lines:    resultLines,
+			SyncType: "UNSYNCED",
+			Provider: "QQ Music",
+			Source:   "QQ Music",
+		}, nil
+	}
+
+	return nil, fmt.Errorf("no lyrics found on qqmusic")
+}
@@ -4,16 +4,97 @@ import (
 	"bytes"
 	"encoding/binary"
 	"fmt"
+	stdimage "image"
+	_ "image/gif"
+	_ "image/jpeg"
+	_ "image/png"
 	"io"
 	"os"
+	"path/filepath"
 	"strconv"
 	"strings"

-	"github.com/go-flac/flacpicture"
-	"github.com/go-flac/flacvorbis"
-	"github.com/go-flac/go-flac"
+	"github.com/go-flac/flacpicture/v2"
+	"github.com/go-flac/flacvorbis/v2"
+	"github.com/go-flac/go-flac/v2"
 )

+func detectCoverMIME(coverPath string, coverData []byte) string {
+	// Prefer magic-byte detection over file extension.
+	// Some providers return non-JPEG data behind .jpg URLs.
+	if len(coverData) >= 8 &&
+		coverData[0] == 0x89 &&
+		coverData[1] == 0x50 &&
+		coverData[2] == 0x4E &&
+		coverData[3] == 0x47 &&
+		coverData[4] == 0x0D &&
+		coverData[5] == 0x0A &&
+		coverData[6] == 0x1A &&
+		coverData[7] == 0x0A {
+		return "image/png"
+	}
+	if len(coverData) >= 3 &&
+		coverData[0] == 0xFF &&
+		coverData[1] == 0xD8 &&
+		coverData[2] == 0xFF {
+		return "image/jpeg"
+	}
+	if len(coverData) >= 6 {
+		header := string(coverData[:6])
+		if header == "GIF87a" || header == "GIF89a" {
+			return "image/gif"
+		}
+	}
+	if len(coverData) >= 12 &&
+		string(coverData[:4]) == "RIFF" &&
+		string(coverData[8:12]) == "WEBP" {
+		return "image/webp"
+	}
+
+	switch strings.ToLower(filepath.Ext(strings.TrimSpace(coverPath))) {
+	case ".png":
+		return "image/png"
+	case ".jpg", ".jpeg":
+		return "image/jpeg"
+	case ".webp":
+		return "image/webp"
+	case ".gif":
+		return "image/gif"
+	}
+
+	return "image/jpeg"
+}
+
+func buildPictureBlock(coverPath string, coverData []byte) (flac.MetaDataBlock, error) {
+	if len(coverData) == 0 {
+		return flac.MetaDataBlock{}, fmt.Errorf("empty cover data")
+	}
+
+	mime := detectCoverMIME(coverPath, coverData)
+	picture := &flacpicture.MetadataBlockPicture{
+		PictureType: flacpicture.PictureTypeFrontCover,
+		MIME:        mime,
+		Description: "Front Cover",
+		ImageData:   coverData,
+	}
+
+	// Width/height/depth are optional in practice; keep zero when decode fails.
+	if cfg, format, err := stdimage.DecodeConfig(bytes.NewReader(coverData)); err == nil {
+		picture.Width = uint32(cfg.Width)
+		picture.Height = uint32(cfg.Height)
+		switch format {
+		case "png":
+			picture.ColorDepth = 32
+		case "jpeg":
+			picture.ColorDepth = 24
+		default:
+			picture.ColorDepth = 0
+		}
+	}
+
+	return picture.Marshal(), nil
+}
+
 type Metadata struct {
 	Title       string
 	Artist      string
@@ -29,6 +110,8 @@ type Metadata struct {
 	Genre       string
 	Label       string
 	Copyright   string
+	Composer    string
+	Comment     string
 }

 func EmbedMetadata(filePath string, metadata Metadata, coverPath string) error {
@@ -98,6 +181,14 @@ func EmbedMetadata(filePath string, metadata Metadata, coverPath string) error {
 		setComment(cmt, "COPYRIGHT", metadata.Copyright)
 	}

+	if metadata.Composer != "" {
+		setComment(cmt, "COMPOSER", metadata.Composer)
+	}
+
+	if metadata.Comment != "" {
+		setComment(cmt, "COMMENT", metadata.Comment)
+	}
+
 	cmtBlock := cmt.Marshal()
 	if cmtIdx >= 0 {
 		f.Meta[cmtIdx] = &cmtBlock
@@ -117,19 +208,12 @@ func EmbedMetadata(filePath string, metadata Metadata, coverPath string) error {
 					}
 				}

-				picture, err := flacpicture.NewFromImageData(
-					flacpicture.PictureTypeFrontCover,
-					"Front Cover",
-					coverData,
-					"image/jpeg",
-				)
+				picBlock, err := buildPictureBlock(coverPath, coverData)
 				if err != nil {
-					fmt.Printf("[Metadata] Warning: Failed to create picture block: %v\n", err)
-				} else {
-					picBlock := picture.Marshal()
-					f.Meta = append(f.Meta, &picBlock)
-					fmt.Printf("[Metadata] Cover art embedded successfully (%d bytes)\n", len(coverData))
+					return fmt.Errorf("failed to create picture block: %w", err)
 				}
+				f.Meta = append(f.Meta, &picBlock)
+				fmt.Printf("[Metadata] Cover art embedded successfully (%d bytes)\n", len(coverData))
 			}
 		} else {
 			fmt.Printf("[Metadata] Warning: Cover file does not exist: %s\n", coverPath)
@@ -206,6 +290,14 @@ func EmbedMetadataWithCoverData(filePath string, metadata Metadata, coverData []
 		setComment(cmt, "COPYRIGHT", metadata.Copyright)
 	}

+	if metadata.Composer != "" {
+		setComment(cmt, "COMPOSER", metadata.Composer)
+	}
+
+	if metadata.Comment != "" {
+		setComment(cmt, "COMMENT", metadata.Comment)
+	}
+
 	cmtBlock := cmt.Marshal()
 	if cmtIdx >= 0 {
 		f.Meta[cmtIdx] = &cmtBlock
@@ -220,19 +312,12 @@ func EmbedMetadataWithCoverData(filePath string, metadata Metadata, coverData []
 			}
 		}

-		picture, err := flacpicture.NewFromImageData(
-			flacpicture.PictureTypeFrontCover,
-			"Front Cover",
-			coverData,
-			"image/jpeg",
-		)
+		picBlock, err := buildPictureBlock("", coverData)
 		if err != nil {
-			fmt.Printf("[Metadata] Warning: Failed to create picture block: %v\n", err)
-		} else {
-			picBlock := picture.Marshal()
-			f.Meta = append(f.Meta, &picBlock)
-			fmt.Printf("[Metadata] Cover art embedded successfully (%d bytes)\n", len(coverData))
+			return fmt.Errorf("failed to create picture block: %w", err)
 		}
+		f.Meta = append(f.Meta, &picBlock)
+		fmt.Printf("[Metadata] Cover art embedded successfully (%d bytes)\n", len(coverData))
 	}

 	return f.Save(filePath)
@@ -292,6 +377,12 @@ func ReadMetadata(filePath string) (*Metadata, error) {
 				metadata.Date = getComment(cmt, "YEAR")
 			}

+			metadata.Genre = getComment(cmt, "GENRE")
+			metadata.Label = getComment(cmt, "ORGANIZATION")
+			metadata.Copyright = getComment(cmt, "COPYRIGHT")
+			metadata.Composer = getComment(cmt, "COMPOSER")
+			metadata.Comment = getComment(cmt, "COMMENT")
+
 			break
 		}
 	}
@@ -451,33 +542,113 @@ func EmbedGenreLabel(filePath string, genre, label string) error {
 }

 func ExtractLyrics(filePath string) (string, error) {
+	lower := strings.ToLower(filePath)
+
+	if strings.HasSuffix(lower, ".flac") {
+		lyrics, err := extractLyricsFromFlac(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 {
+			if strings.TrimSpace(meta.Lyrics) != "" {
+				return meta.Lyrics, nil
+			}
+			if looksLikeEmbeddedLyrics(meta.Comment) {
+				return meta.Comment, nil
+			}
+		}
+		return extractLyricsFromSidecarLRC(filePath)
+	}
+
+	if strings.HasSuffix(lower, ".opus") || strings.HasSuffix(lower, ".ogg") {
+		meta, err := ReadOggVorbisComments(filePath)
+		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 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")
+	}
+
+	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) {
 	f, err := flac.ParseFile(filePath)
 	if err != nil {
 		return "", fmt.Errorf("failed to parse FLAC file: %w", err)
 	}

 	for _, meta := range f.Meta {
-		if meta.Type == flac.VorbisComment {
-			cmt, err := flacvorbis.ParseFromMetaDataBlock(*meta)
-			if err != nil {
-				continue
-			}
+		if meta.Type != flac.VorbisComment {
+			continue
+		}

-			lyrics, err := cmt.Get("LYRICS")
-			if err == nil && len(lyrics) > 0 && lyrics[0] != "" {
-				return lyrics[0], nil
-			}
+		cmt, err := flacvorbis.ParseFromMetaDataBlock(*meta)
+		if err != nil {
+			continue
+		}

-			lyrics, err = cmt.Get("UNSYNCEDLYRICS")
-			if err == nil && len(lyrics) > 0 && lyrics[0] != "" {
-				return lyrics[0], nil
-			}
+		lyrics, err := cmt.Get("LYRICS")
+		if err == nil && len(lyrics) > 0 && strings.TrimSpace(lyrics[0]) != "" {
+			return lyrics[0], nil
+		}
+
+		lyrics, err = cmt.Get("UNSYNCEDLYRICS")
+		if err == nil && len(lyrics) > 0 && strings.TrimSpace(lyrics[0]) != "" {
+			return lyrics[0], nil
 		}
 	}

 	return "", fmt.Errorf("no lyrics found in file")
 }

+func looksLikeEmbeddedLyrics(value string) bool {
+	trimmed := strings.TrimSpace(value)
+	if trimmed == "" {
+		return false
+	}
+
+	lower := strings.ToLower(trimmed)
+	if strings.Contains(lower, "[ar:") || strings.Contains(lower, "[ti:") {
+		return true
+	}
+
+	if strings.Contains(trimmed, "\n") && strings.Contains(trimmed, "[") && strings.Contains(trimmed, "]") {
+		return true
+	}
+
+	return false
+}
+
 type AudioQuality struct {
 	BitDepth     int   `json:"bit_depth"`
 	SampleRate   int   `json:"sample_rate"`
@@ -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"
 )
@@ -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
@@ -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
+}
@@ -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
+}
@@ -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"`
@@ -3,6 +3,24 @@ package gobackend
 import "testing"

 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 +62,74 @@ 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 TestQobuzAvailableProviders(t *testing.T) {
+	providers := NewQobuzDownloader().GetAvailableProviders()
+	if len(providers) != 3 {
+		t.Fatalf("expected 3 Qobuz providers, got %d", len(providers))
+	}
+
+	want := map[string]string{
+		"musicdl":  qobuzAPIKindMusicDL,
+		"dabmusic": qobuzAPIKindStandard,
+		"deeb":     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)
+	}
 }
@@ -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
@@ -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)
 }
@@ -0,0 +1,80 @@
+package gobackend
+
+import (
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestSanitizeSensitiveLogText(t *testing.T) {
+	input := "access_token=abc123 Authorization:Bearer xyz456 https://api.example.com/cb?refresh_token=zzz"
+	redacted := sanitizeSensitiveLogText(input)
+
+	if strings.Contains(redacted, "abc123") || strings.Contains(redacted, "xyz456") || strings.Contains(redacted, "zzz") {
+		t.Fatalf("expected sensitive values to be redacted, got: %s", redacted)
+	}
+	if !strings.Contains(redacted, "[REDACTED]") {
+		t.Fatalf("expected redaction marker in output, got: %s", redacted)
+	}
+}
+
+func TestValidateExtensionAuthURL(t *testing.T) {
+	if err := validateExtensionAuthURL("https://accounts.example.com/oauth/authorize"); err != nil {
+		t.Fatalf("expected valid auth URL, got error: %v", err)
+	}
+
+	blocked := []string{
+		"http://accounts.example.com/oauth/authorize",
+		"https://user:pass@accounts.example.com/oauth/authorize",
+		"https://localhost/oauth/authorize",
+	}
+
+	for _, rawURL := range blocked {
+		if err := validateExtensionAuthURL(rawURL); err == nil {
+			t.Fatalf("expected URL to be blocked: %s", rawURL)
+		}
+	}
+}
+
+func TestValidateDomainRejectsEmbeddedCredentials(t *testing.T) {
+	ext := &LoadedExtension{
+		ID: "test-ext",
+		Manifest: &ExtensionManifest{
+			Name: "test-ext",
+			Permissions: ExtensionPermissions{
+				Network: []string{"api.example.com"},
+			},
+		},
+		DataDir: t.TempDir(),
+	}
+
+	runtime := NewExtensionRuntime(ext)
+	if err := runtime.validateDomain("https://user:pass@api.example.com/resource"); err == nil {
+		t.Fatal("expected embedded URL credentials to be rejected")
+	}
+}
+
+func TestBuildStoreExtensionDestPath(t *testing.T) {
+	baseDir := t.TempDir()
+
+	destPath, err := buildStoreExtensionDestPath(baseDir, "../evil/name")
+	if err != nil {
+		t.Fatalf("expected sanitized path to be generated, got error: %v", err)
+	}
+
+	if !isPathWithinBase(baseDir, destPath) {
+		t.Fatalf("expected destination path to remain under base dir: %s", destPath)
+	}
+
+	baseName := filepath.Base(destPath)
+	if strings.Contains(baseName, "/") || strings.Contains(baseName, `\`) {
+		t.Fatalf("expected filename to be sanitized, got: %s", baseName)
+	}
+	if !strings.HasSuffix(baseName, ".spotiflac-ext") {
+		t.Fatalf("expected .spotiflac-ext suffix, got: %s", baseName)
+	}
+
+	if _, err := buildStoreExtensionDestPath(baseDir, "   "); err == nil {
+		t.Fatal("expected empty extension id to be rejected")
+	}
+}
@@ -1,7 +1,7 @@
 package gobackend

 import (
-	"encoding/base64"
+	"context"
 	"encoding/json"
 	"fmt"
 	"net/http"
@@ -15,42 +15,125 @@ type SongLinkClient struct {
 }

 type TrackAvailability struct {
-	SpotifyID string `json:"spotify_id"`
-	Tidal     bool   `json:"tidal"`
-	Amazon    bool   `json:"amazon"`
-	Qobuz     bool   `json:"qobuz"`
-	Deezer    bool   `json:"deezer"`
-	TidalURL  string `json:"tidal_url,omitempty"`
-	AmazonURL string `json:"amazon_url,omitempty"`
-	QobuzURL  string `json:"qobuz_url,omitempty"`
-	DeezerURL string `json:"deezer_url,omitempty"`
-	DeezerID  string `json:"deezer_id,omitempty"`
-	QobuzID   string `json:"qobuz_id,omitempty"`
-	TidalID   string `json:"tidal_id,omitempty"`
+	SpotifyID  string `json:"spotify_id"`
+	Tidal      bool   `json:"tidal"`
+	Amazon     bool   `json:"amazon"`
+	Qobuz      bool   `json:"qobuz"`
+	Deezer     bool   `json:"deezer"`
+	YouTube    bool   `json:"youtube"`
+	TidalURL   string `json:"tidal_url,omitempty"`
+	AmazonURL  string `json:"amazon_url,omitempty"`
+	QobuzURL   string `json:"qobuz_url,omitempty"`
+	DeezerURL  string `json:"deezer_url,omitempty"`
+	YouTubeURL string `json:"youtube_url,omitempty"`
+	DeezerID   string `json:"deezer_id,omitempty"`
+	QobuzID    string `json:"qobuz_id,omitempty"`
+	TidalID    string `json:"tidal_id,omitempty"`
+	YouTubeID  string `json:"youtube_id,omitempty"`
 }

 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)
+	}
 )

 func NewSongLinkClient() *SongLinkClient {
 	songLinkClientOnce.Do(func() {
 		globalSongLinkClient = &SongLinkClient{
-			client: NewHTTPClientWithTimeout(SongLinkTimeout),
+			client: NewMetadataHTTPClient(SongLinkTimeout),
 		}
 	})
 	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) {
+	spotifyTrackID = strings.TrimSpace(spotifyTrackID)
+	isrc = strings.ToUpper(strings.TrimSpace(isrc))
+
+	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")
+	}
+}
+
+func (s *SongLinkClient) checkTrackAvailabilityFromSpotify(spotifyTrackID string) (*TrackAvailability, error) {
 	songLinkRateLimiter.WaitForSlot()

-	spotifyBase, _ := base64.StdEncoding.DecodeString("aHR0cHM6Ly9vcGVuLnNwb3RpZnkuY29tL3RyYWNrLw==")
-	spotifyURL := fmt.Sprintf("%s%s", string(spotifyBase), spotifyTrackID)
-
-	apiBase, _ := base64.StdEncoding.DecodeString("aHR0cHM6Ly9hcGkuc29uZy5saW5rL3YxLWFscGhhLjEvbGlua3M/dXJsPQ==")
-	apiURL := fmt.Sprintf("%s%s", string(apiBase), url.QueryEscape(spotifyURL))
+	spotifyURL := fmt.Sprintf("https://open.spotify.com/track/%s", spotifyTrackID)
+	apiURL := buildSongLinkURLFromTarget(spotifyURL, "")

 	req, err := http.NewRequest("GET", apiURL, nil)
 	if err != nil {
@@ -119,9 +202,66 @@ func (s *SongLinkClient) CheckTrackAvailability(spotifyTrackID string, isrc stri
 		availability.QobuzID = extractQobuzIDFromURL(qobuzLink.URL)
 	}

+	// 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)
+		}
+	}
+
 	return availability, 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 {
@@ -139,7 +279,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 {
@@ -152,7 +291,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
@@ -163,29 +302,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 {
@@ -204,7 +338,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]
 		}
@@ -217,10 +350,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 ""
@@ -246,6 +375,44 @@ func extractTidalIDFromURL(tidalURL string) string {
 	return ""
 }

+func extractYouTubeIDFromURL(youtubeURL string) string {
+	if youtubeURL == "" {
+		return ""
+	}
+
+	if strings.Contains(youtubeURL, "youtu.be/") {
+		parts := strings.Split(youtubeURL, "youtu.be/")
+		if len(parts) >= 2 {
+			idPart := parts[1]
+			if idx := strings.Index(idPart, "?"); idx > 0 {
+				idPart = idPart[:idx]
+			}
+			if idx := strings.Index(idPart, "&"); idx > 0 {
+				idPart = idPart[:idx]
+			}
+			return strings.TrimSpace(idPart)
+		}
+	}
+
+	parsed, err := url.Parse(youtubeURL)
+	if err != nil {
+		return ""
+	}
+
+	if v := parsed.Query().Get("v"); v != "" {
+		return v
+	}
+
+	if strings.Contains(parsed.Path, "/embed/") {
+		parts := strings.Split(parsed.Path, "/embed/")
+		if len(parts) >= 2 {
+			return strings.Split(parts[1], "/")[0]
+		}
+	}
+
+	return ""
+}
+
 // isNumeric is defined in library_scan.go

 func (s *SongLinkClient) GetDeezerIDFromSpotify(spotifyTrackID string) (string, error) {
@@ -261,7 +428,19 @@ func (s *SongLinkClient) GetDeezerIDFromSpotify(spotifyTrackID string) (string,
 	return availability.DeezerID, nil
 }

-// AlbumAvailability represents album availability on different platforms
+func (s *SongLinkClient) GetYouTubeURLFromSpotify(spotifyTrackID string) (string, error) {
+	availability, err := s.CheckTrackAvailability(spotifyTrackID, "")
+	if err != nil {
+		return "", err
+	}
+
+	if !availability.YouTube || availability.YouTubeURL == "" {
+		return "", fmt.Errorf("track not found on YouTube")
+	}
+
+	return availability.YouTubeURL, nil
+}
+
 type AlbumAvailability struct {
 	SpotifyID string `json:"spotify_id"`
 	Deezer    bool   `json:"deezer"`
@@ -272,11 +451,8 @@ 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 {
@@ -322,7 +498,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 {
@@ -356,14 +531,11 @@ 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 {
@@ -441,6 +613,20 @@ func (s *SongLinkClient) checkAvailabilityFromDeezerSongLink(deezerTrackID strin
 		availability.DeezerURL = deezerLink.URL
 	}

+	// Prefer youtubeMusic URLs — they are usually closer to music catalog matches.
+	if ytMusicLink, ok := songLinkResp.LinksByPlatform["youtubeMusic"]; ok && ytMusicLink.URL != "" {
+		availability.YouTube = true
+		availability.YouTubeURL = ytMusicLink.URL
+		availability.YouTubeID = extractYouTubeIDFromURL(ytMusicLink.URL)
+	}
+	if !availability.YouTube {
+		if youtubeLink, ok := songLinkResp.LinksByPlatform["youtube"]; ok && youtubeLink.URL != "" {
+			availability.YouTube = true
+			availability.YouTubeURL = youtubeLink.URL
+			availability.YouTubeID = extractYouTubeIDFromURL(youtubeLink.URL)
+		}
+	}
+
 	return availability, nil
 }

@@ -454,10 +640,7 @@ 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 {
@@ -528,10 +711,23 @@ func (s *SongLinkClient) CheckAvailabilityByPlatform(platform, entityType, entit
 		availability.DeezerID = extractDeezerIDFromURL(deezerLink.URL)
 	}

+	// Prefer youtubeMusic URLs — they are usually closer to music catalog matches.
+	if ytMusicLink, ok := songLinkResp.LinksByPlatform["youtubeMusic"]; ok && ytMusicLink.URL != "" {
+		availability.YouTube = true
+		availability.YouTubeURL = ytMusicLink.URL
+		availability.YouTubeID = extractYouTubeIDFromURL(ytMusicLink.URL)
+	}
+	if !availability.YouTube {
+		if youtubeLink, ok := songLinkResp.LinksByPlatform["youtube"]; ok && youtubeLink.URL != "" {
+			availability.YouTube = true
+			availability.YouTubeURL = youtubeLink.URL
+			availability.YouTubeID = extractYouTubeIDFromURL(youtubeLink.URL)
+		}
+	}
+
 	return availability, nil
 }

-// extractSpotifyIDFromURL extracts Spotify track ID from URL
 func extractSpotifyIDFromURL(spotifyURL string) string {
 	parts := strings.Split(spotifyURL, "/track/")
 	if len(parts) > 1 {
@@ -557,7 +753,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 {
@@ -584,11 +779,23 @@ func (s *SongLinkClient) GetAmazonURLFromDeezer(deezerTrackID string) (string, e
 	return availability.AmazonURL, nil
 }

+func (s *SongLinkClient) GetYouTubeURLFromDeezer(deezerTrackID string) (string, error) {
+	availability, err := s.CheckAvailabilityFromDeezer(deezerTrackID)
+	if err != nil {
+		return "", err
+	}
+
+	if !availability.YouTube || availability.YouTubeURL == "" {
+		return "", fmt.Errorf("track not found on YouTube")
+	}
+
+	return availability.YouTubeURL, nil
+}
+
 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 {
@@ -652,6 +859,19 @@ func (s *SongLinkClient) CheckAvailabilityFromURL(inputURL string) (*TrackAvaila
 		availability.DeezerURL = deezerLink.URL
 		availability.DeezerID = extractDeezerIDFromURL(deezerLink.URL)
 	}
+	// Prefer youtubeMusic URLs — they are usually closer to music catalog matches.
+	if ytMusicLink, ok := songLinkResp.LinksByPlatform["youtubeMusic"]; ok && ytMusicLink.URL != "" {
+		availability.YouTube = true
+		availability.YouTubeURL = ytMusicLink.URL
+		availability.YouTubeID = extractYouTubeIDFromURL(ytMusicLink.URL)
+	}
+	if !availability.YouTube {
+		if youtubeLink, ok := songLinkResp.LinksByPlatform["youtube"]; ok && youtubeLink.URL != "" {
+			availability.YouTube = true
+			availability.YouTubeURL = youtubeLink.URL
+			availability.YouTubeID = extractYouTubeIDFromURL(youtubeLink.URL)
+		}
+	}

 	return availability, nil
 }
@@ -0,0 +1,80 @@
+package gobackend
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+	"time"
+)
+
+const DefaultSpotFetchAPIBaseURL = "https://spotify.afkarxyz.fun/api"
+
+// GetSpotifyDataWithAPI fetches Spotify metadata through SpotFetch-compatible API.
+// This is used as a fallback when direct Spotify API access is blocked/limited.
+func GetSpotifyDataWithAPI(ctx context.Context, spotifyURL, apiBaseURL string) (interface{}, error) {
+	parsed, err := parseSpotifyURI(spotifyURL)
+	if err != nil {
+		return nil, fmt.Errorf("invalid Spotify URL: %w", err)
+	}
+
+	base := strings.TrimSpace(apiBaseURL)
+	if base == "" {
+		base = DefaultSpotFetchAPIBaseURL
+	}
+
+	endpoint := fmt.Sprintf("%s/%s/%s", strings.TrimSuffix(base, "/"), parsed.Type, parsed.ID)
+	req, err := http.NewRequestWithContext(ctx, "GET", endpoint, nil)
+	if err != nil {
+		return nil, fmt.Errorf("failed to create SpotFetch API request: %w", err)
+	}
+	req.Header.Set("User-Agent", getRandomUserAgent())
+	req.Header.Set("Accept", "application/json")
+
+	client := NewHTTPClientWithTimeout(30 * time.Second)
+	resp, err := client.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("SpotFetch API request failed: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("SpotFetch API error: HTTP %d", resp.StatusCode)
+	}
+
+	bodyBytes, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("failed to read SpotFetch API response: %w", err)
+	}
+
+	switch parsed.Type {
+	case "track":
+		var trackResp TrackResponse
+		if err := json.Unmarshal(bodyBytes, &trackResp); err != nil {
+			return nil, fmt.Errorf("failed to decode track response: %w", err)
+		}
+		return trackResp, nil
+	case "album":
+		var albumResp AlbumResponsePayload
+		if err := json.Unmarshal(bodyBytes, &albumResp); err != nil {
+			return nil, fmt.Errorf("failed to decode album response: %w", err)
+		}
+		return &albumResp, nil
+	case "playlist":
+		var playlistResp PlaylistResponsePayload
+		if err := json.Unmarshal(bodyBytes, &playlistResp); err != nil {
+			return nil, fmt.Errorf("failed to decode playlist response: %w", err)
+		}
+		return playlistResp, nil
+	case "artist":
+		var artistResp ArtistResponsePayload
+		if err := json.Unmarshal(bodyBytes, &artistResp); err != nil {
+			return nil, fmt.Errorf("failed to decode artist response: %w", err)
+		}
+		return &artistResp, nil
+	default:
+		return nil, fmt.Errorf("unsupported Spotify type: %s", parsed.Type)
+	}
+}
@@ -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
 }

@@ -114,7 +89,7 @@ func NewSpotifyMetadataClient() (*SpotifyMetadataClient, error) {
 	src := rand.NewSource(time.Now().UnixNano())

 	c := &SpotifyMetadataClient{
-		httpClient:   NewHTTPClientWithTimeout(15 * time.Second),
+		httpClient:   NewMetadataHTTPClient(15 * time.Second),
 		clientID:     clientID,
 		clientSecret: clientSecret,
 		rng:          rand.New(src),
@@ -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"`
 }

@@ -361,6 +338,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 +356,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 +409,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 +427,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 +827,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"`
@@ -20,13 +20,8 @@ import (
 )

 type TidalDownloader struct {
-	client         *http.Client
-	clientID       string
-	clientSecret   string
-	apiURL         string
-	cachedToken    string
-	tokenExpiresAt time.Time
-	tokenMu        sync.Mutex
+	client *http.Client
+	apiURL string
 }

 var (
@@ -34,6 +29,11 @@ var (
 	tidalDownloaderOnce   sync.Once
 )

+const (
+	spotifyTrackBaseURL   = "https://open.spotify.com/track/"
+	songLinkLookupBaseURL = "https://api.song.link/v1-alpha.1/links?url="
+)
+
 type TidalTrack struct {
 	ID           int64  `json:"id"`
 	Title        string `json:"title"`
@@ -102,13 +102,8 @@ type MPD struct {

 func NewTidalDownloader() *TidalDownloader {
 	tidalDownloaderOnce.Do(func() {
-		clientID, _ := base64.StdEncoding.DecodeString("NkJEU1JkcEs5aHFFQlRnVQ==")
-		clientSecret, _ := base64.StdEncoding.DecodeString("eGV1UG1ZN25icFo5SUliTEFjUTkzc2hrYTFWTmhlVUFxTjZJY3N6alRHOD0=")
-
 		globalTidalDownloader = &TidalDownloader{
-			client:       NewHTTPClientWithTimeout(DefaultTimeout), // 60s timeout
-			clientID:     string(clientID),
-			clientSecret: string(clientSecret),
+			client: NewHTTPClientWithTimeout(DefaultTimeout),
 		}

 		apis := globalTidalDownloader.GetAvailableAPIs()
@@ -120,85 +115,27 @@ func NewTidalDownloader() *TidalDownloader {
 }

 func (t *TidalDownloader) GetAvailableAPIs() []string {
-	encodedAPIs := []string{
-		"dGlkYWwtYXBpLmJpbmltdW0ub3Jn",     // tidal-api.binimum.org (priority)
-		"dGlkYWwua2lub3BsdXMub25saW5l",     // tidal.kinoplus.online
-		"dHJpdG9uLnNxdWlkLnd0Zg==",         // triton.squid.wtf
-		"dm9nZWwucXFkbC5zaXRl",             // vogel.qqdl.site
-		"bWF1cy5xcWRsLnNpdGU=",             // maus.qqdl.site
-		"aHVuZC5xcWRsLnNpdGU=",             // hund.qqdl.site
-		"a2F0emUucXFkbC5zaXRl",             // katze.qqdl.site
-		"d29sZi5xcWRsLnNpdGU=",             // wolf.qqdl.site
-		"aGlmaS1vbmUuc3BvdGlzYXZlci5uZXQ=", // hifi-one.spotisaver.net
-		"aGlmaS10d28uc3BvdGlzYXZlci5uZXQ=", // hifi-two.spotisaver.net
+	return []string{
+		"https://tidal-api.binimum.org",
+		"https://tidal.kinoplus.online",
+		"https://triton.squid.wtf",
+		"https://vogel.qqdl.site",
+		"https://maus.qqdl.site",
+		"https://hund.qqdl.site",
+		"https://katze.qqdl.site",
+		"https://wolf.qqdl.site",
+		"https://hifi-one.spotisaver.net",
+		"https://hifi-two.spotisaver.net",
 	}
-
-	var apis []string
-	for _, encoded := range encodedAPIs {
-		decoded, err := base64.StdEncoding.DecodeString(encoded)
-		if err != nil {
-			continue
-		}
-		apis = append(apis, "https://"+string(decoded))
-	}
-
-	return apis
 }

 func (t *TidalDownloader) GetAccessToken() (string, error) {
-	t.tokenMu.Lock()
-	defer t.tokenMu.Unlock()
-
-	if t.cachedToken != "" && time.Now().Add(60*time.Second).Before(t.tokenExpiresAt) {
-		return t.cachedToken, nil
-	}
-
-	data := fmt.Sprintf("client_id=%s&grant_type=client_credentials", t.clientID)
-
-	authURL, _ := base64.StdEncoding.DecodeString("aHR0cHM6Ly9hdXRoLnRpZGFsLmNvbS92MS9vYXV0aDIvdG9rZW4=")
-	req, err := http.NewRequest("POST", string(authURL), strings.NewReader(data))
-	if err != nil {
-		return "", err
-	}
-
-	req.SetBasicAuth(t.clientID, t.clientSecret)
-	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
-
-	resp, err := DoRequestWithUserAgent(t.client, req)
-	if err != nil {
-		return "", err
-	}
-	defer resp.Body.Close()
-
-	if resp.StatusCode != 200 {
-		return "", fmt.Errorf("failed to get access token: HTTP %d", resp.StatusCode)
-	}
-
-	var result struct {
-		AccessToken string `json:"access_token"`
-		ExpiresIn   int    `json:"expires_in"`
-	}
-
-	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
-		return "", err
-	}
-
-	t.cachedToken = result.AccessToken
-	if result.ExpiresIn > 0 {
-		t.tokenExpiresAt = time.Now().Add(time.Duration(result.ExpiresIn) * time.Second)
-	} else {
-		t.tokenExpiresAt = time.Now().Add(55 * time.Minute) // Default 55 min
-	}
-
-	return result.AccessToken, nil
+	return "", fmt.Errorf("tidal official metadata API disabled: no client credentials mode")
 }

 func (t *TidalDownloader) GetTidalURLFromSpotify(spotifyTrackID string) (string, error) {
-	spotifyBase, _ := base64.StdEncoding.DecodeString("aHR0cHM6Ly9vcGVuLnNwb3RpZnkuY29tL3RyYWNrLw==")
-	spotifyURL := fmt.Sprintf("%s%s", string(spotifyBase), spotifyTrackID)
-
-	apiBase, _ := base64.StdEncoding.DecodeString("aHR0cHM6Ly9hcGkuc29uZy5saW5rL3YxLWFscGhhLjEvbGlua3M/dXJsPQ==")
-	apiURL := fmt.Sprintf("%s%s", string(apiBase), url.QueryEscape(spotifyURL))
+	spotifyURL := fmt.Sprintf("%s%s", spotifyTrackBaseURL, spotifyTrackID)
+	apiURL := fmt.Sprintf("%s%s", songLinkLookupBaseURL, url.QueryEscape(spotifyURL))

 	req, err := http.NewRequest("GET", apiURL, nil)
 	if err != nil {
@@ -251,324 +188,21 @@ func (t *TidalDownloader) GetTrackIDFromURL(tidalURL string) (int64, error) {
 }

 func (t *TidalDownloader) GetTrackInfoByID(trackID int64) (*TidalTrack, error) {
-	token, err := t.GetAccessToken()
-	if err != nil {
-		return nil, fmt.Errorf("failed to get access token: %w", err)
-	}
-
-	trackBase, _ := base64.StdEncoding.DecodeString("aHR0cHM6Ly9hcGkudGlkYWwuY29tL3YxL3RyYWNrcy8=")
-	trackURL := fmt.Sprintf("%s%d?countryCode=US", string(trackBase), trackID)
-
-	req, err := http.NewRequest("GET", trackURL, nil)
-	if err != nil {
-		return nil, err
-	}
-
-	req.Header.Set("Authorization", "Bearer "+token)
-
-	resp, err := DoRequestWithUserAgent(t.client, req)
-	if err != nil {
-		return nil, err
-	}
-	defer resp.Body.Close()
-
-	if resp.StatusCode != 200 {
-		return nil, fmt.Errorf("failed to get track info: HTTP %d", resp.StatusCode)
-	}
-
-	var trackInfo TidalTrack
-	if err := json.NewDecoder(resp.Body).Decode(&trackInfo); err != nil {
-		return nil, err
-	}
-
-	return &trackInfo, nil
+	return nil, fmt.Errorf("tidal track lookup API disabled: no client credentials mode")
 }

 func (t *TidalDownloader) SearchTrackByISRC(isrc string) (*TidalTrack, error) {
-	token, err := t.GetAccessToken()
-	if err != nil {
-		return nil, err
-	}
-
-	searchBase, _ := base64.StdEncoding.DecodeString("aHR0cHM6Ly9hcGkudGlkYWwuY29tL3YxL3NlYXJjaC90cmFja3M/cXVlcnk9")
-	searchURL := fmt.Sprintf("%s%s&limit=50&countryCode=US", string(searchBase), url.QueryEscape(isrc))
-
-	req, err := http.NewRequest("GET", searchURL, nil)
-	if err != nil {
-		return nil, err
-	}
-
-	req.Header.Set("Authorization", "Bearer "+token)
-
-	resp, err := DoRequestWithUserAgent(t.client, req)
-	if err != nil {
-		return nil, err
-	}
-	defer resp.Body.Close()
-
-	if resp.StatusCode != 200 {
-		return nil, fmt.Errorf("search failed: HTTP %d", resp.StatusCode)
-	}
-
-	var result struct {
-		Items []TidalTrack `json:"items"`
-	}
-	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
-		return nil, err
-	}
-
-	for i := range result.Items {
-		if result.Items[i].ISRC == isrc {
-			return &result.Items[i], nil
-		}
-	}
-
-	if len(result.Items) == 0 {
-		return nil, fmt.Errorf("no tracks found for ISRC: %s", isrc)
-	}
-
-	return nil, fmt.Errorf("no exact ISRC match found for: %s", isrc)
+	return nil, fmt.Errorf("tidal ISRC search API disabled: no client credentials mode")
 }

-// Now includes romaji conversion for Japanese text (4 search strategies like PC)
-func (t *TidalDownloader) SearchTrackByMetadataWithISRC(trackName, artistName, spotifyISRC string, expectedDuration int) (*TidalTrack, error) {
-	token, err := t.GetAccessToken()
-	if err != nil {
-		return nil, err
-	}
-
-	// Build search queries - multiple strategies (same as PC version)
-	queries := []string{}
-
-	if artistName != "" && trackName != "" {
-		queries = append(queries, artistName+" "+trackName)
-	}
-
-	if trackName != "" {
-		queries = append(queries, trackName)
-	}
-
-	if ContainsJapanese(trackName) || ContainsJapanese(artistName) {
-		romajiTrack := JapaneseToRomaji(trackName)
-		romajiArtist := JapaneseToRomaji(artistName)
-
-		cleanRomajiTrack := CleanToASCII(romajiTrack)
-		cleanRomajiArtist := CleanToASCII(romajiArtist)
-
-		if cleanRomajiArtist != "" && cleanRomajiTrack != "" {
-			romajiQuery := cleanRomajiArtist + " " + cleanRomajiTrack
-			if !containsQuery(queries, romajiQuery) {
-				queries = append(queries, romajiQuery)
-				GoLog("[Tidal] Japanese detected, adding romaji query: %s\n", romajiQuery)
-			}
-		}
-
-		if cleanRomajiTrack != "" && cleanRomajiTrack != trackName {
-			if !containsQuery(queries, cleanRomajiTrack) {
-				queries = append(queries, cleanRomajiTrack)
-			}
-		}
-
-		if artistName != "" && cleanRomajiTrack != "" {
-			partialQuery := artistName + " " + cleanRomajiTrack
-			if !containsQuery(queries, partialQuery) {
-				queries = append(queries, partialQuery)
-			}
-		}
-	}
-
-	if artistName != "" {
-		artistOnly := CleanToASCII(JapaneseToRomaji(artistName))
-		if artistOnly != "" && !containsQuery(queries, artistOnly) {
-			queries = append(queries, artistOnly)
-		}
-	}
-
-	searchBase, _ := base64.StdEncoding.DecodeString("aHR0cHM6Ly9hcGkudGlkYWwuY29tL3YxL3NlYXJjaC90cmFja3M/cXVlcnk9")
-
-	var allTracks []TidalTrack
-	searchedQueries := make(map[string]bool)
-
-	for _, query := range queries {
-		cleanQuery := strings.TrimSpace(query)
-		if cleanQuery == "" || searchedQueries[cleanQuery] {
-			continue
-		}
-		searchedQueries[cleanQuery] = true
-
-		GoLog("[Tidal] Searching for: %s\n", cleanQuery)
-
-		searchURL := fmt.Sprintf("%s%s&limit=100&countryCode=US", string(searchBase), url.QueryEscape(cleanQuery))
-
-		req, err := http.NewRequest("GET", searchURL, nil)
-		if err != nil {
-			continue
-		}
-
-		req.Header.Set("Authorization", "Bearer "+token)
-
-		resp, err := DoRequestWithUserAgent(t.client, req)
-		if err != nil {
-			GoLog("[Tidal] Search error for '%s': %v\n", cleanQuery, err)
-			continue
-		}
-
-		if resp.StatusCode != 200 {
-			resp.Body.Close()
-			continue
-		}
-
-		var result struct {
-			Items []TidalTrack `json:"items"`
-		}
-		if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
-			resp.Body.Close()
-			continue
-		}
-		resp.Body.Close()
-
-		if len(result.Items) > 0 {
-			GoLog("[Tidal] Found %d results for '%s'\n", len(result.Items), cleanQuery)
-
-			if spotifyISRC != "" {
-				for i := range result.Items {
-					if result.Items[i].ISRC == spotifyISRC {
-						track := &result.Items[i]
-						if expectedDuration > 0 {
-							durationDiff := track.Duration - expectedDuration
-							if durationDiff < 0 {
-								durationDiff = -durationDiff
-							}
-							if durationDiff <= 3 {
-								GoLog("[Tidal] ISRC match: '%s' (duration verified)\n", track.Title)
-								return track, nil
-							}
-							GoLog("[Tidal] ISRC match but duration mismatch (expected %ds, got %ds), continuing...\n",
-								expectedDuration, track.Duration)
-						} else {
-							GoLog("[Tidal] ISRC match: '%s'\n", track.Title)
-							return track, nil
-						}
-					}
-				}
-			}
-
-			allTracks = append(allTracks, result.Items...)
-		}
-	}
-
-	if len(allTracks) == 0 {
-		return nil, fmt.Errorf("no tracks found for any search query")
-	}
-
-	if spotifyISRC != "" {
-		GoLog("[Tidal] Looking for ISRC match: %s\n", spotifyISRC)
-		var isrcMatches []*TidalTrack
-		for i := range allTracks {
-			track := &allTracks[i]
-			if track.ISRC == spotifyISRC {
-				isrcMatches = append(isrcMatches, track)
-			}
-		}
-
-		if len(isrcMatches) > 0 {
-			if expectedDuration > 0 {
-				var durationVerifiedMatches []*TidalTrack
-				for _, track := range isrcMatches {
-					durationDiff := track.Duration - expectedDuration
-					if durationDiff < 0 {
-						durationDiff = -durationDiff
-					}
-					if durationDiff <= 3 {
-						durationVerifiedMatches = append(durationVerifiedMatches, track)
-					}
-				}
-
-				if len(durationVerifiedMatches) > 0 {
-					GoLog("[Tidal] ISRC match with duration verification: '%s' (expected %ds, found %ds)\n",
-						durationVerifiedMatches[0].Title, expectedDuration, durationVerifiedMatches[0].Duration)
-					return durationVerifiedMatches[0], nil
-				}
-
-				GoLog("[Tidal] WARNING: ISRC %s found but duration mismatch. Expected=%ds, Found=%ds. Rejecting.\n",
-					spotifyISRC, expectedDuration, isrcMatches[0].Duration)
-				return nil, fmt.Errorf("ISRC found but duration mismatch: expected %ds, found %ds (likely different version/edit)",
-					expectedDuration, isrcMatches[0].Duration)
-			}
-
-			GoLog("[Tidal] ISRC match (no duration verification): '%s'\n", isrcMatches[0].Title)
-			return isrcMatches[0], nil
-		}
-
-		GoLog("[Tidal] No ISRC match found for: %s\n", spotifyISRC)
-		return nil, fmt.Errorf("ISRC mismatch: no track found with ISRC %s on Tidal", spotifyISRC)
-	}
-
-	if expectedDuration > 0 {
-		tolerance := 3 // 3 seconds tolerance
-		var durationMatches []*TidalTrack
-
-		for i := range allTracks {
-			track := &allTracks[i]
-			durationDiff := track.Duration - expectedDuration
-			if durationDiff < 0 {
-				durationDiff = -durationDiff
-			}
-			if durationDiff <= tolerance {
-				durationMatches = append(durationMatches, track)
-			}
-		}
-
-		if len(durationMatches) > 0 {
-			bestMatch := durationMatches[0]
-			for _, track := range durationMatches {
-				for _, tag := range track.MediaMetadata.Tags {
-					if tag == "HIRES_LOSSLESS" {
-						bestMatch = track
-						break
-					}
-				}
-			}
-			GoLog("[Tidal] Found via duration match: %s - %s (%s)\n",
-				bestMatch.Artist.Name, bestMatch.Title, bestMatch.AudioQuality)
-			return bestMatch, nil
-		}
-	}
-
-	bestMatch := &allTracks[0]
-	for i := range allTracks {
-		track := &allTracks[i]
-		for _, tag := range track.MediaMetadata.Tags {
-			if tag == "HIRES_LOSSLESS" {
-				bestMatch = track
-				break
-			}
-		}
-		if bestMatch != &allTracks[0] {
-			break
-		}
-	}
-
-	GoLog("[Tidal] Found via search (no ISRC provided): %s - %s (ISRC: %s, Quality: %s)\n",
-		bestMatch.Artist.Name, bestMatch.Title, bestMatch.ISRC, bestMatch.AudioQuality)
-
-	return bestMatch, nil
-}
-
-func containsQuery(queries []string, query string) bool {
-	for _, q := range queries {
-		if q == query {
-			return true
-		}
-	}
-	return false
+func (t *TidalDownloader) SearchTrackByMetadataWithISRC(trackName, artistName, albumName, spotifyISRC string, expectedDuration int) (*TidalTrack, error) {
+	return nil, fmt.Errorf("tidal metadata search API disabled: no client credentials mode")
 }

 func (t *TidalDownloader) SearchTrackByMetadata(trackName, artistName string) (*TidalTrack, error) {
-	return t.SearchTrackByMetadataWithISRC(trackName, artistName, "", 0)
+	return nil, fmt.Errorf("tidal metadata search API disabled: no client credentials mode")
 }

-// TidalDownloadInfo contains download URL and quality info
 type TidalDownloadInfo struct {
 	URL        string
 	BitDepth   int
@@ -582,15 +216,13 @@ type tidalAPIResult struct {
 	duration time.Duration
 }

-// Tidal API timeout configuration
 // Mobile networks are more unstable, so we use longer timeouts
 const (
 	tidalAPITimeoutMobile = 25 * time.Second
-	tidalMaxRetries       = 2 // Number of retries per API
+	tidalMaxRetries       = 2
 	tidalRetryDelay       = 500 * time.Millisecond
 )

-// fetchTidalURLWithRetry fetches download URL from a single Tidal API with retry logic
 func fetchTidalURLWithRetry(api string, trackID int64, quality string, timeout time.Duration) (TidalDownloadInfo, error) {
 	var lastErr error
 	retryDelay := tidalRetryDelay
@@ -599,7 +231,7 @@ func fetchTidalURLWithRetry(api string, trackID int64, quality string, timeout t
 		if attempt > 0 {
 			GoLog("[Tidal] Retry %d/%d for %s after %v\n", attempt, tidalMaxRetries, api, retryDelay)
 			time.Sleep(retryDelay)
-			retryDelay *= 2 // Exponential backoff
+			retryDelay *= 2
 		}

 		client := NewHTTPClientWithTimeout(timeout)
@@ -614,17 +246,15 @@ func fetchTidalURLWithRetry(api string, trackID int64, quality string, timeout t
 		resp, err := client.Do(req)
 		if err != nil {
 			lastErr = err
-			// Check for retryable errors (timeout, connection reset)
 			errStr := strings.ToLower(err.Error())
 			if strings.Contains(errStr, "timeout") ||
 				strings.Contains(errStr, "reset") ||
 				strings.Contains(errStr, "connection refused") ||
 				strings.Contains(errStr, "eof") {
-				continue // Retry
+				continue
 			}
-			break // Non-retryable error
+			break
 		}
-		// Server errors are retryable
 		if resp.StatusCode >= 500 {
 			io.Copy(io.Discard, resp.Body)
 			resp.Body.Close()
@@ -637,7 +267,7 @@ func fetchTidalURLWithRetry(api string, trackID int64, quality string, timeout t
 			io.Copy(io.Discard, resp.Body)
 			resp.Body.Close()
 			lastErr = fmt.Errorf("rate limited")
-			retryDelay = 2 * time.Second // Wait longer for rate limit
+			retryDelay = 2 * time.Second
 			continue
 		}

@@ -1289,6 +919,32 @@ func titlesMatch(expectedTitle, foundTitle string) bool {
 		return true
 	}

+	looseExpected := normalizeLooseTitle(normExpected)
+	looseFound := normalizeLooseTitle(normFound)
+	if looseExpected != "" && looseFound != "" {
+		if looseExpected == looseFound {
+			return true
+		}
+		if strings.Contains(looseExpected, looseFound) || strings.Contains(looseFound, looseExpected) {
+			return true
+		}
+	}
+
+	// Emoji/symbol-only titles must be matched strictly to avoid false positives
+	// like mapping "🪐" to "Higher Power".
+	if (!hasAlphaNumericRunes(expectedTitle) || !hasAlphaNumericRunes(foundTitle)) &&
+		strings.TrimSpace(expectedTitle) != "" &&
+		strings.TrimSpace(foundTitle) != "" {
+		expectedSymbols := normalizeSymbolOnlyTitle(expectedTitle)
+		foundSymbols := normalizeSymbolOnlyTitle(foundTitle)
+		if expectedSymbols != "" && foundSymbols != "" && expectedSymbols == foundSymbols {
+			GoLog("[Tidal] Symbol-heavy title matched strictly: '%s' vs '%s'\n", expectedTitle, foundTitle)
+			return true
+		}
+		GoLog("[Tidal] Symbol-heavy title mismatch: '%s' vs '%s'\n", expectedTitle, foundTitle)
+		return false
+	}
+
 	expectedLatin := isLatinScript(expectedTitle)
 	foundLatin := isLatinScript(foundTitle)
 	if expectedLatin != foundLatin {
@@ -1406,182 +1062,9 @@ func isLatinScript(s string) bool {
 	return true
 }

-func downloadFromTidal(req DownloadRequest) (TidalDownloadResult, error) {
-	downloader := NewTidalDownloader()
-
-	isSafOutput := isFDOutput(req.OutputFD) || strings.TrimSpace(req.OutputPath) != ""
-	if !isSafOutput {
-		if existingFile, exists := checkISRCExistsInternal(req.OutputDir, req.ISRC); exists {
-			return TidalDownloadResult{FilePath: "EXISTS:" + existingFile}, nil
-		}
-	}
-
-	expectedDurationSec := req.DurationMS / 1000
-
-	var track *TidalTrack
-	var err error
-
-	if req.TidalID != "" {
-		GoLog("[Tidal] Using Tidal ID from Odesli enrichment: %s\n", req.TidalID)
-		var trackID int64
-		if _, parseErr := fmt.Sscanf(req.TidalID, "%d", &trackID); parseErr == nil && trackID > 0 {
-			track, err = downloader.GetTrackInfoByID(trackID)
-			if err != nil {
-				GoLog("[Tidal] Failed to get track by Odesli ID %d: %v\n", trackID, err)
-				track = nil
-			} else if track != nil {
-				GoLog("[Tidal] Successfully found track via Odesli ID: '%s' by '%s'\n", track.Title, track.Artist.Name)
-			}
-		}
-	}
-
-	if track == nil && req.ISRC != "" {
-		if cached := GetTrackIDCache().Get(req.ISRC); cached != nil && cached.TidalTrackID > 0 {
-			GoLog("[Tidal] Cache hit! Using cached track ID: %d\n", cached.TidalTrackID)
-			track, err = downloader.GetTrackInfoByID(cached.TidalTrackID)
-			if err != nil {
-				GoLog("[Tidal] Cache hit but failed to get track info: %v\n", err)
-				track = nil // Fall through to normal search
-			}
-		}
-	}
-
-	if track == nil && req.ISRC != "" {
-		GoLog("[Tidal] Trying ISRC search: %s\n", req.ISRC)
-		track, err = downloader.SearchTrackByMetadataWithISRC(req.TrackName, req.ArtistName, req.ISRC, expectedDurationSec)
-		if track != nil {
-			// Verify artist only (ISRC match is already accurate)
-			tidalArtist := track.Artist.Name
-			if len(track.Artists) > 0 {
-				var artistNames []string
-				for _, a := range track.Artists {
-					artistNames = append(artistNames, a.Name)
-				}
-				tidalArtist = strings.Join(artistNames, ", ")
-			}
-			if !artistsMatch(req.ArtistName, tidalArtist) {
-				GoLog("[Tidal] Artist mismatch from ISRC search: expected '%s', got '%s'. Rejecting.\n",
-					req.ArtistName, tidalArtist)
-				track = nil
-			}
-		}
-	}
-
-	if track == nil && req.SpotifyID != "" {
-		GoLog("[Tidal] ISRC search failed, trying SongLink...\n")
-
-		var trackID int64
-		var gotTidalID bool
-
-		if strings.HasPrefix(req.SpotifyID, "deezer:") {
-			deezerID := strings.TrimPrefix(req.SpotifyID, "deezer:")
-			GoLog("[Tidal] Using Deezer ID for SongLink lookup: %s\n", deezerID)
-			songlink := NewSongLinkClient()
-			availability, slErr := songlink.CheckAvailabilityFromDeezer(deezerID)
-			if slErr == nil && availability != nil && availability.TidalID != "" {
-				if _, parseErr := fmt.Sscanf(availability.TidalID, "%d", &trackID); parseErr == nil && trackID > 0 {
-					GoLog("[Tidal] Got Tidal ID %d directly from SongLink\n", trackID)
-					gotTidalID = true
-				}
-			}
-			// Fallback to URL parsing if TidalID not in struct
-			if !gotTidalID && availability != nil && availability.TidalURL != "" {
-				var idErr error
-				trackID, idErr = downloader.GetTrackIDFromURL(availability.TidalURL)
-				if idErr == nil && trackID > 0 {
-					GoLog("[Tidal] Got Tidal ID %d from URL parsing\n", trackID)
-					gotTidalID = true
-				}
-			}
-		} else {
-			songlink := NewSongLinkClient()
-			availability, slErr := songlink.CheckTrackAvailability(req.SpotifyID, req.ISRC)
-			if slErr == nil && availability != nil && availability.TidalID != "" {
-				if _, parseErr := fmt.Sscanf(availability.TidalID, "%d", &trackID); parseErr == nil && trackID > 0 {
-					GoLog("[Tidal] Got Tidal ID %d directly from SongLink\n", trackID)
-					gotTidalID = true
-				}
-			}
-			// Fallback to URL parsing if TidalID not in struct
-			if !gotTidalID && availability != nil && availability.TidalURL != "" {
-				var idErr error
-				trackID, idErr = downloader.GetTrackIDFromURL(availability.TidalURL)
-				if idErr == nil && trackID > 0 {
-					GoLog("[Tidal] Got Tidal ID %d from URL parsing\n", trackID)
-					gotTidalID = true
-				}
-			}
-		}
-
-		if gotTidalID && trackID > 0 {
-			track, err = downloader.GetTrackInfoByID(trackID)
-			if track != nil {
-				tidalArtist := track.Artist.Name
-				if len(track.Artists) > 0 {
-					var artistNames []string
-					for _, a := range track.Artists {
-						artistNames = append(artistNames, a.Name)
-					}
-					tidalArtist = strings.Join(artistNames, ", ")
-				}
-
-				if !artistsMatch(req.ArtistName, tidalArtist) {
-					GoLog("[Tidal] Artist mismatch from SongLink: expected '%s', got '%s'. Rejecting.\n",
-						req.ArtistName, tidalArtist)
-					track = nil
-				}
-
-				if track != nil && expectedDurationSec > 0 {
-					durationDiff := track.Duration - expectedDurationSec
-					if durationDiff < 0 {
-						durationDiff = -durationDiff
-					}
-					if durationDiff > 3 {
-						GoLog("[Tidal] Duration mismatch from SongLink: expected %ds, got %ds. Rejecting.\n",
-							expectedDurationSec, track.Duration)
-						track = nil // Reject this match
-					}
-				}
-
-				// Cache for future use
-				if track != nil && req.ISRC != "" {
-					GetTrackIDCache().SetTidal(req.ISRC, track.ID)
-				}
-			}
-		}
-	}
-
+func tidalTrackArtistsDisplay(track *TidalTrack) string {
 	if track == nil {
-		GoLog("[Tidal] Trying metadata search as last resort...\n")
-		track, err = downloader.SearchTrackByMetadataWithISRC(req.TrackName, req.ArtistName, "", expectedDurationSec)
-		if track != nil {
-			tidalArtist := track.Artist.Name
-			if len(track.Artists) > 0 {
-				var artistNames []string
-				for _, a := range track.Artists {
-					artistNames = append(artistNames, a.Name)
-				}
-				tidalArtist = strings.Join(artistNames, ", ")
-			}
-
-			if !titlesMatch(req.TrackName, track.Title) {
-				GoLog("[Tidal] Title mismatch from metadata search: expected '%s', got '%s'. Rejecting.\n",
-					req.TrackName, track.Title)
-				track = nil
-			} else if !artistsMatch(req.ArtistName, tidalArtist) {
-				GoLog("[Tidal] Artist mismatch from metadata search: expected '%s', got '%s'. Rejecting.\n",
-					req.ArtistName, tidalArtist)
-				track = nil
-			}
-		}
-	}
-
-	if track == nil {
-		errMsg := "could not find matching track on Tidal (artist/duration mismatch)"
-		if err != nil {
-			errMsg = err.Error()
-		}
-		return TidalDownloadResult{}, fmt.Errorf("tidal search failed: %s", errMsg)
+		return ""
 	}

 	tidalArtist := track.Artist.Name
@@ -1592,10 +1075,130 @@ func downloadFromTidal(req DownloadRequest) (TidalDownloadResult, error) {
 		}
 		tidalArtist = strings.Join(artistNames, ", ")
 	}
-	GoLog("[Tidal] Match found: '%s' by '%s' (duration: %ds)\n", track.Title, tidalArtist, track.Duration)
+	return tidalArtist
+}
+
+func resolveTidalTrackForRequest(req DownloadRequest, downloader *TidalDownloader, logPrefix string) (*TidalTrack, error) {
+	if downloader == nil {
+		downloader = NewTidalDownloader()
+	}
+	if strings.TrimSpace(logPrefix) == "" {
+		logPrefix = "Tidal"
+	}
+
+	expectedDurationSec := req.DurationMS / 1000
+	var trackID int64
+	var gotTidalID bool
+
+	if req.TidalID != "" {
+		GoLog("[%s] Using Tidal ID from Odesli enrichment: %s\n", logPrefix, req.TidalID)
+		if _, parseErr := fmt.Sscanf(req.TidalID, "%d", &trackID); parseErr == nil && trackID > 0 {
+			gotTidalID = true
+		}
+	}
+
+	if !gotTidalID && req.ISRC != "" {
+		if cached := GetTrackIDCache().Get(req.ISRC); cached != nil && cached.TidalTrackID > 0 {
+			GoLog("[%s] Cache hit! Using cached track ID: %d\n", logPrefix, cached.TidalTrackID)
+			trackID = cached.TidalTrackID
+			gotTidalID = true
+		}
+	}
+
+	if !gotTidalID && (req.SpotifyID != "" || req.DeezerID != "") {
+		GoLog("[%s] Trying SongLink for Tidal ID...\n", logPrefix)
+
+		resolveFromAvailability := func(availability *TrackAvailability) {
+			if availability == nil || gotTidalID {
+				return
+			}
+			if availability.TidalID != "" {
+				if _, parseErr := fmt.Sscanf(availability.TidalID, "%d", &trackID); parseErr == nil && trackID > 0 {
+					GoLog("[%s] Got Tidal ID %d directly from SongLink\n", logPrefix, trackID)
+					gotTidalID = true
+					return
+				}
+			}
+			if availability.TidalURL != "" {
+				var idErr error
+				trackID, idErr = downloader.GetTrackIDFromURL(availability.TidalURL)
+				if idErr == nil && trackID > 0 {
+					GoLog("[%s] Got Tidal ID %d from URL parsing\n", logPrefix, trackID)
+					gotTidalID = true
+				}
+			}
+		}
+
+		// Prefer Deezer-based SongLink lookup when DeezerID is available.
+		if req.DeezerID != "" {
+			GoLog("[%s] Using Deezer ID for SongLink lookup: %s\n", logPrefix, req.DeezerID)
+			songlink := NewSongLinkClient()
+			availability, slErr := songlink.CheckAvailabilityFromDeezer(req.DeezerID)
+			if slErr == nil {
+				resolveFromAvailability(availability)
+			} else {
+				GoLog("[%s] SongLink Deezer lookup failed: %v\n", logPrefix, slErr)
+			}
+		}
+
+		if !gotTidalID && req.SpotifyID != "" {
+			if strings.HasPrefix(req.SpotifyID, "deezer:") {
+				deezerID := strings.TrimPrefix(req.SpotifyID, "deezer:")
+				GoLog("[%s] Using Deezer ID for SongLink lookup: %s\n", logPrefix, deezerID)
+				songlink := NewSongLinkClient()
+				availability, slErr := songlink.CheckAvailabilityFromDeezer(deezerID)
+				if slErr == nil {
+					resolveFromAvailability(availability)
+				} else {
+					GoLog("[%s] SongLink Deezer lookup failed: %v\n", logPrefix, slErr)
+				}
+			}
+		}
+
+		if !gotTidalID && req.SpotifyID != "" && !strings.HasPrefix(req.SpotifyID, "deezer:") {
+			songlink := NewSongLinkClient()
+			availability, slErr := songlink.CheckTrackAvailability(req.SpotifyID, req.ISRC)
+			if slErr == nil {
+				resolveFromAvailability(availability)
+			}
+		}
+	}
+
+	if !gotTidalID || trackID <= 0 {
+		return nil, fmt.Errorf("failed to find tidal track id from request/cache/songlink")
+	}
+
+	track := &TidalTrack{
+		ID:           trackID,
+		Title:        strings.TrimSpace(req.TrackName),
+		ISRC:         strings.TrimSpace(req.ISRC),
+		Duration:     expectedDurationSec,
+		TrackNumber:  req.TrackNumber,
+		VolumeNumber: req.DiscNumber,
+	}
+	track.Artist.Name = strings.TrimSpace(req.ArtistName)
+	track.Album.Title = strings.TrimSpace(req.AlbumName)
+	track.Album.ReleaseDate = strings.TrimSpace(req.ReleaseDate)

 	if req.ISRC != "" {
-		GetTrackIDCache().SetTidal(req.ISRC, track.ID)
+		GetTrackIDCache().SetTidal(req.ISRC, trackID)
+	}
+	return track, nil
+}
+
+func downloadFromTidal(req DownloadRequest) (TidalDownloadResult, error) {
+	downloader := NewTidalDownloader()
+
+	isSafOutput := isFDOutput(req.OutputFD) || strings.TrimSpace(req.OutputPath) != ""
+	if !isSafOutput {
+		if existingFile, exists := checkISRCExistsInternal(req.OutputDir, req.ISRC); exists {
+			return TidalDownloadResult{FilePath: "EXISTS:" + existingFile}, nil
+		}
+	}
+
+	track, err := resolveTidalTrackForRequest(req, downloader, "Tidal")
+	if err != nil {
+		return TidalDownloadResult{}, err
 	}

 	quality := req.Quality
@@ -1609,6 +1212,7 @@ func downloadFromTidal(req DownloadRequest) (TidalDownloadResult, error) {
 		"album":  req.AlbumName,
 		"track":  req.TrackNumber,
 		"year":   extractYear(req.ReleaseDate),
+		"date":   req.ReleaseDate,
 		"disc":   req.DiscNumber,
 	})

@@ -1673,13 +1277,19 @@ func downloadFromTidal(req DownloadRequest) (TidalDownloadResult, error) {
 	parallelDone := make(chan struct{})
 	go func() {
 		defer close(parallelDone)
+		coverURL := req.CoverURL
+		embedLyrics := req.EmbedLyrics
+		if !req.EmbedMetadata {
+			coverURL = ""
+			embedLyrics = false
+		}
 		parallelResult = FetchCoverAndLyricsParallel(
-			req.CoverURL,
+			coverURL,
 			req.EmbedMaxQualityCover,
 			req.SpotifyID,
 			req.TrackName,
 			req.ArtistName,
-			req.EmbedLyrics,
+			embedLyrics,
 			int64(req.DurationMS),
 		)
 	}()
@@ -1763,11 +1373,15 @@ func downloadFromTidal(req DownloadRequest) (TidalDownloadResult, error) {
 	}

 	if (isSafOutput && actualExt == ".flac") || (!isSafOutput && strings.HasSuffix(actualOutputPath, ".flac")) {
-		if err := EmbedMetadataWithCoverData(actualOutputPath, metadata, coverData); err != nil {
-			fmt.Printf("Warning: failed to embed metadata: %v\n", err)
+		if req.EmbedMetadata {
+			if err := EmbedMetadataWithCoverData(actualOutputPath, metadata, coverData); err != nil {
+				fmt.Printf("Warning: failed to embed metadata: %v\n", err)
+			}
+		} else {
+			GoLog("[Tidal] Metadata embedding disabled by settings, skipping FLAC metadata/lyrics embedding\n")
 		}

-		if req.EmbedLyrics && parallelResult != nil && parallelResult.LyricsLRC != "" {
+		if req.EmbedMetadata && req.EmbedLyrics && parallelResult != nil && parallelResult.LyricsLRC != "" {
 			lyricsMode := req.LyricsMode
 			if lyricsMode == "" {
 				lyricsMode = "embed"
@@ -1790,14 +1404,14 @@ func downloadFromTidal(req DownloadRequest) (TidalDownloadResult, error) {
 					fmt.Println("[Tidal] Lyrics embedded successfully")
 				}
 			}
-		} else if req.EmbedLyrics {
+		} else if req.EmbedMetadata && req.EmbedLyrics {
 			fmt.Println("[Tidal] No lyrics available from parallel fetch")
 		}
 	} else if (isSafOutput && actualExt == ".m4a") || (!isSafOutput && strings.HasSuffix(actualOutputPath, ".m4a")) {
 		if quality == "HIGH" {
 			GoLog("[Tidal] HIGH quality M4A - skipping metadata embedding (file from server is already valid)\n")

-			if req.EmbedLyrics && parallelResult != nil && parallelResult.LyricsLRC != "" {
+			if req.EmbedMetadata && req.EmbedLyrics && parallelResult != nil && parallelResult.LyricsLRC != "" {
 				lyricsMode := req.LyricsMode
 				if lyricsMode == "" {
 					lyricsMode = "embed"
@@ -1828,7 +1442,7 @@ func downloadFromTidal(req DownloadRequest) (TidalDownloadResult, error) {
 		bitDepth = 0
 		sampleRate = 44100
 	}
-	if req.EmbedLyrics && parallelResult != nil && parallelResult.LyricsLRC != "" {
+	if req.EmbedMetadata && req.EmbedLyrics && parallelResult != nil && parallelResult.LyricsLRC != "" {
 		lyricsLRC = parallelResult.LyricsLRC
 	}

@@ -0,0 +1,70 @@
+package gobackend
+
+import (
+	"strings"
+	"unicode"
+)
+
+// normalizeLooseTitle collapses separators/punctuation so titles like
+// "Doctor / Cops" and "Doctor _ Cops" can still match.
+func normalizeLooseTitle(title string) string {
+	trimmed := strings.TrimSpace(strings.ToLower(title))
+	if trimmed == "" {
+		return ""
+	}
+
+	var b strings.Builder
+	b.Grow(len(trimmed))
+
+	for _, r := range trimmed {
+		switch {
+		case unicode.IsLetter(r), unicode.IsNumber(r):
+			b.WriteRune(r)
+		case unicode.IsSpace(r):
+			b.WriteByte(' ')
+		// Treat common separators as spaces.
+		case r == '/', r == '\\', r == '_', r == '-', r == '|', r == '.', r == '&', r == '+':
+			b.WriteByte(' ')
+		default:
+			// Drop other punctuation/symbols (including emoji) for loose matching.
+		}
+	}
+
+	return strings.Join(strings.Fields(b.String()), " ")
+}
+
+func hasAlphaNumericRunes(value string) bool {
+	for _, r := range value {
+		if unicode.IsLetter(r) || unicode.IsNumber(r) {
+			return true
+		}
+	}
+	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()
+}
@@ -0,0 +1,52 @@
+package gobackend
+
+import "testing"
+
+func TestNormalizeLooseTitle_Separators(t *testing.T) {
+	got := normalizeLooseTitle("Doctor / Cops")
+	if got != "doctor cops" {
+		t.Fatalf("expected doctor cops, got %q", got)
+	}
+
+	got = normalizeLooseTitle("Doctor _ Cops")
+	if got != "doctor cops" {
+		t.Fatalf("expected doctor cops, got %q", got)
+	}
+}
+
+func TestNormalizeLooseTitle_EmojiAndSymbols(t *testing.T) {
+	got := normalizeLooseTitle("Music Of The Spheres 🌎✨")
+	if got != "music of the spheres" {
+		t.Fatalf("expected music of the spheres, got %q", got)
+	}
+}
+
+func TestTitlesMatch_SeparatorVariants(t *testing.T) {
+	if !titlesMatch("Doctor / Cops", "Doctor _ Cops") {
+		t.Fatal("expected tidal titlesMatch to accept / vs _ variant")
+	}
+}
+
+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")
+	}
+}
@@ -0,0 +1,751 @@
+package gobackend
+
+import (
+	"bufio"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+)
+
+type YouTubeDownloader struct {
+	client *http.Client
+	apiURL string
+	mu     sync.Mutex
+}
+
+const spotubeBaseURL = "https://spotubedl.com"
+
+var (
+	globalYouTubeDownloader *YouTubeDownloader
+	youtubeDownloaderOnce   sync.Once
+)
+
+type YouTubeQuality string
+
+const (
+	YouTubeQualityOpus256 YouTubeQuality = "opus_256"
+	YouTubeQualityOpus128 YouTubeQuality = "opus_128"
+	YouTubeQualityMP3128  YouTubeQuality = "mp3_128"
+	YouTubeQualityMP3256  YouTubeQuality = "mp3_256"
+	YouTubeQualityMP3320  YouTubeQuality = "mp3_320"
+)
+
+var (
+	youtubeOpusSupportedBitrates = []int{128, 256}
+	youtubeMp3SupportedBitrates  = []int{128, 256, 320}
+)
+
+type CobaltRequest struct {
+	URL             string `json:"url"`
+	AudioBitrate    string `json:"audioBitrate,omitempty"`
+	AudioFormat     string `json:"audioFormat,omitempty"`
+	DownloadMode    string `json:"downloadMode,omitempty"`
+	FilenameStyle   string `json:"filenameStyle,omitempty"`
+	DisableMetadata bool   `json:"disableMetadata,omitempty"`
+}
+
+type CobaltResponse struct {
+	Status   string `json:"status"`
+	URL      string `json:"url,omitempty"`
+	Filename string `json:"filename,omitempty"`
+	Error    *struct {
+		Code    string `json:"code"`
+		Context *struct {
+			Service string `json:"service,omitempty"`
+			Limit   int    `json:"limit,omitempty"`
+		} `json:"context,omitempty"`
+	} `json:"error,omitempty"`
+}
+
+type YouTubeDownloadResult struct {
+	FilePath    string
+	Title       string
+	Artist      string
+	Album       string
+	ReleaseDate string
+	TrackNumber int
+	DiscNumber  int
+	ISRC        string
+	Format      string // "opus" or "mp3"
+	Bitrate     int
+	LyricsLRC   string
+	CoverData   []byte
+}
+
+func NewYouTubeDownloader() *YouTubeDownloader {
+	youtubeDownloaderOnce.Do(func() {
+		globalYouTubeDownloader = &YouTubeDownloader{
+			client: NewHTTPClientWithTimeout(120 * time.Second),
+			apiURL: "https://api.qwkuns.me",
+		}
+	})
+	return globalYouTubeDownloader
+}
+
+func extractBitrateFromQuality(raw string, defaultBitrate int) int {
+	parts := strings.FieldsFunc(raw, func(r rune) bool {
+		return (r < '0' || r > '9')
+	})
+	for i := len(parts) - 1; i >= 0; i-- {
+		part := parts[i]
+		if part == "" {
+			continue
+		}
+		if parsed, err := strconv.Atoi(part); err == nil {
+			return parsed
+		}
+	}
+	return defaultBitrate
+}
+
+func nearestSupportedBitrate(value int, supported []int) int {
+	nearest := supported[0]
+	nearestDistance := absInt(value - nearest)
+
+	for _, option := range supported[1:] {
+		distance := absInt(value - option)
+		// On tie prefer higher quality.
+		if distance < nearestDistance || (distance == nearestDistance && option > nearest) {
+			nearest = option
+			nearestDistance = distance
+		}
+	}
+
+	return nearest
+}
+
+func absInt(value int) int {
+	if value < 0 {
+		return -value
+	}
+	return value
+}
+
+func parseYouTubeQualityInput(raw string) (format string, bitrate int, normalized YouTubeQuality) {
+	normalizedRaw := strings.ToLower(strings.TrimSpace(raw))
+
+	if strings.HasPrefix(normalizedRaw, "opus") {
+		parsed := extractBitrateFromQuality(normalizedRaw, 256)
+		finalBitrate := nearestSupportedBitrate(parsed, youtubeOpusSupportedBitrates)
+		return "opus", finalBitrate, YouTubeQuality(fmt.Sprintf("opus_%d", finalBitrate))
+	}
+
+	if strings.HasPrefix(normalizedRaw, "mp3") {
+		parsed := extractBitrateFromQuality(normalizedRaw, 320)
+		finalBitrate := nearestSupportedBitrate(parsed, youtubeMp3SupportedBitrates)
+		return "mp3", finalBitrate, YouTubeQuality(fmt.Sprintf("mp3_%d", finalBitrate))
+	}
+
+	// Backward compatibility for legacy symbolic values.
+	switch normalizedRaw {
+	case "opus_256", "opus256", "opus":
+		return "opus", 256, YouTubeQualityOpus256
+	case "opus_128", "opus128":
+		return "opus", 128, YouTubeQualityOpus128
+	case "mp3_320", "mp3320", "mp3", "":
+		return "mp3", 320, YouTubeQualityMP3320
+	case "mp3_256", "mp3256":
+		return "mp3", 256, YouTubeQualityMP3256
+	case "mp3_128", "mp3128":
+		return "mp3", 128, YouTubeQualityMP3128
+	default:
+		return "mp3", 320, YouTubeQualityMP3320
+	}
+}
+
+func (y *YouTubeDownloader) SearchYouTube(trackName, artistName string) (string, error) {
+	query := fmt.Sprintf("%s %s", artistName, trackName)
+	searchQuery := url.QueryEscape(query)
+
+	GoLog("[YouTube] Search query: %s\n", query)
+
+	youtubeMusicURL := fmt.Sprintf("https://music.youtube.com/search?q=%s", searchQuery)
+
+	return youtubeMusicURL, nil
+}
+
+func (y *YouTubeDownloader) GetDownloadURL(youtubeURL string, quality YouTubeQuality) (*CobaltResponse, error) {
+	y.mu.Lock()
+	defer y.mu.Unlock()
+
+	audioFormat, bitrate, _ := parseYouTubeQualityInput(string(quality))
+	audioBitrate := strconv.Itoa(bitrate)
+
+	// Try SpotubeDL first (primary)
+	var spotubeErr error
+	videoID, extractErr := ExtractYouTubeVideoID(youtubeURL)
+	if extractErr == nil {
+		GoLog("[YouTube] Requesting from SpotubeDL: videoID=%s (format: %s, bitrate: %s)\n",
+			videoID, audioFormat, audioBitrate)
+
+		resp, err := y.requestSpotubeDL(videoID, audioFormat, audioBitrate)
+		if err == nil {
+			return resp, nil
+		}
+		spotubeErr = err
+		GoLog("[YouTube] SpotubeDL failed: %v, trying Cobalt fallback...\n", err)
+	} else {
+		GoLog("[YouTube] Could not extract video ID: %v, skipping SpotubeDL\n", extractErr)
+	}
+
+	// Fallback: direct Cobalt API (api.qwkuns.me)
+	cobaltURL := toYouTubeMusicURL(youtubeURL)
+	GoLog("[YouTube] Requesting from Cobalt API: %s (format: %s, bitrate: %s)\n",
+		cobaltURL, audioFormat, audioBitrate)
+
+	resp, err := y.requestCobaltDirect(cobaltURL, audioFormat, audioBitrate)
+	if err != nil {
+		if spotubeErr != nil {
+			return nil, fmt.Errorf("all download methods failed: spotubedl: %v, cobalt: %v", spotubeErr, err)
+		}
+		return nil, fmt.Errorf("all download methods failed: spotubedl: extractErr=%v, cobalt: %v", extractErr, err)
+	}
+
+	return resp, nil
+}
+
+func (y *YouTubeDownloader) requestCobaltDirect(videoURL, audioFormat, audioBitrate string) (*CobaltResponse, error) {
+	reqBody := CobaltRequest{
+		URL:             videoURL,
+		AudioFormat:     audioFormat,
+		AudioBitrate:    audioBitrate,
+		DownloadMode:    "audio",
+		FilenameStyle:   "basic",
+		DisableMetadata: true,
+	}
+
+	jsonData, err := json.Marshal(reqBody)
+	if err != nil {
+		return nil, fmt.Errorf("failed to marshal request: %w", err)
+	}
+
+	req, err := http.NewRequest("POST", y.apiURL, strings.NewReader(string(jsonData)))
+	if err != nil {
+		return nil, fmt.Errorf("failed to create request: %w", err)
+	}
+
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Accept", "application/json")
+
+	resp, err := DoRequestWithUserAgent(y.client, req)
+	if err != nil {
+		return nil, fmt.Errorf("cobalt API request failed: %w", err)
+	}
+	defer resp.Body.Close()
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("failed to read response: %w", err)
+	}
+
+	GoLog("[YouTube] Cobalt API response status: %d\n", resp.StatusCode)
+
+	if resp.StatusCode != 200 {
+		return nil, fmt.Errorf("cobalt API returned status %d: %s", resp.StatusCode, string(body))
+	}
+
+	var cobaltResp CobaltResponse
+	if err := json.Unmarshal(body, &cobaltResp); err != nil {
+		return nil, fmt.Errorf("failed to parse response: %w", err)
+	}
+
+	if cobaltResp.Status == "error" && cobaltResp.Error != nil {
+		return nil, fmt.Errorf("cobalt error: %s", cobaltResp.Error.Code)
+	}
+
+	if cobaltResp.Status != "tunnel" && cobaltResp.Status != "redirect" {
+		return nil, fmt.Errorf("unexpected cobalt status: %s", cobaltResp.Status)
+	}
+
+	if cobaltResp.URL == "" {
+		return nil, fmt.Errorf("no download URL in response")
+	}
+
+	GoLog("[YouTube] Got download URL from Cobalt (status: %s)\n", cobaltResp.Status)
+	return &cobaltResp, nil
+}
+
+// requestSpotubeDL uses SpotubeDL as a Cobalt proxy (they handle auth to yt-dl.click instances).
+// 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, "v3", "v2")
+	}
+	var lastErr error
+
+	for _, engine := range engines {
+		resp, err := y.requestSpotubeDLEngine(videoID, audioFormat, audioBitrate, engine)
+		if err == nil {
+			return resp, nil
+		}
+		lastErr = err
+		GoLog("[YouTube] SpotubeDL (%s) failed: %v\n", engine, err)
+	}
+
+	if lastErr == nil {
+		lastErr = fmt.Errorf("no SpotubeDL engine available")
+	}
+	return nil, lastErr
+}
+
+func (y *YouTubeDownloader) requestSpotubeDLEngine(videoID, audioFormat, audioBitrate, engine string) (*CobaltResponse, error) {
+	apiURL := fmt.Sprintf("%s/api/download/%s?engine=%s&format=%s&quality=%s",
+		spotubeBaseURL, videoID, url.QueryEscape(engine), url.QueryEscape(audioFormat), url.QueryEscape(audioBitrate))
+
+	GoLog("[YouTube] Requesting from SpotubeDL (%s): %s\n", engine, apiURL)
+
+	req, err := http.NewRequest("GET", apiURL, nil)
+	if err != nil {
+		return nil, fmt.Errorf("failed to create request: %w", err)
+	}
+
+	req.Header.Set("Accept", "application/json")
+
+	resp, err := DoRequestWithUserAgent(y.client, req)
+	if err != nil {
+		return nil, fmt.Errorf("spotubedl request failed: %w", err)
+	}
+	defer resp.Body.Close()
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("failed to read response: %w", err)
+	}
+
+	GoLog("[YouTube] SpotubeDL (%s) response status: %d\n", engine, resp.StatusCode)
+
+	if resp.StatusCode != 200 {
+		return nil, fmt.Errorf("spotubedl(%s) returned status %d: %s", engine, resp.StatusCode, string(body))
+	}
+
+	var result struct {
+		URL      string `json:"url"`
+		Status   string `json:"status"`
+		Error    string `json:"error"`
+		Message  string `json:"message"`
+		Filename string `json:"filename"`
+	}
+	if err := json.Unmarshal(body, &result); err != nil {
+		return nil, fmt.Errorf("failed to parse spotubedl response: %w", err)
+	}
+
+	downloadURL := strings.TrimSpace(result.URL)
+	if downloadURL == "" {
+		if result.Error != "" {
+			return nil, fmt.Errorf("spotubedl(%s) error: %s", engine, result.Error)
+		}
+		if result.Message != "" {
+			return nil, fmt.Errorf("spotubedl(%s) message: %s", engine, result.Message)
+		}
+		return nil, fmt.Errorf("no download URL from spotubedl(%s)", engine)
+	}
+
+	if strings.HasPrefix(downloadURL, "/") {
+		downloadURL = spotubeBaseURL + downloadURL
+	}
+
+	if !strings.HasPrefix(downloadURL, "http://") && !strings.HasPrefix(downloadURL, "https://") {
+		return nil, fmt.Errorf("invalid download URL from spotubedl(%s): %s", engine, downloadURL)
+	}
+
+	filename := strings.TrimSpace(result.Filename)
+	if filename == "" {
+		if parsedURL, parseErr := url.Parse(downloadURL); parseErr == nil {
+			if queryFilename := strings.TrimSpace(parsedURL.Query().Get("filename")); queryFilename != "" {
+				if decodedFilename, decodeErr := url.QueryUnescape(queryFilename); decodeErr == nil {
+					filename = decodedFilename
+				} else {
+					filename = queryFilename
+				}
+			}
+		}
+	}
+
+	GoLog("[YouTube] Got download URL from SpotubeDL (%s)\n", engine)
+	return &CobaltResponse{
+		Status:   "tunnel",
+		URL:      downloadURL,
+		Filename: filename,
+	}, nil
+}
+
+func (y *YouTubeDownloader) 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)
+	}
+
+	resp, err := DoRequestWithUserAgent(y.client, req)
+	if err != nil {
+		if isDownloadCancelled(itemID) {
+			return ErrDownloadCancelled
+		}
+		return fmt.Errorf("download request failed: %w", 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 fmt.Errorf("failed to create output file: %w", err)
+	}
+
+	bufWriter := bufio.NewWriterSize(out, 256*1024)
+
+	var written int64
+	if itemID != "" {
+		progressWriter := NewItemProgressWriter(bufWriter, itemID)
+		written, err = io.Copy(progressWriter, 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("[YouTube] Download completed: %d bytes written\n", written)
+
+	return nil
+}
+
+func BuildYouTubeSearchURL(trackName, artistName string) string {
+	query := fmt.Sprintf("%s %s official audio", artistName, trackName)
+	return fmt.Sprintf("https://music.youtube.com/search?q=%s", url.QueryEscape(query))
+}
+
+func BuildYouTubeWatchURL(videoID string) string {
+	return fmt.Sprintf("https://music.youtube.com/watch?v=%s", videoID)
+}
+
+func isYouTubeVideoID(s string) bool {
+	if len(s) != 11 {
+		return false
+	}
+	for _, c := range s {
+		if !((c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || (c >= '0' && c <= '9') || c == '-' || c == '_') {
+			return false
+		}
+	}
+	return true
+}
+
+func IsYouTubeURL(urlStr string) bool {
+	lower := strings.ToLower(urlStr)
+	return strings.Contains(lower, "youtube.com") ||
+		strings.Contains(lower, "youtu.be") ||
+		strings.Contains(lower, "music.youtube.com")
+}
+
+// toYouTubeMusicURL converts any YouTube URL to music.youtube.com format.
+// YouTube Music URLs bypass the login requirement that affects regular YouTube videos on Cobalt.
+func toYouTubeMusicURL(rawURL string) string {
+	videoID, err := ExtractYouTubeVideoID(rawURL)
+	if err != nil {
+		return rawURL
+	}
+	return fmt.Sprintf("https://music.youtube.com/watch?v=%s", videoID)
+}
+
+func ExtractYouTubeVideoID(urlStr string) (string, error) {
+	if strings.Contains(urlStr, "youtu.be/") {
+		parts := strings.Split(urlStr, "youtu.be/")
+		if len(parts) >= 2 {
+			videoID := strings.Split(parts[1], "?")[0]
+			videoID = strings.Split(videoID, "&")[0]
+			return strings.TrimSpace(videoID), nil
+		}
+	}
+
+	parsed, err := url.Parse(urlStr)
+	if err != nil {
+		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 {
+			return strings.Split(parts[1], "/")[0], nil
+		}
+	}
+
+	// /v/
+	if strings.Contains(parsed.Path, "/v/") {
+		parts := strings.Split(parsed.Path, "/v/")
+		if len(parts) >= 2 {
+			return strings.Split(parts[1], "/")[0], nil
+		}
+	}
+
+	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 > YT Music extension > SongLink (Spotify/Deezer/ISRC)
+	var youtubeURL string
+	var lookupErr error
+
+	// SpotifyID might actually be a YouTube video ID (from YT Music extension)
+	if req.SpotifyID != "" && isYouTubeVideoID(req.SpotifyID) {
+		youtubeURL = BuildYouTubeWatchURL(req.SpotifyID)
+		GoLog("[YouTube] SpotifyID appears to be YouTube video ID, using directly: %s\n", youtubeURL)
+	}
+
+	// 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()
+		youtubeURL, lookupErr = songlink.GetYouTubeURLFromSpotify(req.SpotifyID)
+		if lookupErr != nil {
+			GoLog("[YouTube] SongLink Spotify lookup failed: %v\n", lookupErr)
+		} else {
+			GoLog("[YouTube] Found YouTube URL via SongLink (Spotify): %s\n", youtubeURL)
+		}
+	}
+
+	// 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()
+		youtubeURL, lookupErr = songlink.GetYouTubeURLFromDeezer(req.DeezerID)
+		if lookupErr != nil {
+			GoLog("[YouTube] SongLink Deezer lookup failed: %v\n", lookupErr)
+		} else {
+			GoLog("[YouTube] Found YouTube URL via SongLink (Deezer): %s\n", youtubeURL)
+		}
+	}
+
+	// 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()
+		availability, isrcErr := songlink.CheckTrackAvailability("", req.ISRC)
+		if isrcErr == nil && availability.YouTube && availability.YouTubeURL != "" {
+			youtubeURL = availability.YouTubeURL
+			GoLog("[YouTube] Found YouTube URL via SongLink (ISRC): %s\n", youtubeURL)
+		} else if isrcErr != nil {
+			GoLog("[YouTube] SongLink ISRC lookup failed: %v\n", isrcErr)
+		}
+	}
+
+	// Cobalt requires direct video URLs, not search URLs
+	if youtubeURL == "" {
+		return YouTubeDownloadResult{}, fmt.Errorf("could not find YouTube URL for track: %s - %s (no Spotify/Deezer ID available or track not on YouTube)", req.ArtistName, req.TrackName)
+	}
+
+	GoLog("[YouTube] Requesting download from Cobalt for: %s\n", youtubeURL)
+
+	cobaltResp, err := downloader.GetDownloadURL(youtubeURL, quality)
+	if err != nil {
+		return YouTubeDownloadResult{}, fmt.Errorf("failed to get download URL: %w", err)
+	}
+
+	ext := ".mp3"
+	if format == "opus" {
+		ext = ".opus"
+	}
+
+	// Some SpotubeDL engines may return a different output container than requested.
+	// Respect the provider-reported filename to avoid saving MP3 bytes with .opus extension.
+	if cobaltResp != nil && cobaltResp.Filename != "" {
+		lowerName := strings.ToLower(strings.TrimSpace(cobaltResp.Filename))
+		switch {
+		case strings.HasSuffix(lowerName, ".mp3"):
+			ext = ".mp3"
+			format = "mp3"
+		case strings.HasSuffix(lowerName, ".opus"), strings.HasSuffix(lowerName, ".ogg"):
+			ext = ".opus"
+			format = "opus"
+		}
+	}
+
+	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,
+	})
+	filename = sanitizeFilename(filename) + ext
+
+	var outputPath string
+	isSafOutput := isFDOutput(req.OutputFD) || strings.TrimSpace(req.OutputPath) != ""
+	if isSafOutput {
+		outputPath = strings.TrimSpace(req.OutputPath)
+		if outputPath == "" && isFDOutput(req.OutputFD) {
+			outputPath = fmt.Sprintf("/proc/self/fd/%d", req.OutputFD)
+		}
+	} else {
+		outputPath = req.OutputDir + "/" + filename
+	}
+
+	GoLog("[YouTube] Downloading to: %s\n", outputPath)
+
+	var parallelResult *ParallelDownloadResult
+	if req.EmbedLyrics || req.CoverURL != "" {
+		GoLog("[YouTube] Starting parallel fetch for cover and lyrics...\n")
+		parallelResult = FetchCoverAndLyricsParallel(
+			req.CoverURL,
+			req.EmbedMaxQualityCover,
+			req.SpotifyID,
+			req.TrackName,
+			req.ArtistName,
+			req.EmbedLyrics,
+			int64(req.DurationMS),
+		)
+	}
+
+	if err := downloader.DownloadFile(cobaltResp.URL, outputPath, req.OutputFD, req.ItemID); err != nil {
+		return YouTubeDownloadResult{}, fmt.Errorf("download failed: %w", err)
+	}
+
+	lyricsLRC := ""
+	var coverData []byte
+	if parallelResult != nil {
+		if parallelResult.LyricsLRC != "" {
+			lyricsLRC = parallelResult.LyricsLRC
+			GoLog("[YouTube] Got lyrics from lrclib (%d lines)\n", len(parallelResult.LyricsData.Lines))
+		}
+		if parallelResult.CoverData != nil {
+			coverData = parallelResult.CoverData
+			GoLog("[YouTube] Got cover art (%d bytes)\n", len(coverData))
+		}
+	}
+
+	return YouTubeDownloadResult{
+		FilePath:    outputPath,
+		Title:       req.TrackName,
+		Artist:      req.ArtistName,
+		Album:       req.AlbumName,
+		ReleaseDate: req.ReleaseDate,
+		TrackNumber: req.TrackNumber,
+		DiscNumber:  req.DiscNumber,
+		ISRC:        req.ISRC,
+		Format:      format,
+		Bitrate:     bitrate,
+		LyricsLRC:   lyricsLRC,
+		CoverData:   coverData,
+	}, nil
+}
@@ -0,0 +1,41 @@
+package gobackend
+
+import "testing"
+
+func TestParseYouTubeQualityInput_OpusNormalizesToSupportedBitrates(t *testing.T) {
+	format, bitrate, normalized := parseYouTubeQualityInput("opus_160")
+	if format != "opus" {
+		t.Fatalf("expected opus format, got %s", format)
+	}
+	if bitrate != 128 {
+		t.Fatalf("expected 128 bitrate, got %d", bitrate)
+	}
+	if normalized != YouTubeQualityOpus128 {
+		t.Fatalf("expected %s normalized, got %s", YouTubeQualityOpus128, normalized)
+	}
+}
+
+func TestParseYouTubeQualityInput_Mp3NormalizesToSupportedBitrates(t *testing.T) {
+	format, bitrate, normalized := parseYouTubeQualityInput("mp3_192")
+	if format != "mp3" {
+		t.Fatalf("expected mp3 format, got %s", format)
+	}
+	if bitrate != 256 {
+		t.Fatalf("expected 256 bitrate, got %d", bitrate)
+	}
+	if normalized != YouTubeQualityMP3256 {
+		t.Fatalf("expected %s normalized, got %s", YouTubeQualityMP3256, normalized)
+	}
+}
+
+func TestParseYouTubeQualityInput_PicksNearestSupportedBitrate(t *testing.T) {
+	_, opusBitrate, _ := parseYouTubeQualityInput("opus_999")
+	if opusBitrate != 256 {
+		t.Fatalf("expected opus normalization to 256, got %d", opusBitrate)
+	}
+
+	_, mp3Bitrate, _ := parseYouTubeQualityInput("mp3_1")
+	if mp3Bitrate != 128 {
+		t.Fatalf("expected mp3 normalization to 128, got %d", mp3Bitrate)
+	}
+}
@@ -46,6 +46,11 @@ post_install do |installer|
    flutter_additional_ios_build_settings(target)
    target.build_configurations.each do |config|
      config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '14.0'
+      config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] ||= ['$(inherited)']
+      definitions = config.build_settings['GCC_PREPROCESSOR_DEFINITIONS']
+      unless definitions.include?('PERMISSION_NOTIFICATIONS=1')
+        definitions << 'PERMISSION_NOTIFICATIONS=1'
+      end
    end
  end
 end
@@ -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
@@ -83,18 +168,12 @@ import Gobackend  // Import Go framework
            if let error = error { throw error }
            return response
            
-        case "downloadTrack":
+        case "downloadByStrategy":
            let requestJson = call.arguments as! String
-            let response = GobackendDownloadTrack(requestJson, &error)
+            let response = GobackendDownloadByStrategy(requestJson, &error)
            if let error = error { throw error }
            return response
-            
-        case "downloadWithFallback":
-            let requestJson = call.arguments as! String
-            let response = GobackendDownloadWithFallback(requestJson, &error)
-            if let error = error { throw error }
-            return response
-            
+
        case "getDownloadProgress":
            let response = GobackendGetDownloadProgress()
            return response
@@ -133,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]
@@ -197,6 +283,17 @@ import Gobackend  // Import Go framework
            let response = GobackendGetLyricsLRC(spotifyId, trackName, artistName, filePath, durationMs, &error)
            if let error = error { throw error }
            return response
+
+        case "getLyricsLRCWithSource":
+            let args = call.arguments as! [String: Any]
+            let spotifyId = args["spotify_id"] as! String
+            let trackName = args["track_name"] as! String
+            let artistName = args["artist_name"] as! String
+            let filePath = args["file_path"] as? String ?? ""
+            let durationMs = args["duration_ms"] as? Int64 ?? 0
+            let response = GobackendGetLyricsLRCWithSource(spotifyId, trackName, artistName, filePath, durationMs, &error)
+            if let error = error { throw error }
+            return response
            
        case "embedLyricsToFile":
            let args = call.arguments as! [String: Any]
@@ -209,6 +306,41 @@ import Gobackend  // Import Go framework
        case "cleanupConnections":
            GobackendCleanupConnections()
            return nil
+
+        case "downloadCoverToFile":
+            let args = call.arguments as! [String: Any]
+            let coverURL = args["cover_url"] as! String
+            let outputPath = args["output_path"] as! String
+            let maxQuality = args["max_quality"] as? Bool ?? true
+            GobackendDownloadCoverToFile(coverURL, outputPath, maxQuality, &error)
+            if let error = error { throw error }
+            return "{\"success\":true}"
+
+        case "extractCoverToFile":
+            let args = call.arguments as! [String: Any]
+            let audioPath = args["audio_path"] as! String
+            let outputPath = args["output_path"] as! String
+            GobackendExtractCoverToFile(audioPath, outputPath, &error)
+            if let error = error { throw error }
+            return "{\"success\":true}"
+
+        case "fetchAndSaveLyrics":
+            let args = call.arguments as! [String: Any]
+            let trackName = args["track_name"] as! String
+            let artistName = args["artist_name"] as! String
+            let spotifyId = args["spotify_id"] as! String
+            let durationMs = args["duration_ms"] as? Int64 ?? 0
+            let outputPath = args["output_path"] as! String
+            GobackendFetchAndSaveLyrics(trackName, artistName, spotifyId, durationMs, outputPath, &error)
+            if let error = error { throw error }
+            return "{\"success\":true}"
+
+        case "reEnrichFile":
+            let args = call.arguments as! [String: Any]
+            let requestJson = args["request_json"] as? String ?? "{}"
+            let response = GobackendReEnrichFile(requestJson, &error)
+            if let error = error { throw error }
+            return response
            
        case "readFileMetadata":
            let args = call.arguments as! [String: Any]
@@ -217,6 +349,14 @@ import Gobackend  // Import Go framework
            if let error = error { throw error }
            return response
            
+        case "editFileMetadata":
+            let args = call.arguments as! [String: Any]
+            let filePath = args["file_path"] as! String
+            let metadataJson = args["metadata_json"] as? String ?? "{}"
+            let response = GobackendEditFileMetadata(filePath, metadataJson, &error)
+            if let error = error { throw error }
+            return response
+            
        case "searchDeezerAll":
            let args = call.arguments as! [String: Any]
            let query = args["query"] as! String
@@ -227,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
@@ -315,13 +463,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
@@ -337,17 +478,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()
@@ -471,12 +601,6 @@ import Gobackend  // Import Go framework
            if let error = error { throw error }
            return response
            
-        case "downloadWithExtensions":
-            let requestJson = call.arguments as! String
-            let response = GobackendDownloadWithExtensionsJSON(requestJson, &error)
-            if let error = error { throw error }
-            return response
-            
        case "enrichTrackWithExtension":
            let args = call.arguments as! [String: Any]
            let extensionId = args["extension_id"] as! String
@@ -484,6 +608,12 @@ import Gobackend  // Import Go framework
            let response = GobackendEnrichTrackWithExtensionJSON(extensionId, trackJson, &error)
            if let error = error { throw error }
            return response
+
+        case "downloadWithExtensions":
+            let requestJson = call.arguments as! String
+            let response = GobackendDownloadWithExtensionsJSON(requestJson, &error)
+            if let error = error { throw error }
+            return response
            
        case "removeExtension":
            let args = call.arguments as! [String: Any]
@@ -745,6 +875,65 @@ 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":
+            let args = call.arguments as! [String: Any]
+            let providersJson = args["providers_json"] as? String ?? "[]"
+            GobackendSetLyricsProvidersJSON(providersJson, &error)
+            if let error = error { throw error }
+            return "{\"success\":true}"
+            
+        case "getLyricsProviders":
+            let response = GobackendGetLyricsProvidersJSON(&error)
+            if let error = error { throw error }
+            return response
+            
+        case "getAvailableLyricsProviders":
+            let response = GobackendGetAvailableLyricsProvidersJSON(&error)
+            if let error = error { throw error }
+            return response
+            
+        case "setLyricsFetchOptions":
+            let args = call.arguments as! [String: Any]
+            let optionsJson = args["options_json"] as? String ?? "{}"
+            GobackendSetLyricsFetchOptionsJSON(optionsJson, &error)
+            if let error = error { throw error }
+            return "{\"success\":true}"
+            
+        case "getLyricsFetchOptions":
+            let response = GobackendGetLyricsFetchOptionsJSON(&error)
+            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(
@@ -754,4 +943,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)
+    }
 }
--- a/Show More
+++ b/Show More