fix: handle .mp4 as alias for .m4a throughout download pipeline

When an extension's preferred output isn't .m4a, downloaded M4A streams
are now automatically converted to FLAC via FFmpeg instead of being
preserved. This applies to both SAF and non-SAF download paths.

.fvmrc

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

.gitattributes

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

.github/FUNDING.yml

@@ -1,4 +1,3 @@
 github: zarzet
 ko_fi: zarzet
-buy_me_a_coffee: zarzet
 

.github/ISSUE_TEMPLATE/config.yml

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

.github/workflows/auto-tag.yml

@@ -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
 

.github/workflows/pages.yml

@@ -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

.github/workflows/release.yml

@@ -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.8"
           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
@@ -93,12 +93,12 @@ jobs:
           # Accept licenses
           yes | $ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager --licenses || true
 
-          # Install NDK r27d LTS (required for 16KB page size support on Android 15+)
+          # Install NDK r29 (supports 16KB page size for Android 15+)
           # Platform android-36 and build-tools 36.0.0 for targetSdk 36 (Android 16)
-          $ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager "ndk;27.3.13750724" "platforms;android-36" "build-tools;36.0.0"
+          $ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager "ndk;29.0.14206865" "platforms;android-36" "build-tools;36.0.0"
 
           # Set NDK path
-          echo "ANDROID_NDK_HOME=$ANDROID_HOME/ndk/27.3.13750724" >> $GITHUB_ENV
+          echo "ANDROID_NDK_HOME=$ANDROID_HOME/ndk/29.0.14206865" >> $GITHUB_ENV
 
       - name: Install gomobile
         run: |
@@ -158,28 +158,33 @@ 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
 
   build-ios:
-    runs-on: macos-latest
+    runs-on: macos-15
     needs: get-version # Only depends on version, NOT android build!
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
+
+      - name: Select Xcode 26.1.1
+        run: |
+          sudo xcode-select -s /Applications/Xcode_26.1.1.app
+          xcodebuild -version
 
       - name: Setup Go
-        uses: actions/setup-go@v5
+        uses: actions/setup-go@v6
         with:
-          go-version: "1.25"
+          go-version: "1.25.8"
           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 +300,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,43 +313,33 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0  # Full history needed for git-cliff
 
-      - name: Extract changelog for version
+      - name: Generate changelog with git-cliff
         id: changelog
+        uses: orhun/git-cliff-action@v4
+        with:
+          config: cliff.toml
+          args: --latest --strip header
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          OUTPUT: /tmp/changelog.txt
+
+      - name: Show generated changelog
         run: |
-          VERSION=${{ needs.get-version.outputs.version }}
-          VERSION_NUM=${VERSION#v}  # Remove 'v' prefix
-
-          echo "Looking for version: $VERSION_NUM"
-
-          # Extract changelog section for this version using sed
-          # Find the line with version, then print until next version header or end
-          CHANGELOG=$(sed -n "/^## \[$VERSION_NUM\]/,/^## \[/{ /^## \[$VERSION_NUM\]/d; /^## \[/d; p; }" CHANGELOG.md)
-
-          # If no changelog found, use default message
-          if [ -z "$CHANGELOG" ]; then
-            echo "No changelog found for version $VERSION_NUM"
-            CHANGELOG="See CHANGELOG.md for details."
-          else
-            echo "Found changelog content"
-            # Remove trailing --- separator if present (CHANGELOG uses --- between versions)
-            CHANGELOG=$(echo "$CHANGELOG" | sed '/^---$/d')
-          fi
-
-          # Save to file for multiline support
-          echo "$CHANGELOG" > /tmp/changelog.txt
-          echo "Extracted changelog:"
+          echo "Generated changelog:"
           cat /tmp/changelog.txt
 
       - name: Download Android APK
-        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
@@ -352,15 +347,22 @@ jobs:
       - name: Prepare release body
         run: |
           VERSION=${{ needs.get-version.outputs.version }}
-          cat > /tmp/release_body.txt << 'HEADER'
-          ### What's New
-          HEADER
-
-          cat /tmp/changelog.txt >> /tmp/release_body.txt
-
           REPO_OWNER="${{ github.repository_owner }}"
           REPO_NAME="${{ github.event.repository.name }}"
-          
+          CURRENT_REF=$(git rev-list -n 1 "$VERSION" 2>/dev/null || git rev-parse HEAD)
+          PREVIOUS_TAG=$(git describe --tags --abbrev=0 "${CURRENT_REF}^" 2>/dev/null || true)
+
+          # Start with git-cliff changelog, but replace its compare footer with a
+          # deterministic previous-tag lookup from git.
+          sed '/^## [0-9][0-9.[:alpha:]-]*$/d; /^\*\*Full Changelog\*\*/d' /tmp/changelog.txt > /tmp/release_body.txt
+
+          if [ -n "$PREVIOUS_TAG" ]; then
+            printf '\n**Full Changelog**: [%s...%s](https://github.com/%s/%s/compare/%s...%s)\n' \
+              "$PREVIOUS_TAG" "$VERSION" "$REPO_OWNER" "$REPO_NAME" "$PREVIOUS_TAG" "$VERSION" \
+              >> /tmp/release_body.txt
+          fi
+
+          # Append download section
           cat >> /tmp/release_body.txt << FOOTER
 
           ---
@@ -385,7 +387,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 }}
@@ -396,6 +398,63 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
+  update-altstore:
+    runs-on: ubuntu-latest
+    needs: [get-version, build-ios, create-release]
+    if: ${{ needs.get-version.outputs.is_prerelease != 'true' }}
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout main branch
+        uses: actions/checkout@v6
+        with:
+          ref: main
+
+      - name: Download iOS IPA
+        uses: actions/download-artifact@v7
+        with:
+          name: ios-ipa
+          path: ./release
+
+      - name: Update apps.json
+        run: |
+          VERSION="${{ needs.get-version.outputs.version }}"
+          VERSION_NUM="${VERSION#v}"
+          DATE=$(date -u +%Y-%m-%d)
+          IPA_FILE=$(find ./release -name "*ios*.ipa" | head -1)
+
+          if [ -z "$IPA_FILE" ]; then
+            echo "WARNING: IPA file not found, skipping apps.json update"
+            exit 0
+          fi
+
+          IPA_SIZE=$(stat -c%s "$IPA_FILE" 2>/dev/null || stat -f%z "$IPA_FILE")
+
+          if [ ! -f apps.json ]; then
+            echo "WARNING: apps.json not found on main, skipping"
+            exit 0
+          fi
+
+          jq --arg ver "$VERSION_NUM" \
+             --arg date "$DATE" \
+             --arg url "https://github.com/zarzet/SpotiFLAC-Mobile/releases/download/${VERSION}/SpotiFLAC-${VERSION}-ios-unsigned.ipa" \
+             --argjson size "$IPA_SIZE" \
+             '.apps[0].version = $ver | .apps[0].versionDate = $date | .apps[0].downloadURL = $url | .apps[0].size = $size' \
+             apps.json > apps.json.tmp && mv apps.json.tmp apps.json
+
+          echo "Updated apps.json:"
+          cat apps.json
+
+      - name: Commit and push
+        run: |
+          VERSION="${{ needs.get-version.outputs.version }}"
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add apps.json
+          git diff --cached --quiet && echo "No changes to commit" || \
+            (git commit -m "chore: update AltStore source to ${VERSION}" && git push)
+
   notify-telegram:
     runs-on: ubuntu-latest
     needs: [get-version, create-release]
@@ -403,66 +462,59 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
 
       - 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
 
-      - name: Extract changelog for version
+      - name: Generate changelog with git-cliff for Telegram
+        uses: orhun/git-cliff-action@v4
+        with:
+          config: cliff.toml
+          args: --latest --strip all
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          OUTPUT: /tmp/cliff_tg.txt
+
+      - name: Convert changelog for Telegram
         id: changelog
         run: |
-          VERSION=${{ needs.get-version.outputs.version }}
-          VERSION_NUM=${VERSION#v}
-
-          # Extract changelog, limit to ~2500 chars for Telegram (4096 limit minus message overhead)
-          # Use tr -d '\r' to handle CRLF line endings from Windows
-          FULL_CHANGELOG=$(cat CHANGELOG.md | tr -d '\r' | sed -n "/^## \[$VERSION_NUM\]/,/^## \[/{ /^## \[$VERSION_NUM\]/d; /^## \[/d; p; }" | sed '/^---$/d')
-          
-          echo "DEBUG: Extracted changelog length: ${#FULL_CHANGELOG}"
-          echo "DEBUG: First 200 chars: ${FULL_CHANGELOG:0:200}"
-          
-          if [ -z "$FULL_CHANGELOG" ]; then
-            CHANGELOG="See release notes on GitHub for details."
+          if [ ! -s /tmp/cliff_tg.txt ]; then
+            echo "See release notes on GitHub for details." > /tmp/changelog.txt
           else
-            # Convert GitHub Markdown to Telegram HTML:
-            # - **text** → <b>text</b>
-            # - `code` → <code>code</code>
-            # - ### Header → <b>Header</b>
-            # - Escape HTML special chars first
-            # - Remove > blockquote prefix
-            CHANGELOG=$(echo "$FULL_CHANGELOG" | \
-              sed 's/^> //' | \
+            # Convert Markdown to Telegram HTML
+            CHANGELOG=$(cat /tmp/cliff_tg.txt | \
+              sed '/^## [0-9][0-9.[:alpha:]-]*$/d' | \
+              sed '/^\*\*Full Changelog\*\*/d' | \
+              sed 's/ by \[@[^]]*\](https:\/\/github\.com\/[^)]*)//g' | \
+              sed 's/ by @[A-Za-z0-9_-]\+//g' | \
+              sed 's/\[#\([0-9]*\)\]([^)]*)/#\1/g' | \
+              sed 's/\[@\([^]]*\)\]([^)]*)/@\1/g' | \
               sed 's/&/\&amp;/g' | \
               sed 's/</\&lt;/g' | \
               sed 's/>/\&gt;/g' | \
-              sed 's/`\([^`]*\)`/<code>\1<\/code>/g' | \
               sed 's/\*\*\([^*]*\)\*\*/<b>\1<\/b>/g' | \
               sed 's/^### \(.*\)$/<b>\1<\/b>/g' | \
               sed 's/^## \(.*\)$/<b>\1<\/b>/g' | \
-              sed 's/^- /• /g' | \
-              sed 's/^  - /  ◦ /g')
-            
-            # Take first 2500 characters, then cut at last complete line
+              sed 's/^- /• /g')
+
+            # Truncate for Telegram 4096 char limit
             CHANGELOG=$(echo "$CHANGELOG" | head -c 2500 | sed '$d')
-            
-            # Check if truncated
-            FULL_LEN=${#FULL_CHANGELOG}
-            if [ $FULL_LEN -gt 2500 ]; then
-              CHANGELOG="${CHANGELOG}"$'\n\n... (see full changelog on GitHub)'
-            fi
+            echo "$CHANGELOG" > /tmp/changelog.txt
           fi
 
-          echo "$CHANGELOG" > /tmp/changelog.txt
-          echo "DEBUG: Final changelog:"
+          echo "Telegram changelog:"
           cat /tmp/changelog.txt
 
       - name: Send to Telegram Channel

.gitignore

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

CHANGELOG.md

@@ -1,5 +1,746 @@
 # Changelog
 
+## [3.7.2] - 2026-03-07
+
+### Changed
+
+- **Amazon Music is now an Extension**: Amazon Music has been moved from a built-in service to a separate installable extension. Install the "Amazon Music" extension from the Store to continue using it.
+
+### Fixed
+
+- **Deezer Downloads Timing Out**: Deezer downloads were failing with "context deadline exceeded" on larger files. Now uses the proper download timeout, matching Tidal and Qobuz.
+- **iOS Local Library Scan Fails**: Local library scanning was failing on iOS because the app lost access to user-picked folders after the FilePicker session ended. Implemented iOS security-scoped bookmark system:
+  - When a library folder is picked on iOS, a security-scoped bookmark is created and persisted in settings (`localLibraryBookmark`)
+  - Before each scan, the bookmark is resolved and security-scoped access is started; access is released in `finally` block after scan completes
+  - `cleanupMissingFiles` also activates the bookmark before checking file existence on iOS
+  - New `AppDelegate.swift` method channel handlers: `createIosBookmarkFromPath`, `startAccessingIosBookmark`, `stopAccessingIosBookmark`, `resolveIosBookmark`
+  - New `PlatformBridge` methods: `createIosBookmarkFromPath()`, `startAccessingIosBookmark()`, `stopAccessingIosBookmark()`
+  - All scan call-sites (Library Settings, Queue tab, Local Album screen) now pass the iOS bookmark to `startScan()`
+
+### Added
+
+- **Amazon Music Extension**: Available in `extension/Amazon-SpotiFLAC/` — same functionality as before, now as an installable extension.
+- **Accessibility Tooltips**: Added localized tooltips to all `IconButton` and `PopupMenuButton` widgets across the entire UI for screen reader and long-press discoverability
+  - Back buttons use `MaterialLocalizations.backButtonTooltip`
+  - Close buttons use `MaterialLocalizations.closeButtonTooltip`
+  - Menu buttons use `MaterialLocalizations.showMenuTooltip`
+  - Search buttons use `MaterialLocalizations.searchFieldLabel`
+  - Contextual actions use descriptive labels: "Play track", "Dismiss", "Clear search", "Change folder", "Refresh"
+  - Screens affected: Album, Artist, Playlist, Downloaded Album, Local Album, Home, Search, Queue, Library Playlists, Library Tracks Folder, Setup, Tutorial, Track Metadata, Store, Extension Store Details, and all Settings sub-pages (About, Appearance, Cache Management, Donate, Download, Extensions, Extension Detail, Library, Log, Options, Provider Priority)
+- **Semantics Wrappers**: Added `Semantics` widgets to interactive elements that previously had no accessibility information
+  - Album tiles in Artist screen: announces selection state and album name
+  - Recently downloaded track tiles in Home tab: announces track name and artist
+  - Explore items (albums/artists/playlists) in Home tab: announces item type and name
+  - Color palette picker in Appearance settings: announces selected state and color hex value
+  - Download button demo in Tutorial screen: added `ExcludeSemantics` on icon to prevent duplicate screen reader announcements
+  - Queue tab playlist cards: announces playlist name and item count
+  - Queue tab downloaded album cards: announces album name, artist, and track count
+  - Queue tab local album cards: announces album name, artist, and track count
+  - Queue tab play button on completed downloads: announces track name and artist with `ExcludeSemantics` on icon
+  - Queue tab download status indicators: "Finalizing download", "Download completed", "Downloaded file missing" labels with `ExcludeSemantics` on icons
+
+### Improved
+
+- **Code Formatting**: Reformatted and corrected indentation across multiple files to comply with Dart style guidelines
+  - `extension_detail_page.dart`: Fixed `SliverAppBar` and all subsequent slivers indentation (was 2 spaces short)
+  - `log_screen.dart`: Fixed `SliverAppBar` indentation alignment
+  - `donate_page.dart`: Reformatted ternary expressions and `_cr` function body
+  - `library_tracks_folder_screen.dart`: Minor line-break formatting
+
+---
+
+## [3.7.1] - 2026-03-06
+
+### Added
+
+- **Deezer Download Service**: Deezer is now available as a built-in download service (FLAC CD Quality).
+- **Smarter YouTube Downloads**: If the YouTube Music extension is installed, the app now uses it first to find the correct song — more accurate than SongLink, especially for new releases.
+- **Songs-Only Search Filter**: YouTube Music extension search now filters results server-side, so you only get actual songs — no music videos or covers mixed in.
+- **Qobuz Squid.wtf Fallback**: Added Squid.wtf as an additional Qobuz download provider.
+- **Qobuz Search Fallback**: If Qobuz API search returns nothing, the app now tries the Qobuz web store as a backup to find the track.
+- **Better ISRC Lookup**: Tracks can now be resolved via ISRC even without a Spotify ID, using Deezer as an intermediary.
+
+### Fixed
+
+- **Download Queue Stability**: Fixed duplicate queue item IDs, cancel not working reliably, and "Clear All" not properly stopping active downloads.
+- **Queue Restore on Restart**: Duplicate or broken queue item IDs are now auto-fixed when the app restarts.
+
+### Changed
+
+- **Update Checker**: The app can now detect updates across all versions, not just within the same major version.
+- **Localization Cleanup**: Cleaned up and consolidated translation files across all 13 supported languages.
+
+---
+
+## [3.7.0] - 2026-03-04
+
+Hey everyone, thank you so much for sticking with SpotiFLAC Mobile.
+
+Starting from this release, we're rolling the version back from **v4.x to v3.x**.
+
+### Removed
+
+- **Internal Audio Player** — Removed `just_audio`, `audio_service`, and `audio_session` dependencies entirely. The internal playback engine (smart queue, media notification, shuffle/repeat, lyrics sync, prefetch, playback state persistence) has been completely removed. Playback now delegates to the system's external player.
+- **PlaybackItem Model** — No longer needed without internal playback.
+- **MiniPlayerBar Widget** — Removed the in-app mini player UI.
+- **Media Notification Controls** — Removed notification drawables (`ic_stat_favorite`, `ic_stat_favorite_border`) and the `keep.xml` resource file.
+- **Player Mode Setting** — The `playerMode` setting has been removed since external player is now the only mode.
+- **Online Playback Feature** — Online streaming mode, DASH pipeline, and related components introduced in v4.0.0 are gone from the main branch.
+
+### Changed
+
+- **MainActivity** now extends `FlutterFragmentActivity` directly (previously `AudioServiceFragmentActivity`).
+- **PlaybackController** simplified from ~1200 lines to ~87 lines — now only resolves local file paths and opens them via external player.
+- **ProGuard rules** cleaned up — removed audio_service/just_audio/audio_session rules.
+- **Qobuz** migrated to MusicDL API (Thanks @Ruubiiiii for Hosting the API).
+
+### Note
+There are three main reasons behind this decision:
+
+   1. **Respecting the API providers** — After giving it some thought, we realized that the streaming feature was indirectly hurting the API providers who have been generous enough to make their services available. They already offer streaming directly on their own websites, and it only feels right to direct streaming usage back to their platforms.
+
+   2. **Long-term sustainability** — We want SpotiFLAC to be around for as long as possible. Keeping certain features in the app could attract unwanted attention and put the project's continued existence at risk. Removing them is a proactive step to keep things running smoothly for everyone.
+
+**Still want online playback? Check out these services:**
+- [DabMusic](https://dabmusic.xyz)
+- [SquidWTF](https://tidal.squid.wtf)
+
+Thank you for your understanding and continued support. This decision was made to ensure the long-term sustainability of the app and to respect the ecosystem that has been supporting SpotiFLAC all along. You guys are the best, and we truly appreciate each and every one of you!
+
+---
+
+## [3.6.0] - 2026-02-19
+
+### Added
+
+- **Library Tab Redesign**: Wishlist, Loved, and individual Playlist collections now appear as unified list/grid items in the "All" tab alongside tracks, replacing the old "My Folders" horizontal card section
+- **Drag-and-Drop Track Categorization**: Long-press-drag tracks onto playlist items to add them to that playlist; when multiple tracks are selected and one is dragged, all selected tracks are added to the target playlist
+  - Drag feedback widget displays multi-select count badge
+- **Playlist Multi-Select Deletion**: Long-press playlists to enter selection mode, select multiple playlists, and batch-delete all selected at once via a dedicated selection bottom bar
+- **Track Categorization System**: Tracks added to any playlist are automatically hidden from the main tracks list; removing a track from a playlist or deleting the playlist makes the track reappear — no actual file deletion ever occurs
+- **Create Playlist Button**: New "+" `TextButton.icon` in Library tab header with dynamic theme colors, replacing the old "Select" button
+- **Track Options Bottom Sheet**: Rewrote `TrackCollectionQuickActions` from inline action buttons to a single styled bottom sheet with track header (cover, title, artist), divider, and option tiles matching `DownloadServicePicker` visual style
+- **Library Tracks Folder SliverAppBar**: Wishlist, Loved, and Playlist detail screens now feature a collapsible SliverAppBar with cover art (45% viewport height, parallax, gradient overlay), mode-specific icons (bookmark/heart/queue_music), title, and track count badge
+- **Custom Playlist Cover Images**: Users can set custom cover images for playlists via long-press menu or camera icon in SliverAppBar
+  - Covers stored locally in app support directory with priority: custom cover > first track URL > icon fallback
+  - Cover options bottom sheet with change/remove actions
+  - Playlist list screen shows cover thumbnails
+- **Long-Press Context Menus**: Track tiles in library folders and playlist list items now use long-press for styled bottom sheet context menus instead of trailing icon buttons, matching platform conventions
+- **Wishlist Quick Download**: Tapping a track in Wishlist opens quality picker (respects "Ask quality before download" setting) and starts download
+- **Playlist Track Playback**: Tapping a downloaded track in a Playlist opens it in the device's external music player via `openFile()` with file existence check
+- **Collapsible AppBar on Playlist List Screen**: Playlist list screen now uses a collapsible SliverAppBar matching Settings sub-page style (animated title size 20→28px, animated left padding 56→24px) for visual consistency
+- **`UnifiedLibraryItem.collectionKey` Getter**: Efficient playlist membership checking without constructing a full `Track` object
+- **Multi-select Share**: Share multiple downloaded/local tracks at once from the selection bottom bar
+  - Supports SAF content URIs via native `ACTION_SEND_MULTIPLE` intent
+  - Supports regular file paths via SharePlus
+  - Available in Downloaded Album, Local Album, and Queue tab screens
+- **Multi-select Batch Convert**: Convert multiple selected tracks to MP3 or Opus in one operation
+  - Bottom sheet UI with format (MP3 / Opus) and bitrate (128k / 192k / 256k / 320k) selection
+  - Full SAF support: copies to temp, converts, writes back, deletes original, updates history
+  - Progress and result snackbar feedback during conversion
+  - Available in Downloaded Album, Local Album, and Queue tab screens
+- **Native `shareMultipleContentUris`**: New Android `ACTION_SEND_MULTIPLE` handler in `MainActivity` for sharing multiple SAF content URIs
+- **Localization**: Added selection share/convert strings to all 13 supported locales (`selectionShareCount`, `selectionShareNoFiles`, `selectionConvertCount`, `selectionConvertNoConvertible`, `selectionBatchConvertConfirmTitle`, `selectionBatchConvertConfirmMessage`, `selectionBatchConvertProgress`, `selectionBatchConvertSuccess`)
+- **Localization**: Added library collection l10n keys (`trackOptionAddToLoved`, `trackOptionRemoveFromLoved`, `trackOptionAddToWishlist`, `trackOptionRemoveFromWishlist`, `libraryTracksUnit`, `collectionPlaylistChangeCover`, `collectionPlaylistRemoveCover`)
+- **Global Network Compatibility Mode**: New Download settings toggle to help restricted/ISP-filtered networks
+  - Applies to backend API requests (not SongLink-only)
+  - Enables HTTP scheme fallback and optional insecure TLS behavior in one switch
+  - Synced end-to-end across Flutter settings, platform channel (Android/iOS), and Go backend
+
+### Changed
+
+- **Removed "My Folders" Section**: Horizontal card section removed from Library tab header; collections are now inline items in the unified main list/grid
+- **Playlist Subtitle Simplified**: Playlist items now show "N tracks" instead of "Playlist • N tracks"
+- **Pinned App Bar on All Detail Screens**: `SliverAppBar` changed from `pinned: false` to `pinned: true` in 6 detail screens (album, downloaded album, local album, playlist, track metadata, library tracks folder) so the app bar stays visible when scrolling
+- **Local Album Multi-select Action Updated**: Replaced batch `Share` action with batch `Re-enrich`
+  - Local album selection bar now uses `Re-enrich` + `Convert` actions
+  - Added batch re-enrich processing for local tracks (FLAC native path and MP3/Opus FFmpeg path, including SAF write-back flow)
+  - After batch re-enrich completes, local library is refreshed via incremental scan so updated metadata appears in UI immediately
+- **Queue Multi-select Local Action Updated**: Queue selection bar now switches the first action to `Re-enrich` when selected items are local-only
+  - If selection contains downloaded or mixed items, action remains `Share`
+  - Local-only selection now supports batch re-enrich with the same native/FFmpeg + SAF flow and auto-refreshes local library metadata after completion
+- **SongLink Network Option Scope Expanded**: The previous SongLink compatibility path now routes through global network compatibility controls so all supported backend API clients can benefit under problematic networks
+- **Removed Per-Track Action Buttons**: Album, playlist, home, artist, and search screens no longer show individual download/add buttons on each track tile; all actions accessed via `TrackCollectionQuickActions` bottom sheet
+- **Loved SliverAppBar Always Shows Heart Icon**: Loved tracks folder always displays the heart icon as cover, never uses first track's cover art (like Spotify's Liked Songs)
+- **Wishlist Long-Press Menu Conditional Actions**: "Add to Playlist" option only appears when the track is already downloaded
+- **Loved Track Tap Disabled**: Tapping a track in the Loved folder performs no action (long-press for options only)
+- **Removed Duplicate Create Playlist Button**: Removed `+` IconButton from playlist list screen AppBar since the FAB already serves the same purpose
+- **`coverImagePath` Field on `UserPlaylistCollection`**: Model now supports nullable custom cover path with `copyWith` using `String? Function()?` pattern for explicit null assignment
+
+### Fixed
+
+- **Local Cover Path Handling**: All cover image renderers (Library tab, playlist detail screen hero cover, per-track tiles, options bottom sheet) now detect whether `coverUrl` is a URL or local file path and use `Image.file` for local paths instead of `CachedNetworkImage`
+- **Empty Playlists Now Clickable**: Empty playlist items in Library tab can now be tapped to navigate to their detail screen
+- **RenderFlex Overflow**: Fixed overflow in unified library item Row layout when track metadata text was too long
+- **SAF FD Permission Denied on Tidal Downloads**: Fixed `failed to create file: open /proc/self/fd/*: permission denied` on some devices/providers
+  - Android SAF bridge now hands off detached raw FD (`output_fd`) to Go instead of forcing procfs path reopen
+  - Go output writer includes safer procfs fallback behavior for providers that reject truncate semantics
+- **Batch Convert Lyrics Embedding Gap**: Batch convert in Downloaded Album, Local Album, and Queue now preserves/adds lyrics consistently like single convert
+  - Reuses embedded lyrics when available
+  - Falls back to sidecar `.lrc` when present
+  - Falls back to online lyrics fetch and injects into conversion metadata when embedding is enabled
+
+---
+
+## [3.6.9] - 2026-02-17
+
+### Added
+
+- **YouTube Bitrate Presets**: YouTube bitrate selection now uses supported presets only
+  - Opus: 128 / 256 kbps
+  - MP3: 128 / 256 / 320 kbps
+- **Go Test Coverage for YouTube Quality Parsing**: Added tests for supported-bitrate normalization behavior
+- **Localization for YouTube Bitrate UI**: Added localized strings (EN/ID) for YouTube bitrate titles and labels
+
+### Fixed
+
+- **Cover Image Cache Clear Not Working**: Clearing "Cover image cache" now performs a full on-disk wipe, clears in-memory image cache, and reinitializes cache manager state
+  - Prevents stale/orphaned cache files from keeping the same storage usage after clear
+- **YouTube Queue Fallback Quality Mismatch**: Queue fallback now normalizes YouTube quality IDs so conversion paths use valid bitrate format IDs
+
+### Changed
+
+- **Default Lyrics Behavior**: `Apple/QQ Multi-Person Word-by-Word` is now OFF by default for new installs
+- **Removed Dynamic YouTube Bitrate Mode**: Arbitrary values are now normalized to nearest supported Spotube preset across settings, picker, queue fallback, and Go backend parser
+- **Lyrics Embedding Control**: Users can now disable the embedded-lyrics process from settings (`Embed Lyrics` off)
+
+---
+
+## [3.6.8] - 2026-02-14
+
+### Added
+
+- **Lyrics Source Tracking**: Track Metadata screen now displays the source of loaded lyrics (LRCLIB, Musixmatch, Netease, Apple Music, QQ Music, Embedded, or Extension)
+  - New `getLyricsLRCWithSource` API returns lyrics with source metadata
+  - Source badge appears below lyrics section in Track Metadata screen
+- **Dedicated Lyrics Provider Priority Page**: Lyrics providers can now be configured from a dedicated settings page with full-screen reorderable list
+  - Replaced inline bottom sheet with `LyricsProviderPriorityPage`
+  - Cleaner UI with provider descriptions and priority ordering
+- **Paxsenix Integration**: Added Paxsenix API as official lyrics proxy partner for Apple Music, QQ Music, Musixmatch, and Netease sources
+  - Listed in About page and Partners page on project site
+  - README updated with partner attribution
+
+### Fixed
+
+- **LRC Background Vocal Preservation**: Apple Music/QQ Music `[bg:...]` background vocal tags are now preserved during LRC parsing instead of being stripped
+  - Background vocals attach to the previous timed line in exported LRC files
+- **LRC Display Improvements**:
+  - Inline word-by-word timestamps (`<mm:ss.xx>`) are stripped from lyrics display
+  - Speaker prefixes (`v1:`, `v2:`) are removed for cleaner display
+  - Multi-line background vocals converted to readable secondary vocal lines
+- **Apple Music Lyrics Case Sensitivity**: Fixed `lyricsType` comparison to use case-insensitive matching for "Syllable" type
+
+### Changed
+
+- Track Metadata lyrics fetching now uses `getLyricsLRCWithSource` for consistent source attribution across embedded and online lyrics
+
+---
+
+## [3.6.7] - 2026-02-13
+
+### Added
+
+- "Advanced Filename Templates" - new placeholders for custom track/disc formatting and date patterns
+  - `{track_raw}` and `{disc_raw}` - unpadded raw numbers
+  - `{track:N}` and `{disc:N}` - zero-padded to N digits (e.g. `{track:02}` → `01`)
+  - `{date}` - full release date from metadata
+  - `{date:%Y-%m-%d}` - date formatting with strftime patterns
+  - "Show advanced tags" toggle in Settings > Download > Filename Format to reveal these placeholders
+- Low-RAM / ARM32-only device profiling - detects constrained devices at startup and reduces image cache (120 items / 24 MiB) and disables overscroll effects for smoother performance
+- Responsive selection bar on artist screen - switches to compact stacked layout on narrow screens (< 430dp) or large text scale (> 1.15x)
+- Quality picker dialog before downloading individual tracks from artist screen (when "Ask quality before download" is enabled)
+- Project website with GitHub Pages deployment workflow
+  - Mobile burger menu navigation for all site pages
+- Go filename template test suite
+- "Lyrics Provider" extension type - extensions can now provide lyrics (synced or plain text) via `fetchLyrics()` function
+  - Lyrics provider extensions are called before built-in providers, giving extensions highest priority
+  - New `lyrics_provider` manifest type alongside `metadata_provider` and `download_provider`
+  - Shows "Lyrics Provider" capability badge on extension detail page
+- "Lyrics Providers" settings - configurable provider cascade order and per-provider options
+  - Reorderable provider list: LRCLIB, Musixmatch, Netease, Apple Music, QQ Music
+  - Netease: toggle translated/romanized lyrics appending
+  - Apple Music / QQ Music: multi-person word-by-word speaker tags
+  - Musixmatch: selectable language code for localized lyrics
+- "Documentation Search" - global search modal on all site pages
+  - Opens with Ctrl+K / Cmd+K / `/` keyboard shortcuts on every page
+  - Search button with bordered pill styling in desktop nav and mobile hamburger menu
+  - On non-docs pages, search results navigate to the docs page at the matching section
+  - Full keyboard navigation: arrow keys, Enter to select, Esc to close
+
+### Fixed
+
+- Fixed ICU plural syntax errors in DE, ES, PT, RU translations - incorrect `=1` clause was causing missing plural forms
+- Fixed featured-artist regex incorrectly splitting on `&` character (e.g. "Simon & Garfunkel" was being split) - removed `&` from separator pattern
+- Fixed `{date}` placeholder not working in filename templates - release date was not being passed to the template builder across all providers (Amazon, Qobuz, Tidal, YouTube, extensions)
+
+### Changed
+
+- Improved Go backend metadata handling - filename builder now supports fallback metadata keys and automatic type conversion for more robust template rendering
+- Extension providers now pass full metadata set to filename builder (track, disc, year, date, release_date)
+- Updated translations: added filename advanced tags strings (EN, ID), regenerated all locale dart files
+- Updated app screenshot assets
+
+---
+
+## [3.6.6] - 2026-02-12
+
+### Added
+
+- "Filter Contributing Artists in Album Artist" setting - strips featured/contributing artists from Album Artist metadata tag
+- Library scan notifications (Android and iOS) - shows progress, completion, failure, and cancellation status
+- Collapsible "Artist Name Filters" section in download settings UI
+
+### Fixed
+
+- Fixed downloads not working on iOS - missing `downloadByStrategy` and `downloadFromYouTube` method channel handlers in AppDelegate.swift
+- Fixed extended metadata (genre, label, copyright) lost during service fallback (e.g. Tidal unavailable, falls back to Qobuz) - Go backend now enriches metadata from Deezer by ISRC before download and preserves it through the fallback chain
+- Fixed local library showing incorrect "16-bit" quality label for lossy formats (MP3, Opus) - now displays actual bitrate (e.g. "MP3 320kbps")
+- Fixed inaccurate Opus/Vorbis duration calculation (e.g. 4:11 showing as 8:44) - now reads granule position from last Ogg page for precise duration
+- Fixed MP3 duration/bitrate inaccuracy for VBR files - added Xing/Info and VBRI header parsing with MPEG2/2.5 bitrate table support
+- Fixed Track Metadata screen showing scan date instead of file date for local library items
+- Fixed SAF content URI paths displayed as raw `content://` strings in Track Metadata - now shows human-readable paths
+
+### Changed
+
+- Removed legacy iOS download handlers (`downloadTrack`, `downloadWithFallback`, `downloadFromYouTube`) - iOS now uses `downloadByStrategy` only
+- Updated translations from Crowdin (all 14 languages)
+
+---
+
+## [3.6.5] - 2026-02-10
+
+### Highlights
+
+- **Audio Format Conversion**: Convert between FLAC, MP3, and Opus directly from Track Metadata screen with full metadata and cover art preservation
+- **PC v7.0.8 Backend Merge**: Adopts several Go backend improvements from SpotiFLAC PC v7.0.8 including Amazon encrypted stream support, SpotFetch metadata fallback, and Qobuz API update
+- **Amazon Music Re-enabled**: Amazon provider back in service with new API
+
+### Added
+
+- "Use Primary Artist Only" setting: strips featured artists from folder names (e.g. "Justin Bieber, Quavo" becomes "Justin Bieber") for cleaner folder organization
+  - Supports separators: `, ` `;` `&` `feat.` `ft.` `featuring` `with` `x`
+  - Available in Settings > Download > below "Use Album Artist for folders"
+- Audio format conversion from Track Metadata screen
+  - Convert between FLAC, MP3, and Opus formats (any direction)
+  - Selectable bitrate: 128k, 192k, 256k, 320k
+  - Full metadata and cover art preservation during conversion
+  - Confirmation dialog before converting (original file deleted after)
+  - SAF storage support: copies to temp, converts, writes back via SAF
+  - Download history automatically updated with new file path
+- Unified download request contract (`DownloadRequestPayload`) for all providers/flows
+  - Includes full superset fields: lyrics mode, genre/label/copyright, provider IDs, SAF params, cover/quality settings
+  - Added strategy flags in payload: `use_extensions`, `use_fallback`
+- New Go unified router entrypoint: `DownloadByStrategy(requestJSON)`
+  - Routing priority: YouTube service -> extension fallback -> built-in fallback -> direct service
+- New Android method channel handler: `"downloadByStrategy"` -> `Gobackend.downloadByStrategy(...)`
+- SpotFetch metadata fallback integration for Spotify-blocked regions
+  - New backend client for `sp.afkarxyz.qzz.io/api`
+  - Automatic fallback in Spotify metadata fetch path when primary source fails
+- Lyrics extraction now supports MP3 (ID3v2) and Opus/OGG (Vorbis comments) in addition to FLAC
+  - Includes heuristic detection of lyrics stored in Comment fields
+- 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 `amzn.afkarxyz.qzz.io` API flow (ASIN-based track endpoint + legacy fallback) with encrypted stream support
+- Amazon ASIN extraction rewritten with robust URL/query-param parsing and regex fallback
+- Amazon provider re-enabled in download service picker and download settings (alongside Tidal, Qobuz, and YouTube picker flow)
+- Track Metadata cover UI now refreshes from the embedded file after Edit Metadata/Re-enrich, so the displayed art matches actual file tags
+- 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
@@ -78,7 +819,7 @@ Same as 3.3.1 but fixes crash issues caused by FFmpeg.
 - **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
 
@@ -198,7 +939,7 @@ Same as 3.3.1 but fixes crash issues caused by FFmpeg.
   - 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
 
@@ -495,4 +1236,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)

CONTRIBUTING.md

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

README.md

@@ -1,19 +1,29 @@
-[![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)
-[![Crowdin](https://img.shields.io/badge/HELP%20TRANSLATE%20ON-CROWDIN-%2321252b?style=for-the-badge&logo=crowdin)](https://crowdin.com/project/spotiflac-mobile)
-
 <div align="center">
 
-<img src="icon.png" width="128" />
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="assets/images/banner-readme-dark.png">
+  <source media="(prefers-color-scheme: light)" srcset="assets/images/banner-readme-light.png">
+  <img alt="SpotiFLAC Mobile" src="assets/images/banner-readme-light.png" width="650" height="auto">
+</picture>
 
-Download music in true lossless FLAC from Tidal, Qobuz & Amazon Music — no account required.
-
-![Android](https://img.shields.io/badge/Android-7.0%2B-3DDC84?style=for-the-badge&logo=android&logoColor=white)
-![iOS](https://img.shields.io/badge/iOS-14.0%2B-000000?style=for-the-badge&logo=apple&logoColor=white)
+<p align="center">
+  <a href="https://trendshift.io/repositories/17247">
+    <img src="https://trendshift.io/api/badge/repositories/17247" alt="zarzet%2FSpotiFLAC-Mobile | Trendshift" width="250" height="55">
+  </a>
+</p>
 
 </div>
 
-### [Download](https://github.com/zarzet/SpotiFLAC-Mobile/releases)
+<div align="center">
+
+[![GitHub Release](https://img.shields.io/github/v/release/zarzet/SpotiFLAC-Mobile?style=for-the-badge&logo=github)](https://github.com/zarzet/SpotiFLAC-Mobile/releases)
+[![VirusTotal](https://img.shields.io/badge/VirusTotal-Safe-brightgreen?style=for-the-badge&logo=virustotal)](https://www.virustotal.com/gui/file/31d1bf3c3b2015c13e83c4f909a7c6093a9423e3e702f0c582a3e0035c849424)
+[![Crowdin](https://img.shields.io/badge/HELP%20TRANSLATE%20ON-CROWDIN-%2321252b?style=for-the-badge&logo=crowdin)](https://crowdin.com/project/spotiflac-mobile)
+
+[![Telegram Channel](https://img.shields.io/badge/CHANNEL-2CA5E0?style=for-the-badge&logo=telegram&logoColor=white)](https://t.me/spotiflac)
+[![Telegram Community](https://img.shields.io/badge/COMMUNITY-2CA5E0?style=for-the-badge&logo=telegram&logoColor=white)](https://t.me/spotiflac_chat)
+
+</div>
 
 ## Screenshots
 
@@ -24,90 +34,154 @@ 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.
+Extensions let the community add new music sources and features without waiting for app updates. When a streaming service API changes or a new source becomes available, extensions can be updated independently.
 
 ### Installing Extensions
-1. Go to **Store** tab in the app
-2. Browse and install extensions with one tap
-3. Or download a `.spotiflac-ext` file and install manually via **Settings > Extensions**
-4. Configure extension settings if needed
-5. Set provider priority in **Settings > Extensions > Provider Priority**
+
+1. Open the **Store** tab in the app
+2. On first launch, enter an **Extension Repository URL** when prompted
+3. Browse and install extensions with one tap
+4. Or download a `.spotiflac-ext` file and install manually via **Settings > Extensions**
+5. Configure extension settings if needed
+6. Set provider priority under **Settings > Extensions > Provider Priority**
 
 ### Developing Extensions
-Want to create your own extension? Check out the [Extension Development Guide](https://zarz.moe/docs) for complete documentation.
 
-## Other project
+> [!NOTE]
+> Want to build your own extension? The [Extension Development Guide](https://zarzet.github.io/SpotiFLAC-Mobile/docs) has everything you need.
+
+---
+
+## Related Projects
 
 ### [SpotiFLAC (Desktop)](https://github.com/afkarxyz/SpotiFLAC)
-Download music in true lossless FLAC from Tidal, Qobuz & Amazon Music for Windows, macOS & Linux
+Download music in true lossless FLAC from Tidal, Qobuz & Amazon Music available for Windows, macOS & Linux.
 
-## Telegram
+### [SpotiFLAC (Python Module)](https://github.com/ShuShuzinhuu/SpotiFLAC-Module-Version)
+Python library for SpotiFLAC integration, maintained by [@ShuShuzinhuu](https://github.com/ShuShuzinhuu).
 
-<p align="center">
-  <a href="https://t.me/spotiflac">
-    <img src="https://img.shields.io/badge/Telegram-Channel-2CA5E0?style=for-the-badge&logo=telegram&logoColor=white" alt="Telegram Channel">
-  </a>
-
-  <a href="https://t.me/spotiflac_chat">
-    <img src="https://img.shields.io/badge/Telegram-Community-2CA5E0?style=for-the-badge&logo=telegram&logoColor=white" alt="Telegram Community">
-  </a>
-</p>
+---
 
 ## FAQ
 
-**Q: Why is my download failing with "Song not found"?**  
-A: The track may not be available on Tidal, Qobuz, or Amazon Music. Try enabling more download services in Settings > Download > Provider Priority, or install additional extensions from the Store.
+<details>
+<summary><b>Why does the Store tab ask me to enter a URL?</b></summary>
+<br>
 
-**Q: Why are some tracks downloading in lower quality?**  
-A: Quality depends on what's available from the streaming service. Tidal offers up to 24-bit/192kHz, Qobuz up to 24-bit/192kHz, and Amazon up to 24-bit/48kHz. The app automatically selects the best available quality.
+Starting from version 3.8.0, SpotiFLAC uses a decentralized extension repository system extensions are hosted on GitHub repositories rather than a built-in server, so anyone can create and host their own. Enter a repository URL in the Store tab to browse and install extensions.
 
-**Q: Can I download playlists?**  
-A: Yes! Just paste the playlist URL in the search bar. The app will fetch all tracks and queue them for download.
+</details>
 
-**Q: Why do I need to grant storage permission?**  
-A: The app needs permission to save downloaded files to your device. On Android 13+, you may need to grant "All files access" in Settings > Apps > SpotiFLAC > Permissions.
+<details>
+<summary><b>Why is my download failing with "Song not found"?</b></summary>
+<br>
 
-**Q: Is this app safe?**  
-A: Yes, the app is open source and you can verify the code yourself. Each release is scanned with VirusTotal (see badge at top of README).
+The track may not be available on the streaming services. Try enabling more providers under **Settings > Download > Provider Priority**, or install additional extensions like Amazon Music from the Store.
 
-**Q: Why is download not working in my country?**  
-A: Some countries have restricted access to certain streaming service APIs. If downloads are failing, try using a VPN to connect through a different region.
+</details>
 
+<details>
+<summary><b>Why are some tracks downloading in lower quality?</b></summary>
+<br>
 
-### Want to support SpotiFLAC-Mobile?
+Quality depends on what's available from the streaming service and its extensions. Built-in providers:
+- **Tidal** up to 24-bit/192kHz
+- **Qobuz** up to 24-bit/192kHz
+- **Deezer** up to 16-bit/44.1kHz
 
-_If this software is useful and brings you value, consider supporting the project by buying me a coffee. Your support helps keep development going._
+</details>
 
-[![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>
+<details>
+<summary><b>Can I download playlists?</b></summary>
+<br>
 
+Yes! Just paste the playlist URL in the search bar. The app will fetch all tracks and queue them for download.
+
+</details>
+
+<details>
+<summary><b>Why do I need to grant storage permission?</b></summary>
+<br>
+
+The app needs permission to save downloaded files to your device. On Android 13+, you may need to grant **All files access** under **Settings > Apps > SpotiFLAC > Permissions**.
+
+</details>
+
+<details>
+<summary><b>Is this app safe?</b></summary>
+<br>
+
+Yes SpotiFLAC is open source and you can verify the code yourself. Each release is also scanned with VirusTotal (see badge above).
+
+</details>
+
+<details>
+<summary><b>Why is downloading not working in my country?</b></summary>
+<br>
+
+Some countries have restricted access to certain streaming service APIs. If downloads are failing, try using a VPN to connect through a different region.
+
+</details>
+
+<details>
+<summary><b>Can I add SpotiFLAC to AltStore or SideStore?</b></summary>
+<br>
+
+Yes! Add the official source to receive updates directly within the app. Copy this link:
+
+```
+https://raw.githubusercontent.com/zarzet/SpotiFLAC-Mobile/refs/heads/main/apps.json
+```
+
+In AltStore/SideStore, go to **Browse > Sources**, tap **+**, and paste the link.
+
+</details>
+
+> [!NOTE]
+> If SpotiFLAC is useful to you, consider supporting development:
+>
+> [![Ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/zarzet)
+
+---
+
+## Contributors
+
+Thanks to everyone who has contributed to SpotiFLAC Mobile!
+
+<a href="https://github.com/zarzet/SpotiFLAC-Mobile/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=zarzet/SpotiFLAC-Mobile" />
+</a>
+
+We also appreciate everyone who helped with [translations on Crowdin](https://crowdin.com/project/spotiflac-mobile), reported bugs, suggested features, and spread the word.
+
+Interested in contributing? Check out the [Contributing Guide](CONTRIBUTING.md) to get started!
+
+---
+
+## 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) | [Monochrome](https://monochrome.tf) |
+
+---
 
 ## Disclaimer
 
-This project is for **educational and private use only**. The developer does not condone or encourage copyright infringement.
-
-**SpotiFLAC** is a third-party tool and is not affiliated with, endorsed by, or connected to Tidal, Qobuz, Amazon Music, Deezer, or any other streaming service.
-
-The application is purely a user interface that facilitates communication between your device and existing third-party services.
-
-You are solely responsible for:
-1. Ensuring your use of this software complies with your local laws.
-2. Reading and adhering to the Terms of Service of the respective platforms.
-3. Any legal consequences resulting from the misuse of this tool.
-
-The software is provided "as is", without warranty of any kind. The author assumes no liability for any bans, damages, or legal issues arising from its use.
+This repository and its contents are provided strictly for educational and research purposes. The software is provided "as-is" without warranty of any kind, express or implied, as stated in the [MIT License](LICENSE).
 
+- No copyrighted content is hosted, stored, mirrored, or distributed by this repository.
+- Users must ensure that their use of this software is properly authorized and complies with all applicable laws, regulations, and third-party terms of service.
+- This software is provided free of charge by the maintainer. If you paid a third party for access to this software in its original form from this repository, you may have been misled or scammed. Any redistribution or commercial use by third parties must comply with the terms of the repository license. No affiliation, endorsement, or support by the maintainer is implied unless explicitly stated in writing.
+- SpotiFLAC Mobile is an independent project. It is not affiliated with, endorsed by, or connected to any other project or version on other platforms that may share a similar name. The maintainer of this repository has no control over or responsibility for third-party projects.
+- The author(s) disclaim all liability for any direct, indirect, incidental, or consequential damages arising from the use or misuse of this software. Users assume all risk associated with its use.
+- If you are a copyright holder or authorized representative and believe this repository infringes upon your rights, please contact the maintainer with sufficient detail (including relevant URLs and proof of ownership). The matter will be promptly investigated and appropriate action will be taken, which may include removal of the referenced material.
 
 > [!TIP]
->
-> **Star Us**, You will receive all release notifications from GitHub without any delay ~
+> **Star the repo** to get notified about all new releases directly from GitHub.

analysis_options.yaml

@@ -9,6 +9,19 @@
 # packages, and plugins designed to encourage good coding practices.
 include: package:flutter_lints/flutter.yaml
 
+analyzer:
+  exclude:
+    - build/**
+    - .dart_tool/**
+    - lib/**/*.g.dart
+    - lib/l10n/*.dart
+  language:
+    strict-casts: true
+    strict-inference: true
+    strict-raw-types: true
+  plugins:
+    - custom_lint
+
 linter:
   # The lint rules applied to this project can be customized in the
   # section below to disable rules from the `package:flutter_lints/flutter.yaml`
@@ -23,6 +36,13 @@ linter:
   rules:
     # avoid_print: false  # Uncomment to disable the `avoid_print` rule
     # prefer_single_quotes: true  # Uncomment to enable the `prefer_single_quotes` rule
+    avoid_dynamic_calls: true
+    cancel_subscriptions: true
+    close_sinks: true
+
+custom_lint:
+  rules:
+    - avoid_public_notifier_properties
 
 # Additional information about this file can be found at
 # https://dart.dev/guides/language/analysis-options

android/app/build.gradle.kts

@@ -20,6 +20,10 @@ android {
     compileSdk = flutter.compileSdkVersion
     ndkVersion = flutter.ndkVersion
 
+    buildFeatures {
+        buildConfig = true
+    }
+
     compileOptions {
         isCoreLibraryDesugaringEnabled = true
         sourceCompatibility = JavaVersion.VERSION_17
@@ -57,6 +61,18 @@ android {
     }
 
     buildTypes {
+        getByName("debug") {
+            ndk {
+                debugSymbolLevel = "FULL"
+            }
+        }
+
+        getByName("profile") {
+            ndk {
+                debugSymbolLevel = "FULL"
+            }
+        }
+
         release {
             // For local builds: use release signing if key.properties exists
             // For CI builds: APK is signed by GitHub Action after build
@@ -71,6 +87,9 @@ android {
                 getDefaultProguardFile("proguard-android-optimize.txt"),
                 "proguard-rules.pro"
             )
+            ndk {
+                debugSymbolLevel = "FULL"
+            }
         }
     }
     
@@ -96,11 +115,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")
 }

android/app/src/main/AndroidManifest.xml

@@ -12,6 +12,7 @@
     <uses-permission android:name="android.permission.READ_MEDIA_AUDIO" />
     <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
     <uses-permission android:name="android.permission.FOREGROUND_SERVICE_DATA_SYNC" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />
     <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
     <uses-permission android:name="android.permission.REQUEST_INSTALL_PACKAGES" />
     <uses-permission android:name="android.permission.WAKE_LOCK" />
@@ -21,7 +22,9 @@
         android:name="${applicationName}"
         android:icon="@mipmap/ic_launcher"
         android:usesCleartextTraffic="false"
-        android:enableOnBackInvokedCallback="true">
+        android:networkSecurityConfig="@xml/network_security_config"
+        android:enableOnBackInvokedCallback="true"
+        android:localeConfig="@xml/locale_config">
 
         <activity
             android:name=".MainActivity"
@@ -83,6 +86,20 @@
                 <category android:name="android.intent.category.BROWSABLE" />
                 <data android:scheme="https" android:host="music.youtube.com" />
             </intent-filter>
+
+            <!-- Extension OAuth (PKCE) redirect: spotiflac://callback?code=...&state=<extension_id> -->
+            <intent-filter>
+                <action android:name="android.intent.action.VIEW" />
+                <category android:name="android.intent.category.DEFAULT" />
+                <category android:name="android.intent.category.BROWSABLE" />
+                <data android:scheme="spotiflac" android:host="callback" />
+            </intent-filter>
+            <intent-filter>
+                <action android:name="android.intent.action.VIEW" />
+                <category android:name="android.intent.category.DEFAULT" />
+                <category android:name="android.intent.category.BROWSABLE" />
+                <data android:scheme="spotiflac" android:host="spotify-callback" />
+            </intent-filter>
         </activity>
 
         <!-- Download Service -->

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

@@ -104,7 +104,7 @@ class DownloadService : Service() {
                 updateNotification(progress, total)
             }
         }
-        return START_STICKY
+        return START_NOT_STICKY
     }
     
     override fun onBind(intent: Intent?): IBinder? = null
@@ -115,10 +115,8 @@ class DownloadService : Service() {
      * We must call stopSelf() within a few seconds to avoid a crash.
      */
     override fun onTimeout(startId: Int, fgsType: Int) {
-        // Log the timeout for debugging
         android.util.Log.w("DownloadService", "Foreground service timeout reached (6 hours limit). Stopping service.")
         
-        // Gracefully stop the service
         stopForegroundService()
     }
     
@@ -139,14 +137,13 @@ class DownloadService : Service() {
     
     private fun startForegroundService() {
         isRunning = true
-        
-        // Acquire wake lock to prevent CPU sleep
+
         val powerManager = getSystemService(Context.POWER_SERVICE) as PowerManager
         wakeLock = powerManager.newWakeLock(
             PowerManager.PARTIAL_WAKE_LOCK,
             WAKELOCK_TAG
         ).apply {
-            acquire(60 * 60 * 1000L) // 1 hour max
+            acquire(60 * 60 * 1000L)
         }
         
         val notification = buildNotification(0, 0)

android/app/src/main/res/values/colors.xml

@@ -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>

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

@@ -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>

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

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

android/build.gradle.kts

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

android/gradle.properties

@@ -1,2 +1,2 @@
-org.gradle.jvmargs=-Xmx4G -XX:MaxMetaspaceSize=2G -XX:ReservedCodeCacheSize=256m -XX:+HeapDumpOnOutOfMemoryError
+org.gradle.jvmargs=-Xmx2g -XX:MaxMetaspaceSize=512m -XX:ReservedCodeCacheSize=256m -XX:+HeapDumpOnOutOfMemoryError
 android.useAndroidX=true

android/gradle/wrapper/gradle-wrapper.properties

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

android/settings.gradle.kts

@@ -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.3.20" apply false
 }
 
 include(":app")

apps.json

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

cliff.toml

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

go_backend/amazon.go

@@ -1,422 +0,0 @@
-package gobackend
-
-import (
-	"bufio"
-	"context"
-	"encoding/json"
-	"errors"
-	"fmt"
-	"io"
-	"net/http"
-	"net/url"
-	"os"
-	"path/filepath"
-	"regexp"
-	"strings"
-	"sync"
-	"time"
-)
-
-type AmazonDownloader struct {
-	client *http.Client
-}
-
-var (
-	globalAmazonDownloader *AmazonDownloader
-	amazonDownloaderOnce   sync.Once
-)
-
-// AfkarXYZResponse is the response from AfkarXYZ API
-type AfkarXYZResponse struct {
-	Success bool `json:"success"`
-	Data    struct {
-		DirectLink string `json:"direct_link"`
-		FileName   string `json:"file_name"`
-		FileSize   int64  `json:"file_size"`
-	} `json:"data"`
-}
-
-func amazonIsASCIIString(s string) bool {
-	for _, r := range s {
-		if r > 127 {
-			return false
-		}
-	}
-	return true
-}
-
-func NewAmazonDownloader() *AmazonDownloader {
-	amazonDownloaderOnce.Do(func() {
-		globalAmazonDownloader = &AmazonDownloader{
-			client: NewHTTPClientWithTimeout(120 * time.Second),
-		}
-	})
-	return globalAmazonDownloader
-}
-
-func (a *AmazonDownloader) downloadFromAfkarXYZ(amazonURL string) (string, string, error) {
-	apiURL := "https://amazon.afkarxyz.fun/convert?url=" + url.QueryEscape(amazonURL)
-
-	GoLog("[Amazon] Fetching from AfkarXYZ API...\n")
-
-	req, err := http.NewRequest("GET", apiURL, nil)
-	if err != nil {
-		return "", "", fmt.Errorf("failed to create request: %w", err)
-	}
-
-	req.Header.Set("User-Agent", getRandomUserAgent())
-
-	resp, err := a.client.Do(req)
-	if err != nil {
-		return "", "", fmt.Errorf("failed to call AfkarXYZ API: %w", err)
-	}
-	defer resp.Body.Close()
-
-	if resp.StatusCode != 200 {
-		return "", "", fmt.Errorf("AfkarXYZ API returned status %d", resp.StatusCode)
-	}
-
-	body, err := io.ReadAll(resp.Body)
-	if err != nil {
-		return "", "", fmt.Errorf("failed to read response: %w", err)
-	}
-
-	var apiResp AfkarXYZResponse
-	if err := json.Unmarshal(body, &apiResp); err != nil {
-		return "", "", fmt.Errorf("failed to decode response: %w", err)
-	}
-
-	if !apiResp.Success || apiResp.Data.DirectLink == "" {
-		return "", "", fmt.Errorf("AfkarXYZ API failed or no download link found")
-	}
-
-	fileName := apiResp.Data.FileName
-	if fileName == "" {
-		fileName = "track.flac"
-	}
-
-	reg := regexp.MustCompile(`[<>:"/\\|?*]`)
-	fileName = reg.ReplaceAllString(fileName, "")
-
-	GoLog("[Amazon] AfkarXYZ returned: %s (%.2f MB)\n", fileName, float64(apiResp.Data.FileSize)/(1024*1024))
-
-	return apiResp.Data.DirectLink, fileName, nil
-}
-
-func (a *AmazonDownloader) DownloadFile(downloadURL, outputPath, itemID string) error {
-	ctx := context.Background()
-
-	if itemID != "" {
-		StartItemProgress(itemID)
-		defer CompleteItemProgress(itemID)
-		ctx = initDownloadCancel(itemID)
-		defer clearDownloadCancel(itemID)
-	}
-
-	if isDownloadCancelled(itemID) {
-		return ErrDownloadCancelled
-	}
-
-	req, err := http.NewRequestWithContext(ctx, "GET", downloadURL, nil)
-	if err != nil {
-		return fmt.Errorf("failed to create request: %w", err)
-	}
-
-	req.Header.Set("User-Agent", getRandomUserAgent())
-
-	resp, err := a.client.Do(req)
-	if err != nil {
-		if isDownloadCancelled(itemID) {
-			return ErrDownloadCancelled
-		}
-		return err
-	}
-	defer resp.Body.Close()
-
-	if resp.StatusCode != 200 {
-		return fmt.Errorf("download failed: HTTP %d", resp.StatusCode)
-	}
-
-	expectedSize := resp.ContentLength
-	if expectedSize > 0 && itemID != "" {
-		SetItemBytesTotal(itemID, expectedSize)
-	}
-
-	out, err := os.Create(outputPath)
-	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 {
-		os.Remove(outputPath)
-		if isDownloadCancelled(itemID) {
-			return ErrDownloadCancelled
-		}
-		return fmt.Errorf("download interrupted: %w", err)
-	}
-	if flushErr != nil {
-		os.Remove(outputPath)
-		return fmt.Errorf("failed to flush buffer: %w", flushErr)
-	}
-	if closeErr != nil {
-		os.Remove(outputPath)
-		return fmt.Errorf("failed to close file: %w", closeErr)
-	}
-
-	if expectedSize > 0 && written != expectedSize {
-		os.Remove(outputPath)
-		return fmt.Errorf("incomplete download: expected %d bytes, got %d bytes", expectedSize, written)
-	}
-
-	GoLog("[Amazon] Downloaded: %.2f MB (Complete)\n", float64(written)/(1024*1024))
-	return nil
-}
-
-// AmazonDownloadResult contains download result with quality info
-type AmazonDownloadResult struct {
-	FilePath    string
-	BitDepth    int
-	SampleRate  int
-	Title       string
-	Artist      string
-	Album       string
-	ReleaseDate string
-	TrackNumber int
-	DiscNumber  int
-	ISRC        string
-}
-
-func downloadFromAmazon(req DownloadRequest) (AmazonDownloadResult, error) {
-	downloader := NewAmazonDownloader()
-
-	if existingFile, exists := checkISRCExistsInternal(req.OutputDir, req.ISRC); exists {
-		return AmazonDownloadResult{FilePath: "EXISTS:" + existingFile}, 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)
-		availability, err = songlink.CheckAvailabilityFromDeezer(deezerID)
-	} else if req.SpotifyID != "" {
-		availability, err = songlink.CheckTrackAvailability(req.SpotifyID, req.ISRC)
-	} else {
-		return AmazonDownloadResult{}, fmt.Errorf("no valid Spotify or Deezer ID provided for Amazon lookup")
-	}
-
-	if err != nil {
-		return AmazonDownloadResult{}, fmt.Errorf("failed to check Amazon availability via SongLink: %w", err)
-	}
-
-	if !availability.Amazon || availability.AmazonURL == "" {
-		return AmazonDownloadResult{}, fmt.Errorf("track not available on Amazon Music (SongLink returned no Amazon URL)")
-	}
-
-	if 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)
-	if err != nil {
-		return AmazonDownloadResult{}, fmt.Errorf("failed to get download URL from AfkarXYZ: %w", err)
-	}
-
-	GoLog("[Amazon] Match found: '%s' by '%s'\n", req.TrackName, req.ArtistName)
-
-	filename := buildFilenameFromTemplate(req.FilenameFormat, map[string]any{
-		"title":  req.TrackName,
-		"artist": req.ArtistName,
-		"album":  req.AlbumName,
-		"track":  req.TrackNumber,
-		"year":   extractYear(req.ReleaseDate),
-		"disc":   req.DiscNumber,
-	})
-	filename = sanitizeFilename(filename) + ".flac"
-	outputPath := filepath.Join(req.OutputDir, filename)
-
-	if fileInfo, statErr := os.Stat(outputPath); statErr == nil && fileInfo.Size() > 0 {
-		return AmazonDownloadResult{FilePath: "EXISTS:" + outputPath}, nil
-	}
-
-	// START PARALLEL: Fetch cover and lyrics while downloading audio
-	var parallelResult *ParallelDownloadResult
-	parallelDone := make(chan struct{})
-	go func() {
-		defer close(parallelDone)
-		parallelResult = FetchCoverAndLyricsParallel(
-			req.CoverURL,
-			req.EmbedMaxQualityCover,
-			req.SpotifyID,
-			req.TrackName,
-			req.ArtistName,
-			req.EmbedLyrics,
-			int64(req.DurationMS),
-		)
-	}()
-
-	// Download audio file with item ID for progress tracking
-	if err := downloader.DownloadFile(downloadURL, outputPath, req.ItemID); err != nil {
-		if errors.Is(err, ErrDownloadCancelled) {
-			return AmazonDownloadResult{}, ErrDownloadCancelled
-		}
-		return AmazonDownloadResult{}, fmt.Errorf("download failed: %w", err)
-	}
-
-	// Wait for parallel operations to complete
-	<-parallelDone
-
-	if req.ItemID != "" {
-		SetItemProgress(req.ItemID, 1.0, 0, 0)
-		SetItemFinalizing(req.ItemID)
-	}
-
-	existingMeta, metaErr := ReadMetadata(outputPath)
-	actualTrackNum := req.TrackNumber
-	actualDiscNum := req.DiscNumber
-	actualDate := req.ReleaseDate
-	actualAlbum := req.AlbumName
-	actualTitle := req.TrackName
-	actualArtist := req.ArtistName
-
-	if metaErr == nil && existingMeta != nil {
-		if existingMeta.TrackNumber > 0 && (req.TrackNumber == 0 || req.TrackNumber == 1) {
-			actualTrackNum = existingMeta.TrackNumber
-			GoLog("[Amazon] Using track number from file: %d (request had: %d)\n", actualTrackNum, req.TrackNumber)
-		}
-		if existingMeta.DiscNumber > 0 && (req.DiscNumber == 0 || req.DiscNumber == 1) {
-			actualDiscNum = existingMeta.DiscNumber
-			GoLog("[Amazon] Using disc number from file: %d (request had: %d)\n", actualDiscNum, req.DiscNumber)
-		}
-		if existingMeta.Date != "" && req.ReleaseDate == "" {
-			actualDate = existingMeta.Date
-			GoLog("[Amazon] Using release date from file: %s\n", actualDate)
-		}
-		if existingMeta.Album != "" && req.AlbumName == "" {
-			actualAlbum = existingMeta.Album
-			GoLog("[Amazon] Using album from file: %s\n", actualAlbum)
-		}
-		GoLog("[Amazon] Existing metadata - Title: %s, Artist: %s, Album: %s, Date: %s\n",
-			existingMeta.Title, existingMeta.Artist, existingMeta.Album, existingMeta.Date)
-	}
-
-	metadata := Metadata{
-		Title:       actualTitle,
-		Artist:      actualArtist,
-		Album:       actualAlbum,
-		AlbumArtist: req.AlbumArtist,
-		Date:        actualDate,
-		TrackNumber: actualTrackNum,
-		TotalTracks: req.TotalTracks,
-		DiscNumber:  actualDiscNum,
-		ISRC:        req.ISRC,
-		Genre:       req.Genre,
-		Label:       req.Label,
-		Copyright:   req.Copyright,
-	}
-
-	var coverData []byte
-	if parallelResult != nil && parallelResult.CoverData != nil && len(parallelResult.CoverData) > 0 {
-		coverData = parallelResult.CoverData
-		GoLog("[Amazon] Using parallel-fetched cover (%d bytes)\n", len(coverData))
-	} else {
-		existingCover, coverErr := ExtractCoverArt(outputPath)
-		if coverErr == nil && len(existingCover) > 0 {
-			coverData = existingCover
-			GoLog("[Amazon] Using existing cover from Amazon file (%d bytes)\n", len(coverData))
-		} else {
-			GoLog("[Amazon] No cover available (parallel fetch failed and no existing cover)\n")
-		}
-	}
-
-	if err := EmbedMetadataWithCoverData(outputPath, metadata, coverData); err != nil {
-		GoLog("[Amazon] Warning: failed to embed metadata: %v\n", err)
-	}
-
-	if req.EmbedLyrics && parallelResult != nil && parallelResult.LyricsLRC != "" {
-		lyricsMode := req.LyricsMode
-		if lyricsMode == "" {
-			lyricsMode = "embed"
-		}
-
-		if lyricsMode == "external" || lyricsMode == "both" {
-			GoLog("[Amazon] Saving external LRC file...\n")
-			if lrcPath, lrcErr := SaveLRCFile(outputPath, parallelResult.LyricsLRC); lrcErr != nil {
-				GoLog("[Amazon] Warning: failed to save LRC file: %v\n", lrcErr)
-			} else {
-				GoLog("[Amazon] LRC file saved: %s\n", lrcPath)
-			}
-		}
-
-		if lyricsMode == "embed" || lyricsMode == "both" {
-			GoLog("[Amazon] Embedding parallel-fetched lyrics (%d lines)...\n", len(parallelResult.LyricsData.Lines))
-			if embedErr := EmbedLyrics(outputPath, parallelResult.LyricsLRC); embedErr != nil {
-				GoLog("[Amazon] Warning: failed to embed lyrics: %v\n", embedErr)
-			} else {
-				GoLog("[Amazon] Lyrics embedded successfully\n")
-			}
-		}
-	} else if req.EmbedLyrics {
-		GoLog("[Amazon] No lyrics available from parallel fetch\n")
-	}
-
-	GoLog("[Amazon] Downloaded successfully from Amazon Music\n")
-
-	quality, err := GetAudioQuality(outputPath)
-	if err != nil {
-		GoLog("[Amazon] Warning: couldn't read quality from file: %v\n", err)
-	} else {
-		GoLog("[Amazon] Actual quality: %d-bit/%dHz\n", quality.BitDepth, quality.SampleRate)
-	}
-
-	finalMeta, metaReadErr := ReadMetadata(outputPath)
-	if metaReadErr == nil && finalMeta != nil {
-		GoLog("[Amazon] Final metadata from file - Track: %d, Disc: %d, Date: %s\n",
-			finalMeta.TrackNumber, finalMeta.DiscNumber, finalMeta.Date)
-		actualTrackNum = finalMeta.TrackNumber
-		actualDiscNum = finalMeta.DiscNumber
-		if finalMeta.Date != "" {
-			req.ReleaseDate = finalMeta.Date
-		}
-	}
-
-	// Add to ISRC index for fast duplicate checking
-	AddToISRCIndex(req.OutputDir, req.ISRC, outputPath)
-
-	bitDepth := 0
-	sampleRate := 0
-	if err == nil {
-		bitDepth = quality.BitDepth
-		sampleRate = quality.SampleRate
-	}
-
-	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,
-	}, nil
-}

go_backend/ape_tags.go

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

go_backend/audio_metadata.go

@@ -5,13 +5,13 @@ import (
 	"encoding/binary"
 	"fmt"
 	"io"
+	"math"
 	"os"
 	"path/filepath"
 	"strconv"
 	"strings"
 )
 
-// AudioMetadata represents common audio file metadata
 type AudioMetadata struct {
 	Title       string
 	Artist      string
@@ -21,11 +21,22 @@ type AudioMetadata struct {
 	Year        string
 	Date        string
 	TrackNumber int
+	TotalTracks int
 	DiscNumber  int
+	TotalDiscs  int
 	ISRC        string
+	Lyrics      string
+	Label       string
+	Copyright   string
+	Composer    string
+	Comment     string
+	// ReplayGain fields (text values, e.g. "-6.50 dB", "0.988831")
+	ReplayGainTrackGain string
+	ReplayGainTrackPeak string
+	ReplayGainAlbumGain string
+	ReplayGainAlbumPeak string
 }
 
-// MP3Quality represents MP3 specific quality info
 type MP3Quality struct {
 	SampleRate int
 	BitDepth   int
@@ -33,17 +44,13 @@ type MP3Quality struct {
 	Bitrate    int
 }
 
-// OggQuality represents Ogg/Opus specific quality info
 type OggQuality struct {
 	SampleRate int
 	BitDepth   int
 	Duration   int
+	Bitrate    int // estimated bitrate in bps
 }
 
-// =============================================================================
-// ID3 Tag Reading (MP3)
-// =============================================================================
-
 func ReadID3Tags(filePath string) (*AudioMetadata, error) {
 	file, err := os.Open(filePath)
 	if err != nil {
@@ -168,9 +175,24 @@ func parseID3v22Frames(data []byte, metadata *AudioMetadata, tagUnsync bool) {
 		case "TCO":
 			metadata.Genre = cleanGenre(value)
 		case "TRK":
-			metadata.TrackNumber = parseTrackNumber(value)
+			metadata.TrackNumber, metadata.TotalTracks = parseIndexPair(value)
 		case "TPA":
-			metadata.DiscNumber = parseTrackNumber(value)
+			metadata.DiscNumber, metadata.TotalDiscs = parseIndexPair(value)
+		case "TCM":
+			metadata.Composer = value
+		case "TPB":
+			metadata.Label = value
+		case "TCR":
+			metadata.Copyright = value
+		case "ULT":
+			if v := extractLyricsFrame(frameData); v != "" && metadata.Lyrics == "" {
+				metadata.Lyrics = v
+			}
+		case "TXX":
+			desc, userValue := extractUserTextFrame(frameData)
+			if isLyricsDescription(desc) && userValue != "" && metadata.Lyrics == "" {
+				metadata.Lyrics = userValue
+			}
 		}
 
 		pos += 6 + frameSize
@@ -272,11 +294,41 @@ func parseID3v23Frames(data []byte, metadata *AudioMetadata, version byte, tagUn
 		case "TCON":
 			metadata.Genre = cleanGenre(value)
 		case "TRCK":
-			metadata.TrackNumber = parseTrackNumber(value)
+			metadata.TrackNumber, metadata.TotalTracks = parseIndexPair(value)
 		case "TPOS":
-			metadata.DiscNumber = parseTrackNumber(value)
+			metadata.DiscNumber, metadata.TotalDiscs = parseIndexPair(value)
 		case "TSRC":
 			metadata.ISRC = value
+		case "TCOM":
+			metadata.Composer = value
+		case "TPUB":
+			metadata.Label = value
+		case "TCOP":
+			metadata.Copyright = value
+		case "COMM":
+			if v := extractCommentFrame(frameData); v != "" {
+				metadata.Comment = v
+			}
+		case "USLT":
+			if v := extractLyricsFrame(frameData); v != "" && metadata.Lyrics == "" {
+				metadata.Lyrics = v
+			}
+		case "TXXX":
+			desc, userValue := extractUserTextFrame(frameData)
+			if isLyricsDescription(desc) && userValue != "" && metadata.Lyrics == "" {
+				metadata.Lyrics = userValue
+			}
+			upperDesc := strings.ToUpper(desc)
+			switch upperDesc {
+			case "REPLAYGAIN_TRACK_GAIN":
+				metadata.ReplayGainTrackGain = userValue
+			case "REPLAYGAIN_TRACK_PEAK":
+				metadata.ReplayGainTrackPeak = userValue
+			case "REPLAYGAIN_ALBUM_GAIN":
+				metadata.ReplayGainAlbumGain = userValue
+			case "REPLAYGAIN_ALBUM_PEAK":
+				metadata.ReplayGainAlbumPeak = userValue
+			}
 		}
 
 		pos += 10 + frameSize
@@ -304,7 +356,6 @@ func readID3v1(file *os.File) (*AudioMetadata, error) {
 		Year:   strings.TrimRight(string(tag[93:97]), " \x00"),
 	}
 
-	// ID3v1.1 track number (if byte 125 is 0 and byte 126 is not)
 	if tag[125] == 0 && tag[126] != 0 {
 		metadata.TrackNumber = int(tag[126])
 	}
@@ -339,6 +390,135 @@ func extractTextFrame(data []byte) string {
 	}
 }
 
+func extractCommentFrame(data []byte) string {
+	if len(data) < 5 {
+		return ""
+	}
+	encoding := data[0]
+	rest := data[4:]
+
+	var text []byte
+	switch encoding {
+	case 1, 2:
+		for i := 0; i+1 < len(rest); i += 2 {
+			if rest[i] == 0 && rest[i+1] == 0 {
+				text = rest[i+2:]
+				break
+			}
+		}
+	default:
+		idx := bytes.IndexByte(rest, 0)
+		if idx >= 0 && idx+1 < len(rest) {
+			text = rest[idx+1:]
+		} else {
+			text = rest
+		}
+	}
+
+	if len(text) == 0 {
+		return ""
+	}
+
+	framed := make([]byte, 1+len(text))
+	framed[0] = encoding
+	copy(framed[1:], text)
+	return extractTextFrame(framed)
+}
+
+func extractLyricsFrame(data []byte) string {
+	if len(data) < 5 {
+		return ""
+	}
+
+	encoding := data[0]
+	rest := data[4:]
+
+	var text []byte
+	switch encoding {
+	case 1, 2:
+		for i := 0; i+1 < len(rest); i += 2 {
+			if rest[i] == 0 && rest[i+1] == 0 {
+				text = rest[i+2:]
+				break
+			}
+		}
+	default:
+		idx := bytes.IndexByte(rest, 0)
+		if idx >= 0 && idx+1 < len(rest) {
+			text = rest[idx+1:]
+		} else {
+			text = rest
+		}
+	}
+
+	if len(text) == 0 {
+		return ""
+	}
+
+	framed := make([]byte, 1+len(text))
+	framed[0] = encoding
+	copy(framed[1:], text)
+	return extractTextFrame(framed)
+}
+
+func extractUserTextFrame(data []byte) (string, string) {
+	if len(data) < 2 {
+		return "", ""
+	}
+
+	encoding := data[0]
+	payload := data[1:]
+
+	var descRaw, valueRaw []byte
+	switch encoding {
+	case 1, 2:
+		for i := 0; i+1 < len(payload); i += 2 {
+			if payload[i] == 0 && payload[i+1] == 0 {
+				descRaw = payload[:i]
+				valueRaw = payload[i+2:]
+				break
+			}
+		}
+	default:
+		idx := bytes.IndexByte(payload, 0)
+		if idx >= 0 {
+			descRaw = payload[:idx]
+			if idx+1 <= len(payload) {
+				valueRaw = payload[idx+1:]
+			}
+		}
+	}
+
+	if len(valueRaw) == 0 {
+		return "", ""
+	}
+
+	descFramed := make([]byte, 1+len(descRaw))
+	descFramed[0] = encoding
+	copy(descFramed[1:], descRaw)
+
+	valueFramed := make([]byte, 1+len(valueRaw))
+	valueFramed[0] = encoding
+	copy(valueFramed[1:], valueRaw)
+
+	return strings.TrimSpace(extractTextFrame(descFramed)), strings.TrimSpace(extractTextFrame(valueFramed))
+}
+
+func isLyricsDescription(description string) bool {
+	switch strings.ToLower(strings.TrimSpace(description)) {
+	case
+		"lyrics",
+		"lyric",
+		"unsyncedlyrics",
+		"unsynced lyrics",
+		"uslt",
+		"lrc":
+		return true
+	default:
+		return false
+	}
+}
+
 func decodeUTF16(data []byte) string {
 	if len(data) < 2 {
 		return ""
@@ -402,14 +582,28 @@ func cleanGenre(genre string) string {
 }
 
 func parseTrackNumber(s string) int {
-	s = strings.TrimSpace(s)
-	if idx := strings.Index(s, "/"); idx > 0 {
-		s = s[:idx]
-	}
-	num, _ := strconv.Atoi(s)
+	num, _ := parseIndexPair(s)
 	return num
 }
 
+func parseIndexPair(s string) (int, int) {
+	s = strings.TrimSpace(s)
+	if s == "" {
+		return 0, 0
+	}
+
+	first := s
+	second := ""
+	if idx := strings.Index(s, "/"); idx > 0 {
+		first = s[:idx]
+		second = s[idx+1:]
+	}
+
+	num, _ := strconv.Atoi(strings.TrimSpace(first))
+	total, _ := strconv.Atoi(strings.TrimSpace(second))
+	return num, total
+}
+
 func removeUnsync(data []byte) []byte {
 	if len(data) == 0 {
 		return data
@@ -430,11 +624,12 @@ func extendedHeaderSize(data []byte, version byte) int {
 		return 0
 	}
 	var size int
-	if version == 3 {
+	switch version {
+	case 3:
 		size = int(binary.BigEndian.Uint32(data[:4]))
-	} else if version == 4 {
+	case 4:
 		size = syncsafeToInt(data[:4])
-	} else {
+	default:
 		return 0
 	}
 	if size <= 0 {
@@ -493,49 +688,128 @@ func GetMP3Quality(filePath string) (*MP3Quality, error) {
 	file.Seek(audioStart, io.SeekStart)
 
 	frameHeader := make([]byte, 4)
-	for i := 0; i < 10000; i++ { // Search first 10KB
+	var frameStart int64 = -1
+	for i := 0; i < 10000; i++ {
 		if _, err := io.ReadFull(file, frameHeader); err != nil {
 			break
 		}
 
 		if frameHeader[0] == 0xFF && (frameHeader[1]&0xE0) == 0xE0 {
-			version := (frameHeader[1] >> 3) & 0x03
-			layer := (frameHeader[1] >> 1) & 0x03
-			bitrateIdx := (frameHeader[2] >> 4) & 0x0F
-			sampleRateIdx := (frameHeader[2] >> 2) & 0x03
-
-			sampleRates := [][]int{
-				{11025, 12000, 8000},
-				{0, 0, 0},
-				{22050, 24000, 16000},
-				{44100, 48000, 32000},
-			}
-			if version < 4 && sampleRateIdx < 3 {
-				quality.SampleRate = sampleRates[version][sampleRateIdx]
-			}
-
-			if version == 3 && layer == 1 {
-				bitrates := []int{0, 32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320, 0}
-				if bitrateIdx < 16 {
-					quality.Bitrate = bitrates[bitrateIdx] * 1000
-				}
-			}
-
-			quality.BitDepth = 16
-
-			if quality.Bitrate > 0 {
-				audioSize := fileSize - audioStart - 128
-				if audioSize > 0 {
-					quality.Duration = int(audioSize * 8 / int64(quality.Bitrate))
-				}
-			}
-
+			pos, _ := file.Seek(0, io.SeekCurrent)
+			frameStart = pos - 4
 			break
 		}
 
 		file.Seek(-3, io.SeekCurrent)
 	}
 
+	if frameStart < 0 {
+		return quality, nil
+	}
+
+	version := (frameHeader[1] >> 3) & 0x03
+	layer := (frameHeader[1] >> 1) & 0x03
+	bitrateIdx := (frameHeader[2] >> 4) & 0x0F
+	sampleRateIdx := (frameHeader[2] >> 2) & 0x03
+	channelMode := (frameHeader[3] >> 6) & 0x03
+
+	sampleRates := [][]int{
+		{11025, 12000, 8000},
+		{0, 0, 0},
+		{22050, 24000, 16000},
+		{44100, 48000, 32000},
+	}
+	if version < 4 && sampleRateIdx < 3 {
+		quality.SampleRate = sampleRates[version][sampleRateIdx]
+	}
+
+	if version == 3 && layer == 1 {
+		bitrates := []int{0, 32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320, 0}
+		if bitrateIdx < 16 {
+			quality.Bitrate = bitrates[bitrateIdx] * 1000
+		}
+	}
+	if (version == 0 || version == 2) && layer == 1 {
+		bitrates := []int{0, 8, 16, 24, 32, 40, 48, 56, 64, 80, 96, 112, 128, 144, 160, 0}
+		if bitrateIdx < 16 {
+			quality.Bitrate = bitrates[bitrateIdx] * 1000
+		}
+	}
+
+	samplesPerFrame := 1152 // MPEG1 Layer III
+	if version == 0 || version == 2 {
+		samplesPerFrame = 576 // MPEG2/2.5 Layer III
+	}
+
+	var xingOffset int
+	if version == 3 { // MPEG1
+		if channelMode == 3 { // Mono
+			xingOffset = 17
+		} else {
+			xingOffset = 32
+		}
+	} else { // MPEG2/2.5
+		if channelMode == 3 {
+			xingOffset = 9
+		} else {
+			xingOffset = 17
+		}
+	}
+
+	xingBuf := make([]byte, 200)
+	file.Seek(frameStart+4, io.SeekStart)
+	n, _ := io.ReadFull(file, xingBuf)
+	xingBuf = xingBuf[:n]
+
+	vbrFrames := 0
+	vbrBytes := int64(0)
+	isVBR := false
+
+	if xingOffset+8 <= n {
+		tag := string(xingBuf[xingOffset : xingOffset+4])
+		if tag == "Xing" || tag == "Info" {
+			flags := binary.BigEndian.Uint32(xingBuf[xingOffset+4 : xingOffset+8])
+			off := xingOffset + 8
+			if flags&0x01 != 0 && off+4 <= n { // Frames flag
+				vbrFrames = int(binary.BigEndian.Uint32(xingBuf[off : off+4]))
+				off += 4
+			}
+			if flags&0x02 != 0 && off+4 <= n { // Bytes flag
+				vbrBytes = int64(binary.BigEndian.Uint32(xingBuf[off : off+4]))
+			}
+			if vbrFrames > 0 {
+				isVBR = true
+			}
+		}
+	}
+
+	if !isVBR && 36+26 <= n {
+		if string(xingBuf[32:36]) == "VBRI" {
+			vbrBytes = int64(binary.BigEndian.Uint32(xingBuf[36+6 : 36+10]))
+			vbrFrames = int(binary.BigEndian.Uint32(xingBuf[36+10 : 36+14]))
+			if vbrFrames > 0 {
+				isVBR = true
+			}
+		}
+	}
+
+	if isVBR && vbrFrames > 0 && quality.SampleRate > 0 {
+		totalSamples := int64(vbrFrames) * int64(samplesPerFrame)
+		quality.Duration = int(totalSamples / int64(quality.SampleRate))
+
+		if vbrBytes > 0 && quality.Duration > 0 {
+			quality.Bitrate = int(vbrBytes * 8 / int64(quality.Duration))
+		} else if quality.Duration > 0 {
+			audioSize := fileSize - audioStart
+			quality.Bitrate = int(audioSize * 8 / int64(quality.Duration))
+		}
+	} else if quality.Bitrate > 0 {
+		audioSize := fileSize - audioStart - 128 // subtract possible ID3v1 tag
+		if audioSize > 0 {
+			quality.Duration = int(audioSize * 8 / int64(quality.Bitrate))
+		}
+	}
+
 	return quality, nil
 }
 
@@ -624,14 +898,6 @@ func readOggPageWithHeader(file *os.File) (*oggPage, error) {
 	}, nil
 }
 
-func readOggPage(file *os.File) ([]byte, error) {
-	page, err := readOggPageWithHeader(file)
-	if err != nil {
-		return nil, err
-	}
-	return page.data, nil
-}
-
 func collectOggPackets(file *os.File, maxPackets, maxPages int) ([][]byte, error) {
 	const maxPacketSize = 10 * 1024 * 1024
 	var packets [][]byte
@@ -721,8 +987,9 @@ func parseVorbisComments(data []byte, metadata *AudioMetadata) {
 	}
 
 	reader := bytes.NewReader(data)
+	artistValues := make([]string, 0, 1)
+	albumArtistValues := make([]string, 0, 1)
 
-	// Read vendor string length
 	var vendorLen uint32
 	if err := binary.Read(reader, binary.LittleEndian, &vendorLen); err != nil {
 		return
@@ -747,9 +1014,14 @@ func parseVorbisComments(data []byte, metadata *AudioMetadata) {
 			break
 		}
 
-		if commentLen > 10000 {
+		remaining := uint32(reader.Len())
+		if commentLen > remaining {
 			break
 		}
+		if commentLen > 512*1024 {
+			reader.Seek(int64(commentLen), io.SeekCurrent)
+			continue
+		}
 
 		comment := make([]byte, commentLen)
 		if _, err := reader.Read(comment); err != nil {
@@ -768,9 +1040,9 @@ func parseVorbisComments(data []byte, metadata *AudioMetadata) {
 		case "TITLE":
 			metadata.Title = value
 		case "ARTIST":
-			metadata.Artist = value
+			artistValues = append(artistValues, value)
 		case "ALBUMARTIST", "ALBUM_ARTIST", "ALBUM ARTIST":
-			metadata.AlbumArtist = value
+			albumArtistValues = append(albumArtistValues, value)
 		case "ALBUM":
 			metadata.Album = value
 		case "DATE", "YEAR":
@@ -781,13 +1053,40 @@ func parseVorbisComments(data []byte, metadata *AudioMetadata) {
 		case "GENRE":
 			metadata.Genre = value
 		case "TRACKNUMBER", "TRACK":
-			metadata.TrackNumber = parseTrackNumber(value)
+			metadata.TrackNumber, metadata.TotalTracks = parseIndexPair(value)
 		case "DISCNUMBER", "DISC":
-			metadata.DiscNumber = parseTrackNumber(value)
+			metadata.DiscNumber, metadata.TotalDiscs = parseIndexPair(value)
 		case "ISRC":
 			metadata.ISRC = value
+		case "COMPOSER":
+			metadata.Composer = value
+		case "COMMENT", "DESCRIPTION":
+			metadata.Comment = value
+		case "LYRICS", "UNSYNCEDLYRICS":
+			if metadata.Lyrics == "" {
+				metadata.Lyrics = value
+			}
+		case "ORGANIZATION", "LABEL", "PUBLISHER":
+			metadata.Label = value
+		case "COPYRIGHT":
+			metadata.Copyright = value
+		case "REPLAYGAIN_TRACK_GAIN":
+			metadata.ReplayGainTrackGain = value
+		case "REPLAYGAIN_TRACK_PEAK":
+			metadata.ReplayGainTrackPeak = value
+		case "REPLAYGAIN_ALBUM_GAIN":
+			metadata.ReplayGainAlbumGain = value
+		case "REPLAYGAIN_ALBUM_PEAK":
+			metadata.ReplayGainAlbumPeak = value
 		}
 	}
+
+	if len(artistValues) > 0 {
+		metadata.Artist = joinVorbisCommentValues(artistValues)
+	}
+	if len(albumArtistValues) > 0 {
+		metadata.AlbumArtist = joinVorbisCommentValues(albumArtistValues)
+	}
 }
 
 func GetOggQuality(filePath string) (*OggQuality, error) {
@@ -798,7 +1097,6 @@ func GetOggQuality(filePath string) (*OggQuality, error) {
 	defer file.Close()
 
 	quality := &OggQuality{}
-	isOpus := false
 
 	packets, err := collectOggPackets(file, 5, 10)
 	if err != nil && len(packets) == 0 {
@@ -814,15 +1112,17 @@ func GetOggQuality(filePath string) (*OggQuality, error) {
 		}
 	}
 
-	if streamType == oggStreamOpus {
-		isOpus = true
+	isOpus := streamType == oggStreamOpus
+	var preSkip int
+
+	if isOpus {
 		for _, pkt := range packets {
 			if len(pkt) >= 19 && string(pkt[0:8]) == "OpusHead" {
 				quality.SampleRate = int(binary.LittleEndian.Uint32(pkt[12:16]))
 				if quality.SampleRate == 0 {
 					quality.SampleRate = 48000
 				}
-				quality.BitDepth = 16
+				preSkip = int(binary.LittleEndian.Uint16(pkt[10:12]))
 				break
 			}
 		}
@@ -830,29 +1130,96 @@ func GetOggQuality(filePath string) (*OggQuality, error) {
 		for _, pkt := range packets {
 			if len(pkt) > 29 && pkt[0] == 0x01 && string(pkt[1:7]) == "vorbis" {
 				quality.SampleRate = int(binary.LittleEndian.Uint32(pkt[12:16]))
-				quality.BitDepth = 16
 				break
 			}
 		}
 	}
 
 	stat, err := file.Stat()
-	if err == nil {
-		// Very rough duration estimate based on file size
-		// Assume ~128kbps average for Opus, ~160kbps for Vorbis
-		avgBitrate := 128000
-		if !isOpus {
-			avgBitrate = 160000
+	if err != nil {
+		return quality, nil
+	}
+	fileSize := stat.Size()
+
+	granule := readLastOggGranulePosition(file, fileSize)
+	if granule > 0 {
+		if isOpus {
+			totalSamples := granule - int64(preSkip)
+			if totalSamples > 0 {
+				durationSec := float64(totalSamples) / 48000.0
+				if durationSec > 0 {
+					quality.Duration = int(math.Round(durationSec))
+					quality.Bitrate = int(float64(fileSize*8) / durationSec)
+				}
+			}
+		} else if quality.SampleRate > 0 {
+			durationSec := float64(granule) / float64(quality.SampleRate)
+			if durationSec > 0 {
+				quality.Duration = int(math.Round(durationSec))
+				quality.Bitrate = int(float64(fileSize*8) / durationSec)
+			}
 		}
-		quality.Duration = int(stat.Size() * 8 / int64(avgBitrate))
+	}
+
+	if quality.Bitrate <= 0 && quality.Duration > 0 {
+		quality.Bitrate = int(fileSize * 8 / int64(quality.Duration))
+	}
+	if quality.Duration > 24*60*60 {
+		quality.Duration = 0
+		quality.Bitrate = 0
+	}
+	if quality.Bitrate > 0 && quality.Bitrate < 8000 {
+		quality.Bitrate = 0
 	}
 
 	return quality, nil
 }
 
-// =============================================================================
-// ID3v1 Genre List
-// =============================================================================
+func readLastOggGranulePosition(file *os.File, fileSize int64) int64 {
+	searchSize := int64(65536)
+	if searchSize > fileSize {
+		searchSize = fileSize
+	}
+
+	buf := make([]byte, searchSize)
+	offset := fileSize - searchSize
+	if offset < 0 {
+		offset = 0
+	}
+	n, err := file.ReadAt(buf, offset)
+	if err != nil && n == 0 {
+		return 0
+	}
+	buf = buf[:n]
+
+	for i := n - 4; i >= 0; i-- {
+		if buf[i] != 'O' || buf[i+1] != 'g' || buf[i+2] != 'g' || buf[i+3] != 'S' {
+			continue
+		}
+		if i+27 > n {
+			continue
+		}
+		version := buf[i+4]
+		headerType := buf[i+5]
+		if version != 0 || headerType > 0x07 {
+			continue
+		}
+		segmentCount := int(buf[i+26])
+		headerLen := 27 + segmentCount
+		if i+headerLen > n {
+			continue
+		}
+		payloadLen := 0
+		for s := 0; s < segmentCount; s++ {
+			payloadLen += int(buf[i+27+s])
+		}
+		if i+headerLen+payloadLen > n {
+			continue
+		}
+		return int64(binary.LittleEndian.Uint64(buf[i+6 : i+14]))
+	}
+	return 0
+}
 
 var id3v1Genres = []string{
 	"Blues", "Classic Rock", "Country", "Dance", "Disco", "Funk", "Grunge",
@@ -884,10 +1251,6 @@ var id3v1Genres = []string{
 	"Thrash Metal", "Anime", "J-Pop", "Synthpop",
 }
 
-// =============================================================================
-// Cover Art Extraction
-// =============================================================================
-
 func extractMP3CoverArt(filePath string) ([]byte, string, error) {
 	file, err := os.Open(filePath)
 	if err != nil {
@@ -912,7 +1275,6 @@ func extractMP3CoverArt(filePath string) ([]byte, string, error) {
 		return nil, "", err
 	}
 
-	// Parse frames looking for APIC (Attached Picture)
 	pos := 0
 	var frameIDLen, headerLen int
 	if majorVersion == 2 {
@@ -930,11 +1292,12 @@ func extractMP3CoverArt(filePath string) ([]byte, string, error) {
 		}
 
 		var frameSize int
-		if majorVersion == 2 {
+		switch majorVersion {
+		case 2:
 			frameSize = int(tagData[pos+3])<<16 | int(tagData[pos+4])<<8 | int(tagData[pos+5])
-		} else if majorVersion == 4 {
+		case 4:
 			frameSize = int(tagData[pos+4])<<21 | int(tagData[pos+5])<<14 | int(tagData[pos+6])<<7 | int(tagData[pos+7])
-		} else {
+		default:
 			frameSize = int(tagData[pos+4])<<24 | int(tagData[pos+5])<<16 | int(tagData[pos+6])<<8 | int(tagData[pos+7])
 		}
 
@@ -942,7 +1305,6 @@ func extractMP3CoverArt(filePath string) ([]byte, string, error) {
 			break
 		}
 
-		// Check for APIC (ID3v2.3/2.4) or PIC (ID3v2.2)
 		if (frameIDLen == 4 && frameID == "APIC") || (frameIDLen == 3 && frameID == "PIC") {
 			frameData := tagData[pos+headerLen : pos+headerLen+frameSize]
 			imageData, mimeType := parseAPICFrame(frameData, majorVersion)
@@ -1220,7 +1582,14 @@ func base64StdDecode(dst, src []byte) (int, error) {
 }
 
 func extractAnyCoverArt(filePath string) ([]byte, string, error) {
+	return extractAnyCoverArtWithHint(filePath, "")
+}
+
+func extractAnyCoverArtWithHint(filePath, displayNameHint string) ([]byte, string, error) {
 	ext := strings.ToLower(filepath.Ext(filePath))
+	if ext == "" {
+		ext = strings.ToLower(filepath.Ext(displayNameHint))
+	}
 
 	switch ext {
 	case ".flac":
@@ -1241,7 +1610,19 @@ func extractAnyCoverArt(filePath string) ([]byte, string, error) {
 		return extractOggCoverArt(filePath)
 
 	case ".m4a":
-		return nil, "", fmt.Errorf("M4A cover extraction not yet supported")
+		data, err := extractCoverFromM4A(filePath)
+		if err != nil {
+			return nil, "", err
+		}
+		mimeType := "image/jpeg"
+		if len(data) >= 8 &&
+			data[0] == 0x89 &&
+			data[1] == 0x50 &&
+			data[2] == 0x4E &&
+			data[3] == 0x47 {
+			mimeType = "image/png"
+		}
+		return data, mimeType, nil
 
 	default:
 		return nil, "", fmt.Errorf("unsupported format: %s", ext)
@@ -1249,10 +1630,28 @@ func extractAnyCoverArt(filePath string) ([]byte, string, error) {
 }
 
 func SaveCoverToCache(filePath, cacheDir string) (string, error) {
+	return SaveCoverToCacheWithHintAndKey(filePath, "", cacheDir, "")
+}
+
+func SaveCoverToCacheWithHint(filePath, displayNameHint, cacheDir string) (string, error) {
+	return SaveCoverToCacheWithHintAndKey(filePath, displayNameHint, cacheDir, "")
+}
+
+func resolveLibraryCoverCacheKey(filePath, explicitKey string) string {
+	explicitKey = strings.TrimSpace(explicitKey)
+	if explicitKey != "" {
+		return explicitKey
+	}
+
 	cacheKey := filePath
 	if stat, err := os.Stat(filePath); err == nil {
 		cacheKey = fmt.Sprintf("%s|%d|%d", filePath, stat.Size(), stat.ModTime().UnixNano())
 	}
+	return cacheKey
+}
+
+func SaveCoverToCacheWithHintAndKey(filePath, displayNameHint, cacheDir, coverCacheKey string) (string, error) {
+	cacheKey := resolveLibraryCoverCacheKey(filePath, coverCacheKey)
 	hash := hashString(cacheKey)
 
 	jpgPath := filepath.Join(cacheDir, fmt.Sprintf("cover_%x.jpg", hash))
@@ -1265,7 +1664,7 @@ func SaveCoverToCache(filePath, cacheDir string) (string, error) {
 		return pngPath, nil
 	}
 
-	imageData, mimeType, err := extractAnyCoverArt(filePath)
+	imageData, mimeType, err := extractAnyCoverArtWithHint(filePath, displayNameHint)
 	if err != nil {
 		return "", err
 	}

go_backend/audio_metadata_cache_test.go

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

go_backend/audio_metadata_mp3_test.go

@@ -0,0 +1,133 @@
+package gobackend
+
+import (
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func ffmpegCommand(args ...string) *exec.Cmd {
+	if ffmpegPath, err := exec.LookPath("ffmpeg"); err == nil {
+		return exec.Command(ffmpegPath, args...)
+	}
+	return exec.Command("ffmpeg", args...)
+}
+
+func runFFmpegTestCommand(t *testing.T, args ...string) {
+	t.Helper()
+	cmd := ffmpegCommand(args...)
+	output, err := cmd.CombinedOutput()
+	if err != nil {
+		t.Fatalf("ffmpeg failed: %v\n%s", err, string(output))
+	}
+}
+
+func TestExtractLyricsReadsMp3AfterCoverEmbed(t *testing.T) {
+	if _, err := exec.LookPath("ffmpeg"); err != nil {
+		t.Skip("ffmpeg not available")
+	}
+
+	tempDir := t.TempDir()
+	sourceFlac := filepath.Join(tempDir, "source.flac")
+	baseMp3 := filepath.Join(tempDir, "base.mp3")
+	finalMp3 := filepath.Join(tempDir, "final.mp3")
+	coverPath := filepath.Join(tempDir, "cover.jpg")
+	lyrics := "[ti:Test Song]\n[ar:Test Artist]\n[00:00.00]Hello from embedded lyrics"
+
+	runFFmpegTestCommand(
+		t,
+		"-y",
+		"-f",
+		"lavfi",
+		"-i",
+		"sine=frequency=440:duration=1",
+		"-c:a",
+		"flac",
+		sourceFlac,
+	)
+
+	runFFmpegTestCommand(
+		t,
+		"-y",
+		"-f",
+		"lavfi",
+		"-i",
+		"color=c=red:s=32x32:d=1",
+		"-frames:v",
+		"1",
+		coverPath,
+	)
+
+	runFFmpegTestCommand(
+		t,
+		"-y",
+		"-i",
+		sourceFlac,
+		"-b:a",
+		"320k",
+		"-metadata",
+		"title=Test Song",
+		"-metadata",
+		"artist=Test Artist",
+		"-metadata",
+		"lyrics="+lyrics,
+		baseMp3,
+	)
+
+	runFFmpegTestCommand(
+		t,
+		"-y",
+		"-i",
+		baseMp3,
+		"-i",
+		coverPath,
+		"-map",
+		"0:a",
+		"-map_metadata",
+		"-1",
+		"-map",
+		"1:0",
+		"-c:v:0",
+		"copy",
+		"-id3v2_version",
+		"3",
+		"-metadata",
+		"title=Test Song",
+		"-metadata",
+		"artist=Test Artist",
+		"-metadata",
+		"lyrics="+lyrics,
+		"-metadata:s:v",
+		"title=Album cover",
+		"-metadata:s:v",
+		"comment=Cover (front)",
+		"-c:a",
+		"copy",
+		finalMp3,
+	)
+
+	meta, err := ReadID3Tags(finalMp3)
+	if err != nil {
+		t.Fatalf("ReadID3Tags failed: %v", err)
+	}
+	if meta == nil {
+		t.Fatalf("ReadID3Tags returned nil metadata")
+	}
+
+	embeddedLyrics, err := ExtractLyrics(finalMp3)
+	if err != nil {
+		t.Fatalf("ExtractLyrics failed: %v (metadata=%+v)", err, meta)
+	}
+	if !strings.Contains(embeddedLyrics, "Hello from embedded lyrics") {
+		t.Fatalf("embedded lyrics missing, got %q (metadata=%+v)", embeddedLyrics, meta)
+	}
+	if !strings.Contains(meta.Lyrics, "Hello from embedded lyrics") {
+		t.Fatalf("ReadID3Tags lyrics missing, got %+v", meta)
+	}
+
+	if _, err := os.Stat(finalMp3); err != nil {
+		t.Fatalf("expected final mp3 to exist: %v", err)
+	}
+}

go_backend/cancel.go

@@ -10,6 +10,7 @@ import (
 var ErrDownloadCancelled = errors.New("download cancelled")
 
 type cancelEntry struct {
+	ctx      context.Context
 	cancel   context.CancelFunc
 	canceled bool
 }
@@ -27,8 +28,21 @@ func initDownloadCancel(itemID string) context.Context {
 	cancelMu.Lock()
 	defer cancelMu.Unlock()
 
+	if entry, ok := cancelMap[itemID]; ok {
+		if entry.ctx == nil {
+			ctx, cancel := context.WithCancel(context.Background())
+			entry.ctx = ctx
+			entry.cancel = cancel
+			if entry.canceled && entry.cancel != nil {
+				entry.cancel()
+			}
+		}
+		return entry.ctx
+	}
+
 	ctx, cancel := context.WithCancel(context.Background())
 	cancelMap[itemID] = &cancelEntry{
+		ctx:      ctx,
 		cancel:   cancel,
 		canceled: false,
 	}

go_backend/cover.go

@@ -17,6 +17,8 @@ const (
 // Deezer CDN supports these sizes: 56, 250, 500, 1000, 1400, 1800
 var deezerSizeRegex = regexp.MustCompile(`/(\d+)x(\d+)-\d+-\d+-\d+-\d+\.jpg$`)
 
+var tidalSizeRegex = regexp.MustCompile(`/\d+x\d+\.jpg$`)
+
 func convertSmallToMedium(imageURL string) string {
 	if strings.Contains(imageURL, spotifySize300) {
 		return strings.Replace(imageURL, spotifySize300, spotifySize640, 1)
@@ -40,7 +42,6 @@ func downloadCoverToMemory(coverURL string, maxQuality bool) ([]byte, error) {
 		maxURL := upgradeToMaxQuality(downloadURL)
 		if maxURL != downloadURL {
 			downloadURL = maxURL
-			// Log already printed by upgradeToMaxQuality for Deezer
 			if strings.Contains(coverURL, "scdn.co") || strings.Contains(coverURL, "spotifycdn") {
 				GoLog("[Cover] Spotify: upgraded to max resolution (~2000x2000)")
 			}
@@ -86,16 +87,22 @@ func downloadCoverToMemory(coverURL string, maxQuality bool) ([]byte, error) {
 }
 
 func upgradeToMaxQuality(coverURL string) string {
-	// Spotify CDN upgrade
 	if strings.Contains(coverURL, spotifySize640) {
 		return strings.Replace(coverURL, spotifySize640, spotifySizeMax, 1)
 	}
 
-	// Deezer CDN upgrade
 	if strings.Contains(coverURL, "cdn-images.dzcdn.net") {
 		return upgradeDeezerCover(coverURL)
 	}
 
+	if strings.Contains(coverURL, "resources.tidal.com") {
+		return upgradeTidalCover(coverURL)
+	}
+
+	if strings.Contains(coverURL, "static.qobuz.com") {
+		return upgradeQobuzCover(coverURL)
+	}
+
 	return coverURL
 }
 
@@ -104,7 +111,6 @@ func upgradeDeezerCover(coverURL string) string {
 		return coverURL
 	}
 
-	// Replace any size pattern with 1800x1800
 	upgraded := deezerSizeRegex.ReplaceAllString(coverURL, "/1800x1800-000000-80-0-0.jpg")
 	if upgraded != coverURL {
 		GoLog("[Cover] Deezer: upgraded to 1800x1800")
@@ -112,12 +118,35 @@ func upgradeDeezerCover(coverURL string) string {
 	return upgraded
 }
 
+func upgradeTidalCover(coverURL string) string {
+	if !strings.Contains(coverURL, "resources.tidal.com") {
+		return coverURL
+	}
+
+	upgraded := tidalSizeRegex.ReplaceAllString(coverURL, "/origin.jpg")
+	if upgraded != coverURL {
+		GoLog("[Cover] Tidal: upgraded to origin resolution")
+	}
+	return upgraded
+}
+
+func upgradeQobuzCover(coverURL string) string {
+	if !strings.Contains(coverURL, "static.qobuz.com") {
+		return coverURL
+	}
+
+	upgraded := qobuzImageSizeRe.ReplaceAllString(coverURL, "_max.jpg")
+	if upgraded != coverURL {
+		GoLog("[Cover] Qobuz: upgraded to max resolution")
+	}
+	return upgraded
+}
+
 func GetCoverFromSpotify(imageURL string, maxQuality bool) string {
 	if imageURL == "" {
 		return ""
 	}
 
-	// Always upgrade small to medium first
 	result := convertSmallToMedium(imageURL)
 
 	if maxQuality {

go_backend/cue_parser.go

@@ -0,0 +1,565 @@
+package gobackend
+
+import (
+	"bufio"
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strconv"
+	"strings"
+)
+
+type CueSheet struct {
+	Performer string     `json:"performer"`
+	Title     string     `json:"title"`
+	FileName  string     `json:"file_name"`
+	FileType  string     `json:"file_type"` // WAVE, FLAC, MP3, AIFF, etc.
+	Genre     string     `json:"genre,omitempty"`
+	Date      string     `json:"date,omitempty"`
+	Comment   string     `json:"comment,omitempty"`
+	Composer  string     `json:"composer,omitempty"`
+	Tracks    []CueTrack `json:"tracks"`
+}
+
+type CueTrack struct {
+	Number    int     `json:"number"`
+	Title     string  `json:"title"`
+	Performer string  `json:"performer"`
+	ISRC      string  `json:"isrc,omitempty"`
+	Composer  string  `json:"composer,omitempty"`
+	StartTime float64 `json:"start_time"` // INDEX 01 in seconds
+	PreGap    float64 `json:"pre_gap"`    // INDEX 00 in seconds (or -1 if not present)
+}
+
+type CueSplitInfo struct {
+	CuePath   string          `json:"cue_path"`
+	AudioPath string          `json:"audio_path"`
+	Album     string          `json:"album"`
+	Artist    string          `json:"artist"`
+	Genre     string          `json:"genre,omitempty"`
+	Date      string          `json:"date,omitempty"`
+	Tracks    []CueSplitTrack `json:"tracks"`
+}
+
+type CueSplitTrack struct {
+	Number   int     `json:"number"`
+	Title    string  `json:"title"`
+	Artist   string  `json:"artist"`
+	ISRC     string  `json:"isrc,omitempty"`
+	Composer string  `json:"composer,omitempty"`
+	StartSec float64 `json:"start_sec"`
+	EndSec   float64 `json:"end_sec"` // -1 means until end of file
+}
+
+var (
+	reRemCommand = regexp.MustCompile(`^REM\s+(\S+)\s+(.+)$`)
+	reQuoted     = regexp.MustCompile(`"([^"]*)"`)
+)
+
+func ParseCueFile(cuePath string) (*CueSheet, error) {
+	f, err := os.Open(cuePath)
+	if err != nil {
+		return nil, fmt.Errorf("failed to open cue file: %w", err)
+	}
+	defer f.Close()
+
+	sheet := &CueSheet{}
+	var currentTrack *CueTrack
+
+	scanner := bufio.NewScanner(f)
+	for scanner.Scan() {
+		line := strings.TrimSpace(scanner.Text())
+		if line == "" {
+			continue
+		}
+
+		if strings.HasPrefix(line, "\xef\xbb\xbf") {
+			line = strings.TrimPrefix(line, "\xef\xbb\xbf")
+			line = strings.TrimSpace(line)
+		}
+
+		upper := strings.ToUpper(line)
+
+		if strings.HasPrefix(upper, "REM ") {
+			matches := reRemCommand.FindStringSubmatch(line)
+			if len(matches) == 3 {
+				key := strings.ToUpper(matches[1])
+				value := unquoteCue(matches[2])
+				switch key {
+				case "GENRE":
+					sheet.Genre = value
+				case "DATE":
+					sheet.Date = value
+				case "COMMENT":
+					sheet.Comment = value
+				case "COMPOSER":
+					if currentTrack != nil {
+						currentTrack.Composer = value
+					} else {
+						sheet.Composer = value
+					}
+				}
+			}
+			continue
+		}
+
+		if strings.HasPrefix(upper, "PERFORMER ") {
+			value := unquoteCue(line[len("PERFORMER "):])
+			if currentTrack != nil {
+				currentTrack.Performer = value
+			} else {
+				sheet.Performer = value
+			}
+			continue
+		}
+
+		if strings.HasPrefix(upper, "TITLE ") {
+			value := unquoteCue(line[len("TITLE "):])
+			if currentTrack != nil {
+				currentTrack.Title = value
+			} else {
+				sheet.Title = value
+			}
+			continue
+		}
+
+		if strings.HasPrefix(upper, "FILE ") {
+			rest := line[len("FILE "):]
+			fname, ftype := parseCueFileLine(rest)
+			sheet.FileName = fname
+			sheet.FileType = ftype
+			continue
+		}
+
+		if strings.HasPrefix(upper, "TRACK ") {
+			if currentTrack != nil {
+				sheet.Tracks = append(sheet.Tracks, *currentTrack)
+			}
+
+			parts := strings.Fields(line)
+			trackNum := 0
+			if len(parts) >= 2 {
+				trackNum, _ = strconv.Atoi(parts[1])
+			}
+
+			currentTrack = &CueTrack{
+				Number: trackNum,
+				PreGap: -1,
+			}
+			continue
+		}
+
+		if strings.HasPrefix(upper, "INDEX ") && currentTrack != nil {
+			parts := strings.Fields(line)
+			if len(parts) >= 3 {
+				indexNum, _ := strconv.Atoi(parts[1])
+				timeSec := parseCueTimestamp(parts[2])
+				switch indexNum {
+				case 0:
+					currentTrack.PreGap = timeSec
+				case 1:
+					currentTrack.StartTime = timeSec
+				}
+			}
+			continue
+		}
+
+		if strings.HasPrefix(upper, "ISRC ") && currentTrack != nil {
+			currentTrack.ISRC = strings.TrimSpace(line[len("ISRC "):])
+			continue
+		}
+
+		if strings.HasPrefix(upper, "SONGWRITER ") {
+			value := unquoteCue(line[len("SONGWRITER "):])
+			if currentTrack != nil {
+				currentTrack.Composer = value
+			} else {
+				sheet.Composer = value
+			}
+			continue
+		}
+	}
+
+	if currentTrack != nil {
+		sheet.Tracks = append(sheet.Tracks, *currentTrack)
+	}
+
+	if err := scanner.Err(); err != nil {
+		return nil, fmt.Errorf("error reading cue file: %w", err)
+	}
+
+	if len(sheet.Tracks) == 0 {
+		return nil, fmt.Errorf("no tracks found in cue file")
+	}
+
+	return sheet, nil
+}
+
+func parseCueTimestamp(ts string) float64 {
+	parts := strings.Split(ts, ":")
+	if len(parts) != 3 {
+		return 0
+	}
+
+	minutes, _ := strconv.Atoi(parts[0])
+	seconds, _ := strconv.Atoi(parts[1])
+	frames, _ := strconv.Atoi(parts[2])
+
+	return float64(minutes)*60 + float64(seconds) + float64(frames)/75.0
+}
+
+func formatCueTimestamp(seconds float64) string {
+	if seconds < 0 {
+		return "0"
+	}
+	hours := int(seconds) / 3600
+	mins := (int(seconds) % 3600) / 60
+	secs := seconds - float64(hours*3600) - float64(mins*60)
+	return fmt.Sprintf("%02d:%02d:%06.3f", hours, mins, secs)
+}
+
+func unquoteCue(s string) string {
+	s = strings.TrimSpace(s)
+	if matches := reQuoted.FindStringSubmatch(s); len(matches) == 2 {
+		return matches[1]
+	}
+	return s
+}
+
+func parseCueFileLine(rest string) (string, string) {
+	rest = strings.TrimSpace(rest)
+
+	var filename, ftype string
+
+	if strings.HasPrefix(rest, "\"") {
+		endQuote := strings.Index(rest[1:], "\"")
+		if endQuote >= 0 {
+			filename = rest[1 : endQuote+1]
+			remaining := strings.TrimSpace(rest[endQuote+2:])
+			ftype = remaining
+		} else {
+			filename = rest
+		}
+	} else {
+		parts := strings.Fields(rest)
+		if len(parts) >= 2 {
+			ftype = parts[len(parts)-1]
+			filename = strings.Join(parts[:len(parts)-1], " ")
+		} else if len(parts) == 1 {
+			filename = parts[0]
+		}
+	}
+
+	return filename, strings.TrimSpace(ftype)
+}
+
+func ResolveCueAudioPath(cuePath string, cueFileName string) string {
+	cueDir := filepath.Dir(cuePath)
+
+	candidate := filepath.Join(cueDir, cueFileName)
+	if _, err := os.Stat(candidate); err == nil {
+		return candidate
+	}
+
+	baseName := strings.TrimSuffix(cueFileName, filepath.Ext(cueFileName))
+	commonExts := []string{".flac", ".wav", ".ape", ".mp3", ".ogg", ".wv", ".m4a"}
+	for _, ext := range commonExts {
+		candidate = filepath.Join(cueDir, baseName+ext)
+		if _, err := os.Stat(candidate); err == nil {
+			return candidate
+		}
+		candidate = filepath.Join(cueDir, baseName+strings.ToUpper(ext))
+		if _, err := os.Stat(candidate); err == nil {
+			return candidate
+		}
+	}
+
+	cueBase := strings.TrimSuffix(filepath.Base(cuePath), filepath.Ext(cuePath))
+	for _, ext := range commonExts {
+		candidate = filepath.Join(cueDir, cueBase+ext)
+		if _, err := os.Stat(candidate); err == nil {
+			return candidate
+		}
+	}
+
+	entries, err := os.ReadDir(cueDir)
+	if err == nil {
+		audioExts := map[string]bool{
+			".flac": true, ".wav": true, ".ape": true, ".mp3": true,
+			".ogg": true, ".wv": true, ".m4a": true, ".aiff": true,
+		}
+		var audioFiles []string
+		for _, entry := range entries {
+			if entry.IsDir() {
+				continue
+			}
+			ext := strings.ToLower(filepath.Ext(entry.Name()))
+			if audioExts[ext] {
+				audioFiles = append(audioFiles, filepath.Join(cueDir, entry.Name()))
+			}
+		}
+		if len(audioFiles) == 1 {
+			return audioFiles[0]
+		}
+	}
+
+	return ""
+}
+
+func BuildCueSplitInfo(cuePath string, sheet *CueSheet, audioDir string) (*CueSplitInfo, error) {
+	resolveDir := cuePath
+	if audioDir != "" {
+		resolveDir = filepath.Join(audioDir, filepath.Base(cuePath))
+	}
+	audioPath := ResolveCueAudioPath(resolveDir, sheet.FileName)
+	if audioPath == "" {
+		return nil, fmt.Errorf("audio file not found for cue sheet: %s (referenced: %s)", cuePath, sheet.FileName)
+	}
+
+	info := &CueSplitInfo{
+		CuePath:   cuePath,
+		AudioPath: audioPath,
+		Album:     sheet.Title,
+		Artist:    sheet.Performer,
+		Genre:     sheet.Genre,
+		Date:      sheet.Date,
+	}
+
+	for i, track := range sheet.Tracks {
+		performer := track.Performer
+		if performer == "" {
+			performer = sheet.Performer
+		}
+
+		composer := track.Composer
+		if composer == "" {
+			composer = sheet.Composer
+		}
+
+		endSec := float64(-1)
+		if i+1 < len(sheet.Tracks) {
+			nextTrack := sheet.Tracks[i+1]
+			if nextTrack.PreGap >= 0 {
+				endSec = nextTrack.PreGap
+			} else {
+				endSec = nextTrack.StartTime
+			}
+		}
+
+		info.Tracks = append(info.Tracks, CueSplitTrack{
+			Number:   track.Number,
+			Title:    track.Title,
+			Artist:   performer,
+			ISRC:     track.ISRC,
+			Composer: composer,
+			StartSec: track.StartTime,
+			EndSec:   endSec,
+		})
+	}
+
+	return info, nil
+}
+
+func ParseCueFileJSON(cuePath string, audioDir string) (string, error) {
+	sheet, err := ParseCueFile(cuePath)
+	if err != nil {
+		return "", fmt.Errorf("failed to parse cue file: %w", err)
+	}
+
+	info, err := BuildCueSplitInfo(cuePath, sheet, audioDir)
+	if err != nil {
+		return "", err
+	}
+
+	jsonBytes, err := json.Marshal(info)
+	if err != nil {
+		return "", fmt.Errorf("failed to marshal cue split info: %w", err)
+	}
+
+	return string(jsonBytes), nil
+}
+
+func ScanCueFileForLibrary(cuePath string, scanTime string) ([]LibraryScanResult, error) {
+	sheet, err := ParseCueFile(cuePath)
+	if err != nil {
+		return nil, err
+	}
+	audioPath, err := resolveCueAudioPathForLibrary(cuePath, sheet, "")
+	if err != nil {
+		return nil, err
+	}
+	return scanCueSheetForLibrary(cuePath, sheet, audioPath, "", 0, "", scanTime)
+}
+
+func ScanCueFileForLibraryExt(cuePath, audioDir, virtualPathPrefix string, fileModTime int64, scanTime string) ([]LibraryScanResult, error) {
+	return ScanCueFileForLibraryExtWithCoverCacheKey(
+		cuePath,
+		audioDir,
+		virtualPathPrefix,
+		fileModTime,
+		"",
+		scanTime,
+	)
+}
+
+func ScanCueFileForLibraryExtWithCoverCacheKey(cuePath, audioDir, virtualPathPrefix string, fileModTime int64, coverCacheKey, scanTime string) ([]LibraryScanResult, error) {
+	sheet, err := ParseCueFile(cuePath)
+	if err != nil {
+		return nil, err
+	}
+	audioPath, err := resolveCueAudioPathForLibrary(cuePath, sheet, audioDir)
+	if err != nil {
+		return nil, err
+	}
+	return scanCueSheetForLibrary(
+		cuePath,
+		sheet,
+		audioPath,
+		virtualPathPrefix,
+		fileModTime,
+		coverCacheKey,
+		scanTime,
+	)
+}
+
+func resolveCueAudioPathForLibrary(cuePath string, sheet *CueSheet, audioDir string) (string, error) {
+	if sheet == nil {
+		return "", fmt.Errorf("cue sheet is nil for %s", cuePath)
+	}
+	resolveBase := cuePath
+	if audioDir != "" {
+		resolveBase = filepath.Join(audioDir, filepath.Base(cuePath))
+	}
+	audioPath := ResolveCueAudioPath(resolveBase, sheet.FileName)
+	if audioPath == "" {
+		return "", fmt.Errorf("audio file not found for cue: %s (referenced: %s)", cuePath, sheet.FileName)
+	}
+	return audioPath, nil
+}
+
+func scanCueSheetForLibrary(cuePath string, sheet *CueSheet, audioPath, virtualPathPrefix string, fileModTime int64, coverCacheKey, scanTime string) ([]LibraryScanResult, error) {
+	if sheet == nil {
+		return nil, fmt.Errorf("cue sheet is nil for %s", cuePath)
+	}
+
+	var bitDepth, sampleRate int
+	var totalDurationSec float64
+	audioExt := strings.ToLower(filepath.Ext(audioPath))
+	switch audioExt {
+	case ".flac":
+		quality, qErr := GetAudioQuality(audioPath)
+		if qErr == nil {
+			bitDepth = quality.BitDepth
+			sampleRate = quality.SampleRate
+			if quality.SampleRate > 0 && quality.TotalSamples > 0 {
+				totalDurationSec = float64(quality.TotalSamples) / float64(quality.SampleRate)
+			}
+		}
+	case ".mp3":
+		quality, qErr := GetMP3Quality(audioPath)
+		if qErr == nil {
+			sampleRate = quality.SampleRate
+			totalDurationSec = float64(quality.Duration)
+		}
+	}
+
+	var coverPath string
+	libraryCoverCacheMu.RLock()
+	coverCacheDir := libraryCoverCacheDir
+	libraryCoverCacheMu.RUnlock()
+	if coverCacheDir != "" {
+		cp, err := SaveCoverToCacheWithHintAndKey(
+			audioPath,
+			"",
+			coverCacheDir,
+			coverCacheKey,
+		)
+		if err == nil && cp != "" {
+			coverPath = cp
+		}
+	}
+
+	pathBase := cuePath
+	if virtualPathPrefix != "" {
+		pathBase = virtualPathPrefix
+	}
+
+	modTime := fileModTime
+	if modTime <= 0 {
+		if info, err := os.Stat(cuePath); err == nil {
+			modTime = info.ModTime().UnixMilli()
+		}
+	}
+
+	var results []LibraryScanResult
+	for i, track := range sheet.Tracks {
+		performer := track.Performer
+		if performer == "" {
+			performer = sheet.Performer
+		}
+		if performer == "" {
+			performer = "Unknown Artist"
+		}
+
+		title := track.Title
+		if title == "" {
+			title = fmt.Sprintf("Track %02d", track.Number)
+		}
+
+		album := sheet.Title
+		if album == "" {
+			album = "Unknown Album"
+		}
+
+		composer := track.Composer
+		if composer == "" {
+			composer = sheet.Composer
+		}
+
+		var duration int
+		if i+1 < len(sheet.Tracks) {
+			nextStart := sheet.Tracks[i+1].StartTime
+			if sheet.Tracks[i+1].PreGap >= 0 {
+				nextStart = sheet.Tracks[i+1].PreGap
+			}
+			duration = int(nextStart - track.StartTime)
+		} else if totalDurationSec > 0 {
+			duration = int(totalDurationSec - track.StartTime)
+		}
+
+		id := generateLibraryID(fmt.Sprintf("%s#track%d", pathBase, track.Number))
+
+		virtualFilePath := fmt.Sprintf("%s#track%02d", pathBase, track.Number)
+
+		result := LibraryScanResult{
+			ID:          id,
+			TrackName:   title,
+			ArtistName:  performer,
+			AlbumName:   album,
+			AlbumArtist: sheet.Performer,
+			FilePath:    virtualFilePath,
+			CoverPath:   coverPath,
+			ScannedAt:   scanTime,
+			ISRC:        track.ISRC,
+			TrackNumber: track.Number,
+			TotalTracks: len(sheet.Tracks),
+			DiscNumber:  1,
+			TotalDiscs:  1,
+			Duration:    duration,
+			ReleaseDate: sheet.Date,
+			BitDepth:    bitDepth,
+			SampleRate:  sampleRate,
+			Genre:       sheet.Genre,
+			Composer:    composer,
+			Format:      "cue+" + strings.TrimPrefix(audioExt, "."),
+		}
+
+		result.FileModTime = modTime
+
+		results = append(results, result)
+	}
+
+	return results, nil
+}

go_backend/deezer.go

@@ -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,16 +56,111 @@ 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"`
@@ -87,15 +196,22 @@ type deezerAlbumSimple struct {
 	RecordType  string `json:"record_type"`
 }
 
-func (c *DeezerClient) convertTrack(track deezerTrack) TrackMetadata {
-	artistName := track.Artist.Name
+// deezerTrackArtistDisplay returns the display artist string for a track,
+// preferring the Contributors list (comma-joined) when available, falling
+// back to the primary Artist.Name.
+func deezerTrackArtistDisplay(track deezerTrack) string {
 	if len(track.Contributors) > 0 {
 		names := make([]string, len(track.Contributors))
 		for i, a := range track.Contributors {
 			names[i] = a.Name
 		}
-		artistName = strings.Join(names, ", ")
+		return strings.Join(names, ", ")
 	}
+	return track.Artist.Name
+}
+
+func (c *DeezerClient) convertTrack(track deezerTrack) TrackMetadata {
+	artistName := deezerTrackArtistDisplay(track)
 
 	albumImage := track.Album.CoverXL
 	if albumImage == "" {
@@ -126,6 +242,8 @@ func (c *DeezerClient) convertTrack(track deezerTrack) TrackMetadata {
 		DiscNumber:  track.DiskNumber,
 		ExternalURL: track.Link,
 		ISRC:        track.ISRC,
+		AlbumID:     fmt.Sprintf("deezer:%d", track.Album.ID),
+		ArtistID:    fmt.Sprintf("deezer:%d", track.Artist.ID),
 	}
 }
 
@@ -145,6 +263,7 @@ type deezerAlbumFull struct {
 	NbTracks    int    `json:"nb_tracks"`
 	RecordType  string `json:"record_type"`
 	Label       string `json:"label"`
+	Copyright   string `json:"copyright"`
 	Genres      struct {
 		Data []deezerGenre `json:"data"`
 	} `json:"genres"`
@@ -409,10 +528,12 @@ func (c *DeezerClient) SearchAll(ctx context.Context, query string, trackLimit,
 	GoLog("[Deezer] SearchAll complete: %d tracks, %d artists, %d albums, %d playlists\n", len(result.Tracks), len(result.Artists), len(result.Albums), len(result.Playlists))
 
 	c.cacheMu.Lock()
+	now := time.Now()
 	c.searchCache[cacheKey] = &cacheEntry{
 		data:      result,
-		expiresAt: time.Now().Add(deezerCacheTTL),
+		expiresAt: now.Add(deezerCacheTTL),
 	}
+	c.maybeCleanupCachesLocked(now)
 	c.cacheMu.Unlock()
 
 	return result, nil
@@ -509,6 +630,12 @@ func (c *DeezerClient) GetAlbum(ctx context.Context, albumID string) (*AlbumResp
 	}
 
 	isrcMap := c.fetchISRCsParallel(ctx, allTracks)
+	totalDiscs := 0
+	for _, track := range allTracks {
+		if track.DiskNumber > totalDiscs {
+			totalDiscs = track.DiskNumber
+		}
+	}
 
 	tracks := make([]AlbumTrackMetadata, 0, len(allTracks))
 	albumType := album.RecordType
@@ -527,7 +654,7 @@ func (c *DeezerClient) GetAlbum(ctx context.Context, albumID string) (*AlbumResp
 
 		tracks = append(tracks, AlbumTrackMetadata{
 			SpotifyID:   fmt.Sprintf("deezer:%d", track.ID),
-			Artists:     track.Artist.Name,
+			Artists:     deezerTrackArtistDisplay(track),
 			Name:        track.Title,
 			AlbumName:   album.Title,
 			AlbumArtist: artistName,
@@ -537,6 +664,7 @@ func (c *DeezerClient) GetAlbum(ctx context.Context, albumID string) (*AlbumResp
 			TrackNumber: trackNum,
 			TotalTracks: album.NbTracks,
 			DiscNumber:  track.DiskNumber,
+			TotalDiscs:  totalDiscs,
 			ExternalURL: track.Link,
 			ISRC:        isrc,
 			AlbumID:     fmt.Sprintf("deezer:%d", album.ID),
@@ -550,10 +678,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
@@ -625,6 +755,10 @@ func (c *DeezerClient) GetArtist(ctx context.Context, artistID string) (*ArtistR
 				Artists:     artist.Name,
 			})
 		}
+
+		// The Deezer /artist/{id}/albums endpoint does not return nb_tracks.
+		// Fetch track counts in parallel from individual /album/{id} endpoints.
+		c.fetchAlbumTrackCounts(ctx, albums)
 	}
 
 	result := &ArtistResponsePayload{
@@ -633,15 +767,134 @@ 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
 }
 
+// fetchAlbumTrackCounts fetches nb_tracks for each album in parallel using
+// individual /album/{id} calls, since the /artist/{id}/albums endpoint does
+// not include this field. Albums whose track count is already known (non-zero)
+// are skipped.
+func (c *DeezerClient) fetchAlbumTrackCounts(ctx context.Context, albums []ArtistAlbumMetadata) {
+	// Find albums that need track counts
+	type indexedID struct {
+		idx     int
+		albumID string
+	}
+	var toFetch []indexedID
+	for i, a := range albums {
+		if a.TotalTracks == 0 {
+			rawID := strings.TrimPrefix(a.ID, "deezer:")
+			if rawID != "" {
+				toFetch = append(toFetch, indexedID{idx: i, albumID: rawID})
+			}
+		}
+	}
+	if len(toFetch) == 0 {
+		return
+	}
+
+	const maxParallel = 10
+	sem := make(chan struct{}, maxParallel)
+	var mu sync.Mutex
+	var wg sync.WaitGroup
+
+	for _, item := range toFetch {
+		wg.Add(1)
+		go func(it indexedID) {
+			defer wg.Done()
+
+			select {
+			case sem <- struct{}{}:
+				defer func() { <-sem }()
+			case <-ctx.Done():
+				return
+			}
+
+			albumURL := fmt.Sprintf(deezerAlbumURL, it.albumID)
+			var resp struct {
+				NbTracks int `json:"nb_tracks"`
+			}
+			if err := c.getJSON(ctx, albumURL, &resp); err != nil {
+				return
+			}
+
+			mu.Lock()
+			albums[it.idx].TotalTracks = resp.NbTracks
+			mu.Unlock()
+		}(item)
+	}
+
+	wg.Wait()
+}
+
+func (c *DeezerClient) GetRelatedArtists(ctx context.Context, artistID string, limit int) ([]SearchArtistResult, error) {
+	normalizedArtistID := strings.TrimSpace(strings.TrimPrefix(artistID, "deezer:"))
+	if normalizedArtistID == "" {
+		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)
 
@@ -714,7 +967,7 @@ func (c *DeezerClient) GetPlaylist(ctx context.Context, playlistID string) (*Pla
 
 		tracks = append(tracks, AlbumTrackMetadata{
 			SpotifyID:   fmt.Sprintf("deezer:%d", track.ID),
-			Artists:     track.Artist.Name,
+			Artists:     deezerTrackArtistDisplay(track),
 			Name:        track.Title,
 			AlbumName:   track.Album.Title,
 			AlbumArtist: track.Artist.Name,
@@ -802,6 +1055,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()
 	}
 
@@ -836,6 +1090,7 @@ func (c *DeezerClient) fetchISRCsParallel(ctx context.Context, tracks []deezerTr
 
 			c.cacheMu.Lock()
 			c.isrcCache[trackIDStr] = fullTrack.ISRC
+			c.maybeCleanupCachesLocked(time.Now())
 			c.cacheMu.Unlock()
 		}(track)
 	}
@@ -859,6 +1114,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
@@ -904,8 +1160,9 @@ func (c *DeezerClient) getBestAlbumImage(album deezerAlbumFull) string {
 }
 
 type AlbumExtendedMetadata struct {
-	Genre string
-	Label string
+	Genre     string
+	Label     string
+	Copyright string
 }
 
 func (c *DeezerClient) GetAlbumExtendedMetadata(ctx context.Context, albumID string) (*AlbumExtendedMetadata, error) {
@@ -936,18 +1193,21 @@ func (c *DeezerClient) GetAlbumExtendedMetadata(ctx context.Context, albumID str
 	}
 
 	result := &AlbumExtendedMetadata{
-		Genre: strings.Join(genres, ", "),
-		Label: album.Label,
+		Genre:     strings.Join(genres, ", "),
+		Label:     album.Label,
+		Copyright: album.Copyright,
 	}
 
 	c.cacheMu.Lock()
+	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)
+	GoLog("[Deezer] Album metadata fetched - Genre: %s, Label: %s, Copyright: %s\n", result.Genre, result.Label, result.Copyright)
 
 	return result, nil
 }
@@ -992,6 +1252,41 @@ func (c *DeezerClient) GetExtendedMetadataByISRC(ctx context.Context, isrc strin
 }
 
 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))
+			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()
+
+		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

go_backend/duplicate.go

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

go_backend/exports_deezer_metadata_test.go

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

go_backend/exports_test.go

@@ -0,0 +1,432 @@
+package gobackend
+
+import (
+	"context"
+	"testing"
+)
+
+func TestSetExtensionFallbackProviderIDsJSONEmptyStringResetsDefault(t *testing.T) {
+	original := GetExtensionFallbackProviderIDs()
+	defer SetExtensionFallbackProviderIDs(original)
+
+	SetExtensionFallbackProviderIDs([]string{"custom-ext"})
+
+	if err := SetExtensionFallbackProviderIDsJSON(""); err != nil {
+		t.Fatalf("SetExtensionFallbackProviderIDsJSON returned error: %v", err)
+	}
+
+	if got := GetExtensionFallbackProviderIDs(); got != nil {
+		t.Fatalf("expected nil fallback provider list after reset, got %v", got)
+	}
+}
+
+func TestBuildDownloadSuccessResponsePrefersRequestedAlbumMetadata(t *testing.T) {
+	req := DownloadRequest{
+		TrackName:   "Bonus Track",
+		ArtistName:  "Artist",
+		AlbumName:   "Album (Deluxe)",
+		AlbumArtist: "Artist",
+		ReleaseDate: "2024-01-01",
+		TrackNumber: 14,
+		DiscNumber:  1,
+		ISRC:        "REQ123",
+		CoverURL:    "https://example.com/cover.jpg",
+		Genre:       "Pop",
+		Label:       "Label",
+		Copyright:   "Copyright",
+	}
+
+	result := DownloadResult{
+		Title:       "Bonus Track",
+		Artist:      "Artist",
+		Album:       "Album",
+		ReleaseDate: "2023-12-01",
+		TrackNumber: 2,
+		DiscNumber:  9,
+		ISRC:        "RES456",
+	}
+
+	resp := buildDownloadSuccessResponse(
+		req,
+		result,
+		"tidal",
+		"ok",
+		"/tmp/test.flac",
+		false,
+	)
+
+	if resp.Album != req.AlbumName {
+		t.Fatalf("album = %q, want %q", resp.Album, req.AlbumName)
+	}
+	if resp.ReleaseDate != req.ReleaseDate {
+		t.Fatalf("release date = %q, want %q", resp.ReleaseDate, req.ReleaseDate)
+	}
+	if resp.TrackNumber != req.TrackNumber {
+		t.Fatalf("track number = %d, want %d", resp.TrackNumber, req.TrackNumber)
+	}
+	if resp.DiscNumber != req.DiscNumber {
+		t.Fatalf("disc number = %d, want %d", resp.DiscNumber, req.DiscNumber)
+	}
+	if resp.Artist != result.Artist {
+		t.Fatalf("artist = %q, want provider artist %q", resp.Artist, result.Artist)
+	}
+	if resp.ISRC != result.ISRC {
+		t.Fatalf("isrc = %q, want provider isrc %q", resp.ISRC, result.ISRC)
+	}
+}
+
+func TestPreferredReleaseMetadataPrefersRequestValues(t *testing.T) {
+	album, releaseDate, trackNumber, discNumber := preferredReleaseMetadata(
+		DownloadRequest{
+			AlbumName:   "Album (Deluxe Edition)",
+			ReleaseDate: "2024-01-01",
+			TrackNumber: 13,
+			DiscNumber:  2,
+		},
+		"Album",
+		"2023-01-01",
+		3,
+		1,
+	)
+
+	if album != "Album (Deluxe Edition)" {
+		t.Fatalf("album = %q", album)
+	}
+	if releaseDate != "2024-01-01" {
+		t.Fatalf("release date = %q", releaseDate)
+	}
+	if trackNumber != 13 {
+		t.Fatalf("track number = %d", trackNumber)
+	}
+	if discNumber != 2 {
+		t.Fatalf("disc number = %d", discNumber)
+	}
+}
+
+func TestBuildDownloadSuccessResponsePrefersProviderCoverURL(t *testing.T) {
+	req := DownloadRequest{
+		TrackName:   "Track",
+		ArtistName:  "Artist",
+		AlbumName:   "Album",
+		AlbumArtist: "Artist",
+	}
+
+	result := DownloadResult{
+		Title:    "Track",
+		Artist:   "Artist",
+		Album:    "Album",
+		CoverURL: "https://cdn.qobuz.test/cover.jpg",
+	}
+
+	resp := buildDownloadSuccessResponse(
+		req,
+		result,
+		"qobuz",
+		"ok",
+		"/tmp/test.flac",
+		false,
+	)
+
+	if resp.CoverURL != result.CoverURL {
+		t.Fatalf("cover url = %q, want %q", resp.CoverURL, result.CoverURL)
+	}
+}
+
+func TestBuildDownloadSuccessResponseNormalizesDecryptionDescriptor(t *testing.T) {
+	req := DownloadRequest{
+		TrackName:  "Track",
+		ArtistName: "Artist",
+	}
+
+	result := DownloadResult{
+		Title:         "Track",
+		Artist:        "Artist",
+		DecryptionKey: "00112233",
+	}
+
+	resp := buildDownloadSuccessResponse(
+		req,
+		result,
+		"amazon",
+		"ok",
+		"/tmp/test.m4a",
+		false,
+	)
+
+	if resp.Decryption == nil {
+		t.Fatal("expected decryption descriptor to be present")
+	}
+	if resp.Decryption.Strategy != genericFFmpegMOVDecryptionStrategy {
+		t.Fatalf("strategy = %q", resp.Decryption.Strategy)
+	}
+	if resp.Decryption.Key != result.DecryptionKey {
+		t.Fatalf("key = %q, want %q", resp.Decryption.Key, result.DecryptionKey)
+	}
+}
+
+func TestFormatMusicBrainzGenrePrefersHighestCountTag(t *testing.T) {
+	got := formatMusicBrainzGenre([]musicBrainzTag{
+		{Name: "art pop", Count: 3},
+		{Name: "pop", Count: 8},
+		{Name: "dance pop", Count: 5},
+	})
+
+	if got != "Pop" {
+		t.Fatalf("genre = %q, want %q", got, "Pop")
+	}
+}
+
+func TestEnrichExtraMetadataByISRCFallsBackToMusicBrainzGenre(t *testing.T) {
+	origDeezerFetcher := fetchDeezerExtendedMetadataByISRC
+	origMusicBrainzFetcher := fetchMusicBrainzGenreByISRC
+	defer func() {
+		fetchDeezerExtendedMetadataByISRC = origDeezerFetcher
+		fetchMusicBrainzGenreByISRC = origMusicBrainzFetcher
+	}()
+
+	fetchDeezerExtendedMetadataByISRC = func(ctx context.Context, isrc string) (*AlbumExtendedMetadata, error) {
+		return nil, nil
+	}
+	fetchMusicBrainzGenreByISRC = func(isrc string) (string, error) {
+		if isrc != "TEST123" {
+			t.Fatalf("unexpected isrc: %q", isrc)
+		}
+		return "Alternative Rock", nil
+	}
+
+	genre := ""
+	label := ""
+	copyright := ""
+	enrichExtraMetadataByISRC("DownloadWithFallback", "TEST123", &genre, &label, &copyright)
+
+	if genre != "Alternative Rock" {
+		t.Fatalf("genre = %q, want fallback genre", genre)
+	}
+	if label != "" {
+		t.Fatalf("label = %q, want empty", label)
+	}
+	if copyright != "" {
+		t.Fatalf("copyright = %q, want empty", copyright)
+	}
+}
+
+func TestEnrichExtraMetadataByISRCPrefersDeezerGenre(t *testing.T) {
+	origDeezerFetcher := fetchDeezerExtendedMetadataByISRC
+	origMusicBrainzFetcher := fetchMusicBrainzGenreByISRC
+	defer func() {
+		fetchDeezerExtendedMetadataByISRC = origDeezerFetcher
+		fetchMusicBrainzGenreByISRC = origMusicBrainzFetcher
+	}()
+
+	musicBrainzCalled := false
+	fetchDeezerExtendedMetadataByISRC = func(ctx context.Context, isrc string) (*AlbumExtendedMetadata, error) {
+		return &AlbumExtendedMetadata{
+			Genre:     "Synthpop",
+			Label:     "EMI",
+			Copyright: "(C) Test",
+		}, nil
+	}
+	fetchMusicBrainzGenreByISRC = func(isrc string) (string, error) {
+		musicBrainzCalled = true
+		return "Rock", nil
+	}
+
+	genre := ""
+	label := ""
+	copyright := ""
+	enrichExtraMetadataByISRC("DownloadWithFallback", "TEST456", &genre, &label, &copyright)
+
+	if genre != "Synthpop" {
+		t.Fatalf("genre = %q, want Deezer genre", genre)
+	}
+	if label != "EMI" {
+		t.Fatalf("label = %q, want Deezer label", label)
+	}
+	if copyright != "(C) Test" {
+		t.Fatalf("copyright = %q, want Deezer copyright", copyright)
+	}
+	if musicBrainzCalled {
+		t.Fatal("expected MusicBrainz not to be called when Deezer already provides genre")
+	}
+}
+
+func TestApplyReEnrichTrackMetadataPreservesExistingReleaseDateWhenCandidateMissing(t *testing.T) {
+	req := reEnrichRequest{
+		SpotifyID:   "spotify-track-id",
+		AlbumName:   "Original Album",
+		ReleaseDate: "2024-01-01",
+		ISRC:        "REQ123",
+	}
+
+	applyReEnrichTrackMetadata(&req, ExtTrackMetadata{
+		AlbumName:   "Resolved Album",
+		ReleaseDate: "",
+		ISRC:        "",
+	})
+
+	if req.ReleaseDate != "2024-01-01" {
+		t.Fatalf("release date = %q, want existing value preserved", req.ReleaseDate)
+	}
+	if req.AlbumName != "Resolved Album" {
+		t.Fatalf("album = %q, want updated album", req.AlbumName)
+	}
+	if req.ISRC != "REQ123" {
+		t.Fatalf("isrc = %q, want existing value preserved", req.ISRC)
+	}
+}
+
+func TestSelectBestReEnrichTrackPrefersCandidateWithReleaseDate(t *testing.T) {
+	req := reEnrichRequest{
+		TrackName:   "Song Title",
+		ArtistName:  "Artist Name",
+		AlbumName:   "Album Name",
+		ReleaseDate: "",
+		DurationMs:  180000,
+	}
+
+	tracks := []ExtTrackMetadata{
+		{
+			ID:          "first",
+			Name:        "Song Title",
+			Artists:     "Artist Name",
+			AlbumName:   "Album Name",
+			DurationMS:  180000,
+			ReleaseDate: "",
+			ProviderID:  "spotify",
+		},
+		{
+			ID:          "second",
+			Name:        "Song Title",
+			Artists:     "Artist Name",
+			AlbumName:   "Album Name",
+			DurationMS:  180000,
+			ReleaseDate: "2024-03-09",
+			ProviderID:  "deezer",
+		},
+	}
+
+	best := selectBestReEnrichTrack(req, tracks)
+	if best == nil {
+		t.Fatal("expected a selected track")
+	}
+	if best.ID != "second" {
+		t.Fatalf("selected track = %q, want candidate with release date", best.ID)
+	}
+}
+
+func TestBuildReEnrichFFmpegMetadataOmitsEmptyFields(t *testing.T) {
+	req := reEnrichRequest{
+		TrackName:   "Song",
+		ArtistName:  "Artist",
+		AlbumName:   "Album",
+		AlbumArtist: "",
+		ReleaseDate: "",
+		TrackNumber: 0,
+		DiscNumber:  0,
+		ISRC:        "",
+		Genre:       "",
+		Label:       "",
+		Copyright:   "",
+	}
+
+	metadata := buildReEnrichFFmpegMetadata(&req, "")
+
+	if metadata["TITLE"] != "Song" {
+		t.Fatalf("title = %q", metadata["TITLE"])
+	}
+	if metadata["ARTIST"] != "Artist" {
+		t.Fatalf("artist = %q", metadata["ARTIST"])
+	}
+	if metadata["ALBUM"] != "Album" {
+		t.Fatalf("album = %q", metadata["ALBUM"])
+	}
+
+	for _, key := range []string{
+		"ALBUMARTIST",
+		"DATE",
+		"TRACKNUMBER",
+		"DISCNUMBER",
+		"ISRC",
+		"GENRE",
+		"ORGANIZATION",
+		"COPYRIGHT",
+		"LYRICS",
+		"UNSYNCEDLYRICS",
+	} {
+		if _, exists := metadata[key]; exists {
+			t.Fatalf("did not expect key %s in metadata: %#v", key, metadata)
+		}
+	}
+}
+
+func TestBuildReEnrichSearchQuerySkipsPlaceholderArtist(t *testing.T) {
+	req := reEnrichRequest{
+		TrackName:  "Sign of the Times",
+		ArtistName: "Unknown Artist",
+		AlbumName:  "Harry Styles",
+	}
+
+	query := buildReEnrichSearchQuery(req)
+	if query != "Sign of the Times" {
+		t.Fatalf("query = %q", query)
+	}
+
+	req = reEnrichRequest{
+		TrackName:  "Unknown Title",
+		ArtistName: "Unknown Artist",
+		AlbumName:  "Harry Styles",
+	}
+	query = buildReEnrichSearchQuery(req)
+	if query != "Harry Styles" {
+		t.Fatalf("fallback album query = %q", query)
+	}
+}
+
+func TestApplyReEnrichTrackMetadataCopiesComposerAndTotals(t *testing.T) {
+	req := reEnrichRequest{}
+
+	applyReEnrichTrackMetadata(&req, ExtTrackMetadata{
+		Name:        "Resolved Song",
+		Artists:     "Resolved Artist",
+		TrackNumber: 7,
+		TotalTracks: 12,
+		DiscNumber:  2,
+		TotalDiscs:  3,
+		Composer:    "Composer",
+	})
+
+	if req.TrackNumber != 7 || req.TotalTracks != 12 {
+		t.Fatalf("track metadata = %d/%d", req.TrackNumber, req.TotalTracks)
+	}
+	if req.DiscNumber != 2 || req.TotalDiscs != 3 {
+		t.Fatalf("disc metadata = %d/%d", req.DiscNumber, req.TotalDiscs)
+	}
+	if req.TrackName != "Resolved Song" || req.ArtistName != "Resolved Artist" {
+		t.Fatalf("basic tags = %q / %q", req.TrackName, req.ArtistName)
+	}
+	if req.Composer != "Composer" {
+		t.Fatalf("composer = %q", req.Composer)
+	}
+}
+
+func TestBuildReEnrichFFmpegMetadataFormatsTotalsAndComposer(t *testing.T) {
+	req := reEnrichRequest{
+		TrackNumber: 7,
+		TotalTracks: 12,
+		DiscNumber:  2,
+		TotalDiscs:  3,
+		Composer:    "Composer",
+	}
+
+	metadata := buildReEnrichFFmpegMetadata(&req, "")
+
+	if metadata["TRACKNUMBER"] != "7/12" {
+		t.Fatalf("TRACKNUMBER = %q", metadata["TRACKNUMBER"])
+	}
+	if metadata["DISCNUMBER"] != "2/3" {
+		t.Fatalf("DISCNUMBER = %q", metadata["DISCNUMBER"])
+	}
+	if metadata["COMPOSER"] != "Composer" {
+		t.Fatalf("COMPOSER = %q", metadata["COMPOSER"])
+	}
+}

go_backend/extension_manager.go

@@ -43,40 +43,101 @@ func compareVersions(v1, v2 string) int {
 	return 0
 }
 
-type LoadedExtension struct {
-	ID        string             `json:"id"`
-	Manifest  *ExtensionManifest `json:"manifest"`
-	VM        *goja.Runtime      `json:"-"`
-	VMMu      sync.Mutex         `json:"-"`
-	Enabled   bool               `json:"enabled"`
-	Error     string             `json:"error,omitempty"`
-	DataDir   string             `json:"data_dir"`
-	SourceDir string             `json:"source_dir"`
-	IconPath  string             `json:"icon_path"`
+type loadedExtension struct {
+	ID          string             `json:"id"`
+	Manifest    *ExtensionManifest `json:"manifest"`
+	VM          *goja.Runtime      `json:"-"`
+	VMMu        sync.Mutex         `json:"-"`
+	runtime     *extensionRuntime
+	initialized bool
+	Enabled     bool   `json:"enabled"`
+	Error       string `json:"error,omitempty"`
+	DataDir     string `json:"data_dir"`
+	SourceDir   string `json:"source_dir"`
+	IconPath    string `json:"icon_path"`
 }
 
-type ExtensionManager struct {
+func getExtensionInitSettings(extensionID string) map[string]interface{} {
+	settings := GetExtensionSettingsStore().GetAll(extensionID)
+	if len(settings) == 0 {
+		return settings
+	}
+
+	filtered := make(map[string]interface{}, len(settings))
+	for key, value := range settings {
+		if strings.HasPrefix(key, "_") {
+			continue
+		}
+		filtered[key] = value
+	}
+	return filtered
+}
+
+func ensureRuntimeReadyLocked(ext *loadedExtension, applyStoredSettings bool) error {
+	if ext.VM == nil || ext.runtime == nil {
+		if err := initializeVMLocked(ext); err != nil {
+			ext.Error = err.Error()
+			ext.Enabled = false
+			return err
+		}
+	}
+
+	if applyStoredSettings && !ext.initialized {
+		settings := getExtensionInitSettings(ext.ID)
+		if len(settings) > 0 {
+			if err := initializeExtensionWithSettingsLocked(ext, settings); err != nil {
+				teardownVMLocked(ext)
+				ext.Error = err.Error()
+				ext.Enabled = false
+				return err
+			}
+		} else {
+			ext.initialized = true
+		}
+	}
+
+	ext.Error = ""
+	return nil
+}
+
+func (ext *loadedExtension) ensureRuntimeReady() error {
+	ext.VMMu.Lock()
+	defer ext.VMMu.Unlock()
+
+	return ensureRuntimeReadyLocked(ext, true)
+}
+
+func (ext *loadedExtension) lockReadyVM() (*goja.Runtime, error) {
+	ext.VMMu.Lock()
+	if err := ensureRuntimeReadyLocked(ext, true); err != nil {
+		ext.VMMu.Unlock()
+		return nil, err
+	}
+	return ext.VM, nil
+}
+
+type extensionManager struct {
 	mu            sync.RWMutex
-	extensions    map[string]*LoadedExtension
+	extensions    map[string]*loadedExtension
 	extensionsDir string
 	dataDir       string
 }
 
 var (
-	globalExtManager     *ExtensionManager
+	globalExtManager     *extensionManager
 	globalExtManagerOnce sync.Once
 )
 
-func GetExtensionManager() *ExtensionManager {
+func getExtensionManager() *extensionManager {
 	globalExtManagerOnce.Do(func() {
-		globalExtManager = &ExtensionManager{
-			extensions: make(map[string]*LoadedExtension),
+		globalExtManager = &extensionManager{
+			extensions: make(map[string]*loadedExtension),
 		}
 	})
 	return globalExtManager
 }
 
-func (m *ExtensionManager) SetDirectories(extensionsDir, dataDir string) error {
+func (m *extensionManager) SetDirectories(extensionsDir, dataDir string) error {
 	m.mu.Lock()
 	defer m.mu.Unlock()
 
@@ -93,7 +154,7 @@ func (m *ExtensionManager) SetDirectories(extensionsDir, dataDir string) error {
 	return nil
 }
 
-func (m *ExtensionManager) LoadExtensionFromFile(filePath string) (*LoadedExtension, error) {
+func (m *extensionManager) LoadExtensionFromFile(filePath string) (*loadedExtension, error) {
 	if !strings.HasSuffix(strings.ToLower(filePath), ".spotiflac-ext") {
 		return nil, fmt.Errorf("Invalid file format. Please select a .spotiflac-ext file")
 	}
@@ -150,7 +211,6 @@ func (m *ExtensionManager) LoadExtensionFromFile(filePath string) (*LoadedExtens
 	if exists {
 		versionCompare := compareVersions(manifest.Version, existingVersion)
 		if versionCompare > 0 {
-			// This is an upgrade - call UpgradeExtension
 			return m.UpgradeExtension(filePath)
 		} else if versionCompare == 0 {
 			return nil, fmt.Errorf("Extension '%s' v%s is already installed", existingDisplayName, existingVersion)
@@ -212,7 +272,7 @@ func (m *ExtensionManager) LoadExtensionFromFile(filePath string) (*LoadedExtens
 		return nil, fmt.Errorf("failed to create extension data directory: %w", err)
 	}
 
-	ext := &LoadedExtension{
+	ext := &loadedExtension{
 		ID:        manifest.Name,
 		Manifest:  manifest,
 		Enabled:   false, // New extensions start disabled
@@ -220,10 +280,10 @@ func (m *ExtensionManager) LoadExtensionFromFile(filePath string) (*LoadedExtens
 		SourceDir: extDir,
 	}
 
-	if err := m.initializeVM(ext); err != nil {
+	if err := validateExtensionLoad(ext); err != nil {
 		ext.Error = err.Error()
 		ext.Enabled = false
-		GoLog("[Extension] Failed to initialize VM for %s: %v\n", manifest.Name, err)
+		GoLog("[Extension] Failed to validate extension %s: %v\n", manifest.Name, err)
 	}
 
 	m.extensions[manifest.Name] = ext
@@ -232,7 +292,10 @@ func (m *ExtensionManager) LoadExtensionFromFile(filePath string) (*LoadedExtens
 	return ext, nil
 }
 
-func (m *ExtensionManager) initializeVM(ext *LoadedExtension) error {
+func initializeVMLocked(ext *loadedExtension) error {
+	ext.VM = nil
+	ext.runtime = nil
+	ext.initialized = false
 	vm := goja.New()
 	ext.VM = vm
 
@@ -242,7 +305,8 @@ func (m *ExtensionManager) initializeVM(ext *LoadedExtension) error {
 		return fmt.Errorf("failed to read index.js: %w", err)
 	}
 
-	runtime := NewExtensionRuntime(ext)
+	runtime := newExtensionRuntime(ext)
+	ext.runtime = runtime
 	runtime.RegisterAPIs(vm)
 	runtime.RegisterGoBackendAPIs(vm)
 
@@ -278,7 +342,137 @@ func (m *ExtensionManager) initializeVM(ext *LoadedExtension) error {
 	return nil
 }
 
-func (m *ExtensionManager) UnloadExtension(extensionID string) error {
+func (m *extensionManager) initializeVM(ext *loadedExtension) error {
+	ext.VMMu.Lock()
+	defer ext.VMMu.Unlock()
+	return initializeVMLocked(ext)
+}
+
+func initializeExtensionWithSettingsLocked(
+	ext *loadedExtension,
+	settings map[string]interface{},
+) error {
+	if ext.VM == nil {
+		return fmt.Errorf("Extension failed to load. Please reinstall the extension")
+	}
+
+	settingsJSON, err := json.Marshal(settings)
+	if err != nil {
+		return fmt.Errorf("Failed to save settings")
+	}
+
+	script := fmt.Sprintf(`
+		(function() {
+			var settings = %s;
+			if (typeof extension !== 'undefined' && typeof extension.initialize === 'function') {
+				try {
+					extension.initialize(settings);
+					return { success: true };
+				} catch (e) {
+					return { success: false, error: e.toString() };
+				}
+			}
+			return { success: true, message: 'no initialize function' };
+		})()
+	`, string(settingsJSON))
+
+	result, err := ext.VM.RunString(script)
+	if err != nil {
+		ext.Error = fmt.Sprintf("initialize failed: %v", err)
+		ext.Enabled = false
+		GoLog("[Extension] Initialize error for %s: %v\n", ext.ID, err)
+		return err
+	}
+
+	if result != nil && !goja.IsUndefined(result) {
+		exported := result.Export()
+		if resultMap, ok := exported.(map[string]interface{}); ok {
+			if success, ok := resultMap["success"].(bool); ok && !success {
+				errMsg := "unknown error"
+				if e, ok := resultMap["error"].(string); ok {
+					errMsg = e
+				}
+				ext.Error = errMsg
+				ext.Enabled = false
+				GoLog("[Extension] Initialize failed for %s: %s\n", ext.ID, errMsg)
+				return fmt.Errorf("initialize failed: %s", errMsg)
+			}
+		}
+	}
+
+	ext.initialized = true
+	GoLog("[Extension] Initialized %s\n", ext.ID)
+	return nil
+}
+
+func runCleanupLocked(ext *loadedExtension) error {
+	if ext.VM != nil {
+		script := `
+			(function() {
+				if (typeof extension !== 'undefined' && typeof extension.cleanup === 'function') {
+					try {
+						extension.cleanup();
+						return { success: true };
+					} catch (e) {
+						return { success: false, error: e.toString() };
+					}
+				}
+				return { success: true, message: 'no cleanup function' };
+			})()
+		`
+
+		result, err := ext.VM.RunString(script)
+		if err != nil {
+			return err
+		}
+
+		if result != nil && !goja.IsUndefined(result) {
+			exported := result.Export()
+			if resultMap, ok := exported.(map[string]interface{}); ok {
+				if success, ok := resultMap["success"].(bool); ok && !success {
+					errMsg := "unknown error"
+					if e, ok := resultMap["error"].(string); ok {
+						errMsg = e
+					}
+					return fmt.Errorf("cleanup failed: %s", errMsg)
+				}
+			}
+		}
+
+		if result != nil && !goja.IsUndefined(result) && !goja.IsNull(result) {
+			GoLog("[Extension] Cleanup called for %s\n", ext.ID)
+		}
+	}
+	return nil
+}
+
+func teardownVMLocked(ext *loadedExtension) {
+	if err := runCleanupLocked(ext); err != nil {
+		GoLog("[Extension] Error calling cleanup for %s: %v\n", ext.ID, err)
+	}
+	if ext.runtime != nil {
+		if err := ext.runtime.flushStorageNow(); err != nil {
+			GoLog("[Extension] Failed to flush storage for %s: %v\n", ext.ID, err)
+		}
+		ext.runtime.closeStorageFlusher()
+	}
+	ext.runtime = nil
+	ext.VM = nil
+	ext.initialized = false
+}
+
+func validateExtensionLoad(ext *loadedExtension) error {
+	ext.VMMu.Lock()
+	defer ext.VMMu.Unlock()
+
+	if err := initializeVMLocked(ext); err != nil {
+		return err
+	}
+	teardownVMLocked(ext)
+	return nil
+}
+
+func (m *extensionManager) UnloadExtension(extensionID string) error {
 	m.mu.Lock()
 	defer m.mu.Unlock()
 
@@ -287,14 +481,9 @@ func (m *ExtensionManager) UnloadExtension(extensionID string) error {
 		return fmt.Errorf("Extension not found")
 	}
 
-	if ext.VM != nil {
-		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)
-		} else if cleanup != nil && !goja.IsUndefined(cleanup) && !goja.IsNull(cleanup) {
-			GoLog("[Extension] Cleanup called for %s\n", extensionID)
-		}
-	}
+	ext.VMMu.Lock()
+	teardownVMLocked(ext)
+	ext.VMMu.Unlock()
 
 	delete(m.extensions, extensionID)
 	GoLog("[Extension] Unloaded extension: %s\n", extensionID)
@@ -302,7 +491,7 @@ func (m *ExtensionManager) UnloadExtension(extensionID string) error {
 	return nil
 }
 
-func (m *ExtensionManager) GetExtension(extensionID string) (*LoadedExtension, error) {
+func (m *extensionManager) GetExtension(extensionID string) (*loadedExtension, error) {
 	m.mu.RLock()
 	defer m.mu.RUnlock()
 
@@ -313,18 +502,18 @@ func (m *ExtensionManager) GetExtension(extensionID string) (*LoadedExtension, e
 	return ext, nil
 }
 
-func (m *ExtensionManager) GetAllExtensions() []*LoadedExtension {
+func (m *extensionManager) GetAllExtensions() []*loadedExtension {
 	m.mu.RLock()
 	defer m.mu.RUnlock()
 
-	result := make([]*LoadedExtension, 0, len(m.extensions))
+	result := make([]*loadedExtension, 0, len(m.extensions))
 	for _, ext := range m.extensions {
 		result = append(result, ext)
 	}
 	return result
 }
 
-func (m *ExtensionManager) SetExtensionEnabled(extensionID string, enabled bool) error {
+func (m *extensionManager) SetExtensionEnabled(extensionID string, enabled bool) error {
 	m.mu.Lock()
 	defer m.mu.Unlock()
 
@@ -333,7 +522,21 @@ func (m *ExtensionManager) SetExtensionEnabled(extensionID string, enabled bool)
 		return fmt.Errorf("Extension not found")
 	}
 
-	ext.Enabled = enabled
+	if enabled {
+		ext.Enabled = true
+		if err := ext.ensureRuntimeReady(); err != nil {
+			store := GetExtensionSettingsStore()
+			ext.Enabled = false
+			_ = store.Set(extensionID, "_enabled", false)
+			return err
+		}
+	} else {
+		ext.Enabled = false
+		ext.Error = ""
+		ext.VMMu.Lock()
+		teardownVMLocked(ext)
+		ext.VMMu.Unlock()
+	}
 	GoLog("[Extension] %s %s\n", extensionID, map[bool]string{true: "enabled", false: "disabled"}[enabled])
 
 	store := GetExtensionSettingsStore()
@@ -344,7 +547,7 @@ func (m *ExtensionManager) SetExtensionEnabled(extensionID string, enabled bool)
 	return nil
 }
 
-func (m *ExtensionManager) LoadExtensionsFromDirectory(dirPath string) ([]string, []error) {
+func (m *extensionManager) LoadExtensionsFromDirectory(dirPath string) ([]string, []error) {
 	var loaded []string
 	var errors []error
 
@@ -382,7 +585,7 @@ func (m *ExtensionManager) LoadExtensionsFromDirectory(dirPath string) ([]string
 	return loaded, errors
 }
 
-func (m *ExtensionManager) loadExtensionFromDirectory(dirPath string) (*LoadedExtension, error) {
+func (m *extensionManager) loadExtensionFromDirectory(dirPath string) (*loadedExtension, error) {
 	m.mu.Lock()
 	defer m.mu.Unlock()
 
@@ -392,7 +595,6 @@ func (m *ExtensionManager) loadExtensionFromDirectory(dirPath string) (*LoadedEx
 		return nil, fmt.Errorf("failed to read manifest.json: %w", err)
 	}
 
-	// Parse and validate manifest
 	manifest, err := ParseManifest(manifestData)
 	if err != nil {
 		return nil, fmt.Errorf("Invalid extension manifest: %w", err)
@@ -413,7 +615,7 @@ func (m *ExtensionManager) loadExtensionFromDirectory(dirPath string) (*LoadedEx
 		return nil, fmt.Errorf("failed to create extension data directory: %w", err)
 	}
 
-	ext := &LoadedExtension{
+	ext := &loadedExtension{
 		ID:        manifest.Name,
 		Manifest:  manifest,
 		Enabled:   false, // Will be restored from settings store
@@ -421,7 +623,6 @@ func (m *ExtensionManager) loadExtensionFromDirectory(dirPath string) (*LoadedEx
 		SourceDir: dirPath,
 	}
 
-	// Restore enabled state from settings store
 	store := GetExtensionSettingsStore()
 	if enabledVal, err := store.Get(manifest.Name, "_enabled"); err == nil {
 		if enabled, ok := enabledVal.(bool); ok {
@@ -430,10 +631,10 @@ func (m *ExtensionManager) loadExtensionFromDirectory(dirPath string) (*LoadedEx
 		}
 	}
 
-	if err := m.initializeVM(ext); err != nil {
+	if err := validateExtensionLoad(ext); err != nil {
 		ext.Error = err.Error()
 		ext.Enabled = false
-		GoLog("[Extension] Failed to initialize VM for %s: %v\n", manifest.Name, err)
+		GoLog("[Extension] Failed to validate extension %s: %v\n", manifest.Name, err)
 	}
 
 	m.extensions[manifest.Name] = ext
@@ -442,7 +643,7 @@ func (m *ExtensionManager) loadExtensionFromDirectory(dirPath string) (*LoadedEx
 	return ext, nil
 }
 
-func (m *ExtensionManager) RemoveExtension(extensionID string) error {
+func (m *extensionManager) RemoveExtension(extensionID string) error {
 	ext, err := m.GetExtension(extensionID)
 	if err != nil {
 		return err
@@ -458,17 +659,11 @@ func (m *ExtensionManager) RemoveExtension(extensionID string) error {
 		}
 	}
 
-	// Optionally remove data directory (keep for now to preserve settings)
-	// if ext.DataDir != "" {
-	//     os.RemoveAll(ext.DataDir)
-	// }
-
 	return nil
 }
 
 // Only allows upgrades (new version > current version), not downgrades
-func (m *ExtensionManager) UpgradeExtension(filePath string) (*LoadedExtension, error) {
-	// Validate file extension
+func (m *extensionManager) UpgradeExtension(filePath string) (*loadedExtension, error) {
 	if !strings.HasSuffix(strings.ToLower(filePath), ".spotiflac-ext") {
 		return nil, fmt.Errorf("Invalid file format. Please select a .spotiflac-ext file")
 	}
@@ -520,7 +715,6 @@ func (m *ExtensionManager) UpgradeExtension(filePath string) (*LoadedExtension,
 		return nil, fmt.Errorf("Extension '%s' is not installed. Use install instead of upgrade.", newManifest.DisplayName)
 	}
 
-	// Compare versions - only allow upgrade, not downgrade
 	versionCompare := compareVersions(newManifest.Version, existing.Manifest.Version)
 	if versionCompare < 0 {
 		return nil, fmt.Errorf("Cannot downgrade extension. Current version: %s, New version: %s", existing.Manifest.Version, newManifest.Version)
@@ -531,12 +725,10 @@ func (m *ExtensionManager) UpgradeExtension(filePath string) (*LoadedExtension,
 
 	GoLog("[Extension] Upgrading %s from v%s to v%s\n", newManifest.DisplayName, existing.Manifest.Version, newManifest.Version)
 
-	// Save data directory path and enabled state (we want to preserve them)
 	extDataDir := existing.DataDir
 	extDir := existing.SourceDir
 	wasEnabled := existing.Enabled
 
-	m.CleanupExtension(existing.ID)
 	m.UnloadExtension(existing.ID)
 
 	if extDir != "" {
@@ -585,7 +777,7 @@ func (m *ExtensionManager) UpgradeExtension(filePath string) (*LoadedExtension,
 		}
 	}
 
-	ext := &LoadedExtension{
+	ext := &loadedExtension{
 		ID:        newManifest.Name,
 		Manifest:  newManifest,
 		Enabled:   wasEnabled, // Preserve enabled state from before upgrade
@@ -593,11 +785,14 @@ func (m *ExtensionManager) UpgradeExtension(filePath string) (*LoadedExtension,
 		SourceDir: extDir,
 	}
 
-	// Initialize Goja VM
-	if err := m.initializeVM(ext); err != nil {
+	if wasEnabled {
+		if err := ext.ensureRuntimeReady(); err != nil {
+			GoLog("[Extension] Failed to initialize upgraded extension %s: %v\n", newManifest.Name, err)
+		}
+	} else if err := validateExtensionLoad(ext); err != nil {
 		ext.Error = err.Error()
 		ext.Enabled = false
-		GoLog("[Extension] Failed to initialize VM for %s: %v\n", newManifest.Name, err)
+		GoLog("[Extension] Failed to validate upgraded extension %s: %v\n", newManifest.Name, err)
 	}
 
 	m.mu.Lock()
@@ -617,8 +812,7 @@ type ExtensionUpgradeInfo struct {
 	IsInstalled    bool   `json:"is_installed"`
 }
 
-func (m *ExtensionManager) checkExtensionUpgradeInternal(filePath string) (*ExtensionUpgradeInfo, error) {
-	// Validate file extension
+func (m *extensionManager) checkExtensionUpgradeInternal(filePath string) (*ExtensionUpgradeInfo, error) {
 	if !strings.HasSuffix(strings.ToLower(filePath), ".spotiflac-ext") {
 		return nil, fmt.Errorf("Invalid file format. Please select a .spotiflac-ext file")
 	}
@@ -667,7 +861,6 @@ func (m *ExtensionManager) checkExtensionUpgradeInternal(filePath string) (*Exte
 	}
 
 	if !exists {
-		// Not installed - this is a new install, not upgrade
 		info.CurrentVersion = ""
 		info.CanUpgrade = false
 	} else {
@@ -678,7 +871,7 @@ func (m *ExtensionManager) checkExtensionUpgradeInternal(filePath string) (*Exte
 	return info, nil
 }
 
-func (m *ExtensionManager) CheckExtensionUpgradeJSON(filePath string) (string, error) {
+func (m *extensionManager) CheckExtensionUpgradeJSON(filePath string) (string, error) {
 	info, err := m.checkExtensionUpgradeInternal(filePath)
 	if err != nil {
 		return "", err
@@ -692,7 +885,7 @@ func (m *ExtensionManager) CheckExtensionUpgradeJSON(filePath string) (string, e
 	return string(jsonBytes), nil
 }
 
-func (m *ExtensionManager) GetInstalledExtensionsJSON() (string, error) {
+func (m *extensionManager) GetInstalledExtensionsJSON() (string, error) {
 	extensions := m.GetAllExtensions()
 
 	type ExtensionInfo struct {
@@ -700,7 +893,6 @@ func (m *ExtensionManager) GetInstalledExtensionsJSON() (string, error) {
 		Name                   string                 `json:"name"`
 		DisplayName            string                 `json:"display_name"`
 		Version                string                 `json:"version"`
-		Author                 string                 `json:"author"`
 		Description            string                 `json:"description"`
 		Homepage               string                 `json:"homepage,omitempty"`
 		IconPath               string                 `json:"icon_path,omitempty"`
@@ -713,7 +905,9 @@ 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"`
+		SkipLyrics             bool                   `json:"skip_lyrics"`
 		SearchBehavior         *SearchBehaviorConfig  `json:"search_behavior,omitempty"`
 		TrackMatching          *TrackMatchingConfig   `json:"track_matching,omitempty"`
 		PostProcessing         *PostProcessingConfig  `json:"post_processing,omitempty"`
@@ -730,7 +924,6 @@ func (m *ExtensionManager) GetInstalledExtensionsJSON() (string, error) {
 			permissions = append(permissions, "storage:enabled")
 		}
 
-		// Determine status
 		status := "loaded"
 		if ext.Error != "" {
 			status = "error"
@@ -757,7 +950,6 @@ func (m *ExtensionManager) GetInstalledExtensionsJSON() (string, error) {
 			Name:                   ext.Manifest.Name,
 			DisplayName:            ext.Manifest.DisplayName,
 			Version:                ext.Manifest.Version,
-			Author:                 ext.Manifest.Author,
 			Description:            ext.Manifest.Description,
 			Homepage:               ext.Manifest.Homepage,
 			IconPath:               iconPath,
@@ -770,7 +962,9 @@ func (m *ExtensionManager) GetInstalledExtensionsJSON() (string, error) {
 			Permissions:            permissions,
 			HasMetadataProvider:    ext.Manifest.IsMetadataProvider(),
 			HasDownloadProvider:    ext.Manifest.IsDownloadProvider(),
+			HasLyricsProvider:      ext.Manifest.IsLyricsProvider(),
 			SkipMetadataEnrichment: ext.Manifest.SkipMetadataEnrichment,
+			SkipLyrics:             ext.Manifest.SkipLyrics,
 			SearchBehavior:         ext.Manifest.SearchBehavior,
 			TrackMatching:          ext.Manifest.TrackMatching,
 			PostProcessing:         ext.Manifest.PostProcessing,
@@ -786,7 +980,7 @@ func (m *ExtensionManager) GetInstalledExtensionsJSON() (string, error) {
 	return string(jsonBytes), nil
 }
 
-func (m *ExtensionManager) InitializeExtension(extensionID string, settings map[string]interface{}) error {
+func (m *extensionManager) InitializeExtension(extensionID string, settings map[string]interface{}) error {
 	m.mu.Lock()
 	defer m.mu.Unlock()
 
@@ -795,59 +989,16 @@ func (m *ExtensionManager) InitializeExtension(extensionID string, settings map[
 		return fmt.Errorf("Extension not found")
 	}
 
-	if ext.VM == nil {
-		return fmt.Errorf("Extension failed to load. Please reinstall the extension")
-	}
+	ext.VMMu.Lock()
+	defer ext.VMMu.Unlock()
 
-	settingsJSON, err := json.Marshal(settings)
-	if err != nil {
-		return fmt.Errorf("Failed to save settings")
-	}
-
-	script := fmt.Sprintf(`
-		(function() {
-			var settings = %s;
-			if (typeof extension !== 'undefined' && typeof extension.initialize === 'function') {
-				try {
-					extension.initialize(settings);
-					return { success: true };
-				} catch (e) {
-					return { success: false, error: e.toString() };
-				}
-			}
-			return { success: true, message: 'no initialize function' };
-		})()
-	`, string(settingsJSON))
-
-	result, err := ext.VM.RunString(script)
-	if err != nil {
-		ext.Error = fmt.Sprintf("initialize failed: %v", err)
-		ext.Enabled = false
-		GoLog("[Extension] Initialize error for %s: %v\n", extensionID, err)
+	if err := ensureRuntimeReadyLocked(ext, false); err != nil {
 		return err
 	}
-
-	if result != nil && !goja.IsUndefined(result) {
-		exported := result.Export()
-		if resultMap, ok := exported.(map[string]interface{}); ok {
-			if success, ok := resultMap["success"].(bool); ok && !success {
-				errMsg := "unknown error"
-				if e, ok := resultMap["error"].(string); ok {
-					errMsg = e
-				}
-				ext.Error = errMsg
-				ext.Enabled = false
-				GoLog("[Extension] Initialize failed for %s: %s\n", extensionID, errMsg)
-				return fmt.Errorf("initialize failed: %s", errMsg)
-			}
-		}
-	}
-
-	GoLog("[Extension] Initialized %s\n", extensionID)
-	return nil
+	return initializeExtensionWithSettingsLocked(ext, settings)
 }
 
-func (m *ExtensionManager) CleanupExtension(extensionID string) error {
+func (m *extensionManager) CleanupExtension(extensionID string) error {
 	m.mu.Lock()
 	defer m.mu.Unlock()
 
@@ -859,46 +1010,17 @@ func (m *ExtensionManager) CleanupExtension(extensionID string) error {
 	if ext.VM == nil {
 		return nil
 	}
-
-	script := `
-		(function() {
-			if (typeof extension !== 'undefined' && typeof extension.cleanup === 'function') {
-				try {
-					extension.cleanup();
-					return { success: true };
-				} catch (e) {
-					return { success: false, error: e.toString() };
-				}
-			}
-			return { success: true, message: 'no cleanup function' };
-		})()
-	`
-
-	result, err := ext.VM.RunString(script)
-	if err != nil {
+	ext.VMMu.Lock()
+	defer ext.VMMu.Unlock()
+	if err := runCleanupLocked(ext); err != nil {
 		GoLog("[Extension] Cleanup error for %s: %v\n", extensionID, err)
 		return err
 	}
-
-	if result != nil && !goja.IsUndefined(result) {
-		exported := result.Export()
-		if resultMap, ok := exported.(map[string]interface{}); ok {
-			if success, ok := resultMap["success"].(bool); ok && !success {
-				errMsg := "unknown error"
-				if e, ok := resultMap["error"].(string); ok {
-					errMsg = e
-				}
-				GoLog("[Extension] Cleanup failed for %s: %s\n", extensionID, errMsg)
-				return fmt.Errorf("cleanup failed: %s", errMsg)
-			}
-		}
-	}
-
 	GoLog("[Extension] Cleaned up %s\n", extensionID)
 	return nil
 }
 
-func (m *ExtensionManager) UnloadAllExtensions() {
+func (m *extensionManager) UnloadAllExtensions() {
 	m.mu.Lock()
 	extensionIDs := make([]string, 0, len(m.extensions))
 	for id := range m.extensions {
@@ -907,14 +1029,13 @@ func (m *ExtensionManager) UnloadAllExtensions() {
 	m.mu.Unlock()
 
 	for _, id := range extensionIDs {
-		m.CleanupExtension(id)
 		m.UnloadExtension(id)
 	}
 
 	GoLog("[Extension] All extensions unloaded\n")
 }
 
-func (m *ExtensionManager) InvokeAction(extensionID string, actionName string) (map[string]interface{}, error) {
+func (m *extensionManager) InvokeAction(extensionID string, actionName string) (map[string]interface{}, error) {
 	m.mu.Lock()
 	defer m.mu.Unlock()
 
@@ -923,24 +1044,38 @@ func (m *ExtensionManager) InvokeAction(extensionID string, actionName string) (
 		return nil, fmt.Errorf("extension not found: %s", extensionID)
 	}
 
-	if ext.VM == nil {
-		return nil, fmt.Errorf("extension VM not initialized")
-	}
-
 	if !ext.Enabled {
 		return nil, fmt.Errorf("extension is disabled")
 	}
+	vm, err := ext.lockReadyVM()
+	if err != nil {
+		return nil, err
+	}
+	defer ext.VMMu.Unlock()
 
-	// Call the action function on the extension object
+	// Merge extension return values onto the top-level JSON object so Flutter can read
+	// message, open_auth_url, setting_updates without unwrapping a nested "result" key.
 	script := fmt.Sprintf(`
 		(function() {
 			if (typeof extension !== 'undefined' && typeof extension.%s === 'function') {
 				try {
 					var result = extension.%s();
 					if (result && typeof result.then === 'function') {
-						// Handle promise - return pending status
 						return { success: true, pending: true, message: 'Action started' };
 					}
+					if (result !== null && result !== undefined && typeof result === 'object') {
+						var isArr = false;
+						if (typeof Array !== 'undefined' && Array.isArray) {
+							isArr = Array.isArray(result);
+						}
+						if (!isArr) {
+							var out = { success: true };
+							for (var k in result) {
+								out[k] = result[k];
+							}
+							return out;
+						}
+					}
 					return { success: true, result: result };
 				} catch (e) {
 					return { success: false, error: e.toString() };
@@ -950,7 +1085,7 @@ func (m *ExtensionManager) InvokeAction(extensionID string, actionName string) (
 		})()
 	`, actionName, actionName, actionName)
 
-	result, err := RunWithTimeoutAndRecover(ext.VM, script, DefaultJSTimeout)
+	result, err := RunWithTimeoutAndRecover(vm, script, DefaultJSTimeout)
 	if err != nil {
 		GoLog("[Extension] InvokeAction error for %s.%s: %v\n", extensionID, actionName, err)
 		return nil, fmt.Errorf("action failed: %v", err)

go_backend/extension_manifest.go

@@ -1,4 +1,3 @@
-// Package gobackend provides extension manifest parsing and validation
 package gobackend
 
 import (
@@ -12,6 +11,7 @@ type ExtensionType string
 const (
 	ExtensionTypeMetadataProvider ExtensionType = "metadata_provider"
 	ExtensionTypeDownloadProvider ExtensionType = "download_provider"
+	ExtensionTypeLyricsProvider   ExtensionType = "lyrics_provider"
 )
 
 type SettingType string
@@ -105,7 +105,6 @@ type ExtensionManifest struct {
 	Name                   string                 `json:"name"`
 	DisplayName            string                 `json:"displayName"`
 	Version                string                 `json:"version"`
-	Author                 string                 `json:"author"`
 	Description            string                 `json:"description"`
 	Homepage               string                 `json:"homepage,omitempty"`
 	Icon                   string                 `json:"icon,omitempty"`
@@ -115,6 +114,7 @@ type ExtensionManifest struct {
 	QualityOptions         []QualityOption        `json:"qualityOptions,omitempty"`
 	MinAppVersion          string                 `json:"minAppVersion,omitempty"`
 	SkipMetadataEnrichment bool                   `json:"skipMetadataEnrichment,omitempty"`
+	SkipLyrics             bool                   `json:"skipLyrics,omitempty"`
 	SkipBuiltInFallback    bool                   `json:"skipBuiltInFallback,omitempty"`
 	SearchBehavior         *SearchBehaviorConfig  `json:"searchBehavior,omitempty"`
 	URLHandler             *URLHandlerConfig      `json:"urlHandler,omitempty"`
@@ -154,10 +154,6 @@ func (m *ExtensionManifest) Validate() error {
 		return &ManifestValidationError{Field: "version", Message: "version is required"}
 	}
 
-	if strings.TrimSpace(m.Author) == "" {
-		return &ManifestValidationError{Field: "author", Message: "author is required"}
-	}
-
 	if strings.TrimSpace(m.Description) == "" {
 		return &ManifestValidationError{Field: "description", Message: "description is required"}
 	}
@@ -167,10 +163,10 @@ func (m *ExtensionManifest) Validate() error {
 	}
 
 	for _, t := range m.Types {
-		if t != ExtensionTypeMetadataProvider && t != ExtensionTypeDownloadProvider {
+		if t != ExtensionTypeMetadataProvider && t != ExtensionTypeDownloadProvider && t != ExtensionTypeLyricsProvider {
 			return &ManifestValidationError{
 				Field:   "type",
-				Message: fmt.Sprintf("invalid extension type: %s (must be 'metadata_provider' or 'download_provider')", t),
+				Message: fmt.Sprintf("invalid extension type: %s (must be 'metadata_provider', 'download_provider', or 'lyrics_provider')", t),
 			}
 		}
 	}
@@ -226,6 +222,10 @@ func (m *ExtensionManifest) IsDownloadProvider() bool {
 	return m.HasType(ExtensionTypeDownloadProvider)
 }
 
+func (m *ExtensionManifest) IsLyricsProvider() bool {
+	return m.HasType(ExtensionTypeLyricsProvider)
+}
+
 func (m *ExtensionManifest) IsDomainAllowed(domain string) bool {
 	domain = strings.ToLower(strings.TrimSpace(domain))
 	for _, allowed := range m.Permissions.Network {

go_backend/extension_providers_test.go

@@ -0,0 +1,252 @@
+package gobackend
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestSetMetadataProviderPriorityAddsBuiltIns(t *testing.T) {
+	original := GetMetadataProviderPriority()
+	defer SetMetadataProviderPriority(original)
+
+	SetMetadataProviderPriority([]string{"tidal"})
+	got := GetMetadataProviderPriority()
+	want := []string{"tidal", "qobuz"}
+	if len(got) != len(want) {
+		t.Fatalf("unexpected priority length: got %v want %v", got, want)
+	}
+	for i := range want {
+		if got[i] != want[i] {
+			t.Fatalf("unexpected priority at %d: got %v want %v", i, got, want)
+		}
+	}
+}
+
+func TestSetExtensionFallbackProviderIDsSkipsBuiltInsAndDuplicates(t *testing.T) {
+	original := GetExtensionFallbackProviderIDs()
+	defer SetExtensionFallbackProviderIDs(original)
+
+	SetExtensionFallbackProviderIDs([]string{"ext-a", "tidal", "ext-a", " ext-b "})
+
+	got := GetExtensionFallbackProviderIDs()
+	want := []string{"ext-a", "ext-b"}
+	if len(got) != len(want) {
+		t.Fatalf("unexpected fallback provider length: got %v want %v", got, want)
+	}
+	for i := range want {
+		if got[i] != want[i] {
+			t.Fatalf("unexpected fallback provider at %d: got %v want %v", i, got, want)
+		}
+	}
+}
+
+func TestIsExtensionFallbackAllowedDefaultsToAllExtensions(t *testing.T) {
+	original := GetExtensionFallbackProviderIDs()
+	defer SetExtensionFallbackProviderIDs(original)
+
+	SetExtensionFallbackProviderIDs(nil)
+
+	if !isExtensionFallbackAllowed("custom-ext") {
+		t.Fatal("expected custom extension to be allowed when no fallback allowlist is configured")
+	}
+	if !isExtensionFallbackAllowed("qobuz") {
+		t.Fatal("expected built-in provider to remain allowed")
+	}
+}
+
+func TestIsExtensionFallbackAllowedRespectsAllowlist(t *testing.T) {
+	original := GetExtensionFallbackProviderIDs()
+	defer SetExtensionFallbackProviderIDs(original)
+
+	SetExtensionFallbackProviderIDs([]string{"allowed-ext"})
+
+	if !isExtensionFallbackAllowed("allowed-ext") {
+		t.Fatal("expected explicitly allowed extension to be permitted")
+	}
+	if isExtensionFallbackAllowed("blocked-ext") {
+		t.Fatal("expected extension outside allowlist to be blocked")
+	}
+	if isExtensionFallbackAllowed("deezer") {
+		t.Fatal("expected retired Deezer downloader to respect extension fallback allowlist")
+	}
+}
+
+func TestSetProviderPriorityRemovesRetiredDeezerDownloader(t *testing.T) {
+	original := GetProviderPriority()
+	defer SetProviderPriority(original)
+
+	SetProviderPriority([]string{"deezer", "qobuz", "custom-ext"})
+
+	got := GetProviderPriority()
+	want := []string{"qobuz", "custom-ext", "tidal"}
+	if len(got) != len(want) {
+		t.Fatalf("unexpected priority length: got %v want %v", got, want)
+	}
+	for i := range want {
+		if got[i] != want[i] {
+			t.Fatalf("unexpected priority at %d: got %v want %v", i, got, want)
+		}
+	}
+}
+
+func TestNormalizeDownloadDecryptionInfoPromotesLegacyKey(t *testing.T) {
+	normalized := normalizeDownloadDecryptionInfo(nil, " 001122 ")
+	if normalized == nil {
+		t.Fatal("expected legacy decryption key to produce normalized descriptor")
+	}
+	if normalized.Strategy != genericFFmpegMOVDecryptionStrategy {
+		t.Fatalf("strategy = %q", normalized.Strategy)
+	}
+	if normalized.Key != "001122" {
+		t.Fatalf("key = %q", normalized.Key)
+	}
+	if normalized.InputFormat != "mov" {
+		t.Fatalf("input format = %q", normalized.InputFormat)
+	}
+}
+
+func TestNormalizeDownloadDecryptionInfoCanonicalizesMovAliases(t *testing.T) {
+	normalized := normalizeDownloadDecryptionInfo(&DownloadDecryptionInfo{
+		Strategy:    "mp4_decryption_key",
+		Key:         "abcd",
+		InputFormat: "",
+	}, "")
+	if normalized == nil {
+		t.Fatal("expected descriptor to remain available")
+	}
+	if normalized.Strategy != genericFFmpegMOVDecryptionStrategy {
+		t.Fatalf("strategy = %q", normalized.Strategy)
+	}
+	if normalized.InputFormat != "mov" {
+		t.Fatalf("input format = %q", normalized.InputFormat)
+	}
+}
+
+func TestBuildOutputPathAddsExplicitOutputDirToAllowedDirs(t *testing.T) {
+	SetAllowedDownloadDirs(nil)
+
+	outputDir := t.TempDir()
+	outputPath := buildOutputPath(DownloadRequest{
+		TrackName:      "Song",
+		ArtistName:     "Artist",
+		OutputDir:      outputDir,
+		OutputExt:      ".flac",
+		FilenameFormat: "",
+	})
+
+	if !isPathInAllowedDirs(outputPath) {
+		t.Fatalf("expected output path %q to be allowed", outputPath)
+	}
+}
+
+func TestBuildOutputPathForExtensionAddsExplicitOutputPathDirToAllowedDirs(t *testing.T) {
+	SetAllowedDownloadDirs(nil)
+
+	outputDir := t.TempDir()
+	outputPath := filepath.Join(outputDir, "custom.flac")
+	ext := &loadedExtension{DataDir: t.TempDir()}
+
+	resolved := buildOutputPathForExtension(DownloadRequest{
+		OutputPath: outputPath,
+	}, ext)
+
+	if resolved != outputPath {
+		t.Fatalf("resolved output path = %q", resolved)
+	}
+	if !isPathInAllowedDirs(outputPath) {
+		t.Fatalf("expected output path %q to be allowed", outputPath)
+	}
+}
+
+func TestBuildOutputPathForExtensionUsesTempDirForFDOutput(t *testing.T) {
+	SetAllowedDownloadDirs(nil)
+
+	ext := &loadedExtension{DataDir: t.TempDir()}
+	resolved := buildOutputPathForExtension(DownloadRequest{
+		TrackName:  "Song",
+		ArtistName: "Artist",
+		OutputDir:  filepath.Join("Artist", "Album"),
+		OutputFD:   123,
+		OutputExt:  ".flac",
+	}, ext)
+
+	expectedBase := filepath.Join(ext.DataDir, "downloads")
+	if !isPathWithinBase(expectedBase, resolved) {
+		t.Fatalf("expected SAF extension output under %q, got %q", expectedBase, resolved)
+	}
+	if !isPathInAllowedDirs(resolved) {
+		t.Fatalf("expected resolved output path %q to be allowed", resolved)
+	}
+}
+
+func TestCanEmbedGenreLabelRequiresExistingAbsoluteLocalFile(t *testing.T) {
+	tempFile := filepath.Join(t.TempDir(), "track.flac")
+	if err := os.WriteFile(tempFile, []byte("fLaC"), 0644); err != nil {
+		t.Fatalf("failed to create temp file: %v", err)
+	}
+	tempM4A := filepath.Join(t.TempDir(), "track.m4a")
+	if err := os.WriteFile(tempM4A, []byte("not-flac"), 0644); err != nil {
+		t.Fatalf("failed to create temp m4a file: %v", err)
+	}
+
+	if canEmbedGenreLabel("relative.flac") {
+		t.Fatal("expected relative path to be rejected")
+	}
+	if canEmbedGenreLabel("content://example") {
+		t.Fatal("expected content URI to be rejected")
+	}
+	if canEmbedGenreLabel(filepath.Join(t.TempDir(), "missing.flac")) {
+		t.Fatal("expected missing file to be rejected")
+	}
+	if canEmbedGenreLabel(tempM4A) {
+		t.Fatalf("expected non-FLAC file %q to be rejected", tempM4A)
+	}
+	if !canEmbedGenreLabel(tempFile) {
+		t.Fatalf("expected existing absolute file %q to be accepted", tempFile)
+	}
+}
+
+func TestSearchTracksWithMetadataProvidersUsesPriorityAndDedupes(t *testing.T) {
+	originalPriority := GetMetadataProviderPriority()
+	originalSearch := searchBuiltInMetadataTracksFunc
+	defer func() {
+		SetMetadataProviderPriority(originalPriority)
+		searchBuiltInMetadataTracksFunc = originalSearch
+	}()
+
+	SetMetadataProviderPriority([]string{"qobuz", "tidal"})
+
+	var calls []string
+	searchBuiltInMetadataTracksFunc = func(providerID, query string, limit int) ([]ExtTrackMetadata, error) {
+		calls = append(calls, providerID)
+		switch providerID {
+		case "qobuz":
+			return []ExtTrackMetadata{
+				{ProviderID: "qobuz", SpotifyID: "qobuz:1", ISRC: "AAA111", Name: "First"},
+			}, nil
+		case "tidal":
+			return []ExtTrackMetadata{
+				{ProviderID: "tidal", SpotifyID: "tidal:2", ISRC: "AAA111", Name: "Duplicate"},
+				{ProviderID: "tidal", SpotifyID: "tidal:3", ISRC: "BBB222", Name: "Second"},
+			}, nil
+		default:
+			return nil, nil
+		}
+	}
+
+	manager := getExtensionManager()
+	tracks, err := manager.SearchTracksWithMetadataProviders("query", 3, false)
+	if err != nil {
+		t.Fatalf("SearchTracksWithMetadataProviders returned error: %v", err)
+	}
+	if len(tracks) != 2 {
+		t.Fatalf("unexpected track count: got %d want 2", len(tracks))
+	}
+	if tracks[0].ProviderID != "qobuz" || tracks[1].ProviderID != "tidal" {
+		t.Fatalf("unexpected track provider order: %+v", tracks)
+	}
+	if len(calls) != 2 || calls[0] != "qobuz" || calls[1] != "tidal" {
+		t.Fatalf("unexpected provider call order: %v", calls)
+	}
+}

go_backend/extension_runtime.go

@@ -5,6 +5,7 @@ import (
 	"net"
 	"net/http"
 	"net/url"
+	"strconv"
 	"strings"
 	"sync"
 	"time"
@@ -80,61 +81,184 @@ func SetExtensionTokens(extensionID string, accessToken, refreshToken string, ex
 	state.IsAuthenticated = accessToken != ""
 }
 
-type ExtensionRuntime struct {
-	extensionID string
-	manifest    *ExtensionManifest
-	settings    map[string]interface{}
-	httpClient  *http.Client
-	cookieJar   http.CookieJar
-	dataDir     string
-	vm          *goja.Runtime
+type extensionRuntime struct {
+	extensionID    string
+	manifest       *ExtensionManifest
+	settings       map[string]interface{}
+	httpClient     *http.Client
+	downloadClient *http.Client
+	cookieJar      http.CookieJar
+	dataDir        string
+	vm             *goja.Runtime
+
+	activeDownloadMu     sync.RWMutex
+	activeDownloadItemID string
+
+	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
 }
 
-func NewExtensionRuntime(ext *LoadedExtension) *ExtensionRuntime {
+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,
+	runtime := &extensionRuntime{
+		extensionID:       ext.ID,
+		manifest:          ext.Manifest,
+		settings:          make(map[string]interface{}),
+		cookieJar:         jar,
+		dataDir:           ext.DataDir,
+		vm:                ext.VM,
+		storageFlushDelay: defaultStorageFlushDelay,
 	}
 
-	client := &http.Client{
-		Timeout: 30 * time.Second,
-		Jar:     jar,
-		CheckRedirect: func(req *http.Request, via []*http.Request) error {
-			if req.URL.Scheme != "https" {
-				GoLog("[Extension:%s] Redirect blocked: non-https scheme '%s'\n", ext.ID, req.URL.Scheme)
-				return fmt.Errorf("redirect blocked: only https is allowed")
-			}
-
-			domain := req.URL.Hostname()
-			if domain == "" {
-				GoLog("[Extension:%s] Redirect blocked: missing hostname\n", ext.ID)
-				return fmt.Errorf("redirect blocked: hostname is required")
-			}
-			if !ext.Manifest.IsDomainAllowed(domain) {
-				GoLog("[Extension:%s] Redirect blocked: domain '%s' not in allowed list\n", ext.ID, domain)
-				return &RedirectBlockedError{Domain: domain}
-			}
-			if isPrivateIP(domain) {
-				GoLog("[Extension:%s] Redirect blocked: private IP '%s'\n", ext.ID, domain)
-				return &RedirectBlockedError{Domain: domain, IsPrivate: true}
-			}
-			if len(via) >= 10 {
-				return http.ErrUseLastResponse
-			}
-			return nil
-		},
-	}
-	runtime.httpClient = client
+	runtime.httpClient = newExtensionHTTPClient(ext, jar, extensionHTTPTimeout(ext, 30*time.Second))
+	runtime.downloadClient = newExtensionHTTPClient(ext, jar, DownloadTimeout)
 
 	return runtime
 }
 
+func extensionHTTPTimeout(ext *loadedExtension, fallback time.Duration) time.Duration {
+	if ext == nil || ext.Manifest == nil || ext.Manifest.Capabilities == nil {
+		return fallback
+	}
+
+	raw, ok := ext.Manifest.Capabilities["networkTimeoutSeconds"]
+	if !ok {
+		return fallback
+	}
+
+	seconds := parseExtensionTimeoutSeconds(raw)
+	if seconds <= 0 {
+		return fallback
+	}
+
+	if seconds < 5 {
+		seconds = 5
+	}
+	if seconds > 300 {
+		seconds = 300
+	}
+
+	return time.Duration(seconds) * time.Second
+}
+
+func parseExtensionTimeoutSeconds(raw interface{}) int {
+	switch v := raw.(type) {
+	case int:
+		return v
+	case int32:
+		return int(v)
+	case int64:
+		return int(v)
+	case float32:
+		return int(v)
+	case float64:
+		return int(v)
+	case string:
+		parsed, err := strconv.Atoi(strings.TrimSpace(v))
+		if err != nil {
+			return 0
+		}
+		return parsed
+	default:
+		return 0
+	}
+}
+
+func (r *extensionRuntime) setActiveDownloadItemID(itemID string) {
+	r.activeDownloadMu.Lock()
+	defer r.activeDownloadMu.Unlock()
+	r.activeDownloadItemID = strings.TrimSpace(itemID)
+}
+
+func (r *extensionRuntime) clearActiveDownloadItemID() {
+	r.activeDownloadMu.Lock()
+	defer r.activeDownloadMu.Unlock()
+	r.activeDownloadItemID = ""
+}
+
+func (r *extensionRuntime) getActiveDownloadItemID() string {
+	r.activeDownloadMu.RLock()
+	defer r.activeDownloadMu.RUnlock()
+	return r.activeDownloadItemID
+}
+
+func (r *extensionRuntime) bindDownloadCancelContext(req *http.Request) *http.Request {
+	if req == nil {
+		return nil
+	}
+
+	itemID := r.getActiveDownloadItemID()
+	if itemID == "" {
+		return req
+	}
+
+	return req.WithContext(initDownloadCancel(itemID))
+}
+
+func newExtensionHTTPClient(ext *loadedExtension, jar http.CookieJar, timeout time.Duration) *http.Client {
+	// Extension sandbox enforces HTTPS-only domains. Do not apply global
+	// allow_http scheme downgrade here, because some extension APIs (e.g.
+	// spotify-web) will redirect http -> https and can end up in 301 loops.
+	// We still reuse sharedTransport so insecure TLS compatibility mode remains effective.
+	client := &http.Client{
+		Transport: sharedTransport,
+		Timeout:   timeout,
+		Jar:       jar,
+	}
+	client.CheckRedirect = func(req *http.Request, via []*http.Request) error {
+		if req.URL.Scheme != "https" {
+			GoLog("[Extension:%s] Redirect blocked: non-https scheme '%s'\n", ext.ID, req.URL.Scheme)
+			return fmt.Errorf("redirect blocked: only https is allowed")
+		}
+
+		domain := req.URL.Hostname()
+		if domain == "" {
+			GoLog("[Extension:%s] Redirect blocked: missing hostname\n", ext.ID)
+			return fmt.Errorf("redirect blocked: hostname is required")
+		}
+		if !ext.Manifest.IsDomainAllowed(domain) {
+			GoLog("[Extension:%s] Redirect blocked: domain '%s' not in allowed list\n", ext.ID, domain)
+			return &RedirectBlockedError{Domain: domain}
+		}
+		if isPrivateIP(domain) {
+			GoLog("[Extension:%s] Redirect blocked: private IP '%s'\n", ext.ID, domain)
+			return &RedirectBlockedError{Domain: domain, IsPrivate: true}
+		}
+		if len(via) >= 10 {
+			return http.ErrUseLastResponse
+		}
+		return nil
+	}
+	return client
+}
+
 type RedirectBlockedError struct {
 	Domain    string
 	IsPrivate bool
@@ -147,7 +271,6 @@ func (e *RedirectBlockedError) Error() string {
 	return "redirect blocked: domain '" + e.Domain + "' not in allowed list"
 }
 
-// isPrivateIP checks if a hostname resolves to a private/local IP address
 func isPrivateIP(host string) bool {
 	hostLower := strings.ToLower(strings.TrimSpace(host))
 	if hostLower == "" {
@@ -162,18 +285,68 @@ func isPrivateIP(host string) bool {
 		return isPrivateIPAddr(ip)
 	}
 
+	if cached, ok := getPrivateIPCache(hostLower); ok {
+		return cached
+	}
+
 	ips, err := net.LookupIP(hostLower)
 	if err != nil {
+		setPrivateIPCache(hostLower, false, privateIPErrorCacheTTL)
 		return false
 	}
 
+	isPrivate := false
 	for _, ip := range ips {
 		if isPrivateIPAddr(ip) {
-			return true
+			isPrivate = true
+			break
 		}
 	}
 
-	return false
+	setPrivateIPCache(hostLower, isPrivate, privateIPCacheTTL)
+	return isPrivate
+}
+
+func getPrivateIPCache(host string) (bool, bool) {
+	now := time.Now()
+
+	privateIPCacheMu.RLock()
+	entry, exists := privateIPCache[host]
+	privateIPCacheMu.RUnlock()
+	if !exists {
+		return false, false
+	}
+
+	if now.Before(entry.expiresAt) {
+		return entry.isPrivate, true
+	}
+
+	privateIPCacheMu.Lock()
+	delete(privateIPCache, host)
+	privateIPCacheMu.Unlock()
+	return false, false
+}
+
+func setPrivateIPCache(host string, isPrivate bool, ttl time.Duration) {
+	expiresAt := time.Now().Add(ttl)
+
+	privateIPCacheMu.Lock()
+	if len(privateIPCache) >= maxPrivateIPCacheSize {
+		now := time.Now()
+		for key, entry := range privateIPCache {
+			if now.After(entry.expiresAt) {
+				delete(privateIPCache, key)
+			}
+		}
+		if len(privateIPCache) >= maxPrivateIPCacheSize {
+			privateIPCache = make(map[string]privateIPCacheEntry)
+		}
+	}
+	privateIPCache[host] = privateIPCacheEntry{
+		isPrivate: isPrivate,
+		expiresAt: expiresAt,
+	}
+	privateIPCacheMu.Unlock()
 }
 
 func isPrivateIPAddr(ip net.IP) bool {
@@ -218,11 +391,11 @@ func (j *simpleCookieJar) Cookies(u *url.URL) []*http.Cookie {
 	return j.cookies[u.Host]
 }
 
-func (r *ExtensionRuntime) SetSettings(settings map[string]interface{}) {
+func (r *extensionRuntime) SetSettings(settings map[string]interface{}) {
 	r.settings = settings
 }
 
-func (r *ExtensionRuntime) RegisterAPIs(vm *goja.Runtime) {
+func (r *extensionRuntime) RegisterAPIs(vm *goja.Runtime) {
 	r.vm = vm
 
 	httpObj := vm.NewObject()
@@ -266,7 +439,9 @@ func (r *ExtensionRuntime) RegisterAPIs(vm *goja.Runtime) {
 	fileObj.Set("exists", r.fileExists)
 	fileObj.Set("delete", r.fileDelete)
 	fileObj.Set("read", r.fileRead)
+	fileObj.Set("readBytes", r.fileReadBytes)
 	fileObj.Set("write", r.fileWrite)
+	fileObj.Set("writeBytes", r.fileWriteBytes)
 	fileObj.Set("copy", r.fileCopy)
 	fileObj.Set("move", r.fileMove)
 	fileObj.Set("getSize", r.fileGetSize)
@@ -296,8 +471,14 @@ func (r *ExtensionRuntime) RegisterAPIs(vm *goja.Runtime) {
 	utilsObj.Set("stringifyJSON", r.stringifyJSON)
 	utilsObj.Set("encrypt", r.cryptoEncrypt)
 	utilsObj.Set("decrypt", r.cryptoDecrypt)
+	utilsObj.Set("encryptBlockCipher", r.encryptBlockCipher)
+	utilsObj.Set("decryptBlockCipher", r.decryptBlockCipher)
 	utilsObj.Set("generateKey", r.cryptoGenerateKey)
 	utilsObj.Set("randomUserAgent", r.randomUserAgent)
+	utilsObj.Set("appVersion", r.appVersion)
+	utilsObj.Set("appUserAgent", r.appUserAgent)
+	utilsObj.Set("sleep", r.sleep)
+	utilsObj.Set("isDownloadCancelled", r.isDownloadCancelled)
 	vm.Set("utils", utilsObj)
 
 	logObj := vm.NewObject()

go_backend/extension_runtime_auth.go

@@ -1,4 +1,3 @@
-// Package gobackend provides Auth API and PKCE support for extension runtime
 package gobackend
 
 import (
@@ -16,9 +15,44 @@ import (
 	"github.com/dop251/goja"
 )
 
-// ==================== Auth API (OAuth Support) ====================
+func validateExtensionAuthURL(urlStr string) error {
+	parsed, err := url.Parse(urlStr)
+	if err != nil {
+		return fmt.Errorf("invalid auth URL: %w", err)
+	}
 
-func (r *ExtensionRuntime) authOpenUrl(call goja.FunctionCall) goja.Value {
+	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{}{
 			"success": false,
@@ -32,6 +66,13 @@ func (r *ExtensionRuntime) authOpenUrl(call goja.FunctionCall) goja.Value {
 		callbackURL = call.Arguments[1].String()
 	}
 
+	if err := validateExtensionAuthURL(authURL); err != nil {
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   err.Error(),
+		})
+	}
+
 	pendingAuthRequestsMu.Lock()
 	pendingAuthRequests[r.extensionID] = &PendingAuthRequest{
 		ExtensionID: r.extensionID,
@@ -50,7 +91,7 @@ func (r *ExtensionRuntime) authOpenUrl(call goja.FunctionCall) goja.Value {
 	state.AuthCode = ""
 	extensionAuthStateMu.Unlock()
 
-	GoLog("[Extension:%s] Auth URL requested: %s\n", r.extensionID, authURL)
+	GoLog("[Extension:%s] Auth URL requested: %s\n", r.extensionID, summarizeURLForLog(authURL))
 
 	return r.vm.ToValue(map[string]interface{}{
 		"success": true,
@@ -58,7 +99,7 @@ func (r *ExtensionRuntime) authOpenUrl(call goja.FunctionCall) goja.Value {
 	})
 }
 
-func (r *ExtensionRuntime) authGetCode(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) authGetCode(call goja.FunctionCall) goja.Value {
 	extensionAuthStateMu.RLock()
 	defer extensionAuthStateMu.RUnlock()
 
@@ -70,7 +111,7 @@ func (r *ExtensionRuntime) authGetCode(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(state.AuthCode)
 }
 
-func (r *ExtensionRuntime) authSetCode(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) authSetCode(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue(false)
 	}
@@ -108,7 +149,7 @@ func (r *ExtensionRuntime) authSetCode(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(true)
 }
 
-func (r *ExtensionRuntime) authClear(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) authClear(call goja.FunctionCall) goja.Value {
 	extensionAuthStateMu.Lock()
 	delete(extensionAuthState, r.extensionID)
 	extensionAuthStateMu.Unlock()
@@ -121,7 +162,7 @@ func (r *ExtensionRuntime) authClear(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(true)
 }
 
-func (r *ExtensionRuntime) authIsAuthenticated(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) authIsAuthenticated(call goja.FunctionCall) goja.Value {
 	extensionAuthStateMu.RLock()
 	defer extensionAuthStateMu.RUnlock()
 
@@ -137,7 +178,7 @@ func (r *ExtensionRuntime) authIsAuthenticated(call goja.FunctionCall) goja.Valu
 	return r.vm.ToValue(state.IsAuthenticated)
 }
 
-func (r *ExtensionRuntime) authGetTokens(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) authGetTokens(call goja.FunctionCall) goja.Value {
 	extensionAuthStateMu.RLock()
 	defer extensionAuthStateMu.RUnlock()
 
@@ -160,10 +201,6 @@ func (r *ExtensionRuntime) authGetTokens(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(result)
 }
 
-// ==================== PKCE Support ====================
-
-// generatePKCEVerifier generates a cryptographically random code verifier
-// Length should be between 43-128 characters (RFC 7636)
 func generatePKCEVerifier(length int) (string, error) {
 	if length < 43 {
 		length = 43
@@ -188,11 +225,10 @@ func generatePKCEVerifier(length int) (string, error) {
 
 func generatePKCEChallenge(verifier string) string {
 	hash := sha256.Sum256([]byte(verifier))
-	// Base64url encode without padding (RFC 7636)
 	return base64.RawURLEncoding.EncodeToString(hash[:])
 }
 
-func (r *ExtensionRuntime) authGeneratePKCE(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) authGeneratePKCE(call goja.FunctionCall) goja.Value {
 	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 {
@@ -229,7 +265,7 @@ func (r *ExtensionRuntime) authGeneratePKCE(call goja.FunctionCall) goja.Value {
 	})
 }
 
-func (r *ExtensionRuntime) authGetPKCE(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) authGetPKCE(call goja.FunctionCall) goja.Value {
 	extensionAuthStateMu.RLock()
 	defer extensionAuthStateMu.RUnlock()
 
@@ -245,8 +281,7 @@ func (r *ExtensionRuntime) authGetPKCE(call goja.FunctionCall) goja.Value {
 	})
 }
 
-// config: { authUrl, clientId, redirectUri, scope, extraParams }
-func (r *ExtensionRuntime) authStartOAuthWithPKCE(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) authStartOAuthWithPKCE(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue(map[string]interface{}{
 			"success": false,
@@ -273,6 +308,12 @@ func (r *ExtensionRuntime) authStartOAuthWithPKCE(call goja.FunctionCall) goja.V
 			"error":   "authUrl, clientId, and redirectUri are required",
 		})
 	}
+	if err := validateExtensionAuthURL(authURL); err != nil {
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   err.Error(),
+		})
+	}
 
 	scope, _ := config["scope"].(string)
 	extraParams, _ := config["extraParams"].(map[string]interface{})
@@ -331,7 +372,7 @@ func (r *ExtensionRuntime) authStartOAuthWithPKCE(call goja.FunctionCall) goja.V
 	}
 	pendingAuthRequestsMu.Unlock()
 
-	GoLog("[Extension:%s] PKCE OAuth started: %s\n", r.extensionID, fullAuthURL)
+	GoLog("[Extension:%s] PKCE OAuth started: %s\n", r.extensionID, summarizeURLForLog(fullAuthURL))
 
 	return r.vm.ToValue(map[string]interface{}{
 		"success": true,
@@ -344,10 +385,7 @@ func (r *ExtensionRuntime) authStartOAuthWithPKCE(call goja.FunctionCall) goja.V
 	})
 }
 
-// authExchangeCodeWithPKCE exchanges auth code for tokens using PKCE
-// config: { tokenUrl, clientId, redirectUri, code, extraParams }
-// Uses the stored PKCE verifier automatically
-func (r *ExtensionRuntime) authExchangeCodeWithPKCE(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) authExchangeCodeWithPKCE(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue(map[string]interface{}{
 			"success": false,
@@ -364,7 +402,6 @@ func (r *ExtensionRuntime) authExchangeCodeWithPKCE(call goja.FunctionCall) goja
 		})
 	}
 
-	// Required fields
 	tokenURL, _ := config["tokenUrl"].(string)
 	clientID, _ := config["clientId"].(string)
 	redirectURI, _ := config["redirectUri"].(string)
@@ -421,6 +458,7 @@ func (r *ExtensionRuntime) authExchangeCodeWithPKCE(call goja.FunctionCall) goja
 			"error":   err.Error(),
 		})
 	}
+	req = r.bindDownloadCancelContext(req)
 
 	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
 	req.Header.Set("User-Agent", "SpotiFLAC-Extension/1.0")
@@ -441,13 +479,17 @@ func (r *ExtensionRuntime) authExchangeCodeWithPKCE(call goja.FunctionCall) goja
 			"error":   err.Error(),
 		})
 	}
+	bodyPreview := sanitizeSensitiveLogText(string(body))
+	if len(bodyPreview) > 1000 {
+		bodyPreview = bodyPreview[:1000] + "...[truncated]"
+	}
 
 	var tokenResp map[string]interface{}
 	if err := json.Unmarshal(body, &tokenResp); err != nil {
 		return r.vm.ToValue(map[string]interface{}{
 			"success": false,
 			"error":   fmt.Sprintf("failed to parse token response: %v", err),
-			"body":    string(body),
+			"body":    bodyPreview,
 		})
 	}
 
@@ -468,7 +510,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,
 		})
 	}
 

go_backend/extension_runtime_binary.go

@@ -0,0 +1,359 @@
+package gobackend
+
+import (
+	"crypto/aes"
+	"crypto/cipher"
+	"encoding/base64"
+	"encoding/hex"
+	"fmt"
+	"strings"
+
+	"github.com/dop251/goja"
+	"golang.org/x/crypto/blowfish"
+)
+
+type runtimeBlockCipherOptions struct {
+	Algorithm      string
+	Mode           string
+	Key            []byte
+	IV             []byte
+	InputEncoding  string
+	OutputEncoding string
+	Padding        string
+}
+
+func parseRuntimeOptionsArgument(call goja.FunctionCall, index int) map[string]interface{} {
+	if len(call.Arguments) <= index {
+		return nil
+	}
+
+	value := call.Arguments[index]
+	if goja.IsUndefined(value) || goja.IsNull(value) {
+		return nil
+	}
+
+	exported := value.Export()
+	if options, ok := exported.(map[string]interface{}); ok {
+		return options
+	}
+	return nil
+}
+
+func runtimeOptionString(options map[string]interface{}, key, defaultValue string) string {
+	if options == nil {
+		return defaultValue
+	}
+	raw, ok := options[key]
+	if !ok || raw == nil {
+		return defaultValue
+	}
+	switch value := raw.(type) {
+	case string:
+		if trimmed := strings.TrimSpace(value); trimmed != "" {
+			return trimmed
+		}
+	case []byte:
+		if len(value) > 0 {
+			return string(value)
+		}
+	}
+	return defaultValue
+}
+
+func runtimeOptionBool(options map[string]interface{}, key string, defaultValue bool) bool {
+	if options == nil {
+		return defaultValue
+	}
+	raw, ok := options[key]
+	if !ok || raw == nil {
+		return defaultValue
+	}
+	switch value := raw.(type) {
+	case bool:
+		return value
+	case int:
+		return value != 0
+	case int64:
+		return value != 0
+	case float64:
+		return value != 0
+	case string:
+		switch strings.ToLower(strings.TrimSpace(value)) {
+		case "1", "true", "yes", "on":
+			return true
+		case "0", "false", "no", "off":
+			return false
+		}
+	}
+	return defaultValue
+}
+
+func runtimeOptionInt64(options map[string]interface{}, key string, defaultValue int64) int64 {
+	if options == nil {
+		return defaultValue
+	}
+	raw, ok := options[key]
+	if !ok || raw == nil {
+		return defaultValue
+	}
+	switch value := raw.(type) {
+	case int:
+		return int64(value)
+	case int32:
+		return int64(value)
+	case int64:
+		return value
+	case float32:
+		return int64(value)
+	case float64:
+		return int64(value)
+	case string:
+		value = strings.TrimSpace(value)
+		if value == "" {
+			return defaultValue
+		}
+		var parsed int64
+		if _, err := fmt.Sscanf(value, "%d", &parsed); err == nil {
+			return parsed
+		}
+	}
+	return defaultValue
+}
+
+func runtimeOptionHasKey(options map[string]interface{}, key string) bool {
+	if options == nil {
+		return false
+	}
+	_, exists := options[key]
+	return exists
+}
+
+func decodeRuntimeBytesString(input, encoding string) ([]byte, error) {
+	switch strings.ToLower(strings.TrimSpace(encoding)) {
+	case "", "utf8", "utf-8", "text":
+		return []byte(input), nil
+	case "base64":
+		decoded, err := base64.StdEncoding.DecodeString(strings.TrimSpace(input))
+		if err != nil {
+			return nil, fmt.Errorf("invalid base64 data: %w", err)
+		}
+		return decoded, nil
+	case "hex":
+		decoded, err := hex.DecodeString(strings.TrimSpace(input))
+		if err != nil {
+			return nil, fmt.Errorf("invalid hex data: %w", err)
+		}
+		return decoded, nil
+	default:
+		return nil, fmt.Errorf("unsupported byte encoding: %s", encoding)
+	}
+}
+
+func decodeRuntimeBytesValue(raw interface{}, encoding string) ([]byte, error) {
+	switch value := raw.(type) {
+	case string:
+		return decodeRuntimeBytesString(value, encoding)
+	case []byte:
+		cloned := make([]byte, len(value))
+		copy(cloned, value)
+		return cloned, nil
+	case []interface{}:
+		decoded := make([]byte, len(value))
+		for i, item := range value {
+			switch num := item.(type) {
+			case int:
+				decoded[i] = byte(num)
+			case int64:
+				decoded[i] = byte(num)
+			case float64:
+				decoded[i] = byte(int(num))
+			default:
+				return nil, fmt.Errorf("unsupported byte array item at index %d", i)
+			}
+		}
+		return decoded, nil
+	default:
+		return nil, fmt.Errorf("unsupported byte payload type")
+	}
+}
+
+func encodeRuntimeBytes(data []byte, encoding string) (string, error) {
+	switch strings.ToLower(strings.TrimSpace(encoding)) {
+	case "", "base64":
+		return base64.StdEncoding.EncodeToString(data), nil
+	case "hex":
+		return hex.EncodeToString(data), nil
+	case "utf8", "utf-8", "text":
+		return string(data), nil
+	default:
+		return "", fmt.Errorf("unsupported byte encoding: %s", encoding)
+	}
+}
+
+func parseRuntimeBlockCipherOptions(options map[string]interface{}) (*runtimeBlockCipherOptions, error) {
+	parsed := &runtimeBlockCipherOptions{
+		Algorithm:      strings.ToLower(runtimeOptionString(options, "algorithm", "")),
+		Mode:           strings.ToLower(runtimeOptionString(options, "mode", "cbc")),
+		InputEncoding:  strings.ToLower(runtimeOptionString(options, "inputEncoding", "base64")),
+		OutputEncoding: strings.ToLower(runtimeOptionString(options, "outputEncoding", "base64")),
+		Padding:        strings.ToLower(runtimeOptionString(options, "padding", "none")),
+	}
+	if parsed.Algorithm == "" {
+		return nil, fmt.Errorf("algorithm is required")
+	}
+	if parsed.Mode == "" {
+		return nil, fmt.Errorf("mode is required")
+	}
+
+	key, err := decodeRuntimeBytesString(runtimeOptionString(options, "key", ""), runtimeOptionString(options, "keyEncoding", "utf8"))
+	if err != nil {
+		return nil, fmt.Errorf("invalid key: %w", err)
+	}
+	if len(key) == 0 {
+		return nil, fmt.Errorf("key is required")
+	}
+	parsed.Key = key
+
+	iv, err := decodeRuntimeBytesString(runtimeOptionString(options, "iv", ""), runtimeOptionString(options, "ivEncoding", "utf8"))
+	if err != nil {
+		return nil, fmt.Errorf("invalid iv: %w", err)
+	}
+	parsed.IV = iv
+	return parsed, nil
+}
+
+func newRuntimeBlockCipher(options *runtimeBlockCipherOptions) (cipher.Block, error) {
+	switch options.Algorithm {
+	case "blowfish":
+		return blowfish.NewCipher(options.Key)
+	case "aes":
+		return aes.NewCipher(options.Key)
+	default:
+		return nil, fmt.Errorf("unsupported block cipher algorithm: %s", options.Algorithm)
+	}
+}
+
+func applyPKCS7Padding(data []byte, blockSize int) []byte {
+	padding := blockSize - (len(data) % blockSize)
+	if padding == 0 {
+		padding = blockSize
+	}
+	out := make([]byte, len(data)+padding)
+	copy(out, data)
+	for i := len(data); i < len(out); i++ {
+		out[i] = byte(padding)
+	}
+	return out
+}
+
+func removePKCS7Padding(data []byte, blockSize int) ([]byte, error) {
+	if len(data) == 0 || len(data)%blockSize != 0 {
+		return nil, fmt.Errorf("invalid padded payload length")
+	}
+	padding := int(data[len(data)-1])
+	if padding <= 0 || padding > blockSize || padding > len(data) {
+		return nil, fmt.Errorf("invalid PKCS7 padding")
+	}
+	for i := len(data) - padding; i < len(data); i++ {
+		if int(data[i]) != padding {
+			return nil, fmt.Errorf("invalid PKCS7 padding")
+		}
+	}
+	return data[:len(data)-padding], nil
+}
+
+func (r *extensionRuntime) transformBlockCipher(call goja.FunctionCall, decrypt bool) goja.Value {
+	if len(call.Arguments) < 2 {
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   "data and options are required",
+		})
+	}
+
+	options := parseRuntimeOptionsArgument(call, 1)
+	parsedOptions, err := parseRuntimeBlockCipherOptions(options)
+	if err != nil {
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   err.Error(),
+		})
+	}
+	if parsedOptions.Mode != "cbc" {
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   fmt.Sprintf("unsupported block cipher mode: %s", parsedOptions.Mode),
+		})
+	}
+
+	inputData, err := decodeRuntimeBytesValue(call.Arguments[0].Export(), parsedOptions.InputEncoding)
+	if err != nil {
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   err.Error(),
+		})
+	}
+
+	block, err := newRuntimeBlockCipher(parsedOptions)
+	if err != nil {
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   err.Error(),
+		})
+	}
+
+	if len(parsedOptions.IV) != block.BlockSize() {
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   fmt.Sprintf("iv must be %d bytes for %s", block.BlockSize(), parsedOptions.Algorithm),
+		})
+	}
+
+	data := inputData
+	if !decrypt && parsedOptions.Padding == "pkcs7" {
+		data = applyPKCS7Padding(data, block.BlockSize())
+	}
+	if len(data)%block.BlockSize() != 0 {
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   fmt.Sprintf("input length must be a multiple of %d bytes", block.BlockSize()),
+		})
+	}
+
+	output := make([]byte, len(data))
+	if decrypt {
+		cipher.NewCBCDecrypter(block, parsedOptions.IV).CryptBlocks(output, data)
+		if parsedOptions.Padding == "pkcs7" {
+			output, err = removePKCS7Padding(output, block.BlockSize())
+			if err != nil {
+				return r.vm.ToValue(map[string]interface{}{
+					"success": false,
+					"error":   err.Error(),
+				})
+			}
+		}
+	} else {
+		cipher.NewCBCEncrypter(block, parsedOptions.IV).CryptBlocks(output, data)
+	}
+
+	encoded, err := encodeRuntimeBytes(output, parsedOptions.OutputEncoding)
+	if err != nil {
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   err.Error(),
+		})
+	}
+
+	return r.vm.ToValue(map[string]interface{}{
+		"success":    true,
+		"data":       encoded,
+		"block_size": block.BlockSize(),
+	})
+}
+
+func (r *extensionRuntime) encryptBlockCipher(call goja.FunctionCall) goja.Value {
+	return r.transformBlockCipher(call, false)
+}
+
+func (r *extensionRuntime) decryptBlockCipher(call goja.FunctionCall) goja.Value {
+	return r.transformBlockCipher(call, true)
+}

go_backend/extension_runtime_binary_test.go

@@ -0,0 +1,185 @@
+package gobackend
+
+import (
+	"encoding/json"
+	"testing"
+
+	"github.com/dop251/goja"
+)
+
+func newBinaryTestRuntime(t *testing.T, withFilePermission bool) *goja.Runtime {
+	t.Helper()
+
+	ext := &loadedExtension{
+		ID: "binary-test-ext",
+		Manifest: &ExtensionManifest{
+			Name: "binary-test-ext",
+			Permissions: ExtensionPermissions{
+				File: withFilePermission,
+			},
+		},
+		DataDir: t.TempDir(),
+	}
+
+	runtime := newExtensionRuntime(ext)
+	vm := goja.New()
+	runtime.RegisterAPIs(vm)
+	return vm
+}
+
+func decodeJSONResult[T any](t *testing.T, value goja.Value) T {
+	t.Helper()
+
+	var decoded T
+	if err := json.Unmarshal([]byte(value.String()), &decoded); err != nil {
+		t.Fatalf("failed to decode JSON result: %v", err)
+	}
+	return decoded
+}
+
+func TestExtensionRuntime_FileByteAPIs(t *testing.T) {
+	vm := newBinaryTestRuntime(t, true)
+
+	result, err := vm.RunString(`
+		(function() {
+			var first = file.writeBytes("bytes.bin", "AAEC", {encoding: "base64", truncate: true});
+			if (!first.success) throw new Error(first.error);
+
+			var second = file.writeBytes("bytes.bin", "0304ff", {encoding: "hex", append: true});
+			if (!second.success) throw new Error(second.error);
+
+			var all = file.readBytes("bytes.bin", {encoding: "hex"});
+			if (!all.success) throw new Error(all.error);
+
+			var slice = file.readBytes("bytes.bin", {offset: 2, length: 2, encoding: "hex"});
+			if (!slice.success) throw new Error(slice.error);
+
+			var tail = file.readBytes("bytes.bin", {offset: 6, length: 4, encoding: "hex"});
+			if (!tail.success) throw new Error(tail.error);
+
+			return JSON.stringify({
+				all: all.data,
+				slice: slice.data,
+				size: all.size,
+				sliceBytes: slice.bytes_read,
+				sliceEof: slice.eof,
+				tailBytes: tail.bytes_read,
+				tailEof: tail.eof
+			});
+		})()
+	`)
+	if err != nil {
+		t.Fatalf("file byte APIs failed: %v", err)
+	}
+
+	decoded := decodeJSONResult[struct {
+		All        string `json:"all"`
+		Slice      string `json:"slice"`
+		Size       int64  `json:"size"`
+		SliceBytes int    `json:"sliceBytes"`
+		SliceEof   bool   `json:"sliceEof"`
+		TailBytes  int    `json:"tailBytes"`
+		TailEof    bool   `json:"tailEof"`
+	}](t, result)
+
+	if decoded.All != "0001020304ff" {
+		t.Fatalf("all = %q", decoded.All)
+	}
+	if decoded.Slice != "0203" {
+		t.Fatalf("slice = %q", decoded.Slice)
+	}
+	if decoded.Size != 6 {
+		t.Fatalf("size = %d", decoded.Size)
+	}
+	if decoded.SliceBytes != 2 {
+		t.Fatalf("slice bytes = %d", decoded.SliceBytes)
+	}
+	if decoded.SliceEof {
+		t.Fatal("slice should not be EOF")
+	}
+	if decoded.TailBytes != 0 || !decoded.TailEof {
+		t.Fatalf("tail read mismatch: bytes=%d eof=%v", decoded.TailBytes, decoded.TailEof)
+	}
+}
+
+func TestExtensionRuntime_BlockCipherCBCSupportsBlowfish(t *testing.T) {
+	vm := newBinaryTestRuntime(t, false)
+
+	result, err := vm.RunString(`
+		(function() {
+			var options = {
+				algorithm: "blowfish",
+				mode: "cbc",
+				key: "0123456789ABCDEFF0E1D2C3B4A59687",
+				keyEncoding: "hex",
+				iv: "0001020304050607",
+				ivEncoding: "hex",
+				inputEncoding: "hex",
+				outputEncoding: "hex",
+				padding: "none"
+			};
+			var enc = utils.encryptBlockCipher("00112233445566778899aabbccddeeff", options);
+			if (!enc.success) throw new Error(enc.error);
+			var dec = utils.decryptBlockCipher(enc.data, options);
+			if (!dec.success) throw new Error(dec.error);
+			return JSON.stringify({enc: enc.data, dec: dec.data});
+		})()
+	`)
+	if err != nil {
+		t.Fatalf("blowfish block cipher failed: %v", err)
+	}
+
+	decoded := decodeJSONResult[struct {
+		Enc string `json:"enc"`
+		Dec string `json:"dec"`
+	}](t, result)
+
+	if decoded.Dec != "00112233445566778899aabbccddeeff" {
+		t.Fatalf("dec = %q", decoded.Dec)
+	}
+	if decoded.Enc == decoded.Dec {
+		t.Fatal("expected ciphertext to differ from plaintext")
+	}
+}
+
+func TestExtensionRuntime_BlockCipherCBCSupportsAES(t *testing.T) {
+	vm := newBinaryTestRuntime(t, false)
+
+	result, err := vm.RunString(`
+		(function() {
+			var options = {
+				algorithm: "aes",
+				mode: "cbc",
+				key: "000102030405060708090a0b0c0d0e0f",
+				keyEncoding: "hex",
+				iv: "0f0e0d0c0b0a09080706050403020100",
+				ivEncoding: "hex",
+				inputEncoding: "utf8",
+				outputEncoding: "base64",
+				padding: "pkcs7"
+			};
+			var enc = utils.encryptBlockCipher("hello generic cbc", options);
+			if (!enc.success) throw new Error(enc.error);
+			var dec = utils.decryptBlockCipher(enc.data, {
+				algorithm: "aes",
+				mode: "cbc",
+				key: options.key,
+				keyEncoding: options.keyEncoding,
+				iv: options.iv,
+				ivEncoding: options.ivEncoding,
+				inputEncoding: "base64",
+				outputEncoding: "utf8",
+				padding: "pkcs7"
+			});
+			if (!dec.success) throw new Error(dec.error);
+			return dec.data;
+		})()
+	`)
+	if err != nil {
+		t.Fatalf("aes block cipher failed: %v", err)
+	}
+
+	if result.String() != "hello generic cbc" {
+		t.Fatalf("unexpected decrypted value: %q", result.String())
+	}
+}

go_backend/extension_runtime_ffmpeg.go

@@ -1,4 +1,3 @@
-// Package gobackend provides FFmpeg API for extension runtime
 package gobackend
 
 import (
@@ -10,9 +9,7 @@ import (
 	"github.com/dop251/goja"
 )
 
-// ==================== FFmpeg API (Post-Processing) ====================
-
-// FFmpegCommand holds a pending FFmpeg command for Flutter to execute
+// FFmpegCommand holds a pending FFmpeg command for Flutter to execute.
 type FFmpegCommand struct {
 	ExtensionID string
 	Command     string
@@ -24,7 +21,6 @@ type FFmpegCommand struct {
 	Output      string
 }
 
-// Global FFmpeg command queue
 var (
 	ffmpegCommands   = make(map[string]*FFmpegCommand)
 	ffmpegCommandsMu sync.RWMutex
@@ -54,7 +50,7 @@ func ClearFFmpegCommand(commandID string) {
 	delete(ffmpegCommands, commandID)
 }
 
-func (r *ExtensionRuntime) ffmpegExecute(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) ffmpegExecute(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue(map[string]interface{}{
 			"success": false,
@@ -111,7 +107,7 @@ func (r *ExtensionRuntime) ffmpegExecute(call goja.FunctionCall) goja.Value {
 	}
 }
 
-func (r *ExtensionRuntime) ffmpegGetInfo(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) ffmpegGetInfo(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue(map[string]interface{}{
 			"success": false,
@@ -138,7 +134,7 @@ func (r *ExtensionRuntime) ffmpegGetInfo(call goja.FunctionCall) goja.Value {
 	})
 }
 
-func (r *ExtensionRuntime) ffmpegConvert(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) ffmpegConvert(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 2 {
 		return r.vm.ToValue(map[string]interface{}{
 			"success": false,

go_backend/extension_runtime_file.go

@@ -1,4 +1,3 @@
-// Package gobackend provides File API for extension runtime
 package gobackend
 
 import (
@@ -13,8 +12,6 @@ import (
 	"github.com/dop251/goja"
 )
 
-// ==================== File API (Sandboxed) ====================
-
 var (
 	allowedDownloadDirs   []string
 	allowedDownloadDirsMu sync.RWMutex
@@ -74,7 +71,7 @@ func isPathWithinBase(baseDir, targetPath string) bool {
 	return true
 }
 
-func (r *ExtensionRuntime) validatePath(path string) (string, error) {
+func (r *extensionRuntime) validatePath(path string) (string, error) {
 	if !r.manifest.Permissions.File {
 		return "", fmt.Errorf("file access denied: extension does not have 'file' permission")
 	}
@@ -109,7 +106,7 @@ func (r *ExtensionRuntime) validatePath(path string) (string, error) {
 	return absPath, nil
 }
 
-func (r *ExtensionRuntime) fileDownload(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) fileDownload(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 2 {
 		return r.vm.ToValue(map[string]interface{}{
 			"success": false,
@@ -169,6 +166,7 @@ func (r *ExtensionRuntime) fileDownload(call goja.FunctionCall) goja.Value {
 			"error":   err.Error(),
 		})
 	}
+	req = r.bindDownloadCancelContext(req)
 
 	for k, v := range headers {
 		req.Header.Set(k, v)
@@ -177,7 +175,12 @@ func (r *ExtensionRuntime) fileDownload(call goja.FunctionCall) goja.Value {
 		req.Header.Set("User-Agent", "SpotiFLAC-Extension/1.0")
 	}
 
-	resp, err := r.httpClient.Do(req)
+	client := r.downloadClient
+	if client == nil {
+		client = r.httpClient
+	}
+
+	resp, err := client.Do(req)
 	if err != nil {
 		return r.vm.ToValue(map[string]interface{}{
 			"success": false,
@@ -203,13 +206,22 @@ func (r *ExtensionRuntime) fileDownload(call goja.FunctionCall) goja.Value {
 	defer out.Close()
 
 	contentLength := resp.ContentLength
+	activeItemID := r.getActiveDownloadItemID()
+	if activeItemID != "" && contentLength > 0 {
+		SetItemBytesTotal(activeItemID, contentLength)
+	}
+
+	var progressWriter interface{ Write([]byte) (int, error) } = out
+	if activeItemID != "" {
+		progressWriter = NewItemProgressWriter(out, activeItemID)
+	}
 
 	var written int64
 	buf := make([]byte, 32*1024)
 	for {
 		nr, er := resp.Body.Read(buf)
 		if nr > 0 {
-			nw, ew := out.Write(buf[0:nr])
+			nw, ew := progressWriter.Write(buf[0:nr])
 			if nw < 0 || nr < nw {
 				nw = 0
 				if ew == nil {
@@ -218,6 +230,12 @@ func (r *ExtensionRuntime) fileDownload(call goja.FunctionCall) goja.Value {
 			}
 			written += int64(nw)
 			if ew != nil {
+				if ew == ErrDownloadCancelled {
+					return r.vm.ToValue(map[string]interface{}{
+						"success": false,
+						"error":   "download cancelled",
+					})
+				}
 				return r.vm.ToValue(map[string]interface{}{
 					"success": false,
 					"error":   fmt.Sprintf("failed to write file: %v", ew),
@@ -254,7 +272,7 @@ func (r *ExtensionRuntime) fileDownload(call goja.FunctionCall) goja.Value {
 	})
 }
 
-func (r *ExtensionRuntime) fileExists(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) fileExists(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue(false)
 	}
@@ -269,7 +287,7 @@ func (r *ExtensionRuntime) fileExists(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(err == nil)
 }
 
-func (r *ExtensionRuntime) fileDelete(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) fileDelete(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue(map[string]interface{}{
 			"success": false,
@@ -298,7 +316,7 @@ func (r *ExtensionRuntime) fileDelete(call goja.FunctionCall) goja.Value {
 	})
 }
 
-func (r *ExtensionRuntime) fileRead(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) fileRead(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue(map[string]interface{}{
 			"success": false,
@@ -329,7 +347,105 @@ func (r *ExtensionRuntime) fileRead(call goja.FunctionCall) goja.Value {
 	})
 }
 
-func (r *ExtensionRuntime) fileWrite(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) fileReadBytes(call goja.FunctionCall) goja.Value {
+	if len(call.Arguments) < 1 {
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   "path is required",
+		})
+	}
+
+	path := call.Arguments[0].String()
+	fullPath, err := r.validatePath(path)
+	if err != nil {
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   err.Error(),
+		})
+	}
+
+	options := parseRuntimeOptionsArgument(call, 1)
+	offset := runtimeOptionInt64(options, "offset", 0)
+	length := runtimeOptionInt64(options, "length", -1)
+	encoding := runtimeOptionString(options, "encoding", "base64")
+	if offset < 0 {
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   "offset must be >= 0",
+		})
+	}
+
+	file, err := os.Open(fullPath)
+	if err != nil {
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   err.Error(),
+		})
+	}
+	defer file.Close()
+
+	info, err := file.Stat()
+	if err != nil {
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   err.Error(),
+		})
+	}
+
+	size := info.Size()
+	if offset > size {
+		offset = size
+	}
+	if _, err := file.Seek(offset, io.SeekStart); err != nil {
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   fmt.Sprintf("failed to seek file: %v", err),
+		})
+	}
+
+	var data []byte
+	switch {
+	case length == 0:
+		data = []byte{}
+	case length > 0:
+		buf := make([]byte, int(length))
+		n, readErr := file.Read(buf)
+		if readErr != nil && readErr != io.EOF {
+			return r.vm.ToValue(map[string]interface{}{
+				"success": false,
+				"error":   fmt.Sprintf("failed to read file: %v", readErr),
+			})
+		}
+		data = buf[:n]
+	default:
+		data, err = io.ReadAll(file)
+		if err != nil {
+			return r.vm.ToValue(map[string]interface{}{
+				"success": false,
+				"error":   fmt.Sprintf("failed to read file: %v", err),
+			})
+		}
+	}
+
+	encoded, err := encodeRuntimeBytes(data, encoding)
+	if err != nil {
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   err.Error(),
+		})
+	}
+
+	return r.vm.ToValue(map[string]interface{}{
+		"success":    true,
+		"data":       encoded,
+		"bytes_read": len(data),
+		"offset":     offset,
+		"size":       size,
+		"eof":        offset+int64(len(data)) >= size,
+	})
+}
+
+func (r *extensionRuntime) fileWrite(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 2 {
 		return r.vm.ToValue(map[string]interface{}{
 			"success": false,
@@ -369,7 +485,108 @@ func (r *ExtensionRuntime) fileWrite(call goja.FunctionCall) goja.Value {
 	})
 }
 
-func (r *ExtensionRuntime) fileCopy(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) fileWriteBytes(call goja.FunctionCall) goja.Value {
+	if len(call.Arguments) < 2 {
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   "path and data are required",
+		})
+	}
+
+	path := call.Arguments[0].String()
+	fullPath, err := r.validatePath(path)
+	if err != nil {
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   err.Error(),
+		})
+	}
+
+	options := parseRuntimeOptionsArgument(call, 2)
+	appendMode := runtimeOptionBool(options, "append", false)
+	truncate := runtimeOptionBool(options, "truncate", false)
+	hasOffset := runtimeOptionHasKey(options, "offset")
+	offset := runtimeOptionInt64(options, "offset", 0)
+	encoding := runtimeOptionString(options, "encoding", "base64")
+
+	if appendMode && hasOffset {
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   "append and offset cannot be used together",
+		})
+	}
+	if offset < 0 {
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   "offset must be >= 0",
+		})
+	}
+
+	data, err := decodeRuntimeBytesValue(call.Arguments[1].Export(), encoding)
+	if err != nil {
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   err.Error(),
+		})
+	}
+
+	dir := filepath.Dir(fullPath)
+	if err := os.MkdirAll(dir, 0755); err != nil {
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   fmt.Sprintf("failed to create directory: %v", err),
+		})
+	}
+
+	flags := os.O_CREATE | os.O_WRONLY
+	if appendMode {
+		flags |= os.O_APPEND
+	}
+	if truncate {
+		flags |= os.O_TRUNC
+	}
+
+	file, err := os.OpenFile(fullPath, flags, 0644)
+	if err != nil {
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   err.Error(),
+		})
+	}
+	defer file.Close()
+
+	if hasOffset && !appendMode {
+		if _, err := file.Seek(offset, io.SeekStart); err != nil {
+			return r.vm.ToValue(map[string]interface{}{
+				"success": false,
+				"error":   fmt.Sprintf("failed to seek file: %v", err),
+			})
+		}
+	}
+
+	written, err := file.Write(data)
+	if err != nil {
+		return r.vm.ToValue(map[string]interface{}{
+			"success": false,
+			"error":   err.Error(),
+		})
+	}
+
+	info, statErr := file.Stat()
+	size := int64(0)
+	if statErr == nil {
+		size = info.Size()
+	}
+
+	return r.vm.ToValue(map[string]interface{}{
+		"success":       true,
+		"path":          fullPath,
+		"bytes_written": written,
+		"size":          size,
+	})
+}
+
+func (r *extensionRuntime) fileCopy(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 2 {
 		return r.vm.ToValue(map[string]interface{}{
 			"success": false,
@@ -396,13 +613,14 @@ func (r *ExtensionRuntime) fileCopy(call goja.FunctionCall) goja.Value {
 		})
 	}
 
-	data, err := os.ReadFile(fullSrc)
+	srcFile, err := os.Open(fullSrc)
 	if err != nil {
 		return r.vm.ToValue(map[string]interface{}{
 			"success": false,
 			"error":   fmt.Sprintf("failed to read source: %v", err),
 		})
 	}
+	defer srcFile.Close()
 
 	dir := filepath.Dir(fullDst)
 	if err := os.MkdirAll(dir, 0755); err != nil {
@@ -412,10 +630,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),
 		})
 	}
 
@@ -425,7 +659,7 @@ func (r *ExtensionRuntime) fileCopy(call goja.FunctionCall) goja.Value {
 	})
 }
 
-func (r *ExtensionRuntime) fileMove(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) fileMove(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 2 {
 		return r.vm.ToValue(map[string]interface{}{
 			"success": false,
@@ -473,7 +707,7 @@ func (r *ExtensionRuntime) fileMove(call goja.FunctionCall) goja.Value {
 	})
 }
 
-func (r *ExtensionRuntime) fileGetSize(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) fileGetSize(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue(map[string]interface{}{
 			"success": false,

go_backend/extension_runtime_http.go

@@ -1,4 +1,3 @@
-// Package gobackend provides HTTP API for extension runtime
 package gobackend
 
 import (
@@ -12,15 +11,13 @@ import (
 	"github.com/dop251/goja"
 )
 
-// ==================== HTTP API (Sandboxed) ====================
-
 type HTTPResponse struct {
 	StatusCode int               `json:"statusCode"`
 	Body       string            `json:"body"`
 	Headers    map[string]string `json:"headers"`
 }
 
-func (r *ExtensionRuntime) validateDomain(urlStr string) error {
+func (r *extensionRuntime) validateDomain(urlStr string) error {
 	parsed, err := url.Parse(urlStr)
 	if err != nil {
 		return fmt.Errorf("invalid URL: %w", err)
@@ -32,6 +29,9 @@ func (r *ExtensionRuntime) validateDomain(urlStr string) error {
 	if parsed.Scheme != "https" {
 		return fmt.Errorf("network access denied: only https is allowed")
 	}
+	if parsed.User != nil {
+		return fmt.Errorf("invalid URL: embedded credentials are not allowed")
+	}
 
 	domain := parsed.Hostname()
 	if domain == "" {
@@ -49,7 +49,7 @@ func (r *ExtensionRuntime) validateDomain(urlStr string) error {
 	return nil
 }
 
-func (r *ExtensionRuntime) httpGet(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) httpGet(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue(map[string]interface{}{
 			"error": "URL is required",
@@ -81,6 +81,7 @@ func (r *ExtensionRuntime) httpGet(call goja.FunctionCall) goja.Value {
 			"error": err.Error(),
 		})
 	}
+	req = r.bindDownloadCancelContext(req)
 
 	for k, v := range headers {
 		req.Header.Set(k, v)
@@ -118,12 +119,13 @@ func (r *ExtensionRuntime) httpGet(call goja.FunctionCall) goja.Value {
 		"statusCode": resp.StatusCode,
 		"status":     resp.StatusCode,
 		"ok":         resp.StatusCode >= 200 && resp.StatusCode < 300,
+		"url":        resp.Request.URL.String(),
 		"body":       string(body),
 		"headers":    respHeaders,
 	})
 }
 
-func (r *ExtensionRuntime) httpPost(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) httpPost(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue(map[string]interface{}{
 			"error": "URL is required",
@@ -174,6 +176,7 @@ func (r *ExtensionRuntime) httpPost(call goja.FunctionCall) goja.Value {
 			"error": err.Error(),
 		})
 	}
+	req = r.bindDownloadCancelContext(req)
 
 	for k, v := range headers {
 		req.Header.Set(k, v)
@@ -214,12 +217,13 @@ func (r *ExtensionRuntime) httpPost(call goja.FunctionCall) goja.Value {
 		"statusCode": resp.StatusCode,
 		"status":     resp.StatusCode,
 		"ok":         resp.StatusCode >= 200 && resp.StatusCode < 300,
+		"url":        resp.Request.URL.String(),
 		"body":       string(body),
 		"headers":    respHeaders,
 	})
 }
 
-func (r *ExtensionRuntime) httpRequest(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) httpRequest(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue(map[string]interface{}{
 			"error": "URL is required",
@@ -282,6 +286,7 @@ func (r *ExtensionRuntime) httpRequest(call goja.FunctionCall) goja.Value {
 			"error": err.Error(),
 		})
 	}
+	req = r.bindDownloadCancelContext(req)
 
 	for k, v := range headers {
 		req.Header.Set(k, v)
@@ -322,24 +327,25 @@ func (r *ExtensionRuntime) httpRequest(call goja.FunctionCall) goja.Value {
 		"statusCode": resp.StatusCode,
 		"status":     resp.StatusCode,
 		"ok":         resp.StatusCode >= 200 && resp.StatusCode < 300,
+		"url":        resp.Request.URL.String(),
 		"body":       string(body),
 		"headers":    respHeaders,
 	})
 }
 
-func (r *ExtensionRuntime) httpPut(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) httpPut(call goja.FunctionCall) goja.Value {
 	return r.httpMethodShortcut("PUT", call)
 }
 
-func (r *ExtensionRuntime) httpDelete(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) httpDelete(call goja.FunctionCall) goja.Value {
 	return r.httpMethodShortcut("DELETE", call)
 }
 
-func (r *ExtensionRuntime) httpPatch(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) httpPatch(call goja.FunctionCall) goja.Value {
 	return r.httpMethodShortcut("PATCH", call)
 }
 
-func (r *ExtensionRuntime) httpMethodShortcut(method string, call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) httpMethodShortcut(method string, call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue(map[string]interface{}{
 			"error": "URL is required",
@@ -407,6 +413,7 @@ func (r *ExtensionRuntime) httpMethodShortcut(method string, call goja.FunctionC
 			"error": err.Error(),
 		})
 	}
+	req = r.bindDownloadCancelContext(req)
 
 	for k, v := range headers {
 		req.Header.Set(k, v)
@@ -446,12 +453,13 @@ func (r *ExtensionRuntime) httpMethodShortcut(method string, call goja.FunctionC
 		"statusCode": resp.StatusCode,
 		"status":     resp.StatusCode,
 		"ok":         resp.StatusCode >= 200 && resp.StatusCode < 300,
+		"url":        resp.Request.URL.String(),
 		"body":       string(body),
 		"headers":    respHeaders,
 	})
 }
 
-func (r *ExtensionRuntime) httpClearCookies(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) httpClearCookies(call goja.FunctionCall) goja.Value {
 	if jar, ok := r.cookieJar.(*simpleCookieJar); ok {
 		jar.mu.Lock()
 		jar.cookies = make(map[string][]*http.Cookie)

go_backend/extension_runtime_matching.go

@@ -1,4 +1,3 @@
-// Package gobackend provides Track Matching API for extension runtime
 package gobackend
 
 import (
@@ -7,9 +6,7 @@ import (
 	"github.com/dop251/goja"
 )
 
-// ==================== Track Matching API ====================
-
-func (r *ExtensionRuntime) matchingCompareStrings(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) matchingCompareStrings(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 2 {
 		return r.vm.ToValue(0.0)
 	}
@@ -25,7 +22,7 @@ func (r *ExtensionRuntime) matchingCompareStrings(call goja.FunctionCall) goja.V
 	return r.vm.ToValue(similarity)
 }
 
-func (r *ExtensionRuntime) matchingCompareDuration(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) matchingCompareDuration(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 2 {
 		return r.vm.ToValue(false)
 	}
@@ -46,7 +43,7 @@ func (r *ExtensionRuntime) matchingCompareDuration(call goja.FunctionCall) goja.
 	return r.vm.ToValue(diff <= tolerance)
 }
 
-func (r *ExtensionRuntime) matchingNormalizeString(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) matchingNormalizeString(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue("")
 	}

go_backend/extension_runtime_polyfills.go

@@ -1,4 +1,3 @@
-// Package gobackend provides Browser-like Polyfills for extension runtime
 package gobackend
 
 import (
@@ -13,13 +12,7 @@ import (
 	"github.com/dop251/goja"
 )
 
-// ==================== Browser-like Polyfills ====================
-// These polyfills make porting browser/Node.js libraries easier
-// without compromising sandbox security
-
-// fetchPolyfill implements browser-compatible fetch() API
-// Returns a Promise-like object with json(), text() methods
-func (r *ExtensionRuntime) fetchPolyfill(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) fetchPolyfill(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.createFetchError("URL is required")
 	}
@@ -41,7 +34,6 @@ func (r *ExtensionRuntime) fetchPolyfill(call goja.FunctionCall) goja.Value {
 				method = strings.ToUpper(m)
 			}
 
-			// Body - support string, object (auto-stringify), or nil
 			if bodyArg, ok := opts["body"]; ok && bodyArg != nil {
 				switch v := bodyArg.(type) {
 				case string:
@@ -77,6 +69,7 @@ func (r *ExtensionRuntime) fetchPolyfill(call goja.FunctionCall) goja.Value {
 	if err != nil {
 		return r.createFetchError(err.Error())
 	}
+	req = r.bindDownloadCancelContext(req)
 
 	for k, v := range headers {
 		req.Header.Set(k, v)
@@ -113,7 +106,7 @@ func (r *ExtensionRuntime) fetchPolyfill(call goja.FunctionCall) goja.Value {
 	responseObj.Set("status", resp.StatusCode)
 	responseObj.Set("statusText", http.StatusText(resp.StatusCode))
 	responseObj.Set("headers", respHeaders)
-	responseObj.Set("url", urlStr)
+	responseObj.Set("url", resp.Request.URL.String())
 
 	bodyString := string(body)
 
@@ -141,8 +134,7 @@ func (r *ExtensionRuntime) fetchPolyfill(call goja.FunctionCall) goja.Value {
 	return responseObj
 }
 
-// createFetchError creates a fetch error response
-func (r *ExtensionRuntime) createFetchError(message string) goja.Value {
+func (r *extensionRuntime) createFetchError(message string) goja.Value {
 	errorObj := r.vm.NewObject()
 	errorObj.Set("ok", false)
 	errorObj.Set("status", 0)
@@ -157,8 +149,7 @@ func (r *ExtensionRuntime) createFetchError(message string) goja.Value {
 	return errorObj
 }
 
-// atobPolyfill implements browser atob() - decode base64 to string
-func (r *ExtensionRuntime) atobPolyfill(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) atobPolyfill(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue("")
 	}
@@ -174,8 +165,7 @@ func (r *ExtensionRuntime) atobPolyfill(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(string(decoded))
 }
 
-// btoaPolyfill implements browser btoa() - encode string to base64
-func (r *ExtensionRuntime) btoaPolyfill(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) btoaPolyfill(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue("")
 	}
@@ -183,8 +173,7 @@ func (r *ExtensionRuntime) btoaPolyfill(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(base64.StdEncoding.EncodeToString([]byte(input)))
 }
 
-// registerTextEncoderDecoder registers TextEncoder and TextDecoder classes
-func (r *ExtensionRuntime) registerTextEncoderDecoder(vm *goja.Runtime) {
+func (r *extensionRuntime) registerTextEncoderDecoder(vm *goja.Runtime) {
 	vm.Set("TextEncoder", func(call goja.ConstructorCall) *goja.Object {
 		encoder := call.This
 		encoder.Set("encoding", "utf-8")
@@ -204,7 +193,6 @@ func (r *ExtensionRuntime) registerTextEncoderDecoder(vm *goja.Runtime) {
 		})
 
 		encoder.Set("encodeInto", func(call goja.FunctionCall) goja.Value {
-			// Simplified implementation
 			if len(call.Arguments) < 2 {
 				return vm.ToValue(map[string]interface{}{"read": 0, "written": 0})
 			}
@@ -265,7 +253,7 @@ func (r *ExtensionRuntime) registerTextEncoderDecoder(vm *goja.Runtime) {
 	})
 }
 
-func (r *ExtensionRuntime) registerURLClass(vm *goja.Runtime) {
+func (r *extensionRuntime) registerURLClass(vm *goja.Runtime) {
 	vm.Set("URL", func(call goja.ConstructorCall) *goja.Object {
 		urlObj := call.This
 
@@ -429,9 +417,7 @@ 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
+func (r *extensionRuntime) registerJSONGlobal(vm *goja.Runtime) {
 	jsonScript := `
 		if (typeof JSON === 'undefined') {
 			var JSON = {

go_backend/extension_runtime_storage.go

@@ -1,4 +1,3 @@
-// Package gobackend provides Storage and Credentials API for extension runtime
 package gobackend
 
 import (
@@ -11,58 +10,179 @@ import (
 	"io"
 	"os"
 	"path/filepath"
+	"reflect"
+	"time"
 
 	"github.com/dop251/goja"
 )
 
-// ==================== Storage API ====================
+const (
+	defaultStorageFlushDelay = 400 * time.Millisecond
+	storageFlushRetryDelay   = 2 * time.Second
+)
 
-func (r *ExtensionRuntime) getStoragePath() string {
+func (r *extensionRuntime) getStoragePath() string {
 	return filepath.Join(r.dataDir, "storage.json")
 }
 
-func (r *ExtensionRuntime) loadStorage() (map[string]interface{}, error) {
+func cloneInterfaceMap(src map[string]interface{}) map[string]interface{} {
+	if len(src) == 0 {
+		return make(map[string]interface{})
+	}
+	dst := make(map[string]interface{}, len(src))
+	for k, v := range src {
+		dst[k] = v
+	}
+	return dst
+}
+
+func (r *extensionRuntime) ensureStorageLoaded() error {
+	r.storageMu.RLock()
+	if r.storageLoaded {
+		r.storageMu.RUnlock()
+		return nil
+	}
+	r.storageMu.RUnlock()
+
+	r.storageMu.Lock()
+	defer r.storageMu.Unlock()
+	if r.storageLoaded {
+		return nil
+	}
+
 	storagePath := r.getStoragePath()
 	data, err := os.ReadFile(storagePath)
 	if err != nil {
 		if os.IsNotExist(err) {
-			return make(map[string]interface{}), nil
+			r.storageCache = make(map[string]interface{})
+			r.storageLoaded = true
+			return nil
 		}
-		return nil, err
+		return err
 	}
 
 	var storage map[string]interface{}
 	if err := json.Unmarshal(data, &storage); err != nil {
+		return err
+	}
+	if storage == nil {
+		storage = make(map[string]interface{})
+	}
+
+	r.storageCache = storage
+	r.storageLoaded = true
+	return nil
+}
+
+func (r *extensionRuntime) loadStorage() (map[string]interface{}, error) {
+	if err := r.ensureStorageLoaded(); err != nil {
 		return nil, err
 	}
 
-	return storage, nil
+	r.storageMu.RLock()
+	defer r.storageMu.RUnlock()
+	return cloneInterfaceMap(r.storageCache), nil
 }
 
-func (r *ExtensionRuntime) saveStorage(storage map[string]interface{}) error {
-	storagePath := r.getStoragePath()
-	data, err := json.MarshalIndent(storage, "", "  ")
+func (r *extensionRuntime) queueStorageFlushLocked(delay time.Duration) {
+	if r.storageClosed {
+		return
+	}
+	if r.storageTimer != nil {
+		return
+	}
+	r.storageTimer = time.AfterFunc(delay, r.flushStorageDirtyAsync)
+}
+
+func (r *extensionRuntime) persistStorageSnapshot(storage map[string]interface{}) error {
+	data, err := json.Marshal(storage)
 	if err != nil {
 		return err
 	}
 
-	return os.WriteFile(storagePath, data, 0644)
+	r.storageWriteMu.Lock()
+	defer r.storageWriteMu.Unlock()
+
+	return os.WriteFile(r.getStoragePath(), data, 0600)
 }
 
-func (r *ExtensionRuntime) storageGet(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) flushStorageDirtyAsync() {
+	if err := r.flushStorageDirty(); err != nil {
+		GoLog("[Extension:%s] Storage flush error: %v\n", r.extensionID, err)
+	}
+}
+
+func (r *extensionRuntime) flushStorageDirty() error {
+	r.storageMu.Lock()
+	if r.storageClosed {
+		r.storageTimer = nil
+		r.storageMu.Unlock()
+		return nil
+	}
+	if !r.storageDirty {
+		r.storageTimer = nil
+		r.storageMu.Unlock()
+		return nil
+	}
+	snapshot := cloneInterfaceMap(r.storageCache)
+	r.storageDirty = false
+	r.storageTimer = nil
+	r.storageMu.Unlock()
+
+	if err := r.persistStorageSnapshot(snapshot); err != nil {
+		r.storageMu.Lock()
+		r.storageDirty = true
+		r.queueStorageFlushLocked(storageFlushRetryDelay)
+		r.storageMu.Unlock()
+		return err
+	}
+
+	return nil
+}
+
+func (r *extensionRuntime) flushStorageNow() error {
+	r.storageMu.Lock()
+	if r.storageTimer != nil {
+		r.storageTimer.Stop()
+		r.storageTimer = nil
+	}
+	if !r.storageLoaded || r.storageClosed {
+		r.storageMu.Unlock()
+		return nil
+	}
+	snapshot := cloneInterfaceMap(r.storageCache)
+	r.storageDirty = false
+	r.storageMu.Unlock()
+
+	return r.persistStorageSnapshot(snapshot)
+}
+
+func (r *extensionRuntime) closeStorageFlusher() {
+	r.storageMu.Lock()
+	r.storageClosed = true
+	r.storageDirty = false
+	if r.storageTimer != nil {
+		r.storageTimer.Stop()
+		r.storageTimer = nil
+	}
+	r.storageMu.Unlock()
+}
+
+func (r *extensionRuntime) storageGet(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return goja.Undefined()
 	}
 
 	key := call.Arguments[0].String()
 
-	storage, err := r.loadStorage()
-	if err != nil {
+	if err := r.ensureStorageLoaded(); err != nil {
 		GoLog("[Extension:%s] Storage load error: %v\n", r.extensionID, err)
 		return goja.Undefined()
 	}
 
-	value, exists := storage[key]
+	r.storageMu.RLock()
+	value, exists := r.storageCache[key]
+	r.storageMu.RUnlock()
 	if !exists {
 		if len(call.Arguments) > 1 {
 			return call.Arguments[1]
@@ -73,7 +193,7 @@ func (r *ExtensionRuntime) storageGet(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(value)
 }
 
-func (r *ExtensionRuntime) storageSet(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) storageSet(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 2 {
 		return r.vm.ToValue(false)
 	}
@@ -81,54 +201,68 @@ 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)
 }
 
-func (r *ExtensionRuntime) storageRemove(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) storageRemove(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue(false)
 	}
 
 	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)
 }
 
-func (r *ExtensionRuntime) getCredentialsPath() string {
+func (r *extensionRuntime) getCredentialsPath() string {
 	return filepath.Join(r.dataDir, ".credentials.enc")
 }
 
-func (r *ExtensionRuntime) getSaltPath() string {
+func (r *extensionRuntime) getSaltPath() string {
 	return filepath.Join(r.dataDir, ".cred_salt")
 }
 
-func (r *ExtensionRuntime) getOrCreateSalt() ([]byte, error) {
+func (r *extensionRuntime) getOrCreateSalt() ([]byte, error) {
 	saltPath := r.getSaltPath()
 
 	salt, err := os.ReadFile(saltPath)
@@ -148,7 +282,7 @@ func (r *ExtensionRuntime) getOrCreateSalt() ([]byte, error) {
 	return salt, nil
 }
 
-func (r *ExtensionRuntime) getEncryptionKey() ([]byte, error) {
+func (r *extensionRuntime) getEncryptionKey() ([]byte, error) {
 	salt, err := r.getOrCreateSalt()
 	if err != nil {
 		return nil, err
@@ -159,34 +293,64 @@ func (r *ExtensionRuntime) getEncryptionKey() ([]byte, error) {
 	return hash[:], nil
 }
 
-func (r *ExtensionRuntime) loadCredentials() (map[string]interface{}, error) {
+func (r *extensionRuntime) ensureCredentialsLoaded() error {
+	r.credentialsMu.RLock()
+	if r.credentialsLoaded {
+		r.credentialsMu.RUnlock()
+		return nil
+	}
+	r.credentialsMu.RUnlock()
+
+	r.credentialsMu.Lock()
+	defer r.credentialsMu.Unlock()
+	if r.credentialsLoaded {
+		return nil
+	}
+
 	credPath := r.getCredentialsPath()
 	data, err := os.ReadFile(credPath)
 	if err != nil {
 		if os.IsNotExist(err) {
-			return make(map[string]interface{}), nil
+			r.credentialsCache = make(map[string]interface{})
+			r.credentialsLoaded = true
+			return nil
 		}
-		return nil, err
+		return err
 	}
 
 	key, err := r.getEncryptionKey()
 	if err != nil {
-		return nil, fmt.Errorf("failed to get encryption key: %w", err)
+		return fmt.Errorf("failed to get encryption key: %w", err)
 	}
 	decrypted, err := decryptAES(data, key)
 	if err != nil {
-		return nil, fmt.Errorf("failed to decrypt credentials: %w", err)
+		return fmt.Errorf("failed to decrypt credentials: %w", err)
 	}
 
 	var creds map[string]interface{}
 	if err := json.Unmarshal(decrypted, &creds); err != nil {
+		return err
+	}
+	if creds == nil {
+		creds = make(map[string]interface{})
+	}
+
+	r.credentialsCache = creds
+	r.credentialsLoaded = true
+	return nil
+}
+
+func (r *extensionRuntime) loadCredentials() (map[string]interface{}, error) {
+	if err := r.ensureCredentialsLoaded(); err != nil {
 		return nil, err
 	}
 
-	return creds, nil
+	r.credentialsMu.RLock()
+	defer r.credentialsMu.RUnlock()
+	return cloneInterfaceMap(r.credentialsCache), nil
 }
 
-func (r *ExtensionRuntime) saveCredentials(creds map[string]interface{}) error {
+func (r *extensionRuntime) saveCredentials(creds map[string]interface{}) error {
 	data, err := json.Marshal(creds)
 	if err != nil {
 		return err
@@ -202,10 +366,18 @@ func (r *ExtensionRuntime) saveCredentials(creds map[string]interface{}) error {
 	}
 
 	credPath := r.getCredentialsPath()
-	return os.WriteFile(credPath, encrypted, 0600)
+	if err := os.WriteFile(credPath, encrypted, 0600); err != nil {
+		return err
+	}
+
+	r.credentialsMu.Lock()
+	r.credentialsCache = cloneInterfaceMap(creds)
+	r.credentialsLoaded = true
+	r.credentialsMu.Unlock()
+	return nil
 }
 
-func (r *ExtensionRuntime) credentialsStore(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) credentialsStore(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 2 {
 		return r.vm.ToValue(map[string]interface{}{
 			"success": false,
@@ -216,8 +388,7 @@ func (r *ExtensionRuntime) credentialsStore(call goja.FunctionCall) goja.Value {
 	key := call.Arguments[0].String()
 	value := call.Arguments[1].Export()
 
-	creds, err := r.loadCredentials()
-	if err != nil {
+	if err := r.ensureCredentialsLoaded(); err != nil {
 		GoLog("[Extension:%s] Credentials load error: %v\n", r.extensionID, err)
 		return r.vm.ToValue(map[string]interface{}{
 			"success": false,
@@ -225,9 +396,12 @@ func (r *ExtensionRuntime) credentialsStore(call goja.FunctionCall) goja.Value {
 		})
 	}
 
-	creds[key] = value
+	r.credentialsMu.RLock()
+	nextCreds := cloneInterfaceMap(r.credentialsCache)
+	r.credentialsMu.RUnlock()
+	nextCreds[key] = value
 
-	if err := r.saveCredentials(creds); err != nil {
+	if err := r.saveCredentials(nextCreds); err != nil {
 		GoLog("[Extension:%s] Credentials save error: %v\n", r.extensionID, err)
 		return r.vm.ToValue(map[string]interface{}{
 			"success": false,
@@ -240,20 +414,21 @@ func (r *ExtensionRuntime) credentialsStore(call goja.FunctionCall) goja.Value {
 	})
 }
 
-func (r *ExtensionRuntime) credentialsGet(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) credentialsGet(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return goja.Undefined()
 	}
 
 	key := call.Arguments[0].String()
 
-	creds, err := r.loadCredentials()
-	if err != nil {
+	if err := r.ensureCredentialsLoaded(); err != nil {
 		GoLog("[Extension:%s] Credentials load error: %v\n", r.extensionID, err)
 		return goja.Undefined()
 	}
 
-	value, exists := creds[key]
+	r.credentialsMu.RLock()
+	value, exists := r.credentialsCache[key]
+	r.credentialsMu.RUnlock()
 	if !exists {
 		if len(call.Arguments) > 1 {
 			return call.Arguments[1]
@@ -264,22 +439,24 @@ func (r *ExtensionRuntime) credentialsGet(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(value)
 }
 
-func (r *ExtensionRuntime) credentialsRemove(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) credentialsRemove(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue(false)
 	}
 
 	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)
 	}
@@ -287,19 +464,20 @@ func (r *ExtensionRuntime) credentialsRemove(call goja.FunctionCall) goja.Value
 	return r.vm.ToValue(true)
 }
 
-func (r *ExtensionRuntime) credentialsHas(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) credentialsHas(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue(false)
 	}
 
 	key := call.Arguments[0].String()
 
-	creds, err := r.loadCredentials()
-	if err != nil {
+	if err := r.ensureCredentialsLoaded(); err != nil {
 		return r.vm.ToValue(false)
 	}
 
-	_, exists := creds[key]
+	r.credentialsMu.RLock()
+	_, exists := r.credentialsCache[key]
+	r.credentialsMu.RUnlock()
 	return r.vm.ToValue(exists)
 }
 

go_backend/extension_runtime_storage_test.go

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

go_backend/extension_runtime_utils.go

@@ -1,4 +1,3 @@
-// Package gobackend provides Utility functions for extension runtime
 package gobackend
 
 import (
@@ -17,9 +16,7 @@ import (
 	"github.com/dop251/goja"
 )
 
-// ==================== Utility Functions ====================
-
-func (r *ExtensionRuntime) base64Encode(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) base64Encode(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue("")
 	}
@@ -27,7 +24,7 @@ func (r *ExtensionRuntime) base64Encode(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(base64.StdEncoding.EncodeToString([]byte(input)))
 }
 
-func (r *ExtensionRuntime) base64Decode(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) base64Decode(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue("")
 	}
@@ -39,7 +36,7 @@ func (r *ExtensionRuntime) base64Decode(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(string(decoded))
 }
 
-func (r *ExtensionRuntime) md5Hash(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) md5Hash(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue("")
 	}
@@ -48,7 +45,7 @@ func (r *ExtensionRuntime) md5Hash(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(hex.EncodeToString(hash[:]))
 }
 
-func (r *ExtensionRuntime) sha256Hash(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) sha256Hash(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue("")
 	}
@@ -57,7 +54,7 @@ func (r *ExtensionRuntime) sha256Hash(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(hex.EncodeToString(hash[:]))
 }
 
-func (r *ExtensionRuntime) hmacSHA256(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) hmacSHA256(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 2 {
 		return r.vm.ToValue("")
 	}
@@ -69,7 +66,7 @@ func (r *ExtensionRuntime) hmacSHA256(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(hex.EncodeToString(mac.Sum(nil)))
 }
 
-func (r *ExtensionRuntime) hmacSHA256Base64(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) hmacSHA256Base64(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 2 {
 		return r.vm.ToValue("")
 	}
@@ -81,7 +78,7 @@ func (r *ExtensionRuntime) hmacSHA256Base64(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(base64.StdEncoding.EncodeToString(mac.Sum(nil)))
 }
 
-func (r *ExtensionRuntime) hmacSHA1(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) hmacSHA1(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 2 {
 		return r.vm.ToValue([]byte{})
 	}
@@ -133,7 +130,7 @@ func (r *ExtensionRuntime) hmacSHA1(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(jsArray)
 }
 
-func (r *ExtensionRuntime) parseJSON(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) parseJSON(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return goja.Undefined()
 	}
@@ -148,7 +145,7 @@ func (r *ExtensionRuntime) parseJSON(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(result)
 }
 
-func (r *ExtensionRuntime) stringifyJSON(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) stringifyJSON(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue("")
 	}
@@ -163,7 +160,7 @@ func (r *ExtensionRuntime) stringifyJSON(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(string(data))
 }
 
-func (r *ExtensionRuntime) cryptoEncrypt(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) cryptoEncrypt(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 2 {
 		return r.vm.ToValue(map[string]interface{}{
 			"success": false,
@@ -190,7 +187,7 @@ func (r *ExtensionRuntime) cryptoEncrypt(call goja.FunctionCall) goja.Value {
 	})
 }
 
-func (r *ExtensionRuntime) cryptoDecrypt(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) cryptoDecrypt(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 2 {
 		return r.vm.ToValue(map[string]interface{}{
 			"success": false,
@@ -225,7 +222,7 @@ func (r *ExtensionRuntime) cryptoDecrypt(call goja.FunctionCall) goja.Value {
 	})
 }
 
-func (r *ExtensionRuntime) cryptoGenerateKey(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) cryptoGenerateKey(call goja.FunctionCall) goja.Value {
 	length := 32
 	if len(call.Arguments) > 0 && !goja.IsUndefined(call.Arguments[0]) {
 		if l, ok := call.Arguments[0].Export().(float64); ok {
@@ -248,35 +245,98 @@ func (r *ExtensionRuntime) cryptoGenerateKey(call goja.FunctionCall) goja.Value
 	})
 }
 
-func (r *ExtensionRuntime) randomUserAgent(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) randomUserAgent(call goja.FunctionCall) goja.Value {
 	return r.vm.ToValue(getRandomUserAgent())
 }
 
-func (r *ExtensionRuntime) logDebug(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) appVersion(call goja.FunctionCall) goja.Value {
+	return r.vm.ToValue(GetAppVersion())
+}
+
+func (r *extensionRuntime) appUserAgent(call goja.FunctionCall) goja.Value {
+	return r.vm.ToValue(appUserAgent())
+}
+
+func (r *extensionRuntime) sleep(call goja.FunctionCall) goja.Value {
+	if len(call.Arguments) < 1 {
+		return r.vm.ToValue(true)
+	}
+
+	sleepMs := 0
+	switch value := call.Arguments[0].Export().(type) {
+	case int64:
+		sleepMs = int(value)
+	case int32:
+		sleepMs = int(value)
+	case int:
+		sleepMs = value
+	case float64:
+		sleepMs = int(value)
+	default:
+		sleepMs = 0
+	}
+
+	if sleepMs <= 0 {
+		return r.vm.ToValue(true)
+	}
+	if sleepMs > 5*60*1000 {
+		sleepMs = 5 * 60 * 1000
+	}
+
+	itemID := r.getActiveDownloadItemID()
+	deadline := time.Now().Add(time.Duration(sleepMs) * time.Millisecond)
+
+	for {
+		if itemID != "" && isDownloadCancelled(itemID) {
+			return r.vm.ToValue(false)
+		}
+
+		remaining := time.Until(deadline)
+		if remaining <= 0 {
+			return r.vm.ToValue(true)
+		}
+
+		step := 100 * time.Millisecond
+		if remaining < step {
+			step = remaining
+		}
+		time.Sleep(step)
+	}
+}
+
+func (r *extensionRuntime) isDownloadCancelled(call goja.FunctionCall) goja.Value {
+	itemID := r.getActiveDownloadItemID()
+	if itemID == "" {
+		return r.vm.ToValue(false)
+	}
+	return r.vm.ToValue(isDownloadCancelled(itemID))
+}
+
+func (r *extensionRuntime) logDebug(call goja.FunctionCall) goja.Value {
 	msg := r.formatLogArgs(call.Arguments)
 	GoLog("[Extension:%s:DEBUG] %s\n", r.extensionID, msg)
 	return goja.Undefined()
 }
 
-func (r *ExtensionRuntime) logInfo(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) logInfo(call goja.FunctionCall) goja.Value {
 	msg := r.formatLogArgs(call.Arguments)
 	GoLog("[Extension:%s:INFO] %s\n", r.extensionID, msg)
 	return goja.Undefined()
 }
 
-func (r *ExtensionRuntime) logWarn(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) logWarn(call goja.FunctionCall) goja.Value {
 	msg := r.formatLogArgs(call.Arguments)
 	GoLog("[Extension:%s:WARN] %s\n", r.extensionID, msg)
 	return goja.Undefined()
 }
 
-func (r *ExtensionRuntime) logError(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) logError(call goja.FunctionCall) goja.Value {
 	msg := r.formatLogArgs(call.Arguments)
 	GoLog("[Extension:%s:ERROR] %s\n", r.extensionID, msg)
 	return goja.Undefined()
 }
 
-func (r *ExtensionRuntime) formatLogArgs(args []goja.Value) string {
+func (r *extensionRuntime) formatLogArgs(args []goja.Value) string {
 	parts := make([]string, len(args))
 	for i, arg := range args {
 		parts[i] = fmt.Sprintf("%v", arg.Export())
@@ -284,7 +344,7 @@ func (r *ExtensionRuntime) formatLogArgs(args []goja.Value) string {
 	return strings.Join(parts, " ")
 }
 
-func (r *ExtensionRuntime) sanitizeFilenameWrapper(call goja.FunctionCall) goja.Value {
+func (r *extensionRuntime) sanitizeFilenameWrapper(call goja.FunctionCall) goja.Value {
 	if len(call.Arguments) < 1 {
 		return r.vm.ToValue("")
 	}
@@ -292,7 +352,7 @@ func (r *ExtensionRuntime) sanitizeFilenameWrapper(call goja.FunctionCall) goja.
 	return r.vm.ToValue(sanitizeFilename(input))
 }
 
-func (r *ExtensionRuntime) RegisterGoBackendAPIs(vm *goja.Runtime) {
+func (r *extensionRuntime) RegisterGoBackendAPIs(vm *goja.Runtime) {
 	gobackendObj := vm.Get("gobackend")
 	if gobackendObj == nil || goja.IsUndefined(gobackendObj) {
 		gobackendObj = vm.NewObject()

go_backend/extension_settings.go

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

go_backend/extension_store.go

@@ -8,6 +8,7 @@ import (
 	"net/url"
 	"os"
 	"path/filepath"
+	"strings"
 	"sync"
 	"time"
 )
@@ -20,12 +21,11 @@ const (
 	CategoryIntegration = "integration"
 )
 
-type StoreExtension struct {
+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"`
@@ -40,7 +40,7 @@ type StoreExtension struct {
 	MinAppVersionAlt string   `json:"minAppVersion,omitempty"`
 }
 
-func (e *StoreExtension) getDisplayName() string {
+func (e *storeExtension) getDisplayName() string {
 	if e.DisplayName != "" {
 		return e.DisplayName
 	}
@@ -50,40 +50,38 @@ func (e *StoreExtension) getDisplayName() string {
 	return e.Name
 }
 
-func (e *StoreExtension) getDownloadURL() string {
+func (e *storeExtension) getDownloadURL() string {
 	if e.DownloadURL != "" {
 		return e.DownloadURL
 	}
 	return e.DownloadURLAlt
 }
 
-func (e *StoreExtension) getIconURL() string {
+func (e *storeExtension) getIconURL() string {
 	if e.IconURL != "" {
 		return e.IconURL
 	}
 	return e.IconURLAlt
 }
 
-func (e *StoreExtension) getMinAppVersion() string {
+func (e *storeExtension) getMinAppVersion() string {
 	if e.MinAppVersion != "" {
 		return e.MinAppVersion
 	}
 	return e.MinAppVersionAlt
 }
 
-type StoreRegistry struct {
+type storeRegistry struct {
 	Version    int              `json:"version"`
 	UpdatedAt  string           `json:"updated_at"`
-	Extensions []StoreExtension `json:"extensions"`
+	Extensions []storeExtension `json:"extensions"`
 }
 
-// StoreExtensionResponse is the normalized response sent to Flutter
-type StoreExtensionResponse struct {
+type storeExtensionResponse struct {
 	ID               string   `json:"id"`
 	Name             string   `json:"name"`
 	DisplayName      string   `json:"display_name"`
 	Version          string   `json:"version"`
-	Author           string   `json:"author"`
 	Description      string   `json:"description"`
 	DownloadURL      string   `json:"download_url"`
 	IconURL          string   `json:"icon_url,omitempty"`
@@ -97,66 +95,95 @@ type StoreExtensionResponse struct {
 	HasUpdate        bool     `json:"has_update"`
 }
 
-func (e *StoreExtension) ToResponse() StoreExtensionResponse {
-	return StoreExtensionResponse{
+func (e *storeExtension) toResponse() storeExtensionResponse {
+	resp := storeExtensionResponse{
 		ID:            e.ID,
 		Name:          e.Name,
 		DisplayName:   e.getDisplayName(),
 		Version:       e.Version,
-		Author:        e.Author,
 		Description:   e.Description,
 		DownloadURL:   e.getDownloadURL(),
 		IconURL:       e.getIconURL(),
 		Category:      e.Category,
-		Tags:          e.Tags,
 		Downloads:     e.Downloads,
 		UpdatedAt:     e.UpdatedAt,
 		MinAppVersion: e.getMinAppVersion(),
 	}
+
+	if len(e.Tags) > 0 {
+		resp.Tags = append([]string(nil), e.Tags...)
+	}
+
+	return resp
 }
 
-type ExtensionStore struct {
+type extensionStore struct {
 	registryURL string
 	cacheDir    string
-	cache       *StoreRegistry
+	cache       *storeRegistry
 	cacheMu     sync.RWMutex
 	cacheTime   time.Time
 	cacheTTL    time.Duration
 }
 
 var (
-	extensionStore   *ExtensionStore
-	extensionStoreMu sync.Mutex
+	globalExtensionStore *extensionStore
+	extensionStoreMu     sync.Mutex
 )
 
 const (
-	defaultRegistryURL = "https://raw.githubusercontent.com/zarzet/SpotiFLAC-Extension/main/registry.json"
-	cacheTTL           = 30 * time.Minute
-	cacheFileName      = "store_cache.json"
+	cacheTTL      = 30 * time.Minute
+	cacheFileName = "store_cache.json"
 )
 
-func InitExtensionStore(cacheDir string) *ExtensionStore {
+func initExtensionStore(cacheDir string) *extensionStore {
 	extensionStoreMu.Lock()
 	defer extensionStoreMu.Unlock()
 
-	if extensionStore == nil {
-		extensionStore = &ExtensionStore{
-			registryURL: defaultRegistryURL,
+	if globalExtensionStore == nil {
+		globalExtensionStore = &extensionStore{
+			registryURL: "",
 			cacheDir:    cacheDir,
 			cacheTTL:    cacheTTL,
 		}
-		extensionStore.loadDiskCache()
+		globalExtensionStore.loadDiskCache()
 	}
-	return extensionStore
+	return globalExtensionStore
 }
 
-func GetExtensionStore() *ExtensionStore {
+func (s *extensionStore) setRegistryURL(registryURL string) {
+	s.cacheMu.Lock()
+	defer s.cacheMu.Unlock()
+
+	if s.registryURL == registryURL {
+		return
+	}
+
+	s.registryURL = registryURL
+	s.cache = nil
+	s.cacheTime = time.Time{}
+
+	if s.cacheDir != "" {
+		cachePath := filepath.Join(s.cacheDir, cacheFileName)
+		os.Remove(cachePath)
+	}
+
+	LogInfo("ExtensionStore", "Registry URL updated to: %s", registryURL)
+}
+
+func (s *extensionStore) getRegistryURL() string {
+	s.cacheMu.RLock()
+	defer s.cacheMu.RUnlock()
+	return s.registryURL
+}
+
+func getExtensionStore() *extensionStore {
 	extensionStoreMu.Lock()
 	defer extensionStoreMu.Unlock()
-	return extensionStore
+	return globalExtensionStore
 }
 
-func (s *ExtensionStore) loadDiskCache() {
+func (s *extensionStore) loadDiskCache() {
 	if s.cacheDir == "" {
 		return
 	}
@@ -168,7 +195,7 @@ func (s *ExtensionStore) loadDiskCache() {
 	}
 
 	var cacheData struct {
-		Registry  StoreRegistry `json:"registry"`
+		Registry  storeRegistry `json:"registry"`
 		CacheTime int64         `json:"cache_time"`
 	}
 
@@ -181,13 +208,13 @@ func (s *ExtensionStore) loadDiskCache() {
 	LogDebug("ExtensionStore", "Loaded %d extensions from disk cache", len(s.cache.Extensions))
 }
 
-func (s *ExtensionStore) saveDiskCache() {
+func (s *extensionStore) saveDiskCache() {
 	if s.cacheDir == "" || s.cache == nil {
 		return
 	}
 
 	cacheData := struct {
-		Registry  StoreRegistry `json:"registry"`
+		Registry  storeRegistry `json:"registry"`
 		CacheTime int64         `json:"cache_time"`
 	}{
 		Registry:  *s.cache,
@@ -203,10 +230,14 @@ func (s *ExtensionStore) saveDiskCache() {
 	os.WriteFile(cachePath, data, 0644)
 }
 
-func (s *ExtensionStore) FetchRegistry(forceRefresh bool) (*StoreRegistry, error) {
+func (s *extensionStore) fetchRegistry(forceRefresh bool) (*storeRegistry, error) {
 	s.cacheMu.Lock()
 	defer s.cacheMu.Unlock()
 
+	if s.registryURL == "" {
+		return nil, fmt.Errorf("no registry URL configured. Please add a repository URL first")
+	}
+
 	if !forceRefresh && s.cache != nil && time.Since(s.cacheTime) < s.cacheTTL {
 		LogDebug("ExtensionStore", "Using cached registry (%d extensions)", len(s.cache.Extensions))
 		return s.cache, nil
@@ -218,8 +249,18 @@ func (s *ExtensionStore) FetchRegistry(forceRefresh bool) (*StoreRegistry, error
 
 	LogInfo("ExtensionStore", "Fetching registry from %s", s.registryURL)
 
-	client := &http.Client{Timeout: 30 * time.Second}
-	resp, err := client.Get(s.registryURL)
+	client := NewHTTPClientWithTimeout(30 * time.Second)
+	req, err := http.NewRequest(http.MethodGet, s.registryURL, nil)
+	if err != nil {
+		if s.cache != nil {
+			LogWarn("ExtensionStore", "Failed to build registry request, using cached registry: %v", err)
+			return s.cache, nil
+		}
+		return nil, fmt.Errorf("failed to build registry request: %w", err)
+	}
+	req.Header.Set("Cache-Control", "no-cache")
+	req.Header.Set("Pragma", "no-cache")
+	resp, err := client.Do(req)
 	if err != nil {
 		if s.cache != nil {
 			LogWarn("ExtensionStore", "Network error, using cached registry: %v", err)
@@ -242,7 +283,7 @@ func (s *ExtensionStore) FetchRegistry(forceRefresh bool) (*StoreRegistry, error
 		return nil, fmt.Errorf("failed to read registry: %w", err)
 	}
 
-	var registry StoreRegistry
+	var registry storeRegistry
 	if err := json.Unmarshal(body, &registry); err != nil {
 		return nil, fmt.Errorf("failed to parse registry: %w", err)
 	}
@@ -255,13 +296,13 @@ func (s *ExtensionStore) FetchRegistry(forceRefresh bool) (*StoreRegistry, error
 	return &registry, nil
 }
 
-func (s *ExtensionStore) GetExtensionsWithStatus() ([]StoreExtensionResponse, error) {
-	registry, err := s.FetchRegistry(false)
+func (s *extensionStore) getExtensionsWithStatus(forceRefresh bool) ([]storeExtensionResponse, error) {
+	registry, err := s.fetchRegistry(forceRefresh)
 	if err != nil {
 		return nil, err
 	}
 
-	manager := GetExtensionManager()
+	manager := getExtensionManager()
 	installed := make(map[string]string) // id -> version
 
 	if manager != nil {
@@ -270,29 +311,32 @@ func (s *ExtensionStore) GetExtensionsWithStatus() ([]StoreExtensionResponse, er
 		}
 	}
 
-	result := make([]StoreExtensionResponse, len(registry.Extensions))
-	for i, ext := range registry.Extensions {
-		resp := ext.ToResponse()
+	LogDebug("ExtensionStore", "Building store response for %d registry extensions (%d installed)", len(registry.Extensions), len(installed))
 
+	result := make([]storeExtensionResponse, 0, len(registry.Extensions))
+	for i := range registry.Extensions {
+		ext := &registry.Extensions[i]
+		resp := ext.toResponse()
 		if installedVersion, ok := installed[ext.ID]; ok {
 			resp.IsInstalled = true
 			resp.InstalledVersion = installedVersion
 			resp.HasUpdate = compareVersions(ext.Version, installedVersion) > 0
 		}
 
-		result[i] = resp
+		result = append(result, resp)
 	}
 
+	LogDebug("ExtensionStore", "Built store response payload for %d extensions", len(result))
 	return result, nil
 }
 
-func (s *ExtensionStore) DownloadExtension(extensionID string, destPath string) error {
-	registry, err := s.FetchRegistry(false)
+func (s *extensionStore) downloadExtension(extensionID string, destPath string) error {
+	registry, err := s.fetchRegistry(false)
 	if err != nil {
 		return err
 	}
 
-	var ext *StoreExtension
+	var ext *storeExtension
 	for _, e := range registry.Extensions {
 		if e.ID == extensionID {
 			ext = &e
@@ -310,8 +354,14 @@ func (s *ExtensionStore) DownloadExtension(extensionID string, destPath string)
 
 	LogInfo("ExtensionStore", "Downloading %s from %s", ext.getDisplayName(), ext.getDownloadURL())
 
-	client := &http.Client{Timeout: 5 * time.Minute}
-	resp, err := client.Get(ext.getDownloadURL())
+	client := NewHTTPClientWithTimeout(5 * time.Minute)
+	req, err := http.NewRequest(http.MethodGet, ext.getDownloadURL(), nil)
+	if err != nil {
+		return fmt.Errorf("failed to build download request: %w", err)
+	}
+	req.Header.Set("Cache-Control", "no-cache")
+	req.Header.Set("Pragma", "no-cache")
+	resp, err := client.Do(req)
 	if err != nil {
 		return fmt.Errorf("failed to download: %w", err)
 	}
@@ -337,6 +387,68 @@ func (s *ExtensionStore) DownloadExtension(extensionID string, destPath string)
 	return nil
 }
 
+func resolveRegistryURL(input string) (string, error) {
+	input = strings.TrimSpace(input)
+	if input == "" {
+		return "", fmt.Errorf("registry URL is empty")
+	}
+
+	if strings.Contains(input, "raw.githubusercontent.com") {
+		return input, nil
+	}
+
+	const ghPrefix = "https://github.com/"
+	if !strings.HasPrefix(input, ghPrefix) {
+		const ghPrefixHTTP = "http://github.com/"
+		if strings.HasPrefix(input, ghPrefixHTTP) {
+			input = "https://github.com/" + input[len(ghPrefixHTTP):]
+		} else {
+			return input, nil
+		}
+	}
+
+	path := input[len(ghPrefix):]
+	parts := strings.SplitN(path, "/", 3) // owner, repo, [rest]
+	if len(parts) < 2 || parts[0] == "" || parts[1] == "" {
+		return "", fmt.Errorf("invalid GitHub URL: expected github.com/<owner>/<repo>")
+	}
+	owner := parts[0]
+	repo := strings.TrimSuffix(parts[1], ".git")
+
+	branch := resolveGitHubDefaultBranch(owner, repo)
+
+	resolved := fmt.Sprintf("https://raw.githubusercontent.com/%s/%s/%s/registry.json", owner, repo, branch)
+	LogInfo("ExtensionStore", "Resolved %s → %s (branch: %s)", input, resolved, branch)
+	return resolved, nil
+}
+
+func resolveGitHubDefaultBranch(owner, repo string) string {
+	apiURL := fmt.Sprintf("https://api.github.com/repos/%s/%s", owner, repo)
+	client := NewHTTPClientWithTimeout(10 * time.Second)
+
+	resp, err := client.Get(apiURL)
+	if err != nil {
+		LogWarn("ExtensionStore", "GitHub API request failed for %s/%s: %v – falling back to main", owner, repo, err)
+		return "main"
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		LogWarn("ExtensionStore", "GitHub API returned %d for %s/%s – falling back to main", resp.StatusCode, owner, repo)
+		return "main"
+	}
+
+	var info struct {
+		DefaultBranch string `json:"default_branch"`
+	}
+	if err := json.NewDecoder(resp.Body).Decode(&info); err != nil || info.DefaultBranch == "" {
+		LogWarn("ExtensionStore", "Could not parse default_branch for %s/%s – falling back to main", owner, repo)
+		return "main"
+	}
+
+	return info.DefaultBranch
+}
+
 func requireHTTPSURL(rawURL string, context string) error {
 	if rawURL == "" {
 		return fmt.Errorf("%s URL is empty", context)
@@ -351,7 +463,7 @@ func requireHTTPSURL(rawURL string, context string) error {
 	return nil
 }
 
-func (s *ExtensionStore) GetCategories() []string {
+func (s *extensionStore) getCategories() []string {
 	return []string{
 		CategoryMetadata,
 		CategoryDownload,
@@ -361,8 +473,8 @@ func (s *ExtensionStore) GetCategories() []string {
 	}
 }
 
-func (s *ExtensionStore) SearchExtensions(query string, category string) ([]StoreExtensionResponse, error) {
-	extensions, err := s.GetExtensionsWithStatus()
+func (s *extensionStore) searchExtensions(query string, category string) ([]storeExtensionResponse, error) {
+	extensions, err := s.getExtensionsWithStatus(false)
 	if err != nil {
 		return nil, err
 	}
@@ -371,22 +483,18 @@ func (s *ExtensionStore) SearchExtensions(query string, category string) ([]Stor
 		return extensions, nil
 	}
 
-	var result []StoreExtensionResponse
+	result := make([]storeExtensionResponse, 0, len(extensions))
 	queryLower := toLower(query)
 
 	for _, ext := range extensions {
-		// Filter by category
 		if category != "" && ext.Category != category {
 			continue
 		}
 
-		// Filter by query
 		if query != "" {
 			if !containsIgnoreCase(ext.Name, queryLower) &&
 				!containsIgnoreCase(ext.DisplayName, queryLower) &&
-				!containsIgnoreCase(ext.Description, queryLower) &&
-				!containsIgnoreCase(ext.Author, queryLower) {
-				// Check tags
+				!containsIgnoreCase(ext.Description, queryLower) {
 				found := false
 				for _, tag := range ext.Tags {
 					if containsIgnoreCase(tag, queryLower) {
@@ -406,7 +514,7 @@ func (s *ExtensionStore) SearchExtensions(query string, category string) ([]Stor
 	return result, nil
 }
 
-func (s *ExtensionStore) ClearCache() {
+func (s *extensionStore) clearCache() {
 	s.cacheMu.Lock()
 	defer s.cacheMu.Unlock()
 
@@ -421,7 +529,6 @@ func (s *ExtensionStore) ClearCache() {
 	LogInfo("ExtensionStore", "Cache cleared")
 }
 
-// Helper: case-insensitive contains
 func containsIgnoreCase(s, substr string) bool {
 	return containsStr(toLower(s), substr)
 }

go_backend/extension_test.go

@@ -1,8 +1,10 @@
 package gobackend
 
 import (
+	"net/http"
 	"path/filepath"
 	"testing"
+	"time"
 
 	"github.com/dop251/goja"
 )
@@ -12,7 +14,6 @@ func TestParseManifest_Valid(t *testing.T) {
 		"name": "test-provider",
 		"displayName": "Test Provider",
 		"version": "1.0.0",
-		"author": "Test Author",
 		"description": "A test extension",
 		"type": ["metadata_provider"],
 		"permissions": {
@@ -46,7 +47,6 @@ func TestParseManifest_Valid(t *testing.T) {
 func TestParseManifest_MissingName(t *testing.T) {
 	invalidManifest := `{
 		"version": "1.0.0",
-		"author": "Test Author",
 		"description": "A test extension",
 		"type": ["metadata_provider"]
 	}`
@@ -61,7 +61,6 @@ func TestParseManifest_MissingType(t *testing.T) {
 	invalidManifest := `{
 		"name": "test-provider",
 		"version": "1.0.0",
-		"author": "Test Author",
 		"description": "A test extension"
 	}`
 
@@ -99,7 +98,7 @@ func TestIsDomainAllowed(t *testing.T) {
 
 func TestExtensionRuntime_NetworkSandbox(t *testing.T) {
 	// Create a mock extension with limited network permissions
-	ext := &LoadedExtension{
+	ext := &loadedExtension{
 		ID: "test-ext",
 		Manifest: &ExtensionManifest{
 			Name: "test-ext",
@@ -110,7 +109,7 @@ func TestExtensionRuntime_NetworkSandbox(t *testing.T) {
 		DataDir: t.TempDir(),
 	}
 
-	runtime := NewExtensionRuntime(ext)
+	runtime := newExtensionRuntime(ext)
 
 	if err := runtime.validateDomain("https://api.allowed.com/path"); err != nil {
 		t.Errorf("Expected api.allowed.com to be allowed, got error: %v", err)
@@ -132,7 +131,7 @@ func TestExtensionRuntime_NetworkSandbox(t *testing.T) {
 func TestExtensionRuntime_FileSandbox(t *testing.T) {
 	tempDir := t.TempDir()
 
-	ext := &LoadedExtension{
+	ext := &loadedExtension{
 		ID: "test-ext",
 		Manifest: &ExtensionManifest{
 			Name: "test-ext",
@@ -143,7 +142,7 @@ func TestExtensionRuntime_FileSandbox(t *testing.T) {
 		DataDir: tempDir,
 	}
 
-	runtime := NewExtensionRuntime(ext)
+	runtime := newExtensionRuntime(ext)
 
 	validPath, err := runtime.validatePath("test.txt")
 	if err != nil {
@@ -177,7 +176,7 @@ func TestExtensionRuntime_FileSandbox(t *testing.T) {
 		t.Error("Expected absolute path to be blocked")
 	}
 
-	extNoFile := &LoadedExtension{
+	extNoFile := &loadedExtension{
 		ID: "test-ext-no-file",
 		Manifest: &ExtensionManifest{
 			Name: "test-ext-no-file",
@@ -187,7 +186,7 @@ func TestExtensionRuntime_FileSandbox(t *testing.T) {
 		},
 		DataDir: tempDir,
 	}
-	runtimeNoFile := NewExtensionRuntime(extNoFile)
+	runtimeNoFile := newExtensionRuntime(extNoFile)
 	_, err = runtimeNoFile.validatePath("test.txt")
 	if err == nil {
 		t.Error("Expected file access to be denied without file permission")
@@ -195,7 +194,7 @@ func TestExtensionRuntime_FileSandbox(t *testing.T) {
 }
 
 func TestExtensionRuntime_UtilityFunctions(t *testing.T) {
-	ext := &LoadedExtension{
+	ext := &loadedExtension{
 		ID: "test-ext",
 		Manifest: &ExtensionManifest{
 			Name: "test-ext",
@@ -203,7 +202,7 @@ func TestExtensionRuntime_UtilityFunctions(t *testing.T) {
 		DataDir: t.TempDir(),
 	}
 
-	runtime := NewExtensionRuntime(ext)
+	runtime := newExtensionRuntime(ext)
 	vm := goja.New()
 	runtime.RegisterAPIs(vm)
 
@@ -239,11 +238,133 @@ func TestExtensionRuntime_UtilityFunctions(t *testing.T) {
 	if result.String() == "" {
 		t.Error("Expected non-empty JSON string")
 	}
+
+	result, err = vm.RunString(`utils.sleep(1)`)
+	if err != nil {
+		t.Fatalf("sleep failed: %v", err)
+	}
+	if !result.ToBoolean() {
+		t.Error("Expected sleep to complete successfully")
+	}
+
+	runtime.setActiveDownloadItemID("test-item")
+	cancelDownload("test-item")
+	t.Cleanup(func() {
+		clearDownloadCancel("test-item")
+		runtime.clearActiveDownloadItemID()
+	})
+
+	result, err = vm.RunString(`utils.isDownloadCancelled()`)
+	if err != nil {
+		t.Fatalf("isDownloadCancelled failed: %v", err)
+	}
+	if !result.ToBoolean() {
+		t.Error("Expected active download cancellation to be visible to JS")
+	}
+
+	SetAppVersion("4.2.2")
+	t.Cleanup(func() {
+		SetAppVersion("")
+	})
+
+	result, err = vm.RunString(`utils.appVersion()`)
+	if err != nil {
+		t.Fatalf("appVersion failed: %v", err)
+	}
+	if got := result.String(); got != "4.2.2" {
+		t.Fatalf("Expected appVersion 4.2.2, got %q", got)
+	}
+
+	result, err = vm.RunString(`utils.appUserAgent()`)
+	if err != nil {
+		t.Fatalf("appUserAgent failed: %v", err)
+	}
+	if got := result.String(); got != "SpotiFLAC-Mobile/4.2.2" {
+		t.Fatalf("Expected appUserAgent SpotiFLAC-Mobile/4.2.2, got %q", got)
+	}
+
+	result, err = vm.RunString(`utils.sleep(50)`)
+	if err != nil {
+		t.Fatalf("cancel-aware sleep failed: %v", err)
+	}
+	if result.ToBoolean() {
+		t.Error("Expected sleep to abort when download is cancelled")
+	}
+}
+
+func TestExtensionRuntime_BindDownloadCancelContext(t *testing.T) {
+	ext := &loadedExtension{
+		ID: "test-ext",
+		Manifest: &ExtensionManifest{
+			Name: "test-ext",
+		},
+		DataDir: t.TempDir(),
+	}
+
+	runtime := newExtensionRuntime(ext)
+	runtime.setActiveDownloadItemID("test-item")
+	t.Cleanup(func() {
+		clearDownloadCancel("test-item")
+		runtime.clearActiveDownloadItemID()
+	})
+
+	req, err := http.NewRequest("GET", "https://api.example.com/test", nil)
+	if err != nil {
+		t.Fatalf("NewRequest failed: %v", err)
+	}
+
+	req = runtime.bindDownloadCancelContext(req)
+	cancelDownload("test-item")
+
+	select {
+	case <-req.Context().Done():
+	case <-time.After(500 * time.Millisecond):
+		t.Fatal("Expected bound request context to be cancelled")
+	}
+
+	if req.Context().Err() == nil {
+		t.Fatal("Expected request context error after cancellation")
+	}
+}
+
+func TestExtensionRuntime_BindDownloadCancelContextPreservesPreCancelledState(t *testing.T) {
+	ext := &loadedExtension{
+		ID: "test-ext",
+		Manifest: &ExtensionManifest{
+			Name: "test-ext",
+		},
+		DataDir: t.TempDir(),
+	}
+
+	runtime := newExtensionRuntime(ext)
+	runtime.setActiveDownloadItemID("test-item")
+	cancelDownload("test-item")
+	t.Cleanup(func() {
+		clearDownloadCancel("test-item")
+		runtime.clearActiveDownloadItemID()
+	})
+
+	req, err := http.NewRequest("GET", "https://api.example.com/test", nil)
+	if err != nil {
+		t.Fatalf("NewRequest failed: %v", err)
+	}
+
+	req = runtime.bindDownloadCancelContext(req)
+
+	select {
+	case <-req.Context().Done():
+	case <-time.After(500 * time.Millisecond):
+		t.Fatal("Expected pre-cancelled request context to stay cancelled")
+	}
+
+	if req.Context().Err() == nil {
+		t.Fatal("Expected request context error for pre-cancelled item")
+	}
 }
 
 func TestExtensionRuntime_SSRFProtection(t *testing.T) {
 	// Create extension with limited network permissions
-	ext := &LoadedExtension{
+	ext := &loadedExtension{
 		ID: "test-ext",
 		Manifest: &ExtensionManifest{
 			Name: "test-ext",
@@ -254,7 +375,7 @@ func TestExtensionRuntime_SSRFProtection(t *testing.T) {
 		DataDir: t.TempDir(),
 	}
 
-	runtime := NewExtensionRuntime(ext)
+	runtime := newExtensionRuntime(ext)
 
 	privateIPs := []string{
 		"http://localhost/admin",

go_backend/extension_timeout.go

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

go_backend/filename.go

@@ -3,28 +3,60 @@ package gobackend
 import (
 	"fmt"
 	"regexp"
+	"strconv"
 	"strings"
+	"time"
+	"unicode"
+	"unicode/utf8"
 )
 
-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.ReplaceAll(filename, "/", " ")
+	sanitized = invalidChars.ReplaceAllString(sanitized, " ")
+
+	var builder strings.Builder
+	for _, r := range sanitized {
+		if r < 0x20 && r != 0x09 && r != 0x0A && r != 0x0D {
+			continue
+		}
+		if r == 0x7F {
+			continue
+		}
+		if unicode.IsControl(r) && r != 0x09 && r != 0x0A && r != 0x0D {
+			continue
+		}
+		builder.WriteRune(r)
+	}
+
+	sanitized = builder.String()
 	sanitized = strings.TrimSpace(sanitized)
-	sanitized = strings.Trim(sanitized, ".")
-	
-	multiUnderscore := regexp.MustCompile(`_+`)
+	sanitized = strings.Trim(sanitized, ". ")
+	sanitized = strings.Join(strings.Fields(sanitized), " ")
 	sanitized = multiUnderscore.ReplaceAllString(sanitized, "_")
-	
+	sanitized = strings.Trim(sanitized, "_ ")
+
+	if !utf8.ValidString(sanitized) {
+		sanitized = strings.ToValidUTF8(sanitized, "_")
+	}
+
 	if len(sanitized) > 200 {
 		sanitized = sanitized[:200]
+		sanitized = strings.TrimSpace(strings.Trim(sanitized, ". "))
+		sanitized = strings.Trim(sanitized, "_ ")
 	}
-	
+
 	if sanitized == "" {
-		sanitized = "untitled"
+		return "Unknown"
 	}
-	
+
 	return sanitized
 }
 
@@ -32,45 +64,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 +195,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]

go_backend/filename_test.go

@@ -0,0 +1,100 @@
+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)
+	}
+}
+
+func TestSanitizeFilenameMatchesDesktopSpacingBehavior(t *testing.T) {
+	got := sanitizeFilename(`  "Text In Quotes"?%* / Demo  `)
+	want := "Text In Quotes % Demo"
+	if got != want {
+		t.Fatalf("expected %q, got %q", want, got)
+	}
+}
+
+func TestSanitizeFilenameFallsBackToUnknownWhenEmpty(t *testing.T) {
+	got := sanitizeFilename(`<>:"/\|?*`)
+	if got != "Unknown" {
+		t.Fatalf("expected %q, got %q", "Unknown", got)
+	}
+}

go_backend/go.mod

@@ -2,28 +2,28 @@ module github.com/zarz/spotiflac_android/go_backend
 
 go 1.25.0
 
-toolchain go1.25.6
+toolchain go1.25.8
 
 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-20260311135729-065cd970411c
+	github.com/go-flac/flacpicture/v2 v2.0.2
+	github.com/go-flac/flacvorbis/v2 v2.0.2
+	github.com/go-flac/go-flac/v2 v2.0.4
 	github.com/refraction-networking/utls v1.8.2
-	golang.org/x/mobile v0.0.0-20260120165949-40bd9ace6ce4
-	golang.org/x/net v0.49.0
+	golang.org/x/mobile v0.0.0-20260312152759-81488f6aeb60
+	golang.org/x/net v0.52.0
+	golang.org/x/text v0.35.0
 )
 
 require (
-	github.com/andybalholm/brotli v1.0.6 // indirect
-	github.com/dlclark/regexp2 v1.11.4 // indirect
-	github.com/go-sourcemap/sourcemap v2.1.3+incompatible // indirect
-	github.com/google/pprof v0.0.0-20230207041349-798e818bf904 // indirect
-	github.com/klauspost/compress v1.17.4 // indirect
-	golang.org/x/crypto v0.47.0 // indirect
-	golang.org/x/mod v0.32.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
+	github.com/andybalholm/brotli v1.2.0 // indirect
+	github.com/dlclark/regexp2 v1.11.5 // indirect
+	github.com/go-sourcemap/sourcemap v2.1.4+incompatible // indirect
+	github.com/google/pprof v0.0.0-20260302011040-a15ffb7f9dcc // indirect
+	github.com/klauspost/compress v1.18.5 // indirect
+	golang.org/x/crypto v0.49.0 // indirect
+	golang.org/x/mod v0.34.0 // indirect
+	golang.org/x/sync v0.20.0 // indirect
+	golang.org/x/sys v0.42.0 // indirect
+	golang.org/x/tools v0.43.0 // indirect
 )

go_backend/go.sum

@@ -1,42 +1,52 @@
 github.com/Masterminds/semver/v3 v3.2.1 h1:RN9w6+7QoMeJVGyfmbcgs28Br8cvmnucEXnY0rYXWg0=
 github.com/Masterminds/semver/v3 v3.2.1/go.mod h1:qvl/7zhW3nngYb5+80sSMF+FG2BjYrf8m9wsX0PNOMQ=
-github.com/andybalholm/brotli v1.0.6 h1:Yf9fFpf49Zrxb9NlQaluyE92/+X7UVHlhMNJN2sxfOI=
-github.com/andybalholm/brotli v1.0.6/go.mod h1:fO7iG3H7G2nSZ7m0zPUDn85XEX2GTukHGRSepvi9Eig=
-github.com/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/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/andybalholm/brotli v1.2.0 h1:ukwgCxwYrmACq68yiUqwIWnGY0cTPox/M94sVwToPjQ=
+github.com/andybalholm/brotli v1.2.0/go.mod h1:rzTDkvFWvIrjDXZHkuS16NPggd91W3kUSvPlQ1pLaKY=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/dlclark/regexp2 v1.11.5 h1:Q/sSnsKerHeCkc/jSTNq1oCm7KiVgUMZRDUoRu0JQZQ=
+github.com/dlclark/regexp2 v1.11.5/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8=
+github.com/dop251/goja v0.0.0-20260311135729-065cd970411c h1:OcLmPfx1T1RmZVHHFwWMPaZDdRf0DBMZOFMVWJa7Pdk=
+github.com/dop251/goja v0.0.0-20260311135729-065cd970411c/go.mod h1:MxLav0peU43GgvwVgNbLAj1s/bSGboKkhuULvq/7hx4=
+github.com/go-flac/flacpicture/v2 v2.0.2 h1:HCaJIVZpxnpdWs6G3ECEVRelzqS5xOi1Ba1AGmtXbzE=
+github.com/go-flac/flacpicture/v2 v2.0.2/go.mod h1:DMZBPWPAmdLqNhqFSy5ZBs9wyBzOekXutGfP7/TFCuo=
+github.com/go-flac/flacvorbis/v2 v2.0.2 h1:xCL3OhxrxWkHrbWUBvGNe+6FQ03yLmBbz0v5z4V2PoQ=
+github.com/go-flac/flacvorbis/v2 v2.0.2/go.mod h1:SwTB5gs13VaM/N7rstwPoUsPibiMKklgwybYP9dYo2g=
+github.com/go-flac/go-flac/v2 v2.0.4 h1:atf/kFa8U9idtkA//NO22XGr+MzQLeXZecnmP9sYBf0=
+github.com/go-flac/go-flac/v2 v2.0.4/go.mod h1:sYOlTKxutMW0RDYF+KlD6Zn+VOCZlIFQG/r/usPveCs=
+github.com/go-sourcemap/sourcemap v2.1.4+incompatible h1:a+iTbH5auLKxaNwQFg0B+TCYl6lbukKPc7b5x0n1s6Q=
+github.com/go-sourcemap/sourcemap v2.1.4+incompatible/go.mod h1:F8jJfvm2KbVjc5NqelyYJmf/v5J0dwNLS2mL4sNA1Jg=
 github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
 github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
-github.com/google/pprof v0.0.0-20230207041349-798e818bf904 h1:4/hN5RUoecvl+RmJRE2YxKWtnnQls6rQjjW5oV7qg2U=
-github.com/google/pprof v0.0.0-20230207041349-798e818bf904/go.mod h1:uglQLonpP8qtYCYyzA+8c/9qtqgA3qsXGYqCPKARAFg=
-github.com/klauspost/compress v1.17.4 h1:Ej5ixsIri7BrIjBkRZLTo6ghwrEtHFk7ijlczPW4fZ4=
-github.com/klauspost/compress v1.17.4/go.mod h1:/dCuZOvVtNoHsyb+cuJD3itjs3NbnF6KH9zAO4BDxPM=
+github.com/google/pprof v0.0.0-20260302011040-a15ffb7f9dcc h1:VBbFa1lDYWEeV5FZKUiYKYT0VxCp9twUmmaq9eb8sXw=
+github.com/google/pprof v0.0.0-20260302011040-a15ffb7f9dcc/go.mod h1:MxpfABSjhmINe3F1It9d+8exIHFvUqtLIRCdOGNXqiI=
+github.com/klauspost/compress v1.18.5 h1:/h1gH5Ce+VWNLSWqPzOVn6XBO+vJbCNGvjoaGBFW2IE=
+github.com/klauspost/compress v1.18.5/go.mod h1:cwPg85FWrGar70rWktvGQj8/hthj3wpl0PGDogxkrSQ=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/refraction-networking/utls v1.8.2 h1:j4Q1gJj0xngdeH+Ox/qND11aEfhpgoEvV+S9iJ2IdQo=
 github.com/refraction-networking/utls v1.8.2/go.mod h1:jkSOEkLqn+S/jtpEHPOsVv/4V4EVnelwbMQl4vCWXAM=
-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/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/net v0.49.0 h1:eeHFmOGUTtaaPSGNmjBKpbng9MulQsJURQUAfUwY++o=
-golang.org/x/net v0.49.0/go.mod h1:/ysNB2EvaqvesRkuLAyjI1ycPZlQHM3q01F02UY/MV8=
-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/text v0.33.0 h1:B3njUFyqtHDUI5jMn1YIr5B0IE2U0qck04r6d4KPAxE=
-golang.org/x/text v0.33.0/go.mod h1:LuMebE6+rBincTi9+xWTY8TztLzKHc/9C1uBCG27+q8=
-golang.org/x/tools v0.41.0 h1:a9b8iMweWG+S0OBnlU36rzLp20z1Rp10w+IY2czHTQc=
-golang.org/x/tools v0.41.0/go.mod h1:XSY6eDqxVNiYgezAVqqCeihT4j1U2CCsqvH3WhQpnlg=
+github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA=
+github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
+github.com/xyproto/randomstring v1.0.5 h1:YtlWPoRdgMu3NZtP45drfy1GKoojuR7hmRcnhZqKjWU=
+github.com/xyproto/randomstring v1.0.5/go.mod h1:rgmS5DeNXLivK7YprL0pY+lTuhNQW3iGxZ18UQApw/E=
+golang.org/x/crypto v0.49.0 h1:+Ng2ULVvLHnJ/ZFEq4KdcDd/cfjrrjjNSXNzxg0Y4U4=
+golang.org/x/crypto v0.49.0/go.mod h1:ErX4dUh2UM+CFYiXZRTcMpEcN8b/1gxEuv3nODoYtCA=
+golang.org/x/mobile v0.0.0-20260312152759-81488f6aeb60 h1:MOzyaj0wu2xneBkzkg9LHNYjDBB4W5vP043A2SYQRPA=
+golang.org/x/mobile v0.0.0-20260312152759-81488f6aeb60/go.mod h1:th6VJvzjMbrYF8SduQY5rpD0HG0GleGxjadkqSxFs3k=
+golang.org/x/mod v0.34.0 h1:xIHgNUUnW6sYkcM5Jleh05DvLOtwc6RitGHbDk4akRI=
+golang.org/x/mod v0.34.0/go.mod h1:ykgH52iCZe79kzLLMhyCUzhMci+nQj+0XkbXpNYtVjY=
+golang.org/x/net v0.52.0 h1:He/TN1l0e4mmR3QqHMT2Xab3Aj3L9qjbhRm78/6jrW0=
+golang.org/x/net v0.52.0/go.mod h1:R1MAz7uMZxVMualyPXb+VaqGSa3LIaUqk0eEt3w36Sw=
+golang.org/x/sync v0.20.0 h1:e0PTpb7pjO8GAtTs2dQ6jYa5BWYlMuX047Dco/pItO4=
+golang.org/x/sync v0.20.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
+golang.org/x/sys v0.42.0 h1:omrd2nAlyT5ESRdCLYdm3+fMfNFE/+Rf4bDIQImRJeo=
+golang.org/x/sys v0.42.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/text v0.35.0 h1:JOVx6vVDFokkpaq1AEptVzLTpDe9KGpj5tR4/X+ybL8=
+golang.org/x/text v0.35.0/go.mod h1:khi/HExzZJ2pGnjenulevKNX1W67CUy0AsXcNubPGCA=
+golang.org/x/tools v0.43.0 h1:12BdW9CeB3Z+J/I/wj34VMl8X+fEXBxVR90JeMX5E7s=
+golang.org/x/tools v0.43.0/go.mod h1:uHkMso649BX2cZK6+RpuIPXS3ho2hZo4FVwfoy1vIk0=
 gopkg.in/yaml.v2 v2.4.0 h1:D8xgwECY7CYvx+Y2n4sBz93Jn9JRvxdiyyo8CTfuKaY=
 gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

go_backend/httputil.go

@@ -11,10 +11,24 @@ import (
 	"net/url"
 	"strconv"
 	"strings"
+	"sync"
 	"syscall"
 	"time"
 )
 
+func userAgentForURL(u *url.URL) string {
+	if u == nil {
+		return getRandomUserAgent()
+	}
+
+	host := strings.ToLower(strings.TrimSpace(u.Hostname()))
+	if host == "api.zarz.moe" {
+		return appUserAgent()
+	}
+
+	return getRandomUserAgent()
+}
+
 func getRandomUserAgent() string {
 	chromeVersion := rand.Intn(26) + 120
 	chromeBuild := rand.Intn(1500) + 6000
@@ -30,13 +44,23 @@ func getRandomUserAgent() string {
 
 const (
 	DefaultTimeout    = 60 * time.Second
-	DownloadTimeout   = 120 * time.Second
+	DownloadTimeout   = 24 * time.Hour
 	SongLinkTimeout   = 30 * time.Second
 	DefaultMaxRetries = 3
 	DefaultRetryDelay = 1 * time.Second
 	Second            = time.Second
 )
 
+type NetworkCompatibilityOptions struct {
+	AllowHTTP   bool
+	InsecureTLS bool
+}
+
+var (
+	networkCompatibilityMu      sync.RWMutex
+	networkCompatibilityOptions NetworkCompatibilityOptions
+)
+
 var sharedTransport = &http.Transport{
 	DialContext: (&net.Dialer{
 		Timeout:   30 * time.Second,
@@ -55,19 +79,44 @@ var sharedTransport = &http.Transport{
 	DisableCompression:    true,
 }
 
+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,
+	}
+}
+
+func NewMetadataHTTPClient(timeout time.Duration) *http.Client {
+	return &http.Client{
+		Transport: newCompatibilityTransport(metadataTransport),
 		Timeout:   timeout,
 	}
 }
@@ -82,11 +131,114 @@ func GetDownloadClient() *http.Client {
 
 func CloseIdleConnections() {
 	sharedTransport.CloseIdleConnections()
+	metadataTransport.CloseIdleConnections()
+}
+
+func SetNetworkCompatibilityOptions(allowHTTP, insecureTLS bool) {
+	networkCompatibilityMu.Lock()
+	networkCompatibilityOptions = NetworkCompatibilityOptions{
+		AllowHTTP:   allowHTTP,
+		InsecureTLS: insecureTLS,
+	}
+	networkCompatibilityMu.Unlock()
+
+	applyTLSCompatibility(sharedTransport, insecureTLS)
+	applyTLSCompatibility(metadataTransport, insecureTLS)
+	CloseIdleConnections()
+
+	GoLog("[HTTP] Network compatibility options updated: allow_http=%v insecure_tls=%v\n", allowHTTP, insecureTLS)
+}
+
+func GetNetworkCompatibilityOptions() NetworkCompatibilityOptions {
+	networkCompatibilityMu.RLock()
+	defer networkCompatibilityMu.RUnlock()
+	return networkCompatibilityOptions
+}
+
+func applyTLSCompatibility(transport *http.Transport, insecureTLS bool) {
+	if insecureTLS {
+		cfg := &tls.Config{InsecureSkipVerify: true}
+		if transport.TLSClientConfig != nil {
+			cfg = transport.TLSClientConfig.Clone()
+			cfg.InsecureSkipVerify = true
+		}
+		transport.TLSClientConfig = cfg
+		return
+	}
+
+	transport.TLSClientConfig = nil
+}
+
+type compatibilityTransport struct {
+	base http.RoundTripper
+}
+
+func newCompatibilityTransport(base http.RoundTripper) http.RoundTripper {
+	return &compatibilityTransport{base: base}
+}
+
+func (t *compatibilityTransport) RoundTrip(req *http.Request) (*http.Response, error) {
+	if req == nil || req.URL == nil {
+		return t.base.RoundTrip(req)
+	}
+
+	opts := GetNetworkCompatibilityOptions()
+	if !opts.AllowHTTP || req.URL.Scheme != "https" {
+		return t.base.RoundTrip(req)
+	}
+
+	// Compatibility mode should prefer HTTPS and only fallback to HTTP on
+	// transport-level failures. Forcing HTTP unconditionally can trigger
+	// redirect loops (http -> https) on providers that enforce HTTPS.
+	resp, err := t.base.RoundTrip(req)
+	if err == nil {
+		return resp, nil
+	}
+
+	if !canFallbackToHTTP(req) {
+		return nil, err
+	}
+
+	fallbackReq, cloneErr := cloneRequestWithHTTPScheme(req, "http")
+	if cloneErr != nil {
+		return nil, err
+	}
+
+	GoLog("[HTTP] HTTPS request failed for %s, retrying over HTTP: %v\n", req.URL.Host, err)
+	return t.base.RoundTrip(fallbackReq)
+}
+
+func canFallbackToHTTP(req *http.Request) bool {
+	if req == nil {
+		return false
+	}
+
+	switch strings.ToUpper(req.Method) {
+	case http.MethodGet, http.MethodHead, http.MethodOptions, http.MethodDelete:
+		return true
+	default:
+		return req.GetBody != nil
+	}
+}
+
+func cloneRequestWithHTTPScheme(req *http.Request, scheme string) (*http.Request, error) {
+	reqCopy := req.Clone(req.Context())
+	if req.Body != nil && req.GetBody != nil {
+		bodyCopy, err := req.GetBody()
+		if err != nil {
+			return nil, err
+		}
+		reqCopy.Body = bodyCopy
+	}
+
+	urlCopy := *req.URL
+	urlCopy.Scheme = scheme
+	reqCopy.URL = &urlCopy
+	return reqCopy, nil
 }
 
-// Also checks for ISP blocking on errors
 func DoRequestWithUserAgent(client *http.Client, req *http.Request) (*http.Response, error) {
-	req.Header.Set("User-Agent", getRandomUserAgent())
+	req.Header.Set("User-Agent", userAgentForURL(req.URL))
 	resp, err := client.Do(req)
 	if err != nil {
 		CheckAndLogISPBlocking(err, req.URL.String(), "HTTP")
@@ -94,7 +246,6 @@ func DoRequestWithUserAgent(client *http.Client, req *http.Request) (*http.Respo
 	return resp, err
 }
 
-// RetryConfig holds configuration for retry logic
 type RetryConfig struct {
 	MaxRetries    int
 	InitialDelay  time.Duration
@@ -114,18 +265,17 @@ func DefaultRetryConfig() RetryConfig {
 func DoRequestWithRetry(client *http.Client, req *http.Request, config RetryConfig) (*http.Response, error) {
 	var lastErr error
 	delay := config.InitialDelay
-	requestURL := req.URL.String()
 
 	for attempt := 0; attempt <= config.MaxRetries; attempt++ {
 		reqCopy := req.Clone(req.Context())
-		reqCopy.Header.Set("User-Agent", getRandomUserAgent())
+		reqCopy.Header.Set("User-Agent", userAgentForURL(reqCopy.URL))
 
 		resp, err := client.Do(reqCopy)
 		if err != nil {
 			lastErr = err
 
-			if CheckAndLogISPBlocking(err, requestURL, "HTTP") {
-				return nil, WrapErrorWithISPCheck(err, requestURL, "HTTP")
+			if CheckAndLogISPBlocking(err, reqCopy.URL.String(), "HTTP") {
+				return nil, WrapErrorWithISPCheck(err, reqCopy.URL.String(), "HTTP")
 			}
 
 			if attempt < config.MaxRetries {
@@ -156,14 +306,11 @@ func DoRequestWithRetry(client *http.Client, req *http.Request, config RetryConf
 			continue
 		}
 
-		// Check for ISP blocking via HTTP status codes
-		// Some ISPs return 403 or 451 when blocking content
 		if resp.StatusCode == 403 || resp.StatusCode == 451 {
 			body, _ := io.ReadAll(resp.Body)
 			resp.Body.Close()
 			bodyStr := strings.ToLower(string(body))
 
-			// Check if response looks like ISP blocking page
 			ispBlockingIndicators := []string{
 				"blocked", "forbidden", "access denied", "not available in your",
 				"restricted", "censored", "unavailable for legal", "blocked by",
@@ -202,11 +349,12 @@ func calculateNextDelay(currentDelay time.Duration, config RetryConfig) time.Dur
 	return min(nextDelay, config.MaxDelay)
 }
 
-// Returns 60 seconds as default if header is missing or invalid
+// Returns 0 if the header is missing or invalid so callers can keep their
+// normal exponential backoff instead of stalling for an arbitrary minute.
 func getRetryAfterDuration(resp *http.Response) time.Duration {
 	retryAfter := resp.Header.Get("Retry-After")
 	if retryAfter == "" {
-		return 60 * time.Second // Default wait time
+		return 0
 	}
 
 	if seconds, err := strconv.Atoi(retryAfter); err == nil {
@@ -220,7 +368,7 @@ func getRetryAfterDuration(resp *http.Response) time.Duration {
 		}
 	}
 
-	return 60 * time.Second // Default
+	return 0
 }
 
 func ReadResponseBody(resp *http.Response) ([]byte, error) {
@@ -345,7 +493,6 @@ func IsISPBlocking(err error, requestURL string) *ISPBlockingError {
 		}
 	}
 
-	// Check error message patterns for common ISP blocking indicators
 	blockingPatterns := []struct {
 		pattern string
 		reason  string
@@ -374,7 +521,6 @@ func IsISPBlocking(err error, requestURL string) *ISPBlockingError {
 	return nil
 }
 
-// Returns true if ISP blocking was detected
 func CheckAndLogISPBlocking(err error, requestURL string, tag string) bool {
 	ispErr := IsISPBlocking(err, requestURL)
 	if ispErr != nil {
@@ -388,7 +534,6 @@ func CheckAndLogISPBlocking(err error, requestURL string, tag string) bool {
 	return false
 }
 
-// extractDomain extracts the domain from a URL string
 func extractDomain(rawURL string) string {
 	if rawURL == "" {
 		return "unknown"
@@ -410,7 +555,6 @@ func extractDomain(rawURL string) string {
 	return "unknown"
 }
 
-// If ISP blocking is detected, returns a more descriptive error
 func WrapErrorWithISPCheck(err error, requestURL string, tag string) error {
 	if err == nil {
 		return nil

go_backend/httputil_ios.go

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

go_backend/httputil_utls.go

@@ -16,8 +16,6 @@ import (
 	"golang.org/x/net/http2"
 )
 
-// uTLS transport that mimics Chrome's TLS fingerprint to bypass Cloudflare
-// Uses HTTP/2 for optimal performance as uTLS works best with HTTP/2
 type utlsTransport struct {
 	dialer       *net.Dialer
 	mu           sync.Mutex
@@ -91,7 +89,6 @@ func (t *utlsTransport) getPort(u *url.URL) string {
 	return "80"
 }
 
-// Cloudflare bypass client using uTLS Chrome fingerprint
 var cloudflareBypassTransport = newUTLSTransport()
 
 var cloudflareBypassClient = &http.Client{
@@ -99,22 +96,15 @@ var cloudflareBypassClient = &http.Client{
 	Timeout:   DefaultTimeout,
 }
 
-// GetCloudflareBypassClient returns an HTTP client that mimics Chrome's TLS fingerprint
-// Use this when requests are blocked by Cloudflare (common when using VPN)
 func GetCloudflareBypassClient() *http.Client {
 	return cloudflareBypassClient
 }
 
-// DoRequestWithCloudflareBypass attempts request with standard client first,
-// then retries with uTLS Chrome fingerprint if Cloudflare blocks it.
-// This is useful when using VPN as Cloudflare detects Go's default TLS fingerprint.
 func DoRequestWithCloudflareBypass(req *http.Request) (*http.Response, error) {
-	req.Header.Set("User-Agent", getRandomUserAgent())
+	req.Header.Set("User-Agent", userAgentForURL(req.URL))
 
-	// Try with standard client first
 	resp, err := sharedClient.Do(req)
 	if err == nil {
-		// Check for Cloudflare challenge page (403 with specific markers)
 		if resp.StatusCode == 403 || resp.StatusCode == 503 {
 			body, readErr := io.ReadAll(resp.Body)
 			resp.Body.Close()
@@ -138,16 +128,13 @@ func DoRequestWithCloudflareBypass(req *http.Request) (*http.Response, error) {
 				if isCloudflare {
 					LogDebug("HTTP", "Cloudflare detected, retrying with Chrome TLS fingerprint...")
 
-					// Clone request for retry
 					reqCopy := req.Clone(req.Context())
-					reqCopy.Header.Set("User-Agent", getRandomUserAgent())
+					reqCopy.Header.Set("User-Agent", userAgentForURL(reqCopy.URL))
 
-					// Retry with uTLS Chrome fingerprint
 					return cloudflareBypassClient.Do(reqCopy)
 				}
 			}
 
-			// Not Cloudflare, return original response (recreate body)
 			return &http.Response{
 				Status:     resp.Status,
 				StatusCode: resp.StatusCode,
@@ -158,7 +145,6 @@ func DoRequestWithCloudflareBypass(req *http.Request) (*http.Response, error) {
 		return resp, nil
 	}
 
-	// Check if error might be TLS-related (Cloudflare blocking)
 	errStr := strings.ToLower(err.Error())
 	tlsRelated := strings.Contains(errStr, "tls") ||
 		strings.Contains(errStr, "handshake") ||
@@ -168,11 +154,9 @@ func DoRequestWithCloudflareBypass(req *http.Request) (*http.Response, error) {
 	if tlsRelated {
 		LogDebug("HTTP", "TLS error detected, retrying with Chrome TLS fingerprint: %v", err)
 
-		// Clone request for retry
 		reqCopy := req.Clone(req.Context())
-		reqCopy.Header.Set("User-Agent", getRandomUserAgent())
+		reqCopy.Header.Set("User-Agent", userAgentForURL(reqCopy.URL))
 
-		// Retry with uTLS Chrome fingerprint
 		return cloudflareBypassClient.Do(reqCopy)
 	}
 

go_backend/idhs.go

@@ -10,8 +10,6 @@ import (
 	"time"
 )
 
-// IDHSClient is a client for I Don't Have Spotify API
-// Used as fallback when SongLink fails or is rate limited
 type IDHSClient struct {
 	client *http.Client
 }
@@ -22,13 +20,11 @@ var (
 	idhsRateLimiter  = NewRateLimiter(8, time.Minute) // 8 req/min (below 10 limit)
 )
 
-// IDHSSearchRequest represents the request body for IDHS API
 type IDHSSearchRequest struct {
 	Link     string   `json:"link"`
 	Adapters []string `json:"adapters,omitempty"`
 }
 
-// IDHSSearchResponse represents the response from IDHS API
 type IDHSSearchResponse struct {
 	ID            string     `json:"id"`
 	Type          string     `json:"type"` // song, album, artist, podcast, show
@@ -41,7 +37,6 @@ type IDHSSearchResponse struct {
 	Links         []IDHSLink `json:"links"`
 }
 
-// IDHSLink represents a link to a streaming platform
 type IDHSLink struct {
 	Type         string `json:"type"` // spotify, youTube, appleMusic, deezer, soundCloud, tidal
 	URL          string `json:"url"`
@@ -49,7 +44,6 @@ type IDHSLink struct {
 	NotAvailable bool   `json:"notAvailable,omitempty"`
 }
 
-// NewIDHSClient creates a new IDHS client
 func NewIDHSClient() *IDHSClient {
 	idhsClientOnce.Do(func() {
 		globalIDHSClient = &IDHSClient{
@@ -59,7 +53,6 @@ func NewIDHSClient() *IDHSClient {
 	return globalIDHSClient
 }
 
-// Search converts a music link to links on other platforms
 func (c *IDHSClient) Search(link string, adapters []string) (*IDHSSearchResponse, error) {
 	idhsRateLimiter.WaitForSlot()
 
@@ -113,11 +106,9 @@ func (c *IDHSClient) Search(link string, adapters []string) (*IDHSSearchResponse
 	return &result, nil
 }
 
-// GetAvailabilityFromSpotify checks track availability using IDHS as fallback
 func (c *IDHSClient) GetAvailabilityFromSpotify(spotifyTrackID string) (*TrackAvailability, error) {
 	spotifyURL := fmt.Sprintf("https://open.spotify.com/track/%s", spotifyTrackID)
 
-	// Request only the platforms we need
 	adapters := []string{"tidal", "deezer"}
 
 	result, err := c.Search(spotifyURL, adapters)
@@ -151,11 +142,9 @@ func (c *IDHSClient) GetAvailabilityFromSpotify(spotifyTrackID string) (*TrackAv
 	return availability, nil
 }
 
-// GetAvailabilityFromDeezer checks track availability using IDHS
 func (c *IDHSClient) GetAvailabilityFromDeezer(deezerTrackID string) (*TrackAvailability, error) {
 	deezerURL := fmt.Sprintf("https://www.deezer.com/track/%s", deezerTrackID)
 
-	// Request only the platforms we need
 	adapters := []string{"spotify", "tidal"}
 
 	result, err := c.Search(deezerURL, adapters)

go_backend/library_scan.go

@@ -1,34 +1,43 @@
 package gobackend
 
 import (
+	"bufio"
 	"encoding/json"
 	"fmt"
 	"os"
 	"path/filepath"
+	"strconv"
 	"strings"
 	"sync"
 	"time"
 )
 
-// LibraryScanResult represents metadata from a scanned audio file
 type LibraryScanResult struct {
-	ID          string `json:"id"`
-	TrackName   string `json:"trackName"`
-	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"`
-	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"`
-	Genre       string `json:"genre,omitempty"`
-	Format      string `json:"format,omitempty"`
+	ID                   string `json:"id"`
+	TrackName            string `json:"trackName"`
+	ArtistName           string `json:"artistName"`
+	AlbumName            string `json:"albumName"`
+	AlbumArtist          string `json:"albumArtist,omitempty"`
+	FilePath             string `json:"filePath"`
+	CoverPath            string `json:"coverPath,omitempty"`
+	ScannedAt            string `json:"scannedAt"`
+	FileModTime          int64  `json:"fileModTime,omitempty"` // Unix timestamp in milliseconds
+	ISRC                 string `json:"isrc,omitempty"`
+	TrackNumber          int    `json:"trackNumber,omitempty"`
+	TotalTracks          int    `json:"totalTracks,omitempty"`
+	DiscNumber           int    `json:"discNumber,omitempty"`
+	TotalDiscs           int    `json:"totalDiscs,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"`
+	Composer             string `json:"composer,omitempty"`
+	Label                string `json:"label,omitempty"`
+	Copyright            string `json:"copyright,omitempty"`
+	Format               string `json:"format,omitempty"`
+	MetadataFromFilename bool   `json:"metadataFromFilename,omitempty"`
 }
 
 type LibraryScanProgress struct {
@@ -40,6 +49,13 @@ type LibraryScanProgress struct {
 	IsComplete   bool    `json:"is_complete"`
 }
 
+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
@@ -55,6 +71,57 @@ var supportedAudioFormats = map[string]bool{
 	".mp3":  true,
 	".opus": true,
 	".ogg":  true,
+	".ape":  true,
+	".wv":   true,
+	".mpc":  true,
+	".cue":  true,
+}
+
+type libraryAudioFileInfo struct {
+	path    string
+	modTime int64
+}
+
+type scannedCueFileInfo struct {
+	sheet     *CueSheet
+	audioPath string
+}
+
+func collectLibraryAudioFiles(folderPath string, cancelCh <-chan struct{}) ([]libraryAudioFileInfo, error) {
+	var files []libraryAudioFileInfo
+
+	err := filepath.Walk(folderPath, func(path string, info os.FileInfo, err error) error {
+		if err != nil {
+			return nil
+		}
+
+		select {
+		case <-cancelCh:
+			return fmt.Errorf("scan cancelled")
+		default:
+		}
+
+		if info.IsDir() {
+			return nil
+		}
+
+		ext := strings.ToLower(filepath.Ext(path))
+		if !supportedAudioFormats[ext] {
+			return nil
+		}
+
+		files = append(files, libraryAudioFileInfo{
+			path:    path,
+			modTime: info.ModTime().UnixMilli(),
+		})
+		return nil
+	})
+
+	if err != nil {
+		return nil, err
+	}
+
+	return files, nil
 }
 
 func SetLibraryCoverCacheDir(cacheDir string) {
@@ -88,32 +155,12 @@ func ScanLibraryFolder(folderPath string) (string, error) {
 	cancelCh := libraryScanCancel
 	libraryScanCancelMu.Unlock()
 
-	var audioFiles []string
-	err = filepath.Walk(folderPath, func(path string, info os.FileInfo, err error) error {
-		if err != nil {
-			return nil
-		}
-
-		select {
-		case <-cancelCh:
-			return fmt.Errorf("scan cancelled")
-		default:
-		}
-
-		if !info.IsDir() {
-			ext := strings.ToLower(filepath.Ext(path))
-			if supportedAudioFormats[ext] {
-				audioFiles = append(audioFiles, path)
-			}
-		}
-		return nil
-	})
-
+	audioFileInfos, err := collectLibraryAudioFiles(folderPath, cancelCh)
 	if err != nil {
 		return "[]", err
 	}
 
-	totalFiles := len(audioFiles)
+	totalFiles := len(audioFileInfos)
 	libraryScanProgressMu.Lock()
 	libraryScanProgress.TotalFiles = totalFiles
 	libraryScanProgressMu.Unlock()
@@ -131,7 +178,29 @@ func ScanLibraryFolder(folderPath string) (string, error) {
 	scanTime := time.Now().UTC().Format(time.RFC3339)
 	errorCount := 0
 
-	for i, filePath := range audioFiles {
+	cueReferencedAudioFiles := make(map[string]bool)
+	parsedCueFiles := make(map[string]scannedCueFileInfo)
+
+	for _, fileInfo := range audioFileInfos {
+		filePath := fileInfo.path
+		ext := strings.ToLower(filepath.Ext(filePath))
+		if ext == ".cue" {
+			sheet, err := ParseCueFile(filePath)
+			if err == nil && sheet.FileName != "" {
+				audioPath := ResolveCueAudioPath(filePath, sheet.FileName)
+				if audioPath != "" {
+					parsedCueFiles[filePath] = scannedCueFileInfo{
+						sheet:     sheet,
+						audioPath: audioPath,
+					}
+					cueReferencedAudioFiles[audioPath] = true
+				}
+			}
+		}
+	}
+
+	for i, fileInfo := range audioFileInfos {
+		filePath := fileInfo.path
 		select {
 		case <-cancelCh:
 			return "[]", fmt.Errorf("scan cancelled")
@@ -144,7 +213,40 @@ func ScanLibraryFolder(folderPath string) (string, error) {
 		libraryScanProgress.ProgressPct = float64(i+1) / float64(totalFiles) * 100
 		libraryScanProgressMu.Unlock()
 
-		result, err := scanAudioFile(filePath, scanTime)
+		ext := strings.ToLower(filepath.Ext(filePath))
+
+		if ext == ".cue" {
+			var cueResults []LibraryScanResult
+			cueInfo, ok := parsedCueFiles[filePath]
+			if ok {
+				cueResults, err = scanCueSheetForLibrary(
+					filePath,
+					cueInfo.sheet,
+					cueInfo.audioPath,
+					"",
+					fileInfo.modTime,
+					"",
+					scanTime,
+				)
+			} else {
+				cueResults, err = ScanCueFileForLibrary(filePath, scanTime)
+			}
+			if err != nil {
+				errorCount++
+				GoLog("[LibraryScan] Error scanning cue %s: %v\n", filePath, err)
+				continue
+			}
+			results = append(results, cueResults...)
+			GoLog("[LibraryScan] CUE sheet %s: %d tracks\n", filepath.Base(filePath), len(cueResults))
+			continue
+		}
+
+		if cueReferencedAudioFiles[filePath] {
+			GoLog("[LibraryScan] Skipping %s (referenced by .cue sheet)\n", filepath.Base(filePath))
+			continue
+		}
+
+		result, err := scanAudioFileWithKnownModTime(filePath, scanTime, fileInfo.modTime)
 		if err != nil {
 			errorCount++
 			GoLog("[LibraryScan] Error scanning %s: %v\n", filePath, err)
@@ -170,7 +272,19 @@ func ScanLibraryFolder(folderPath string) (string, error) {
 }
 
 func scanAudioFile(filePath, scanTime string) (*LibraryScanResult, error) {
-	ext := strings.ToLower(filepath.Ext(filePath))
+	return scanAudioFileWithKnownModTimeAndDisplayName(filePath, "", scanTime, 0)
+}
+
+func scanAudioFileWithKnownModTime(filePath, scanTime string, knownModTime int64) (*LibraryScanResult, error) {
+	return scanAudioFileWithKnownModTimeAndDisplayNameAndCoverCacheKey(filePath, "", "", scanTime, knownModTime)
+}
+
+func scanAudioFileWithKnownModTimeAndDisplayName(filePath, displayNameHint, scanTime string, knownModTime int64) (*LibraryScanResult, error) {
+	return scanAudioFileWithKnownModTimeAndDisplayNameAndCoverCacheKey(filePath, displayNameHint, "", scanTime, knownModTime)
+}
+
+func scanAudioFileWithKnownModTimeAndDisplayNameAndCoverCacheKey(filePath, displayNameHint, coverCacheKey, scanTime string, knownModTime int64) (*LibraryScanResult, error) {
+	ext := resolveLibraryAudioExt(filePath, displayNameHint)
 
 	result := &LibraryScanResult{
 		ID:        generateLibraryID(filePath),
@@ -179,11 +293,22 @@ func scanAudioFile(filePath, scanTime string) (*LibraryScanResult, error) {
 		Format:    strings.TrimPrefix(ext, "."),
 	}
 
+	if knownModTime > 0 {
+		result.FileModTime = knownModTime
+	} else 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 coverCacheDir != "" {
+		coverPath, err := SaveCoverToCacheWithHintAndKey(
+			filePath,
+			displayNameHint,
+			coverCacheDir,
+			coverCacheKey,
+		)
 		if err == nil && coverPath != "" {
 			result.CoverPath = coverPath
 		}
@@ -191,22 +316,52 @@ func scanAudioFile(filePath, scanTime string) (*LibraryScanResult, error) {
 
 	switch ext {
 	case ".flac":
-		return scanFLACFile(filePath, result)
+		return scanFLACFile(filePath, result, displayNameHint)
 	case ".m4a":
-		return scanM4AFile(filePath, result)
+		return scanM4AFile(filePath, result, displayNameHint)
 	case ".mp3":
-		return scanMP3File(filePath, result)
+		return scanMP3File(filePath, result, displayNameHint)
 	case ".opus", ".ogg":
-		return scanOggFile(filePath, result)
+		return scanOggFile(filePath, result, displayNameHint)
+	case ".ape", ".wv", ".mpc":
+		return scanAPEFile(filePath, result, displayNameHint)
 	default:
-		return scanFromFilename(filePath, result)
+		return scanFromFilename(filePath, displayNameHint, result)
 	}
 }
 
-func scanFLACFile(filePath string, result *LibraryScanResult) (*LibraryScanResult, error) {
+func resolveLibraryAudioExt(filePath, displayNameHint string) string {
+	ext := strings.ToLower(filepath.Ext(filePath))
+	if ext != "" {
+		return ext
+	}
+	return strings.ToLower(filepath.Ext(displayNameHint))
+}
+
+func libraryDisplayNameOrPath(filePath, displayNameHint string) string {
+	if displayNameHint != "" {
+		return displayNameHint
+	}
+	return filePath
+}
+
+func applyDefaultLibraryMetadata(filePath, displayNameHint string, result *LibraryScanResult) {
+	nameSource := libraryDisplayNameOrPath(filePath, displayNameHint)
+	if result.TrackName == "" {
+		result.TrackName = strings.TrimSuffix(filepath.Base(nameSource), filepath.Ext(nameSource))
+	}
+	if result.ArtistName == "" {
+		result.ArtistName = "Unknown Artist"
+	}
+	if result.AlbumName == "" {
+		result.AlbumName = "Unknown Album"
+	}
+}
+
+func scanFLACFile(filePath string, result *LibraryScanResult, displayNameHint string) (*LibraryScanResult, error) {
 	metadata, err := ReadMetadata(filePath)
 	if err != nil {
-		return scanFromFilename(filePath, result)
+		return scanFromFilename(filePath, displayNameHint, result)
 	}
 
 	result.TrackName = metadata.Title
@@ -215,9 +370,14 @@ func scanFLACFile(filePath string, result *LibraryScanResult) (*LibraryScanResul
 	result.AlbumArtist = metadata.AlbumArtist
 	result.ISRC = metadata.ISRC
 	result.TrackNumber = metadata.TrackNumber
+	result.TotalTracks = metadata.TotalTracks
 	result.DiscNumber = metadata.DiscNumber
+	result.TotalDiscs = metadata.TotalDiscs
 	result.ReleaseDate = metadata.Date
 	result.Genre = metadata.Genre
+	result.Composer = metadata.Composer
+	result.Label = metadata.Label
+	result.Copyright = metadata.Copyright
 
 	quality, err := GetAudioQuality(filePath)
 	if err == nil {
@@ -228,34 +388,53 @@ func scanFLACFile(filePath string, result *LibraryScanResult) (*LibraryScanResul
 		}
 	}
 
-	if result.TrackName == "" {
-		result.TrackName = strings.TrimSuffix(filepath.Base(filePath), filepath.Ext(filePath))
-	}
-	if result.ArtistName == "" {
-		result.ArtistName = "Unknown Artist"
-	}
-	if result.AlbumName == "" {
-		result.AlbumName = "Unknown Album"
-	}
+	applyDefaultLibraryMetadata(filePath, displayNameHint, result)
 
 	return result, nil
 }
 
-func scanM4AFile(filePath string, result *LibraryScanResult) (*LibraryScanResult, error) {
+func scanM4AFile(filePath string, result *LibraryScanResult, displayNameHint string) (*LibraryScanResult, error) {
+	metadata, err := ReadM4ATags(filePath)
+	if err != nil {
+		GoLog("[LibraryScan] M4A read error for %s: %v\n", filePath, err)
+		return scanFromFilename(filePath, displayNameHint, result)
+	}
+
+	if metadata != nil {
+		result.TrackName = metadata.Title
+		result.ArtistName = metadata.Artist
+		result.AlbumName = metadata.Album
+		result.AlbumArtist = metadata.AlbumArtist
+		result.ISRC = metadata.ISRC
+		result.TrackNumber = metadata.TrackNumber
+		result.TotalTracks = metadata.TotalTracks
+		result.DiscNumber = metadata.DiscNumber
+		result.TotalDiscs = metadata.TotalDiscs
+		result.ReleaseDate = metadata.Date
+		if result.ReleaseDate == "" {
+			result.ReleaseDate = metadata.Year
+		}
+		result.Genre = metadata.Genre
+		result.Composer = metadata.Composer
+		result.Label = metadata.Label
+		result.Copyright = metadata.Copyright
+	}
+
 	quality, err := GetM4AQuality(filePath)
 	if err == nil {
 		result.BitDepth = quality.BitDepth
 		result.SampleRate = quality.SampleRate
 	}
 
-	return scanFromFilename(filePath, result)
+	applyDefaultLibraryMetadata(filePath, displayNameHint, result)
+	return result, nil
 }
 
-func scanMP3File(filePath string, result *LibraryScanResult) (*LibraryScanResult, error) {
+func scanMP3File(filePath string, result *LibraryScanResult, displayNameHint string) (*LibraryScanResult, error) {
 	metadata, err := ReadID3Tags(filePath)
 	if err != nil {
 		GoLog("[LibraryScan] ID3 read error for %s: %v\n", filePath, err)
-		return scanFromFilename(filePath, result)
+		return scanFromFilename(filePath, displayNameHint, result)
 	}
 
 	result.TrackName = metadata.Title
@@ -263,7 +442,9 @@ func scanMP3File(filePath string, result *LibraryScanResult) (*LibraryScanResult
 	result.AlbumName = metadata.Album
 	result.AlbumArtist = metadata.AlbumArtist
 	result.TrackNumber = metadata.TrackNumber
+	result.TotalTracks = metadata.TotalTracks
 	result.DiscNumber = metadata.DiscNumber
+	result.TotalDiscs = metadata.TotalDiscs
 	result.Genre = metadata.Genre
 	if metadata.Date != "" {
 		result.ReleaseDate = metadata.Date
@@ -271,32 +452,30 @@ func scanMP3File(filePath string, result *LibraryScanResult) (*LibraryScanResult
 		result.ReleaseDate = metadata.Year
 	}
 	result.ISRC = metadata.ISRC
+	result.Composer = metadata.Composer
+	result.Label = metadata.Label
+	result.Copyright = metadata.Copyright
 
 	quality, err := GetMP3Quality(filePath)
 	if err == nil {
 		result.SampleRate = quality.SampleRate
-		result.BitDepth = quality.BitDepth
+		result.BitDepth = quality.BitDepth // 0 for lossy
 		result.Duration = quality.Duration
+		if quality.Bitrate > 0 {
+			result.Bitrate = quality.Bitrate / 1000 // convert bps to kbps
+		}
 	}
 
-	if result.TrackName == "" {
-		result.TrackName = strings.TrimSuffix(filepath.Base(filePath), filepath.Ext(filePath))
-	}
-	if result.ArtistName == "" {
-		result.ArtistName = "Unknown Artist"
-	}
-	if result.AlbumName == "" {
-		result.AlbumName = "Unknown Album"
-	}
+	applyDefaultLibraryMetadata(filePath, displayNameHint, result)
 
 	return result, nil
 }
 
-func scanOggFile(filePath string, result *LibraryScanResult) (*LibraryScanResult, error) {
+func scanOggFile(filePath string, result *LibraryScanResult, displayNameHint string) (*LibraryScanResult, error) {
 	metadata, err := ReadOggVorbisComments(filePath)
 	if err != nil {
 		GoLog("[LibraryScan] Ogg/Opus read error for %s: %v\n", filePath, err)
-		return scanFromFilename(filePath, result)
+		return scanFromFilename(filePath, displayNameHint, result)
 	}
 
 	result.TrackName = metadata.Title
@@ -305,32 +484,70 @@ func scanOggFile(filePath string, result *LibraryScanResult) (*LibraryScanResult
 	result.AlbumArtist = metadata.AlbumArtist
 	result.ISRC = metadata.ISRC
 	result.TrackNumber = metadata.TrackNumber
+	result.TotalTracks = metadata.TotalTracks
 	result.DiscNumber = metadata.DiscNumber
+	result.TotalDiscs = metadata.TotalDiscs
 	result.Genre = metadata.Genre
 	result.ReleaseDate = metadata.Date
+	result.Composer = metadata.Composer
+	result.Label = metadata.Label
+	result.Copyright = metadata.Copyright
 
 	quality, err := GetOggQuality(filePath)
 	if err == nil {
 		result.SampleRate = quality.SampleRate
-		result.BitDepth = quality.BitDepth
+		result.BitDepth = quality.BitDepth // 0 for lossy
 		result.Duration = quality.Duration
+		if quality.Bitrate > 0 {
+			result.Bitrate = quality.Bitrate / 1000 // convert bps to kbps
+		}
 	}
 
-	if result.TrackName == "" {
-		result.TrackName = strings.TrimSuffix(filepath.Base(filePath), filepath.Ext(filePath))
-	}
-	if result.ArtistName == "" {
-		result.ArtistName = "Unknown Artist"
-	}
-	if result.AlbumName == "" {
-		result.AlbumName = "Unknown Album"
-	}
+	applyDefaultLibraryMetadata(filePath, displayNameHint, result)
 
 	return result, nil
 }
 
-func scanFromFilename(filePath string, result *LibraryScanResult) (*LibraryScanResult, error) {
-	filename := strings.TrimSuffix(filepath.Base(filePath), filepath.Ext(filePath))
+func scanAPEFile(filePath string, result *LibraryScanResult, displayNameHint string) (*LibraryScanResult, error) {
+	tag, err := ReadAPETags(filePath)
+	if err != nil {
+		GoLog("[LibraryScan] APE tag read error for %s: %v\n", filePath, err)
+		return scanFromFilename(filePath, displayNameHint, result)
+	}
+
+	metadata := APETagToAudioMetadata(tag)
+	if metadata == nil {
+		return scanFromFilename(filePath, displayNameHint, result)
+	}
+
+	result.TrackName = metadata.Title
+	result.ArtistName = metadata.Artist
+	result.AlbumName = metadata.Album
+	result.AlbumArtist = metadata.AlbumArtist
+	result.ISRC = metadata.ISRC
+	result.TrackNumber = metadata.TrackNumber
+	result.TotalTracks = metadata.TotalTracks
+	result.DiscNumber = metadata.DiscNumber
+	result.TotalDiscs = metadata.TotalDiscs
+	result.Genre = metadata.Genre
+	if metadata.Date != "" {
+		result.ReleaseDate = metadata.Date
+	} else {
+		result.ReleaseDate = metadata.Year
+	}
+	result.Composer = metadata.Composer
+	result.Label = metadata.Label
+	result.Copyright = metadata.Copyright
+
+	applyDefaultLibraryMetadata(filePath, displayNameHint, result)
+
+	return result, nil
+}
+
+func scanFromFilename(filePath, displayNameHint string, result *LibraryScanResult) (*LibraryScanResult, error) {
+	result.MetadataFromFilename = true
+	nameSource := libraryDisplayNameOrPath(filePath, displayNameHint)
+	filename := strings.TrimSuffix(filepath.Base(nameSource), filepath.Ext(nameSource))
 
 	parts := strings.SplitN(filename, " - ", 2)
 	if len(parts) == 2 {
@@ -353,7 +570,7 @@ func scanFromFilename(filePath string, result *LibraryScanResult) (*LibraryScanR
 
 	dir := filepath.Dir(filePath)
 	result.AlbumName = filepath.Base(dir)
-	if result.AlbumName == "." || result.AlbumName == "" {
+	if result.AlbumName == "." || result.AlbumName == "" || result.AlbumName == "fd" || result.AlbumName == "self" {
 		result.AlbumName = "Unknown Album"
 	}
 
@@ -400,8 +617,22 @@ func CancelLibraryScan() {
 }
 
 func ReadAudioMetadata(filePath string) (string, error) {
+	return ReadAudioMetadataWithDisplayName(filePath, "")
+}
+
+func ReadAudioMetadataWithDisplayName(filePath, displayNameHint string) (string, error) {
+	return ReadAudioMetadataWithDisplayNameAndCoverCacheKey(filePath, displayNameHint, "")
+}
+
+func ReadAudioMetadataWithDisplayNameAndCoverCacheKey(filePath, displayNameHint, coverCacheKey string) (string, error) {
 	scanTime := time.Now().UTC().Format(time.RFC3339)
-	result, err := scanAudioFile(filePath, scanTime)
+	result, err := scanAudioFileWithKnownModTimeAndDisplayNameAndCoverCacheKey(
+		filePath,
+		displayNameHint,
+		coverCacheKey,
+		scanTime,
+		0,
+	)
 	if err != nil {
 		return "", err
 	}
@@ -413,3 +644,266 @@ func ReadAudioMetadata(filePath string) (string, error) {
 
 	return string(jsonBytes), nil
 }
+
+func loadExistingFilesSnapshot(snapshotPath string) (map[string]int64, error) {
+	existingFiles := make(map[string]int64)
+	if snapshotPath == "" {
+		return existingFiles, nil
+	}
+
+	file, err := os.Open(snapshotPath)
+	if err != nil {
+		return nil, err
+	}
+	defer file.Close()
+
+	scanner := bufio.NewScanner(file)
+	for scanner.Scan() {
+		line := scanner.Text()
+		if line == "" {
+			continue
+		}
+		parts := strings.SplitN(line, "\t", 2)
+		if len(parts) != 2 {
+			continue
+		}
+		modTime, err := strconv.ParseInt(parts[0], 10, 64)
+		if err != nil {
+			continue
+		}
+		existingFiles[parts[1]] = modTime
+	}
+
+	if err := scanner.Err(); err != nil {
+		return nil, err
+	}
+
+	return existingFiles, nil
+}
+
+func scanLibraryFolderIncrementalWithExistingFiles(folderPath string, existingFiles map[string]int64) (string, error) {
+	if folderPath == "" {
+		return "{}", fmt.Errorf("folder path is empty")
+	}
+
+	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)
+	}
+
+	GoLog("[LibraryScan] Incremental scan starting, %d existing files in database\n", len(existingFiles))
+
+	libraryScanProgressMu.Lock()
+	libraryScanProgress = LibraryScanProgress{}
+	libraryScanProgressMu.Unlock()
+
+	libraryScanCancelMu.Lock()
+	if libraryScanCancel != nil {
+		close(libraryScanCancel)
+	}
+	libraryScanCancel = make(chan struct{})
+	cancelCh := libraryScanCancel
+	libraryScanCancelMu.Unlock()
+
+	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()
+
+	var filesToScan []libraryAudioFileInfo
+	skippedCount := 0
+	existingCueTrackModTimes := make(map[string]int64)
+	for existingPath, modTime := range existingFiles {
+		if idx := strings.LastIndex(existingPath, "#track"); idx > 0 {
+			baseCuePath := existingPath[:idx]
+			if _, exists := existingCueTrackModTimes[baseCuePath]; !exists {
+				existingCueTrackModTimes[baseCuePath] = modTime
+			}
+		}
+	}
+
+	for _, f := range currentFiles {
+		existingModTime, exists := existingFiles[f.path]
+		if !exists {
+			if strings.ToLower(filepath.Ext(f.path)) == ".cue" {
+				if cueTrackModTime, hasCueTracks := existingCueTrackModTimes[f.path]; hasCueTracks {
+					if f.modTime == cueTrackModTime {
+						skippedCount++
+					} else {
+						filesToScan = append(filesToScan, f)
+					}
+					continue
+				}
+			}
+			filesToScan = append(filesToScan, f)
+		} else if f.modTime != existingModTime {
+			filesToScan = append(filesToScan, f)
+		} else {
+			skippedCount++
+		}
+	}
+
+	var deletedPaths []string
+	for existingPath := range existingFiles {
+		if idx := strings.LastIndex(existingPath, "#track"); idx > 0 {
+			baseCuePath := existingPath[:idx]
+			if currentPathSet[baseCuePath] {
+				continue
+			}
+			deletedPaths = append(deletedPaths, existingPath)
+		} else 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
+	}
+
+	results := make([]LibraryScanResult, 0, len(filesToScan))
+	scanTime := time.Now().UTC().Format(time.RFC3339)
+	errorCount := 0
+
+	cueReferencedAudioFilesInc := make(map[string]bool)
+	parsedCueFiles := make(map[string]scannedCueFileInfo)
+	for _, f := range filesToScan {
+		ext := strings.ToLower(filepath.Ext(f.path))
+		if ext == ".cue" {
+			sheet, err := ParseCueFile(f.path)
+			if err == nil && sheet.FileName != "" {
+				audioPath := ResolveCueAudioPath(f.path, sheet.FileName)
+				if audioPath != "" {
+					parsedCueFiles[f.path] = scannedCueFileInfo{
+						sheet:     sheet,
+						audioPath: audioPath,
+					}
+					cueReferencedAudioFilesInc[audioPath] = true
+				}
+			}
+		}
+	}
+
+	for i, f := range filesToScan {
+		select {
+		case <-cancelCh:
+			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()
+
+		ext := strings.ToLower(filepath.Ext(f.path))
+
+		if ext == ".cue" {
+			var cueResults []LibraryScanResult
+			cueInfo, ok := parsedCueFiles[f.path]
+			if ok {
+				cueResults, err = scanCueSheetForLibrary(
+					f.path,
+					cueInfo.sheet,
+					cueInfo.audioPath,
+					"",
+					f.modTime,
+					"",
+					scanTime,
+				)
+			} else {
+				cueResults, err = ScanCueFileForLibrary(f.path, scanTime)
+			}
+			if err != nil {
+				errorCount++
+				GoLog("[LibraryScan] Error scanning cue %s: %v\n", f.path, err)
+				continue
+			}
+			results = append(results, cueResults...)
+			continue
+		}
+
+		if cueReferencedAudioFilesInc[f.path] {
+			continue
+		}
+
+		result, err := scanAudioFileWithKnownModTime(f.path, scanTime, f.modTime)
+		if err != nil {
+			errorCount++
+			GoLog("[LibraryScan] Error scanning %s: %v\n", f.path, err)
+			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
+}
+
+func ScanLibraryFolderIncremental(folderPath, existingFilesJSON string) (string, error) {
+	existingFiles := make(map[string]int64)
+	if existingFilesJSON != "" && existingFilesJSON != "{}" {
+		if err := json.Unmarshal([]byte(existingFilesJSON), &existingFiles); err != nil {
+			GoLog("[LibraryScan] Warning: failed to parse existing files JSON: %v\n", err)
+		}
+	}
+	return scanLibraryFolderIncrementalWithExistingFiles(folderPath, existingFiles)
+}
+
+func ScanLibraryFolderIncrementalFromSnapshot(folderPath, snapshotPath string) (string, error) {
+	existingFiles, err := loadExistingFilesSnapshot(snapshotPath)
+	if err != nil {
+		return "{}", fmt.Errorf("failed to load incremental snapshot: %w", err)
+	}
+	return scanLibraryFolderIncrementalWithExistingFiles(folderPath, existingFiles)
+}

go_backend/library_scan_test.go

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

go_backend/logbuffer.go

@@ -3,6 +3,7 @@ package gobackend
 import (
 	"encoding/json"
 	"fmt"
+	"regexp"
 	"strings"
 	"sync"
 	"time"
@@ -22,17 +23,35 @@ type LogBuffer struct {
 	loggingEnabled bool
 }
 
+const (
+	defaultLogBufferSize = 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._~+/\-]+=*`)
 )
 
+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,
-			loggingEnabled: false, // Default: disabled for performance (user can enable in settings)
+			entries:        make([]LogEntry, 0, defaultLogBufferSize),
+			maxSize:        defaultLogBufferSize,
+			loggingEnabled: false,
 		}
 	})
 	return globalLogBuffer
@@ -58,6 +77,8 @@ func (lb *LogBuffer) Add(level, tag, message string) {
 		return
 	}
 
+	message = sanitizeSensitiveLogText(message)
+
 	entry := LogEntry{
 		Timestamp: time.Now().Format("15:04:05.000"),
 		Level:     level,
@@ -124,13 +145,10 @@ func LogError(tag, format string, args ...interface{}) {
 	GetLogBuffer().Add("ERROR", tag, fmt.Sprintf(format, args...))
 }
 
-// GoLog is a drop-in replacement for fmt.Printf that also logs to buffer
-// It parses the tag from the format string if it starts with [Tag]
 func GoLog(format string, args ...interface{}) {
 	message := fmt.Sprintf(format, args...)
 	message = strings.TrimSuffix(message, "\n")
 
-	// Extract tag from message if present (e.g., "[Tidal] message")
 	tag := "Go"
 	level := "INFO"
 
@@ -142,7 +160,6 @@ func GoLog(format string, args ...interface{}) {
 		}
 	}
 
-	// Determine level from message content
 	msgLower := strings.ToLower(message)
 	if strings.Contains(msgLower, "error") || strings.Contains(msgLower, "failed") {
 		level = "ERROR"

go_backend/lyrics.go

@@ -20,6 +20,154 @@ const (
 	durationToleranceSec = 10.0
 )
 
+const (
+	LyricsProviderLRCLIB     = "lrclib"
+	LyricsProviderNetease    = "netease"
+	LyricsProviderMusixmatch = "musixmatch"
+	LyricsProviderAppleMusic = "apple_music"
+	LyricsProviderQQMusic    = "qqmusic"
+)
+
+var DefaultLyricsProviders = []string{
+	LyricsProviderLRCLIB,
+	LyricsProviderMusixmatch,
+	LyricsProviderNetease,
+	LyricsProviderAppleMusic,
+	LyricsProviderQQMusic,
+}
+
+var (
+	lyricsProvidersMu sync.RWMutex
+	lyricsProviders   []string // ordered list of enabled providers
+	appVersionMu      sync.RWMutex
+	appVersion        string
+)
+
+func SetAppVersion(version string) {
+	normalized := strings.TrimSpace(version)
+
+	appVersionMu.Lock()
+	defer appVersionMu.Unlock()
+	appVersion = normalized
+}
+
+func GetAppVersion() string {
+	appVersionMu.RLock()
+	defer appVersionMu.RUnlock()
+	return appVersion
+}
+
+func appUserAgent() string {
+	version := GetAppVersion()
+
+	if version == "" {
+		return "SpotiFLAC-Mobile"
+	}
+
+	return "SpotiFLAC-Mobile/" + version
+}
+
+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
+)
+
+func SetLyricsProviderOrder(providers []string) {
+	lyricsProvidersMu.Lock()
+	defer lyricsProvidersMu.Unlock()
+
+	if len(providers) == 0 {
+		lyricsProviders = nil
+		return
+	}
+
+	validNames := map[string]bool{
+		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)
+}
+
+func GetLyricsProviderOrder() []string {
+	lyricsProvidersMu.RLock()
+	defer lyricsProvidersMu.RUnlock()
+
+	if len(lyricsProviders) == 0 {
+		return DefaultLyricsProviders
+	}
+
+	result := make([]string, len(lyricsProviders))
+	copy(result, lyricsProviders)
+	return result
+}
+
+func GetAvailableLyricsProviders() []map[string]interface{} {
+	return []map[string]interface{}{
+		{"id": LyricsProviderLRCLIB, "name": "LRCLIB", "has_proxy_dependency": false, "description": "Open-source synced lyrics database"},
+		{"id": LyricsProviderNetease, "name": "Netease", "has_proxy_dependency": true, "description": "NetEase Cloud Music lyrics via Paxsenix"},
+		{"id": LyricsProviderMusixmatch, "name": "Musixmatch", "has_proxy_dependency": true, "description": "Musixmatch lyrics via Paxsenix"},
+		{"id": LyricsProviderAppleMusic, "name": "Apple Music", "has_proxy_dependency": true, "description": "Apple Music synced lyrics via Paxsenix"},
+		{"id": LyricsProviderQQMusic, "name": "QQ Music", "has_proxy_dependency": true, "description": "QQ Music lyrics via Paxsenix"},
+	}
+}
+
+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
+}
+
+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,
+	)
+}
+
+func GetLyricsFetchOptions() LyricsFetchOptions {
+	lyricsFetchOptionsMu.RLock()
+	defer lyricsFetchOptionsMu.RUnlock()
+	return lyricsFetchOptions
+}
+
 type lyricsCacheEntry struct {
 	response  *LyricsResponse
 	expiresAt time.Time
@@ -90,6 +238,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"`
@@ -139,7 +296,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 +331,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 {
@@ -233,6 +390,18 @@ func (c *LyricsClient) findBestMatch(results []LRCLibResponse, targetDurationSec
 	return bestPlain
 }
 
+func plainLyricsFromTimedLines(lines []LyricsLine) string {
+	parts := make([]string, 0, len(lines))
+	for _, line := range lines {
+		words := strings.TrimSpace(line.Words)
+		if words == "" {
+			continue
+		}
+		parts = append(parts, words)
+	}
+	return strings.Join(parts, "\n")
+}
+
 func (c *LyricsClient) durationMatches(lrcDuration, targetDuration float64) bool {
 	diff := math.Abs(lrcDuration - targetDuration)
 	return diff <= durationToleranceSec
@@ -240,66 +409,192 @@ func (c *LyricsClient) durationMatches(lrcDuration, targetDuration float64) bool
 
 func (c *LyricsClient) FetchLyricsAllSources(spotifyID, trackName, artistName string, durationSec float64) (*LyricsResponse, error) {
 	primaryArtist := normalizeArtistName(artistName)
+	fetchOptions := GetLyricsFetchOptions()
 
+	extManager := getExtensionManager()
+	var extensionProviders []*extensionProviderWrapper
+	if extManager != nil {
+		extensionProviders = extManager.GetLyricsProviders()
+	}
+
+	var cachedNonExtension *LyricsResponse
 	if cached, found := globalLyricsCache.Get(artistName, trackName, durationSec); found {
-		fmt.Printf("[Lyrics] Cache hit for: %s - %s\n", artistName, trackName)
-		cachedCopy := *cached
-		cachedCopy.Source = cached.Source + " (cached)"
+		isExtensionCache := strings.HasPrefix(cached.Source, "Extension:")
+		if len(extensionProviders) == 0 || isExtensionCache {
+			fmt.Printf("[Lyrics] Cache hit for: %s - %s\n", artistName, trackName)
+			cachedCopy := *cached
+			cachedCopy.Source = cached.Source + " (cached)"
+			return &cachedCopy, nil
+		}
+
+		// If extension providers are currently enabled, don't let stale built-in cache
+		// mask newly installed/activated extensions.
+		cachedNonExtension = cached
+		GoLog("[Lyrics] Ignoring cached non-extension lyrics because extension providers are available\n")
+	}
+
+	isValidResult := func(l *LyricsResponse) bool {
+		return lyricsHasUsableText(l)
+	}
+
+	if len(extensionProviders) > 0 {
+		for _, provider := range extensionProviders {
+			GoLog("[Lyrics] Trying extension lyrics provider: %s\n", provider.extension.ID)
+			lyrics, err := provider.FetchLyrics(trackName, artistName, "", durationSec)
+			if err == nil && isValidResult(lyrics) {
+				GoLog("[Lyrics] Got lyrics from extension: %s\n", provider.extension.ID)
+				globalLyricsCache.Set(artistName, trackName, durationSec, lyrics)
+				return lyrics, nil
+			}
+			if err != nil {
+				GoLog("[Lyrics] Extension %s failed: %v\n", provider.extension.ID, err)
+			}
+		}
+	}
+
+	if cachedNonExtension != nil {
+		cachedCopy := *cachedNonExtension
+		cachedCopy.Source = cachedNonExtension.Source + " (cached fallback)"
+		GoLog("[Lyrics] Extension providers unavailable for this track, using cached built-in lyrics\n")
 		return &cachedCopy, nil
 	}
 
+	providerOrder := GetLyricsProviderOrder()
+	simplifiedTrack := simplifyTrackName(trackName)
+
+	GoLog("[Lyrics] Searching for: %s - %s (providers: %v)\n", artistName, trackName, providerOrder)
+
+	for _, providerName := range providerOrder {
+		GoLog("[Lyrics] Trying provider: %s\n", providerName)
+
+		var lyrics *LyricsResponse
+		var err error
+
+		switch providerName {
+		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) {
+			GoLog("[Lyrics] Got lyrics from: %s\n", providerName)
+			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")
+}
+
+func (c *LyricsClient) tryLRCLIB(primaryArtist, artistName, trackName, simplifiedTrack string, durationSec float64) (*LyricsResponse, error) {
 	var lyrics *LyricsResponse
 	var err error
 
-	isValidResult := func(l *LyricsResponse) bool {
-		return l != nil && (len(l.Lines) > 0 || l.Instrumental)
-	}
-
 	lyrics, err = c.FetchLyricsWithMetadata(primaryArtist, trackName)
-	if err == nil && isValidResult(lyrics) {
+	if err == nil && lyrics != nil && (len(lyrics.Lines) > 0 || lyrics.Instrumental) {
 		lyrics.Source = "LRCLIB"
-		globalLyricsCache.Set(artistName, trackName, durationSec, lyrics)
 		return lyrics, nil
 	}
 
 	if primaryArtist != artistName {
 		lyrics, err = c.FetchLyricsWithMetadata(artistName, trackName)
-		if err == nil && isValidResult(lyrics) {
+		if err == nil && lyrics != nil && (len(lyrics.Lines) > 0 || lyrics.Instrumental) {
 			lyrics.Source = "LRCLIB"
-			globalLyricsCache.Set(artistName, trackName, durationSec, lyrics)
 			return lyrics, nil
 		}
 	}
 
-	simplifiedTrack := simplifyTrackName(trackName)
 	if simplifiedTrack != trackName {
 		lyrics, err = c.FetchLyricsWithMetadata(primaryArtist, simplifiedTrack)
-		if err == nil && isValidResult(lyrics) {
+		if err == nil && lyrics != nil && (len(lyrics.Lines) > 0 || lyrics.Instrumental) {
 			lyrics.Source = "LRCLIB (simplified)"
-			globalLyricsCache.Set(artistName, trackName, durationSec, lyrics)
 			return lyrics, nil
 		}
 	}
 
 	query := primaryArtist + " " + trackName
 	lyrics, err = c.FetchLyricsFromLRCLibSearch(query, durationSec)
-	if err == nil && isValidResult(lyrics) {
+	if err == nil && lyrics != nil && (len(lyrics.Lines) > 0 || lyrics.Instrumental) {
 		lyrics.Source = "LRCLIB Search"
-		globalLyricsCache.Set(artistName, trackName, durationSec, lyrics)
 		return lyrics, nil
 	}
 
 	if simplifiedTrack != trackName {
 		query = primaryArtist + " " + simplifiedTrack
 		lyrics, err = c.FetchLyricsFromLRCLibSearch(query, durationSec)
-		if err == nil && isValidResult(lyrics) {
+		if err == nil && lyrics != nil && (len(lyrics.Lines) > 0 || lyrics.Instrumental) {
 			lyrics.Source = "LRCLIB Search (simplified)"
-			globalLyricsCache.Set(artistName, trackName, durationSec, lyrics)
 			return lyrics, nil
 		}
 	}
 
-	return nil, fmt.Errorf("lyrics not found from any source")
+	return nil, fmt.Errorf("LRCLIB: no lyrics found")
 }
 
 func (c *LyricsClient) parseLRCLibResponse(resp *LRCLibResponse) *LyricsResponse {
@@ -339,10 +634,20 @@ func parseSyncedLyrics(syncedLyrics string) []LyricsLine {
 			continue
 		}
 
+		// Preserve Apple/QQ background vocal tags by attaching them to
+		// the previous timed line. This keeps [bg:...] in final exported LRC.
+		if strings.HasPrefix(line, "[bg:") && len(lines) > 0 {
+			lines[len(lines)-1].Words = strings.TrimSpace(lines[len(lines)-1].Words + "\n" + line)
+			continue
+		}
+
 		matches := lrcPattern.FindStringSubmatch(line)
 		if len(matches) == 5 {
 			startMs := lrcTimestampToMs(matches[1], matches[2], matches[3])
 			words := strings.TrimSpace(matches[4])
+			if words == "" {
+				continue
+			}
 
 			lines = append(lines, LyricsLine{
 				StartTimeMs: startMs,
@@ -363,6 +668,77 @@ 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
+}
+
+func detectLyricsErrorPayload(raw string) (string, bool) {
+	trimmed := strings.TrimSpace(raw)
+	if trimmed == "" || !strings.HasPrefix(trimmed, "{") {
+		return "", false
+	}
+
+	var payload map[string]interface{}
+	if err := json.Unmarshal([]byte(trimmed), &payload); err != nil {
+		return "", false
+	}
+
+	lyricsKeys := []string{"lyrics", "lyric", "lrc", "content", "lines", "syncedLyrics", "unsyncedLyrics"}
+	hasLyricsKey := false
+	for _, key := range lyricsKeys {
+		if _, ok := payload[key]; ok {
+			hasLyricsKey = true
+			break
+		}
+	}
+
+	errorKeys := []string{"message", "error", "detail", "reason"}
+	for _, key := range errorKeys {
+		if msg, ok := payload[key].(string); ok {
+			msg = strings.TrimSpace(msg)
+			if msg != "" && !hasLyricsKey {
+				return msg, true
+			}
+		}
+	}
+
+	if success, ok := payload["success"].(bool); ok && !success && !hasLyricsKey {
+		return "request unsuccessful", true
+	}
+
+	return "", false
+}
+
 func lrcTimestampToMs(minutes, seconds, centiseconds string) int64 {
 	min, _ := strconv.ParseInt(minutes, 10, 64)
 	sec, _ := strconv.ParseInt(seconds, 10, 64)
@@ -376,12 +752,16 @@ func lrcTimestampToMs(minutes, seconds, centiseconds string) int64 {
 }
 
 func msToLRCTimestamp(ms int64) string {
+	return fmt.Sprintf("[%s]", msToLRCTimestampInline(ms))
+}
+
+func msToLRCTimestampInline(ms int64) string {
 	totalSeconds := ms / 1000
 	minutes := totalSeconds / 60
 	seconds := totalSeconds % 60
 	centiseconds := (ms % 1000) / 10
 
-	return fmt.Sprintf("[%02d:%02d.%02d]", minutes, seconds, centiseconds)
+	return fmt.Sprintf("%02d:%02d.%02d", minutes, seconds, centiseconds)
 }
 
 func convertToLRCWithMetadata(lyrics *LyricsResponse, trackName, artistName string) string {
@@ -393,7 +773,7 @@ func convertToLRCWithMetadata(lyrics *LyricsResponse, trackName, artistName stri
 
 	builder.WriteString(fmt.Sprintf("[ti:%s]\n", trackName))
 	builder.WriteString(fmt.Sprintf("[ar:%s]\n", artistName))
-	builder.WriteString("[by:SpotiFLAC-Mobile]\n")
+	builder.WriteString("[by:Implemented by SpotiFLAC-Mobile using Paxsenix API]\n")
 	builder.WriteString("\n")
 
 	if lyrics.SyncType == "LINE_SYNCED" {
@@ -441,8 +821,16 @@ 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)
+	if loose := normalizeLooseTitle(result); loose != "" {
+		return loose
+	}
+
+	return result
 }
 
 func normalizeArtistName(name string) string {

go_backend/lyrics_apple.go

@@ -0,0 +1,297 @@
+package gobackend
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"math"
+	"net/http"
+	"net/url"
+	"strings"
+	"time"
+)
+
+type AppleMusicClient struct {
+	httpClient *http.Client
+}
+
+type appleMusicSearchResult struct {
+	ID         string `json:"id"`
+	SongName   string `json:"songName"`
+	ArtistName string `json:"artistName"`
+	AlbumName  string `json:"albumName"`
+	Duration   int    `json:"duration"`
+}
+
+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),
+	}
+}
+
+func selectBestAppleMusicSearchResult(results []appleMusicSearchResult, trackName, artistName string, durationSec float64) *appleMusicSearchResult {
+	if len(results) == 0 {
+		return nil
+	}
+
+	normalizedTrack := strings.ToLower(strings.TrimSpace(simplifyTrackName(trackName)))
+	normalizedArtist := strings.ToLower(strings.TrimSpace(normalizeArtistName(artistName)))
+	if normalizedArtist == "" {
+		normalizedArtist = strings.ToLower(strings.TrimSpace(artistName))
+	}
+
+	bestIndex := 0
+	bestScore := -1
+	for i := range results {
+		result := &results[i]
+		score := 0
+
+		candidateTrack := strings.ToLower(strings.TrimSpace(simplifyTrackName(result.SongName)))
+		candidateArtist := strings.ToLower(strings.TrimSpace(normalizeArtistName(result.ArtistName)))
+
+		switch {
+		case candidateTrack == normalizedTrack:
+			score += 50
+		case strings.Contains(candidateTrack, normalizedTrack) || strings.Contains(normalizedTrack, candidateTrack):
+			score += 25
+		}
+
+		switch {
+		case candidateArtist == normalizedArtist:
+			score += 60
+		case strings.Contains(candidateArtist, normalizedArtist) || strings.Contains(normalizedArtist, candidateArtist):
+			score += 30
+		}
+
+		if durationSec > 0 && result.Duration > 0 {
+			diff := math.Abs(float64(result.Duration)/1000.0 - durationSec)
+			if diff <= durationToleranceSec {
+				score += 20
+			}
+		}
+
+		if score > bestScore {
+			bestScore = score
+			bestIndex = i
+		}
+	}
+
+	return &results[bestIndex]
+}
+
+func (c *AppleMusicClient) SearchSong(trackName, artistName string, durationSec float64) (string, error) {
+	query := trackName + " " + artistName
+	if strings.TrimSpace(query) == "" {
+		return "", fmt.Errorf("empty search query")
+	}
+
+	encodedQuery := url.QueryEscape(query)
+	searchURL := fmt.Sprintf("https://lyrics.paxsenix.org/apple-music/search?q=%s", encodedQuery)
+
+	req, err := http.NewRequest("GET", searchURL, nil)
+	if err != nil {
+		return "", fmt.Errorf("failed to create request: %w", err)
+	}
+
+	req.Header.Set("User-Agent", appUserAgent())
+	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 != 200 {
+		return "", fmt.Errorf("apple music search returned HTTP %d", resp.StatusCode)
+	}
+
+	var searchResp []appleMusicSearchResult
+	if err := json.NewDecoder(resp.Body).Decode(&searchResp); err != nil {
+		return "", fmt.Errorf("failed to decode apple music response: %w", err)
+	}
+
+	best := selectBestAppleMusicSearchResult(searchResp, trackName, artistName, durationSec)
+	if best == nil || strings.TrimSpace(best.ID) == "" {
+		return "", fmt.Errorf("no songs found on apple music")
+	}
+
+	return strings.TrimSpace(best.ID), nil
+}
+
+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", appUserAgent())
+	req.Header.Set("Accept", "application/json")
+
+	resp, err := c.httpClient.Do(req)
+	if err != nil {
+		return "", fmt.Errorf("apple music lyrics fetch failed: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != 200 {
+		return "", fmt.Errorf("apple music lyrics proxy returned HTTP %d", resp.StatusCode)
+	}
+
+	bodyBytes, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return "", fmt.Errorf("failed to read lyrics response: %w", err)
+	}
+
+	bodyStr := strings.TrimSpace(string(bodyBytes))
+	if bodyStr == "" {
+		return "", fmt.Errorf("empty lyrics response from apple music")
+	}
+
+	return bodyStr, nil
+}
+
+func formatPaxLyricsToLRC(rawJSON string, multiPersonWordByWord bool) (string, error) {
+	var paxResp paxResponse
+	if err := json.Unmarshal([]byte(rawJSON), &paxResp); err == nil && paxResp.Content != nil {
+		return formatPaxContent(paxResp.Type, paxResp.Content, multiPersonWordByWord), nil
+	}
+
+	var directLyrics []paxLyrics
+	if err := json.Unmarshal([]byte(rawJSON), &directLyrics); err == nil && len(directLyrics) > 0 {
+		return formatPaxContent("Syllable", directLyrics, multiPersonWordByWord), nil
+	}
+
+	return "", fmt.Errorf("failed to parse pax lyrics response")
+}
+
+func appendPaxLyricDetail(builder *strings.Builder, details []paxLyricDetail) {
+	lastStart := ""
+
+	for _, syllable := range details {
+		if syllable.Timestamp != nil {
+			start := fmt.Sprintf("<%s>", msToLRCTimestampInline(int64(*syllable.Timestamp)))
+			if start != lastStart {
+				builder.WriteString(start)
+				lastStart = start
+			}
+		}
+
+		builder.WriteString(syllable.Text)
+		if !syllable.Part {
+			builder.WriteString(" ")
+		}
+
+		if syllable.EndTime != nil {
+			builder.WriteString(fmt.Sprintf("<%s>", msToLRCTimestampInline(int64(*syllable.EndTime))))
+		}
+	}
+}
+
+func formatPaxContent(lyricsType string, content []paxLyrics, multiPersonWordByWord bool) string {
+	var sb strings.Builder
+
+	for i, line := range content {
+		if i > 0 {
+			sb.WriteString("\n")
+		}
+
+		timestamp := msToLRCTimestamp(int64(line.Timestamp))
+
+		if strings.EqualFold(lyricsType, "Syllable") {
+			sb.WriteString(timestamp)
+			if multiPersonWordByWord {
+				if line.OppositeTurn {
+					sb.WriteString("v2:")
+				} else {
+					sb.WriteString("v1:")
+				}
+			}
+
+			appendPaxLyricDetail(&sb, line.Text)
+
+			if line.Background && multiPersonWordByWord && len(line.BackgroundText) > 0 {
+				sb.WriteString("\n[bg:")
+				appendPaxLyricDetail(&sb, line.BackgroundText)
+				sb.WriteString("]")
+			}
+		} else {
+			if len(line.Text) > 0 {
+				sb.WriteString(timestamp)
+				sb.WriteString(line.Text[0].Text)
+			}
+		}
+	}
+
+	return strings.TrimSpace(sb.String())
+}
+
+func (c *AppleMusicClient) FetchLyrics(
+	trackName,
+	artistName string,
+	durationSec float64,
+	multiPersonWordByWord bool,
+) (*LyricsResponse, error) {
+	songID, err := c.SearchSong(trackName, artistName, durationSec)
+	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)
+	}
+
+	lrcText, err := formatPaxLyricsToLRC(rawLyrics, multiPersonWordByWord)
+	if err != nil {
+		lrcText = rawLyrics
+	}
+
+	lines := parseSyncedLyrics(lrcText)
+	if len(lines) > 0 {
+		return &LyricsResponse{
+			Lines:    lines,
+			SyncType: "LINE_SYNCED",
+			Provider: "Apple Music",
+			Source:   "Apple Music",
+		}, nil
+	}
+
+	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")
+}

go_backend/lyrics_musixmatch.go

@@ -0,0 +1,188 @@
+package gobackend
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"math"
+	"net/http"
+	"net/url"
+	"strings"
+	"time"
+)
+
+type MusixmatchClient struct {
+	httpClient *http.Client
+	baseURL    string
+}
+
+type musixmatchSearchResponse struct {
+	ID                 int64                     `json:"id"`
+	SongName           string                    `json:"songName"`
+	ArtistName         string                    `json:"artistName"`
+	AlbumName          string                    `json:"albumName"`
+	Artwork            string                    `json:"artwork"`
+	ReleaseDate        string                    `json:"releaseDate"`
+	Duration           int                       `json:"duration"`
+	URL                string                    `json:"url"`
+	AlbumID            int64                     `json:"albumId"`
+	HasSyncedLyrics    bool                      `json:"hasSyncedLyrics"`
+	HasUnsyncedLyrics  bool                      `json:"hasUnsyncedLyrics"`
+	AvailableLanguages []string                  `json:"availableLanguages"`
+	OriginalLanguage   string                    `json:"originalLanguage"`
+	SyncedLyrics       *musixmatchLyricsResponse `json:"syncedLyrics"`
+	UnsyncedLyrics     *musixmatchLyricsResponse `json:"unsyncedLyrics"`
+}
+
+type musixmatchLyricsResponse struct {
+	ID          int64  `json:"id"`
+	Duration    int    `json:"duration"`
+	Language    string `json:"language"`
+	UpdatedTime string `json:"updatedTime"`
+	Lyrics      string `json:"lyrics"`
+}
+
+func NewMusixmatchClient() *MusixmatchClient {
+	return &MusixmatchClient{
+		httpClient: NewMetadataHTTPClient(15 * time.Second),
+		baseURL:    "https://lyrics.paxsenix.org/musixmatch/lyrics",
+	}
+}
+
+func (c *MusixmatchClient) fetchLyricsPayload(trackName, artistName string, durationSec float64, lyricsType, language string) (string, error) {
+	if strings.TrimSpace(trackName) == "" || strings.TrimSpace(artistName) == "" {
+		return "", fmt.Errorf("empty track or artist name")
+	}
+
+	params := url.Values{}
+	params.Set("t", trackName)
+	params.Set("a", artistName)
+	params.Set("type", lyricsType)
+	params.Set("format", "lrc")
+	if durationSec > 0 {
+		params.Set("d", fmt.Sprintf("%d", int(math.Round(durationSec))))
+	}
+	if strings.TrimSpace(language) != "" {
+		params.Set("l", strings.ToLower(strings.TrimSpace(language)))
+	}
+	fullURL := c.baseURL + "?" + params.Encode()
+
+	req, err := http.NewRequest("GET", fullURL, nil)
+	if err != nil {
+		return "", fmt.Errorf("failed to create request: %w", err)
+	}
+	req.Header.Set("Accept", "application/json")
+	req.Header.Set("User-Agent", appUserAgent())
+
+	resp, err := c.httpClient.Do(req)
+	if err != nil {
+		return "", fmt.Errorf("musixmatch request failed: %w", err)
+	}
+	defer resp.Body.Close()
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return "", fmt.Errorf("failed to read musixmatch response: %w", err)
+	}
+
+	if resp.StatusCode != 200 {
+		trimmed := strings.TrimSpace(string(body))
+		if errMsg, isErrorPayload := detectLyricsErrorPayload(trimmed); isErrorPayload {
+			return "", fmt.Errorf("musixmatch proxy returned HTTP %d: %s", resp.StatusCode, errMsg)
+		}
+		return "", fmt.Errorf("musixmatch proxy returned HTTP %d", resp.StatusCode)
+	}
+
+	var lrcPayload string
+	if err := json.Unmarshal(body, &lrcPayload); err == nil {
+		lrcPayload = strings.TrimSpace(lrcPayload)
+		if lrcPayload == "" {
+			return "", fmt.Errorf("empty musixmatch lyrics payload")
+		}
+		return lrcPayload, nil
+	}
+
+	trimmed := strings.TrimSpace(string(body))
+	if errMsg, isErrorPayload := detectLyricsErrorPayload(trimmed); isErrorPayload {
+		return "", fmt.Errorf("%s", errMsg)
+	}
+	if trimmed != "" && !strings.HasPrefix(trimmed, "{") {
+		return trimmed, nil
+	}
+	return "", fmt.Errorf("failed to decode musixmatch response")
+}
+
+func (c *MusixmatchClient) FetchLyricsInLanguage(trackName, artistName string, durationSec float64, language string) (*LyricsResponse, error) {
+	lang := strings.ToLower(strings.TrimSpace(language))
+	if lang == "" {
+		return nil, fmt.Errorf("invalid language")
+	}
+
+	lrcText, err := c.fetchLyricsPayload(trackName, artistName, durationSec, "translate", lang)
+	if err != nil {
+		return nil, err
+	}
+
+	lines := parseSyncedLyrics(lrcText)
+	if len(lines) > 0 {
+		return &LyricsResponse{
+			Lines:       lines,
+			SyncType:    "LINE_SYNCED",
+			PlainLyrics: plainLyricsFromTimedLines(lines),
+			Provider:    "Musixmatch",
+			Source:      fmt.Sprintf("Musixmatch (%s)", lang),
+		}, nil
+	}
+
+	plainLines := plainTextLyricsLines(lrcText)
+	if len(plainLines) > 0 {
+		return &LyricsResponse{
+			Lines:       plainLines,
+			SyncType:    "UNSYNCED",
+			PlainLyrics: lrcText,
+			Provider:    "Musixmatch",
+			Source:      fmt.Sprintf("Musixmatch (%s)", lang),
+		}, nil
+	}
+
+	return nil, fmt.Errorf("no lyrics found on musixmatch for language %s", lang)
+}
+
+func (c *MusixmatchClient) FetchLyrics(trackName, artistName string, durationSec float64, preferredLanguage string) (*LyricsResponse, error) {
+	if preferred := strings.ToLower(strings.TrimSpace(preferredLanguage)); preferred != "" {
+		localized, localizedErr := c.FetchLyricsInLanguage(trackName, artistName, durationSec, preferred)
+		if localizedErr == nil {
+			return localized, nil
+		}
+		GoLog("[Musixmatch] Language override '%s' failed: %v\n", preferred, localizedErr)
+	}
+
+	lrcText, err := c.fetchLyricsPayload(trackName, artistName, durationSec, "word", "")
+	if err != nil {
+		return nil, err
+	}
+
+	lines := parseSyncedLyrics(lrcText)
+	if len(lines) > 0 {
+		return &LyricsResponse{
+			Lines:       lines,
+			SyncType:    "LINE_SYNCED",
+			PlainLyrics: plainLyricsFromTimedLines(lines),
+			Provider:    "Musixmatch",
+			Source:      "Musixmatch",
+		}, nil
+	}
+
+	plainLines := plainTextLyricsLines(lrcText)
+	if len(plainLines) > 0 {
+		return &LyricsResponse{
+			Lines:       plainLines,
+			SyncType:    "UNSYNCED",
+			PlainLyrics: lrcText,
+			Provider:    "Musixmatch",
+			Source:      "Musixmatch",
+		}, nil
+	}
+
+	return nil, fmt.Errorf("no lyrics found on musixmatch")
+}

go_backend/lyrics_netease.go

@@ -0,0 +1,195 @@
+package gobackend
+
+import (
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/url"
+	"strings"
+	"time"
+)
+
+type NeteaseClient struct {
+	httpClient *http.Client
+}
+
+type neteaseSearchResponse struct {
+	Result struct {
+		Songs []struct {
+			Name    string `json:"name"`
+			ID      int64  `json:"id"`
+			Artists []struct {
+				Name string `json:"name"`
+			} `json:"artists"`
+		} `json:"songs"`
+		SongCount int `json:"songCount"`
+	} `json:"result"`
+	Code int `json:"code"`
+}
+
+type neteaseLyricsResponse struct {
+	LRC     *neteaseLyricField `json:"lrc"`
+	TLyric  *neteaseLyricField `json:"tlyric"`
+	RomaLRC *neteaseLyricField `json:"romalrc"`
+	Code    int                `json:"code"`
+}
+
+type neteaseLyricField struct {
+	Lyric string `json:"lyric"`
+}
+
+var neteaseHeaders = map[string]string{
+	"Accept":          "application/json",
+	"Accept-Language": "en-US,en;q=0.9",
+	"Cache-Control":   "max-age=0",
+}
+
+func NewNeteaseClient() *NeteaseClient {
+	return &NeteaseClient{
+		httpClient: NewMetadataHTTPClient(15 * time.Second),
+	}
+}
+
+func (c *NeteaseClient) SearchSong(trackName, artistName string) (int64, error) {
+	query := trackName + " " + artistName
+	if strings.TrimSpace(query) == "" {
+		return 0, fmt.Errorf("empty search query")
+	}
+
+	searchURL := "https://lyrics.paxsenix.org/netease/search"
+	params := url.Values{}
+	params.Set("q", query)
+
+	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", appUserAgent())
+
+	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
+}
+
+func (c *NeteaseClient) FetchLyricsByID(songID int64, includeTranslation, includeRomanization bool) (string, error) {
+	lyricsURL := "https://lyrics.paxsenix.org/netease/lyrics"
+	params := url.Values{}
+	params.Set("id", fmt.Sprintf("%d", songID))
+
+	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", appUserAgent())
+
+	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
+}
+
+func (c *NeteaseClient) FetchLyrics(
+	trackName,
+	artistName string,
+	durationSec float64,
+	includeTranslation,
+	includeRomanization bool,
+) (*LyricsResponse, error) {
+	songID, err := c.SearchSong(trackName, artistName)
+	if err != nil {
+		return nil, err
+	}
+
+	lrcText, err := c.FetchLyricsByID(songID, includeTranslation, includeRomanization)
+	if err != nil {
+		return nil, err
+	}
+
+	lines := parseSyncedLyrics(lrcText)
+	if len(lines) == 0 {
+		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
+}

go_backend/lyrics_qqmusic.go

@@ -0,0 +1,138 @@
+package gobackend
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"math"
+	"net/http"
+	"strings"
+	"time"
+)
+
+type QQMusicClient struct {
+	httpClient *http.Client
+}
+
+type qqLyricsMetadataRequest struct {
+	Artist   []string `json:"artist"`
+	Album    string   `json:"album,omitempty"`
+	SongID   int64    `json:"songid,omitempty"`
+	Title    string   `json:"title"`
+	Duration int64    `json:"duration,omitempty"`
+}
+
+type qqLyricsMetadataResponse struct {
+	Lyrics []paxLyrics `json:"lyrics"`
+}
+
+func NewQQMusicClient() *QQMusicClient {
+	return &QQMusicClient{
+		httpClient: NewMetadataHTTPClient(15 * time.Second),
+	}
+}
+
+func (c *QQMusicClient) fetchLyricsByMetadata(trackName, artistName string, durationSec float64) (string, error) {
+	payload := qqLyricsMetadataRequest{
+		Artist: []string{artistName},
+		Title:  trackName,
+	}
+	if durationSec > 0 {
+		payload.Duration = int64(math.Round(durationSec))
+	}
+
+	lyricsURL := "https://lyrics.paxsenix.org/qq/lyrics-metadata"
+
+	payloadBytes, err := json.Marshal(payload)
+	if err != nil {
+		return "", fmt.Errorf("failed to marshal payload: %w", err)
+	}
+
+	req, err := http.NewRequest("POST", lyricsURL, strings.NewReader(string(payloadBytes)))
+	if err != nil {
+		return "", fmt.Errorf("failed to create request: %w", err)
+	}
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Accept", "application/json")
+	req.Header.Set("User-Agent", appUserAgent())
+
+	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
+}
+
+func formatQQLyricsMetadataToLRC(rawJSON string, multiPersonWordByWord bool) (string, error) {
+	var response qqLyricsMetadataResponse
+	if err := json.Unmarshal([]byte(rawJSON), &response); err != nil {
+		return "", fmt.Errorf("failed to parse qq metadata lyrics response")
+	}
+	if len(response.Lyrics) == 0 {
+		return "", fmt.Errorf("qq metadata lyrics response was empty")
+	}
+	return formatPaxContent("Syllable", response.Lyrics, multiPersonWordByWord), nil
+}
+
+func (c *QQMusicClient) FetchLyrics(
+	trackName,
+	artistName string,
+	durationSec float64,
+	multiPersonWordByWord bool,
+) (*LyricsResponse, error) {
+	rawLyrics, err := c.fetchLyricsByMetadata(trackName, artistName, durationSec)
+	if err != nil {
+		return nil, err
+	}
+	if errMsg, isErrorPayload := detectLyricsErrorPayload(rawLyrics); isErrorPayload {
+		return nil, fmt.Errorf("qqmusic proxy returned non-lyric payload: %s", errMsg)
+	}
+
+	lrcText, err := formatQQLyricsMetadataToLRC(rawLyrics, multiPersonWordByWord)
+	if err != nil {
+		if fallback, fallbackErr := formatPaxLyricsToLRC(rawLyrics, multiPersonWordByWord); fallbackErr == nil {
+			lrcText = fallback
+		} else {
+			lrcText = rawLyrics
+		}
+	}
+
+	lines := parseSyncedLyrics(lrcText)
+	if len(lines) > 0 {
+		return &LyricsResponse{
+			Lines:    lines,
+			SyncType: "LINE_SYNCED",
+			Provider: "QQ Music",
+			Source:   "QQ Music",
+		}, nil
+	}
+
+	resultLines := plainTextLyricsLines(lrcText)
+
+	if len(resultLines) > 0 {
+		return &LyricsResponse{
+			Lines:    resultLines,
+			SyncType: "UNSYNCED",
+			Provider: "QQ Music",
+			Source:   "QQ Music",
+		}, nil
+	}
+
+	return nil, fmt.Errorf("no lyrics found on qqmusic")
+}

go_backend/metadata_artist_tags_test.go

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

go_backend/metadata_m4a_quality_test.go

@@ -0,0 +1,49 @@
+package gobackend
+
+import "testing"
+
+func TestParseALACSpecificConfigStandardPayload(t *testing.T) {
+	payload := make([]byte, 24)
+	payload[5] = 24
+	payload[20] = 0x00
+	payload[21] = 0x00
+	payload[22] = 0xac
+	payload[23] = 0x44
+
+	bitDepth, sampleRate, ok := parseALACSpecificConfig(payload)
+	if !ok {
+		t.Fatal("expected standard ALAC payload to parse")
+	}
+	if bitDepth != 24 {
+		t.Fatalf("bitDepth = %d, want 24", bitDepth)
+	}
+	if sampleRate != 44100 {
+		t.Fatalf("sampleRate = %d, want 44100", sampleRate)
+	}
+}
+
+func TestParseALACSpecificConfigPayloadWithLeadingFourBytes(t *testing.T) {
+	payload := make([]byte, 28)
+	payload[9] = 16
+	payload[24] = 0x00
+	payload[25] = 0x00
+	payload[26] = 0xbb
+	payload[27] = 0x80
+
+	bitDepth, sampleRate, ok := parseALACSpecificConfig(payload)
+	if !ok {
+		t.Fatal("expected offset ALAC payload to parse")
+	}
+	if bitDepth != 16 {
+		t.Fatalf("bitDepth = %d, want 16", bitDepth)
+	}
+	if sampleRate != 48000 {
+		t.Fatalf("sampleRate = %d, want 48000", sampleRate)
+	}
+}
+
+func TestParseALACSpecificConfigRejectsShortPayload(t *testing.T) {
+	if _, _, ok := parseALACSpecificConfig(make([]byte, 12)); ok {
+		t.Fatal("expected short ALAC payload to be rejected")
+	}
+}

go_backend/metadata_types.go

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

go_backend/mobile_deps.go

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

go_backend/output_fd.go

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

go_backend/output_fd_unix.go

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