Fix AA shuffle/repeat buttons and artist images

Shuffle/repeat buttons showed disabled after starting playback because
_refreshQueueAfterDelay only updated queue items without syncing the
shuffle/repeat state. Now syncs both flags and refreshes playback state.

Artist images failed in AA because _autoBuildArtistList used the basic
getImageUrl which returns null for artists without MA metadata images.
Now uses getArtistImageUrlWithFallback which tries external sources.

Co-Authored-By: Claude Opus 4.6 <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

@@ -4,10 +4,13 @@ on:
   push:
     branches:
       - main
+      - master
       - 'claude/**'
+      - 'feature/**'
   pull_request:
     branches:
       - main
+      - master
   workflow_dispatch:
 
 jobs:
@@ -28,13 +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
 
@@ -42,19 +61,13 @@ jobs:
         run: flutter analyze
         continue-on-error: true
 
-      - name: Create signing keystore
+      - name: Setup signing keystore
         run: |
-          # Create a keystore for signing (valid for 10000 days)
-          keytool -genkey -v -keystore android/app/upload-keystore.jks \
-            -storetype JKS -keyalg RSA -keysize 2048 -validity 10000 \
-            -storepass android -keypass android \
-            -alias upload -dname "CN=AssistantToTheMusic, OU=HomeServer, O=Personal, L=Home, S=Home, C=US"
-
-          # Create key.properties file
+          echo "${{ secrets.KEYSTORE_BASE64 }}" | base64 -d > android/app/upload-keystore.jks
           cat > android/key.properties << EOF
-          storePassword=android
-          keyPassword=android
-          keyAlias=upload
+          storePassword=${{ secrets.KEYSTORE_PASSWORD }}
+          keyPassword=${{ secrets.KEY_PASSWORD }}
+          keyAlias=${{ secrets.KEY_ALIAS }}
           storeFile=upload-keystore.jks
           EOF
 
@@ -64,16 +77,11 @@ jobs:
       - name: Upload APK artifact
         uses: actions/upload-artifact@v4
         with:
-          name: amass-apk
+          name: ensemble-apk
           path: build/app/outputs/flutter-apk/app-release.apk
           retention-days: 30
 
       - 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

ARCHITECTURE.md

@@ -1,429 +0,0 @@
-# Music Assistant Mobile - Architecture Documentation
-
-## Overview
-
-Music Assistant Mobile is a Flutter application that connects to a [Music Assistant](https://music-assistant.io/) server to browse and control music playback across various devices and players.
-
-## Architecture Pattern
-
-The app follows the **Provider pattern** for state management with a **layered architecture**:
-
-```
-┌─────────────────────────────────────┐
-│         Presentation Layer          │
-│    (Screens, Widgets, UI Logic)     │
-└──────────────┬──────────────────────┘
-               │
-┌──────────────┴──────────────────────┐
-│         State Management            │
-│    (Providers - Business Logic)     │
-└──────────────┬──────────────────────┘
-               │
-┌──────────────┴──────────────────────┐
-│         Service Layer               │
-│  (API, Auth, Audio, Settings, etc)  │
-└──────────────┬──────────────────────┘
-               │
-┌──────────────┴──────────────────────┐
-│         Data Layer                  │
-│      (Models, DTOs)                 │
-└─────────────────────────────────────┘
-```
-
-## Key Components
-
-### 1. Providers (`lib/providers/`)
-
-**MusicAssistantProvider** - Central state manager
-- Manages WebSocket connection to Music Assistant server
-- Handles authentication and auto-login
-- Maintains library state (artists, albums, tracks)
-- Manages player selection and playback state
-- Implements player list caching (5-minute cache)
-- Polls selected player state every 2 seconds
-
-**MusicPlayerProvider** - Local audio playback (deprecated)
-- Legacy local playback using just_audio
-- Being phased out in favor of server-side playback control
-
-### 2. Services (`lib/services/`)
-
-**MusicAssistantAPI** - WebSocket API client
-- Connects to Music Assistant server via WebSocket
-- Implements JSON-RPC message protocol
-- Handles server info, events, and command responses
-- Provides methods for:
-  - Library browsing (artists, albums, tracks, playlists)
-  - Search functionality
-  - Player control and queue management
-  - Built-in player registration
-  - Stream URL generation
-
-**AuthService** - Authentication management
-- Handles Authelia authentication (separate auth domain)
-- Stores and retrieves session cookies
-- Auto-login with saved credentials
-
-**SettingsService** - Persistent settings
-- Uses `shared_preferences` for local storage
-- Stores:
-  - Server URL and WebSocket port
-  - Username and password (encrypted)
-  - Built-in player ID
-  - Authentication token
-
-**AudioPlayerService** - Local audio playback
-- Wraps `just_audio` for audio playback
-- Handles play, pause, stop, seek operations
-- Currently used for built-in player mode
-
-**BuiltinPlayerService** - Server push events
-- Listens to built-in player events from server
-- Handles QUEUE_ITEMS, PLAY_MEDIA, STOP, etc.
-- Coordinates with AudioPlayerService
-
-**DebugLogger** - Logging utility
-- Prints timestamped debug logs
-- Helps troubleshooting and development
-
-### 3. Models (`lib/models/`)
-
-**MediaItem** - Base class for media entities
-- `Artist` - Artist metadata
-- `Album` - Album metadata with artists
-- `Track` - Track metadata with artists and album
-- All include provider mappings and metadata
-
-**Player** - Music Assistant player
-- Player ID, name, state (idle/playing/paused)
-- Availability and power status
-- Derived `isPlaying` getter
-
-**PlayerQueue** - Player queue state
-- List of `QueueItem`
-- Current index/item
-- Player ID
-
-**QueueItem** - Item in player queue
-- Queue item ID
-- Track metadata
-- Stream details (sample rate, bit depth, content type)
-
-**BuiltinPlayerEvent** - Server push events
-- Event type (QUEUE_ITEMS, PLAY_MEDIA, etc.)
-- Event data payload
-
-### 4. Screens (`lib/screens/`)
-
-**Navigation Flow:**
-```
-MainLayout (Bottom Navigation)
-├── NewHomeScreen
-│   ├── LibraryStats
-│   ├── AlbumRow (Recent, Random, All)
-│   └── SearchScreen (via app bar)
-├── NewLibraryScreen
-│   ├── LibraryArtistsScreen (with pull-to-refresh)
-│   ├── LibraryAlbumsScreen (with pull-to-refresh)
-│   └── LibraryTracksScreen
-└── SettingsScreen
-```
-
-**Detail Screens:**
-- `ArtistDetailsScreen` - Artist albums
-- `AlbumDetailsScreen` - Album tracks with play button
-- `PlayerScreen` - Full player view
-- `QueueScreen` - Queue management (reorder, remove)
-- `SearchScreen` - Global search (artists, albums, tracks)
-
-### 5. Widgets (`lib/widgets/`)
-
-**Reusable Components:**
-- `MiniPlayer` - Bottom now playing bar
-- `PlayerSelector` - Device/player picker
-- `AlbumRow` - Horizontal scrolling album list
-- `LibraryStats` - Library statistics card
-- `PlayerControls` - Playback controls (deprecated)
-
-## Data Flow
-
-### Player Selection & Control
-
-```
-User selects player → PlayerSelector widget
-                    ↓
-        MusicAssistantProvider.selectPlayer()
-                    ↓
-        Starts player state polling (every 2s)
-                    ↓
-        Fetches queue via getQueue()
-                    ↓
-        Updates currentTrack
-                    ↓
-        MiniPlayer displays track info
-```
-
-### Music Playback
-
-```
-User plays album → AlbumDetailsScreen._playAlbum()
-                ↓
-        MusicAssistantProvider.playTracks()
-                ↓
-        API: player_queues/play_media
-                ↓
-        Server queues tracks on selected player
-                ↓
-        Player state polling updates UI
-```
-
-### Library Loading
-
-```
-App connects → MusicAssistantProvider._initialize()
-             ↓
-         connectToServer()
-             ↓
-         WebSocket connection established
-             ↓
-         loadLibrary() (auto-triggered)
-             ↓
-         Fetches artists, albums, tracks (limit: 100 each)
-             ↓
-         notifyListeners() → UI updates
-```
-
-## API Integration
-
-### WebSocket Commands
-
-The app uses Music Assistant's WebSocket JSON-RPC API:
-
-**Library:**
-- `music/artists/library_items` - Get artists
-- `music/albums/library_items` - Get albums
-- `music/tracks/library_items` - Get tracks
-- `music/search` - Search all media types
-
-**Playback Control:**
-- `player_queues/play_media` - Queue and play tracks
-- `player_command/play` - Resume playback
-- `player_command/pause` - Pause playback
-- `player_command/next` - Next track
-- `player_command/previous` - Previous track
-
-**Queue Management:**
-- `player_queues/items` - Get queue items (returns List, not object)
-
-**Players:**
-- `players/all` - Get all available players
-
-**Built-in Player:**
-- `builtin_player/register` - Register device as player
-- `builtin_player/update_state` - Update player state
-
-### Event Subscriptions
-
-The WebSocket connection receives real-time events:
-- `player_updated` - Player state changed
-- `queue_updated` - Queue modified
-- `queue_items_updated` - Queue items changed
-- `media_item_played` - Track started playing
-- `builtin_player` - Built-in player event (QUEUE_ITEMS, PLAY_MEDIA, etc.)
-
-## Performance Optimizations
-
-### 1. Player List Caching
-- Cache player list for 5 minutes
-- Reduces API calls on player selector opens
-- Force refresh available via `refreshPlayers()`
-
-### 2. Debounced Search
-- 500ms debounce on search input
-- Prevents excessive API calls while typing
-
-### 3. Pagination
-- Library loads with limit (default: 100)
-- Can be extended for infinite scroll
-
-### 4. Image Loading
-- NetworkImage with error handling
-- Fallback to icon on load failure
-- Size parameter for different image resolutions
-
-## State Management Pattern
-
-```dart
-// Provider pattern example
-class MusicAssistantProvider with ChangeNotifier {
-  List<Album> _albums = [];
-
-  List<Album> get albums => _albums;
-
-  Future<void> loadAlbums() async {
-    _albums = await _api.getAlbums();
-    notifyListeners(); // Triggers UI rebuild
-  }
-}
-
-// Widget consumption
-class AlbumList extends StatelessWidget {
-  @override
-  Widget build(BuildContext context) {
-    final provider = context.watch<MusicAssistantProvider>();
-    return ListView(
-      children: provider.albums.map((album) => AlbumTile(album)).toList(),
-    );
-  }
-}
-```
-
-## Authentication Flow
-
-### Authelia Integration
-
-Music Assistant Mobile supports Authelia authentication on separate domains:
-
-```
-1. User enters credentials in SettingsScreen
-           ↓
-2. AuthService.login(serverUrl, username, password)
-           ↓
-3. POST to auth.serverscloud.org
-           ↓
-4. Extract authelia_session cookie
-           ↓
-5. Store cookie in SettingsService
-           ↓
-6. Include cookie in WebSocket handshake
-           ↓
-7. WebSocket: headers['Cookie'] = 'authelia_session=...'
-```
-
-### Auto-Login
-
-On app startup:
-1. Check for saved credentials
-2. If found, attempt silent login
-3. On success, connect to Music Assistant server
-4. On failure, user can re-enter credentials
-
-## Error Handling
-
-### API Errors
-- Try-catch blocks around all API calls
-- Errors logged via DebugLogger
-- UI shows error states (empty states, snackbars)
-
-### WebSocket Reconnection
-- Auto-reconnect on disconnect (3-second delay)
-- Connection state tracked via Stream
-- UI reflects connection status
-
-### Queue Parsing Errors
-- Defensive parsing with try-catch per item
-- Failed items skipped, parsing continues
-- Debug logging for troubleshooting
-
-## Testing Strategy
-
-### Unit Tests (TODO)
-- API service methods
-- Model parsing (fromJson/toJson)
-- State management logic
-
-### Widget Tests (TODO)
-- Screen rendering
-- User interactions
-- Navigation flows
-
-### Integration Tests (TODO)
-- End-to-end user flows
-- WebSocket communication
-- Authentication
-
-## Future Enhancements
-
-### Planned Features
-1. **Playlists** - Browse and play playlists
-2. **Favorites** - Mark/unmark favorites, filter by favorites
-3. **Lyrics** - Display lyrics for current track
-4. **Sleep Timer** - Auto-stop playback
-5. **Crossfade** - Smooth transitions between tracks
-6. **Equalizer** - Audio customization
-7. **Offline Mode** - Cached playback
-8. **Android Auto / CarPlay** - In-car integration
-
-### Technical Improvements
-1. **Retry Logic** - Exponential backoff for failed requests
-2. **Better Error Messages** - User-friendly error descriptions
-3. **Loading States** - Skeleton screens, shimmer effects
-4. **Infinite Scroll** - Lazy load library items
-5. **Image Caching** - Reduce network usage
-6. **WebSocket Reconnection** - Smarter reconnection strategy
-
-## Development Guidelines
-
-### Code Style
-- Follow [Effective Dart](https://dart.dev/guides/language/effective-dart)
-- Use meaningful variable names
-- Add comments for complex logic
-- Keep functions small and focused
-
-### File Organization
-```
-lib/
-├── main.dart                 # App entry point
-├── models/                   # Data models
-├── providers/                # State management
-├── screens/                  # Full-screen views
-├── widgets/                  # Reusable components
-└── services/                 # Business logic, API, utilities
-```
-
-### Adding New Features
-
-1. **Define Model** (if needed) - Add to `lib/models/`
-2. **Create API Method** - Add to `MusicAssistantAPI`
-3. **Update Provider** - Add state and methods to relevant provider
-4. **Build UI** - Create screen/widget in `lib/screens/` or `lib/widgets/`
-5. **Wire Navigation** - Update navigation logic
-6. **Test** - Write unit/widget tests
-7. **Document** - Update this file and add code comments
-
-### Debugging Tips
-
-1. **Enable Debug Logging** - DebugLogger prints to console
-2. **Check WebSocket Messages** - Logs show all WS traffic
-3. **Inspect Provider State** - Use Flutter DevTools
-4. **Network Debugging** - Check API responses
-5. **Test Authentication** - Verify session cookies
-
-## Dependencies
-
-### Core
-- `flutter` - UI framework
-- `provider` - State management
-- `web_socket_channel` - WebSocket client
-
-### Audio
-- `just_audio` - Audio playback
-- `audio_service` - Background playback
-
-### Networking
-- `http` - HTTP requests
-- `uuid` - Unique ID generation
-
-### Storage
-- `shared_preferences` - Local key-value storage
-
-### UI
-- `flutter_launcher_icons` - App icons
-
-## Resources
-
-- **Music Assistant**: https://music-assistant.io/
-- **Music Assistant API Docs**: https://music-assistant.io/integration/websocket/
-- **Flutter Docs**: https://docs.flutter.dev/
-- **Provider Package**: https://pub.dev/packages/provider
-- **just_audio Package**: https://pub.dev/packages/just_audio

CLEANUP_GHOST_PLAYERS.md

@@ -1,153 +0,0 @@
-# Cleaning Up Ghost "Music Assistant Mobile" Players
-
-## The Problem
-
-Early versions of Amass registered the mobile device as a local playback player with Music Assistant. This created "Music Assistant Mobile" player entities on your server. Multiple app restarts/logins created multiple ghost players that persist on the server.
-
-## Current Status
-
-The Amass app now:
-- ✅ No longer registers as a player (acts as remote control only)
-- ✅ Filters out these ghost players automatically
-- ✅ Won't create new ghost players
-
-However, the old players still exist on your Music Assistant server.
-
-## Finding Ghost Players
-
-### Using Amass Player Diagnostics Tool
-
-1. Open Amass app
-2. Go to **Settings** → **Debug Logs**
-3. Tap the **speaker icon** (🔊) in the top right
-4. See all players including hidden ghost players (highlighted in red)
-5. Tap **Copy List** to copy player IDs for manual removal
-
-This shows you:
-- All player names and IDs
-- Whether they're available or unavailable
-- Their current state (idle/playing/paused)
-
-**Note**: Ghost players are marked as `available: true` but are builtin_player type with default_name "Music Assistant Mobile". They exist in your `settings.json` but don't show in the web UI because they're orphaned mobile players.
-
-## Findings from Your Server
-
-Your Music Assistant logs show:
-- **26 ghost "Music Assistant Mobile" players** found in `settings.json`
-- Created between Nov 22-23, 2025 (during app development/testing)
-- All are `provider: builtin_player` with `available: true`
-- Player IDs are UUIDs like `202f4c01-abbf-4a46-83f8-9954570e7e50`
-
-These players are in your settings but not visible in the UI, which is why manual cleanup is needed.
-
-## Automated Cleanup (Recommended)
-
-A cleanup script has been created for your server:
-
-```bash
-# Run the cleanup script
-cd /home/home-server/Amass
-./cleanup_ghost_players.sh
-
-# It will:
-# 1. Show you all 26 ghost players
-# 2. Ask for confirmation
-# 3. Backup settings.json
-# 4. Remove ghost players
-# 5. Tell you to restart Music Assistant
-```
-
-After running the script, restart Music Assistant:
-```bash
-docker restart music_assistant
-# Or if using docker-compose:
-cd /home/home-server/docker/music-assistant
-docker compose restart
-```
-
-## Manual Cleanup (Advanced)
-
-If you prefer manual cleanup:
-
-### Option 1: Via Web UI Settings
-
-1. Open your Music Assistant web UI (e.g., `http://ma.serverscloud.org:8097`)
-2. Navigate to **Settings** → **Players**
-3. Look for players named "Music Assistant Mobile" or similar
-4. For each ghost player:
-   - Click the **⋮** (three dots) menu
-   - Select **Remove Player** or **Delete**
-5. Confirm deletion for each one
-
-### Option 2: Via Players Tab
-
-1. Open Music Assistant web UI
-2. Click the **Players** tab
-3. Find all "Music Assistant Mobile" entries
-4. Right-click or use the context menu to remove each one
-
-## How to Clean Up (Home Assistant)
-
-If Music Assistant is integrated with Home Assistant:
-
-1. Open Home Assistant
-2. Go to **Settings** → **Devices & Services**
-3. Click **Music Assistant**
-4. Look for "Music Assistant Mobile" devices/entities
-5. For each one:
-   - Click on the entity
-   - Click **⋮** → **Delete**
-
-## How to Clean Up (Command Line / SSH)
-
-If you have SSH access to your Music Assistant server:
-
-```bash
-# Connect to your server
-ssh user@ma.serverscloud.org
-
-# Access Music Assistant container (if dockerized)
-docker exec -it music_assistant bash
-
-# Or if running as an add-on, use Home Assistant CLI
-ha addons exec music_assistant
-
-# Navigate to data directory (location varies by installation)
-cd /data  # or wherever your config is stored
-
-# Backup first!
-cp mass.json mass.json.backup
-
-# Edit the config file
-nano mass.json  # or vi, etc.
-
-# Look for player entries with names like "Music Assistant Mobile"
-# Remove those entries (be careful with JSON syntax!)
-# Save and exit
-
-# Restart Music Assistant
-# (from outside container if dockerized)
-docker restart music_assistant
-```
-
-⚠️ **Warning**: Manual JSON editing is risky. Use web UI method if possible.
-
-## Verifying Cleanup
-
-After cleanup, check the Amass app logs. You should see:
-- No more "Filtering out leftover player" messages
-- "Loaded X players" with a reasonable count (not 30+)
-
-## Prevention
-
-The current version of Amass (v1.0.0+) will not create new ghost players. If you see new ones appearing:
-1. Make sure you're using the latest version
-2. Uninstall any old versions of the app
-3. Clear app data before reinstalling
-
-## Questions?
-
-If ghost players keep appearing after cleanup, there may be another app or integration registering them. Check:
-- Other Music Assistant mobile apps
-- Home Assistant automations
-- Music Assistant player announcements

OVERNIGHT_WORK_SUMMARY.md

@@ -1,472 +0,0 @@
-# Overnight Work Session Summary
-
-## Session Overview
-
-This document summarizes all improvements and features added to the Music Assistant Mobile app during the comprehensive overnight development session.
-
-**Session Date:** 2025-01-22
-**Total Commits:** 9
-**Files Changed:** 20+
-**Lines Added:** 1,500+
-
----
-
-## ✅ Completed Tasks
-
-### 1. Now Playing Bar Debugging & Fixes
-
-**Problem:** Now playing bar wasn't showing even when music was playing
-
-**Solution:**
-- Fixed queue endpoint from `players/queue/items` to `player_queues/items`
-- Changed parameter from `player_id` to `queue_id` to match API format
-- Added defensive parsing for queue items with try-catch per item
-- Added debug logging to inspect raw queue data structure
-- Fixed QueueItem parsing to handle missing `queue_item_id` field (fallback to `item_id`)
-
-**Files Modified:**
-- `lib/services/music_assistant_api.dart`
-- `lib/models/player.dart`
-
-**Impact:** Now playing bar now correctly shows current track when music is playing on any selected player.
-
----
-
-### 2. Home Page Enhancements
-
-**Added Features:**
-- **Recent Albums Row** - Shows recently played albums
-- **Random Albums Row** ("Discover") - Displays random albums for music discovery
-- **Library Statistics** - Visual card showing artists/albums/tracks counts
-- **Improved Layout** - Better spacing and visual hierarchy
-
-**New API Methods:**
-```dart
-Future<List<Album>> getRecentAlbums({int limit = 10})
-Future<List<Album>> getRandomAlbums({int limit = 10})
-Future<Map<String, int>> getLibraryStats()
-```
-
-**New Widgets:**
-- `lib/widgets/album_row.dart` - Horizontal scrolling album list
-- `lib/widgets/library_stats.dart` - Statistics display card
-
-**Files Modified:**
-- `lib/screens/new_home_screen.dart`
-- `lib/services/music_assistant_api.dart`
-
-**Impact:** Home screen is now much more engaging with personalized content and discovery features.
-
----
-
-### 3. Global Search Functionality
-
-**Added:**
-- Search button in home and library screen app bars
-- Navigation to existing SearchScreen
-- Quick access to search from main navigation
-
-**Files Modified:**
-- `lib/screens/new_home_screen.dart`
-- `lib/screens/new_library_screen.dart`
-
-**Impact:** Users can now easily search their entire music library from any main screen.
-
----
-
-### 4. Queue Viewer Screen
-
-**Features:**
-- Full-screen queue management
-- Display all queued tracks with album art
-- Reorder tracks via drag and drop
-- Remove tracks via swipe to dismiss
-- Visual indicator for currently playing track
-- Refresh button to reload queue
-- Queue button in mini-player for easy access
-
-**New Files:**
-- `lib/screens/queue_screen.dart`
-
-**Files Modified:**
-- `lib/widgets/mini_player.dart`
-
-**Impact:** Users can now see and manage their playback queue with intuitive gestures.
-
-**Note:** Reordering and removing are currently local-only (server sync not yet implemented).
-
----
-
-### 5. Pull-to-Refresh on Library Screens
-
-**Added:**
-- RefreshIndicator on artists list
-- RefreshIndicator on albums grid
-- Triggers library reload on pull-down gesture
-
-**Files Modified:**
-- `lib/screens/library_artists_screen.dart`
-- `lib/screens/library_albums_screen.dart`
-
-**Impact:** Better UX for refreshing library data without navigating away.
-
----
-
-### 6. Player List Caching
-
-**Optimization:**
-- Cache player list for 5 minutes
-- Reduce API calls when opening player selector
-- Force refresh available via explicit refresh
-- Automatic cache invalidation after timeout
-
-**Implementation:**
-```dart
-DateTime? _playersLastFetched;
-static const Duration _playersCacheDuration = Duration(minutes: 5);
-
-Future<void> _loadAndSelectPlayers({bool forceRefresh = false}) {
-  // Check cache first
-  if (!forceRefresh && cache_valid) {
-    return cached_players;
-  }
-  // Fetch fresh data
-}
-```
-
-**Files Modified:**
-- `lib/providers/music_assistant_provider.dart`
-
-**Impact:** Reduced network traffic and improved app responsiveness when switching players.
-
----
-
-### 7. Comprehensive Documentation
-
-**Created:**
-
-#### ARCHITECTURE.md (600+ lines)
-- Complete architecture overview
-- Component descriptions and responsibilities
-- Data flow diagrams
-- API integration details
-- Performance optimizations
-- Development guidelines
-- Future enhancement roadmap
-
-**Sections:**
-- Architecture Pattern
-- Key Components (Providers, Services, Models, Screens, Widgets)
-- Data Flow (Player Selection, Music Playback, Library Loading)
-- API Integration (WebSocket Commands, Event Subscriptions)
-- Performance Optimizations
-- State Management Pattern
-- Authentication Flow
-- Error Handling
-- Testing Strategy
-- Development Guidelines
-
-#### TROUBLESHOOTING.md (500+ lines)
-- Common issues and solutions
-- Debug logging instructions
-- Performance troubleshooting
-- Bug reporting templates
-- FAQ section
-
-**Sections:**
-- Connection Issues
-- Authentication Issues
-- Playback Issues
-- Library Issues
-- Queue Issues
-- Performance Issues
-- UI Issues
-- Debug Logging
-- Known Limitations
-- Advanced Troubleshooting
-- Getting Help
-- FAQ
-
-**Impact:** Future development and debugging will be much easier with comprehensive documentation.
-
----
-
-## 📊 Statistics
-
-### Commits Summary
-
-1. `965bf9d` - Add defensive parsing and debug logging for queue items
-2. `38b29cb` - Add home page enhancements (albums, stats)
-3. `6c291f7` - Add search functionality to main screens
-4. `ad4136f` - Add queue viewer screen
-5. `4f7856e` - Add pull-to-refresh to library screens
-6. `e24b542` - Add player list caching
-7. `0422752` - Add comprehensive documentation
-
-### Files Created
-
-**Screens:**
-- (queue_screen.dart already existed, enhanced it)
-
-**Widgets:**
-- `lib/widgets/album_row.dart`
-- `lib/widgets/library_stats.dart`
-
-**Documentation:**
-- `ARCHITECTURE.md`
-- `TROUBLESHOOTING.md`
-
-### Files Modified
-
-**Screens:**
-- `lib/screens/new_home_screen.dart`
-- `lib/screens/new_library_screen.dart`
-- `lib/screens/library_artists_screen.dart`
-- `lib/screens/library_albums_screen.dart`
-
-**Widgets:**
-- `lib/widgets/mini_player.dart`
-
-**Services:**
-- `lib/services/music_assistant_api.dart`
-
-**Providers:**
-- `lib/providers/music_assistant_provider.dart`
-
-**Models:**
-- `lib/models/player.dart`
-
----
-
-## 🎯 Key Improvements
-
-### User Experience
-- ✅ Now playing bar actually works
-- ✅ Engaging home screen with discovery features
-- ✅ Easy search access from anywhere
-- ✅ Full queue management capabilities
-- ✅ Pull-to-refresh for better control
-- ✅ Faster player selection with caching
-
-### Developer Experience
-- ✅ Comprehensive architecture documentation
-- ✅ Detailed troubleshooting guide
-- ✅ Better error handling
-- ✅ Debug logging throughout
-- ✅ Clear code structure
-- ✅ Development guidelines
-
-### Performance
-- ✅ Player list caching (5-minute cache)
-- ✅ Defensive parsing (continues on errors)
-- ✅ Reduced API calls
-- ✅ Better state management
-
----
-
-## 🔄 Features NOT Implemented
-
-Due to time constraints, the following planned features were not implemented:
-
-### High Priority (Should do next)
-1. **Retry Logic** - Exponential backoff for failed API calls
-2. **Playlist Support** - Browse and play playlists
-3. **Favorites System** - Mark/filter favorites
-
-### Medium Priority
-4. **Loading States** - Skeleton screens, shimmer effects
-5. **Better Error Messages** - User-friendly error descriptions
-6. **Unit Tests** - API layer testing
-
-### Why Not Done
-- Focus was on getting core features working (now playing bar, home page, queue)
-- Documentation was prioritized for long-term value
-- User-facing features were chosen over technical improvements
-- Time better spent on visible improvements
-
----
-
-## 🐛 Known Issues
-
-### Minor Issues
-1. **Queue Reordering** - Changes are local-only, don't sync to server
-   - **Workaround:** Use Music Assistant web interface for persistent changes
-   - **Fix Required:** Implement server API calls for queue manipulation
-
-2. **Library Pagination** - Only loads 100 items per category
-   - **Workaround:** Use search to find specific items
-   - **Fix Required:** Implement infinite scroll
-
-3. **Player State Polling** - Polls every 2 seconds
-   - **Impact:** Slight battery drain
-   - **Fix Required:** Switch to event-based updates
-
-### Fixed Issues
-- ✅ Now playing bar not showing - FIXED
-- ✅ Queue endpoint errors - FIXED
-- ✅ Queue item parsing failures - FIXED
-- ✅ Player list fetching on every open - FIXED (caching)
-
----
-
-## 💡 Recommendations for Next Session
-
-### Immediate Next Steps
-
-1. **Test Everything**
-   - Thoroughly test all new features
-   - Verify now playing bar works reliably
-   - Test queue viewer on different players
-   - Validate home page album rows
-
-2. **Fix Any Bugs Found**
-   - Monitor debug logs for errors
-   - Address any parsing issues
-   - Fix UI glitches
-
-3. **Implement Retry Logic**
-   - Add exponential backoff for failed requests
-   - Improve error handling
-   - Better user feedback on failures
-
-4. **Add Playlist Support**
-   - List playlists from server
-   - Play playlists
-   - Add to queue
-
-5. **Implement Favorites**
-   - Mark items as favorites
-   - Filter by favorites
-   - Sync with server
-
-### Code Quality Improvements
-
-1. **Add Unit Tests**
-   - Test API parsing
-   - Test state management
-   - Test model serialization
-
-2. **Improve Loading States**
-   - Add skeleton screens
-   - Better loading indicators
-   - Smooth transitions
-
-3. **Better Error Handling**
-   - User-friendly error messages
-   - Retry buttons
-   - Offline state handling
-
-### User Experience Enhancements
-
-1. **Infinite Scroll**
-   - Load more items as user scrolls
-   - Better for large libraries
-
-2. **Image Caching**
-   - Cache album artwork
-   - Reduce network usage
-   - Faster loading
-
-3. **Search Improvements**
-   - Search history
-   - Search suggestions
-   - Filter by category
-
----
-
-## 📝 Code Examples
-
-### Home Page Album Rows
-```dart
-AlbumRow(
-  title: 'Recently Played',
-  loadAlbums: () async {
-    if (provider.api == null) return [];
-    return await provider.api!.getRecentAlbums(limit: 10);
-  },
-)
-```
-
-### Player List Caching
-```dart
-// Check cache first
-if (!forceRefresh &&
-    _playersLastFetched != null &&
-    _availablePlayers.isNotEmpty &&
-    now.difference(_playersLastFetched!) < _playersCacheDuration) {
-  _logger.log('Using cached player list');
-  return;
-}
-```
-
-### Queue Defensive Parsing
-```dart
-final items = <QueueItem>[];
-for (var i in (result as List<dynamic>)) {
-  try {
-    items.add(QueueItem.fromJson(i as Map<String, dynamic>));
-  } catch (e) {
-    _logger.log('⚠️ Failed to parse queue item: $e');
-    // Continue parsing other items
-  }
-}
-```
-
----
-
-## 🎉 Achievements
-
-### Features Delivered
-- ✅ 7 major features implemented
-- ✅ 9 commits pushed
-- ✅ 20+ files modified
-- ✅ 1,500+ lines of code added
-
-### Quality Improvements
-- ✅ Comprehensive documentation (1,100+ lines)
-- ✅ Better error handling
-- ✅ Performance optimizations
-- ✅ Code organization
-
-### User Impact
-- ✅ Working now playing bar
-- ✅ Much better home screen
-- ✅ Queue management
-- ✅ Faster performance
-
----
-
-## 🔗 Related Files
-
-**Main Implementation:**
-- `lib/services/music_assistant_api.dart` - API layer with new methods
-- `lib/providers/music_assistant_provider.dart` - State management with caching
-- `lib/screens/new_home_screen.dart` - Enhanced home screen
-- `lib/screens/queue_screen.dart` - Queue viewer
-- `lib/widgets/album_row.dart` - Album carousel
-- `lib/widgets/library_stats.dart` - Statistics display
-
-**Documentation:**
-- `ARCHITECTURE.md` - Technical architecture
-- `TROUBLESHOOTING.md` - Troubleshooting guide
-- `OVERNIGHT_WORK_SUMMARY.md` - This file
-
----
-
-## 🙏 Final Notes
-
-This overnight session delivered significant improvements to the Music Assistant Mobile app:
-
-1. **Now playing bar works** - Core functionality that was broken is now fixed
-2. **Engaging home screen** - Users now have discovery features
-3. **Queue management** - Full control over playback queue
-4. **Better performance** - Caching reduces unnecessary API calls
-5. **Excellent documentation** - Future development will be much easier
-
-The app is now in a much better state for continued development. The most critical issues have been addressed, and new features have been added to enhance the user experience.
-
-**Branch:** `claude/implement-features-01YRy2D4tHYs2gKkxrP9nqVC`
-**Status:** All changes committed and pushed
-**Next Step:** Test everything and fix any issues found
-
-Thank you for the opportunity to work on this project! 🎵

README.md

@@ -1,83 +1,180 @@
 <div align="center">
-  <img src="assets/images/attm_long_logo.png" alt="Assistant To The Music Logo" height="200">
+  <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>A minimalistic mobile client for <a href="https://music-assistant.io/">Music Assistant</a></p>
-  <p>Control your Music Assistant server and manage your entire music library from your mobile device.</p>
+  <p><strong>An unofficial mobile client for Music Assistant</strong></p>
+  <p>Stream your music library directly to your phone, or control playback on any connected speaker.</p>
 </div>
 
 ---
 
 ## Disclaimer
 
-I am not a developer. This application was created using **Claude Code** and **Gemini CLI**.
+**Ensemble is an unofficial, community-built mobile client for Music Assistant. It is not affiliated with, endorsed by, or supported by the Music Assistant project or its developers.**
+
+This application was built with AI-assisted development using **Claude Code** and **Gemini CLI**.
+
+---
+
+## 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
 
-### Music Assistant Integration
-- **Server Connection** - Connect to your Music Assistant server via WebSocket
-- **Library Browsing** - Browse artists, albums, and tracks from your server
-- **Album Details** - View album information and track listings
-- **Playback Control** - Control playback on your Music Assistant server players
-- **Auto-Reconnect** - Automatic reconnection with connection status monitoring
-- **Settings Management** - Configure server URL with persistent storage
+### Local Playback
+- **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
 
-### Control Features
-- Full playback controls (play/pause/skip/seek) for server players
-- Progress bar with time display
-- Volume control for server players
-- Now playing display with track information
-- Queue management and viewing
-- Multi-player support with device selector
-- Play on... button for quick device selection
+### Remote Control
+- **Multi-Player Support** - Control any speaker or device connected to Music Assistant
+- **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
+- **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
 
-### Theming Options
+### 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 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
+- **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
+- **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
+- **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
-- **Adaptive Theming** - Album artwork-based color schemes
+- **Adaptive Colors** - Album artwork-based color schemes
 - **Light/Dark Mode** - System-aware or manual theme selection
-- Clean, minimalistic UI design
 
 ## Screenshots
 
 <div align="center">
-  <img src="assets/screenshots/1.png" alt="Connection Screen" width="250">
-  <img src="assets/screenshots/2.png" alt="Home Screen" width="250">
-  <img src="assets/screenshots/3.png" alt="Album Details" width="250">
-</div>
-
-<div align="center">
-  <img src="assets/screenshots/4.png" alt="Now Playing" width="250">
-  <img src="assets/screenshots/5.png" alt="Device Selection" width="250">
-  <img src="assets/screenshots/6.png" alt="Settings" width="250">
+  <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
 
-Download the latest release from the [Releases page](https://github.com/CollotsSpot/Assistant-To-The-Music/releases).
+Download the latest release from the [Releases page](https://github.com/CollotsSpot/Ensemble/releases).
 
 ## Setup
 
 1. Launch the app
-2. Navigate to the **Library** tab
-3. Tap **Configure Server** or go to **Settings**
-4. Enter your Music Assistant server URL (e.g., `music.example.com` or `192.168.1.100`)
-5. Tap **Connect**
-6. Browse your library and control playback on your Music Assistant players!
+2. Enter your Music Assistant server URL
+3. Connect to your server
+4. Start playing! Music plays on your phone by default, or swipe down on the mini player to choose a different player.
+
+### Finding Your Server URL
+
+**Important:** You need the **Music Assistant** URL, not your Home Assistant URL.
+
+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`)
+
+### 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 or later recommended)
+- 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)
 
-## About Music Assistant
+## Sponsors
 
-Amass Your Music is a remote control client for [Music Assistant](https://music-assistant.io/), an open-source music library manager and player that integrates with various music sources and streaming providers. You'll need a running Music Assistant server to use this app. Music playback happens on your Music Assistant server's configured players (speakers, smart devices, etc.), not on your mobile device.
+A huge thank you to my sponsors! 💖
 
-Learn more: [music-assistant.io](https://music-assistant.io/)
+<a href="https://github.com/pcsokonay"><img src="https://github.com/pcsokonay.png" width="60px" alt="pcsokonay" /></a>
 
 ## License
 
@@ -98,8 +195,8 @@ MIT License
 
 1. Clone the repository
 ```bash
-git clone https://github.com/CollotsSpot/AssistantToTheMusic.git
-cd AssistantToTheMusic
+git clone https://github.com/CollotsSpot/Ensemble.git
+cd Ensemble
 ```
 
 2. Install dependencies
@@ -125,9 +222,10 @@ The APK will be available at `build/app/outputs/flutter-apk/app-release.apk`
 <summary>Technologies Used</summary>
 
 - **Flutter** - Cross-platform mobile framework
-- **web_socket_channel** - WebSocket communication with Music Assistant server
+- **audio_service** - Background playback and media notifications
+- **web_socket_channel** - WebSocket communication with Music Assistant
 - **provider** - State management
+- **cached_network_image** - Image caching
 - **shared_preferences** - Local settings storage
-- **http** - HTTP requests for API communication
 
 </details>

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 |

TROUBLESHOOTING.md

@@ -1,642 +0,0 @@
-# Music Assistant Mobile - Troubleshooting Guide
-
-## Common Issues and Solutions
-
-### Connection Issues
-
-#### Problem: "Not Connected to Music Assistant"
-
-**Symptoms:**
-- App shows disconnected state
-- Cannot browse library
-- No players available
-
-**Solutions:**
-
-1. **Verify Server URL**
-   - Go to Settings
-   - Check server URL format: `https://ma.serverscloud.org` or `http://192.168.1.100:8095`
-   - Ensure no trailing slash
-   - Try both HTTP and HTTPS if unsure
-
-2. **Check Network Connectivity**
-   - Ensure device has internet/network access
-   - Try opening server URL in mobile browser
-   - Check if on same network (for local servers)
-
-3. **Verify Music Assistant Server**
-   - Ensure Music Assistant server is running
-   - Check server is accessible from your device
-   - Verify port 8095 (default) or custom port is open
-
-4. **Check Authentication**
-   - If using Authelia, verify credentials
-   - Try re-entering username/password
-   - Check Authelia is accessible
-
-5. **Clear App Data**
-   - Go to Settings → Clear all settings
-   - Re-enter server URL and credentials
-   - Restart app
-
-#### Problem: "WebSocket Connection Failed"
-
-**Symptoms:**
-- Connection drops frequently
-- "Connection timeout" errors in logs
-
-**Solutions:**
-
-1. **Check WebSocket Port**
-   - Default: 8095 for local, 443 for HTTPS
-   - Go to Settings → Custom WebSocket Port
-   - Try entering port explicitly
-
-2. **Verify Firewall Rules**
-   - Ensure WebSocket traffic is allowed
-   - Check reverse proxy configuration (if using)
-   - Cloudflare users: Ensure WebSocket support enabled
-
-3. **Test WebSocket Connection**
-   - Use browser dev tools to test WebSocket
-   - URL format: `wss://ma.serverscloud.org/ws`
-   - Look for successful upgrade to WebSocket
-
----
-
-### Authentication Issues
-
-#### Problem: "Login Failed" or "401 Unauthorized"
-
-**Symptoms:**
-- Cannot login with correct credentials
-- Session expires immediately
-- WebSocket authentication fails
-
-**Solutions:**
-
-1. **Verify Authelia Credentials**
-   - Double-check username and password
-   - Check Authelia domain is correct
-   - Try logging in via web browser first
-
-2. **Check Session Cookie**
-   - Cookie name should be `authelia_session`
-   - Check cookie is being set by Authelia
-   - Verify cookie domain matches
-
-3. **Clear Saved Credentials**
-   - Settings → Clear all settings
-   - Re-enter credentials
-   - Test login
-
-4. **Check Authelia Configuration**
-   - Ensure Authelia is properly configured
-   - Verify session timeout settings
-   - Check Authelia logs for errors
-
-#### Problem: "Auto-login Fails"
-
-**Symptoms:**
-- Must re-login every app start
-- "Auto-login failed" in logs
-
-**Solutions:**
-
-1. **Check Saved Credentials**
-   - Settings → Verify username is saved
-   - Password should be saved (not visible)
-   - Re-save credentials if needed
-
-2. **Session Timeout**
-   - Authelia session may have expired
-   - Check Authelia session duration
-   - Re-login to refresh session
-
----
-
-### Playback Issues
-
-#### Problem: "No Players Available"
-
-**Symptoms:**
-- Player selector shows empty list
-- Cannot select any player
-- Music won't play
-
-**Solutions:**
-
-1. **Refresh Player List**
-   - Open player selector (top right icon)
-   - Tap refresh icon
-   - Wait for players to load
-
-2. **Check Music Assistant Server**
-   - Verify players are configured in MA server
-   - Check players are powered on
-   - Ensure players are available
-
-3. **Wait for Initial Load**
-   - Players load on connection
-   - May take a few seconds
-   - Check debug logs for "Loaded X players"
-
-#### Problem: "Now Playing Bar Not Showing"
-
-**Symptoms:**
-- Music is playing but no mini-player appears
-- Cannot see current track
-
-**Solutions:**
-
-1. **Check Player Selection**
-   - Ensure a player is selected (green dot in player selector)
-   - Select player explicitly if needed
-
-2. **Verify Queue Has Items**
-   - Some players may not support queue state
-   - Try playing an album/track
-   - Check queue screen for items
-
-3. **Check Debug Logs**
-   - Look for "Error getting queue" messages
-   - Check for parsing errors
-   - Report specific error in GitHub issues
-
-4. **Force Refresh**
-   - Stop and restart playback
-   - Select different player, then select back
-   - Restart app
-
-#### Problem: "Cannot Control Playback"
-
-**Symptoms:**
-- Play/pause buttons don't work
-- Skip track buttons unresponsive
-
-**Solutions:**
-
-1. **Check Player State**
-   - Some players may not support all controls
-   - Verify player is powered on
-   - Check Music Assistant server logs
-
-2. **Network Latency**
-   - Commands may take 1-2 seconds
-   - Wait before clicking again
-   - Check network connection
-
-3. **Player Availability**
-   - Player may have disconnected
-   - Refresh player list
-   - Re-select player
-
----
-
-### Library Issues
-
-#### Problem: "No Artists/Albums/Tracks Found"
-
-**Symptoms:**
-- Empty library screens
-- "No items found" messages
-
-**Solutions:**
-
-1. **Check Music Assistant Library**
-   - Verify library is populated in MA server
-   - Scan library in MA web interface
-   - Ensure provider is configured
-
-2. **Force Library Reload**
-   - Pull down to refresh on library screens
-   - Go to home screen and back
-   - Restart app
-
-3. **Check API Limits**
-   - Default limit is 100 items
-   - May not show all items if library > 100
-   - Pagination planned for future release
-
-4. **Verify Connection**
-   - Ensure WebSocket is connected
-   - Check connection status on home screen
-   - Look for green dot indicator
-
-#### Problem: "Search Returns No Results"
-
-**Symptoms:**
-- Search finds nothing
-- Known items don't appear
-
-**Solutions:**
-
-1. **Check Search Query**
-   - Try partial matches
-   - Search is case-insensitive
-   - Wait for debounce (500ms)
-
-2. **Verify Library Content**
-   - Ensure items exist in MA library
-   - Test search in MA web interface
-   - Re-scan library if needed
-
-3. **Check Network**
-   - Search requires active connection
-   - Verify WebSocket is connected
-   - Try again with better connection
-
----
-
-### Queue Issues
-
-#### Problem: "Queue Screen Shows Empty"
-
-**Symptoms:**
-- Queue screen has no items
-- Music is playing but queue empty
-
-**Solutions:**
-
-1. **Check Player Type**
-   - Some players may not support queue viewing
-   - Try different player
-   - Check MA server capabilities
-
-2. **Refresh Queue**
-   - Tap refresh icon in queue screen
-   - Play a new album/track
-   - Restart playback
-
-3. **API Issues**
-   - Check logs for "Error getting queue"
-   - May be API parsing issue
-   - Report bug with logs
-
-#### Problem: "Cannot Reorder/Remove Queue Items"
-
-**Symptoms:**
-- Drag and drop doesn't work
-- Swipe to dismiss fails
-
-**Solutions:**
-
-1. **API Support**
-   - Reordering/removing is local only (currently)
-   - Server sync not yet implemented
-   - Changes won't persist on server
-
-2. **UI Issues**
-   - Ensure you're dragging from handle icon
-   - Swipe fully to left to dismiss
-   - Try on different queue items
-
----
-
-### Performance Issues
-
-#### Problem: "App is Slow/Laggy"
-
-**Symptoms:**
-- UI stutters
-- Slow navigation
-- Delayed responses
-
-**Solutions:**
-
-1. **Clear App Cache**
-   - Settings → Clear all settings
-   - Restart app
-   - May improve performance
-
-2. **Reduce Polling**
-   - Player state polls every 2 seconds
-   - Expected behavior for now
-   - Future: Event-based updates
-
-3. **Check Device Performance**
-   - Close other apps
-   - Restart device
-   - Check available storage
-
-4. **Network Latency**
-   - Test network speed
-   - Move closer to WiFi
-   - Try different network
-
-#### Problem: "High Battery Drain"
-
-**Symptoms:**
-- Battery drains quickly
-- App using lots of background power
-
-**Solutions:**
-
-1. **Polling Frequency**
-   - Player state polling uses power
-   - Will be optimized in future
-   - Close app when not in use
-
-2. **Background Activity**
-   - App doesn't support background playback yet
-   - Ensure app is closed when done
-   - Check battery settings
-
----
-
-### UI Issues
-
-#### Problem: "Images Not Loading"
-
-**Symptoms:**
-- Album/artist artwork missing
-- Broken image icons
-
-**Solutions:**
-
-1. **Check Network**
-   - Images load from server
-   - Requires active connection
-   - Try refreshing
-
-2. **Verify Image URLs**
-   - Check MA server has artwork
-   - Test image URL in browser
-   - May be missing for some items
-
-3. **Server Configuration**
-   - Check image proxy settings
-   - Verify image API endpoint
-   - Check CORS configuration
-
-#### Problem: "Screen Layout Broken"
-
-**Symptoms:**
-- Overlapping elements
-- Text cut off
-- Weird spacing
-
-**Solutions:**
-
-1. **Restart App**
-   - Force close and reopen
-   - May fix temporary layout issues
-
-2. **Check Device**
-   - Test on different screen size
-   - May be device-specific issue
-   - Report with device model
-
----
-
-## Debug Logging
-
-### Enabling Logs
-
-Logs are always enabled and print to console. To view:
-
-**Android Studio / VS Code:**
-1. Run app in debug mode
-2. Open Debug Console
-3. Look for timestamped logs: `[HH:MM:SS.mmm] Message`
-
-**Physical Device:**
-1. Connect via USB
-2. Run `flutter logs`
-3. Filter for app logs
-
-### Important Log Messages
-
-**Connection:**
-- `Connected to Music Assistant successfully` - Connection established
-- `WebSocket error: ...` - Connection problem
-- `Connection timeout` - Server not responding
-
-**Authentication:**
-- `🔑 Adding session cookie to WebSocket handshake` - Auth in progress
-- `✓ Authenticated` - Auth successful
-- `⚠️ Auto-login failed` - Credentials issue
-
-**Players:**
-- `Loaded X players` - Player list fetched
-- `Selected player: Name (ID)` - Player selected
-- `Using cached player list` - Cache hit
-
-**Queue:**
-- `🔍 DEBUG: First queue item raw data` - Queue structure
-- `Error getting queue: ...` - Queue fetch failed
-- `⚠️ Failed to parse queue item` - Parsing error
-
-**Playback:**
-- `Playing X tracks via queue on player Y` - Playback started
-- `✓ X tracks queued successfully` - Queue successful
-
-### Reporting Bugs
-
-When reporting issues, include:
-
-1. **Steps to Reproduce**
-   - Exact actions taken
-   - Expected vs actual behavior
-
-2. **Debug Logs**
-   - Copy relevant log section
-   - Include timestamps
-   - Show 10-20 lines before/after error
-
-3. **Environment**
-   - Device model and OS version
-   - App version
-   - Music Assistant server version
-   - Network type (WiFi, cellular, etc.)
-
-4. **Screenshots**
-   - Error messages
-   - UI issues
-   - Settings screen
-
----
-
-## Known Limitations
-
-### Current Constraints
-
-1. **Library Pagination**
-   - Loads max 100 items per category
-   - Infinite scroll coming soon
-
-2. **Queue Management**
-   - Reorder/remove only local
-   - Server sync not implemented
-   - Changes don't persist
-
-3. **Player State**
-   - Polls every 2 seconds
-   - Event-based updates coming
-   - May have slight delay
-
-4. **Search**
-   - Searches entire library only
-   - No category-specific search
-   - No search history
-
-5. **Offline Mode**
-   - No offline playback
-   - Requires active connection
-   - Planned for future
-
-### Planned Improvements
-
-See ARCHITECTURE.md → Future Enhancements for roadmap.
-
----
-
-## Advanced Troubleshooting
-
-### WebSocket Debugging
-
-1. **Chrome DevTools Method**
-   ```
-   1. Open ma.serverscloud.org in Chrome
-   2. F12 → Network tab
-   3. Filter: WS (WebSocket)
-   4. Look for /ws connection
-   5. Inspect frames (messages)
-   ```
-
-2. **Test WebSocket Manually**
-   ```javascript
-   const ws = new WebSocket('wss://ma.serverscloud.org/ws');
-   ws.onopen = () => console.log('Connected');
-   ws.onmessage = (e) => console.log('Message:', e.data);
-   ws.onerror = (e) => console.error('Error:', e);
-   ```
-
-### API Testing
-
-Use Music Assistant's web interface to test API:
-1. Open developer tools
-2. Go to Network tab
-3. Perform action (search, play, etc.)
-4. Inspect WebSocket messages
-5. Compare with app behavior
-
-### Flutter Debugging
-
-**DevTools:**
-```bash
-flutter pub global activate devtools
-flutter pub global run devtools
-```
-
-**Widget Inspector:**
-- Shows widget tree
-- Inspect layout issues
-- Debug rendering
-
-**Performance:**
-- Profile mode: `flutter run --profile`
-- Check frame rendering times
-- Monitor memory usage
-
----
-
-## Getting Help
-
-### Support Channels
-
-1. **GitHub Issues**
-   - Bug reports
-   - Feature requests
-   - Technical discussions
-   - URL: https://github.com/CollotsSpot/music-assistant-mobile/issues
-
-2. **Music Assistant Community**
-   - Discord server
-   - Forum discussions
-   - General questions
-   - URL: https://music-assistant.io/
-
-3. **Documentation**
-   - ARCHITECTURE.md - Technical details
-   - README.md - Getting started
-   - Code comments - Implementation details
-
-### Before Asking
-
-1. Check this troubleshooting guide
-2. Search existing GitHub issues
-3. Check Music Assistant docs
-4. Test with Music Assistant web interface
-5. Gather debug logs
-
-### Providing Feedback
-
-**Bug Report Template:**
-```
-**Description**
-[Clear description of the issue]
-
-**Steps to Reproduce**
-1. Step one
-2. Step two
-3. ...
-
-**Expected Behavior**
-[What should happen]
-
-**Actual Behavior**
-[What actually happens]
-
-**Logs**
-[Relevant log excerpt]
-
-**Environment**
-- Device: [e.g. Samsung Galaxy S21]
-- OS: [e.g. Android 13]
-- App Version: [e.g. 1.0.0]
-- MA Server Version: [e.g. 2.7.0]
-
-**Screenshots**
-[If applicable]
-```
-
----
-
-## FAQ
-
-### Q: Does the app support offline playback?
-**A:** Not currently. All playback requires connection to Music Assistant server.
-
-### Q: Can I use this with multiple Music Assistant servers?
-**A:** Not simultaneously, but you can change servers in Settings.
-
-### Q: Why isn't my local file library showing?
-**A:** Check Music Assistant server has scanned your local files and the provider is enabled.
-
-### Q: Does it support Android Auto / CarPlay?
-**A:** Not yet, but planned for future releases.
-
-### Q: Can I download music for offline listening?
-**A:** Not currently supported.
-
-### Q: How do I update the app?
-**A:** Updates will be distributed via app stores once released. Currently, build from source.
-
-### Q: Is my password stored securely?
-**A:** Yes, credentials are stored using Flutter's secure storage mechanisms.
-
-### Q: Can I control playback when screen is off?
-**A:** Background playback is limited. The app is designed for active use currently.
-
-### Q: Why can't I see all my albums?
-**A:** Current limit is 100 items per category. Pagination coming soon.
-
-### Q: Does it work with Spotify/YouTube/etc?
-**A:** Yes, if configured as providers in Music Assistant server.
-
----
-
-**Last Updated:** 2025-01-22
-**App Version:** Development Build
-**Music Assistant Version:** 2.7.0+

WORK_SUMMARY.md

@@ -1,299 +0,0 @@
-# Music Assistant Mobile - Implementation Summary
-
-This document summarizes all the features and improvements implemented during the overnight development session.
-
-## 🎯 Overview
-
-This was an intensive development session focused on transforming the Music Assistant mobile app from a basic prototype into a feature-rich, production-ready music player with comprehensive functionality, robust error handling, and extensive test coverage.
-
-## ✨ Major Features Implemented
-
-### 1. Playlist Support
-**Files Added:**
-- `lib/screens/playlist_details_screen.dart`
-- `lib/widgets/playlist_row.dart`
-
-**Features:**
-- Browse playlists from all providers (Spotify, local library, etc.)
-- View playlist details with track listings
-- Play entire playlists with queue management
-- Play individual tracks from playlists
-- Beautiful UI with album artwork and metadata
-- Provider-specific playlist support
-
-### 2. Favorites System
-**Files Modified:**
-- `lib/providers/music_assistant_provider.dart`
-- `lib/services/music_assistant_api.dart`
-- `lib/screens/*_details_screen.dart`
-
-**Features:**
-- Mark/unmark tracks, albums, and artists as favorites
-- Persistent favorites sync with Music Assistant server
-- Visual indicators for favorited items (filled heart icons)
-- Real-time UI updates when toggling favorites
-- Error handling for favorite operations
-
-### 3. Volume Control
-**Files Added:**
-- `lib/widgets/volume_control.dart`
-
-**Features:**
-- Full volume slider with live adjustment
-- Mute/unmute toggle
-- Visual volume percentage display
-- Compact mode for mini player (mute button only)
-- Smooth UI with pending volume tracking
-- Dynamic volume icons (off/down/up)
-
-### 4. Shuffle & Repeat Modes
-**Files Modified:**
-- `lib/models/player.dart` (added shuffle/repeat to PlayerQueue)
-- `lib/providers/music_assistant_provider.dart` (added control methods)
-- `lib/screens/now_playing_screen.dart` (added UI controls)
-
-**Features:**
-- Shuffle toggle with visual state indication
-- Repeat modes: Off, One, All
-- Persistent state across sessions
-- Visual feedback with icon states
-- Integration with Music Assistant queue
-
-### 5. Retry Logic with Exponential Backoff
-**Files Added:**
-- `lib/services/retry_helper.dart`
-
-**Features:**
-- Generic retry mechanism for any async operation
-- Exponential backoff (2s → 4s → 8s → 16s)
-- Network-specific retry logic
-- Critical operation retry mode
-- Configurable max attempts and delays
-- Smart error detection for retryable errors
-- Comprehensive logging
-
-### 6. Error Handling System
-**Files Added:**
-- `lib/services/error_handler.dart`
-
-**Features:**
-- User-friendly error messages
-- Error type classification (connection, network, auth, playback, library)
-- Technical vs. user-facing messages
-- Retryability detection
-- Comprehensive error logging
-- Context-aware error handling
-
-### 7. Search Functionality
-**Files Added:**
-- `lib/screens/search_screen.dart`
-- `lib/services/search_service.dart`
-
-**Features:**
-- Global search across tracks, albums, artists, playlists
-- Real-time search results
-- Debounced search input
-- Category filtering
-- Direct playback from search results
-- Navigation to detail screens
-
-### 8. Home Page Enhancements
-**Files Modified:**
-- `lib/screens/home_screen.dart`
-- `lib/widgets/album_row.dart`
-
-**Features:**
-- Recent albums section
-- Random albums discovery
-- Library statistics display
-- Horizontal scrolling album rows
-- Beautiful album artwork display
-- Quick navigation to album details
-
-### 9. Queue Management
-**Files Added:**
-- `lib/screens/queue_screen.dart`
-
-**Features:**
-- View current playback queue
-- Visual indicator for currently playing track
-- Track numbers and metadata
-- Album artwork for each track
-- Shuffle and repeat controls
-- Clear queue functionality
-- Jump to any track in queue
-
-### 10. Pull-to-Refresh
-**Files Modified:**
-- All library screens (albums, artists, tracks, playlists)
-
-**Features:**
-- Swipe down to refresh library content
-- Visual refresh indicator
-- Background data reload
-- Smooth animations
-- Maintained scroll position
-
-### 11. Player List Caching
-**Files Modified:**
-- `lib/providers/music_assistant_provider.dart`
-
-**Features:**
-- Cache player list for 30 seconds
-- Reduced API calls
-- Faster UI updates
-- Background refresh
-- Cache invalidation on manual refresh
-
-### 12. Comprehensive Unit Tests
-**Files Added:**
-- `test/models/media_item_test.dart`
-- `test/models/player_test.dart`
-- `test/services/retry_helper_test.dart`
-- `test/services/error_handler_test.dart`
-
-**Coverage:**
-- 130+ test cases
-- MediaItem model tests (Track, Album, Artist, Playlist, Radio)
-- Player model tests (Player, QueueItem, PlayerQueue, StreamDetails)
-- RetryHelper service tests
-- ErrorHandler service tests
-- JSON parsing validation
-- Null safety verification
-- Edge case handling
-- Default value testing
-
-### 13. Playback Quality Settings
-**Files Added:**
-- `lib/models/settings.dart`
-- `lib/providers/settings_provider.dart`
-- `lib/screens/playback_settings_screen.dart`
-
-**Files Modified:**
-- `lib/main.dart` (added SettingsProvider)
-- `lib/screens/settings_screen.dart` (added navigation)
-
-**Features:**
-- Audio quality preferences (Lossless/Lossy)
-- Quality levels: Low (96 kbps), Normal (128 kbps), High (256 kbps), Very High (320 kbps)
-- Configurable max bitrate
-- Prefer lossless (FLAC) option
-- Network settings (cellular streaming, downloads)
-- Appearance settings (album art, animations)
-- Settings persistence with SharedPreferences
-- Reset to defaults functionality
-- Beautiful settings UI with sliders and toggles
-
-## 🐛 Bug Fixes
-
-### 1. Build Errors
-**Fixed:**
-- Missing `api` getter in MusicAssistantProvider
-- Null safety issues in multiple screens
-- Constructor parameter mismatches in AlbumDetailsScreen
-- Missing imports and dependencies
-
-### 2. Queue Item Parsing Failures
-**Fixed:**
-- Nested `media_item` structure handling
-- Null safety in MediaItem.fromJson
-- ProviderMapping null field defaults
-- QueueItem queue_item_id fallback logic
-- Comprehensive null checks throughout parsing
-
-### 3. Player Selection Issues
-**Fixed:**
-- Smart player selection based on playback state
-- Prioritize actually playing player over builtin
-- Maintain player selection when still available
-- Auto-select playing player on app launch
-- Refresh selected player state
-
-### 4. Now Playing Display
-**Fixed:**
-- Stale queue data from parsing failures
-- Wrong track information display
-- Player-queue mismatch
-- Current item detection
-
-## 📊 Statistics
-
-### Code Added
-- **New Files:** 20+
-- **Modified Files:** 30+
-- **Lines of Code:** ~5,000+
-- **Test Cases:** 130+
-- **Commits:** 20
-
-### Features Breakdown
-- **UI Screens:** 6 new screens
-- **Widgets:** 8 new reusable widgets
-- **Services:** 4 new service classes
-- **Models:** 3 new model classes
-- **Providers:** 2 new state management providers
-
-## 🏗️ Architecture Improvements
-
-### State Management
-- Proper use of Provider pattern
-- ChangeNotifier for reactive UI
-- Separation of concerns
-- Clean data flow
-
-### Error Handling
-- Centralized error handling service
-- User-friendly error messages
-- Comprehensive logging
-- Retry mechanisms
-
-### Code Quality
-- Null safety throughout
-- Defensive programming
-- Comprehensive tests
-- Clear documentation
-
-### Performance
-- Caching strategies
-- Debounced operations
-- Optimized API calls
-- Smooth animations
-
-## 🚀 Ready for Production
-
-The app now includes:
-- ✅ Comprehensive feature set
-- ✅ Robust error handling
-- ✅ Extensive test coverage
-- ✅ User-configurable settings
-- ✅ Smooth, polished UI
-- ✅ Performance optimizations
-- ✅ Production-ready code quality
-
-## 📝 Commit History
-
-```
-f6c0c88 Add comprehensive unit tests and playback quality settings
-56cd6ef Fix player selection to show correct now playing information
-18d74e9 Improve null safety in JSON parsing for queue items and media items
-f3c5c66 Fix QueueItem parsing - track data is nested in media_item field
-ace810a Fix AlbumDetailsScreen constructor call - remove extra parameters
-649583e Fix build errors - null safety and API access issues
-3bce979 Implement shuffle and repeat modes for queue control
-7f4730a Add volume control for Music Assistant players
-fcb038a Improve error handling with user-friendly messages
-db0cefe Add retry logic with exponential backoff for network resilience
-d0ab37e Add favorites system
-d7949a3 Add comprehensive playlist support
-e24b542 Add player list caching to reduce API calls
-4f7856e Add pull-to-refresh to library screens
-ad4136f Add queue viewer screen with management capabilities
-6c291f7 Add search functionality to home and library screens
-38b29cb Add home page enhancements - recent albums, random albums, and stats
-965bf9d Add defensive parsing and debug logging for queue items
-```
-
-## 🎉 Conclusion
-
-This intensive development session successfully transformed the Music Assistant mobile app into a feature-complete, production-ready application. The app now provides a rich music listening experience with comprehensive playback controls, library management, search, playlists, favorites, quality settings, and robust error handling - all backed by extensive test coverage.
-
-The codebase is clean, well-structured, and ready for deployment. All major features are implemented, tested, and committed to the repository.

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,11 @@ android {
             signingConfig keystorePropertiesFile.exists() ? signingConfigs.release : signingConfigs.debug
         }
     }
+
+    dependenciesInfo {
+        includeInApk = false
+        includeInBundle = false
+    }
 }
 
 flutter {

android/app/src/main/AndroidManifest.xml

@@ -1,14 +1,23 @@
 <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"/>
     <uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK"/>
+    <uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>
 
     <application
-        android:label="ATTM"
+        android:label="Ensemble"
         android:name="${applicationName}"
         android:icon="@mipmap/ic_launcher"
+        android:appCategory="audio"
         android:usesCleartextTraffic="true"
         android:networkSecurityConfig="@xml/network_security_config">
         <activity
@@ -45,6 +54,16 @@
             </intent-filter>
         </receiver>
 
+        <provider
+            android:name=".ArtworkContentProvider"
+            android:authorities="com.collotsspot.ensemble.artwork"
+            android:exported="true"
+            android:grantUriPermissions="true" />
+
+        <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/ArtworkContentProvider.kt

@@ -0,0 +1,84 @@
+package com.collotsspot.ensemble
+
+import android.content.ContentProvider
+import android.content.ContentValues
+import android.database.Cursor
+import android.net.Uri
+import android.os.ParcelFileDescriptor
+import android.util.Base64
+import java.io.File
+import java.net.HttpURLConnection
+import java.net.URL
+import java.security.MessageDigest
+
+/**
+ * ContentProvider that serves artwork images to Android Auto.
+ *
+ * Android Auto only supports content:// and android.resource:// URIs for artwork.
+ * This provider accepts a base64url-encoded HTTP URL in the path, downloads the
+ * image (with disk caching), and returns a ParcelFileDescriptor.
+ *
+ * URI format: content://com.collotsspot.ensemble.artwork/{base64url_encoded_http_url}
+ */
+class ArtworkContentProvider : ContentProvider() {
+
+    companion object {
+        private const val CONNECT_TIMEOUT_MS = 5000
+        private const val READ_TIMEOUT_MS = 10000
+    }
+
+    override fun onCreate(): Boolean = true
+
+    override fun openFile(uri: Uri, mode: String): ParcelFileDescriptor? {
+        val encoded = uri.lastPathSegment ?: return null
+        val httpUrl: String
+        try {
+            httpUrl = String(Base64.decode(encoded, Base64.URL_SAFE or Base64.NO_WRAP))
+        } catch (e: Exception) {
+            return null
+        }
+
+        val cacheDir = File(context?.cacheDir, "artwork")
+        if (!cacheDir.exists()) cacheDir.mkdirs()
+
+        val hash = md5(httpUrl)
+        val cacheFile = File(cacheDir, hash)
+
+        if (!cacheFile.exists()) {
+            try {
+                val connection = URL(httpUrl).openConnection() as HttpURLConnection
+                connection.connectTimeout = CONNECT_TIMEOUT_MS
+                connection.readTimeout = READ_TIMEOUT_MS
+                connection.instanceFollowRedirects = true
+                try {
+                    connection.inputStream.use { input ->
+                        cacheFile.outputStream().use { output ->
+                            input.copyTo(output)
+                        }
+                    }
+                } finally {
+                    connection.disconnect()
+                }
+            } catch (e: Exception) {
+                cacheFile.delete()
+                return null
+            }
+        }
+
+        return ParcelFileDescriptor.open(cacheFile, ParcelFileDescriptor.MODE_READ_ONLY)
+    }
+
+    override fun query(uri: Uri, projection: Array<String>?, selection: String?,
+                       selectionArgs: Array<String>?, sortOrder: String?): Cursor? = null
+    override fun getType(uri: Uri): String = "image/*"
+    override fun insert(uri: Uri, values: ContentValues?): Uri? = null
+    override fun delete(uri: Uri, selection: String?, selectionArgs: Array<String>?): Int = 0
+    override fun update(uri: Uri, values: ContentValues?, selection: String?,
+                        selectionArgs: Array<String>?): Int = 0
+
+    private fun md5(input: String): String {
+        val digest = MessageDigest.getInstance("MD5")
+        val bytes = digest.digest(input.toByteArray())
+        return bytes.joinToString("") { "%02x".format(it) }
+    }
+}

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

@@ -0,0 +1,309 @@
+package com.collotsspot.ensemble
+
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import android.content.IntentFilter
+import android.database.ContentObserver
+import android.hardware.display.DisplayManager
+import android.media.AudioManager
+import android.os.Build
+import android.os.Handler
+import android.os.Looper
+import android.provider.Settings
+import android.app.UiModeManager
+import android.util.Log
+import android.view.Display
+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 val AA_CHANNEL = "com.collotsspot.ensemble/android_auto"
+    private var methodChannel: MethodChannel? = null
+    private var aaChannel: MethodChannel? = null
+    private var carModeReceiver: BroadcastReceiver? = 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
+
+    // Android Auto projection tracking via display listener
+    private var isAATracked = false
+    private var displayListener: DisplayManager.DisplayListener? = null
+
+    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()
+                }
+            }
+        }
+
+        // Android Auto / car mode detection
+        aaChannel = MethodChannel(flutterEngine.dartExecutor.binaryMessenger, AA_CHANNEL)
+
+        // Receive AA connection signal from Dart side
+        aaChannel?.setMethodCallHandler { call, result ->
+            when (call.method) {
+                "notifyAAConnected" -> {
+                    Log.d(TAG, "AA tracked via Dart notifyAAConnected")
+                    isAATracked = true
+                    result.success(null)
+                }
+                else -> result.notImplemented()
+            }
+        }
+
+        carModeReceiver = object : BroadcastReceiver() {
+            override fun onReceive(context: Context, intent: Intent) {
+                when (intent.action) {
+                    UiModeManager.ACTION_ENTER_CAR_MODE -> {
+                        Log.d(TAG, "Car mode ENTERED")
+                        isAATracked = true
+                        aaChannel?.invokeMethod("onAndroidAutoConnected", null)
+                    }
+                    UiModeManager.ACTION_EXIT_CAR_MODE -> {
+                        Log.d(TAG, "Car mode EXITED")
+                        aaChannel?.invokeMethod("onAndroidAutoDisconnected", null)
+                    }
+                }
+            }
+        }
+        val carModeFilter = IntentFilter().apply {
+            addAction(UiModeManager.ACTION_ENTER_CAR_MODE)
+            addAction(UiModeManager.ACTION_EXIT_CAR_MODE)
+        }
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
+            applicationContext.registerReceiver(carModeReceiver, carModeFilter, Context.RECEIVER_EXPORTED)
+        } else {
+            applicationContext.registerReceiver(carModeReceiver, carModeFilter)
+        }
+
+        // Detect AA disconnect via display removal (projection mode)
+        val dm = getSystemService(Context.DISPLAY_SERVICE) as DisplayManager
+        displayListener = object : DisplayManager.DisplayListener {
+            override fun onDisplayAdded(displayId: Int) {}
+            override fun onDisplayChanged(displayId: Int) {}
+            override fun onDisplayRemoved(displayId: Int) {
+                if (!isAATracked) return
+                val hasExtraDisplay = dm.displays.any {
+                    it.displayId != Display.DEFAULT_DISPLAY
+                }
+                if (!hasExtraDisplay) {
+                    Log.d(TAG, "AA projection ended (all extra displays removed)")
+                    isAATracked = false
+                    aaChannel?.invokeMethod("onAndroidAutoDisconnected", null)
+                }
+            }
+        }
+        dm.registerDisplayListener(displayListener, Handler(Looper.getMainLooper()))
+    }
+
+    /// 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()
+        carModeReceiver?.let {
+            try { applicationContext.unregisterReceiver(it) } catch (_: Exception) {}
+        }
+        displayListener?.let {
+            val dm = getSystemService(Context.DISPLAY_SERVICE) as DisplayManager
+            dm.unregisterDisplayListener(it)
+        }
+        super.onDestroy()
+    }
+}

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

@@ -1,6 +0,0 @@
-package com.musicassistant.music_assistant
-
-import io.flutter.embedding.android.FlutterActivity
-
-class MainActivity: FlutterActivity() {
-}

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_favorite_off.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="M16.5,3c-1.74,0 -3.41,0.81 -4.5,2.09C10.91,3.81 9.24,3 7.5,3 4.42,3 2,5.42 2,8.5c0,3.78 3.4,6.86 8.55,11.54L12,21.35l1.45,-1.32C18.6,15.36 22,12.28 22,8.5 22,5.42 19.58,3 16.5,3zM12.1,18.55l-0.1,0.1 -0.1,-0.1C7.14,14.24 4,11.39 4,8.5 4,6.5 5.5,5 7.5,5c1.54,0 3.04,0.99 3.57,2.36h1.87C13.46,5.99 14.96,5 16.5,5c2,0 3.5,1.5 3.5,3.5 0,2.89 -3.14,5.74 -7.9,10.05z"/>
+</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/drawable/ic_auto_repeat.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="M7,7h10v3l4,-4 -4,-4v3H5v6h2V7zM17,17H7v-3l-4,4 4,4v-3h12v-6h-2v4z"/>
+</vector>

android/app/src/main/res/drawable/ic_auto_repeat_all.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="M7,7h10v3l4,-4 -4,-4v3H5v6h2V7zM17,17H7v-3l-4,4 4,4v-3h12v-6h-2v4z"/>
+  <path android:fillColor="#FFFFFF"
+      android:pathData="M4,22h16v2H4z"/>
+</vector>

android/app/src/main/res/drawable/ic_auto_repeat_one.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="M7,7h10v3l4,-4 -4,-4v3H5v6h2V7zM17,17H7v-3l-4,4 4,4v-3h12v-6h-2v4z"/>
+  <path android:fillColor="#FFFFFF"
+      android:pathData="M13,15V9h-1l-2,1v1h1.5v4z"/>
+</vector>

android/app/src/main/res/drawable/ic_auto_shuffle.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.59,9.17L5.41,4 4,5.41l5.17,5.17 1.42,-1.41zM14.5,4l2.04,2.04L4,18.59 5.41,20 17.96,7.46 20,9.5V4h-5.5zM14.83,13.41l-1.41,1.41 3.13,3.13L14.5,20H20v-5.5l-2.04,2.04 -3.13,-3.13z"/>
+</vector>

android/app/src/main/res/drawable/ic_auto_shuffle_on.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="M10.59,9.17L5.41,4 4,5.41l5.17,5.17 1.42,-1.41zM14.5,4l2.04,2.04L4,18.59 5.41,20 17.96,7.46 20,9.5V4h-5.5zM14.83,13.41l-1.41,1.41 3.13,3.13L14.5,20H20v-5.5l-2.04,2.04 -3.13,-3.13z"/>
+  <path android:fillColor="#FFFFFF"
+      android:pathData="M4,22h16v2H4z"/>
+</vector>

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

@@ -0,0 +1,13 @@
+<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">
+  <!-- Shuffle arrows -->
+  <path android:fillColor="#FFFFFF"
+      android:pathData="M10.59,9.17L5.41,4 4,5.41l5.17,5.17 1.42,-1.41zM14.5,4l2.04,2.04L4,18.59 5.41,20 17.96,7.46 20,9.5V4h-5.5zM14.83,13.41l-1.41,1.41 3.13,3.13L14.5,20H20v-5.5l-2.04,2.04 -3.13,-3.13z"/>
+  <!-- Sparkle -->
+  <path android:fillColor="#FFFFFF"
+      android:pathData="M19,1l-1.26,2.74L15,5l2.74,1.26L19,9l1.26,-2.74L23,5l-2.74,-1.26z"/>
+</vector>

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

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="utf-8"?>
+<vector xmlns:android="http://schemas.android.com/apk/res/android"
+    android:width="24dp"
+    android:height="24dp"
+    android:viewportWidth="24"
+    android:viewportHeight="24">
+    <!-- Swap/cycle arrows icon -->
+    <path
+        android:fillColor="#FFFFFF"
+        android:pathData="M12,6v3l4,-4 -4,-4v3c-4.42,0 -8,3.58 -8,8 0,1.57 0.46,3.03 1.24,4.26L6.7,14.8c-0.45,-0.83 -0.7,-1.79 -0.7,-2.8 0,-3.31 2.69,-6 6,-6zM18.76,7.74L17.3,9.2c0.44,0.84 0.7,1.79 0.7,2.8 0,3.31 -2.69,6 -6,6v-3l-4,4 4,4v-3c4.42,0 8,-3.58 8,-8 0,-1.57 -0.46,-3.03 -1.24,-4.26z"/>
+</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/raw/keep.xml

@@ -0,0 +1,3 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources xmlns:tools="http://schemas.android.com/tools"
+    tools:keep="@drawable/*,@drawable/audio_service_*" />

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"

cleanup_ghost_players.sh

@@ -1,93 +0,0 @@
-#!/bin/bash
-# Script to remove ghost "Music Assistant Mobile" players from Music Assistant
-
-set -e
-
-SETTINGS_FILE="/home/home-server/docker/music-assistant/data/settings.json"
-BACKUP_FILE="/home/home-server/docker/music-assistant/data/settings.json.pre-cleanup-backup"
-
-# Colors for output
-RED='\033[0;31m'
-GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
-NC='\033[0m' # No Color
-
-echo -e "${YELLOW}=== Music Assistant Ghost Player Cleanup ===${NC}"
-echo ""
-
-# Check if settings file exists
-if [ ! -f "$SETTINGS_FILE" ]; then
-    echo -e "${RED}Error: Settings file not found at $SETTINGS_FILE${NC}"
-    exit 1
-fi
-
-# Check if jq is installed
-if ! command -v jq &> /dev/null; then
-    echo -e "${RED}Error: jq is not installed. Install with: sudo apt install jq${NC}"
-    exit 1
-fi
-
-# Count ghost players before cleanup
-GHOST_COUNT=$(cat "$SETTINGS_FILE" | jq '[.players | to_entries[] | select(.value.default_name == "Music Assistant Mobile")] | length')
-
-echo -e "Found ${RED}$GHOST_COUNT${NC} ghost \"Music Assistant Mobile\" players"
-echo ""
-
-if [ "$GHOST_COUNT" -eq 0 ]; then
-    echo -e "${GREEN}No ghost players to remove!${NC}"
-    exit 0
-fi
-
-# List the ghost players
-echo "Ghost players to be removed:"
-cat "$SETTINGS_FILE" | jq -r '.players | to_entries[] | select(.value.default_name == "Music Assistant Mobile") | "  - " + .key'
-echo ""
-
-# Ask for confirmation
-read -p "Do you want to remove these players? (yes/no): " CONFIRM
-
-if [ "$CONFIRM" != "yes" ]; then
-    echo -e "${YELLOW}Cleanup cancelled.${NC}"
-    exit 0
-fi
-
-# Create backup
-echo ""
-echo -e "${YELLOW}Creating backup...${NC}"
-cp "$SETTINGS_FILE" "$BACKUP_FILE"
-echo -e "${GREEN}Backup created at: $BACKUP_FILE${NC}"
-
-# Remove ghost players
-echo ""
-echo -e "${YELLOW}Removing ghost players...${NC}"
-
-# Get list of ghost player IDs
-GHOST_IDS=$(cat "$SETTINGS_FILE" | jq -r '.players | to_entries[] | select(.value.default_name == "Music Assistant Mobile") | .key')
-
-# Remove each ghost player from settings
-for player_id in $GHOST_IDS; do
-    echo "  Removing: $player_id"
-done
-
-# Use jq to filter out ghost players
-cat "$SETTINGS_FILE" | jq '.players |= with_entries(select(.value.default_name != "Music Assistant Mobile"))' > "${SETTINGS_FILE}.tmp"
-mv "${SETTINGS_FILE}.tmp" "$SETTINGS_FILE"
-
-# Verify cleanup
-REMAINING=$(cat "$SETTINGS_FILE" | jq '[.players | to_entries[] | select(.value.default_name == "Music Assistant Mobile")] | length')
-
-echo ""
-if [ "$REMAINING" -eq 0 ]; then
-    echo -e "${GREEN}✓ Successfully removed all $GHOST_COUNT ghost players!${NC}"
-else
-    echo -e "${RED}Warning: $REMAINING ghost players still remain${NC}"
-fi
-
-echo ""
-echo -e "${YELLOW}Next steps:${NC}"
-echo "1. Restart Music Assistant: docker restart music_assistant"
-echo "2. Or: cd /home/home-server/docker/music-assistant && docker compose restart"
-echo ""
-echo -e "${YELLOW}To restore backup if needed:${NC}"
-echo "cp $BACKUP_FILE $SETTINGS_FILE"
-echo "Then restart Music Assistant"

docs/AUDIOBOOKS_IMPLEMENTATION_PLAN.md

@@ -0,0 +1,255 @@
+# Audiobooks Integration - Implementation Plan
+
+## Overview
+
+Add audiobook support to Ensemble with automatic user profile separation based on Music Assistant authentication. Includes local database for performance caching and per-user data isolation.
+
+---
+
+## Phase 1: Database Foundation
+
+**Goal:** Add persistent local storage layer using Drift (SQLite)
+
+### Tasks
+- [ ] Add Drift package dependencies (`drift`, `drift_flutter`, `path_provider`)
+- [ ] Create database class with schema version management
+- [ ] Create `profiles` table:
+  ```dart
+  class Profiles extends Table {
+    TextColumn get username => text()();  // MA username (primary key)
+    TextColumn get displayName => text().nullable()();
+    TextColumn get source => text()();  // 'ma_auth' or 'manual'
+    DateTimeColumn get createdAt => dateTime()();
+    BoolColumn get isActive => boolean().withDefault(const Constant(false))();
+  }
+  ```
+- [ ] Create `recently_played` table:
+  ```dart
+  class RecentlyPlayed extends Table {
+    IntColumn get id => integer().autoIncrement()();
+    TextColumn get profileUsername => text().references(Profiles, #username)();
+    TextColumn get mediaId => text()();
+    TextColumn get mediaType => text()();  // 'track', 'album', 'artist', 'audiobook'
+    TextColumn get name => text()();
+    TextColumn get artist => text().nullable()();
+    TextColumn get imageUrl => text().nullable()();
+    DateTimeColumn get playedAt => dateTime()();
+  }
+  ```
+- [ ] Create `library_cache` table for albums/artists/audiobooks
+- [ ] Generate Drift code (`dart run build_runner build`)
+- [ ] Create `DatabaseService` singleton with initialization
+
+### Acceptance Criteria
+- Database initializes on app startup
+- Schema migrations work correctly
+- CRUD operations functional for all tables
+
+---
+
+## Phase 2: Profile System
+
+**Goal:** Auto-create and manage user profiles based on MA authentication
+
+### Tasks
+- [ ] Create `ProfileService` class
+- [ ] On MA login success: check if profile exists for username
+  - If not, create new profile with `displayName` from MA user info
+  - Set as active profile
+- [ ] On manual name entry (no-auth): create/select profile by entered name
+- [ ] Add `getCurrentProfile()` method
+- [ ] Migrate existing `ownerName` to profile on first launch post-update
+- [ ] Add profile indicator to settings screen (show current profile name)
+
+### Acceptance Criteria
+- Profile auto-created on first login
+- Correct profile selected on subsequent logins
+- Existing users migrated seamlessly
+
+---
+
+## Phase 3: Recently Played Migration
+
+**Goal:** Move recently played from memory cache to database, scoped by profile
+
+### Tasks
+- [ ] Update `CacheService` to use database for recently played
+- [ ] Scope all recently played queries by `profileUsername`
+- [ ] Update home screen to load recently played from database
+- [ ] Add `addRecentlyPlayed()` method that records profile + media info
+- [ ] Limit recently played to last 50 items per profile
+- [ ] Remove old memory-based recently played logic
+
+### Acceptance Criteria
+- Recently played persists across app restarts
+- Each profile sees only their own recently played
+- No cross-contamination between profiles
+
+---
+
+## Phase 4: Library Caching
+
+**Goal:** Cache library data locally for instant UI and reduced API calls
+
+### Tasks
+- [ ] Create `SyncService` for background library synchronization
+- [ ] On app launch: load from cache immediately, sync in background
+- [ ] Store albums, artists in `library_cache` table
+- [ ] Add `lastSynced` timestamp to track freshness
+- [ ] Implement delta sync (only fetch changed items if MA supports it)
+- [ ] Add pull-to-refresh that forces full sync
+- [ ] Show subtle sync indicator when background sync in progress
+
+### Acceptance Criteria
+- Home screen loads instantly from cache
+- Library tabs load instantly
+- Background sync updates data without blocking UI
+- Stale data refreshed within reasonable timeframe
+
+---
+
+## Phase 5: Scrollable Library Tabs
+
+**Goal:** Make library tab row scrollable to accommodate more tabs
+
+### Tasks
+- [ ] Convert `TabBar` to scrollable variant (`isScrollable: true`)
+- [ ] Adjust tab styling for scrollable layout
+- [ ] Ensure indicator line spans correctly
+- [ ] Test with varying number of tabs
+- [ ] Add "Books" tab placeholder (disabled until Phase 6)
+
+### Acceptance Criteria
+- Tabs scroll horizontally when they exceed screen width
+- Current tab indicator works correctly
+- Smooth scrolling experience
+
+---
+
+## Phase 6: Audiobooks Tab - Browse by Author
+
+**Goal:** Add Books tab with author → books hierarchy
+
+### Tasks
+- [ ] Add MA API method to fetch audiobooks: `getAudiobooks()`
+- [ ] Add MA API method to fetch audiobook authors
+- [ ] Create `AudiobookAuthor` model
+- [ ] Create `Audiobook` model with fields:
+  - `id`, `name`, `authors`, `narrators`, `description`
+  - `duration`, `imageUrl`, `chapters`, `resumePosition`, `fullyPlayed`
+- [ ] Create `BooksScreen` with author list view
+- [ ] Tapping author expands to show their books
+- [ ] Add to library tab bar
+- [ ] Cache audiobooks in local database
+
+### Acceptance Criteria
+- Books tab shows list of authors
+- Authors expandable to show their audiobooks
+- Audiobook covers and titles display correctly
+- Data cached locally for fast subsequent loads
+
+---
+
+## Phase 7: Audiobook Detail Screen
+
+**Goal:** Full audiobook detail view with metadata and chapters
+
+### Tasks
+- [ ] Create `AudiobookDetailScreen`
+- [ ] Display: cover art, title, author(s), narrator(s)
+- [ ] Display: description (expandable if long)
+- [ ] Display: total duration, progress indicator
+- [ ] Chapter list with:
+  - Chapter title
+  - Duration
+  - Played indicator (based on resume position)
+- [ ] Tapping chapter starts playback from that chapter
+- [ ] "Resume" button that continues from `resume_position_ms`
+- [ ] "Start Over" option
+
+### Acceptance Criteria
+- All metadata displays correctly
+- Chapters show with accurate durations
+- Resume position reflected in UI
+- Can start playback from any chapter
+
+---
+
+## Phase 8: Audiobook Playback Integration
+
+**Goal:** Proper audiobook playback with seek and resume
+
+### Tasks
+- [ ] Implement `playAudiobook(bookId, startPosition?)` method
+- [ ] Use `queueCommandSeek()` to resume at correct position
+- [ ] Update now playing UI to show:
+  - Book title instead of track
+  - Current chapter name
+  - Chapter progress (not just total progress)
+- [ ] Add skip forward/back buttons (30 sec for audiobooks?)
+- [ ] Add chapter skip buttons (next/previous chapter)
+- [ ] Record to recently played when audiobook starts (with 'audiobook' type)
+
+### Acceptance Criteria
+- Audiobooks resume from correct position
+- Chapter information shows in now playing
+- Skip controls work correctly
+- Recently played records audiobook plays
+
+---
+
+## Phase 9: Polish & Edge Cases
+
+**Goal:** Handle edge cases and improve UX
+
+### Tasks
+- [ ] Handle audiobooks with no chapters gracefully
+- [ ] Handle very long audiobooks (20+ hours)
+- [ ] Add "Mark as Finished" option
+- [ ] Add "Mark as Unplayed" option
+- [ ] Ensure offline browsing works for cached audiobooks
+- [ ] Test with various audiobook lengths and chapter counts
+- [ ] Performance testing with large audiobook libraries
+
+### Acceptance Criteria
+- No crashes on edge cases
+- Smooth performance
+- All user actions have appropriate feedback
+
+---
+
+## Future Enhancements (Out of Scope)
+
+- Sleep timer
+- Playback speed control
+- Series support (requires MA provider update)
+- Bookmarks
+- Listening statistics
+- Download for offline playback
+
+---
+
+## Technical Notes
+
+### Database Choice: Drift
+- SQLite wrapper with type-safe queries
+- Good for relational data (profiles → recently_played)
+- Mature, well-documented
+- Supports migrations
+
+### MA API Endpoints Used
+- `music/audiobooks` - List audiobooks
+- `music/audiobook/{id}` - Get audiobook details
+- `player_queues/play_media` - Start playback
+- `player_queues/seek` - Seek to position
+- `music/in_progress_items` - Get items with resume positions
+
+### Profile Data Flow
+```
+MA Login → Get user_info → Check/Create Profile → Set Active → Load Profile Data
+```
+
+### Recently Played Flow
+```
+Play Media → Check Active Profile → Insert RecentlyPlayed Row → Update UI
+```

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.