Add MA_BETA14_IMPACT.md

Required by F-Droid for Flutter apps using --split-per-abi: each
per-ABI APK gets a unique versionCode = base * 10 + abiCode
(armeabi-v7a=1, arm64-v8a=2, x86_64=3).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

.github/FUNDING.yml

@@ -0,0 +1,3 @@
+# These are the funding models supported by Ensemble
+github: CollotsSpot
+custom: https://ko-fi.com/collotsspot

.github/workflows/build-apk.yml

@@ -31,16 +31,29 @@ jobs:
       - name: Setup Flutter
         uses: subosito/flutter-action@v2
         with:
-          flutter-version: '3.24.0'
-          channel: 'stable'
+          flutter-version: '3.38.0'
+          channel: 'master'
           cache: true
 
+      - name: Cache Gradle dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.gradle/caches
+            ~/.gradle/wrapper
+          key: gradle-${{ runner.os }}-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties') }}
+          restore-keys: |
+            gradle-${{ runner.os }}-
+
       - name: Get dependencies
         run: flutter pub get
 
       - name: Generate code (Drift database)
         run: dart run build_runner build --delete-conflicting-outputs
 
+      - name: Generate localizations
+        run: flutter gen-l10n
+
       - name: Generate launcher icons
         run: flutter pub run flutter_launcher_icons
 
@@ -50,10 +63,7 @@ jobs:
 
       - name: Setup signing keystore
         run: |
-          # Decode keystore from secret (persistent key for consistent signatures)
           echo "${{ secrets.KEYSTORE_BASE64 }}" | base64 -d > android/app/upload-keystore.jks
-
-          # Create key.properties file
           cat > android/key.properties << EOF
           storePassword=${{ secrets.KEYSTORE_PASSWORD }}
           keyPassword=${{ secrets.KEY_PASSWORD }}
@@ -73,10 +83,5 @@ jobs:
 
       - name: Upload APK summary
         run: |
-          echo "## APK Build Successful! 🎉" >> $GITHUB_STEP_SUMMARY
-          echo "" >> $GITHUB_STEP_SUMMARY
-          echo "📱 **APK Location:** \`build/app/outputs/flutter-apk/app-release.apk\`" >> $GITHUB_STEP_SUMMARY
-          echo "" >> $GITHUB_STEP_SUMMARY
-          echo "📦 **Download:** Check the artifacts section below" >> $GITHUB_STEP_SUMMARY
-          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "## APK Build Successful!" >> $GITHUB_STEP_SUMMARY
           ls -lh build/app/outputs/flutter-apk/app-release.apk >> $GITHUB_STEP_SUMMARY

.prompts/player-animation-audit.md

@@ -0,0 +1,182 @@
+# Player System Animation & Polish Audit
+
+## Context
+
+This is a Music Assistant client app (Ensemble) built with Flutter. The player system has undergone extensive development and now needs a comprehensive polish audit. The goal is buttery smooth 60fps animations and a premium user experience.
+
+## Architecture Overview
+
+The player system consists of three interconnected components:
+
+1. **Mini Player** (collapsed state) - Floating card at bottom, shows current track
+2. **Expanded Player** - Full-screen player with album art, controls, progress
+3. **Queue Panel** - Slides in from right of expanded player, shows playback queue
+
+Additionally:
+- **Player Selector** - Horizontal swipe between multiple players (collapsed mode)
+- **Device Reveal** - Swipe down from mini player to show available players
+
+## Key Files
+
+```
+lib/widgets/
+├── expandable_player.dart      # Main player widget (1800+ lines)
+├── global_player_overlay.dart  # Overlay wrapper, static accessors
+├── player/
+│   ├── queue_panel.dart        # Queue list with great_list_view
+│   ├── chapters_panel.dart     # Audiobook chapters
+│   └── mini_player_content.dart
+```
+
+## CRITICAL CONSTRAINTS
+
+1. **DO NOT MODIFY the queue list implementation** - It uses `great_list_view` package with `AutomaticAnimatedListView`. This was chosen specifically to avoid Flutter's grey screen overlay bug (#103804). The current implementation works correctly.
+
+2. **Preserve all existing functionality** - Focus on polish, not rewrites
+
+3. **Test changes incrementally** - This system is complex with many interdependencies
+
+## Audit Areas
+
+### 1. Animation Performance Audit
+
+Use sub-agents to analyze each animation system:
+
+**Agent 1: Expand/Collapse Animation**
+- Analyze `_controller` and `_expandAnimation`
+- Check for jank during morphing transition
+- Verify lerp functions are efficient
+- Look for unnecessary rebuilds during animation
+- Check `RepaintBoundary` placement
+
+**Agent 2: Queue Panel Animation**
+- Analyze `_queuePanelController` and `_queuePanelAnimation`
+- Verify slide-in/out is smooth
+- Check interaction with expanded player state
+- Verify the Listener-based swipe detection doesn't cause issues
+
+**Agent 3: Player Selector Animation**
+- Analyze horizontal swipe between players
+- Check `_slideOffset` and peek player animations
+- Verify finger-following feels natural
+- Look for edge cases with rapid swipes
+
+**Agent 4: Micro-interactions**
+- Play/pause button animations
+- Progress bar interactions
+- Volume swipe overlay
+- Favorite button feedback
+- Skip button responsiveness
+
+### 2. State Management Audit
+
+**Check for:**
+- Unnecessary `setState` calls during animations
+- ValueNotifier usage efficiency
+- Animation listener cleanup
+- Memory leaks from subscriptions
+- State synchronization between components
+
+### 3. Visual Polish Audit
+
+**Check for:**
+- Color transitions during expand/collapse
+- Text fade/scale animations
+- Image loading placeholders
+- Shadow/elevation consistency
+- Border radius morphing smoothness
+- Safe area handling
+
+### 4. Gesture Conflict Resolution
+
+**Verify:**
+- Vertical drag (expand/collapse) vs horizontal drag (player switch)
+- Queue panel swipe-right-to-close vs Dismissible swipe-left-to-delete
+- Edge dead zones for Android back gesture
+- Tap vs drag disambiguation
+
+### 5. Edge Cases
+
+**Test scenarios:**
+- Rapid expand/collapse
+- Swipe during animation
+- Back button during animations
+- Track change during queue scroll
+- Network image loading failures
+- Very long track/artist names
+
+## Execution Strategy
+
+```
+ultrathink: true
+```
+
+### Phase 1: Discovery (Read-Only)
+Launch parallel sub-agents to analyze each file:
+- Read and understand the animation architecture
+- Map all animation controllers and their relationships
+- Identify potential performance bottlenecks
+- Document current RepaintBoundary usage
+
+### Phase 2: Analysis Report
+Compile findings into categories:
+- **Critical**: Causes visible jank or bugs
+- **Important**: Noticeable but not breaking
+- **Nice-to-have**: Minor polish improvements
+
+### Phase 3: Implementation Plan
+For each finding:
+- Specific file and line numbers
+- Proposed change
+- Risk assessment
+- Testing approach
+
+### Phase 4: Incremental Fixes
+- One fix at a time
+- Build and test after each change
+- Verify no regressions
+
+## Output Format
+
+Provide a structured audit report:
+
+```markdown
+## Animation Audit Report
+
+### Executive Summary
+[2-3 sentences on overall state]
+
+### Critical Issues
+1. [Issue]: [File:Line] - [Description] - [Proposed Fix]
+
+### Important Issues
+1. [Issue]: [File:Line] - [Description] - [Proposed Fix]
+
+### Polish Opportunities
+1. [Issue]: [File:Line] - [Description] - [Proposed Fix]
+
+### Architecture Observations
+[Notes on overall structure, patterns noticed]
+
+### Recommended Priority Order
+1. [First fix]
+2. [Second fix]
+...
+```
+
+## Success Criteria
+
+After this audit and fixes:
+- All animations run at consistent 60fps
+- No jank during any transition
+- Gestures feel responsive and natural
+- State transitions are seamless
+- No visual glitches or flickers
+- Memory usage is stable during interactions
+
+## Notes
+
+- The app uses adaptive theming (colors extracted from album art)
+- There's an `AnimationDebugger` utility for profiling
+- Position tracking uses a shared `PositionTracker` singleton
+- The player supports both music and audiobooks (different UI modes)

ANDROID_AUTO_PLAN.md

@@ -0,0 +1,388 @@
+# Android Auto Implementation Plan for Ensemble
+
+## 1. Overview
+
+This document describes adding Android Auto support to Ensemble. When a user connects their Android phone to a car head unit, Android Auto will browse and play music through Ensemble without touching the phone.
+
+### What we're building
+
+- A browse hierarchy (Favorites, Playlists, Albums, Radio) accessible from the car screen
+- Playback from Android Auto routes through the builtin (local) player, which streams through MA as normal
+- Voice search support
+
+### Why builtin player only
+
+Android Auto requires local audio output. The builtin player plays audio through `just_audio` on the device, which the car receives over Bluetooth. Remote MA players are irrelevant in a car context.
+
+---
+
+## 2. Architecture
+
+### Provider reference
+
+`MassivAudioHandler` has no reference to `MusicAssistantProvider` today. The handler is created before the provider (in `main()` before `runApp`). Solution: add a `setProvider()` method and call it from `_MusicAssistantAppState.initState()`.
+
+```
+main.dart
+  audioHandler = await AudioService.init(...)   // global, created first
+  runApp(MusicAssistantApp())
+    _MusicAssistantAppState.initState()
+      _musicProvider = MusicAssistantProvider()
+      audioHandler.setProvider(_musicProvider)  // NEW
+```
+
+### Browse → play call flow
+
+```
+Android Auto          MassivAudioHandler              MusicAssistantProvider
+     |                       |                                |
+  getChildren('root') -----> | returns category items        |
+  getChildren('cat|playlists')-> | SyncService.cachedPlaylists  |
+  getChildren('playlist|lib|5')-> | provider.getPlaylistTracksWithCache()
+                             |  populates _trackQueueCache   |
+  playFromMediaId('track|lib|7|plist|lib|5') ->               |
+                             | lookup _trackQueueCache        |
+                             | provider.playTracks(builtinId, tracks, startIndex: i)
+```
+
+---
+
+## 3. Media ID Scheme
+
+Separator: `|` (pipe). Provider names use underscores/colons, never pipes — safe.
+
+| ID | Meaning |
+|----|---------|
+| `root` | Root (browsable) |
+| `recent` | Currently playing track (playable) |
+| `cat\|favorites` | Favorites category (browsable) |
+| `cat\|playlists` | Playlists category (browsable) |
+| `cat\|albums` | Albums category (browsable) |
+| `cat\|radio` | Radio stations category (browsable) |
+| `playlist\|{provider}\|{itemId}` | A playlist (browsable) |
+| `album\|{provider}\|{itemId}` | An album (browsable) |
+| `track\|{tProvider}\|{tItemId}\|{ctxType}\|{ctxProvider}\|{ctxId}` | A track in context (playable) |
+| `radio\|{provider}\|{itemId}` | A radio station (playable) |
+
+The `ctxType|ctxProvider|ctxId` suffix in track IDs encodes the parent container. Context types: `plist`, `album`, `favs`, `search`.
+
+**Track queue cache key** = `{ctxType}|{ctxProvider}|{ctxId}` (e.g. `plist|spotify|abc`). Stored when building children, looked up in `playFromMediaId`.
+
+---
+
+## 4. Browse Hierarchy
+
+```
+root
+├── recent              (playable, shown if something is/was playing)
+├── cat|favorites       (browsable → favorite tracks, all playable)
+├── cat|playlists       (browsable → list of playlists, each browsable)
+│   └── playlist|{provider}|{id}  → tracks (playable)
+├── cat|albums          (browsable → list of albums, each browsable)
+│   └── album|{provider}|{id}     → tracks (playable)
+└── cat|radio           (browsable → radio stations, each playable)
+```
+
+Artists are **not included**. Navigating Artist → Albums → Album → Tracks is four taps — too many while driving. Can be added later.
+
+---
+
+## 5. Track Queue Cache
+
+Tapping a track in Android Auto should play the full album/playlist from that track, not just the single track. The handler caches track lists when building children:
+
+```dart
+// Key: ctxKey e.g. "plist|spotify|abc" or "album|library|42" or "favs||"
+// Value: ordered list of tracks in that container
+final Map<String, List<ma.Track>> _trackQueueCache = {};
+```
+
+When `getChildren('playlist|spotify|abc')` is called:
+1. Fetch tracks via `provider.getPlaylistTracksWithCache('spotify', 'abc')`
+2. Store `_trackQueueCache['plist|spotify|abc'] = tracks`
+3. Return each track as a playable `MediaItem` with id `track|{t.provider}|{t.itemId}|plist|spotify|abc`
+
+When `playFromMediaId('track|lib|7|plist|spotify|abc')` is called:
+1. Parse ctxKey = `plist|spotify|abc`
+2. Look up `_trackQueueCache['plist|spotify|abc']`
+3. Find track index where `itemId == '7'`
+4. Call `provider.playTracks(builtinId, tracks, startIndex: index)`
+
+---
+
+## 6. Key Code for `massiv_audio_handler.dart`
+
+### New imports
+
+```dart
+import 'package:rxdart/rxdart.dart';
+import '../../providers/music_assistant_provider.dart';
+import '../settings_service.dart';
+import '../sync_service.dart';
+import '../../models/media_item.dart' as ma;
+```
+
+Note: `audio_service` exports its own `MediaItem`. Use `ma.MediaItem`, `ma.Track`, `ma.Album`, `ma.Playlist` for app models. The bare `MediaItem` refers to the audio_service type throughout new methods.
+
+### New fields
+
+```dart
+MusicAssistantProvider? _provider;
+final Map<String, ma.Track> _trackQueueCache = {}; // ctxKey -> tracks (see section 5)
+final Map<String, BehaviorSubject<Map<String, dynamic>>> _childrenSubjects = {};
+
+void setProvider(MusicAssistantProvider provider) {
+  _provider = provider;
+}
+```
+
+### `getChildren`
+
+```dart
+@override
+Future<List<MediaItem>> getChildren(String parentMediaId,
+    [Map<String, dynamic>? options]) async {
+  final provider = _provider;
+  if (provider == null) return [];
+
+  switch (parentMediaId) {
+    case AudioService.browsableRootId:
+      return _buildRoot(provider);
+    case 'cat|favorites':
+      return _buildFavorites(provider);
+    case 'cat|playlists':
+      return _buildPlaylistList(provider);
+    case 'cat|albums':
+      return _buildAlbumList(provider);
+    case 'cat|radio':
+      return _buildRadioList(provider);
+    default:
+      if (parentMediaId.startsWith('playlist|')) {
+        final parts = parentMediaId.split('|');
+        if (parts.length >= 3) return _buildPlaylistTracks(provider, parts[1], parts[2]);
+      }
+      if (parentMediaId.startsWith('album|')) {
+        final parts = parentMediaId.split('|');
+        if (parts.length >= 3) return _buildAlbumTracks(provider, parts[1], parts[2]);
+      }
+      return [];
+  }
+}
+```
+
+### `playFromMediaId`
+
+```dart
+@override
+Future<void> playFromMediaId(String mediaId, [Map<String, dynamic>? extras]) async {
+  final provider = _provider;
+  if (provider == null) return;
+
+  final playerId = await SettingsService.getBuiltinPlayerId();
+  if (playerId == null) return;
+
+  _logger.log('AndroidAuto: playFromMediaId $mediaId');
+
+  try {
+    if (mediaId == 'recent') {
+      await provider.playPauseSelectedPlayer();
+      return;
+    }
+
+    if (mediaId.startsWith('radio|')) {
+      final parts = mediaId.split('|'); // ['radio', provider, itemId]
+      if (parts.length < 3) return;
+      final station = provider.radioStations.firstWhere(
+        (s) => s.provider == parts[1] && s.itemId == parts[2],
+        orElse: () => throw Exception('Station not found: $mediaId'),
+      );
+      await provider.playRadio(playerId, station);
+      return;
+    }
+
+    if (mediaId.startsWith('track|')) {
+      // Format: track|{tProvider}|{tItemId}|{ctxType}|{ctxProvider}|{ctxId}
+      final parts = mediaId.split('|');
+      if (parts.length < 6) return;
+      final tProvider = parts[1];
+      final tItemId = parts[2];
+      final ctxKey = parts.sublist(3).join('|');
+
+      final trackList = _trackQueueCache[ctxKey];
+      if (trackList == null || trackList.isEmpty) {
+        // Fallback: play single track (minimal Track object)
+        await provider.playTrack(playerId, ma.Track(itemId: tItemId, provider: tProvider, name: ''));
+        return;
+      }
+
+      final index = trackList.indexWhere((t) => t.provider == tProvider && t.itemId == tItemId);
+      await provider.playTracks(playerId, trackList, startIndex: index < 0 ? 0 : index);
+      return;
+    }
+  } catch (e) {
+    _logger.log('AndroidAuto: playFromMediaId error: $e');
+  }
+}
+```
+
+### `search`
+
+```dart
+@override
+Future<List<MediaItem>> search(String query, [Map<String, dynamic>? extras]) async {
+  final provider = _provider;
+  if (provider == null || query.trim().isEmpty) return [];
+
+  try {
+    final results = await provider.searchWithCache(query);
+    final tracks = (results['tracks'] ?? []).whereType<ma.Track>().toList();
+    const ctxKey = 'search||';
+    _trackQueueCache[ctxKey] = tracks;
+
+    return tracks.map((t) => MediaItem(
+      id: 'track|${t.provider}|${t.itemId}|$ctxKey',
+      title: t.name,
+      artist: t.artistsString,
+      album: t.album?.name,
+      duration: t.duration,
+      artUri: _artUri(provider, t),
+      playable: true,
+    )).toList();
+  } catch (e) {
+    _logger.log('AndroidAuto: search error: $e');
+    return [];
+  }
+}
+```
+
+### `subscribeToChildren`
+
+```dart
+@override
+ValueStream<Map<String, dynamic>> subscribeToChildren(String parentMediaId) {
+  _childrenSubjects[parentMediaId] ??= BehaviorSubject.seeded({});
+  return _childrenSubjects[parentMediaId]!.stream;
+}
+```
+
+### `_artUri` helper
+
+```dart
+Uri? _artUri(MusicAssistantProvider provider, ma.MediaItem item) {
+  final url = provider.getImageUrl(item, size: 256);
+  return url != null ? Uri.tryParse(url) : null;
+}
+```
+
+---
+
+## 7. Files to Change
+
+### `pubspec.yaml`
+Add `rxdart: ^0.28.0` as direct dependency. The `^0.28.0` constraint matches the already-resolved transitive version so no upgrade occurs.
+
+### `android/app/build.gradle`
+Change:
+```groovy
+minSdkVersion flutter.minSdkVersion
+```
+To:
+```groovy
+minSdkVersion 23
+```
+Android Auto requires API 23+. `flutter.minSdkVersion` resolves to 21 — too low.
+
+### `android/app/src/main/AndroidManifest.xml`
+Add inside `<application>` tag:
+```xml
+<meta-data
+    android:name="com.google.android.gms.car.application"
+    android:resource="@xml/automotive_app_desc" />
+```
+The `MediaBrowserService` intent filter on `AudioService` is already present — no changes needed there.
+
+### `android/app/src/main/res/xml/automotive_app_desc.xml` (NEW)
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<automotiveApp>
+    <uses name="media" />
+</automotiveApp>
+```
+
+### `lib/main.dart`
+In `_MusicAssistantAppState.initState()`, after creating `_musicProvider`:
+```dart
+audioHandler.setProvider(_musicProvider);
+```
+
+### `lib/services/audio/massiv_audio_handler.dart`
+Add ~200 lines. New imports, fields, `setProvider()`, `getChildren()`, `playFromMediaId()`, `search()`, `subscribeToChildren()`, and private builder helpers. All existing code is untouched.
+
+---
+
+## 8. Testing with DHU (No Car Required)
+
+### Install DHU
+In Android Studio: SDK Manager → SDK Tools → Android Auto Desktop Head Unit Emulator.
+
+Or via command line:
+```bash
+sdkmanager "extras;google;auto"
+```
+
+### Enable Android Auto developer mode on phone
+1. Settings → Apps → Android Auto → tap version number 10 times
+2. In Android Auto developer settings: enable "Unknown sources"
+
+### Run the test session
+```bash
+# Terminal 1: forward the port
+adb forward tcp:5277 tcp:5277
+
+# Terminal 2: start the DHU
+$ANDROID_SDK_ROOT/extras/google/auto/desktop-head-unit
+```
+
+In Android Auto developer settings on phone: tap "Start head unit server".
+
+### Build and install
+```bash
+flutter build apk --debug
+adb install build/app/outputs/flutter-apk/app-debug.apk
+```
+
+Launch Ensemble on phone first (so audio service starts). Then tap the media icon in DHU — Ensemble should appear.
+
+### Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| App not visible in DHU | Missing `automotive_app_desc.xml` or wrong meta-data name | Check manifest and XML |
+| App visible, browse is empty | `setProvider` not yet called | Check `initState` wiring |
+| Build fails | `minSdkVersion` too low | Check `build.gradle` |
+| Track plays but wrong song | `_trackQueueCache` miss | Ensure `getChildren` ran before `playFromMediaId` |
+
+---
+
+## 9. Implementation Order
+
+Do these steps in order to test incrementally:
+
+1. Android config files (`build.gradle`, `AndroidManifest.xml`, `automotive_app_desc.xml`) — verify app appears in DHU before writing Dart
+2. `pubspec.yaml` + `flutter pub get`
+3. `massiv_audio_handler.dart`: add `setProvider`, fields, `subscribeToChildren` — minimum to not crash
+4. `main.dart`: wire `setProvider`
+5. `massiv_audio_handler.dart`: `getChildren` with hardcoded root categories — verify tree appears in DHU
+6. `massiv_audio_handler.dart`: add all `_build*` helpers one by one, test each
+7. `massiv_audio_handler.dart`: add `playFromMediaId` — test track playback
+8. `massiv_audio_handler.dart`: add `search` — test voice search
+
+---
+
+## 10. Not In Scope
+
+- **Artists browse** — too many taps for driving; albums alone suffice
+- **Audiobooks/podcasts** — different UX needs; add later
+- **Queue management from Android Auto** — MA queue model is complex
+- **Push updates** — `notifyChildrenChanged` stubbed but not wired to sync events
+- **Android Automotive OS** — different platform, requires a separate flavor

MA_BETA14_IMPACT.md

@@ -0,0 +1,167 @@
+# Music Assistant 2.8.0 Beta 14 — Impact on Ensemble
+
+**Date:** 2026-03-03
+**Current server:** 2.8.0 beta 12
+**Target server:** 2.8.0 beta 14 (released March 2, 2026)
+
+---
+
+## Summary
+
+Beta 14 is a large release (50+ PRs). The headline change — merging multi-protocol players into a single entity — directly overlaps with Ensemble's client-side Cast↔Sendspin consolidation logic. Sendspin also received a major v4.0 overhaul. Most changes should degrade gracefully but player ID persistence will break on upgrade.
+
+---
+
+## Breaking: Player Merging (PR #3150)
+
+MA now merges players that support multiple protocols (e.g. a Chromecast with Cast + Sendspin) into a **single player entity** server-side. Previously these appeared as two separate players.
+
+> *"After this change, all your players will be reset. If you previously had multiple players in Music Assistant per protocol, this will now show up as one single player."*
+
+### What Ensemble does today
+
+Ensemble handles this client-side in `music_assistant_provider.dart:4271-4406`:
+
+- `_castToSendspinIdMap` maps Cast IDs → Sendspin IDs
+- When Sendspin is grouped: hides Cast player, shows Sendspin (renamed to base name)
+- When ungrouped: hides Sendspin, shows original Cast
+- Mappings persisted to database for cold start restoration
+
+### Impact on Ensemble
+
+| Component | Location | Impact | Severity |
+|---|---|---|---|
+| `_castToSendspinIdMap` + consolidation logic | `provider:4271-4406` | Dead code — server no longer sends separate players | Medium |
+| `isManuallySyncedPlayer()` ID translation | `provider:533-595` | Lookups against stale map fail silently (returns `false`) | Low |
+| Player selection persistence | Settings + DB | **Stored player IDs invalid after upgrade** — all players reset | **High** |
+| `_handlePlayerUpdatedEvent()` ID matching | `provider:2956-3358` | Events arrive with new merged IDs, old translation won't match | Medium |
+| Database-persisted Cast↔Sendspin mappings | `DatabaseService` | Stale data, won't match anything | Low |
+
+### Assessment
+
+The consolidation logic should degrade gracefully — it won't find Sendspin suffixes to strip or Cast pairs to merge, so the server's already-merged players pass through `filterPlayers()` as-is. The main risk is **player selection breaking** because saved player IDs no longer exist.
+
+### Action required
+
+1. Verify the existing fallback logic (`provider:4427-4465`) gracefully re-selects when the stored `selectedPlayerId` doesn't exist in the player list
+2. Remove or gate the Cast↔Sendspin consolidation code behind a server version check (on beta 14+ it's unnecessary and could cause confusion)
+3. Clear stale database mappings on first connection to a beta 14+ server
+
+---
+
+## Sendspin v4.0 (PR #3158)
+
+Major rewrite of the Sendspin server.
+
+### Changes
+
+- New `SendspinPlaybackSession` coordinator architecture
+- Per-member DSP pipelines, dynamic group membership, late-join audio backfill
+- Max buffer capacity 5 → 30 seconds
+- Multiple Sendspin servers with automatic failover
+- Per-client codec/sample-rate/bit-depth options
+- Album artwork persists during skip/pause
+- Reduced latency for live streams
+
+### Impact on Ensemble
+
+| Change | Impact |
+|---|---|
+| New session architecture | **Likely compatible** — sendspin-js only bumped 2.0.0 → 2.0.1 (minor), suggesting wire protocol didn't fundamentally change |
+| Per-client codec options | `stream/start` may contain new fields — safe if Ensemble ignores unknown fields |
+| Multiple servers with failover | Ensemble's 3-tier connection strategy may need awareness |
+| Buffer increase | No client impact |
+
+### Action required
+
+1. Test Sendspin connection against beta 14 — verify `client/hello`, `stream/start`, state reporting all still work
+2. Confirm unknown fields in protocol messages are ignored gracefully
+
+---
+
+## Sendspin-Chromecast Bridge (PR #3255)
+
+Replaces the inline experimental Sendspin mode in `ChromecastPlayer` with a dedicated bridge. Cast devices now use a Cast receiver app with an embedded JS Sendspin client.
+
+### Impact on Ensemble
+
+- **Direct impact: None** — Ensemble is a Sendspin client itself, not going through Cast
+- **Indirect:** Changes how grouped Cast players behave, which could affect `GroupVolumeManager`
+
+---
+
+## Group Volume / Grouping Fixes
+
+| PR | Change | Ensemble Impact |
+|---|---|---|
+| #3192 | Fix grouping for players whose native protocol is also a protocol of other players | Bidirectional grouping translation — may affect group detection logic |
+| #3205 | Fix group mute for protocol-synced players (`player.state.group_members` vs `player.group_members`) | `GroupVolumeManager` may see different/correct member lists |
+| #3277 | Fix `volume_up`/`volume_down` for group players | Server-side fix, should improve behavior |
+| #3118 | Fix sync groups losing members on power off | Affects dynamic group management |
+
+### Action required
+
+1. Test group volume behavior — may "just work better" with server-side fixes
+2. Verify `GroupVolumeManager` handles any changes to `group_members` field population
+
+---
+
+## Sendspin Bug Fixes
+
+| PR | Fix | Ensemble Relevance |
+|---|---|---|
+| #3191 | DSP not applying for Sendspin players | DSP config stored on parent player, looked up by protocol player ID — now fixed |
+| #3249 | Update to aiosendspin 4.2.0 | Library update, potential behavior changes |
+| #3250 | Metadata sending wrong progress when paused | Progress reporting fix — Ensemble's position tracker may see better data |
+| #3258 | Floating point for internal audio data | Audio quality improvement, no client impact |
+
+---
+
+## New APIs — Opportunities
+
+| Feature | PR | Details | Ensemble Opportunity |
+|---|---|---|---|
+| Playback speed | #3198 | `player_queues/set_playback_speed`, stored in `queue.extra_attributes["playback_speed"]` | Great for audiobooks/podcasts |
+| Save queue to playlist | #3149 | `save_as_playlist` command on player queue controller | Easy feature add |
+| Mixed-media playlists | #3216 | Playlists can contain tracks + podcasts + audiobooks. DB schema bumped to v30. `get_playlist_tracks()` returns `Sequence[PlaylistPlayableItem]` | Playlist screens may need to handle heterogeneous items |
+| Genres v2 | #3164 | New browsing category with icons and SVG support | New library section |
+
+---
+
+## Also Changed in Beta 13 (Skipped)
+
+Relevant changes from beta 13 (between current beta 12 and target beta 14):
+
+- Group volume mute support (#3034)
+- Frontend prepared for multiprotocol support (#1409) — groundwork for beta 14 merging
+- IPv6 support for zeroconf, stream server, AirPlay (#3086)
+- Snapcast player availability alignment (#3104)
+- DLNA reconnection fix (#3132)
+
+---
+
+## Recommended Action Plan
+
+### Before upgrading
+
+- [ ] Verify player selection fallback handles missing player IDs gracefully
+- [ ] Back up current configuration
+
+### Immediate (after upgrading)
+
+- [ ] Test Sendspin protocol compatibility (connection, streaming, state reporting)
+- [ ] Test player list — confirm merged players appear correctly without client-side consolidation
+- [ ] Test group volume behavior with new server-side fixes
+- [ ] Test player selection persistence across app restarts
+
+### Short-term
+
+- [ ] Remove or version-gate Cast↔Sendspin consolidation code
+- [ ] Clear stale database mappings on beta 14+ detection
+- [ ] Test mixed-media playlist handling if playlists are used
+
+### Opportunistic
+
+- [ ] Add playback speed control (audiobook/podcast feature)
+- [ ] Add save-queue-to-playlist
+- [ ] Explore Genres v2 browsing

README.md

@@ -1,6 +1,12 @@
 <div align="center">
   <img src="assets/images/ensemble_logo.png" alt="Ensemble Logo" height="200">
 
+  [![GitHub release](https://img.shields.io/badge/Release-v3.0.4-blue?style=for-the-badge&logo=github)](https://github.com/CollotsSpot/Ensemble/releases)
+  [![GitHub Downloads](https://img.shields.io/github/downloads/CollotsSpot/Ensemble/latest/total?style=for-the-badge&logo=android&label=APK%20Downloads&color=green)](https://github.com/CollotsSpot/Ensemble/releases/latest)
+  [![License: MIT](https://img.shields.io/badge/License-MIT-purple.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
+  [![GitHub Sponsors](https://img.shields.io/badge/Sponsor-GitHub-EA4AAA?style=for-the-badge&logo=GitHub%20Sponsors&logoColor=white)](https://github.com/sponsors/CollotsSpot)
+  [![Ko-fi](https://img.shields.io/badge/Ko--fi-FF5E5B?style=for-the-badge&logo=Ko-fi&logoColor=white)](https://ko-fi.com/collotsspot)
+
 ---
 
   <p><strong>An unofficial mobile client for Music Assistant</strong></p>
@@ -17,47 +23,82 @@ This application was built with AI-assisted development using **Claude Code** an
 
 ---
 
+## Also See
+
+**[Ensemble TV](https://github.com/CollotsSpot/ensemble-tv)** - A simple Android TV client for Music Assistant that displays what's currently playing on your TV with remote control support.
+
+---
+
 ## Features
 
 ### Local Playback
-- **Stream to Your Phone** - Play music from your Music Assistant library directly on your mobile device
+- **Stream to Your Phone** - Play music from your Music Assistant library directly on your mobile device via Sendspin protocol
 - **Background Playback** - Music continues playing when the app is minimized
 - **Media Notifications** - Control playback from your notification shade with album art display
+- **Instant Response** - Pause/resume in ~300ms
 
 ### Remote Control
 - **Multi-Player Support** - Control any speaker or device connected to Music Assistant
-- **Device Selector** - Quickly switch between your phone and other players
+- **Device Selector** - Swipe down on mini player to reveal all your devices
+- **Multi-Room Grouping** - Long-press any player to sync it with the current player
 - **Full Playback Controls** - Play, pause, skip, seek, and adjust volume
-- **Queue Management** - View and manage the playback queue
+- **Volume Precision Mode** - Hold the volume slider for fine-grained control with haptic feedback
+- **Power Control** - Turn players on/off directly from the mini player
+
+### Queue Management
+- **View & Manage Queue** - See upcoming tracks in the playback queue
+- **Drag to Reorder** - Instant drag handles for reordering tracks
+- **Swipe left to Delete** - Remove tracks with a simple swipe gesture
+- **Swipe right to play next** - Move tracks with a simple swipe gesture
 
 ### Home Screen
-- **Customizable Rows** - Toggle Recently Played, Discover Artists, and Discover Albums
-- **Favorites Rows** - Optional rows for Favorite Albums, Artists, and Tracks
+- **Customizable Rows** - Toggle and reorder: Recently Played, Discover Artists, Discover Albums
+- **Favorites Rows** - Optional rows for Favorite Albums, Artists, Tracks, Playlists, and Radio Stations
 - **Adaptive Layout** - Rows scale properly for different screen sizes and aspect ratios
 - **Pull to Refresh** - Refresh content with a simple pull gesture
 
-### Library Browsing
-- **Browse Your Collection** - Artists, albums, playlists, and tracks from all your music sources
+### Library
+- **Music** - Browse artists, albums, playlists, and tracks from all your music sources
+- **Radio Stations** - Browse and play radio stations with list or grid view
+- **Podcasts** - Browse podcasts, view episodes with descriptions and publish dates
+- **Audiobooks** - Browse by title, series, or author with progress tracking
 - **Favorites Filter** - Toggle to show only your favorite items
-- **Album Details** - View track listings with artwork
-- **Artist Details** - View artist albums and top tracks
-- **Playlist Support** - Browse and play your playlists
-- **Search** - Find music across your entire library
+- **Providers Filter** - Toggle to show only specific provider items
+- **Letter Scrollbar** - Fast navigation through long lists
+- **Provider Icons** - Provider icons on library covers
+
+### Search
+- **Universal Search** - Find music, podcasts, radio stations, playlists, and audiobooks
+- **Fuzzy Matching** - Typo-tolerant search (e.g., "beetles" finds "Beatles")
+- **Smart Scoring** - Results ranked by relevance with colored type indicators
+- **Search History** - Quickly access your recent searches
+- **Quick Actions** - Long-press any result to add to queue or play next
 
 ### Audiobooks
-- **Audiobooks Tab** - Browse your audiobook library with grid/list view options
-- **Series Support** - View audiobooks organized by series with collage cover art
-- **Author Browsing** - Browse audiobooks by author
 - **Chapter Navigation** - Jump between chapters with timestamp display
 - **Progress Tracking** - Track your listening progress across sessions
 - **Continue Listening** - Pick up where you left off
 - **Mark as Finished/Unplayed** - Manage your reading progress
+- **Series Support** - View audiobooks organized by series with collage cover art
+
+### Podcasts
+- **Episode Browser** - View full episode list with artwork and descriptions
+- **Skip Controls** - Skip forward/backward during playback
+- **High-Resolution Artwork** - Fetched via iTunes for best quality
+
+### Android Auto
+- **Media Browsing** - Browse your library from your car's display with categories for Home, Music, Audiobooks, Podcasts, and Radio
+- **Voice Search** - Find and play tracks using voice commands
+- **Full Playback Controls** - Play, pause, and skip from your car's head unit
+- **Album Art & Metadata** - Track info and artwork displayed on your car's screen
+- **Smart Queueing** - Tap any track in an album or playlist to play from that point with the full queue
 
 ### Smart Features
 - **Instant App Restore** - App loads instantly with cached library data while syncing in background
 - **Auto-Reconnect** - Automatically reconnects when connection is lost
 - **Offline Browsing** - Browse your cached library even when disconnected
 - **Hero Animations** - Smooth transitions between screens
+- **Welcome Screen** - Guided onboarding for first-time users
 
 ### Theming
 - **Material You** - Dynamic theming based on your device's wallpaper
@@ -67,14 +108,18 @@ This application was built with AI-assisted development using **Claude Code** an
 ## Screenshots
 
 <div align="center">
-  <img src="assets/screenshots/1.png?v=2" alt="Connection Screen" width="150">
-  <img src="assets/screenshots/2.png?v=2" alt="Home Screen" width="150">
-  <img src="assets/screenshots/3.png?v=2" alt="Album Details" width="150">
-  <img src="assets/screenshots/4.png?v=2" alt="Now Playing" width="150">
-  <img src="assets/screenshots/5.png?v=2" alt="Queue" width="150">
-  <img src="assets/screenshots/6.png?v=2" alt="Settings" width="150">
-  <img src="assets/screenshots/7.png?v=2" alt="Audiobooks" width="150">
-  <img src="assets/screenshots/8.png?v=2" alt="Audiobook Player" width="150">
+  <img src="assets/screenshots/1.png?v=4" alt="Screenshot 1" width="150">
+  <img src="assets/screenshots/2.png?v=4" alt="Screenshot 2" width="150">
+  <img src="assets/screenshots/3.png?v=4" alt="Screenshot 3" width="150">
+  <img src="assets/screenshots/4.png?v=4" alt="Screenshot 4" width="150">
+  <img src="assets/screenshots/5.png?v=4" alt="Screenshot 5" width="150">
+  <img src="assets/screenshots/6.png?v=4" alt="Screenshot 6" width="150">
+  <img src="assets/screenshots/7.png?v=4" alt="Screenshot 7" width="150">
+  <img src="assets/screenshots/8.png?v=4" alt="Screenshot 8" width="150">
+  <img src="assets/screenshots/9.png?v=4" alt="Screenshot 9" width="150">
+  <img src="assets/screenshots/10.png?v=4" alt="Screenshot 10" width="150">
+  <img src="assets/screenshots/11.png?v=4" alt="Screenshot 11" width="150">
+  <img src="assets/screenshots/12.png?v=4" alt="Screenshot 12" width="150">
 </div>
 
 ## Download
@@ -84,30 +129,54 @@ Download the latest release from the [Releases page](https://github.com/CollotsS
 ## Setup
 
 1. Launch the app
-2. Enter your Music Assistant server URL (e.g., `music.example.com` or `192.168.1.100`)
+2. Enter your Music Assistant server URL
 3. Connect to your server
-4. Start playing! Music plays on your phone by default, or tap the device icon to choose a different player.
+4. Start playing! Music plays on your phone by default, or swipe down on the mini player to choose a different player.
 
-## Authentication
+### Finding Your Server URL
 
-Ensemble supports multiple authentication methods:
+**Important:** You need the **Music Assistant** URL, not your Home Assistant URL.
 
-| Method | Status |
-|--------|--------|
-| Music Assistant native auth | Tested |
-| No authentication | Tested |
-| Authelia | Implemented, not recently tested |
-| HTTP Basic Auth | Implemented, not recently tested |
+To find the correct URL:
+1. Open Music Assistant web UI
+2. Go to **Settings** > **About**
+3. Look for **Base URL** (e.g., `http://192.168.1.100:8095`)
 
-**Note:** Development and testing is done against Music Assistant beta with native authentication enabled.
+### Home Assistant Add-on Users
+
+If you run Music Assistant as a Home Assistant add-on:
+- Use the IP address of your Home Assistant server
+- Do **not** use your Home Assistant URL or ingress URL
+
+### Android Auto
+
+Since Ensemble is not installed from the Play Store, you need to enable unknown sources in Android Auto:
+
+1. Open **Android Auto** settings on your phone
+2. Tap the **Version** number at the bottom 10 times to enable developer mode
+3. Tap the three-dot menu and open **Developer settings**
+4. Enable **Unknown sources**
+5. Connect your phone to your car via USB or wirelessly
+6. Ensemble will appear in Android Auto's app list
+
+### Remote Access
+
+For access outside your home network, you'll need to expose Music Assistant through a reverse proxy (e.g., Traefik, Nginx Proxy Manager, Cloudflare Tunnel).
 
 ## Requirements
 
-- Music Assistant server (v2.7.0 beta 20 or later)
+- Music Assistant server (v2.7.0 beta 20 or later recommended)
 - Network connectivity to your Music Assistant server
 - Android device (Android 5.0+)
 - Audiobookshelf provider configured in Music Assistant (for audiobook features)
 
+## Sponsors
+
+A huge thank you to my sponsors! 💖
+
+<a href="https://github.com/pcsokonay"><img src="https://github.com/pcsokonay.png" width="60px" alt="pcsokonay" /></a>
+<a href="https://github.com/githubchb"><img src="https://github.com/githubchb.png" width="60px" alt="githubchb" /></a>
+
 ## License
 
 MIT License

RELEASE_NOTES_DRAFT.md

@@ -0,0 +1,78 @@
+# Release Notes Draft
+
+## v2.9.2-beta (TBD)
+
+### New Features
+
+#### Context Menus
+- **Long-press context menus on all media items**: Albums, artists, tracks, playlists, podcasts, and radio stations now all support long-press to show a context menu with Play, Add to Library, and Favorite options.
+
+#### Podcasts
+- **Podcast episode detail screen**: Tap "View Details" from episode context menu to see full scrollable description, publish date, duration, with Play, Play On, and Add to Queue actions.
+- **Episode sorting**: Sort podcast episodes by newest first, oldest first, alphabetical, or duration.
+
+#### Audio Quality
+- **Hi-res audio badge**: Track listings now show a hi-res badge when high quality audio is available.
+
+### Improvements
+
+#### UI/UX
+- **New library icon**: Replaced confusing library icon with clearer book icon (book_2) across bottom nav, search filter, detail screens, and context menus. Filled when in library, outlined when not.
+- **Player selector**: Replaced popup dialog with player select overlay for queue actions.
+- **Search library filter**: Filled icon indicates active filter state without background highlight.
+- **Context menu polish**: Slightly larger buttons (46px), wider menu (185px), consistent text colors that don't pick up adaptive theming.
+- **Navigation transitions**: Smoother fade/slide animations between screens.
+- **Hero animations**: Podcast episode images animate smoothly to detail screen.
+
+#### Performance
+- **Library list optimization**: Standardized list item heights with itemExtent, reduced image cache sizes for smoother scrolling.
+- **Palette extraction**: Moved to isolate for better UI responsiveness during color extraction.
+- **Provider selects**: Optimized provider state watching to reduce unnecessary rebuilds.
+
+### Bug Fixes
+
+#### Audiobooks
+- **Fixed audiobooks not loading after provider re-add**: When removing and re-adding an AudiobookShelf provider, the app would show 0 audiobooks because saved library paths referenced the old provider instance ID. Now automatically clears stale settings and falls back to the library_items API.
+
+- **Fixed duplicate provider filter options**: After re-adding a provider, two entries for the same provider could appear in the library filter menu. Now deduplicates providers by name, keeping the one with more items.
+
+- **Fixed multiple accounts of same service not showing**: When you have multiple accounts of the same service (e.g., two Spotify accounts for different family members), only one would appear in the library menu provider toggles. Now all accounts with distinct names are shown.
+
+- **Fixed audiobook year sorting**: Sort by year now works correctly for audiobooks. Fixed two issues:
+  - Year data is now properly extracted from ABS's `metadata.release_date` field (handles both "2024" and "2024-01-15" formats)
+  - Sort handler now properly supports ascending and descending year sorts
+
+#### Library Sorting
+- **Fixed letter scrollbar showing irrelevant letters**: When sorting by date or play count, the scrollbar popup now hides instead of showing meaningless letters. Shows contextual info based on sort type (letters for alphabetical, years for year sort, hidden for date/count sorts).
+
+- **Fixed sorting not working for date added, last played, play count**: These sort options now correctly preserve server-side sorting instead of re-sorting alphabetically on the client. Affected albums, artists, and tracks tabs.
+
+- **Fixed playlists sorting**: Modified, last played, and play count sorting now works for playlists by properly requesting sorted data from the server.
+
+- **Fixed ascending/descending not working**: Sort direction now properly applies for all sort types across albums, artists, playlists, and audiobooks.
+
+- **Fixed list not updating when sort order changes**: Added sort order to ListView/GridView keys to force UI rebuilds when changing sort direction.
+
+#### Provider Management
+- **Fixed stale provider IDs persisting in settings**: When toggling providers, stale provider instance IDs (from removed providers) are now automatically cleaned up from saved settings.
+
+#### Playback
+- **Fixed Spotify external source detection** (issue #27): Properly detects when Spotify is the music provider.
+- **Fixed foreground service not stopping** (issue #51): Auto-stops after 30 minutes idle.
+- **Fixed Sendspin proxy auth**: Now works correctly for local network connections.
+
+#### UI Fixes
+- **Fixed nav bar hidden when no player selected**: Navigation bar now always visible.
+- **Fixed Flutter 3.38 slider grey rectangles**: Volume and seek sliders render correctly.
+- **Fixed library tab scroll position**: Maintains position when switching tabs.
+
+### Technical Changes
+- Flutter 3.38 compatibility
+- Simplified authentication using MA built-in auth
+- Added `material_symbols_icons` package for book_2 icon
+- Added `ScrollbarDisplayMode` enum (`letter`, `year`, `count`, `none`) for contextual scrollbar popups
+- Added `updateCachedAlbums()`, `updateCachedArtists()`, `updateCachedPlaylists()` methods to SyncService for proper cache synchronization with sorted data
+- Provider filter now validates against available providers when toggling, not just on initial load
+- Removed Selector caching from albums and artists tabs to ensure proper rebuilds when source tracking updates
+- Options menu provider toggles now use Consumer to watch Provider state directly
+- Centralized player selector logic in GlobalPlayerOverlay.showPlayerSelectorForAction()

SEARCH-IMPROVEMENTS.md

@@ -0,0 +1,52 @@
+# Search Improvements
+
+Branch: `feature/search-improvements`
+
+## Completed
+
+- [x] Add playlists and audiobooks to search results
+  - Parse from MA API response
+  - Filter chips for each type
+  - Tile builders with navigation to detail screens
+
+- [x] Unified Relevance-Based "All" Results
+  - Scoring algorithm implemented:
+    - Exact match: 100 points
+    - Starts with query: 80 points
+    - Contains query (word boundary): 60 points
+    - Contains query (anywhere): 40 points
+    - Fuzzy match: 20 points
+    - Bonus for library items (albums): +10 points
+    - Bonus for favorites: +5 points
+    - Secondary field matching (artist name in albums/tracks)
+  - Merged all results into single sorted list
+  - Type indicators in subtitle (e.g., "Artist • Album")
+
+- [x] Smart Cross-Referencing
+  - Extracts unique artists from matched tracks/albums
+  - Filters to artists whose name contains query words (min 3 chars)
+  - Adds cross-referenced artists with lower relevance score (25)
+  - Avoids duplicates with direct search results
+
+- [x] Past Searches Row
+  - Added SearchHistory table to database (schema v4)
+  - Saves successful searches (deduplicated, max 10)
+  - Displays as ActionChips in empty state
+  - Clicking chip performs that search
+
+## Remaining Ideas (Lower Priority)
+
+- **Library-only toggle:** Add switch to filter search to library items only (MA API supports this)
+- **Voice search:** Add microphone button if platform supports speech recognition
+- **Search suggestions:** Typeahead from library as user types
+- **Quick actions:** Long-press result for play/queue options without navigating
+- **Clear history in settings:** Add option to clear search history
+
+## Files Modified
+
+| File | Changes |
+|------|---------|
+| `lib/database/database.dart` | Added SearchHistory table, schema v4 |
+| `lib/services/database_service.dart` | Added search history methods |
+| `lib/screens/search_screen.dart` | Relevance scoring, cross-refs, history UI |
+| `lib/l10n/app_en.arb` | Added localization strings |

android/app/build.gradle

@@ -29,8 +29,8 @@ if (keystorePropertiesFile.exists()) {
 }
 
 android {
-    namespace "com.musicassistant.music_assistant"
-    compileSdk 35
+    namespace "com.collotsspot.ensemble"
+    compileSdk 36
     ndkVersion flutter.ndkVersion
 
     compileOptions {
@@ -58,8 +58,8 @@ android {
     }
 
     defaultConfig {
-        applicationId "com.musicassistant.music_assistant"
-        minSdk 21
+        applicationId "com.collotsspot.ensemble"
+        minSdkVersion flutter.minSdkVersion
         targetSdk 35
         versionCode flutterVersionCode.toInteger()
         versionName flutterVersionName
@@ -70,6 +70,21 @@ android {
             signingConfig keystorePropertiesFile.exists() ? signingConfigs.release : signingConfigs.debug
         }
     }
+
+    dependenciesInfo {
+        includeInApk = false
+        includeInBundle = false
+    }
+}
+
+def abiCodes = ['armeabi-v7a': 1, 'arm64-v8a': 2, 'x86_64': 3]
+android.applicationVariants.configureEach { variant ->
+    variant.outputs.each { output ->
+        def abiVersionCode = abiCodes[output.getFilter('ABI')]
+        if (abiVersionCode != null) {
+            output.versionCodeOverride = variant.versionCode * 10 + abiVersionCode
+        }
+    }
 }
 
 flutter {

android/app/src/main/AndroidManifest.xml

@@ -1,5 +1,11 @@
 <manifest xmlns:android="http://schemas.android.com/apk/res/android">
     <uses-permission android:name="android.permission.INTERNET"/>
+    <queries>
+        <intent>
+            <action android:name="android.intent.action.VIEW" />
+            <data android:scheme="https" />
+        </intent>
+    </queries>
     <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
     <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
     <uses-permission android:name="android.permission.WAKE_LOCK"/>
@@ -11,6 +17,7 @@
         android:label="Ensemble"
         android:name="${applicationName}"
         android:icon="@mipmap/ic_launcher"
+        android:appCategory="audio"
         android:usesCleartextTraffic="true"
         android:networkSecurityConfig="@xml/network_security_config">
         <activity
@@ -47,6 +54,10 @@
             </intent-filter>
         </receiver>
 
+        <meta-data
+            android:name="com.google.android.gms.car.application"
+            android:resource="@xml/automotive_app_desc" />
+
         <meta-data
             android:name="flutterEmbedding"
             android:value="2" />

android/app/src/main/kotlin/com/collotsspot/ensemble/MainActivity.kt

@@ -0,0 +1,229 @@
+package com.collotsspot.ensemble
+
+import android.content.Context
+import android.database.ContentObserver
+import android.media.AudioManager
+import android.os.Handler
+import android.os.Looper
+import android.provider.Settings
+import android.util.Log
+import android.view.KeyEvent
+import com.ryanheise.audioservice.AudioServiceActivity
+import io.flutter.embedding.engine.FlutterEngine
+import io.flutter.plugin.common.MethodChannel
+
+// Extend AudioServiceActivity instead of FlutterActivity to support audio_service package
+// while also intercepting volume button events
+class MainActivity: AudioServiceActivity() {
+    private val TAG = "EnsembleVolume"
+    private val CHANNEL = "com.collotsspot.ensemble/volume_buttons"
+    private var methodChannel: MethodChannel? = null
+    private var isListening = false
+
+    // Volume observer for lockscreen volume changes
+    // Watches system STREAM_MUSIC volume and mirrors changes to the MA player
+    // when a remote/group player is active
+    private var audioManager: AudioManager? = null
+    private var volumeObserver: VolumeContentObserver? = null
+    private var isObservingVolume = false
+    private var lastKnownVolume: Int = -1
+    // Guard flag to ignore volume changes triggered by our own setStreamVolume calls
+    private var ignoringVolumeChange = false
+
+    override fun configureFlutterEngine(flutterEngine: FlutterEngine) {
+        super.configureFlutterEngine(flutterEngine)
+        Log.d(TAG, "Configuring Flutter engine, setting up MethodChannel")
+
+        audioManager = getSystemService(Context.AUDIO_SERVICE) as AudioManager
+
+        methodChannel = MethodChannel(flutterEngine.dartExecutor.binaryMessenger, CHANNEL)
+        methodChannel?.setMethodCallHandler { call, result ->
+            Log.d(TAG, "Received method call: ${call.method}")
+            when (call.method) {
+                "startListening" -> {
+                    isListening = true
+                    Log.d(TAG, "Volume listening ENABLED")
+                    result.success(null)
+                }
+                "stopListening" -> {
+                    isListening = false
+                    Log.d(TAG, "Volume listening DISABLED")
+                    result.success(null)
+                }
+                "startVolumeObserver" -> {
+                    // Start observing system volume for lockscreen volume changes.
+                    // Optional: initialVolume (0-100) sets the system volume to match
+                    // the MA player's current volume for a consistent HUD display.
+                    val initialVolume = call.argument<Int>("initialVolume")
+                    startVolumeObserver(initialVolume)
+                    result.success(null)
+                }
+                "stopVolumeObserver" -> {
+                    stopVolumeObserver()
+                    result.success(null)
+                }
+                "syncSystemVolume" -> {
+                    // Sync system volume to match MA player volume (0-100)
+                    val volume = call.argument<Int>("volume") ?: 0
+                    syncSystemVolume(volume)
+                    result.success(null)
+                }
+                else -> {
+                    Log.d(TAG, "Unknown method: ${call.method}")
+                    result.notImplemented()
+                }
+            }
+        }
+    }
+
+    /// Start observing system STREAM_MUSIC volume changes.
+    /// When a change is detected, sends an "absoluteVolumeChange" event to Flutter
+    /// with the new volume mapped to 0-100 scale.
+    private fun startVolumeObserver(initialVolume: Int?) {
+        if (isObservingVolume) return
+
+        val am = audioManager ?: return
+
+        // Optionally set system volume to match the MA player's current volume
+        if (initialVolume != null) {
+            syncSystemVolume(initialVolume)
+        }
+
+        lastKnownVolume = am.getStreamVolume(AudioManager.STREAM_MUSIC)
+
+        volumeObserver = VolumeContentObserver(Handler(Looper.getMainLooper()))
+        contentResolver.registerContentObserver(
+            Settings.System.CONTENT_URI,
+            true,
+            volumeObserver!!
+        )
+        isObservingVolume = true
+        Log.d(TAG, "Volume observer STARTED, initial system volume: $lastKnownVolume")
+    }
+
+    /// Stop observing system volume changes.
+    private fun stopVolumeObserver() {
+        if (!isObservingVolume) return
+
+        volumeObserver?.let {
+            contentResolver.unregisterContentObserver(it)
+        }
+        volumeObserver = null
+        isObservingVolume = false
+        Log.d(TAG, "Volume observer STOPPED")
+    }
+
+    /// Set the system STREAM_MUSIC volume to match an MA player volume (0-100).
+    /// Maps MA's 0-100 range to the device's 0-maxVolume range.
+    private fun syncSystemVolume(maVolume: Int) {
+        val am = audioManager ?: return
+        val maxSystemVolume = am.getStreamMaxVolume(AudioManager.STREAM_MUSIC)
+        val systemVolume = (maVolume * maxSystemVolume / 100).coerceIn(0, maxSystemVolume)
+
+        ignoringVolumeChange = true
+        am.setStreamVolume(AudioManager.STREAM_MUSIC, systemVolume, 0)
+        lastKnownVolume = systemVolume
+        ignoringVolumeChange = false
+        Log.d(TAG, "Synced system volume: MA $maVolume% -> system $systemVolume/$maxSystemVolume")
+    }
+
+    /// ContentObserver that watches for system volume changes.
+    /// When volume changes (e.g., from lockscreen hardware buttons),
+    /// maps the change to a 0-100 value and sends to Flutter.
+    inner class VolumeContentObserver(handler: Handler) : ContentObserver(handler) {
+        override fun onChange(selfChange: Boolean) {
+            super.onChange(selfChange)
+
+            if (ignoringVolumeChange) return
+
+            val am = audioManager ?: return
+            val currentVolume = am.getStreamVolume(AudioManager.STREAM_MUSIC)
+
+            if (currentVolume != lastKnownVolume) {
+                val maxVolume = am.getStreamMaxVolume(AudioManager.STREAM_MUSIC)
+                val maVolume = if (maxVolume > 0) (currentVolume * 100 / maxVolume) else 0
+
+                Log.d(TAG, "Volume observer: system $lastKnownVolume -> $currentVolume (MA: $maVolume%)")
+                lastKnownVolume = currentVolume
+
+                // Send the absolute volume (0-100) to Flutter
+                methodChannel?.invokeMethod("absoluteVolumeChange", maVolume)
+            }
+        }
+    }
+
+    // Use dispatchKeyEvent instead of onKeyDown - Flutter's engine uses dispatchKeyEvent
+    // and may consume events before they reach onKeyDown
+    override fun dispatchKeyEvent(event: KeyEvent?): Boolean {
+        if (event == null) {
+            return super.dispatchKeyEvent(event)
+        }
+
+        val keyCode = event.keyCode
+        val action = event.action
+
+        Log.d(TAG, "dispatchKeyEvent: keyCode=$keyCode, action=$action, isListening=$isListening")
+
+        // Only handle KEY_DOWN events to avoid double-triggering (down + up)
+        if (action != KeyEvent.ACTION_DOWN) {
+            // For volume keys when listening, also consume ACTION_UP to fully block system volume
+            if (isListening && (keyCode == KeyEvent.KEYCODE_VOLUME_UP || keyCode == KeyEvent.KEYCODE_VOLUME_DOWN)) {
+                Log.d(TAG, "Consuming ACTION_UP for volume key")
+                return true
+            }
+            return super.dispatchKeyEvent(event)
+        }
+
+        if (!isListening) {
+            Log.d(TAG, "Not listening, passing to super")
+            return super.dispatchKeyEvent(event)
+        }
+
+        return when (keyCode) {
+            KeyEvent.KEYCODE_VOLUME_UP -> {
+                Log.d(TAG, "VOLUME UP pressed - sending to Flutter")
+                methodChannel?.invokeMethod("volumeUp", null)
+                true // Consume the event to prevent system volume change
+            }
+            KeyEvent.KEYCODE_VOLUME_DOWN -> {
+                Log.d(TAG, "VOLUME DOWN pressed - sending to Flutter")
+                methodChannel?.invokeMethod("volumeDown", null)
+                true // Consume the event to prevent system volume change
+            }
+            else -> {
+                Log.d(TAG, "Other key, passing to super")
+                super.dispatchKeyEvent(event)
+            }
+        }
+    }
+
+    // Pause volume interception when app goes to background so hardware buttons
+    // only control the system volume (e.g., YouTube, phone ringer) as expected.
+    private var wasListeningBeforePause = false
+    private var wasObservingBeforePause = false
+
+    override fun onPause() {
+        wasListeningBeforePause = isListening
+        wasObservingBeforePause = isObservingVolume
+        isListening = false
+        stopVolumeObserver()
+        Log.d(TAG, "onPause: suspended volume interception (wasListening=$wasListeningBeforePause, wasObserving=$wasObservingBeforePause)")
+        super.onPause()
+    }
+
+    override fun onResume() {
+        super.onResume()
+        if (wasListeningBeforePause) {
+            isListening = true
+        }
+        if (wasObservingBeforePause) {
+            startVolumeObserver(null)
+        }
+        Log.d(TAG, "onResume: restored volume interception (listening=$isListening, observing=$isObservingVolume)")
+    }
+
+    override fun onDestroy() {
+        stopVolumeObserver()
+        super.onDestroy()
+    }
+}

android/app/src/main/kotlin/com/musicassistant/music_assistant/MainActivity.kt

@@ -1,87 +0,0 @@
-package com.musicassistant.music_assistant
-
-import android.util.Log
-import android.view.KeyEvent
-import com.ryanheise.audioservice.AudioServiceActivity
-import io.flutter.embedding.engine.FlutterEngine
-import io.flutter.plugin.common.MethodChannel
-
-// Extend AudioServiceActivity instead of FlutterActivity to support audio_service package
-// while also intercepting volume button events
-class MainActivity: AudioServiceActivity() {
-    private val TAG = "EnsembleVolume"
-    private val CHANNEL = "com.musicassistant.music_assistant/volume_buttons"
-    private var methodChannel: MethodChannel? = null
-    private var isListening = false
-
-    override fun configureFlutterEngine(flutterEngine: FlutterEngine) {
-        super.configureFlutterEngine(flutterEngine)
-        Log.d(TAG, "Configuring Flutter engine, setting up MethodChannel")
-
-        methodChannel = MethodChannel(flutterEngine.dartExecutor.binaryMessenger, CHANNEL)
-        methodChannel?.setMethodCallHandler { call, result ->
-            Log.d(TAG, "Received method call: ${call.method}")
-            when (call.method) {
-                "startListening" -> {
-                    isListening = true
-                    Log.d(TAG, "Volume listening ENABLED")
-                    result.success(null)
-                }
-                "stopListening" -> {
-                    isListening = false
-                    Log.d(TAG, "Volume listening DISABLED")
-                    result.success(null)
-                }
-                else -> {
-                    Log.d(TAG, "Unknown method: ${call.method}")
-                    result.notImplemented()
-                }
-            }
-        }
-    }
-
-    // Use dispatchKeyEvent instead of onKeyDown - Flutter's engine uses dispatchKeyEvent
-    // and may consume events before they reach onKeyDown
-    override fun dispatchKeyEvent(event: KeyEvent?): Boolean {
-        if (event == null) {
-            return super.dispatchKeyEvent(event)
-        }
-
-        val keyCode = event.keyCode
-        val action = event.action
-
-        Log.d(TAG, "dispatchKeyEvent: keyCode=$keyCode, action=$action, isListening=$isListening")
-
-        // Only handle KEY_DOWN events to avoid double-triggering (down + up)
-        if (action != KeyEvent.ACTION_DOWN) {
-            // For volume keys when listening, also consume ACTION_UP to fully block system volume
-            if (isListening && (keyCode == KeyEvent.KEYCODE_VOLUME_UP || keyCode == KeyEvent.KEYCODE_VOLUME_DOWN)) {
-                Log.d(TAG, "Consuming ACTION_UP for volume key")
-                return true
-            }
-            return super.dispatchKeyEvent(event)
-        }
-
-        if (!isListening) {
-            Log.d(TAG, "Not listening, passing to super")
-            return super.dispatchKeyEvent(event)
-        }
-
-        return when (keyCode) {
-            KeyEvent.KEYCODE_VOLUME_UP -> {
-                Log.d(TAG, "VOLUME UP pressed - sending to Flutter")
-                methodChannel?.invokeMethod("volumeUp", null)
-                true // Consume the event to prevent system volume change
-            }
-            KeyEvent.KEYCODE_VOLUME_DOWN -> {
-                Log.d(TAG, "VOLUME DOWN pressed - sending to Flutter")
-                methodChannel?.invokeMethod("volumeDown", null)
-                true // Consume the event to prevent system volume change
-            }
-            else -> {
-                Log.d(TAG, "Other key, passing to super")
-                super.dispatchKeyEvent(event)
-            }
-        }
-    }
-}

android/app/src/main/res/drawable/ic_auto_album.xml

@@ -0,0 +1,9 @@
+<vector xmlns:android="http://schemas.android.com/apk/res/android"
+    android:width="24dp"
+    android:height="24dp"
+    android:viewportWidth="24"
+    android:viewportHeight="24"
+    android:tint="#FFFFFF">
+  <path android:fillColor="#FFFFFF"
+      android:pathData="M12,2C6.48,2 2,6.48 2,12s4.48,10 10,10 10,-4.48 10,-10S17.52,2 12,2zM12,16.5c-2.49,0 -4.5,-2.01 -4.5,-4.5S9.51,7.5 12,7.5s4.5,2.01 4.5,4.5 -2.01,4.5 -4.5,4.5zM12,11c-0.55,0 -1,0.45 -1,1s0.45,1 1,1 1,-0.45 1,-1 -0.45,-1 -1,-1z"/>
+</vector>

android/app/src/main/res/drawable/ic_auto_artist.xml

@@ -0,0 +1,9 @@
+<vector xmlns:android="http://schemas.android.com/apk/res/android"
+    android:width="24dp"
+    android:height="24dp"
+    android:viewportWidth="24"
+    android:viewportHeight="24"
+    android:tint="#FFFFFF">
+  <path android:fillColor="#FFFFFF"
+      android:pathData="M12,12c2.21,0 4,-1.79 4,-4s-1.79,-4 -4,-4 -4,1.79 -4,4 1.79,4 4,4zM12,14c-2.67,0 -8,1.34 -8,4v2h16v-2c0,-2.66 -5.33,-4 -8,-4z"/>
+</vector>

android/app/src/main/res/drawable/ic_auto_book.xml

@@ -0,0 +1,9 @@
+<vector xmlns:android="http://schemas.android.com/apk/res/android"
+    android:width="24dp"
+    android:height="24dp"
+    android:viewportWidth="24"
+    android:viewportHeight="24"
+    android:tint="#FFFFFF">
+  <path android:fillColor="#FFFFFF"
+      android:pathData="M18,2H6c-1.1,0 -2,0.9 -2,2v16c0,1.1 0.9,2 2,2h12c1.1,0 2,-0.9 2,-2V4c0,-1.1 -0.9,-2 -2,-2zM6,4h5v8l-2.5,-1.5L6,12V4z"/>
+</vector>

android/app/src/main/res/drawable/ic_auto_favorite.xml

@@ -0,0 +1,9 @@
+<vector xmlns:android="http://schemas.android.com/apk/res/android"
+    android:width="24dp"
+    android:height="24dp"
+    android:viewportWidth="24"
+    android:viewportHeight="24"
+    android:tint="#FFFFFF">
+  <path android:fillColor="#FFFFFF"
+      android:pathData="M12,21.35l-1.45,-1.32C5.4,15.36 2,12.28 2,8.5 2,5.42 4.42,3 7.5,3c1.74,0 3.41,0.81 4.5,2.09C13.09,3.81 14.76,3 16.5,3 19.58,3 22,5.42 22,8.5c0,3.78 -3.4,6.86 -8.55,11.54L12,21.35z"/>
+</vector>

android/app/src/main/res/drawable/ic_auto_home.xml

@@ -0,0 +1,9 @@
+<vector xmlns:android="http://schemas.android.com/apk/res/android"
+    android:width="24dp"
+    android:height="24dp"
+    android:viewportWidth="24"
+    android:viewportHeight="24"
+    android:tint="#FFFFFF">
+  <path android:fillColor="#FFFFFF"
+      android:pathData="M10,20v-6h4v6h5v-8h3L12,3 2,12h3v8z"/>
+</vector>

android/app/src/main/res/drawable/ic_auto_music.xml

@@ -0,0 +1,9 @@
+<vector xmlns:android="http://schemas.android.com/apk/res/android"
+    android:width="24dp"
+    android:height="24dp"
+    android:viewportWidth="24"
+    android:viewportHeight="24"
+    android:tint="#FFFFFF">
+  <path android:fillColor="#FFFFFF"
+      android:pathData="M12,3v10.55c-0.59,-0.34 -1.27,-0.55 -2,-0.55C7.79,13 6,14.79 6,17s1.79,4 4,4 4,-1.79 4,-4V7h4V3h-6z"/>
+</vector>

android/app/src/main/res/drawable/ic_auto_playlist.xml

@@ -0,0 +1,9 @@
+<vector xmlns:android="http://schemas.android.com/apk/res/android"
+    android:width="24dp"
+    android:height="24dp"
+    android:viewportWidth="24"
+    android:viewportHeight="24"
+    android:tint="#FFFFFF">
+  <path android:fillColor="#FFFFFF"
+      android:pathData="M15,6H3v2h12V6zM15,10H3v2h12V10zM3,16h8v-2H3V16zM17,6v8.18C16.69,14.07 16.35,14 16,14c-1.66,0 -3,1.34 -3,3s1.34,3 3,3 3,-1.34 3,-3V8h3V6H17z"/>
+</vector>

android/app/src/main/res/drawable/ic_auto_podcast.xml

@@ -0,0 +1,11 @@
+<vector xmlns:android="http://schemas.android.com/apk/res/android"
+    android:width="24dp"
+    android:height="24dp"
+    android:viewportWidth="24"
+    android:viewportHeight="24"
+    android:tint="#FFFFFF">
+  <path android:fillColor="#FFFFFF"
+      android:pathData="M12,14c1.66,0 3,-1.34 3,-3V5c0,-1.66 -1.34,-3 -3,-3S9,3.34 9,5v6c0,1.66 1.34,3 3,3z"/>
+  <path android:fillColor="#FFFFFF"
+      android:pathData="M17,11c0,2.76 -2.24,5 -5,5s-5,-2.24 -5,-5H5c0,3.53 2.61,6.43 6,6.92V21h2v-3.08c3.39,-0.49 6,-3.39 6,-6.92h-2z"/>
+</vector>

android/app/src/main/res/drawable/ic_auto_radio.xml

@@ -0,0 +1,9 @@
+<vector xmlns:android="http://schemas.android.com/apk/res/android"
+    android:width="24dp"
+    android:height="24dp"
+    android:viewportWidth="24"
+    android:viewportHeight="24"
+    android:tint="#FFFFFF">
+  <path android:fillColor="#FFFFFF"
+      android:pathData="M3.24,6.15C2.51,6.43 2,7.17 2,8v12c0,1.1 0.89,2 2,2h16c1.1,0 2,-0.9 2,-2V8c0,-1.1 -0.9,-2 -2,-2H8.3l8.26,-3.34 -0.37,-0.92L3.24,6.15zM7,20c-1.66,0 -3,-1.34 -3,-3s1.34,-3 3,-3 3,1.34 3,3 -1.34,3 -3,3zM20,12H12V9h8v3z"/>
+</vector>

android/app/src/main/res/mipmap-anydpi-v26/ic_launcher.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="utf-8"?>
+<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
+  <background android:drawable="@color/ic_launcher_background"/>
+  <foreground android:drawable="@drawable/ic_launcher_foreground"/>
+</adaptive-icon>

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

@@ -1,4 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
 <resources>
     <color name="launch_background_color">#1a1a1a</color>
-</resources>
+	<color name="ic_launcher_background">#1a1a1a</color>
+</resources>

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

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="utf-8"?>
+<automotiveApp>
+    <uses name="media" />
+</automotiveApp>

android/build.gradle

@@ -1,12 +1,12 @@
 buildscript {
-    ext.kotlin_version = '1.9.10'
+    ext.kotlin_version = '2.1.0'
     repositories {
         google()
         mavenCentral()
     }
 
     dependencies {
-        classpath 'com.android.tools.build:gradle:8.1.0'
+        classpath 'com.android.tools.build:gradle:8.9.1'
         classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
     }
 }

android/gradle/wrapper/gradle-wrapper.properties

@@ -0,0 +1,5 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.11.1-all.zip

android/init.gradle

@@ -0,0 +1,37 @@
+// Force all repositories to use mirrors first
+allprojects {
+    repositories {
+        all { ArtifactRepository repo ->
+            if (repo instanceof MavenArtifactRepository) {
+                def url = repo.url.toString()
+                if (url.contains('repo.maven.apache.org') || url.contains('repo1.maven.org')) {
+                    remove repo
+                }
+            }
+        }
+        // Add mirrors before Maven Central
+        maven { url 'https://maven.aliyun.com/repository/central' }
+        maven { url 'https://maven.aliyun.com/repository/google' }
+        maven { url 'https://maven.aliyun.com/repository/gradle-plugin' }
+        maven { url 'https://maven.aliyun.com/repository/public' }
+    }
+}
+
+settingsEvaluated { settings ->
+    settings.pluginManagement {
+        repositories {
+            all { ArtifactRepository repo ->
+                if (repo instanceof MavenArtifactRepository) {
+                    def url = repo.url.toString()
+                    if (url.contains('repo.maven.apache.org') || url.contains('repo1.maven.org')) {
+                        remove repo
+                    }
+                }
+            }
+            maven { url 'https://maven.aliyun.com/repository/central' }
+            maven { url 'https://maven.aliyun.com/repository/google' }
+            maven { url 'https://maven.aliyun.com/repository/gradle-plugin' }
+            maven { url 'https://maven.aliyun.com/repository/public' }
+        }
+    }
+}

android/settings.gradle

@@ -22,8 +22,8 @@ pluginManagement {
 
 plugins {
     id "dev.flutter.flutter-plugin-loader" version "1.0.0"
-    id "com.android.application" version "8.1.0" apply false
-    id "org.jetbrains.kotlin.android" version "1.9.10" apply false
+    id "com.android.application" version "8.9.1" apply false
+    id "org.jetbrains.kotlin.android" version "2.1.0" apply false
 }
 
 include ":app"

docs/PER_PROVIDER_SYNC_IMPLEMENTATION.md

@@ -0,0 +1,336 @@
+# Per-Provider Sync Implementation
+
+## Date: January 17, 2026
+
+## Overview
+
+This document details the implementation of per-provider sync with source tracking, enabling instant client-side filtering that properly differentiates between multiple accounts of the same provider type (e.g., two different Spotify accounts).
+
+## Problem Statement
+
+### The Core Issue
+
+When a user has multiple accounts of the same provider type (e.g., two Spotify accounts: "Chris Laycock" and "Bababagoly"), the existing provider filter couldn't differentiate between them.
+
+**Why?** Music Assistant's `provider_mappings` field on media items shows which providers **CAN PLAY** an item, not which provider **ADDED** it. When both Spotify accounts can play the same artist, both appear in `provider_mappings`, making client-side filtering impossible.
+
+### Previous Approach (Failed)
+
+The initial implementation tried to filter client-side using `provider_mappings`:
+
+```dart
+bool isItemAllowedByProviderFilter(MediaItem item) {
+  final mappings = item.providerMappings;
+  for (final mapping in mappings) {
+    if (_providerFilter.contains(mapping.providerInstance)) {
+      return true;
+    }
+  }
+  return false;
+}
+```
+
+**Result:** Both Spotify accounts showed the same items because `provider_mappings` contained both account IDs for shared content.
+
+### Race Condition Issue
+
+Additionally, when rapidly toggling providers, a race condition occurred:
+1. User toggles Provider A off
+2. Sync starts for remaining providers
+3. User toggles Provider B off before sync completes
+4. First sync completes with wrong filter state
+5. UI shows incorrect results
+
+## Solution: Per-Provider Sync with Source Tracking
+
+### Concept
+
+Instead of relying on `provider_mappings`, we:
+1. **Sync each provider separately** using the MA API's `provider` parameter
+2. **Tag each item** with which provider instance(s) returned it
+3. **Store source tracking** in the local database
+4. **Filter client-side** using the source tracking data (instant)
+5. **Background sync** keeps data fresh without blocking UI
+
+### Why This Works
+
+When we call the MA API with `provider: ["spotify--RKnr3jKx"]`, the server returns **only items from that specific account's library**. By syncing each provider separately and remembering which provider returned each item, we can accurately filter.
+
+## Implementation Details
+
+### 1. Database Schema Update
+
+**File:** `lib/database/database.dart`
+
+Added `sourceProviders` column to `LibraryCache` table:
+
+```dart
+class LibraryCache extends Table {
+  // ... existing columns ...
+
+  /// Provider instance IDs that provided this item (JSON array)
+  /// Used for client-side filtering by source provider
+  TextColumn get sourceProviders => text().withDefault(const Constant('[]'))();
+}
+```
+
+**Schema version:** 5 → 6
+
+**Migration:**
+```dart
+if (from < 6) {
+  await customStatement(
+    "ALTER TABLE library_cache ADD COLUMN source_providers TEXT NOT NULL DEFAULT '[]'"
+  );
+}
+```
+
+### 2. Database Service Updates
+
+**File:** `lib/services/database_service.dart`
+
+Added `sourceProvider` parameter to `cacheItem()`:
+
+```dart
+Future<void> cacheItem<T>({
+  required String itemType,
+  required String itemId,
+  required Map<String, dynamic> data,
+  String? sourceProvider,  // NEW: tracks which provider this item came from
+})
+```
+
+Added new method to retrieve items with source tracking:
+
+```dart
+Future<List<(Map<String, dynamic>, List<String>)>> getCachedItemsWithProviders(String itemType)
+```
+
+Returns tuples of `(itemData, sourceProviderIds)`.
+
+### 3. SyncService Rewrite
+
+**File:** `lib/services/sync_service.dart`
+
+#### New Fields
+
+```dart
+// Source provider tracking for client-side filtering
+Map<String, List<String>> _albumSourceProviders = {};
+Map<String, List<String>> _artistSourceProviders = {};
+Map<String, List<String>> _audiobookSourceProviders = {};
+Map<String, List<String>> _playlistSourceProviders = {};
+```
+
+#### Per-Provider Sync Logic
+
+```dart
+Future<void> syncFromApi(MusicAssistantAPI api, {
+  bool force = false,
+  List<String>? providerInstanceIds,
+}) async {
+  // If specific providers are requested, sync each separately
+  if (providerInstanceIds != null && providerInstanceIds.isNotEmpty) {
+    for (final providerId in providerInstanceIds) {
+      // Fetch from this specific provider
+      final results = await Future.wait([
+        api.getAlbums(limit: 1000, providerInstanceIds: [providerId]),
+        api.getArtists(limit: 1000, providerInstanceIds: [providerId]),
+        // ... etc
+      ]);
+
+      // Track source provider for each item
+      for (final album in albums) {
+        albumMap[album.itemId] = album;
+        _albumSourceProviders.putIfAbsent(album.itemId, () => []);
+        if (!_albumSourceProviders[album.itemId]!.contains(providerId)) {
+          _albumSourceProviders[album.itemId]!.add(providerId);
+        }
+      }
+    }
+  }
+}
+```
+
+#### Client-Side Filtering Methods
+
+```dart
+/// Filter albums by source provider (instant, no network)
+List<Album> getAlbumsFilteredByProviders(Set<String> enabledProviderIds) {
+  if (enabledProviderIds.isEmpty || _albumSourceProviders.isEmpty) {
+    return _cachedAlbums;
+  }
+  return _cachedAlbums.where((album) {
+    final sources = _albumSourceProviders[album.itemId];
+    if (sources == null || sources.isEmpty) return true; // No tracking = show
+    return sources.any((s) => enabledProviderIds.contains(s));
+  }).toList();
+}
+
+// Similar methods for artists, audiobooks, playlists
+```
+
+### 4. Library Screen Updates
+
+**File:** `lib/screens/new_library_screen.dart`
+
+#### Hybrid Provider Toggle Handler
+
+```dart
+void _handleProviderToggle(String providerId, bool enabled) {
+  final maProvider = context.read<MusicAssistantProvider>();
+
+  // Instant UI update via global provider toggle
+  maProvider.toggleProviderEnabled(providerId, enabled);
+  setState(() {}); // Rebuild with client-side filtering
+
+  // Background sync after 1.5s debounce
+  _providerFilterDebounce?.cancel();
+  _providerFilterDebounce = Timer(const Duration(milliseconds: 1500), () async {
+    if (mounted) {
+      await maProvider.forceLibrarySync();
+      if (mounted) setState(() {});
+    }
+  });
+}
+```
+
+#### Updated Tab Builders
+
+Artists tab now uses source tracking:
+
+```dart
+Widget _buildArtistsTab(BuildContext context, S l10n) {
+  return Selector<MusicAssistantProvider, (List<Artist>, bool, Set<String>)>(
+    selector: (_, provider) => (
+      provider.artists,
+      provider.isLoading,
+      provider.enabledProviderIds.toSet()
+    ),
+    builder: (context, data, _) {
+      final (allArtists, isLoading, enabledProviders) = data;
+
+      // Client-side filtering using SyncService source tracking
+      final syncService = SyncService.instance;
+      final filteredArtists = syncService.hasSourceTracking && enabledProviders.isNotEmpty
+          ? syncService.getArtistsFilteredByProviders(enabledProviders)
+          : allArtists;
+
+      // ... rest of build
+    },
+  );
+}
+```
+
+Similar updates for albums, playlists, and audiobooks tabs.
+
+### 5. Provider Instance Model
+
+**File:** `lib/models/provider_instance.dart` (new file)
+
+```dart
+class ProviderInstance {
+  final String instanceId;  // e.g., "spotify--abc123"
+  final String domain;      // e.g., "spotify"
+  final String name;        // e.g., "Spotify (John's Account)"
+  final bool available;
+
+  /// Known music provider domains
+  static const Set<String> musicProviderDomains = {
+    'spotify', 'tidal', 'qobuz', 'deezer', 'ytmusic', 'soundcloud',
+    'apple_music', 'amazon_music', 'plex', 'subsonic', 'opensubsonic',
+    'jellyfin', 'emby', 'navidrome', 'audiobookshelf', 'filesystem',
+    'tunein', 'radiobrowser', 'snapcast', 'fully_kiosk',
+  };
+
+  bool get isMusicProvider => musicProviderDomains.contains(domain);
+}
+```
+
+## Data Flow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                     User Toggles Provider                        │
+└─────────────────────────────────────────────────────────────────┘
+                                │
+                                ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  1. MusicAssistantProvider.toggleProviderEnabled()              │
+│     - Updates enabledProviderIds                                │
+│     - Triggers setState() for instant UI update                 │
+└─────────────────────────────────────────────────────────────────┘
+                                │
+                                ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  2. UI Rebuilds Immediately                                     │
+│     - Selector detects enabledProviderIds change                │
+│     - Calls SyncService.getArtistsFilteredByProviders()         │
+│     - Filters using source tracking (instant, no network)       │
+└─────────────────────────────────────────────────────────────────┘
+                                │
+                                ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  3. Background Sync (after 1.5s debounce)                       │
+│     - forceLibrarySync() called                                 │
+│     - Syncs each enabled provider separately                    │
+│     - Updates source tracking in database                       │
+│     - UI refreshes with fresh data                              │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Files Changed
+
+| File | Changes |
+|------|---------|
+| `lib/database/database.dart` | Added `sourceProviders` column, schema v6, migration |
+| `lib/database/database.g.dart` | Auto-generated from schema changes |
+| `lib/services/database_service.dart` | Added `sourceProvider` param, `getCachedItemsWithProviders()` |
+| `lib/services/sync_service.dart` | Per-provider sync, source tracking maps, filtering methods |
+| `lib/screens/new_library_screen.dart` | Hybrid toggle handler, updated tab builders |
+| `lib/models/provider_instance.dart` | New model for provider instances |
+
+## Testing Checklist
+
+- [ ] Fresh install: First sync should populate source tracking
+- [ ] Toggle single provider: UI updates instantly
+- [ ] Toggle multiple providers rapidly: Debounce prevents race conditions
+- [ ] Two Spotify accounts: Toggling one only shows that account's items
+- [ ] Mixed providers: Toggling Spotify doesn't affect Audiobookshelf items
+- [ ] Legacy cache: Items without source tracking show regardless of filter
+- [ ] Pull to refresh: Refreshes source tracking data
+
+## Known Limitations
+
+1. **First sync required:** Source tracking only works after at least one sync with providers enabled
+2. **Network cost:** Per-provider sync makes N API calls (one per provider) vs. 1 call for all providers
+3. **Items in multiple accounts:** If the same item exists in both Spotify accounts, it will show when either is enabled
+
+## Future Improvements
+
+1. **Incremental sync:** Only sync changed items instead of full library
+2. **Provider-specific cache age:** Different sync intervals per provider
+3. **Offline source tracking:** Persist source tracking independently of full cache
+
+## Branch
+
+All changes are on the `feature/per-provider-sync` branch.
+
+```bash
+git checkout feature/per-provider-sync
+```
+
+## Commit
+
+```
+feat: Add per-provider sync with source tracking for instant filtering
+
+- Add sourceProviders column to database schema (v6) for tracking which
+  provider instance each item came from
+- Update SyncService to sync each enabled provider separately and tag
+  items with their source provider
+- Add client-side filtering methods that use source tracking to properly
+  differentiate between multiple accounts of the same provider type
+- Update library UI to use instant client-side filtering with background
+  sync for data freshness
+```

docs/PROVIDER_FILTER_IMPLEMENTATION.md

@@ -0,0 +1,217 @@
+# Provider Filter Implementation Notes
+
+## Overview
+
+This document captures the context and learnings from an attempted implementation of provider filtering in the Ensemble app. The goal was to allow users to filter their library to show only items from a specific music provider (e.g., only one Spotify account when multiple are configured).
+
+## The Problem
+
+Users with multiple music provider accounts (e.g., two Spotify accounts: one personal, one family) want to filter their library view to show only items from one specific account. The Music Assistant (MA) web UI successfully implements this feature.
+
+## What Works vs What Failed
+
+### Works: Different Provider Types
+Filtering between different provider types (e.g., Spotify vs Tidal vs Plex) works correctly. Each provider type has distinct `provider_mappings` entries.
+
+### Failed: Multiple Accounts of Same Provider
+Filtering between multiple Spotify accounts (e.g., `spotify--abc123` vs `spotify--xyz789`) does NOT work correctly. The same library items appear regardless of which Spotify account is selected.
+
+## Root Cause Analysis
+
+### The provider_mappings Problem
+
+MA's `provider_mappings` field on media items does NOT indicate "which account ADDED this item to the library." Instead, it indicates "which providers CAN PLAY this item."
+
+Example: An artist "Ari Mason" that exists ONLY in User A's Spotify library will show provider_mappings containing BOTH Spotify accounts:
+```json
+{
+  "provider_mappings": [
+    {"provider_instance": "spotify--userA_id", "item_id": "..."},
+    {"provider_instance": "spotify--userB_id", "item_id": "..."}
+  ]
+}
+```
+
+This happens because:
+1. MA's internal database stores that the artist exists
+2. MA knows both Spotify accounts CAN play this artist (Spotify has the content)
+3. MA doesn't track WHICH account originally added the item to the library
+
+### MA Web UI Behavior
+
+The MA web UI's provider filter works differently - it appears to use server-side filtering via the `provider` parameter on library_items API calls. When you select a single provider in MA settings, the API returns only items from that provider's library.
+
+## API Investigation
+
+### Server-Side Filtering Parameter
+
+The MA server's `library_items` method accepts a `provider` parameter:
+- Parameter name: `provider` (string or list of strings)
+- Endpoint: `music/{type}/library_items` (e.g., `music/artists/library_items`)
+- Expected behavior: Filter to only return items from the specified provider's library
+
+### What We Tried
+
+1. **Client-side filtering based on provider_mappings**
+   - Result: Failed - all Spotify accounts appear in mappings regardless of which added the item
+
+2. **Server-side filtering with `provider` parameter**
+   - Result: Partially implemented but behavior was inconsistent
+   - The API accepts the parameter but may not filter correctly for same-provider-type accounts
+
+3. **Using `provider_instance_id_or_domain` parameter**
+   - Result: This parameter is for getting specific items by ID, not for filtering library_items
+
+## Code Locations
+
+### Files Modified (in stash)
+
+The implementation attempt is preserved in git stash:
+```bash
+git stash list  # Look for "provider-filter-and-dropdown-work"
+git stash show -p stash@{0}  # View the changes
+```
+
+Key files that were modified:
+
+1. **lib/providers/music_assistant_provider.dart**
+   - `_disabledProviders`: List of disabled provider instance IDs (local app setting)
+   - `selectedProviderForFilter`: Returns single enabled provider for server-side filtering
+   - `toggleProviderEnabled()`: Toggle provider on/off and trigger re-sync
+   - `loadDisabledProviders()`: Load from local settings
+   - `filterByProvider()`: Client-side filtering (enhanced version)
+   - `isItemAllowedByProviderFilter()`: Check if item should be visible
+
+2. **lib/services/music_assistant_api.dart**
+   - Added `provider` parameter to: `getArtists`, `getAlbums`, `getTracks`, `getRandomArtists`, `getRandomAlbums`
+   - Added `MusicProvider` model parsing from `/providers` endpoint
+   - `musicProviders` getter: List of available music providers
+
+3. **lib/services/sync_service.dart**
+   - Added `provider` parameter to `syncFromApi()` and `forceSync()`
+   - Pass provider filter to API calls during sync
+
+4. **lib/services/settings_service.dart**
+   - `getDisabledMusicProviders()`: Get list of disabled provider IDs
+   - `setDisabledMusicProviders()`: Save disabled providers
+   - `toggleProviderEnabled()`: Toggle and persist
+
+5. **lib/screens/settings_screen.dart**
+   - UI for toggling individual providers on/off
+   - Display provider name and instance ID
+
+6. **lib/screens/new_library_screen.dart**
+   - Integration with provider filtering
+
+7. **lib/models/music_provider.dart** (new file)
+   - Model for MA provider instances
+   - Fields: `instanceId`, `domain`, `name`, `available`
+
+## Race Condition Issue
+
+A race condition was identified where:
+1. Initial app sync starts WITHOUT provider filter
+2. User toggles provider filter
+3. `clearCache()` is called
+4. New sync with provider filter tries to start
+5. "Sync already in progress" - new sync is skipped
+6. Result: Old unfiltered data remains
+
+Fix attempted: Reset `_isSyncing = false` in `clearCache()` to allow fresh sync.
+
+## Potential Solutions to Explore
+
+### 1. Investigate MA Server-Side Filtering
+
+The MA server should support filtering by provider. Need to verify:
+- Does the `provider` parameter work for filtering between same-type providers?
+- Is there a different parameter or API endpoint?
+- Check MA source code: https://github.com/music-assistant/server
+
+### 2. Library Sync Per Provider
+
+Instead of syncing all items and filtering, sync each provider's library separately:
+```dart
+for (final provider in enabledProviders) {
+  final items = await api.getAlbums(provider: provider.instanceId);
+  // Store with provider association
+}
+```
+
+### 3. Track Item Origin
+
+Store which provider originally added each item:
+- Modify database schema to track `source_provider`
+- When syncing, record which provider the item came from
+- Filter based on source, not playability
+
+### 4. Use MA's Internal Library State
+
+MA might have internal state about which items are in which provider's library. Investigate:
+- `/music/library/items` endpoint
+- Provider-specific library endpoints
+- MA's database schema for library associations
+
+### 5. Check MA User Settings
+
+The MA web UI's provider filter might be stored in user settings:
+```dart
+final userInfo = await api.getCurrentUserInfo();
+// Check for provider_filter or similar field
+```
+
+## Testing Notes
+
+### Log Messages to Watch
+
+```
+🔌 Selected provider for filter: spotify--xxxxx
+🔍 API getArtists args: {limit: 1000, provider: spotify--xxxxx}
+🔍 API getArtists returned XXX items
+🔌 filterByProvider: XXX → YYY (disabled=[...])
+```
+
+### Test Scenario
+
+1. Configure two Spotify accounts in MA
+2. Add different artists to each account's library
+3. In Ensemble, select only one Spotify account
+4. Verify library shows ONLY that account's items
+5. Switch to other account, verify different items
+
+### Expected vs Actual
+
+- **Expected**: Artist "Ari Mason" (only in Account A) should NOT appear when Account B is selected
+- **Actual**: Artist appears regardless of which account is selected
+
+## MA API Reference
+
+### Get Providers
+```
+Command: providers
+Returns: List of provider instances with type, domain, instanceId, name, available
+```
+
+### Library Items with Filter
+```
+Command: music/artists/library_items
+Args: {
+  limit: int,
+  offset: int,
+  provider: string | list<string>,  // Filter to specific provider(s)
+  album_artists_only: bool,
+  order_by: string
+}
+```
+
+### Relevant MA Source Files
+
+- `music_assistant/server/controllers/music.py` - Library item retrieval
+- `music_assistant/server/models/provider.py` - Provider model
+- `music_assistant/server/providers/` - Individual provider implementations
+
+## Conclusion
+
+The core challenge is that MA's `provider_mappings` indicates playability, not ownership. Server-side filtering via the `provider` parameter should work but needs further investigation to understand why it doesn't differentiate between multiple accounts of the same provider type.
+
+The implementation is preserved in the git stash for future reference. The sorting/dropdown improvements were extracted and committed separately.

docs/SESSION_2026_01_17_AUDIOBOOK_PROVIDER_FIX.md

@@ -0,0 +1,271 @@
+# Audiobook Provider Filtering Fix
+
+## Date: January 17, 2026 (Continuation)
+
+## Overview
+
+This session focused on fixing provider filtering issues discovered after the initial provider filtering improvements:
+1. Audiobooks were not responding to provider filter changes (browse API ignoring `providerInstanceIds`)
+2. UI not updating instantly when toggling providers (missing `notifyListeners()` call)
+3. Audiobook tabs not rebuilding on provider changes (using `context.read` instead of `Selector`)
+
+---
+
+## Problem Statement
+
+After implementing capability-based provider filtering for the music library, two issues remained:
+
+### Issue 1: Audiobooks Not Filtering During Sync
+
+The bug report showed:
+```
+📊 Source tracking: 252 albums, 87 artists have provider info
+📚 Total audiobooks from browse: 186
+```
+
+- Albums and artists had provider source tracking
+- Audiobooks had NO provider source tracking (not listed)
+- All 186 audiobooks were returned regardless of provider selection
+
+### Issue 2: UI Not Updating Instantly
+
+When toggling providers in the library menu:
+- Music tabs weren't updating immediately
+- Audiobooks required manual pull-to-refresh
+- Changes only appeared after ~600ms (debounce timer)
+
+---
+
+## Root Cause Analysis
+
+### Cause 1: Browse API Ignoring Provider Filter
+
+In `lib/services/music_assistant_api.dart`, when ABS library filtering is enabled, the `getAudiobooks()` function uses the browse API but was **ignoring** the `providerInstanceIds` parameter:
+
+```dart
+// BEFORE: providerInstanceIds was ignored when using browse API
+if (enabledLibraries != null && enabledLibraries.isNotEmpty) {
+  return await _getAudiobooksFromBrowse(enabledLibraries, favoriteOnly: favoriteOnly);
+}
+```
+
+### Cause 2: `notifyListeners()` Called Too Late
+
+In `lib/providers/music_assistant_provider.dart`, the `toggleProviderEnabled()` function only called `notifyListeners()` **inside** the 600ms debounce timer:
+
+```dart
+// BEFORE: notifyListeners only called after 600ms debounce
+_providerFilterDebounceTimer = Timer(const Duration(milliseconds: 600), () {
+  forceLibrarySync();
+  notifyListeners();  // Too late! UI should update immediately
+});
+```
+
+### Cause 3: Audiobook Tabs Not Listening for Changes
+
+The audiobook tabs used `context.read<MusicAssistantProvider>()` which doesn't trigger rebuilds when the provider changes:
+
+```dart
+// BEFORE: context.read doesn't listen for changes
+Widget _buildBooksAuthorsTab(BuildContext context, S l10n) {
+  final maProvider = context.read<MusicAssistantProvider>();
+  final enabledProviders = maProvider.enabledProviderIds.toSet();
+  // ... widget doesn't rebuild when enabledProviders changes
+}
+```
+
+---
+
+## Solutions
+
+### Fix 1: Browse API Provider Filtering
+
+**File:** `lib/services/music_assistant_api.dart` (lines 760-785)
+
+Added logic to filter library paths by provider ID before browsing:
+
+```dart
+if (enabledLibraries != null && enabledLibraries.isNotEmpty) {
+  _logger.log('📚 getAudiobooks: enabledLibraries=$enabledLibraries, providerInstanceIds=$providerInstanceIds');
+
+  // If specific providers are requested, filter libraries to only matching providers
+  // Library paths start with provider ID (e.g., "audiobookshelf--abc123://lb...")
+  var librariesToBrowse = enabledLibraries;
+  if (providerInstanceIds != null && providerInstanceIds.isNotEmpty) {
+    librariesToBrowse = enabledLibraries.where((libPath) {
+      // Extract provider ID from library path (everything before "://")
+      final providerEnd = libPath.indexOf('://');
+      if (providerEnd == -1) return false;
+      final providerId = libPath.substring(0, providerEnd);
+      return providerInstanceIds.contains(providerId);
+    }).toList();
+
+    // If no libraries match the requested providers, return empty
+    if (librariesToBrowse.isEmpty) {
+      return [];
+    }
+  }
+  return await _getAudiobooksFromBrowse(librariesToBrowse, favoriteOnly: favoriteOnly);
+}
+```
+
+### Fix 2: Immediate `notifyListeners()` Call
+
+**File:** `lib/providers/music_assistant_provider.dart` (line 1149)
+
+Moved `notifyListeners()` to fire immediately after `_enabledProviderIds` changes:
+
+```dart
+// Reload the enabled providers
+final savedEnabled = await SettingsService.getEnabledMusicProviders();
+_enabledProviderIds = savedEnabled ?? [];
+
+// Notify listeners IMMEDIATELY so UI rebuilds with client-side filtering
+// This enables instant UI updates using cached data with source tracking
+notifyListeners();
+
+// Cancel any pending debounce timer
+_providerFilterDebounceTimer?.cancel();
+
+// Start debounced sync - waits 600ms for user to finish toggling
+// This refreshes the cache with new data from enabled providers
+_providerFilterDebounceTimer = Timer(const Duration(milliseconds: 600), () {
+  _logger.log('🔄 Debounce complete, starting library sync...');
+  forceLibrarySync();
+});
+```
+
+### Fix 3: Audiobook Tabs Use Selector
+
+**File:** `lib/screens/new_library_screen.dart`
+
+Wrapped `_buildBooksAuthorsTab` and `_buildAllBooksTab` in `Selector` to rebuild when `enabledProviderIds` changes:
+
+```dart
+Widget _buildBooksAuthorsTab(BuildContext context, S l10n) {
+  // Use Selector to rebuild when enabledProviderIds changes
+  return Selector<MusicAssistantProvider, Set<String>>(
+    selector: (_, provider) => provider.enabledProviderIds.toSet(),
+    builder: (context, enabledProviders, _) {
+      final syncService = SyncService.instance;
+
+      // Client-side filtering using SyncService source tracking for instant updates
+      var audiobooks = syncService.hasSourceTracking && enabledProviders.isNotEmpty
+          ? syncService.getAudiobooksFilteredByProviders(enabledProviders)
+          : List<Audiobook>.from(_audiobooks);
+
+      // ... rest of widget
+    },
+  );
+}
+```
+
+### Fix 4: Enhanced Sync Logging
+
+**File:** `lib/services/sync_service.dart`
+
+Added audiobook counts to logging:
+
+```dart
+// Per-provider log (line 237)
+_logger.log('  📥 Got ${albums.length} albums, ${artists.length} artists, ${audiobooks.length} audiobooks from $providerId');
+
+// Source tracking summary (line 323)
+_logger.log('📊 Source tracking: ${_albumSourceProviders.length} albums, ${_artistSourceProviders.length} artists, ${_audiobookSourceProviders.length} audiobooks have provider info');
+```
+
+---
+
+## Data Flow After Fixes
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    User Toggles Provider                         │
+│                                                                  │
+│   1. toggleProviderEnabled() called                             │
+│   2. _enabledProviderIds updated                                │
+│   3. notifyListeners() called IMMEDIATELY                       │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    Selectors Detect Change                       │
+│                                                                  │
+│   Music tabs: Selector<..., (List, bool, Set<String>)>         │
+│   Audiobook tabs: Selector<..., Set<String>>                    │
+│                                                                  │
+│   → All tabs rebuild immediately                                 │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                Client-Side Filtering (Instant)                   │
+│                                                                  │
+│   syncService.getAlbumsFilteredByProviders(enabledProviders)    │
+│   syncService.getArtistsFilteredByProviders(enabledProviders)   │
+│   syncService.getAudiobooksFilteredByProviders(enabledProviders)│
+│                                                                  │
+│   → Uses EXISTING cache with source tracking                    │
+│   → Instant UI update, no network required                      │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│              Background Sync (After 600ms Debounce)              │
+│                                                                  │
+│   - Refreshes cache with new data from enabled providers        │
+│   - Updates source tracking                                      │
+│   - Only needed when ENABLING providers (to fetch new data)     │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Files Changed
+
+| File | Changes |
+|------|---------|
+| `lib/services/music_assistant_api.dart` | Added provider filtering to browse API path in `getAudiobooks()`, added debug logging |
+| `lib/services/sync_service.dart` | Added audiobook counts to per-provider and summary logs |
+| `lib/providers/music_assistant_provider.dart` | Moved `notifyListeners()` to fire immediately on provider toggle |
+| `lib/screens/new_library_screen.dart` | Wrapped audiobook tabs in `Selector` to rebuild on provider changes |
+
+---
+
+## Expected Behavior After Fixes
+
+1. **Instant UI Updates:** When you toggle a provider, the library immediately updates using client-side filtering
+2. **Audiobook Source Tracking:** Audiobooks now have provider source tracking (visible in logs)
+3. **Audiobook Tab Rebuilds:** Both audiobook tabs (Authors and All Books) rebuild instantly on provider toggle
+4. **Music Tab Consistency:** Music tabs continue to work as before, now with immediate rebuilds
+
+---
+
+## Testing Checklist
+
+- [ ] Toggle a music provider, verify instant UI update (no 600ms delay)
+- [ ] Toggle between different Spotify accounts, verify correct filtering
+- [ ] Sync with ABS library filtering enabled
+- [ ] Verify audiobooks appear in source tracking log
+- [ ] Toggle ABS provider off in library menu
+- [ ] Verify audiobooks list becomes empty immediately (no pull-to-refresh needed)
+- [ ] Toggle ABS provider back on
+- [ ] Verify audiobooks reappear after sync completes
+- [ ] Test with multiple providers (Spotify audiobooks + ABS)
+
+---
+
+## Related Documentation
+
+- `docs/SESSION_2026_01_17_PROVIDER_FILTERING.md` - Initial provider filtering implementation
+- `docs/PER_PROVIDER_SYNC_IMPLEMENTATION.md` - Per-provider sync architecture
+
+---
+
+## Known Limitations
+
+1. **Series Tab:** The Series tab still doesn't filter by provider. Series are fetched as `AudiobookSeries` objects without per-provider tracking.
+
+2. **Mixed Provider Scenario:** If user has both Spotify audiobooks and ABS audiobooks, and ABS library filtering is enabled, Spotify audiobooks may not be fetched because the browse API path is taken. This is a pre-existing architectural limitation.
+
+3. **Enabling Providers:** When ENABLING a previously disabled provider, the UI updates immediately but shows empty until the background sync completes (because the cache doesn't have that provider's data yet). This is expected behavior.

docs/SESSION_2026_01_17_OPTIMISTIC_UPDATES.md

@@ -0,0 +1,217 @@
+# Session 2026-01-17: Optimistic Updates & Podcast Provider Filtering
+
+## Overview
+
+This session focused on fixing provider filtering for podcasts, resolving iTunes podcast provider issues, and implementing optimistic updates for library buttons across detail screens.
+
+## Issues Addressed
+
+### 1. Podcast Provider Counts Showing Incorrectly
+
+**Problem**: All Spotify accounts showed the same podcast count instead of only counting podcasts owned by each account.
+
+**Root Cause**: The podcast counting logic wasn't checking the `inLibrary` field on provider mappings.
+
+**Solution**:
+- Added `inLibrary` field to `ProviderMapping` model
+- Updated `getProvidersWithPodcasts()` to only count mappings where `inLibrary == true`
+- Updated podcast filtering in library screen to check `inLibrary` field
+
+**Files Modified**:
+- `lib/models/media_item.dart` - Added `inLibrary` field
+- `lib/providers/music_assistant_provider.dart` - Updated counting logic
+- `lib/screens/new_library_screen.dart` - Updated filtering logic
+
+### 2. iTunes Podcasts Not Appearing in Library
+
+**Problem**: Podcasts added from iTunes search weren't showing in library and iTunes provider filter showed 0 count.
+
+**Investigation**:
+- Added `itunes_podcasts` to provider capabilities and music provider domains
+- Added synthetic provider instance creation for search-only providers
+- Added debug logging to understand podcast loading
+
+**Resolution**: The issue was with Music Assistant's iTunes podcast provider itself - podcasts added via iTunes weren't being properly stored in the MA library. The user removed the iTunes provider from MA and re-added podcasts via Spotify search as a workaround.
+
+**Files Modified**:
+- `lib/models/provider_instance.dart` - Added `itunes_podcasts` to capabilities
+
+### 3. Episode Loading Failing for Non-Library Podcasts
+
+**Problem**: When a podcast was removed from library, the old library ID became invalid and episodes wouldn't load.
+
+**Solution**: Added fallback logic to try loading episodes via provider mappings when the primary ID fails.
+
+**Files Modified**:
+- `lib/screens/podcast_detail_screen.dart` - Added fallback episode loading
+
+### 4. Search Filtering Rework
+
+**Problem**: Server-side provider filtering was being applied to search results when it should only apply when the "in library" toggle is enabled.
+
+**Solution**:
+- Removed `filterSearchResults()` calls from search methods
+- Added client-side `_filterByEnabledProviders()` helper
+- Applied filtering only when `_libraryOnly` toggle is ON
+
+**Files Modified**:
+- `lib/providers/music_assistant_provider.dart` - Removed filterSearchResults calls
+- `lib/screens/search_screen.dart` - Added client-side filtering
+
+### 5. Library Buttons Not Updating Immediately
+
+**Problem**: Add/remove library buttons on detail screens waited for API response before updating, causing perceived lag.
+
+**Solution**: Implemented optimistic updates - update UI immediately, revert on failure.
+
+**Files Modified**:
+- `lib/screens/podcast_detail_screen.dart`
+- `lib/screens/album_details_screen.dart`
+- `lib/screens/artist_details_screen.dart`
+
+## Code Changes
+
+### ProviderMapping.inLibrary Field
+
+```dart
+// lib/models/media_item.dart
+class ProviderMapping {
+  final String itemId;
+  final String providerDomain;
+  final String providerInstance;
+  final bool available;
+  final Map<String, dynamic>? audioFormat;
+  final bool inLibrary;  // NEW: indicates ownership
+
+  factory ProviderMapping.fromJson(Map<String, dynamic> json) {
+    return ProviderMapping(
+      // ... other fields ...
+      inLibrary: json['in_library'] == true || json['in_library'] == 1,
+    );
+  }
+}
+```
+
+### Podcast Provider Counting
+
+```dart
+// lib/providers/music_assistant_provider.dart
+Map<String, int> getProvidersWithPodcasts() {
+  final counts = <String, int>{};
+  for (final item in _podcasts) {
+    final mappings = item.providerMappings;
+    if (mappings != null) {
+      for (final mapping in mappings) {
+        // Only count if this provider "owns" the item
+        if (mapping.inLibrary) {
+          final instanceId = mapping.providerInstance;
+          if (instanceId.isNotEmpty) {
+            counts[instanceId] = (counts[instanceId] ?? 0) + 1;
+          }
+        }
+      }
+    }
+  }
+  return counts;
+}
+```
+
+### Optimistic Update Pattern
+
+```dart
+// Example from podcast_detail_screen.dart
+Future<void> _toggleLibrary() async {
+  final newState = !_isInLibrary;
+
+  // OPTIMISTIC UPDATE: Update UI immediately
+  setState(() {
+    _isInLibrary = newState;
+  });
+
+  if (mounted) {
+    ScaffoldMessenger.of(context).showSnackBar(
+      SnackBar(content: Text(S.of(context)!.addedToLibrary)),
+    );
+  }
+
+  // Fire and forget - API call happens in background
+  maProvider.addToLibrary(...).catchError((e) {
+    // Revert on failure
+    if (mounted) {
+      setState(() {
+        _isInLibrary = !newState;
+      });
+    }
+  });
+}
+```
+
+### Client-Side Search Filtering
+
+```dart
+// lib/screens/search_screen.dart
+Map<String, List<MediaItem>> _filterByEnabledProviders(
+  Map<String, List<MediaItem>> results,
+  Set<String> enabledProviders,
+) {
+  if (enabledProviders.isEmpty) return results;
+
+  bool isItemAllowed(MediaItem item) {
+    final mappings = item.providerMappings;
+    if (mappings == null || mappings.isEmpty) return true;
+    return mappings.any((m) => m.inLibrary && enabledProviders.contains(m.providerInstance));
+  }
+
+  return {
+    for (final entry in results.entries)
+      entry.key: entry.value.where(isItemAllowed).toList(),
+  };
+}
+
+// Applied when setting results:
+if (_libraryOnly) {
+  final enabledProviders = provider.enabledProviderIds.toSet();
+  combinedResults = _filterByEnabledProviders(combinedResults, enabledProviders);
+}
+```
+
+## Provider Capabilities Update
+
+```dart
+// lib/models/provider_instance.dart
+static const Map<String, Set<String>> providerCapabilities = {
+  'spotify': {'artists', 'albums', 'tracks', 'playlists', 'audiobooks', 'podcasts'},
+  'ytmusic': {'artists', 'albums', 'tracks', 'playlists', 'podcasts'},
+  'apple_music': {'artists', 'albums', 'tracks', 'playlists', 'podcasts'},
+  'plex': {'artists', 'albums', 'tracks', 'playlists', 'audiobooks', 'podcasts'},
+  'jellyfin': {'artists', 'albums', 'tracks', 'playlists', 'audiobooks', 'podcasts'},
+  'emby': {'artists', 'albums', 'tracks', 'playlists', 'audiobooks', 'podcasts'},
+  'audiobookshelf': {'audiobooks', 'podcasts'},
+  'itunes_podcasts': {'podcasts'},  // NEW
+  'tunein': {'radio', 'podcasts'},
+  // ... other providers
+};
+```
+
+## Summary of All Modified Files
+
+| File | Changes |
+|------|---------|
+| `lib/models/media_item.dart` | Added `inLibrary` field to ProviderMapping |
+| `lib/models/provider_instance.dart` | Added `itunes_podcasts`, podcasts to capabilities |
+| `lib/providers/music_assistant_provider.dart` | Updated podcast counting, removed filterSearchResults |
+| `lib/screens/new_library_screen.dart` | Updated podcast filtering with inLibrary check |
+| `lib/screens/search_screen.dart` | Added client-side filtering for in-library mode |
+| `lib/screens/podcast_detail_screen.dart` | Optimistic updates, fallback episode loading |
+| `lib/screens/album_details_screen.dart` | Optimistic updates for library button |
+| `lib/screens/artist_details_screen.dart` | Optimistic updates for library button |
+
+## Key Learnings
+
+1. **inLibrary field**: Music Assistant's provider mappings include an `in_library` field that indicates whether the user added the item from that specific provider account. This is essential for accurate per-provider filtering.
+
+2. **iTunes podcast provider**: The MA iTunes podcast provider is for search only - it doesn't properly store items in the library. Users should add podcasts from streaming providers like Spotify instead.
+
+3. **Optimistic updates**: For better UX, library toggle buttons should update immediately and only revert if the API call fails, rather than waiting for API response.
+
+4. **Search vs Library filtering**: Server-side provider filtering should only apply to library views, not search results (unless the "in library" toggle is enabled).

docs/SESSION_2026_01_17_PROVIDER_FILTERING.md

@@ -0,0 +1,263 @@
+# Provider Filtering Improvements
+
+## Date: January 17, 2026
+
+## Overview
+
+This session focused on improving the provider filtering system across the app, building on the per-provider sync implementation. Key improvements include a cleaner capability-based architecture, fixing filter visibility bugs, and extending filtering to the audiobooks library.
+
+---
+
+## Changes Made
+
+### 1. Provider Capability Mapping
+
+**File:** `lib/models/provider_instance.dart`
+
+Replaced the clunky item-count-based filtering with a static capability map that defines what content types each provider domain supports.
+
+```dart
+static const Map<String, Set<String>> providerCapabilities = {
+  // Music streaming services
+  'spotify': {'artists', 'albums', 'tracks', 'playlists', 'audiobooks'},
+  'tidal': {'artists', 'albums', 'tracks', 'playlists'},
+  'qobuz': {'artists', 'albums', 'tracks', 'playlists'},
+  'deezer': {'artists', 'albums', 'tracks', 'playlists'},
+  'ytmusic': {'artists', 'albums', 'tracks', 'playlists'},
+  'soundcloud': {'artists', 'albums', 'tracks', 'playlists'},
+  'apple_music': {'artists', 'albums', 'tracks', 'playlists'},
+  'amazon_music': {'artists', 'albums', 'tracks', 'playlists'},
+
+  // Self-hosted media servers (can have music and audiobooks)
+  'plex': {'artists', 'albums', 'tracks', 'playlists', 'audiobooks'},
+  'jellyfin': {'artists', 'albums', 'tracks', 'playlists', 'audiobooks'},
+  'emby': {'artists', 'albums', 'tracks', 'playlists', 'audiobooks'},
+
+  // Music-only servers
+  'subsonic': {'artists', 'albums', 'tracks', 'playlists'},
+  'opensubsonic': {'artists', 'albums', 'tracks', 'playlists'},
+  'navidrome': {'artists', 'albums', 'tracks', 'playlists'},
+  'filesystem': {'artists', 'albums', 'tracks', 'playlists'},
+
+  // Audiobook-only providers
+  'audiobookshelf': {'audiobooks'},
+
+  // Radio providers
+  'tunein': {'radio'},
+  'radiobrowser': {'radio'},
+
+  // Player/system providers (no library content)
+  'snapcast': <String>{},
+  'fully_kiosk': <String>{},
+};
+```
+
+**Added helper methods:**
+```dart
+Set<String> get supportedContentTypes => providerCapabilities[domain] ?? <String>{};
+bool supportsContentType(String category) => supportedContentTypes.contains(category);
+```
+
+**Benefits:**
+- Radio providers never show in Artists tab (by design, not by count)
+- Works immediately, even with empty libraries
+- Disabled providers still show in menu (if they support the content type)
+- Clean separation of concerns
+
+---
+
+### 2. Updated Provider Filtering in MusicAssistantProvider
+
+**File:** `lib/providers/music_assistant_provider.dart`
+
+Updated `getRelevantProvidersForCategory()` to filter by capability:
+
+```dart
+List<(ProviderInstance, int)> getRelevantProvidersForCategory(String category) {
+  // ... get counts ...
+
+  final result = <(ProviderInstance, int)>[];
+  for (final provider in _availableMusicProviders) {
+    // Only include providers that support this content type
+    if (provider.supportsContentType(category)) {
+      final count = counts[provider.instanceId] ?? 0;
+      result.add((provider, count));
+    }
+  }
+  // ...
+}
+```
+
+---
+
+### 3. Simplified Library Menu Provider Filter
+
+**File:** `lib/screens/new_library_screen.dart`
+
+Simplified the options menu overlay to show all providers that support the current category:
+
+**Before (clunky):**
+```dart
+if (widget.relevantProviders.where((p) {
+  final hasItems = p.$2 > 0;
+  final isDisabledByUser = widget.enabledProviderIds.isNotEmpty &&
+      !widget.enabledProviderIds.contains(p.$1.instanceId);
+  return hasItems || isDisabledByUser;
+}).length > 1) ...[
+```
+
+**After (clean):**
+```dart
+// relevantProviders is pre-filtered by capability
+if (widget.relevantProviders.length > 1) ...[
+  // Show all providers that support this category
+  ...widget.relevantProviders.map((providerData) {
+```
+
+---
+
+### 4. Removed Provider Toggles from Settings Screen
+
+**File:** `lib/screens/settings_screen.dart`
+
+Removed the "Music Providers" section entirely since provider filtering is now handled in the library menu:
+
+- Removed `_providerEnabled` state variable
+- Removed provider loading code from `_loadSettings()`
+- Removed the entire Music Providers UI section (~100 lines)
+
+**Rationale:** Single source of truth - provider toggles now only appear in the library menu where they're contextually relevant.
+
+---
+
+### 5. Fixed Audiobooks Library Provider Filtering
+
+**File:** `lib/screens/new_library_screen.dart`
+
+The audiobooks tabs were not filtering by provider - they loaded data once and displayed it without responding to provider changes.
+
+**Fixed `_buildBooksAuthorsTab()`:**
+```dart
+final syncService = SyncService.instance;
+final enabledProviders = maProvider.enabledProviderIds.toSet();
+
+// Client-side filtering using SyncService source tracking
+var audiobooks = syncService.hasSourceTracking && enabledProviders.isNotEmpty
+    ? syncService.getAudiobooksFilteredByProviders(enabledProviders)
+    : List<Audiobook>.from(_audiobooks);
+
+// Filter by favorites if enabled
+if (_showFavoritesOnly) {
+  audiobooks = audiobooks.where((a) => a.favorite == true).toList();
+}
+
+// Group filtered audiobooks by author (dynamic, not cached)
+final groupedByAuthor = <String, List<Audiobook>>{};
+for (final book in audiobooks) {
+  final authorName = book.authorsString;
+  groupedByAuthor.putIfAbsent(authorName, () => []).add(book);
+}
+```
+
+**Fixed `_buildAllBooksTab()`:**
+- Same provider filtering pattern
+- Dynamic sorting after filtering
+- Updated PageStorageKey to include provider count for proper rebuild
+
+---
+
+## Bug Fixes
+
+### Provider Filter Menu Disappearing
+
+**Problem:** When providers were deselected, the background sync would clear the cache and only fetch data for enabled providers. Disabled providers then had 0 items, and the menu required `> 1 providers WITH items` to show. The entire Providers section would disappear.
+
+**Solution:** Changed to capability-based filtering. The menu now shows all providers that support the category, regardless of item count.
+
+### Audiobooks Not Filtering by Provider
+
+**Problem:** Audiobooks tabs loaded data once into `_audiobooks` and displayed it without provider filtering. Toggling providers in the menu had no effect.
+
+**Solution:** Added inline provider filtering during build (same pattern as music tabs).
+
+---
+
+## Files Changed
+
+| File | Changes |
+|------|---------|
+| `lib/models/provider_instance.dart` | Added `providerCapabilities` map and helper methods |
+| `lib/providers/music_assistant_provider.dart` | Updated `getRelevantProvidersForCategory()` to filter by capability |
+| `lib/screens/new_library_screen.dart` | Simplified menu filter logic, added audiobook provider filtering |
+| `lib/screens/settings_screen.dart` | Removed Music Providers section |
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    Provider Capability Map                       │
+│         (ProviderInstance.providerCapabilities)                  │
+│                                                                  │
+│   spotify → {artists, albums, tracks, playlists, audiobooks}    │
+│   audiobookshelf → {audiobooks}                                 │
+│   tunein → {radio}                                              │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│            getRelevantProvidersForCategory(category)             │
+│                                                                  │
+│   - Filters _availableMusicProviders by capability              │
+│   - Returns only providers that support the category            │
+│   - Includes item counts for display                            │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    Library Menu (Options)                        │
+│                                                                  │
+│   - Shows providers section if > 1 providers support category   │
+│   - All relevant providers shown (can toggle on/off)            │
+│   - Instant UI update via setState()                            │
+│   - Background sync after 1.5s debounce                         │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                   Tab Build Methods                              │
+│                                                                  │
+│   - Get enabledProviderIds from MusicAssistantProvider          │
+│   - Filter data using SyncService source tracking               │
+│   - Display filtered results                                    │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Known Limitations
+
+1. **Series Tab:** The Series tab in audiobooks doesn't filter by provider yet. Series are fetched separately as `AudiobookSeries` objects and don't have the same source tracking as individual audiobooks.
+
+2. **First Sync Required:** Source tracking only works after at least one sync with providers enabled.
+
+---
+
+## Testing Checklist
+
+- [x] Music tabs filter by provider correctly
+- [x] Provider menu shows only relevant providers per category
+- [x] Radio providers don't appear in Artists/Albums tabs
+- [x] Spotify appears in Audiobooks tab (has audiobooks)
+- [x] Audiobooks Authors tab filters by provider
+- [x] Audiobooks All Books tab filters by provider
+- [ ] Audiobooks Series tab filters by provider (not implemented)
+- [x] Disabled providers can be re-enabled from menu
+- [x] Settings screen no longer has provider toggles
+
+---
+
+## Related Documentation
+
+- `docs/PER_PROVIDER_SYNC_IMPLEMENTATION.md` - Original per-provider sync implementation

docs/discovery-rows-submenu-plan.md

@@ -0,0 +1,242 @@
+# Discovery Rows Submenu - Implementation Plan
+
+## Option: Hybrid with Discovery Badge
+
+### Overview
+Transform the "Discovery Mixes" toggle into a section that:
+1. Shows individual discovery row toggles
+2. Adds those rows to the main home row list with visual distinction
+3. Allows full reordering alongside other rows
+
+---
+
+## UI Design
+
+### Settings Screen - Discovery Section
+
+```
+┌─────────────────────────────────────────────┐
+│ ⚬ Discovery Mixes                        ● │
+│   Show discovery-based rows on home screen │
+│   ──────────────────────────────────────── │
+│   Discovery rows from Music Assistant:     │
+│                                            │
+│   ☑ New Releases                        ● │
+│   ☑ Recently Played                     ● │
+│   ☐ Recommended Albums                  ○ │
+│   ☐ For You                             ○ │
+│                                            │
+│   [Refresh available rows]                │
+└─────────────────────────────────────────────┘
+```
+
+### Main Home Row List - With Badge
+
+Discovery rows appear interleaved with a badge:
+
+```
+┌─────────────────────────────────────────────┐
+│ ⋮ ☑ Recent Albums                        ● │
+│ ⋮ ☑ Discovery: New Releases    ●  [MUSIC] │ ← Badge
+│ ⋮ ☑ Discover Artists                     ● │
+│ ⋮ ☐ Discovery: For You           ○  [MUSIC] │
+│ ⋮ ☑ Favorite Albums                      ● │
+└─────────────────────────────────────────────┘
+```
+
+Badge style: Small chip/icon indicating this is a dynamic discovery row.
+
+---
+
+## Technical Changes
+
+### 1. Settings Screen (`lib/screens/settings_screen.dart`)
+
+**Add state for discovery folders:**
+```dart
+List<RecommendationFolder> _discoveryFolders = [];
+Map<String, bool> _discoveryRowEnabled = {}; // itemId -> enabled
+bool _isDiscoveryFoldersExpanded = false;
+```
+
+**New methods:**
+```dart
+Future<void> _loadDiscoveryFolders() async { }
+Future<void> _refreshDiscoveryFolders() async { }
+void _toggleDiscoveryRow(String itemId, bool enabled) { }
+void _toggleDiscoveryMixes(bool enabled) { }
+Widget _buildDiscoverySection() { }
+```
+
+**Modify existing:**
+- `_loadSettings()` - load discovery row preferences
+- Home row list builder - filter out individual discovery rows
+- Add discovery section before home row list
+
+### 2. Settings Service (`lib/services/settings_service.dart`)
+
+**New methods:**
+```dart
+static Future<bool> getShowDiscoveryFolders() async { }
+static Future<void> setShowDiscoveryFolders(bool value) async { }
+
+// Per-row discovery preferences
+static Future<Map<String, bool>> getDiscoveryRowPreferences() async { }
+static Future<void> setDiscoveryRowPreference(String itemId, bool enabled) async { }
+static Future<void> setDiscoveryRowPreferences(Map<String, bool> prefs) async { }
+```
+
+**Storage key pattern:**
+- `discovery_folders_enabled` (bool)
+- `discovery_row_{itemId}` (bool per row)
+
+### 3. Provider (`lib/providers/music_assistant_provider.dart`)
+
+**Already has:** `getDiscoveryFoldersWithCache()`
+
+**Add method:**
+```dart
+Future<void> refreshDiscoveryFolders() async {
+  // Clear cache and refetch from API
+  _cacheService.clearDiscoveryFoldersCache();
+  await getDiscoveryFoldersWithCache();
+}
+```
+
+### 4. Home Screen (`lib/screens/new_home_screen.dart`)
+
+**Changes to row rendering:**
+
+Instead of a single `_discoveryFolders` list, discovery rows are integrated into `_homeRowOrder`:
+
+```dart
+// Before: static list of row IDs
+List<String> _homeRowOrder = ['recent-albums', 'discover-artists', ...];
+
+// After: can include discovery row IDs
+List<String> _homeRowOrder = [
+  'recent-albums',
+  'discovery:abc123',  // Discovery row ID
+  'discover-artists',
+  'discovery:def456',
+  ...
+];
+```
+
+**New method:**
+```dart
+bool _isDiscoveryRowId(String rowId) {
+  return rowId.startsWith('discovery:');
+}
+
+String _getDiscoveryRowItemId(String rowId) {
+  return rowId.substring('discovery:'.length);
+}
+```
+
+**Modify row rendering:**
+- Check if rowId is a discovery row
+- If yes, render DiscoveryRow widget with that folder
+- Cache discovery folders for quick lookup
+
+### 5. Localization (`lib/l10n/app_en.arb`)
+
+**Add strings:**
+```json
+{
+  "discoveryMixesDescription": "Show personalized recommendations from Music Assistant",
+  "discoveryRows": "Discovery rows from Music Assistant",
+  "refreshDiscoveryRows": "Refresh available rows",
+  "noDiscoveryRows": "No discovery rows available",
+  "discoveryRowBadge": "Music Assistant"
+}
+```
+
+### 6. Models (`lib/models/recommendation_folder.dart`)
+
+**Add property:**
+```dart
+class RecommendationFolder {
+  ...
+  /// Unique ID for use in row ordering and settings
+  String get rowId => 'discovery:$itemId';
+}
+```
+
+---
+
+## Data Flow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                          Settings Screen                        │
+├─────────────────────────────────────────────────────────────────┤
+│  1. Load discovery folders from Provider                        │
+│  2. Load per-row enabled state from Settings                    │
+│  3. Render section with toggles                                 │
+│  4. User toggles row → save to Settings                         │
+│  5. User toggles main → save to Settings + update home row list │
+│  6. User refreshes → Provider.fetch → update UI                 │
+└─────────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────────┐
+│                        Home Screen                              │
+├─────────────────────────────────────────────────────────────────┤
+│  1. Load home row order from Settings                           │
+│  2. Identify discovery row IDs (prefix "discovery:")             │
+│  3. For discovery rows: look up folder from Provider cache      │
+│  4. Render appropriate widget (DiscoveryRow or other)           │
+│  5. Handle reordering including discovery rows                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Migration Path
+
+### Phase 1: Settings Screen (No breaking changes)
+- Add discovery section to settings
+- Load and display discovery folders
+- Individual row toggles (but don't affect home screen yet)
+- Refresh button
+
+### Phase 2: Home Screen Integration
+- Modify home row order to support discovery row IDs
+- Render discovery rows in main list
+- Add badge visual distinction
+
+### Phase 3: Polish
+- Translations
+- Edge cases (folder disappears from MA)
+- Performance (lazy loading)
+
+---
+
+## Edge Cases & Considerations
+
+| Issue | Solution |
+|-------|----------|
+| Discovery folder no longer returned by MA | Keep user preference, hide row if not found |
+| User reorders then MA returns new folders | New folders appended to end of discovery section |
+| All discovery rows disabled | Discovery section shows but appears empty/minimized |
+| Many discovery folders (10+) | Show scrollable sublist, keep main setting compact |
+| Row ID collision | Use `discovery:{itemId}` prefix ensures uniqueness |
+
+---
+
+## Implementation Checklist
+
+- [ ] Settings: Add `_discoveryFolders` state
+- [ ] Settings: Add `_discoveryRowEnabled` map
+- [ ] Settings: Implement `_loadDiscoveryFolders()`
+- [ ] Settings: Implement `_buildDiscoverySection()`
+- [ ] Settings: Add refresh button handler
+- [ ] SettingsService: Add discovery row preference methods
+- [ ] Provider: Add `refreshDiscoveryFolders()`
+- [ ] HomeScreen: Support discovery row IDs in order list
+- [ ] HomeScreen: Render discovery rows with badge
+- [ ] Localization: Add new strings
+- [ ] Test: Toggle discovery rows on/off
+- [ ] Test: Reorder discovery rows
+- [ ] Test: Refresh discovery folders
+- [ ] Test: Migrate existing preference to new system

docs/plans/player-selector-for-play-on.md

@@ -0,0 +1,221 @@
+# Feature: Replace "Play On" Popups with Player Selector
+
+## Overview
+
+Replace the `PlayerPickerSheet` popup modal with the existing Player Selector (reveal overlay) when users tap "Play on" buttons throughout the app. This provides a consistent, richer player selection experience.
+
+## Current State
+
+### PlayerPickerSheet Popup
+Used in 7+ places:
+- `album_details_screen.dart` - Play Album, Play From Here, Play Radio
+- `playlist_details_screen.dart` - Play Playlist, Play Radio
+- `search_screen.dart` - Play album/playlist/audiobook/radio from search
+- `podcast_detail_screen.dart` - Play Episode
+- `audiobook_detail_screen.dart` - Play Audiobook
+- `queue_screen.dart` - Transfer Queue (special case - keep popup)
+
+### Player Selector (Reveal Overlay)
+- Location: `lib/widgets/player/player_reveal_overlay.dart`
+- Shows vertical list of all players with artwork, current track, sync status
+- Has hints above player list: "Long-press to sync" & "Swipe to adjust volume"
+- Triggered by pull-down gesture or device button tap
+
+## Proposed Changes
+
+### 1. Modify PlayerRevealOverlay
+
+**File:** `lib/widgets/player/player_reveal_overlay.dart`
+
+Add new optional parameters:
+
+```dart
+class PlayerRevealOverlay extends StatefulWidget {
+  final VoidCallback onDismiss;
+  final double miniPlayerBottom;
+  final double miniPlayerHeight;
+  final bool showOnboardingHints;
+
+  // NEW: Callback when player is selected for a pending action
+  final void Function(Player player)? onPlayerSelected;
+
+  // NEW: Context hint to display instead of default hints
+  // e.g., "Select player to play album"
+  final String? contextHint;
+
+  // NEW: Icon for context hint (default: speaker icon)
+  final IconData? contextHintIcon;
+```
+
+### 2. Modify Hint Display
+
+**File:** `lib/widgets/player/player_reveal_overlay.dart` (around line 386-394)
+
+```dart
+// Current:
+: Column(
+    mainAxisSize: MainAxisSize.min,
+    children: [
+      buildHintRow(Icons.lightbulb_outline, S.of(context)!.holdToSync),
+      const SizedBox(height: 4),
+      buildHintRow(Icons.lightbulb_outline, S.of(context)!.swipeToAdjustVolume),
+    ],
+  ),
+
+// New:
+: widget.contextHint != null
+    ? buildHintRow(
+        widget.contextHintIcon ?? Icons.play_circle_outline,
+        widget.contextHint!,
+      )
+    : Column(
+        mainAxisSize: MainAxisSize.min,
+        children: [
+          buildHintRow(Icons.lightbulb_outline, S.of(context)!.holdToSync),
+          const SizedBox(height: 4),
+          buildHintRow(Icons.lightbulb_outline, S.of(context)!.swipeToAdjustVolume),
+        ],
+      ),
+```
+
+### 3. Modify Player Card onTap
+
+**File:** `lib/widgets/player/player_reveal_overlay.dart` (around line 437-441 and 490-494)
+
+```dart
+// Current:
+onTap: () {
+  HapticFeedback.mediumImpact();
+  maProvider.selectPlayer(data.player);
+  dismiss();
+},
+
+// New:
+onTap: () {
+  HapticFeedback.mediumImpact();
+  if (widget.onPlayerSelected != null) {
+    // Execute the pending action with selected player
+    widget.onPlayerSelected!(data.player);
+  } else {
+    // Default behavior: just select the player
+    maProvider.selectPlayer(data.player);
+  }
+  dismiss();
+},
+```
+
+### 4. Add Helper Method to GlobalPlayerOverlay
+
+**File:** `lib/widgets/global_player_overlay.dart`
+
+Add a static method to show player selector with pending action:
+
+```dart
+/// Show player selector for a "Play on" action
+///
+/// [contextHint] - Message shown instead of default hints
+/// [onPlayerSelected] - Called when user taps a player
+///
+/// Example:
+/// ```dart
+/// GlobalPlayerOverlay.showPlayerSelectorForAction(
+///   contextHint: "Select player to play album",
+///   onPlayerSelected: (player) {
+///     provider.playAlbum(albumId, playerId: player.playerId);
+///   },
+/// );
+/// ```
+static void showPlayerSelectorForAction({
+  required String contextHint,
+  required void Function(Player player) onPlayerSelected,
+  IconData? hintIcon,
+}) {
+  // Implementation: trigger the player reveal overlay with these parameters
+  // May need to store pending action in state and pass to overlay
+}
+```
+
+### 5. Update Calling Sites
+
+Replace `showPlayerPickerSheet()` calls with new method:
+
+**Example - album_details_screen.dart:**
+
+```dart
+// Current (around line 1305-1316):
+showPlayerPickerSheet(
+  context: context,
+  title: 'Play Album',
+  onPlayerSelected: (player) async {
+    GlobalPlayerOverlay.hidePlayer();
+    await maProvider.playAlbum(albumId, playerId: player.playerId);
+    GlobalPlayerOverlay.showPlayer();
+  },
+);
+
+// New:
+GlobalPlayerOverlay.showPlayerSelectorForAction(
+  contextHint: S.of(context)!.selectPlayerToPlayAlbum, // Add localization
+  onPlayerSelected: (player) async {
+    await maProvider.playAlbum(albumId, playerId: player.playerId);
+  },
+);
+```
+
+### 6. Add Localizations
+
+**File:** `lib/l10n/app_en.arb` (and other language files)
+
+```json
+"selectPlayerToPlay": "Select player to play",
+"selectPlayerToPlayAlbum": "Select player to play album",
+"selectPlayerToPlayPlaylist": "Select player to play playlist",
+"selectPlayerToPlayRadio": "Select player to start radio",
+"selectPlayerToPlayEpisode": "Select player to play episode",
+"selectPlayerToPlayAudiobook": "Select player to play audiobook"
+```
+
+## Files to Modify
+
+1. `lib/widgets/player/player_reveal_overlay.dart` - Add parameters, modify hints & onTap
+2. `lib/widgets/global_player_overlay.dart` - Add helper method
+3. `lib/screens/album_details_screen.dart` - Replace 3 popup calls
+4. `lib/screens/playlist_details_screen.dart` - Replace 2 popup calls
+5. `lib/screens/search_screen.dart` - Replace ~5 popup calls
+6. `lib/screens/podcast_detail_screen.dart` - Replace 1 popup call
+7. `lib/screens/audiobook_detail_screen.dart` - Replace 1 popup call
+8. `lib/l10n/app_en.arb` - Add new strings
+9. `lib/l10n/app_de.arb`, `app_fr.arb`, `app_es.arb` - Translations
+
+## Exception: Queue Transfer
+
+**Keep the popup for `queue_screen.dart`** because:
+- Needs to filter out current player (can't transfer to self)
+- Needs to filter out certain player types
+- Different UX intent (transfer vs play)
+
+## Implementation Order
+
+1. Modify `PlayerRevealOverlay` to accept new parameters
+2. Add helper method to `GlobalPlayerOverlay`
+3. Test with one screen (album_details_screen.dart)
+4. Add localizations
+5. Migrate remaining screens
+6. Clean up unused code from PlayerPickerSheet if no longer needed elsewhere
+
+## Testing Checklist
+
+- [ ] Album details: Play Album button
+- [ ] Album details: Play From Here (track context menu)
+- [ ] Album details: Play Radio (track context menu)
+- [ ] Playlist details: Play Playlist button
+- [ ] Playlist details: Play Radio (track context menu)
+- [ ] Search: Play album from results
+- [ ] Search: Play playlist from results
+- [ ] Search: Play radio from results
+- [ ] Podcast detail: Play episode
+- [ ] Audiobook detail: Play audiobook
+- [ ] Queue transfer still works with popup
+- [ ] Long-press to sync still works in player selector
+- [ ] Dismiss by tapping backdrop works
+- [ ] Dismiss by swiping down works

docs/remote-connection/FUTURE_IMPLEMENTATION_GUIDE.md

@@ -0,0 +1,328 @@
+# Remote Connection - Future Implementation Guide
+
+## Overview
+
+This document provides guidance for implementing remote connection to Music Assistant servers via WebRTC. Remote connection allows the Ensemble app to connect to MA servers outside the local network using Nabu Casa's WebRTC signaling infrastructure.
+
+## Current Status: On Hold
+
+Remote connection was partially implemented but put on hold due to a critical bug where the `ma-api` data channel becomes one-way after 1-3 minutes. See `MA_WEBRTC_BUG_REPORT.md` for details.
+
+---
+
+## Architecture
+
+### How It Works
+
+```
+┌─────────────────┐     WebSocket      ┌──────────────────────────┐
+│  Ensemble App   │◄──────────────────►│  MA Server (local WS)    │
+└─────────────────┘                    └──────────────────────────┘
+        │                                         │
+        │ (when local unavailable)                │
+        ▼                                         ▼
+┌─────────────────┐                    ┌──────────────────────────┐
+│  SignalingClient│◄──── WebSocket ───►│ signaling.music-assistant│
+└─────────────────┘                    │        .io/ws            │
+        │                              └──────────────────────────┘
+        │ ICE candidates, SDP                     │
+        ▼                                         ▼
+┌─────────────────┐                    ┌──────────────────────────┐
+│  WebRTC Peer    │◄═══ Data Channel ══►│  MA Server WebRTC       │
+│  Connection     │    (ma-api)         │  Endpoint               │
+└─────────────────┘                    └──────────────────────────┘
+```
+
+### Components
+
+1. **SignalingClient** - WebSocket connection to `wss://signaling.music-assistant.io/ws`
+2. **WebRTCConnection** - Manages RTCPeerConnection and data channels
+3. **RemoteBridge** - Bridges local WebSocket API to remote WebRTC connection
+
+### Data Channels
+
+| Channel | Purpose | Traffic Pattern |
+|---------|---------|-----------------|
+| `ma-api` | JSON API requests/responses | High volume, large payloads |
+| `sendspin` | Audio streaming + control | Low JSON, binary audio data |
+
+---
+
+## Key Files to Create/Modify
+
+### New Files
+
+| File | Purpose |
+|------|---------|
+| `lib/services/remote/signaling_client.dart` | WebSocket client for signaling server |
+| `lib/services/remote/webrtc_connection.dart` | WebRTC peer connection management |
+| `lib/services/remote/remote_bridge.dart` | Bridges API calls to WebRTC |
+
+### Files to Modify
+
+| File | Changes |
+|------|---------|
+| `lib/services/music_assistant_api.dart` | Add remote connection fallback |
+| `lib/providers/music_assistant_provider.dart` | Expose remote connection state |
+| `pubspec.yaml` | Add `flutter_webrtc` dependency |
+
+---
+
+## Implementation Steps
+
+### Step 1: Add Dependencies
+
+```yaml
+# pubspec.yaml
+dependencies:
+  flutter_webrtc: ^0.12.0  # or latest
+```
+
+### Step 2: Implement SignalingClient
+
+The signaling client connects to Music Assistant's signaling server and exchanges WebRTC offers/answers.
+
+```dart
+class SignalingClient {
+  WebSocket? _socket;
+
+  Future<void> connect(String serverId) async {
+    _socket = await WebSocket.connect('wss://signaling.music-assistant.io/ws');
+
+    // Send connect request
+    _send({
+      'type': 'connect-request',
+      'server_id': serverId,
+    });
+
+    // Listen for messages
+    _socket!.listen(_handleMessage);
+  }
+
+  void _handleMessage(dynamic data) {
+    final message = jsonDecode(data);
+    switch (message['type']) {
+      case 'answer':
+        onAnswer?.call(message['sdp']);
+        break;
+      case 'ice-candidate':
+        onIceCandidate?.call(message['candidate']);
+        break;
+    }
+  }
+}
+```
+
+### Step 3: Implement WebRTCConnection
+
+```dart
+class WebRTCConnection {
+  RTCPeerConnection? _peerConnection;
+  RTCDataChannel? _apiChannel;
+  RTCDataChannel? _sendspinChannel;
+
+  Future<void> connect(SignalingClient signaling) async {
+    // Create peer connection with STUN/TURN servers
+    _peerConnection = await createPeerConnection({
+      'iceServers': [
+        {'urls': 'stun:stun.l.google.com:19302'},
+        // TURN servers provided by signaling
+      ],
+    });
+
+    // Create data channels BEFORE creating offer
+    _apiChannel = await _peerConnection!.createDataChannel(
+      'ma-api',
+      RTCDataChannelInit()..ordered = true,
+    );
+
+    _sendspinChannel = await _peerConnection!.createDataChannel(
+      'sendspin',
+      RTCDataChannelInit()..ordered = true,
+    );
+
+    // Create and send offer
+    final offer = await _peerConnection!.createOffer();
+    await _peerConnection!.setLocalDescription(offer);
+    signaling.sendOffer(offer.sdp!);
+
+    // Handle answer from server
+    signaling.onAnswer = (sdp) async {
+      await _peerConnection!.setRemoteDescription(
+        RTCSessionDescription(sdp, 'answer'),
+      );
+    };
+  }
+}
+```
+
+### Step 4: Implement RemoteBridge
+
+The bridge translates between the local WebSocket API format and WebRTC data channel messages.
+
+```dart
+class RemoteBridge {
+  final WebRTCConnection _webrtc;
+  final StreamController<String> _messageController;
+
+  void sendCommand(String json) {
+    _webrtc.sendToApiChannel(json);
+  }
+
+  Stream<String> get messages => _messageController.stream;
+}
+```
+
+### Step 5: Integrate with MusicAssistantAPI
+
+```dart
+class MusicAssistantAPI {
+  WebSocket? _localSocket;
+  RemoteBridge? _remoteBridge;
+
+  Future<void> connect(String host, {String? serverId}) async {
+    try {
+      // Try local connection first
+      _localSocket = await WebSocket.connect('ws://$host/ws');
+    } catch (e) {
+      // Fall back to remote if serverId provided
+      if (serverId != null) {
+        _remoteBridge = RemoteBridge();
+        await _remoteBridge!.connect(serverId);
+      }
+    }
+  }
+}
+```
+
+---
+
+## Critical Implementation Details
+
+### 1. Channel Creation Order
+
+The client MUST create data channels BEFORE sending the WebRTC offer. The server expects the client to create:
+- `ma-api` - for API traffic
+- `sendspin` - for audio streaming (optional)
+
+### 2. Health Monitoring
+
+Implement aggressive health checks because data channels can silently die:
+
+```dart
+// Track message counts
+int _sentCount = 0;
+int _recvCount = 0;
+DateTime _lastRecvTime = DateTime.now();
+
+// Health check every 10 seconds
+void _healthCheck() {
+  final timeSinceRecv = DateTime.now().difference(_lastRecvTime);
+  if (timeSinceRecv.inSeconds > 30) {
+    // Channel is dead, trigger reconnection
+    _reconnect();
+  }
+}
+```
+
+### 3. Keepalive Messages
+
+Send periodic keepalive on the data channel itself (not just signaling):
+
+```dart
+void _sendKeepalive() {
+  _apiChannel?.send(RTCDataChannelMessage(
+    jsonEncode({'type': 'ping', 'timestamp': DateTime.now().toIso8601String()}),
+  ));
+}
+```
+
+### 4. Flow Control
+
+Monitor buffer to prevent overflow:
+
+```dart
+void sendMessage(String json) {
+  if (_apiChannel!.bufferedAmount > 1048576) {  // 1MB
+    // Queue message, don't send
+    _sendQueue.add(json);
+    return;
+  }
+  _apiChannel!.send(RTCDataChannelMessage(json));
+}
+```
+
+---
+
+## Known Issues & Pitfalls
+
+### 1. One-Way Channel Death (CRITICAL - UNSOLVED)
+
+The `ma-api` channel stops receiving after 1-3 minutes while `sendspin` continues working. This occurs in both flutter_webrtc and WebView implementations.
+
+**Workaround options:**
+- Detect via health check and force reconnection
+- Try single-channel multiplexing (see `PLAN_B_SINGLE_CHANNEL.md`)
+- Report to MA team and wait for server-side fix
+
+### 2. flutter_webrtc Quirks
+
+- `RTCDataChannel.state` may show "open" when actually dead
+- `bufferedAmount` accuracy varies by platform
+- `onBufferedAmountLow` callback support inconsistent
+
+### 3. Android Background Throttling
+
+Android aggressively throttles background WebRTC. Consider:
+- Foreground service for sustained connections
+- Reconnection on app resume
+
+### 4. ICE/TURN Issues
+
+- aiortc (server-side) has known TURN + DataChannel bugs
+- May need ICE restart on network changes
+
+---
+
+## Testing Checklist
+
+- [ ] Connect via remote when local unavailable
+- [ ] Verify API commands work (players/all, library queries)
+- [ ] Test sustained connection (30+ minutes)
+- [ ] Test app backgrounding and resume
+- [ ] Test network transitions (WiFi ↔ cellular)
+- [ ] Verify reconnection after channel death
+- [ ] Test sendspin audio streaming (if implemented)
+
+---
+
+## Useful Resources
+
+- [Music Assistant Remote Access Docs](https://music-assistant.io/docs/remote-access/)
+- [flutter_webrtc Package](https://pub.dev/packages/flutter_webrtc)
+- [WebRTC Data Channel MDN](https://developer.mozilla.org/en-US/docs/Web/API/RTCDataChannel)
+- Signaling server: `wss://signaling.music-assistant.io/ws`
+
+---
+
+## Files in This Directory
+
+| File | Description |
+|------|-------------|
+| `FUTURE_IMPLEMENTATION_GUIDE.md` | This file - implementation guide |
+| `MA_WEBRTC_BUG_REPORT.md` | Bug report for MA team |
+| `WEBRTC_DISCONNECT_FIXES.md` | All fixes attempted |
+| `WEBRTC_PROGRESS.md` | Progress log |
+| `PLAN_B_SINGLE_CHANNEL.md` | Alternative single-channel approach |
+| `webrtc-failure-logs.txt` | Raw failure logs |
+| `console-export-*.log` | Browser console exports |
+
+---
+
+## Quick Start for Future Implementation
+
+1. Read this guide fully
+2. Review `WEBRTC_DISCONNECT_FIXES.md` for all attempted fixes
+3. Check if MA team has fixed server-side issues
+4. Start with basic implementation, add health monitoring early
+5. Test extensively before shipping - the failure mode is subtle

docs/remote-connection/MA_WEBRTC_BUG_REPORT.md

@@ -0,0 +1,127 @@
+# WebRTC Data Channel Failure on Android - Bug Report
+
+## Summary
+
+When connecting to Music Assistant via WebRTC remote access (Nabu Casa), the `ma-api` data channel becomes **one-way** (can send, cannot receive) after 1-3 minutes of use, while the `sendspin` channel continues working normally.
+
+## Environment
+
+- **MA Server**: 2.8.0b7 (Home Assistant add-on)
+- **Client**: Android app (Flutter) connecting via Nabu Casa remote access
+- **Remote Access**: WebRTC via `wss://signaling.music-assistant.io/ws`
+
+## Reproduction Steps
+
+1. Connect to MA server via WebRTC remote access (not local network)
+2. Use the app normally - browse library, view players
+3. After 1-3 minutes, the connection degrades
+4. Commands time out, but signaling ping/pong continues working
+
+## Observed Behavior
+
+### Timeline from logs:
+
+```
+07:14:20 - Working normally
+           Health: API sent:51 recv:54 (balanced)
+
+07:15:57 - Receive stops
+           Health: API sent:97 recv:97, lastRecv:12s ago
+
+07:16:02 - Timeouts begin
+           "TimeoutException: Command timeout: players/all"
+
+07:16:17 - Sendspin still works!
+           "Sendspin: Received server/time response"
+           Health: API sent:114 recv:97, lastRecv:27s ago
+
+07:17:30 - Forced reconnect
+           Health: API sent:137 recv:97, lastRecv:42s ago
+           "Health check detected stale connection"
+```
+
+### Key Observation
+
+| Channel | Traffic Pattern | Status |
+|---------|-----------------|--------|
+| `ma-api` | High (10+ msg/s, large payloads) | **FAILS** - stops receiving |
+| `sendspin` | Low (~1 msg/5s, small payloads) | **SURVIVES** - continues working |
+| Signaling | Ping/pong every 15s | **SURVIVES** - continues working |
+
+The WebRTC peer connection remains in "connected" state. ICE connection shows "completed". Only the ma-api data channel stops receiving.
+
+## Testing Performed
+
+### Test 1: flutter_webrtc (Native WebRTC)
+- **Result**: ma-api channel dies after 1-3 minutes
+- **Sendspin**: Continues working
+
+### Test 2: WebView-based WebRTC (Browser engine)
+- **Hypothesis**: Use Android WebView's browser-native WebRTC, since MA Web UI works
+- **Implementation**: Hidden InAppWebView running JavaScript WebRTC engine
+- **Result**: **Same failure mode** - ma-api dies, sendspin survives
+- **Conclusion**: Not a flutter_webrtc bug
+
+### Test 3: Various Data Channel Settings
+- Tried `ordered: false` with `maxRetransmits: 3`
+- Tried letting server create channels (failed - server expects client to create)
+- No improvement
+
+## Analysis
+
+The identical failure in both native and WebView WebRTC implementations suggests the issue is:
+
+1. **Server-side** - Different handling of ma-api vs sendspin channels
+2. **TURN relay** - High-traffic channel may hit limits
+3. **Not client-specific** - Both implementations fail identically
+
+### Questions for MA Team
+
+1. Are the two data channels (`ma-api`, `sendspin`) created with different settings?
+2. Is there any server-side buffering or rate limiting that could affect high-traffic channels?
+3. Does the MA Web UI use different data channel configurations?
+4. Are there known issues with the TURN relay for sustained high-traffic channels?
+
+## Comparison: MA Web UI vs Android App
+
+| Aspect | MA Web UI | Android App |
+|--------|-----------|-------------|
+| Platform | Browser tab (visible, active) | Background-capable app |
+| WebRTC | Browser native | flutter_webrtc / WebView |
+| Result | Works | Fails after 1-3 min |
+
+The MA Web UI runs in a **visible, active browser tab**. Android may throttle background apps differently, but this doesn't explain why sendspin survives while ma-api dies on the same connection.
+
+## Logs
+
+### Health Check Pattern (shows channel death)
+```
+07:14:25 API sent:51 recv:54, lastRecv:2s ago   <- Working
+07:15:35 API sent:87 recv:91, lastRecv:2s ago   <- Working
+07:16:05 API sent:108 recv:97, lastRecv:17s ago <- DYING (gap growing)
+07:16:15 API sent:114 recv:97, lastRecv:27s ago <- DEAD
+07:16:45 API sent:130 recv:97, lastRecv:27s ago <- Still sending, no receive
+07:17:30 API sent:137 recv:97, lastRecv:42s ago <- Forced reconnect
+```
+
+### Sendspin Still Working During Failure
+```
+07:16:17 Sendspin: Received server/time response  <- Still alive!
+07:16:47 Sendspin: Received server/time response  <- Still alive!
+```
+
+## Requested Information
+
+1. Data channel creation code/settings for both channels
+2. Any server-side differences in channel handling
+3. TURN server configuration details
+4. Whether this has been reported by other Android/mobile clients
+
+## Workaround
+
+Currently using local WebSocket connection when on same network. Remote access via WebRTC is unusable for sustained use.
+
+---
+
+**Reporter**: Ensemble Android App Developer
+**Date**: 2026-01-24

docs/remote-connection/PLAN_B_SINGLE_CHANNEL.md

@@ -0,0 +1,149 @@
+# Plan B: Single Data Channel Multiplexing
+
+## Why This Might Be Needed
+
+If upgrading flutter_webrtc doesn't fix the one-way channel failure, the root cause is likely a bug in how flutter_webrtc (or underlying libwebrtc) handles **multiple data channels**.
+
+Evidence:
+- MA Web UI works fine with local playback (same server, browser WebRTC)
+- Our app uses flutter_webrtc which has known issues:
+  - [Issue #1428](https://github.com/flutter-webrtc/flutter-webrtc/issues/1428): Threading issues causing data loss
+  - [Issue #974](https://github.com/flutter-webrtc/flutter-webrtc/issues/974): EventChannel intermittently fails
+- Pattern matches: second channel survives while first dies
+
+## Current Architecture
+
+```
+┌─────────────────────────────────────────────────┐
+│              WebRTC Peer Connection             │
+├────────────────────┬────────────────────────────┤
+│   ma-api channel   │     sendspin channel       │
+│   (JSON API)       │   (JSON + binary audio)    │
+│   SCTP stream 0    │     SCTP stream 1          │
+└────────────────────┴────────────────────────────┘
+```
+
+## Proposed Architecture
+
+```
+┌─────────────────────────────────────────────────┐
+│              WebRTC Peer Connection             │
+├─────────────────────────────────────────────────┤
+│              unified channel                     │
+│    (multiplexed: API + Sendspin text + binary)  │
+│              SCTP stream 0                       │
+└─────────────────────────────────────────────────┘
+```
+
+## Multiplexing Protocol
+
+### Message Framing
+
+Each message has a 1-byte type prefix:
+
+| Prefix | Type | Content |
+|--------|------|---------|
+| 0x00 | API | JSON text (MA API request/response) |
+| 0x01 | Sendspin Text | JSON text (Sendspin control messages) |
+| 0x02 | Sendspin Binary | Raw bytes (PCM audio data) |
+
+### Implementation
+
+#### Sending (Client → Server)
+
+```dart
+void sendApiMessage(String json) {
+  final prefix = Uint8List.fromList([0x00]);
+  final payload = utf8.encode(json);
+  final message = Uint8List(1 + payload.length);
+  message[0] = 0x00;
+  message.setRange(1, message.length, payload);
+  _dataChannel.send(RTCDataChannelMessage.fromBinary(message));
+}
+
+void sendSendspinText(String json) {
+  final prefix = Uint8List.fromList([0x01]);
+  final payload = utf8.encode(json);
+  final message = Uint8List(1 + payload.length);
+  message[0] = 0x01;
+  message.setRange(1, message.length, payload);
+  _dataChannel.send(RTCDataChannelMessage.fromBinary(message));
+}
+
+void sendSendspinBinary(Uint8List audio) {
+  final message = Uint8List(1 + audio.length);
+  message[0] = 0x02;
+  message.setRange(1, message.length, audio);
+  _dataChannel.send(RTCDataChannelMessage.fromBinary(message));
+}
+```
+
+#### Receiving (Server → Client)
+
+```dart
+void _onMessage(RTCDataChannelMessage message) {
+  final data = message.binary;
+  if (data == null || data.isEmpty) return;
+
+  final type = data[0];
+  final payload = data.sublist(1);
+
+  switch (type) {
+    case 0x00: // API
+      final json = utf8.decode(payload);
+      _handleApiMessage(json);
+      break;
+    case 0x01: // Sendspin text
+      final json = utf8.decode(payload);
+      _handleSendspinText(json);
+      break;
+    case 0x02: // Sendspin binary
+      _handleSendspinBinary(payload);
+      break;
+  }
+}
+```
+
+## Server-Side Changes Required
+
+The Music Assistant server would need to:
+1. Accept a single "unified" data channel instead of separate ma-api and sendspin channels
+2. Multiplex responses using the same framing protocol
+3. This requires changes to the MA remote connection code
+
+**Alternative**: Keep server unchanged, do multiplexing in a proxy layer on the client.
+
+## Client-Only Approach (No Server Changes)
+
+If we can't change the server, we could:
+
+1. Still create two channels to the server (ma-api + sendspin)
+2. But internally route them through a single "virtual" channel for flutter_webrtc
+3. This is more complex and may not avoid the underlying bug
+
+## Files to Modify
+
+| File | Changes |
+|------|---------|
+| `webrtc_connection.dart` | Single channel creation, multiplexing logic |
+| `remote_bridge.dart` | Route messages based on type prefix |
+
+## Risks
+
+1. **Server compatibility**: Requires MA server changes or complex client proxy
+2. **Performance**: Extra byte per message, decode overhead
+3. **Binary handling**: Must handle all messages as binary (not text)
+
+## Testing Plan
+
+1. Implement client-side changes
+2. Test with modified server (if available) or mock
+3. Verify both API and Sendspin traffic flows correctly
+4. Long-duration stability test
+
+## Decision Point
+
+Try this approach if:
+- flutter_webrtc 0.14.x doesn't fix the issue
+- The one-way failure pattern continues
+- We've confirmed the issue is multi-channel specific

docs/remote-connection/WEBRTC_DISCONNECT_FIXES.md

@@ -0,0 +1,406 @@
+# WebRTC Data Channel Disconnect Fixes
+
+## Document Purpose
+Track all fixes attempted for the WebRTC data channel disconnection issues in Ensemble's remote connection feature. This document should be referenced when debugging future disconnection problems.
+
+---
+
+## Problem Summary
+
+The WebRTC data channel between the Ensemble mobile app and Music Assistant server can fail in several ways:
+
+1. **One-way failure**: Data channel appears "open" but only sends work, receives stop
+2. **Silent disconnect**: No error events fire, channel just stops working
+3. **ICE failure**: ICE connection fails, properly detected but causes disconnect
+4. **Signaling disconnect**: Signaling WebSocket closes, causing ICE/WebRTC to fail
+
+---
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `lib/services/remote/webrtc_connection.dart` | WebRTC peer connection, data channel management |
+| `lib/services/remote/remote_bridge.dart` | WebSocket bridge, health monitoring, reconnection logic |
+| `lib/services/remote/signaling_client.dart` | Signaling server WebSocket connection |
+
+---
+
+## Implemented Fixes (Chronological)
+
+### Fix 1: Data Channel Keepalive (Original)
+**Problem**: Data channel could silently die without any error events firing.
+
+**Solution**: Added periodic keepalive ping/pong on the data channel itself.
+
+**Code** (`webrtc_connection.dart`):
+- `_keepaliveTimer`: Runs every 10 seconds
+- `_checkKeepalive()`: Checks time since last data received
+- `_sendKeepalivePing()`: Sends JSON ping message
+- `_recordDataReceived()`: Called on every message receipt
+
+**Constants**:
+```dart
+static const _keepaliveInterval = Duration(seconds: 10);
+static const _keepaliveTimeout = Duration(seconds: 20);  // Reduced from 30
+static const _maxKeepaliveMisses = 2;  // Reduced from 3
+```
+
+### Fix 2: ICE Recovery
+**Problem**: ICE connection could temporarily disconnect and might auto-recover.
+
+**Solution**: Added ICE recovery timer before declaring failure.
+
+**Code** (`webrtc_connection.dart`):
+- `_startIceRecovery()`: Starts 5-second timer when ICE disconnects
+- `_cancelIceRecovery()`: Cancels if ICE recovers on its own
+- `_attemptIceRestart()`: Calls `restartIce()` if recovery timer expires
+
+### Fix 3: Flow Control (Buffer Overflow Prevention)
+**Problem**: Fire-and-forget sends could overflow the 16MB SCTP buffer, causing silent channel death.
+
+**Solution**: Added send-side flow control with buffering.
+
+**Code** (`webrtc_connection.dart`):
+```dart
+static const _maxBufferedAmount = 1048576;  // 1MB threshold
+static const _bufferLowThreshold = 65536;   // 64KB resume threshold
+bool _sendPaused = false;
+final _sendQueue = <String>[];
+```
+
+**Modified `sendRaw()`**:
+- Checks `bufferedAmount` before sending
+- Queues messages if buffer > 1MB
+- `onBufferedAmountLow` callback drains queue
+
+### Fix 4: Health Check Stale Detection
+**Problem**: Health check could see "30s since last data" but not trigger reconnection.
+
+**Solution**: Reduced stale detection threshold from 45s to 30s.
+
+**Code** (`remote_bridge.dart`):
+```dart
+if (_state == RemoteBridgeState.connected && timeSinceLastData > 30 && !_isReconnecting) {
+  // Force reconnection
+}
+```
+
+### Fix 5: Reduced Keepalive Timeouts
+**Problem**: 30s timeout × 3 misses = 90s minimum before detection.
+
+**Solution**: Reduced to 20s timeout × 2 misses = ~40s detection.
+
+### Fix 6: Recv Stagnation Detection
+**Problem**: One-way failure where recv stops but sent continues not detected quickly enough.
+
+**Solution**: Track recv count across health checks. If recv stuck while sent increases for 2 consecutive checks (20s), force reconnection.
+
+**Code** (`remote_bridge.dart`):
+```dart
+// Track across health checks
+int _lastHealthCheckRecvCount = 0;
+int _lastHealthCheckSentCount = 0;
+int _recvStagnationCount = 0;
+
+// In health check:
+if (recvStuck && sentIncreased) {
+  _recvStagnationCount++;
+  if (_recvStagnationCount >= 2) {
+    // Force reconnection - channel is one-way
+  }
+}
+```
+
+**Detection time**: ~20 seconds (2 × 10s health check interval)
+
+---
+
+## Log Patterns to Watch For
+
+### Healthy Connection
+```
+Health check - API sent:93 recv:88 ... lastRecv:0s ago
+```
+- `sent` and `recv` both increasing
+- `lastRecv` low (< 5s typically)
+
+### One-Way Failure (CRITICAL)
+```
+Health check - API sent:206 recv:163 ... lastRecv:30s ago
+Health check - API sent:218 recv:163 ... lastRecv:40s ago
+```
+- `sent` increases, `recv` STUCK
+- `lastRecv` keeps increasing
+- Data channel still shows "open"
+
+### Signaling Disconnect
+```
+WebRTC: Signaling disconnected
+... (6-16 seconds later) ...
+WebRTC: ICE connection state: RTCIceConnectionStateDisconnected
+WebRTC: ICE connection state: RTCIceConnectionStateFailed
+```
+
+### Network Failure (DNS)
+```
+Signaling: WebSocket closed
+... (reconnection attempt) ...
+Signaling: Failed to connect: SocketException: Failed host lookup: 'signaling.music-assistant.io'
+```
+This indicates the phone lost network connectivity entirely.
+
+### Reconnection Storm (Signaling Instability)
+```
+Signaling: Connecting to wss://signaling.music-assistant.io/ws
+Signaling: Sending connect-request
+Signaling: WebSocket closed  ← Closes within 100-500ms
+WebRTC: Signaling disconnected
+RemoteBridge: Scheduling reconnect attempt X/10 in Ys
+```
+Rapid reconnection loop - signaling never stays connected long enough.
+
+### Flow Control Engaged
+```
+WebRTC: ⚠️ Buffer full (1234567 bytes) or paused - queueing message
+WebRTC: Buffer drained to 12345 bytes - draining 5 queued messages
+WebRTC: ✅ Send queue drained (5 messages) - resuming normal sends
+```
+
+### Keepalive Detection
+```
+WebRTC: ⚠️ Keepalive timeout! No data for 22s (missed: 1/2)
+WebRTC: ❌ Data channel appears dead - triggering reconnection
+```
+
+---
+
+## Known Issues / Limitations
+
+### 1. flutter_webrtc Limitations
+- `RTCDataChannel.state` may show "open" when actually dead (Issue #843)
+- `bufferedAmount` may not be accurate on all platforms
+- `onBufferedAmountLow` callback support varies
+
+### 2. SCTP Receive Window
+- If server sends faster than client processes, receive window fills
+- This causes server-side to stop sending, client sees no data
+- No way to monitor receive-side buffer from client
+
+### 3. TURN Server Issues
+- aiortc (server-side) has known issues with TURN + DataChannel (#1156)
+- Data channel may fail silently when using TURN relay
+
+### 4. Network Transitions
+- WiFi → Cellular or vice versa can cause ICE to fail
+- App backgrounding on mobile can close WebSocket/WebRTC
+
+---
+
+## Root Cause Categories
+
+### Category A: Network Issues (Not Code Bugs)
+These are environmental issues, not bugs in our code:
+- **DNS failure**: `Failed host lookup` - Phone lost internet
+- **WiFi/Cellular switch**: Network changed, connections dropped
+- **Server unreachable**: Signaling server down or blocked
+- **Firewall/NAT issues**: TURN relay needed but unavailable
+
+**Evidence**: Signaling WebSocket closes, DNS lookups fail, reconnection attempts fail repeatedly.
+
+### Category B: WebRTC/SCTP Issues (Partial Code Control)
+These can be mitigated but not fully prevented:
+- **One-way channel death**: Channel appears open but data stops flowing
+- **Buffer overflow**: Too much data sent, SCTP buffer exceeded
+- **ICE failure**: Network path lost, no recovery possible
+
+**Evidence**: Data channel shows "open" but `recv` stuck, `lastRecv` increasing.
+
+### Category C: Code Bugs (Fixable)
+Issues in our implementation:
+- **Detection too slow**: Timeouts too long, misses too many
+- **Recovery not triggered**: State checks wrong, reconnection not started
+- **Resource leaks**: Timers not cancelled, connections not cleaned up
+
+**Evidence**: Logs show problem but no action taken, or wrong action taken.
+
+---
+
+## Debugging Checklist
+
+When investigating a disconnect:
+
+1. **Find the last successful response**:
+   ```
+   grep "WebRTC API → WS" logs.txt | head -5
+   ```
+
+2. **Check health check progression**:
+   ```
+   grep "Health check" logs.txt
+   ```
+   Look for `recv` getting stuck while `sent` increases.
+
+3. **Check for signaling issues**:
+   ```
+   grep -i "signaling" logs.txt
+   ```
+
+4. **Check ICE state changes**:
+   ```
+   grep "ICE connection state" logs.txt
+   ```
+
+5. **Check for keepalive detection**:
+   ```
+   grep -i "keepalive" logs.txt
+   ```
+
+6. **Check buffer status**:
+   ```
+   grep -E "(buffer|queue|paused)" logs.txt
+   ```
+
+---
+
+## Potential Future Improvements
+
+### 1. Server-Side Backpressure
+MA protocol doesn't have explicit backpressure. Could add:
+- Client-side request throttling
+- Application-level ACKs for critical messages
+
+### 2. More Aggressive Detection
+- Track recv count across health checks, detect stagnation
+- Shorter keepalive interval (5s instead of 10s)
+
+### 3. Proactive Health Signals
+- Monitor `bufferedAmount` trend (increasing = problem)
+- Track round-trip latency of keepalive pings
+
+### 4. Connection Quality Metrics
+- Expose packet loss, jitter from WebRTC stats
+- Use to predict imminent failure
+
+---
+
+## Test Scenarios
+
+| Scenario | How to Test | Expected Behavior |
+|----------|-------------|-------------------|
+| Normal usage | Browse library, play music | No warnings |
+| Heavy sync | Pull-to-refresh library | Buffer may queue, should drain |
+| Long session | Leave connected 2+ hours | Should stay connected |
+| Rapid navigation | Quick tab switching | Brief queue usage, recovers |
+| Network change | WiFi → Cellular | Should detect and reconnect |
+| App background | Background for 5+ min | May disconnect, should reconnect |
+
+---
+
+## Observed Failure Patterns
+
+### Pattern 1: One-Way Death After Library Sync
+**Observed**: 2026-01-23 (multiple times)
+
+```
+17:13:06.175 - Last response (playlists sync)
+17:13:06.264 - Local batch save
+-- 5 seconds silence --
+17:13:11.005 - Send players/all → NO RESPONSE
+17:13:13.914 - ICE state: completed (looks healthy!)
+17:13:28 - Keepalive detects timeout
+17:13:38 - Reconnection triggered
+```
+
+**Characteristics**:
+- Often happens after library sync (large batch responses)
+- ICE shows "completed" even though data channel is dead
+- Signaling ping/pong continues working
+- Only data channel receive is affected
+
+**Hypothesis**:
+- Server-side SCTP buffer exhausted from sending large responses?
+- Client receive window full, server blocks?
+- flutter_webrtc onMessage callback stops firing?
+
+### Pattern 2: Reconnection Storm / Signaling Instability
+**Observed**: 2026-01-23 17:30-17:31
+
+```
+17:31:05.093 - Signaling: Connecting
+17:31:05.216 - Signaling: Sending connect-request
+17:31:05.218 - Signaling: WebSocket closed (123ms later!)
+17:31:05.218 - WebRTC: Signaling disconnected
+```
+
+**Characteristics**:
+- Signaling WebSocket closes almost immediately after connect
+- Multiple rapid reconnection attempts (storm)
+- Connection never stable long enough for data flow
+- Often happens after network instability
+- Artist detail, albums etc don't load because connection keeps failing
+
+**Possible Causes**:
+- Network instability (WiFi/cellular issues)
+- Signaling server rate limiting
+- DNS resolution failures
+- Server rejecting rapid reconnection attempts
+
+**Side Effects**:
+- UI shows errors like "Not connected to Music Assistant server"
+- Artist/album detail screens fail to load
+- Players list empty or stale
+
+### Pattern 3: API Channel Dies While Sendspin Lives
+**Observed**: 2026-01-23 17:53
+
+```
+17:53:35.755 - Send album_tracks request → NO RESPONSE
+17:53:40.596 - Health check: recv stuck at 197, sent increased
+17:53:55.204 - Sendspin channel RECEIVES server/time response!
+17:54:02.790 - Keepalive detects dead API channel
+```
+
+**Characteristics**:
+- API data channel (ma-api) stops receiving
+- Sendspin data channel continues working normally
+- Same WebRTC peer connection, different data channels
+- This proves it's NOT a network issue - Sendspin traffic flows fine
+
+**Hypothesis**:
+- flutter_webrtc bug where `onMessage` callback stops firing for one channel
+- Possible memory/GC issue with the callback
+- Server-side might be sending to wrong channel?
+
+**Key Evidence**:
+- Recv count stays at 197 for API
+- Sendspin recv count increases (7→8)
+- Both channels use same peer connection
+
+---
+
+## Version History
+
+| Date | Build | Changes |
+|------|-------|---------|
+| 2026-01-23 | ~v49 | Initial flow control implementation |
+| 2026-01-23 | ~v49 | Reduced keepalive timeout 30→20s, misses 3→2 |
+| 2026-01-23 | ~v49 | Reduced health check stale threshold 45→30s |
+| 2026-01-23 | ~v49 | Fixed excessive "queue drained" logging |
+| 2026-01-23 | ~v49 | Created WEBRTC_DISCONNECT_FIXES.md documentation |
+| 2026-01-23 | ~v49 | Added recv stagnation detection (20s detection) |
+| 2026-01-23 | ~v49 | Documented Pattern 2: Reconnection storm / signaling instability |
+| 2026-01-23 | ~v49 | Fixed race condition in _scheduleReconnect (multiple simultaneous calls) |
+| 2026-01-23 | ~v49 | Added WebSocket close code/reason logging to signaling |
+| 2026-01-23 | ~v49 | **CRITICAL FIX**: _reconnectWebRTC() was returning immediately due to _isReconnecting already being true |
+| 2026-01-23 | ~v49 | Fixed old WebRTC callbacks firing during reconnection cleanup (clear callbacks before disconnect) |
+| 2026-01-23 | ~v49 | Fixed onStateChanged handler calling _handleWebRTCDisconnection during active reconnection |
+
+---
+
+## References
+
+- flutter_webrtc Issue #843: Data channel state unreliable
+- aiortc Issue #1156: TURN + DataChannel bugs
+- WebRTC SCTP: Max buffer is 16MB, recommended threshold 1MB
+- Music Assistant remote protocol: No explicit flow control

docs/remote-connection/WEBRTC_PROGRESS.md

@@ -0,0 +1,118 @@
+# WebRTC Remote Connection Progress
+
+## Problem Statement
+The flutter_webrtc library has reliability issues causing data channel failures during remote connections via Nabu Casa. The ma-api data channel becomes one-way (can send, but receives stop) after some time, while the sendspin channel continues working.
+
+## Approaches Tried
+
+### 1. Original Implementation (flutter_webrtc)
+- **Status**: Fails
+- **Issue**: ma-api data channel goes one-way after some time
+- **Files**: `lib/services/remote/webrtc_connection.dart`
+
+### 2. WebView-based WebRTC Implementation
+- **Status**: Same failure mode
+- **Hypothesis**: Use browser-native WebRTC via InAppWebView, since MA Web UI works
+- **Result**: Same one-way channel death occurs
+- **Key Finding**: This proves the issue is NOT specific to flutter_webrtc
+
+## Key Observations
+
+From the logs:
+```
+lastRecv:26s ago          <- No messages received in 26 seconds
+API sent:674 recv:618     <- Gap growing, responses stopped
+```
+
+- Signaling ping/pong continues working
+- Sendspin channel continues receiving (`server/time` responses)
+- Only ma-api channel becomes one-way
+- WebRTC peer connection itself remains "connected"
+
+## Differences from Working MA Web UI
+
+The MA Web UI runs in a **visible, active browser tab**. Our implementations:
+1. flutter_webrtc: Native WebRTC in background app
+2. WebView: Browser WebRTC in **hidden 1x1 pixel WebView**
+
+Android aggressively throttles hidden WebViews to save battery.
+
+## Current Implementation (WebView)
+
+### Files Created
+| File | Purpose |
+|------|---------|
+| `lib/services/remote/webview_webrtc_connection.dart` | Dart WebView wrapper |
+| `assets/webrtc_engine.js` | JavaScript WebRTC engine |
+
+### Files Modified
+| File | Changes |
+|------|---------|
+| `pubspec.yaml` | Added `flutter_inappwebview: ^6.0.0` |
+| `lib/services/remote/remote_bridge.dart` | Uses `WebViewWebRTCConnection` |
+| `lib/providers/music_assistant_provider.dart` | Exposes WebView widget |
+| `lib/main.dart` | Adds WebView to widget tree |
+
+### Architecture
+```
+MusicAssistantAPI -> localhost WebSocket -> RemoteBridge
+                                              |
+                                   WebViewWebRTCConnection
+                                              |
+                                   Hidden InAppWebView
+                                              |
+                                   JavaScript WebRTC Engine
+                                              |
+                                   MA Server via TURN
+```
+
+## Current Fixes Being Tested
+
+### 1. Prevent WebView Throttling
+- Changed WebView position from off-screen (-10,-10) to on-screen (0,0) with Opacity(0)
+- Added various InAppWebViewSettings to prevent background throttling
+
+### 2. Data Channel Settings
+- Changed from `ordered: true` to `ordered: false` with `maxRetransmits: 3`
+- Hypothesis: Ordered delivery may cause buffer bloat issues
+
+### 3. Buffer Monitoring
+- Added `bufferedAmount` checking in JavaScript
+- Logs warning when buffer exceeds 1MB
+- Added `getChannelHealth()` function for diagnostics
+
+### 4. Reduced Logging
+- Removed per-message logging (was filling logs too fast)
+- Keep only state changes, errors, and warnings
+
+## Experiments Completed
+
+### 5. Server-Created Channels (Failed)
+- **Hypothesis**: Let server create data channels to avoid ID collisions
+- **Result**: Connection timeout - server expects CLIENT to create channels
+- **Learning**: Client must create channels before sending offer
+
+## Next Steps to Try
+
+1. **Make WebView actually visible** - Android may still throttle Opacity(0) WebView
+2. **Single data channel** - Use only ma-api, disable sendspin
+3. **Periodic channel recreation** - Detect stale channel and recreate
+4. **Report to MA team** - Browser WebRTC also fails, suggesting server-side issue
+
+## Test APK Location
+`/home/chris/Ensemble/ensemble-webview-webrtc.apk`
+
+## Useful Debug Commands
+
+Check channel health (in JS console or via Dart):
+```javascript
+getChannelHealth()
+// Returns: { peerConnection, iceConnection, apiChannel, apiBuffered, sendspinChannel, sendspinBuffered, signalingConnected }
+```
+
+## Open Questions
+
+1. Why does sendspin channel survive when ma-api dies?
+2. Is there a difference in how MA server handles the two channels?
+3. Does MA Web UI use different data channel settings?
+4. Is there a TURN relay issue specific to high-traffic channels?

fastlane/metadata/android/en-US/changelogs/52.txt

@@ -0,0 +1,2 @@
+New package ID (com.collotsspot.ensemble) - reinstall required.
+Prepares for F-Droid and Play Store submission.

fastlane/metadata/android/en-US/changelogs/53.txt

@@ -0,0 +1 @@
+Add fastlane metadata for F-Droid.

fastlane/metadata/android/en-US/changelogs/54.txt

@@ -0,0 +1 @@
+Disable dependency metadata in APK for F-Droid compliance.

fastlane/metadata/android/en-US/full_description.txt

@@ -0,0 +1,13 @@
+Ensemble is an unofficial, community-built mobile client for Music Assistant, providing both local playback and remote control of your music library.
+
+Features:
+* Stream music directly to your phone with background playback
+* Control any speaker or device connected to Music Assistant
+* Multi-room grouping capabilities
+* Queue management with drag-to-reorder
+* Background playback with media notifications
+* Fast ~300ms response for play/pause controls
+
+Ensemble supports both local playback (streaming to your phone) and remote control of any Music Assistant player in your home.
+
+Note: Requires a running Music Assistant server. This is a community project and is not affiliated with the official Music Assistant team.

fastlane/metadata/android/en-US/short_description.txt

@@ -0,0 +1 @@
+Unofficial mobile client for Music Assistant

fastlane/metadata/android/en-US/title.txt

@@ -0,0 +1 @@
+Ensemble

l10n.yaml

@@ -0,0 +1,5 @@
+arb-dir: lib/l10n
+template-arb-file: app_en.arb
+output-localization-file: app_localizations.dart
+synthetic-package: false
+output-class: S

lib/constants/hero_tags.dart

@@ -25,4 +25,28 @@ class HeroTags {
 
   /// Audiobook author image hero tag prefix
   static const String authorImage = 'author_image_';
+
+  /// Podcast cover hero tag prefix
+  static const String podcastCover = 'podcast_cover_';
+
+  /// Podcast title hero tag prefix
+  static const String podcastTitle = 'podcast_title_';
+
+  /// Podcast episode cover hero tag prefix
+  static const String podcastEpisodeCover = 'podcast_episode_cover_';
+
+  /// Podcast episode title hero tag prefix
+  static const String podcastEpisodeTitle = 'podcast_episode_title_';
+
+  /// Playlist cover hero tag prefix
+  static const String playlistCover = 'playlist_cover_';
+
+  /// Playlist title hero tag prefix
+  static const String playlistTitle = 'playlist_title_';
+
+  /// Radio station cover hero tag prefix
+  static const String radioCover = 'radio_cover_';
+
+  /// Radio station title hero tag prefix
+  static const String radioTitle = 'radio_title_';
 }

lib/constants/network.dart

@@ -10,4 +10,7 @@ class NetworkConstants {
 
   /// Default HTTP port
   static const int defaultHttpPort = 80;
+
+  /// Maximum number of pending WebSocket requests to prevent memory leaks
+  static const int maxPendingRequests = 100;
 }

lib/constants/timings.dart

@@ -31,6 +31,9 @@ class Timings {
   /// Search debounce delay
   static const Duration searchDebounce = Duration(milliseconds: 500);
 
+  /// Navigation debounce to prevent double-tap navigation
+  static const Duration navigationDebounce = Duration(milliseconds: 500);
+
   /// Delay after track change before updating state
   static const Duration trackChangeDelay = Duration(milliseconds: 500);
 }

lib/database/database.dart

@@ -25,6 +25,8 @@ class Profiles extends Table {
 }
 
 /// Recently played items - scoped by profile
+@TableIndex(name: 'idx_recently_played_profile', columns: {#profileUsername})
+@TableIndex(name: 'idx_recently_played_profile_played', columns: {#profileUsername, #playedAt})
 class RecentlyPlayed extends Table {
   /// Auto-incrementing ID
   IntColumn get id => integer().autoIncrement()();
@@ -55,6 +57,8 @@ class RecentlyPlayed extends Table {
 }
 
 /// Cached library items for fast startup
+@TableIndex(name: 'idx_library_cache_type', columns: {#itemType})
+@TableIndex(name: 'idx_library_cache_type_deleted', columns: {#itemType, #isDeleted})
 class LibraryCache extends Table {
   /// Composite key: provider + item_id
   TextColumn get cacheKey => text()();
@@ -74,6 +78,10 @@ class LibraryCache extends Table {
   /// Whether this item was deleted on the server
   BoolColumn get isDeleted => boolean().withDefault(const Constant(false))();
 
+  /// Provider instance IDs that provided this item (JSON array)
+  /// Used for client-side filtering by source provider
+  TextColumn get sourceProviders => text().withDefault(const Constant('[]'))();
+
   @override
   Set<Column> get primaryKey => {cacheKey};
 }
@@ -93,12 +101,126 @@ class SyncMetadata extends Table {
   Set<Column> get primaryKey => {syncType};
 }
 
-@DriftDatabase(tables: [Profiles, RecentlyPlayed, LibraryCache, SyncMetadata])
+/// Persisted playback state - survives app restarts and disconnects
+class PlaybackState extends Table {
+  /// Always 'current' - single row table
+  TextColumn get id => text().withDefault(const Constant('current'))();
+
+  /// Selected player ID
+  TextColumn get playerId => text().nullable()();
+
+  /// Selected player name (for display if player unavailable)
+  TextColumn get playerName => text().nullable()();
+
+  /// Current track as JSON
+  TextColumn get currentTrackJson => text().nullable()();
+
+  /// Current position in seconds
+  RealColumn get positionSeconds => real().withDefault(const Constant(0.0))();
+
+  /// Whether playback was active
+  BoolColumn get isPlaying => boolean().withDefault(const Constant(false))();
+
+  /// When this state was saved
+  DateTimeColumn get savedAt => dateTime()();
+
+  @override
+  Set<Column> get primaryKey => {id};
+}
+
+/// Cached player list - for instant display on app resume
+class CachedPlayers extends Table {
+  /// Player ID from Music Assistant
+  TextColumn get playerId => text()();
+
+  /// Player data as JSON
+  TextColumn get playerJson => text()();
+
+  /// Current track for this player as JSON (for mini player display)
+  TextColumn get currentTrackJson => text().nullable()();
+
+  /// When this was last updated
+  DateTimeColumn get lastUpdated => dateTime()();
+
+  @override
+  Set<Column> get primaryKey => {playerId};
+}
+
+/// Cached queue items for selected player
+@TableIndex(name: 'idx_cached_queue_player', columns: {#playerId})
+@TableIndex(name: 'idx_cached_queue_player_position', columns: {#playerId, #position})
+class CachedQueue extends Table {
+  /// Auto-incrementing ID for ordering
+  IntColumn get id => integer().autoIncrement()();
+
+  /// Player ID this queue belongs to
+  TextColumn get playerId => text()();
+
+  /// Queue item as JSON
+  TextColumn get itemJson => text()();
+
+  /// Position in queue
+  IntColumn get position => integer()();
+}
+
+/// Cached home row data for instant display on startup
+class HomeRowCache extends Table {
+  /// Row type: 'recent_albums', 'discover_artists', 'discover_albums'
+  TextColumn get rowType => text()();
+
+  /// Serialized list of items as JSON array
+  TextColumn get itemsJson => text()();
+
+  /// When this was last updated
+  DateTimeColumn get lastUpdated => dateTime()();
+
+  @override
+  Set<Column> get primaryKey => {rowType};
+}
+
+/// Search history for quick access to recent searches
+class SearchHistory extends Table {
+  /// Auto-incrementing ID
+  IntColumn get id => integer().autoIncrement()();
+
+  /// The search query
+  TextColumn get query => text()();
+
+  /// When the search was performed
+  DateTimeColumn get searchedAt => dateTime()();
+}
+
+/// Cached detail tracks for album/playlist detail screens
+/// Persists across app restarts so detail screens load instantly
+class DetailTrackCache extends Table {
+  /// Composite key: "{parentType}_{parentKey}"
+  TextColumn get cacheKey => text()();
+
+  /// Type: 'album' or 'playlist'
+  TextColumn get parentType => text()();
+
+  /// The parent item's cache key (e.g., "provider_itemId")
+  TextColumn get parentKey => text()();
+
+  /// Serialized list of tracks as JSON array
+  TextColumn get tracksJson => text()();
+
+  /// When this was fetched from API
+  DateTimeColumn get lastFetched => dateTime()();
+
+  /// When this was last accessed (for LRU eviction)
+  DateTimeColumn get lastAccessed => dateTime()();
+
+  @override
+  Set<Column> get primaryKey => {cacheKey};
+}
+
+@DriftDatabase(tables: [Profiles, RecentlyPlayed, LibraryCache, SyncMetadata, PlaybackState, CachedPlayers, CachedQueue, HomeRowCache, SearchHistory, DetailTrackCache])
 class AppDatabase extends _$AppDatabase {
   AppDatabase([QueryExecutor? executor]) : super(executor ?? _openConnection());
 
   @override
-  int get schemaVersion => 1;
+  int get schemaVersion => 7;
 
   @override
   MigrationStrategy get migration {
@@ -107,7 +229,40 @@ class AppDatabase extends _$AppDatabase {
         await m.createAll();
       },
       onUpgrade: (Migrator m, int from, int to) async {
-        // Future migrations will go here
+        // Migration from v1 to v2: Add playback state, cached players, cached queue tables
+        if (from < 2) {
+          await m.createTable(playbackState);
+          await m.createTable(cachedPlayers);
+          await m.createTable(cachedQueue);
+        }
+        // Migration from v2 to v3: Add home row cache table
+        if (from < 3) {
+          await m.createTable(homeRowCache);
+        }
+        // Migration from v3 to v4: Add search history table
+        if (from < 4) {
+          await m.createTable(searchHistory);
+        }
+        // Migration from v4 to v5: Add indexes for query performance
+        if (from < 5) {
+          // RecentlyPlayed indexes
+          await customStatement('CREATE INDEX IF NOT EXISTS idx_recently_played_profile ON recently_played (profile_username)');
+          await customStatement('CREATE INDEX IF NOT EXISTS idx_recently_played_profile_played ON recently_played (profile_username, played_at)');
+          // LibraryCache indexes
+          await customStatement('CREATE INDEX IF NOT EXISTS idx_library_cache_type ON library_cache (item_type)');
+          await customStatement('CREATE INDEX IF NOT EXISTS idx_library_cache_type_deleted ON library_cache (item_type, is_deleted)');
+          // CachedQueue indexes
+          await customStatement('CREATE INDEX IF NOT EXISTS idx_cached_queue_player ON cached_queue (player_id)');
+          await customStatement('CREATE INDEX IF NOT EXISTS idx_cached_queue_player_position ON cached_queue (player_id, position)');
+        }
+        // Migration from v5 to v6: Add source_providers column for client-side filtering
+        if (from < 6) {
+          await customStatement("ALTER TABLE library_cache ADD COLUMN source_providers TEXT NOT NULL DEFAULT '[]'");
+        }
+        // Migration from v6 to v7: Add detail track cache table
+        if (from < 7) {
+          await m.createTable(detailTrackCache);
+        }
       },
     );
   }
@@ -250,20 +405,57 @@ class AppDatabase extends _$AppDatabase {
   // ============================================
 
   /// Cache a library item
+  /// [sourceProvider] - the provider instance ID that provided this item (for filtering)
   Future<void> cacheItem({
     required String itemType,
     required String itemId,
     required String data,
+    String? sourceProvider,
   }) async {
     final cacheKey = '${itemType}_$itemId';
 
-    await into(libraryCache).insertOnConflictUpdate(LibraryCacheCompanion.insert(
-      cacheKey: cacheKey,
-      itemType: itemType,
-      itemId: itemId,
-      data: data,
-      lastSynced: DateTime.now(),
-    ));
+    // If sourceProvider is specified, we need to merge with existing providers
+    if (sourceProvider != null) {
+      final existing = await getCachedItem(itemType, itemId);
+      List<String> providers = [];
+      if (existing != null) {
+        try {
+          final existingProviders = existing.sourceProviders;
+          if (existingProviders.isNotEmpty && existingProviders != '[]') {
+            providers = List<String>.from(
+              (await Future.value(existingProviders))
+                  .replaceAll('[', '')
+                  .replaceAll(']', '')
+                  .replaceAll('"', '')
+                  .split(',')
+                  .where((s) => s.trim().isNotEmpty)
+                  .map((s) => s.trim()),
+            );
+          }
+        } catch (_) {}
+      }
+      if (!providers.contains(sourceProvider)) {
+        providers.add(sourceProvider);
+      }
+      final sourceProvidersJson = '[${providers.map((p) => '"$p"').join(',')}]';
+
+      await into(libraryCache).insertOnConflictUpdate(LibraryCacheCompanion.insert(
+        cacheKey: cacheKey,
+        itemType: itemType,
+        itemId: itemId,
+        data: data,
+        lastSynced: DateTime.now(),
+        sourceProviders: Value(sourceProvidersJson),
+      ));
+    } else {
+      await into(libraryCache).insertOnConflictUpdate(LibraryCacheCompanion.insert(
+        cacheKey: cacheKey,
+        itemType: itemType,
+        itemId: itemId,
+        data: data,
+        lastSynced: DateTime.now(),
+      ));
+    }
   }
 
   /// Get cached items by type
@@ -327,4 +519,331 @@ class AppDatabase extends _$AppDatabase {
     if (lastSync == null) return true;
     return DateTime.now().difference(lastSync) > maxAge;
   }
+
+  // ============================================
+  // Playback State Operations
+  // ============================================
+
+  /// Save current playback state
+  Future<void> savePlaybackState({
+    String? playerId,
+    String? playerName,
+    String? currentTrackJson,
+    double positionSeconds = 0.0,
+    bool isPlaying = false,
+  }) async {
+    await into(playbackState).insertOnConflictUpdate(PlaybackStateCompanion.insert(
+      id: const Value('current'),
+      playerId: Value(playerId),
+      playerName: Value(playerName),
+      currentTrackJson: Value(currentTrackJson),
+      positionSeconds: Value(positionSeconds),
+      isPlaying: Value(isPlaying),
+      savedAt: DateTime.now(),
+    ));
+  }
+
+  /// Get saved playback state
+  Future<PlaybackStateData?> getPlaybackState() async {
+    return (select(playbackState)..where((p) => p.id.equals('current')))
+        .getSingleOrNull();
+  }
+
+  /// Clear playback state
+  Future<void> clearPlaybackState() async {
+    await delete(playbackState).go();
+  }
+
+  // ============================================
+  // Cached Players Operations
+  // ============================================
+
+  /// Cache a player with its current track
+  Future<void> cachePlayer({
+    required String playerId,
+    required String playerJson,
+    String? currentTrackJson,
+  }) async {
+    await into(cachedPlayers).insertOnConflictUpdate(CachedPlayersCompanion.insert(
+      playerId: playerId,
+      playerJson: playerJson,
+      currentTrackJson: Value(currentTrackJson),
+      lastUpdated: DateTime.now(),
+    ));
+  }
+
+  /// Cache multiple players at once
+  Future<void> cachePlayers(List<Map<String, dynamic>> players) async {
+    await transaction(() async {
+      for (final player in players) {
+        await into(cachedPlayers).insertOnConflictUpdate(CachedPlayersCompanion.insert(
+          playerId: player['playerId'] as String,
+          playerJson: player['playerJson'] as String,
+          currentTrackJson: Value(player['currentTrackJson'] as String?),
+          lastUpdated: DateTime.now(),
+        ));
+      }
+    });
+  }
+
+  /// Get all cached players
+  Future<List<CachedPlayer>> getCachedPlayers() async {
+    return (select(cachedPlayers)
+      ..orderBy([(p) => OrderingTerm.desc(p.lastUpdated)]))
+      .get();
+  }
+
+  /// Get a specific cached player
+  Future<CachedPlayer?> getCachedPlayer(String playerId) async {
+    return (select(cachedPlayers)..where((p) => p.playerId.equals(playerId)))
+        .getSingleOrNull();
+  }
+
+  /// Update cached track for a player
+  Future<void> updateCachedPlayerTrack(String playerId, String? trackJson) async {
+    await (update(cachedPlayers)..where((p) => p.playerId.equals(playerId)))
+        .write(CachedPlayersCompanion(
+          currentTrackJson: Value(trackJson),
+          lastUpdated: Value(DateTime.now()),
+        ));
+  }
+
+  /// Clear all cached players
+  Future<void> clearCachedPlayers() async {
+    await delete(cachedPlayers).go();
+  }
+
+  // ============================================
+  // Cached Queue Operations
+  // ============================================
+
+  /// Save queue for a player
+  Future<void> saveQueue(String playerId, List<String> itemJsonList) async {
+    await transaction(() async {
+      // Clear existing queue for this player
+      await (delete(cachedQueue)..where((q) => q.playerId.equals(playerId))).go();
+
+      // Insert new queue items
+      for (var i = 0; i < itemJsonList.length; i++) {
+        await into(cachedQueue).insert(CachedQueueCompanion.insert(
+          playerId: playerId,
+          itemJson: itemJsonList[i],
+          position: i,
+        ));
+      }
+    });
+  }
+
+  /// Get cached queue for a player
+  Future<List<CachedQueueData>> getCachedQueue(String playerId) async {
+    return (select(cachedQueue)
+      ..where((q) => q.playerId.equals(playerId))
+      ..orderBy([(q) => OrderingTerm.asc(q.position)]))
+      .get();
+  }
+
+  /// Clear queue for a player
+  Future<void> clearCachedQueue(String playerId) async {
+    await (delete(cachedQueue)..where((q) => q.playerId.equals(playerId))).go();
+  }
+
+  /// Clear all cached queues
+  Future<void> clearAllCachedQueues() async {
+    await delete(cachedQueue).go();
+  }
+
+  // ============================================
+  // Home Row Cache Operations
+  // ============================================
+
+  /// Save home row data
+  Future<void> saveHomeRowCache(String rowType, String itemsJson) async {
+    await into(homeRowCache).insertOnConflictUpdate(
+      HomeRowCacheCompanion(
+        rowType: Value(rowType),
+        itemsJson: Value(itemsJson),
+        lastUpdated: Value(DateTime.now()),
+      ),
+    );
+  }
+
+  /// Get cached home row data
+  Future<HomeRowCacheData?> getHomeRowCache(String rowType) async {
+    return (select(homeRowCache)..where((h) => h.rowType.equals(rowType)))
+        .getSingleOrNull();
+  }
+
+  /// Clear all home row cache
+  Future<void> clearHomeRowCache() async {
+    await delete(homeRowCache).go();
+  }
+
+  // ============================================
+  // Search History Operations
+  // ============================================
+
+  /// Save a search query to history (deduplicates and limits to 10)
+  Future<void> saveSearchQuery(String query) async {
+    final trimmedQuery = query.trim();
+    if (trimmedQuery.isEmpty) return;
+
+    await transaction(() async {
+      // Delete existing entry with same query (case-insensitive)
+      await (delete(searchHistory)
+            ..where((s) => s.query.lower().equals(trimmedQuery.toLowerCase())))
+          .go();
+
+      // Insert the new search
+      await into(searchHistory).insert(SearchHistoryCompanion.insert(
+        query: trimmedQuery,
+        searchedAt: DateTime.now(),
+      ));
+
+      // Keep only the 10 most recent searches
+      final allSearches = await (select(searchHistory)
+            ..orderBy([(s) => OrderingTerm.desc(s.searchedAt)]))
+          .get();
+
+      if (allSearches.length > 10) {
+        final toDelete = allSearches.skip(10).map((s) => s.id).toList();
+        await (delete(searchHistory)..where((s) => s.id.isIn(toDelete))).go();
+      }
+    });
+  }
+
+  /// Get recent search queries (up to 10, most recent first)
+  Future<List<String>> getRecentSearches() async {
+    final searches = await (select(searchHistory)
+          ..orderBy([(s) => OrderingTerm.desc(s.searchedAt)])
+          ..limit(10))
+        .get();
+    return searches.map((s) => s.query).toList();
+  }
+
+  /// Clear all search history
+  Future<void> clearSearchHistory() async {
+    await delete(searchHistory).go();
+  }
+
+  // ============================================
+  // Detail Track Cache Operations
+  // ============================================
+
+  /// Save detail tracks for an album or playlist
+  Future<void> saveDetailTracks(String parentType, String parentKey, String tracksJson) async {
+    final cacheKey = '${parentType}_$parentKey';
+    final now = DateTime.now();
+    await into(detailTrackCache).insertOnConflictUpdate(
+      DetailTrackCacheCompanion.insert(
+        cacheKey: cacheKey,
+        parentType: parentType,
+        parentKey: parentKey,
+        tracksJson: tracksJson,
+        lastFetched: now,
+        lastAccessed: now,
+      ),
+    );
+    // Evict old entries if cache grows too large
+    await _evictDetailTrackCache();
+  }
+
+  /// Get cached detail tracks for an album or playlist
+  /// Returns null if not cached, updates lastAccessed on hit
+  Future<DetailTrackCacheData?> getDetailTracks(String parentType, String parentKey) async {
+    final cacheKey = '${parentType}_$parentKey';
+    final result = await (select(detailTrackCache)
+      ..where((d) => d.cacheKey.equals(cacheKey)))
+      .getSingleOrNull();
+    if (result != null) {
+      // Update last accessed time
+      await (update(detailTrackCache)..where((d) => d.cacheKey.equals(cacheKey)))
+          .write(DetailTrackCacheCompanion(lastAccessed: Value(DateTime.now())));
+    }
+    return result;
+  }
+
+  /// Evict oldest detail track cache entries when over limit
+  Future<void> _evictDetailTrackCache() async {
+    const maxEntries = 100;
+    final count = await (selectOnly(detailTrackCache)..addColumns([countAll()]))
+        .map((row) => row.read(countAll())!)
+        .getSingle();
+    if (count <= maxEntries) return;
+
+    // Delete oldest by lastAccessed
+    final oldest = await (select(detailTrackCache)
+      ..orderBy([(d) => OrderingTerm.asc(d.lastAccessed)])
+      ..limit(count - maxEntries))
+      .get();
+    for (final entry in oldest) {
+      await (delete(detailTrackCache)..where((d) => d.cacheKey.equals(entry.cacheKey))).go();
+    }
+  }
+
+  /// Clear all detail track cache
+  Future<void> clearDetailTrackCache() async {
+    await delete(detailTrackCache).go();
+  }
+
+  // ============================================
+  // Batch Cache Operations
+  // ============================================
+
+  /// Batch size for chunked inserts to prevent SQLite limits
+  static const int _batchChunkSize = 500;
+
+  /// Batch cache multiple items efficiently using drift batch API
+  /// This is much faster than individual inserts for large datasets.
+  /// Items are chunked into batches of 500 to prevent SQLite variable limits.
+  ///
+  /// [items] - List of items to cache, each containing:
+  ///   - itemType: 'album', 'artist', 'track', 'playlist', 'audiobook', etc.
+  ///   - itemId: the item's ID
+  ///   - data: JSON string of the item
+  ///   - sourceProviders: list of provider instance IDs
+  Future<void> batchCacheItems(List<BatchCacheItem> items) async {
+    if (items.isEmpty) return;
+
+    // Process in chunks to avoid SQLite variable limits
+    for (var i = 0; i < items.length; i += _batchChunkSize) {
+      final chunk = items.skip(i).take(_batchChunkSize).toList();
+
+      await batch((b) {
+        for (final item in chunk) {
+          final cacheKey = '${item.itemType}_${item.itemId}';
+          final sourceProvidersJson = item.sourceProviders.isEmpty
+              ? '[]'
+              : '[${item.sourceProviders.map((p) => '"$p"').join(',')}]';
+
+          b.insert(
+            libraryCache,
+            LibraryCacheCompanion.insert(
+              cacheKey: cacheKey,
+              itemType: item.itemType,
+              itemId: item.itemId,
+              data: item.data,
+              lastSynced: DateTime.now(),
+              sourceProviders: Value(sourceProvidersJson),
+            ),
+            mode: InsertMode.insertOrReplace,
+          );
+        }
+      });
+    }
+  }
+}
+
+/// Data class for batch cache operations
+class BatchCacheItem {
+  final String itemType;
+  final String itemId;
+  final String data;
+  final List<String> sourceProviders;
+
+  const BatchCacheItem({
+    required this.itemType,
+    required this.itemId,
+    required this.data,
+    this.sourceProviders = const [],
+  });
 }

lib/l10n/app_de.arb

@@ -0,0 +1,309 @@
+{
+  "@@locale": "de",
+
+  "appTitle": "Ensemble",
+  "connecting": "Verbinde...",
+  "connected": "Verbunden",
+  "disconnected": "Getrennt",
+
+  "serverAddress": "Serveradresse",
+  "serverAddressHint": "z.B. music.example.com oder 192.168.1.100",
+  "yourName": "Dein Name",
+  "yourFirstName": "Dein Vorname",
+  "portOptional": "Port (Optional)",
+  "portHint": "z.B. 8095 oder leer lassen",
+  "portDescription": "Leer lassen bei Reverse Proxy oder Standardports. 8095 eingeben bei Direktverbindung.",
+
+  "username": "Benutzername",
+  "password": "Passwort",
+  "detectAndConnect": "Erkennen & Verbinden",
+  "connect": "Verbinden",
+  "disconnect": "Trennen",
+
+  "authServerUrlOptional": "Auth-Server URL (Optional)",
+  "authServerUrlHint": "z.B. auth.example.com (wenn abweichend vom Server)",
+  "authServerUrlDescription": "Leer lassen, wenn Authentifizierung auf demselben Server",
+  "detectedAuthType": "Erkannt: {authType}",
+  "serverRequiresAuth": "Dieser Server erfordert Authentifizierung",
+
+  "tailscaleVpnConnection": "Tailscale VPN-Verbindung",
+  "unencryptedConnection": "Unverschlusselte Verbindung",
+  "usingHttpOverTailscale": "HTTP uber Tailscale (verschlusselter Tunnel)",
+  "httpsFailedUsingHttp": "HTTPS fehlgeschlagen, verwende HTTP",
+  "httpNotEncrypted": "HTTP-Verbindung - Daten sind nicht verschlusselt",
+
+  "pleaseEnterServerAddress": "Bitte gib deine Music Assistant Serveradresse ein",
+  "pleaseEnterName": "Bitte gib deinen Namen ein",
+  "pleaseEnterValidPort": "Bitte gib eine gultige Portnummer ein (1-65535)",
+  "pleaseEnterCredentials": "Bitte gib Benutzername und Passwort ein",
+  "authFailed": "Authentifizierung fehlgeschlagen. Bitte uberprufe deine Anmeldedaten.",
+  "maLoginFailed": "Music Assistant Anmeldung fehlgeschlagen. Bitte uberprufe deine Anmeldedaten.",
+  "connectionFailed": "Verbindung zum Server fehlgeschlagen. Bitte uberprufe die Adresse und versuche es erneut.",
+  "detectingAuth": "Erkenne Authentifizierung...",
+  "cannotDetermineAuth": "Authentifizierungsanforderungen konnten nicht ermittelt werden. Bitte uberprufe die Server-URL.",
+
+  "noAuthentication": "Keine Authentifizierung",
+  "httpBasicAuth": "HTTP Basic Auth",
+  "authelia": "Authelia",
+  "musicAssistantLogin": "Music Assistant Anmeldung",
+
+  "pressBackToMinimize": "Erneut drucken zum Minimieren",
+
+  "recentlyPlayed": "Zuletzt gespielt",
+  "discoverArtists": "Kunstler entdecken",
+  "discoverAlbums": "Alben entdecken",
+  "continueListening": "Weiterhoren",
+  "discoverAudiobooks": "Horbücher entdecken",
+  "discoverSeries": "Serien entdecken",
+  "favoriteAlbums": "Lieblingsalben",
+  "favoriteArtists": "Lieblingskünstler",
+  "favoriteTracks": "Lieblingssongs",
+
+  "searchMusic": "Musik suchen...",
+  "searchForContent": "Nach Künstlern, Alben oder Songs suchen",
+  "retry": "Wiederholen",
+  "all": "Alle",
+  "artists": "Künstler",
+  "albums": "Alben",
+  "tracks": "Songs",
+  "playlists": "Wiedergabelisten",
+  "audiobooks": "Hörbücher",
+  "music": "Musik",
+  "radio": "Radio",
+  "stations": "Sender",
+  "selectLibrary": "Bibliothek auswählen",
+  "noRadioStations": "Keine Radiosender",
+  "addRadioStationsHint": "Füge Radiosender in Music Assistant hinzu",
+  "searchFailed": "Suche fehlgeschlagen. Bitte überprüfe deine Verbindung.",
+
+  "queue": "Warteschlange",
+  "playerQueue": "{playerName} Warteschlange",
+  "noPlayerSelected": "Kein Player ausgewählt",
+  "undo": "Rückgängig",
+  "removedItem": "{itemName} entfernt",
+
+  "settings": "Einstellungen",
+  "debugLogs": "Debug-Protokolle",
+  "themeMode": "Design",
+  "light": "Hell",
+  "dark": "Dunkel",
+  "system": "System",
+  "pullToRefresh": "Ziehe zum Aktualisieren der Bibliothek",
+  "viewDebugLogs": "Debug-Protokolle anzeigen",
+
+  "viewAllPlayers": "Alle Player anzeigen",
+  "copyLogs": "Protokolle kopieren",
+  "clearLogs": "Protokolle löschen",
+  "copyList": "Liste kopieren",
+  "close": "Schließen",
+  "allPlayersCount": "Alle Player ({count})",
+  "errorLoadingPlayers": "Fehler beim Laden der Player: {error}",
+  "logsCopied": "Protokolle in Zwischenablage kopiert",
+  "logsCleared": "Protokolle gelöscht",
+  "playerListCopied": "Playerliste in Zwischenablage kopiert!",
+  "noLogsYet": "Noch keine Protokolle",
+  "infoPlus": "Info+",
+  "warnings": "Warnungen",
+  "errors": "Fehler",
+  "showingEntries": "Zeige {filtered} von {total} Einträgen",
+  "thisDevice": "Dieses Gerät",
+  "ghostPlayer": "Geist-Player (Duplikat)",
+  "unavailableCorrupt": "Nicht verfügbar/Beschädigt",
+  "playerId": "ID: {id}",
+  "playerInfo": "Verfügbar: {available} | Anbieter: {provider}",
+  "shareBugReport": "Fehlerbericht teilen",
+  "moreOptions": "Weitere Optionen",
+
+  "failedToUpdateFavorite": "Favorit konnte nicht aktualisiert werden: {error}",
+  "noPlayersAvailable": "Keine Player verfügbar",
+  "albumAddedToQueue": "Album zur Warteschlange hinzugefügt",
+  "tracksAddedToQueue": "Songs zur Warteschlange hinzugefügt",
+  "play": "Abspielen",
+  "noPlayersFound": "Keine Player gefunden",
+
+  "startingRadio": "Starte {name} Radio",
+  "failedToStartRadio": "Radio konnte nicht gestartet werden: {error}",
+  "startingRadioOnPlayer": "Starte {name} Radio auf {playerName}",
+  "addedRadioToQueue": "{name} Radio zur Warteschlange hinzugefügt",
+  "failedToAddToQueue": "Konnte nicht zur Warteschlange hinzufügen: {error}",
+  "radio": "Radio",
+  "inLibrary": "In Bibliothek",
+  "noAlbumsFound": "Keine Alben gefunden",
+
+  "playing": "Spiele {name}",
+  "playingTrack": "Spiele Song",
+  "nowPlaying": "Wird gespielt",
+
+  "markedAsFinished": "{name} als beendet markiert",
+  "failedToMarkFinished": "Konnte nicht als beendet markieren: {error}",
+  "markedAsUnplayed": "{name} als ungespielt markiert",
+  "failedToMarkUnplayed": "Konnte nicht als ungespielt markieren: {error}",
+  "failedToPlay": "Abspielen fehlgeschlagen: {error}",
+  "markAsFinished": "Als beendet markieren",
+  "markAsUnplayed": "Als ungespielt markieren",
+  "byAuthor": "Von {author}",
+
+  "audiobookCount": "{count} Hörbuch/Hörbücher",
+  "loading": "Laden...",
+  "bookCount": "{count} Buch/Bücher",
+  "books": "Bücher",
+
+  "noFavoriteAudiobooks": "Keine Lieblingshörbücher",
+  "tapHeartAudiobook": "Tippe auf das Herz bei einem Hörbuch, um es zu Favoriten hinzuzufügen",
+  "noAudiobooks": "Keine Hörbücher",
+  "addAudiobooksHint": "Füge Hörbücher zu deiner Bibliothek hinzu, um sie hier zu sehen",
+
+  "noFavoriteArtists": "Keine Lieblingskünstler",
+  "tapHeartArtist": "Tippe auf das Herz bei einem Künstler, um ihn zu Favoriten hinzuzufügen",
+  "noFavoriteAlbums": "Keine Lieblingsalben",
+  "tapHeartAlbum": "Tippe auf das Herz bei einem Album, um es zu Favoriten hinzuzufügen",
+  "noFavoritePlaylists": "Keine Lieblings-Wiedergabelisten",
+  "tapHeartPlaylist": "Tippe auf das Herz bei einer Wiedergabeliste, um sie zu Favoriten hinzuzufügen",
+  "noFavoriteTracks": "Keine Lieblingssongs",
+  "longPressTrackHint": "Halte einen Song gedrückt und tippe auf das Herz, um ihn zu Favoriten hinzuzufügen",
+  "loadSeries": "Serien laden",
+
+  "notConnected": "Nicht mit Music Assistant verbunden",
+  "notConnectedTitle": "Nicht verbunden",
+  "connectHint": "Verbinde dich mit deinem Music Assistant Server, um Musik zu hören",
+  "configureServer": "Server konfigurieren",
+
+  "noArtistsFound": "Keine Künstler gefunden",
+  "noTracksFound": "Keine Songs gefunden",
+  "noPlaylistsFound": "Keine Wiedergabelisten gefunden",
+  "queueIsEmpty": "Warteschlange ist leer",
+  "noResultsFound": "Keine Ergebnisse gefunden",
+  "refresh": "Aktualisieren",
+
+  "debugConsole": "Debug-Konsole",
+  "copy": "Kopieren",
+  "clear": "Löschen",
+  "noLogsToCopy": "Keine Protokolle zum Kopieren",
+  "noDebugLogsYet": "Noch keine Debug-Protokolle. Versuche Authentifizierung zu erkennen.",
+  "showDebug": "Debug anzeigen",
+  "hideDebug": "Debug ausblenden",
+
+  "chapters": "Kapitel",
+  "noChapters": "Keine Kapitel",
+  "noChapterInfo": "Dieses Hörbuch hat keine Kapitelinformationen",
+
+  "errorSeeking": "Fehler beim Spulen: {error}",
+  "error": "Fehler: {error}",
+
+  "home": "Start",
+  "library": "Bibliothek",
+
+  "homeScreen": "Startbildschirm",
+  "metadataApis": "Metadaten-APIs",
+  "theme": "Design",
+  "materialYou": "Material You",
+  "adaptiveTheme": "Adaptives Design",
+
+  "language": "Sprache",
+  "english": "Englisch",
+  "german": "Deutsch",
+  "spanish": "Spanisch",
+  "french": "Französisch",
+
+  "noTracksInPlaylist": "Keine Songs in Wiedergabeliste",
+  "sortAlphabetically": "Alphabetisch sortieren",
+  "sortByYear": "Nach Jahr sortieren",
+  "sortBySeriesOrder": "Nach Serienreihenfolge sortieren",
+  "listView": "Listenansicht",
+  "gridView": "Rasteransicht",
+  "noBooksInSeries": "Keine Bücher in dieser Serie gefunden",
+  "artist": "Künstler",
+  "showRecentlyPlayedAlbums": "Kürzlich gespielte Alben anzeigen",
+  "showRandomArtists": "Zufällige Künstler zum Entdecken anzeigen",
+  "showRandomAlbums": "Zufällige Alben zum Entdecken anzeigen",
+  "showAudiobooksInProgress": "Hörbücher in Bearbeitung anzeigen",
+  "showRandomAudiobooks": "Zufällige Hörbücher zum Entdecken anzeigen",
+  "showRandomSeries": "Zufällige Hörbuchserien zum Entdecken anzeigen",
+  "showFavoriteAlbums": "Lieblingsalben anzeigen",
+  "showFavoriteArtists": "Lieblingskünstler anzeigen",
+  "showFavoriteTracks": "Lieblingssongs anzeigen",
+  "extractColorsFromArtwork": "Farben aus Album- und Künstlercover extrahieren",
+  "chooseHomeScreenRows": "Wähle welche Zeilen auf dem Startbildschirm angezeigt werden",
+  "addedToFavorites": "Zu Favoriten hinzugefügt",
+  "removedFromFavorites": "Aus Favoriten entfernt",
+  "unknown": "Unbekannt",
+  "noUpcomingTracks": "Keine weiteren Songs",
+  "showAll": "Alle anzeigen",
+  "showFavoritesOnly": "Nur Favoriten anzeigen",
+  "changeView": "Ansicht ändern",
+  "authors": "Autoren",
+  "series": "Serien",
+  "shows": "Sendungen",
+  "podcasts": "Podcasts",
+  "podcastSupportComingSoon": "Podcast-Unterstützung kommt bald",
+  "playlist": "Wiedergabeliste",
+  "connectionError": "Verbindungsfehler",
+  "twoColumnGrid": "2-Spalten-Raster",
+  "threeColumnGrid": "3-Spalten-Raster",
+  "fromProviders": "Von Anbietern",
+
+  "resume": "Fortsetzen",
+  "about": "Über",
+  "inProgress": "In Bearbeitung",
+  "narratedBy": "Gesprochen von {narrators}",
+  "unknownNarrator": "Unbekannter Sprecher",
+  "unknownAuthor": "Unbekannter Autor",
+  "loadingChapters": "Lade Kapitel...",
+  "noChapterInfoAvailable": "Keine Kapitelinformationen verfügbar",
+  "percentComplete": "{percent}% abgeschlossen",
+  "theAudioDbApiKey": "TheAudioDB API-Schlüssel",
+  "theAudioDbApiKeyHint": "\"2\" für kostenlosen Zugang oder Premium-Schlüssel",
+  "audiobookLibraries": "Hörbuch-Bibliotheken",
+  "chooseAudiobookLibraries": "Wähle welche Audiobookshelf-Bibliotheken einbezogen werden",
+  "unknownLibrary": "Unbekannte Bibliothek",
+  "noSeriesFound": "Keine Serien gefunden",
+  "ensembleBugReport": "Ensemble Fehlerbericht",
+  "byOwner": "Von {owner}",
+  "noSeriesAvailable": "Keine Serien in deiner Hörbuch-Bibliothek verfügbar.\nZiehe zum Aktualisieren.",
+  "pullToLoadSeries": "Ziehe nach unten um Serien\nvon Music Assistant zu laden",
+
+  "search": "Suche",
+  "metadataApisDescription": "Künstlerbilder werden automatisch von Deezer abgerufen. Füge unten API-Schlüssel für Künstlerbiografien und Albenbeschreibungen hinzu.",
+  "lastFmApiKey": "Last.fm API-Schlüssel",
+  "lastFmApiKeyHint": "Kostenlosen Schlüssel auf last.fm/api holen",
+  "swipeToSwitchDevice": "Wischen um Gerät zu wechseln",
+  "chapterNumber": "Kapitel {number}",
+  "pcmAudio": "PCM-Audio",
+  "playOn": "Abspielen auf...",
+  "addAlbumToQueueOn": "Album zur Warteschlange hinzufügen auf...",
+  "addToQueueOn": "Zur Warteschlange hinzufügen auf...",
+  "startRadioOn": "{name} Radio starten auf...",
+  "book": "Buch",
+  "audiobookSingular": "Hörbuch",
+  "trackCount": "{count} {count, plural, =1{Song} other{Songs}}",
+  "materialYouDescription": "Systemfarben verwenden (Android 12+)",
+  "accentColor": "Akzentfarbe",
+  "players": "Geräte",
+  "preferLocalPlayer": "Lokales Gerät bevorzugen",
+  "preferLocalPlayerDescription": "Dieses Gerät immer zuerst auswählen, wenn verfügbar",
+  "smartSortPlayers": "Intelligente Sortierung",
+  "smartSortPlayersDescription": "Nach Status sortieren (spielt, an, aus) statt alphabetisch",
+  "playerStateUnavailable": "Nicht verfügbar",
+  "playerStateOff": "Aus",
+  "playerStateIdle": "Inaktiv",
+  "playerStateExternalSource": "Externe Quelle",
+  "playerSelected": "Ausgewählt",
+  "actionQueuedForSync": "Wird synchronisiert wenn online",
+  "pendingOfflineActions": "{count} ausstehende Synchronisierung",
+  "hintsAndTips": "Tipps & Hinweise",
+  "showHints": "Hinweise anzeigen",
+  "showHintsDescription": "Hilfreiche Tipps zum Entdecken von Funktionen anzeigen",
+  "pullToSelectPlayers": "Ziehen um Geräte auszuwählen",
+  "holdToSync": "Gedrückt halten zum Sync",
+  "swipeToAdjustVolume": "Wischen für Lautstärke",
+
+  "aboutAndSupport": "Über & Unterstützung",
+  "supportDevelopment": "Entwicklung unterstützen",
+  "ensembleIsUnofficial": "Ensemble ist ein inoffizieller, von der Community erstellter Client. Erwäge, die Entwicklung zu unterstützen.",
+  "sponsorOnGitHub": "Auf GitHub sponsoren",
+  "buyMeAKoFi": "Kauf mir einen Ko-fi",
+  "aboutEnsemble": "Über Ensemble",
+  "version": "Version",
+  "visitGitHubRepo": "GitHub-Repository besuchen",
+  "reportABug": "Einen Fehler melden"
+}

lib/l10n/app_es.arb

@@ -0,0 +1,505 @@
+{
+  "@@locale": "es",
+
+  "appTitle": "Ensemble",
+  "connecting": "Conectando...",
+  "connected": "Conectado",
+  "disconnected": "Desconectado",
+  "serverAddress": "Dirección del servidor",
+  "serverAddressHint": "ej., music.example.com o 192.168.1.100",
+  "yourName": "Tu nombre",
+  "yourFirstName": "Tu nombre de pila",
+  "portOptional": "Puerto (Opcional)",
+  "portHint": "ej., 8095 o dejar en blanco",
+  "portDescription": "Dejar en blanco para proxy inverso o puertos estándar. Introduce 8095 para conexión directa.",
+  "username": "Usuario",
+  "password": "Contraseña",
+  "detectAndConnect": "Detectar y conectar",
+  "connect": "Conectar",
+  "disconnect": "Desconectar",
+  "authServerUrlOptional": "URL del servidor de autenticación (Opcional)",
+  "authServerUrlHint": "ej., auth.example.com (si es diferente del servidor)",
+  "authServerUrlDescription": "Dejar vacío si la autenticación está en el mismo servidor",
+  "detectedAuthType": "Detectado: {authType}",
+  "@detectedAuthType": {
+    "placeholders": {
+      "authType": {
+        "type": "String"
+      }
+    }
+  },
+  "serverRequiresAuth": "Este servidor requiere autenticación",
+  "tailscaleVpnConnection": "Conexión VPN Tailscale",
+  "unencryptedConnection": "Conexión sin cifrar",
+  "usingHttpOverTailscale": "Usando HTTP sobre Tailscale (túnel cifrado)",
+  "httpsFailedUsingHttp": "HTTPS falló, usando HTTP como alternativa",
+  "httpNotEncrypted": "Conexión HTTP - los datos no están cifrados",
+  "pleaseEnterServerAddress": "Por favor, introduce la dirección de tu servidor Music Assistant",
+  "pleaseEnterName": "Por favor, introduce tu nombre",
+  "pleaseEnterValidPort": "Por favor, introduce un número de puerto válido (1-65535)",
+  "pleaseEnterCredentials": "Por favor, introduce usuario y contraseña",
+  "authFailed": "Autenticación fallida. Por favor, verifica tus credenciales.",
+  "maLoginFailed": "Inicio de sesión en Music Assistant fallido. Por favor, verifica tus credenciales.",
+  "connectionFailed": "No se pudo conectar al servidor. Por favor, verifica la dirección e inténtalo de nuevo.",
+  "detectingAuth": "Detectando autenticación...",
+  "cannotDetermineAuth": "No se pueden determinar los requisitos de autenticación. Por favor, verifica la URL del servidor.",
+  "noAuthentication": "Sin autenticación",
+  "httpBasicAuth": "Autenticación HTTP Basic",
+  "authelia": "Authelia",
+  "musicAssistantLogin": "Inicio de sesión de Music Assistant",
+  "pressBackToMinimize": "Presiona atrás de nuevo para minimizar",
+  "recentlyPlayed": "Reproducido recientemente",
+  "discoverArtists": "Descubrir artistas",
+  "discoverAlbums": "Descubrir álbumes",
+  "continueListening": "Continuar escuchando",
+  "discoverAudiobooks": "Descubrir audiolibros",
+  "discoverSeries": "Descubrir series",
+  "favoriteAlbums": "Álbumes favoritos",
+  "favoriteArtists": "Artistas favoritos",
+  "favoriteTracks": "Canciones favoritas",
+  "searchMusic": "Buscar música...",
+  "searchForContent": "Buscar artistas, álbumes o canciones",
+  "retry": "Reintentar",
+  "all": "Todo",
+  "artists": "Artistas",
+  "albums": "Álbumes",
+  "tracks": "Canciones",
+  "playlists": "Listas de reproducción",
+  "audiobooks": "Audiolibros",
+  "music": "Música",
+  "radio": "Radio",
+  "stations": "Emisoras",
+  "selectLibrary": "Seleccionar Biblioteca",
+  "noRadioStations": "No hay emisoras de radio",
+  "addRadioStationsHint": "Añade emisoras de radio en Music Assistant",
+  "searchFailed": "Búsqueda fallida. Por favor, verifica tu conexión.",
+  "queue": "Cola",
+  "playerQueue": "Cola de {playerName}",
+  "@playerQueue": {
+    "placeholders": {
+      "playerName": {
+        "type": "String"
+      }
+    }
+  },
+  "noPlayerSelected": "Ningún reproductor seleccionado",
+  "undo": "Deshacer",
+  "removedItem": "Eliminado {itemName}",
+  "@removedItem": {
+    "placeholders": {
+      "itemName": {
+        "type": "String"
+      }
+    }
+  },
+  "settings": "Ajustes",
+  "debugLogs": "Registros de depuración",
+  "themeMode": "Modo de tema",
+  "light": "Claro",
+  "dark": "Oscuro",
+  "system": "Sistema",
+  "pullToRefresh": "Desliza hacia abajo para actualizar la biblioteca y aplicar los cambios",
+  "viewDebugLogs": "Ver registros de depuración",
+  "viewAllPlayers": "Ver todos los reproductores",
+  "copyLogs": "Copiar registros",
+  "clearLogs": "Borrar registros",
+  "copyList": "Copiar lista",
+  "close": "Cerrar",
+  "allPlayersCount": "Todos los reproductores ({count})",
+  "@allPlayersCount": {
+    "placeholders": {
+      "count": {
+        "type": "int"
+      }
+    }
+  },
+  "errorLoadingPlayers": "Error al cargar reproductores: {error}",
+  "@errorLoadingPlayers": {
+    "placeholders": {
+      "error": {
+        "type": "String"
+      }
+    }
+  },
+  "logsCopied": "Registros copiados al portapapeles",
+  "logsCleared": "Registros borrados",
+  "playerListCopied": "Lista de reproductores copiada al portapapeles",
+  "noLogsYet": "Aún no hay registros",
+  "infoPlus": "Info+",
+  "warnings": "Advertencias",
+  "errors": "Errores",
+  "showingEntries": "Mostrando {filtered} de {total} entradas",
+  "@showingEntries": {
+    "placeholders": {
+      "filtered": {
+        "type": "int"
+      },
+      "total": {
+        "type": "int"
+      }
+    }
+  },
+  "thisDevice": "Este dispositivo",
+  "ghostPlayer": "Reproductor fantasma (duplicado)",
+  "unavailableCorrupt": "No disponible/Corrupto",
+  "playerId": "ID: {id}",
+  "@playerId": {
+    "placeholders": {
+      "id": {
+        "type": "String"
+      }
+    }
+  },
+  "playerInfo": "Disponible: {available} | Proveedor: {provider}",
+  "@playerInfo": {
+    "placeholders": {
+      "available": {
+        "type": "String"
+      },
+      "provider": {
+        "type": "String"
+      }
+    }
+  },
+  "shareBugReport": "Compartir informe de errores",
+  "moreOptions": "Más opciones",
+  "failedToUpdateFavorite": "Error al actualizar favorito: {error}",
+  "@failedToUpdateFavorite": {
+    "placeholders": {
+      "error": {
+        "type": "String"
+      }
+    }
+  },
+  "noPlayersAvailable": "No hay reproductores disponibles",
+  "albumAddedToQueue": "Álbum añadido a la cola",
+  "tracksAddedToQueue": "Canciones añadidas a la cola",
+  "play": "Reproducir",
+  "noPlayersFound": "No se encontraron reproductores",
+  "startingRadio": "Iniciando radio de {name}",
+  "@startingRadio": {
+    "placeholders": {
+      "name": {
+        "type": "String"
+      }
+    }
+  },
+  "failedToStartRadio": "Error al iniciar radio: {error}",
+  "@failedToStartRadio": {
+    "placeholders": {
+      "error": {
+        "type": "String"
+      }
+    }
+  },
+  "startingRadioOnPlayer": "Iniciando radio de {name} en {playerName}",
+  "@startingRadioOnPlayer": {
+    "placeholders": {
+      "name": {
+        "type": "String"
+      },
+      "playerName": {
+        "type": "String"
+      }
+    }
+  },
+  "addedRadioToQueue": "Radio de {name} añadida a la cola",
+  "@addedRadioToQueue": {
+    "placeholders": {
+      "name": {
+        "type": "String"
+      }
+    }
+  },
+  "failedToAddToQueue": "Error al añadir a la cola: {error}",
+  "@failedToAddToQueue": {
+    "placeholders": {
+      "error": {
+        "type": "String"
+      }
+    }
+  },
+  "radio": "Radio",
+  "inLibrary": "En la biblioteca",
+  "noAlbumsFound": "No se encontraron álbumes",
+  "playing": "Reproduciendo {name}",
+  "@playing": {
+    "placeholders": {
+      "name": {
+        "type": "String"
+      }
+    }
+  },
+  "playingTrack": "Reproduciendo canción",
+  "nowPlaying": "Reproduciendo ahora",
+  "markedAsFinished": "{name} marcado como terminado",
+  "@markedAsFinished": {
+    "placeholders": {
+      "name": {
+        "type": "String"
+      }
+    }
+  },
+  "failedToMarkFinished": "Error al marcar como terminado: {error}",
+  "@failedToMarkFinished": {
+    "placeholders": {
+      "error": {
+        "type": "String"
+      }
+    }
+  },
+  "markedAsUnplayed": "{name} marcado como no reproducido",
+  "@markedAsUnplayed": {
+    "placeholders": {
+      "name": {
+        "type": "String"
+      }
+    }
+  },
+  "failedToMarkUnplayed": "Error al marcar como no reproducido: {error}",
+  "@failedToMarkUnplayed": {
+    "placeholders": {
+      "error": {
+        "type": "String"
+      }
+    }
+  },
+  "failedToPlay": "Error al reproducir: {error}",
+  "@failedToPlay": {
+    "placeholders": {
+      "error": {
+        "type": "String"
+      }
+    }
+  },
+  "markAsFinished": "Marcar como terminado",
+  "markAsUnplayed": "Marcar como no reproducido",
+  "byAuthor": "Por {author}",
+  "@byAuthor": {
+    "placeholders": {
+      "author": {
+        "type": "String"
+      }
+    }
+  },
+  "audiobookCount": "{count} audiolibro(s)",
+  "@audiobookCount": {
+    "placeholders": {
+      "count": {
+        "type": "int"
+      }
+    }
+  },
+  "loading": "Cargando...",
+  "bookCount": "{count} libro(s)",
+  "@bookCount": {
+    "placeholders": {
+      "count": {
+        "type": "int"
+      }
+    }
+  },
+  "books": "Libros",
+  "noFavoriteAudiobooks": "No hay audiolibros favoritos",
+  "tapHeartAudiobook": "Toca el corazón en un audiolibro para añadirlo a favoritos",
+  "noAudiobooks": "No hay audiolibros",
+  "addAudiobooksHint": "Añade audiolibros a tu biblioteca para verlos aquí",
+  "noFavoriteArtists": "No hay artistas favoritos",
+  "tapHeartArtist": "Toca el corazón en un artista para añadirlo a favoritos",
+  "noFavoriteAlbums": "No hay álbumes favoritos",
+  "tapHeartAlbum": "Toca el corazón en un álbum para añadirlo a favoritos",
+  "noFavoritePlaylists": "No hay listas de reproducción favoritas",
+  "tapHeartPlaylist": "Toca el corazón en una lista para añadirla a favoritos",
+  "noFavoriteTracks": "No hay canciones favoritas",
+  "longPressTrackHint": "Mantén presionada una canción y toca el corazón para añadirla a favoritos",
+  "loadSeries": "Cargar series",
+  "notConnected": "No conectado a Music Assistant",
+  "notConnectedTitle": "No conectado",
+  "connectHint": "Conéctate a tu servidor Music Assistant para empezar a escuchar",
+  "configureServer": "Configurar servidor",
+  "noArtistsFound": "No se encontraron artistas",
+  "noTracksFound": "No se encontraron canciones",
+  "noPlaylistsFound": "No se encontraron listas de reproducción",
+  "queueIsEmpty": "La cola está vacía",
+  "noResultsFound": "No se encontraron resultados",
+  "refresh": "Actualizar",
+  "debugConsole": "Consola de depuración",
+  "copy": "Copiar",
+  "clear": "Borrar",
+  "noLogsToCopy": "No hay registros para copiar",
+  "noDebugLogsYet": "Aún no hay registros de depuración. Intenta detectar autenticación.",
+  "showDebug": "Mostrar depuración",
+  "hideDebug": "Ocultar depuración",
+  "chapters": "Capítulos",
+  "noChapters": "Sin capítulos",
+  "noChapterInfo": "Este audiolibro no tiene información de capítulos",
+  "errorSeeking": "Error al buscar: {error}",
+  "@errorSeeking": {
+    "placeholders": {
+      "error": {
+        "type": "String"
+      }
+    }
+  },
+  "error": "Error: {error}",
+  "@error": {
+    "placeholders": {
+      "error": {
+        "type": "String"
+      }
+    }
+  },
+  "home": "Inicio",
+  "library": "Biblioteca",
+  "homeScreen": "Pantalla de inicio",
+  "metadataApis": "APIs de metadatos",
+  "theme": "Tema",
+  "materialYou": "Material You",
+  "adaptiveTheme": "Tema adaptativo",
+  "language": "Idioma",
+  "english": "Inglés",
+  "german": "Alemán",
+  "spanish": "Español",
+  "french": "Francés",
+  "noTracksInPlaylist": "No hay canciones en la lista",
+  "sortAlphabetically": "Ordenar alfabéticamente",
+  "sortByYear": "Ordenar por año",
+  "sortBySeriesOrder": "Ordenar por orden de serie",
+  "listView": "Vista de lista",
+  "gridView": "Vista de cuadrícula",
+  "noBooksInSeries": "No se encontraron libros en esta serie",
+  "artist": "Artista",
+  "showRecentlyPlayedAlbums": "Mostrar álbumes reproducidos recientemente",
+  "showRandomArtists": "Mostrar artistas aleatorios para descubrir",
+  "showRandomAlbums": "Mostrar álbumes aleatorios para descubrir",
+  "showAudiobooksInProgress": "Mostrar audiolibros en progreso",
+  "showRandomAudiobooks": "Mostrar audiolibros aleatorios para descubrir",
+  "showRandomSeries": "Mostrar series de audiolibros aleatorias para descubrir",
+  "showFavoriteAlbums": "Mostrar una fila de tus álbumes favoritos",
+  "showFavoriteArtists": "Mostrar una fila de tus artistas favoritos",
+  "showFavoriteTracks": "Mostrar una fila de tus canciones favoritas",
+  "extractColorsFromArtwork": "Extraer colores de las portadas de álbumes y artistas",
+  "chooseHomeScreenRows": "Elige qué filas mostrar en la pantalla de inicio",
+  "addedToFavorites": "Añadido a favoritos",
+  "removedFromFavorites": "Eliminado de favoritos",
+  "unknown": "Desconocido",
+  "noUpcomingTracks": "No hay canciones próximas",
+  "showAll": "Mostrar todo",
+  "showFavoritesOnly": "Mostrar solo favoritos",
+  "changeView": "Cambiar vista",
+  "authors": "Autores",
+  "series": "Series",
+  "shows": "Programas",
+  "podcasts": "Podcasts",
+  "podcastSupportComingSoon": "Soporte de podcasts próximamente",
+  "playlist": "Lista de reproducción",
+  "connectionError": "Error de conexión",
+  "twoColumnGrid": "Cuadrícula de 2 columnas",
+  "threeColumnGrid": "Cuadrícula de 3 columnas",
+  "fromProviders": "De proveedores",
+  "resume": "Continuar",
+  "about": "Acerca de",
+  "inProgress": "En progreso",
+  "narratedBy": "Narrado por {narrators}",
+  "@narratedBy": {
+    "placeholders": {
+      "narrators": {
+        "type": "String"
+      }
+    }
+  },
+  "unknownNarrator": "Narrador desconocido",
+  "unknownAuthor": "Autor desconocido",
+  "loadingChapters": "Cargando capítulos...",
+  "noChapterInfoAvailable": "No hay información de capítulos disponible",
+  "percentComplete": "{percent}% completado",
+  "@percentComplete": {
+    "placeholders": {
+      "percent": {
+        "type": "int"
+      }
+    }
+  },
+  "theAudioDbApiKey": "Clave API de TheAudioDB",
+  "theAudioDbApiKeyHint": "Usa \"2\" para nivel gratuito o clave premium",
+  "audiobookLibraries": "Bibliotecas de audiolibros",
+  "chooseAudiobookLibraries": "Elige qué bibliotecas de Audiobookshelf incluir",
+  "unknownLibrary": "Biblioteca desconocida",
+  "noSeriesFound": "No se encontraron series",
+  "ensembleBugReport": "Informe de errores de Ensemble",
+  "byOwner": "Por {owner}",
+  "@byOwner": {
+    "placeholders": {
+      "owner": {
+        "type": "String"
+      }
+    }
+  },
+  "noSeriesAvailable": "No hay series disponibles en tu biblioteca de audiolibros.\nDesliza para actualizar.",
+  "pullToLoadSeries": "Desliza hacia abajo para cargar series\ndesde Music Assistant",
+  "search": "Buscar",
+  "metadataApisDescription": "Las imágenes de artistas se obtienen automáticamente de Deezer. Añade claves API a continuación para biografías de artistas y descripciones de álbumes.",
+  "lastFmApiKey": "Clave API de Last.fm",
+  "lastFmApiKeyHint": "Obtén una clave gratuita en last.fm/api",
+  "swipeToSwitchDevice": "Desliza para cambiar dispositivo",
+  "chapterNumber": "Capítulo {number}",
+  "@chapterNumber": {
+    "placeholders": {
+      "number": {
+        "type": "int"
+      }
+    }
+  },
+  "pcmAudio": "Audio PCM",
+  "playOn": "Reproducir en...",
+  "addAlbumToQueueOn": "Añadir álbum a la cola en...",
+  "addToQueueOn": "Añadir a la cola en...",
+  "startRadioOn": "Iniciar radio de {name} en...",
+  "@startRadioOn": {
+    "placeholders": {
+      "name": {
+        "type": "String"
+      }
+    }
+  },
+  "book": "libro",
+  "audiobookSingular": "audiolibro",
+  "trackCount": "{count} {count, plural, =1{canción} other{canciones}}",
+  "@trackCount": {
+    "placeholders": {
+      "count": {
+        "type": "int"
+      }
+    }
+  },
+  "materialYouDescription": "Usar colores del sistema (Android 12+)",
+  "accentColor": "Color de acento",
+  "players": "Dispositivos",
+  "preferLocalPlayer": "Preferir dispositivo local",
+  "preferLocalPlayerDescription": "Seleccionar siempre este dispositivo primero cuando esté disponible",
+  "smartSortPlayers": "Orden inteligente",
+  "smartSortPlayersDescription": "Ordenar por estado (reproduciendo, encendido, apagado) en lugar de alfabéticamente",
+  "playerStateUnavailable": "No disponible",
+  "playerStateOff": "Apagado",
+  "playerStateIdle": "Inactivo",
+  "playerStateExternalSource": "Fuente Externa",
+  "playerSelected": "Seleccionado",
+  "actionQueuedForSync": "Se sincronizará cuando esté en línea",
+  "pendingOfflineActions": "{count} sincronización pendiente",
+  "hintsAndTips": "Consejos y Sugerencias",
+  "showHints": "Mostrar Sugerencias",
+  "showHintsDescription": "Mostrar consejos útiles para descubrir funciones",
+  "pullToSelectPlayers": "Desliza para seleccionar dispositivos",
+  "holdToSync": "Mantén presionado para sync",
+  "swipeToAdjustVolume": "Desliza para ajustar volumen",
+
+  "aboutAndSupport": "Acerca de y Soporte",
+  "supportDevelopment": "Apoyar el Desarrollo",
+  "ensembleIsUnofficial": "Ensemble es un cliente no oficial creado por la comunidad. Considera apoyar su desarrollo.",
+  "sponsorOnGitHub": "Patrocina en GitHub",
+  "buyMeAKoFi": "Cómprame un Ko-fi",
+  "aboutEnsemble": "Acerca de Ensemble",
+  "version": "Versión",
+  "visitGitHubRepo": "Visitar Repositorio GitHub",
+  "reportABug": "Reportar un Error"
+}

lib/main.dart

@@ -1,8 +1,12 @@
 import 'dart:async';
+import 'dart:ui';
 import 'package:flutter/material.dart';
 import 'package:flutter/services.dart';
 import 'package:provider/provider.dart';
 import 'package:audio_service/audio_service.dart';
+import 'package:flutter_localizations/flutter_localizations.dart';
+import 'l10n/app_localizations.dart';
+import 'providers/locale_provider.dart';
 import 'providers/music_assistant_provider.dart';
 import 'providers/navigation_provider.dart';
 import 'screens/home_screen.dart';
@@ -27,54 +31,90 @@ late MassivAudioHandler audioHandler;
 // Global debug logger instance
 final _logger = DebugLogger();
 
-Future<void> main() async {
-  WidgetsFlutterBinding.ensureInitialized();
+void main() {
+  // All initialization must run inside the same zone as runApp() to avoid
+  // "Zone mismatch" errors from Flutter's binding system
+  runZonedGuarded(
+    () async {
+      WidgetsFlutterBinding.ensureInitialized();
 
-  // Initialize local database
-  await DatabaseService.instance.initialize();
-  _logger.log('💾 Database initialized');
+      // Initialize SharedPreferences cache early for performance
+      await SettingsService.initialize();
+      _logger.log('⚡ SharedPreferences cached');
 
-  // Migrate existing ownerName to profile (one-time for existing users)
-  await ProfileService.instance.migrateFromOwnerName();
+      // Initialize local database
+      await DatabaseService.instance.initialize();
+      _logger.log('💾 Database initialized');
 
-  // Load library from cache for instant startup
-  await SyncService.instance.loadFromCache();
-  _logger.log('📦 Library cache loaded');
+      // Migrate existing ownerName to profile (one-time for existing users)
+      await ProfileService.instance.migrateFromOwnerName();
 
-  // Create auth manager for streaming headers
-  final authManager = AuthManager();
+      // Migrate credentials to secure storage (one-time for existing users)
+      await SettingsService.migrateToSecureStorage();
+      _logger.log('🔐 Secure storage migration complete');
 
-  // Initialize audio_service with our custom handler
-  audioHandler = await AudioService.init(
-    builder: () => MassivAudioHandler(authManager: authManager),
-    config: const AudioServiceConfig(
-      androidNotificationChannelId: 'io.github.collotsspot.massiv.audio',
-      androidNotificationChannelName: 'Ensemble Audio',
-      androidNotificationOngoing: false,  // Must be false when androidStopForegroundOnPause is false
-      androidNotificationIcon: 'drawable/ic_notification',
-      androidShowNotificationBadge: false,
-      androidStopForegroundOnPause: false,  // Keep service alive when paused for background playback
-    ),
+      // Load library from cache for instant startup
+      await SyncService.instance.loadFromCache();
+      _logger.log('📦 Library cache loaded');
+
+      // Create auth manager for streaming headers
+      final authManager = AuthManager();
+
+      // Initialize audio_service with our custom handler
+      audioHandler = await AudioService.init(
+        builder: () => MassivAudioHandler(authManager: authManager),
+        config: const AudioServiceConfig(
+          androidNotificationChannelId: 'io.github.collotsspot.massiv.audio',
+          androidNotificationChannelName: 'Ensemble Audio',
+          androidNotificationOngoing: false,  // Must be false when androidStopForegroundOnPause is false
+          androidNotificationIcon: 'drawable/ic_notification',
+          androidShowNotificationBadge: false,
+          androidStopForegroundOnPause: false,  // Keep service alive when paused for background playback
+        ),
+      );
+      _logger.log('🎵 AudioService initialized - background playback and media notifications ENABLED');
+
+      // Set preferred orientations
+      SystemChrome.setPreferredOrientations([
+        DeviceOrientation.portraitUp,
+        DeviceOrientation.portraitDown,
+      ]);
+
+      // Set initial system UI overlay style based on platform brightness
+      // SystemUIWrapper will update this dynamically when theme changes
+      final platformBrightness = WidgetsBinding.instance.platformDispatcher.platformBrightness;
+      final isDark = platformBrightness == Brightness.dark;
+      SystemChrome.setSystemUIOverlayStyle(
+        SystemUiOverlayStyle(
+          statusBarColor: Colors.transparent,
+          statusBarIconBrightness: isDark ? Brightness.light : Brightness.dark,
+          systemNavigationBarColor: isDark ? const Color(0xFF1a1a1a) : const Color(0xFFF5F5F5),
+          systemNavigationBarIconBrightness: isDark ? Brightness.light : Brightness.dark,
+        ),
+      );
+
+      // Set up Flutter error boundary to catch and log widget build errors
+      FlutterError.onError = (FlutterErrorDetails details) {
+        _logger.error('Flutter error: ${details.exceptionAsString()}', context: 'FlutterError');
+        _logger.error('Stack trace:\n${details.stack}', context: 'FlutterError');
+        // Still report to Flutter's default handler in debug mode
+        FlutterError.presentError(details);
+      };
+
+      // Catch errors from the platform dispatcher (platform channel errors)
+      PlatformDispatcher.instance.onError = (error, stack) {
+        _logger.error('Platform error: $error', context: 'PlatformDispatcher');
+        _logger.error('Stack trace:\n$stack', context: 'PlatformDispatcher');
+        return true; // Handled
+      };
+
+      runApp(const MusicAssistantApp());
+    },
+    (error, stackTrace) {
+      _logger.error('Uncaught async error: $error', context: 'ZoneError');
+      _logger.error('Stack trace:\n$stackTrace', context: 'ZoneError');
+    },
   );
-  _logger.log('🎵 AudioService initialized - background playback and media notifications ENABLED');
-
-  // Set preferred orientations
-  SystemChrome.setPreferredOrientations([
-    DeviceOrientation.portraitUp,
-    DeviceOrientation.portraitDown,
-  ]);
-
-  // Set system UI overlay style
-  SystemChrome.setSystemUIOverlayStyle(
-    const SystemUiOverlayStyle(
-      statusBarColor: Colors.transparent,
-      statusBarIconBrightness: Brightness.light,
-      systemNavigationBarColor: Color(0xFF1a1a1a),
-      systemNavigationBarIconBrightness: Brightness.light,
-    ),
-  );
-
-  runApp(const MusicAssistantApp());
 }
 
 class MusicAssistantApp extends StatefulWidget {
@@ -87,9 +127,11 @@ class MusicAssistantApp extends StatefulWidget {
 class _MusicAssistantAppState extends State<MusicAssistantApp> with WidgetsBindingObserver {
   late MusicAssistantProvider _musicProvider;
   late ThemeProvider _themeProvider;
+  late LocaleProvider _localeProvider;
   final _hardwareVolumeService = HardwareVolumeService();
   StreamSubscription? _volumeUpSub;
   StreamSubscription? _volumeDownSub;
+  StreamSubscription? _absoluteVolumeSub;
   String? _lastSelectedPlayerId;
   String? _builtinPlayerId;
 
@@ -101,6 +143,8 @@ class _MusicAssistantAppState extends State<MusicAssistantApp> with WidgetsBindi
     super.initState();
     _musicProvider = MusicAssistantProvider();
     _themeProvider = ThemeProvider();
+    _localeProvider = LocaleProvider();
+    audioHandler.setProvider(_musicProvider);
     WidgetsBinding.instance.addObserver(this);
     _initHardwareVolumeControl();
     // Listen to player selection changes to toggle volume interception
@@ -119,6 +163,12 @@ class _MusicAssistantAppState extends State<MusicAssistantApp> with WidgetsBindi
       _volumeDownSub = _hardwareVolumeService.onVolumeDown.listen((_) {
         _adjustVolume(-_volumeStep);
       });
+
+      // Listen for absolute volume changes from lockscreen/background
+      // (ContentObserver on system STREAM_MUSIC volume)
+      _absoluteVolumeSub = _hardwareVolumeService.onAbsoluteVolumeChange.listen((volume) {
+        _setAbsoluteVolume(volume);
+      });
     } catch (e, stack) {
       _logger.error('Hardware volume init failed', context: 'VolumeInit', error: e, stackTrace: stack);
     }
@@ -134,18 +184,41 @@ class _MusicAssistantAppState extends State<MusicAssistantApp> with WidgetsBindi
   }
 
   /// Enable/disable volume button interception based on selected player.
+  /// Also manages the volume observer for lockscreen volume routing.
   Future<void> _updateVolumeInterception() async {
+    final player = _musicProvider.selectedPlayer;
     final isBuiltinPlayer = _builtinPlayerId != null &&
-        _musicProvider.selectedPlayer?.playerId == _builtinPlayerId;
+        player?.playerId == _builtinPlayerId;
     await _hardwareVolumeService.setIntercepting(!isBuiltinPlayer);
+
+    // Start/stop volume observer for lockscreen volume changes.
+    // When a remote/group player is active, observe system volume changes
+    // so lockscreen hardware buttons route to the MA player.
+    if (!isBuiltinPlayer && player != null) {
+      // Get the effective volume to sync the system volume HUD
+      final effectiveVolume = _musicProvider.groupVolumeManager.isGroupPlayer(player)
+          ? (_musicProvider.groupVolumeManager.getEffectiveVolumeLevel(
+                  player, _musicProvider.availablePlayersUnfiltered) ?? player.volume)
+          : player.volume;
+      await _hardwareVolumeService.startVolumeObserver(initialVolume: effectiveVolume);
+    } else {
+      await _hardwareVolumeService.stopVolumeObserver();
+    }
   }
 
   Future<void> _adjustVolume(int delta) async {
     final player = _musicProvider.selectedPlayer;
     if (player == null) return;
 
-    final newVolume = (player.volume + delta).clamp(0, 100);
-    if (newVolume != player.volume) {
+    // Use effective volume for group players (player.volume returns 0
+    // because MA API returns null for group player volume_level)
+    final currentVolume = _musicProvider.groupVolumeManager.isGroupPlayer(player)
+        ? (_musicProvider.groupVolumeManager.getEffectiveVolumeLevel(
+                player, _musicProvider.availablePlayersUnfiltered) ?? player.volume)
+        : player.volume;
+
+    final newVolume = (currentVolume + delta).clamp(0, 100);
+    if (newVolume != currentVolume) {
       try {
         await _musicProvider.setVolume(player.playerId, newVolume);
       } catch (e) {
@@ -154,11 +227,29 @@ class _MusicAssistantAppState extends State<MusicAssistantApp> with WidgetsBindi
     }
   }
 
+  /// Handle absolute volume change from lockscreen/background.
+  /// Called when the ContentObserver detects a system volume change
+  /// while a remote/group player is active.
+  Future<void> _setAbsoluteVolume(int volume) async {
+    final player = _musicProvider.selectedPlayer;
+    if (player == null) return;
+
+    // Don't route to builtin player - that's handled by the system directly
+    if (_builtinPlayerId != null && player.playerId == _builtinPlayerId) return;
+
+    try {
+      await _musicProvider.setVolume(player.playerId, volume.clamp(0, 100));
+    } catch (e) {
+      _logger.error('Lockscreen volume change failed', context: 'VolumeControl', error: e);
+    }
+  }
+
   @override
   void dispose() {
     _musicProvider.removeListener(_onProviderChanged);
     _volumeUpSub?.cancel();
     _volumeDownSub?.cancel();
+    _absoluteVolumeSub?.cancel();
     _hardwareVolumeService.dispose();
     WidgetsBinding.instance.removeObserver(this);
     super.dispose();
@@ -167,11 +258,29 @@ class _MusicAssistantAppState extends State<MusicAssistantApp> with WidgetsBindi
   @override
   Future<bool> didPopRoute() async {
     // Intercept back button at app level - runs BEFORE Navigator processes it
-    // If player is expanded, collapse it and consume the back gesture
-    if (GlobalPlayerOverlay.isPlayerExpanded) {
-      GlobalPlayerOverlay.collapsePlayer();
+    // Priority order: device list > queue panel > expanded player > normal navigation
+
+    // Device list has highest priority - dismiss it first
+    if (GlobalPlayerOverlay.isPlayerRevealVisible) {
+      GlobalPlayerOverlay.dismissPlayerReveal();
       return true; // We handled it, don't let Navigator process it
     }
+
+    // Queue panel second - close it before collapsing player
+    // Use target state (not animation value) to handle rapid open-close timing
+    // Use withHaptic: false because Android back gesture provides system haptic
+    if (GlobalPlayerOverlay.isQueuePanelTargetOpen) {
+      GlobalPlayerOverlay.closeQueuePanel(withHaptic: false);
+      return true; // We handled it, don't let Navigator process it
+    }
+
+    // Then check expanded player
+    // No haptic - Android back gesture provides its own
+    if (GlobalPlayerOverlay.isPlayerExpanded) {
+      GlobalPlayerOverlay.collapsePlayer(withHaptic: false);
+      return true; // We handled it, don't let Navigator process it
+    }
+
     // Let Navigator handle the back gesture normally
     return super.didPopRoute();
   }
@@ -197,9 +306,10 @@ class _MusicAssistantAppState extends State<MusicAssistantApp> with WidgetsBindi
       providers: [
         ChangeNotifierProvider.value(value: _musicProvider),
         ChangeNotifierProvider.value(value: _themeProvider),
+        ChangeNotifierProvider.value(value: _localeProvider),
       ],
-      child: Consumer<ThemeProvider>(
-        builder: (context, themeProvider, _) {
+      child: Consumer2<ThemeProvider, LocaleProvider>(
+        builder: (context, themeProvider, localeProvider, _) {
           return FutureBuilder<(ColorScheme, ColorScheme)?>(
             future: themeProvider.useMaterialTheme
                 ? SystemThemeHelper.getSystemColorSchemes()
@@ -210,14 +320,21 @@ class _MusicAssistantAppState extends State<MusicAssistantApp> with WidgetsBindi
               ColorScheme? darkColorScheme;
 
               if (themeProvider.useMaterialTheme && snapshot.hasData && snapshot.data != null) {
-                // Use system color schemes
+                // Use system color schemes, but override background to match app design
+                // Material You doesn't set background consistently, causing black screen issues
                 final (light, dark) = snapshot.data!;
-                lightColorScheme = light;
-                darkColorScheme = dark;
+                lightColorScheme = light.copyWith(
+                  surface: light.surface,
+                  background: const Color(0xFFFAFAFA), // App's preferred light background
+                );
+                darkColorScheme = dark.copyWith(
+                  surface: const Color(0xFF2a2a2a), // App's preferred dark surface
+                  background: const Color(0xFF1a1a1a), // App's preferred dark background
+                );
               } else {
-                // Use brand color schemes
-                lightColorScheme = brandLightColorScheme;
-                darkColorScheme = brandDarkColorScheme;
+                // Use custom color from theme provider
+                lightColorScheme = generateLightColorScheme(themeProvider.customColor);
+                darkColorScheme = generateDarkColorScheme(themeProvider.customColor);
               }
 
               return SystemUIWrapper(
@@ -228,12 +345,53 @@ class _MusicAssistantAppState extends State<MusicAssistantApp> with WidgetsBindi
                   navigatorKey: navigationProvider.navigatorKey,
                   title: 'Ensemble',
                   debugShowCheckedModeBanner: false,
+                  // Localization
+                  localizationsDelegates: const [
+                    S.delegate,
+                    GlobalMaterialLocalizations.delegate,
+                    GlobalWidgetsLocalizations.delegate,
+                    GlobalCupertinoLocalizations.delegate,
+                  ],
+                  supportedLocales: S.supportedLocales,
+                  locale: localeProvider.locale,
+                  // Fallback to English when locale is not supported
+                  localeListResolutionCallback: (locales, supportedLocales) {
+                    // If user has set a specific locale, try to use it
+                    if (localeProvider.locale != null) {
+                      for (final supported in supportedLocales) {
+                        if (supported.languageCode == localeProvider.locale!.languageCode) {
+                          return supported;
+                        }
+                      }
+                    }
+                    // Try to match system locales
+                    if (locales != null) {
+                      for (final locale in locales) {
+                        for (final supported in supportedLocales) {
+                          if (supported.languageCode == locale.languageCode) {
+                            return supported;
+                          }
+                        }
+                      }
+                    }
+                    // Fallback to English (not German)
+                    return const Locale('en');
+                  },
                   themeMode: themeProvider.themeMode,
                   theme: AppTheme.lightTheme(colorScheme: lightColorScheme),
                   darkTheme: AppTheme.darkTheme(colorScheme: darkColorScheme),
                   builder: (context, child) {
-                    // Wrap entire app with global player overlay
-                    return GlobalPlayerOverlay(child: child ?? const SizedBox.shrink());
+                    // Wrap entire app with global player overlay.
+                    // Provide an Overlay ancestor so BottomNavigationBar/Tooltip can render safely.
+                    return Overlay(
+                      initialEntries: [
+                        OverlayEntry(
+                          builder: (context) => GlobalPlayerOverlay(
+                            child: child ?? const SizedBox.shrink(),
+                          ),
+                        ),
+                      ],
+                    );
                   },
                   home: const AppStartup(),
                 ),
@@ -304,8 +462,8 @@ class _SystemUIWrapperState extends State<SystemUIWrapper> {
           statusBarColor: Colors.transparent,
           statusBarIconBrightness: isDark ? Brightness.light : Brightness.dark,
           systemNavigationBarColor: isDark
-              ? widget.darkColorScheme.background
-              : widget.lightColorScheme.background,
+              ? widget.darkColorScheme.surface
+              : widget.lightColorScheme.surface,
           systemNavigationBarIconBrightness: isDark ? Brightness.light : Brightness.dark,
         ),
       );
@@ -324,7 +482,16 @@ class _SystemUIWrapperState extends State<SystemUIWrapper> {
   }
 }
 
-/// Startup widget that checks if user is logged in and auto-connects
+/// Startup widget that checks if user is logged in and auto-connects.
+///
+/// CRITICAL: This widget is the single source of truth for the startup transition.
+/// It loads settings FIRST (before connection), then waits for the appropriate
+/// conditions before showing HomeScreen. This eliminates the race condition between
+/// AppStartup and GlobalPlayerOverlay that caused the home screen flash.
+///
+/// For first-time users: Holds dark screen until connected + player selected,
+/// so the welcome overlay can appear seamlessly.
+/// For returning users: Transitions as soon as connection is established.
 class AppStartup extends StatefulWidget {
   const AppStartup({super.key});
 
@@ -337,15 +504,41 @@ class _AppStartupState extends State<AppStartup> {
   String? _savedServerUrl;
   bool _connectionAttempted = false;
 
+  // Welcome system state - loaded FIRST before connection check
+  bool _settingsLoaded = false;
+  bool _hasCompletedOnboarding = true; // Default to true (no welcome needed)
+
   @override
   void initState() {
     super.initState();
+    _loadSettingsFirst();
+  }
+
+  /// Load settings BEFORE checking connection.
+  /// This ensures we know if this is a first-time user before transitioning.
+  Future<void> _loadSettingsFirst() async {
+    // Load onboarding state first - this is critical for determining
+    // when to transition to HomeScreen
+    _hasCompletedOnboarding = await SettingsService.getHasCompletedOnboarding();
+
+    if (!mounted) return;
+
+    setState(() {
+      _settingsLoaded = true;
+    });
+
+    _logger.log('🚀 AppStartup: Settings loaded, hasCompletedOnboarding=$_hasCompletedOnboarding');
+
+    // Now check connection
     _checkAndConnect();
   }
 
   Future<void> _checkAndConnect() async {
     final serverUrl = await SettingsService.getServerUrl();
 
+    // DEBUG: Log where server URL is coming from
+    _logger.log('🐛 DEBUG: Server URL from SharedPreferences: $serverUrl');
+
     if (!mounted) return;
 
     setState(() {
@@ -354,6 +547,7 @@ class _AppStartupState extends State<AppStartup> {
 
     // If we have a saved server URL, attempt auto-connection
     if (serverUrl != null && serverUrl.isNotEmpty) {
+      _logger.log('🐛 DEBUG: Auto-connecting because server URL exists');
       setState(() {
         _isConnecting = true;
       });
@@ -364,14 +558,30 @@ class _AppStartupState extends State<AppStartup> {
       // Just wait for it to complete or timeout
       _logger.log('🚀 AppStartup: Waiting for provider auto-connection to $serverUrl');
 
+      // For first-time users, we need to wait for both connection AND player selection
+      // so the welcome overlay can appear immediately without home screen flash.
+      // For returning users, just wait for connection.
+      final needsWelcome = !_hasCompletedOnboarding;
+
       // Give the provider time to connect (it restores credentials and connects in _initialize)
       // Check connection state periodically
       for (var i = 0; i < 20; i++) {
         await Future.delayed(const Duration(milliseconds: 250));
-        if (provider.isConnected) {
-          _logger.log('🚀 AppStartup: Connection established');
-          break;
+
+        if (needsWelcome) {
+          // First-time user: wait for connection + player selection
+          if (provider.isConnected && provider.selectedPlayer != null) {
+            _logger.log('🚀 AppStartup: First-time user ready (connected + player selected)');
+            break;
+          }
+        } else {
+          // Returning user: just wait for connection
+          if (provider.isConnected) {
+            _logger.log('🚀 AppStartup: Connection established');
+            break;
+          }
         }
+
         if (provider.connectionState == MAConnectionState.error) {
           _logger.log('🚀 AppStartup: Connection failed with error');
           break;
@@ -398,7 +608,8 @@ class _AppStartupState extends State<AppStartup> {
   @override
   Widget build(BuildContext context) {
     // Show loading while checking settings or connecting
-    if (!_connectionAttempted || _isConnecting) {
+    // CRITICAL: Don't transition until settings are loaded - this prevents the race
+    if (!_settingsLoaded || !_connectionAttempted || _isConnecting) {
       return Scaffold(
         backgroundColor: const Color(0xFF1a1a1a),
         body: Center(

lib/models/media_item.dart

@@ -16,6 +16,10 @@ class ProviderMapping {
   final String providerInstance;
   final bool available;
   final Map<String, dynamic>? audioFormat;
+  /// Whether this item is in the library for this specific provider instance.
+  /// True = this provider "owns" the item (user added it from this account)
+  /// False = item exists but wasn't added from this provider
+  final bool inLibrary;
 
   ProviderMapping({
     required this.itemId,
@@ -23,6 +27,7 @@ class ProviderMapping {
     required this.providerInstance,
     required this.available,
     this.audioFormat,
+    this.inLibrary = true,
   });
 
   factory ProviderMapping.fromJson(Map<String, dynamic> json) {
@@ -32,6 +37,8 @@ class ProviderMapping {
       providerInstance: json['provider_instance'] as String? ?? '',
       available: json['available'] as bool? ?? true,
       audioFormat: json['audio_format'] as Map<String, dynamic>?,
+      // Parse in_library field - MA uses 1/0 or true/false
+      inLibrary: json['in_library'] == true || json['in_library'] == 1,
     );
   }
 
@@ -42,6 +49,7 @@ class ProviderMapping {
       'provider_instance': providerInstance,
       'available': available,
       if (audioFormat != null) 'audio_format': audioFormat,
+      'in_library': inLibrary,
     };
   }
 }
@@ -110,13 +118,31 @@ class MediaItem {
       'media_type': mediaType.name,
       if (sortName != null) 'sort_name': sortName,
       if (uri != null) 'uri': uri,
-      if (providerMappings != null) 'provider_mappings': providerMappings,
+      if (providerMappings != null)
+        'provider_mappings': providerMappings!.map((m) => m.toJson()).toList(),
       if (metadata != null) 'metadata': metadata,
       if (favorite != null) 'favorite': favorite,
       if (position != null) 'position': position,
       if (duration != null) 'duration': duration!.inSeconds,
     };
   }
+
+  @override
+  bool operator ==(Object other) =>
+      identical(this, other) ||
+      other is MediaItem &&
+          runtimeType == other.runtimeType &&
+          itemId == other.itemId &&
+          provider == other.provider;
+
+  @override
+  int get hashCode => Object.hash(itemId, provider);
+
+  /// Check if this item is in the user's library
+  bool get inLibrary {
+    if (provider == 'library') return true;
+    return providerMappings?.any((m) => m.providerInstance == 'library') ?? false;
+  }
 }
 
 class Artist extends MediaItem {
@@ -145,6 +171,12 @@ class Artist extends MediaItem {
     );
   }
 
+  /// Check if this artist is in the user's library
+  bool get inLibrary {
+    if (provider == 'library') return true;
+    return providerMappings?.any((m) => m.providerInstance == 'library') ?? false;
+  }
+
   @override
   Map<String, dynamic> toJson() => super.toJson();
 }
@@ -266,6 +298,12 @@ class Track extends MediaItem {
   String get artistsString =>
       artists?.map((a) => a.name).join(', ') ?? 'Unknown Artist';
 
+  /// Check if this track is in the user's library
+  bool get inLibrary {
+    if (provider == 'library') return true;
+    return providerMappings?.any((m) => m.providerInstance == 'library') ?? false;
+  }
+
   @override
   Map<String, dynamic> toJson() {
     final json = super.toJson();
@@ -312,6 +350,12 @@ class Playlist extends MediaItem {
       favorite: item.favorite,
     );
   }
+
+  /// Check if this playlist is in the user's library
+  bool get inLibrary {
+    if (provider == 'library') return true;
+    return providerMappings?.any((m) => m.providerInstance == 'library') ?? false;
+  }
 }
 
 class Chapter {
@@ -420,9 +464,20 @@ class Audiobook extends MediaItem {
   factory Audiobook.fromJson(Map<String, dynamic> json) {
     final item = MediaItem.fromJson(json);
 
-    // Parse year
+    // Parse year - check top level first, then metadata.release_date (ABS format)
     int? year;
-    final yearValue = json['year'];
+    final metadata = json['metadata'] as Map<String, dynamic>?;
+    dynamic yearValue = json['year'];
+    if (yearValue == null && metadata != null) {
+      // ABS stores year in metadata.release_date (can be "2024" or "2024-01-15")
+      final releaseDate = metadata['release_date'];
+      if (releaseDate is String && releaseDate.isNotEmpty) {
+        // Extract year from date string (handles both "2024" and "2024-01-15" formats)
+        yearValue = releaseDate.split('-').first;
+      } else if (releaseDate is int) {
+        yearValue = releaseDate;
+      }
+    }
     if (yearValue is int) {
       year = yearValue;
     } else if (yearValue is String) {
@@ -452,8 +507,6 @@ class Audiobook extends MediaItem {
 
     // Parse chapters - check top level first, then metadata
     List<Chapter>? chapters;
-    final metadata = json['metadata'] as Map<String, dynamic>?;
-
     dynamic chaptersData = json['chapters'];
     if (chaptersData == null && metadata != null) {
       chaptersData = metadata['chapters'];
@@ -499,6 +552,12 @@ class Audiobook extends MediaItem {
   String get narratorsString =>
       narrators?.map((n) => n.name).join(', ') ?? 'Unknown Narrator';
 
+  /// Check if this audiobook is in the user's library
+  bool get inLibrary {
+    if (provider == 'library') return true;
+    return providerMappings?.any((m) => m.providerInstance == 'library') ?? false;
+  }
+
   /// Get progress as a percentage (0.0 to 1.0)
   double get progress {
     if (fullyPlayed == true) return 1.0;

lib/models/player.dart

@@ -12,6 +12,12 @@ class Player {
   final bool? volumeMuted;
   final double? elapsedTime; // Seconds elapsed in current track
   final double? elapsedTimeLastUpdated; // Unix timestamp when elapsed_time was last updated
+  final List<String>? groupMembers; // List of player IDs in sync group (includes self)
+  final String? syncedTo; // Player ID this player is synced to (null if leader or not synced)
+  final String? activeSource; // The currently active source for this player
+  final bool isExternalSource; // True when an external source (optical, Spotify, etc.) is active
+  final String? appId; // The app_id from MA - 'music_assistant' when MA is playing, else external source
+  final String? activeQueue; // The active_queue from MA - has value when MA is controlling playback
 
   Player({
     required this.playerId,
@@ -25,6 +31,12 @@ class Player {
     this.volumeMuted,
     this.elapsedTime,
     this.elapsedTimeLastUpdated,
+    this.groupMembers,
+    this.syncedTo,
+    this.activeSource,
+    this.isExternalSource = false,
+    this.appId,
+    this.activeQueue,
   });
 
   /// Create a copy of this Player with some fields replaced
@@ -40,6 +52,12 @@ class Player {
     bool? volumeMuted,
     double? elapsedTime,
     double? elapsedTimeLastUpdated,
+    List<String>? groupMembers,
+    String? syncedTo,
+    String? activeSource,
+    bool? isExternalSource,
+    String? appId,
+    String? activeQueue,
   }) {
     return Player(
       playerId: playerId ?? this.playerId,
@@ -53,6 +71,12 @@ class Player {
       volumeMuted: volumeMuted ?? this.volumeMuted,
       elapsedTime: elapsedTime ?? this.elapsedTime,
       elapsedTimeLastUpdated: elapsedTimeLastUpdated ?? this.elapsedTimeLastUpdated,
+      groupMembers: groupMembers ?? this.groupMembers,
+      syncedTo: syncedTo ?? this.syncedTo,
+      activeSource: activeSource ?? this.activeSource,
+      isExternalSource: isExternalSource ?? this.isExternalSource,
+      appId: appId ?? this.appId,
+      activeQueue: activeQueue ?? this.activeQueue,
     );
   }
 
@@ -61,8 +85,37 @@ class Player {
   bool get isMuted => volumeMuted ?? false;
   int get volume => volumeLevel ?? 0;
 
+  // Group properties
+  // A player is grouped if it's a leader with members OR a child synced to another
+  bool get isGrouped => (groupMembers != null && groupMembers!.length > 1) || syncedTo != null;
+  bool get isGroupLeader => groupMembers != null && groupMembers!.length > 1 && syncedTo == null;
+  bool get isGroupChild => syncedTo != null;
+
+  // A player is manually synced if it's synced TO another player (child of a sync group)
+  // This excludes pre-configured MA speaker groups which have groupMembers but no syncedTo
+  // Used for yellow border highlight - only shows for players the user manually synced
+  bool get isManuallySynced => syncedTo != null;
+
   // Track when this Player object was created (for local interpolation fallback)
   static final Map<String, double> _playerCreationTimes = {};
+  static const int _maxCreationTimesEntries = 50;
+
+  /// Clean up old creation time entries using LRU eviction
+  static void _cleanupCreationTimes() {
+    if (_playerCreationTimes.length <= _maxCreationTimesEntries) return;
+
+    // Sort by timestamp value (oldest first) for true LRU eviction
+    final sortedEntries = _playerCreationTimes.entries.toList()
+      ..sort((a, b) => a.value.compareTo(b.value));
+
+    // Remove oldest entries until we're at target size
+    final entriesToRemove = sortedEntries.take(
+      _playerCreationTimes.length - _maxCreationTimesEntries,
+    );
+    for (final entry in entriesToRemove) {
+      _playerCreationTimes.remove(entry.key);
+    }
+  }
 
   // Calculate current elapsed time (interpolated if playing)
   double get currentElapsedTime {
@@ -104,13 +157,8 @@ class Player {
     if (!_playerCreationTimes.containsKey(creationKey)) {
       // First time seeing this elapsed_time - record when we saw it
       _playerCreationTimes[creationKey] = now;
-      // Clean up old entries to prevent memory leak
-      if (_playerCreationTimes.length > 100) {
-        final keysToRemove = _playerCreationTimes.keys.take(50).toList();
-        for (final key in keysToRemove) {
-          _playerCreationTimes.remove(key);
-        }
-      }
+      // Clean up old entries to prevent memory leak (LRU eviction)
+      _cleanupCreationTimes();
     }
 
     final creationTime = _playerCreationTimes[creationKey]!;
@@ -164,6 +212,79 @@ class Player {
     elapsedTime ??= topLevelElapsedTime;
     elapsedTimeLastUpdated ??= topLevelLastUpdated;
 
+    // Parse group members - MA returns this as a list of player IDs
+    final groupMembersList = json['group_members'] as List<dynamic>?;
+    final groupMembers = groupMembersList?.map((e) => e.toString()).toList();
+
+    // Parse synced_to - the player ID this player is synced to
+    final syncedTo = json['synced_to'] as String?;
+
+    // Parse active_source - the currently active source for this player
+    final activeSource = json['active_source'] as String?;
+
+    // Parse active_queue - this is the key indicator for MA-controlled playback
+    // When MA is playing: active_queue = 'uuid:...' or similar queue ID
+    // When external source: active_queue = null
+    final activeQueue = json['active_queue'] as String?;
+
+    // Parse app_id - helps distinguish external sources on DLNA players
+    final appId = json['app_id'] as String?;
+
+    // Detect external source (optical, Spotify Connect, AirPlay, etc.)
+    //
+    // Detection logic priority:
+    // 1. If app_id == 'music_assistant' -> MA is playing, NOT external
+    // 2. If active_queue has a value -> MA has a queue, NOT external
+    //    (This handles Spotify as music provider where URI is spotify:// but MA controls playback)
+    // 3. If app_id is set and NOT 'music_assistant' -> external source (e.g., 'http', 'spotify')
+    // 4. Fallback: Check URI patterns for simple external IDs (optical, line_in, etc.)
+    bool isExternalSource = false;
+
+    // If MA explicitly says it's playing, trust that
+    if (appId == 'music_assistant') {
+      isExternalSource = false;
+    }
+    // If there's an active queue, MA is controlling playback (even with spotify:// URIs)
+    else if (activeQueue != null && activeQueue.isNotEmpty) {
+      isExternalSource = false;
+    }
+    // If app_id is set to something else (http, spotify, etc.), it's external
+    else if (appId != null && appId.isNotEmpty) {
+      isExternalSource = true;
+    }
+    // Fallback: check current_media for simple external source indicators
+    // Only check these when we have no app_id and no active_queue
+    else if (json.containsKey('current_media')) {
+      final currentMedia = json['current_media'] as Map<String, dynamic>?;
+      if (currentMedia != null) {
+        final uri = currentMedia['uri'] as String?;
+        final mediaType = currentMedia['media_type'] as String?;
+
+        // Only check for simple external source identifiers (physical inputs)
+        // Do NOT flag spotify://, airplay://, etc. as external here -
+        // those should only be external if app_id indicates external control
+        if (uri != null) {
+          final uriLower = uri.toLowerCase();
+          // Simple external source identifiers (no :// or /)
+          // These are physical inputs that are always external
+          final isSimpleExternalId = !uri.contains('://') && !uri.contains('/') &&
+              (uriLower == 'optical' || uriLower == 'line_in' || uriLower == 'bluetooth' ||
+               uriLower == 'hdmi' || uriLower == 'tv' || uriLower == 'aux' ||
+               uriLower == 'coaxial' || uriLower == 'toslink');
+
+          isExternalSource = isSimpleExternalId;
+        }
+
+        // Also check media_type - 'unknown' with non-MA URI indicates external source
+        if (!isExternalSource && mediaType == 'unknown') {
+          final uri = currentMedia['uri'] as String?;
+          if (uri != null && !uri.startsWith('library://') && !uri.contains('://track/')) {
+            isExternalSource = true;
+          }
+        }
+      }
+    }
+
     return Player(
       playerId: json['player_id'] as String,
       name: json['name'] as String,
@@ -176,6 +297,12 @@ class Player {
       volumeMuted: json['volume_muted'] as bool?,
       elapsedTime: elapsedTime,
       elapsedTimeLastUpdated: elapsedTimeLastUpdated,
+      groupMembers: groupMembers,
+      syncedTo: syncedTo,
+      activeSource: activeSource,
+      isExternalSource: isExternalSource,
+      appId: appId,
+      activeQueue: activeQueue,
     );
   }
 
@@ -192,6 +319,12 @@ class Player {
       if (volumeMuted != null) 'volume_muted': volumeMuted,
       if (elapsedTime != null) 'elapsed_time': elapsedTime,
       if (elapsedTimeLastUpdated != null) 'elapsed_time_last_updated': elapsedTimeLastUpdated,
+      if (groupMembers != null) 'group_members': groupMembers,
+      if (syncedTo != null) 'synced_to': syncedTo,
+      if (activeSource != null) 'active_source': activeSource,
+      'is_external_source': isExternalSource,
+      if (appId != null) 'app_id': appId,
+      if (activeQueue != null) 'active_queue': activeQueue,
     };
   }
 }