feat: add Deezer download service, Qobuz squid.wtf fallback, update changelog

v3.7.1: YT Music extension priority for YouTube downloads, Qobuz store fallback, queue fixes, server-side search filters
fix(queue): unique queue IDs, nullable currentDownload, local cancel tracking; refactor(l10n): consolidate and clean up localization files
2026-07-03 19:27:57 +02:00 · 2026-03-06 21:18:50 +07:00 · 2026-03-06 16:44:53 +07:00 · 2026-03-06 16:44:53 +07:00 · 2026-03-05 17:32:17 +07:00 · 2026-03-05 10:14:36 +00:00
239 changed files with 88605 additions and 41125 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

@@ -15,7 +15,7 @@ jobs:
    
    steps:
      - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
        with:
          fetch-depth: 2  # Need previous commit to compare

@@ -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
@@ -60,23 +60,23 @@ jobs:
          df -h

      - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6

      - name: Setup Java
-        uses: actions/setup-java@v4
+        uses: actions/setup-java@v5
        with:
          distribution: "temurin"
          java-version: "17"

      - name: Setup Go
-        uses: actions/setup-go@v5
+        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
      - name: Cache Gradle
-        uses: actions/cache@v4
+        uses: actions/cache@v5
        with:
          path: |
            ~/.gradle/caches
@@ -158,7 +158,7 @@ jobs:
          ls -la

      - name: Upload APK artifact
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v6
        with:
          name: android-apk
          path: build/app/outputs/flutter-apk/SpotiFLAC-*.apk
@@ -169,17 +169,17 @@ jobs:

    steps:
      - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6

      - name: Setup Go
-        uses: actions/setup-go@v5
+        uses: actions/setup-go@v6
        with:
-          go-version: "1.25"
+          go-version: "1.25.7"
          cache-dependency-path: go_backend/go.sum

      # Cache CocoaPods
      - name: Cache CocoaPods
-        uses: actions/cache@v4
+        uses: actions/cache@v5
        with:
          path: ios/Pods
          key: pods-${{ runner.os }}-${{ hashFiles('ios/Podfile.lock') }}
@@ -295,7 +295,7 @@ jobs:
          fi

      - name: Upload IPA artifact
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v6
        with:
          name: ios-ipa
          path: build/ios/ipa/SpotiFLAC-*.ipa
@@ -308,7 +308,7 @@ jobs:

    steps:
      - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6

      - name: Extract changelog for version
        id: changelog
@@ -338,13 +338,13 @@ jobs:
          cat /tmp/changelog.txt

      - name: Download Android APK
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v7
        with:
          name: android-apk
          path: ./release

      - name: Download iOS IPA
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v7
        with:
          name: ios-ipa
          path: ./release
@@ -385,7 +385,7 @@ jobs:
          cat /tmp/release_body.txt

      - name: Create Release
-        uses: softprops/action-gh-release@v1
+        uses: softprops/action-gh-release@v2
        with:
          tag_name: ${{ needs.get-version.outputs.version }}
          name: SpotiFLAC ${{ needs.get-version.outputs.version }}
@@ -403,16 +403,16 @@ jobs:

    steps:
      - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6

      - name: Download Android APK
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v7
        with:
          name: android-apk
          path: ./release

      - name: Download iOS IPA
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v7
        with:
          name: ios-ipa
          path: ./release
@@ -1,5 +1,766 @@
 # Changelog

+## [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
+
+- Removed PaletteService (palette_generator) from all screens for faster navigation and reduced memory usage
+- Album, Playlist, Downloaded Album, Local Album, and Track Metadata screens now use blurred cover art as header background instead of dominant color extraction
+- Removed `palette_generator` dependency
+- App startup now renders immediately (`runApp`) while service initialization runs asynchronously in eager init
+- Main shell provider subscriptions now use field-level `select(...)` to reduce unnecessary rebuilds
+- Settings persistence now uses single-flight + queued save coalescing to avoid redundant disk writes
+- Progress polling cadence adjusted to 800ms for download queue, local library scan progress, and Go log polling
+- Android foreground download service progress updates are throttled (change-based updates + 5s heartbeat)
+- SAF history repair is now batched (`20` items per batch) and capped per launch (`60`) to reduce startup I/O spikes
+- Incremental library scan now builds final item list in-memory instead of reloading from database
+- Local cover images in queue/library use direct `Image.file` with `errorBuilder` instead of `FutureBuilder` existence check
+- CSV parser `_parseLine` rewritten: correct escaped-quote handling, no quote characters in output
+- Removed unused legacy screen files (`home_screen.dart`, `queue_screen.dart`, `settings_screen.dart`, `settings_tab.dart`)
+- Incremental local library scan now merges delta results in-memory and sorts once, avoiding full-state reload churn
+- Queue local cover rendering now uses direct `Image.file` + `errorBuilder` (removed repeated async file-exists checks)
+
+### Added
+
+- Auto-cleanup orphaned downloads on history load (files that no longer exist are automatically removed from history)
+
+### Changed
+
+- Removed legacy screen files that were no longer used after the tab/part refactor:
+  - `lib/screens/home_screen.dart`
+  - `lib/screens/queue_screen.dart`
+  - `lib/screens/settings_screen.dart`
+  - `lib/screens/settings_tab.dart`
+- Concurrent download limit increased from `3` to `5` (settings clamp + Options UI chips now support `1..5`)
+- Download queue now uses a single parallel scheduler path; `1` concurrency is handled as parallel-with-limit-1 (no separate sequential engine)
+- Download queue now listens to settings updates in real-time so concurrency/output settings stay in sync while queue is active
+
+### Fixed
+
+- CSV parser now correctly handles escaped quotes (`""`) inside quoted fields during import
+- Fixed dynamic concurrency update during active downloads: changing limit (e.g. `1 -> 3`) now schedules additional queued items without waiting current active item to finish
+- Queue scheduler now re-checks capacity/queued items on short intervals to avoid blocking on long-running single active download
+
+### Dependencies
+
+#### Flutter
+- `flutter_local_notifications` 19.x → 20.0.0 (breaking: all positional params converted to named params)
+- `connectivity_plus` 6.x → 7.0.0
+- `flutter_secure_storage` 9.x → 10.0.0
+- Removed `palette_generator` dependency
+
+#### Go
+- `go-flac/go-flac` v1.0.0 → v2.0.4
+- `go-flac/flacvorbis` v0.2.0 → v2.0.2
+- `go-flac/flacpicture` v0.3.0 → v2.0.2
+- Go toolchain 1.24 → 1.25.7
+
+#### Android
+- Android Gradle Plugin 8.x → 9.0.0
+- Kotlin 2.1.x → 2.3.10
+- `desugar_jdk_libs` → 2.1.5
+- `kotlinx-coroutines-android` → 1.10.2
+- `lifecycle-runtime-ktx` → 2.10.0
+- `activity-ktx` → 1.12.3
+
+#### CI/CD
+- `actions/cache` v4 → v5
+- `actions/checkout` v4 → v6
+- `actions/setup-go` v5 → v6
+- `actions/setup-java` v4 → v5
+- `softprops/action-gh-release` v1 → v2
+- GitHub artifact actions updated
+
+---
+
+## [3.5.0] - 2026-02-07
+
+### Highlights
+
+- **SAF Storage (Android 10+)**: Proper Storage Access Framework support for download destination (content URIs)
+  - Select download folder via SAF tree picker
+  - Downloads now write to SAF file descriptors (`/proc/self/fd/*`) instead of raw filesystem paths
+  - Works around Android 10+ scoped storage permission errors
+- **Modern Onboarding Experience**: Completely redesigned Setup and Tutorial screens
+
+### Added
+
+- Home feed disk caching via SharedPreferences for instant restore on app startup
+- SAF display path resolver in native Android layer (converts tree URIs to readable paths)
+- New settings fields for storage mode + SAF tree URI
+- SAF platform bridge methods: pick tree, stat/exists/delete, open content URI, copy to temp, write back to SAF
+- SAF library scan mode (DocumentFile traversal + metadata read)
+- Incremental library scanning for filesystem and SAF paths (only scans new/modified files and detects removed files)
+- Force Full Scan action in Library Settings to rescan all files on demand
+- Downloaded files are now excluded from Local Library scan results to prevent duplicate entries
+- Legacy library rows now support `file_mod_time` backfill before incremental scans (faster follow-up scans after upgrade)
+- Library UI toggle to show SAF-repaired history items
+- Scan cancelled banner + retry action for library scans
+- Android DocumentFile dependency for SAF operations
+- Post-processing API v2 (SAF-aware, ready to replace v1)
+- Donate page in Settings with Ko-fi and Buy Me a Coffee links
+- Per-App Language support on Android 13+ (locale_config.xml)
+- Interactive tutorial with working search bar simulation and clickable download buttons
+- Tutorial completion state is persisted after onboarding
+- Visual feedback animations for page transitions, entrance effects, and feature lists
+- New dedicated welcome step in setup wizard with improved branding
+
+### Changed
+
+- Download pipeline supports `output_path` + `output_ext` for Go backend
+- Tidal/Qobuz/Amazon/Extension downloads use SAF-aware output when enabled
+- Post-processing hooks run for SAF content URIs (via temp file bridge)
+- File operations in Library/Queue/Track screens now SAF-aware (`open`, `exists`, `delete`, `stat`)
+- Local Library scan defaults to incremental mode; full rescan is available via Force Full Scan
+- Local library database upgraded to schema v3 with `file_mod_time` tracking for incremental scan cache
+- Platform channels expanded with incremental scan APIs (`scanLibraryFolderIncremental`) on Android and iOS
+- Android platform channel adds `getSafFileModTimes` for SAF legacy cache backfill
+- Android build tooling upgraded to Gradle 9.3.1 (wrapper)
+- Android build path validated with Java 25 (Gradle/Kotlin/assemble debug)
+- SAF tree picker flow in `MainActivity` migrated to Activity Result API (`registerForActivityResult`)
+- `MainActivity` host migrated to `FlutterFragmentActivity` for SAF picker compatibility
+- Legacy `startActivityForResult` / `onActivityResult` SAF picker path removed
+- Setup screen UI polish: smaller logo, thin outline borders on text fields
+- Removed support section from About page (moved to Donate page)
+- Qobuz squid.wtf region fallback for blocked regions
+- Setup screen converted to PageView flow with animated progress bar and modern card layouts
+- Tutorial screen aligned with Setup Screen design, updated typography and softened UI shapes
+- Larger, more accessible navigation buttons for onboarding flow
+- Reduced visual noise by removing unnecessary glow effects
+
+### Fixed
+
+- Android 10+ `permission denied` when writing to `/storage/emulated/0` (now handled via SAF)
+- SAF history repair: auto-resolve missing content URIs using tree + filename
+- SAF download fallback: retry in app-private storage when SAF write fails
+- Tidal DASH manifest writing when output path is a file descriptor (no invalid `.m4a` path)
+- External LRC output in SAF mode
+- Restored old-device renderer fallback while using `FlutterFragmentActivity` by injecting shell args from a custom `FlutterFragment` (`--enable-impeller=false` on problematic devices)
+- Preserved Flutter fragment creation behavior (cached engine, engine group, new engine) while adding Impeller fallback support
+- SAF tree picker result now consistently returns `tree_uri` payload with persisted URI permission handling
+- SAF share file now copies to temp before sharing (fixes share from SAF content URI)
+- Home feed not updating after installing extension with homeFeed capability (no longer requires app restart)
+- Library scan hero card showing 0 tracks during scan (now shows scanned file count in real-time)
+- Library folder picker no longer requires MANAGE_EXTERNAL_STORAGE on Android 10+ (uses SAF tree picker)
+- One-time SAF migration prompt for users updating from pre-SAF versions
+- Fixed `fileModTime` propagation across Go/Android/Dart so incremental scan cache is stored and reused correctly
+- Fixed SAF incremental scan key mismatch (`lastModified` vs `fileModTime`) and normalized result fields (`skippedCount`, `totalFiles`)
+- Fixed incremental scan progress when all files are skipped (`scanned_files` now reaches total files)
+- Removed duplicate `"removeExtension"` branch in Android method channel handler (eliminates Kotlin duplicate-branch warning)
+
+---
+
+## [3.4.2] - 2026-02-04
+
+### Improved
+
+- **Mobile Network Reliability**: All providers (Qobuz, Tidal, Amazon, Deezer) now have retry logic with exponential backoff
+  - Increased API timeouts: 15s → 25s (Deezer, Qobuz, Tidal), 30s (Amazon)
+  - Up to 3 retry attempts per API call (500ms → 1s → 2s backoff)
+  - Retryable: timeout, connection reset/refused, EOF, HTTP 5xx, HTTP 429
+- **SongLink ID Extraction**: Extract QobuzID/TidalID directly from SongLink URLs
+  - New fields in `TrackAvailability`: `QobuzID`, `TidalID`
+  - Qobuz/Tidal now use direct Track ID from SongLink instead of re-parsing URLs
+- **Qobuz Download Flow**: New Strategy 3 - get QobuzID from SongLink before ISRC search
+  - Cache hit now uses `GetTrackByID()` directly instead of searching again
+  - Pre-warm cache tries SongLink first before direct ISRC search
+- **Tidal Download Flow**: Use `availability.TidalID` directly from SongLink struct
+
+---
+
+## [3.4.1] - 2026-02-04
+
+### Fixed
+
+- Metadata Priority order now persists after app restart
+- Download Provider Priority order now persists after app restart
+
+---
+
+## [3.4.0] - 2026-02-03
+
+### Highlights
+
+- **Local Library Scanning** ([#117](https://github.com/zarzet/SpotiFLAC-Mobile/issues/117)): Scan existing music collection to detect duplicates (FLAC, M4A, MP3, Opus, OGG)
+- **Duplicate Detection** ([#117](https://github.com/zarzet/SpotiFLAC-Mobile/issues/117)): "In Library" badge on tracks matching by ISRC or track name + artist
+- **Unified Library Tab**: History renamed to Library, shows Downloaded + Local Library tracks with source badges
+
+### Added
+
+- Local Album Screen with cover art, disc grouping, and selection mode
+- Albums tab shows local library albums with folder icon badge
+- Singles filter includes local library singles
+- Advanced library filters: Source, Quality, Format, Date
+- Cover art extraction from embedded tags (FLAC, MP3, Opus/Ogg)
+- "Already in Library" notification when downloading existing tracks
+- Spotify secrets now stored in secure storage (`flutter_secure_storage`)
+- **Multi-Service Link Support**: Share links from Deezer, Tidal, and YouTube Music (in addition to Spotify)
+  - Deezer: Full support for track, album, playlist, artist links
+  - Tidal: Track links converted via SongLink to Spotify/Deezer for metadata
+  - YouTube Music: Handled via ytmusic extension URL handler
+- Local library tracks now open metadata screen on tap
+
+### Changed
+
+- Extension HTTP sandbox enforces HTTPS and blocks private IPs
+- Extension file sandbox validates paths with boundary-safe checks
+
+### Fixed
+
+- Search filter bar now only appears after results load, not during loading
+- MP3/Ogg metadata parsing (ID3v2 extended headers, Ogg packet reassembly)
+- Library scan metadata (ISRC, disc number, release date)
+- Cover cache robustness (size + mtime cache key)
+- Local library selection and delete in list/grid views
+- Albums/Singles count includes local library items
+
+---
+
+## [3.3.6] - 2026-02-02
+
+### Added
+
+- **WiFi-Only Download Mode**: Pause downloads on mobile data, auto-resume on WiFi (Settings > Download > Download Network)
+- Added `connectivity_plus: ^6.0.3` dependency
+
+---
+
+## [3.3.5] - 2026-02-01
+
+Same as 3.3.1 but fixes crash issues caused by FFmpeg.
+
+### Added
+
+- **Export Failed Downloads**: Export failed downloads to TXT file for easy lookup on other platforms
+- **Auto-Export Setting**: Option to automatically export failed downloads when queue finishes
+
+### Fixed
+
+- **FFmpeg Crash**: Fixed crash issues during M4A to MP3/Opus conversion
+- **Service Selection Ignored**: Fixed bug where selecting Qobuz/Amazon from service picker was ignored and always used Tidal instead
+- **iOS iCloud Drive Permission Error**: Block iCloud Drive folder selection on iOS (Go backend cannot access iCloud due to sandboxing)
+
+### Changed
+
+- **Amazon Fallback Only**: Amazon Music is now grayed out in service picker and can only be used as fallback provider
+
+---
+
 ## [3.3.1] - 2026-02-01

 ### Added
@@ -9,7 +770,7 @@
 - **Lossy Bitrate Options**: MP3 (320/256/192/128kbps), Opus (128/96/64kbps)
 - **Search Filters**: Filter results by type (Tracks, Artists, Albums, Playlists)
 - **Album/Playlist Search**: Deezer search now includes albums and playlists
- **New Languages**: Turkish (Kaan, BedirhanGltkn), Japanese (Re*Index.(ot_inc))
+- **New Languages**: Turkish (Kaan, BedirhanGltkn), Japanese (Re\*Index.(ot_inc))
 - **Optional All Files Access**: Android 13+ no longer requires full storage access; enable in Settings if needed
 - **Improved VPN Compatibility**: Better HTTP/2 support for users behind VPN or restricted networks

@@ -110,31 +871,26 @@
  - Perfect for players like Samsung Music that prefer external .lrc files
  - LRC files include metadata headers (title, artist, by:SpotiFLAC-Mobile)
  - Works with all download services (Tidal, Qobuz, Amazon)
-
 - **CSV Import Quality Selection**: Choose audio quality when importing CSV playlists
  - Quality picker now appears before adding CSV tracks to download queue
  - Select between FLAC qualities (Lossless, Hi-Res, Hi-Res Max) or MP3
  - Respects "Ask quality before download" setting - uses default quality if disabled
-
  - **Persistent Cover Image Cache**: Album/track cover images now cached to persistent storage instead of temporary directory
  - Cover images no longer disappear when app is closed or device restarts
  - Cache stored in `app_flutter/cover_cache/` directory (not cleared by system)
  - Maximum 1000 images cached for up to 365 days
  - Covers are cached when displayed in History, Home, Album, Artist, or any other screen
  - New `CoverCacheManager` service with `clearCache()` and `getStats()` methods for future cache management
-
 - **Extended Metadata from Deezer Enrichment**: Track downloads now include label, copyright, and genre metadata from Deezer
  - New fields in `ExtTrackMetadata`: `label`, `copyright`, `genre`
  - Metadata fetched during `enrichTrack()` via Deezer album API
  - Embedded as FLAC Vorbis comments: `GENRE`, `ORGANIZATION` (label), `COPYRIGHT`
  - Works for both extension downloads and built-in provider downloads (Tidal, Qobuz, Amazon)
-
 - **Track Metadata Screen Extended Info**: Genre, label, and copyright now displayed in track metadata screen
  - Added `genre`, `label`, `copyright` fields to `DownloadHistoryItem` model
  - Metadata is stored in download history and persists across app restarts
  - New localization strings: `trackGenre`, `trackLabel`, `trackCopyright`
-
- **`utils.randomUserAgent()` for Extensions**: New utility function for extensions to get random browser User-Agent strings
+- `**utils.randomUserAgent()` for Extensions\*\*: New utility function for extensions to get random browser User-Agent strings
  - Returns modern Chrome User-Agent format: `Chrome/{120-145}.0.{6000-7499}.{100-299}` with `Windows NT 10.0`
  - Useful for extensions that need to rotate User-Agents to avoid detection

@@ -143,7 +899,6 @@
 - **Portuguese Language Bug**: Fixed locale parsing for languages with country codes (e.g., pt_PT, es_ES)
  - App now correctly loads Portuguese and Spanish translations
  - Updated Portuguese label to "Português (Brasil)"
-
 - **VM Race Condition Panic**: Fixed `panic during execution: runtime error: index out of range [-2]` crash when switching search providers
  - Root cause: Goja VM was being accessed concurrently by multiple goroutines without synchronization
  - Added `VMMu sync.Mutex` to `LoadedExtension` struct
@@ -152,16 +907,13 @@
    - `EnrichTrack`, `CheckAvailability`, `GetDownloadURL`, `Download`
    - `CustomSearch`, `HandleURL`, `MatchTrack`, `PostProcess`
  - Prevents race conditions when rapidly switching between extension search providers
-
 - **Tidal Release Date Fallback**: Fixed missing release date in FLAC metadata when downloading from Tidal
  - Now uses Tidal API's release date when `req.ReleaseDate` is empty
  - Ensures release date is always embedded in downloaded files
-
 - **Extended Metadata for M4A→FLAC Conversion**: Fixed genre, label, and copyright not being embedded when converting Amazon M4A to FLAC
  - Flutter now extracts extended metadata from Go backend response
  - Passes `genre`, `label`, `copyright` parameters to `_embedMetadataAndCover()`
  - Tags correctly embedded during FFmpeg conversion
-
 - **Extended Metadata for MP3 Conversion**: Genre, label, and copyright now embedded in MP3 files when converting from FLAC
  - Added `genre`, `label`, `copyright` parameters to `_embedMetadataToMp3()`
  - Tags embedded as ID3v2: `GENRE`, `ORGANIZATION` (label), `COPYRIGHT`
@@ -222,7 +974,6 @@
  - `go_backend/httputil.go`: Updated `getRandomUserAgent()` to use modern Chrome versions
  - `go_backend/tidal.go`: Added release date fallback logic
  - `go_backend/exports.go`: Added `Genre`, `Label`, `Copyright` fields to `DownloadResponse`
-
 - **Flutter Changes**:
  - `lib/services/cover_cache_manager.dart`: New persistent cache manager for cover images (365 days, 1000 images max)
  - `lib/widgets/cached_cover_image.dart`: Wrapper widget for CachedNetworkImage with persistent cache
@@ -247,7 +998,6 @@
  - Spanish: Credits 125 ([@credits125](https://crowdin.com/profile/credits125))
  - Portuguese: Pedro Marcondes ([@justapedro](https://crowdin.com/profile/justapedro))
  - Russian: Владислав ([@odinokiy_kot](https://crowdin.com/profile/odinokiy_kot))
-
 - **Quick Search Provider Switcher** ([#76](https://github.com/zarzet/SpotiFLAC-Mobile/issues/76)): Dropdown menu in search bar for instant provider switching
  - Tap the search icon to reveal a dropdown menu with all available search providers
  - Shows default provider (Deezer based on metadata source setting) at the top
@@ -257,56 +1007,46 @@
  - Search hint text updates immediately when switching providers
  - Re-triggers search automatically if there's existing text in the search bar
  - Eliminates need to navigate to Settings > Extensions > Search Provider
-
 - **Extension Button Setting Type** ([#74](https://github.com/zarzet/SpotiFLAC-Mobile/issues/74)): New setting type for extension actions
  - Extensions can define `button` type in manifest settings
  - Triggers JavaScript function when tapped (e.g., start OAuth flow)
  - Useful for authentication, manual sync, or any custom action
-
 - **Genre & Label Metadata** ([#75](https://github.com/zarzet/SpotiFLAC-Mobile/issues/75)): Downloaded tracks now include genre and record label information
  - Fetches genre and label from Deezer album API for each track
  - Embeds GENRE, ORGANIZATION (label), and COPYRIGHT tags into FLAC files
  - Works automatically when Deezer track ID is available (via ISRC matching)
  - Supports all download services (Tidal, Qobuz, Amazon) and extension downloads
-
 - **MP3 Quality Option** ([#69](https://github.com/zarzet/SpotiFLAC-Mobile/issues/69)): Optional MP3 download format with FLAC-to-MP3 conversion
  - New "Enable MP3 Option" toggle in Settings > Download > Audio Quality
  - When enabled, MP3 (320kbps) appears as a quality option alongside FLAC options
  - Available in both the quality picker dialog and default quality settings
  - Works with all services (Tidal, Qobuz, Amazon) and extensions
-
 - **MP3 Metadata Embedding**: Full metadata support for MP3 files
  - Cover art embedded using ID3v2 tags
  - Synced lyrics embedded (fetched from lrclib.net)
  - All metadata preserved: title, artist, album, album artist, track/disc number, date, ISRC
  - Automatic tag conversion from Vorbis comments (FLAC) to ID3v2 (MP3)
-
 - **Dominant Color Header**: Album, Playlist, Downloaded Album, and Track Metadata screens now feature dynamic header backgrounds
  - Extracts dominant color from cover art using `palette_generator`
  - Creates a gradient from dominant color to theme surface color
  - Smooth 500ms color transition animation
-
 - **Larger Cover Art**: Cover images on detail screens are now 50% of screen width (previously 140px fixed)
  - More prominent album artwork display
  - Larger shadow and rounded corners (20px radius)
  - Higher resolution cover caching
-
 - **Sticky Title**: Title appears in AppBar when scrolling past the info card
  - Smooth fade-in animation (200ms) when scrolling down
  - Title hidden when header is expanded (shows in info card instead)
  - AppBar uses theme color (surface) for clean, native look
  - Works on Album, Playlist, Downloaded Album, Track Metadata, and Artist screens
-
 - **Artist Name in Album Screen**: Album info card now displays artist name below album title
  - Extracted from first track's artist metadata
  - Styled with `onSurfaceVariant` color for visual hierarchy
-
 - **Disc Separation for Multi-Disc Albums** ([#70](https://github.com/zarzet/SpotiFLAC-Mobile/issues/70)): Downloaded albums with multiple discs now display tracks grouped by disc
  - Visual disc separator header showing "Disc 1", "Disc 2", etc.
  - Tracks sorted by disc number first, then by track number
  - Single-disc albums display normally without separators
  - Fixes confusion when albums have duplicate track numbers across discs
-
 - **Album Grouping in Recents** ([#70](https://github.com/zarzet/SpotiFLAC-Mobile/issues/70)): Downloads now show as albums instead of individual tracks in the Recent section
  - Prevents flooding the recents list when downloading full albums
  - Groups tracks by album name and artist
@@ -319,7 +1059,6 @@
  - MP3 files now saved in the same folder as FLAC (no separate MP3 subfolder)
  - Original FLAC file automatically deleted after successful conversion
  - New `embedMetadataToMp3()` method for MP3-specific tag embedding
-
 - **Sticky Header Theme Integration**: AppBar background uses `colorScheme.surface` instead of dominant color when collapsed
  - Dark theme: Black background with white text
  - Light theme: White background with black text
@@ -331,12 +1070,10 @@
  - MP3 files now show "320kbps" instead of FLAC's bit depth/sample rate
  - History no longer stores FLAC audio specs for converted MP3 files
  - Both File Info badges and metadata grid show correct MP3 quality
-
 - **Empty Catch Blocks**: Fixed analyzer warnings for empty catch blocks
  - `download_queue_provider.dart`: Added comments explaining why polling errors are silently ignored
  - `track_provider.dart`: Added comments explaining why availability check errors are silently ignored
  - `ffmpeg_service.dart`: Added proper error logging for temp file cleanup failures
-
 - **Russian Plural Forms**: Fixed ICU syntax warnings in Russian localization
  - Removed redundant `=1` clauses that were overriding `one` plural category
  - Affected 10 plural strings including track counts and delete confirmations
@@ -356,24 +1093,20 @@
  - Thread-safe cache with automatic expiration
  - Cache key based on artist, track, and duration
  - Log indicator shows "(cached)" when lyrics are served from cache
-
 - **Lyrics Duration Matching**: Improved lyrics accuracy with duration-based matching
  - Compares track duration with lrclib.net results
  - 10-second tolerance to handle version differences (radio edit, remaster, etc.)
  - Prioritizes synced lyrics over plain text when duration matches
  - Falls back gracefully if no duration match found
-
 - **Deezer Cover Art Upgrade**: Cover art from Deezer CDN now automatically upgraded to maximum quality
  - Detects Deezer CDN URLs (`cdn-images.dzcdn.net`)
  - Upgrades cover resolution to 1800x1800 (max available)
  - Works alongside existing cover upgrade
-
 - **Live Search for Extensions**: Search-as-you-type functionality for extension search
  - 800ms debounce delay to prevent excessive API calls
  - Minimum 3 characters required before searching
  - Concurrency control to prevent race conditions in extension runtime
  - Queues pending searches if a search is already in progress
-
 - **Russian Language Support**: Added Russian (Русский) translation - 99% complete
  - Translated via Crowdin community contributions
  - Covers all UI elements, settings, and error messages
@@ -384,12 +1117,10 @@
  - Added per-directory build lock using `sync.Map` and `sync.Mutex`
  - Double-check locking pattern ensures index is built only once
  - Significantly improves performance during CSV import with many tracks
-
 - **Queue Tab Scroll Exception**: Fixed Flutter rendering exception with NestedScrollView
  - Disabled Material 3 stretch overscroll indicator that caused `_StretchController` assertion
  - Wrapped NestedScrollView with ScrollConfiguration to prevent `setState during build` errors
  - Issue was especially noticeable during rapid queue updates (CSV import)
-
 - **CSV Import**: Fixed CSV export not being parsed correctly
  - Added support for `Artist Name(s)` header (with parentheses)
  - Added support for `Track URI` header for track IDs
@@ -456,4 +1187,4 @@ SpotiFLAC 3.0 introduces a powerful extension system that allows third-party int

 ---

-*For older versions, see [GitHub Releases](https://github.com/zarzet/SpotiFLAC-Mobile/releases)*
+_For older versions, see [GitHub Releases_](https://github.com/zarzet/SpotiFLAC-Mobile/releases)
@@ -1,5 +1,5 @@
 [![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/516142f029a4f3642a899832a6f600acf07040170a98c106cd03222cf584d9a3)
+[![VirusTotal](https://img.shields.io/badge/VirusTotal-Safe-brightgreen?style=for-the-badge&logo=virustotal)](https://www.virustotal.com/gui/file/40f8f1914287dea317122a837f98b0ddf7af3205adc2f84a350d767e0a6a345c)
 [![Crowdin](https://img.shields.io/badge/HELP%20TRANSLATE%20ON-CROWDIN-%2321252b?style=for-the-badge&logo=crowdin)](https://crowdin.com/project/spotiflac-mobile)

 <div align="center">
@@ -24,15 +24,6 @@ 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
-
-SpotiFLAC supports multiple search sources for finding music metadata:
-
-| Source | Setup |
-|--------|-------|
-| **Deezer** (Default) | No setup required |
-| **Extensions** | Install additional search providers from the Store |
-
 ## Extensions

 Extensions allow the community to add new music sources and features without waiting for app updates. When a streaming service API changes or a new source becomes available, extensions can be updated independently.
@@ -54,15 +45,8 @@ Download music in true lossless FLAC from Tidal, Qobuz & Amazon Music for Window

 ## 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>
+[![Telegram Channel](https://img.shields.io/badge/CHANNEL-2CA5E0?style=for-the-badge&logo=telegram&logoColor=white)](https://t.me/spotiflac)
+[![Telegram Community](https://img.shields.io/badge/COMMUNITY-2CA5E0?style=for-the-badge&logo=telegram&logoColor=white)](https://t.me/spotiflac_chat)

 ## FAQ

@@ -87,9 +71,9 @@ 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)


 ## Disclaimer
@@ -108,6 +92,11 @@ You are solely responsible for:
 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.


+## API Credits
+
+[hifi-api](https://github.com/binimum/hifi-api) · [music.binimum.org](https://music.binimum.org) · [qqdl.site](https://qqdl.site) · [squid.wtf](https://squid.wtf) · [spotisaver.net](https://spotisaver.net) · [dabmusic.xyz](https://dabmusic.xyz) · [AfkarXYZ](https://github.com/afkarxyz) · [LRCLib](https://lrclib.net) · [Paxsenix](https://lyrics.paxsenix.org) · [Cobalt](https://cobalt.tools) · [qwkuns.me](https://qwkuns.me) · [SpotubeDL](https://spotubedl.com) · [Song.link](https://song.link) · [IDHS](https://github.com/sjdonado/idonthavespotify)
+
+
 > [!TIP]
 >
 > **Star Us**, You will receive all release notifications from GitHub without any delay ~
@@ -96,11 +96,13 @@ repositories {
 }

 dependencies {
-    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.4")
+    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.5")
    
    // Include all AAR and JAR files from libs folder
    implementation(fileTree(mapOf("dir" to "libs", "include" to listOf("*.jar", "*.aar"))))
    
-    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3")
-    implementation("androidx.lifecycle:lifecycle-runtime-ktx:2.7.0")
+    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.10.2")
+    implementation("androidx.lifecycle:lifecycle-runtime-ktx:2.10.0")
+    implementation("androidx.documentfile:documentfile:1.1.0")
+    implementation("androidx.activity:activity-ktx:1.12.3")
 }
@@ -28,6 +28,9 @@
 # FFmpeg Kit
 -keep class com.arthenica.ffmpegkit.** { *; }
 -keep class com.arthenica.smartexception.** { *; }
+# FFmpeg Kit (new fork package)
+-keep class com.antonkarpenko.ffmpegkit.** { *; }
+-keep class com.antonkarpenko.smartexception.** { *; }

 # Apache Tika (if used by FFmpeg)
 -dontwarn org.apache.tika.**
@@ -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" />
@@ -20,9 +21,10 @@
        android:label="SpotiFLAC"
        android:name="${applicationName}"
        android:icon="@mipmap/ic_launcher"
-        android:requestLegacyExternalStorage="true"
-        android:usesCleartextTraffic="true"
-        android:enableOnBackInvokedCallback="true">
+        android:usesCleartextTraffic="false"
+        android:networkSecurityConfig="@xml/network_security_config"
+        android:enableOnBackInvokedCallback="true"
+        android:localeConfig="@xml/locale_config">

        <activity
            android:name=".MainActivity"
@@ -43,7 +45,7 @@
                <category android:name="android.intent.category.LAUNCHER"/>
            </intent-filter>

-            <!-- Handle Spotify URL sharing -->
+            <!-- Handle music URL sharing (Spotify, Deezer, Tidal, YT Music) -->
            <intent-filter>
                <action android:name="android.intent.action.SEND" />
                <category android:name="android.intent.category.DEFAULT" />
@@ -57,6 +59,33 @@
                <category android:name="android.intent.category.BROWSABLE" />
                <data android:scheme="https" android:host="open.spotify.com" />
            </intent-filter>
+
+            <!-- Handle Deezer deep links -->
+            <intent-filter android:autoVerify="true">
+                <action android:name="android.intent.action.VIEW" />
+                <category android:name="android.intent.category.DEFAULT" />
+                <category android:name="android.intent.category.BROWSABLE" />
+                <data android:scheme="https" android:host="www.deezer.com" />
+                <data android:scheme="https" android:host="deezer.com" />
+                <data android:scheme="https" android:host="deezer.page.link" />
+            </intent-filter>
+
+            <!-- Handle Tidal deep links -->
+            <intent-filter android:autoVerify="true">
+                <action android:name="android.intent.action.VIEW" />
+                <category android:name="android.intent.category.DEFAULT" />
+                <category android:name="android.intent.category.BROWSABLE" />
+                <data android:scheme="https" android:host="tidal.com" />
+                <data android:scheme="https" android:host="listen.tidal.com" />
+            </intent-filter>
+
+            <!-- Handle YouTube Music deep links -->
+            <intent-filter android:autoVerify="true">
+                <action android:name="android.intent.action.VIEW" />
+                <category android:name="android.intent.category.DEFAULT" />
+                <category android:name="android.intent.category.BROWSABLE" />
+                <data android:scheme="https" android:host="music.youtube.com" />
+            </intent-filter>
        </activity>

        <!-- Download Service -->
@@ -65,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,16 @@
+<?xml version="1.0" encoding="utf-8"?>
+<locale-config xmlns:android="http://schemas.android.com/apk/res/android">
+    <locale android:name="en" />
+    <locale android:name="ru" />
+    <locale android:name="es-ES" />
+    <locale android:name="id" />
+    <locale android:name="pt-PT" />
+    <locale android:name="ja" />
+    <locale android:name="tr" />
+    <locale android:name="de" />
+    <locale android:name="fr" />
+    <locale android:name="hi" />
+    <locale android:name="ko" />
+    <locale android:name="nl" />
+    <locale android:name="zh" />
+</locale-config>
@@ -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>
@@ -22,7 +22,7 @@ subprojects {
            }
            
            // Add desugaring dependency to all Android subprojects
-            project.dependencies.add("coreLibraryDesugaring", "com.android.tools:desugar_jdk_libs:2.1.4")
+            project.dependencies.add("coreLibraryDesugaring", "com.android.tools:desugar_jdk_libs:2.1.5")
        }
        
        tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompile>().configureEach {
@@ -1,2 +1,2 @@
-org.gradle.jvmargs=-Xmx8G -XX:MaxMetaspaceSize=4G -XX:ReservedCodeCacheSize=512m -XX:+HeapDumpOnOutOfMemoryError
+org.gradle.jvmargs=-Xmx4G -XX:MaxMetaspaceSize=2G -XX:ReservedCodeCacheSize=256m -XX:+HeapDumpOnOutOfMemoryError
 android.useAndroidX=true
@@ -2,4 +2,4 @@ distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-8.14-all.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-9.3.1-all.zip
@@ -19,8 +19,8 @@ pluginManagement {

 plugins {
    id("dev.flutter.flutter-plugin-loader") version "1.0.0"
-    id("com.android.application") version "8.11.1" apply false
-    id("org.jetbrains.kotlin.android") version "2.3.0" apply false
+    id("com.android.application") version "8.13.2" apply false
+    id("org.jetbrains.kotlin.android") version "2.2.21" apply false
 }

 include(":app")
@@ -17,6 +17,13 @@ import (
 	"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
 }
@@ -24,6 +31,8 @@ type AmazonDownloader struct {
 var (
 	globalAmazonDownloader *AmazonDownloader
 	amazonDownloaderOnce   sync.Once
+	amazonASINRegex        = regexp.MustCompile(`(?i)^B[0-9A-Z]{9}$`)
+	amazonASINFindRegex    = regexp.MustCompile(`(?i)B[0-9A-Z]{9}`)
 )

 // AfkarXYZResponse is the response from AfkarXYZ API
@@ -36,13 +45,10 @@ type AfkarXYZResponse struct {
 	} `json:"data"`
 }

-func amazonIsASCIIString(s string) bool {
-	for _, r := range s {
-		if r > 127 {
-			return false
-		}
-	}
-	return true
+// AmazonStreamResponse is the new response format from amzn.afkarxyz.fun/api/track/{asin}
+type AmazonStreamResponse struct {
+	StreamURL     string `json:"streamUrl"`
+	DecryptionKey string `json:"decryptionKey"`
 }

 func NewAmazonDownloader() *AmazonDownloader {
@@ -54,43 +60,195 @@ func NewAmazonDownloader() *AmazonDownloader {
 	return globalAmazonDownloader
 }

-// downloadFromAfkarXYZ downloads a track using AfkarXYZ API
-// Returns: downloadURL, fileName, error
-func (a *AmazonDownloader) downloadFromAfkarXYZ(amazonURL string) (string, string, error) {
-	// AfkarXYZ API endpoint
-	apiURL := "https://amazon.afkarxyz.fun/convert?url=" + url.QueryEscape(amazonURL)
+// fetchAmazonURLWithRetry fetches from AfkarXYZ API with retry logic for mobile networks.
+// Returns downloadURL, suggested fileName, optional decryptionKey.
+func (a *AmazonDownloader) fetchAmazonURLWithRetry(amazonURL string) (string, string, string, error) {
+	var lastErr error
+	for attempt := 0; attempt <= amazonMaxRetries; attempt++ {
+		if attempt > 0 {
+			delay := amazonRetryDelay * time.Duration(1<<(attempt-1)) // Exponential backoff
+			GoLog("[Amazon] Retry %d/%d after %v...\n", attempt, amazonMaxRetries, delay)
+			time.Sleep(delay)
+		}

-	GoLog("[Amazon] Fetching from AfkarXYZ API...\n")
+		downloadURL, fileName, decryptionKey, err := a.doAfkarXYZRequest(amazonURL)
+		if err == nil {
+			return downloadURL, fileName, decryptionKey, nil
+		}

-	req, err := http.NewRequest("GET", apiURL, nil)
+		lastErr = err
+		errStr := strings.ToLower(err.Error())
+
+		// Check if error is retryable
+		isRetryable := strings.Contains(errStr, "timeout") ||
+			strings.Contains(errStr, "connection reset") ||
+			strings.Contains(errStr, "connection refused") ||
+			strings.Contains(errStr, "eof") ||
+			strings.Contains(errStr, "status 5") ||
+			strings.Contains(errStr, "status 429") ||
+			strings.Contains(errStr, "http 429")
+
+		if !isRetryable {
+			return "", "", "", err
+		}
+
+		GoLog("[Amazon] Attempt %d failed (retryable): %v\n", attempt+1, err)
+	}
+
+	return "", "", "", fmt.Errorf("all %d attempts failed: %w", amazonMaxRetries+1, lastErr)
+}
+
+func normalizeAmazonASIN(candidate string) string {
+	trimmed := strings.TrimSpace(candidate)
+	if trimmed == "" {
+		return ""
+	}
+
+	if decoded, err := url.QueryUnescape(trimmed); err == nil {
+		trimmed = decoded
+	}
+
+	trimmed = strings.ToUpper(trimmed)
+	if idx := strings.IndexAny(trimmed, "?#&/"); idx >= 0 {
+		trimmed = trimmed[:idx]
+	}
+
+	if amazonASINRegex.MatchString(trimmed) {
+		return trimmed
+	}
+
+	return ""
+}
+
+func extractAmazonASIN(amazonURL string) string {
+	raw := strings.TrimSpace(amazonURL)
+	if raw == "" {
+		return ""
+	}
+
+	parsed, err := url.Parse(raw)
+	if err == nil {
+		query := parsed.Query()
+
+		// Prefer track-level ASIN when URL also contains albumAsin.
+		for _, key := range []string{"trackAsin", "trackasin", "trackASIN", "asin", "ASIN", "i"} {
+			if asin := normalizeAmazonASIN(query.Get(key)); asin != "" {
+				return asin
+			}
+		}
+
+		path := strings.Trim(parsed.Path, "/")
+		if path != "" {
+			segments := strings.Split(path, "/")
+
+			for i := 0; i < len(segments)-1; i++ {
+				segment := strings.ToLower(strings.TrimSpace(segments[i]))
+				if segment == "track" || segment == "tracks" {
+					if asin := normalizeAmazonASIN(segments[i+1]); asin != "" {
+						return asin
+					}
+				}
+			}
+
+			if asin := normalizeAmazonASIN(segments[len(segments)-1]); asin != "" {
+				return asin
+			}
+		}
+	}
+
+	match := amazonASINFindRegex.FindString(strings.ToUpper(raw))
+	return normalizeAmazonASIN(match)
+}
+
+// doAfkarXYZRequest performs a single request to Amazon API.
+// It tries new endpoint first, then falls back to legacy /convert endpoint.
+func (a *AmazonDownloader) doAfkarXYZRequest(amazonURL string) (string, string, string, error) {
+	asin := extractAmazonASIN(amazonURL)
+	if asin != "" {
+		GoLog("[Amazon] Using ASIN: %s\n", asin)
+		downloadURL, fileName, decryptKey, err := a.doAfkarXYZRequestNew(asin)
+		if err == nil {
+			return downloadURL, fileName, decryptKey, nil
+		}
+		GoLog("[Amazon] New API failed for ASIN %s, trying legacy endpoint: %v\n", asin, err)
+	}
+	return a.doAfkarXYZRequestLegacy(amazonURL)
+}
+
+func (a *AmazonDownloader) doAfkarXYZRequestNew(asin string) (string, string, string, error) {
+	ctx, cancel := context.WithTimeout(context.Background(), amazonAPITimeoutMobile)
+	defer cancel()
+
+	apiURL := fmt.Sprintf("https://amzn.afkarxyz.fun/api/track/%s", asin)
+	req, err := http.NewRequestWithContext(ctx, "GET", apiURL, nil)
 	if err != nil {
-		return "", "", fmt.Errorf("failed to create request: %w", err)
+		return "", "", "", fmt.Errorf("failed to create request: %w", err)
+	}
+
+	req.Header.Set("User-Agent", "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/144.0.0.0 Safari/537.36")
+
+	resp, err := a.client.Do(req)
+	if err != nil {
+		return "", "", "", fmt.Errorf("failed to call Amazon API: %w", err)
+	}
+	defer resp.Body.Close()
+
+	body, readErr := io.ReadAll(resp.Body)
+	if readErr != nil {
+		return "", "", "", fmt.Errorf("failed to read response: %w", readErr)
+	}
+
+	if resp.StatusCode != 200 {
+		return "", "", "", fmt.Errorf("Amazon API returned status %d", resp.StatusCode)
+	}
+
+	var apiResp AmazonStreamResponse
+	if err := json.Unmarshal(body, &apiResp); err != nil {
+		return "", "", "", fmt.Errorf("failed to decode response: %w", err)
+	}
+
+	if strings.TrimSpace(apiResp.StreamURL) == "" {
+		return "", "", "", fmt.Errorf("Amazon API returned empty stream URL")
+	}
+
+	fileName := asin + ".m4a"
+	return apiResp.StreamURL, fileName, strings.TrimSpace(apiResp.DecryptionKey), nil
+}
+
+func (a *AmazonDownloader) doAfkarXYZRequestLegacy(amazonURL string) (string, string, string, error) {
+	ctx, cancel := context.WithTimeout(context.Background(), amazonAPITimeoutMobile)
+	defer cancel()
+
+	apiURL := "https://amzn.afkarxyz.fun/convert?url=" + url.QueryEscape(amazonURL)
+	req, err := http.NewRequestWithContext(ctx, "GET", apiURL, nil)
+	if err != nil {
+		return "", "", "", fmt.Errorf("failed to create legacy request: %w", err)
 	}

 	req.Header.Set("User-Agent", getRandomUserAgent())

 	resp, err := a.client.Do(req)
 	if err != nil {
-		return "", "", fmt.Errorf("failed to call AfkarXYZ API: %w", err)
+		return "", "", "", fmt.Errorf("failed to call legacy AfkarXYZ API: %w", err)
 	}
 	defer resp.Body.Close()

 	if resp.StatusCode != 200 {
-		return "", "", fmt.Errorf("AfkarXYZ API returned status %d", resp.StatusCode)
+		return "", "", "", fmt.Errorf("legacy AfkarXYZ API returned status %d", resp.StatusCode)
 	}

 	body, err := io.ReadAll(resp.Body)
 	if err != nil {
-		return "", "", fmt.Errorf("failed to read response: %w", err)
+		return "", "", "", fmt.Errorf("failed to read legacy response: %w", err)
 	}

 	var apiResp AfkarXYZResponse
 	if err := json.Unmarshal(body, &apiResp); err != nil {
-		return "", "", fmt.Errorf("failed to decode response: %w", err)
+		return "", "", "", fmt.Errorf("failed to decode legacy response: %w", err)
 	}

-	if !apiResp.Success || apiResp.Data.DirectLink == "" {
-		return "", "", fmt.Errorf("AfkarXYZ API failed or no download link found")
+	if !apiResp.Success || strings.TrimSpace(apiResp.Data.DirectLink) == "" {
+		return "", "", "", fmt.Errorf("legacy AfkarXYZ API failed or no download link found")
 	}

 	fileName := apiResp.Data.FileName
@@ -98,19 +256,30 @@ func (a *AmazonDownloader) downloadFromAfkarXYZ(amazonURL string) (string, strin
 		fileName = "track.flac"
 	}

-	// Sanitize filename
 	reg := regexp.MustCompile(`[<>:"/\\|?*]`)
 	fileName = reg.ReplaceAllString(fileName, "")

-	GoLog("[Amazon] AfkarXYZ returned: %s (%.2f MB)\n", fileName, float64(apiResp.Data.FileSize)/(1024*1024))
-
-	return apiResp.Data.DirectLink, fileName, nil
+	return apiResp.Data.DirectLink, fileName, "", nil
 }

-func (a *AmazonDownloader) DownloadFile(downloadURL, outputPath, itemID string) error {
+func (a *AmazonDownloader) downloadFromAfkarXYZ(amazonURL string) (string, string, string, error) {
+	GoLog("[Amazon] Fetching from AfkarXYZ API...\n")
+
+	downloadURL, fileName, decryptionKey, err := a.fetchAmazonURLWithRetry(amazonURL)
+	if err != nil {
+		return "", "", "", err
+	}
+
+	if decryptionKey != "" {
+		GoLog("[Amazon] AfkarXYZ returned encrypted stream (decryption key available)\n")
+	}
+	GoLog("[Amazon] AfkarXYZ returned: %s\n", fileName)
+	return downloadURL, fileName, decryptionKey, nil
+}
+
+func (a *AmazonDownloader) DownloadFile(downloadURL, outputPath string, outputFD int, itemID string) error {
 	ctx := context.Background()

-	// Initialize item progress (required for all downloads)
 	if itemID != "" {
 		StartItemProgress(itemID)
 		defer CompleteItemProgress(itemID)
@@ -147,7 +316,7 @@ func (a *AmazonDownloader) DownloadFile(downloadURL, outputPath, itemID string)
 		SetItemBytesTotal(itemID, expectedSize)
 	}

-	out, err := os.Create(outputPath)
+	out, err := openOutputForWrite(outputPath, outputFD)
 	if err != nil {
 		return err
 	}
@@ -162,29 +331,27 @@ func (a *AmazonDownloader) DownloadFile(downloadURL, outputPath, itemID string)
 		written, err = io.Copy(bufWriter, resp.Body)
 	}

-	// Flush buffer before checking for errors
 	flushErr := bufWriter.Flush()
 	closeErr := out.Close()

 	if err != nil {
-		os.Remove(outputPath)
+		cleanupOutputOnError(outputPath, outputFD)
 		if isDownloadCancelled(itemID) {
 			return ErrDownloadCancelled
 		}
 		return fmt.Errorf("download interrupted: %w", err)
 	}
 	if flushErr != nil {
-		os.Remove(outputPath)
+		cleanupOutputOnError(outputPath, outputFD)
 		return fmt.Errorf("failed to flush buffer: %w", flushErr)
 	}
 	if closeErr != nil {
-		os.Remove(outputPath)
+		cleanupOutputOnError(outputPath, outputFD)
 		return fmt.Errorf("failed to close file: %w", closeErr)
 	}

-	// Verify file size if Content-Length was provided
 	if expectedSize > 0 && written != expectedSize {
-		os.Remove(outputPath)
+		cleanupOutputOnError(outputPath, outputFD)
 		return fmt.Errorf("incomplete download: expected %d bytes, got %d bytes", expectedSize, written)
 	}

@@ -194,55 +361,94 @@ func (a *AmazonDownloader) DownloadFile(downloadURL, outputPath, itemID string)

 // 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
+	FilePath      string
+	BitDepth      int
+	SampleRate    int
+	Title         string
+	Artist        string
+	Album         string
+	ReleaseDate   string
+	TrackNumber   int
+	DiscNumber    int
+	ISRC          string
+	LyricsLRC     string
+	DecryptionKey string
 }

-// downloadFromAmazon uses AfkarXYZ API to download from Amazon Music
-func downloadFromAmazon(req DownloadRequest) (AmazonDownloadResult, error) {
-	downloader := NewAmazonDownloader()
+func resolveAmazonURLForRequest(req DownloadRequest, logPrefix string) (string, error) {
+	if strings.TrimSpace(logPrefix) == "" {
+		logPrefix = "Amazon"
+	}

-	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("[%s] Cache hit! Using cached Amazon URL for ISRC %s\n", logPrefix, req.ISRC)
+		}
+	}
+
+	if amazonURL != "" {
+		return amazonURL, nil
 	}

 	songlink := NewSongLinkClient()
 	var availability *TrackAvailability
 	var err error

-	if deezerID, found := strings.CutPrefix(req.SpotifyID, "deezer:"); found {
-		GoLog("[Amazon] Using Deezer ID for SongLink lookup: %s\n", deezerID)
+	deezerID := strings.TrimSpace(req.DeezerID)
+	if prefixedDeezerID, found := strings.CutPrefix(req.SpotifyID, "deezer:"); found && strings.TrimSpace(prefixedDeezerID) != "" {
+		deezerID = strings.TrimSpace(prefixedDeezerID)
+	}
+
+	if deezerID != "" {
+		GoLog("[%s] Using Deezer ID for SongLink lookup: %s\n", logPrefix, 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")
+		return "", 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)
+		return "", 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)")
+	if availability == nil || !availability.Amazon || availability.AmazonURL == "" {
+		return "", fmt.Errorf("track not available on Amazon Music (SongLink returned no Amazon URL)")
 	}

-	if req.OutputDir != "." {
+	amazonURL = availability.AmazonURL
+	if req.ISRC != "" {
+		GetTrackIDCache().SetAmazonURL(req.ISRC, amazonURL)
+	}
+
+	return amazonURL, nil
+}
+
+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, err := resolveAmazonURLForRequest(req, "Amazon")
+	if err != nil {
+		return AmazonDownloadResult{}, err
+	}
+
+	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(availability.AmazonURL)
+	downloadURL, afkarFileName, decryptionKey, err := downloader.downloadFromAfkarXYZ(amazonURL)
 	if err != nil {
 		return AmazonDownloadResult{}, fmt.Errorf("failed to get download URL from AfkarXYZ: %w", err)
 	}
@@ -255,13 +461,25 @@ func downloadFromAmazon(req DownloadRequest) (AmazonDownloadResult, error) {
 		"album":  req.AlbumName,
 		"track":  req.TrackNumber,
 		"year":   extractYear(req.ReleaseDate),
+		"date":   req.ReleaseDate,
 		"disc":   req.DiscNumber,
 	})
-	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
+	var outputPath string
+	if isSafOutput {
+		outputPath = strings.TrimSpace(req.OutputPath)
+		if outputPath == "" && isFDOutput(req.OutputFD) {
+			outputPath = fmt.Sprintf("/proc/self/fd/%d", req.OutputFD)
+		}
+	} else {
+		outputExt := strings.ToLower(filepath.Ext(afkarFileName))
+		if outputExt == "" {
+			outputExt = ".flac"
+		}
+		filename = sanitizeFilename(filename) + outputExt
+		outputPath = filepath.Join(req.OutputDir, filename)
+		if fileInfo, statErr := os.Stat(outputPath); statErr == nil && fileInfo.Size() > 0 {
+			return AmazonDownloadResult{FilePath: "EXISTS:" + outputPath}, nil
+		}
 	}

 	// START PARALLEL: Fetch cover and lyrics while downloading audio
@@ -269,25 +487,37 @@ func downloadFromAmazon(req DownloadRequest) (AmazonDownloadResult, 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),
 		)
 	}()

 	// Download audio file with item ID for progress tracking
-	if err := downloader.DownloadFile(downloadURL, outputPath, req.ItemID); err != nil {
+	if err := downloader.DownloadFile(downloadURL, outputPath, req.OutputFD, req.ItemID); err != nil {
 		if errors.Is(err, ErrDownloadCancelled) {
 			return AmazonDownloadResult{}, ErrDownloadCancelled
 		}
 		return AmazonDownloadResult{}, fmt.Errorf("download failed: %w", err)
 	}

+	actualOutputPath := outputPath
+	needsDecryption := strings.TrimSpace(decryptionKey) != ""
+	if needsDecryption {
+		GoLog("[Amazon] Download requires decryption; deferring decrypt to Flutter FFmpeg path\n")
+	}
+
 	// Wait for parallel operations to complete
 	<-parallelDone

@@ -296,28 +526,43 @@ func downloadFromAmazon(req DownloadRequest) (AmazonDownloadResult, error) {
 		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 !needsDecryption {
+		existingMeta, metaErr := ReadMetadata(actualOutputPath)
+		if metaErr == nil && existingMeta != nil {
+			if existingMeta.TrackNumber > 0 && (req.TrackNumber == 0 || req.TrackNumber == 1) {
+				actualTrackNum = existingMeta.TrackNumber
+				GoLog("[Amazon] Using track number from file: %d (request had: %d)\n", actualTrackNum, req.TrackNumber)
+			}
+			if existingMeta.DiscNumber > 0 && (req.DiscNumber == 0 || req.DiscNumber == 1) {
+				actualDiscNum = existingMeta.DiscNumber
+				GoLog("[Amazon] Using disc number from file: %d (request had: %d)\n", actualDiscNum, req.DiscNumber)
+			}
+			if existingMeta.Date != "" && req.ReleaseDate == "" {
+				actualDate = existingMeta.Date
+				GoLog("[Amazon] Using release date from file: %s\n", actualDate)
+			}
+			if existingMeta.Album != "" && req.AlbumName == "" {
+				actualAlbum = existingMeta.Album
+				GoLog("[Amazon] Using album from file: %s\n", actualAlbum)
+			}
+			GoLog("[Amazon] Existing metadata - Title: %s, Artist: %s, Album: %s, Date: %s\n",
+				existingMeta.Title, existingMeta.Artist, existingMeta.Album, existingMeta.Date)
 		}
 	}

-	// Embed metadata using Spotify data
 	metadata := Metadata{
-		Title:       req.TrackName,
-		Artist:      req.ArtistName,
-		Album:       req.AlbumName,
+		Title:       actualTitle,
+		Artist:      actualArtist,
+		Album:       actualAlbum,
 		AlbumArtist: req.AlbumArtist,
-		Date:        req.ReleaseDate,
+		Date:        actualDate,
 		TrackNumber: actualTrackNum,
 		TotalTracks: req.TotalTracks,
 		DiscNumber:  actualDiscNum,
@@ -327,66 +572,96 @@ func downloadFromAmazon(req DownloadRequest) (AmazonDownloadResult, error) {
 		Copyright:   req.Copyright,
 	}

-	// Use cover data from parallel fetch
 	var coverData []byte
-	if parallelResult != nil && parallelResult.CoverData != nil {
+	if parallelResult != nil && parallelResult.CoverData != nil && len(parallelResult.CoverData) > 0 {
 		coverData = parallelResult.CoverData
 		GoLog("[Amazon] Using parallel-fetched cover (%d bytes)\n", len(coverData))
+	} else {
+		existingCover, coverErr := ExtractCoverArt(actualOutputPath)
+		if coverErr == nil && len(existingCover) > 0 {
+			coverData = existingCover
+			GoLog("[Amazon] Using existing cover from Amazon file (%d bytes)\n", len(coverData))
+		} else {
+			GoLog("[Amazon] No cover available (parallel fetch failed and no existing cover)\n")
+		}
 	}

-	if 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" // default
+	if isSafOutput || needsDecryption || !req.EmbedMetadata {
+		if !req.EmbedMetadata {
+			GoLog("[Amazon] Metadata embedding disabled by settings, skipping in-backend metadata/lyrics embedding\n")
+		} else {
+			GoLog("[Amazon] SAF output detected - skipping in-backend metadata/lyrics embedding (handled in Flutter)\n")
 		}
-
-		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)
+	} else {
+		isFlacOutput := strings.HasSuffix(strings.ToLower(actualOutputPath), ".flac")
+		if isFlacOutput {
+			if err := EmbedMetadataWithCoverData(actualOutputPath, metadata, coverData); err != nil {
+				GoLog("[Amazon] Warning: failed to embed metadata: %v\n", err)
 			}
+		} else {
+			GoLog("[Amazon] Non-FLAC output detected (%s), skipping native metadata embedding\n", filepath.Ext(actualOutputPath))
 		}

-		if 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")
+		if req.EmbedLyrics && parallelResult != nil && parallelResult.LyricsLRC != "" {
+			lyricsMode := req.LyricsMode
+			if lyricsMode == "" {
+				lyricsMode = "embed"
 			}
+
+			if lyricsMode == "external" || lyricsMode == "both" {
+				GoLog("[Amazon] Saving external LRC file...\n")
+				if lrcPath, lrcErr := SaveLRCFile(actualOutputPath, parallelResult.LyricsLRC); lrcErr != nil {
+					GoLog("[Amazon] Warning: failed to save LRC file: %v\n", lrcErr)
+				} else {
+					GoLog("[Amazon] LRC file saved: %s\n", lrcPath)
+				}
+			}
+
+			if (lyricsMode == "embed" || lyricsMode == "both") && isFlacOutput {
+				GoLog("[Amazon] Embedding parallel-fetched lyrics (%d lines)...\n", len(parallelResult.LyricsData.Lines))
+				if embedErr := EmbedLyrics(actualOutputPath, parallelResult.LyricsLRC); embedErr != nil {
+					GoLog("[Amazon] Warning: failed to embed lyrics: %v\n", embedErr)
+				} else {
+					GoLog("[Amazon] Lyrics embedded successfully\n")
+				}
+			} else if (lyricsMode == "embed" || lyricsMode == "both") && !isFlacOutput {
+				GoLog("[Amazon] Skipping embedded lyrics for non-FLAC output\n")
+			}
+		} else if req.EmbedLyrics {
+			GoLog("[Amazon] No lyrics available from parallel fetch\n")
 		}
-	} else if req.EmbedLyrics {
-		GoLog("[Amazon] No lyrics available from parallel fetch\n")
 	}

 	GoLog("[Amazon] Downloaded successfully from Amazon Music\n")

-	quality, err := GetAudioQuality(outputPath)
-	if err != nil {
-		GoLog("[Amazon] Warning: couldn't read quality from file: %v\n", err)
+	quality := AudioQuality{}
+	if isSafOutput || needsDecryption {
+		GoLog("[Amazon] SAF output detected - skipping post-write file inspection in backend\n")
 	} else {
-		GoLog("[Amazon] Actual quality: %d-bit/%dHz\n", quality.BitDepth, quality.SampleRate)
-	}
+		quality, err = GetAudioQuality(actualOutputPath)
+		if err != nil {
+			GoLog("[Amazon] Warning: couldn't read quality from file: %v\n", err)
+		} else {
+			GoLog("[Amazon] Actual quality: %d-bit/%dHz\n", quality.BitDepth, quality.SampleRate)
+		}

-	finalMeta, metaReadErr := ReadMetadata(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
+		finalMeta, metaReadErr := ReadMetadata(actualOutputPath)
+		if metaReadErr == nil && finalMeta != nil {
+			GoLog("[Amazon] Final metadata from file - Track: %d, Disc: %d, Date: %s\n",
+				finalMeta.TrackNumber, finalMeta.DiscNumber, finalMeta.Date)
+			actualTrackNum = finalMeta.TrackNumber
+			actualDiscNum = finalMeta.DiscNumber
+			if finalMeta.Date != "" {
+				req.ReleaseDate = finalMeta.Date
+			}
 		}
 	}

-	// Add to ISRC index for fast duplicate checking
-	AddToISRCIndex(req.OutputDir, req.ISRC, outputPath)
+	// Add to ISRC index for fast duplicate checking.
+	// When decryption is pending in Flutter, postpone indexing until final file is settled.
+	if !isSafOutput && !needsDecryption {
+		AddToISRCIndex(req.OutputDir, req.ISRC, actualOutputPath)
+	}

 	bitDepth := 0
 	sampleRate := 0
@@ -395,16 +670,23 @@ func downloadFromAmazon(req DownloadRequest) (AmazonDownloadResult, error) {
 		sampleRate = quality.SampleRate
 	}

+	lyricsLRC := ""
+	if req.EmbedMetadata && 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,
+		FilePath:      outputPath,
+		BitDepth:      bitDepth,
+		SampleRate:    sampleRate,
+		Title:         req.TrackName,
+		Artist:        req.ArtistName,
+		Album:         req.AlbumName,
+		ReleaseDate:   req.ReleaseDate,
+		TrackNumber:   actualTrackNum,
+		DiscNumber:    actualDiscNum,
+		ISRC:          req.ISRC,
+		LyricsLRC:     lyricsLRC,
+		DecryptionKey: decryptionKey,
 	}, nil
 }
@@ -0,0 +1,46 @@
+package gobackend
+
+import "testing"
+
+func TestExtractAmazonASIN(t *testing.T) {
+	tests := []struct {
+		name string
+		url  string
+		want string
+	}{
+		{
+			name: "prefers trackAsin over albumAsin",
+			url:  "https://music.amazon.com/albums/B0ALBUM123?trackAsin=B0TRACK456&musicTerritory=US",
+			want: "B0TRACK456",
+		},
+		{
+			name: "extract from tracks path",
+			url:  "https://music.amazon.com/tracks/B0CYQHGWZJ?musicTerritory=US",
+			want: "B0CYQHGWZJ",
+		},
+		{
+			name: "extract from plain query asin",
+			url:  "https://example.com/?asin=B0CYQHGWZJ",
+			want: "B0CYQHGWZJ",
+		},
+		{
+			name: "fallback regex",
+			url:  "https://example.com/path/B0CYQHGWZJ",
+			want: "B0CYQHGWZJ",
+		},
+		{
+			name: "invalid url",
+			url:  "https://music.amazon.com/tracks/not-valid",
+			want: "",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := extractAmazonASIN(tt.url)
+			if got != tt.want {
+				t.Fatalf("extractAmazonASIN() = %q, want %q", got, tt.want)
+			}
+		})
+	}
+}
@@ -13,25 +13,39 @@ 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

 	deezerMaxParallelISRC = 10
+
+	// Deezer API timeout and retry configuration for mobile networks
+	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 (
@@ -42,20 +56,115 @@ var (
 func GetDeezerClient() *DeezerClient {
 	deezerClientOnce.Do(func() {
 		deezerClient = &DeezerClient{
-			httpClient:  NewHTTPClientWithTimeout(15 * time.Second),
-			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"`
-	Duration      int               `json:"duration"` // in seconds
+	Duration      int               `json:"duration"`
 	TrackPosition int               `json:"track_position"`
 	DiskNumber    int               `json:"disk_number"`
 	ISRC          string            `json:"isrc"`
@@ -121,11 +230,13 @@ func (c *DeezerClient) convertTrack(track deezerTrack) TrackMetadata {
 		AlbumArtist: track.Artist.Name,
 		DurationMS:  track.Duration * 1000,
 		Images:      albumImage,
-		ReleaseDate: releaseDate, // Added this
+		ReleaseDate: releaseDate,
 		TrackNumber: track.TrackPosition,
 		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),
 	}
 }

@@ -182,15 +293,12 @@ type deezerPlaylistFull struct {
 	} `json:"tracks"`
 }

-// NOTE: ISRC is NOT fetched during search for performance - use GetTrackISRC when needed for download
-// filter can be: "" (all), "track", "artist", "album", "playlist"
 func (c *DeezerClient) SearchAll(ctx context.Context, query string, trackLimit, artistLimit int, filter string) (*SearchAllResult, error) {
 	GoLog("[Deezer] SearchAll: query=%q, trackLimit=%d, artistLimit=%d, filter=%q\n", query, trackLimit, artistLimit, filter)

-	albumLimit := 5 // Same as artistLimit for consistency
+	albumLimit := 5
 	playlistLimit := 5

-	// When filter is specified, increase limits for that type only
 	if filter != "" {
 		switch filter {
 		case "track":
@@ -233,7 +341,6 @@ func (c *DeezerClient) SearchAll(ctx context.Context, query string, trackLimit,
 		Playlists: make([]SearchPlaylistResult, 0, playlistLimit),
 	}

-	// Search tracks - NO ISRC fetch for performance
 	if trackLimit > 0 {
 		trackURL := fmt.Sprintf("%s/track?q=%s&limit=%d", deezerSearchURL, url.QueryEscape(query), trackLimit)
 		GoLog("[Deezer] Fetching tracks from: %s\n", trackURL)
@@ -263,7 +370,6 @@ func (c *DeezerClient) SearchAll(ctx context.Context, query string, trackLimit,
 		}
 	}

-	// Search artists
 	if artistLimit > 0 {
 		artistURL := fmt.Sprintf("%s/artist?q=%s&limit=%d", deezerSearchURL, url.QueryEscape(query), artistLimit)
 		GoLog("[Deezer] Fetching artists from: %s\n", artistURL)
@@ -296,7 +402,6 @@ func (c *DeezerClient) SearchAll(ctx context.Context, query string, trackLimit,
 		}
 	}

-	// Search albums
 	if albumLimit > 0 {
 		albumURL := fmt.Sprintf("%s/album?q=%s&limit=%d", deezerSearchURL, url.QueryEscape(query), albumLimit)
 		GoLog("[Deezer] Fetching albums from: %s\n", albumURL)
@@ -358,7 +463,6 @@ func (c *DeezerClient) SearchAll(ctx context.Context, query string, trackLimit,
 		}
 	}

-	// Search playlists
 	if playlistLimit > 0 {
 		playlistURL := fmt.Sprintf("%s/playlist?q=%s&limit=%d", deezerSearchURL, url.QueryEscape(query), playlistLimit)
 		GoLog("[Deezer] Fetching playlists from: %s\n", playlistURL)
@@ -416,16 +520,17 @@ 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
 }

-// GetTrack fetches a single track by Deezer ID
 func (c *DeezerClient) GetTrack(ctx context.Context, trackID string) (*TrackResponse, error) {
 	trackURL := fmt.Sprintf(deezerTrackURL, trackID)

@@ -439,7 +544,6 @@ func (c *DeezerClient) GetTrack(ctx context.Context, trackID string) (*TrackResp
 	}, nil
 }

-// ISRC is fetched in parallel for better performance
 func (c *DeezerClient) GetAlbum(ctx context.Context, albumID string) (*AlbumResponsePayload, error) {
 	c.cacheMu.RLock()
 	if entry, ok := c.albumCache[albumID]; ok && !entry.isExpired() {
@@ -465,7 +569,6 @@ func (c *DeezerClient) GetAlbum(ctx context.Context, albumID string) (*AlbumResp
 		artistName = strings.Join(names, ", ")
 	}

-	// Extract genres as comma-separated string
 	var genres []string
 	for _, g := range album.Genres.Data {
 		if g.Name != "" {
@@ -481,14 +584,12 @@ func (c *DeezerClient) GetAlbum(ctx context.Context, albumID string) (*AlbumResp
 		Artists:     artistName,
 		ArtistId:    fmt.Sprintf("deezer:%d", album.Artist.ID),
 		Images:      albumImage,
-		Genre:       genreStr,    // From Deezer album
-		Label:       album.Label, // From Deezer album
+		Genre:       genreStr,
+		Label:       album.Label,
 	}

-	// Fetch all tracks with pagination (Deezer default limit is 25)
 	allTracks := album.Tracks.Data

-	// If album has more tracks than returned, fetch remaining pages
 	if album.NbTracks > len(allTracks) {
 		GoLog("[Deezer] Album has %d tracks but only got %d, fetching remaining...", album.NbTracks, len(allTracks))

@@ -523,7 +624,6 @@ func (c *DeezerClient) GetAlbum(ctx context.Context, albumID string) (*AlbumResp
 	isrcMap := c.fetchISRCsParallel(ctx, allTracks)

 	tracks := make([]AlbumTrackMetadata, 0, len(allTracks))
-	// Normalize record_type (Deezer uses "compile" instead of "compilation")
 	albumType := album.RecordType
 	if albumType == "compile" {
 		albumType = "compilation"
@@ -533,7 +633,6 @@ func (c *DeezerClient) GetAlbum(ctx context.Context, albumID string) (*AlbumResp
 		trackIDStr := fmt.Sprintf("%d", track.ID)
 		isrc := isrcMap[trackIDStr]

-		// Use track position from API, fallback to index+1 if not provided
 		trackNum := track.TrackPosition
 		if trackNum == 0 {
 			trackNum = i + 1
@@ -564,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
@@ -581,7 +682,6 @@ func (c *DeezerClient) GetArtist(ctx context.Context, artistID string) (*ArtistR
 	}
 	c.cacheMu.RUnlock()

-	// Fetch artist info
 	artistURL := fmt.Sprintf(deezerArtistURL, artistID)
 	var artist deezerArtistFull
 	if err := c.getJSON(ctx, artistURL, &artist); err != nil {
@@ -596,7 +696,6 @@ func (c *DeezerClient) GetArtist(ctx context.Context, artistID string) (*ArtistR
 		Popularity: 0,
 	}

-	// Fetch artist albums
 	albumsURL := fmt.Sprintf("%s/albums?limit=100", fmt.Sprintf(deezerArtistURL, artistID))
 	var albumsResp struct {
 		Data []struct {
@@ -608,7 +707,7 @@ func (c *DeezerClient) GetArtist(ctx context.Context, artistID string) (*ArtistR
 			CoverMedium string `json:"cover_medium"`
 			CoverBig    string `json:"cover_big"`
 			CoverXL     string `json:"cover_xl"`
-			RecordType  string `json:"record_type"` // album, single, ep, compile
+			RecordType  string `json:"record_type"`
 		} `json:"data"`
 	}

@@ -649,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)

@@ -680,10 +841,8 @@ func (c *DeezerClient) GetPlaylist(ctx context.Context, playlistID string) (*Pla
 	info.Owner.Name = playlist.Title
 	info.Owner.Images = playlistImage

-	// Fetch all tracks with pagination (Deezer default limit is 25)
 	allTracks := playlist.Tracks.Data

-	// If playlist has more tracks than returned, fetch remaining pages
 	if playlist.NbTracks > len(allTracks) {
 		GoLog("[Deezer] Playlist has %d tracks but only got %d, fetching remaining...", playlist.NbTracks, len(allTracks))

@@ -789,7 +948,6 @@ func (c *DeezerClient) fetchFullTrack(ctx context.Context, trackID string) (*dee
 	return &track, nil
 }

-// fetchISRCsParallel fetches ISRCs for multiple tracks in parallel with caching
 func (c *DeezerClient) fetchISRCsParallel(ctx context.Context, tracks []deezerTrack) map[string]string {
 	result := make(map[string]string, len(tracks))
 	var resultMu sync.Mutex
@@ -821,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()
 	}

@@ -828,7 +987,6 @@ func (c *DeezerClient) fetchISRCsParallel(ctx context.Context, tracks []deezerTr
 		return result
 	}

-	// Use semaphore to limit concurrent requests
 	sem := make(chan struct{}, deezerMaxParallelISRC)
 	var wg sync.WaitGroup

@@ -850,13 +1008,13 @@ func (c *DeezerClient) fetchISRCsParallel(ctx context.Context, tracks []deezerTr
 				return
 			}

-			// Store in result and cache
 			resultMu.Lock()
 			result[trackIDStr] = fullTrack.ISRC
 			resultMu.Unlock()

 			c.cacheMu.Lock()
 			c.isrcCache[trackIDStr] = fullTrack.ISRC
+			c.maybeCleanupCachesLocked(time.Now())
 			c.cacheMu.Unlock()
 		}(track)
 	}
@@ -865,7 +1023,6 @@ func (c *DeezerClient) fetchISRCsParallel(ctx context.Context, tracks []deezerTr
 	return result
 }

-// Use this when you need ISRC for download
 func (c *DeezerClient) GetTrackISRC(ctx context.Context, trackID string) (string, error) {
 	c.cacheMu.RLock()
 	if isrc, ok := c.isrcCache[trackID]; ok {
@@ -881,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
@@ -926,11 +1084,10 @@ func (c *DeezerClient) getBestAlbumImage(album deezerAlbumFull) string {
 }

 type AlbumExtendedMetadata struct {
-	Genre string // Comma-separated list of genres
-	Label string // Record label name
+	Genre string
+	Label string
 }

-// Uses the album ID from a track to fetch extended metadata
 func (c *DeezerClient) GetAlbumExtendedMetadata(ctx context.Context, albumID string) (*AlbumExtendedMetadata, error) {
 	if albumID == "" {
 		return nil, fmt.Errorf("empty album ID")
@@ -964,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)
@@ -975,7 +1134,6 @@ func (c *DeezerClient) GetAlbumExtendedMetadata(ctx context.Context, albumID str
 	return result, nil
 }

-// GetTrackAlbumID fetches the album ID for a Deezer track
 func (c *DeezerClient) GetTrackAlbumID(ctx context.Context, trackID string) (string, error) {
 	trackURL := fmt.Sprintf(deezerTrackURL, trackID)

@@ -987,7 +1145,6 @@ func (c *DeezerClient) GetTrackAlbumID(ctx context.Context, trackID string) (str
 	return fmt.Sprintf("%d", track.Album.ID), nil
 }

-// This is a convenience function that first gets the album ID, then fetches album metadata
 func (c *DeezerClient) GetExtendedMetadataByTrackID(ctx context.Context, trackID string) (*AlbumExtendedMetadata, error) {
 	albumID, err := c.GetTrackAlbumID(ctx, trackID)
 	if err != nil {
@@ -997,30 +1154,62 @@ func (c *DeezerClient) GetExtendedMetadataByTrackID(ctx context.Context, trackID
 	return c.GetAlbumExtendedMetadata(ctx, albumID)
 }

-// GetExtendedMetadataByISRC searches for a track by ISRC and fetches extended metadata (genre, label)
 func (c *DeezerClient) GetExtendedMetadataByISRC(ctx context.Context, isrc string) (*AlbumExtendedMetadata, error) {
 	if isrc == "" {
 		return nil, fmt.Errorf("empty ISRC")
 	}

-	// First, search for track by ISRC
 	track, err := c.SearchByISRC(ctx, isrc)
 	if err != nil {
 		return nil, fmt.Errorf("failed to find track by ISRC: %w", err)
 	}

-	// SpotifyID contains "deezer:123" format, extract the ID
 	deezerID := strings.TrimPrefix(track.SpotifyID, "deezer:")

 	if deezerID == "" {
 		return nil, fmt.Errorf("track found but no Deezer ID")
 	}

-	// Then fetch extended metadata using the Deezer track ID
 	return c.GetExtendedMetadataByTrackID(ctx, deezerID)
 }

 func (c *DeezerClient) getJSON(ctx context.Context, endpoint string, dst interface{}) error {
+	var lastErr error
+
+	for attempt := 0; attempt <= deezerMaxRetries; attempt++ {
+		if attempt > 0 {
+			delay := deezerRetryDelay * time.Duration(1<<(attempt-1)) // Exponential backoff
+			GoLog("[Deezer] Retry %d/%d after %v...\n", attempt, deezerMaxRetries, delay)
+			time.Sleep(delay)
+		}
+
+		err := c.doGetJSON(ctx, endpoint, dst)
+		if err == nil {
+			return 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("[Deezer] Attempt %d failed (retryable): %v\n", attempt+1, err)
+	}
+
+	return fmt.Errorf("all %d attempts failed: %w", deezerMaxRetries+1, lastErr)
+}
+
+func (c *DeezerClient) doGetJSON(ctx context.Context, endpoint string, dst interface{}) error {
 	req, err := http.NewRequestWithContext(ctx, http.MethodGet, endpoint, nil)
 	if err != nil {
 		return err
@@ -1046,7 +1235,6 @@ func (c *DeezerClient) getJSON(ctx context.Context, endpoint string, dst interfa
 	return json.Unmarshal(body, dst)
 }

-// parseDeezerURL is internal function, returns type and ID
 func parseDeezerURL(input string) (string, string, error) {
 	trimmed := strings.TrimSpace(input)
 	if trimmed == "" {
@@ -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 := c.httpClient.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 := c.httpClient.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
+}
@@ -10,7 +10,6 @@ import (
 	"time"
 )

-// ISRCIndex holds a cached map of ISRC -> file path for fast duplicate checking
 type ISRCIndex struct {
 	index     map[string]string // ISRC (uppercase) -> file path
 	outputDir string
@@ -25,8 +24,6 @@ var (
 	isrcIndexTTL     = 5 * time.Minute
 )

-// GetISRCIndex returns or builds an ISRC index for the given directory
-// Uses per-directory mutex to prevent concurrent builds (race condition fix)
 func GetISRCIndex(outputDir string) *ISRCIndex {
 	// Fast path: check cache first
 	isrcIndexCacheMu.RLock()
@@ -56,7 +53,6 @@ func GetISRCIndex(outputDir string) *ISRCIndex {
 	return buildISRCIndex(outputDir)
 }

-// buildISRCIndex scans a directory and builds a map of ISRC -> file path
 func buildISRCIndex(outputDir string) *ISRCIndex {
 	idx := &ISRCIndex{
 		index:     make(map[string]string),
@@ -91,7 +87,7 @@ func buildISRCIndex(outputDir string) *ISRCIndex {
 		return nil
 	})

-	fmt.Printf("[ISRCIndex] Built index for %s: %d files in %v\n", 
+	fmt.Printf("[ISRCIndex] Built index for %s: %d files in %v\n",
 		outputDir, fileCount, time.Since(startTime).Round(time.Millisecond))

 	isrcIndexCacheMu.Lock()
@@ -113,7 +109,6 @@ func (idx *ISRCIndex) lookup(isrc string) (string, bool) {
 	return path, exists
 }

-// remove deletes an ISRC entry from the index (internal use)
 func (idx *ISRCIndex) remove(isrc string) {
 	if isrc == "" {
 		return
@@ -125,14 +120,11 @@ func (idx *ISRCIndex) remove(isrc string) {
 	delete(idx.index, strings.ToUpper(isrc))
 }

-// Lookup checks if an ISRC exists in the index (gomobile compatible)
-// Returns filepath if found, empty string if not found
 func (idx *ISRCIndex) Lookup(isrc string) (string, error) {
 	path, _ := idx.lookup(isrc)
 	return path, nil
 }

-// Add adds a new ISRC to the index (call after successful download)
 func (idx *ISRCIndex) Add(isrc, filePath string) {
 	if isrc == "" || filePath == "" {
 		return
@@ -144,15 +136,12 @@ func (idx *ISRCIndex) Add(isrc, filePath string) {
 	idx.index[strings.ToUpper(isrc)] = filePath
 }

-// InvalidateCache clears the ISRC index cache for a directory
 func InvalidateISRCCache(outputDir string) {
 	isrcIndexCacheMu.Lock()
 	delete(isrcIndexCache, outputDir)
 	isrcIndexCacheMu.Unlock()
 }

-// checkISRCExistsInternal checks if a file with the given ISRC exists (internal use)
-// Uses ISRC index for fast lookup
 func checkISRCExistsInternal(outputDir, isrc string) (string, bool) {
 	if isrc == "" || outputDir == "" {
 		return "", false
@@ -173,13 +162,11 @@ func checkISRCExistsInternal(outputDir, isrc string) (string, bool) {
 	return filePath, true
 }

-// CheckISRCExists is the exported version for gomobile (returns string, error)
 func CheckISRCExists(outputDir, isrc string) (string, error) {
 	filepath, _ := checkISRCExistsInternal(outputDir, isrc)
 	return filepath, nil
 }

-// CheckFileExists checks if a file with the given name exists
 func CheckFileExists(filePath string) bool {
 	info, err := os.Stat(filePath)
 	if err != nil {
@@ -188,7 +175,6 @@ func CheckFileExists(filePath string) bool {
 	return !info.IsDir() && info.Size() > 0
 }

-// FileExistenceResult represents the result of checking if a file exists
 type FileExistenceResult struct {
 	ISRC       string `json:"isrc"`
 	Exists     bool   `json:"exists"`
@@ -249,8 +235,6 @@ func CheckFilesExistParallel(outputDir string, tracksJSON string) (string, error
 	return string(resultJSON), nil
 }

-// PreBuildISRCIndex pre-builds the ISRC index for a directory
-// Call this when app starts or when entering album/playlist screen
 func PreBuildISRCIndex(outputDir string) error {
 	if outputDir == "" {
 		return fmt.Errorf("output directory is required")
@@ -260,7 +244,6 @@ func PreBuildISRCIndex(outputDir string) error {
 	return nil
 }

-// AddToISRCIndex adds a new file to the ISRC index after successful download
 func AddToISRCIndex(outputDir, isrc, filePath string) {
 	if outputDir == "" || isrc == "" || filePath == "" {
 		return
@@ -47,20 +47,20 @@ type LoadedExtension struct {
 	ID        string             `json:"id"`
 	Manifest  *ExtensionManifest `json:"manifest"`
 	VM        *goja.Runtime      `json:"-"`
-	VMMu      sync.Mutex         `json:"-"` // Mutex to prevent concurrent VM access
-	Enabled   bool               `json:"enabled"`
-	Error     string             `json:"error,omitempty"`
-	DataDir   string             `json:"data_dir"`
-	SourceDir string             `json:"source_dir"`
-	IconPath  string             `json:"icon_path"`
+	VMMu      sync.Mutex         `json:"-"`
+	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"`
 }

-// ExtensionManager manages all loaded extensions
 type ExtensionManager struct {
 	mu            sync.RWMutex
 	extensions    map[string]*LoadedExtension
-	extensionsDir string // Base directory for extensions
-	dataDir       string // Base directory for extension data
+	extensionsDir string
+	dataDir       string
 }

 var (
@@ -99,7 +99,6 @@ func (m *ExtensionManager) LoadExtensionFromFile(filePath string) (*LoadedExtens
 		return nil, fmt.Errorf("Invalid file format. Please select a .spotiflac-ext file")
 	}

-	// Open the zip file
 	zipReader, err := zip.OpenReader(filePath)
 	if err != nil {
 		return nil, fmt.Errorf("Cannot open extension file. The file may be corrupted or not a valid extension package")
@@ -222,7 +221,6 @@ func (m *ExtensionManager) LoadExtensionFromFile(filePath string) (*LoadedExtens
 		SourceDir: extDir,
 	}

-	// Initialize Goja VM
 	if err := m.initializeVM(ext); err != nil {
 		ext.Error = err.Error()
 		ext.Enabled = false
@@ -246,6 +244,7 @@ func (m *ExtensionManager) initializeVM(ext *LoadedExtension) error {
 	}

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

@@ -269,13 +268,11 @@ func (m *ExtensionManager) initializeVM(ext *LoadedExtension) error {
 		return goja.Undefined()
 	})

-	// Run the extension code
 	_, err = vm.RunString(string(jsCode))
 	if err != nil {
 		return fmt.Errorf("failed to execute extension code: %w", err)
 	}

-	// Verify extension was registered
 	if registeredExtension == nil || goja.IsUndefined(registeredExtension) {
 		return fmt.Errorf("extension did not call registerExtension()")
 	}
@@ -283,7 +280,6 @@ func (m *ExtensionManager) initializeVM(ext *LoadedExtension) error {
 	return nil
 }

-// UnloadExtension unloads an extension by ID
 func (m *ExtensionManager) UnloadExtension(extensionID string) error {
 	m.mu.Lock()
 	defer m.mu.Unlock()
@@ -293,9 +289,7 @@ func (m *ExtensionManager) UnloadExtension(extensionID string) error {
 		return fmt.Errorf("Extension not found")
 	}

-	// Call cleanup if VM is initialized
 	if ext.VM != nil {
-		// Try to call cleanup function
 		cleanup, err := ext.VM.RunString("typeof extension !== 'undefined' && typeof extension.cleanup === 'function' ? extension.cleanup() : null")
 		if err != nil {
 			GoLog("[Extension] Error calling cleanup for %s: %v\n", extensionID, err)
@@ -303,15 +297,20 @@ 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
+	}

-	// Remove from registry
 	delete(m.extensions, extensionID)
 	GoLog("[Extension] Unloaded extension: %s\n", extensionID)

 	return nil
 }

-// Returns error if extension not found (gomobile compatible)
 func (m *ExtensionManager) GetExtension(extensionID string) (*LoadedExtension, error) {
 	m.mu.RLock()
 	defer m.mu.RUnlock()
@@ -323,7 +322,6 @@ func (m *ExtensionManager) GetExtension(extensionID string) (*LoadedExtension, e
 	return ext, nil
 }

-// GetAllExtensions returns all loaded extensions
 func (m *ExtensionManager) GetAllExtensions() []*LoadedExtension {
 	m.mu.RLock()
 	defer m.mu.RUnlock()
@@ -347,7 +345,6 @@ func (m *ExtensionManager) SetExtensionEnabled(extensionID string, enabled bool)
 	ext.Enabled = enabled
 	GoLog("[Extension] %s %s\n", extensionID, map[bool]string{true: "enabled", false: "disabled"}[enabled])

-	// Persist enabled state to settings store
 	store := GetExtensionSettingsStore()
 	if err := store.Set(extensionID, "_enabled", enabled); err != nil {
 		GoLog("[Extension] Failed to persist enabled state for %s: %v\n", extensionID, err)
@@ -356,7 +353,6 @@ func (m *ExtensionManager) SetExtensionEnabled(extensionID string, enabled bool)
 	return nil
 }

-// LoadExtensionsFromDirectory scans a directory and loads all valid extensions
 func (m *ExtensionManager) LoadExtensionsFromDirectory(dirPath string) ([]string, []error) {
 	var loaded []string
 	var errors []error
@@ -443,7 +439,6 @@ func (m *ExtensionManager) loadExtensionFromDirectory(dirPath string) (*LoadedEx
 		}
 	}

-	// Initialize Goja VM
 	if err := m.initializeVM(ext); err != nil {
 		ext.Error = err.Error()
 		ext.Enabled = false
@@ -456,19 +451,16 @@ func (m *ExtensionManager) loadExtensionFromDirectory(dirPath string) (*LoadedEx
 	return ext, nil
 }

-// RemoveExtension completely removes an extension (unload + delete files)
 func (m *ExtensionManager) RemoveExtension(extensionID string) error {
 	ext, err := m.GetExtension(extensionID)
 	if err != nil {
 		return err
 	}

-	// Unload first
 	if err := m.UnloadExtension(extensionID); err != nil {
 		return err
 	}

-	// Remove source directory
 	if ext.SourceDir != "" {
 		if err := os.RemoveAll(ext.SourceDir); err != nil {
 			GoLog("[Extension] Warning: failed to remove source dir: %v\n", err)
@@ -490,7 +482,6 @@ func (m *ExtensionManager) UpgradeExtension(filePath string) (*LoadedExtension,
 		return nil, fmt.Errorf("Invalid file format. Please select a .spotiflac-ext file")
 	}

-	// Open the zip file
 	zipReader, err := zip.OpenReader(filePath)
 	if err != nil {
 		return nil, fmt.Errorf("Cannot open extension file. The file may be corrupted or not a valid extension package")
@@ -554,11 +545,8 @@ func (m *ExtensionManager) UpgradeExtension(filePath string) (*LoadedExtension,
 	extDir := existing.SourceDir
 	wasEnabled := existing.Enabled

-	// Cleanup and unload existing extension
-	m.CleanupExtension(existing.ID)
 	m.UnloadExtension(existing.ID)

-	// Remove old source files but keep data directory
 	if extDir != "" {
 		if err := os.RemoveAll(extDir); err != nil {
 			GoLog("[Extension] Warning: failed to remove old source dir: %v\n", err)
@@ -637,16 +625,14 @@ type ExtensionUpgradeInfo struct {
 	IsInstalled    bool   `json:"is_installed"`
 }

-// checkExtensionUpgradeInternal checks if a package file is an upgrade for an existing extension
-// Internal function that returns 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")
+		return nil, fmt.Errorf("Invalid file format. Please select a .spotiflac-ext file")
 	}

-	// Open the zip file
 	zipReader, err := zip.OpenReader(filePath)
+
 	if err != nil {
 		return nil, fmt.Errorf("Cannot open extension file")
 	}
@@ -714,7 +700,6 @@ func (m *ExtensionManager) CheckExtensionUpgradeJSON(filePath string) (string, e
 	return string(jsonBytes), nil
 }

-// GetInstalledExtensionsJSON returns all extensions as JSON for Flutter
 func (m *ExtensionManager) GetInstalledExtensionsJSON() (string, error) {
 	extensions := m.GetAllExtensions()

@@ -736,6 +721,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"`
@@ -793,6 +779,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,
@@ -809,8 +796,6 @@ func (m *ExtensionManager) GetInstalledExtensionsJSON() (string, error) {
 	return string(jsonBytes), nil
 }

-// ==================== Extension Lifecycle ====================
-
 func (m *ExtensionManager) InitializeExtension(extensionID string, settings map[string]interface{}) error {
 	m.mu.Lock()
 	defer m.mu.Unlock()
@@ -923,7 +908,6 @@ func (m *ExtensionManager) CleanupExtension(extensionID string) error {
 	return nil
 }

-// UnloadAllExtensions unloads all extensions gracefully
 func (m *ExtensionManager) UnloadAllExtensions() {
 	m.mu.Lock()
 	extensionIDs := make([]string, 0, len(m.extensions))
@@ -933,14 +917,12 @@ func (m *ExtensionManager) UnloadAllExtensions() {
 	m.mu.Unlock()

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

 	GoLog("[Extension] All extensions unloaded\n")
 }

-// The function is called as extension.<actionName>() and can return a result
 func (m *ExtensionManager) InvokeAction(extensionID string, actionName string) (map[string]interface{}, error) {
 	m.mu.Lock()
 	defer m.mu.Unlock()
@@ -7,15 +7,14 @@ import (
 	"strings"
 )

-// ExtensionType represents the type of extension
 type ExtensionType string

 const (
 	ExtensionTypeMetadataProvider ExtensionType = "metadata_provider"
 	ExtensionTypeDownloadProvider ExtensionType = "download_provider"
+	ExtensionTypeLyricsProvider   ExtensionType = "lyrics_provider"
 )

-// SettingType represents the type of a setting field
 type SettingType string

 const (
@@ -26,14 +25,12 @@ const (
 	SettingTypeButton SettingType = "button" // Action button that calls a JS function
 )

-// ExtensionPermissions defines what resources an extension can access
 type ExtensionPermissions struct {
-	Network []string `json:"network"` // List of allowed domains
-	Storage bool     `json:"storage"` // Whether extension can use storage API
-	File    bool     `json:"file"`    // Whether extension can use file API
+	Network []string `json:"network"`
+	Storage bool     `json:"storage"`
+	File    bool     `json:"file"`
 }

-// ExtensionSetting defines a configurable setting for an extension
 type ExtensionSetting struct {
 	Key         string      `json:"key"`
 	Type        SettingType `json:"type"`
@@ -42,19 +39,17 @@ type ExtensionSetting struct {
 	Required    bool        `json:"required,omitempty"`
 	Secret      bool        `json:"secret,omitempty"`
 	Default     interface{} `json:"default,omitempty"`
-	Options     []string    `json:"options,omitempty"` // For select type
-	Action      string      `json:"action,omitempty"`  // For button type: JS function name to call (e.g., "startLogin")
+	Options     []string    `json:"options,omitempty"`
+	Action      string      `json:"action,omitempty"`
 }

-// QualityOption represents a quality option for download providers
 type QualityOption struct {
-	ID          string                   `json:"id"`                 // Unique identifier (e.g., "mp3_320", "opus_128")
-	Label       string                   `json:"label"`              // Display name (e.g., "MP3 320kbps")
-	Description string                   `json:"description"`        // Optional description (e.g., "Best quality MP3")
-	Settings    []QualitySpecificSetting `json:"settings,omitempty"` // Quality-specific settings
+	ID          string                   `json:"id"`
+	Label       string                   `json:"label"`
+	Description string                   `json:"description"`
+	Settings    []QualitySpecificSetting `json:"settings,omitempty"`
 }

-// QualitySpecificSetting represents a setting that's specific to a quality option
 type QualitySpecificSetting struct {
 	Key         string      `json:"key"`
 	Type        SettingType `json:"type"`
@@ -63,57 +58,50 @@ type QualitySpecificSetting struct {
 	Required    bool        `json:"required,omitempty"`
 	Secret      bool        `json:"secret,omitempty"`
 	Default     interface{} `json:"default,omitempty"`
-	Options     []string    `json:"options,omitempty"` // For select type
+	Options     []string    `json:"options,omitempty"`
 }

-// SearchFilter defines a filter option for search
 type SearchFilter struct {
-	ID    string `json:"id"`              // Filter identifier (e.g., "track", "album", "artist", "playlist")
-	Label string `json:"label,omitempty"` // Display label (e.g., "Songs", "Albums", "Artists", "Playlists")
-	Icon  string `json:"icon,omitempty"`  // Optional icon name
+	ID    string `json:"id"`
+	Label string `json:"label,omitempty"`
+	Icon  string `json:"icon,omitempty"`
 }

-// SearchBehaviorConfig defines custom search behavior for an extension
 type SearchBehaviorConfig struct {
-	Enabled         bool           `json:"enabled"`                   // Whether extension provides custom search
-	Placeholder     string         `json:"placeholder,omitempty"`     // Placeholder text for search box
-	Primary         bool           `json:"primary,omitempty"`         // If true, show as primary search tab
-	Icon            string         `json:"icon,omitempty"`            // Icon for search tab
-	ThumbnailRatio  string         `json:"thumbnailRatio,omitempty"`  // Thumbnail aspect ratio: "square" (1:1), "wide" (16:9), "portrait" (2:3)
-	ThumbnailWidth  int            `json:"thumbnailWidth,omitempty"`  // Custom thumbnail width in pixels
-	ThumbnailHeight int            `json:"thumbnailHeight,omitempty"` // Custom thumbnail height in pixels
-	Filters         []SearchFilter `json:"filters,omitempty"`         // Available search filters (e.g., track, album, artist, playlist)
+	Enabled         bool           `json:"enabled"`
+	Placeholder     string         `json:"placeholder,omitempty"`
+	Primary         bool           `json:"primary,omitempty"`
+	Icon            string         `json:"icon,omitempty"`
+	ThumbnailRatio  string         `json:"thumbnailRatio,omitempty"`
+	ThumbnailWidth  int            `json:"thumbnailWidth,omitempty"`
+	ThumbnailHeight int            `json:"thumbnailHeight,omitempty"`
+	Filters         []SearchFilter `json:"filters,omitempty"`
 }

-// URLHandlerConfig defines custom URL handling for an extension
 type URLHandlerConfig struct {
-	Enabled  bool     `json:"enabled"`            // Whether extension handles URLs
-	Patterns []string `json:"patterns,omitempty"` // URL patterns to match (e.g., "music.youtube.com", "soundcloud.com")
+	Enabled  bool     `json:"enabled"`
+	Patterns []string `json:"patterns,omitempty"`
 }

-// TrackMatchingConfig defines custom track matching behavior
 type TrackMatchingConfig struct {
-	CustomMatching    bool   `json:"customMatching"`              // Whether extension handles matching
-	Strategy          string `json:"strategy,omitempty"`          // "isrc", "name", "duration", "custom"
-	DurationTolerance int    `json:"durationTolerance,omitempty"` // Tolerance in seconds for duration matching
+	CustomMatching    bool   `json:"customMatching"`
+	Strategy          string `json:"strategy,omitempty"`
+	DurationTolerance int    `json:"durationTolerance,omitempty"`
 }

-// PostProcessingHook defines a post-processing hook
 type PostProcessingHook struct {
-	ID               string   `json:"id"`                         // Unique identifier
-	Name             string   `json:"name"`                       // Display name
-	Description      string   `json:"description,omitempty"`      // Description
-	DefaultEnabled   bool     `json:"defaultEnabled,omitempty"`   // Whether enabled by default
-	SupportedFormats []string `json:"supportedFormats,omitempty"` // Supported file formats (e.g., ["flac", "mp3"])
+	ID               string   `json:"id"`
+	Name             string   `json:"name"`
+	Description      string   `json:"description,omitempty"`
+	DefaultEnabled   bool     `json:"defaultEnabled,omitempty"`
+	SupportedFormats []string `json:"supportedFormats,omitempty"`
 }

-// PostProcessingConfig defines post-processing capabilities
 type PostProcessingConfig struct {
-	Enabled bool                 `json:"enabled"`         // Whether extension provides post-processing
-	Hooks   []PostProcessingHook `json:"hooks,omitempty"` // Available hooks
+	Enabled bool                 `json:"enabled"`
+	Hooks   []PostProcessingHook `json:"hooks,omitempty"`
 }

-// ExtensionManifest represents the manifest.json of an extension
 type ExtensionManifest struct {
 	Name                   string                 `json:"name"`
 	DisplayName            string                 `json:"displayName"`
@@ -121,22 +109,21 @@ type ExtensionManifest struct {
 	Author                 string                 `json:"author"`
 	Description            string                 `json:"description"`
 	Homepage               string                 `json:"homepage,omitempty"`
-	Icon                   string                 `json:"icon,omitempty"` // Icon filename (e.g., "icon.png")
+	Icon                   string                 `json:"icon,omitempty"`
 	Types                  []ExtensionType        `json:"type"`
 	Permissions            ExtensionPermissions   `json:"permissions"`
 	Settings               []ExtensionSetting     `json:"settings,omitempty"`
-	QualityOptions         []QualityOption        `json:"qualityOptions,omitempty"` // Custom quality options for download providers
+	QualityOptions         []QualityOption        `json:"qualityOptions,omitempty"`
 	MinAppVersion          string                 `json:"minAppVersion,omitempty"`
-	SkipMetadataEnrichment bool                   `json:"skipMetadataEnrichment,omitempty"` // If true, don't enrich metadata from Deezer/Spotify
-	SkipBuiltInFallback    bool                   `json:"skipBuiltInFallback,omitempty"`    // If true, don't fallback to built-in providers (tidal/qobuz/amazon)
-	SearchBehavior         *SearchBehaviorConfig  `json:"searchBehavior,omitempty"`         // Custom search behavior
-	URLHandler             *URLHandlerConfig      `json:"urlHandler,omitempty"`             // Custom URL handling
-	TrackMatching          *TrackMatchingConfig   `json:"trackMatching,omitempty"`          // Custom track matching
-	PostProcessing         *PostProcessingConfig  `json:"postProcessing,omitempty"`         // Post-processing hooks
-	Capabilities           map[string]interface{} `json:"capabilities,omitempty"`           // Extension capabilities (homeFeed, browseCategories, etc.)
+	SkipMetadataEnrichment bool                   `json:"skipMetadataEnrichment,omitempty"`
+	SkipBuiltInFallback    bool                   `json:"skipBuiltInFallback,omitempty"`
+	SearchBehavior         *SearchBehaviorConfig  `json:"searchBehavior,omitempty"`
+	URLHandler             *URLHandlerConfig      `json:"urlHandler,omitempty"`
+	TrackMatching          *TrackMatchingConfig   `json:"trackMatching,omitempty"`
+	PostProcessing         *PostProcessingConfig  `json:"postProcessing,omitempty"`
+	Capabilities           map[string]interface{} `json:"capabilities,omitempty"`
 }

-// ManifestValidationError represents a validation error in the manifest
 type ManifestValidationError struct {
 	Field   string
 	Message string
@@ -146,7 +133,6 @@ func (e *ManifestValidationError) Error() string {
 	return fmt.Sprintf("manifest validation error: %s - %s", e.Field, e.Message)
 }

-// ParseManifest parses and validates a manifest from JSON bytes
 func ParseManifest(data []byte) (*ExtensionManifest, error) {
 	var manifest ExtensionManifest
 	if err := json.Unmarshal(data, &manifest); err != nil {
@@ -182,15 +168,14 @@ 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),
 			}
 		}
 	}

-	// Validate settings if present
 	for i, setting := range m.Settings {
 		if strings.TrimSpace(setting.Key) == "" {
 			return &ManifestValidationError{
@@ -225,7 +210,6 @@ func (m *ExtensionManifest) Validate() error {
 	return nil
 }

-// HasType checks if the extension has a specific type
 func (m *ExtensionManifest) HasType(t ExtensionType) bool {
 	for _, et := range m.Types {
 		if et == t {
@@ -235,17 +219,18 @@ func (m *ExtensionManifest) HasType(t ExtensionType) bool {
 	return false
 }

-// IsMetadataProvider returns true if extension provides metadata
 func (m *ExtensionManifest) IsMetadataProvider() bool {
 	return m.HasType(ExtensionTypeMetadataProvider)
 }

-// IsDownloadProvider returns true if extension provides downloads
 func (m *ExtensionManifest) IsDownloadProvider() bool {
 	return m.HasType(ExtensionTypeDownloadProvider)
 }

-// IsDomainAllowed checks if a domain is in the allowed network permissions
+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 {
@@ -255,7 +240,7 @@ func (m *ExtensionManifest) IsDomainAllowed(domain string) bool {
 		}
 		// Support wildcard subdomains (e.g., *.example.com)
 		if strings.HasPrefix(allowed, "*.") {
-			suffix := allowed[1:] // Remove the *
+			suffix := allowed[1:]
 			if strings.HasSuffix(domain, suffix) {
 				return true
 			}
@@ -264,27 +249,22 @@ func (m *ExtensionManifest) IsDomainAllowed(domain string) bool {
 	return false
 }

-// HasCustomSearch returns true if extension provides custom search
 func (m *ExtensionManifest) HasCustomSearch() bool {
 	return m.SearchBehavior != nil && m.SearchBehavior.Enabled
 }

-// HasCustomMatching returns true if extension provides custom track matching
 func (m *ExtensionManifest) HasCustomMatching() bool {
 	return m.TrackMatching != nil && m.TrackMatching.CustomMatching
 }

-// HasPostProcessing returns true if extension provides post-processing
 func (m *ExtensionManifest) HasPostProcessing() bool {
 	return m.PostProcessing != nil && m.PostProcessing.Enabled
 }

-// HasURLHandler returns true if extension handles custom URLs
 func (m *ExtensionManifest) HasURLHandler() bool {
 	return m.URLHandler != nil && m.URLHandler.Enabled && len(m.URLHandler.Patterns) > 0
 }

-// MatchesURL checks if a URL matches any of the extension's URL patterns
 func (m *ExtensionManifest) MatchesURL(urlStr string) bool {
 	if !m.HasURLHandler() {
 		return false
@@ -293,7 +273,6 @@ func (m *ExtensionManifest) MatchesURL(urlStr string) bool {
 	urlStr = strings.ToLower(strings.TrimSpace(urlStr))
 	for _, pattern := range m.URLHandler.Patterns {
 		pattern = strings.ToLower(strings.TrimSpace(pattern))
-		// Check if URL contains the pattern (host match)
 		if strings.Contains(urlStr, pattern) {
 			return true
 		}
@@ -301,7 +280,6 @@ func (m *ExtensionManifest) MatchesURL(urlStr string) bool {
 	return false
 }

-// GetPostProcessingHooks returns all post-processing hooks
 func (m *ExtensionManifest) GetPostProcessingHooks() []PostProcessingHook {
 	if m.PostProcessing == nil {
 		return nil
@@ -309,7 +287,6 @@ func (m *ExtensionManifest) GetPostProcessingHooks() []PostProcessingHook {
 	return m.PostProcessing.Hooks
 }

-// ToJSON serializes the manifest to JSON
 func (m *ExtensionManifest) ToJSON() ([]byte, error) {
 	return json.Marshal(m)
 }
@@ -1,8 +1,11 @@
 package gobackend

 import (
+	"fmt"
+	"net"
 	"net/http"
 	"net/url"
+	"strings"
 	"sync"
 	"time"

@@ -23,9 +26,8 @@ type ExtensionAuthState struct {
 	RefreshToken    string
 	ExpiresAt       time.Time
 	IsAuthenticated bool
-	// PKCE support
-	PKCEVerifier  string
-	PKCEChallenge string
+	PKCEVerifier    string
+	PKCEChallenge   string
 }

 type PendingAuthRequest struct {
@@ -39,7 +41,6 @@ var (
 	pendingAuthRequestsMu sync.RWMutex
 )

-// GetPendingAuthRequest returns pending auth request for an extension (called from Flutter)
 func GetPendingAuthRequest(extensionID string) *PendingAuthRequest {
 	pendingAuthRequestsMu.RLock()
 	defer pendingAuthRequestsMu.RUnlock()
@@ -87,40 +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 {
-			// Validate redirect target domain against allowed domains
-			domain := req.URL.Hostname()
-			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}
-			}
-			// Default redirect limit (10)
-			if len(via) >= 10 {
-				return http.ErrUseLastResponse
-			}
-			return nil
-		},
+		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
 	}
 	runtime.httpClient = client

@@ -139,37 +182,99 @@ 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 {
-	// Block common private network patterns
-	// This is a simple check - for production, consider DNS resolution
-	privatePatterns := []string{
-		"localhost",
-		"127.",
-		"10.",
-		"172.16.", "172.17.", "172.18.", "172.19.",
-		"172.20.", "172.21.", "172.22.", "172.23.",
-		"172.24.", "172.25.", "172.26.", "172.27.",
-		"172.28.", "172.29.", "172.30.", "172.31.",
-		"192.168.",
-		"169.254.",
-		"::1",
-		"fc00:",
-		"fe80:",
+	hostLower := strings.ToLower(strings.TrimSpace(host))
+	if hostLower == "" {
+		return false
 	}

-	hostLower := host
-	for _, pattern := range privatePatterns {
-		if hostLower == pattern || len(hostLower) > len(pattern) && hostLower[:len(pattern)] == pattern {
-			return true
-		}
-	}
-
-	// Also block .local domains
-	if len(host) > 6 && host[len(host)-6:] == ".local" {
+	if hostLower == "localhost" || strings.HasSuffix(hostLower, ".local") {
 		return true
 	}

+	if ip := net.ParseIP(hostLower); ip != nil {
+		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) {
+			isPrivate = true
+			break
+		}
+	}
+
+	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 {
+	if ip == nil {
+		return false
+	}
+	if ip.IsLoopback() ||
+		ip.IsPrivate() ||
+		ip.IsLinkLocalUnicast() ||
+		ip.IsLinkLocalMulticast() ||
+		ip.IsMulticast() ||
+		ip.IsUnspecified() {
+		return true
+	}
+	if !ip.IsGlobalUnicast() {
+		return true
+	}
 	return false
 }

@@ -201,18 +306,16 @@ func (r *ExtensionRuntime) SetSettings(settings map[string]interface{}) {
 	r.settings = settings
 }

-// RegisterAPIs registers all sandboxed APIs to the Goja VM
 func (r *ExtensionRuntime) RegisterAPIs(vm *goja.Runtime) {
 	r.vm = vm

-	// HTTP client (sandboxed to allowed domains)
 	httpObj := vm.NewObject()
 	httpObj.Set("get", r.httpGet)
 	httpObj.Set("post", r.httpPost)
 	httpObj.Set("put", r.httpPut)
 	httpObj.Set("delete", r.httpDelete)
 	httpObj.Set("patch", r.httpPatch)
-	httpObj.Set("request", r.httpRequest) // Generic HTTP request (GET, POST, PUT, DELETE, etc.)
+	httpObj.Set("request", r.httpRequest)
 	httpObj.Set("clearCookies", r.httpClearCookies)
 	vm.Set("http", httpObj)

@@ -222,7 +325,6 @@ func (r *ExtensionRuntime) RegisterAPIs(vm *goja.Runtime) {
 	storageObj.Set("remove", r.storageRemove)
 	vm.Set("storage", storageObj)

-	// Secure Credentials API (encrypted storage for sensitive data)
 	credentialsObj := vm.NewObject()
 	credentialsObj.Set("store", r.credentialsStore)
 	credentialsObj.Set("get", r.credentialsGet)
@@ -237,14 +339,12 @@ func (r *ExtensionRuntime) RegisterAPIs(vm *goja.Runtime) {
 	authObj.Set("clearAuth", r.authClear)
 	authObj.Set("isAuthenticated", r.authIsAuthenticated)
 	authObj.Set("getTokens", r.authGetTokens)
-	// PKCE support
 	authObj.Set("generatePKCE", r.authGeneratePKCE)
 	authObj.Set("getPKCE", r.authGetPKCE)
 	authObj.Set("startOAuthWithPKCE", r.authStartOAuthWithPKCE)
 	authObj.Set("exchangeCodeWithPKCE", r.authExchangeCodeWithPKCE)
 	vm.Set("auth", authObj)

-	// File operations (sandboxed)
 	fileObj := vm.NewObject()
 	fileObj.Set("download", r.fileDownload)
 	fileObj.Set("exists", r.fileExists)
@@ -262,7 +362,6 @@ func (r *ExtensionRuntime) RegisterAPIs(vm *goja.Runtime) {
 	ffmpegObj.Set("convert", r.ffmpegConvert)
 	vm.Set("ffmpeg", ffmpegObj)

-	// Track matching API
 	matchingObj := vm.NewObject()
 	matchingObj.Set("compareStrings", r.matchingCompareStrings)
 	matchingObj.Set("compareDuration", r.matchingCompareDuration)
@@ -279,14 +378,12 @@ func (r *ExtensionRuntime) RegisterAPIs(vm *goja.Runtime) {
 	utilsObj.Set("hmacSHA1", r.hmacSHA1)
 	utilsObj.Set("parseJSON", r.parseJSON)
 	utilsObj.Set("stringifyJSON", r.stringifyJSON)
-	// Crypto utilities for developers
 	utilsObj.Set("encrypt", r.cryptoEncrypt)
 	utilsObj.Set("decrypt", r.cryptoDecrypt)
 	utilsObj.Set("generateKey", r.cryptoGenerateKey)
 	utilsObj.Set("randomUserAgent", r.randomUserAgent)
 	vm.Set("utils", utilsObj)

-	// Log object (already set in extension_manager.go, but we can enhance it)
 	logObj := vm.NewObject()
 	logObj.Set("debug", r.logDebug)
 	logObj.Set("info", r.logInfo)
@@ -298,10 +395,6 @@ func (r *ExtensionRuntime) RegisterAPIs(vm *goja.Runtime) {
 	gobackendObj.Set("sanitizeFilename", r.sanitizeFilenameWrapper)
 	vm.Set("gobackend", gobackendObj)

-	// ==================== Browser-like Polyfills ====================
-	// These make porting browser/Node.js libraries easier
-
-	// Global fetch() - Promise-style HTTP API (browser-compatible)
 	vm.Set("fetch", r.fetchPolyfill)

 	vm.Set("atob", r.atobPolyfill)
@@ -18,6 +18,43 @@ import (

 // ==================== 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 {
 		return r.vm.ToValue(map[string]interface{}{
@@ -32,6 +69,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 +94,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,
@@ -70,13 +114,11 @@ func (r *ExtensionRuntime) authGetCode(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(state.AuthCode)
 }

-// authSetCode sets auth code and tokens (can be called by extension after token exchange)
 func (r *ExtensionRuntime) authSetCode(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue(false)
 	}

-	// Can accept either just auth code or an object with tokens
 	arg := call.Arguments[0].Export()

 	extensionAuthStateMu.Lock()
@@ -123,7 +165,6 @@ func (r *ExtensionRuntime) authClear(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(true)
 }

-// authIsAuthenticated checks if extension has valid auth
 func (r *ExtensionRuntime) authIsAuthenticated(call goja.FunctionCall) goja.Value {
 	extensionAuthStateMu.RLock()
 	defer extensionAuthStateMu.RUnlock()
@@ -196,7 +237,6 @@ func generatePKCEChallenge(verifier string) string {
 }

 func (r *ExtensionRuntime) authGeneratePKCE(call goja.FunctionCall) goja.Value {
-	// Default length is 64 characters
 	length := 64
 	if len(call.Arguments) > 0 && !goja.IsUndefined(call.Arguments[0]) {
 		if l, ok := call.Arguments[0].Export().(float64); ok && l >= 43 && l <= 128 {
@@ -249,9 +289,7 @@ func (r *ExtensionRuntime) authGetPKCE(call goja.FunctionCall) goja.Value {
 	})
 }

-// authStartOAuthWithPKCE is a high-level helper that generates PKCE and opens OAuth URL
 // config: { authUrl, clientId, redirectUri, scope, extraParams }
-// Returns: { success, authUrl, pkce: { verifier, challenge } }
 func (r *ExtensionRuntime) authStartOAuthWithPKCE(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue(map[string]interface{}{
@@ -269,7 +307,6 @@ func (r *ExtensionRuntime) authStartOAuthWithPKCE(call goja.FunctionCall) goja.V
 		})
 	}

-	// Required fields
 	authURL, _ := config["authUrl"].(string)
 	clientID, _ := config["clientId"].(string)
 	redirectURI, _ := config["redirectUri"].(string)
@@ -280,12 +317,16 @@ 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(),
+		})
+	}

-	// Optional fields
 	scope, _ := config["scope"].(string)
 	extraParams, _ := config["extraParams"].(map[string]interface{})

-	// Generate PKCE
 	verifier, err := generatePKCEVerifier(64)
 	if err != nil {
 		return r.vm.ToValue(map[string]interface{}{
@@ -295,7 +336,6 @@ func (r *ExtensionRuntime) authStartOAuthWithPKCE(call goja.FunctionCall) goja.V
 	}
 	challenge := generatePKCEChallenge(verifier)

-	// Store PKCE in auth state
 	extensionAuthStateMu.Lock()
 	state, exists := extensionAuthState[r.extensionID]
 	if !exists {
@@ -304,10 +344,9 @@ func (r *ExtensionRuntime) authStartOAuthWithPKCE(call goja.FunctionCall) goja.V
 	}
 	state.PKCEVerifier = verifier
 	state.PKCEChallenge = challenge
-	state.AuthCode = "" // Clear any previous auth code
+	state.AuthCode = ""
 	extensionAuthStateMu.Unlock()

-	// Build OAuth URL with PKCE parameters
 	parsedURL, err := url.Parse(authURL)
 	if err != nil {
 		return r.vm.ToValue(map[string]interface{}{
@@ -327,7 +366,6 @@ func (r *ExtensionRuntime) authStartOAuthWithPKCE(call goja.FunctionCall) goja.V
 		query.Set("scope", scope)
 	}

-	// Add extra params
 	for k, v := range extraParams {
 		query.Set(k, fmt.Sprintf("%v", v))
 	}
@@ -335,7 +373,6 @@ func (r *ExtensionRuntime) authStartOAuthWithPKCE(call goja.FunctionCall) goja.V
 	parsedURL.RawQuery = query.Encode()
 	fullAuthURL := parsedURL.String()

-	// Store pending auth request for Flutter
 	pendingAuthRequestsMu.Lock()
 	pendingAuthRequests[r.extensionID] = &PendingAuthRequest{
 		ExtensionID: r.extensionID,
@@ -344,7 +381,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,
@@ -454,13 +491,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,
 		})
 	}

@@ -481,7 +522,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,
 		})
 	}

@@ -64,7 +64,6 @@ func (r *ExtensionRuntime) ffmpegExecute(call goja.FunctionCall) goja.Value {

 	command := call.Arguments[0].String()

-	// Generate unique command ID
 	ffmpegCommandsMu.Lock()
 	ffmpegCommandID++
 	cmdID := fmt.Sprintf("%s_%d", r.extensionID, ffmpegCommandID)
@@ -77,7 +76,6 @@ func (r *ExtensionRuntime) ffmpegExecute(call goja.FunctionCall) goja.Value {

 	GoLog("[Extension:%s] FFmpeg command queued: %s\n", r.extensionID, cmdID)

-	// Wait for completion (with timeout)
 	timeout := 5 * time.Minute
 	start := time.Now()
 	for {
@@ -97,7 +95,6 @@ func (r *ExtensionRuntime) ffmpegExecute(call goja.FunctionCall) goja.Value {
 			}
 			ffmpegCommandsMu.RUnlock()

-			// Cleanup
 			ClearFFmpegCommand(cmdID)
 			return r.vm.ToValue(result)
 		}
@@ -124,7 +121,6 @@ func (r *ExtensionRuntime) ffmpegGetInfo(call goja.FunctionCall) goja.Value {

 	filePath := call.Arguments[0].String()

-	// Use Go's built-in audio quality function
 	quality, err := GetAudioQuality(filePath)
 	if err != nil {
 		return r.vm.ToValue(map[string]interface{}{
@@ -153,7 +149,6 @@ func (r *ExtensionRuntime) ffmpegConvert(call goja.FunctionCall) goja.Value {
 	inputPath := call.Arguments[0].String()
 	outputPath := call.Arguments[1].String()

-	// Get options if provided
 	options := map[string]interface{}{}
 	if len(call.Arguments) > 2 && !goja.IsUndefined(call.Arguments[2]) && !goja.IsNull(call.Arguments[2]) {
 		if opts, ok := call.Arguments[2].Export().(map[string]interface{}); ok {
@@ -161,36 +156,29 @@ func (r *ExtensionRuntime) ffmpegConvert(call goja.FunctionCall) goja.Value {
 		}
 	}

-	// Build FFmpeg command
 	var cmdParts []string
 	cmdParts = append(cmdParts, "-i", fmt.Sprintf("%q", inputPath))

-	// Audio codec
 	if codec, ok := options["codec"].(string); ok {
 		cmdParts = append(cmdParts, "-c:a", codec)
 	}

-	// Bitrate
 	if bitrate, ok := options["bitrate"].(string); ok {
 		cmdParts = append(cmdParts, "-b:a", bitrate)
 	}

-	// Sample rate
 	if sampleRate, ok := options["sample_rate"].(float64); ok {
 		cmdParts = append(cmdParts, "-ar", fmt.Sprintf("%d", int(sampleRate)))
 	}

-	// Channels
 	if channels, ok := options["channels"].(float64); ok {
 		cmdParts = append(cmdParts, "-ac", fmt.Sprintf("%d", int(channels)))
 	}

-	// Overwrite output
 	cmdParts = append(cmdParts, "-y", fmt.Sprintf("%q", outputPath))

 	command := strings.Join(cmdParts, " ")

-	// Execute via ffmpegExecute
 	execCall := goja.FunctionCall{
 		Arguments: []goja.Value{r.vm.ToValue(command)},
 	}
@@ -15,7 +15,6 @@ import (

 // ==================== File API (Sandboxed) ====================

-// List of allowed directories for file operations (set by Go backend for download operations)
 var (
 	allowedDownloadDirs   []string
 	allowedDownloadDirsMu sync.RWMutex
@@ -42,18 +41,40 @@ func isPathInAllowedDirs(absPath string) bool {
 	defer allowedDownloadDirsMu.RUnlock()

 	for _, allowedDir := range allowedDownloadDirs {
-		if strings.HasPrefix(absPath, allowedDir) {
+		if isPathWithinBase(allowedDir, absPath) {
 			return true
 		}
 	}
 	return false
 }

-// validatePath checks if the path is within the extension's sandbox
-// Security: Absolute paths are BLOCKED unless they're in allowed download directories
-// Extensions should use relative paths for their own data storage
+func isPathWithinBase(baseDir, targetPath string) bool {
+	baseAbs, err := filepath.Abs(baseDir)
+	if err != nil {
+		return false
+	}
+	targetAbs, err := filepath.Abs(targetPath)
+	if err != nil {
+		return false
+	}
+
+	rel, err := filepath.Rel(baseAbs, targetAbs)
+	if err != nil {
+		return false
+	}
+	rel = filepath.Clean(rel)
+	if rel == "." {
+		return true
+	}
+
+	prefix := ".." + string(filepath.Separator)
+	if rel == ".." || strings.HasPrefix(rel, prefix) {
+		return false
+	}
+	return true
+}
+
 func (r *ExtensionRuntime) validatePath(path string) (string, error) {
-	// Check if extension has file permission
 	if !r.manifest.Permissions.File {
 		return "", fmt.Errorf("file access denied: extension does not have 'file' permission")
 	}
@@ -81,7 +102,7 @@ func (r *ExtensionRuntime) validatePath(path string) (string, error) {
 	}

 	absDataDir, _ := filepath.Abs(r.dataDir)
-	if !strings.HasPrefix(absPath, absDataDir) {
+	if !isPathWithinBase(absDataDir, absPath) {
 		return "", fmt.Errorf("file access denied: path '%s' is outside sandbox", path)
 	}

@@ -327,7 +348,6 @@ func (r *ExtensionRuntime) fileWrite(call goja.FunctionCall) goja.Value {
 		})
 	}

-	// Create directory if needed
 	dir := filepath.Dir(fullPath)
 	if err := os.MkdirAll(dir, 0755); err != nil {
 		return r.vm.ToValue(map[string]interface{}{
@@ -376,13 +396,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 {
@@ -392,10 +413,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),
 		})
 	}

@@ -14,23 +14,33 @@ import (

 // ==================== HTTP API (Sandboxed) ====================

-// HTTPResponse represents the response from an HTTP request
 type HTTPResponse struct {
 	StatusCode int               `json:"statusCode"`
 	Body       string            `json:"body"`
 	Headers    map[string]string `json:"headers"`
 }

-// validateDomain checks if the domain is allowed by the extension's permissions
 func (r *ExtensionRuntime) validateDomain(urlStr string) error {
 	parsed, err := url.Parse(urlStr)
 	if err != nil {
 		return fmt.Errorf("invalid URL: %w", err)
 	}

-	domain := parsed.Hostname()
+	if parsed.Scheme == "" {
+		return fmt.Errorf("invalid URL: scheme is required")
+	}
+	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 == "" {
+		return fmt.Errorf("invalid URL: hostname is required")
+	}

-	// Block private/local network access (SSRF protection)
 	if isPrivateIP(domain) {
 		return fmt.Errorf("network access denied: private/local network '%s' not allowed", domain)
 	}
@@ -42,7 +52,6 @@ func (r *ExtensionRuntime) validateDomain(urlStr string) error {
 	return nil
 }

-// httpGet performs a GET request (sandboxed)
 func (r *ExtensionRuntime) httpGet(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue(map[string]interface{}{
@@ -76,16 +85,14 @@ func (r *ExtensionRuntime) httpGet(call goja.FunctionCall) goja.Value {
 		})
 	}

-	// Set headers - user headers first
 	for k, v := range headers {
 		req.Header.Set(k, v)
 	}
-	// Only set default User-Agent if not provided by extension
+
 	if req.Header.Get("User-Agent") == "" {
 		req.Header.Set("User-Agent", "Spotiflac-Extension/1.0")
 	}

-	// Execute request
 	resp, err := r.httpClient.Do(req)
 	if err != nil {
 		return r.vm.ToValue(map[string]interface{}{
@@ -101,26 +108,24 @@ func (r *ExtensionRuntime) httpGet(call goja.FunctionCall) goja.Value {
 		})
 	}

-	// Extract response headers - return all values as arrays for multi-value headers (cookies, etc.)
 	respHeaders := make(map[string]interface{})
 	for k, v := range resp.Header {
 		if len(v) == 1 {
 			respHeaders[k] = v[0]
 		} else {
-			respHeaders[k] = v // Return as array if multiple values
+			respHeaders[k] = v
 		}
 	}

 	return r.vm.ToValue(map[string]interface{}{
 		"statusCode": resp.StatusCode,
-		"status":     resp.StatusCode, // Alias for convenience
+		"status":     resp.StatusCode,
 		"ok":         resp.StatusCode >= 200 && resp.StatusCode < 300,
 		"body":       string(body),
 		"headers":    respHeaders,
 	})
 }

-// httpPost performs a POST request (sandboxed)
 func (r *ExtensionRuntime) httpPost(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue(map[string]interface{}{
@@ -137,7 +142,6 @@ func (r *ExtensionRuntime) httpPost(call goja.FunctionCall) goja.Value {
 		})
 	}

-	// Get body if provided - support both string and object
 	var bodyStr string
 	if len(call.Arguments) > 1 && !goja.IsUndefined(call.Arguments[1]) && !goja.IsNull(call.Arguments[1]) {
 		bodyArg := call.Arguments[1].Export()
@@ -145,7 +149,6 @@ func (r *ExtensionRuntime) httpPost(call goja.FunctionCall) goja.Value {
 		case string:
 			bodyStr = v
 		case map[string]interface{}, []interface{}:
-			// Auto-stringify objects and arrays to JSON
 			jsonBytes, err := json.Marshal(v)
 			if err != nil {
 				return r.vm.ToValue(map[string]interface{}{
@@ -154,12 +157,10 @@ func (r *ExtensionRuntime) httpPost(call goja.FunctionCall) goja.Value {
 			}
 			bodyStr = string(jsonBytes)
 		default:
-			// Fallback to string conversion
 			bodyStr = call.Arguments[1].String()
 		}
 	}

-	// Get headers if provided
 	headers := make(map[string]string)
 	if len(call.Arguments) > 2 && !goja.IsUndefined(call.Arguments[2]) && !goja.IsNull(call.Arguments[2]) {
 		headersObj := call.Arguments[2].Export()
@@ -177,11 +178,10 @@ func (r *ExtensionRuntime) httpPost(call goja.FunctionCall) goja.Value {
 		})
 	}

-	// Set headers - user headers first
 	for k, v := range headers {
 		req.Header.Set(k, v)
 	}
-	// Only set defaults if not provided by extension
+
 	if req.Header.Get("User-Agent") == "" {
 		req.Header.Set("User-Agent", "Spotiflac-Extension/1.0")
 	}
@@ -189,7 +189,6 @@ func (r *ExtensionRuntime) httpPost(call goja.FunctionCall) goja.Value {
 		req.Header.Set("Content-Type", "application/json")
 	}

-	// Execute request
 	resp, err := r.httpClient.Do(req)
 	if err != nil {
 		return r.vm.ToValue(map[string]interface{}{
@@ -205,19 +204,18 @@ func (r *ExtensionRuntime) httpPost(call goja.FunctionCall) goja.Value {
 		})
 	}

-	// Extract response headers - return all values as arrays for multi-value headers
 	respHeaders := make(map[string]interface{})
 	for k, v := range resp.Header {
 		if len(v) == 1 {
 			respHeaders[k] = v[0]
 		} else {
-			respHeaders[k] = v // Return as array if multiple values
+			respHeaders[k] = v
 		}
 	}

 	return r.vm.ToValue(map[string]interface{}{
 		"statusCode": resp.StatusCode,
-		"status":     resp.StatusCode, // Alias for convenience
+		"status":     resp.StatusCode,
 		"ok":         resp.StatusCode >= 200 && resp.StatusCode < 300,
 		"body":       string(body),
 		"headers":    respHeaders,
@@ -240,27 +238,22 @@ func (r *ExtensionRuntime) httpRequest(call goja.FunctionCall) goja.Value {
 		})
 	}

-	// Default options
 	method := "GET"
 	var bodyStr string
 	headers := make(map[string]string)

-	// Parse options if provided
 	if len(call.Arguments) > 1 && !goja.IsUndefined(call.Arguments[1]) && !goja.IsNull(call.Arguments[1]) {
 		optionsObj := call.Arguments[1].Export()
 		if opts, ok := optionsObj.(map[string]interface{}); ok {
-			// Get method
 			if m, ok := opts["method"].(string); ok {
 				method = strings.ToUpper(m)
 			}

-			// Get body - support both string and object
 			if bodyArg, ok := opts["body"]; ok && bodyArg != nil {
 				switch v := bodyArg.(type) {
 				case string:
 					bodyStr = v
 				case map[string]interface{}, []interface{}:
-					// Auto-stringify objects and arrays to JSON
 					jsonBytes, err := json.Marshal(v)
 					if err != nil {
 						return r.vm.ToValue(map[string]interface{}{
@@ -273,7 +266,6 @@ func (r *ExtensionRuntime) httpRequest(call goja.FunctionCall) goja.Value {
 				}
 			}

-			// Get headers
 			if h, ok := opts["headers"].(map[string]interface{}); ok {
 				for k, v := range h {
 					headers[k] = fmt.Sprintf("%v", v)
@@ -282,7 +274,6 @@ func (r *ExtensionRuntime) httpRequest(call goja.FunctionCall) goja.Value {
 		}
 	}

-	// Create request
 	var reqBody io.Reader
 	if bodyStr != "" {
 		reqBody = strings.NewReader(bodyStr)
@@ -295,11 +286,10 @@ func (r *ExtensionRuntime) httpRequest(call goja.FunctionCall) goja.Value {
 		})
 	}

-	// Set headers - user headers first
 	for k, v := range headers {
 		req.Header.Set(k, v)
 	}
-	// Only set defaults if not provided by extension
+
 	if req.Header.Get("User-Agent") == "" {
 		req.Header.Set("User-Agent", "Spotiflac-Extension/1.0")
 	}
@@ -307,7 +297,6 @@ func (r *ExtensionRuntime) httpRequest(call goja.FunctionCall) goja.Value {
 		req.Header.Set("Content-Type", "application/json")
 	}

-	// Execute request
 	resp, err := r.httpClient.Do(req)
 	if err != nil {
 		return r.vm.ToValue(map[string]interface{}{
@@ -323,20 +312,18 @@ func (r *ExtensionRuntime) httpRequest(call goja.FunctionCall) goja.Value {
 		})
 	}

-	// Extract response headers - return all values as arrays for multi-value headers
 	respHeaders := make(map[string]interface{})
 	for k, v := range resp.Header {
 		if len(v) == 1 {
 			respHeaders[k] = v[0]
 		} else {
-			respHeaders[k] = v // Return as array if multiple values
+			respHeaders[k] = v
 		}
 	}

-	// Return response with helper properties
 	return r.vm.ToValue(map[string]interface{}{
 		"statusCode": resp.StatusCode,
-		"status":     resp.StatusCode, // Alias for convenience
+		"status":     resp.StatusCode,
 		"ok":         resp.StatusCode >= 200 && resp.StatusCode < 300,
 		"body":       string(body),
 		"headers":    respHeaders,
@@ -347,7 +334,6 @@ func (r *ExtensionRuntime) httpPut(call goja.FunctionCall) goja.Value {
 	return r.httpMethodShortcut("PUT", call)
 }

-// httpDelete performs a DELETE request (shortcut for http.request with method: "DELETE")
 func (r *ExtensionRuntime) httpDelete(call goja.FunctionCall) goja.Value {
 	return r.httpMethodShortcut("DELETE", call)
 }
@@ -356,8 +342,6 @@ func (r *ExtensionRuntime) httpPatch(call goja.FunctionCall) goja.Value {
 	return r.httpMethodShortcut("PATCH", call)
 }

-// httpMethodShortcut is a helper for PUT/DELETE/PATCH shortcuts
-// Signature: http.put(url, body, headers) / http.delete(url, headers) / http.patch(url, body, headers)
 func (r *ExtensionRuntime) httpMethodShortcut(method string, call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue(map[string]interface{}{
@@ -377,9 +361,7 @@ func (r *ExtensionRuntime) httpMethodShortcut(method string, call goja.FunctionC
 	var bodyStr string
 	headers := make(map[string]string)

-	// For DELETE, second arg is headers; for PUT/PATCH, second arg is body
 	if method == "DELETE" {
-		// http.delete(url, headers)
 		if len(call.Arguments) > 1 && !goja.IsUndefined(call.Arguments[1]) && !goja.IsNull(call.Arguments[1]) {
 			headersObj := call.Arguments[1].Export()
 			if h, ok := headersObj.(map[string]interface{}); ok {
@@ -389,7 +371,6 @@ func (r *ExtensionRuntime) httpMethodShortcut(method string, call goja.FunctionC
 			}
 		}
 	} else {
-		// http.put(url, body, headers) / http.patch(url, body, headers)
 		if len(call.Arguments) > 1 && !goja.IsUndefined(call.Arguments[1]) && !goja.IsNull(call.Arguments[1]) {
 			bodyArg := call.Arguments[1].Export()
 			switch v := bodyArg.(type) {
@@ -418,7 +399,6 @@ func (r *ExtensionRuntime) httpMethodShortcut(method string, call goja.FunctionC
 		}
 	}

-	// Create request
 	var reqBody io.Reader
 	if bodyStr != "" {
 		reqBody = strings.NewReader(bodyStr)
@@ -431,7 +411,6 @@ func (r *ExtensionRuntime) httpMethodShortcut(method string, call goja.FunctionC
 		})
 	}

-	// Set headers - user headers first
 	for k, v := range headers {
 		req.Header.Set(k, v)
 	}
@@ -442,7 +421,6 @@ func (r *ExtensionRuntime) httpMethodShortcut(method string, call goja.FunctionC
 		req.Header.Set("Content-Type", "application/json")
 	}

-	// Execute request
 	resp, err := r.httpClient.Do(req)
 	if err != nil {
 		return r.vm.ToValue(map[string]interface{}{
@@ -458,7 +436,6 @@ func (r *ExtensionRuntime) httpMethodShortcut(method string, call goja.FunctionC
 		})
 	}

-	// Extract response headers
 	respHeaders := make(map[string]interface{})
 	for k, v := range resp.Header {
 		if len(v) == 1 {
@@ -9,7 +9,6 @@ import (

 // ==================== Track Matching API ====================

-// matchingCompareStrings compares two strings with fuzzy matching
 func (r *ExtensionRuntime) matchingCompareStrings(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 2 {
 		return r.vm.ToValue(0.0)
@@ -22,12 +21,10 @@ func (r *ExtensionRuntime) matchingCompareStrings(call goja.FunctionCall) goja.V
 		return r.vm.ToValue(1.0)
 	}

-	// Calculate Levenshtein distance-based similarity
 	similarity := calculateStringSimilarity(str1, str2)
 	return r.vm.ToValue(similarity)
 }

-// matchingCompareDuration compares two durations with tolerance
 func (r *ExtensionRuntime) matchingCompareDuration(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 2 {
 		return r.vm.ToValue(false)
@@ -36,8 +33,7 @@ func (r *ExtensionRuntime) matchingCompareDuration(call goja.FunctionCall) goja.
 	dur1 := int(call.Arguments[0].ToInteger())
 	dur2 := int(call.Arguments[1].ToInteger())

-	// Default tolerance: 3 seconds
-	tolerance := 3000 // milliseconds
+	tolerance := 3000
 	if len(call.Arguments) > 2 && !goja.IsUndefined(call.Arguments[2]) {
 		tolerance = int(call.Arguments[2].ToInteger())
 	}
@@ -50,7 +46,6 @@ func (r *ExtensionRuntime) matchingCompareDuration(call goja.FunctionCall) goja.
 	return r.vm.ToValue(diff <= tolerance)
 }

-// matchingNormalizeString normalizes a string for comparison
 func (r *ExtensionRuntime) matchingNormalizeString(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue("")
@@ -61,7 +56,6 @@ func (r *ExtensionRuntime) matchingNormalizeString(call goja.FunctionCall) goja.
 	return r.vm.ToValue(normalized)
 }

-// calculateStringSimilarity calculates similarity between two strings (0-1)
 func calculateStringSimilarity(s1, s2 string) float64 {
 	if len(s1) == 0 && len(s2) == 0 {
 		return 1.0
@@ -70,7 +64,6 @@ func calculateStringSimilarity(s1, s2 string) float64 {
 		return 0.0
 	}

-	// Use Levenshtein distance
 	distance := levenshteinDistance(s1, s2)
 	maxLen := len(s1)
 	if len(s2) > maxLen {
@@ -80,7 +73,6 @@ func calculateStringSimilarity(s1, s2 string) float64 {
 	return 1.0 - float64(distance)/float64(maxLen)
 }

-// levenshteinDistance calculates the Levenshtein distance between two strings
 func levenshteinDistance(s1, s2 string) int {
 	if len(s1) == 0 {
 		return len(s2)
@@ -89,7 +81,6 @@ func levenshteinDistance(s1, s2 string) int {
 		return len(s1)
 	}

-	// Create matrix
 	matrix := make([][]int, len(s1)+1)
 	for i := range matrix {
 		matrix[i] = make([]int, len(s2)+1)
@@ -99,7 +90,6 @@ func levenshteinDistance(s1, s2 string) int {
 		matrix[0][j] = j
 	}

-	// Fill matrix
 	for i := 1; i <= len(s1); i++ {
 		for j := 1; j <= len(s2); j++ {
 			cost := 1
@@ -107,9 +97,9 @@ func levenshteinDistance(s1, s2 string) int {
 				cost = 0
 			}
 			matrix[i][j] = min(
-				matrix[i-1][j]+1,      // deletion
-				matrix[i][j-1]+1,      // insertion
-				matrix[i-1][j-1]+cost, // substitution
+				matrix[i-1][j]+1,
+				matrix[i][j-1]+1,
+				matrix[i-1][j-1]+cost,
 			)
 		}
 	}
@@ -117,12 +107,9 @@ func levenshteinDistance(s1, s2 string) int {
 	return matrix[len(s1)][len(s2)]
 }

-// normalizeStringForMatching normalizes a string for comparison
 func normalizeStringForMatching(s string) string {
-	// Convert to lowercase
 	s = strings.ToLower(s)

-	// Remove common suffixes/prefixes
 	suffixes := []string{
 		" (remastered)", " (remaster)", " - remastered", " - remaster",
 		" (deluxe)", " (deluxe edition)", " - deluxe", " - deluxe edition",
@@ -136,7 +123,6 @@ func normalizeStringForMatching(s string) string {
 		}
 	}

-	// Remove special characters
 	var result strings.Builder
 	for _, r := range s {
 		if (r >= 'a' && r <= 'z') || (r >= '0' && r <= '9') || r == ' ' {
@@ -144,7 +130,6 @@ func normalizeStringForMatching(s string) string {
 		}
 	}

-	// Collapse multiple spaces
 	s = strings.Join(strings.Fields(result.String()), " ")

 	return strings.TrimSpace(s)
@@ -25,14 +25,11 @@ func (r *ExtensionRuntime) fetchPolyfill(call goja.FunctionCall) goja.Value {
 	}

 	urlStr := call.Arguments[0].String()
-
-	// Validate domain
 	if err := r.validateDomain(urlStr); err != nil {
 		GoLog("[Extension:%s] fetch blocked: %v\n", r.extensionID, err)
 		return r.createFetchError(err.Error())
 	}

-	// Parse options
 	method := "GET"
 	var bodyStr string
 	headers := make(map[string]string)
@@ -40,7 +37,6 @@ func (r *ExtensionRuntime) fetchPolyfill(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) > 1 && !goja.IsUndefined(call.Arguments[1]) && !goja.IsNull(call.Arguments[1]) {
 		optionsObj := call.Arguments[1].Export()
 		if opts, ok := optionsObj.(map[string]interface{}); ok {
-			// Method
 			if m, ok := opts["method"].(string); ok {
 				method = strings.ToUpper(m)
 			}
@@ -61,7 +57,6 @@ func (r *ExtensionRuntime) fetchPolyfill(call goja.FunctionCall) goja.Value {
 				}
 			}

-			// Headers
 			if h, ok := opts["headers"]; ok && h != nil {
 				switch hv := h.(type) {
 				case map[string]interface{}:
@@ -73,7 +68,6 @@ func (r *ExtensionRuntime) fetchPolyfill(call goja.FunctionCall) goja.Value {
 		}
 	}

-	// Create HTTP request
 	var reqBody io.Reader
 	if bodyStr != "" {
 		reqBody = strings.NewReader(bodyStr)
@@ -84,11 +78,9 @@ func (r *ExtensionRuntime) fetchPolyfill(call goja.FunctionCall) goja.Value {
 		return r.createFetchError(err.Error())
 	}

-	// Set headers - user headers first
 	for k, v := range headers {
 		req.Header.Set(k, v)
 	}
-	// Set defaults if not provided
 	if req.Header.Get("User-Agent") == "" {
 		req.Header.Set("User-Agent", "SpotiFLAC-Extension/1.0")
 	}
@@ -96,20 +88,17 @@ func (r *ExtensionRuntime) fetchPolyfill(call goja.FunctionCall) goja.Value {
 		req.Header.Set("Content-Type", "application/json")
 	}

-	// Execute request
 	resp, err := r.httpClient.Do(req)
 	if err != nil {
 		return r.createFetchError(err.Error())
 	}
 	defer resp.Body.Close()

-	// Read body
 	body, err := io.ReadAll(resp.Body)
 	if err != nil {
 		return r.createFetchError(err.Error())
 	}

-	// Extract response headers
 	respHeaders := make(map[string]interface{})
 	for k, v := range resp.Header {
 		if len(v) == 1 {
@@ -119,7 +108,6 @@ func (r *ExtensionRuntime) fetchPolyfill(call goja.FunctionCall) goja.Value {
 		}
 	}

-	// Create Response object (browser-compatible)
 	responseObj := r.vm.NewObject()
 	responseObj.Set("ok", resp.StatusCode >= 200 && resp.StatusCode < 300)
 	responseObj.Set("status", resp.StatusCode)
@@ -127,15 +115,12 @@ func (r *ExtensionRuntime) fetchPolyfill(call goja.FunctionCall) goja.Value {
 	responseObj.Set("headers", respHeaders)
 	responseObj.Set("url", urlStr)

-	// Store body for methods
 	bodyString := string(body)

-	// text() method - returns body as string
 	responseObj.Set("text", func(call goja.FunctionCall) goja.Value {
 		return r.vm.ToValue(bodyString)
 	})

-	// json() method - parses body as JSON
 	responseObj.Set("json", func(call goja.FunctionCall) goja.Value {
 		var result interface{}
 		if err := json.Unmarshal(body, &result); err != nil {
@@ -145,9 +130,7 @@ func (r *ExtensionRuntime) fetchPolyfill(call goja.FunctionCall) goja.Value {
 		return r.vm.ToValue(result)
 	})

-	// arrayBuffer() method - returns body as array (simplified)
 	responseObj.Set("arrayBuffer", func(call goja.FunctionCall) goja.Value {
-		// Return as array of bytes
 		byteArray := make([]interface{}, len(body))
 		for i, b := range body {
 			byteArray[i] = int(b)
@@ -182,7 +165,6 @@ func (r *ExtensionRuntime) atobPolyfill(call goja.FunctionCall) goja.Value {
 	input := call.Arguments[0].String()
 	decoded, err := base64.StdEncoding.DecodeString(input)
 	if err != nil {
-		// Try URL-safe base64
 		decoded, err = base64.URLEncoding.DecodeString(input)
 		if err != nil {
 			GoLog("[Extension:%s] atob decode error: %v\n", r.extensionID, err)
@@ -203,12 +185,10 @@ func (r *ExtensionRuntime) btoaPolyfill(call goja.FunctionCall) goja.Value {

 // registerTextEncoderDecoder registers TextEncoder and TextDecoder classes
 func (r *ExtensionRuntime) registerTextEncoderDecoder(vm *goja.Runtime) {
-	// TextEncoder constructor
 	vm.Set("TextEncoder", func(call goja.ConstructorCall) *goja.Object {
 		encoder := call.This
 		encoder.Set("encoding", "utf-8")

-		// encode() method - string to Uint8Array
 		encoder.Set("encode", func(call goja.FunctionCall) goja.Value {
 			if len(call.Arguments) < 1 {
 				return vm.ToValue([]byte{})
@@ -216,7 +196,6 @@ func (r *ExtensionRuntime) registerTextEncoderDecoder(vm *goja.Runtime) {
 			input := call.Arguments[0].String()
 			bytes := []byte(input)

-			// Return as array (Uint8Array-like)
 			result := make([]interface{}, len(bytes))
 			for i, b := range bytes {
 				result[i] = int(b)
@@ -224,7 +203,6 @@ func (r *ExtensionRuntime) registerTextEncoderDecoder(vm *goja.Runtime) {
 			return vm.ToValue(result)
 		})

-		// encodeInto() method
 		encoder.Set("encodeInto", func(call goja.FunctionCall) goja.Value {
 			// Simplified implementation
 			if len(call.Arguments) < 2 {
@@ -240,11 +218,9 @@ func (r *ExtensionRuntime) registerTextEncoderDecoder(vm *goja.Runtime) {
 		return nil
 	})

-	// TextDecoder constructor
 	vm.Set("TextDecoder", func(call goja.ConstructorCall) *goja.Object {
 		decoder := call.This

-		// Get encoding from arguments (default: utf-8)
 		encoding := "utf-8"
 		if len(call.Arguments) > 0 && !goja.IsUndefined(call.Arguments[0]) {
 			encoding = call.Arguments[0].String()
@@ -253,13 +229,11 @@ func (r *ExtensionRuntime) registerTextEncoderDecoder(vm *goja.Runtime) {
 		decoder.Set("fatal", false)
 		decoder.Set("ignoreBOM", false)

-		// decode() method - Uint8Array to string
 		decoder.Set("decode", func(call goja.FunctionCall) goja.Value {
 			if len(call.Arguments) < 1 {
 				return vm.ToValue("")
 			}

-			// Handle different input types
 			input := call.Arguments[0].Export()
 			var bytes []byte

@@ -279,7 +253,6 @@ func (r *ExtensionRuntime) registerTextEncoderDecoder(vm *goja.Runtime) {
 					}
 				}
 			case string:
-				// Already a string, just return it
 				return vm.ToValue(v)
 			default:
 				return vm.ToValue("")
@@ -292,7 +265,6 @@ func (r *ExtensionRuntime) registerTextEncoderDecoder(vm *goja.Runtime) {
 	})
 }

-// registerURLClass registers the URL class for URL parsing
 func (r *ExtensionRuntime) registerURLClass(vm *goja.Runtime) {
 	vm.Set("URL", func(call goja.ConstructorCall) *goja.Object {
 		urlObj := call.This
@@ -304,7 +276,6 @@ func (r *ExtensionRuntime) registerURLClass(vm *goja.Runtime) {

 		urlStr := call.Arguments[0].String()

-		// Handle relative URLs with base
 		if len(call.Arguments) > 1 && !goja.IsUndefined(call.Arguments[1]) {
 			baseStr := call.Arguments[1].String()
 			baseURL, err := url.Parse(baseStr)
@@ -322,7 +293,6 @@ func (r *ExtensionRuntime) registerURLClass(vm *goja.Runtime) {
 			return nil
 		}

-		// Set URL properties
 		urlObj.Set("href", parsed.String())
 		urlObj.Set("protocol", parsed.Scheme+":")
 		urlObj.Set("host", parsed.Host)
@@ -342,10 +312,9 @@ func (r *ExtensionRuntime) registerURLClass(vm *goja.Runtime) {
 		password, _ := parsed.User.Password()
 		urlObj.Set("password", password)

-		// searchParams object
-		searchParams := vm.NewObject()
 		queryValues := parsed.Query()

+		searchParams := vm.NewObject()
 		searchParams.Set("get", func(call goja.FunctionCall) goja.Value {
 			if len(call.Arguments) < 1 {
 				return goja.Null()
@@ -379,12 +348,10 @@ func (r *ExtensionRuntime) registerURLClass(vm *goja.Runtime) {

 		urlObj.Set("searchParams", searchParams)

-		// toString method
 		urlObj.Set("toString", func(call goja.FunctionCall) goja.Value {
 			return vm.ToValue(parsed.String())
 		})

-		// toJSON method
 		urlObj.Set("toJSON", func(call goja.FunctionCall) goja.Value {
 			return vm.ToValue(parsed.String())
 		})
@@ -392,17 +359,14 @@ func (r *ExtensionRuntime) registerURLClass(vm *goja.Runtime) {
 		return nil
 	})

-	// URLSearchParams constructor
 	vm.Set("URLSearchParams", func(call goja.ConstructorCall) *goja.Object {
 		paramsObj := call.This
 		values := url.Values{}

-		// Parse initial value if provided
 		if len(call.Arguments) > 0 && !goja.IsUndefined(call.Arguments[0]) {
 			init := call.Arguments[0].Export()
 			switch v := init.(type) {
 			case string:
-				// Parse query string
 				parsed, _ := url.ParseQuery(strings.TrimPrefix(v, "?"))
 				values = parsed
 			case map[string]interface{}:
@@ -468,10 +432,6 @@ func (r *ExtensionRuntime) registerURLClass(vm *goja.Runtime) {
 // registerJSONGlobal ensures JSON global is properly set up
 func (r *ExtensionRuntime) registerJSONGlobal(vm *goja.Runtime) {
 	// JSON is already built-in to Goja, but we can enhance it
-	// This ensures JSON.parse and JSON.stringify work as expected
-
-	// The built-in JSON object should already work, but let's verify
-	// and add any missing functionality if needed
 	jsonScript := `
 		if (typeof JSON === 'undefined') {
 			var JSON = {
@@ -11,48 +11,166 @@ import (
 	"io"
 	"os"
 	"path/filepath"
+	"reflect"
+	"time"

 	"github.com/dop251/goja"
 )

 // ==================== Storage API ====================

-// getStoragePath returns the path to the extension's storage file
+const (
+	defaultStorageFlushDelay = 400 * time.Millisecond
+	storageFlushRetryDelay   = 2 * time.Second
+)
+
 func (r *ExtensionRuntime) getStoragePath() string {
 	return filepath.Join(r.dataDir, "storage.json")
 }

-// loadStorage loads the storage data from disk
-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
 }

-// saveStorage saves the storage data to disk
-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()
 }

-// storageGet retrieves a value from storage
 func (r *ExtensionRuntime) storageGet(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return goja.Undefined()
@@ -60,15 +178,15 @@ 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 {
-		// Return default value if provided
 		if len(call.Arguments) > 1 {
 			return call.Arguments[1]
 		}
@@ -78,7 +196,6 @@ func (r *ExtensionRuntime) storageGet(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(value)
 }

-// storageSet stores a value in storage
 func (r *ExtensionRuntime) storageSet(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 2 {
 		return r.vm.ToValue(false)
@@ -87,23 +204,30 @@ 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)
 }

-// storageRemove removes a value from storage
 func (r *ExtensionRuntime) storageRemove(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue(false)
@@ -111,35 +235,36 @@ 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)
 }

-// ==================== Credentials API (Encrypted Storage) ====================
-
-// getCredentialsPath returns the path to the extension's encrypted credentials file
 func (r *ExtensionRuntime) getCredentialsPath() string {
 	return filepath.Join(r.dataDir, ".credentials.enc")
 }

-// getSaltPath returns the path to the extension's encryption salt file
 func (r *ExtensionRuntime) getSaltPath() string {
 	return filepath.Join(r.dataDir, ".cred_salt")
 }

-// getOrCreateSalt gets existing salt or creates a new random one
 func (r *ExtensionRuntime) getOrCreateSalt() ([]byte, error) {
 	saltPath := r.getSaltPath()

@@ -160,51 +285,74 @@ func (r *ExtensionRuntime) getOrCreateSalt() ([]byte, error) {
 	return salt, nil
 }

-// getEncryptionKey derives an encryption key from extension ID + random salt
 func (r *ExtensionRuntime) getEncryptionKey() ([]byte, error) {
-	// Get or create per-installation random salt
 	salt, err := r.getOrCreateSalt()
 	if err != nil {
 		return nil, err
 	}

-	// Combine extension ID + random salt for key derivation
-	// This makes each installation unique, preventing mass decryption attacks
 	combined := append([]byte(r.extensionID), salt...)
 	hash := sha256.Sum256(combined)
 	return hash[:], nil
 }

-// loadCredentials loads and decrypts credentials from disk
-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
 	}

-	// Decrypt the data
 	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
 }

-// saveCredentials encrypts and saves credentials to disk
 func (r *ExtensionRuntime) saveCredentials(creds map[string]interface{}) error {
 	data, err := json.Marshal(creds)
 	if err != nil {
@@ -221,10 +369,17 @@ func (r *ExtensionRuntime) saveCredentials(creds map[string]interface{}) error {
 	}

 	credPath := r.getCredentialsPath()
-	return os.WriteFile(credPath, encrypted, 0600) // Restrictive permissions
+	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
 }

-// credentialsStore stores an encrypted credential
 func (r *ExtensionRuntime) credentialsStore(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 2 {
 		return r.vm.ToValue(map[string]interface{}{
@@ -236,8 +391,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,
@@ -245,9 +399,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,
@@ -260,7 +417,6 @@ func (r *ExtensionRuntime) credentialsStore(call goja.FunctionCall) goja.Value {
 	})
 }

-// credentialsGet retrieves a decrypted credential
 func (r *ExtensionRuntime) credentialsGet(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return goja.Undefined()
@@ -268,15 +424,15 @@ 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 {
-		// Return default value if provided
 		if len(call.Arguments) > 1 {
 			return call.Arguments[1]
 		}
@@ -286,7 +442,6 @@ func (r *ExtensionRuntime) credentialsGet(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(value)
 }

-// credentialsRemove removes a credential
 func (r *ExtensionRuntime) credentialsRemove(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue(false)
@@ -294,15 +449,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)
 	}
@@ -310,7 +467,6 @@ func (r *ExtensionRuntime) credentialsRemove(call goja.FunctionCall) goja.Value
 	return r.vm.ToValue(true)
 }

-// credentialsHas checks if a credential exists
 func (r *ExtensionRuntime) credentialsHas(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue(false)
@@ -318,18 +474,16 @@ 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)
 }

-// ==================== Crypto Utilities ====================
-
-// encryptAES encrypts data using AES-GCM
 func encryptAES(plaintext []byte, key []byte) ([]byte, error) {
 	block, err := aes.NewCipher(key)
 	if err != nil {
@@ -350,7 +504,6 @@ func encryptAES(plaintext []byte, key []byte) ([]byte, error) {
 	return ciphertext, nil
 }

-// decryptAES decrypts data using AES-GCM
 func decryptAES(ciphertext []byte, key []byte) ([]byte, error) {
 	block, err := aes.NewCipher(key)
 	if err != nil {
@@ -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"])
+	}
+}
@@ -19,7 +19,6 @@ import (

 // ==================== Utility Functions ====================

-// base64Encode encodes a string to base64
 func (r *ExtensionRuntime) base64Encode(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue("")
@@ -28,7 +27,6 @@ func (r *ExtensionRuntime) base64Encode(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(base64.StdEncoding.EncodeToString([]byte(input)))
 }

-// base64Decode decodes a base64 string
 func (r *ExtensionRuntime) base64Decode(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue("")
@@ -41,7 +39,6 @@ func (r *ExtensionRuntime) base64Decode(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(string(decoded))
 }

-// md5Hash computes MD5 hash of a string
 func (r *ExtensionRuntime) md5Hash(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue("")
@@ -51,7 +48,6 @@ func (r *ExtensionRuntime) md5Hash(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(hex.EncodeToString(hash[:]))
 }

-// sha256Hash computes SHA256 hash of a string
 func (r *ExtensionRuntime) sha256Hash(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue("")
@@ -61,7 +57,6 @@ func (r *ExtensionRuntime) sha256Hash(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(hex.EncodeToString(hash[:]))
 }

-// hmacSHA256 computes HMAC-SHA256 of a message with a key
 func (r *ExtensionRuntime) hmacSHA256(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 2 {
 		return r.vm.ToValue("")
@@ -74,7 +69,6 @@ func (r *ExtensionRuntime) hmacSHA256(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(hex.EncodeToString(mac.Sum(nil)))
 }

-// hmacSHA256Base64 computes HMAC-SHA256 and returns base64 encoded result
 func (r *ExtensionRuntime) hmacSHA256Base64(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 2 {
 		return r.vm.ToValue("")
@@ -87,9 +81,6 @@ func (r *ExtensionRuntime) hmacSHA256Base64(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(base64.StdEncoding.EncodeToString(mac.Sum(nil)))
 }

-// hmacSHA1 computes HMAC-SHA1 of a message with a key (for TOTP)
-// Arguments: message (string or array of bytes), key (string or array of bytes)
-// Returns: array of bytes (for TOTP dynamic truncation)
 func (r *ExtensionRuntime) hmacSHA1(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 2 {
 		return r.vm.ToValue([]byte{})
@@ -142,7 +133,6 @@ func (r *ExtensionRuntime) hmacSHA1(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(jsArray)
 }

-// parseJSON parses a JSON string
 func (r *ExtensionRuntime) parseJSON(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return goja.Undefined()
@@ -158,7 +148,6 @@ func (r *ExtensionRuntime) parseJSON(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(result)
 }

-// stringifyJSON converts a value to JSON string
 func (r *ExtensionRuntime) stringifyJSON(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue("")
@@ -174,9 +163,6 @@ func (r *ExtensionRuntime) stringifyJSON(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(string(data))
 }

-// ==================== Crypto Utilities for Extensions ====================
-
-// cryptoEncrypt encrypts a string using AES-GCM (for extension use)
 func (r *ExtensionRuntime) cryptoEncrypt(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 2 {
 		return r.vm.ToValue(map[string]interface{}{
@@ -188,7 +174,6 @@ func (r *ExtensionRuntime) cryptoEncrypt(call goja.FunctionCall) goja.Value {
 	plaintext := call.Arguments[0].String()
 	keyStr := call.Arguments[1].String()

-	// Derive 32-byte key from provided key string
 	keyHash := sha256.Sum256([]byte(keyStr))

 	encrypted, err := encryptAES([]byte(plaintext), keyHash[:])
@@ -205,7 +190,6 @@ func (r *ExtensionRuntime) cryptoEncrypt(call goja.FunctionCall) goja.Value {
 	})
 }

-// cryptoDecrypt decrypts a string using AES-GCM (for extension use)
 func (r *ExtensionRuntime) cryptoDecrypt(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 2 {
 		return r.vm.ToValue(map[string]interface{}{
@@ -225,14 +209,13 @@ func (r *ExtensionRuntime) cryptoDecrypt(call goja.FunctionCall) goja.Value {
 		})
 	}

-	// Derive 32-byte key from provided key string
 	keyHash := sha256.Sum256([]byte(keyStr))

 	decrypted, err := decryptAES(ciphertext, keyHash[:])
 	if err != nil {
 		return r.vm.ToValue(map[string]interface{}{
 			"success": false,
-			"error":   err.Error(),
+			"error":   "invalid base64 ciphertext",
 		})
 	}

@@ -242,9 +225,8 @@ func (r *ExtensionRuntime) cryptoDecrypt(call goja.FunctionCall) goja.Value {
 	})
 }

-// cryptoGenerateKey generates a random encryption key
 func (r *ExtensionRuntime) cryptoGenerateKey(call goja.FunctionCall) goja.Value {
-	length := 32 // Default 256-bit key
+	length := 32
 	if len(call.Arguments) > 0 && !goja.IsUndefined(call.Arguments[0]) {
 		if l, ok := call.Arguments[0].Export().(float64); ok {
 			length = int(l)
@@ -266,13 +248,10 @@ func (r *ExtensionRuntime) cryptoGenerateKey(call goja.FunctionCall) goja.Value
 	})
 }

-// randomUserAgent returns a random Chrome User-Agent string
 func (r *ExtensionRuntime) randomUserAgent(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(getRandomUserAgent())
 }

-// ==================== Logging Functions ====================
-
 func (r *ExtensionRuntime) logDebug(call goja.FunctionCall) goja.Value {
 	msg := r.formatLogArgs(call.Arguments)
 	GoLog("[Extension:%s:DEBUG] %s\n", r.extensionID, msg)
@@ -305,8 +284,6 @@ func (r *ExtensionRuntime) formatLogArgs(args []goja.Value) string {
 	return strings.Join(parts, " ")
 }

-// ==================== Go Backend Wrappers ====================
-
 func (r *ExtensionRuntime) sanitizeFilenameWrapper(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue("")
@@ -315,7 +292,6 @@ func (r *ExtensionRuntime) sanitizeFilenameWrapper(call goja.FunctionCall) goja.
 	return r.vm.ToValue(sanitizeFilename(input))
 }

-// RegisterGoBackendAPIs adds more Go backend functions to the VM
 func (r *ExtensionRuntime) RegisterGoBackendAPIs(vm *goja.Runtime) {
 	gobackendObj := vm.Get("gobackend")
 	if gobackendObj == nil || goja.IsUndefined(gobackendObj) {
@@ -325,7 +301,6 @@ func (r *ExtensionRuntime) RegisterGoBackendAPIs(vm *goja.Runtime) {

 	obj := gobackendObj.(*goja.Object)

-	// Expose sanitizeFilename
 	obj.Set("sanitizeFilename", func(call goja.FunctionCall) goja.Value {
 		if len(call.Arguments) < 1 {
 			return vm.ToValue("")
@@ -333,7 +308,6 @@ func (r *ExtensionRuntime) RegisterGoBackendAPIs(vm *goja.Runtime) {
 		return vm.ToValue(sanitizeFilename(call.Arguments[0].String()))
 	})

-	// Expose getAudioQuality
 	obj.Set("getAudioQuality", func(call goja.FunctionCall) goja.Value {
 		if len(call.Arguments) < 1 {
 			return vm.ToValue(map[string]interface{}{
@@ -356,7 +330,6 @@ func (r *ExtensionRuntime) RegisterGoBackendAPIs(vm *goja.Runtime) {
 		})
 	})

-	// Expose buildFilename
 	obj.Set("buildFilename", func(call goja.FunctionCall) goja.Value {
 		if len(call.Arguments) < 2 {
 			return vm.ToValue("")
@@ -373,7 +346,6 @@ func (r *ExtensionRuntime) RegisterGoBackendAPIs(vm *goja.Runtime) {
 		return vm.ToValue(buildFilenameFromTemplate(template, metadata))
 	})

-	// Expose getLocalTime - returns device local time info
 	obj.Set("getLocalTime", func(call goja.FunctionCall) goja.Value {
 		now := time.Now()
 		_, offsetSeconds := now.Zone()
@@ -9,20 +9,17 @@ import (
 	"sync"
 )

-// ExtensionSettingsStore manages settings for all extensions
 type ExtensionSettingsStore struct {
 	mu       sync.RWMutex
 	dataDir  string
 	settings map[string]map[string]interface{} // extensionID -> settings
 }

-// Global settings store
 var (
 	globalSettingsStore     *ExtensionSettingsStore
 	globalSettingsStoreOnce sync.Once
 )

-// GetExtensionSettingsStore returns the global settings store
 func GetExtensionSettingsStore() *ExtensionSettingsStore {
 	globalSettingsStoreOnce.Do(func() {
 		globalSettingsStore = &ExtensionSettingsStore{
@@ -32,7 +29,6 @@ func GetExtensionSettingsStore() *ExtensionSettingsStore {
 	return globalSettingsStore
 }

-// SetDataDir sets the data directory for settings storage
 func (s *ExtensionSettingsStore) SetDataDir(dataDir string) error {
 	s.mu.Lock()
 	defer s.mu.Unlock()
@@ -45,12 +41,10 @@ func (s *ExtensionSettingsStore) SetDataDir(dataDir string) error {
 	return s.loadAllSettings()
 }

-// getSettingsPath returns the path to an extension's settings file
 func (s *ExtensionSettingsStore) getSettingsPath(extensionID string) string {
 	return filepath.Join(s.dataDir, extensionID, "settings.json")
 }

-// loadAllSettings loads settings for all extensions from disk
 func (s *ExtensionSettingsStore) loadAllSettings() error {
 	entries, err := os.ReadDir(s.dataDir)
 	if err != nil {
@@ -75,7 +69,6 @@ func (s *ExtensionSettingsStore) loadAllSettings() error {
 	return nil
 }

-// loadSettings loads settings for a specific extension
 func (s *ExtensionSettingsStore) loadSettings(extensionID string) (map[string]interface{}, error) {
 	settingsPath := s.getSettingsPath(extensionID)
 	data, err := os.ReadFile(settingsPath)
@@ -94,7 +87,6 @@ func (s *ExtensionSettingsStore) loadSettings(extensionID string) (map[string]in
 	return settings, nil
 }

-// saveSettings saves settings for a specific extension
 func (s *ExtensionSettingsStore) saveSettings(extensionID string, settings map[string]interface{}) error {
 	settingsPath := s.getSettingsPath(extensionID)

@@ -111,8 +103,6 @@ func (s *ExtensionSettingsStore) saveSettings(extensionID string, settings map[s
 	return os.WriteFile(settingsPath, data, 0644)
 }

-// Get retrieves a setting value for an extension
-// Returns error if extension or key not found (gomobile compatible)
 func (s *ExtensionSettingsStore) Get(extensionID, key string) (interface{}, error) {
 	s.mu.RLock()
 	defer s.mu.RUnlock()
@@ -129,7 +119,6 @@ func (s *ExtensionSettingsStore) Get(extensionID, key string) (interface{}, erro
 	return value, nil
 }

-// GetAll retrieves all settings for an extension
 func (s *ExtensionSettingsStore) GetAll(extensionID string) map[string]interface{} {
 	s.mu.RLock()
 	defer s.mu.RUnlock()
@@ -139,7 +128,6 @@ func (s *ExtensionSettingsStore) GetAll(extensionID string) map[string]interface
 		return make(map[string]interface{})
 	}

-	// Return a copy
 	result := make(map[string]interface{})
 	for k, v := range extSettings {
 		result[k] = v
@@ -147,7 +135,6 @@ func (s *ExtensionSettingsStore) GetAll(extensionID string) map[string]interface
 	return result
 }

-// Set stores a setting value for an extension
 func (s *ExtensionSettingsStore) Set(extensionID, key string, value interface{}) error {
 	s.mu.Lock()
 	defer s.mu.Unlock()
@@ -161,18 +148,15 @@ func (s *ExtensionSettingsStore) Set(extensionID, key string, value interface{})
 	return s.saveSettings(extensionID, s.settings[extensionID])
 }

-// SetAll stores all settings for an extension
 func (s *ExtensionSettingsStore) SetAll(extensionID string, settings map[string]interface{}) error {
 	s.mu.Lock()
 	defer s.mu.Unlock()

 	s.settings[extensionID] = settings

-	// Persist to disk
 	return s.saveSettings(extensionID, settings)
 }

-// Remove removes a setting for an extension
 func (s *ExtensionSettingsStore) Remove(extensionID, key string) error {
 	s.mu.Lock()
 	defer s.mu.Unlock()
@@ -184,11 +168,9 @@ func (s *ExtensionSettingsStore) Remove(extensionID, key string) error {

 	delete(extSettings, key)

-	// Persist to disk
 	return s.saveSettings(extensionID, extSettings)
 }

-// RemoveAll removes all settings for an extension
 func (s *ExtensionSettingsStore) RemoveAll(extensionID string) error {
 	s.mu.Lock()
 	defer s.mu.Unlock()
@@ -203,7 +185,6 @@ func (s *ExtensionSettingsStore) RemoveAll(extensionID string) error {
 	return nil
 }

-// GetAllExtensionSettings returns settings for all extensions as JSON
 func (s *ExtensionSettingsStore) GetAllExtensionSettingsJSON() (string, error) {
 	s.mu.RLock()
 	defer s.mu.RUnlock()
@@ -5,13 +5,13 @@ import (
 	"fmt"
 	"io"
 	"net/http"
+	"net/url"
 	"os"
 	"path/filepath"
 	"sync"
 	"time"
 )

-// Extension categories
 const (
 	CategoryMetadata    = "metadata"
 	CategoryDownload    = "download"
@@ -20,28 +20,26 @@ const (
 	CategoryIntegration = "integration"
 )

-// StoreExtension represents an extension in the store
 type StoreExtension struct {
-	ID            string   `json:"id"`
-	Name          string   `json:"name"`
-	DisplayName   string   `json:"display_name,omitempty"`
-	Version       string   `json:"version"`
-	Author        string   `json:"author"`
-	Description   string   `json:"description"`
-	DownloadURL   string   `json:"download_url,omitempty"`
-	IconURL       string   `json:"icon_url,omitempty"`
-	Category      string   `json:"category"`
-	Tags          []string `json:"tags,omitempty"`
-	Downloads     int      `json:"downloads"`
-	UpdatedAt     string   `json:"updated_at"`
-	MinAppVersion string   `json:"min_app_version,omitempty"`
-	DisplayNameAlt   string `json:"displayName,omitempty"`
-	DownloadURLAlt   string `json:"downloadUrl,omitempty"`
-	IconURLAlt       string `json:"iconUrl,omitempty"`
-	MinAppVersionAlt string `json:"minAppVersion,omitempty"`
+	ID               string   `json:"id"`
+	Name             string   `json:"name"`
+	DisplayName      string   `json:"display_name,omitempty"`
+	Version          string   `json:"version"`
+	Author           string   `json:"author"`
+	Description      string   `json:"description"`
+	DownloadURL      string   `json:"download_url,omitempty"`
+	IconURL          string   `json:"icon_url,omitempty"`
+	Category         string   `json:"category"`
+	Tags             []string `json:"tags,omitempty"`
+	Downloads        int      `json:"downloads"`
+	UpdatedAt        string   `json:"updated_at"`
+	MinAppVersion    string   `json:"min_app_version,omitempty"`
+	DisplayNameAlt   string   `json:"displayName,omitempty"`
+	DownloadURLAlt   string   `json:"downloadUrl,omitempty"`
+	IconURLAlt       string   `json:"iconUrl,omitempty"`
+	MinAppVersionAlt string   `json:"minAppVersion,omitempty"`
 }

-// getDisplayName returns display name, falling back to name (private to avoid gomobile conflict)
 func (e *StoreExtension) getDisplayName() string {
 	if e.DisplayName != "" {
 		return e.DisplayName
@@ -52,7 +50,6 @@ func (e *StoreExtension) getDisplayName() string {
 	return e.Name
 }

-// getDownloadURL returns download URL from either field (private to avoid gomobile conflict)
 func (e *StoreExtension) getDownloadURL() string {
 	if e.DownloadURL != "" {
 		return e.DownloadURL
@@ -60,7 +57,6 @@ func (e *StoreExtension) getDownloadURL() string {
 	return e.DownloadURLAlt
 }

-// getIconURL returns icon URL from either field (private to avoid gomobile conflict)
 func (e *StoreExtension) getIconURL() string {
 	if e.IconURL != "" {
 		return e.IconURL
@@ -68,7 +64,6 @@ func (e *StoreExtension) getIconURL() string {
 	return e.IconURLAlt
 }

-// getMinAppVersion returns min app version from either field (private to avoid gomobile conflict)
 func (e *StoreExtension) getMinAppVersion() string {
 	if e.MinAppVersion != "" {
 		return e.MinAppVersion
@@ -76,14 +71,12 @@ func (e *StoreExtension) getMinAppVersion() string {
 	return e.MinAppVersionAlt
 }

-// StoreRegistry represents the extension registry
 type StoreRegistry struct {
 	Version    int              `json:"version"`
 	UpdatedAt  string           `json:"updated_at"`
 	Extensions []StoreExtension `json:"extensions"`
 }

-// StoreExtensionResponse is the normalized response sent to Flutter
 type StoreExtensionResponse struct {
 	ID               string   `json:"id"`
 	Name             string   `json:"name"`
@@ -103,7 +96,6 @@ type StoreExtensionResponse struct {
 	HasUpdate        bool     `json:"has_update"`
 }

-// ToResponse converts StoreExtension to normalized response
 func (e *StoreExtension) ToResponse() StoreExtensionResponse {
 	return StoreExtensionResponse{
 		ID:            e.ID,
@@ -122,7 +114,6 @@ func (e *StoreExtension) ToResponse() StoreExtensionResponse {
 	}
 }

-// ExtensionStore manages the extension store
 type ExtensionStore struct {
 	registryURL string
 	cacheDir    string
@@ -143,7 +134,6 @@ const (
 	cacheFileName      = "store_cache.json"
 )

-// InitExtensionStore initializes the extension store
 func InitExtensionStore(cacheDir string) *ExtensionStore {
 	extensionStoreMu.Lock()
 	defer extensionStoreMu.Unlock()
@@ -154,20 +144,17 @@ func InitExtensionStore(cacheDir string) *ExtensionStore {
 			cacheDir:    cacheDir,
 			cacheTTL:    cacheTTL,
 		}
-		// Try to load from disk cache
 		extensionStore.loadDiskCache()
 	}
 	return extensionStore
 }

-// GetExtensionStore returns the singleton store instance
 func GetExtensionStore() *ExtensionStore {
 	extensionStoreMu.Lock()
 	defer extensionStoreMu.Unlock()
 	return extensionStore
 }

-// loadDiskCache loads cached registry from disk
 func (s *ExtensionStore) loadDiskCache() {
 	if s.cacheDir == "" {
 		return
@@ -193,7 +180,6 @@ func (s *ExtensionStore) loadDiskCache() {
 	LogDebug("ExtensionStore", "Loaded %d extensions from disk cache", len(s.cache.Extensions))
 }

-// saveDiskCache saves registry to disk cache
 func (s *ExtensionStore) saveDiskCache() {
 	if s.cacheDir == "" || s.cache == nil {
 		return
@@ -216,23 +202,24 @@ func (s *ExtensionStore) saveDiskCache() {
 	os.WriteFile(cachePath, data, 0644)
 }

-// FetchRegistry fetches the extension registry from GitHub
 func (s *ExtensionStore) FetchRegistry(forceRefresh bool) (*StoreRegistry, error) {
 	s.cacheMu.Lock()
 	defer s.cacheMu.Unlock()

-	// Return cached if valid and not forcing refresh
 	if !forceRefresh && s.cache != nil && time.Since(s.cacheTime) < s.cacheTTL {
 		LogDebug("ExtensionStore", "Using cached registry (%d extensions)", len(s.cache.Extensions))
 		return s.cache, nil
 	}

+	if err := requireHTTPSURL(s.registryURL, "registry"); err != nil {
+		return nil, err
+	}
+
 	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 {
-		// Return cached data if available on network error
 		if s.cache != nil {
 			LogWarn("ExtensionStore", "Network error, using cached registry: %v", err)
 			return s.cache, nil
@@ -267,7 +254,6 @@ func (s *ExtensionStore) FetchRegistry(forceRefresh bool) (*StoreRegistry, error
 	return &registry, nil
 }

-// GetExtensionsWithStatus returns extensions with installation status
 func (s *ExtensionStore) GetExtensionsWithStatus() ([]StoreExtensionResponse, error) {
 	registry, err := s.FetchRegistry(false)
 	if err != nil {
@@ -299,7 +285,6 @@ func (s *ExtensionStore) GetExtensionsWithStatus() ([]StoreExtensionResponse, er
 	return result, nil
 }

-// DownloadExtension downloads an extension package to the specified path
 func (s *ExtensionStore) DownloadExtension(extensionID string, destPath string) error {
 	registry, err := s.FetchRegistry(false)
 	if err != nil {
@@ -318,9 +303,13 @@ func (s *ExtensionStore) DownloadExtension(extensionID string, destPath string)
 		return fmt.Errorf("extension %s not found in store", extensionID)
 	}

+	if err := requireHTTPSURL(ext.getDownloadURL(), "extension download"); err != nil {
+		return err
+	}
+
 	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)
@@ -347,7 +336,20 @@ func (s *ExtensionStore) DownloadExtension(extensionID string, destPath string)
 	return nil
 }

-// GetCategories returns all available categories
+func requireHTTPSURL(rawURL string, context string) error {
+	if rawURL == "" {
+		return fmt.Errorf("%s URL is empty", context)
+	}
+	parsed, err := url.Parse(rawURL)
+	if err != nil || parsed.Host == "" {
+		return fmt.Errorf("%s URL is invalid: %s", context, rawURL)
+	}
+	if parsed.Scheme != "https" {
+		return fmt.Errorf("%s URL must use https: %s", context, rawURL)
+	}
+	return nil
+}
+
 func (s *ExtensionStore) GetCategories() []string {
 	return []string{
 		CategoryMetadata,
@@ -358,7 +360,6 @@ func (s *ExtensionStore) GetCategories() []string {
 	}
 }

-// SearchExtensions searches extensions by query
 func (s *ExtensionStore) SearchExtensions(query string, category string) ([]StoreExtensionResponse, error) {
 	extensions, err := s.GetExtensionsWithStatus()
 	if err != nil {
@@ -404,7 +405,6 @@ func (s *ExtensionStore) SearchExtensions(query string, category string) ([]Stor
 	return result, nil
 }

-// ClearCache clears the in-memory and disk cache
 func (s *ExtensionStore) ClearCache() {
 	s.cacheMu.Lock()
 	defer s.cacheMu.Unlock()
@@ -420,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)
 }
@@ -112,7 +112,6 @@ func TestExtensionRuntime_NetworkSandbox(t *testing.T) {

 	runtime := NewExtensionRuntime(ext)

-	// Test allowed domains
 	if err := runtime.validateDomain("https://api.allowed.com/path"); err != nil {
 		t.Errorf("Expected api.allowed.com to be allowed, got error: %v", err)
 	}
@@ -121,7 +120,6 @@ func TestExtensionRuntime_NetworkSandbox(t *testing.T) {
 		t.Errorf("Expected sub.wildcard.com to be allowed (wildcard), got error: %v", err)
 	}

-	// Test blocked domains
 	if err := runtime.validateDomain("https://blocked.com/path"); err == nil {
 		t.Error("Expected blocked.com to be denied")
 	}
@@ -139,7 +137,7 @@ func TestExtensionRuntime_FileSandbox(t *testing.T) {
 		Manifest: &ExtensionManifest{
 			Name: "test-ext",
 			Permissions: ExtensionPermissions{
-				File: true, // Enable file permission for test
+				File: true,
 			},
 		},
 		DataDir: tempDir,
@@ -147,7 +145,6 @@ func TestExtensionRuntime_FileSandbox(t *testing.T) {

 	runtime := NewExtensionRuntime(ext)

-	// Test valid path within sandbox
 	validPath, err := runtime.validatePath("test.txt")
 	if err != nil {
 		t.Errorf("Expected relative path to be valid, got error: %v", err)
@@ -156,13 +153,11 @@ func TestExtensionRuntime_FileSandbox(t *testing.T) {
 		t.Error("Expected non-empty path")
 	}

-	// Test path traversal attack
 	_, err = runtime.validatePath("../../../etc/passwd")
 	if err == nil {
 		t.Error("Expected path traversal to be blocked")
 	}

-	// Test nested path within sandbox (should be allowed)
 	nestedPath, err := runtime.validatePath("subdir/file.txt")
 	if err != nil {
 		t.Errorf("Expected nested path to be valid, got error: %v", err)
@@ -171,26 +166,23 @@ func TestExtensionRuntime_FileSandbox(t *testing.T) {
 		t.Error("Expected non-empty nested path")
 	}

-	// Test absolute path should be blocked (security fix)
-	// Use platform-appropriate absolute path
 	var absPath string
 	if filepath.IsAbs("C:\\Windows\\System32") {
-		absPath = "C:\\Windows\\System32\\test.txt" // Windows
+		absPath = "C:\\Windows\\System32\\test.txt"
 	} else {
-		absPath = "/etc/passwd" // Unix
+		absPath = "/etc/passwd"
 	}
 	_, err = runtime.validatePath(absPath)
 	if err == nil {
 		t.Error("Expected absolute path to be blocked")
 	}

-	// Test that extension without file permission is blocked
 	extNoFile := &LoadedExtension{
 		ID: "test-ext-no-file",
 		Manifest: &ExtensionManifest{
 			Name: "test-ext-no-file",
 			Permissions: ExtensionPermissions{
-				File: false, // No file permission
+				File: false,
 			},
 		},
 		DataDir: tempDir,
@@ -215,7 +207,6 @@ func TestExtensionRuntime_UtilityFunctions(t *testing.T) {
 	vm := goja.New()
 	runtime.RegisterAPIs(vm)

-	// Test base64 encode/decode
 	result, err := vm.RunString(`utils.base64Encode("hello")`)
 	if err != nil {
 		t.Fatalf("base64Encode failed: %v", err)
@@ -232,7 +223,6 @@ func TestExtensionRuntime_UtilityFunctions(t *testing.T) {
 		t.Errorf("Expected 'hello', got '%s'", result.String())
 	}

-	// Test MD5
 	result, err = vm.RunString(`utils.md5("hello")`)
 	if err != nil {
 		t.Fatalf("md5 failed: %v", err)
@@ -241,7 +231,6 @@ func TestExtensionRuntime_UtilityFunctions(t *testing.T) {
 		t.Errorf("Expected '5d41402abc4b2a76b9719d911017c592', got '%s'", result.String())
 	}

-	// Test JSON parse/stringify
 	result, err = vm.RunString(`utils.stringifyJSON({name: "test", value: 123})`)
 	if err != nil {
 		t.Fatalf("stringifyJSON failed: %v", err)
@@ -267,7 +256,6 @@ func TestExtensionRuntime_SSRFProtection(t *testing.T) {

 	runtime := NewExtensionRuntime(ext)

-	// Test that private IPs are blocked (SSRF protection)
 	privateIPs := []string{
 		"http://localhost/admin",
 		"http://127.0.0.1/admin",
@@ -285,7 +273,6 @@ func TestExtensionRuntime_SSRFProtection(t *testing.T) {
 		}
 	}

-	// Test that allowed public domain still works
 	if err := runtime.validateDomain("https://api.example.com/path"); err != nil {
 		t.Errorf("Expected api.example.com to be allowed, got error: %v", err)
 	}
@@ -296,7 +283,6 @@ func TestIsPrivateIP(t *testing.T) {
 		host     string
 		expected bool
 	}{
-		// Private IPs should be blocked
 		{"localhost", true},
 		{"127.0.0.1", true},
 		{"127.0.0.2", true},
@@ -306,18 +292,17 @@ func TestIsPrivateIP(t *testing.T) {
 		{"172.31.255.255", true},
 		{"192.168.0.1", true},
 		{"192.168.255.255", true},
-		{"169.254.169.254", true}, // AWS metadata
+		{"169.254.169.254", true},
 		{"router.local", true},
 		{"mydevice.local", true},

-		// Public IPs should be allowed
 		{"8.8.8.8", false},
 		{"1.1.1.1", false},
 		{"api.example.com", false},
 		{"google.com", false},
-		{"172.15.0.1", false},  // Just outside 172.16-31 range
-		{"172.32.0.1", false},  // Just outside 172.16-31 range
-		{"192.167.0.1", false}, // Not 192.168.x.x
+		{"172.15.0.1", false},
+		{"172.32.0.1", false},
+		{"192.167.0.1", false},
 	}

 	for _, tt := range tests {
@@ -4,13 +4,13 @@ package gobackend
 import (
 	"context"
 	"fmt"
+	"runtime/debug"
 	"sync"
 	"time"

 	"github.com/dop251/goja"
 )

-// JSExecutionError represents an error during JS execution
 type JSExecutionError struct {
 	Message   string
 	IsTimeout bool
@@ -20,8 +20,6 @@ func (e *JSExecutionError) Error() string {
 	return e.Message
 }

-// RunWithTimeout executes JavaScript code with a timeout
-// Returns the result value and any error (including timeout)
 func RunWithTimeout(vm *goja.Runtime, script string, timeout time.Duration) (goja.Value, error) {
 	if timeout <= 0 {
 		timeout = DefaultJSTimeout
@@ -30,22 +28,18 @@ func RunWithTimeout(vm *goja.Runtime, script string, timeout time.Duration) (goj
 	ctx, cancel := context.WithTimeout(context.Background(), timeout)
 	defer cancel()

-	// Channel to receive result
 	type result struct {
 		value goja.Value
 		err   error
 	}
 	resultCh := make(chan result, 1)

-	// Track if we've interrupted
 	var interrupted bool
 	var interruptMu sync.Mutex

-	// Run script in goroutine
 	go func() {
 		defer func() {
 			if r := recover(); r != nil {
-				// Check if this was our interrupt
 				interruptMu.Lock()
 				wasInterrupted := interrupted
 				interruptMu.Unlock()
@@ -56,6 +50,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)}
 				}
 			}
@@ -65,22 +60,18 @@ func RunWithTimeout(vm *goja.Runtime, script string, timeout time.Duration) (goj
 		resultCh <- result{val, err}
 	}()

-	// Wait for result or timeout
 	select {
 	case res := <-resultCh:
 		return res.value, res.err
 	case <-ctx.Done():
-		// Timeout - interrupt the VM
 		interruptMu.Lock()
 		interrupted = true
 		interruptMu.Unlock()

 		vm.Interrupt("execution timeout")

-		// Wait a bit for the goroutine to finish
 		select {
 		case res := <-resultCh:
-			// If we got a result after interrupt, it might be the timeout error
 			if res.err != nil {
 				return nil, res.err
 			}
@@ -89,7 +80,6 @@ func RunWithTimeout(vm *goja.Runtime, script string, timeout time.Duration) (goj
 				IsTimeout: true,
 			}
 		case <-time.After(1 * time.Second):
-			// Force return timeout error
 			return nil, &JSExecutionError{
 				Message:   "execution timeout exceeded (force)",
 				IsTimeout: true,
@@ -109,7 +99,6 @@ func RunWithTimeoutAndRecover(vm *goja.Runtime, script string, timeout time.Dura
 	return result, err
 }

-// IsTimeoutError checks if an error is a timeout error
 func IsTimeoutError(err error) bool {
 	if jsErr, ok := err.(*JSExecutionError); ok {
 		return jsErr.IsTimeout
@@ -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)
+	}
+}
@@ -2,16 +2,16 @@ module github.com/zarz/spotiflac_android/go_backend

 go 1.25.0

-toolchain go1.25.6
+toolchain go1.25.7

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

 require (
@@ -20,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,16 +2,20 @@ 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/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/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/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/v2 v2.0.2 h1:xCL3OhxrxWkHrbWUBvGNe+6FQ03yLmBbz0v5z4V2PoQ=
+github.com/go-flac/flacvorbis/v2 v2.0.2/go.mod h1:SwTB5gs13VaM/N7rstwPoUsPibiMKklgwybYP9dYo2g=
+github.com/go-flac/go-flac/v2 v2.0.4 h1:atf/kFa8U9idtkA//NO22XGr+MzQLeXZecnmP9sYBf0=
+github.com/go-flac/go-flac/v2 v2.0.4/go.mod h1:sYOlTKxutMW0RDYF+KlD6Zn+VOCZlIFQG/r/usPveCs=
 github.com/go-sourcemap/sourcemap v2.1.3+incompatible h1:W1iEw64niKVGogNgBN3ePyLFfuisuzeidWPMPWmECqU=
 github.com/go-sourcemap/sourcemap v2.1.3+incompatible/go.mod h1:F8jJfvm2KbVjc5NqelyYJmf/v5J0dwNLS2mL4sNA1Jg=
 github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
@@ -20,23 +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,15 +11,12 @@ import (
 	"net/url"
 	"strconv"
 	"strings"
+	"sync"
 	"syscall"
 	"time"
 )

-// getRandomUserAgent generates a random Windows Chrome User-Agent string
-// Uses modern Chrome format with build and patch numbers
-// Windows 11 still reports as "Windows NT 10.0" for compatibility
 func getRandomUserAgent() string {
-	// Chrome version 120-145 (modern range)
 	chromeVersion := rand.Intn(26) + 120
 	chromeBuild := rand.Intn(1500) + 6000
 	chromePatch := rand.Intn(200) + 100
@@ -38,10 +35,19 @@ const (
 	SongLinkTimeout   = 30 * time.Second
 	DefaultMaxRetries = 3
 	DefaultRetryDelay = 1 * time.Second
-	Second            = time.Second // Exported for use in other files
+	Second            = time.Second
+)
+
+type NetworkCompatibilityOptions struct {
+	AllowHTTP   bool
+	InsecureTLS bool
+}
+
+var (
+	networkCompatibilityMu      sync.RWMutex
+	networkCompatibilityOptions NetworkCompatibilityOptions
 )

-// Shared transport with connection pooling to prevent TCP exhaustion
 var sharedTransport = &http.Transport{
 	DialContext: (&net.Dialer{
 		Timeout:   30 * time.Second,
@@ -60,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,
 	}
 }
@@ -85,9 +121,112 @@ func GetDownloadClient() *http.Client {
 	return downloadClient
 }

-// CloseIdleConnections closes idle connections in the shared transport
 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
@@ -117,16 +256,11 @@ func DefaultRetryConfig() RetryConfig {
 	}
 }

-// DoRequestWithRetry executes an HTTP request with retry logic and exponential backoff
-// Handles 429 (Too Many Requests) responses with Retry-After header
-// Also detects and logs ISP blocking
 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++ {
-		// Clone request for retry (body needs to be re-readable)
 		reqCopy := req.Clone(req.Context())
 		reqCopy.Header.Set("User-Agent", getRandomUserAgent())

@@ -134,10 +268,8 @@ func DoRequestWithRetry(client *http.Client, req *http.Request, config RetryConf
 		if err != nil {
 			lastErr = err

-			// Check for ISP blocking on network errors
-			if CheckAndLogISPBlocking(err, requestURL, "HTTP") {
-				// Don't retry if ISP blocking is detected - it won't help
-				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 {
@@ -149,12 +281,10 @@ func DoRequestWithRetry(client *http.Client, req *http.Request, config RetryConf
 			continue
 		}

-		// Success
 		if resp.StatusCode >= 200 && resp.StatusCode < 300 {
 			return resp, nil
 		}

-		// Handle rate limiting (429)
 		if resp.StatusCode == 429 {
 			resp.Body.Close()
 			retryAfter := getRetryAfterDuration(resp)
@@ -194,7 +324,6 @@ func DoRequestWithRetry(client *http.Client, req *http.Request, config RetryConf
 			}
 		}

-		// Server errors (5xx) - retry
 		if resp.StatusCode >= 500 {
 			resp.Body.Close()
 			lastErr = fmt.Errorf("server error: HTTP %d", resp.StatusCode)
@@ -206,7 +335,6 @@ func DoRequestWithRetry(client *http.Client, req *http.Request, config RetryConf
 			continue
 		}

-		// Client errors (4xx except 429) - don't retry
 		return resp, nil
 	}

@@ -225,12 +353,10 @@ func getRetryAfterDuration(resp *http.Response) time.Duration {
 		return 60 * time.Second // Default wait time
 	}

-	// Try parsing as seconds
 	if seconds, err := strconv.Atoi(retryAfter); err == nil {
 		return time.Duration(seconds) * time.Second
 	}

-	// Try parsing as HTTP date
 	if t, err := http.ParseTime(retryAfter); err == nil {
 		duration := time.Until(t)
 		if duration > 0 {
@@ -241,8 +367,6 @@ func getRetryAfterDuration(resp *http.Response) time.Duration {
 	return 60 * time.Second // Default
 }

-// ReadResponseBody reads and returns the response body
-// Returns error if body is empty
 func ReadResponseBody(resp *http.Response) ([]byte, error) {
 	if resp == nil {
 		return nil, fmt.Errorf("response is nil")
@@ -272,14 +396,12 @@ func ValidateResponse(resp *http.Response) error {
 	return nil
 }

-// BuildErrorMessage creates a detailed error message for API failures
 func BuildErrorMessage(apiURL string, statusCode int, responsePreview string) string {
 	msg := fmt.Sprintf("API %s failed", apiURL)
 	if statusCode > 0 {
 		msg += fmt.Sprintf(" (HTTP %d)", statusCode)
 	}
 	if responsePreview != "" {
-		// Truncate preview if too long
 		if len(responsePreview) > 100 {
 			responsePreview = responsePreview[:100] + "..."
 		}
@@ -298,18 +420,14 @@ func (e *ISPBlockingError) Error() string {
 	return fmt.Sprintf("ISP blocking detected for %s: %s", e.Domain, e.Reason)
 }

-// IsISPBlocking checks if an error is likely caused by ISP blocking
-// Returns the ISPBlockingError if detected, nil otherwise
 func IsISPBlocking(err error, requestURL string) *ISPBlockingError {
 	if err == nil {
 		return nil
 	}

-	// Extract domain from URL
 	domain := extractDomain(requestURL)
 	errStr := strings.ToLower(err.Error())

-	// Check for DNS resolution failure (common ISP blocking method)
 	var dnsErr *net.DNSError
 	if errors.As(err, &dnsErr) {
 		if dnsErr.IsNotFound || dnsErr.IsTemporary {
@@ -321,11 +439,9 @@ func IsISPBlocking(err error, requestURL string) *ISPBlockingError {
 		}
 	}

-	// Check for connection refused (ISP firewall blocking)
 	var opErr *net.OpError
 	if errors.As(err, &opErr) {
 		if opErr.Op == "dial" {
-			// Check for specific syscall errors
 			var syscallErr syscall.Errno
 			if errors.As(opErr.Err, &syscallErr) {
 				switch syscallErr {
@@ -364,7 +480,6 @@ func IsISPBlocking(err error, requestURL string) *ISPBlockingError {
 		}
 	}

-	// Check for TLS handshake failure (ISP MITM or blocking HTTPS)
 	var tlsErr *tls.RecordHeaderError
 	if errors.As(err, &tlsErr) {
 		return &ISPBlockingError{
@@ -425,7 +540,6 @@ func extractDomain(rawURL string) string {

 	parsed, err := url.Parse(rawURL)
 	if err != nil {
-		// Try to extract domain manually
 		rawURL = strings.TrimPrefix(rawURL, "https://")
 		rawURL = strings.TrimPrefix(rawURL, "http://")
 		if idx := strings.Index(rawURL, "/"); idx > 0 {
@@ -35,7 +35,6 @@ func newUTLSTransport() *utlsTransport {
 }

 func (t *utlsTransport) RoundTrip(req *http.Request) (*http.Response, error) {
-	// For non-HTTPS, use standard transport
 	if req.URL.Scheme != "https" {
 		return sharedTransport.RoundTrip(req)
 	}
@@ -44,29 +43,24 @@ func (t *utlsTransport) RoundTrip(req *http.Request) (*http.Response, error) {
 	port := t.getPort(req.URL)
 	addr := net.JoinHostPort(host, port)

-	// Dial TCP connection
 	conn, err := t.dialer.DialContext(req.Context(), "tcp", addr)
 	if err != nil {
 		return nil, err
 	}

-	// Create uTLS connection with Chrome fingerprint (supports HTTP/2 ALPN)
 	tlsConn := utls.UClient(conn, &utls.Config{
 		ServerName: host,
-		NextProtos: []string{"h2", "http/1.1"}, // Prefer HTTP/2
+		NextProtos: []string{"h2", "http/1.1"},
 	}, utls.HelloChrome_Auto)

-	// Perform TLS handshake
 	if err := tlsConn.Handshake(); err != nil {
 		conn.Close()
 		return nil, err
 	}

-	// Check if server supports HTTP/2
 	negotiatedProto := tlsConn.ConnectionState().NegotiatedProtocol

 	if negotiatedProto == "h2" {
-		// Use HTTP/2 transport
 		h2Transport := &http2.Transport{
 			DialTLSContext: func(ctx context.Context, network, addr string, cfg *tls.Config) (net.Conn, error) {
 				return tlsConn, nil
@@ -77,7 +71,6 @@ func (t *utlsTransport) RoundTrip(req *http.Request) (*http.Response, error) {
 		return h2Transport.RoundTrip(req)
 	}

-	// Fallback to HTTP/1.1
 	transport := &http.Transport{
 		DialTLSContext: func(ctx context.Context, network, addr string) (net.Conn, error) {
 			return tlsConn, nil
@@ -0,0 +1,605 @@
+package gobackend
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"time"
+)
+
+// LibraryScanResult represents metadata from a scanned audio file
+type LibraryScanResult struct {
+	ID          string `json:"id"`
+	TrackName   string `json:"trackName"`
+	ArtistName  string `json:"artistName"`
+	AlbumName   string `json:"albumName"`
+	AlbumArtist string `json:"albumArtist,omitempty"`
+	FilePath    string `json:"filePath"`
+	CoverPath   string `json:"coverPath,omitempty"`
+	ScannedAt   string `json:"scannedAt"`
+	FileModTime int64  `json:"fileModTime,omitempty"` // Unix timestamp in milliseconds
+	ISRC        string `json:"isrc,omitempty"`
+	TrackNumber int    `json:"trackNumber,omitempty"`
+	DiscNumber  int    `json:"discNumber,omitempty"`
+	Duration    int    `json:"duration,omitempty"`
+	ReleaseDate string `json:"releaseDate,omitempty"`
+	BitDepth    int    `json:"bitDepth,omitempty"`
+	SampleRate  int    `json:"sampleRate,omitempty"`
+	Bitrate     int    `json:"bitrate,omitempty"` // kbps, for lossy formats (MP3, Opus, Vorbis)
+	Genre       string `json:"genre,omitempty"`
+	Format      string `json:"format,omitempty"`
+}
+
+type LibraryScanProgress struct {
+	TotalFiles   int     `json:"total_files"`
+	ScannedFiles int     `json:"scanned_files"`
+	CurrentFile  string  `json:"current_file"`
+	ErrorCount   int     `json:"error_count"`
+	ProgressPct  float64 `json:"progress_pct"`
+	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
+	SkippedCount int                 `json:"skippedCount"` // Files that were unchanged
+	TotalFiles   int                 `json:"totalFiles"`   // Total files in folder
+}
+
+var (
+	libraryScanProgress   LibraryScanProgress
+	libraryScanProgressMu sync.RWMutex
+	libraryScanCancel     chan struct{}
+	libraryScanCancelMu   sync.Mutex
+	libraryCoverCacheDir  string
+	libraryCoverCacheMu   sync.RWMutex
+)
+
+var supportedAudioFormats = map[string]bool{
+	".flac": true,
+	".m4a":  true,
+	".mp3":  true,
+	".opus": true,
+	".ogg":  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) {
+	libraryCoverCacheMu.Lock()
+	libraryCoverCacheDir = cacheDir
+	libraryCoverCacheMu.Unlock()
+}
+
+func ScanLibraryFolder(folderPath string) (string, error) {
+	if folderPath == "" {
+		return "[]", fmt.Errorf("folder path is empty")
+	}
+
+	info, err := os.Stat(folderPath)
+	if err != nil {
+		return "[]", fmt.Errorf("folder not found: %w", err)
+	}
+	if !info.IsDir() {
+		return "[]", fmt.Errorf("path is not a folder: %s", folderPath)
+	}
+
+	libraryScanProgressMu.Lock()
+	libraryScanProgress = LibraryScanProgress{}
+	libraryScanProgressMu.Unlock()
+
+	libraryScanCancelMu.Lock()
+	if libraryScanCancel != nil {
+		close(libraryScanCancel)
+	}
+	libraryScanCancel = make(chan struct{})
+	cancelCh := libraryScanCancel
+	libraryScanCancelMu.Unlock()
+
+	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
+	libraryScanProgressMu.Unlock()
+
+	if totalFiles == 0 {
+		libraryScanProgressMu.Lock()
+		libraryScanProgress.IsComplete = true
+		libraryScanProgressMu.Unlock()
+		return "[]", nil
+	}
+
+	GoLog("[LibraryScan] Found %d audio files to scan\n", totalFiles)
+
+	results := make([]LibraryScanResult, 0, totalFiles)
+	scanTime := time.Now().UTC().Format(time.RFC3339)
+	errorCount := 0
+
+	for i, filePath := range audioFiles {
+		select {
+		case <-cancelCh:
+			return "[]", fmt.Errorf("scan cancelled")
+		default:
+		}
+
+		libraryScanProgressMu.Lock()
+		libraryScanProgress.ScannedFiles = i + 1
+		libraryScanProgress.CurrentFile = filepath.Base(filePath)
+		libraryScanProgress.ProgressPct = float64(i+1) / float64(totalFiles) * 100
+		libraryScanProgressMu.Unlock()
+
+		result, err := scanAudioFile(filePath, scanTime)
+		if err != nil {
+			errorCount++
+			GoLog("[LibraryScan] Error scanning %s: %v\n", filePath, err)
+			continue
+		}
+
+		results = append(results, *result)
+	}
+
+	libraryScanProgressMu.Lock()
+	libraryScanProgress.ErrorCount = errorCount
+	libraryScanProgress.IsComplete = true
+	libraryScanProgressMu.Unlock()
+
+	GoLog("[LibraryScan] Scan complete: %d tracks found, %d errors\n", len(results), errorCount)
+
+	jsonBytes, err := json.Marshal(results)
+	if err != nil {
+		return "[]", fmt.Errorf("failed to marshal results: %w", err)
+	}
+
+	return string(jsonBytes), nil
+}
+
+func scanAudioFile(filePath, scanTime string) (*LibraryScanResult, error) {
+	ext := strings.ToLower(filepath.Ext(filePath))
+
+	result := &LibraryScanResult{
+		ID:        generateLibraryID(filePath),
+		FilePath:  filePath,
+		ScannedAt: scanTime,
+		Format:    strings.TrimPrefix(ext, "."),
+	}
+
+	// Get file modification time
+	if info, err := os.Stat(filePath); err == nil {
+		result.FileModTime = info.ModTime().UnixMilli()
+	}
+
+	libraryCoverCacheMu.RLock()
+	coverCacheDir := libraryCoverCacheDir
+	libraryCoverCacheMu.RUnlock()
+	if coverCacheDir != "" && ext != ".m4a" {
+		coverPath, err := SaveCoverToCache(filePath, coverCacheDir)
+		if err == nil && coverPath != "" {
+			result.CoverPath = coverPath
+		}
+	}
+
+	switch ext {
+	case ".flac":
+		return scanFLACFile(filePath, result)
+	case ".m4a":
+		return scanM4AFile(filePath, result)
+	case ".mp3":
+		return scanMP3File(filePath, result)
+	case ".opus", ".ogg":
+		return scanOggFile(filePath, result)
+	default:
+		return scanFromFilename(filePath, result)
+	}
+}
+
+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 {
+		return scanFromFilename(filePath, result)
+	}
+
+	result.TrackName = metadata.Title
+	result.ArtistName = metadata.Artist
+	result.AlbumName = metadata.Album
+	result.AlbumArtist = metadata.AlbumArtist
+	result.ISRC = metadata.ISRC
+	result.TrackNumber = metadata.TrackNumber
+	result.DiscNumber = metadata.DiscNumber
+	result.ReleaseDate = metadata.Date
+	result.Genre = metadata.Genre
+
+	quality, err := GetAudioQuality(filePath)
+	if err == nil {
+		result.BitDepth = quality.BitDepth
+		result.SampleRate = quality.SampleRate
+		if quality.SampleRate > 0 && quality.TotalSamples > 0 {
+			result.Duration = int(quality.TotalSamples / int64(quality.SampleRate))
+		}
+	}
+
+	applyDefaultLibraryMetadata(filePath, result)
+
+	return result, nil
+}
+
+func scanM4AFile(filePath string, result *LibraryScanResult) (*LibraryScanResult, error) {
+	quality, err := GetM4AQuality(filePath)
+	if err == nil {
+		result.BitDepth = quality.BitDepth
+		result.SampleRate = quality.SampleRate
+	}
+
+	return scanFromFilename(filePath, result)
+}
+
+func scanMP3File(filePath string, result *LibraryScanResult) (*LibraryScanResult, error) {
+	metadata, err := ReadID3Tags(filePath)
+	if err != nil {
+		GoLog("[LibraryScan] ID3 read error for %s: %v\n", filePath, err)
+		return scanFromFilename(filePath, result)
+	}
+
+	result.TrackName = metadata.Title
+	result.ArtistName = metadata.Artist
+	result.AlbumName = metadata.Album
+	result.AlbumArtist = metadata.AlbumArtist
+	result.TrackNumber = metadata.TrackNumber
+	result.DiscNumber = metadata.DiscNumber
+	result.Genre = metadata.Genre
+	if metadata.Date != "" {
+		result.ReleaseDate = metadata.Date
+	} else {
+		result.ReleaseDate = metadata.Year
+	}
+	result.ISRC = metadata.ISRC
+
+	quality, err := GetMP3Quality(filePath)
+	if err == nil {
+		result.SampleRate = quality.SampleRate
+		result.BitDepth = quality.BitDepth // 0 for lossy
+		result.Duration = quality.Duration
+		if quality.Bitrate > 0 {
+			result.Bitrate = quality.Bitrate / 1000 // convert bps to kbps
+		}
+	}
+
+	applyDefaultLibraryMetadata(filePath, result)
+
+	return result, nil
+}
+
+func scanOggFile(filePath string, result *LibraryScanResult) (*LibraryScanResult, error) {
+	metadata, err := ReadOggVorbisComments(filePath)
+	if err != nil {
+		GoLog("[LibraryScan] Ogg/Opus read error for %s: %v\n", filePath, err)
+		return scanFromFilename(filePath, result)
+	}
+
+	result.TrackName = metadata.Title
+	result.ArtistName = metadata.Artist
+	result.AlbumName = metadata.Album
+	result.AlbumArtist = metadata.AlbumArtist
+	result.ISRC = metadata.ISRC
+	result.TrackNumber = metadata.TrackNumber
+	result.DiscNumber = metadata.DiscNumber
+	result.Genre = metadata.Genre
+	result.ReleaseDate = metadata.Date
+
+	quality, err := GetOggQuality(filePath)
+	if err == nil {
+		result.SampleRate = quality.SampleRate
+		result.BitDepth = quality.BitDepth // 0 for lossy
+		result.Duration = quality.Duration
+		if quality.Bitrate > 0 {
+			result.Bitrate = quality.Bitrate / 1000 // convert bps to kbps
+		}
+	}
+
+	applyDefaultLibraryMetadata(filePath, result)
+
+	return result, nil
+}
+
+func scanFromFilename(filePath string, result *LibraryScanResult) (*LibraryScanResult, error) {
+	filename := strings.TrimSuffix(filepath.Base(filePath), filepath.Ext(filePath))
+
+	parts := strings.SplitN(filename, " - ", 2)
+	if len(parts) == 2 {
+		if len(parts[0]) <= 3 && isNumeric(parts[0]) {
+			result.TrackName = parts[1]
+			result.ArtistName = "Unknown Artist"
+		} else {
+			result.ArtistName = parts[0]
+			result.TrackName = parts[1]
+		}
+	} else {
+		if len(filename) > 3 && isNumeric(filename[:2]) {
+			title := strings.TrimLeft(filename[2:], " .-")
+			result.TrackName = title
+		} else {
+			result.TrackName = filename
+		}
+		result.ArtistName = "Unknown Artist"
+	}
+
+	dir := filepath.Dir(filePath)
+	result.AlbumName = filepath.Base(dir)
+	if result.AlbumName == "." || result.AlbumName == "" {
+		result.AlbumName = "Unknown Album"
+	}
+
+	return result, nil
+}
+
+func isNumeric(s string) bool {
+	for _, c := range s {
+		if c < '0' || c > '9' {
+			return false
+		}
+	}
+	return len(s) > 0
+}
+
+func generateLibraryID(filePath string) string {
+	return fmt.Sprintf("lib_%x", hashString(filePath))
+}
+
+func hashString(s string) uint32 {
+	var hash uint32 = 5381
+	for _, c := range s {
+		hash = ((hash << 5) + hash) + uint32(c)
+	}
+	return hash
+}
+
+func GetLibraryScanProgress() string {
+	libraryScanProgressMu.RLock()
+	defer libraryScanProgressMu.RUnlock()
+
+	jsonBytes, _ := json.Marshal(libraryScanProgress)
+	return string(jsonBytes)
+}
+
+func CancelLibraryScan() {
+	libraryScanCancelMu.Lock()
+	defer libraryScanCancelMu.Unlock()
+
+	if libraryScanCancel != nil {
+		close(libraryScanCancel)
+		libraryScanCancel = nil
+	}
+}
+
+func ReadAudioMetadata(filePath string) (string, error) {
+	scanTime := time.Now().UTC().Format(time.RFC3339)
+	result, err := scanAudioFile(filePath, scanTime)
+	if err != nil {
+		return "", err
+	}
+
+	jsonBytes, err := json.Marshal(result)
+	if err != nil {
+		return "", fmt.Errorf("failed to marshal result: %w", err)
+	}
+
+	return string(jsonBytes), nil
+}
+
+// ScanLibraryFolderIncremental performs an incremental scan of the library folder
+// existingFilesJSON is a JSON object mapping filePath -> modTime (unix millis)
+// Only files that are new or have changed modification time will be scanned
+func ScanLibraryFolderIncremental(folderPath, existingFilesJSON string) (string, error) {
+	if folderPath == "" {
+		return "{}", fmt.Errorf("folder path is empty")
+	}
+
+	info, err := os.Stat(folderPath)
+	if err != nil {
+		return "{}", fmt.Errorf("folder not found: %w", err)
+	}
+	if !info.IsDir() {
+		return "{}", fmt.Errorf("path is not a folder: %s", folderPath)
+	}
+
+	// Parse existing files map
+	existingFiles := make(map[string]int64)
+	if existingFilesJSON != "" && existingFilesJSON != "{}" {
+		if err := json.Unmarshal([]byte(existingFilesJSON), &existingFiles); err != nil {
+			GoLog("[LibraryScan] Warning: failed to parse existing files JSON: %v\n", err)
+		}
+	}
+
+	GoLog("[LibraryScan] Incremental scan starting, %d existing files in database\n", len(existingFiles))
+
+	// Reset progress
+	libraryScanProgressMu.Lock()
+	libraryScanProgress = LibraryScanProgress{}
+	libraryScanProgressMu.Unlock()
+
+	// Setup cancellation
+	libraryScanCancelMu.Lock()
+	if libraryScanCancel != nil {
+		close(libraryScanCancel)
+	}
+	libraryScanCancel = make(chan struct{})
+	cancelCh := libraryScanCancel
+	libraryScanCancelMu.Unlock()
+
+	// Collect all audio files with their mod times
+	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()
+	libraryScanProgress.TotalFiles = totalFiles
+	libraryScanProgressMu.Unlock()
+
+	// Find files to scan (new or modified)
+	var filesToScan []libraryAudioFileInfo
+	skippedCount := 0
+
+	for _, f := range currentFiles {
+		existingModTime, exists := existingFiles[f.path]
+		if !exists {
+			// New file
+			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] {
+			deletedPaths = append(deletedPaths, existingPath)
+		}
+	}
+
+	GoLog("[LibraryScan] Incremental: %d to scan, %d skipped, %d deleted\n",
+		len(filesToScan), skippedCount, len(deletedPaths))
+
+	if len(filesToScan) == 0 {
+		libraryScanProgressMu.Lock()
+		libraryScanProgress.ScannedFiles = totalFiles
+		libraryScanProgress.IsComplete = true
+		libraryScanProgress.ProgressPct = 100
+		libraryScanProgressMu.Unlock()
+
+		result := IncrementalScanResult{
+			Scanned:      []LibraryScanResult{},
+			DeletedPaths: deletedPaths,
+			SkippedCount: skippedCount,
+			TotalFiles:   totalFiles,
+		}
+		jsonBytes, _ := json.Marshal(result)
+		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
+
+	for i, f := range filesToScan {
+		select {
+		case <-cancelCh:
+			return "{}", fmt.Errorf("scan cancelled")
+		default:
+		}
+
+		libraryScanProgressMu.Lock()
+		libraryScanProgress.ScannedFiles = skippedCount + i + 1
+		libraryScanProgress.CurrentFile = filepath.Base(f.path)
+		libraryScanProgress.ProgressPct = float64(skippedCount+i+1) / float64(totalFiles) * 100
+		libraryScanProgressMu.Unlock()
+
+		result, err := scanAudioFile(f.path, scanTime)
+		if err != nil {
+			errorCount++
+			GoLog("[LibraryScan] Error scanning %s: %v\n", f.path, err)
+			continue
+		}
+
+		results = append(results, *result)
+	}
+
+	libraryScanProgressMu.Lock()
+	libraryScanProgress.ErrorCount = errorCount
+	libraryScanProgress.IsComplete = true
+	libraryScanProgress.ScannedFiles = totalFiles
+	libraryScanProgress.ProgressPct = 100
+	libraryScanProgressMu.Unlock()
+
+	GoLog("[LibraryScan] Incremental scan complete: %d scanned, %d skipped, %d deleted, %d errors\n",
+		len(results), skippedCount, len(deletedPaths), errorCount)
+
+	scanResult := IncrementalScanResult{
+		Scanned:      results,
+		DeletedPaths: deletedPaths,
+		SkippedCount: skippedCount,
+		TotalFiles:   totalFiles,
+	}
+
+	jsonBytes, err := json.Marshal(scanResult)
+	if err != nil {
+		return "{}", fmt.Errorf("failed to marshal results: %w", err)
+	}
+
+	return string(jsonBytes), nil
+}
@@ -3,6 +3,7 @@ package gobackend
 import (
 	"encoding/json"
 	"fmt"
+	"regexp"
 	"strings"
 	"sync"
 	"time"
@@ -22,30 +23,55 @@ type LogBuffer struct {
 	loggingEnabled bool
 }

+const (
+	defaultLogBufferSize = 500
+	maxLogMessageLength  = 500
+)
+
 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._~+/\-]+=*`)
 )

-// GetLogBuffer returns the singleton log buffer instance
+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{
-			entries:        make([]LogEntry, 0, 1000),
-			maxSize:        1000,
+			entries:        make([]LogEntry, 0, defaultLogBufferSize),
+			maxSize:        defaultLogBufferSize,
 			loggingEnabled: false, // Default: disabled for performance (user can enable in settings)
 		}
 	})
 	return globalLogBuffer
 }

+func truncateLogMessage(message string) string {
+	runes := []rune(message)
+	if len(runes) <= maxLogMessageLength {
+		return message
+	}
+	return string(runes[:maxLogMessageLength]) + "...[truncated]"
+}
+
 func (lb *LogBuffer) SetLoggingEnabled(enabled bool) {
 	lb.mu.Lock()
 	defer lb.mu.Unlock()
 	lb.loggingEnabled = enabled
 }

-// IsLoggingEnabled returns whether logging is enabled
 func (lb *LogBuffer) IsLoggingEnabled() bool {
 	lb.mu.RLock()
 	defer lb.mu.RUnlock()
@@ -60,6 +86,9 @@ func (lb *LogBuffer) Add(level, tag, message string) {
 		return
 	}

+	message = sanitizeSensitiveLogText(message)
+	message = truncateLogMessage(message)
+
 	entry := LogEntry{
 		Timestamp: time.Now().Format("15:04:05.000"),
 		Level:     level,
@@ -75,7 +104,6 @@ func (lb *LogBuffer) Add(level, tag, message string) {
 	fmt.Printf("[%s] %s\n", tag, message)
 }

-// GetAll returns all log entries as JSON
 func (lb *LogBuffer) GetAll() string {
 	lb.mu.RLock()
 	defer lb.mu.RUnlock()
@@ -99,21 +127,18 @@ func (lb *LogBuffer) getSince(index int) ([]LogEntry, int) {
 	return entries, len(lb.entries)
 }

-// Clear clears all log entries
 func (lb *LogBuffer) Clear() {
 	lb.mu.Lock()
 	defer lb.mu.Unlock()
 	lb.entries = lb.entries[:0]
 }

-// Count returns the number of log entries
 func (lb *LogBuffer) Count() int {
 	lb.mu.RLock()
 	defer lb.mu.RUnlock()
 	return len(lb.entries)
 }

-// Helper functions for logging with different levels
 func LogDebug(tag, format string, args ...interface{}) {
 	GetLogBuffer().Add("DEBUG", tag, fmt.Sprintf(format, args...))
 }
@@ -163,15 +188,10 @@ func GoLog(format string, args ...interface{}) {
 	GetLogBuffer().Add(level, tag, message)
 }

-// Exported functions for Flutter
-
-// GetLogs returns all logs as JSON array
 func GetLogs() string {
 	return GetLogBuffer().GetAll()
 }

-// GetLogsSince returns logs since the given index
-// Returns JSON: {"logs": [...], "next_index": N}
 func GetLogsSince(index int) string {
 	entries, nextIndex := GetLogBuffer().getSince(index)
 	logsJson, _ := json.Marshal(entries)
@@ -179,17 +199,14 @@ func GetLogsSince(index int) string {
 	return result
 }

-// ClearLogs clears all logs
 func ClearLogs() {
 	GetLogBuffer().Clear()
 }

-// GetLogCount returns the number of log entries
 func GetLogCount() int {
 	return GetLogBuffer().Count()
 }

-// SetLoggingEnabled enables or disables logging from Flutter
 func SetLoggingEnabled(enabled bool) {
 	GetLogBuffer().SetLoggingEnabled(enabled)
 }
@@ -20,6 +20,149 @@ 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,
+}
+
+// Global lyrics provider configuration
+var (
+	lyricsProvidersMu sync.RWMutex
+	lyricsProviders   []string // ordered list of enabled providers
+)
+
+var (
+	spotifyLyricsRateLimitMu    sync.RWMutex
+	spotifyLyricsRateLimitedTil time.Time
+)
+
+// LyricsFetchOptions controls optional provider-specific enhancements.
+type LyricsFetchOptions struct {
+	IncludeTranslationNetease  bool   `json:"include_translation_netease"`
+	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 +233,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 +254,18 @@ type LRCLibResponse struct {
 	SyncedLyrics string  `json:"syncedLyrics"`
 }

+type SpotifyLyricsLine struct {
+	TimeTag string `json:"timeTag"`
+	Words   string `json:"words"`
+}
+
+type SpotifyLyricsAPIResponse struct {
+	Error    bool                `json:"error"`
+	Message  string              `json:"message"`
+	SyncType string              `json:"syncType"`
+	Lines    []SpotifyLyricsLine `json:"lines"`
+}
+
 type LyricsLine struct {
 	StartTimeMs int64  `json:"startTimeMs"`
 	Words       string `json:"words"`
@@ -139,7 +303,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 +338,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 +373,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
@@ -238,79 +568,208 @@ func (c *LyricsClient) durationMatches(lrcDuration, targetDuration float64) bool
 	return diff <= durationToleranceSec
 }

-// durationSec: track duration in seconds for matching, use 0 to skip duration matching
 func (c *LyricsClient) FetchLyricsAllSources(spotifyID, trackName, artistName string, durationSec float64) (*LyricsResponse, error) {
-	// Normalize artist name - take first artist before comma/semicolon for better matching
 	primaryArtist := normalizeArtistName(artistName)
+	fetchOptions := GetLyricsFetchOptions()

-	// Check cache first (use original artist name for cache key)
+	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)
+	}
+
+	// Try extension lyrics providers first
+	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
-
-	// Helper to check if lyrics result is valid (has lines OR is instrumental)
-	isValidResult := func(l *LyricsResponse) bool {
-		return l != nil && (len(l.Lines) > 0 || l.Instrumental)
-	}
-
-	// Try exact match first with primary artist
-	lyrics, err = c.FetchLyricsWithMetadata(primaryArtist, trackName)
-	if err == nil && isValidResult(lyrics) {
-		lyrics.Source = "LRCLIB"
-		globalLyricsCache.Set(artistName, trackName, durationSec, lyrics)
-		return lyrics, nil
-	}
-
-	// Try with full artist name if different from primary
-	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
-		}
-	}
-
-	// Try with simplified track name
+	// Get configured provider order
+	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
 		}
-	}

-	// Search with duration matching (use primary artist for search)
-	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
-	}
-
-	// Search with simplified name and duration matching
-	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,
@@ -348,10 +807,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,
@@ -372,6 +841,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)
@@ -385,40 +927,18 @@ 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)
 }

-// Use convertToLRCWithMetadata for full LRC with headers
-// Kept for potential future use
-// func convertToLRC(lyrics *LyricsResponse) string {
-// 	if lyrics == nil || len(lyrics.Lines) == 0 {
-// 		return ""
-// 	}
-//
-// 	var builder strings.Builder
-//
-// 	if lyrics.SyncType == "LINE_SYNCED" {
-// 		for _, line := range lyrics.Lines {
-// 			timestamp := msToLRCTimestamp(line.StartTimeMs)
-// 			builder.WriteString(timestamp)
-// 			builder.WriteString(line.Words)
-// 			builder.WriteString("\n")
-// 		}
-// 	} else {
-// 		for _, line := range lyrics.Lines {
-// 			builder.WriteString(line.Words)
-// 			builder.WriteString("\n")
-// 		}
-// 	}
-//
-// 	return builder.String()
-// }
-
 func convertToLRCWithMetadata(lyrics *LyricsResponse, trackName, artistName string) string {
 	if lyrics == nil || len(lyrics.Lines) == 0 {
 		return ""
@@ -476,15 +996,21 @@ 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
 }

-// normalizeArtistName extracts the primary artist from multi-artist strings
-// e.g., "HOYO-MiX, AURORA" -> "HOYO-MiX"
-// e.g., "Artist1; Artist2" -> "Artist1"
 func normalizeArtistName(name string) string {
-	// Split by common separators: ", " or "; " or " & " or " feat. " or " ft. "
 	separators := []string{", ", "; ", " & ", " feat. ", " ft. ", " featuring ", " with "}

 	result := name
@@ -0,0 +1,370 @@
+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 = ""
+}
+
+// Apple Music API response models
+type appleMusicSearchResponse struct {
+	Results struct {
+		Songs *struct {
+			Data []struct {
+				ID   string `json:"id"`
+				Type string `json:"type"`
+			} `json:"data"`
+		} `json:"songs"`
+	} `json:"results"`
+	Resources *struct {
+		Songs map[string]struct {
+			Attributes struct {
+				Name       string `json:"name"`
+				ArtistName string `json:"artistName"`
+				AlbumName  string `json:"albumName"`
+				URL        string `json:"url"`
+				Artwork    struct {
+					URL string `json:"url"`
+				} `json:"artwork"`
+			} `json:"attributes"`
+		} `json:"songs"`
+	} `json:"resources"`
+}
+
+// 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
+}
+
+// formatPaxLyricsToLRC converts a pax proxy response to standard LRC format.
+func formatPaxLyricsToLRC(rawJSON string, multiPersonWordByWord bool) (string, error) {
+	// Try to parse as PaxResponse first
+	var paxResp paxResponse
+	if err := json.Unmarshal([]byte(rawJSON), &paxResp); err == nil && paxResp.Content != nil {
+		return formatPaxContent(paxResp.Type, paxResp.Content, multiPersonWordByWord), nil
+	}
+
+	// Try to parse as a direct list of PaxLyrics
+	var directLyrics []paxLyrics
+	if err := json.Unmarshal([]byte(rawJSON), &directLyrics); err == nil && len(directLyrics) > 0 {
+		return formatPaxContent("Syllable", directLyrics, multiPersonWordByWord), nil
+	}
+
+	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,194 @@
+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
+}
+
+// Musixmatch proxy response models
+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)
+	}
+
+	// Prefer synced lyrics for selected language
+	if result.SyncedLyrics != nil && strings.TrimSpace(result.SyncedLyrics.Lyrics) != "" {
+		lines := parseSyncedLyrics(result.SyncedLyrics.Lyrics)
+		if len(lines) > 0 {
+			return &LyricsResponse{
+				Lines:    lines,
+				SyncType: "LINE_SYNCED",
+				Provider: "Musixmatch",
+				Source:   fmt.Sprintf("Musixmatch (%s)", lang),
+			}, nil
+		}
+	}
+
+	// Fall back to unsynced lyrics for selected language
+	if result.UnsyncedLyrics != nil && strings.TrimSpace(result.UnsyncedLyrics.Lyrics) != "" {
+		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)
+	}
+
+	// Prefer synced lyrics
+	if result.SyncedLyrics != nil && strings.TrimSpace(result.SyncedLyrics.Lyrics) != "" {
+		lines := parseSyncedLyrics(result.SyncedLyrics.Lyrics)
+		if len(lines) > 0 {
+			return &LyricsResponse{
+				Lines:    lines,
+				SyncType: "LINE_SYNCED",
+				Provider: "Musixmatch",
+				Source:   "Musixmatch",
+			}, nil
+		}
+	}
+
+	// Fall back to unsynced lyrics
+	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,209 @@
+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
+}
+
+// Netease API response models
+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
+	}
+
+	// Parse the LRC text into LyricsResponse
+	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,200 @@
+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
+}
+
+// QQ Music search response models
+type qqMusicSearchResponse struct {
+	Data struct {
+		Song struct {
+			List []struct {
+				Title  string `json:"title"`
+				Singer []struct {
+					Name string `json:"name"`
+				} `json:"singer"`
+				Album struct {
+					Name string `json:"name"`
+				} `json:"album"`
+				ID int64 `json:"id"`
+			} `json:"list"`
+		} `json:"song"`
+	} `json:"data"`
+}
+
+// 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
+	}
+
+	// Fall back to plain text
+	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,25 +312,17 @@ 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)
 }

-// ReadMetadata reads metadata from a FLAC file
 func ReadMetadata(filePath string) (*Metadata, error) {
 	f, err := flac.ParseFile(filePath)
 	if err != nil {
@@ -293,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
 		}
 	}
@@ -336,6 +426,39 @@ func fileExists(path string) bool {
 	return err == nil
 }

+func ExtractCoverArt(filePath string) ([]byte, error) {
+	f, err := flac.ParseFile(filePath)
+	if err != nil {
+		return nil, fmt.Errorf("failed to parse FLAC file: %w", err)
+	}
+
+	for _, meta := range f.Meta {
+		if meta.Type == flac.Picture {
+			pic, err := flacpicture.ParseFromMetaDataBlock(*meta)
+			if err != nil {
+				continue
+			}
+			if pic.PictureType == flacpicture.PictureTypeFrontCover && len(pic.ImageData) > 0 {
+				return pic.ImageData, nil
+			}
+		}
+	}
+
+	for _, meta := range f.Meta {
+		if meta.Type == flac.Picture {
+			pic, err := flacpicture.ParseFromMetaDataBlock(*meta)
+			if err != nil {
+				continue
+			}
+			if len(pic.ImageData) > 0 {
+				return pic.ImageData, nil
+			}
+		}
+	}
+
+	return nil, fmt.Errorf("no cover art found in file")
+}
+
 func EmbedLyrics(filePath string, lyrics string) error {
 	f, err := flac.ParseFile(filePath)
 	if err != nil {
@@ -418,35 +541,114 @@ func EmbedGenreLabel(filePath string, genre, label string) error {
 	return f.Save(filePath)
 }

-// ExtractLyrics extracts embedded lyrics from a FLAC file
 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"`
@@ -512,356 +714,6 @@ func GetAudioQuality(filePath string) (AudioQuality, error) {
 	return AudioQuality{}, fmt.Errorf("unsupported file format (not FLAC or M4A)")
 }

-// ========================================
-// M4A (MP4/AAC) Metadata Embedding
-// ========================================
-
-// EmbedM4AMetadata embeds metadata into an M4A file using iTunes-style atoms
-func EmbedM4AMetadata(filePath string, metadata Metadata, coverData []byte) error {
-	input, err := os.Open(filePath)
-	if err != nil {
-		return fmt.Errorf("failed to open M4A file: %w", err)
-	}
-	defer input.Close()
-
-	info, err := input.Stat()
-	if err != nil {
-		return fmt.Errorf("failed to stat M4A file: %w", err)
-	}
-	fileSize := info.Size()
-
-	moovHeader, moovFound, err := findAtomInRange(input, 0, fileSize, "moov", fileSize)
-	if err != nil {
-		return fmt.Errorf("failed to find moov atom: %w", err)
-	}
-	if !moovFound {
-		return fmt.Errorf("moov atom not found in M4A file")
-	}
-
-	moovContentStart := moovHeader.offset + moovHeader.headerSize
-	moovContentSize := moovHeader.size - moovHeader.headerSize
-
-	udtaHeader, udtaFound, err := findAtomInRange(input, moovContentStart, moovContentSize, "udta", fileSize)
-	if err != nil {
-		return fmt.Errorf("failed to locate udta atom: %w", err)
-	}
-
-	var metaHeader atomHeader
-	metaFound := false
-	if udtaFound {
-		udtaContentStart := udtaHeader.offset + udtaHeader.headerSize
-		udtaContentSize := udtaHeader.size - udtaHeader.headerSize
-		metaHeader, metaFound, err = findAtomInRange(input, udtaContentStart, udtaContentSize, "meta", fileSize)
-		if err != nil {
-			return fmt.Errorf("failed to locate meta atom: %w", err)
-		}
-	}
-
-	metaAtom := buildMetaAtom(metadata, coverData)
-	metaSize := int64(len(metaAtom))
-
-	var delta int64
-	var newUdtaSize int64
-	switch {
-	case udtaFound && metaFound:
-		delta = metaSize - metaHeader.size
-		newUdtaSize = udtaHeader.size + delta
-	case udtaFound && !metaFound:
-		delta = metaSize
-		newUdtaSize = udtaHeader.size + delta
-	case !udtaFound:
-		newUdtaSize = int64(8 + len(metaAtom))
-		delta = newUdtaSize
-	}
-
-	newMoovSize := moovHeader.size + delta
-	if moovHeader.headerSize == 8 && newMoovSize > int64(^uint32(0)) {
-		return fmt.Errorf("moov atom exceeds 32-bit size after update")
-	}
-	if udtaFound && udtaHeader.headerSize == 8 && newUdtaSize > int64(^uint32(0)) {
-		return fmt.Errorf("udta atom exceeds 32-bit size after update")
-	}
-	if !udtaFound && newUdtaSize > int64(^uint32(0)) {
-		return fmt.Errorf("udta atom exceeds 32-bit size after update")
-	}
-
-	tempPath := filePath + ".tmp"
-	output, err := os.OpenFile(tempPath, os.O_CREATE|os.O_TRUNC|os.O_WRONLY, 0644)
-	if err != nil {
-		return fmt.Errorf("failed to create temp file: %w", err)
-	}
-	cleanupTemp := true
-	defer func() {
-		_ = output.Close()
-		if cleanupTemp {
-			_ = os.Remove(tempPath)
-		}
-	}()
-
-	switch {
-	case udtaFound && metaFound:
-		if err := copyRange(output, input, 0, moovHeader.offset); err != nil {
-			return err
-		}
-		if err := writeAtomHeader(output, "moov", newMoovSize, moovHeader.headerSize); err != nil {
-			return err
-		}
-		if err := copyRange(output, input, moovHeader.offset+moovHeader.headerSize, udtaHeader.offset-(moovHeader.offset+moovHeader.headerSize)); err != nil {
-			return err
-		}
-		if err := writeAtomHeader(output, "udta", newUdtaSize, udtaHeader.headerSize); err != nil {
-			return err
-		}
-		if err := copyRange(output, input, udtaHeader.offset+udtaHeader.headerSize, metaHeader.offset-(udtaHeader.offset+udtaHeader.headerSize)); err != nil {
-			return err
-		}
-		if _, err := output.Write(metaAtom); err != nil {
-			return fmt.Errorf("failed to write meta atom: %w", err)
-		}
-		metaEnd := metaHeader.offset + metaHeader.size
-		if err := copyRange(output, input, metaEnd, fileSize-metaEnd); err != nil {
-			return err
-		}
-	case udtaFound && !metaFound:
-		if err := copyRange(output, input, 0, moovHeader.offset); err != nil {
-			return err
-		}
-		if err := writeAtomHeader(output, "moov", newMoovSize, moovHeader.headerSize); err != nil {
-			return err
-		}
-		if err := copyRange(output, input, moovHeader.offset+moovHeader.headerSize, udtaHeader.offset-(moovHeader.offset+moovHeader.headerSize)); err != nil {
-			return err
-		}
-		if err := writeAtomHeader(output, "udta", newUdtaSize, udtaHeader.headerSize); err != nil {
-			return err
-		}
-		insertPos := udtaHeader.offset + udtaHeader.size
-		if err := copyRange(output, input, udtaHeader.offset+udtaHeader.headerSize, insertPos-(udtaHeader.offset+udtaHeader.headerSize)); err != nil {
-			return err
-		}
-		if _, err := output.Write(metaAtom); err != nil {
-			return fmt.Errorf("failed to write meta atom: %w", err)
-		}
-		if err := copyRange(output, input, insertPos, fileSize-insertPos); err != nil {
-			return err
-		}
-	case !udtaFound:
-		newUdtaAtom := buildUdtaAtom(metaAtom)
-		if err := copyRange(output, input, 0, moovHeader.offset); err != nil {
-			return err
-		}
-		if err := writeAtomHeader(output, "moov", newMoovSize, moovHeader.headerSize); err != nil {
-			return err
-		}
-		moovEnd := moovHeader.offset + moovHeader.size
-		if err := copyRange(output, input, moovHeader.offset+moovHeader.headerSize, moovEnd-(moovHeader.offset+moovHeader.headerSize)); err != nil {
-			return err
-		}
-		if _, err := output.Write(newUdtaAtom); err != nil {
-			return fmt.Errorf("failed to write udta atom: %w", err)
-		}
-		if err := copyRange(output, input, moovEnd, fileSize-moovEnd); err != nil {
-			return err
-		}
-	}
-
-	if err := output.Close(); err != nil {
-		return fmt.Errorf("failed to close temp file: %w", err)
-	}
-
-	_ = input.Close()
-	if err := os.Remove(filePath); err != nil {
-		return fmt.Errorf("failed to replace original file: %w", err)
-	}
-	if err := os.Rename(tempPath, filePath); err != nil {
-		return fmt.Errorf("failed to move temp file: %w", err)
-	}
-	cleanupTemp = false
-
-	fmt.Printf("[M4A] Metadata embedded successfully\n")
-	return nil
-}
-
-// buildMetaAtom builds a complete meta atom with ilst containing metadata
-func buildMetaAtom(metadata Metadata, coverData []byte) []byte {
-	var ilst []byte
-
-	if metadata.Title != "" {
-		ilst = append(ilst, buildTextAtom("©nam", metadata.Title)...)
-	}
-
-	if metadata.Artist != "" {
-		ilst = append(ilst, buildTextAtom("©ART", metadata.Artist)...)
-	}
-
-	if metadata.Album != "" {
-		ilst = append(ilst, buildTextAtom("©alb", metadata.Album)...)
-	}
-
-	if metadata.AlbumArtist != "" {
-		ilst = append(ilst, buildTextAtom("aART", metadata.AlbumArtist)...)
-	}
-
-	if metadata.Date != "" {
-		ilst = append(ilst, buildTextAtom("©day", metadata.Date)...)
-	}
-
-	if metadata.TrackNumber > 0 {
-		ilst = append(ilst, buildTrackNumberAtom(metadata.TrackNumber, metadata.TotalTracks)...)
-	}
-
-	if metadata.DiscNumber > 0 {
-		ilst = append(ilst, buildDiscNumberAtom(metadata.DiscNumber, 0)...)
-	}
-
-	if metadata.Lyrics != "" {
-		ilst = append(ilst, buildTextAtom("©lyr", metadata.Lyrics)...)
-	}
-
-	if len(coverData) > 0 {
-		ilst = append(ilst, buildCoverAtom(coverData)...)
-	}
-
-	ilstSize := 8 + len(ilst)
-	ilstAtom := make([]byte, 4)
-	ilstAtom[0] = byte(ilstSize >> 24)
-	ilstAtom[1] = byte(ilstSize >> 16)
-	ilstAtom[2] = byte(ilstSize >> 8)
-	ilstAtom[3] = byte(ilstSize)
-	ilstAtom = append(ilstAtom, []byte("ilst")...)
-	ilstAtom = append(ilstAtom, ilst...)
-
-	hdlr := []byte{
-		0, 0, 0, 33, // size = 33
-		'h', 'd', 'l', 'r',
-		0, 0, 0, 0, // version + flags
-		0, 0, 0, 0, // predefined
-		'm', 'd', 'i', 'r', // handler type
-		'a', 'p', 'p', 'l', // manufacturer
-		0, 0, 0, 0, // component flags
-		0, 0, 0, 0, // component flags mask
-		0, // null terminator
-	}
-
-	metaContent := append([]byte{0, 0, 0, 0}, hdlr...) // version + flags + hdlr
-	metaContent = append(metaContent, ilstAtom...)
-
-	metaSize := 8 + len(metaContent)
-	metaAtom := make([]byte, 4)
-	metaAtom[0] = byte(metaSize >> 24)
-	metaAtom[1] = byte(metaSize >> 16)
-	metaAtom[2] = byte(metaSize >> 8)
-	metaAtom[3] = byte(metaSize)
-	metaAtom = append(metaAtom, []byte("meta")...)
-	metaAtom = append(metaAtom, metaContent...)
-
-	return metaAtom
-}
-
-func buildTextAtom(name, value string) []byte {
-	valueBytes := []byte(value)
-
-	dataSize := 16 + len(valueBytes)
-	dataAtom := make([]byte, 4)
-	dataAtom[0] = byte(dataSize >> 24)
-	dataAtom[1] = byte(dataSize >> 16)
-	dataAtom[2] = byte(dataSize >> 8)
-	dataAtom[3] = byte(dataSize)
-	dataAtom = append(dataAtom, []byte("data")...)
-	dataAtom = append(dataAtom, 0, 0, 0, 1) // type = UTF-8
-	dataAtom = append(dataAtom, 0, 0, 0, 0) // locale
-	dataAtom = append(dataAtom, valueBytes...)
-
-	atomSize := 8 + len(dataAtom)
-	atom := make([]byte, 4)
-	atom[0] = byte(atomSize >> 24)
-	atom[1] = byte(atomSize >> 16)
-	atom[2] = byte(atomSize >> 8)
-	atom[3] = byte(atomSize)
-	atom = append(atom, []byte(name)...)
-	atom = append(atom, dataAtom...)
-
-	return atom
-}
-
-// buildTrackNumberAtom builds trkn atom
-func buildTrackNumberAtom(track, total int) []byte {
-	dataAtom := []byte{
-		0, 0, 0, 24, // size
-		'd', 'a', 't', 'a',
-		0, 0, 0, 0, // type = implicit
-		0, 0, 0, 0, // locale
-		0, 0, // padding
-		byte(track >> 8), byte(track), // track number
-		byte(total >> 8), byte(total), // total tracks
-		0, 0, // padding
-	}
-
-	atomSize := 8 + len(dataAtom)
-	atom := make([]byte, 4)
-	atom[0] = byte(atomSize >> 24)
-	atom[1] = byte(atomSize >> 16)
-	atom[2] = byte(atomSize >> 8)
-	atom[3] = byte(atomSize)
-	atom = append(atom, []byte("trkn")...)
-	atom = append(atom, dataAtom...)
-
-	return atom
-}
-
-func buildDiscNumberAtom(disc, total int) []byte {
-	dataAtom := []byte{
-		0, 0, 0, 22, // size
-		'd', 'a', 't', 'a',
-		0, 0, 0, 0, // type = implicit
-		0, 0, 0, 0, // locale
-		0, 0, // padding
-		byte(disc >> 8), byte(disc), // disc number
-		byte(total >> 8), byte(total), // total discs
-	}
-
-	atomSize := 8 + len(dataAtom)
-	atom := make([]byte, 4)
-	atom[0] = byte(atomSize >> 24)
-	atom[1] = byte(atomSize >> 16)
-	atom[2] = byte(atomSize >> 8)
-	atom[3] = byte(atomSize)
-	atom = append(atom, []byte("disk")...)
-	atom = append(atom, dataAtom...)
-
-	return atom
-}
-
-// buildCoverAtom builds covr atom with image data
-func buildCoverAtom(coverData []byte) []byte {
-	imageType := byte(13)
-	if len(coverData) > 8 && coverData[0] == 0x89 && coverData[1] == 'P' && coverData[2] == 'N' && coverData[3] == 'G' {
-		imageType = 14
-	}
-
-	dataSize := 16 + len(coverData)
-	dataAtom := make([]byte, 4)
-	dataAtom[0] = byte(dataSize >> 24)
-	dataAtom[1] = byte(dataSize >> 16)
-	dataAtom[2] = byte(dataSize >> 8)
-	dataAtom[3] = byte(dataSize)
-	dataAtom = append(dataAtom, []byte("data")...)
-	dataAtom = append(dataAtom, 0, 0, 0, imageType)
-	dataAtom = append(dataAtom, 0, 0, 0, 0)
-	dataAtom = append(dataAtom, coverData...)
-
-	atomSize := 8 + len(dataAtom)
-	atom := make([]byte, 4)
-	atom[0] = byte(atomSize >> 24)
-	atom[1] = byte(atomSize >> 16)
-	atom[2] = byte(atomSize >> 8)
-	atom[3] = byte(atomSize)
-	atom = append(atom, []byte("covr")...)
-	atom = append(atom, dataAtom...)
-
-	return atom
-}
-
 func GetM4AQuality(filePath string) (AudioQuality, error) {
 	f, err := os.Open(filePath)
 	if err != nil {
@@ -974,52 +826,6 @@ func findAtomInRange(f *os.File, start, size int64, target string, fileSize int6
 	return atomHeader{}, false, nil
 }

-func writeAtomHeader(w io.Writer, typ string, size int64, headerSize int64) error {
-	if len(typ) != 4 {
-		return fmt.Errorf("invalid atom type: %s", typ)
-	}
-
-	if headerSize == 16 {
-		header := make([]byte, 16)
-		binary.BigEndian.PutUint32(header[0:4], 1)
-		copy(header[4:8], []byte(typ))
-		binary.BigEndian.PutUint64(header[8:16], uint64(size))
-		_, err := w.Write(header)
-		return err
-	}
-
-	if size > int64(^uint32(0)) {
-		return fmt.Errorf("atom size exceeds 32-bit for %s", typ)
-	}
-
-	header := make([]byte, 8)
-	binary.BigEndian.PutUint32(header[0:4], uint32(size))
-	copy(header[4:8], []byte(typ))
-	_, err := w.Write(header)
-	return err
-}
-
-func copyRange(dst io.Writer, src *os.File, offset, length int64) error {
-	if length <= 0 {
-		return nil
-	}
-	if _, err := src.Seek(offset, io.SeekStart); err != nil {
-		return fmt.Errorf("failed to seek source: %w", err)
-	}
-	if _, err := io.CopyN(dst, src, length); err != nil {
-		return fmt.Errorf("failed to copy data: %w", err)
-	}
-	return nil
-}
-
-func buildUdtaAtom(metaAtom []byte) []byte {
-	size := 8 + len(metaAtom)
-	header := make([]byte, 8)
-	binary.BigEndian.PutUint32(header[0:4], uint32(size))
-	copy(header[4:8], []byte("udta"))
-	return append(header, metaAtom...)
-}
-
 func findAudioSampleEntry(f *os.File, start, end, fileSize int64) (int64, string, error) {
 	const chunkSize = 64 * 1024
 	patternMP4A := []byte("mp4a")
@@ -0,0 +1,88 @@
+package gobackend
+
+import (
+	"fmt"
+	"os"
+	"strings"
+)
+
+func isFDOutput(outputFD int) bool {
+	return outputFD > 0
+}
+
+func openOutputForWrite(outputPath string, outputFD int) (*os.File, error) {
+	if isFDOutput(outputFD) {
+		// 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
+	}
+
+	path := strings.TrimSpace(outputPath)
+	if path == "" || strings.HasPrefix(path, "/proc/self/fd/") {
+		return
+	}
+
+	_ = os.Remove(path)
+}
@@ -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
+}
@@ -1,6 +1,7 @@
 package gobackend

 import (
+	"encoding/json"
 	"fmt"
 	"sync"
 	"time"
@@ -9,15 +10,14 @@ import (
 type TrackIDCacheEntry struct {
 	TidalTrackID  int64
 	QobuzTrackID  int64
-	AmazonTrackID string
+	AmazonURL     string
 	ExpiresAt     time.Time
 }

 type TrackIDCache struct {
-	cache map[string]*TrackIDCacheEntry
-	mu    sync.RWMutex
-	ttl   time.Duration
-	// Cleanup is triggered on writes at a fixed interval to avoid unbounded growth.
+	cache           map[string]*TrackIDCacheEntry
+	mu              sync.RWMutex
+	ttl             time.Duration
 	lastCleanup     time.Time
 	cleanupInterval time.Duration
 }
@@ -52,7 +52,6 @@ func (c *TrackIDCache) Get(isrc string) *TrackIDCacheEntry {
 		return entry
 	}

-	// Lazily delete expired entry.
 	c.mu.Lock()
 	entry, exists = c.cache[isrc]
 	if exists && time.Now().After(entry.ExpiresAt) {
@@ -108,7 +107,7 @@ func (c *TrackIDCache) SetQobuz(isrc string, trackID int64) {
 	}
 }

-func (c *TrackIDCache) SetAmazon(isrc string, trackID string) {
+func (c *TrackIDCache) SetAmazonURL(isrc string, amazonURL string) {
 	c.mu.Lock()
 	defer c.mu.Unlock()

@@ -117,7 +116,7 @@ func (c *TrackIDCache) SetAmazon(isrc string, trackID string) {
 		entry = &TrackIDCacheEntry{}
 		c.cache[isrc] = entry
 	}
-	entry.AmazonTrackID = trackID
+	entry.AmazonURL = amazonURL
 	now := time.Now()
 	entry.ExpiresAt = now.Add(c.ttl)

@@ -139,7 +138,6 @@ func (c *TrackIDCache) Size() int {
 	return len(c.cache)
 }

-// ParallelDownloadResult holds results from parallel operations
 type ParallelDownloadResult struct {
 	CoverData  []byte
 	LyricsData *LyricsResponse
@@ -159,20 +157,20 @@ func FetchCoverAndLyricsParallel(
 ) *ParallelDownloadResult {
 	result := &ParallelDownloadResult{}
 	var wg sync.WaitGroup
+	var resultMu sync.Mutex

 	if coverURL != "" {
 		wg.Add(1)
 		go func() {
 			defer wg.Done()
-			fmt.Println("[Parallel] Starting cover download...")
 			data, err := downloadCoverToMemory(coverURL, maxQualityCover)
+			resultMu.Lock()
 			if err != nil {
 				result.CoverErr = err
-				fmt.Printf("[Parallel] Cover download failed: %v\n", err)
 			} else {
 				result.CoverData = data
-				fmt.Printf("[Parallel] Cover downloaded: %d bytes\n", len(data))
 			}
+			resultMu.Unlock()
 		}()
 	}

@@ -180,21 +178,19 @@ func FetchCoverAndLyricsParallel(
 		wg.Add(1)
 		go func() {
 			defer wg.Done()
-			fmt.Println("[Parallel] Starting lyrics fetch...")
 			client := NewLyricsClient()
 			durationSec := float64(durationMs) / 1000.0
 			lyrics, err := client.FetchLyricsAllSources(spotifyID, trackName, artistName, durationSec)
+			resultMu.Lock()
 			if err != nil {
 				result.LyricsErr = err
-				fmt.Printf("[Parallel] Lyrics fetch failed: %v\n", err)
 			} else if lyrics != nil && len(lyrics.Lines) > 0 {
 				result.LyricsData = lyrics
 				result.LyricsLRC = convertToLRCWithMetadata(lyrics, trackName, artistName)
-				fmt.Printf("[Parallel] Lyrics fetched: %d lines\n", len(lyrics.Lines))
 			} else {
 				result.LyricsErr = fmt.Errorf("no lyrics found")
-				fmt.Println("[Parallel] No lyrics found")
 			}
+			resultMu.Unlock()
 		}()
 	}

@@ -206,8 +202,8 @@ type PreWarmCacheRequest struct {
 	ISRC       string
 	TrackName  string
 	ArtistName string
-	SpotifyID  string // Needed for Amazon (SongLink lookup)
-	Service    string // "tidal", "qobuz", "amazon"
+	SpotifyID  string
+	Service    string
 }

 func PreWarmTrackCache(requests []PreWarmCacheRequest) {
@@ -215,13 +211,15 @@ func PreWarmTrackCache(requests []PreWarmCacheRequest) {
 		return
 	}

-	fmt.Printf("[Cache] Pre-warming cache for %d tracks...\n", len(requests))
 	cache := GetTrackIDCache()

 	semaphore := make(chan struct{}, 3)
 	var wg sync.WaitGroup

 	for _, req := range requests {
+		if req.ISRC == "" {
+			continue
+		}
 		if cached := cache.Get(req.ISRC); cached != nil {
 			continue
 		}
@@ -236,7 +234,7 @@ func PreWarmTrackCache(requests []PreWarmCacheRequest) {
 			case "tidal":
 				preWarmTidalCache(r.ISRC, r.TrackName, r.ArtistName)
 			case "qobuz":
-				preWarmQobuzCache(r.ISRC)
+				preWarmQobuzCache(r.ISRC, r.SpotifyID)
 			case "amazon":
 				preWarmAmazonCache(r.ISRC, r.SpotifyID)
 			}
@@ -244,7 +242,6 @@ func PreWarmTrackCache(requests []PreWarmCacheRequest) {
 	}

 	wg.Wait()
-	fmt.Printf("[Cache] Pre-warm complete. Cache size: %d\n", cache.Size())
 }

 func preWarmTidalCache(isrc, _, _ string) {
@@ -252,30 +249,68 @@ func preWarmTidalCache(isrc, _, _ string) {
 	track, err := downloader.SearchTrackByISRC(isrc)
 	if err == nil && track != nil {
 		GetTrackIDCache().SetTidal(isrc, track.ID)
-		fmt.Printf("[Cache] Cached Tidal ID for ISRC %s: %d\n", isrc, track.ID)
 	}
 }

-func preWarmQobuzCache(isrc string) {
+// preWarmQobuzCache tries to get Qobuz Track ID in the following order:
+// 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)
+				GetTrackIDCache().SetQobuz(isrc, trackID)
+				return
+			}
+		}
+	}
+
+	// Fallback: Direct ISRC search on Qobuz API
 	downloader := NewQobuzDownloader()
 	track, err := downloader.SearchTrackByISRC(isrc)
 	if err == nil && track != nil {
+		GoLog("[Qobuz] Pre-warm cache: Got Qobuz ID %d from direct ISRC search for %s\n", track.ID, isrc)
 		GetTrackIDCache().SetQobuz(isrc, track.ID)
-		fmt.Printf("[Cache] Cached Qobuz ID for ISRC %s: %d\n", isrc, track.ID)
 	}
 }

 func preWarmAmazonCache(isrc, spotifyID string) {
 	client := NewSongLinkClient()
 	availability, err := client.CheckTrackAvailability(spotifyID, isrc)
-	if err == nil && availability != nil && availability.Amazon {
-		GetTrackIDCache().SetAmazon(isrc, availability.AmazonURL)
-		fmt.Printf("[Cache] Cached Amazon URL for ISRC %s\n", isrc)
+	if err == nil && availability != nil && availability.AmazonURL != "" {
+		GetTrackIDCache().SetAmazonURL(isrc, availability.AmazonURL)
 	}
 }

 func PreWarmCache(tracksJSON string) error {
-	var requests []PreWarmCacheRequest
+	var tracks []struct {
+		ISRC       string `json:"isrc"`
+		TrackName  string `json:"track_name"`
+		ArtistName string `json:"artist_name"`
+		SpotifyID  string `json:"spotify_id"`
+		Service    string `json:"service"`
+	}
+
+	if err := json.Unmarshal([]byte(tracksJSON), &tracks); err != nil {
+		return fmt.Errorf("failed to parse tracks JSON: %w", err)
+	}
+
+	requests := make([]PreWarmCacheRequest, len(tracks))
+	for i, t := range tracks {
+		requests[i] = PreWarmCacheRequest{
+			ISRC:       t.ISRC,
+			TrackName:  t.TrackName,
+			ArtistName: t.ArtistName,
+			SpotifyID:  t.SpotifyID,
+			Service:    t.Service,
+		}
+	}

 	go PreWarmTrackCache(requests)
 	return nil
@@ -283,7 +318,6 @@ func PreWarmCache(tracksJSON string) error {

 func ClearTrackCache() {
 	GetTrackIDCache().Clear()
-	fmt.Println("[Cache] Track ID cache cleared")
 }

 func GetCacheSize() int {
@@ -78,7 +78,6 @@ func GetItemProgress(itemID string) string {
 	return "{}"
 }

-// StartItemProgress initializes progress tracking for an item
 func StartItemProgress(itemID string) {
 	multiMu.Lock()
 	defer multiMu.Unlock()
@@ -93,7 +92,6 @@ func StartItemProgress(itemID string) {
 	}
 }

-// SetItemBytesTotal sets total bytes for an item
 func SetItemBytesTotal(itemID string, total int64) {
 	multiMu.Lock()
 	defer multiMu.Unlock()
@@ -103,7 +101,6 @@ func SetItemBytesTotal(itemID string, total int64) {
 	}
 }

-// SetItemBytesReceived sets bytes received for an item
 func SetItemBytesReceived(itemID string, received int64) {
 	multiMu.Lock()
 	defer multiMu.Unlock()
@@ -116,7 +113,6 @@ func SetItemBytesReceived(itemID string, received int64) {
 	}
 }

-// SetItemBytesReceivedWithSpeed sets bytes received and speed for an item
 func SetItemBytesReceivedWithSpeed(itemID string, received int64, speedMBps float64) {
 	multiMu.Lock()
 	defer multiMu.Unlock()
@@ -130,7 +126,6 @@ func SetItemBytesReceivedWithSpeed(itemID string, received int64, speedMBps floa
 	}
 }

-// CompleteItemProgress marks an item as complete
 func CompleteItemProgress(itemID string) {
 	multiMu.Lock()
 	defer multiMu.Unlock()
@@ -142,7 +137,6 @@ func CompleteItemProgress(itemID string) {
 	}
 }

-// SetItemProgress sets progress for an item directly
 func SetItemProgress(itemID string, progress float64, bytesReceived, bytesTotal int64) {
 	multiMu.Lock()
 	defer multiMu.Unlock()
@@ -158,7 +152,6 @@ func SetItemProgress(itemID string, progress float64, bytesReceived, bytesTotal
 	}
 }

-// SetItemFinalizing marks an item as finalizing (embedding metadata)
 func SetItemFinalizing(itemID string) {
 	multiMu.Lock()
 	defer multiMu.Unlock()
@@ -169,7 +162,6 @@ func SetItemFinalizing(itemID string) {
 	}
 }

-// RemoveItemProgress removes progress tracking for an item
 func RemoveItemProgress(itemID string) {
 	multiMu.Lock()
 	defer multiMu.Unlock()
@@ -177,7 +169,6 @@ func RemoveItemProgress(itemID string) {
 	delete(multiProgress.Items, itemID)
 }

-// ClearAllItemProgress clears all item progress
 func ClearAllItemProgress() {
 	multiMu.Lock()
 	defer multiMu.Unlock()
@@ -185,7 +176,6 @@ func ClearAllItemProgress() {
 	multiProgress.Items = make(map[string]*ItemProgress)
 }

-// setDownloadDir sets the default download directory
 func setDownloadDir(path string) error {
 	downloadDirMu.Lock()
 	defer downloadDirMu.Unlock()
@@ -193,20 +183,18 @@ func setDownloadDir(path string) error {
 	return nil
 }

-// ItemProgressWriter wraps io.Writer to track download progress for a specific item
 type ItemProgressWriter struct {
 	writer       interface{ Write([]byte) (int, error) }
 	itemID       string
 	current      int64
-	lastReported int64     // Track last reported bytes for threshold-based updates
-	startTime    time.Time // Track start time for speed calculation
-	lastTime     time.Time // Track last update time for speed calculation
-	lastBytes    int64     // Track bytes at last speed calculation
+	lastReported int64
+	startTime    time.Time
+	lastTime     time.Time
+	lastBytes    int64
 }

-const progressUpdateThreshold = 64 * 1024 // Update progress every 64KB
+const progressUpdateThreshold = 64 * 1024

-// NewItemProgressWriter creates a new progress writer for a specific item
 func NewItemProgressWriter(w interface{ Write([]byte) (int, error) }, itemID string) *ItemProgressWriter {
 	now := time.Now()
 	return &ItemProgressWriter{
@@ -220,7 +208,6 @@ func NewItemProgressWriter(w interface{ Write([]byte) (int, error) }, itemID str
 	}
 }

-// Write implements io.Writer with threshold-based progress updates and speed tracking
 func (pw *ItemProgressWriter) Write(p []byte) (int, error) {
 	if pw.itemID != "" && isDownloadCancelled(pw.itemID) {
 		return 0, ErrDownloadCancelled
@@ -0,0 +1,135 @@
+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"}}`)
+
+		got, err := extractQobuzDownloadURLFromBody(body)
+		if err != nil {
+			t.Fatalf("expected no error, got %v", err)
+		}
+		if got != "https://example.test/audio.flac" {
+			t.Fatalf("unexpected URL: %q", got)
+		}
+	})
+
+	t.Run("reads top-level url", func(t *testing.T) {
+		body := []byte(`{"url":"https://example.test/top.flac"}`)
+
+		got, err := extractQobuzDownloadURLFromBody(body)
+		if err != nil {
+			t.Fatalf("expected no error, got %v", err)
+		}
+		if got != "https://example.test/top.flac" {
+			t.Fatalf("unexpected URL: %q", got)
+		}
+	})
+
+	t.Run("returns API error", func(t *testing.T) {
+		body := []byte(`{"error":"track not found"}`)
+
+		_, err := extractQobuzDownloadURLFromBody(body)
+		if err == nil || err.Error() != "track not found" {
+			t.Fatalf("expected track-not-found error, got %v", err)
+		}
+	})
+
+	t.Run("returns message when success false", func(t *testing.T) {
+		body := []byte(`{"success":false,"message":"blocked"}`)
+
+		_, err := extractQobuzDownloadURLFromBody(body)
+		if err == nil || err.Error() != "blocked" {
+			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)
+	}
+}
@@ -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,14 +1,13 @@
 package gobackend

 import (
-	"encoding/base64"
+	"context"
 	"encoding/json"
 	"fmt"
 	"net/http"
 	"net/url"
 	"strings"
 	"sync"
-	"time"
 )

 type SongLinkClient struct {
@@ -16,67 +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"`
+	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 (s *SongLinkClient) CheckTrackAvailability(spotifyTrackID string, isrc string) (*TrackAvailability, error) {
-	if spotifyTrackID == "" {
-		return nil, fmt.Errorf("spotify track ID is empty")
+func normalizeSongLinkRegion(region string) string {
+	normalized := strings.ToUpper(strings.TrimSpace(region))
+	if len(normalized) != 2 {
+		return "US"
 	}
-
-	// Try SongLink first
-	availability, err := s.checkTrackAvailabilitySongLink(spotifyTrackID)
-	if err != nil {
-		// Fallback to IDHS if SongLink fails
-		LogWarn("SongLink", "SongLink failed, trying IDHS fallback: %v", err)
-		idhsClient := NewIDHSClient()
-		availability, err = idhsClient.GetAvailabilityFromSpotify(spotifyTrackID)
-		if err != nil {
-			return nil, fmt.Errorf("both SongLink and IDHS failed: %w", err)
+	for _, ch := range normalized {
+		if ch < 'A' || ch > 'Z' {
+			return "US"
 		}
-		LogInfo("SongLink", "IDHS fallback successful for %s", spotifyTrackID)
 	}
-
-	// Check Qobuz availability separately via ISRC
-	if isrc != "" {
-		availability.Qobuz = checkQobuzAvailability(isrc)
-	}
-
-	return availability, nil
+	return normalized
 }

-// checkTrackAvailabilitySongLink is the original SongLink implementation
-func (s *SongLinkClient) checkTrackAvailabilitySongLink(spotifyTrackID string) (*TrackAvailability, error) {
+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 {
@@ -125,6 +182,7 @@ func (s *SongLinkClient) checkTrackAvailabilitySongLink(spotifyTrackID string) (
 	if tidalLink, ok := songLinkResp.LinksByPlatform["tidal"]; ok && tidalLink.URL != "" {
 		availability.Tidal = true
 		availability.TidalURL = tidalLink.URL
+		availability.TidalID = extractTidalIDFromURL(tidalLink.URL)
 	}

 	if amazonLink, ok := songLinkResp.LinksByPlatform["amazonMusic"]; ok && amazonLink.URL != "" {
@@ -138,9 +196,72 @@ func (s *SongLinkClient) checkTrackAvailabilitySongLink(spotifyTrackID string) (
 		availability.DeezerID = extractDeezerIDFromURL(deezerLink.URL)
 	}

+	if qobuzLink, ok := songLinkResp.LinksByPlatform["qobuz"]; ok && qobuzLink.URL != "" {
+		availability.Qobuz = true
+		availability.QobuzURL = qobuzLink.URL
+		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 {
@@ -158,41 +279,6 @@ func (s *SongLinkClient) GetStreamingURLs(spotifyTrackID string) (map[string]str
 	return urls, nil
 }

-func checkQobuzAvailability(isrc string) bool {
-	client := NewHTTPClientWithTimeout(10 * time.Second)
-	appID := "798273057"
-
-	apiBase, _ := base64.StdEncoding.DecodeString("aHR0cHM6Ly93d3cucW9idXouY29tL2FwaS5qc29uLzAuMi90cmFjay9zZWFyY2g/cXVlcnk9")
-	searchURL := fmt.Sprintf("%s%s&limit=1&app_id=%s", string(apiBase), isrc, appID)
-
-	req, err := http.NewRequest("GET", searchURL, nil)
-	if err != nil {
-		return false
-	}
-
-	resp, err := DoRequestWithUserAgent(client, req)
-	if err != nil {
-		return false
-	}
-	defer resp.Body.Close()
-
-	if resp.StatusCode != 200 {
-		return false
-	}
-
-	var searchResp struct {
-		Tracks struct {
-			Total int `json:"total"`
-		} `json:"tracks"`
-	}
-	if err := json.NewDecoder(resp.Body).Decode(&searchResp); err != nil {
-		return false
-	}
-
-	return searchResp.Tracks.Total > 0
-}
-
-// extractDeezerIDFromURL extracts Deezer track/album/artist ID from URL
 func extractDeezerIDFromURL(deezerURL string) string {
 	parts := strings.Split(deezerURL, "/")
 	if len(parts) > 0 {
@@ -205,6 +291,139 @@ func extractDeezerIDFromURL(deezerURL string) string {
 	return ""
 }

+// 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
+//   - https://www.qobuz.com/track/12345678
+//   - https://play.qobuz.com/track/12345678
+func extractQobuzIDFromURL(qobuzURL string) string {
+	if qobuzURL == "" {
+		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
+	if strings.Contains(qobuzURL, "trackId=") {
+		parts := strings.Split(qobuzURL, "trackId=")
+		if len(parts) > 1 {
+			idPart := parts[1]
+			if idx := strings.Index(idPart, "&"); idx > 0 {
+				idPart = idPart[:idx]
+			}
+			idPart = strings.TrimSpace(idPart)
+			if idPart != "" && isNumeric(idPart) {
+				return idPart
+			}
+		}
+	}
+
+	// Last resort: get last numeric segment from URL
+	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]
+		}
+		part = strings.TrimSpace(part)
+		if part != "" && isNumeric(part) {
+			return part
+		}
+	}
+
+	return ""
+}
+
+func extractTidalIDFromURL(tidalURL string) string {
+	if tidalURL == "" {
+		return ""
+	}
+
+	if strings.Contains(tidalURL, "/track/") {
+		parts := strings.Split(tidalURL, "/track/")
+		if len(parts) > 1 {
+			idPart := parts[1]
+			if idx := strings.Index(idPart, "?"); idx > 0 {
+				idPart = idPart[:idx]
+			}
+			if idx := strings.Index(idPart, "/"); idx > 0 {
+				idPart = idPart[:idx]
+			}
+			idPart = strings.TrimSpace(idPart)
+			if idPart != "" && isNumeric(idPart) {
+				return idPart
+			}
+		}
+	}
+
+	return ""
+}
+
+func extractYouTubeIDFromURL(youtubeURL string) string {
+	if youtubeURL == "" {
+		return ""
+	}
+
+	// Handle youtu.be short URLs
+	if strings.Contains(youtubeURL, "youtu.be/") {
+		parts := strings.Split(youtubeURL, "youtu.be/")
+		if len(parts) >= 2 {
+			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)
+		}
+	}
+
+	// Handle youtube.com URLs with ?v= parameter
+	parsed, err := url.Parse(youtubeURL)
+	if err != nil {
+		return ""
+	}
+
+	if v := parsed.Query().Get("v"); v != "" {
+		return v
+	}
+
+	// Handle /embed/ format
+	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) {
 	availability, err := s.CheckTrackAvailability(spotifyTrackID, "")
 	if err != nil {
@@ -218,7 +437,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"`
@@ -227,15 +458,10 @@ type AlbumAvailability struct {
 }

 func (s *SongLinkClient) CheckAlbumAvailability(spotifyAlbumID string) (*AlbumAvailability, error) {
-	// Use global rate limiter
 	songLinkRateLimiter.WaitForSlot()

-	// Build API URL for album
-	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 {
@@ -281,7 +507,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 {
@@ -301,10 +526,8 @@ func (s *SongLinkClient) CheckAvailabilityFromDeezer(deezerTrackID string) (*Tra
 		return nil, fmt.Errorf("deezer track ID is empty")
 	}

-	// Try SongLink first
 	availability, err := s.checkAvailabilityFromDeezerSongLink(deezerTrackID)
 	if err != nil {
-		// Fallback to IDHS if SongLink fails
 		LogWarn("SongLink", "SongLink failed for Deezer, trying IDHS fallback: %v", err)
 		idhsClient := NewIDHSClient()
 		availability, err = idhsClient.GetAvailabilityFromDeezer(deezerTrackID)
@@ -322,9 +545,7 @@ func (s *SongLinkClient) checkAvailabilityFromDeezerSongLink(deezerTrackID strin
 	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 {
@@ -338,7 +559,6 @@ func (s *SongLinkClient) checkAvailabilityFromDeezerSongLink(deezerTrackID strin
 	}
 	defer resp.Body.Close()

-	// Handle specific error codes
 	if resp.StatusCode == 400 {
 		return nil, fmt.Errorf("track not found on SongLink (invalid Deezer ID)")
 	}
@@ -385,6 +605,7 @@ func (s *SongLinkClient) checkAvailabilityFromDeezerSongLink(deezerTrackID strin
 	if tidalLink, ok := songLinkResp.LinksByPlatform["tidal"]; ok && tidalLink.URL != "" {
 		availability.Tidal = true
 		availability.TidalURL = tidalLink.URL
+		availability.TidalID = extractTidalIDFromURL(tidalLink.URL)
 	}

 	if amazonLink, ok := songLinkResp.LinksByPlatform["amazonMusic"]; ok && amazonLink.URL != "" {
@@ -392,10 +613,30 @@ func (s *SongLinkClient) checkAvailabilityFromDeezerSongLink(deezerTrackID strin
 		availability.AmazonURL = amazonLink.URL
 	}

+	if qobuzLink, ok := songLinkResp.LinksByPlatform["qobuz"]; ok && qobuzLink.URL != "" {
+		availability.Qobuz = true
+		availability.QobuzURL = qobuzLink.URL
+		availability.QobuzID = extractQobuzIDFromURL(qobuzLink.URL)
+	}
+
 	if deezerLink, ok := songLinkResp.LinksByPlatform["deezer"]; ok && deezerLink.URL != "" {
 		availability.DeezerURL = deezerLink.URL
 	}

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

@@ -407,15 +648,9 @@ func (s *SongLinkClient) CheckAvailabilityByPlatform(platform, entityType, entit
 		return nil, fmt.Errorf("%s ID is empty", platform)
 	}

-	// Use global rate limiter
 	songLinkRateLimiter.WaitForSlot()

-	// Build API URL using platform, type, and id parameters (as per API docs)
-	// https://api.song.link/v1-alpha.1/links?platform=deezer&type=song&id=123456
-	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 {
@@ -429,7 +664,6 @@ func (s *SongLinkClient) CheckAvailabilityByPlatform(platform, entityType, entit
 	}
 	defer resp.Body.Close()

-	// Handle specific error codes
 	if resp.StatusCode == 400 {
 		return nil, fmt.Errorf("track not found on SongLink (invalid %s ID)", platform)
 	}
@@ -467,6 +701,7 @@ func (s *SongLinkClient) CheckAvailabilityByPlatform(platform, entityType, entit
 	if tidalLink, ok := songLinkResp.LinksByPlatform["tidal"]; ok && tidalLink.URL != "" {
 		availability.Tidal = true
 		availability.TidalURL = tidalLink.URL
+		availability.TidalID = extractTidalIDFromURL(tidalLink.URL)
 	}

 	if amazonLink, ok := songLinkResp.LinksByPlatform["amazonMusic"]; ok && amazonLink.URL != "" {
@@ -474,16 +709,35 @@ func (s *SongLinkClient) CheckAvailabilityByPlatform(platform, entityType, entit
 		availability.AmazonURL = amazonLink.URL
 	}

+	if qobuzLink, ok := songLinkResp.LinksByPlatform["qobuz"]; ok && qobuzLink.URL != "" {
+		availability.Qobuz = true
+		availability.QobuzURL = qobuzLink.URL
+		availability.QobuzID = extractQobuzIDFromURL(qobuzLink.URL)
+	}
+
 	if deezerLink, ok := songLinkResp.LinksByPlatform["deezer"]; ok && deezerLink.URL != "" {
 		availability.Deezer = true
 		availability.DeezerURL = deezerLink.URL
 		availability.DeezerID = extractDeezerIDFromURL(deezerLink.URL)
 	}

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

-// extractSpotifyIDFromURL extracts Spotify track ID from URL
 func extractSpotifyIDFromURL(spotifyURL string) string {
 	parts := strings.Split(spotifyURL, "/track/")
 	if len(parts) > 1 {
@@ -509,7 +763,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 {
@@ -535,3 +788,100 @@ 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()
+
+	apiURL := buildSongLinkURLFromTarget(inputURL, "")
+
+	req, err := http.NewRequest("GET", apiURL, nil)
+	if err != nil {
+		return nil, fmt.Errorf("failed to create request: %w", err)
+	}
+
+	retryConfig := DefaultRetryConfig()
+	resp, err := DoRequestWithRetry(s.client, req, retryConfig)
+	if err != nil {
+		return nil, fmt.Errorf("failed to check availability: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode == 400 || resp.StatusCode == 404 {
+		return nil, fmt.Errorf("track not found on SongLink")
+	}
+	if resp.StatusCode == 429 {
+		return nil, fmt.Errorf("SongLink rate limit exceeded")
+	}
+	if resp.StatusCode != 200 {
+		return nil, fmt.Errorf("SongLink API returned status %d", resp.StatusCode)
+	}
+
+	body, err := ReadResponseBody(resp)
+	if err != nil {
+		return nil, fmt.Errorf("failed to read response: %w", err)
+	}
+
+	var songLinkResp struct {
+		LinksByPlatform map[string]struct {
+			URL      string `json:"url"`
+			EntityID string `json:"entityUniqueId"`
+		} `json:"linksByPlatform"`
+	}
+
+	if err := json.Unmarshal(body, &songLinkResp); err != nil {
+		return nil, fmt.Errorf("failed to decode response: %w", err)
+	}
+
+	availability := &TrackAvailability{}
+
+	if spotifyLink, ok := songLinkResp.LinksByPlatform["spotify"]; ok && spotifyLink.URL != "" {
+		availability.SpotifyID = extractSpotifyIDFromURL(spotifyLink.URL)
+	}
+	if tidalLink, ok := songLinkResp.LinksByPlatform["tidal"]; ok && tidalLink.URL != "" {
+		availability.Tidal = true
+		availability.TidalURL = tidalLink.URL
+		availability.TidalID = extractTidalIDFromURL(tidalLink.URL)
+	}
+	if amazonLink, ok := songLinkResp.LinksByPlatform["amazonMusic"]; ok && amazonLink.URL != "" {
+		availability.Amazon = true
+		availability.AmazonURL = amazonLink.URL
+	}
+	if qobuzLink, ok := songLinkResp.LinksByPlatform["qobuz"]; ok && qobuzLink.URL != "" {
+		availability.Qobuz = true
+		availability.QobuzURL = qobuzLink.URL
+		availability.QobuzID = extractQobuzIDFromURL(qobuzLink.URL)
+	}
+	if deezerLink, ok := songLinkResp.LinksByPlatform["deezer"]; ok && deezerLink.URL != "" {
+		availability.Deezer = true
+		availability.DeezerURL = deezerLink.URL
+		availability.DeezerID = extractDeezerIDFromURL(deezerLink.URL)
+	}
+	// Prefer youtubeMusic URLs — they are usually closer to music catalog matches.
+	if ytMusicLink, ok := songLinkResp.LinksByPlatform["youtubeMusic"]; ok && ytMusicLink.URL != "" {
+		availability.YouTube = true
+		availability.YouTubeURL = ytMusicLink.URL
+		availability.YouTubeID = extractYouTubeIDFromURL(ytMusicLink.URL)
+	}
+	if !availability.YouTube {
+		if youtubeLink, ok := songLinkResp.LinksByPlatform["youtube"]; ok && youtubeLink.URL != "" {
+			availability.YouTube = true
+			availability.YouTubeURL = youtubeLink.URL
+			availability.YouTubeID = extractYouTubeIDFromURL(youtubeLink.URL)
+		}
+	}
+
+	return availability, nil
+}
@@ -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)
+	}
+}
@@ -16,13 +16,14 @@ import (
 )

 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,10 +64,8 @@ var (
 	credentialsMu      sync.RWMutex
 )

-// ErrNoSpotifyCredentials is returned when Spotify credentials are not configured
 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)")

-// SetSpotifyCredentials sets custom Spotify API credentials
 func SetSpotifyCredentials(clientID, clientSecret string) {
 	credentialsMu.Lock()
 	defer credentialsMu.Unlock()
@@ -89,7 +88,6 @@ func HasSpotifyCredentials() bool {
 	return false
 }

-// getCredentials returns the current credentials or error if not configured
 func getCredentials() (string, string, error) {
 	credentialsMu.RLock()
 	defer credentialsMu.RUnlock()
@@ -117,7 +115,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),
@@ -143,7 +141,9 @@ type TrackMetadata struct {
 	DiscNumber  int    `json:"disc_number,omitempty"`
 	ExternalURL string `json:"external_urls"`
 	ISRC        string `json:"isrc"`
-	AlbumType   string `json:"album_type,omitempty"` // album, single, ep, compilation
+	AlbumID     string `json:"album_id,omitempty"`
+	ArtistID    string `json:"artist_id,omitempty"`
+	AlbumType   string `json:"album_type,omitempty"`
 }

 type AlbumTrackMetadata struct {
@@ -212,7 +212,7 @@ type ArtistAlbumMetadata struct {
 	ReleaseDate string `json:"release_date"`
 	TotalTracks int    `json:"total_tracks"`
 	Images      string `json:"images"`
-	AlbumType   string `json:"album_type"` // album, single, compilation
+	AlbumType   string `json:"album_type"`
 	Artists     string `json:"artists"`
 }

@@ -364,6 +364,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),
@@ -378,6 +382,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,
 		})
 	}
@@ -429,6 +435,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),
@@ -443,6 +453,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,
 		})
 	}
@@ -534,7 +546,6 @@ func (c *SpotifyMetadataClient) fetchAlbum(ctx context.Context, albumID, token s

 	albumImage := firstImageURL(data.Images)

-	// Get first artist ID
 	var firstArtistId string
 	if len(data.Artists) > 0 {
 		firstArtistId = data.Artists[0].ID
@@ -567,7 +578,6 @@ func (c *SpotifyMetadataClient) fetchAlbum(ctx context.Context, albumID, token s

 	fmt.Printf("[Spotify] Album has %d tracks (total: %d)\n", len(allTrackItems), data.TotalTracks)

-	// Collect track IDs for parallel ISRC fetching
 	trackIDs := make([]string, len(allTrackItems))
 	for i, item := range allTrackItems {
 		trackIDs[i] = item.ID
@@ -843,6 +853,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"`
@@ -939,14 +990,14 @@ func (c *SpotifyMetadataClient) randomUserAgent() string {
 	defer c.rngMu.Unlock()

 	macMajor := c.rng.Intn(4) + 11
-	macMinor := c.rng.Intn(5) + 4          // 4-8
-	webkitMajor := c.rng.Intn(7) + 530     // 530-536
-	webkitMinor := c.rng.Intn(7) + 30      // 30-36
-	chromeMajor := c.rng.Intn(25) + 80     // 80-104
-	chromeBuild := c.rng.Intn(1500) + 3000 // 3000-4499
-	chromePatch := c.rng.Intn(65) + 60     // 60-124
-	safariMajor := c.rng.Intn(7) + 530     // 530-536
-	safariMinor := c.rng.Intn(6) + 30      // 30-35
+	macMinor := c.rng.Intn(5) + 4
+	webkitMajor := c.rng.Intn(7) + 530
+	webkitMinor := c.rng.Intn(7) + 30
+	chromeMajor := c.rng.Intn(25) + 80
+	chromeBuild := c.rng.Intn(1500) + 3000
+	chromePatch := c.rng.Intn(65) + 60
+	safariMajor := c.rng.Intn(7) + 530
+	safariMinor := c.rng.Intn(6) + 30

 	return fmt.Sprintf(
 		"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_%d_%d) AppleWebKit/%d.%d (KHTML, like Gecko) Chrome/%d.0.%d.%d Safari/%d.%d",
@@ -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,756 @@
+// Package gobackend - YouTube download via Cobalt API (lossy-only provider)
+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
+	}
+}
+
+// SearchYouTube returns a YouTube Music search URL for the given track
+func (y *YouTubeDownloader) SearchYouTube(trackName, artistName string) (string, error) {
+	query := fmt.Sprintf("%s %s", artistName, trackName)
+	searchQuery := url.QueryEscape(query)
+
+	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
+}
+
+// requestCobaltDirect sends a download request to the primary Cobalt API.
+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)
+}
+
+// isYouTubeVideoID checks if s is an 11-char YouTube video ID
+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)
+
+	// Parallel fetch cover art + lyrics
+	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,15 @@ 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?
    
    override func application(
        _ application: UIApplication,
@@ -16,14 +25,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 {
@@ -74,6 +180,14 @@ import Gobackend  // Import Go framework
            let response = GobackendSearchSpotifyAll(query, Int(trackLimit), Int(artistLimit), &error)
            if let error = error { throw error }
            return response
+
+        case "getSpotifyRelatedArtists":
+            let args = call.arguments as! [String: Any]
+            let artistId = args["artist_id"] as! String
+            let limit = args["limit"] as? Int ?? 12
+            let response = GobackendGetSpotifyRelatedArtists(artistId, Int(limit), &error)
+            if let error = error { throw error }
+            return response
            
        case "checkAvailability":
            let args = call.arguments as! [String: Any]
@@ -83,18 +197,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 +241,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 +312,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 +335,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 +378,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 +396,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
@@ -242,6 +419,20 @@ import Gobackend  // Import Go framework
            if let error = error { throw error }
            return response

+        case "parseTidalUrl":
+            let args = call.arguments as! [String: Any]
+            let url = args["url"] as! String
+            let response = GobackendParseTidalURLExport(url, &error)
+            if let error = error { throw error }
+            return response
+
+        case "convertTidalToSpotifyDeezer":
+            let args = call.arguments as! [String: Any]
+            let url = args["url"] as! String
+            let response = GobackendConvertTidalToSpotifyDeezer(url, &error)
+            if let error = error { throw error }
+            return response
+
        case "searchDeezerByISRC":
            let args = call.arguments as! [String: Any]
            let isrc = args["isrc"] as! String
@@ -457,12 +648,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
@@ -470,6 +655,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]
@@ -625,6 +816,14 @@ import Gobackend  // Import Go framework
            let response = GobackendRunPostProcessingJSON(filePath, metadataJson, &error)
            if let error = error { throw error }
            return response
+
+        case "runPostProcessingV2":
+            let args = call.arguments as! [String: Any]
+            let inputJson = args["input"] as? String ?? ""
+            let metadataJson = args["metadata"] as? String ?? ""
+            let response = GobackendRunPostProcessingV2JSON(inputJson, metadataJson, &error)
+            if let error = error { throw error }
+            return response
            
        case "getPostProcessingProviders":
            let response = GobackendGetPostProcessingProvidersJSON(&error)
@@ -687,6 +886,73 @@ import Gobackend  // Import Go framework
            if let error = error { throw error }
            return response
            
+        // Local Library Scanning
+        case "setLibraryCoverCacheDir":
+            let args = call.arguments as! [String: Any]
+            let cacheDir = args["cache_dir"] as! String
+            GobackendSetLibraryCoverCacheDirJSON(cacheDir)
+            return nil
+            
+        case "scanLibraryFolder":
+            let args = call.arguments as! [String: Any]
+            let folderPath = args["folder_path"] as! String
+            let response = GobackendScanLibraryFolderJSON(folderPath, &error)
+            if let error = error { throw error }
+            return response
+            
+        case "scanLibraryFolderIncremental":
+            let args = call.arguments as! [String: Any]
+            let folderPath = args["folder_path"] as! String
+            let existingFiles = args["existing_files"] as? String ?? "{}"
+            let response = GobackendScanLibraryFolderIncrementalJSON(folderPath, existingFiles, &error)
+            if let error = error { throw error }
+            return response
+            
+        case "getLibraryScanProgress":
+            let response = GobackendGetLibraryScanProgressJSON()
+            return response
+            
+        case "cancelLibraryScan":
+            GobackendCancelLibraryScanJSON()
+            return nil
+            
+        case "readAudioMetadata":
+            let args = call.arguments as! [String: Any]
+            let filePath = args["file_path"] as! String
+            let response = GobackendReadAudioMetadataJSON(filePath, &error)
+            if let error = error { throw error }
+            return response
+            
+        // 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
+            
        default:
            throw NSError(
                domain: "SpotiFLAC",
@@ -696,3 +962,27 @@ import Gobackend  // Import Go framework
        }
    }
 }
+
+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