chore: update AltStore source to v4.7.1

feat(extensions): embed full metadata and cover after extension downloads
Replace duplicate genre/label-only embedding with a shared post-download step that writes complete FLAC tags and optional cover art when the output file is available locally.
2026-07-02 19:05:57 +02:00 · 2026-07-01 18:42:31 +00:00 · 2026-07-02 01:24:22 +07:00 · 2026-07-02 01:24:22 +07:00 · 2026-07-02 01:24:21 +07:00 · 2026-07-02 01:24:21 +07:00
376 changed files with 342785 additions and 14769 deletions
@@ -0,0 +1,3 @@
+{
+  "flutter": "3.41.5"
+}
@@ -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
@@ -0,0 +1,3 @@
+github: zarzet
+ko_fi: zarzet
+
@@ -0,0 +1,123 @@
+name: Bug Report
+description: Report a bug or unexpected behavior
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report a bug! Please fill out the form below.
+
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: Checklist
+      description: Please confirm the following before submitting
+      options:
+        - label: I have searched existing issues and this bug hasn't been reported yet
+          required: true
+        - label: I am using the latest version of SpotiFLAC (Stable Version)
+          required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Bug Description
+      description: A clear and concise description of what the bug is
+      placeholder: Describe the bug...
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to Reproduce
+      description: Steps to reproduce the behavior
+      placeholder: |
+        1. Go to '...'
+        2. Click on '...'
+        3. See error
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What did you expect to happen?
+      placeholder: Describe what you expected...
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual Behavior
+      description: What actually happened?
+      placeholder: Describe what actually happened...
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: App Version
+      description: Which version of SpotiFLAC are you using? (Check in Settings > About)
+      placeholder: "e.g., v2.2.0"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: platform
+    attributes:
+      label: Platform
+      description: Which platform are you using?
+      options:
+        - Android
+        - iOS
+    validations:
+      required: true
+
+  - type: input
+    id: device
+    attributes:
+      label: Device & OS Version
+      description: What device and OS version are you using?
+      placeholder: "e.g., Samsung Galaxy S24, Android 14"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: download-service
+    attributes:
+      label: Download Service
+      description: Which download service were you using when the bug occurred?
+      options:
+        - Tidal
+        - Qobuz
+        - Amazon Music
+        - Deezer (search only)
+        - Not applicable
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs / Screenshots
+      description: |
+        If applicable, add logs or screenshots to help explain your problem.
+        
+        **To get logs:**
+        1. Go to Settings > Options > Detailed Logging (turn ON)
+        2. Reproduce the bug
+        3. Go to Settings > Logs
+        4. Tap Share button to export logs
+      placeholder: Paste logs or drag & drop screenshots here...
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional Context
+      description: Any other context about the problem
+      placeholder: Add any other context...
@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: README
+    url: https://github.com/zarzet/SpotiFLAC-Mobile#readme
+    about: Check the README for setup instructions and FAQ
+  - name: Extension Development Guide
+    url: https://spotiflac.zarz.moe/docs
+    about: Documentation for building SpotiFLAC extensions
@@ -0,0 +1,111 @@
+name: Download Issue
+description: Report issues with downloading specific tracks or albums
+title: "[Download]: "
+labels: ["download-issue"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Having trouble downloading a specific track or album? Please provide details below.
+
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: Checklist
+      description: Please confirm the following before submitting
+      options:
+        - label: I have tried downloading with a different service (Tidal/Qobuz/Amazon)
+          required: true
+        - label: I am using the latest version of SpotiFLAC (Stable Version)
+          required: true
+
+  - type: dropdown
+    id: issue-type
+    attributes:
+      label: Issue Type
+      description: What kind of download issue are you experiencing?
+      options:
+        - Track not found on service
+        - Wrong track downloaded
+        - Download fails/errors
+        - Metadata incorrect
+        - Audio quality issue
+        - Other
+    validations:
+      required: true
+
+  - type: input
+    id: spotify-url
+    attributes:
+      label: Spotify URL
+      description: The Spotify URL of the track/album you're trying to download
+      placeholder: "https://open.spotify.com/track/..."
+    validations:
+      required: true
+
+  - type: input
+    id: track-info
+    attributes:
+      label: Track Info
+      description: Artist name and track title
+      placeholder: "Artist - Track Title"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: download-service
+    attributes:
+      label: Download Service
+      description: Which service did you try to download from?
+      options:
+        - Tidal
+        - Qobuz
+        - Amazon Music
+        - All services
+    validations:
+      required: true
+
+  - type: dropdown
+    id: search-service
+    attributes:
+      label: Search Service
+      description: Which search service are you using?
+      options:
+        - Spotify
+        - Deezer
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: Describe the issue in detail
+      placeholder: |
+        What happened? What did you expect?
+        If wrong track was downloaded, what track was downloaded instead?
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: App Version
+      description: Which version of SpotiFLAC are you using?
+      placeholder: "e.g., v2.2.0"
+    validations:
+      required: true
+
+  - type: textarea
+    id: screenshots
+    attributes:
+      label: Screenshots / Logs
+      description: |
+        If applicable, add screenshots or logs.
+        
+        **To get logs:**
+        1. Go to Settings > Options > Detailed Logging (turn ON)
+        2. Try downloading the track again
+        3. Go to Settings > Logs
+        4. Tap Share button to export logs
+      placeholder: Drag & drop screenshots or paste logs here...
@@ -0,0 +1,117 @@
+name: Extension API Feature Request
+description: Request new API features or capabilities for extension development
+title: "[Extension API]: "
+labels: ["enhancement", "extension-api"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for helping improve the SpotiFLAC Extension API! 
+        This form is for extension developers who need new features or capabilities that don't exist yet.
+
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: Checklist
+      description: Please confirm the following before submitting
+      options:
+        - label: I have read the [Extension Development Guide](https://github.com/zarzet/SpotiFLAC-Mobile/blob/main/docs/EXTENSION_DEVELOPMENT.md)
+          required: true
+        - label: I have searched existing issues and this API feature hasn't been requested yet
+          required: true
+
+  - type: textarea
+    id: extension_goal
+    attributes:
+      label: What are you trying to build?
+      description: Describe the extension or feature you're developing
+      placeholder: "I'm building an extension that downloads from [service name] / provides metadata from [source]..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: current_limitation
+    attributes:
+      label: Current API Limitation
+      description: What's missing or limiting in the current extension API?
+      placeholder: |
+        The current API doesn't support:
+        - [missing feature 1]
+        - [missing feature 2]
+        
+        This prevents me from...
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposed_api
+    attributes:
+      label: Proposed API / Feature
+      description: Describe the API or feature you'd like to see added
+      placeholder: |
+        I would like to have:
+        - A new function `api.newFeature()` that does X
+        - A new manifest field `newOption` that enables Y
+        - Access to Z capability...
+    validations:
+      required: true
+
+  - type: textarea
+    id: use_case
+    attributes:
+      label: Use Case Example
+      description: Provide a code example of how you would use this feature
+      placeholder: |
+        ```javascript
+        // Example usage in extension code
+        function download(request, progressCallback) {
+          const result = api.proposedFeature(params);
+          // ...
+        }
+        ```
+    validations:
+      required: false
+
+  - type: dropdown
+    id: api_category
+    attributes:
+      label: API Category
+      description: What category does this feature fall under?
+      options:
+        - HTTP/Network API
+        - File System API
+        - Storage API
+        - FFmpeg/Audio Processing
+        - Manifest Options
+        - Runtime Functions
+        - UI Integration
+        - Authentication
+        - Other
+    validations:
+      required: true
+
+  - type: dropdown
+    id: priority
+    attributes:
+      label: How critical is this for your extension?
+      options:
+        - Blocker - Cannot build my extension without this
+        - High - Major functionality depends on this
+        - Medium - Would significantly improve my extension
+        - Low - Nice to have
+    validations:
+      required: true
+
+  - type: textarea
+    id: workaround
+    attributes:
+      label: Current Workaround
+      description: Are you using any workaround currently? If so, describe it.
+      placeholder: "Currently I'm working around this by..."
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional Context
+      description: Add any other context, links to similar APIs, or examples from other platforms
+      placeholder: "Similar feature in other platforms: ..."
@@ -0,0 +1,66 @@
+name: Feature Request
+description: Suggest a new feature or improvement
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for suggesting a feature! Please fill out the form below.
+
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: Checklist
+      description: Please confirm the following before submitting
+      options:
+        - label: I have searched existing issues and this feature hasn't been requested yet
+          required: true
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem / Motivation
+      description: Is your feature request related to a problem? Please describe.
+      placeholder: "A clear description of what the problem is. Ex: I'm always frustrated when..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Solution
+      description: Describe the solution you'd like
+      placeholder: A clear description of what you want to happen...
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: Describe any alternative solutions or features you've considered
+      placeholder: Other approaches you've thought about...
+
+  - type: dropdown
+    id: category
+    attributes:
+      label: Category
+      description: What category does this feature fall under?
+      options:
+        - UI/UX Improvement
+        - Download Feature
+        - New Service Integration
+        - Metadata/Tagging
+        - Performance
+        - Settings/Configuration
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional Context
+      description: Add any other context, mockups, or screenshots about the feature request
+      placeholder: Add any other context or screenshots...
@@ -15,7 +15,7 @@ jobs:
    
    steps:
      - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
        with:
          fetch-depth: 2  # Need previous commit to compare

@@ -0,0 +1,44 @@
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'site/**'
+      - '.github/workflows/pages.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
@@ -3,13 +3,13 @@ name: Release
 on:
  push:
    tags:
-      - 'v*'
+      - "v*"
  workflow_dispatch:
    inputs:
      version:
-        description: 'Version tag (e.g., v1.0.0)'
+        description: "Version tag (e.g., v1.0.0)"
        required: true
-        default: 'v1.0.0'
+        default: "v1.0.0"

 jobs:
  # Get version first (quick job)
@@ -28,7 +28,7 @@ jobs:
            VERSION="${GITHUB_REF#refs/tags/}"
          fi
          echo "version=$VERSION" >> $GITHUB_OUTPUT
-          
+
          # Check if version contains -preview, -beta, -rc, or -alpha (NOT -hotfix)
          VERSION_LOWER=$(echo "$VERSION" | tr '[:upper:]' '[:lower:]')
          if [[ "$VERSION_LOWER" == *"-preview"* ]] || [[ "$VERSION_LOWER" == *"-beta"* ]] || [[ "$VERSION_LOWER" == *"-rc"* ]] || [[ "$VERSION_LOWER" == *"-alpha"* ]]; then
@@ -43,7 +43,7 @@ jobs:
  build-android:
    runs-on: ubuntu-latest
    needs: get-version
-    
+
    steps:
      - name: Free disk space
        run: |
@@ -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'
+          distribution: "temurin"
+          java-version: "25"

      - name: Setup Go
-        uses: actions/setup-go@v5
+        uses: actions/setup-go@v6
        with:
-          go-version: '1.21'
+          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
@@ -89,15 +89,16 @@ jobs:
          # Use pre-installed Android SDK on GitHub runners
          echo "ANDROID_HOME=$ANDROID_HOME"
          echo "ANDROID_SDK_ROOT=$ANDROID_SDK_ROOT"
-          
+
          # Accept licenses
          yes | $ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager --licenses || true
-          
-          # Install NDK (required for gomobile)
-          $ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager "ndk;25.2.9519653" "platforms;android-34" "build-tools;34.0.0"
-          
+
+          # 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;29.0.14206865" "platforms;android-36" "build-tools;36.0.0"
+
          # Set NDK path
-          echo "ANDROID_NDK_HOME=$ANDROID_HOME/ndk/25.2.9519653" >> $GITHUB_ENV
+          echo "ANDROID_NDK_HOME=$ANDROID_HOME/ndk/29.0.14206865" >> $GITHUB_ENV

      - name: Install gomobile
        run: |
@@ -115,7 +116,7 @@ jobs:
      - name: Setup Flutter
        uses: subosito/flutter-action@v2
        with:
-          channel: 'stable'
+          channel: "stable"
          cache: true

      - name: Get Flutter dependencies
@@ -125,7 +126,14 @@ jobs:
        run: dart run flutter_launcher_icons

      - name: Build APK (Release - unsigned)
-        run: flutter build apk --release --split-per-abi
+        run: |
+          flutter build apk --release --split-per-abi || true
+          # Verify APKs were created
+          ls -la build/app/outputs/flutter-apk/
+          if [ ! -f "build/app/outputs/flutter-apk/app-arm64-v8a-release.apk" ]; then
+            echo "ERROR: APK not found!"
+            exit 1
+          fi

      - name: Sign APKs
        uses: r0adkll/sign-android-release@v1
@@ -137,7 +145,7 @@ jobs:
          keyStorePassword: ${{ secrets.KEYSTORE_PASSWORD }}
          keyPassword: ${{ secrets.KEY_PASSWORD }}
        env:
-          BUILD_TOOLS_VERSION: "34.0.0"
+          BUILD_TOOLS_VERSION: "36.0.0"

      - name: Rename APKs
        run: |
@@ -150,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
-    needs: get-version  # Only depends on version, NOT android build!
-    
+    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.21'
+          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') }}
@@ -186,7 +199,7 @@ jobs:
        working-directory: go_backend
        run: |
          mkdir -p ../ios/Frameworks
-          gomobile bind -target=ios -o ../ios/Frameworks/Gobackend.xcframework .
+          gomobile bind -target=ios -tags ios -o ../ios/Frameworks/Gobackend.xcframework .
        env:
          CGO_ENABLED: 1

@@ -194,91 +207,109 @@ jobs:
        run: |
          ls -la ios/Frameworks/
          ls -la ios/Frameworks/Gobackend.xcframework/ || (echo "ERROR: XCFramework not found!" && exit 1)
-          
+
      - name: Add XCFramework to Xcode project
        run: |
          # Install xcodeproj gem for modifying Xcode project
          sudo gem install xcodeproj
-          
+
          # Create Ruby script to add framework
          cat > add_framework.rb << 'EOF'
          require 'xcodeproj'
-          
+
          project_path = 'ios/Runner.xcodeproj'
          project = Xcodeproj::Project.open(project_path)
-          
+
          # Get the main target
          target = project.targets.find { |t| t.name == 'Runner' }
-          
+
          # Get or create Frameworks group
          frameworks_group = project.main_group.find_subpath('Frameworks', true)
          frameworks_group ||= project.main_group.new_group('Frameworks')
-          
+
          # Add XCFramework reference
          framework_path = 'Frameworks/Gobackend.xcframework'
          framework_ref = frameworks_group.new_file(framework_path, :project)
-          
+
          # Add to frameworks build phase
          frameworks_build_phase = target.frameworks_build_phase
          frameworks_build_phase.add_file_reference(framework_ref)
-          
+
          # Add to embed frameworks build phase
          embed_phase = target.build_phases.find { |p| p.is_a?(Xcodeproj::Project::Object::PBXCopyFilesBuildPhase) && p.name == 'Embed Frameworks' }
          if embed_phase
            build_file = embed_phase.add_file_reference(framework_ref)
            build_file.settings = { 'ATTRIBUTES' => ['CodeSignOnCopy', 'RemoveHeadersOnCopy'] }
          end
-          
+
          project.save
          puts "Successfully added Gobackend.xcframework to Xcode project"
          EOF
-          
+
          ruby add_framework.rb

      - name: Setup Flutter
        uses: subosito/flutter-action@v2
        with:
-          channel: 'stable'
+          channel: "stable"
          cache: true

-      # Swap pubspec for iOS build (includes ffmpeg_kit_flutter)
-      - name: Use iOS pubspec with FFmpeg plugin
-        run: |
-          cp pubspec.yaml pubspec_android_backup.yaml
-          cp pubspec_ios.yaml pubspec.yaml
-          echo "Swapped to iOS pubspec with ffmpeg_kit_flutter"
-
-      # Swap FFmpeg service for iOS
-      - name: Use iOS FFmpeg service
-        run: |
-          cp lib/services/ffmpeg_service.dart lib/services/ffmpeg_service_android.dart
-          cp build_assets/ffmpeg_service_ios.dart lib/services/ffmpeg_service.dart
-          # Update class name in the swapped file
-          sed -i '' 's/FFmpegServiceIOS/FFmpegService/g' lib/services/ffmpeg_service.dart
-          sed -i '' 's/FFmpegResultIOS/FFmpegResult/g' lib/services/ffmpeg_service.dart
-          echo "Swapped to iOS FFmpeg service"
-
      - name: Get Flutter dependencies
        run: flutter pub get

+      - name: Normalize ffmpeg plugin shell scripts (strip CRLF)
+        run: |
+          find "$HOME/.pub-cache/hosted" -path "*ffmpeg_kit_flutter_new_full*/scripts/*.sh" -type f -print0 |
+            while IFS= read -r -d '' f; do
+              perl -pi -e 's/\r$//' "$f"
+              chmod +x "$f"
+              echo "Normalized line endings: $f"
+            done
+
      - name: Generate app icons
        run: dart run flutter_launcher_icons

      - name: Build iOS (unsigned)
-        run: flutter build ios --release --no-codesign
+        run: |
+          # Build Flutter iOS without codesigning
+          flutter build ios --release --no-codesign --config-only
+
+          # Use xcodebuild with code signing disabled
+          cd ios
+          xcodebuild -workspace Runner.xcworkspace \
+            -scheme Runner \
+            -configuration Release \
+            -sdk iphoneos \
+            -destination 'generic/platform=iOS' \
+            -archivePath build/Runner.xcarchive \
+            archive \
+            CODE_SIGNING_ALLOWED=NO \
+            CODE_SIGNING_REQUIRED=NO \
+            CODE_SIGN_IDENTITY="" \
+            DEVELOPMENT_TEAM=""

      - name: Create IPA
        run: |
          VERSION=${{ needs.get-version.outputs.version }}
          mkdir -p build/ios/ipa
-          cd build/ios/iphoneos
+          cd ios/build/Runner.xcarchive/Products/Applications
          mkdir Payload
          cp -r Runner.app Payload/
-          zip -r ../ipa/SpotiFLAC-${VERSION}-ios-unsigned.ipa Payload
+          # Use absolute path to avoid relative path issues
+          zip -r $GITHUB_WORKSPACE/build/ios/ipa/SpotiFLAC-${VERSION}-ios-unsigned.ipa Payload
          rm -rf Payload

+      - name: Verify IPA created
+        run: |
+          ls -la build/ios/ipa/
+          VERSION=${{ needs.get-version.outputs.version }}
+          if [ ! -f "build/ios/ipa/SpotiFLAC-${VERSION}-ios-unsigned.ipa" ]; then
+            echo "ERROR: IPA not created!"
+            exit 1
+          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
@@ -288,44 +319,36 @@ jobs:
    needs: [get-version, build-android, build-ios]
    permissions:
      contents: write
-    
+
    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"
-          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
@@ -333,44 +356,233 @@ jobs:
      - name: Prepare release body
        run: |
          VERSION=${{ needs.get-version.outputs.version }}
-          cat > /tmp/release_body.txt << 'HEADER'
-          ## SpotiFLAC $VERSION
-          
-          Download Spotify tracks in FLAC quality from Tidal, Qobuz & Amazon Music.
-          
-          ### What's New
-          HEADER
-          
-          # Replace $VERSION in header
-          sed -i "s/\$VERSION/$VERSION/g" /tmp/release_body.txt
-          
-          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
-          
+
          ---
-          
+
          ### Downloads
-          - **Android (arm64)**: \`SpotiFLAC-${VERSION}-arm64.apk\` (recommended)
-          - **Android (arm32)**: \`SpotiFLAC-${VERSION}-arm32.apk\` (older devices)
+
+          #### Android
+          - **arm64**: \`SpotiFLAC-${VERSION}-arm64.apk\` (recommended for modern devices)
+          - **arm32**: \`SpotiFLAC-${VERSION}-arm32.apk\` (older devices)
+
+          #### iOS
          - **iOS**: \`SpotiFLAC-${VERSION}-ios-unsigned.ipa\` (sideload required)
-          
+
          ### Installation
          **Android**: Enable "Install from unknown sources" and install the APK
          **iOS**: Use AltStore, Sideloadly, or similar tools to sideload the IPA
          FOOTER
-          
+
          echo "Release body:"
          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 }}
+          name: SpotiFLAC-Mobile ${{ needs.get-version.outputs.version }}
          body_path: /tmp/release_body.txt
          files: ./release/*
          draft: false
          prerelease: ${{ needs.get-version.outputs.is_prerelease == 'true' }}
        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]
+    if: ${{ needs.get-version.outputs.is_prerelease != 'true' }}
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Download Android APK
+        uses: actions/download-artifact@v7
+        with:
+          name: android-apk
+          path: ./release
+
+      - name: Download iOS IPA
+        uses: actions/download-artifact@v7
+        with:
+          name: ios-ipa
+          path: ./release
+
+      - 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: |
+          if [ ! -s /tmp/cliff_tg.txt ]; then
+            echo "See release notes on GitHub for details." > /tmp/changelog.txt
+          else
+            # 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/\*\*\([^*]*\)\*\*/<b>\1<\/b>/g' | \
+              sed 's/^### \(.*\)$/<b>\1<\/b>/g' | \
+              sed 's/^## \(.*\)$/<b>\1<\/b>/g' | \
+              sed 's/^- /• /g')
+
+            # Truncate for Telegram 4096 char limit
+            CHANGELOG=$(echo "$CHANGELOG" | head -c 2500 | sed '$d')
+            echo "$CHANGELOG" > /tmp/changelog.txt
+          fi
+
+          echo "Telegram changelog:"
+          cat /tmp/changelog.txt
+
+      - name: Send to Telegram Channel
+        env:
+          TELEGRAM_BOT_TOKEN: ${{ secrets.TELEGRAM_BOT_TOKEN }}
+          TELEGRAM_CHANNEL_ID: ${{ secrets.TELEGRAM_CHANNEL_ID }}
+        run: |
+          VERSION=${{ needs.get-version.outputs.version }}
+          CHANGELOG=$(cat /tmp/changelog.txt)
+          
+          # Find APK files
+          ARM64_APK=$(find ./release -name "*arm64*.apk" | head -1)
+          ARM32_APK=$(find ./release -name "*arm32*.apk" | head -1)
+          
+          # Prepare message with changelog (HTML format)
+          printf '%s\n' \
+            "<b>SpotiFLAC Mobile ${VERSION} Released!</b>" \
+            "" \
+            "<b>What's New:</b>" \
+            "${CHANGELOG}" \
+            "" \
+            "<a href=\"https://github.com/${{ github.repository }}/releases/tag/${VERSION}\">View Release Notes</a>" \
+            > /tmp/telegram_message.txt
+
+          MESSAGE=$(cat /tmp/telegram_message.txt)
+
+          # Send message first (using HTML parse mode)
+          # Use --data-urlencode for proper encoding of special chars (+, &, etc.)
+          # Use || true to ensure file uploads continue even if message fails
+          curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendMessage" \
+            --data-urlencode "chat_id=${TELEGRAM_CHANNEL_ID}" \
+            --data-urlencode "text=${MESSAGE}" \
+            --data-urlencode "parse_mode=HTML" \
+            --data-urlencode "disable_web_page_preview=true" || true
+
+          # Upload arm64 APK to channel
+          if [ -f "$ARM64_APK" ]; then
+            echo "Uploading arm64 APK to Telegram..."
+            curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendDocument" \
+              -F chat_id="${TELEGRAM_CHANNEL_ID}" \
+              -F document=@"${ARM64_APK}" \
+              -F caption="SpotiFLAC Mobile ${VERSION} - arm64 (recommended)"
+          fi
+
+          # Upload arm32 APK to channel
+          if [ -f "$ARM32_APK" ]; then
+            echo "Uploading arm32 APK to Telegram..."
+            curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendDocument" \
+              -F chat_id="${TELEGRAM_CHANNEL_ID}" \
+              -F document=@"${ARM32_APK}" \
+              -F caption="SpotiFLAC Mobile ${VERSION} - arm32"
+          fi
+
+          # Upload iOS IPA to channel
+          IOS_IPA=$(find ./release -name "*ios*.ipa" | head -1)
+          if [ -f "$IOS_IPA" ]; then
+            echo "Uploading iOS IPA to Telegram..."
+            curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendDocument" \
+              -F chat_id="${TELEGRAM_CHANNEL_ID}" \
+              -F document=@"${IOS_IPA}" \
+              -F caption="SpotiFLAC Mobile ${VERSION} - iOS (unsigned, sideload required)"
+          fi
+
+          echo "Telegram notification sent!"
@@ -6,13 +6,21 @@ Thumbs.db
 .idea/
 .vscode/
 *.iml
+.cursorignore
+.cursorrules

 # Kiro specs (development only)
 .kiro/

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

+# Documentation (development only, published separately)
+docs/
+
 # Old spotiflac_android folder (moved to root)
 spotiflac_android/

@@ -36,6 +44,7 @@ go_backend/*.xcframework/
 # Android
 android/.gradle/
 android/app/libs/gobackend.aar
+android/app/libs/gobackend-sources.jar
 android/local.properties
 android/*.iml
 android/key.properties
@@ -49,4 +58,32 @@ ios/Pods/
 ios/.symlinks/
 ios/Flutter/Flutter.framework/
 ios/Flutter/Flutter.podspec
-android/app/libs/gobackend-sources.jar
+
+# Extension folder
+extension/*
+extension/v2/
+extension/v2/**
+
+# Agent instructions
+AGENTS.md
+
+# Temp/misc
+.tmp/
+nul
+NUL
+network_requests.txt
+*.bak
+/AndroidManifest.xml
+
+# Log files
+*.log
+hs_err_*.log
+flutter_*.log
+
+# Development tools
+tool/
+.claude/settings.local.json
+.playwright-mcp/
+
+# FVM Version Cache
+.fvm/
@@ -0,0 +1,133 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+**[zarzet](https://github.com/zarzet)**.
+
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations
@@ -0,0 +1,282 @@
+# Contributing to SpotiFLAC
+
+First off, thank you for considering contributing to SpotiFLAC! 🎉
+
+This document provides guidelines and steps for contributing. Following these guidelines helps maintain code quality and ensures a smooth collaboration process.
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [How Can I Contribute?](#how-can-i-contribute)
+  - [Reporting Bugs](#reporting-bugs)
+  - [Suggesting Features](#suggesting-features)
+  - [Code Contributions](#code-contributions)
+  - [Translations](#translations)
+- [Development Setup](#development-setup)
+- [Project Structure](#project-structure)
+- [Coding Guidelines](#coding-guidelines)
+- [Commit Guidelines](#commit-guidelines)
+- [Pull Request Process](#pull-request-process)
+
+## Code of Conduct
+
+This project and everyone participating in it is governed by our [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to the project maintainers.
+
+## How Can I Contribute?
+
+### Reporting Bugs
+
+Before creating bug reports, please check the [existing issues](https://github.com/zarzet/SpotiFLAC-Mobile/issues) to avoid duplicates.
+
+When creating a bug report, please use the bug report template and include:
+
+- **Clear and descriptive title**
+- **Steps to reproduce** the issue
+- **Expected behavior** vs **actual behavior**
+- **Screenshots or screen recordings** if applicable
+- **Device information** (model, OS version)
+- **App version**
+- **Logs** from Settings > About > View Logs
+
+### Suggesting Features
+
+Feature requests are welcome! Please use the feature request template and:
+
+- **Check existing issues** to avoid duplicates
+- **Describe the feature** clearly
+- **Explain the use case** - why would this be useful?
+- **Consider the scope** - is this a small enhancement or a major feature?
+
+### Code Contributions
+
+1. **Fork the repository** and create your branch from `dev`
+2. **Make your changes** following our coding guidelines
+3. **Test your changes** thoroughly
+4. **Submit a pull request** to the `dev` branch
+
+### Translations
+
+We use [Crowdin](https://crowdin.com/project/spotiflac-mobile) for translations. To contribute:
+
+1. Visit our [Crowdin project](https://crowdin.com/project/spotiflac-mobile)
+2. Select your language or request a new one
+3. Start translating!
+
+Translation files are located in `lib/l10n/arb/`.
+
+## Development Setup
+
+### Prerequisites
+
+- **Flutter SDK** 3.10.0 or higher
+- **Dart SDK** 3.10.0 or higher
+- **Android Studio** or **VS Code** with Flutter extensions
+- **Git**
+
+### Getting Started
+
+1. **Clone your fork**
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/SpotiFLAC-Mobile.git
+   cd SpotiFLAC-Mobile
+   ```
+
+2. **Add upstream remote**
+   ```bash
+   git remote add upstream https://github.com/zarzet/SpotiFLAC-Mobile.git
+   ```
+
+3. **Use FVM (Flutter Version: 3.41.5)**
+   ```bash
+   fvm use
+   ```
+
+4. **Install dependencies**
+   ```bash
+   flutter pub get
+   ```
+
+5. **Generate code** (for Riverpod, JSON serialization, etc.)
+   ```bash
+   dart run build_runner build --delete-conflicting-outputs
+   ```
+
+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
+   ```
+
+### Building
+
+```bash
+# Debug build
+flutter build apk --debug
+
+# Release build
+flutter build apk --release
+```
+
+## Project Structure
+
+```
+lib/
+├── l10n/               # Localization files
+│   └── arb/            # ARB translation files
+├── models/             # Data models
+├── providers/          # Riverpod providers
+├── screens/            # UI screens
+│   └── settings/       # Settings sub-screens
+├── services/           # Business logic services
+├── theme/              # App theming
+├── utils/              # Utility functions
+├── widgets/            # Reusable widgets
+├── app.dart            # App configuration
+└── main.dart           # Entry point
+```
+
+## Coding Guidelines
+
+### General
+
+- Follow [Effective Dart](https://dart.dev/effective-dart) guidelines
+- Use meaningful variable and function names
+- Keep functions small and focused
+- Add comments for complex logic
+
+### Formatting
+
+- Use `dart format` before committing
+- Maximum line length: 80 characters
+- Use trailing commas for better formatting
+
+```bash
+dart format .
+```
+
+### Linting
+
+Ensure your code passes all lints:
+
+```bash
+flutter analyze
+```
+
+### State Management
+
+We use **Riverpod** for state management. Follow these patterns:
+
+```dart
+// Use code generation with riverpod_annotation
+@riverpod
+class MyNotifier extends _$MyNotifier {
+  @override
+  MyState build() => MyState();
+  
+  // Methods to update state
+}
+```
+
+### Localization
+
+All user-facing strings should be localized:
+
+```dart
+// Good
+Text(AppLocalizations.of(context)!.downloadComplete)
+
+// Bad
+Text('Download Complete')
+```
+
+To add new strings:
+1. Add the key to `lib/l10n/arb/app_en.arb`
+2. Run `flutter gen-l10n`
+
+## Commit Guidelines
+
+We follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+### Types
+
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation changes
+- `style`: Code style changes (formatting, etc.)
+- `refactor`: Code refactoring
+- `perf`: Performance improvements
+- `test`: Adding or updating tests
+- `chore`: Maintenance tasks
+
+### Examples
+
+```
+feat(download): add batch download support
+fix(ui): resolve overflow on small screens
+docs: update contributing guidelines
+chore(deps): update flutter_riverpod to 3.1.0
+```
+
+## Pull Request Process
+
+1. **Update your fork**
+   ```bash
+   git fetch upstream
+   git rebase upstream/dev
+   ```
+
+2. **Create a feature branch**
+   ```bash
+   git checkout -b feat/my-new-feature
+   ```
+
+3. **Make your changes** and commit following our guidelines
+
+4. **Push to your fork**
+   ```bash
+   git push origin feat/my-new-feature
+   ```
+
+5. **Create a Pull Request**
+   - Target the `dev` branch
+   - Fill in the PR template
+   - Link related issues
+
+6. **Address review feedback**
+   - Make requested changes
+   - Push additional commits
+   - Request re-review when ready
+
+### PR Requirements
+
+- [ ] Code follows project conventions
+- [ ] All tests pass
+- [ ] No new linting errors
+- [ ] Documentation updated (if needed)
+- [ ] Commit messages follow guidelines
+- [ ] PR description is clear and complete
+
+## Questions?
+
+If you have questions, feel free to:
+
+- Open a [Discussion](https://github.com/zarzet/SpotiFLAC-Mobile/discussions)
+- Check existing [Issues](https://github.com/zarzet/SpotiFLAC-Mobile/issues)
+
+Thank you for contributing! 💚
@@ -1,72 +1,183 @@
-[![GitHub All Releases](https://img.shields.io/github/downloads/zarzet/SpotiFLAC-Mobile/total?style=for-the-badge)](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/9092dd9300289ceadd8e70cd71706a3ba32225d9cb2ae8b12648611d31814708)
-
 <div align="center">

-<img src="icon.png" width="128" />
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="assets/readme/banner-readme-dark.png">
+  <source media="(prefers-color-scheme: light)" srcset="assets/readme/banner-readme-light.png">
+  <img alt="SpotiFLAC Mobile" src="assets/readme/banner-readme-light.png" width="650" height="auto">
+</picture>

-Get Spotify tracks in true 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/25971" target="_blank">
+    <img src="https://trendshift.io/api/badge/repositories/25971" alt="spotiflacapp%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

 <p align="center">
-  <img src="assets/images/1.jpg?v=2" width="200" />
-  <img src="assets/images/2.jpg?v=2" width="200" />
-  <img src="assets/images/3.jpg?v=2" width="200" />
-  <img src="assets/images/4.jpg?v=2" width="200" />
+  <img src="assets/readme/1.jpg?v=2" width="200" />
+  <img src="assets/readme/2.jpg?v=2" width="200" />
+  <img src="assets/readme/3.jpg?v=2" width="200" />
+  <img src="assets/readme/4.jpg?v=2" width="200" />
 </p>

-## Metadata Source
+---

-SpotiFLAC supports two metadata sources for searching tracks:
+## Extensions

-| Source | Pros | Cons |
-|--------|------|------|
-| **Deezer** (Default) | No developer account needed, rate limit per user IP | Slightly less comprehensive catalog |
-| **Spotify** | More comprehensive catalog, better search results | Requires developer API credentials to avoid rate limiting |
+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.

-### Using Deezer (Recommended)
-Works out of the box. No setup required.
+### Installing Extensions

-### Using Spotify
-To use Spotify as your search source without hitting rate limits:
-1. Create a Spotify Developer account at [developer.spotify.com](https://developer.spotify.com)
-2. Create an app to get your Client ID and Client Secret
-3. Go to **Settings > Options > Spotify API > Custom Credentials**
-4. Enter your Client ID and Secret
-5. Change **Search Source** to Spotify
+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**

-> **Note**: Spotify URLs (track, album) are always supported regardless of your search source setting. The app will automatically fall back to Deezer if Spotify API is rate limited.
+### Developing Extensions

-## Support
+> [!NOTE]
+> Want to build your own extension? The [Extension Development Guide](https://zarzet.github.io/SpotiFLAC-Mobile/docs) has everything you need.

-If you find this app useful, consider supporting the development:
+---

-[![Ko-fi](https://img.shields.io/badge/Ko--fi-Support%20Me-FF5E5B?style=for-the-badge&logo=ko-fi&logoColor=white)](https://ko-fi.com/zarzet)
-
-## Other project
+## Related Projects

 ### [SpotiFLAC (Desktop)](https://github.com/afkarxyz/SpotiFLAC)
-Get Spotify tracks in true FLAC from Tidal, Qobuz & Amazon Music for Windows, macOS & Linux
+Download music in true lossless FLAC from extension-provided sources on Windows, macOS & Linux.
+
+### [SpotiFLAC (Python Module)](https://github.com/ShuShuzinhuu/SpotiFLAC-Module-Version)
+Python library for SpotiFLAC integration, maintained by [@ShuShuzinhuu](https://github.com/ShuShuzinhuu).
+
+---
+
+## FAQ
+
+<details>
+<summary><b>Why does the Store tab ask me to enter a URL?</b></summary>
+<br>
+
+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.
+
+</details>
+
+<details>
+<summary><b>Why is my download failing with "Song not found"?</b></summary>
+<br>
+
+The track may not be available from your enabled providers. Try enabling more providers under **Settings > Extensions > Provider Priority**, or install additional download extensions from the Store.
+
+</details>
+
+<details>
+<summary><b>Why are some tracks downloading in lower quality?</b></summary>
+<br>
+
+Quality depends on what's available from the source and the installed download extension. Check each extension's quality options and service notes in the app.
+
+</details>
+
+<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
+
+| | | | | |
+|---|---|---|---|---|
+| [MusicDL](https://www.musicdl.me) | [LRCLib](https://lrclib.net) | [Paxsenix](https://lyrics.paxsenix.org) | [Cobalt](https://cobalt.tools) | [Song.link](https://song.link) |
+| [IDHS](https://github.com/sjdonado/idonthavespotify) |  |  |  |  |
+
+---

 ## Disclaimer

-> **iOS Support**: This app is primarily tested on Android. iOS support is experimental and may have bugs — the developer is too poor to afford an iPhone for proper testing. If you encounter issues on iOS, please report them!
+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).

-This project is for **educational and private use only**. The developer does not condone or encourage copyright infringement.
+- 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.

-**SpotiFLAC** is a third-party tool and is not affiliated with, endorsed by, or connected to Spotify, Tidal, Qobuz, Amazon Music, or any other streaming service.
-
-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.
+> [!TIP]
+> **Star the repo** to get notified about all new releases directly from GitHub.
@@ -9,6 +9,19 @@
 # packages, and plugins designed to encourage good coding practices.
 include: package:flutter_lints/flutter.yaml

+plugins:
+  riverpod_lint: 3.1.4-dev.3
+
+analyzer:
+  exclude:
+    - build/**
+    - .dart_tool/**
+    - lib/**/*.g.dart
+    - lib/l10n/*.dart
+  language:
+    strict-casts: true
+    strict-inference: true
+    strict-raw-types: true
 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
+    always_declare_return_types: true
+    avoid_dynamic_calls: true
+    avoid_types_as_parameter_names: true
+    strict_top_level_inference: true
+    type_annotate_public_apis: true
+    cancel_subscriptions: true
+    close_sinks: true

 # Additional information about this file can be found at
 # https://dart.dev/guides/language/analysis-options
@@ -1,71 +0,0 @@
-plugins {
-    id "com.android.application"
-    id "kotlin-android"
-    id "dev.flutter.flutter-gradle-plugin"
-}
-
-def localProperties = new Properties()
-def localPropertiesFile = rootProject.file('local.properties')
-if (localPropertiesFile.exists()) {
-    localPropertiesFile.withReader('UTF-8') { reader ->
-        localProperties.load(reader)
-    }
-}
-
-def flutterVersionCode = localProperties.getProperty('flutter.versionCode')
-if (flutterVersionCode == null) {
-    flutterVersionCode = '1'
-}
-
-def flutterVersionName = localProperties.getProperty('flutter.versionName')
-if (flutterVersionName == null) {
-    flutterVersionName = '1.0'
-}
-
-android {
-    namespace "com.zarz.spotiflac"
-    compileSdk flutter.compileSdkVersion
-    ndkVersion flutter.ndkVersion
-
-    compileOptions {
-        sourceCompatibility JavaVersion.VERSION_1_8
-        targetCompatibility JavaVersion.VERSION_1_8
-    }
-
-    kotlinOptions {
-        jvmTarget = '1.8'
-    }
-
-    sourceSets {
-        main.java.srcDirs += 'src/main/kotlin'
-    }
-
-    defaultConfig {
-        applicationId "com.zarz.spotiflac"
-        minSdkVersion flutter.minSdkVersion
-        targetSdk flutter.targetSdkVersion
-        versionCode flutterVersionCode.toInteger()
-        versionName flutterVersionName
-    }
-
-    buildTypes {
-        release {
-            signingConfig signingConfigs.debug
-            minifyEnabled false
-            shrinkResources false
-        }
-    }
-}
-
-flutter {
-    source '../..'
-}
-
-dependencies {
-    // Go backend library (gomobile generated)
-    implementation fileTree(dir: 'libs', include: ['*.aar'])
-    
-    // Kotlin coroutines for async Go backend calls
-    implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3'
-    implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3'
-}
@@ -1,3 +1,6 @@
+import java.util.Properties
+import java.io.FileInputStream
+
 plugins {
    id("com.android.application")
    id("kotlin-android")
@@ -7,35 +10,39 @@ plugins {

 // Load keystore properties for local builds
 val keystorePropertiesFile = rootProject.file("key.properties")
-val keystoreProperties = java.util.Properties()
+val keystoreProperties = Properties()
 if (keystorePropertiesFile.exists()) {
-    keystoreProperties.load(java.io.FileInputStream(keystorePropertiesFile))
+    keystoreProperties.load(FileInputStream(keystorePropertiesFile))
 }

 android {
    namespace = "com.zarz.spotiflac"
-    compileSdk = flutter.compileSdkVersion
+    compileSdk = 37
    ndkVersion = flutter.ndkVersion

+    buildFeatures {
+        buildConfig = true
+    }
+
    compileOptions {
        isCoreLibraryDesugaringEnabled = true
-        sourceCompatibility = JavaVersion.VERSION_17
-        targetCompatibility = JavaVersion.VERSION_17
+        sourceCompatibility = JavaVersion.VERSION_25
+        targetCompatibility = JavaVersion.VERSION_25
    }

    kotlin {
        compilerOptions {
-            jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17)
+            jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_25)
        }
    }

    signingConfigs {
        if (keystorePropertiesFile.exists()) {
            create("release") {
-                keyAlias = keystoreProperties["keyAlias"] as String
-                keyPassword = keystoreProperties["keyPassword"] as String
-                storeFile = file(keystoreProperties["storeFile"] as String)
-                storePassword = keystoreProperties["storePassword"] as String
+                keyAlias = keystoreProperties.getProperty("keyAlias")
+                keyPassword = keystoreProperties.getProperty("keyPassword")
+                storeFile = file(keystoreProperties.getProperty("storeFile"))
+                storePassword = keystoreProperties.getProperty("storePassword")
            }
        }
    }
@@ -43,7 +50,7 @@ android {
    defaultConfig {
        applicationId = "com.zarz.spotiflac"
        minSdk = flutter.minSdkVersion
-        targetSdk = 34
+        targetSdk = 37
        versionCode = flutter.versionCode
        versionName = flutter.versionName
        multiDexEnabled = true
@@ -54,6 +61,20 @@ android {
    }

    buildTypes {
+        getByName("debug") {
+            applicationIdSuffix = ".debug"
+            versionNameSuffix = "-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
@@ -68,6 +89,9 @@ android {
                getDefaultProguardFile("proguard-android-optimize.txt"),
                "proguard-rules.pro"
            )
+            ndk {
+                debugSymbolLevel = "FULL"
+            }
        }
    }
    
@@ -93,9 +117,14 @@ repositories {
 }

 dependencies {
-    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.4")
-    implementation(files("libs/gobackend.aar"))
-    implementation(files("libs/ffmpeg-kit-with-lame.aar"))
-    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3")
-    implementation("androidx.lifecycle:lifecycle-runtime-ktx:2.7.0")
+    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.11.0")
+    implementation("androidx.lifecycle:lifecycle-runtime-ktx:2.11.0-beta02")
+    implementation("androidx.documentfile:documentfile:1.1.0")
+    implementation("androidx.activity:activity-ktx:1.13.0")
+    implementation("com.antonkarpenko:ffmpeg-kit-full:2.1.0")
 }
@@ -5,29 +5,112 @@
 -keep class io.flutter.view.** { *; }
 -keep class io.flutter.** { *; }
 -keep class io.flutter.plugins.** { *; }
+-keep class io.flutter.embedding.** { *; }

-# Go backend (gobackend.aar)
+# Ignore missing Play Core classes (not used, but referenced by Flutter)
+-dontwarn com.google.android.play.core.splitcompat.**
+-dontwarn com.google.android.play.core.splitinstall.**
+-dontwarn com.google.android.play.core.tasks.**
+
+# Ignore missing javax.xml.stream (not used on Android)
+-dontwarn javax.xml.stream.**
+
+# Go backend (gobackend.aar) - CRITICAL for release builds
 -keep class gobackend.** { *; }
 -keep class go.** { *; }
+-keep interface gobackend.** { *; }
+-keepclassmembers class gobackend.** { *; }
+
+# Go mobile binding internals
+-keep class org.golang.** { *; }
+-dontwarn org.golang.**

 # FFmpeg Kit
 -keep class com.arthenica.ffmpegkit.** { *; }
 -keep class com.arthenica.smartexception.** { *; }
+# FFmpeg Kit (new fork package)
+-keep class com.antonkarpenko.ffmpegkit.** { *; }
+-keep class com.antonkarpenko.smartexception.** { *; }
+
+# Apache Tika (if used by FFmpeg)
+-dontwarn org.apache.tika.**

 # Keep native methods
 -keepclasseswithmembernames class * {
    native <methods>;
 }

-# Kotlin coroutines
+# Kotlin coroutines - expanded rules
 -keepnames class kotlinx.coroutines.internal.MainDispatcherFactory {}
 -keepnames class kotlinx.coroutines.CoroutineExceptionHandler {}
 -keepclassmembers class kotlinx.coroutines.** {
    volatile <fields>;
 }
+-keepclassmembernames class kotlinx.** {
+    volatile <fields>;
+}
+-dontwarn kotlinx.coroutines.**
+
+# Kotlin serialization
+-keepattributes RuntimeVisibleAnnotations,AnnotationDefault
+-dontwarn kotlin.**
+-keep class kotlin.** { *; }
+-keep class kotlin.Metadata { *; }
+
+# Keep MainActivity and related classes
+-keep class com.zarz.spotiflac.** { *; }

 # Prevent R8 from removing metadata
 -keepattributes *Annotation*
 -keepattributes SourceFile,LineNumberTable
 -keepattributes Signature
 -keepattributes Exceptions
+-keepattributes InnerClasses
+-keepattributes EnclosingMethod
+
+# JSON parsing (used by Go backend responses)
+-keep class org.json.** { *; }
+
+# Shared Preferences
+-keep class androidx.datastore.** { *; }
+-dontwarn androidx.datastore.**
+
+# Flutter Plugins - CRITICAL: Prevent R8 from removing plugin implementations
+# Path Provider
+-keep class io.flutter.plugins.pathprovider.** { *; }
+-keep class dev.flutter.pigeon.** { *; }
+
+# Local Notifications
+-keep class com.dexterous.** { *; }
+-keep class com.dexterous.flutterlocalnotifications.** { *; }
+
+# Receive Sharing Intent
+-keep class com.kasem.receive_sharing_intent.** { *; }
+
+# Permission Handler
+-keep class com.baseflow.permissionhandler.** { *; }
+
+# File Picker
+-keep class com.mr.flutter.plugin.filepicker.** { *; }
+
+# URL Launcher
+-keep class io.flutter.plugins.urllauncher.** { *; }
+
+# Share Plus
+-keep class dev.fluttercommunity.plus.share.** { *; }
+
+# Device Info Plus
+-keep class dev.fluttercommunity.plus.device_info.** { *; }
+
+# Open File
+-keep class com.crazecoder.openfile.** { *; }
+
+# Sqflite
+-keep class com.tekartik.sqflite.** { *; }
+
+# Dynamic Color
+-keep class io.material.** { *; }
+
+# Keep all Flutter plugin registrants
+-keep class io.flutter.plugins.GeneratedPluginRegistrant { *; }
+-keep class ** extends io.flutter.embedding.engine.plugins.FlutterPlugin { *; }
@@ -12,17 +12,19 @@
    <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" />

    <application
-        android:label="SpotiFLAC"
+        android:label="SpotiFLAC Mobile"
        android:name="${applicationName}"
        android:icon="@mipmap/ic_launcher"
-        android:requestLegacyExternalStorage="true"
-        android:usesCleartextTraffic="true"
-        android:enableOnBackInvokedCallback="true">
+        android:usesCleartextTraffic="false"
+        android:networkSecurityConfig="@xml/network_security_config"
+        android:enableOnBackInvokedCallback="true"
+        android:localeConfig="@xml/locale_config">

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

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

        <!-- Download Service -->
@@ -65,6 +114,23 @@
            android:exported="false"
            android:foregroundServiceType="dataSync" />

+        <service
+            android:name="com.ryanheise.audioservice.AudioService"
+            android:foregroundServiceType="mediaPlayback"
+            android:exported="true"
+            android:enabled="true">
+            <intent-filter>
+                <action android:name="android.media.browse.MediaBrowserService" />
+            </intent-filter>
+        </service>
+        <receiver
+            android:name="com.ryanheise.audioservice.MediaButtonReceiver"
+            android:exported="true">
+            <intent-filter>
+                <action android:name="android.intent.action.MEDIA_BUTTON" />
+            </intent-filter>
+        </receiver>
+
        <!-- flutter_local_notifications receivers -->
        <receiver android:exported="false" android:name="com.dexterous.flutterlocalnotifications.ScheduledNotificationReceiver" />
        <receiver android:exported="false" android:name="com.dexterous.flutterlocalnotifications.ScheduledNotificationBootReceiver">
@@ -81,6 +147,10 @@
            android:name="flutterEmbedding"
            android:value="2" />

+        <meta-data
+            android:name="com.google.android.gms.car.application"
+            android:resource="@xml/automotive_app_desc" />
+
        <!-- FileProvider for APK installation -->
        <provider
            android:name="androidx.core.content.FileProvider"
@@ -1,5 +0,0 @@
-package com.example.temp_project
-
-import io.flutter.embedding.android.FlutterActivity
-
-class MainActivity : FlutterActivity()
@@ -0,0 +1,496 @@
+package com.zarz.spotiflac
+
+import android.content.Context
+import android.net.Uri
+import android.util.Log
+import androidx.documentfile.provider.DocumentFile
+import org.json.JSONObject
+import java.io.File
+import java.util.Locale
+
+/**
+ * Shared SAF download wrapper for foreground activity calls and service-owned
+ * native workers.
+ */
+object SafDownloadHandler {
+    private val safDirLock = Any()
+    private const val MAX_SAF_DISPLAY_NAME_UTF8_BYTES = 180
+    private const val STAGED_SAF_MIME_TYPE = "application/octet-stream"
+
+    fun handle(context: Context, requestJson: String, downloader: (String) -> String): String {
+        val req = JSONObject(requestJson)
+        val storageMode = req.optString("storage_mode", "")
+        val treeUriStr = req.optString("saf_tree_uri", "")
+        if (storageMode != "saf" || treeUriStr.isBlank()) {
+            return downloader(requestJson)
+        }
+
+        val treeUri = Uri.parse(treeUriStr)
+        val relativeDir = sanitizeRelativeDir(req.optString("saf_relative_dir", ""))
+        val outputExt = normalizeExt(req.optString("saf_output_ext", ""))
+        val mimeType = mimeTypeForExt(outputExt)
+        val fileName = buildSafFileName(req, outputExt)
+        val deferSafPublish = req.optBoolean("defer_saf_publish", false)
+        val useStagedOutput = req.optBoolean("stage_saf_output", false) && !deferSafPublish
+        val stagedFileName = if (useStagedOutput) buildStagedSafFileName(fileName) else fileName
+        val stagedMimeType = if (useStagedOutput) STAGED_SAF_MIME_TYPE else mimeType
+
+        val existingDir = findDocumentDir(context, treeUri, relativeDir)
+        if (existingDir != null) {
+            val existing = existingDir.findFile(fileName)
+            if (existing != null && existing.isFile && existing.length() > 0) {
+                if (useStagedOutput || deferSafPublish) {
+                    deleteStaleStagedFiles(existingDir, fileName, outputExt)
+                }
+                val obj = JSONObject()
+                obj.put("success", true)
+                obj.put("message", "File already exists")
+                obj.put("file_path", existing.uri.toString())
+                obj.put("file_name", existing.name ?: fileName)
+                obj.put("already_exists", true)
+                return obj.toString()
+            }
+        }
+
+        val targetDir = ensureDocumentDir(context, treeUri, relativeDir)
+            ?: return errorJson("Failed to access SAF directory")
+
+        if (deferSafPublish) {
+            deleteStaleStagedFiles(targetDir, fileName, outputExt)
+            val workingExt = outputExt.ifBlank { ".tmp" }
+            val workingFile = File.createTempFile("native_saf_work_", workingExt, context.cacheDir)
+            Log.i("SpotiFLAC", "SAF deferred native output: target=$fileName working=${workingFile.name}")
+            return try {
+                req.put("output_path", workingFile.absolutePath)
+                req.put("output_ext", outputExt)
+                req.remove("output_fd")
+                val response = downloader(req.toString())
+                val respObj = JSONObject(response)
+                if (respObj.optBoolean("success", false)) {
+                    val reportedPath = respObj.optString("file_path", "").trim()
+                    if (reportedPath.isEmpty() || reportedPath.startsWith("/proc/self/fd/")) {
+                        respObj.put("file_path", workingFile.absolutePath)
+                    } else if (reportedPath != workingFile.absolutePath) {
+                        workingFile.delete()
+                    }
+                    respObj.put("file_name", respObj.optString("file_name", "").ifBlank { fileName })
+                    respObj.put("saf_deferred_publish", true)
+                    respObj.put("saf_final_file_name", fileName)
+                    respObj.put("saf_relative_dir", relativeDir)
+                    respObj.put("saf_tree_uri", treeUriStr)
+                    respObj.put("saf_output_ext", outputExt)
+                    respObj.put("saf_final_mime_type", mimeType)
+                } else {
+                    workingFile.delete()
+                }
+                respObj.toString()
+            } catch (e: Exception) {
+                workingFile.delete()
+                errorJson("SAF deferred download failed: ${e.message}")
+            }
+        }
+
+        var document = createOrReuseDocumentFile(targetDir, stagedMimeType, stagedFileName)
+            ?: return errorJson("Failed to create SAF file")
+
+        val pfd = context.contentResolver.openFileDescriptor(document.uri, "rw")
+            ?: return errorJson("Failed to open SAF file")
+
+        var detachedFd: Int? = null
+        try {
+            detachedFd = pfd.detachFd()
+            req.put("output_path", "")
+            req.put("output_fd", detachedFd)
+            req.put("output_ext", outputExt)
+            val response = downloader(req.toString())
+            val respObj = JSONObject(response)
+            if (respObj.optBoolean("success", false)) {
+                val goFilePath = respObj.optString("file_path", "")
+                if (goFilePath.isNotEmpty() &&
+                    !goFilePath.startsWith("content://") &&
+                    !goFilePath.startsWith("/proc/self/fd/")
+                ) {
+                    try {
+                        val srcFile = File(goFilePath)
+                        if (!srcFile.exists() || srcFile.length() <= 0) {
+                            throw IllegalStateException("extension output missing or empty: $goFilePath")
+                        }
+                        val actualExt = normalizeExt(srcFile.extension)
+                        if (actualExt.isNotBlank()) {
+                            respObj.put("actual_extension", actualExt)
+                        }
+                        if (actualExt.isNotBlank() && actualExt != outputExt) {
+                            val actualFileName = buildSafFileName(req, actualExt)
+                            val actualStagedFileName = if (useStagedOutput) {
+                                buildStagedSafFileName(actualFileName)
+                            } else {
+                                actualFileName
+                            }
+                            val actualMimeType = mimeTypeForExt(actualExt)
+                            val replacement = createOrReuseDocumentFile(
+                                targetDir,
+                                if (useStagedOutput) STAGED_SAF_MIME_TYPE else actualMimeType,
+                                actualStagedFileName
+                            ) ?: throw IllegalStateException(
+                                "failed to create SAF output with actual extension"
+                            )
+                            if (replacement.uri != document.uri) {
+                                document.delete()
+                                document = replacement
+                            }
+                        }
+                        context.contentResolver.openOutputStream(document.uri, "wt")?.use { output ->
+                            srcFile.inputStream().use { input ->
+                                input.copyTo(output)
+                            }
+                        } ?: throw IllegalStateException("failed to open SAF output stream")
+                        srcFile.delete()
+                    } catch (e: Exception) {
+                        document.delete()
+                        android.util.Log.w(
+                            "SpotiFLAC",
+                            "Failed to copy extension output to SAF: ${e.message}"
+                        )
+                        return errorJson("Failed to copy extension output to SAF: ${e.message}")
+                    }
+                }
+                respObj.put("file_path", document.uri.toString())
+                respObj.put("file_name", document.name ?: fileName)
+                if (useStagedOutput) {
+                    respObj.put("saf_staged_output", true)
+                    respObj.put("saf_staged_file_name", document.name ?: stagedFileName)
+                }
+            } else {
+                document.delete()
+            }
+            return respObj.toString()
+        } catch (e: Exception) {
+            document.delete()
+            return errorJson("SAF download failed: ${e.message}")
+        } finally {
+            if (detachedFd == null) {
+                try {
+                    pfd.close()
+                } catch (_: Exception) {
+                }
+            }
+        }
+    }
+
+    fun copyContentUriToTemp(context: Context, uriStr: String): String? {
+        return try {
+            val uri = Uri.parse(uriStr)
+            val extension = DocumentFile.fromSingleUri(context, uri)
+                ?.name
+                ?.substringAfterLast('.', "")
+                ?.takeIf { it.isNotBlank() }
+                ?.let { ".$it" }
+                ?: ".tmp"
+            val temp = File.createTempFile("native_saf_", extension, context.cacheDir)
+            context.contentResolver.openInputStream(uri)?.use { input ->
+                temp.outputStream().use { output ->
+                    input.copyTo(output)
+                }
+            } ?: return null
+            temp.absolutePath
+        } catch (e: Exception) {
+            android.util.Log.w("SpotiFLAC", "Failed to copy SAF URI to temp: ${e.message}")
+            null
+        }
+    }
+
+    fun writeFileToSaf(
+        context: Context,
+        treeUriStr: String,
+        relativeDir: String,
+        fileName: String,
+        mimeType: String,
+        srcPath: String
+    ): String? {
+        var stagedDocument: DocumentFile? = null
+        return try {
+            val treeUri = Uri.parse(treeUriStr)
+            val targetDir = ensureDocumentDir(context, treeUri, relativeDir) ?: return null
+            val finalName = sanitizeFilename(fileName)
+            val ext = normalizeExt(finalName.substringAfterLast('.', ""))
+            val stagedName = buildStagedSafFileName(finalName)
+            deleteStaleStagedFiles(targetDir, finalName, ext)
+            val document = createOrReuseDocumentFile(targetDir, STAGED_SAF_MIME_TYPE, stagedName)
+                ?: return null
+            stagedDocument = document
+            val outputStream = context.contentResolver.openOutputStream(document.uri, "wt")
+            if (outputStream == null) {
+                document.delete()
+                stagedDocument = null
+                return null
+            }
+            outputStream.use { output ->
+                File(srcPath).inputStream().use { input ->
+                    input.copyTo(output)
+                }
+            }
+
+            val existingFinal = targetDir.findFile(finalName)
+            if (existingFinal != null && existingFinal.uri != document.uri) {
+                existingFinal.delete()
+            }
+            if (!document.renameTo(finalName)) {
+                document.delete()
+                return null
+            }
+            stagedDocument = null
+            targetDir.findFile(finalName)?.uri?.toString() ?: document.uri.toString()
+        } catch (e: Exception) {
+            stagedDocument?.delete()
+            android.util.Log.w("SpotiFLAC", "Failed to write file to SAF: ${e.message}")
+            null
+        }
+    }
+
+    fun deleteContentUri(context: Context, uriStr: String): Boolean {
+        return try {
+            DocumentFile.fromSingleUri(context, Uri.parse(uriStr))?.delete() == true
+        } catch (_: Exception) {
+            false
+        }
+    }
+
+    private fun normalizeExt(ext: String?): String {
+        if (ext.isNullOrBlank()) return ""
+        return if (ext.startsWith(".")) {
+            ext.lowercase(Locale.ROOT)
+        } else {
+            ".${ext.lowercase(Locale.ROOT)}"
+        }
+    }
+
+    private fun mimeTypeForExt(ext: String?): String {
+        return when (normalizeExt(ext)) {
+            ".m4a", ".mp4" -> "audio/mp4"
+            ".mp3" -> "audio/mpeg"
+            ".opus" -> "audio/ogg"
+            ".flac" -> "audio/flac"
+            ".lrc" -> "application/octet-stream"
+            else -> "application/octet-stream"
+        }
+    }
+
+    private fun forceFilenameExt(name: String, outputExt: String): String {
+        val normalizedExt = normalizeExt(outputExt)
+        if (normalizedExt.isBlank()) return sanitizeFilename(name)
+
+        val safeName = sanitizeFilename(name)
+        val lower = safeName.lowercase(Locale.ROOT)
+        val knownExts = listOf(".flac", ".m4a", ".mp4", ".mp3", ".opus", ".lrc")
+        for (knownExt in knownExts) {
+            if (lower.endsWith(knownExt)) {
+                return safeName.dropLast(knownExt.length) + normalizedExt
+            }
+        }
+        return safeName + normalizedExt
+    }
+
+    private fun buildStagedSafFileName(fileName: String): String {
+        val safeName = sanitizeFilename(fileName)
+        return "$safeName.partial"
+    }
+
+    private fun buildLegacyStagedSafFileName(fileName: String, outputExt: String): String {
+        val safeName = sanitizeFilename(fileName)
+        val ext = normalizeExt(outputExt)
+        if (ext.isNotBlank() && safeName.lowercase(Locale.ROOT).endsWith(ext)) {
+            return safeName.dropLast(ext.length).trimEnd('.', ' ') + ".partial$ext"
+        }
+        val dot = safeName.lastIndexOf('.')
+        if (dot > 0 && dot < safeName.lastIndex) {
+            return safeName.substring(0, dot).trimEnd('.', ' ') +
+                ".partial" +
+                safeName.substring(dot)
+        }
+        return "$safeName.partial"
+    }
+
+    private fun deleteStaleStagedFiles(parent: DocumentFile, fileName: String, outputExt: String) {
+        val stagedNames = linkedSetOf(
+            buildStagedSafFileName(fileName),
+            buildLegacyStagedSafFileName(fileName, outputExt)
+        )
+        for (stagedName in stagedNames) {
+            try {
+                parent.findFile(stagedName)?.delete()
+            } catch (_: Exception) {
+            }
+        }
+    }
+
+    private fun sanitizeFilename(name: String): String {
+        var sanitized = name
+            .replace("/", " ")
+            .replace(Regex("[\\\\:*?\"<>|]"), " ")
+            .filter { ch ->
+                val code = ch.code
+                !((code < 0x20 && ch != '\t' && ch != '\n' && ch != '\r') ||
+                    code == 0x7F ||
+                    (Character.isISOControl(ch) && ch != '\t' && ch != '\n' && ch != '\r'))
+            }
+            .trim()
+            .trim('.', ' ')
+
+        sanitized = sanitized
+            .replace(Regex("\\s+"), " ")
+            .replace(Regex("_+"), "_")
+            .trim('_', ' ')
+
+        sanitized = truncateSafDisplayName(sanitized, MAX_SAF_DISPLAY_NAME_UTF8_BYTES)
+        sanitized = sanitized.trim().trim('.', ' ').trim('_', ' ')
+        return if (sanitized.isBlank()) "Unknown" else sanitized
+    }
+
+    private fun truncateSafDisplayName(name: String, maxBytes: Int): String {
+        if (maxBytes <= 0 || name.toByteArray(Charsets.UTF_8).size <= maxBytes) return name
+
+        val dotIndex = name.lastIndexOf('.')
+        val ext = if (
+            dotIndex > 0 &&
+            dotIndex < name.length - 1 &&
+            name.length - dotIndex <= 10
+        ) {
+            name.substring(dotIndex)
+        } else {
+            ""
+        }
+        val stem = if (ext.isNotEmpty()) name.substring(0, dotIndex) else name
+        val maxStemBytes = (maxBytes - ext.toByteArray(Charsets.UTF_8).size).coerceAtLeast(1)
+        return truncateUtf8Bytes(stem, maxStemBytes).trim().trim('.', ' ').trim('_', ' ') + ext
+    }
+
+    private fun truncateUtf8Bytes(value: String, maxBytes: Int): String {
+        if (maxBytes <= 0 || value.toByteArray(Charsets.UTF_8).size <= maxBytes) return value
+
+        val builder = StringBuilder()
+        var usedBytes = 0
+        var index = 0
+        while (index < value.length) {
+            val codePoint = value.codePointAt(index)
+            val char = String(Character.toChars(codePoint))
+            val charBytes = char.toByteArray(Charsets.UTF_8).size
+            if (usedBytes + charBytes > maxBytes) break
+            builder.append(char)
+            usedBytes += charBytes
+            index += Character.charCount(codePoint)
+        }
+        return builder.toString()
+    }
+
+    private fun sanitizeRelativeDir(relativeDir: String): String {
+        if (relativeDir.isBlank()) return ""
+        return relativeDir
+            .split("/")
+            .map { sanitizeFilename(it) }
+            .filter { it.isNotBlank() && it != "." && it != ".." }
+            .joinToString("/")
+    }
+
+    private fun ensureDocumentDir(
+        context: Context,
+        treeUri: Uri,
+        relativeDir: String
+    ): DocumentFile? {
+        val safeRelativeDir = sanitizeRelativeDir(relativeDir)
+        if (safeRelativeDir.isBlank()) {
+            return DocumentFile.fromTreeUri(context, treeUri)
+        }
+
+        synchronized(safDirLock) {
+            var current = DocumentFile.fromTreeUri(context, treeUri) ?: return null
+            val parts = safeRelativeDir.split("/").filter { it.isNotBlank() }
+            for (part in parts) {
+                val existing = current.findFile(part)
+                current = if (existing != null && existing.isDirectory) {
+                    existing
+                } else {
+                    val created = current.createDirectory(part) ?: return null
+                    val createdName = created.name ?: part
+                    if (createdName != part) {
+                        created.delete()
+                        current.findFile(part) ?: return null
+                    } else {
+                        created
+                    }
+                }
+            }
+            return current
+        }
+    }
+
+    private fun findDocumentDir(
+        context: Context,
+        treeUri: Uri,
+        relativeDir: String
+    ): DocumentFile? {
+        var current = DocumentFile.fromTreeUri(context, treeUri) ?: return null
+        val safeRelativeDir = sanitizeRelativeDir(relativeDir)
+        if (safeRelativeDir.isBlank()) return current
+
+        val parts = safeRelativeDir.split("/").filter { it.isNotBlank() }
+        for (part in parts) {
+            val existing = current.findFile(part)
+            if (existing == null || !existing.isDirectory) return null
+            current = existing
+        }
+        return current
+    }
+
+    private fun createOrReuseDocumentFile(
+        parent: DocumentFile,
+        mimeType: String,
+        fileName: String
+    ): DocumentFile? {
+        val safeFileName = sanitizeFilename(fileName)
+        if (safeFileName.isBlank()) return null
+
+        synchronized(safDirLock) {
+            val existing = parent.findFile(safeFileName)
+            if (existing != null && existing.isFile) {
+                return existing
+            }
+
+            val created = parent.createFile(mimeType, safeFileName) ?: return null
+            val createdName = created.name ?: safeFileName
+            if (createdName == safeFileName) {
+                return created
+            }
+
+            val winner = parent.findFile(safeFileName)
+            if (winner != null && winner.isFile) {
+                if (winner.uri != created.uri) {
+                    try {
+                        created.delete()
+                    } catch (_: Exception) {
+                    }
+                }
+                return winner
+            }
+
+            return created
+        }
+    }
+
+    private fun buildSafFileName(req: JSONObject, outputExt: String): String {
+        val provided = req.optString("saf_file_name", "")
+        if (provided.isNotBlank()) return forceFilenameExt(provided, outputExt)
+
+        val trackName = req.optString("track_name", "track")
+        val artistName = req.optString("artist_name", "")
+        val baseName = if (artistName.isNotBlank()) "$artistName - $trackName" else trackName
+        return forceFilenameExt(baseName, outputExt)
+    }
+
+    private fun errorJson(message: String): String {
+        val obj = JSONObject()
+        obj.put("success", false)
+        obj.put("error", message)
+        obj.put("message", message)
+        return obj.toString()
+    }
+}
@@ -1,12 +1,4 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- Modify this file to customize your launch splash screen -->
 <layer-list xmlns:android="http://schemas.android.com/apk/res/android">
    <item android:drawable="?android:colorBackground" />
-
-    <!-- You can insert your own image assets here -->
-    <!-- <item>
-        <bitmap
-            android:gravity="center"
-            android:src="@mipmap/launch_image" />
-    </item> -->
 </layer-list>
@@ -1,12 +1,4 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- Modify this file to customize your launch splash screen -->
 <layer-list xmlns:android="http://schemas.android.com/apk/res/android">
    <item android:drawable="@android:color/white" />
-
-    <!-- You can insert your own image assets here -->
-    <!-- <item>
-        <bitmap
-            android:gravity="center"
-            android:src="@mipmap/launch_image" />
-    </item> -->
 </layer-list>
@@ -6,4 +6,9 @@
          android:drawable="@drawable/ic_launcher_foreground"
          android:inset="16%" />
  </foreground>
+  <monochrome>
+      <inset
+          android:drawable="@drawable/ic_launcher_monochrome"
+          android:inset="16%" />
+  </monochrome>
 </adaptive-icon>
@@ -1,17 +1,8 @@
 <?xml version="1.0" encoding="utf-8"?>
 <resources>
-    <!-- Theme applied to the Android Window while the process is starting when the OS's Dark Mode setting is on -->
    <style name="LaunchTheme" parent="@android:style/Theme.Black.NoTitleBar">
-        <!-- Show a splash screen on the activity. Automatically removed when
-             the Flutter engine draws its first frame -->
        <item name="android:windowBackground">@drawable/launch_background</item>
    </style>
-    <!-- Theme applied to the Android Window as soon as the process has started.
-         This theme determines the color of the Android Window while your
-         Flutter UI initializes, as well as behind your Flutter UI while its
-         running.
-
-         This Theme is only used starting with V2 of Flutter's Android embedding. -->
    <style name="NormalTheme" parent="@android:style/Theme.Black.NoTitleBar">
        <item name="android:windowBackground">?android:colorBackground</item>
    </style>
@@ -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>
@@ -1,17 +1,8 @@
 <?xml version="1.0" encoding="utf-8"?>
 <resources>
-    <!-- Theme applied to the Android Window while the process is starting when the OS's Dark Mode setting is off -->
    <style name="LaunchTheme" parent="@android:style/Theme.Light.NoTitleBar">
-        <!-- Show a splash screen on the activity. Automatically removed when
-             the Flutter engine draws its first frame -->
        <item name="android:windowBackground">@drawable/launch_background</item>
    </style>
-    <!-- Theme applied to the Android Window as soon as the process has started.
-         This theme determines the color of the Android Window while your
-         Flutter UI initializes, as well as behind your Flutter UI while its
-         running.
-
-         This Theme is only used starting with V2 of Flutter's Android embedding. -->
    <style name="NormalTheme" parent="@android:style/Theme.Light.NoTitleBar">
        <item name="android:windowBackground">?android:colorBackground</item>
    </style>
@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="utf-8"?>
+<automotiveApp>
+    <uses name="media" />
+</automotiveApp>
@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="utf-8"?>
+<locale-config xmlns:android="http://schemas.android.com/apk/res/android">
+    <locale android:name="en" />
+    <locale android:name="ru" />
+    <locale android:name="es-ES" />
+    <locale android:name="id" />
+    <locale android:name="pt-PT" />
+    <locale android:name="ja" />
+    <locale android:name="tr" />
+    <locale android:name="de" />
+    <locale android:name="fr" />
+    <locale android:name="hi" />
+    <locale android:name="ko" />
+    <locale android:name="nl" />
+    <locale android:name="zh" />
+</locale-config>
@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="utf-8"?>
+<network-security-config>
+    <base-config cleartextTrafficPermitted="false" />
+
+    <!-- Allow local loopback cleartext for FFmpeg live decrypt tunnel only. -->
+    <domain-config cleartextTrafficPermitted="true">
+        <domain includeSubdomains="true">localhost</domain>
+        <domain includeSubdomains="true">127.0.0.1</domain>
+    </domain-config>
+</network-security-config>
@@ -11,8 +11,8 @@ subprojects {
            project.extensions.configure<com.android.build.gradle.BaseExtension>("android") {
                compileOptions {
                    isCoreLibraryDesugaringEnabled = true
-                    sourceCompatibility = JavaVersion.VERSION_17
-                    targetCompatibility = JavaVersion.VERSION_17
+                    sourceCompatibility = JavaVersion.VERSION_25
+                    targetCompatibility = JavaVersion.VERSION_25
                }
                
                // Enable multidex for all subprojects
@@ -22,12 +22,12 @@ 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 {
            compilerOptions {
-                jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17)
+                jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_25)
            }
        }
    }
@@ -1,2 +1,6 @@
-org.gradle.jvmargs=-Xmx8G -XX:MaxMetaspaceSize=4G -XX:ReservedCodeCacheSize=512m -XX:+HeapDumpOnOutOfMemoryError
+org.gradle.jvmargs=-Xmx2g -XX:MaxMetaspaceSize=512m -XX:ReservedCodeCacheSize=256m -XX:+HeapDumpOnOutOfMemoryError
 android.useAndroidX=true
+# This builtInKotlin flag was added automatically by Flutter migrator
+android.builtInKotlin=false
+# This newDsl flag was added automatically by Flutter migrator
+android.newDsl=false
@@ -1,5 +1,9 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-9.5.0-all.zip
+networkTimeout=10000
+retries=0
+retryBackOffMs=500
+validateDistributionUrl=true
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-8.14-all.zip
@@ -19,8 +19,8 @@ pluginManagement {

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

 include(":app")
@@ -0,0 +1,18 @@
+{
+  "name": "SpotiFLAC Mobile Source",
+  "identifier": "com.zarzet.spotiflac.source",
+  "subtitle": "FLAC Downloader for iOS",
+  "apps": [
+    {
+      "name": "SpotiFLAC Mobile",
+      "bundleIdentifier": "com.zarzet.spotiflac",
+      "developerName": "zarzet",
+      "version": "4.7.1",
+      "versionDate": "2026-07-01",
+      "downloadURL": "https://github.com/zarzet/SpotiFLAC-Mobile/releases/download/v4.7.1/SpotiFLAC-v4.7.1-ios-unsigned.ipa",
+      "localizedDescription": "SpotiFLAC Mobile is 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": 37455821
+    }
+  ]
+}
@@ -1,136 +0,0 @@
-import 'dart:io';
-import 'package:ffmpeg_kit_flutter_new_audio/ffmpeg_kit.dart';
-import 'package:ffmpeg_kit_flutter_new_audio/return_code.dart';
-import 'package:spotiflac_android/utils/logger.dart';
-
-final _log = AppLogger('FFmpeg');
-
-/// FFmpeg service for iOS using ffmpeg_kit_flutter plugin
-class FFmpegServiceIOS {
-  /// Execute FFmpeg command and return result
-  static Future<FFmpegResultIOS> _execute(String command) async {
-    try {
-      final session = await FFmpegKit.execute(command);
-      final returnCode = await session.getReturnCode();
-      final output = await session.getOutput() ?? '';
-      return FFmpegResultIOS(
-        success: ReturnCode.isSuccess(returnCode),
-        returnCode: returnCode?.getValue() ?? -1,
-        output: output,
-      );
-    } catch (e) {
-      _log.e('FFmpeg execute error: $e');
-      return FFmpegResultIOS(success: false, returnCode: -1, output: e.toString());
-    }
-  }
-
-  /// Convert M4A (DASH segments) to FLAC
-  static Future<String?> convertM4aToFlac(String inputPath) async {
-    final outputPath = inputPath.replaceAll('.m4a', '.flac');
-    final command = '-i "$inputPath" -c:a flac -compression_level 8 "$outputPath" -y';
-    final result = await _execute(command);
-
-    if (result.success) {
-      try {
-        await File(inputPath).delete();
-      } catch (_) {}
-      return outputPath;
-    }
-
-    _log.e('M4A to FLAC conversion failed: ${result.output}');
-    return null;
-  }
-
-  /// Convert FLAC to MP3
-  static Future<String?> convertFlacToMp3(String inputPath, {String bitrate = '320k'}) async {
-    final dir = File(inputPath).parent.path;
-    final baseName = inputPath.split(Platform.pathSeparator).last.replaceAll('.flac', '');
-    final outputDir = '$dir${Platform.pathSeparator}MP3';
-    await Directory(outputDir).create(recursive: true);
-    final outputPath = '$outputDir${Platform.pathSeparator}$baseName.mp3';
-
-    final command = '-i "$inputPath" -codec:a libmp3lame -b:a $bitrate -map 0:a -map_metadata 0 -id3v2_version 3 "$outputPath" -y';
-    final result = await _execute(command);
-
-    if (result.success) return outputPath;
-    _log.e('FLAC to MP3 conversion failed: ${result.output}');
-    return null;
-  }
-
-  /// Convert FLAC to M4A
-  static Future<String?> convertFlacToM4a(String inputPath, {String codec = 'aac', String bitrate = '256k'}) async {
-    final dir = File(inputPath).parent.path;
-    final baseName = inputPath.split(Platform.pathSeparator).last.replaceAll('.flac', '');
-    final outputDir = '$dir${Platform.pathSeparator}M4A';
-    await Directory(outputDir).create(recursive: true);
-    final outputPath = '$outputDir${Platform.pathSeparator}$baseName.m4a';
-
-    String command;
-    if (codec == 'alac') {
-      command = '-i "$inputPath" -codec:a alac -map 0:a -map_metadata 0 "$outputPath" -y';
-    } else {
-      command = '-i "$inputPath" -codec:a aac -b:a $bitrate -map 0:a -map_metadata 0 "$outputPath" -y';
-    }
-
-    final result = await _execute(command);
-    if (result.success) return outputPath;
-    _log.e('FLAC to M4A conversion failed: ${result.output}');
-    return null;
-  }
-
-  /// Embed cover art to FLAC file
-  static Future<String?> embedCover(String flacPath, String coverPath) async {
-    final tempOutput = '$flacPath.tmp';
-    final command = '-i "$flacPath" -i "$coverPath" -map 0:a -map 1:0 -c copy -metadata:s:v title="Album cover" -metadata:s:v comment="Cover (front)" -disposition:v attached_pic "$tempOutput" -y';
-
-    final result = await _execute(command);
-
-    if (result.success) {
-      try {
-        await File(flacPath).delete();
-        await File(tempOutput).rename(flacPath);
-        return flacPath;
-      } catch (e) {
-        _log.e('Failed to replace file after cover embed: $e');
-        return null;
-      }
-    }
-
-    try {
-      final tempFile = File(tempOutput);
-      if (await tempFile.exists()) await tempFile.delete();
-    } catch (_) {}
-
-    _log.e('Cover embed failed: ${result.output}');
-    return null;
-  }
-
-  /// Check if FFmpeg is available
-  static Future<bool> isAvailable() async {
-    try {
-      final session = await FFmpegKit.execute('-version');
-      final returnCode = await session.getReturnCode();
-      return ReturnCode.isSuccess(returnCode);
-    } catch (e) {
-      return false;
-    }
-  }
-
-  /// Get FFmpeg version info
-  static Future<String?> getVersion() async {
-    try {
-      final session = await FFmpegKit.execute('-version');
-      return await session.getOutput();
-    } catch (e) {
-      return null;
-    }
-  }
-}
-
-class FFmpegResultIOS {
-  final bool success;
-  final int returnCode;
-  final String output;
-
-  FFmpegResultIOS({required this.success, required this.returnCode, required this.output});
-}
@@ -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"
@@ -0,0 +1,23 @@
+files:
+  - source: /lib/l10n/arb/app_en.arb
+    translation: /lib/l10n/arb/app_%locale%.arb
+    languages_mapping:
+      locale:
+        # Keys MUST be the project's Crowdin language ids; values are the
+        # %locale% suffix used in app_%locale%.arb (underscores so Flutter
+        # gen-l10n parses them — hyphenated filenames break gen-l10n).
+        ar: ar
+        de: de
+        es-ES: es_ES
+        fr: fr
+        hi: hi
+        id: id
+        ja: ja
+        ko: ko
+        nl: nl
+        pt-PT: pt_PT
+        ru: ru
+        tr: tr
+        uk: uk
+        zh-CN: zh_CN
+        zh-TW: zh_TW
@@ -0,0 +1,322 @@
+package gobackend
+
+import (
+	"encoding/binary"
+	"fmt"
+	"os"
+)
+
+// mp4Box is a minimal ISO-BMFF / QuickTime box view over an in-memory buffer.
+type mp4Box struct {
+	offset int64
+	size   int64
+	hdr    int64
+	typ    string
+}
+
+func (b mp4Box) body() int64 { return b.offset + b.hdr }
+func (b mp4Box) end() int64  { return b.offset + b.size }
+
+func readMP4Box(data []byte, pos int64) (mp4Box, bool) {
+	n := int64(len(data))
+	if pos < 0 || pos+8 > n {
+		return mp4Box{}, false
+	}
+	size := int64(binary.BigEndian.Uint32(data[pos : pos+4]))
+	typ := string(data[pos+4 : pos+8])
+	hdr := int64(8)
+	if size == 1 {
+		if pos+16 > n {
+			return mp4Box{}, false
+		}
+		size = int64(binary.BigEndian.Uint64(data[pos+8 : pos+16]))
+		hdr = 16
+	} else if size == 0 {
+		size = n - pos
+	}
+	if size < hdr || pos+size > n {
+		return mp4Box{}, false
+	}
+	return mp4Box{offset: pos, size: size, hdr: hdr, typ: typ}, true
+}
+
+func findChildMP4(data []byte, start, end int64, typ string) (mp4Box, bool) {
+	pos := start
+	for pos+8 <= end {
+		b, ok := readMP4Box(data, pos)
+		if !ok {
+			return mp4Box{}, false
+		}
+		if b.typ == typ {
+			return b, true
+		}
+		pos = b.end()
+	}
+	return mp4Box{}, false
+}
+
+func eachChildMP4(data []byte, start, end int64, typ string, fn func(mp4Box) bool) {
+	pos := start
+	for pos+8 <= end {
+		b, ok := readMP4Box(data, pos)
+		if !ok {
+			return
+		}
+		if b.typ == typ && !fn(b) {
+			return
+		}
+		pos = b.end()
+	}
+}
+
+// findBoxBySignature scans [start,end) for a box of the given type, matching the
+// 4-byte type tag and validating the preceding size field. Used to locate dac4
+// which may be nested inside an encrypted (enca) sample entry.
+func findBoxBySignature(data []byte, start, end int64, typ string) (mp4Box, bool) {
+	if len(typ) != 4 {
+		return mp4Box{}, false
+	}
+	for i := start; i+8 <= end; i++ {
+		if data[i+4] == typ[0] && data[i+5] == typ[1] && data[i+6] == typ[2] && data[i+7] == typ[3] {
+			if b, ok := readMP4Box(data, i); ok && b.typ == typ {
+				return b, true
+			}
+		}
+	}
+	return mp4Box{}, false
+}
+
+// audioSampleEntryHeaderLen returns the byte length of the fixed audio sample
+// entry header (from the box body start) before child boxes begin. ok is false
+// for malformed/truncated entries whose declared header is not fully present.
+func audioSampleEntryHeaderLen(data []byte, entry mp4Box) (hdrLen int64, ok bool) {
+	// 6 bytes reserved + 2 bytes data_reference_index, then the audio fields.
+	base := entry.body()
+	if base+10 > entry.end() {
+		return 0, false
+	}
+	version := binary.BigEndian.Uint16(data[base+8 : base+10])
+	hdrLen = 8 + 20
+	switch version {
+	case 1:
+		hdrLen += 16
+	case 2:
+		hdrLen += 36
+	}
+	if base+hdrLen > entry.end() {
+		return 0, false
+	}
+	return hdrLen, true
+}
+
+type ac4Location struct {
+	chain []mp4Box // moov, trak, mdia, minf, stbl, stsd (ancestors to grow)
+	entry mp4Box   // the ac-4 sample entry
+}
+
+func locateAC4Entry(data []byte) (ac4Location, bool) {
+	moov, ok := findChildMP4(data, 0, int64(len(data)), "moov")
+	if !ok {
+		return ac4Location{}, false
+	}
+	var found ac4Location
+	var ok2 bool
+	eachChildMP4(data, moov.body(), moov.end(), "trak", func(trak mp4Box) bool {
+		mdia, ok := findChildMP4(data, trak.body(), trak.end(), "mdia")
+		if !ok {
+			return true
+		}
+		minf, ok := findChildMP4(data, mdia.body(), mdia.end(), "minf")
+		if !ok {
+			return true
+		}
+		stbl, ok := findChildMP4(data, minf.body(), minf.end(), "stbl")
+		if !ok {
+			return true
+		}
+		stsd, ok := findChildMP4(data, stbl.body(), stbl.end(), "stsd")
+		if !ok {
+			return true
+		}
+		entry, ok := findChildMP4(data, stsd.body()+8, stsd.end(), "ac-4")
+		if !ok {
+			return true
+		}
+		found = ac4Location{chain: []mp4Box{moov, trak, mdia, minf, stbl, stsd}, entry: entry}
+		ok2 = true
+		return false
+	})
+	return found, ok2
+}
+
+func growBoxSize(data []byte, b mp4Box, delta int64) {
+	if b.hdr == 16 {
+		binary.BigEndian.PutUint64(data[b.offset+8:b.offset+16], uint64(b.size+delta))
+	} else {
+		binary.BigEndian.PutUint32(data[b.offset:b.offset+4], uint32(b.size+delta))
+	}
+}
+
+// shiftChunkOffsets adds delta to every stco/co64 entry that references a file
+// offset at or beyond insertPos, keeping sample pointers valid after bytes are
+// inserted into moov.
+func shiftChunkOffsets(data []byte, moov mp4Box, insertPos, delta int64) {
+	eachChildMP4(data, moov.body(), moov.end(), "trak", func(trak mp4Box) bool {
+		mdia, ok := findChildMP4(data, trak.body(), trak.end(), "mdia")
+		if !ok {
+			return true
+		}
+		minf, ok := findChildMP4(data, mdia.body(), mdia.end(), "minf")
+		if !ok {
+			return true
+		}
+		stbl, ok := findChildMP4(data, minf.body(), minf.end(), "stbl")
+		if !ok {
+			return true
+		}
+		if stco, ok := findChildMP4(data, stbl.body(), stbl.end(), "stco"); ok {
+			base := stco.body() + 4
+			if base+4 <= stco.end() {
+				count := int64(binary.BigEndian.Uint32(data[base : base+4]))
+				p := base + 4
+				for i := int64(0); i < count && p+4 <= stco.end(); i++ {
+					v := int64(binary.BigEndian.Uint32(data[p : p+4]))
+					if v >= insertPos {
+						binary.BigEndian.PutUint32(data[p:p+4], uint32(v+delta))
+					}
+					p += 4
+				}
+			}
+		}
+		if co64, ok := findChildMP4(data, stbl.body(), stbl.end(), "co64"); ok {
+			base := co64.body() + 4
+			if base+4 <= co64.end() {
+				count := int64(binary.BigEndian.Uint32(data[base : base+4]))
+				p := base + 4
+				for i := int64(0); i < count && p+8 <= co64.end(); i++ {
+					v := int64(binary.BigEndian.Uint64(data[p : p+8]))
+					if v >= insertPos {
+						binary.BigEndian.PutUint64(data[p:p+8], uint64(v+delta))
+					}
+					p += 8
+				}
+			}
+		}
+		return true
+	})
+}
+
+// normalizeQuickTimeAudioToMP4 rewrites a QuickTime-flavored file (FFmpeg mov
+// muxer output: ftyp brand "qt  " and a version-1 sound sample entry) into a
+// standard ISO MP4: an isom/mp42 brand and a plain version-0 AudioSampleEntry.
+// Windows Media Foundation (and other strict parsers) reject the QuickTime
+// flavor for AC-4 even when dac4 is present.
+func normalizeQuickTimeAudioToMP4(data []byte) []byte {
+	if ftyp, ok := findChildMP4(data, 0, int64(len(data)), "ftyp"); ok {
+		if ftyp.body()+4 <= int64(len(data)) {
+			copy(data[ftyp.body():ftyp.body()+4], []byte("mp42"))
+		}
+		for p := ftyp.body() + 8; p+4 <= ftyp.end(); p += 4 {
+			if string(data[p:p+4]) == "qt  " {
+				copy(data[p:p+4], []byte("isom"))
+			}
+		}
+	}
+
+	loc, ok := locateAC4Entry(data)
+	if !ok {
+		return data
+	}
+	entry := loc.entry
+	verPos := entry.body() + 8
+	if verPos+2 > entry.end() {
+		return data
+	}
+	if binary.BigEndian.Uint16(data[verPos:verPos+2]) != 1 {
+		return data // already v0 (or v2, left untouched)
+	}
+
+	// The v1 QuickTime sound extension is the 16 bytes following the 20-byte v0
+	// audio fields (samplesPerPacket, bytesPerPacket, bytesPerFrame, bytesPerSample).
+	extStart := entry.body() + 8 + 20
+	extEnd := extStart + 16
+	if extEnd > entry.end() {
+		return data
+	}
+	delta := int64(-16)
+
+	binary.BigEndian.PutUint16(data[verPos:verPos+2], 0)
+	shiftChunkOffsets(data, loc.chain[0], extStart, delta)
+	for _, b := range loc.chain {
+		growBoxSize(data, b, delta)
+	}
+	growBoxSize(data, entry, delta)
+
+	out := make([]byte, 0, len(data)-16)
+	out = append(out, data[:extStart]...)
+	out = append(out, data[extEnd:]...)
+	return out
+}
+
+// EnsureAC4ConfigBox makes a decrypted AC-4 MP4 standards-compliant and
+// playable: it normalizes FFmpeg's QuickTime-flavored mov output to an ISO MP4
+// and injects the AC-4 configuration box (dac4) into the ac-4 sample entry. The
+// dac4 box is copied verbatim from sourcePath (the original MP4, whose plaintext
+// moov still carries it). No-op when the file has no AC-4 track.
+func EnsureAC4ConfigBox(decryptedPath, sourcePath string) error {
+	dst, err := os.ReadFile(decryptedPath)
+	if err != nil {
+		return err
+	}
+
+	if _, ok := locateAC4Entry(dst); !ok {
+		return nil // not an AC-4 file; nothing to do
+	}
+
+	dst = normalizeQuickTimeAudioToMP4(dst)
+
+	loc, ok := locateAC4Entry(dst)
+	if !ok {
+		return nil
+	}
+
+	hdrLen, ok := audioSampleEntryHeaderLen(dst, loc.entry)
+	if !ok {
+		return fmt.Errorf("malformed ac-4 sample entry")
+	}
+	childStart := loc.entry.body() + hdrLen
+	if _, has := findChildMP4(dst, childStart, loc.entry.end(), "dac4"); has {
+		// Already has dac4; still persist any normalization changes.
+		return os.WriteFile(decryptedPath, dst, 0o644)
+	}
+
+	src, err := os.ReadFile(sourcePath)
+	if err != nil {
+		return err
+	}
+	srcMoov, ok := findChildMP4(src, 0, int64(len(src)), "moov")
+	if !ok {
+		return fmt.Errorf("source has no moov")
+	}
+	dac4Box, ok := findBoxBySignature(src, srcMoov.body(), srcMoov.end(), "dac4")
+	if !ok {
+		return fmt.Errorf("dac4 not found in source")
+	}
+	dac4 := append([]byte{}, src[dac4Box.offset:dac4Box.end()]...)
+
+	insertPos := childStart
+	delta := int64(len(dac4))
+
+	shiftChunkOffsets(dst, loc.chain[0], insertPos, delta)
+	for _, b := range loc.chain {
+		growBoxSize(dst, b, delta)
+	}
+	growBoxSize(dst, loc.entry, delta)
+
+	out := make([]byte, 0, len(dst)+len(dac4))
+	out = append(out, dst[:insertPos]...)
+	out = append(out, dac4...)
+	out = append(out, dst[insertPos:]...)
+
+	return os.WriteFile(decryptedPath, out, 0o644)
+}
@@ -0,0 +1,76 @@
+package gobackend
+
+import (
+	"bytes"
+	"encoding/binary"
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func mp4TestBox(typ string, body []byte) []byte {
+	out := make([]byte, 8+len(body))
+	binary.BigEndian.PutUint32(out[:4], uint32(len(out)))
+	copy(out[4:8], typ)
+	copy(out[8:], body)
+	return out
+}
+
+func mp4TestAC4Tree(entryBody []byte) []byte {
+	entry := mp4TestBox("ac-4", entryBody)
+	stsdBody := append([]byte{
+		0, 0, 0, 0, // version/flags
+		0, 0, 0, 1, // entry_count
+	}, entry...)
+	stsd := mp4TestBox("stsd", stsdBody)
+	stbl := mp4TestBox("stbl", stsd)
+	minf := mp4TestBox("minf", stbl)
+	mdia := mp4TestBox("mdia", minf)
+	trak := mp4TestBox("trak", mdia)
+	moov := mp4TestBox("moov", trak)
+	return moov
+}
+
+func shortAC4SampleEntryBody(version uint16) []byte {
+	body := make([]byte, 10)
+	binary.BigEndian.PutUint16(body[8:10], version)
+	return body
+}
+
+func TestNormalizeQuickTimeAudioToMP4IgnoresTruncatedAC4Entry(t *testing.T) {
+	input := mp4TestAC4Tree(shortAC4SampleEntryBody(1))
+
+	defer func() {
+		if r := recover(); r != nil {
+			t.Fatalf("normalizeQuickTimeAudioToMP4 panicked: %v", r)
+		}
+	}()
+
+	got := normalizeQuickTimeAudioToMP4(append([]byte{}, input...))
+	if !bytes.Equal(got, input) {
+		t.Fatal("truncated QuickTime AC-4 entry should be left unchanged")
+	}
+}
+
+func TestEnsureAC4ConfigBoxRejectsTruncatedAC4Entry(t *testing.T) {
+	dir := t.TempDir()
+	decryptedPath := filepath.Join(dir, "decrypted.mp4")
+	sourcePath := filepath.Join(dir, "source.mp4")
+
+	if err := os.WriteFile(decryptedPath, mp4TestAC4Tree(shortAC4SampleEntryBody(2)), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(sourcePath, mp4TestBox("moov", mp4TestBox("dac4", []byte{1, 2, 3, 4})), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	defer func() {
+		if r := recover(); r != nil {
+			t.Fatalf("EnsureAC4ConfigBox panicked: %v", r)
+		}
+	}()
+
+	if err := EnsureAC4ConfigBox(decryptedPath, sourcePath); err == nil {
+		t.Fatal("expected malformed AC-4 sample entry error")
+	}
+}
@@ -0,0 +1,182 @@
+package gobackend
+
+import (
+	"encoding/binary"
+	"encoding/json"
+	"os"
+	"strconv"
+	"strings"
+)
+
+// ac4Metadata mirrors the tag fields the app embeds for other formats. Numeric
+// fields are strings because they arrive as a JSON-encoded map of strings.
+type ac4Metadata struct {
+	Title       string `json:"title"`
+	Artist      string `json:"artist"`
+	Album       string `json:"album"`
+	AlbumArtist string `json:"albumArtist"`
+	Date        string `json:"date"`
+	Genre       string `json:"genre"`
+	Composer    string `json:"composer"`
+	TrackNumber string `json:"trackNumber"`
+	TotalTracks string `json:"totalTracks"`
+	DiscNumber  string `json:"discNumber"`
+	TotalDiscs  string `json:"totalDiscs"`
+	ISRC        string `json:"isrc"`
+	Label       string `json:"label"`
+	Copyright   string `json:"copyright"`
+	Lyrics      string `json:"lyrics"`
+}
+
+func atoiSafe(s string) int {
+	n, err := strconv.Atoi(strings.TrimSpace(s))
+	if err != nil {
+		return 0
+	}
+	return n
+}
+
+func itunesTextTag(atomType, value string) []byte {
+	data := make([]byte, 8+len(value))
+	binary.BigEndian.PutUint32(data[0:4], 1) // well-known type 1 = UTF-8
+	copy(data[8:], []byte(value))
+	return buildM4AAtom(atomType, buildM4AAtom("data", data))
+}
+
+func itunesNumberPairTag(atomType string, number, total int) []byte {
+	payload := make([]byte, 8)
+	binary.BigEndian.PutUint16(payload[2:4], uint16(number))
+	binary.BigEndian.PutUint16(payload[4:6], uint16(total))
+	data := make([]byte, 8+len(payload))
+	binary.BigEndian.PutUint32(data[0:4], 0) // type 0 = implicit/binary
+	copy(data[8:], payload)
+	return buildM4AAtom(atomType, buildM4AAtom("data", data))
+}
+
+func itunesCoverTag(image []byte) []byte {
+	typeCode := uint32(13) // JPEG
+	if len(image) >= 8 &&
+		image[0] == 0x89 && image[1] == 0x50 && image[2] == 0x4E && image[3] == 0x47 {
+		typeCode = 14 // PNG
+	}
+	data := make([]byte, 8+len(image))
+	binary.BigEndian.PutUint32(data[0:4], typeCode)
+	copy(data[8:], image)
+	return buildM4AAtom("covr", buildM4AAtom("data", data))
+}
+
+func itunesMetadataHandler() []byte {
+	payload := make([]byte, 0, 25)
+	payload = append(payload, 0, 0, 0, 0)            // version + flags
+	payload = append(payload, 0, 0, 0, 0)            // pre_defined
+	payload = append(payload, []byte("mdir")...)     // handler type
+	payload = append(payload, []byte("appl")...)     // reserved[0]
+	payload = append(payload, 0, 0, 0, 0, 0, 0, 0, 0) // reserved[1..2]
+	payload = append(payload, 0)                     // empty name
+	return buildM4AAtom("hdlr", payload)
+}
+
+// buildITunesUdta assembles a fresh udta>meta>(hdlr+ilst) box from metadata.
+func buildITunesUdta(md ac4Metadata, cover []byte) []byte {
+	ilst := make([]byte, 0, 256)
+	add := func(atomType, value string) {
+		if strings.TrimSpace(value) != "" {
+			ilst = append(ilst, itunesTextTag(atomType, value)...)
+		}
+	}
+	add("\xa9nam", md.Title)
+	add("\xa9ART", md.Artist)
+	add("\xa9alb", md.Album)
+	add("aART", md.AlbumArtist)
+	add("\xa9day", md.Date)
+	add("\xa9gen", md.Genre)
+	add("\xa9wrt", md.Composer)
+	if tn := atoiSafe(md.TrackNumber); tn > 0 {
+		ilst = append(ilst, itunesNumberPairTag("trkn", tn, atoiSafe(md.TotalTracks))...)
+	}
+	if dn := atoiSafe(md.DiscNumber); dn > 0 {
+		ilst = append(ilst, itunesNumberPairTag("disk", dn, atoiSafe(md.TotalDiscs))...)
+	}
+	if strings.TrimSpace(md.ISRC) != "" {
+		ilst = append(ilst, buildM4AFreeformAtom("ISRC", strings.TrimSpace(md.ISRC))...)
+	}
+	if strings.TrimSpace(md.Label) != "" {
+		ilst = append(ilst, buildM4AFreeformAtom("LABEL", strings.TrimSpace(md.Label))...)
+	}
+	if strings.TrimSpace(md.Copyright) != "" {
+		add("cprt", md.Copyright)
+	}
+	if strings.TrimSpace(md.Lyrics) != "" {
+		add("\xa9lyr", md.Lyrics)
+	}
+	if len(cover) > 0 {
+		ilst = append(ilst, itunesCoverTag(cover)...)
+	}
+
+	ilstBox := buildM4AAtom("ilst", ilst)
+	metaPayload := append([]byte{0, 0, 0, 0}, itunesMetadataHandler()...)
+	metaPayload = append(metaPayload, ilstBox...)
+	meta := buildM4AAtom("meta", metaPayload)
+	return buildM4AAtom("udta", meta)
+}
+
+// writeMP4iTunesMetadata replaces (or inserts) a udta>meta>ilst metadata box in
+// the moov of an MP4 buffer and returns the rewritten bytes.
+func writeMP4iTunesMetadata(data []byte, md ac4Metadata, cover []byte) []byte {
+	moov, ok := findChildMP4(data, 0, int64(len(data)), "moov")
+	if !ok {
+		return data
+	}
+	newUdta := buildITunesUdta(md, cover)
+
+	if udta, ok := findChildMP4(data, moov.body(), moov.end(), "udta"); ok {
+		delta := int64(len(newUdta)) - udta.size
+		shiftChunkOffsets(data, moov, udta.offset, delta)
+		growBoxSize(data, moov, delta)
+		out := make([]byte, 0, len(data)+len(newUdta))
+		out = append(out, data[:udta.offset]...)
+		out = append(out, newUdta...)
+		out = append(out, data[udta.end():]...)
+		return out
+	}
+
+	delta := int64(len(newUdta))
+	insertPos := moov.end()
+	shiftChunkOffsets(data, moov, insertPos, delta)
+	growBoxSize(data, moov, delta)
+	out := make([]byte, 0, len(data)+len(newUdta))
+	out = append(out, data[:insertPos]...)
+	out = append(out, newUdta...)
+	out = append(out, data[insertPos:]...)
+	return out
+}
+
+// WriteAC4MetadataIfApplicable writes iTunes metadata into an AC-4 MP4. Returns
+// true when the file was an AC-4 track and metadata was written; false when the
+// file is not AC-4 (the caller should fall back to its normal metadata path).
+func WriteAC4MetadataIfApplicable(decryptedPath, metadataJSON, coverPath string) (bool, error) {
+	data, err := os.ReadFile(decryptedPath)
+	if err != nil {
+		return false, err
+	}
+	if _, ok := locateAC4Entry(data); !ok {
+		return false, nil
+	}
+
+	var md ac4Metadata
+	if strings.TrimSpace(metadataJSON) != "" {
+		_ = json.Unmarshal([]byte(metadataJSON), &md)
+	}
+	var cover []byte
+	if strings.TrimSpace(coverPath) != "" {
+		if b, err := os.ReadFile(coverPath); err == nil {
+			cover = b
+		}
+	}
+
+	out := writeMP4iTunesMetadata(data, md, cover)
+	if err := os.WriteFile(decryptedPath, out, 0o644); err != nil {
+		return false, err
+	}
+	return true, nil
+}
@@ -1,488 +0,0 @@
-package gobackend
-
-import (
-	"bufio"
-	"encoding/base64"
-	"encoding/json"
-	"fmt"
-	"io"
-	"net/http"
-	"net/url"
-	"os"
-	"path/filepath"
-	"strings"
-	"sync"
-	"time"
-)
-
-// AmazonDownloader handles Amazon Music downloads using DoubleDouble service (same as PC)
-type AmazonDownloader struct {
-	client  *http.Client
-	regions []string // us, eu regions for DoubleDouble service
-}
-
-var (
-	// Global Amazon downloader instance for connection reuse
-	globalAmazonDownloader *AmazonDownloader
-	amazonDownloaderOnce   sync.Once
-)
-
-// DoubleDoubleSubmitResponse is the response from DoubleDouble submit endpoint
-type DoubleDoubleSubmitResponse struct {
-	Success bool   `json:"success"`
-	ID      string `json:"id"`
-}
-
-// DoubleDoubleStatusResponse is the response from DoubleDouble status endpoint
-type DoubleDoubleStatusResponse struct {
-	Status         string `json:"status"`
-	FriendlyStatus string `json:"friendlyStatus"`
-	URL            string `json:"url"`
-	Current        struct {
-		Name   string `json:"name"`
-		Artist string `json:"artist"`
-	} `json:"current"`
-}
-
-// amazonArtistsMatch checks if the artist names are similar enough
-func amazonArtistsMatch(expectedArtist, foundArtist string) bool {
-	normExpected := strings.ToLower(strings.TrimSpace(expectedArtist))
-	normFound := strings.ToLower(strings.TrimSpace(foundArtist))
-	
-	// Exact match
-	if normExpected == normFound {
-		return true
-	}
-	
-	// Check if one contains the other
-	if strings.Contains(normExpected, normFound) || strings.Contains(normFound, normExpected) {
-		return true
-	}
-	
-	// Check first artist (before comma or feat)
-	expectedFirst := strings.Split(normExpected, ",")[0]
-	expectedFirst = strings.Split(expectedFirst, " feat")[0]
-	expectedFirst = strings.Split(expectedFirst, " ft.")[0]
-	expectedFirst = strings.TrimSpace(expectedFirst)
-	
-	foundFirst := strings.Split(normFound, ",")[0]
-	foundFirst = strings.Split(foundFirst, " feat")[0]
-	foundFirst = strings.Split(foundFirst, " ft.")[0]
-	foundFirst = strings.TrimSpace(foundFirst)
-	
-	if expectedFirst == foundFirst {
-		return true
-	}
-	
-	// Check if first artist is contained in the other
-	if strings.Contains(expectedFirst, foundFirst) || strings.Contains(foundFirst, expectedFirst) {
-		return true
-	}
-	
-	// If scripts are different (one is ASCII, one is non-ASCII like Japanese/Chinese/Korean),
-	// assume they're the same artist with different transliteration
-	expectedASCII := amazonIsASCIIString(expectedArtist)
-	foundASCII := amazonIsASCIIString(foundArtist)
-	if expectedASCII != foundASCII {
-		fmt.Printf("[Amazon] Artist names in different scripts, assuming match: '%s' vs '%s'\n", expectedArtist, foundArtist)
-		return true
-	}
-	
-	return false
-}
-
-// amazonIsASCIIString checks if a string contains only ASCII characters
-func amazonIsASCIIString(s string) bool {
-	for _, r := range s {
-		if r > 127 {
-			return false
-		}
-	}
-	return true
-}
-
-// NewAmazonDownloader creates a new Amazon downloader (returns singleton for connection reuse)
-func NewAmazonDownloader() *AmazonDownloader {
-	amazonDownloaderOnce.Do(func() {
-		globalAmazonDownloader = &AmazonDownloader{
-			client:  NewHTTPClientWithTimeout(120 * time.Second), // 120s timeout like PC
-			regions: []string{"us", "eu"},                        // Same regions as PC
-		}
-	})
-	return globalAmazonDownloader
-}
-
-// GetAvailableAPIs returns list of available DoubleDouble regions
-// Uses same service as PC version (doubledouble.top)
-func (a *AmazonDownloader) GetAvailableAPIs() []string {
-	// DoubleDouble service regions (same as PC)
-	// Format: https://{region}.doubledouble.top
-	var apis []string
-	for _, region := range a.regions {
-		apis = append(apis, fmt.Sprintf("https://%s.doubledouble.top", region))
-	}
-	return apis
-}
-
-
-// downloadFromDoubleDoubleService downloads a track using DoubleDouble service (same as PC)
-// This uses submit → poll → download mechanism
-// Internal function - not exported to gomobile
-func (a *AmazonDownloader) downloadFromDoubleDoubleService(amazonURL, outputDir string) (string, string, string, error) {
-	var lastError error
-
-	for _, region := range a.regions {
-		fmt.Printf("[Amazon] Trying region: %s...\n", region)
-
-		// Build base URL for DoubleDouble service
-		// Decode base64 service URL (same as PC)
-		serviceBase, _ := base64.StdEncoding.DecodeString("aHR0cHM6Ly8=")         // https://
-		serviceDomain, _ := base64.StdEncoding.DecodeString("LmRvdWJsZWRvdWJsZS50b3A=") // .doubledouble.top
-		baseURL := fmt.Sprintf("%s%s%s", string(serviceBase), region, string(serviceDomain))
-
-		// Step 1: Submit download request
-		encodedURL := url.QueryEscape(amazonURL)
-		submitURL := fmt.Sprintf("%s/dl?url=%s", baseURL, encodedURL)
-
-		req, err := http.NewRequest("GET", submitURL, nil)
-		if err != nil {
-			lastError = fmt.Errorf("failed to create request: %w", err)
-			continue
-		}
-
-		req.Header.Set("User-Agent", getRandomUserAgent())
-
-		fmt.Println("[Amazon] Submitting download request...")
-		resp, err := a.client.Do(req)
-		if err != nil {
-			lastError = fmt.Errorf("failed to submit request: %w", err)
-			continue
-		}
-
-		if resp.StatusCode != 200 {
-			resp.Body.Close()
-			lastError = fmt.Errorf("submit failed with status %d", resp.StatusCode)
-			continue
-		}
-
-		var submitResp DoubleDoubleSubmitResponse
-		if err := json.NewDecoder(resp.Body).Decode(&submitResp); err != nil {
-			resp.Body.Close()
-			lastError = fmt.Errorf("failed to decode submit response: %w", err)
-			continue
-		}
-		resp.Body.Close()
-
-		if !submitResp.Success || submitResp.ID == "" {
-			lastError = fmt.Errorf("submit request failed")
-			continue
-		}
-
-		downloadID := submitResp.ID
-		fmt.Printf("[Amazon] Download ID: %s\n", downloadID)
-
-		// Step 2: Poll for completion
-		statusURL := fmt.Sprintf("%s/dl/%s", baseURL, downloadID)
-		fmt.Println("[Amazon] Waiting for download to complete...")
-
-		maxWait := 300 * time.Second // 5 minutes max wait
-		elapsed := time.Duration(0)
-		pollInterval := 3 * time.Second
-
-		for elapsed < maxWait {
-			time.Sleep(pollInterval)
-			elapsed += pollInterval
-
-			statusReq, err := http.NewRequest("GET", statusURL, nil)
-			if err != nil {
-				continue
-			}
-
-			statusReq.Header.Set("User-Agent", getRandomUserAgent())
-
-			statusResp, err := a.client.Do(statusReq)
-			if err != nil {
-				fmt.Printf("\r[Amazon] Status check failed, retrying...")
-				continue
-			}
-
-			if statusResp.StatusCode != 200 {
-				statusResp.Body.Close()
-				fmt.Printf("\r[Amazon] Status check failed (status %d), retrying...", statusResp.StatusCode)
-				continue
-			}
-
-			var status DoubleDoubleStatusResponse
-			if err := json.NewDecoder(statusResp.Body).Decode(&status); err != nil {
-				statusResp.Body.Close()
-				fmt.Printf("\r[Amazon] Invalid JSON response, retrying...")
-				continue
-			}
-			statusResp.Body.Close()
-
-			if status.Status == "done" {
-				fmt.Println("\n[Amazon] Download ready!")
-
-				// Build download URL
-				fileURL := status.URL
-				if strings.HasPrefix(fileURL, "./") {
-					fileURL = fmt.Sprintf("%s/%s", baseURL, fileURL[2:])
-				} else if strings.HasPrefix(fileURL, "/") {
-					fileURL = fmt.Sprintf("%s%s", baseURL, fileURL)
-				}
-
-				trackName := status.Current.Name
-				artist := status.Current.Artist
-
-				fmt.Printf("[Amazon] Downloading: %s - %s\n", artist, trackName)
-				return fileURL, trackName, artist, nil
-
-			} else if status.Status == "error" {
-				errorMsg := status.FriendlyStatus
-				if errorMsg == "" {
-					errorMsg = "Unknown error"
-				}
-				lastError = fmt.Errorf("processing failed: %s", errorMsg)
-				break
-			} else {
-				// Still processing
-				friendlyStatus := status.FriendlyStatus
-				if friendlyStatus == "" {
-					friendlyStatus = status.Status
-				}
-				fmt.Printf("\r[Amazon] %s...", friendlyStatus)
-			}
-		}
-
-		if elapsed >= maxWait {
-			lastError = fmt.Errorf("download timeout")
-			fmt.Printf("\n[Amazon] Error with %s region: %v\n", region, lastError)
-			continue
-		}
-
-		if lastError != nil {
-			fmt.Printf("\n[Amazon] Error with %s region: %v\n", region, lastError)
-		}
-	}
-
-	return "", "", "", fmt.Errorf("all regions failed. Last error: %v", lastError)
-}
-
-
-// DownloadFile downloads a file from URL with User-Agent and progress tracking
-func (a *AmazonDownloader) DownloadFile(downloadURL, outputPath, itemID string) error {
-	// Initialize item progress (required for all downloads)
-	if itemID != "" {
-		StartItemProgress(itemID)
-		defer CompleteItemProgress(itemID)
-	}
-
-	req, err := http.NewRequest("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 {
-		return err
-	}
-	defer resp.Body.Close()
-
-	if resp.StatusCode != 200 {
-		return fmt.Errorf("download failed: HTTP %d", resp.StatusCode)
-	}
-
-	// Set total bytes if available
-	if resp.ContentLength > 0 && itemID != "" {
-		SetItemBytesTotal(itemID, resp.ContentLength)
-	}
-
-	out, err := os.Create(outputPath)
-	if err != nil {
-		return err
-	}
-	defer out.Close()
-
-	// Use buffered writer for better performance (256KB buffer)
-	bufWriter := bufio.NewWriterSize(out, 256*1024)
-	defer bufWriter.Flush()
-
-	// Use item progress writer with buffered output
-	var bytesWritten int64
-	if itemID != "" {
-		pw := NewItemProgressWriter(bufWriter, itemID)
-		bytesWritten, err = io.Copy(pw, resp.Body)
-	} else {
-		// Fallback: direct copy without progress tracking
-		bytesWritten, err = io.Copy(bufWriter, resp.Body)
-	}
-	if err != nil {
-		return fmt.Errorf("failed to write file: %w", err)
-	}
-
-	fmt.Printf("\r[Amazon] Downloaded: %.2f MB (Complete)\n", float64(bytesWritten)/(1024*1024))
-	return nil
-}
-
-// AmazonDownloadResult contains download result with quality info
-type AmazonDownloadResult struct {
-	FilePath   string
-	BitDepth   int
-	SampleRate int
-}
-
-// downloadFromAmazon downloads a track using the request parameters
-// Uses DoubleDouble service (same as PC version)
-func downloadFromAmazon(req DownloadRequest) (AmazonDownloadResult, error) {
-	downloader := NewAmazonDownloader()
-
-	// Check for existing file first
-	if existingFile, exists := checkISRCExistsInternal(req.OutputDir, req.ISRC); exists {
-		return AmazonDownloadResult{FilePath: "EXISTS:" + existingFile}, nil
-	}
-
-	// Get Amazon URL from SongLink
-	songlink := NewSongLinkClient()
-	availability, err := songlink.CheckTrackAvailability(req.SpotifyID, req.ISRC)
-	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)")
-	}
-
-	// Create output directory if needed
-	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 DoubleDouble service (same as PC)
-	downloadURL, trackName, artistName, err := downloader.downloadFromDoubleDoubleService(availability.AmazonURL, req.OutputDir)
-	if err != nil {
-		return AmazonDownloadResult{}, fmt.Errorf("failed to get download URL: %w", err)
-	}
-
-	// Verify artist matches
-	if artistName != "" && !amazonArtistsMatch(req.ArtistName, artistName) {
-		fmt.Printf("[Amazon] Artist mismatch: expected '%s', got '%s'. Rejecting.\n", req.ArtistName, artistName)
-		return AmazonDownloadResult{}, fmt.Errorf("artist mismatch: expected '%s', got '%s'", req.ArtistName, artistName)
-	}
-
-	// Log match found
-	fmt.Printf("[Amazon] Match found: '%s' by '%s'\n", trackName, artistName)
-
-	// Build filename using Spotify metadata (more accurate)
-	filename := buildFilenameFromTemplate(req.FilenameFormat, map[string]interface{}{
-		"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)
-
-	// Check if file already exists
-	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,
-		)
-	}()
-
-	// Download audio file with item ID for progress tracking
-	if err := downloader.DownloadFile(downloadURL, outputPath, req.ItemID); err != nil {
-		return AmazonDownloadResult{}, fmt.Errorf("download failed: %w", err)
-	}
-
-	// Wait for parallel operations to complete
-	<-parallelDone
-
-	// Set progress to 100% and status to finalizing (before embedding)
-	// This makes the UI show "Finalizing..." while embedding happens
-	if req.ItemID != "" {
-		SetItemProgress(req.ItemID, 1.0, 0, 0)
-		SetItemFinalizing(req.ItemID)
-	}
-
-	// Log track info from DoubleDouble (for debugging)
-	if trackName != "" && artistName != "" {
-		fmt.Printf("[Amazon] DoubleDouble returned: %s - %s\n", artistName, trackName)
-	}
-
-	// Embed metadata using Spotify data (more accurate than DoubleDouble)
-	metadata := Metadata{
-		Title:       req.TrackName,
-		Artist:      req.ArtistName,
-		Album:       req.AlbumName,
-		AlbumArtist: req.AlbumArtist,
-		Date:        req.ReleaseDate,
-		TrackNumber: req.TrackNumber,
-		TotalTracks: req.TotalTracks,
-		DiscNumber:  req.DiscNumber,
-		ISRC:        req.ISRC,
-	}
-
-	// Use cover data from parallel fetch
-	var coverData []byte
-	if parallelResult != nil && parallelResult.CoverData != nil {
-		coverData = parallelResult.CoverData
-		fmt.Printf("[Amazon] Using parallel-fetched cover (%d bytes)\n", len(coverData))
-	}
-
-	if err := EmbedMetadataWithCoverData(outputPath, metadata, coverData); err != nil {
-		fmt.Printf("Warning: failed to embed metadata: %v\n", err)
-	}
-
-	// Embed lyrics from parallel fetch
-	if req.EmbedLyrics && parallelResult != nil && parallelResult.LyricsLRC != "" {
-		fmt.Printf("[Amazon] Embedding parallel-fetched lyrics (%d lines)...\n", len(parallelResult.LyricsData.Lines))
-		if embedErr := EmbedLyrics(outputPath, parallelResult.LyricsLRC); embedErr != nil {
-			fmt.Printf("[Amazon] Warning: failed to embed lyrics: %v\n", embedErr)
-		} else {
-			fmt.Println("[Amazon] Lyrics embedded successfully")
-		}
-	} else if req.EmbedLyrics {
-		fmt.Println("[Amazon] No lyrics available from parallel fetch")
-	}
-
-	fmt.Println("[Amazon] ✓ Downloaded successfully from Amazon Music")
-	
-	// Read actual quality from the downloaded FLAC file
-	// Amazon API doesn't provide quality info, but we can read it from the file itself
-	quality, err := GetAudioQuality(outputPath)
-	if err != nil {
-		fmt.Printf("[Amazon] Warning: couldn't read quality from file: %v\n", err)
-		// Return 0 to indicate unknown quality
-		return AmazonDownloadResult{
-			FilePath:   outputPath,
-			BitDepth:   0,
-			SampleRate: 0,
-		}, nil
-	}
-	
-	fmt.Printf("[Amazon] Actual quality: %d-bit/%dHz\n", quality.BitDepth, quality.SampleRate)
-	return AmazonDownloadResult{
-		FilePath:   outputPath,
-		BitDepth:   quality.BitDepth,
-		SampleRate: quality.SampleRate,
-	}, nil
-}
@@ -0,0 +1,606 @@
+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")
+	}
+
+	// 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]))
+
+		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)
+
+	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 {
+	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")
+	}
+
+	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
+}
@@ -0,0 +1,121 @@
+package gobackend
+
+import (
+	"bytes"
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestAPETagReadWriteMergeAndMetadataConversion(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "sample.ape")
+	if err := os.WriteFile(path, []byte("audio-data"), 0600); err != nil {
+		t.Fatalf("write sample: %v", err)
+	}
+
+	metadata := &AudioMetadata{
+		Title:               "Song",
+		Artist:              "Artist",
+		Album:               "Album",
+		AlbumArtist:         "Album Artist",
+		Genre:               "Pop",
+		Date:                "2026",
+		TrackNumber:         3,
+		TotalTracks:         12,
+		DiscNumber:          1,
+		TotalDiscs:          2,
+		ISRC:                "USRC17607839",
+		Lyrics:              "lyrics",
+		Label:               "Label",
+		Copyright:           "Copyright",
+		Composer:            "Composer",
+		Comment:             "Comment",
+		ReplayGainTrackGain: "-6.50 dB",
+		ReplayGainTrackPeak: "0.98",
+		ReplayGainAlbumGain: "-5.00 dB",
+		ReplayGainAlbumPeak: "0.99",
+	}
+	items := AudioMetadataToAPEItems(metadata)
+	if len(items) == 0 {
+		t.Fatal("expected APE items")
+	}
+
+	tag := &APETag{Items: append(items, APETagItem{Key: "Custom", Value: "Keep"})}
+	if err := WriteAPETags(path, tag); err != nil {
+		t.Fatalf("WriteAPETags: %v", err)
+	}
+
+	readTag, err := ReadAPETags(path)
+	if err != nil {
+		t.Fatalf("ReadAPETags: %v", err)
+	}
+	if readTag.Version != apeTagVersion2 {
+		t.Fatalf("version = %d", readTag.Version)
+	}
+	readMetadata := APETagToAudioMetadata(readTag)
+	if readMetadata.Title != "Song" || readMetadata.TrackNumber != 3 || readMetadata.TotalTracks != 12 {
+		t.Fatalf("metadata = %#v", readMetadata)
+	}
+
+	readerTag, err := ReadAPETagsFromReader(bytes.NewReader(mustReadFile(t, path)), int64(len(mustReadFile(t, path))))
+	if err != nil {
+		t.Fatalf("ReadAPETagsFromReader: %v", err)
+	}
+	if len(readerTag.Items) != len(readTag.Items) {
+		t.Fatalf("reader items = %d, file items = %d", len(readerTag.Items), len(readTag.Items))
+	}
+
+	override := apeKeysFromFields(map[string]string{"title": "", "lyrics": "", "disc_total": ""})
+	merged := MergeAPEItems(readTag.Items, []APETagItem{{Key: "Title", Value: "New Song"}}, override)
+	mergedMeta := APETagToAudioMetadata(&APETag{Items: merged})
+	if mergedMeta.Title != "New Song" {
+		t.Fatalf("merged title = %q", mergedMeta.Title)
+	}
+	if mergedMeta.Lyrics != "" {
+		t.Fatalf("expected lyrics cleared, got %q", mergedMeta.Lyrics)
+	}
+
+	if err := WriteAPETags(path, &APETag{Items: []APETagItem{{Key: "Title", Value: "Replacement"}}}); err != nil {
+		t.Fatalf("replace APE tags: %v", err)
+	}
+	replaced, err := ReadAPETags(path)
+	if err != nil {
+		t.Fatalf("read replacement: %v", err)
+	}
+	if got := APETagToAudioMetadata(replaced).Title; got != "Replacement" {
+		t.Fatalf("replacement title = %q", got)
+	}
+
+	if _, err := marshalAPETag(nil); err == nil {
+		t.Fatal("expected empty tag error")
+	}
+	if _, err := ReadAPETags(filepath.Join(dir, "missing.ape")); err == nil {
+		t.Fatal("expected missing file error")
+	}
+	if _, err := ReadAPETagsFromReader(bytes.NewReader([]byte("short")), 5); err == nil {
+		t.Fatal("expected small reader error")
+	}
+}
+
+func TestAPETagInvalidFooterBranches(t *testing.T) {
+	footer := buildAPEHeaderFooter(9999, apeTagHeaderSize, 1, 0)
+	if _, err := parseAPETagFromFooter(bytes.NewReader(footer), int64(len(footer)), 0, footer); err == nil {
+		t.Fatal("expected unsupported version")
+	}
+
+	footer = buildAPEHeaderFooter(apeTagVersion2, apeTagHeaderSize-1, 1, 0)
+	if _, err := parseAPETagFromFooter(bytes.NewReader(footer), int64(len(footer)), 0, footer); err == nil {
+		t.Fatal("expected small tag size")
+	}
+
+	footer = buildAPEHeaderFooter(apeTagVersion2, apeTagHeaderSize, 1001, 0)
+	if _, err := parseAPETagFromFooter(bytes.NewReader(footer), int64(len(footer)), 0, footer); err == nil {
+		t.Fatal("expected too many items")
+	}
+
+	footer = buildAPEHeaderFooter(apeTagVersion2, apeTagHeaderSize, 1, apeTagFlagHeader)
+	if _, err := parseAPETagFromFooter(bytes.NewReader(footer), int64(len(footer)), 0, footer); err == nil {
+		t.Fatal("expected header flag error")
+	}
+}
@@ -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)
+	}
+}
@@ -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)
+	}
+}
@@ -0,0 +1,517 @@
+package gobackend
+
+import (
+	"bytes"
+	"encoding/base64"
+	"encoding/binary"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestAudioMetadataID3ParsingBranches(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "tagged.mp3")
+	tag := buildID3v23Tag(
+		id3TextFrame("TIT2", "Title"),
+		id3TextFrame("TPE1", "Artist"),
+		id3TextFrame("TPE2", "Album Artist"),
+		id3TextFrame("TALB", "Album"),
+		id3TextFrame("TDRC", "2026-05-04"),
+		id3TextFrame("TCON", "(13)Pop"),
+		id3TextFrame("TRCK", "4/12"),
+		id3TextFrame("TPOS", "1/2"),
+		id3TextFrame("TSRC", "USRC17607839"),
+		id3TextFrame("TCOM", "Composer"),
+		id3TextFrame("TPUB", "Label"),
+		id3TextFrame("TCOP", "Copyright"),
+		id3CommentFrame("COMM", "Comment"),
+		id3CommentFrame("USLT", "Lyrics"),
+		id3UserTextFrame("TXXX", "REPLAYGAIN_TRACK_GAIN", "-6.50 dB"),
+		id3UserTextFrame("TXXX", "REPLAYGAIN_TRACK_PEAK", "0.98"),
+	)
+	if err := os.WriteFile(path, append(tag, []byte("audio")...), 0600); err != nil {
+		t.Fatalf("write ID3v2: %v", err)
+	}
+
+	meta, err := ReadID3Tags(path)
+	if err != nil {
+		t.Fatalf("ReadID3Tags: %v", err)
+	}
+	if meta.Title != "Title" || meta.TrackNumber != 4 || meta.TotalTracks != 12 || meta.Genre != "Pop" {
+		t.Fatalf("metadata = %#v", meta)
+	}
+	if meta.Comment != "Comment" || meta.Lyrics != "Lyrics" || meta.ReplayGainTrackGain == "" {
+		t.Fatalf("metadata comments/lyrics/replaygain = %#v", meta)
+	}
+
+	id3v1Path := filepath.Join(dir, "id3v1.mp3")
+	if err := os.WriteFile(id3v1Path, append([]byte("audio"), buildID3v1Tag("V1 Title", "V1 Artist", "V1 Album", "1999", 7, 13)...), 0600); err != nil {
+		t.Fatalf("write ID3v1: %v", err)
+	}
+	v1, err := ReadID3Tags(id3v1Path)
+	if err != nil {
+		t.Fatalf("ReadID3Tags v1: %v", err)
+	}
+	if v1.Title != "V1 Title" || v1.Artist != "V1 Artist" || v1.Genre == "" {
+		t.Fatalf("v1 = %#v", v1)
+	}
+
+	v22Path := filepath.Join(dir, "id3v22.mp3")
+	v22 := buildID3v22Tag(
+		id3v22TextFrame("TT2", "V22 Title"),
+		id3v22TextFrame("TP1", "V22 Artist"),
+		id3v22TextFrame("TRK", "2/5"),
+		id3v22CommentFrame("ULT", "V22 Lyrics"),
+	)
+	if err := os.WriteFile(v22Path, append(v22, []byte("audio")...), 0600); err != nil {
+		t.Fatalf("write ID3v2.2: %v", err)
+	}
+	v22Meta, err := ReadID3Tags(v22Path)
+	if err != nil {
+		t.Fatalf("ReadID3Tags v2.2: %v", err)
+	}
+	if v22Meta.Title != "V22 Title" || v22Meta.Artist != "V22 Artist" || v22Meta.Lyrics != "V22 Lyrics" {
+		t.Fatalf("v22 = %#v", v22Meta)
+	}
+
+	if got := decodeUTF16([]byte{0xff, 0xfe, 'H', 0, 'i', 0}); got != "Hi" {
+		t.Fatalf("decodeUTF16 = %q", got)
+	}
+	if got := decodeUTF16BE([]byte{0, 'O', 0, 'K'}); got != "OK" {
+		t.Fatalf("decodeUTF16BE = %q", got)
+	}
+	if n, total := parseIndexPair(" 8 / 10 "); n != 8 || total != 10 {
+		t.Fatalf("parseIndexPair = %d/%d", n, total)
+	}
+	if got := parseTrackNumber("9/11"); got != 9 {
+		t.Fatalf("parseTrackNumber = %d", got)
+	}
+	if got := removeUnsync([]byte{0xff, 0x00, 0xe0}); !bytes.Equal(got, []byte{0xff, 0xe0}) {
+		t.Fatalf("removeUnsync = %#v", got)
+	}
+	if got := extendedHeaderSize([]byte{0, 0, 0, 6, 0, 0, 0, 0, 0, 0}, 3); got != 10 {
+		t.Fatalf("extendedHeaderSize = %d", got)
+	}
+	if got := syncsafeToInt([]byte{0, 0, 2, 0}); got != 256 {
+		t.Fatalf("syncsafe = %d", got)
+	}
+}
+
+func TestAudioMetadataCoverAndQualityHelpers(t *testing.T) {
+	png := []byte{0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A, 0, 0, 0, 0}
+	if detectCoverMIME("cover.jpg", png) != "image/png" || detectCoverMIME("cover.webp", []byte("RIFFxxxxWEBPdata")) != "image/webp" {
+		t.Fatal("cover MIME detection mismatch")
+	}
+	if _, err := buildPictureBlock("", nil); err == nil {
+		t.Fatal("expected empty picture block error")
+	}
+
+	apic := append([]byte{3}, []byte("image/png\x00")...)
+	apic = append(apic, 3, 0)
+	apic = append(apic, png...)
+	image, mime := parseAPICFrame(apic, 3)
+	if mime != "image/png" || !bytes.Equal(image, png) {
+		t.Fatalf("APIC = %s/%v", mime, image)
+	}
+	pic := append([]byte{0}, []byte("PNG")...)
+	pic = append(pic, 3, 0)
+	pic = append(pic, png...)
+	image, mime = parseAPICFrame(pic, 2)
+	if mime != "image/png" || !bytes.Equal(image, png) {
+		t.Fatalf("PIC = %s/%v", mime, image)
+	}
+
+	frame := make([]byte, 10)
+	copy(frame[:4], "APIC")
+	binary.BigEndian.PutUint32(frame[4:8], uint32(len(apic)))
+	tag := append(frame, apic...)
+	header := []byte{'I', 'D', '3', 3, 0, 0, byte(len(tag) >> 21), byte(len(tag) >> 14), byte(len(tag) >> 7), byte(len(tag))}
+	mp3CoverPath := filepath.Join(t.TempDir(), "cover.mp3")
+	if err := os.WriteFile(mp3CoverPath, append(append(header, tag...), []byte("audio")...), 0600); err != nil {
+		t.Fatal(err)
+	}
+	extracted, extractedMIME, err := extractMP3CoverArt(mp3CoverPath)
+	if err != nil || extractedMIME != "image/png" || !bytes.Equal(extracted, png) {
+		t.Fatalf("extractMP3CoverArt = %s/%v/%v", extractedMIME, extracted, err)
+	}
+
+	var picture bytes.Buffer
+	binary.Write(&picture, binary.BigEndian, uint32(3))
+	binary.Write(&picture, binary.BigEndian, uint32(len("image/png")))
+	picture.WriteString("image/png")
+	binary.Write(&picture, binary.BigEndian, uint32(0))
+	binary.Write(&picture, binary.BigEndian, uint32(1))
+	binary.Write(&picture, binary.BigEndian, uint32(1))
+	binary.Write(&picture, binary.BigEndian, uint32(32))
+	binary.Write(&picture, binary.BigEndian, uint32(0))
+	binary.Write(&picture, binary.BigEndian, uint32(len(png)))
+	picture.Write(png)
+	flacImage, flacMIME := parseFLACPictureBlock(picture.Bytes())
+	if flacMIME != "image/png" || !bytes.Equal(flacImage, png) {
+		t.Fatalf("FLAC picture = %s/%v", flacMIME, flacImage)
+	}
+
+	comment := "METADATA_BLOCK_PICTURE=" + base64.StdEncoding.EncodeToString(picture.Bytes())
+	var vorbis bytes.Buffer
+	binary.Write(&vorbis, binary.LittleEndian, uint32(6))
+	vorbis.WriteString("vendor")
+	binary.Write(&vorbis, binary.LittleEndian, uint32(1))
+	binary.Write(&vorbis, binary.LittleEndian, uint32(len(comment)))
+	vorbis.WriteString(comment)
+	commentImage, commentMIME := extractPictureFromVorbisComments(vorbis.Bytes())
+	if commentMIME != "image/png" || !bytes.Equal(commentImage, png) {
+		t.Fatalf("vorbis picture = %s/%v", commentMIME, commentImage)
+	}
+	decoded := make([]byte, base64StdDecodeLen(len("SGV sbG8="))+4)
+	n, err := base64StdDecode(decoded, []byte("SGV sbG8="))
+	if err != nil || strings.TrimRight(string(decoded[:n]), "\x00") != "Hello" {
+		t.Fatalf("base64 decode = %q/%v", decoded[:n], err)
+	}
+
+	if detectOggStreamType([][]byte{[]byte("OpusHeadxxxx")}) != oggStreamOpus {
+		t.Fatal("expected opus stream")
+	}
+	if detectOggStreamType([][]byte{append([]byte{1}, []byte("vorbisxxxx")...)}) != oggStreamVorbis {
+		t.Fatal("expected vorbis stream")
+	}
+
+	mp3Path := filepath.Join(t.TempDir(), "quality.mp3")
+	audio := append([]byte{0xFF, 0xFB, 0x90, 0x64}, bytes.Repeat([]byte{0}, 2000)...)
+	if err := os.WriteFile(mp3Path, audio, 0600); err != nil {
+		t.Fatal(err)
+	}
+	quality, err := GetMP3Quality(mp3Path)
+	if err != nil || quality.SampleRate != 44100 || quality.Bitrate != 128000 {
+		t.Fatalf("MP3 quality = %#v/%v", quality, err)
+	}
+	if _, _, err := extractMP3CoverArt(filepath.Join(t.TempDir(), "missing.mp3")); err == nil {
+		t.Fatal("expected missing MP3 cover error")
+	}
+}
+
+func TestM4AMetadataAtomHelpers(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "tagged.m4a")
+	cover := []byte{0xFF, 0xD8, 0xFF, 0x00}
+	ilstPayload := []byte{}
+	ilstPayload = append(ilstPayload, buildM4ATextTag("\xa9nam", "M4A Title")...)
+	ilstPayload = append(ilstPayload, buildM4ATextTag("\xa9ART", "M4A Artist")...)
+	ilstPayload = append(ilstPayload, buildM4ATextTag("\xa9alb", "M4A Album")...)
+	ilstPayload = append(ilstPayload, buildM4ATextTag("aART", "Album Artist")...)
+	ilstPayload = append(ilstPayload, buildM4ATextTag("\xa9day", "2026")...)
+	ilstPayload = append(ilstPayload, buildM4ATextTag("\xa9gen", "Pop")...)
+	ilstPayload = append(ilstPayload, buildM4ATextTag("\xa9wrt", "Composer")...)
+	ilstPayload = append(ilstPayload, buildM4ATextTag("\xa9cmt", "[ti:Comment Lyrics]")...)
+	ilstPayload = append(ilstPayload, buildM4ATextTag("cprt", "Copyright")...)
+	ilstPayload = append(ilstPayload, buildM4ATextTag("\xa9lyr", "[00:00.00]M4A Lyrics")...)
+	ilstPayload = append(ilstPayload, buildM4AIndexTag("trkn", 3, 12)...)
+	ilstPayload = append(ilstPayload, buildM4AIndexTag("disk", 1, 2)...)
+	ilstPayload = append(ilstPayload, buildM4AFreeformAtom("ISRC", "USRC17607839")...)
+	ilstPayload = append(ilstPayload, buildM4AFreeformAtom("LABEL", "Label")...)
+	ilstPayload = append(ilstPayload, buildM4AFreeformAtom("REPLAYGAIN_TRACK_GAIN", "-6.50 dB")...)
+	ilstPayload = append(ilstPayload, buildM4AAtom("covr", buildM4AAtom("data", append([]byte{0, 0, 0, 13, 0, 0, 0, 0}, cover...)))...)
+	fileData := buildM4AFileWithIlst(ilstPayload, true)
+	if err := os.WriteFile(path, fileData, 0600); err != nil {
+		t.Fatal(err)
+	}
+
+	meta, err := ReadM4ATags(path)
+	if err != nil {
+		t.Fatalf("ReadM4ATags: %v", err)
+	}
+	if meta.Title != "M4A Title" || meta.Artist != "M4A Artist" || meta.TrackNumber != 3 || meta.TotalTracks != 12 || meta.ISRC != "USRC17607839" {
+		t.Fatalf("M4A metadata = %#v", meta)
+	}
+	if lyrics, err := extractLyricsFromM4A(path); err != nil || !strings.Contains(lyrics, "M4A Lyrics") {
+		t.Fatalf("extractLyricsFromM4A = %q/%v", lyrics, err)
+	}
+	if image, err := extractCoverFromM4A(path); err != nil || !bytes.Equal(image, cover) {
+		t.Fatalf("extractCoverFromM4A = %#v/%v", image, err)
+	}
+	if pathInfo, err := func() (m4aMetadataPath, error) {
+		f, err := os.Open(path)
+		if err != nil {
+			return m4aMetadataPath{}, err
+		}
+		defer f.Close()
+		info, _ := f.Stat()
+		return findM4AMetadataPath(f, info.Size())
+	}(); err != nil || pathInfo.udta == nil {
+		t.Fatalf("findM4AMetadataPath = %#v/%v", pathInfo, err)
+	}
+	if err := EditM4AReplayGain(path, map[string]string{"replaygain_track_gain": "-5.00 dB", "replaygain_track_peak": "0.98"}); err != nil {
+		t.Fatalf("EditM4AReplayGain: %v", err)
+	}
+	edited, err := ReadM4ATags(path)
+	if err != nil || edited.ReplayGainTrackGain != "-5.00 dB" || edited.ReplayGainTrackPeak != "0.98" {
+		t.Fatalf("edited M4A = %#v/%v", edited, err)
+	}
+
+	noUdtaPath := filepath.Join(dir, "noudta.m4a")
+	if err := os.WriteFile(noUdtaPath, buildM4AFileWithIlst(buildM4ATextTag("\xa9nam", "No Udta"), false), 0600); err != nil {
+		t.Fatal(err)
+	}
+	if meta, err := ReadM4ATags(noUdtaPath); err != nil || meta.Title != "No Udta" {
+		t.Fatalf("ReadM4ATags no udta = %#v/%v", meta, err)
+	}
+	if _, err := ReadM4ATags(filepath.Join(dir, "missing.m4a")); err == nil {
+		t.Fatal("expected missing M4A error")
+	}
+	emptyM4A := filepath.Join(dir, "empty.m4a")
+	if err := os.WriteFile(emptyM4A, buildM4AFileWithIlst(nil, true), 0600); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := ReadM4ATags(emptyM4A); err == nil {
+		t.Fatal("expected empty M4A tags error")
+	}
+	if _, err := extractCoverFromM4A(emptyM4A); err == nil {
+		t.Fatal("expected missing M4A cover error")
+	}
+	if _, err := extractLyricsFromM4A(emptyM4A); err == nil {
+		t.Fatal("expected missing M4A lyrics error")
+	}
+
+	sidecarAudio := filepath.Join(dir, "sidecar.mp3")
+	if err := os.WriteFile(sidecarAudio, []byte("audio"), 0600); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "sidecar.lrc"), []byte(" [00:00.00]Sidecar "), 0600); err != nil {
+		t.Fatal(err)
+	}
+	if lyrics, err := extractLyricsFromSidecarLRC(sidecarAudio); err != nil || !strings.Contains(lyrics, "Sidecar") {
+		t.Fatalf("sidecar lyrics = %q/%v", lyrics, err)
+	}
+	if !looksLikeEmbeddedLyrics("[ti:Song]") || !looksLikeEmbeddedLyrics("[00:00.00]Line\n[00:01.00]Next") || looksLikeEmbeddedLyrics("plain") {
+		t.Fatal("embedded lyric heuristic mismatch")
+	}
+	if formatIndexValue(3, 12) != "3/12" || formatIndexValue(3, 0) != "3" || formatIndexValue(0, 12) != "" {
+		t.Fatal("formatIndexValue mismatch")
+	}
+	if parsePositiveInt(" 42 ") != 42 || parsePositiveInt("bad") != 0 {
+		t.Fatal("parsePositiveInt mismatch")
+	}
+	if !hasMapKey(map[string]string{"x": "y"}, "x") {
+		t.Fatal("expected map key")
+	}
+	if _, ok := parseReplayGainDb("-6.50 dB"); !ok {
+		t.Fatal("expected ReplayGain dB parse")
+	}
+	if _, ok := parseReplayGainPeak("0.98"); !ok {
+		t.Fatal("expected ReplayGain peak parse")
+	}
+	if norm := buildITunNORMTag("-6.50 dB", "0.98"); norm == "" {
+		t.Fatal("expected iTunNORM")
+	}
+	if fields := collectM4AReplayGainFields(map[string]string{"replaygain_track_gain": "-6 dB", "replaygain_track_peak": "0.9"}); fields["iTunNORM"] == "" {
+		t.Fatalf("ReplayGain fields = %#v", fields)
+	}
+
+	qualityPath := filepath.Join(dir, "quality-alac.m4a")
+	mvhd := make([]byte, 20)
+	binary.BigEndian.PutUint32(mvhd[12:16], 1000)
+	binary.BigEndian.PutUint32(mvhd[16:20], 180000)
+	sampleEntry := make([]byte, 32)
+	copy(sampleEntry[0:4], "alac")
+	binary.BigEndian.PutUint16(sampleEntry[22:24], 24)
+	sampleEntry[28] = 0xAC
+	sampleEntry[29] = 0x44
+	alacConfig := make([]byte, 24)
+	alacConfig[5] = 24
+	binary.BigEndian.PutUint32(alacConfig[20:24], 44100)
+	alacEntryPayload := append(append([]byte{}, sampleEntry[4:]...), buildM4AAtom("alac", alacConfig)...)
+	qualityFile := append(buildM4AAtom("ftyp", []byte("M4A \x00\x00\x00\x00")), buildM4AAtom("moov", append(buildM4AAtom("mvhd", mvhd), buildM4AAtom("alac", alacEntryPayload)...))...)
+	if err := os.WriteFile(qualityPath, qualityFile, 0600); err != nil {
+		t.Fatal(err)
+	}
+	if quality, err := GetM4AQuality(qualityPath); err != nil || quality.BitDepth != 24 || quality.SampleRate != 44100 || quality.Duration != 180 {
+		t.Fatalf("GetM4AQuality = %#v/%v", quality, err)
+	}
+	if quality, err := GetAudioQuality(qualityPath); err != nil || quality.SampleRate != 44100 {
+		t.Fatalf("GetAudioQuality M4A = %#v/%v", quality, err)
+	}
+	aacQualityPath := filepath.Join(dir, "quality-aac.m4a")
+	copy(sampleEntry[0:4], "mp4a")
+	aacQualityFile := append(buildM4AAtom("ftyp", []byte("M4A \x00\x00\x00\x00")), buildM4AAtom("moov", append(buildM4AAtom("mvhd", mvhd), sampleEntry...))...)
+	if err := os.WriteFile(aacQualityPath, aacQualityFile, 0600); err != nil {
+		t.Fatal(err)
+	}
+	if quality, err := GetM4AQuality(aacQualityPath); err != nil || quality.BitDepth != 0 || quality.SampleRate != 44100 || quality.Duration != 180 {
+		t.Fatalf("GetM4AQuality AAC = %#v/%v", quality, err)
+	}
+	eac3QualityPath := filepath.Join(dir, "quality-eac3.m4a")
+	zeroMvhd := make([]byte, 20)
+	eac3SampleEntry := make([]byte, 32)
+	copy(eac3SampleEntry[0:4], "ec-3")
+	eac3SampleEntry[28] = 0xBB
+	eac3SampleEntry[29] = 0x80
+	mdhd := make([]byte, 20)
+	binary.BigEndian.PutUint32(mdhd[12:16], 48000)
+	binary.BigEndian.PutUint32(mdhd[16:20], 48000*123)
+	eac3QualityFile := append(
+		buildM4AAtom("ftyp", []byte("M4A \x00\x00\x00\x00")),
+		buildM4AAtom("moov", append(
+			append(buildM4AAtom("mvhd", zeroMvhd), buildM4AAtom("trak", buildM4AAtom("mdia", buildM4AAtom("mdhd", mdhd)))...),
+			eac3SampleEntry...,
+		))...,
+	)
+	if err := os.WriteFile(eac3QualityPath, eac3QualityFile, 0600); err != nil {
+		t.Fatal(err)
+	}
+	if quality, err := GetM4AQuality(eac3QualityPath); err != nil || quality.Codec != "eac3" || quality.Duration != 123 {
+		t.Fatalf("GetM4AQuality EAC3 mdhd fallback = %#v/%v", quality, err)
+	}
+	if _, _, ok := parseALACSpecificConfig(make([]byte, 4)); ok {
+		t.Fatal("short ALAC config should not parse")
+	}
+	alac := make([]byte, 24)
+	alac[5] = 16
+	binary.BigEndian.PutUint32(alac[20:24], 48000)
+	if depth, rate, ok := parseALACSpecificConfig(alac); !ok || depth != 16 || rate != 48000 {
+		t.Fatalf("ALAC config = %d/%d/%v", depth, rate, ok)
+	}
+}
+
+func TestOggMetadataQualityAndCoverHelpers(t *testing.T) {
+	dir := t.TempDir()
+	opusHead := make([]byte, 19)
+	copy(opusHead[0:8], "OpusHead")
+	binary.LittleEndian.PutUint16(opusHead[10:12], 312)
+	binary.LittleEndian.PutUint32(opusHead[12:16], 48000)
+
+	var comments bytes.Buffer
+	binary.Write(&comments, binary.LittleEndian, uint32(6))
+	comments.WriteString("vendor")
+	entries := []string{
+		"TITLE=Ogg Title",
+		"ARTIST=Artist",
+		"ALBUMARTIST=Album Artist",
+		"TRACKNUMBER=2/9",
+		"DISCNUMBER=1/2",
+		"LYRICS=[00:00.00]Ogg Lyrics",
+	}
+	binary.Write(&comments, binary.LittleEndian, uint32(len(entries)))
+	for _, entry := range entries {
+		binary.Write(&comments, binary.LittleEndian, uint32(len(entry)))
+		comments.WriteString(entry)
+	}
+	opusTags := append([]byte("OpusTags"), comments.Bytes()...)
+	oggPath := filepath.Join(dir, "tagged.opus")
+	oggData := append(buildOggPage(0x02, 0, opusHead), buildOggPage(0x00, 48000+312, opusTags)...)
+	if err := os.WriteFile(oggPath, oggData, 0600); err != nil {
+		t.Fatal(err)
+	}
+	quality, err := GetOggQuality(oggPath)
+	if err != nil || quality.SampleRate != 48000 || quality.Duration != 1 {
+		t.Fatalf("GetOggQuality = %#v/%v", quality, err)
+	}
+	meta, err := ReadOggVorbisComments(oggPath)
+	if err != nil || meta.Title != "Ogg Title" || meta.TrackNumber != 2 || meta.TotalTracks != 9 {
+		t.Fatalf("ReadOggVorbisComments = %#v/%v", meta, err)
+	}
+
+	picture := buildTestFLACPictureBlock([]byte{0x89, 0x50, 0x4E, 0x47}, "image/png")
+	pictureComment := "METADATA_BLOCK_PICTURE=" + base64.StdEncoding.EncodeToString(picture)
+	var coverComments bytes.Buffer
+	binary.Write(&coverComments, binary.LittleEndian, uint32(6))
+	coverComments.WriteString("vendor")
+	binary.Write(&coverComments, binary.LittleEndian, uint32(1))
+	binary.Write(&coverComments, binary.LittleEndian, uint32(len(pictureComment)))
+	coverComments.WriteString(pictureComment)
+	coverPath := filepath.Join(dir, "cover.opus")
+	coverData := append(buildOggPage(0x02, 0, opusHead), buildOggPage(0x00, 48000+312, append([]byte("OpusTags"), coverComments.Bytes()...))...)
+	if err := os.WriteFile(coverPath, coverData, 0600); err != nil {
+		t.Fatal(err)
+	}
+	if image, mime, err := extractOggCoverArt(coverPath); err != nil || mime != "image/png" || len(image) == 0 {
+		t.Fatalf("extractOggCoverArt = %s/%#v/%v", mime, image, err)
+	}
+	if image, mime, err := extractAnyCoverArtWithHint(coverPath, "cover.opus"); err != nil || mime != "image/png" || len(image) == 0 {
+		t.Fatalf("extractAnyCoverArtWithHint = %s/%#v/%v", mime, image, err)
+	}
+	if image, mime, err := extractAnyCoverArt(coverPath); err != nil || mime != "image/png" || len(image) == 0 {
+		t.Fatalf("extractAnyCoverArt = %s/%#v/%v", mime, image, err)
+	}
+	extractedCoverPath := filepath.Join(dir, "extracted.png")
+	if err := ExtractCoverToFile(coverPath, extractedCoverPath); err != nil {
+		t.Fatalf("ExtractCoverToFile = %v", err)
+	}
+	if data := mustReadFile(t, extractedCoverPath); len(data) == 0 {
+		t.Fatal("expected extracted cover data")
+	}
+	cachePath, err := SaveCoverToCacheWithHintAndKey(coverPath, "cover.opus", dir, "key")
+	if err != nil || cachePath == "" {
+		t.Fatalf("SaveCoverToCacheWithHintAndKey = %q/%v", cachePath, err)
+	}
+	cacheDir := filepath.Join(dir, "cache")
+	if path, err := SaveCoverToCache(coverPath, cacheDir); err != nil || !strings.HasSuffix(path, ".png") {
+		t.Fatalf("SaveCoverToCache = %q/%v", path, err)
+	}
+	if path, err := SaveCoverToCacheWithHint(coverPath, "cover.opus", cacheDir); err != nil || path == "" {
+		t.Fatalf("SaveCoverToCacheWithHint = %q/%v", path, err)
+	}
+	hitPath, err := SaveCoverToCache(coverPath, cacheDir)
+	if err != nil || hitPath == "" {
+		t.Fatalf("SaveCoverToCache cache hit = %q/%v", hitPath, err)
+	}
+	if _, err := SaveCoverToCacheWithHintAndKey(filepath.Join(dir, "missing.opus"), "missing.opus", dir, "missing"); err == nil {
+		t.Fatal("expected missing cover cache error")
+	}
+
+	badPath := filepath.Join(dir, "bad.ogg")
+	if err := os.WriteFile(badPath, []byte("bad"), 0600); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := GetOggQuality(badPath); err == nil {
+		t.Fatal("expected invalid Ogg quality error")
+	}
+}
+
+func buildM4ADataPayload(payload []byte) []byte {
+	return append([]byte{0, 0, 0, 1, 0, 0, 0, 0}, payload...)
+}
+
+func buildM4ATextTag(atomType, value string) []byte {
+	return buildM4AAtom(atomType, buildM4AAtom("data", buildM4ADataPayload([]byte(value))))
+}
+
+func buildM4AIndexTag(atomType string, number, total int) []byte {
+	payload := []byte{0, 0, 0, byte(number), 0, byte(total), 0, 0}
+	return buildM4AAtom(atomType, buildM4AAtom("data", buildM4ADataPayload(payload)))
+}
+
+func buildM4AFileWithIlst(ilstPayload []byte, withUdta bool) []byte {
+	ilst := buildM4AAtom("ilst", ilstPayload)
+	meta := buildM4AAtom("meta", append([]byte{0, 0, 0, 0}, ilst...))
+	moovPayload := meta
+	if withUdta {
+		moovPayload = buildM4AAtom("udta", meta)
+	}
+	return append(buildM4AAtom("ftyp", []byte("M4A \x00\x00\x00\x00")), buildM4AAtom("moov", moovPayload)...)
+}
+
+func buildOggPage(headerType byte, granule uint64, packet []byte) []byte {
+	header := make([]byte, 27)
+	copy(header[0:4], "OggS")
+	header[4] = 0
+	header[5] = headerType
+	binary.LittleEndian.PutUint64(header[6:14], granule)
+	header[26] = 1
+	return append(append(header, byte(len(packet))), packet...)
+}
+
+func buildTestFLACPictureBlock(image []byte, mime string) []byte {
+	var picture bytes.Buffer
+	binary.Write(&picture, binary.BigEndian, uint32(3))
+	binary.Write(&picture, binary.BigEndian, uint32(len(mime)))
+	picture.WriteString(mime)
+	binary.Write(&picture, binary.BigEndian, uint32(0))
+	binary.Write(&picture, binary.BigEndian, uint32(1))
+	binary.Write(&picture, binary.BigEndian, uint32(1))
+	binary.Write(&picture, binary.BigEndian, uint32(32))
+	binary.Write(&picture, binary.BigEndian, uint32(0))
+	binary.Write(&picture, binary.BigEndian, uint32(len(image)))
+	picture.Write(image)
+	return picture.Bytes()
+}
@@ -0,0 +1,182 @@
+package gobackend
+
+import (
+	"context"
+	"errors"
+	"sync"
+)
+
+// ErrDownloadCancelled is returned when a download is cancelled by the user.
+var ErrDownloadCancelled = errors.New("download cancelled")
+
+// ErrExtensionRequestCancelled is returned when a UI-driven extension request
+// is superseded by a newer home/search request.
+var ErrExtensionRequestCancelled = errors.New("extension request cancelled")
+
+type cancelEntry struct {
+	ctx      context.Context
+	cancel   context.CancelFunc
+	canceled bool
+	refs     int
+}
+
+var (
+	cancelMu  sync.Mutex
+	cancelMap = make(map[string]*cancelEntry)
+
+	extensionRequestCancelMu  sync.Mutex
+	extensionRequestCancelMap = make(map[string]*cancelEntry)
+)
+
+func initDownloadCancel(itemID string) context.Context {
+	if itemID == "" {
+		return context.Background()
+	}
+
+	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()
+			}
+		}
+		entry.refs++
+		return entry.ctx
+	}
+
+	ctx, cancel := context.WithCancel(context.Background())
+	cancelMap[itemID] = &cancelEntry{
+		ctx:      ctx,
+		cancel:   cancel,
+		canceled: false,
+		refs:     1,
+	}
+	return ctx
+}
+
+func cancelDownload(itemID string) {
+	if itemID == "" {
+		return
+	}
+
+	cancelMu.Lock()
+	entry, ok := cancelMap[itemID]
+	if ok {
+		entry.canceled = true
+		if entry.cancel != nil {
+			entry.cancel()
+		}
+	} else {
+		cancelMap[itemID] = &cancelEntry{canceled: true}
+	}
+	cancelMu.Unlock()
+
+	RemoveItemProgress(itemID)
+}
+
+func isDownloadCancelled(itemID string) bool {
+	if itemID == "" {
+		return false
+	}
+
+	cancelMu.Lock()
+	entry, ok := cancelMap[itemID]
+	canceled := ok && entry.canceled
+	cancelMu.Unlock()
+	return canceled
+}
+
+func clearDownloadCancel(itemID string) {
+	if itemID == "" {
+		return
+	}
+
+	cancelMu.Lock()
+	if entry, ok := cancelMap[itemID]; ok {
+		entry.refs--
+		if entry.refs <= 0 {
+			delete(cancelMap, itemID)
+		}
+	}
+	cancelMu.Unlock()
+}
+
+func initExtensionRequestCancel(requestID string) context.Context {
+	if requestID == "" {
+		return context.Background()
+	}
+
+	extensionRequestCancelMu.Lock()
+	defer extensionRequestCancelMu.Unlock()
+
+	if entry, ok := extensionRequestCancelMap[requestID]; 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()
+			}
+		}
+		entry.refs++
+		return entry.ctx
+	}
+
+	ctx, cancel := context.WithCancel(context.Background())
+	extensionRequestCancelMap[requestID] = &cancelEntry{
+		ctx:      ctx,
+		cancel:   cancel,
+		canceled: false,
+		refs:     1,
+	}
+	return ctx
+}
+
+func cancelExtensionRequest(requestID string) {
+	if requestID == "" {
+		return
+	}
+
+	extensionRequestCancelMu.Lock()
+	if entry, ok := extensionRequestCancelMap[requestID]; ok {
+		entry.canceled = true
+		if entry.cancel != nil {
+			entry.cancel()
+		}
+	} else {
+		extensionRequestCancelMap[requestID] = &cancelEntry{canceled: true}
+	}
+	extensionRequestCancelMu.Unlock()
+}
+
+func isExtensionRequestCancelled(requestID string) bool {
+	if requestID == "" {
+		return false
+	}
+
+	extensionRequestCancelMu.Lock()
+	entry, ok := extensionRequestCancelMap[requestID]
+	canceled := ok && entry.canceled
+	extensionRequestCancelMu.Unlock()
+	return canceled
+}
+
+func clearExtensionRequestCancel(requestID string) {
+	if requestID == "" {
+		return
+	}
+
+	extensionRequestCancelMu.Lock()
+	if entry, ok := extensionRequestCancelMap[requestID]; ok {
+		entry.refs--
+		if entry.refs <= 0 {
+			delete(extensionRequestCancelMap, requestID)
+		}
+	}
+	extensionRequestCancelMu.Unlock()
+}
@@ -4,36 +4,56 @@ import (
 	"fmt"
 	"io"
 	"net/http"
+	"regexp"
 	"strings"
 )

-// Spotify image size codes (same as PC version)
 const (
-	spotifySize640 = "ab67616d0000b273" // 640x640
-	spotifySizeMax = "ab67616d000082c1" // Max resolution (~2000x2000)
+	spotifySize300 = "ab67616d00001e02"
+	spotifySize640 = "ab67616d0000b273"
+	spotifySizeMax = "ab67616d000082c1"
 )

-// downloadCoverToMemory downloads cover art and returns as bytes (no file creation)
-// This avoids file permission issues on Android
+// 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$`)
+
+var qobuzSizeRegex = regexp.MustCompile(`_\d+\.jpg$`)
+
+func convertSmallToMedium(imageURL string) string {
+	if strings.Contains(imageURL, spotifySize300) {
+		return strings.Replace(imageURL, spotifySize300, spotifySize640, 1)
+	}
+	return imageURL
+}
+
 func downloadCoverToMemory(coverURL string, maxQuality bool) ([]byte, error) {
 	if coverURL == "" {
 		return nil, fmt.Errorf("no cover URL provided")
 	}

-	fmt.Printf("[Cover] Downloading cover from: %s\n", coverURL)
+	GoLog("[Cover] Original URL: %s", coverURL)
+
+	downloadURL := convertSmallToMedium(coverURL)
+	if downloadURL != coverURL {
+		GoLog("[Cover] Upgraded 300x300 → 640x640")
+	}

-	// Upgrade to max quality if requested
-	downloadURL := coverURL
 	if maxQuality {
-		downloadURL = upgradeToMaxQuality(coverURL)
-		if downloadURL != coverURL {
-			fmt.Printf("[Cover] Upgraded to max quality URL: %s\n", downloadURL)
+		maxURL := upgradeToMaxQuality(downloadURL)
+		if maxURL != downloadURL {
+			downloadURL = maxURL
+			if strings.Contains(coverURL, "scdn.co") || strings.Contains(coverURL, "spotifycdn") {
+				GoLog("[Cover] Spotify: upgraded to max resolution (~2000x2000)")
+			}
 		}
 	}

+	GoLog("[Cover] Final URL: %s", downloadURL)
+
 	client := NewHTTPClientWithTimeout(DefaultTimeout)

-	// Create request with User-Agent (required by Spotify CDN)
 	req, err := http.NewRequest("GET", downloadURL, nil)
 	if err != nil {
 		return nil, fmt.Errorf("failed to create request: %w", err)
@@ -54,48 +74,86 @@ func downloadCoverToMemory(coverURL string, maxQuality bool) ([]byte, error) {
 		return nil, fmt.Errorf("failed to read cover data: %w", err)
 	}

-	fmt.Printf("[Cover] Downloaded %d bytes\n", len(data))
+	sizeKB := len(data) / 1024
+	var resolution string
+	if sizeKB > 200 {
+		resolution = "~2000x2000 (hi-res)"
+	} else if sizeKB > 50 {
+		resolution = "~640x640"
+	} else {
+		resolution = "~300x300"
+	}
+	GoLog("[Cover] Downloaded %d KB (%s)", sizeKB, resolution)
+
 	return data, nil
 }

-// upgradeToMaxQuality upgrades Spotify cover URL to maximum quality
-// Uses same logic as PC version - replaces 640x640 size code with max resolution
 func upgradeToMaxQuality(coverURL string) string {
-	// Spotify image URLs can be upgraded by changing the size parameter
-	// Format: https://i.scdn.co/image/ab67616d0000b273...
-	// ab67616d0000b273 = 640x640
-	// ab67616d000082c1 = Max resolution (~2000x2000)
-
 	if strings.Contains(coverURL, spotifySize640) {
-		// Try max resolution first
-		maxURL := strings.Replace(coverURL, spotifySize640, spotifySizeMax, 1)
+		return strings.Replace(coverURL, spotifySize640, spotifySizeMax, 1)
+	}

-		// Verify max resolution URL is available
-		client := NewHTTPClientWithTimeout(DefaultTimeout)
-		req, err := http.NewRequest("HEAD", maxURL, nil)
-		if err == nil {
-			resp, err := DoRequestWithUserAgent(client, req)
-			if err == nil {
-				resp.Body.Close()
-				if resp.StatusCode == http.StatusOK {
-					return maxURL
-				}
-			}
-		}
+	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
 }

-// GetCoverFromSpotify gets cover URL from Spotify metadata
+func upgradeDeezerCover(coverURL string) string {
+	if !strings.Contains(coverURL, "cdn-images.dzcdn.net") {
+		return coverURL
+	}
+
+	upgraded := deezerSizeRegex.ReplaceAllString(coverURL, "/1800x1800-000000-80-0-0.jpg")
+	if upgraded != coverURL {
+		GoLog("[Cover] Deezer: upgraded to 1800x1800")
+	}
+	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 := qobuzSizeRegex.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 ""
 	}

+	result := convertSmallToMedium(imageURL)
+
 	if maxQuality {
-		return upgradeToMaxQuality(imageURL)
+		result = upgradeToMaxQuality(result)
 	}

-	return imageURL
+	return result
 }
@@ -0,0 +1,401 @@
+package gobackend
+
+import (
+	"archive/zip"
+	"bytes"
+	"encoding/binary"
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func newTestLoadedExtension(t *testing.T, types ...ExtensionType) *loadedExtension {
+	t.Helper()
+	dir := t.TempDir()
+	if err := os.WriteFile(filepath.Join(dir, "index.js"), []byte(testExtensionJS), 0600); err != nil {
+		t.Fatalf("write index.js: %v", err)
+	}
+	return &loadedExtension{
+		ID: "coverage-ext",
+		Manifest: &ExtensionManifest{
+			Name:        "coverage-ext",
+			Description: "Coverage extension",
+			Version:     "1.0.0",
+			Types:       types,
+			Permissions: ExtensionPermissions{File: true, Network: []string{"example.test"}},
+			SearchBehavior: &SearchBehaviorConfig{
+				Enabled:     true,
+				Placeholder: "Search coverage",
+				Primary:     true,
+				Icon:        "search",
+			},
+			URLHandler:    &URLHandlerConfig{Enabled: true, Patterns: []string{"https://example.test/"}},
+			TrackMatching: &TrackMatchingConfig{CustomMatching: true},
+			PostProcessing: &PostProcessingConfig{
+				Enabled: true,
+				Hooks:   []PostProcessingHook{{ID: "hook", Name: "Hook", DefaultEnabled: true, SupportedFormats: []string{"flac"}}},
+			},
+		},
+		Enabled:   true,
+		SourceDir: dir,
+		DataDir:   t.TempDir(),
+	}
+}
+
+const testExtensionJS = `
+function track(id) {
+  return {
+    id: id,
+    name: "Track " + id,
+    artists: "Artist",
+    albumName: "Album",
+    albumArtist: "Album Artist",
+    durationMs: 180000,
+    coverUrl: "https://example.test/cover.jpg",
+    releaseDate: "2026-05-04",
+    trackNumber: 1,
+    totalTracks: 10,
+    discNumber: 1,
+    totalDiscs: 1,
+    isrc: "USRC17607839",
+    itemType: "track",
+    albumType: "album",
+    tidalId: "tidal-1",
+    qobuzId: "qobuz-1",
+    deezerId: "deezer-1",
+    spotifyId: "spotify:track:1",
+    externalLinks: { tidal: "https://tidal.example/1" },
+    label: "Label",
+    copyright: "Copyright",
+    genre: "Pop",
+    composer: "Composer",
+    audioQuality: "FLAC 24-bit",
+    audioModes: "DOLBY_ATMOS"
+  };
+}
+
+registerExtension({
+  searchTracks: function(query, limit) {
+    return { tracks: [track("search-1")], total: 1 };
+  },
+  customSearch: function(query, options) {
+    var t = track("custom-1");
+    t.name = "Custom " + query;
+    return [t];
+  },
+  getHomeFeed: function() {
+    return [{ id: "home-1", title: "Home", tracks: [track("home-track")] }];
+  },
+  getBrowseCategories: function() {
+    return [{ id: "cat-1", title: "Category" }];
+  },
+  getTrack: function(id) {
+    return track(id);
+  },
+  getAlbum: function(id) {
+    return {
+      id: id,
+      name: "Album " + id,
+      artists: "Artist",
+      artistId: "artist-1",
+      coverUrl: "https://example.test/album.jpg",
+      releaseDate: "2026-05-04",
+      totalTracks: 1,
+      albumType: "album",
+      tracks: [track("album-track")]
+    };
+  },
+  getPlaylist: function(id) {
+    return {
+      id: id,
+      name: "Playlist " + id,
+      artists: "Owner",
+      coverUrl: "https://example.test/playlist.jpg",
+      totalTracks: 1,
+      tracks: [track("playlist-track")]
+    };
+  },
+  getArtist: function(id) {
+    return {
+      id: id,
+      name: "Artist",
+      imageUrl: "https://example.test/artist.jpg",
+      headerImage: "https://example.test/header.jpg",
+      listeners: 123,
+      albums: [{ id: "album-1", name: "Album", artists: "Artist", totalTracks: 1 }],
+      releases: [{ id: "release-1", name: "Release", artists: "Artist", totalTracks: 1, tracks: [track("release-track")] }],
+      topTracks: [track("top-track")]
+    };
+  },
+  enrichTrack: function(input) {
+    var t = track(input.id || "enriched");
+    t.name = "Enriched";
+    return t;
+  },
+  checkAvailability: function(isrc, name, artist, ids) {
+    return { available: true, reason: "ok", trackId: "download-track", skipFallback: true };
+  },
+  getDownloadUrl: function(id, quality) {
+    return { url: "https://example.test/audio.flac", format: "flac", bitDepth: 24, sampleRate: 96000 };
+  },
+  download: function(id, quality, outputPath, onProgress) {
+    if (onProgress) onProgress(100);
+    return {
+      success: true,
+      filePath: "EXISTS:" + outputPath,
+      alreadyExists: false,
+      bitDepth: 24,
+      sampleRate: 96000,
+      title: "Downloaded",
+      artist: "Artist",
+      album: "Album",
+      albumArtist: "Album Artist",
+      trackNumber: 1,
+      totalTracks: 10,
+      discNumber: 1,
+      totalDiscs: 1,
+      releaseDate: "2026-05-04",
+      coverUrl: "https://example.test/cover.jpg",
+      isrc: "USRC17607839",
+      genre: "Pop",
+      label: "Label",
+      copyright: "Copyright",
+      composer: "Composer",
+      lyricsLrc: "[00:00.00]Hello",
+      decryptionKey: "001122",
+      decryption: { strategy: "mp4_decryption_key", options: { kid: "1" } }
+    };
+  },
+  fetchLyrics: function(name, artist, album, duration) {
+    return { syncType: "LINE_SYNCED", provider: "coverage-ext", lines: [{ startTimeMs: 0, endTimeMs: 1000, words: "Hello" }] };
+  },
+  handleUrl: function(url) {
+    return { type: "track", name: "Handled", coverUrl: "https://example.test/cover.jpg", track: track("url-track"), tracks: [track("url-track")], album: this.getAlbum("url-album"), artist: this.getArtist("url-artist") };
+  },
+  matchTrack: function(req) {
+    return { matched: true, trackId: "download-track", confidence: 0.95, reason: "exact" };
+  },
+  postProcess: function(path, req) {
+    return { success: true, newFilePath: path, bitDepth: 24, sampleRate: 96000 };
+  },
+  postProcessV2: function(input, metadata, hookId) {
+    return { success: true, newFilePath: input.path || input.uri, newFileUri: input.uri || "", bitDepth: 24, sampleRate: 96000 };
+  }
+});
+`
+
+func mustReadFile(t *testing.T, path string) []byte {
+	t.Helper()
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("read file: %v", err)
+	}
+	return data
+}
+
+func buildID3v23Tag(frames ...[]byte) []byte {
+	body := bytes.Join(frames, nil)
+	header := []byte{'I', 'D', '3', 3, 0, 0, 0, 0, 0, 0}
+	copy(header[6:10], syncsafeBytes(len(body)))
+	return append(header, body...)
+}
+
+func id3TextFrame(id, value string) []byte {
+	return id3v23Frame(id, append([]byte{3}, []byte(value)...))
+}
+
+func id3CommentFrame(id, value string) []byte {
+	payload := append([]byte{3, 'e', 'n', 'g', 0}, []byte(value)...)
+	return id3v23Frame(id, payload)
+}
+
+func id3UserTextFrame(id, desc, value string) []byte {
+	payload := append([]byte{3}, []byte(desc)...)
+	payload = append(payload, 0)
+	payload = append(payload, []byte(value)...)
+	return id3v23Frame(id, payload)
+}
+
+func id3v23Frame(id string, payload []byte) []byte {
+	frame := make([]byte, 10+len(payload))
+	copy(frame[0:4], id)
+	binary.BigEndian.PutUint32(frame[4:8], uint32(len(payload)))
+	copy(frame[10:], payload)
+	return frame
+}
+
+func buildID3v22Tag(frames ...[]byte) []byte {
+	body := bytes.Join(frames, nil)
+	header := []byte{'I', 'D', '3', 2, 0, 0, 0, 0, 0, 0}
+	copy(header[6:10], syncsafeBytes(len(body)))
+	return append(header, body...)
+}
+
+func id3v22TextFrame(id, value string) []byte {
+	return id3v22Frame(id, append([]byte{3}, []byte(value)...))
+}
+
+func id3v22CommentFrame(id, value string) []byte {
+	payload := append([]byte{3, 'e', 'n', 'g', 0}, []byte(value)...)
+	return id3v22Frame(id, payload)
+}
+
+func id3v22Frame(id string, payload []byte) []byte {
+	frame := make([]byte, 6+len(payload))
+	copy(frame[0:3], id)
+	size := len(payload)
+	frame[3] = byte(size >> 16)
+	frame[4] = byte(size >> 8)
+	frame[5] = byte(size)
+	copy(frame[6:], payload)
+	return frame
+}
+
+func syncsafeBytes(size int) []byte {
+	return []byte{
+		byte((size >> 21) & 0x7f),
+		byte((size >> 14) & 0x7f),
+		byte((size >> 7) & 0x7f),
+		byte(size & 0x7f),
+	}
+}
+
+func buildID3v1Tag(title, artist, album, year string, track, genre byte) []byte {
+	tag := make([]byte, 128)
+	copy(tag[0:3], "TAG")
+	copyPadded(tag[3:33], title)
+	copyPadded(tag[33:63], artist)
+	copyPadded(tag[63:93], album)
+	copyPadded(tag[93:97], year)
+	tag[125] = 0
+	tag[126] = track
+	tag[127] = genre
+	return tag
+}
+
+func copyPadded(dst []byte, value string) {
+	for i := range dst {
+		dst[i] = ' '
+	}
+	copy(dst, value)
+}
+
+func writeExportCueFixture(t *testing.T, dir string) (string, string) {
+	t.Helper()
+	audioPath := filepath.Join(dir, "exports.wav")
+	if err := os.WriteFile(audioPath, []byte("audio"), 0600); err != nil {
+		t.Fatalf("write export audio: %v", err)
+	}
+	cuePath := filepath.Join(dir, "exports.cue")
+	cue := "PERFORMER \"Artist\"\nTITLE \"Album\"\nFILE \"exports.wav\" WAVE\n  TRACK 01 AUDIO\n    TITLE \"Song\"\n    INDEX 01 00:00:00\n"
+	if err := os.WriteFile(cuePath, []byte(cue), 0600); err != nil {
+		t.Fatalf("write export cue: %v", err)
+	}
+	return cuePath, audioPath
+}
+
+func escapeJSONPath(path string) string {
+	data, _ := json.Marshal(path)
+	return strings.Trim(string(data), `"`)
+}
+
+func fakeDeezerResponse(path, rawQuery string) string {
+	switch {
+	case path == "/2.0/search/track":
+		if strings.Contains(rawQuery, "MISSING") {
+			return `{"data":[]}`
+		}
+		return `{"data":[` + fakeDeezerTrackJSON(101, true) + `]}`
+	case path == "/2.0/search/artist":
+		return `{"data":[{"id":301,"name":"Artist","picture_xl":"artist-xl","nb_fan":123}]}`
+	case path == "/2.0/search/album":
+		return `{"data":[{"id":201,"title":"Album","cover_xl":"album-xl","nb_tracks":2,"release_date":"2026-05-04","record_type":"compile","artist":{"id":301,"name":"Artist"}}]}`
+	case path == "/2.0/search/playlist":
+		return `{"data":[{"id":401,"title":"Playlist","picture_xl":"playlist-xl","nb_tracks":2,"user":{"name":"Owner"}}]}`
+	case path == "/2.0/track/101", path == "/2.0/track/isrc:USRC17607839":
+		return fakeDeezerTrackJSON(101, true)
+	case path == "/2.0/track/102":
+		return fakeDeezerTrackJSON(102, true)
+	case path == "/2.0/track/isrc:MISSING":
+		return `{"id":0}`
+	case path == "/2.0/album/201":
+		return `{"id":201,"title":"Album","cover_xl":"album-xl","release_date":"2026-05-04","nb_tracks":2,"record_type":"compile","label":"Label","copyright":"Copyright","genres":{"data":[{"name":"Pop"},{"name":"Dance"}]},"artist":{"id":301,"name":"Album Artist"},"contributors":[{"name":"Contributor A"},{"name":"Contributor B"}],"tracks":{"data":[` + fakeDeezerTrackJSON(101, true) + `,` + fakeDeezerTrackJSON(102, false) + `]}}`
+	case path == "/2.0/artist/301":
+		return `{"id":301,"name":"Artist","picture_xl":"artist-xl","nb_fan":123,"nb_album":1}`
+	case path == "/2.0/artist/301/albums":
+		return `{"data":[{"id":201,"title":"Album","release_date":"2026-05-04","nb_tracks":0,"cover_xl":"album-xl","record_type":"compile"}]}`
+	case path == "/2.0/artist/301/related":
+		return `{"data":[{"id":302,"name":"Related","picture_xl":"related-xl","nb_fan":10}]}`
+	case path == "/2.0/playlist/401":
+		return `{"id":401,"title":"Playlist","picture_xl":"playlist-xl","nb_tracks":2,"creator":{"name":"Owner"},"tracks":{"data":[` + fakeDeezerTrackJSON(101, true) + `,` + fakeDeezerTrackJSON(102, false) + `]}}`
+	default:
+		return ""
+	}
+}
+
+func fakeDeezerTrackJSON(id int, withISRC bool) string {
+	isrc := ""
+	if withISRC {
+		isrc = `,"isrc":"USRC17607839"`
+		if id == 102 {
+			isrc = `,"isrc":"USRC17607840"`
+		}
+	}
+	return fmt.Sprintf(`{"id":%d,"title":"Track %d","duration":180,"track_position":%d,"disk_number":1%s,"link":"https://deezer.test/track/%d","release_date":"2026-05-04","artist":{"id":301,"name":"Artist"},"contributors":[{"name":"Contributor A"},{"name":"Contributor B"}],"album":{"id":201,"title":"Album","cover_xl":"album-xl","release_date":"2026-05-04","record_type":"album"}}`, id, id, id-100, isrc, id)
+}
+
+func createTestExtensionPackage(t *testing.T, path, name, version, js string, extraFiles map[string]string) {
+	t.Helper()
+	out, err := os.Create(path)
+	if err != nil {
+		t.Fatalf("create extension package: %v", err)
+	}
+	defer out.Close()
+
+	zw := zip.NewWriter(out)
+	defer zw.Close()
+
+	manifest := fmt.Sprintf(`{
+		"name": %q,
+		"displayName": %q,
+		"version": %q,
+		"description": "Packaged test extension",
+		"type": ["metadata_provider", "download_provider", "lyrics_provider"],
+		"permissions": {"network": ["example.test"], "storage": true, "file": true},
+		"icon": "icon.png",
+		"settings": [{"key":"quality","type":"string","label":"Quality"}],
+		"qualityOptions": [{"id":"lossless","label":"Lossless","description":"Lossless"}],
+		"searchBehavior": {"enabled": true, "placeholder": "Search", "primary": true},
+		"urlHandler": {"enabled": true, "patterns": ["https://example.test/"]},
+		"trackMatching": {"customMatching": true},
+		"postProcessing": {"enabled": true, "hooks": [{"id":"hook","name":"Hook"}]},
+		"serviceHealth": [{"id":"main","url":"https://example.test/health"}],
+		"capabilities": {"homeFeed": true}
+	}`, name, name, version)
+
+	for fileName, content := range map[string]string{
+		"manifest.json": manifest,
+		"index.js":      js,
+		"icon.png":      "png",
+	} {
+		writer, err := zw.Create(fileName)
+		if err != nil {
+			t.Fatalf("zip create %s: %v", fileName, err)
+		}
+		if _, err := writer.Write([]byte(content)); err != nil {
+			t.Fatalf("zip write %s: %v", fileName, err)
+		}
+	}
+	for fileName, content := range extraFiles {
+		writer, err := zw.Create(fileName)
+		if err != nil {
+			t.Fatalf("zip create extra %s: %v", fileName, err)
+		}
+		if _, err := writer.Write([]byte(content)); err != nil {
+			t.Fatalf("zip write extra %s: %v", fileName, err)
+		}
+	}
+}
@@ -0,0 +1,442 @@
+package gobackend
+
+import (
+	"encoding/json"
+	"sort"
+	"strings"
+	"sync"
+)
+
+type CrossExtensionShareResult struct {
+	ExtensionID string `json:"extension_id"`
+	DisplayName string `json:"display_name"`
+	Found       bool   `json:"found"`
+	URL         string `json:"url,omitempty"`
+	ItemName    string `json:"item_name,omitempty"`
+	ItemArtists string `json:"item_artists,omitempty"`
+	Error       string `json:"error,omitempty"`
+}
+
+var crossExtensionShareResultCache = struct {
+	sync.RWMutex
+	entries map[string]string
+	order   []string
+}{
+	entries: make(map[string]string),
+}
+
+const crossExtensionShareResultCacheLimit = 128
+
+func FindCollectionAcrossExtensionsJSON(requestJSON string) (string, error) {
+	var req struct {
+		Name              string `json:"name"`
+		Artists           string `json:"artists"`
+		Type              string `json:"type"`
+		SourceExtensionID string `json:"source_extension_id"`
+	}
+	if err := json.Unmarshal([]byte(requestJSON), &req); err != nil {
+		return "", err
+	}
+
+	req.Name = strings.TrimSpace(req.Name)
+	req.Artists = strings.TrimSpace(req.Artists)
+	req.Type = strings.ToLower(strings.TrimSpace(req.Type))
+	req.SourceExtensionID = strings.TrimSpace(req.SourceExtensionID)
+	if req.Name == "" {
+		return "[]", nil
+	}
+	if req.Type == "" {
+		req.Type = "album"
+	}
+
+	providers := getExtensionManager().GetMetadataProviders()
+	work := make([]*extensionProviderWrapper, 0, len(providers))
+	for _, provider := range providers {
+		if provider == nil || provider.extension == nil {
+			continue
+		}
+		if provider.extension.ID == req.SourceExtensionID {
+			continue
+		}
+		work = append(work, provider)
+	}
+	cacheKey := crossExtensionShareCacheKey(req.Name, req.Artists, req.Type, req.SourceExtensionID, work)
+	if cached := getCrossExtensionShareCache(cacheKey); cached != "" {
+		return cached, nil
+	}
+
+	query := req.Name
+	if req.Artists != "" {
+		query += " " + req.Artists
+	}
+
+	results := make([]CrossExtensionShareResult, len(work))
+	var wg sync.WaitGroup
+	for i, provider := range work {
+		wg.Add(1)
+		go func(index int, p *extensionProviderWrapper) {
+			defer wg.Done()
+			results[index] = findCollectionForExtension(
+				p,
+				req.Type,
+				req.Name,
+				req.Artists,
+				query,
+			)
+		}(i, provider)
+	}
+	wg.Wait()
+
+	data, err := json.Marshal(results)
+	if err != nil {
+		return "[]", err
+	}
+	response := string(data)
+	if crossExtensionShareResultsCacheable(results) {
+		setCrossExtensionShareCache(cacheKey, response)
+	}
+	return response, nil
+}
+
+func crossExtensionShareCacheKey(name string, artists string, itemType string, sourceExtensionID string, providers []*extensionProviderWrapper) string {
+	providerKeys := make([]string, 0, len(providers))
+	for _, provider := range providers {
+		if provider == nil || provider.extension == nil {
+			continue
+		}
+		ext := provider.extension
+		displayName := ""
+		if ext.Manifest != nil {
+			displayName = ext.Manifest.DisplayName
+		}
+		providerKeys = append(providerKeys, strings.Join([]string{
+			strings.TrimSpace(ext.ID),
+			strings.TrimSpace(displayName),
+			strings.TrimSpace(ext.SourceDir),
+		}, "\x1f"))
+	}
+	sort.Strings(providerKeys)
+
+	return strings.Join([]string{
+		normalizeLooseTitle(itemType),
+		normalizeLooseTitle(name),
+		normalizeLooseArtistName(artists),
+		strings.TrimSpace(sourceExtensionID),
+		strings.Join(providerKeys, "\x1e"),
+	}, "\x1d")
+}
+
+func getCrossExtensionShareCache(key string) string {
+	if key == "" {
+		return ""
+	}
+	crossExtensionShareResultCache.RLock()
+	defer crossExtensionShareResultCache.RUnlock()
+	return crossExtensionShareResultCache.entries[key]
+}
+
+func setCrossExtensionShareCache(key string, value string) {
+	if key == "" || value == "" {
+		return
+	}
+	crossExtensionShareResultCache.Lock()
+	defer crossExtensionShareResultCache.Unlock()
+
+	if _, exists := crossExtensionShareResultCache.entries[key]; !exists {
+		crossExtensionShareResultCache.order = append(crossExtensionShareResultCache.order, key)
+	}
+	crossExtensionShareResultCache.entries[key] = value
+
+	for len(crossExtensionShareResultCache.order) > crossExtensionShareResultCacheLimit {
+		oldest := crossExtensionShareResultCache.order[0]
+		crossExtensionShareResultCache.order = crossExtensionShareResultCache.order[1:]
+		delete(crossExtensionShareResultCache.entries, oldest)
+	}
+}
+
+func crossExtensionShareResultsCacheable(results []CrossExtensionShareResult) bool {
+	for _, result := range results {
+		if result.Found {
+			continue
+		}
+		errText := strings.ToLower(strings.TrimSpace(result.Error))
+		if errText == "" ||
+			errText == "no results" ||
+			errText == "unsupported collection type" ||
+			strings.HasSuffix(errText, " not found") ||
+			strings.Contains(errText, "found without shareable link") {
+			continue
+		}
+		return false
+	}
+	return true
+}
+
+func findCollectionForExtension(
+	provider *extensionProviderWrapper,
+	itemType string,
+	name string,
+	artists string,
+	query string,
+) CrossExtensionShareResult {
+	result := CrossExtensionShareResult{
+		ExtensionID: provider.extension.ID,
+	}
+	if provider.extension.Manifest != nil {
+		result.DisplayName = provider.extension.Manifest.DisplayName
+	}
+	if result.DisplayName == "" {
+		result.DisplayName = provider.extension.ID
+	}
+
+	searchResult, err := searchCollectionCandidates(provider, itemType, query)
+	if err != nil {
+		result.Error = err.Error()
+		return result
+	}
+	if searchResult == nil || len(searchResult.Tracks) == 0 {
+		result.Error = "no results"
+		return result
+	}
+
+	var best *ExtTrackMetadata
+	switch itemType {
+	case "artist":
+		best = bestArtistTrack(searchResult.Tracks, name)
+	case "album":
+		best = bestAlbumTrack(searchResult.Tracks, name, artists)
+	default:
+		result.Error = "unsupported collection type"
+		return result
+	}
+	if best == nil {
+		result.Error = itemType + " not found"
+		return result
+	}
+
+	url := resolveCollectionShareURL(provider.extension, itemType, best)
+	if url == "" {
+		result.Error = itemType + " found without shareable link"
+		return result
+	}
+
+	result.Found = true
+	result.URL = url
+	if itemType == "artist" {
+		result.ItemName = collectionArtistName(*best)
+	} else {
+		result.ItemName = collectionAlbumName(*best)
+		result.ItemArtists = best.Artists
+	}
+	return result
+}
+
+func searchCollectionCandidates(provider *extensionProviderWrapper, itemType string, query string) (*ExtSearchResult, error) {
+	filter := ""
+	switch itemType {
+	case "album":
+		filter = "albums"
+	case "artist":
+		filter = "artists"
+	}
+
+	if filter != "" {
+		tracks, err := provider.CustomSearch(query, map[string]interface{}{
+			"filter": filter,
+			"limit":  10,
+		})
+		if err == nil && len(tracks) > 0 {
+			return &ExtSearchResult{Tracks: tracks, Total: len(tracks)}, nil
+		}
+	}
+
+	return provider.SearchTracks(query, 10)
+}
+
+func bestAlbumTrack(tracks []ExtTrackMetadata, albumName string, artists string) *ExtTrackMetadata {
+	targetAlbum := normalizeLooseTitle(albumName)
+	targetArtists := normalizeLooseArtistName(artists)
+	bestScore := 0
+	bestIndex := -1
+
+	for i := range tracks {
+		track := tracks[i]
+		album := normalizeLooseTitle(collectionAlbumName(track))
+		trackArtists := normalizeLooseArtistName(track.Artists + " " + track.AlbumArtist)
+
+		score := 0
+		if isCollectionItemType(track, "album") {
+			score += 25
+		}
+		if album == targetAlbum {
+			score += 100
+		} else if album != "" && targetAlbum != "" && (strings.Contains(album, targetAlbum) || strings.Contains(targetAlbum, album)) {
+			score += 50
+		}
+		if targetArtists != "" && (strings.Contains(trackArtists, targetArtists) || strings.Contains(targetArtists, trackArtists)) {
+			score += 30
+		}
+		if score > bestScore {
+			bestScore = score
+			bestIndex = i
+		}
+	}
+
+	if bestIndex < 0 || bestScore < 50 {
+		return nil
+	}
+	return &tracks[bestIndex]
+}
+
+func bestArtistTrack(tracks []ExtTrackMetadata, artistName string) *ExtTrackMetadata {
+	targetArtist := normalizeLooseArtistName(artistName)
+	bestScore := 0
+	bestIndex := -1
+
+	for i := range tracks {
+		artist := normalizeLooseArtistName(collectionArtistName(tracks[i]))
+		score := 0
+		if isCollectionItemType(tracks[i], "artist") {
+			score += 25
+		}
+		if artist == targetArtist {
+			score += 100
+		} else if artist != "" && targetArtist != "" && (strings.Contains(artist, targetArtist) || strings.Contains(targetArtist, artist)) {
+			score += 60
+		}
+		if score > bestScore {
+			bestScore = score
+			bestIndex = i
+		}
+	}
+
+	if bestIndex < 0 || bestScore < 60 {
+		return nil
+	}
+	return &tracks[bestIndex]
+}
+
+func resolveCollectionShareURL(ext *loadedExtension, itemType string, track *ExtTrackMetadata) string {
+	if track == nil {
+		return ""
+	}
+
+	if itemType == "album" {
+		if isCollectionItemType(*track, "album") {
+			if url := normalizeShareURL(track.ExternalURL); url != "" {
+				return url
+			}
+		}
+		if url := normalizeShareURL(track.AlbumURL); url != "" {
+			return url
+		}
+		if url := urlFromExternalLinks(track.ExternalLinks, "album"); url != "" {
+			return url
+		}
+		if url := templateShareURL(ext, "album", firstNonEmptyString(track.AlbumID, collectionID(*track, "album"), track.AlbumURL)); url != "" {
+			return url
+		}
+		return ""
+	}
+
+	if isCollectionItemType(*track, "artist") {
+		if url := normalizeShareURL(track.ExternalURL); url != "" {
+			return url
+		}
+	}
+	if url := normalizeShareURL(track.ArtistURL); url != "" {
+		return url
+	}
+	if url := urlFromExternalLinks(track.ExternalLinks, "artist"); url != "" {
+		return url
+	}
+	if url := templateShareURL(ext, "artist", firstNonEmptyString(track.ArtistID, collectionID(*track, "artist"))); url != "" {
+		return url
+	}
+	return ""
+}
+
+func collectionAlbumName(track ExtTrackMetadata) string {
+	if isCollectionItemType(track, "album") {
+		return track.Name
+	}
+	return track.AlbumName
+}
+
+func collectionArtistName(track ExtTrackMetadata) string {
+	if isCollectionItemType(track, "artist") {
+		return track.Name
+	}
+	return track.Artists
+}
+
+func collectionID(track ExtTrackMetadata, itemType string) string {
+	if isCollectionItemType(track, itemType) {
+		return track.ID
+	}
+	return ""
+}
+
+func isCollectionItemType(track ExtTrackMetadata, itemType string) bool {
+	return strings.EqualFold(strings.TrimSpace(track.ItemType), itemType)
+}
+
+func normalizeShareURL(value string) string {
+	trimmed := strings.TrimSpace(value)
+	if strings.HasPrefix(trimmed, "http://") || strings.HasPrefix(trimmed, "https://") {
+		return trimmed
+	}
+	return ""
+}
+
+func urlFromExternalLinks(links map[string]string, preferredKey string) string {
+	for key, value := range links {
+		if strings.Contains(strings.ToLower(key), preferredKey) {
+			if url := normalizeShareURL(value); url != "" {
+				return url
+			}
+		}
+	}
+	return ""
+}
+
+func templateShareURL(ext *loadedExtension, itemType string, id string) string {
+	if ext == nil || ext.Manifest == nil || ext.Manifest.Capabilities == nil {
+		return ""
+	}
+	id = stripProviderPrefix(strings.TrimSpace(id))
+	if id == "" {
+		return ""
+	}
+
+	templates, ok := ext.Manifest.Capabilities["shareUrlTemplates"].(map[string]interface{})
+	if !ok {
+		return ""
+	}
+	rawTemplate, ok := templates[itemType].(string)
+	if !ok {
+		return ""
+	}
+	rawTemplate = strings.TrimSpace(rawTemplate)
+	if rawTemplate == "" {
+		return ""
+	}
+	return strings.ReplaceAll(rawTemplate, "{id}", id)
+}
+
+func stripProviderPrefix(id string) string {
+	if index := strings.Index(id, ":"); index > 0 && index < len(id)-1 {
+		return id[index+1:]
+	}
+	return id
+}
+
+func firstNonEmptyString(values ...string) string {
+	for _, value := range values {
+		trimmed := strings.TrimSpace(value)
+		if trimmed != "" {
+			return trimmed
+		}
+	}
+	return ""
+}
@@ -0,0 +1,100 @@
+package gobackend
+
+import "testing"
+
+func TestCrossExtensionShareUsesAlbumCollectionItems(t *testing.T) {
+	ext := &loadedExtension{
+		Manifest: &ExtensionManifest{
+			Capabilities: map[string]interface{}{
+				"shareUrlTemplates": map[string]interface{}{
+					"album": "https://music.apple.com/us/album/{id}",
+				},
+			},
+		},
+	}
+	tracks := []ExtTrackMetadata{
+		{
+			ID:       "1440783617",
+			Name:     "Nevermind",
+			Artists:  "Nirvana",
+			ItemType: "album",
+		},
+	}
+
+	best := bestAlbumTrack(tracks, "Nevermind", "Nirvana")
+	if best == nil {
+		t.Fatal("expected album collection item to match")
+	}
+	if url := resolveCollectionShareURL(ext, "album", best); url != "https://music.apple.com/us/album/1440783617" {
+		t.Fatalf("album share URL = %q", url)
+	}
+}
+
+func TestCrossExtensionShareUsesArtistCollectionItems(t *testing.T) {
+	ext := &loadedExtension{
+		Manifest: &ExtensionManifest{
+			Capabilities: map[string]interface{}{
+				"shareUrlTemplates": map[string]interface{}{
+					"artist": "https://music.youtube.com/browse/{id}",
+				},
+			},
+		},
+	}
+	tracks := []ExtTrackMetadata{
+		{
+			ID:       "UCrPe3hLA51968GwxHSZ1llw",
+			Name:     "Nirvana",
+			ItemType: "artist",
+		},
+	}
+
+	best := bestArtistTrack(tracks, "Nirvana")
+	if best == nil {
+		t.Fatal("expected artist collection item to match")
+	}
+	if url := resolveCollectionShareURL(ext, "artist", best); url != "https://music.youtube.com/browse/UCrPe3hLA51968GwxHSZ1llw" {
+		t.Fatalf("artist share URL = %q", url)
+	}
+}
+
+func TestCrossExtensionShareCacheKeyIsProviderOrderStable(t *testing.T) {
+	apple := &extensionProviderWrapper{
+		extension: &loadedExtension{
+			ID:        "apple",
+			SourceDir: "/extensions/apple",
+			Manifest:  &ExtensionManifest{DisplayName: "Apple Music"},
+		},
+	}
+	qobuz := &extensionProviderWrapper{
+		extension: &loadedExtension{
+			ID:        "qobuz",
+			SourceDir: "/extensions/qobuz",
+			Manifest:  &ExtensionManifest{DisplayName: "Qobuz"},
+		},
+	}
+
+	first := crossExtensionShareCacheKey("Nevermind", "Nirvana", "album", "spotify", []*extensionProviderWrapper{apple, qobuz})
+	second := crossExtensionShareCacheKey("Nevermind", "Nirvana", "album", "spotify", []*extensionProviderWrapper{qobuz, apple})
+	if first != second {
+		t.Fatalf("cache key should not depend on provider order:\n%s\n%s", first, second)
+	}
+}
+
+func TestCrossExtensionShareCacheableSkipsTransientErrors(t *testing.T) {
+	cacheable := []CrossExtensionShareResult{
+		{ExtensionID: "apple", Found: true, URL: "https://music.apple.com/us/album/1"},
+		{ExtensionID: "qobuz", Error: "album not found"},
+		{ExtensionID: "tidal", Error: "no results"},
+	}
+	if !crossExtensionShareResultsCacheable(cacheable) {
+		t.Fatal("expected found and deterministic not-found results to be cacheable")
+	}
+
+	transient := []CrossExtensionShareResult{
+		{ExtensionID: "apple", Found: true, URL: "https://music.apple.com/us/album/1"},
+		{ExtensionID: "qobuz", Error: "request failed: timeout"},
+	}
+	if crossExtensionShareResultsCacheable(transient) {
+		t.Fatal("expected transient extension errors to skip cache")
+	}
+}
@@ -0,0 +1,171 @@
+package gobackend
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+)
+
+func TestCueParserEndToEnd(t *testing.T) {
+	dir := t.TempDir()
+	audioPath := filepath.Join(dir, "album.wav")
+	if err := os.WriteFile(audioPath, []byte("audio"), 0600); err != nil {
+		t.Fatalf("write audio: %v", err)
+	}
+	cuePath := filepath.Join(dir, "album.cue")
+	cue := "\ufeffREM GENRE \"Pop\"\n" +
+		"REM DATE 2026\n" +
+		"REM COMMENT \"comment\"\n" +
+		"REM COMPOSER \"Album Composer\"\n" +
+		"PERFORMER \"Album Artist\"\n" +
+		"TITLE \"Album Title\"\n" +
+		"FILE \"album.wav\" WAVE\n" +
+		"  TRACK 01 AUDIO\n" +
+		"    TITLE \"First\"\n" +
+		"    PERFORMER \"Track Artist\"\n" +
+		"    ISRC USRC17607839\n" +
+		"    INDEX 01 00:00:00\n" +
+		"  TRACK 02 AUDIO\n" +
+		"    TITLE \"Second\"\n" +
+		"    SONGWRITER \"Track Composer\"\n" +
+		"    INDEX 00 03:00:00\n" +
+		"    INDEX 01 03:05:00\n"
+	if err := os.WriteFile(cuePath, []byte(cue), 0600); err != nil {
+		t.Fatalf("write cue: %v", err)
+	}
+
+	sheet, err := ParseCueFile(cuePath)
+	if err != nil {
+		t.Fatalf("ParseCueFile: %v", err)
+	}
+	if sheet.Performer != "Album Artist" || sheet.Title != "Album Title" || len(sheet.Tracks) != 2 {
+		t.Fatalf("sheet = %#v", sheet)
+	}
+	if got := parseCueTimestamp("01:02:37"); got <= 62 || got >= 63 {
+		t.Fatalf("timestamp = %f", got)
+	}
+	if got := formatCueTimestamp(3723.5); got != "01:02:03.500" {
+		t.Fatalf("format timestamp = %q", got)
+	}
+	if got := unquoteCue("  \"quoted\"  "); got != "quoted" {
+		t.Fatalf("unquote = %q", got)
+	}
+	fileName, fileType := parseCueFileLine("unquoted album.flac FLAC")
+	if fileName != "unquoted album.flac" || fileType != "FLAC" {
+		t.Fatalf("file line = %q/%q", fileName, fileType)
+	}
+
+	if resolved := ResolveCueAudioPath(cuePath, "album.flac"); resolved != audioPath {
+		t.Fatalf("resolved = %q want %q", resolved, audioPath)
+	}
+	info, err := BuildCueSplitInfo(cuePath, sheet, "")
+	if err != nil {
+		t.Fatalf("BuildCueSplitInfo: %v", err)
+	}
+	if info.Tracks[0].EndSec != 180 || info.Tracks[1].Composer != "Track Composer" {
+		t.Fatalf("split info = %#v", info.Tracks)
+	}
+
+	jsonText, err := ParseCueFileJSON(cuePath, "")
+	if err != nil {
+		t.Fatalf("ParseCueFileJSON: %v", err)
+	}
+	var decoded CueSplitInfo
+	if err := json.Unmarshal([]byte(jsonText), &decoded); err != nil {
+		t.Fatalf("decode cue json: %v", err)
+	}
+	if decoded.AudioPath != audioPath {
+		t.Fatalf("decoded audio path = %q", decoded.AudioPath)
+	}
+
+	results, err := ScanCueFileForLibraryExt(cuePath, "", "virtual/album.cue", 1234, "scan-time")
+	if err != nil {
+		t.Fatalf("ScanCueFileForLibraryExt: %v", err)
+	}
+	if len(results) != 2 || results[0].TrackName != "First" || results[0].Duration != 180 {
+		t.Fatalf("scan results = %#v", results)
+	}
+	if results[0].FilePath != "virtual/album.cue#track01" || results[0].Format != "cue+wav" {
+		t.Fatalf("scan path/format = %q/%q", results[0].FilePath, results[0].Format)
+	}
+
+	if _, err := ParseCueFile(filepath.Join(dir, "missing.cue")); err == nil {
+		t.Fatal("expected missing cue error")
+	}
+	emptyCue := filepath.Join(dir, "empty.cue")
+	if err := os.WriteFile(emptyCue, []byte("TITLE \"No tracks\""), 0600); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := ParseCueFile(emptyCue); err == nil {
+		t.Fatal("expected no tracks error")
+	}
+	missingDir := t.TempDir()
+	missingCuePath := filepath.Join(missingDir, "missing.cue")
+	if err := os.WriteFile(missingCuePath, []byte(cue), 0600); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := BuildCueSplitInfo(missingCuePath, &CueSheet{FileName: "missing.wav"}, ""); err == nil {
+		t.Fatal("expected missing audio error")
+	}
+	if _, err := resolveCueAudioPathForLibrary(cuePath, nil, ""); err == nil {
+		t.Fatal("expected nil sheet error")
+	}
+	if _, err := scanCueSheetForLibrary(cuePath, nil, audioPath, "", 0, "", ""); err == nil {
+		t.Fatal("expected nil scan sheet error")
+	}
+}
+
+func TestDuplicateIndexAndParallelExistence(t *testing.T) {
+	dir := t.TempDir()
+	filePath := filepath.Join(dir, "song.flac")
+	if err := os.WriteFile(filePath, []byte("audio"), 0600); err != nil {
+		t.Fatal(err)
+	}
+
+	idx := &ISRCIndex{index: map[string]string{}, outputDir: dir, buildTime: time.Now()}
+	idx.Add("usrc17607839", filePath)
+	if got, ok := idx.lookup("USRC17607839"); !ok || got != filePath {
+		t.Fatalf("lookup = %q/%v", got, ok)
+	}
+	if got, err := idx.Lookup("usrc17607839"); err != nil || got != filePath {
+		t.Fatalf("Lookup = %q/%v", got, err)
+	}
+	idx.remove("usrc17607839")
+	if _, ok := idx.lookup("usrc17607839"); ok {
+		t.Fatal("expected removed ISRC")
+	}
+
+	isrcIndexCacheMu.Lock()
+	isrcIndexCache[dir] = idx
+	isrcIndexCacheMu.Unlock()
+	defer InvalidateISRCCache(dir)
+
+	AddToISRCIndex(dir, "USRC17607839", filePath)
+	if found, err := CheckISRCExists(dir, "USRC17607839"); err != nil || found != filePath {
+		t.Fatalf("CheckISRCExists = %q/%v", found, err)
+	}
+	if !CheckFileExists(filePath) || CheckFileExists(dir) || CheckFileExists(filepath.Join(dir, "missing.flac")) {
+		t.Fatal("unexpected file existence result")
+	}
+
+	tracksJSON := `[{"isrc":"USRC17607839","track_name":"Song","artist_name":"Artist"},{"isrc":"MISSING","track_name":"Other","artist_name":"Artist"}]`
+	resultJSON, err := CheckFilesExistParallel(dir, tracksJSON)
+	if err != nil {
+		t.Fatalf("CheckFilesExistParallel: %v", err)
+	}
+	var results []FileExistenceResult
+	if err := json.Unmarshal([]byte(resultJSON), &results); err != nil {
+		t.Fatalf("decode results: %v", err)
+	}
+	if !results[0].Exists || results[0].FilePath != filePath || results[1].Exists {
+		t.Fatalf("results = %#v", results)
+	}
+	if _, err := CheckFilesExistParallel(dir, `not-json`); err == nil {
+		t.Fatal("expected invalid json error")
+	}
+	if err := PreBuildISRCIndex(""); err == nil {
+		t.Fatal("expected empty dir error")
+	}
+}
@@ -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", ".aiff", ".aif", ".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
+}
@@ -0,0 +1,153 @@
+package gobackend
+
+import (
+	"context"
+	"io"
+	"net/http"
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestDeezerClientWithFakeHTTP(t *testing.T) {
+	client := &DeezerClient{
+		httpClient: &http.Client{Transport: roundTripFunc(func(req *http.Request) (*http.Response, error) {
+			body := fakeDeezerResponse(req.URL.Path, req.URL.RawQuery)
+			status := http.StatusOK
+			if body == "" {
+				status = http.StatusNotFound
+				body = `{"error":"missing"}`
+			}
+			return &http.Response{
+				StatusCode: status,
+				Header:     make(http.Header),
+				Body:       io.NopCloser(strings.NewReader(body)),
+				Request:    req,
+			}, nil
+		})},
+		searchCache:          map[string]*cacheEntry{},
+		albumCache:           map[string]*cacheEntry{},
+		artistCache:          map[string]*cacheEntry{},
+		isrcCache:            map[string]string{},
+		cacheCleanupInterval: time.Millisecond,
+	}
+	ctx := context.Background()
+
+	search, err := client.SearchAll(ctx, "artist song", 2, 2, "")
+	if err != nil {
+		t.Fatalf("SearchAll: %v", err)
+	}
+	if len(search.Tracks) != 1 || len(search.Artists) != 1 || len(search.Albums) != 1 || len(search.Playlists) != 1 {
+		t.Fatalf("search = %#v", search)
+	}
+	cached, err := client.SearchAll(ctx, "artist song", 2, 2, "")
+	if err != nil || cached != search {
+		t.Fatalf("cached SearchAll = %#v/%v", cached, err)
+	}
+	if filtered, err := client.SearchAll(ctx, "artist song", 1, 1, "track"); err != nil || len(filtered.Tracks) != 1 || len(filtered.Artists) != 0 {
+		t.Fatalf("filtered search = %#v/%v", filtered, err)
+	}
+
+	track, err := client.GetTrack(ctx, "101")
+	if err != nil {
+		t.Fatalf("GetTrack: %v", err)
+	}
+	if track.Track.SpotifyID != "deezer:101" || track.Track.Artists != "Contributor A, Contributor B" {
+		t.Fatalf("track = %#v", track)
+	}
+
+	album, err := client.GetAlbum(ctx, "201")
+	if err != nil {
+		t.Fatalf("GetAlbum: %v", err)
+	}
+	if album.AlbumInfo.Name != "Album" || len(album.TrackList) != 2 || album.TrackList[1].ISRC == "" {
+		t.Fatalf("album = %#v", album)
+	}
+	if cachedAlbum, err := client.GetAlbum(ctx, "201"); err != nil || cachedAlbum != album {
+		t.Fatalf("cached album = %#v/%v", cachedAlbum, err)
+	}
+
+	artist, err := client.GetArtist(ctx, "301")
+	if err != nil {
+		t.Fatalf("GetArtist: %v", err)
+	}
+	if artist.ArtistInfo.Name != "Artist" || len(artist.Albums) != 1 || artist.Albums[0].TotalTracks == 0 {
+		t.Fatalf("artist = %#v", artist)
+	}
+	if cachedArtist, err := client.GetArtist(ctx, "301"); err != nil || cachedArtist != artist {
+		t.Fatalf("cached artist = %#v/%v", cachedArtist, err)
+	}
+
+	related, err := client.GetRelatedArtists(ctx, "deezer:301", 3)
+	if err != nil {
+		t.Fatalf("GetRelatedArtists: %v", err)
+	}
+	if len(related) != 1 || related[0].ID != "deezer:302" {
+		t.Fatalf("related = %#v", related)
+	}
+	if _, err := client.GetRelatedArtists(ctx, "", 0); err == nil {
+		t.Fatal("expected invalid related artist ID")
+	}
+
+	playlist, err := client.GetPlaylist(ctx, "401")
+	if err != nil {
+		t.Fatalf("GetPlaylist: %v", err)
+	}
+	if playlist.PlaylistInfo.Tracks.Total != 2 || len(playlist.TrackList) != 2 {
+		t.Fatalf("playlist = %#v", playlist)
+	}
+
+	byISRC, err := client.SearchByISRC(ctx, "USRC17607839")
+	if err != nil {
+		t.Fatalf("SearchByISRC: %v", err)
+	}
+	if byISRC.SpotifyID != "deezer:101" {
+		t.Fatalf("by ISRC = %#v", byISRC)
+	}
+	if _, err := client.SearchByISRC(ctx, "MISSING"); err == nil {
+		t.Fatal("expected missing ISRC error")
+	}
+
+	isrc, err := client.GetTrackISRC(ctx, "102")
+	if err != nil || isrc != "USRC17607840" {
+		t.Fatalf("GetTrackISRC = %q/%v", isrc, err)
+	}
+	albumID, err := client.GetTrackAlbumID(ctx, "101")
+	if err != nil || albumID != "201" {
+		t.Fatalf("GetTrackAlbumID = %q/%v", albumID, err)
+	}
+	extended, err := client.GetAlbumExtendedMetadata(ctx, "201")
+	if err != nil {
+		t.Fatalf("GetAlbumExtendedMetadata: %v", err)
+	}
+	if extended.Genre != "Pop, Dance" || extended.Label != "Label" {
+		t.Fatalf("extended = %#v", extended)
+	}
+	if byTrack, err := client.GetExtendedMetadataByTrackID(ctx, "101"); err != nil || byTrack.Label != "Label" {
+		t.Fatalf("metadata by track = %#v/%v", byTrack, err)
+	}
+	if byISRCMeta, err := client.GetExtendedMetadataByISRC(ctx, "USRC17607839"); err != nil || byISRCMeta.Label != "Label" {
+		t.Fatalf("metadata by isrc = %#v/%v", byISRCMeta, err)
+	}
+	if _, err := client.GetExtendedMetadataByISRC(ctx, ""); err == nil {
+		t.Fatal("expected empty ISRC metadata error")
+	}
+
+	if typ, id, err := parseDeezerURL("https://www.deezer.com/us/track/101"); err != nil || typ != "track" || id != "101" {
+		t.Fatalf("parseDeezerURL = %q/%q/%v", typ, id, err)
+	}
+	if _, _, err := parseDeezerURL("https://example.com/track/101"); err == nil {
+		t.Fatal("expected non-Deezer URL error")
+	}
+
+	client.cacheMu.Lock()
+	client.searchCache["expired"] = &cacheEntry{expiresAt: time.Now().Add(-time.Hour)}
+	client.searchCache["keep1"] = &cacheEntry{expiresAt: time.Now().Add(time.Hour)}
+	client.searchCache["keep2"] = &cacheEntry{expiresAt: time.Now().Add(2 * time.Hour)}
+	client.pruneExpiredCacheEntriesLocked(client.searchCache, time.Now())
+	client.trimCacheEntriesLocked(client.searchCache, 1)
+	client.isrcCache["1"] = "A"
+	client.isrcCache["2"] = "B"
+	client.trimStringCacheEntriesLocked(client.isrcCache, 1)
+	client.cacheMu.Unlock()
+}
@@ -1,59 +1,168 @@
 package gobackend

 import (
+	"encoding/json"
+	"fmt"
 	"os"
 	"path/filepath"
 	"strings"
+	"sync"
+	"time"
 )

-// checkISRCExistsInternal checks if a file with the given ISRC exists (internal use)
+type ISRCIndex struct {
+	index     map[string]string // ISRC (uppercase) -> file path
+	outputDir string
+	buildTime time.Time
+	mu        sync.RWMutex
+}
+
+var (
+	isrcIndexCache   = make(map[string]*ISRCIndex)
+	isrcIndexCacheMu sync.RWMutex
+	isrcBuildingMu   sync.Map // Per-directory build lock to prevent concurrent builds
+	isrcIndexTTL     = 5 * time.Minute
+)
+
+func GetISRCIndex(outputDir string) *ISRCIndex {
+	isrcIndexCacheMu.RLock()
+	idx, exists := isrcIndexCache[outputDir]
+	isrcIndexCacheMu.RUnlock()
+
+	if exists && time.Since(idx.buildTime) < isrcIndexTTL {
+		return idx
+	}
+
+	buildLock, _ := isrcBuildingMu.LoadOrStore(outputDir, &sync.Mutex{})
+	mu := buildLock.(*sync.Mutex)
+	mu.Lock()
+	defer mu.Unlock()
+
+	isrcIndexCacheMu.RLock()
+	idx, exists = isrcIndexCache[outputDir]
+	isrcIndexCacheMu.RUnlock()
+
+	if exists && time.Since(idx.buildTime) < isrcIndexTTL {
+		return idx
+	}
+
+	return buildISRCIndex(outputDir)
+}
+
+func buildISRCIndex(outputDir string) *ISRCIndex {
+	idx := &ISRCIndex{
+		index:     make(map[string]string),
+		outputDir: outputDir,
+		buildTime: time.Now(),
+	}
+
+	if outputDir == "" {
+		return idx
+	}
+
+	startTime := time.Now()
+	fileCount := 0
+
+	filepath.Walk(outputDir, func(path string, info os.FileInfo, err error) error {
+		if err != nil || info.IsDir() {
+			return nil
+		}
+
+		ext := strings.ToLower(filepath.Ext(path))
+		if ext != ".flac" {
+			return nil
+		}
+
+		metadata, err := ReadMetadata(path)
+		if err != nil || metadata.ISRC == "" {
+			return nil
+		}
+
+		idx.index[strings.ToUpper(metadata.ISRC)] = path
+		fileCount++
+		return nil
+	})
+
+	fmt.Printf("[ISRCIndex] Built index for %s: %d files in %v\n",
+		outputDir, fileCount, time.Since(startTime).Round(time.Millisecond))
+
+	isrcIndexCacheMu.Lock()
+	isrcIndexCache[outputDir] = idx
+	isrcIndexCacheMu.Unlock()
+
+	return idx
+}
+
+func (idx *ISRCIndex) lookup(isrc string) (string, bool) {
+	if isrc == "" {
+		return "", false
+	}
+
+	idx.mu.RLock()
+	defer idx.mu.RUnlock()
+
+	path, exists := idx.index[strings.ToUpper(isrc)]
+	return path, exists
+}
+
+func (idx *ISRCIndex) remove(isrc string) {
+	if isrc == "" {
+		return
+	}
+
+	idx.mu.Lock()
+	defer idx.mu.Unlock()
+
+	delete(idx.index, strings.ToUpper(isrc))
+}
+
+func (idx *ISRCIndex) Lookup(isrc string) (string, error) {
+	path, _ := idx.lookup(isrc)
+	return path, nil
+}
+
+func (idx *ISRCIndex) Add(isrc, filePath string) {
+	if isrc == "" || filePath == "" {
+		return
+	}
+
+	idx.mu.Lock()
+	defer idx.mu.Unlock()
+
+	idx.index[strings.ToUpper(isrc)] = filePath
+}
+
+func InvalidateISRCCache(outputDir string) {
+	isrcIndexCacheMu.Lock()
+	delete(isrcIndexCache, outputDir)
+	isrcIndexCacheMu.Unlock()
+}
+
 func checkISRCExistsInternal(outputDir, isrc string) (string, bool) {
 	if isrc == "" || outputDir == "" {
 		return "", false
 	}

-	// Walk through directory looking for FLAC files
-	var foundFile string
-	filepath.Walk(outputDir, func(path string, info os.FileInfo, err error) error {
-		if err != nil {
-			return nil
-		}
-
-		// Only check FLAC files
-		if info.IsDir() || !strings.HasSuffix(strings.ToLower(path), ".flac") {
-			return nil
-		}
-
-		// Read metadata from file
-		metadata, err := ReadMetadata(path)
-		if err != nil {
-			return nil
-		}
-
-		// Check if ISRC matches
-		if metadata.ISRC == isrc {
-			foundFile = path
-			return filepath.SkipAll // Stop walking
-		}
-
-		return nil
-	})
-
-	if foundFile != "" {
-		return foundFile, true
+	idx := GetISRCIndex(outputDir)
+	filePath, exists := idx.lookup(isrc)
+	if !exists {
+		return "", false
 	}

-	return "", false
+	if !CheckFileExists(filePath) {
+		// Stale index entry; remove it and return not found.
+		idx.remove(isrc)
+		return "", false
+	}
+
+	return filePath, true
 }

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

-// CheckFileExists checks if a file with the given name exists
 func CheckFileExists(filePath string) bool {
 	info, err := os.Stat(filePath)
 	if err != nil {
@@ -61,3 +170,86 @@ func CheckFileExists(filePath string) bool {
 	}
 	return !info.IsDir() && info.Size() > 0
 }
+
+type FileExistenceResult struct {
+	ISRC       string `json:"isrc"`
+	Exists     bool   `json:"exists"`
+	FilePath   string `json:"file_path,omitempty"`
+	TrackName  string `json:"track_name,omitempty"`
+	ArtistName string `json:"artist_name,omitempty"`
+}
+
+func CheckFilesExistParallel(outputDir string, tracksJSON string) (string, error) {
+	var tracks []struct {
+		ISRC       string `json:"isrc"`
+		TrackName  string `json:"track_name"`
+		ArtistName string `json:"artist_name"`
+	}
+	if err := json.Unmarshal([]byte(tracksJSON), &tracks); err != nil {
+		return "", fmt.Errorf("failed to parse tracks JSON: %w", err)
+	}
+
+	results := make([]FileExistenceResult, len(tracks))
+
+	isrcIdx := GetISRCIndex(outputDir)
+
+	var wg sync.WaitGroup
+	for i, track := range tracks {
+		wg.Add(1)
+		go func(resultIdx int, t struct {
+			ISRC       string `json:"isrc"`
+			TrackName  string `json:"track_name"`
+			ArtistName string `json:"artist_name"`
+		}) {
+			defer wg.Done()
+
+			result := FileExistenceResult{
+				ISRC:       t.ISRC,
+				TrackName:  t.TrackName,
+				ArtistName: t.ArtistName,
+				Exists:     false,
+			}
+
+			if t.ISRC != "" {
+				if filePath, exists := isrcIdx.lookup(t.ISRC); exists {
+					result.Exists = true
+					result.FilePath = filePath
+				}
+			}
+
+			results[resultIdx] = result
+		}(i, track)
+	}
+
+	wg.Wait()
+
+	resultJSON, err := json.Marshal(results)
+	if err != nil {
+		return "", fmt.Errorf("failed to marshal results: %w", err)
+	}
+
+	return string(resultJSON), nil
+}
+
+func PreBuildISRCIndex(outputDir string) error {
+	if outputDir == "" {
+		return fmt.Errorf("output directory is required")
+	}
+
+	buildISRCIndex(outputDir)
+	return nil
+}
+
+func AddToISRCIndex(outputDir, isrc, filePath string) {
+	if outputDir == "" || isrc == "" || filePath == "" {
+		return
+	}
+
+	isrcIndexCacheMu.RLock()
+	idx, exists := isrcIndexCache[outputDir]
+	isrcIndexCacheMu.RUnlock()
+
+	if exists {
+		idx.Add(isrc, filePath)
+	}
+}
@@ -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"])
+	}
+}
@@ -0,0 +1,83 @@
+package gobackend
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestExtensionPackageExportWrappers(t *testing.T) {
+	dir := t.TempDir()
+	extensionsDir := filepath.Join(dir, "extensions")
+	dataDir := filepath.Join(dir, "data")
+	if err := InitExtensionSystem(extensionsDir, dataDir); err != nil {
+		t.Fatalf("InitExtensionSystem: %v", err)
+	}
+	CleanupExtensions()
+	defer CleanupExtensions()
+
+	js := `
+registerExtension({
+  initialize: function(settings) { this.settings = settings || {}; },
+  cleanup: function() {},
+  doAction: function() { return { message: "wrapped", setting_updates: { quality: "lossless" } }; },
+  searchTracks: function() { return { tracks: [], total: 0 }; },
+  fetchLyrics: function() { return { syncType: "UNSYNCED", lines: [{ words: "hello" }] }; },
+  getDownloadUrl: function() { return { url: "https://example.test/a.flac" }; }
+});
+`
+	pkgV1 := filepath.Join(dir, "wrapper-ext-v1.spotiflac-ext")
+	pkgV2 := filepath.Join(dir, "wrapper-ext-v2.spotiflac-ext")
+	createTestExtensionPackage(t, pkgV1, "wrapper-ext", "1.0.0", js, nil)
+	createTestExtensionPackage(t, pkgV2, "wrapper-ext", "1.1.0", js, nil)
+
+	loadedJSON, err := LoadExtensionFromPath(pkgV1)
+	if err != nil || !strings.Contains(loadedJSON, "wrapper-ext") {
+		t.Fatalf("LoadExtensionFromPath = %q/%v", loadedJSON, err)
+	}
+	if installedJSON, err := GetInstalledExtensions(); err != nil || !strings.Contains(installedJSON, "wrapper-ext") {
+		t.Fatalf("GetInstalledExtensions = %q/%v", installedJSON, err)
+	}
+	if err := SetExtensionEnabledByID("wrapper-ext", true); err != nil {
+		t.Fatalf("SetExtensionEnabledByID true: %v", err)
+	}
+	if actionJSON, err := InvokeExtensionActionJSON("wrapper-ext", "doAction"); err != nil || !strings.Contains(actionJSON, "wrapped") {
+		t.Fatalf("InvokeExtensionActionJSON = %q/%v", actionJSON, err)
+	}
+	if upgradeJSON, err := CheckExtensionUpgradeFromPath(pkgV2); err != nil || !strings.Contains(upgradeJSON, `"can_upgrade":true`) {
+		t.Fatalf("CheckExtensionUpgradeFromPath = %q/%v", upgradeJSON, err)
+	}
+	if upgradedJSON, err := UpgradeExtensionFromPath(pkgV2); err != nil || !strings.Contains(upgradedJSON, "1.1.0") {
+		t.Fatalf("UpgradeExtensionFromPath = %q/%v", upgradedJSON, err)
+	}
+	if err := SetExtensionEnabledByID("wrapper-ext", false); err != nil {
+		t.Fatalf("SetExtensionEnabledByID false: %v", err)
+	}
+	if err := UnloadExtensionByID("wrapper-ext"); err != nil {
+		t.Fatalf("UnloadExtensionByID: %v", err)
+	}
+
+	dirExt := filepath.Join(extensionsDir, "wrapper-dir-ext")
+	if err := createDirectoryExtension(dirExt, "wrapper-dir-ext", "1.0.0"); err != nil {
+		t.Fatalf("create directory extension: %v", err)
+	}
+	if loadedDirJSON, err := LoadExtensionsFromDir(extensionsDir); err != nil || !strings.Contains(loadedDirJSON, "wrapper-dir-ext") {
+		t.Fatalf("LoadExtensionsFromDir = %q/%v", loadedDirJSON, err)
+	}
+	if err := RemoveExtensionByID("wrapper-dir-ext"); err != nil {
+		t.Fatalf("RemoveExtensionByID: %v", err)
+	}
+}
+
+func createDirectoryExtension(dir, name, version string) error {
+	if err := os.MkdirAll(dir, 0755); err != nil {
+		return err
+	}
+	manifest := fmt.Sprintf(`{"name":%q,"displayName":%q,"version":%q,"description":"Directory wrapper extension","type":["metadata_provider"],"permissions":{}}`, name, name, version)
+	if err := os.WriteFile(filepath.Join(dir, "manifest.json"), []byte(manifest), 0600); err != nil {
+		return err
+	}
+	return os.WriteFile(filepath.Join(dir, "index.js"), []byte(`registerExtension({searchTracks:function(){return {tracks:[], total:0};}});`), 0600)
+}
@@ -0,0 +1,158 @@
+package gobackend
+
+import (
+	"context"
+	"io"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestLyricsExportWrappersWithoutNetwork(t *testing.T) {
+	dir := t.TempDir()
+	audioPath := filepath.Join(dir, "sidecar.mp3")
+	if err := os.WriteFile(audioPath, []byte("audio"), 0600); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "sidecar.lrc"), []byte("[00:00.00]Sidecar lyric"), 0600); err != nil {
+		t.Fatal(err)
+	}
+
+	if jsonText, err := FetchLyrics("spotify-1", "Song Instrumental", "Artist", 180000); err != nil || !strings.Contains(jsonText, `"instrumental":true`) {
+		t.Fatalf("FetchLyrics instrumental = %q/%v", jsonText, err)
+	}
+	if lrc, err := GetLyricsLRC("spotify-1", "Song Instrumental", "Artist", "", 180000); err != nil || lrc != "[instrumental:true]" {
+		t.Fatalf("GetLyricsLRC instrumental = %q/%v", lrc, err)
+	}
+	if jsonText, err := GetLyricsLRCWithSource("spotify-1", "Song Instrumental", "Artist", "", 180000); err != nil || !strings.Contains(jsonText, `"instrumental":true`) {
+		t.Fatalf("GetLyricsLRCWithSource instrumental = %q/%v", jsonText, err)
+	}
+	if lrc, err := GetLyricsLRC("", "", "", audioPath, 0); err != nil || !strings.Contains(lrc, "Sidecar lyric") {
+		t.Fatalf("GetLyricsLRC sidecar = %q/%v", lrc, err)
+	}
+	if jsonText, err := GetLyricsLRCWithSource("", "", "", audioPath, 0); err != nil || !strings.Contains(jsonText, "Sidecar lyric") {
+		t.Fatalf("GetLyricsLRCWithSource sidecar = %q/%v", jsonText, err)
+	}
+
+	outPath := filepath.Join(dir, "lyrics.lrc")
+	if err := FetchAndSaveLyrics("Song", "Artist", "", 0, outPath, audioPath); err != nil {
+		t.Fatalf("FetchAndSaveLyrics sidecar: %v", err)
+	}
+	if data := string(mustReadFile(t, outPath)); !strings.Contains(data, "Sidecar lyric") {
+		t.Fatalf("saved lyrics = %q", data)
+	}
+	if response, err := EmbedLyricsToFile(filepath.Join(dir, "not-flac.mp3"), "lyrics"); err != nil || !strings.Contains(response, `"success":false`) {
+		t.Fatalf("EmbedLyricsToFile error = %q/%v", response, err)
+	}
+	if response, err := RewriteSplitArtistTagsExport(filepath.Join(dir, "not-flac.mp3"), "A;B", "A"); err != nil || !strings.Contains(response, `"success":false`) {
+		t.Fatalf("RewriteSplitArtistTagsExport error = %q/%v", response, err)
+	}
+}
+
+func TestSongLinkExportWrappersWithFakeClient(t *testing.T) {
+	origClient := globalSongLinkClient
+	origRetryConfig := songLinkRetryConfig
+	origSearchByISRC := songLinkSearchByISRC
+	origCheckFromDeezer := songLinkCheckAvailabilityFromDeezer
+	defer func() {
+		globalSongLinkClient = origClient
+		songLinkRetryConfig = origRetryConfig
+		songLinkSearchByISRC = origSearchByISRC
+		songLinkCheckAvailabilityFromDeezer = origCheckFromDeezer
+		SetSongLinkNetworkOptions(false, false)
+	}()
+	songLinkRetryConfig = func() RetryConfig {
+		return RetryConfig{MaxRetries: 0, InitialDelay: 0, MaxDelay: 0, BackoffFactor: 1}
+	}
+	globalSongLinkClient = &SongLinkClient{client: &http.Client{Transport: roundTripFunc(func(req *http.Request) (*http.Response, error) {
+		var body string
+		if req.URL.Host == "api.zarz.moe" {
+			body = `{"success":true,"songUrls":{"Spotify":"https://open.spotify.com/track/spotify-1","Deezer":"https://www.deezer.com/track/101","Tidal":"https://listen.tidal.com/track/202","YouTube":"https://youtu.be/yt1","AmazonMusic":"https://music.amazon.com/tracks/amz1","Qobuz":"https://open.qobuz.com/track/303"}}`
+		} else if req.URL.Host == "api.song.link" {
+			body = `{"linksByPlatform":{"spotify":{"url":"https://open.spotify.com/track/spotify-1"},"deezer":{"url":"https://www.deezer.com/track/101"},"tidal":{"url":"https://listen.tidal.com/track/202"},"youtubeMusic":{"url":"https://music.youtube.com/watch?v=ytm1"},"amazonMusic":{"url":"https://music.amazon.com/tracks/amz1"},"qobuz":{"url":"https://open.qobuz.com/track/303"}}}`
+		} else {
+			t.Fatalf("unexpected SongLink request: %s", req.URL.String())
+		}
+		return &http.Response{StatusCode: http.StatusOK, Header: make(http.Header), Body: io.NopCloser(strings.NewReader(body)), Request: req}, nil
+	})}}
+	songLinkClientOnce.Do(func() {})
+
+	SetSongLinkNetworkOptions(true, true)
+	if availabilityJSON, err := CheckAvailability("spotify-1", ""); err != nil || !strings.Contains(availabilityJSON, `"deezer_id":"101"`) {
+		t.Fatalf("CheckAvailability = %q/%v", availabilityJSON, err)
+	}
+	if availabilityJSON, err := CheckAvailabilityFromDeezerID("101"); err != nil || !strings.Contains(availabilityJSON, `"spotify_id":"spotify-1"`) {
+		t.Fatalf("CheckAvailabilityFromDeezerID = %q/%v", availabilityJSON, err)
+	}
+	if availabilityJSON, err := CheckAvailabilityByPlatformID("deezer", "song", "101"); err != nil || !strings.Contains(availabilityJSON, `"tidal_url"`) {
+		t.Fatalf("CheckAvailabilityByPlatformID = %q/%v", availabilityJSON, err)
+	}
+	if spotifyID, err := GetSpotifyIDFromDeezerTrack("101"); err != nil || spotifyID != "spotify-1" {
+		t.Fatalf("GetSpotifyIDFromDeezerTrack = %q/%v", spotifyID, err)
+	}
+	if tidalURL, err := GetTidalURLFromDeezerTrack("101"); err != nil || !strings.Contains(tidalURL, "tidal") {
+		t.Fatalf("GetTidalURLFromDeezerTrack = %q/%v", tidalURL, err)
+	}
+	if urls, err := NewSongLinkClient().GetStreamingURLs("spotify-1"); err != nil || urls["tidal"] == "" || urls["amazon"] == "" {
+		t.Fatalf("GetStreamingURLs = %#v/%v", urls, err)
+	}
+	if youtubeURL, err := NewSongLinkClient().GetYouTubeURLFromSpotify("spotify-1"); err != nil || !strings.Contains(youtubeURL, "youtu") {
+		t.Fatalf("GetYouTubeURLFromSpotify = %q/%v", youtubeURL, err)
+	}
+	if amazonURL, err := NewSongLinkClient().GetAmazonURLFromDeezer("101"); err != nil || !strings.Contains(amazonURL, "amazon") {
+		t.Fatalf("GetAmazonURLFromDeezer = %q/%v", amazonURL, err)
+	}
+	if youtubeURL, err := NewSongLinkClient().GetYouTubeURLFromDeezer("101"); err != nil || !strings.Contains(youtubeURL, "youtube") {
+		t.Fatalf("GetYouTubeURLFromDeezer = %q/%v", youtubeURL, err)
+	}
+	if deezerID, err := NewSongLinkClient().GetDeezerIDFromSpotify("spotify-1"); err != nil || deezerID != "101" {
+		t.Fatalf("GetDeezerIDFromSpotify = %q/%v", deezerID, err)
+	}
+	if album, err := NewSongLinkClient().CheckAlbumAvailability("album-1"); err != nil || !album.Deezer || album.DeezerID == "" {
+		t.Fatalf("CheckAlbumAvailability = %#v/%v", album, err)
+	}
+	if albumID, err := NewSongLinkClient().GetDeezerAlbumIDFromSpotify("album-1"); err != nil || albumID == "" {
+		t.Fatalf("GetDeezerAlbumIDFromSpotify = %q/%v", albumID, err)
+	}
+	if availability, err := NewSongLinkClient().CheckAvailabilityFromURL("https://www.deezer.com/track/101"); err != nil || !availability.Deezer {
+		t.Fatalf("CheckAvailabilityFromURL = %#v/%v", availability, err)
+	}
+
+	songLinkSearchByISRC = func(ctx context.Context, isrc string) (*TrackMetadata, error) {
+		return &TrackMetadata{SpotifyID: "deezer:101", ExternalURL: "https://www.deezer.com/track/101"}, nil
+	}
+	songLinkCheckAvailabilityFromDeezer = func(s *SongLinkClient, deezerTrackID string) (*TrackAvailability, error) {
+		return &TrackAvailability{SpotifyID: "spotify-1", Deezer: true, DeezerID: deezerTrackID}, nil
+	}
+	if availabilityJSON, err := CheckAvailability("", "USRC17607839"); err != nil || !strings.Contains(availabilityJSON, `"deezer_id":"101"`) {
+		t.Fatalf("CheckAvailability by ISRC = %q/%v", availabilityJSON, err)
+	}
+	if songLinkExtractDeezerTrackID(nil) != "" || songLinkExtractDeezerTrackID(&TrackMetadata{ExternalURL: "https://www.deezer.com/track/202"}) != "202" {
+		t.Fatal("songLinkExtractDeezerTrackID mismatch")
+	}
+
+	deezerClient = &DeezerClient{
+		httpClient: &http.Client{Transport: roundTripFunc(func(req *http.Request) (*http.Response, error) {
+			body := fakeDeezerResponse(req.URL.Path, req.URL.RawQuery)
+			if body == "" {
+				body = `{"error":"missing"}`
+			}
+			return &http.Response{StatusCode: http.StatusOK, Header: make(http.Header), Body: io.NopCloser(strings.NewReader(body)), Request: req}, nil
+		})},
+		searchCache:          map[string]*cacheEntry{},
+		albumCache:           map[string]*cacheEntry{},
+		artistCache:          map[string]*cacheEntry{},
+		isrcCache:            map[string]string{},
+		cacheCleanupInterval: time.Hour,
+	}
+	deezerClientOnce.Do(func() {})
+	if jsonText, err := ConvertSpotifyToDeezer("track", "spotify-1"); err != nil || !strings.Contains(jsonText, `"spotify_id":"deezer:101"`) {
+		t.Fatalf("ConvertSpotifyToDeezer track = %q/%v", jsonText, err)
+	}
+	if jsonText, err := ConvertSpotifyToDeezer("album", "album-1"); err != nil || jsonText == "" {
+		t.Fatalf("ConvertSpotifyToDeezer album = %q/%v", jsonText, err)
+	}
+}
@@ -0,0 +1,493 @@
+package gobackend
+
+import (
+	"encoding/json"
+	"io"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestDownloadErrorClassificationPrioritizesRateLimit(t *testing.T) {
+	got := classifyDownloadErrorType("All providers failed. Last error: HTTP status 429: too many requests")
+	if got != "rate_limit" {
+		t.Fatalf("expected rate_limit, got %q", got)
+	}
+
+	responseJSON, err := errorResponse("All services failed. Last error: rate limit exceeded")
+	if err != nil {
+		t.Fatalf("errorResponse returned error: %v", err)
+	}
+
+	var response DownloadResponse
+	if err := json.Unmarshal([]byte(responseJSON), &response); err != nil {
+		t.Fatalf("invalid response JSON: %v", err)
+	}
+	if response.ErrorType != "rate_limit" {
+		t.Fatalf("expected rate_limit response, got %q", response.ErrorType)
+	}
+}
+
+func TestDownloadErrorClassificationDetectsVerificationRequired(t *testing.T) {
+	cases := []string{
+		"HTTP 401 for /tickets",
+		"HTTP status 428: precondition required",
+		"Verification required",
+	}
+	for _, tc := range cases {
+		if got := classifyDownloadErrorType(tc); got != "verification_required" {
+			t.Fatalf("classifyDownloadErrorType(%q) = %q, want verification_required", tc, got)
+		}
+	}
+}
+
+func TestGetProviderMetadataPrefersEnabledDeezerExtension(t *testing.T) {
+	dir := t.TempDir()
+	if err := InitExtensionSystem(filepath.Join(dir, "extensions"), filepath.Join(dir, "data")); err != nil {
+		t.Fatalf("InitExtensionSystem: %v", err)
+	}
+	CleanupExtensions()
+	defer CleanupExtensions()
+
+	ext := newTestLoadedExtension(t, ExtensionTypeMetadataProvider)
+	ext.ID = "deezer"
+	ext.Manifest.Name = "deezer"
+	manager := getExtensionManager()
+	manager.mu.Lock()
+	manager.extensions = map[string]*loadedExtension{ext.ID: ext}
+	manager.mu.Unlock()
+
+	jsonText, err := GetProviderMetadataJSON("deezer", "album", "201")
+	if err != nil {
+		t.Fatalf("GetProviderMetadataJSON deezer album: %v", err)
+	}
+	if !strings.Contains(jsonText, "album-track") {
+		t.Fatalf("expected enabled deezer extension metadata, got %s", jsonText)
+	}
+}
+
+func TestExportsJSONWrappersAndExtensionManagerSurface(t *testing.T) {
+	dir := t.TempDir()
+	dataDir := filepath.Join(dir, "data")
+	extensionsDir := filepath.Join(dir, "extensions")
+	if err := InitExtensionSystem(extensionsDir, dataDir); err != nil {
+		t.Fatalf("InitExtensionSystem: %v", err)
+	}
+
+	ext := newTestLoadedExtension(t, ExtensionTypeMetadataProvider, ExtensionTypeDownloadProvider, ExtensionTypeLyricsProvider)
+	manager := getExtensionManager()
+	manager.mu.Lock()
+	if manager.extensions == nil {
+		manager.extensions = map[string]*loadedExtension{}
+	}
+	manager.extensions[ext.ID] = ext
+	manager.mu.Unlock()
+	defer func() {
+		manager.mu.Lock()
+		delete(manager.extensions, ext.ID)
+		manager.mu.Unlock()
+	}()
+
+	if response, err := DownloadTrack(`{}`); err != nil || !strings.Contains(response, "retired") {
+		t.Fatalf("DownloadTrack = %q/%v", response, err)
+	}
+	if response, err := DownloadByStrategy(`not-json`); err != nil || !strings.Contains(response, "Invalid request") {
+		t.Fatalf("DownloadByStrategy invalid = %q/%v", response, err)
+	}
+	if response, err := DownloadByStrategy(`{"use_extensions":false}`); err != nil || !strings.Contains(response, "disabled") {
+		t.Fatalf("DownloadByStrategy disabled = %q/%v", response, err)
+	}
+	if response, err := DownloadWithFallback(`{}`); err != nil || !strings.Contains(response, "retired") {
+		t.Fatalf("DownloadWithFallback = %q/%v", response, err)
+	}
+
+	InitItemProgress("item-1")
+	FinishItemProgress("item-1")
+	ClearItemProgress("item-1")
+	CancelDownload("item-1")
+	if GetDownloadProgress() == "" || GetAllDownloadProgress() == "" || GetAllDownloadProgressDelta(0) == "" {
+		t.Fatal("expected progress JSON")
+	}
+	CleanupConnections()
+
+	cuePath, audioPath := writeExportCueFixture(t, dir)
+	if jsonText, err := ParseCueSheet(cuePath, ""); err != nil {
+		t.Fatalf("ParseCueSheet = %q/%v", jsonText, err)
+	} else {
+		var parsed CueSplitInfo
+		if err := json.Unmarshal([]byte(jsonText), &parsed); err != nil {
+			t.Fatalf("decode ParseCueSheet: %v", err)
+		}
+		if parsed.AudioPath != audioPath {
+			t.Fatalf("ParseCueSheet audio path = %q want %q", parsed.AudioPath, audioPath)
+		}
+	}
+	if jsonText, err := ScanCueSheetForLibrary(cuePath, "", "virtual.cue", 111); err != nil || !strings.Contains(jsonText, "cue+wav") {
+		t.Fatalf("ScanCueSheetForLibrary = %q/%v", jsonText, err)
+	}
+	if jsonText, err := ScanCueSheetForLibraryWithCoverCacheKey(cuePath, "", "virtual.cue", 111, "cover-key"); err != nil || !strings.Contains(jsonText, "cue+wav") {
+		t.Fatalf("ScanCueSheetForLibraryWithCoverCacheKey = %q/%v", jsonText, err)
+	}
+
+	apePath := filepath.Join(dir, "edit.ape")
+	if err := os.WriteFile(apePath, []byte("audio"), 0600); err != nil {
+		t.Fatal(err)
+	}
+	editJSON := `{"title":"Edited","artist":"Artist","track_number":"1","track_total":"2","disc_number":"1","disc_total":"1"}`
+	if response, err := EditFileMetadata(apePath, editJSON); err != nil || !strings.Contains(response, "native_ape") {
+		t.Fatalf("EditFileMetadata ape = %q/%v", response, err)
+	}
+	if response, err := EditFileMetadata(filepath.Join(dir, "edit.mp3"), editJSON); err != nil || !strings.Contains(response, "ffmpeg") {
+		t.Fatalf("EditFileMetadata ffmpeg = %q/%v", response, err)
+	}
+	misnamedM4APath := filepath.Join(dir, "misnamed.flac")
+	if err := os.WriteFile(misnamedM4APath, buildM4AFileWithIlst(buildM4ATextTag("\xa9nam", "Misnamed"), true), 0600); err != nil {
+		t.Fatal(err)
+	}
+	replayGainJSON := `{"replaygain_track_gain":"-1 dB","replaygain_track_peak":"0.9"}`
+	if response, err := EditFileMetadata(misnamedM4APath, replayGainJSON); err != nil || !strings.Contains(response, "native_m4a_replaygain") {
+		t.Fatalf("EditFileMetadata misnamed m4a replaygain = %q/%v", response, err)
+	}
+	if _, err := EditFileMetadata(apePath, `not-json`); err == nil {
+		t.Fatal("expected invalid metadata JSON")
+	}
+	if !hasOnlyM4AReplayGainFields(map[string]string{"replaygain_track_gain": "-1 dB"}) {
+		t.Fatal("expected replaygain-only fields")
+	}
+	if hasOnlyM4AReplayGainFields(map[string]string{"title": "Song"}) {
+		t.Fatal("expected non-replaygain field rejection")
+	}
+
+	AllowDownloadDir(dir)
+	if err := SetDownloadDirectory(dir); err != nil {
+		t.Fatalf("SetDownloadDirectory: %v", err)
+	}
+	if duplicateJSON, err := CheckDuplicate(dir, ""); err != nil || !strings.Contains(duplicateJSON, "exists") {
+		t.Fatalf("CheckDuplicate = %q/%v", duplicateJSON, err)
+	}
+	if batchJSON, err := CheckDuplicatesBatch(dir, `[{"isrc":"","track_name":"Song","artist_name":"Artist"}]`); err != nil || !strings.Contains(batchJSON, "Song") {
+		t.Fatalf("CheckDuplicatesBatch = %q/%v", batchJSON, err)
+	}
+	_ = PreBuildDuplicateIndex(dir)
+	InvalidateDuplicateIndex(dir)
+	if filename, err := BuildFilename("{artist} - {title}", `{"artist":"A/B","title":"Song?"}`); err != nil || filename == "" {
+		t.Fatalf("BuildFilename = %q/%v", filename, err)
+	}
+	if _, err := BuildFilename("{title}", `not-json`); err == nil {
+		t.Fatal("expected BuildFilename JSON error")
+	}
+	if got := SanitizeFilename(`A/B:C*D?`); strings.ContainsAny(got, `/:*?`) {
+		t.Fatalf("SanitizeFilename = %q", got)
+	}
+
+	if response, err := PreWarmTrackCacheJSON(`not-json`); err != nil || !strings.Contains(response, "Invalid JSON") {
+		t.Fatalf("PreWarmTrackCacheJSON invalid = %q/%v", response, err)
+	}
+	if response, err := PreWarmTrackCacheJSON(`[{"isrc":"ISRC","track_name":"Song","artist_name":"Artist"}]`); err != nil || !strings.Contains(response, "success") {
+		t.Fatalf("PreWarmTrackCacheJSON = %q/%v", response, err)
+	}
+	if GetTrackCacheSize() != 0 {
+		t.Fatal("expected empty track cache")
+	}
+	ClearTrackIDCache()
+
+	if err := SetLyricsProvidersJSON(`["lrclib","apple_music"]`); err != nil {
+		t.Fatalf("SetLyricsProvidersJSON: %v", err)
+	}
+	if providers, err := GetLyricsProvidersJSON(); err != nil || !strings.Contains(providers, "lrclib") {
+		t.Fatalf("GetLyricsProvidersJSON = %q/%v", providers, err)
+	}
+	if available, err := GetAvailableLyricsProvidersJSON(); err != nil || available == "" {
+		t.Fatalf("GetAvailableLyricsProvidersJSON = %q/%v", available, err)
+	}
+	if err := SetLyricsFetchOptionsJSON(`{"include_translation_netease":true}`); err != nil {
+		t.Fatalf("SetLyricsFetchOptionsJSON: %v", err)
+	}
+	if opts, err := GetLyricsFetchOptionsJSON(); err != nil || opts == "" {
+		t.Fatalf("GetLyricsFetchOptionsJSON = %q/%v", opts, err)
+	}
+
+	if err := SetProviderPriorityJSON(`["coverage-ext"]`); err != nil {
+		t.Fatalf("SetProviderPriorityJSON: %v", err)
+	}
+	if jsonText, err := GetProviderPriorityJSON(); err != nil || !strings.Contains(jsonText, "coverage-ext") {
+		t.Fatalf("GetProviderPriorityJSON = %q/%v", jsonText, err)
+	}
+	if err := SetExtensionFallbackProviderIDsJSON(`["coverage-ext"]`); err != nil {
+		t.Fatalf("SetExtensionFallbackProviderIDsJSON: %v", err)
+	}
+	if jsonText, err := GetExtensionFallbackProviderIDsJSON(); err != nil || !strings.Contains(jsonText, "coverage-ext") {
+		t.Fatalf("GetExtensionFallbackProviderIDsJSON = %q/%v", jsonText, err)
+	}
+	if err := SetExtensionFallbackProviderIDsJSON(""); err != nil {
+		t.Fatalf("reset extension fallback IDs: %v", err)
+	}
+	if err := SetMetadataProviderPriorityJSON(`["coverage-ext"]`); err != nil {
+		t.Fatalf("SetMetadataProviderPriorityJSON: %v", err)
+	}
+	if jsonText, err := GetMetadataProviderPriorityJSON(); err != nil || !strings.Contains(jsonText, "coverage-ext") {
+		t.Fatalf("GetMetadataProviderPriorityJSON = %q/%v", jsonText, err)
+	}
+
+	if err := SetExtensionSettingsJSON(ext.ID, `{"quality":"lossless","_secret":"hidden"}`); err != nil {
+		t.Fatalf("SetExtensionSettingsJSON: %v", err)
+	}
+	if settingsJSON, err := GetExtensionSettingsJSON(ext.ID); err != nil || !strings.Contains(settingsJSON, "quality") {
+		t.Fatalf("GetExtensionSettingsJSON = %q/%v", settingsJSON, err)
+	}
+	if err := SetExtensionSettingsJSON(ext.ID, `not-json`); err == nil {
+		t.Fatal("expected settings JSON error")
+	}
+
+	if jsonText, err := SearchTracksWithExtensionsJSON("song", 5); err != nil || !strings.Contains(jsonText, "search-1") {
+		t.Fatalf("SearchTracksWithExtensionsJSON = %q/%v", jsonText, err)
+	}
+	if jsonText, err := SearchTracksWithMetadataProvidersJSON("song", 5, true); err != nil || !strings.Contains(jsonText, "search-1") {
+		t.Fatalf("SearchTracksWithMetadataProvidersJSON = %q/%v", jsonText, err)
+	}
+	if jsonText, err := GetProviderMetadataJSON(ext.ID, "track", "track-1"); err != nil || !strings.Contains(jsonText, "Track track-1") {
+		t.Fatalf("GetProviderMetadataJSON track = %q/%v", jsonText, err)
+	}
+	for _, resourceType := range []string{"album", "playlist", "artist"} {
+		if jsonText, err := GetProviderMetadataJSON(ext.ID, resourceType, resourceType+"-1"); err != nil || jsonText == "" {
+			t.Fatalf("GetProviderMetadataJSON %s = %q/%v", resourceType, jsonText, err)
+		}
+	}
+	if _, err := GetProviderMetadataJSON("", "track", "id"); err == nil {
+		t.Fatal("expected empty provider ID error")
+	}
+	if _, err := GetProviderMetadataJSON(ext.ID, "unsupported", "id"); err == nil {
+		t.Fatal("expected unsupported provider type")
+	}
+	if firstNonEmptyTrimmed(" ", " value ") != "value" {
+		t.Fatal("expected first trimmed value")
+	}
+	requestJSON := `{"use_extensions":true,"use_fallback":false,"service":"coverage-ext","source":"coverage-ext","track_name":"Song","artist_name":"Artist","album_name":"Album","output_dir":"` + escapeJSONPath(dir) + `","output_ext":".flac","quality":"LOSSLESS"}`
+	if jsonText, err := DownloadWithExtensionsJSON(requestJSON); err != nil || !strings.Contains(jsonText, "coverage-ext") {
+		t.Fatalf("DownloadWithExtensionsJSON = %q/%v", jsonText, err)
+	}
+	if _, err := DownloadWithExtensionsJSON(`not-json`); err == nil {
+		t.Fatal("expected DownloadWithExtensionsJSON JSON error")
+	}
+
+	SetExtensionAuthCodeByID(ext.ID, "code")
+	SetExtensionTokensByID(ext.ID, "access", "refresh", 60)
+	if !IsExtensionAuthenticatedByID(ext.ID) {
+		t.Fatal("expected authenticated extension")
+	}
+	if pending, err := GetExtensionPendingAuthJSON(ext.ID); err != nil || pending != "" {
+		t.Fatalf("GetExtensionPendingAuthJSON = %q/%v", pending, err)
+	}
+	ClearExtensionPendingAuthByID(ext.ID)
+	if all, err := GetAllPendingAuthRequestsJSON(); err != nil || all == "" {
+		t.Fatalf("GetAllPendingAuthRequestsJSON = %q/%v", all, err)
+	}
+
+	ffmpegCommandsMu.Lock()
+	ffmpegCommands["cmd-1"] = &FFmpegCommand{ExtensionID: ext.ID, Command: "ffmpeg -version", InputPath: "in", OutputPath: "out"}
+	ffmpegCommandsMu.Unlock()
+	if cmdJSON, err := GetPendingFFmpegCommandJSON("cmd-1"); err != nil || !strings.Contains(cmdJSON, "cmd-1") {
+		t.Fatalf("GetPendingFFmpegCommandJSON = %q/%v", cmdJSON, err)
+	}
+	if all, err := GetAllPendingFFmpegCommandsJSON(); err != nil || !strings.Contains(all, "cmd-1") {
+		t.Fatalf("GetAllPendingFFmpegCommandsJSON = %q/%v", all, err)
+	}
+	SetFFmpegCommandResultByID("cmd-1", true, "ok", "")
+	ClearFFmpegCommand("cmd-1")
+	if empty, err := GetPendingFFmpegCommandJSON("missing"); err != nil || empty != "" {
+		t.Fatalf("missing ffmpeg = %q/%v", empty, err)
+	}
+
+	enrichedJSON, err := EnrichTrackWithExtensionJSON(ext.ID, `{"id":"track-1","name":"Old","artists":"Artist"}`)
+	if err != nil || !strings.Contains(enrichedJSON, "Enriched") {
+		t.Fatalf("EnrichTrackWithExtensionJSON = %q/%v", enrichedJSON, err)
+	}
+	if sameJSON, err := EnrichTrackWithExtensionJSON("missing", `{"name":"Old"}`); err != nil || !strings.Contains(sameJSON, "Old") {
+		t.Fatalf("missing EnrichTrackWithExtensionJSON = %q/%v", sameJSON, err)
+	}
+
+	deezerClient = &DeezerClient{
+		httpClient: &http.Client{Transport: roundTripFunc(func(req *http.Request) (*http.Response, error) {
+			body := fakeDeezerResponse(req.URL.Path, req.URL.RawQuery)
+			status := http.StatusOK
+			if body == "" {
+				status = http.StatusNotFound
+				body = `{"error":"missing"}`
+			}
+			return &http.Response{StatusCode: status, Header: make(http.Header), Body: io.NopCloser(strings.NewReader(body)), Request: req}, nil
+		})},
+		searchCache:          map[string]*cacheEntry{},
+		albumCache:           map[string]*cacheEntry{},
+		artistCache:          map[string]*cacheEntry{},
+		isrcCache:            map[string]string{},
+		cacheCleanupInterval: time.Hour,
+	}
+	deezerClientOnce.Do(func() {})
+	for _, item := range []struct {
+		typ string
+		id  string
+	}{
+		{"track", "101"},
+		{"album", "201"},
+		{"artist", "301"},
+		{"playlist", "401"},
+	} {
+		if jsonText, err := GetDeezerMetadata(item.typ, item.id); err != nil || jsonText == "" {
+			t.Fatalf("GetDeezerMetadata %s = %q/%v", item.typ, jsonText, err)
+		}
+	}
+	if _, err := GetDeezerMetadata("bad", "1"); err == nil {
+		t.Fatal("expected unsupported Deezer metadata type")
+	}
+	if jsonText, err := GetDeezerRelatedArtists("301", 2); err != nil || !strings.Contains(jsonText, "Related") {
+		t.Fatalf("GetDeezerRelatedArtists = %q/%v", jsonText, err)
+	}
+	if jsonText, err := GetDeezerExtendedMetadata("101"); err != nil || !strings.Contains(jsonText, "Label") {
+		t.Fatalf("GetDeezerExtendedMetadata = %q/%v", jsonText, err)
+	}
+	if _, err := GetDeezerExtendedMetadata(""); err == nil {
+		t.Fatal("expected empty Deezer metadata ID error")
+	}
+	if jsonText, err := SearchDeezerByISRC("USRC17607839"); err != nil || !strings.Contains(jsonText, "deezer:101") {
+		t.Fatalf("SearchDeezerByISRC = %q/%v", jsonText, err)
+	}
+	if jsonText, err := SearchDeezerByISRCForItemID("USRC17607839", "item-isrc"); err != nil || !strings.Contains(jsonText, "deezer:101") {
+		t.Fatalf("SearchDeezerByISRCForItemID = %q/%v", jsonText, err)
+	}
+
+	customJSON, err := CustomSearchWithExtensionJSON(ext.ID, "needle", `{"filter":"tracks"}`)
+	if err != nil || !strings.Contains(customJSON, "Custom needle") {
+		t.Fatalf("CustomSearchWithExtensionJSON = %q/%v", customJSON, err)
+	}
+	if customJSON, err := CustomSearchWithExtensionJSONWithRequestID(ext.ID, "needle", `not-json`, "req-custom"); err != nil || !strings.Contains(customJSON, "custom-1") {
+		t.Fatalf("CustomSearchWithExtensionJSONWithRequestID = %q/%v", customJSON, err)
+	}
+	if providersJSON, err := GetSearchProvidersJSON(); err != nil || !strings.Contains(providersJSON, "coverage-ext") {
+		t.Fatalf("GetSearchProvidersJSON = %q/%v", providersJSON, err)
+	}
+	if found := FindURLHandlerJSON("https://example.test/track/1"); found != ext.ID {
+		t.Fatalf("FindURLHandlerJSON = %q", found)
+	}
+	if handlersJSON, err := GetURLHandlersJSON(); err != nil || !strings.Contains(handlersJSON, "coverage-ext") {
+		t.Fatalf("GetURLHandlersJSON = %q/%v", handlersJSON, err)
+	}
+	if handledJSON, err := HandleURLWithExtensionJSON("https://example.test/track/1"); err != nil || !strings.Contains(handledJSON, "url-track") {
+		t.Fatalf("HandleURLWithExtensionJSON = %q/%v", handledJSON, err)
+	}
+	if postJSON, err := RunPostProcessingJSON(filepath.Join(dir, "song.flac"), `{"title":"Song"}`); err != nil || !strings.Contains(postJSON, "success") {
+		t.Fatalf("RunPostProcessingJSON = %q/%v", postJSON, err)
+	}
+	v2Input := `{"path":"` + escapeJSONPath(filepath.Join(dir, "song.flac")) + `","uri":"content://song","name":"song.flac","mime_type":"audio/flac","size":10}`
+	if postJSON, err := RunPostProcessingV2JSON(v2Input, `not-json`); err != nil || !strings.Contains(postJSON, "success") {
+		t.Fatalf("RunPostProcessingV2JSON = %q/%v", postJSON, err)
+	}
+	if postProviders, err := GetPostProcessingProvidersJSON(); err != nil || !strings.Contains(postProviders, "hook") {
+		t.Fatalf("GetPostProcessingProvidersJSON = %q/%v", postProviders, err)
+	}
+	if feedJSON, err := GetExtensionHomeFeedJSON(ext.ID); err != nil || !strings.Contains(feedJSON, "home-1") {
+		t.Fatalf("GetExtensionHomeFeedJSON = %q/%v", feedJSON, err)
+	}
+	if feedJSON, err := GetExtensionHomeFeedJSONWithRequestID(ext.ID, "req-home"); err != nil || !strings.Contains(feedJSON, "home-1") {
+		t.Fatalf("GetExtensionHomeFeedJSONWithRequestID = %q/%v", feedJSON, err)
+	}
+	if categoriesJSON, err := GetExtensionBrowseCategoriesJSON(ext.ID); err != nil || !strings.Contains(categoriesJSON, "cat-1") {
+		t.Fatalf("GetExtensionBrowseCategoriesJSON = %q/%v", categoriesJSON, err)
+	}
+	CancelExtensionRequestJSON("req-home")
+
+	storeDir := filepath.Join(dir, "store")
+	if err := InitExtensionStoreJSON(storeDir); err != nil {
+		t.Fatalf("InitExtensionStoreJSON: %v", err)
+	}
+	if err := SetStoreRegistryURLJSON("https://registry.example.com/index.json"); err != nil {
+		t.Fatalf("SetStoreRegistryURLJSON: %v", err)
+	}
+	store := getExtensionStore()
+	store.cache = &storeRegistry{Extensions: []storeExtension{{
+		ID:          "coverage-ext",
+		Name:        "coverage-ext",
+		Version:     "1.0.0",
+		Description: "Coverage",
+		Category:    CategoryMetadata,
+		Tags:        []string{"metadata"},
+		DownloadURL: "https://registry.example.com/coverage.spotiflac-ext",
+	}}}
+	store.cacheTime = time.Now()
+	if registryURL, err := GetStoreRegistryURLJSON(); err != nil || registryURL == "" {
+		t.Fatalf("GetStoreRegistryURLJSON = %q/%v", registryURL, err)
+	}
+	if storeJSON, err := GetStoreExtensionsJSON(false); err != nil || !strings.Contains(storeJSON, "coverage-ext") {
+		t.Fatalf("GetStoreExtensionsJSON = %q/%v", storeJSON, err)
+	}
+	if storeJSON, err := SearchStoreExtensionsJSON("coverage", CategoryMetadata); err != nil || !strings.Contains(storeJSON, "coverage-ext") {
+		t.Fatalf("SearchStoreExtensionsJSON = %q/%v", storeJSON, err)
+	}
+	if catsJSON, err := GetStoreCategoriesJSON(); err != nil || !strings.Contains(catsJSON, "metadata") {
+		t.Fatalf("GetStoreCategoriesJSON = %q/%v", catsJSON, err)
+	}
+	if dest, err := buildStoreExtensionDestPath(
+		dir,
+		"coverage/ext",
+		"https://registry.example.com/coverage.spotiflac-ext",
+	); err != nil || !strings.HasSuffix(dest, ".spotiflac-ext") {
+		t.Fatalf("buildStoreExtensionDestPath = %q/%v", dest, err)
+	}
+	if dest, err := buildStoreExtensionDestPath(
+		dir,
+		"coverage/ext",
+		"https://registry.example.com/coverage.sflx",
+	); err != nil || !strings.HasSuffix(dest, ".sflx") {
+		t.Fatalf("buildStoreExtensionDestPath sflx = %q/%v", dest, err)
+	}
+	if _, err := buildStoreExtensionDestPath(
+		dir,
+		" ",
+		"https://registry.example.com/coverage.sflx",
+	); err == nil {
+		t.Fatal("expected invalid extension id")
+	}
+	if err := ClearStoreCacheJSON(); err != nil {
+		t.Fatalf("ClearStoreCacheJSON: %v", err)
+	}
+	if err := ClearStoreRegistryURLJSON(); err != nil {
+		t.Fatalf("ClearStoreRegistryURLJSON: %v", err)
+	}
+
+	SetLibraryCoverCacheDirJSON(filepath.Join(dir, "covers"))
+	libraryDir := filepath.Join(dir, "library")
+	if err := os.MkdirAll(libraryDir, 0755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(libraryDir, "Artist - Song.mp3"), []byte("not mp3"), 0600); err != nil {
+		t.Fatal(err)
+	}
+	if scanJSON, err := ScanLibraryFolderJSON(libraryDir); err != nil || !strings.Contains(scanJSON, "Song") {
+		t.Fatalf("ScanLibraryFolderJSON = %q/%v", scanJSON, err)
+	}
+	if scanJSON, err := ScanLibraryFolderIncrementalJSON(libraryDir, `[]`); err != nil || !strings.Contains(scanJSON, "Song") {
+		t.Fatalf("ScanLibraryFolderIncrementalJSON = %q/%v", scanJSON, err)
+	}
+	snapshotPath := filepath.Join(dir, "snapshot.json")
+	if err := os.WriteFile(snapshotPath, []byte(`[]`), 0600); err != nil {
+		t.Fatal(err)
+	}
+	if scanJSON, err := ScanLibraryFolderIncrementalFromSnapshotJSON(libraryDir, snapshotPath); err != nil || !strings.Contains(scanJSON, "Song") {
+		t.Fatalf("ScanLibraryFolderIncrementalFromSnapshotJSON = %q/%v", scanJSON, err)
+	}
+	if GetLibraryScanProgressJSON() == "" {
+		t.Fatal("expected scan progress JSON")
+	}
+	CancelLibraryScanJSON()
+	if metadataJSON, err := ReadAudioMetadataJSON(filepath.Join(libraryDir, "missing.mp3")); err != nil || metadataJSON == "" {
+		t.Fatalf("ReadAudioMetadataJSON = %q/%v", metadataJSON, err)
+	}
+	if metadataJSON, err := ReadAudioMetadataWithHintJSON(filepath.Join(libraryDir, "missing.mp3"), "Missing"); err != nil || metadataJSON == "" {
+		t.Fatalf("ReadAudioMetadataWithHintJSON = %q/%v", metadataJSON, err)
+	}
+	if metadataJSON, err := ReadAudioMetadataWithHintAndCoverCacheKeyJSON(filepath.Join(libraryDir, "missing.mp3"), "Missing", "key"); err != nil || metadataJSON == "" {
+		t.Fatalf("ReadAudioMetadataWithHintAndCoverCacheKeyJSON = %q/%v", metadataJSON, err)
+	}
+}
@@ -0,0 +1,609 @@
+package gobackend
+
+import (
+	"context"
+	"fmt"
+	"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 TestSelectMusicBrainzAlbumArtistPrefersMatchingRelease(t *testing.T) {
+	releases := []musicBrainzRelease{
+		{
+			Title: "Other Album",
+			ArtistCredit: []musicBrainzArtistCredit{
+				{Name: "Wrong Artist"},
+			},
+		},
+		{
+			Title: "Target Album",
+			ArtistCredit: []musicBrainzArtistCredit{
+				{Name: "Artist A", JoinPhrase: " & "},
+				{Name: "Artist B"},
+			},
+		},
+	}
+
+	got := selectMusicBrainzAlbumArtist(releases, "Target Album")
+	if got != "Artist A & Artist B" {
+		t.Fatalf("album artist = %q, want matching release artist credit", got)
+	}
+}
+
+func TestEnrichRequestExtendedMetadataUsesMusicBrainzAlbumArtist(t *testing.T) {
+	origDeezerFetcher := fetchDeezerExtendedMetadataByISRC
+	origMusicBrainzGenreFetcher := fetchMusicBrainzGenreByISRC
+	origMusicBrainzAlbumArtistFetcher := fetchMusicBrainzAlbumArtistByISRC
+	defer func() {
+		fetchDeezerExtendedMetadataByISRC = origDeezerFetcher
+		fetchMusicBrainzGenreByISRC = origMusicBrainzGenreFetcher
+		fetchMusicBrainzAlbumArtistByISRC = origMusicBrainzAlbumArtistFetcher
+	}()
+
+	fetchDeezerExtendedMetadataByISRC = func(ctx context.Context, isrc string) (*AlbumExtendedMetadata, error) {
+		return &AlbumExtendedMetadata{}, nil
+	}
+	fetchMusicBrainzGenreByISRC = func(isrc string) (string, error) {
+		return "", fmt.Errorf("no genre")
+	}
+	fetchMusicBrainzAlbumArtistByISRC = func(isrc string, albumName string) (string, error) {
+		if isrc != "TESTISRC" || albumName != "Target Album" {
+			t.Fatalf("unexpected MusicBrainz args: %q / %q", isrc, albumName)
+		}
+		return "MusicBrainz Album Artist", nil
+	}
+
+	req := DownloadRequest{
+		ISRC:       "TESTISRC",
+		ArtistName: "Track Artist",
+		AlbumName:  "Target Album",
+	}
+
+	enrichRequestExtendedMetadata(&req)
+
+	if req.AlbumArtist != "MusicBrainz Album Artist" {
+		t.Fatalf("album artist = %q, want MusicBrainz value", req.AlbumArtist)
+	}
+}
+
+func TestEnrichRequestExtendedMetadataDoesNotFallbackAlbumArtistToTrackArtist(t *testing.T) {
+	origDeezerFetcher := fetchDeezerExtendedMetadataByISRC
+	origMusicBrainzGenreFetcher := fetchMusicBrainzGenreByISRC
+	origMusicBrainzAlbumArtistFetcher := fetchMusicBrainzAlbumArtistByISRC
+	defer func() {
+		fetchDeezerExtendedMetadataByISRC = origDeezerFetcher
+		fetchMusicBrainzGenreByISRC = origMusicBrainzGenreFetcher
+		fetchMusicBrainzAlbumArtistByISRC = origMusicBrainzAlbumArtistFetcher
+	}()
+
+	fetchDeezerExtendedMetadataByISRC = func(ctx context.Context, isrc string) (*AlbumExtendedMetadata, error) {
+		return &AlbumExtendedMetadata{}, nil
+	}
+	fetchMusicBrainzGenreByISRC = func(isrc string) (string, error) {
+		return "", fmt.Errorf("no genre")
+	}
+	fetchMusicBrainzAlbumArtistByISRC = func(isrc string, albumName string) (string, error) {
+		return "", fmt.Errorf("no album artist")
+	}
+
+	req := DownloadRequest{
+		ISRC:       "TESTISRC",
+		ArtistName: "Track Artist",
+		AlbumName:  "Target Album",
+	}
+
+	enrichRequestExtendedMetadata(&req)
+
+	if req.AlbumArtist != "" {
+		t.Fatalf("album artist = %q, want empty when MusicBrainz has no value", req.AlbumArtist)
+	}
+}
+
+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 TestSelectBestReEnrichTrackRejectsMismatchedSearchResults(t *testing.T) {
+	req := reEnrichRequest{
+		TrackName:  "Song Title",
+		ArtistName: "Artist Name",
+		AlbumName:  "Album Name",
+		DurationMs: 180000,
+	}
+
+	tracks := []ExtTrackMetadata{
+		{
+			ID:          "wrong-rich-metadata",
+			Name:        "Different Song",
+			Artists:     "Different Artist",
+			AlbumName:   "Album Name",
+			DurationMS:  180000,
+			ReleaseDate: "2024-03-09",
+			TrackNumber: 4,
+			DiscNumber:  1,
+			ISRC:        "WRONG1234567",
+			ProviderID:  "deezer",
+		},
+	}
+
+	if best := selectBestReEnrichTrack(req, tracks); best != nil {
+		t.Fatalf("selected track = %q, want no match", best.ID)
+	}
+}
+
+func TestSelectBestReEnrichTrackAllowsExactISRCDespiteMetadataMismatch(t *testing.T) {
+	req := reEnrichRequest{
+		TrackName:  "Song Title",
+		ArtistName: "Artist Name",
+		ISRC:       "USRC17607839",
+		DurationMs: 999999000,
+	}
+
+	tracks := []ExtTrackMetadata{
+		{
+			ID:         "same-isrc",
+			Name:       "Different Song",
+			Artists:    "Different Artist",
+			DurationMS: 180000,
+			ISRC:       "USRC17607839",
+			ProviderID: "deezer",
+		},
+	}
+
+	best := selectBestReEnrichTrack(req, tracks)
+	if best == nil {
+		t.Fatal("expected exact ISRC candidate to be selected")
+	}
+	if best.ID != "same-isrc" {
+		t.Fatalf("selected track = %q, want exact ISRC candidate", best.ID)
+	}
+}
+
+func TestSelectBestReEnrichTrackPlaceholderFallsBackToAlbum(t *testing.T) {
+	req := reEnrichRequest{
+		TrackName:  "Unknown Title",
+		ArtistName: "Unknown Artist",
+		AlbumName:  "Harry Styles",
+		DurationMs: 180000,
+	}
+
+	tracks := []ExtTrackMetadata{
+		{
+			ID:         "album-match",
+			Name:       "Sign of the Times",
+			Artists:    "Harry Styles",
+			AlbumName:  "Harry Styles",
+			DurationMS: 180000,
+			ProviderID: "deezer",
+		},
+	}
+
+	best := selectBestReEnrichTrack(req, tracks)
+	if best == nil {
+		t.Fatal("expected album-matching candidate to be selected when title/artist are placeholders")
+	}
+	if best.ID != "album-match" {
+		t.Fatalf("selected track = %q, want album-match", 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"])
+	}
+}
@@ -0,0 +1,459 @@
+package gobackend
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"strings"
+	"sync"
+	"time"
+)
+
+const (
+	extensionHealthDefaultTimeout = 4 * time.Second
+	extensionHealthMaxBodyBytes   = 64 * 1024
+	extensionHealthDefaultCache   = 10 * time.Minute
+	extensionHealthMinCache       = 60 * time.Second
+	extensionHealthUnknownCache   = 2 * time.Minute
+)
+
+type ExtensionHealthResult struct {
+	ExtensionID string                       `json:"extension_id"`
+	Status      string                       `json:"status"`
+	CheckedAt   string                       `json:"checked_at"`
+	Checks      []ExtensionHealthCheckResult `json:"checks"`
+}
+
+type ExtensionHealthCheckResult struct {
+	ID         string `json:"id"`
+	Label      string `json:"label,omitempty"`
+	URL        string `json:"url"`
+	Method     string `json:"method"`
+	ServiceKey string `json:"service_key,omitempty"`
+	Required   bool   `json:"required"`
+	Status     string `json:"status"`
+	HTTPStatus int    `json:"http_status,omitempty"`
+	LatencyMs  int64  `json:"latency_ms"`
+	Message    string `json:"message,omitempty"`
+	Error      string `json:"error,omitempty"`
+	CheckedAt  string `json:"checked_at"`
+}
+
+type cachedExtensionHealthResult struct {
+	result    ExtensionHealthResult
+	expiresAt time.Time
+}
+
+var (
+	extensionHealthCacheMu sync.Mutex
+	extensionHealthCache   = map[string]cachedExtensionHealthResult{}
+)
+
+func CheckExtensionHealthJSON(extensionID string) (string, error) {
+	manager := getExtensionManager()
+	ext, err := manager.GetExtension(extensionID)
+	if err != nil {
+		return "", err
+	}
+
+	result := CheckExtensionHealth(ext)
+	cacheExtensionHealthResult(ext, result)
+	bytes, err := json.Marshal(result)
+	if err != nil {
+		return "", err
+	}
+	return string(bytes), nil
+}
+
+func CheckExtensionHealthCached(ext *loadedExtension) ExtensionHealthResult {
+	if ext == nil || ext.Manifest == nil || len(ext.Manifest.ServiceHealth) == 0 {
+		return CheckExtensionHealth(ext)
+	}
+
+	cacheKey := strings.TrimSpace(ext.ID)
+	if cacheKey == "" {
+		return CheckExtensionHealth(ext)
+	}
+
+	now := time.Now()
+	extensionHealthCacheMu.Lock()
+	cached, ok := extensionHealthCache[cacheKey]
+	if ok && now.Before(cached.expiresAt) {
+		extensionHealthCacheMu.Unlock()
+		return cached.result
+	}
+	extensionHealthCacheMu.Unlock()
+
+	result := CheckExtensionHealth(ext)
+	cacheExtensionHealthResult(ext, result)
+	return result
+}
+
+func cacheExtensionHealthResult(ext *loadedExtension, result ExtensionHealthResult) {
+	if ext == nil || ext.Manifest == nil || len(ext.Manifest.ServiceHealth) == 0 {
+		return
+	}
+
+	cacheKey := strings.TrimSpace(ext.ID)
+	if cacheKey == "" {
+		return
+	}
+
+	ttl := extensionHealthCacheTTL(ext.Manifest.ServiceHealth)
+	if result.Status == "unknown" && ttl > extensionHealthUnknownCache {
+		ttl = extensionHealthUnknownCache
+	}
+
+	extensionHealthCacheMu.Lock()
+	extensionHealthCache[cacheKey] = cachedExtensionHealthResult{
+		result:    result,
+		expiresAt: time.Now().Add(ttl),
+	}
+	extensionHealthCacheMu.Unlock()
+}
+
+func CheckExtensionHealth(ext *loadedExtension) ExtensionHealthResult {
+	now := time.Now().UTC().Format(time.RFC3339)
+	result := ExtensionHealthResult{
+		ExtensionID: "",
+		Status:      "unsupported",
+		CheckedAt:   now,
+		Checks:      []ExtensionHealthCheckResult{},
+	}
+	if ext == nil || ext.Manifest == nil {
+		result.Status = "offline"
+		return result
+	}
+
+	result.ExtensionID = ext.ID
+	checks := ext.Manifest.ServiceHealth
+	if len(checks) == 0 {
+		return result
+	}
+
+	result.Status = "online"
+	for _, check := range checks {
+		checkResult := runExtensionHealthCheck(ext.Manifest, check)
+		result.Checks = append(result.Checks, checkResult)
+
+		switch checkResult.Status {
+		case "offline":
+			if check.Required {
+				result.Status = "offline"
+			} else if result.Status == "online" {
+				result.Status = "degraded"
+			}
+		case "degraded":
+			if result.Status == "online" {
+				result.Status = "degraded"
+			}
+		case "unknown":
+			if result.Status == "online" {
+				result.Status = "unknown"
+			}
+		}
+	}
+
+	return result
+}
+
+func extensionHealthCacheTTL(checks []ExtensionHealthCheck) time.Duration {
+	ttl := extensionHealthDefaultCache
+	for _, check := range checks {
+		if check.CacheTTLSeconds <= 0 {
+			continue
+		}
+		checkTTL := time.Duration(check.CacheTTLSeconds) * time.Second
+		if checkTTL < extensionHealthMinCache {
+			checkTTL = extensionHealthMinCache
+		}
+		if checkTTL < ttl {
+			ttl = checkTTL
+		}
+	}
+	return ttl
+}
+
+func runExtensionHealthCheck(manifest *ExtensionManifest, check ExtensionHealthCheck) ExtensionHealthCheckResult {
+	method := strings.ToUpper(strings.TrimSpace(check.Method))
+	if method == "" {
+		method = http.MethodGet
+	}
+	now := time.Now().UTC().Format(time.RFC3339)
+	result := ExtensionHealthCheckResult{
+		ID:         check.ID,
+		Label:      check.Label,
+		URL:        check.URL,
+		Method:     method,
+		ServiceKey: strings.TrimSpace(check.ServiceKey),
+		Required:   check.Required,
+		Status:     "unknown",
+		CheckedAt:  now,
+	}
+
+	parsed, err := url.Parse(check.URL)
+	if err != nil {
+		result.Status = "offline"
+		result.Error = fmt.Sprintf("invalid health URL: %v", err)
+		return result
+	}
+	if parsed.Scheme != "https" {
+		result.Status = "offline"
+		result.Error = "health check must use https"
+		return result
+	}
+	host := parsed.Hostname()
+	if host == "" {
+		result.Status = "offline"
+		result.Error = "health check URL hostname is required"
+		return result
+	}
+	if isPrivateIP(host) {
+		result.Status = "offline"
+		result.Error = "private/local health check host is not allowed"
+		return result
+	}
+	if manifest == nil || !manifest.IsDomainAllowed(host) {
+		result.Status = "offline"
+		result.Error = fmt.Sprintf("health check host '%s' is not in extension network permissions", host)
+		return result
+	}
+	if method != http.MethodGet && method != http.MethodHead {
+		result.Status = "offline"
+		result.Error = "health check method must be GET or HEAD"
+		return result
+	}
+
+	timeout := extensionHealthDefaultTimeout
+	if check.TimeoutMs > 0 {
+		timeout = time.Duration(check.TimeoutMs) * time.Millisecond
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), timeout)
+	defer cancel()
+
+	req, err := http.NewRequestWithContext(ctx, method, check.URL, nil)
+	if err != nil {
+		result.Status = "offline"
+		result.Error = err.Error()
+		return result
+	}
+	req.Header.Set("Accept", "application/json")
+	req.Header.Set("User-Agent", userAgentForURL(parsed))
+
+	start := time.Now()
+	resp, err := NewMetadataHTTPClient(timeout).Do(req)
+	result.LatencyMs = time.Since(start).Milliseconds()
+	if err != nil {
+		if isTransientExtensionHealthError(err) {
+			result.Status = "unknown"
+		} else {
+			result.Status = "offline"
+		}
+		result.Error = err.Error()
+		return result
+	}
+	defer resp.Body.Close()
+
+	result.HTTPStatus = resp.StatusCode
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		result.Status = "offline"
+		result.Message = resp.Status
+		return result
+	}
+
+	if method == http.MethodHead {
+		result.Status = "online"
+		result.Message = resp.Status
+		return result
+	}
+
+	body, err := io.ReadAll(io.LimitReader(resp.Body, extensionHealthMaxBodyBytes))
+	if err != nil {
+		result.Status = "degraded"
+		result.Error = err.Error()
+		return result
+	}
+
+	status, message := classifyExtensionHealthBody(body, check.ServiceKey)
+	result.Status = status
+	if message == "" {
+		result.Message = resp.Status
+	} else {
+		result.Message = message
+	}
+	return result
+}
+
+func isTransientExtensionHealthError(err error) bool {
+	return isTransientNetworkError(err) || isConnectivityFailure(err)
+}
+
+func classifyExtensionHealthBody(body []byte, serviceKey string) (string, string) {
+	if len(strings.TrimSpace(string(body))) == 0 {
+		return "online", ""
+	}
+
+	var payload map[string]interface{}
+	if err := json.Unmarshal(body, &payload); err != nil {
+		return "online", ""
+	}
+
+	serviceKey = strings.TrimSpace(serviceKey)
+	if serviceKey != "" {
+		if status, message, ok := classifyExtensionHealthService(payload, serviceKey); ok {
+			return status, message
+		}
+	}
+
+	rawStatus, _ := payload["status"].(string)
+	normalized := strings.ToLower(strings.TrimSpace(rawStatus))
+	switch normalized {
+	case "", "ok", "up", "online", "healthy", "operational", "pass", "passing":
+		return "online", rawStatus
+	case "degraded", "partial", "warning", "warn":
+		return "degraded", rawStatus
+	case "down", "offline", "error", "failed", "fail", "unhealthy":
+		if isTransientHealthStatusMessage(string(body)) {
+			return "unknown", rawStatus
+		}
+		return "offline", rawStatus
+	default:
+		return "online", rawStatus
+	}
+}
+
+func classifyExtensionHealthService(payload map[string]interface{}, serviceKey string) (string, string, bool) {
+	rawServices, ok := payload["services"]
+	if !ok {
+		return "", "", false
+	}
+	services, ok := rawServices.(map[string]interface{})
+	if !ok {
+		return "", "", false
+	}
+	rawService, ok := services[serviceKey]
+	if !ok {
+		return "unknown", fmt.Sprintf("service '%s' not found", serviceKey), true
+	}
+	service, ok := rawService.(map[string]interface{})
+	if !ok {
+		return "unknown", fmt.Sprintf("service '%s' has invalid health payload", serviceKey), true
+	}
+
+	label, _ := service["label"].(string)
+	detail, _ := service["detail"].(string)
+	errText, _ := service["error"].(string)
+	messageParts := []string{}
+	if strings.TrimSpace(label) != "" {
+		messageParts = append(messageParts, strings.TrimSpace(label))
+	}
+	if strings.TrimSpace(detail) != "" {
+		messageParts = append(messageParts, strings.TrimSpace(detail))
+	}
+	if strings.TrimSpace(errText) != "" {
+		messageParts = append(messageParts, strings.TrimSpace(errText))
+	}
+
+	rawStatus, hasStatus := service["status"]
+	okValue, hasOK := service["ok"].(bool)
+	joinedMessage := strings.Join(messageParts, ": ")
+	transient := isTransientHealthStatusMessage(detail) ||
+		isTransientHealthStatusMessage(errText) ||
+		isTransientHealthStatusMessage(label)
+
+	if statusCode, ok := healthNumber(rawStatus); ok {
+		if statusCode >= 200 && statusCode < 300 {
+			return "online", joinedMessage, true
+		}
+		if statusCode == http.StatusUnauthorized || statusCode == http.StatusForbidden {
+			return "degraded", joinedMessage, true
+		}
+		if statusCode == http.StatusInternalServerError && hasOK && okValue {
+			return "online", joinedMessage, true
+		}
+		if transient || isTransientHealthStatusCode(statusCode) {
+			return "unknown", joinedMessage, true
+		}
+		return "offline", joinedMessage, true
+	}
+
+	if isExtensionHealthAuthRequired(detail) {
+		return "degraded", joinedMessage, true
+	}
+	if transient {
+		return "unknown", joinedMessage, true
+	}
+	if hasOK {
+		if okValue {
+			return "online", joinedMessage, true
+		}
+		return "offline", joinedMessage, true
+	}
+	if !hasStatus {
+		return "unknown", joinedMessage, true
+	}
+
+	statusString := strings.ToLower(strings.TrimSpace(fmt.Sprintf("%v", rawStatus)))
+	switch statusString {
+	case "ok", "up", "online", "healthy", "operational":
+		return "online", joinedMessage, true
+	case "degraded", "partial", "warning", "warn":
+		return "degraded", joinedMessage, true
+	case "down", "offline", "error", "failed", "fail", "unhealthy":
+		return "offline", joinedMessage, true
+	default:
+		return "unknown", joinedMessage, true
+	}
+}
+
+func isExtensionHealthAuthRequired(detail string) bool {
+	switch strings.ToLower(strings.TrimSpace(detail)) {
+	case "auth_required", "authorization_required", "login_required", "unauthorized":
+		return true
+	default:
+		return false
+	}
+}
+
+func isTransientHealthStatusMessage(text string) bool {
+	t := strings.ToLower(strings.TrimSpace(text))
+	if t == "" {
+		return false
+	}
+	return strings.Contains(t, "context deadline exceeded") ||
+		strings.Contains(t, "deadline exceeded") ||
+		strings.Contains(t, "timeout") ||
+		strings.Contains(t, "timed out") ||
+		strings.Contains(t, "temporarily unavailable") ||
+		strings.Contains(t, "try again")
+}
+
+func isTransientHealthStatusCode(code int) bool {
+	switch code {
+	case http.StatusRequestTimeout,
+		http.StatusTooManyRequests,
+		http.StatusBadGateway,
+		http.StatusServiceUnavailable,
+		http.StatusGatewayTimeout:
+		return true
+	default:
+		return false
+	}
+}
+
+func healthNumber(value interface{}) (int, bool) {
+	switch v := value.(type) {
+	case float64:
+		return int(v), true
+	case int:
+		return v, true
+	case json.Number:
+		n, err := v.Int64()
+		return int(n), err == nil
+	default:
+		return 0, false
+	}
+}
@@ -0,0 +1,151 @@
+package gobackend
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"net"
+	"net/http"
+	"strings"
+	"testing"
+)
+
+func TestExtensionHealthClassificationAndValidation(t *testing.T) {
+	if status, msg := classifyExtensionHealthBody([]byte(`{"status":"degraded"}`), ""); status != "degraded" || msg != "degraded" {
+		t.Fatalf("status/message = %q/%q", status, msg)
+	}
+	if status, _ := classifyExtensionHealthBody([]byte(`not-json`), ""); status != "online" {
+		t.Fatalf("invalid JSON status = %q", status)
+	}
+	if status, msg := classifyExtensionHealthBody([]byte(`{"services":{"tidal":{"status":401,"label":"Tidal","detail":"auth_required"}}}`), "tidal"); status != "degraded" || !strings.Contains(msg, "Tidal") {
+		t.Fatalf("service status/message = %q/%q", status, msg)
+	}
+	if status, msg, ok := classifyExtensionHealthService(map[string]interface{}{"services": map[string]interface{}{}}, "missing"); !ok || status != "unknown" || !strings.Contains(msg, "missing") {
+		t.Fatalf("missing service = %q/%q/%v", status, msg, ok)
+	}
+	if n, ok := healthNumber(json.Number("503")); !ok || n != 503 {
+		t.Fatalf("health number = %d/%v", n, ok)
+	}
+	if !isExtensionHealthAuthRequired(" unauthorized ") {
+		t.Fatal("expected auth required")
+	}
+	if !isTransientExtensionHealthError(context.DeadlineExceeded) || !isTransientExtensionHealthError(&net.DNSError{IsTimeout: true}) {
+		t.Fatal("expected timeout health errors to be transient")
+	}
+	if !isTransientExtensionHealthError(&net.DNSError{IsNotFound: true}) {
+		t.Fatal("expected health transport lookup errors to be indeterminate")
+	}
+
+	if result := CheckExtensionHealth(nil); result.Status != "offline" {
+		t.Fatalf("nil health = %#v", result)
+	}
+	manifest := &ExtensionManifest{Permissions: ExtensionPermissions{Network: []string{"status.example.com"}}}
+	invalidURL := runExtensionHealthCheck(manifest, ExtensionHealthCheck{ID: "bad", URL: "://bad"})
+	if invalidURL.Status != "offline" {
+		t.Fatalf("invalid URL = %#v", invalidURL)
+	}
+	insecure := runExtensionHealthCheck(manifest, ExtensionHealthCheck{ID: "http", URL: "http://status.example.com"})
+	if insecure.Status != "offline" || !strings.Contains(insecure.Error, "https") {
+		t.Fatalf("insecure = %#v", insecure)
+	}
+	disallowedHost := runExtensionHealthCheck(manifest, ExtensionHealthCheck{ID: "host", URL: "https://other.example.com"})
+	if disallowedHost.Status != "offline" || !strings.Contains(disallowedHost.Error, "permissions") {
+		t.Fatalf("host = %#v", disallowedHost)
+	}
+	badMethod := runExtensionHealthCheck(manifest, ExtensionHealthCheck{ID: "method", URL: "https://status.example.com", Method: "POST"})
+	if badMethod.Status != "offline" || !strings.Contains(badMethod.Error, "method") {
+		t.Fatalf("method = %#v", badMethod)
+	}
+
+	ext := &loadedExtension{
+		ID: "health-ext",
+		Manifest: &ExtensionManifest{
+			ServiceHealth: []ExtensionHealthCheck{
+				{ID: "required", URL: "http://status.example.com", Required: true},
+				{ID: "optional", URL: "http://status.example.com", Required: false},
+			},
+		},
+	}
+	if result := CheckExtensionHealth(ext); result.Status != "offline" || len(result.Checks) != 2 {
+		t.Fatalf("extension health = %#v", result)
+	}
+}
+
+func TestCoverRomajiParallelAndIDHSHelpers(t *testing.T) {
+	spotify := "https://i.scdn.co/image/ab67616d00001e02abcdef"
+	if got := GetCoverFromSpotify(spotify, true); !strings.Contains(got, spotifySizeMax) {
+		t.Fatalf("spotify cover = %q", got)
+	}
+	if got := upgradeToMaxQuality("https://cdn-images.dzcdn.net/images/cover/abc/500x500-000000-80-0-0.jpg"); !strings.Contains(got, "1800x1800") {
+		t.Fatalf("deezer cover = %q", got)
+	}
+	if got := upgradeToMaxQuality("https://resources.tidal.com/images/id/320x320.jpg"); !strings.Contains(got, "origin.jpg") {
+		t.Fatalf("tidal cover = %q", got)
+	}
+	if got := upgradeToMaxQuality("https://static.qobuz.com/images/covers/ab/cd/foo_600.jpg"); !strings.Contains(got, "_max.jpg") {
+		t.Fatalf("qobuz cover = %q", got)
+	}
+	if data, err := downloadCoverToMemory("", false); err == nil || data != nil {
+		t.Fatalf("expected empty cover error")
+	}
+
+	if !ContainsJapanese("カタカナ") || ContainsJapanese("abc") {
+		t.Fatal("unexpected Japanese detection")
+	}
+	if got := JapaneseToRomaji("きゃット"); got != "kyatto" {
+		t.Fatalf("romaji = %q", got)
+	}
+	if got := BuildSearchQuery("きゃ! song", "アーティスト"); got != "atisuto kya song" {
+		t.Fatalf("query = %q", got)
+	}
+	if got := CleanToASCII("A, B. C!"); got != "A B C" {
+		t.Fatalf("ascii = %q", got)
+	}
+
+	if err := PreWarmCache(`not-json`); err == nil {
+		t.Fatal("expected prewarm JSON error")
+	}
+	if err := PreWarmCache(`[{"isrc":"ISRC","track_name":"Song","artist_name":"Artist","spotify_id":"sp","service":"tidal"}]`); err != nil {
+		t.Fatalf("PreWarmCache: %v", err)
+	}
+	if result := FetchCoverAndLyricsParallel("", false, "", "", "", false, 0); result == nil || result.CoverErr != nil || result.LyricsErr != nil {
+		t.Fatalf("parallel result = %#v", result)
+	}
+	if ClearTrackCache(); GetCacheSize() != 0 {
+		t.Fatal("expected empty cache size")
+	}
+
+	client := &IDHSClient{client: &http.Client{Transport: roundTripFunc(func(req *http.Request) (*http.Response, error) {
+		if req.Method != http.MethodPost {
+			t.Fatalf("method = %s", req.Method)
+		}
+		body := `{"id":"1","type":"song","title":"Song","links":[{"type":"tidal","url":"https://tidal.com/browse/track/7"},{"type":"deezer","url":"https://www.deezer.com/track/9"},{"type":"spotify","url":"https://open.spotify.com/track/abc"}]}`
+		return &http.Response{
+			StatusCode: 200,
+			Header:     make(http.Header),
+			Body:       io.NopCloser(strings.NewReader(body)),
+			Request:    req,
+		}, nil
+	})}}
+	availability, err := client.GetAvailabilityFromSpotify("spotify-track")
+	if err != nil {
+		t.Fatalf("GetAvailabilityFromSpotify: %v", err)
+	}
+	if !availability.Tidal || !availability.Deezer || availability.DeezerID != "9" {
+		t.Fatalf("spotify availability = %#v", availability)
+	}
+	deezerAvailability, err := client.GetAvailabilityFromDeezer("9")
+	if err != nil {
+		t.Fatalf("GetAvailabilityFromDeezer: %v", err)
+	}
+	if deezerAvailability.SpotifyID != "abc" || !deezerAvailability.Tidal {
+		t.Fatalf("deezer availability = %#v", deezerAvailability)
+	}
+
+	errorClient := &IDHSClient{client: &http.Client{Transport: roundTripFunc(func(req *http.Request) (*http.Response, error) {
+		return &http.Response{StatusCode: 429, Body: io.NopCloser(strings.NewReader("")), Request: req}, nil
+	})}}
+	if _, err := errorClient.Search("bad", nil); err == nil {
+		t.Fatal("expected rate limit error")
+	}
+}
--- a/Show More
+++ b/Show More