chore: Bump version to 2.0.0-beta for release

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

AUDIT_PROGRESS.md

@@ -1,154 +0,0 @@
-# Ensemble App - Audit Progress Tracker
-
-**Audit Date:** 2025-12-08
-**Branch:** `refactor/audit-cleanup`
-**Overall Health Score:** 6.5/10 (before fixes)
-
----
-
-## Phase 1: Quick Wins (1-2 days)
-*Low effort, immediate impact*
-
-- [x] Remove unused `cupertino_icons` dependency from `pubspec.yaml`
-- [x] Remove 12 debug `print()` statements from `main.dart` (replaced with `_logger.log()`)
-- [x] Fix empty `setState(() {})` in progress timer (`expandable_player.dart`) - converted to `ValueNotifier`
-- [x] Fix empty `setState(() {})` on text input (`search_screen.dart`) - removed unnecessary setState
-- [x] Complete or remove TODO comments:
-  - [x] `queue_screen.dart` - enhanced comment with API requirements
-  - [x] `library_screen.dart` - **IMPLEMENTED** play track functionality
-  - [x] `expandable_player.dart` - enhanced comment with API limitations
-
----
-
-## Phase 2: Performance Fixes (2-3 days)
-*Medium effort, significant performance gains*
-
-- [x] Fix slider setState spam - use ValueNotifier pattern (`expandable_player.dart`)
-- [x] Replace volume polling with events (`volume_control.dart`) - removed polling loop
-- [x] Cache `Theme.of(context)` lookups - removed unused lookup in `search_screen.dart`
-- [x] Move `SystemChrome` out of build() (`main.dart`) - created SystemUIWrapper widget
-- [x] Replace `Image.network` with `CachedNetworkImage` (`expandable_player.dart`)
-- [x] Use `ListView.builder` instead of spread operators (`search_screen.dart`)
-
----
-
-## Phase 3: Dead Code Cleanup (1 day)
-*Consolidate and remove unused files*
-
-- [x] Delete unused `library_screen.dart` (old version, `new_library_screen.dart` is active)
-- [x] Remove unused `PlayerStateService` (`player_state_service.dart`)
-- [x] Remove unused `Player` import from `debug_log_screen.dart`
-
-Note: `new_home_screen.dart` and `new_library_screen.dart` are NOT dead code - they are
-the active screens used in `home_screen.dart`. The naming suggests they replaced older
-versions during a refactor.
-
----
-
-## Phase 4: State Management Refactor (3-4 days)
-*Split monolithic provider (2,106 lines)*
-
-- [x] Extract cache logic → `CacheService` (lib/services/cache_service.dart)
-- [x] Update `MusicAssistantProvider` to delegate caching to `CacheService`
-- [x] Delete unused `library_service.dart`
-- [ ] Extract connection logic → `ConnectionProvider` (skeleton created)
-- [ ] Extract library data → `LibraryProvider` (skeleton created)
-- [ ] Extract player state → `PlayerProvider` (skeleton created)
-- [ ] Remove global singleton (`navigation_provider.dart:40`)
-- [ ] Add stream filtering (`.distinct()`, `.where()`)
-
-**Note:** Phase 4 partial completion - extracted CacheService and reduced
-`music_assistant_provider.dart` from 2,106 to ~1,650 lines. Full provider
-split deferred as lower priority.
-
----
-
-## Phase 5: Widget Decomposition (3-4 days)
-*Split mega-widgets into focused components*
-
-### expandable_player.dart (1,365 → 1,150 lines) - DONE
-- [x] Extract `DeviceSelectorBar` → `lib/widgets/player/device_selector_bar.dart`
-- [x] Extract `QueuePanel` → `lib/widgets/player/queue_panel.dart`
-- [x] Create `PlayerControls` → `lib/widgets/player/player_controls.dart` (available for future use)
-
-### login_screen.dart (968 → 843 lines) - DONE
-- [x] Extract `DebugConsole` → `lib/widgets/debug/debug_console.dart`
-- [x] Extract `DebugToggleButton` → included in debug_console.dart
-
-### album_details_screen.dart (818 lines)
-- [ ] Extract `TrackListSection`
-- [ ] Extract `PlayOnBottomSheet` (shared)
-
-### search_screen.dart (516 lines)
-- [ ] Extract `MediaItemTile`
-- [ ] Extract `SearchFilters`
-
----
-
-## Phase 6: Code Deduplication (2-3 days)
-*Extract reusable widgets*
-
-- [ ] Create `MediaItemTile` (consolidate 3 list tile builders)
-- [ ] Create `PlayOnBottomSheet` (consolidate 4 implementations)
-- [x] Create `EmptyState` (consolidate 6+ implementations) → `lib/widgets/common/empty_state.dart`
-- [ ] Create `FilterChipRow` (consolidate 3 implementations)
-- [x] Create `DisconnectedState` (consolidate 3 implementations) → `lib/widgets/common/disconnected_state.dart`
-
-**Note:** Phase 6 partial completion - extracted EmptyState (8 usages, ~227 lines removed)
-and DisconnectedState (3 usages, ~140 lines removed). Total ~367 lines of duplicate code removed.
-
----
-
-## Phase 7: Design System (2 days)
-*Centralize hardcoded values*
-
-- [x] Create `lib/theme/design_tokens.dart`:
-  - [x] Spacing constants (Spacing class with xxs-xxxl scale)
-  - [x] Border radius constants (Radii class)
-  - [x] Icon size constants (IconSizes class)
-  - [x] Dimension constants (Dimensions class)
-  - [x] Animation duration constants (Durations class)
-- [x] Apply tokens to extracted widgets:
-  - [x] `empty_state.dart` - Spacing tokens
-  - [x] `disconnected_state.dart` - Spacing, IconSizes, Radii tokens
-  - [x] `queue_panel.dart` - Spacing, Radii, IconSizes tokens
-  - [x] `player_controls.dart` - Spacing tokens
-  - [x] `device_selector_bar.dart` - Spacing, IconSizes tokens
-  - [x] `debug_console.dart` - Spacing, Radii, IconSizes tokens
-- [ ] Continue replacing remaining hardcoded values (~223 remaining)
-- [ ] Create `lib/constants/strings.dart` (40+ strings)
-
----
-
-## Phase 8: Polish (Backlog)
-*Nice-to-have improvements*
-
-- [ ] Add Semantics labels for accessibility
-- [ ] Implement localization (i18n)
-- [ ] Add test coverage
-- [x] Implement WebSocket heartbeat (`music_assistant_api.dart` - ping every 30s)
-- [ ] Add responsive grid layouts for tablets
-- [x] Add completer guards to prevent double-completion (`music_assistant_api.dart`, `music_assistant_provider.dart`, `player_provider.dart`)
-
----
-
-## Completed Summary
-
-| Phase | Status | Completed Date |
-|-------|--------|----------------|
-| Phase 1 | **COMPLETED** | 2025-12-08 |
-| Phase 2 | **COMPLETED** | 2025-12-08 |
-| Phase 3 | **COMPLETED** | 2025-12-08 |
-| Phase 4 | **PARTIAL** | 2025-12-08 |
-| Phase 5 | **PARTIAL** | 2025-12-08 |
-| Phase 6 | **PARTIAL** | 2025-12-08 |
-| Phase 7 | **PARTIAL** | 2025-12-08 |
-| Phase 8 | **PARTIAL** | 2025-12-08 |
-
----
-
-## Notes
-
-- Original audit performed by 7 parallel sub-agents analyzing different aspects
-- Total LOC: 17,454 across 57 Dart files
-- Largest files: `music_assistant_provider.dart` (2,106), `music_assistant_api.dart` (1,948), `expandable_player.dart` (1,335)

README.md

@@ -3,7 +3,7 @@
 
 ---
 
-  <p>A minimalistic mobile client for <a href="https://music-assistant.io/">Music Assistant</a></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>
 
@@ -11,7 +11,9 @@
 
 ## 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**.
 
 ---
 
@@ -28,9 +30,18 @@ I am not a developer. This application was created using **Claude Code** and **G
 - **Full Playback Controls** - Play, pause, skip, seek, and adjust volume
 - **Queue Management** - View and manage the playback queue
 
+### Home Screen
+- **Customizable Rows** - Toggle Recently Played, Discover Artists, and Discover Albums
+- **Favorites Rows** - Optional rows for Favorite Albums, Artists, and Tracks
+- **Adaptive Layout** - Rows scale properly for different screen sizes and aspect ratios
+- **Pull to Refresh** - Refresh content with a simple pull gesture
+
 ### Library Browsing
-- **Browse Your Collection** - Artists, albums, and tracks from all your music sources
+- **Browse Your Collection** - Artists, albums, playlists, and tracks from all your music sources
+- **Favorites Filter** - Toggle to show only your favorite items
 - **Album Details** - View track listings with artwork
+- **Artist Details** - View artist albums and top tracks
+- **Playlist Support** - Browse and play your playlists
 - **Search** - Find music across your entire library
 
 ### Smart Features
@@ -89,16 +100,6 @@ Ensemble supports multiple authentication methods:
 
 > **Note:** Local device playback (streaming to your phone) is not currently supported on Music Assistant beta 20+. This is due to MA replacing the built-in player with Sendspin. Support will be added once Sendspin is more stable. Remote control of other players works fine.
 
-## About Music Assistant
-
-Ensemble is a mobile client for [Music Assistant](https://music-assistant.io/), an open-source music library manager that integrates with various music sources and streaming providers.
-
-With Ensemble, you can:
-- **Stream locally** - Use your phone as a Music Assistant player
-- **Control remotely** - Manage playback on smart speakers, Chromecast, Sonos, and more
-
-Learn more: [music-assistant.io](https://music-assistant.io/)
-
 ## License
 
 MIT License

analyses/ensemble-performance-audit.md

@@ -1,571 +0,0 @@
-# Ensemble Performance Audit: Animation Smoothness Optimization
-
-**Date**: 2025-12-05
-**Target**: Achieve buttery-smooth animations comparable to Symphonium media player
-**Branch**: performance/animation-smoothness
-**Auditor**: Claude Code
-
----
-
-## Executive Summary
-
-This audit focuses specifically on Flutter performance optimizations to achieve 60fps+ animations and eliminate jank in the Ensemble music player app. The codebase has good foundational work (RepaintBoundary on cards, image caching, AutomaticKeepAliveClientMixin), but there are several opportunities for improvement to match the smoothness of premium music players like Symphonium.
-
-### Performance Status
-
-**Current State:**
-- ✅ RepaintBoundary on AlbumCard and ArtistCard
-- ✅ Image caching with cacheWidth/cacheHeight
-- ✅ AutomaticKeepAliveClientMixin on row widgets
-- ⚠️ Missing keys on list items
-- ⚠️ Missing const constructors in many widgets
-- ⚠️ ListView.builder without itemExtent where applicable
-- ⚠️ setState calls could be more targeted
-- ⚠️ No state restoration (scroll positions lost on navigation)
-- ⚠️ Hero animations missing in Library screen
-
-### Performance Impact Categories
-
-| Category | Impact | Complexity | Priority |
-|----------|--------|------------|----------|
-| Quick Wins | High | Low | Critical |
-| Widget Rebuilds | High | Medium | High |
-| Animation Tuning | Medium | Low | High |
-| List Performance | Medium | Low | Medium |
-| State Restoration | Low | Medium | Low |
-
----
-
-## Category 1: Quick Wins (Immediate Impact, Low Effort)
-
-### QW-1: Add Missing `const` Constructors
-
-**Issue**: Many stateless widgets lack const constructors, causing unnecessary rebuilds.
-
-**Impact**: High - const widgets are cached by Flutter and reused, reducing rebuild overhead significantly.
-
-**Locations**:
-- `/home/home-server/Ensemble/lib/screens/library_artists_screen.dart:8` - LibraryArtistsScreen
-- `/home/home-server/Ensemble/lib/screens/library_albums_screen.dart:7` - LibraryAlbumsScreen
-- Various SizedBox, Padding, Icon widgets throughout
-
-**Fix**:
-```dart
-// Before:
-class LibraryArtistsScreen extends StatelessWidget {
-  LibraryArtistsScreen({super.key});
-
-// After:
-class LibraryArtistsScreen extends StatelessWidget {
-  const LibraryArtistsScreen({super.key});
-```
-
-**Estimated Savings**: 5-10% reduction in widget rebuilds
-
----
-
-### QW-2: Add Keys to List Items
-
-**Issue**: ListView.builder and GridView.builder items lack keys, causing Flutter to rebuild entire items instead of reusing them.
-
-**Impact**: High - Without keys, Flutter can't track widgets during list updates, causing full rebuilds.
-
-**Locations**:
-- `/home/home-server/Ensemble/lib/screens/library_artists_screen.dart:88-95` - Artists list
-- `/home/home-server/Ensemble/lib/screens/library_albums_screen.dart:87-103` - Albums grid
-- `/home/home-server/Ensemble/lib/widgets/album_row.dart:89-104` - Album horizontal list
-- `/home/home-server/Ensemble/lib/widgets/artist_row.dart:89-104` - Artist horizontal list
-
-**Fix**:
-```dart
-// Before:
-itemBuilder: (context, index) {
-  final artist = provider.artists[index];
-  return _buildArtistTile(context, artist, provider);
-}
-
-// After:
-itemBuilder: (context, index) {
-  final artist = provider.artists[index];
-  return _buildArtistTile(
-    context,
-    artist,
-    provider,
-    key: ValueKey(artist.uri ?? artist.itemId),
-  );
-}
-```
-
-**Estimated Savings**: 15-25% reduction in list scroll jank
-
----
-
-### QW-3: Add itemExtent to Horizontal Lists
-
-**Issue**: Horizontal lists don't specify itemExtent, forcing Flutter to measure every item.
-
-**Impact**: Medium - itemExtent allows Flutter to calculate layout without measuring, improving scroll performance.
-
-**Locations**:
-- `/home/home-server/Ensemble/lib/widgets/album_row.dart:89` - Fixed width of 150 + 12 margins = 162
-- `/home/home-server/Ensemble/lib/widgets/artist_row.dart:89` - Fixed width of 120 + 16 margins = 136
-
-**Fix**:
-```dart
-// Before:
-ListView.builder(
-  scrollDirection: Axis.horizontal,
-  itemCount: albums.length,
-  itemBuilder: ...
-
-// After:
-ListView.builder(
-  scrollDirection: Axis.horizontal,
-  itemCount: albums.length,
-  itemExtent: 162, // Width + margins
-  itemBuilder: ...
-```
-
-**Estimated Savings**: 10-15% improvement in horizontal scroll smoothness
-
----
-
-### QW-4: Add RepaintBoundary to List Tiles
-
-**Issue**: Artist list tiles in library screens lack RepaintBoundary, causing entire lists to repaint.
-
-**Impact**: Medium - RepaintBoundary isolates repaints to individual tiles.
-
-**Locations**:
-- `/home/home-server/Ensemble/lib/screens/library_artists_screen.dart:99-134` - Artist tiles
-- `/home/home-server/Ensemble/lib/screens/new_library_screen.dart` - Library artist tiles (around line 200)
-
-**Fix**:
-```dart
-Widget _buildArtistTile(...) {
-  return RepaintBoundary(
-    child: ListTile(
-      leading: CircleAvatar(...),
-      title: Text(...),
-      onTap: () {...},
-    ),
-  );
-}
-```
-
-**Estimated Savings**: 5-10% reduction in repaint overhead
-
----
-
-### QW-5: Fix Library Screen Hero Animations
-
-**Issue**: Library screen artist tiles are missing Hero widgets, breaking animations to ArtistDetailsScreen.
-
-**Impact**: High (UX) - Smooth hero animations are critical for premium feel.
-
-**Location**: `/home/home-server/Ensemble/lib/screens/new_library_screen.dart` (around lines 200-235)
-
-**Fix**: Wrap CircleAvatar and Text with Hero widgets matching ArtistDetailsScreen tags.
-
-```dart
-Widget _buildArtistTile(BuildContext context, Artist artist, MusicAssistantProvider provider) {
-  final imageUrl = provider.getImageUrl(artist, size: 128);
-  final suffix = '_library';
-
-  return ListTile(
-    leading: Hero(
-      tag: HeroTags.artistImage + (artist.uri ?? artist.itemId) + suffix,
-      child: CircleAvatar(
-        radius: 24,
-        backgroundImage: imageUrl != null ? NetworkImage(imageUrl) : null,
-      ),
-    ),
-    title: Hero(
-      tag: HeroTags.artistName + (artist.uri ?? artist.itemId) + suffix,
-      child: Material(
-        color: Colors.transparent,
-        child: Text(artist.name),
-      ),
-    ),
-    onTap: () {...},
-  );
-}
-```
-
-**Estimated Impact**: Eliminates jarring cross-fade, creates smooth morphing animation
-
----
-
-## Category 2: Widget Rebuild Optimization
-
-### WR-1: Replace context.watch() with context.select() in Lists
-
-**Issue**: Using context.watch<MusicAssistantProvider>() causes entire screen rebuilds when any provider property changes.
-
-**Impact**: High - Lists rebuild unnecessarily when unrelated state changes (e.g., playback state).
-
-**Locations**:
-- `/home/home-server/Ensemble/lib/screens/library_artists_screen.dart:13`
-- `/home/home-server/Ensemble/lib/screens/library_albums_screen.dart:12`
-- `/home/home-server/Ensemble/lib/screens/new_library_screen.dart:62`
-
-**Fix**:
-```dart
-// Before:
-final provider = context.watch<MusicAssistantProvider>();
-// Rebuilds when currentTrack, isPlaying, volume, etc. change
-
-// After:
-final artists = context.select<MusicAssistantProvider, List<Artist>>(
-  (p) => p.artists
-);
-final isLoading = context.select<MusicAssistantProvider, bool>(
-  (p) => p.isLoading
-);
-// Only rebuilds when artists or isLoading change
-```
-
-**Estimated Savings**: 30-50% reduction in unnecessary rebuilds
-
----
-
-### WR-2: Extract Static Widgets
-
-**Issue**: Static decoration widgets are recreated on every build.
-
-**Impact**: Medium - Flutter recreates identical widgets instead of reusing them.
-
-**Locations**: Throughout screens (Icons, Padding, SizedBox, etc.)
-
-**Fix**:
-```dart
-// Before:
-Icon(Icons.person_rounded, size: 60, color: colorScheme.onSurfaceVariant)
-
-// After:
-static const _placeholderIcon = Icon(Icons.person_rounded, size: 60);
-// Use colorScheme.onSurfaceVariant in IconTheme instead
-```
-
-**Estimated Savings**: 2-5% reduction in widget allocations
-
----
-
-### WR-3: Add const to BoxDecoration and TextStyle
-
-**Issue**: Decorations and styles are recreated on every build.
-
-**Impact**: Low-Medium - Small per-widget overhead that adds up in lists.
-
-**Fix**: Use const where colors are not dynamic, extract to constants file for reuse.
-
----
-
-## Category 3: Animation Improvements
-
-### AN-1: Optimize Hero Animation Curves
-
-**Issue**: FadeSlidePageRoute uses generic easeOut/easeIn curves.
-
-**Impact**: Medium - Better curves create more natural animations.
-
-**Location**: `/home/home-server/Ensemble/lib/utils/page_transitions.dart`
-
-**Recommendation**:
-```dart
-// Current:
-curve: Curves.easeOut,
-reverseCurve: Curves.easeIn,
-
-// Better for hero animations:
-curve: Curves.easeOutCubic,
-reverseCurve: Curves.easeInCubic,
-
-// Or match Material Design 3:
-curve: Curves.easeInOutCubicEmphasized,
-```
-
-**Note**: ExpandablePlayer already uses easeOutCubic/easeInCubic (good!)
-
----
-
-### AN-2: Reduce Overdraw with Transparent Backgrounds
-
-**Issue**: Some widgets have unnecessary background colors causing overdraw.
-
-**Impact**: Low - Minor GPU savings, more noticeable on older devices.
-
-**Recommendation**: Audit Material widgets for unnecessary color properties.
-
----
-
-### AN-3: Animation Disposal
-
-**Issue**: Verify all AnimationController instances are disposed.
-
-**Status**: ✅ Already handled correctly in ExpandablePlayer and GlobalPlayerOverlay
-
----
-
-## Category 4: List Performance
-
-### LP-1: Enable ListView.builder cacheExtent Tuning
-
-**Issue**: Default cacheExtent may not be optimal for music library browsing.
-
-**Impact**: Medium - Prebuilding items off-screen prevents scroll stutters.
-
-**Recommendation**:
-```dart
-ListView.builder(
-  cacheExtent: 500, // Prebuild ~500px off-screen
-  itemCount: items.length,
-  itemBuilder: ...
-)
-```
-
-**Note**: Test on device to find optimal value (300-1000px typical range).
-
----
-
-### LP-2: Lazy Load Images in Lists
-
-**Issue**: NetworkImage starts loading immediately, even for off-screen items.
-
-**Impact**: Low - Flutter already lazy-loads decoding, but could optimize further.
-
-**Current State**: ✅ Already using cacheWidth/cacheHeight (good!)
-
-**Optional Enhancement**: Use cached_network_image package for better caching.
-
----
-
-### LP-3: GridView childAspectRatio Precision
-
-**Issue**: GridView.builder uses childAspectRatio: 0.75, causing layout calculations.
-
-**Impact**: Very Low - Already efficient, no changes needed.
-
-**Status**: ✅ Current implementation is optimal
-
----
-
-## Category 5: State Restoration
-
-### SR-1: Preserve Scroll Positions
-
-**Issue**: Scroll positions are lost when navigating away and back to library screens.
-
-**Impact**: Medium (UX) - Users have to scroll back to where they were.
-
-**Locations**:
-- Library artists/albums/playlists tabs
-- Home screen rows
-
-**Fix**: Implement PageStorageKey for lists
-```dart
-ListView.builder(
-  key: const PageStorageKey<String>('artists_list'),
-  itemCount: items.length,
-  itemBuilder: ...
-)
-```
-
----
-
-### SR-2: Implement RestorationMixin for Tab State
-
-**Issue**: NewLibraryScreen tab selection is lost on app restart.
-
-**Impact**: Low (UX) - Minor annoyance, not performance-related.
-
-**Recommendation**: Add RestorationMixin to NewLibraryScreen state.
-
----
-
-## Performance Benchmarking Recommendations
-
-### Metrics to Track
-
-1. **Frame Rendering Time**: Should be <16ms (60fps) or <11ms (90fps on capable devices)
-2. **Jank Count**: Number of frames >16ms (target: <5% of frames)
-3. **Overdraw**: Use Flutter DevTools Performance Overlay
-4. **Widget Rebuild Count**: Use performance overlay to track rebuilds
-5. **Memory Usage**: Track during long scrolling sessions
-
-### Testing Scenarios
-
-1. **Scroll Performance Test**:
-   - Library with 1000+ albums
-   - Continuous fast scroll for 30 seconds
-   - Measure frame drops and jank count
-
-2. **Animation Smoothness Test**:
-   - Navigate Album → Details → Back 20 times rapidly
-   - Measure hero animation frame rate
-   - Check for stutter or dropped frames
-
-3. **Mini Player Expansion Test**:
-   - Expand/collapse player 20 times
-   - Measure animation consistency
-   - Check for layout jank
-
-4. **Concurrent Operations Test**:
-   - Play music while scrolling library
-   - Navigate between screens during playback
-   - Ensure no frame drops during animations
-
-### Tools
-
-- Flutter DevTools Performance View
-- Timeline profiler
-- Performance overlay: `flutter run --profile`
-- fps_monitor package for production monitoring
-
----
-
-## Implementation Priority
-
-### Phase 1: Quick Wins (1-2 hours)
-Priority: **CRITICAL** - Highest impact/effort ratio
-
-- [ ] QW-1: Add const constructors
-- [ ] QW-2: Add keys to list items
-- [ ] QW-3: Add itemExtent to horizontal lists
-- [ ] QW-4: Add RepaintBoundary to list tiles
-- [ ] QW-5: Fix Library hero animations
-
-**Expected Impact**: 20-35% improvement in scroll smoothness, eliminate hero animation jank
-
----
-
-### Phase 2: Widget Rebuilds (2-3 hours)
-Priority: **HIGH** - Significant performance gains
-
-- [ ] WR-1: Replace context.watch() with context.select()
-- [ ] WR-2: Extract static widgets
-- [ ] WR-3: Add const to decorations/styles
-
-**Expected Impact**: 25-40% reduction in unnecessary rebuilds
-
----
-
-### Phase 3: Animation Tuning (30 min)
-Priority: **HIGH** - Polish that users notice
-
-- [ ] AN-1: Optimize curve selection
-- [ ] AN-2: Reduce overdraw
-
-**Expected Impact**: Subtle but noticeable smoothness improvement
-
----
-
-### Phase 4: List Optimization (1 hour)
-Priority: **MEDIUM** - Performance headroom for large libraries
-
-- [ ] LP-1: Add cacheExtent tuning
-- [ ] LP-2: Verify image lazy loading (already good)
-
-**Expected Impact**: 10-15% improvement in large list scroll performance
-
----
-
-### Phase 5: State Restoration (1-2 hours)
-Priority: **LOW** - UX polish, not performance
-
-- [ ] SR-1: Add PageStorageKey to lists
-- [ ] SR-2: Implement RestorationMixin for tabs
-
-**Expected Impact**: Better UX, maintains user context
-
----
-
-## Files to Modify
-
-### High Priority (Phase 1-2)
-1. `/home/home-server/Ensemble/lib/screens/library_artists_screen.dart`
-2. `/home/home-server/Ensemble/lib/screens/library_albums_screen.dart`
-3. `/home/home-server/Ensemble/lib/screens/new_library_screen.dart`
-4. `/home/home-server/Ensemble/lib/widgets/album_row.dart`
-5. `/home/home-server/Ensemble/lib/widgets/artist_row.dart`
-
-### Medium Priority (Phase 3-4)
-6. `/home/home-server/Ensemble/lib/utils/page_transitions.dart`
-7. `/home/home-server/Ensemble/lib/widgets/album_card.dart` (verify, already good)
-8. `/home/home-server/Ensemble/lib/widgets/artist_card.dart` (verify, already good)
-
-### Low Priority (Phase 5)
-9. State restoration utilities (may need new file)
-
----
-
-## Success Criteria
-
-### Performance Targets
-- [ ] 95%+ of frames render in <16ms (60fps)
-- [ ] <5% jank rate during scroll/animations
-- [ ] Hero animations consistently smooth (no visible stutter)
-- [ ] Mini player expansion/collapse at 60fps
-- [ ] Library scroll maintains 60fps with 1000+ items
-
-### Code Quality
-- [ ] flutter analyze: 0 errors, 0 warnings
-- [ ] No performance-related lint warnings
-- [ ] All AnimationControllers properly disposed
-- [ ] Consistent use of const constructors
-
-### User Experience
-- [ ] Animations feel comparable to Symphonium
-- [ ] No visible lag during navigation
-- [ ] Scroll positions preserved (Phase 5)
-- [ ] Smooth transitions throughout app
-
----
-
-## Notes
-
-**What's Already Good:**
-- RepaintBoundary on cards ✅
-- Image caching with dimensions ✅
-- AutomaticKeepAliveClientMixin on rows ✅
-- Proper animation controller disposal ✅
-- Good use of CurvedAnimation ✅
-
-**Biggest Opportunities:**
-1. Adding keys to list items (huge impact, easy fix)
-2. Replacing context.watch() with context.select() (massive rebuild reduction)
-3. Adding const constructors (free performance)
-4. Fixing hero animations (UX polish)
-
-**Reference Implementation:**
-The ExpandablePlayer and card widgets are well-optimized examples. Use them as templates for other widgets.
-
----
-
-## Appendix: Flutter Performance Best Practices Applied
-
-### ✅ Already Implemented
-- RepaintBoundary for expensive widgets
-- const constructors where appropriate
-- AutomaticKeepAliveClientMixin for stateful widgets
-- Image caching with explicit dimensions
-- CurvedAnimation for smooth curves
-- Proper animation controller management
-- SingleTickerProviderStateMixin where needed
-
-### ⚠️ Partially Implemented
-- Keys on list items (missing in several places)
-- const constructors (many widgets still mutable)
-- Targeted rebuilds (some broad context.watch() usage)
-
-### ❌ Not Yet Implemented
-- PageStorageKey for scroll restoration
-- itemExtent for fixed-size lists
-- cacheExtent tuning
-- Comprehensive use of context.select()
-
----
-
-**End of Audit**
-
-**Next Steps**: Implement Phase 1 (Quick Wins) on `performance/animation-smoothness` branch and measure impact before proceeding to Phase 2.

analyses/performance-fixes-implemented.md

@@ -1,502 +0,0 @@
-# Performance Fixes Implementation Summary
-
-**Date**: 2025-12-05
-**Branch**: performance/animation-smoothness
-**Goal**: Achieve buttery-smooth 60fps+ animations comparable to Symphonium media player
-
----
-
-## Executive Summary
-
-Successfully implemented **100%** of the identified quick wins and high-priority performance optimizations from the Ensemble Performance Audit. All changes focus on reducing unnecessary widget rebuilds, optimizing list performance, and improving animation smoothness.
-
-### Implementation Status
-
-| Phase | Items | Status | Completion |
-|-------|-------|--------|------------|
-| Phase 1: Quick Wins | 5 items | ✅ Complete | 100% |
-| Phase 2: Widget Rebuilds | 3 items | ✅ Complete | 100% |
-| Phase 3: Animation Tuning | 1 item | ✅ Complete | 100% |
-| Phase 4: List Optimization | 1 item | ✅ Complete | 100% |
-| Phase 5: State Restoration | 1 item | ✅ Complete | 100% |
-
-**Overall Completion**: 100% (11/11 items)
-
----
-
-## Files Modified
-
-### Core Library Screens
-1. `/home/home-server/Ensemble/lib/screens/library_artists_screen.dart`
-2. `/home/home-server/Ensemble/lib/screens/library_albums_screen.dart`
-3. `/home/home-server/Ensemble/lib/screens/new_library_screen.dart`
-
-### Widgets
-4. `/home/home-server/Ensemble/lib/widgets/album_row.dart`
-5. `/home/home-server/Ensemble/lib/widgets/artist_row.dart`
-
-### Utilities
-6. `/home/home-server/Ensemble/lib/utils/page_transitions.dart`
-
-**Total Files Modified**: 6
-
----
-
-## Detailed Changes by Phase
-
-### Phase 1: Quick Wins (Critical Priority)
-
-#### ✅ QW-1: Added `const` Constructors
-**Impact**: High - 5-10% reduction in widget rebuilds
-
-**Changes**:
-- `LibraryArtistsScreen`: Added `const` constructor
-- `LibraryAlbumsScreen`: Added `const` constructor
-- All stateless widgets now use const constructors where applicable
-
-**Code Example**:
-```dart
-// Before:
-class LibraryArtistsScreen extends StatelessWidget {
-  LibraryArtistsScreen({super.key});
-
-// After:
-class LibraryArtistsScreen extends StatelessWidget {
-  const LibraryArtistsScreen({super.key});
-```
-
----
-
-#### ✅ QW-2: Added Keys to List Items
-**Impact**: High - 15-25% reduction in list scroll jank
-
-**Changes**:
-- Added `ValueKey` to all list items in:
-  - `library_artists_screen.dart` (line 104)
-  - `library_albums_screen.dart` (line 99)
-  - `new_library_screen.dart` (artists: line 212, albums: line 319)
-  - `album_row.dart` (line 97)
-  - `artist_row.dart` (line 97)
-
-**Code Example**:
-```dart
-return AlbumCard(
-  key: ValueKey(album.uri ?? album.itemId),
-  album: album,
-  heroTagSuffix: 'library',
-);
-```
-
----
-
-#### ✅ QW-3: Added itemExtent to Horizontal Lists
-**Impact**: Medium - 10-15% improvement in horizontal scroll smoothness
-
-**Changes**:
-- `album_row.dart`: Added `itemExtent: 162` (150px width + 12px margins)
-- `artist_row.dart`: Added `itemExtent: 136` (120px width + 16px margins)
-
-**Code Example**:
-```dart
-ListView.builder(
-  scrollDirection: Axis.horizontal,
-  itemCount: albums.length,
-  itemExtent: 162, // Width + margins
-  itemBuilder: ...
-)
-```
-
----
-
-#### ✅ QW-4: Added RepaintBoundary to List Tiles
-**Impact**: Medium - 5-10% reduction in repaint overhead
-
-**Changes**:
-- Wrapped artist list tiles with `RepaintBoundary`:
-  - `library_artists_screen.dart` (line 122)
-  - `new_library_screen.dart` (line 220)
-
-**Code Example**:
-```dart
-Widget _buildArtistTile(...) {
-  return RepaintBoundary(
-    child: ListTile(
-      // ListTile content
-    ),
-  );
-}
-```
-
----
-
-#### ✅ QW-5: Fixed Library Screen Hero Animations
-**Impact**: High (UX) - Eliminates jarring transitions, creates smooth morphing
-
-**Changes**:
-- Added Hero widgets to artist tiles in `new_library_screen.dart`:
-  - Hero tag for CircleAvatar (artist image)
-  - Hero tag for Text (artist name) with Material wrapper
-  - Tags match the format in `ArtistDetailsScreen`
-
-**Code Example**:
-```dart
-leading: Hero(
-  tag: HeroTags.artistImage + (artist.uri ?? artist.itemId) + '_library',
-  child: CircleAvatar(...)
-),
-title: Hero(
-  tag: HeroTags.artistName + (artist.uri ?? artist.itemId) + '_library',
-  child: Material(
-    color: Colors.transparent,
-    child: Text(artist.name),
-  ),
-)
-```
-
----
-
-### Phase 2: Widget Rebuild Optimization (High Priority)
-
-#### ✅ WR-1: Replaced context.watch() with Selector
-**Impact**: High - 30-50% reduction in unnecessary rebuilds
-
-**Changes**:
-- `library_artists_screen.dart`: Uses `Selector<MusicAssistantProvider, (List<Artist>, bool)>` to only rebuild when artists or loading state changes
-- `library_albums_screen.dart`: Uses `Selector<MusicAssistantProvider, (List<Album>, bool)>` to only rebuild when albums or loading state changes
-- `new_library_screen.dart`:
-  - Main build uses `Selector<MusicAssistantProvider, bool>` for connection state
-  - Artists tab uses `Selector` for (artists, isLoading)
-  - Albums tab uses `Selector` for (albums, isLoading)
-
-**Benefit**: Previously, these widgets rebuilt on ANY provider change (playback state, volume, current track, etc.). Now they only rebuild when their specific data changes.
-
-**Code Example**:
-```dart
-// Before:
-final provider = context.watch<MusicAssistantProvider>();
-// Rebuilds when currentTrack, isPlaying, volume, etc. change
-
-// After:
-Selector<MusicAssistantProvider, (List<Artist>, bool)>(
-  selector: (_, provider) => (provider.artists, provider.isLoading),
-  builder: (context, data, _) {
-    final (artists, isLoading) = data;
-    // Only rebuilds when artists or isLoading change
-  },
-)
-```
-
----
-
-#### ✅ WR-2: Converted to context.read() Where Appropriate
-**Impact**: Medium - Eliminates unnecessary widget subscriptions
-
-**Changes**:
-- Replaced `provider.loadLibrary()` with `context.read<MusicAssistantProvider>().loadLibrary()` in callbacks
-- Used `context.read()` in `_buildArtistTile()` and `_buildPlaylistTile()` methods
-
-**Benefit**: Prevents these methods from subscribing to provider changes when they only need one-time access.
-
----
-
-### Phase 3: Animation Improvements (High Priority)
-
-#### ✅ AN-1: Optimized Hero Animation Curves
-**Impact**: Medium - Noticeably smoother and more natural animations
-
-**Changes**:
-- `page_transitions.dart`: Updated all animation curves:
-  - `Curves.easeOut` → `Curves.easeOutCubic`
-  - `Curves.easeIn` → `Curves.easeInCubic`
-
-**Benefit**: Cubic curves provide more natural, premium-feeling motion that better matches Material Design 3 guidelines and apps like Symphonium.
-
-**Code Example**:
-```dart
-// Before:
-curve: Curves.easeOut,
-reverseCurve: Curves.easeIn,
-
-// After:
-curve: Curves.easeOutCubic,
-reverseCurve: Curves.easeInCubic,
-```
-
----
-
-### Phase 4: List Performance (Medium Priority)
-
-#### ✅ LP-1: Added cacheExtent Tuning
-**Impact**: Medium - 10-15% improvement in large list scroll performance
-
-**Changes**:
-- Added `cacheExtent: 500` to all ListViews and GridViews:
-  - `library_artists_screen.dart`
-  - `library_albums_screen.dart`
-  - `new_library_screen.dart` (all 3 tabs)
-
-**Benefit**: Prebuilds items ~500px off-screen, preventing scroll stutters when items come into view.
-
-**Code Example**:
-```dart
-ListView.builder(
-  cacheExtent: 500, // Prebuild items off-screen for smoother scrolling
-  itemCount: items.length,
-  itemBuilder: ...
-)
-```
-
----
-
-### Phase 5: State Restoration (Low Priority - UX Polish)
-
-#### ✅ SR-1: Added PageStorageKey to All Lists
-**Impact**: Medium (UX) - Users no longer lose scroll position
-
-**Changes**:
-- Added unique `PageStorageKey<String>` to all scrollable lists:
-  - `library_artists_full_list`
-  - `library_albums_full_grid`
-  - `library_artists_list` (in NewLibraryScreen)
-  - `library_albums_grid` (in NewLibraryScreen)
-  - `library_playlists_list`
-
-**Benefit**: Scroll positions are now preserved when navigating away and back to library screens.
-
-**Code Example**:
-```dart
-ListView.builder(
-  key: const PageStorageKey<String>('library_artists_list'),
-  itemCount: items.length,
-  itemBuilder: ...
-)
-```
-
----
-
-## Performance Impact Estimates
-
-### Expected Improvements
-
-| Optimization | Expected Impact | Affected Operations |
-|--------------|----------------|---------------------|
-| const Constructors | 5-10% | All widget rebuilds |
-| List Item Keys | 15-25% | List scrolling and updates |
-| itemExtent | 10-15% | Horizontal list scrolling |
-| RepaintBoundary | 5-10% | List item repaints |
-| Selector vs watch() | 30-50% | Provider-triggered rebuilds |
-| Animation Curves | Subtle but noticeable | Page transitions and Hero animations |
-| cacheExtent | 10-15% | Fast scrolling in large lists |
-
-### Combined Expected Improvement
-
-**Conservative Estimate**: 40-60% reduction in jank and frame drops
-**Optimistic Estimate**: 60-80% reduction in jank and frame drops
-
-**Target**: 95%+ of frames render in <16ms (60fps)
-
----
-
-## Items NOT Implemented (and Why)
-
-**None** - All items from the audit were successfully implemented.
-
----
-
-## Verification Checklist
-
-### Pre-Commit Verification
-- ✅ All identified quick wins implemented
-- ✅ All high-priority optimizations implemented
-- ✅ Widget rebuild optimizations complete
-- ✅ Animation curves optimized
-- ✅ List performance improved
-- ✅ State restoration working
-- ⚠️ `flutter analyze` - Flutter not available in environment (manual verification needed)
-- ⚠️ `flutter test` - Flutter not available in environment (manual verification needed)
-
-### Code Quality
-- ✅ All changes follow existing code style
-- ✅ All imports are correct
-- ✅ No new dependencies added
-- ✅ All existing functionality preserved
-- ✅ Performance comments added where non-obvious
-
----
-
-## Testing Recommendations
-
-### On-Device Testing Required
-
-Since Flutter CLI is not available in this environment, the following tests should be performed on an actual device or emulator:
-
-#### 1. Scroll Performance Test
-- **Test**: Library with 1000+ albums
-- **Action**: Continuous fast scroll for 30 seconds
-- **Measure**: Frame drops and jank count using Flutter DevTools
-- **Expected**: <5% jank rate
-
-#### 2. Animation Smoothness Test
-- **Test**: Navigate Album → Details → Back 20 times rapidly
-- **Measure**: Hero animation frame rate
-- **Expected**: Consistent 60fps, no visible stutter
-
-#### 3. Mini Player Test
-- **Test**: Expand/collapse mini player 20 times
-- **Measure**: Animation consistency
-- **Expected**: Smooth 60fps animation
-
-#### 4. Concurrent Operations Test
-- **Test**: Play music while scrolling library
-- **Action**: Navigate between screens during playback
-- **Expected**: No frame drops during animations
-
-#### 5. State Restoration Test
-- **Test**: Scroll to middle of artist list
-- **Action**: Navigate away and back
-- **Expected**: Scroll position preserved
-
-### Performance Profiling Tools
-
-Run the app with:
-```bash
-flutter run --profile
-```
-
-Enable performance overlay:
-```bash
-flutter run --profile --enable-software-rendering
-```
-
-Use Flutter DevTools:
-- Timeline profiler to identify frame drops
-- Performance overlay to visualize rebuilds
-- Memory profiler to check for leaks
-
----
-
-## Comparison to Symphonium
-
-### Target Benchmarks (Symphonium-like smoothness)
-
-| Metric | Symphonium | Ensemble Before | Ensemble Target |
-|--------|-----------|-----------------|-----------------|
-| Frame Time (avg) | <12ms | ~18-20ms (est) | <14ms |
-| Jank Rate | <3% | ~15-20% (est) | <5% |
-| Hero Animation | Silky smooth | Occasional stutter | Smooth 60fps |
-| List Scroll | Buttery smooth | Minor jank | Smooth 60fps |
-| Rebuild Count | Minimal | Excessive | Targeted |
-
----
-
-## Implementation Notes
-
-### What Worked Well
-1. **Selector Pattern**: Massive improvement over context.watch() - dramatically reduced unnecessary rebuilds
-2. **List Item Keys**: Essential for Flutter's diffing algorithm to work efficiently
-3. **itemExtent**: Simple change with big impact on horizontal lists
-4. **Cubic Curves**: Subtle but makes animations feel more premium
-
-### Lessons Learned
-1. Always use Selector when only watching specific provider properties
-2. Keys are critical for list performance, not optional
-3. RepaintBoundary should be standard practice for list items
-4. cacheExtent is a powerful tool for large lists
-
-### Best Practices Applied
-- ✅ RepaintBoundary for expensive widgets
-- ✅ const constructors everywhere possible
-- ✅ Keys on all list items
-- ✅ Targeted rebuilds with Selector
-- ✅ Proper animation curves
-- ✅ State restoration for better UX
-- ✅ Cache extent for smooth scrolling
-
----
-
-## Next Steps (Future Optimizations)
-
-While all audit items are implemented, consider these future enhancements:
-
-### Low Priority Improvements
-1. **Tab State Restoration**: Implement RestorationMixin for NewLibraryScreen to remember selected tab (SR-2 from audit)
-2. **Cached Network Images**: Consider `cached_network_image` package for better image caching
-3. **Virtual Scrolling**: For extremely large libraries (>5000 items), consider implementing virtual scrolling
-
-### Monitoring
-1. Add fps_monitor package for production performance tracking
-2. Set up performance benchmarks in CI/CD
-3. Create automated performance regression tests
-
----
-
-## Success Criteria
-
-### Achieved
-- ✅ New branch created: `performance/animation-smoothness`
-- ✅ All quick wins implemented
-- ✅ 100% of audit items addressed
-- ✅ Changes committed with clear messages (pending)
-- ✅ Summary document created
-
-### Pending Device Testing
-- ⚠️ flutter analyze passes (requires Flutter environment)
-- ⚠️ flutter test passes (requires Flutter environment)
-- ⚠️ On-device performance verification
-
----
-
-## Git Commit Strategy
-
-### Recommended Commits
-
-1. **Commit 1**: Phase 1 Quick Wins
-   ```
-   perf: implement quick wins for animation smoothness
-
-   - Add const constructors to library screens
-   - Add keys to all list items
-   - Add itemExtent to horizontal lists
-   - Add RepaintBoundary to artist tiles
-   - Fix Hero animations in library screen
-
-   Expected: 20-35% improvement in scroll smoothness
-   ```
-
-2. **Commit 2**: Phase 2 Widget Rebuilds
-   ```
-   perf: optimize widget rebuilds with Selector pattern
-
-   - Replace context.watch() with Selector in all library screens
-   - Use context.read() for one-time provider access
-   - Add targeted selectors for (artists, isLoading) and (albums, isLoading)
-
-   Expected: 30-50% reduction in unnecessary rebuilds
-   ```
-
-3. **Commit 3**: Phase 3-5 Remaining Optimizations
-   ```
-   perf: optimize animations, lists, and state restoration
-
-   - Upgrade animation curves to easeOutCubic/easeInCubic
-   - Add cacheExtent: 500 to all lists for smoother scrolling
-   - Add PageStorageKey to all lists for scroll position restoration
-
-   Expected: 10-15% improvement in scroll performance + better UX
-   ```
-
-Alternatively, all changes can be committed together as a single atomic commit.
-
----
-
-## Conclusion
-
-All performance optimizations from the audit have been successfully implemented. The changes are focused, well-documented, and follow Flutter best practices. Once verified on device, these optimizations should bring Ensemble's animation smoothness on par with premium music players like Symphonium.
-
-**Expected Result**: Buttery-smooth 60fps animations and scrolling throughout the app.
-
-**Estimated Total Impact**: 50-70% reduction in jank and frame drops.
-
----
-
-**End of Implementation Summary**

android/app/src/main/AndroidManifest.xml

@@ -14,7 +14,7 @@
         android:usesCleartextTraffic="true"
         android:networkSecurityConfig="@xml/network_security_config">
         <activity
-            android:name="com.ryanheise.audioservice.AudioServiceActivity"
+            android:name=".MainActivity"
             android:exported="true"
             android:launchMode="singleTop"
             android:theme="@style/LaunchTheme"

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

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

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

@@ -1,11 +0,0 @@
-<?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">
-    <!-- Music note icon for notification -->
-    <path
-        android:fillColor="#FFFFFF"
-        android:pathData="M12,3v10.55c-0.59,-0.34 -1.27,-0.55 -2,-0.55 -2.21,0 -4,1.79 -4,4s1.79,4 4,4 4,-1.79 4,-4V7h4V3h-6z"/>
-</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>

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/implementation/ensemble-navigation-restructure-summary.md

@@ -1,414 +0,0 @@
-# Ensemble Navigation Restructure Implementation Summary
-
-**Implementation Date:** December 4, 2025
-**Branch:** feature/fixed-bottom-nav-fluid-animations
-**Implemented By:** Claude Code
-**Status:** Complete - Ready for Testing
-
----
-
-## Overview
-
-This document summarizes the implementation of the Ensemble app navigation restructuring to achieve fixed bottom navigation, fluid hero animations, and seamless mini player expansion.
-
-### Goals Achieved
-
-1. **Fixed Bottom Navigation Bar** - Bottom nav no longer animates during page transitions
-2. **Fluid Hero Animations** - All hero animations morph smoothly, including the previously broken Library → Artist animation
-3. **Mini Player Over Bottom Nav** - Mini player correctly expands over the fixed bottom navigation
-4. **Adaptive Color Flow** - Adaptive colors update smoothly on the fixed bottom navigation
-
----
-
-## What Was Changed
-
-### Phase 1: Fix Library → Artist Hero Animation
-
-**File Modified:** `/home/home-server/Ensemble/lib/screens/new_library_screen.dart`
-
-**Changes:**
-- Added import for `../constants/hero_tags.dart`
-- Wrapped `CircleAvatar` in `Hero` widget with tag: `HeroTags.artistImage + uri + '_library'`
-- Wrapped artist name `Text` in `Hero` widget with tag: `HeroTags.artistName + uri + '_library'`
-- Added `Material` wrapper to text hero with transparent color (required for text heroes)
-
-**Impact:** Library → Artist navigation now has smooth hero animation instead of cross-fade
-
-**Commit:** `c38e266` - "feat: add Hero widgets to Library artist tiles"
-
----
-
-### Phase 2: Remove AlbumDetailsScreen Bottom Nav
-
-**File Modified:** `/home/home-server/Ensemble/lib/screens/album_details_screen.dart`
-
-**Changes:**
-- Removed entire `bottomNavigationBar` property from Scaffold (lines 341-388)
-- Deleted 48 lines of duplicate navigation bar code
-
-**Impact:**
-- No bottom navigation animation when navigating to album details
-- Bottom nav remains fixed at HomeScreen level
-- Cleaner, simpler detail screen
-
-**Commit:** `f16522b` - "feat: remove duplicate bottom navigation from AlbumDetailsScreen"
-
----
-
-### Phase 3: Remove ArtistDetailsScreen Bottom Nav
-
-**File Modified:** `/home/home-server/Ensemble/lib/screens/artist_details_screen.dart`
-
-**Changes:**
-- Removed entire `bottomNavigationBar` property from Scaffold (lines 162-209)
-- Deleted 48 lines of duplicate navigation bar code
-
-**Impact:**
-- Consistent with album details behavior
-- No bottom navigation animation when navigating to artist details
-- Bottom nav remains fixed at HomeScreen level
-
-**Commit:** `152eff5` - "feat: remove duplicate bottom navigation from ArtistDetailsScreen"
-
----
-
-### Phase 4: Integration Testing & Validation
-
-**Activities:**
-- Code-level validation of all changes
-- Verified bottomNavigationBar removed from both detail screens
-- Verified Hero tags correctly added to Library screen
-- Verified HomeScreen bottom nav still exists
-- Verified hero tag consistency between screens
-- Verified GlobalPlayerOverlay Stack structure unchanged
-- Verified adaptive color implementation intact
-
-**Results:** All validation checks passed
-
----
-
-### Phase 5: Polish & Optional Enhancements
-
-**Files Modified:**
-- `/home/home-server/Ensemble/lib/screens/album_details_screen.dart`
-- `/home/home-server/Ensemble/lib/screens/artist_details_screen.dart`
-
-**Changes:**
-- Reduced bottom padding from 140px to 80px in both detail screens
-- Updated comments to reflect change (removed "bottom nav" reference)
-
-**Impact:**
-- More content visible before scrolling
-- Appropriate spacing for mini player only (no bottom nav needed)
-
-**Commit:** `22ce7a3` - "polish: reduce bottom padding in detail screens"
-
----
-
-## Key Architectural Decisions
-
-### 1. Remove Bottom Nav vs. Fix It
-
-**Decision:** Remove duplicate bottom navigation bars from detail screens entirely
-
-**Rationale:**
-- Simplest solution (only removes code, no complex refactoring)
-- Completely eliminates bottom nav animation during transitions
-- Standard pattern used by major music apps (Spotify, Apple Music)
-- Reduces widget tree complexity
-- Focuses user attention on detail content
-
-**Alternative Considered:** Keep bottom nav everywhere with adaptive colors - Would still show cross-fade animation during transitions
-
----
-
-### 2. Hero Animation Approach
-
-**Decision:** Add Hero widgets to match existing pattern, keep FadeSlidePageRoute
-
-**Rationale:**
-- Library artist tiles were missing Hero widgets that ArtistDetailsScreen expected
-- Solution follows existing successful pattern from ArtistCard widget
-- Simple fix with low risk
-- FadeSlidePageRoute doesn't interfere with hero animations once tags match
-
-**Alternative Considered:** Switch to MaterialPageRoute - Not necessary since FadeSlidePageRoute works fine with proper hero tags
-
----
-
-### 3. Bottom Padding Reduction
-
-**Decision:** Reduce from 140px to 80px
-
-**Rationale:**
-- Original 140px was for mini player (64px) + bottom nav (56px) + margins
-- With bottom nav removed from detail screens, only need space for mini player
-- 80px provides adequate space (64px player + 16px buffer)
-- More content visible without sacrificing usability
-
----
-
-## Code Quality Highlights
-
-### Clean Implementation
-- No hardcoded values introduced
-- Consistent animation patterns maintained
-- Proper hero tag construction following existing conventions
-- Material wrapper on text heroes (required by Flutter)
-
-### Architecture Preservation
-- No changes to ThemeProvider
-- No changes to GlobalPlayerOverlay
-- No changes to ExpandablePlayer
-- No changes to navigation system (still using Navigator.push)
-- All core systems left intact
-
-### Code Reduction
-- Net deletion of ~96 lines of duplicate code
-- Added ~15 lines for hero widgets
-- **Total: -81 lines** (simpler, cleaner codebase)
-
----
-
-## Known Limitations
-
-### Navigation Pattern
-- Users can no longer switch tabs directly from album/artist detail screens
-- Must use back button/gesture to return to main navigation
-- This is intentional and follows industry standard patterns
-
-### Hero Animation Timing
-- Hero animations use Flutter's default timing (300ms)
-- Consistent with MaterialPageRoute and FadeSlidePageRoute
-- If custom timing is desired, would need custom hero flight shuttle builder
-
----
-
-## Future Improvements
-
-### Optional Enhancements Not Implemented
-These were considered but deemed unnecessary after code review:
-
-1. **Back Button Visibility Enhancement** - Current AppBar back button is sufficient
-2. **Smooth Color Transition Animation** - Current implementation already smooth via ThemeProvider
-3. **Custom Page Transitions** - FadeSlidePageRoute works well with hero animations
-4. **Empty State Navigation Hints** - Users understand standard back navigation
-
-### Potential Future Work
-- **Performance Profiling:** Test on low-end devices to ensure 60 FPS
-- **User Testing:** Gather feedback on navigation UX without bottom nav in details
-- **go_router Migration:** If app grows complex, consider router-based navigation
-- **Gesture Navigation:** Could add swipe-between-tabs from detail screens if needed
-
----
-
-## How to Test the Changes
-
-### Manual Testing Checklist
-
-#### Fixed Bottom Navigation
-1. Navigate to Home screen
-2. Tap any album card → Album details
-3. **Verify:** Bottom navigation bar does NOT move or change color during transition
-4. Navigate back
-5. **Verify:** Bottom nav remains fixed during back transition
-6. Repeat for: Home → Artist, Library → Album, Library → Artist
-
-#### Hero Animations
-1. Navigate to Library screen → Artists tab
-2. Tap any artist from the list
-3. **Verify:** Artist circle avatar morphs smoothly from small to large
-4. **Verify:** Artist name transitions smoothly
-5. **Verify:** No cross-fade or jarring transition
-6. Navigate back
-7. **Verify:** Reverse animation plays smoothly
-8. Repeat for: Home → Album, Home → Artist, Library → Album
-
-#### Mini Player Layering
-1. Play a track (mini player appears)
-2. Navigate to Album details
-3. **Verify:** Mini player visible above bottom nav
-4. Tap mini player to expand
-5. **Verify:** Player expands over bottom nav (not behind)
-6. **Verify:** Background morphs from tinted to dark surface
-7. Collapse player
-8. **Verify:** Smooth collapse animation
-
-#### Adaptive Colors
-1. Play a track with colorful album art (e.g., red/orange)
-2. **Verify:** Bottom nav selected color changes to match album
-3. Navigate to album details
-4. **Verify:** Bottom nav color persists (doesn't reset)
-5. Navigate back to Home
-6. Play different track with different colored art (e.g., blue)
-7. **Verify:** Bottom nav color updates smoothly
-
-#### Content Spacing
-1. Navigate to album details
-2. Scroll to bottom of track list
-3. **Verify:** Last track is not obscured by mini player
-4. **Verify:** Adequate spacing below last item
-5. Repeat for artist details (scroll through albums)
-
-### Automated Testing (Future)
-- Widget tests for hero tag consistency
-- Integration tests for navigation flows
-- Performance tests for animation frame rates
-
----
-
-## Verification Results
-
-### Code-Level Validation (Completed)
-
-✅ **Bottom Nav Removal:**
-- Verified `bottomNavigationBar` property removed from AlbumDetailsScreen
-- Verified `bottomNavigationBar` property removed from ArtistDetailsScreen
-- Verified HomeScreen bottom nav still exists
-
-✅ **Hero Tags:**
-- Verified `HeroTags.artistImage` added to Library screen with `_library` suffix
-- Verified `HeroTags.artistName` added to Library screen with `_library` suffix
-- Verified tags match ArtistDetailsScreen expectations
-- Verified Material wrapper on text hero
-
-✅ **Architecture Integrity:**
-- Verified GlobalPlayerOverlay Stack structure unchanged
-- Verified adaptive color implementation intact in HomeScreen
-- Verified ThemeProvider integration preserved
-
-✅ **Code Quality:**
-- No syntax errors introduced
-- Consistent code style maintained
-- Proper imports added
-- Comments updated to reflect changes
-
-### Manual Testing (Required)
-Manual testing should be performed by running the app on a device/emulator to verify:
-- Visual animations are smooth
-- Navigation flows work correctly
-- No runtime errors occur
-- Performance is acceptable (60 FPS target)
-
----
-
-## Deployment Recommendations
-
-### Pre-Merge Checklist
-- [ ] Manual testing completed on Android device/emulator
-- [ ] Manual testing completed on iOS device/simulator (if applicable)
-- [ ] All hero animations verified working
-- [ ] Bottom nav confirmed fixed during all transitions
-- [ ] Mini player expansion verified
-- [ ] Adaptive colors confirmed updating correctly
-- [ ] No regressions found in existing functionality
-- [ ] Performance profiling shows 60 FPS during animations
-- [ ] Code review completed by team member
-
-### Rollback Plan
-If issues are discovered:
-
-1. **Hero Animation Broken:** Revert commit `c38e266`
-   - Returns to cross-fade transition for Library → Artist
-   - No other functionality affected
-
-2. **Users Need Bottom Nav in Details:**
-   - Revert commits `f16522b` and `152eff5`
-   - Consider implementing adaptive colors in detail nav (Phase 2 Alternative)
-
-3. **Content Spacing Issues:**
-   - Revert commit `22ce7a3`
-   - Returns to 140px padding
-
-4. **Complete Rollback:**
-   - Revert all commits on branch
-   - Merge would not occur
-
----
-
-## Branch and Commit History
-
-**Branch:** `feature/fixed-bottom-nav-fluid-animations`
-
-**Commits:**
-1. `c38e266` - feat: add Hero widgets to Library artist tiles
-2. `f16522b` - feat: remove duplicate bottom navigation from AlbumDetailsScreen
-3. `152eff5` - feat: remove duplicate bottom navigation from ArtistDetailsScreen
-4. `22ce7a3` - polish: reduce bottom padding in detail screens
-5. `fd3ef47` - docs: add analysis and planning documents
-
-**Total Files Changed:** 5
-- `lib/screens/new_library_screen.dart` - Modified (Phase 1)
-- `lib/screens/album_details_screen.dart` - Modified (Phase 2, 5)
-- `lib/screens/artist_details_screen.dart` - Modified (Phase 3, 5)
-- `docs/analysis/ensemble-navigation-animation-analysis.md` - Created
-- `docs/planning/ensemble-navigation-restructure-plan.md` - Created
-
-**Lines Changed:**
-- Added: ~15 lines (hero widgets)
-- Removed: ~96 lines (duplicate bottom navs)
-- Modified: ~4 lines (padding values, comments)
-- **Net: -81 lines**
-
----
-
-## Success Criteria Status
-
-### Primary Goals
-✅ **Fixed Bottom Navigation** - Code changes ensure bottom nav only exists at HomeScreen level
-✅ **Adaptive Colors Update** - No changes to adaptive color system; continues to work
-✅ **Mini Player Over Bottom Nav** - No changes to GlobalPlayerOverlay z-order; continues to work
-✅ **Fluid Hero Animations** - Hero tags added to Library screen; should now morph smoothly
-✅ **No Regressions** - Only removed duplicate code; core functionality preserved
-
-### Secondary Goals
-✅ **Visual Polish** - Bottom padding optimized for detail screens
-✅ **Performance** - Fewer widgets should improve performance (requires testing to confirm)
-✅ **Code Quality** - Net reduction in code, cleaner architecture
-
----
-
-## Contact & Support
-
-**For Questions About This Implementation:**
-- Review analysis document: `docs/analysis/ensemble-navigation-animation-analysis.md`
-- Review planning document: `docs/planning/ensemble-navigation-restructure-plan.md`
-- Check commit messages for specific change rationale
-
-**For Issues or Bugs:**
-- Test the specific navigation path showing issues
-- Check if hero tags are matching between screens
-- Verify ThemeProvider is notifying listeners
-- Review GlobalPlayerOverlay Stack structure
-
-**For Future Enhancements:**
-- Reference "Future Improvements" section above
-- Consider user feedback from manual testing
-- Evaluate performance profiling results
-
----
-
-## Conclusion
-
-The Ensemble navigation restructuring has been successfully implemented following the detailed plan. All code changes are complete, committed, and pushed to the feature branch.
-
-**Key Achievements:**
-- Bottom navigation is now truly fixed during all page transitions
-- Library → Artist hero animation is fixed and should morph smoothly
-- Mini player remains correctly positioned above bottom navigation
-- Adaptive colors continue to flow to the fixed bottom nav
-- Cleaner codebase with less duplication
-
-**Next Steps:**
-1. Manual testing on device/emulator to verify animations
-2. Performance profiling to ensure 60 FPS target
-3. User testing to validate navigation UX
-4. Address any issues found during testing
-5. Merge to main branch after approval
-
-The implementation follows Flutter best practices, maintains the existing architecture, and achieves all primary goals without brute-forcing solutions.
-
----
-
-**Implementation Complete: December 4, 2025**
-**Ready for Testing and Review**

lib/constants/timings.dart

@@ -8,8 +8,10 @@ class Timings {
   /// Player state polling interval (for selected player updates)
   static const Duration playerPollingInterval = Duration(seconds: 5);
 
-  /// Local player state report interval (for seek bar smoothness)
-  static const Duration localPlayerReportInterval = Duration(seconds: 1);
+  /// Local player state report interval
+  /// Note: Sendspin protocol only requires state on changes, not periodic reports.
+  /// This is mainly for local UI position tracking. Set to 5s to reduce server traffic.
+  static const Duration localPlayerReportInterval = Duration(seconds: 5);
 
   /// Player list cache duration before refresh
   static const Duration playersCacheDuration = Duration(minutes: 5);

lib/main.dart

@@ -1,3 +1,4 @@
+import 'dart:async';
 import 'package:flutter/material.dart';
 import 'package:flutter/services.dart';
 import 'package:provider/provider.dart';
@@ -10,6 +11,7 @@ import 'services/settings_service.dart';
 import 'services/audio/massiv_audio_handler.dart';
 import 'services/auth/auth_manager.dart';
 import 'services/debug_logger.dart';
+import 'services/hardware_volume_service.dart';
 import 'services/music_assistant_api.dart' show MAConnectionState;
 import 'theme/theme_provider.dart';
 import 'theme/app_theme.dart';
@@ -71,6 +73,14 @@ class MusicAssistantApp extends StatefulWidget {
 class _MusicAssistantAppState extends State<MusicAssistantApp> with WidgetsBindingObserver {
   late MusicAssistantProvider _musicProvider;
   late ThemeProvider _themeProvider;
+  final _hardwareVolumeService = HardwareVolumeService();
+  StreamSubscription? _volumeUpSub;
+  StreamSubscription? _volumeDownSub;
+  String? _lastSelectedPlayerId;
+  String? _builtinPlayerId;
+
+  // Volume step size (percentage points per button press)
+  static const int _volumeStep = 5;
 
   @override
   void initState() {
@@ -78,10 +88,64 @@ class _MusicAssistantAppState extends State<MusicAssistantApp> with WidgetsBindi
     _musicProvider = MusicAssistantProvider();
     _themeProvider = ThemeProvider();
     WidgetsBinding.instance.addObserver(this);
+    _initHardwareVolumeControl();
+    // Listen to player selection changes to toggle volume interception
+    _musicProvider.addListener(_onProviderChanged);
+  }
+
+  Future<void> _initHardwareVolumeControl() async {
+    try {
+      _builtinPlayerId = await SettingsService.getBuiltinPlayerId();
+      await _hardwareVolumeService.init();
+
+      _volumeUpSub = _hardwareVolumeService.onVolumeUp.listen((_) {
+        _adjustVolume(_volumeStep);
+      });
+
+      _volumeDownSub = _hardwareVolumeService.onVolumeDown.listen((_) {
+        _adjustVolume(-_volumeStep);
+      });
+    } catch (e, stack) {
+      _logger.error('Hardware volume init failed', context: 'VolumeInit', error: e, stackTrace: stack);
+    }
+  }
+
+  /// Called when provider state changes - check if selected player changed
+  void _onProviderChanged() {
+    final currentPlayerId = _musicProvider.selectedPlayer?.playerId;
+    if (currentPlayerId != _lastSelectedPlayerId) {
+      _lastSelectedPlayerId = currentPlayerId;
+      _updateVolumeInterception();
+    }
+  }
+
+  /// Enable/disable volume button interception based on selected player.
+  Future<void> _updateVolumeInterception() async {
+    final isBuiltinPlayer = _builtinPlayerId != null &&
+        _musicProvider.selectedPlayer?.playerId == _builtinPlayerId;
+    await _hardwareVolumeService.setIntercepting(!isBuiltinPlayer);
+  }
+
+  Future<void> _adjustVolume(int delta) async {
+    final player = _musicProvider.selectedPlayer;
+    if (player == null) return;
+
+    final newVolume = (player.volume + delta).clamp(0, 100);
+    if (newVolume != player.volume) {
+      try {
+        await _musicProvider.setVolume(player.playerId, newVolume);
+      } catch (e) {
+        _logger.error('Hardware volume adjustment failed', context: 'VolumeControl', error: e);
+      }
+    }
   }
 
   @override
   void dispose() {
+    _musicProvider.removeListener(_onProviderChanged);
+    _volumeUpSub?.cancel();
+    _volumeDownSub?.cancel();
+    _hardwareVolumeService.dispose();
     WidgetsBinding.instance.removeObserver(this);
     super.dispose();
   }

lib/models/player.dart

@@ -27,31 +27,99 @@ class Player {
     this.elapsedTimeLastUpdated,
   });
 
+  /// Create a copy of this Player with some fields replaced
+  Player copyWith({
+    String? playerId,
+    String? name,
+    String? provider,
+    bool? available,
+    bool? powered,
+    String? state,
+    String? currentItemId,
+    int? volumeLevel,
+    bool? volumeMuted,
+    double? elapsedTime,
+    double? elapsedTimeLastUpdated,
+  }) {
+    return Player(
+      playerId: playerId ?? this.playerId,
+      name: name ?? this.name,
+      provider: provider ?? this.provider,
+      available: available ?? this.available,
+      powered: powered ?? this.powered,
+      state: state ?? this.state,
+      currentItemId: currentItemId ?? this.currentItemId,
+      volumeLevel: volumeLevel ?? this.volumeLevel,
+      volumeMuted: volumeMuted ?? this.volumeMuted,
+      elapsedTime: elapsedTime ?? this.elapsedTime,
+      elapsedTimeLastUpdated: elapsedTimeLastUpdated ?? this.elapsedTimeLastUpdated,
+    );
+  }
+
   // Derived properties
   bool get isPlaying => state == 'playing';
   bool get isMuted => volumeMuted ?? false;
   int get volume => volumeLevel ?? 0;
 
+  // Track when this Player object was created (for local interpolation fallback)
+  static final Map<String, double> _playerCreationTimes = {};
+
   // Calculate current elapsed time (interpolated if playing)
   double get currentElapsedTime {
     if (elapsedTime == null) {
       return 0;
     }
 
-    if (!isPlaying || elapsedTimeLastUpdated == null) {
+    if (!isPlaying) {
       return elapsedTime!;
     }
 
-    // If playing, interpolate based on time since last update
     final now = DateTime.now().millisecondsSinceEpoch / 1000.0;
-    final timeSinceUpdate = now - elapsedTimeLastUpdated!;
 
-    // Safety check: if time since update is negative or too large, just return elapsed time
-    if (timeSinceUpdate < 0 || timeSinceUpdate > 30) {
-      return elapsedTime!;
+    // Try server-provided timestamp first, but only if it's recent
+    if (elapsedTimeLastUpdated != null) {
+      final timeSinceUpdate = now - elapsedTimeLastUpdated!;
+
+      // Only use server timestamp if it's within valid range (0-10 seconds)
+      // - Negative means clock skew (client ahead of server)
+      // - > 10 seconds means stale data (e.g., after player switch)
+      // If outside this range, fall through to local fallback for smooth interpolation
+      if (timeSinceUpdate >= 0 && timeSinceUpdate <= 10.0) {
+        return elapsedTime! + timeSinceUpdate;
+      }
+      // Server timestamp is stale or invalid - fall through to local fallback
     }
 
-    return elapsedTime! + timeSinceUpdate;
+    // Fallback: use local creation time for interpolation
+    // This handles:
+    // 1. Server doesn't send elapsed_time_last_updated
+    // 2. Server timestamp is stale (e.g., after switching to a remote player)
+    // 3. Clock skew between client and server
+    //
+    // Key insight: when server sends a NEW elapsed_time, we get a NEW key,
+    // so interpolation naturally starts fresh. We should NEVER reset an existing
+    // key's creation time, as that causes progress to jump backward.
+    final creationKey = '$playerId:$elapsedTime';
+
+    if (!_playerCreationTimes.containsKey(creationKey)) {
+      // First time seeing this elapsed_time - record when we saw it
+      _playerCreationTimes[creationKey] = now;
+      // Clean up old entries to prevent memory leak
+      if (_playerCreationTimes.length > 100) {
+        final keysToRemove = _playerCreationTimes.keys.take(50).toList();
+        for (final key in keysToRemove) {
+          _playerCreationTimes.remove(key);
+        }
+      }
+    }
+
+    final creationTime = _playerCreationTimes[creationKey]!;
+    final timeSinceCreation = now - creationTime;
+
+    // Server sends updates every ~5 seconds with new elapsed_time values,
+    // which creates new keys and corrects any drift. Allow unlimited
+    // interpolation since new server data will naturally correct it.
+    return elapsedTime! + timeSinceCreation;
   }
 
   factory Player.fromJson(Map<String, dynamic> json) {
@@ -61,8 +129,13 @@ class Player {
     double? elapsedTimeLastUpdated;
 
     // Get top-level elapsed time values
-    final topLevelElapsedTime = (json['elapsed_time'] as num?)?.toDouble();
-    final topLevelLastUpdated = (json['elapsed_time_last_updated'] as num?)?.toDouble();
+    // Try multiple field names as different player types may report position differently
+    final topLevelElapsedTime = (json['elapsed_time'] as num?)?.toDouble()
+        ?? (json['position'] as num?)?.toDouble()
+        ?? (json['media_position'] as num?)?.toDouble()
+        ?? (json['current_position'] as num?)?.toDouble();
+    final topLevelLastUpdated = (json['elapsed_time_last_updated'] as num?)?.toDouble()
+        ?? (json['position_updated_at'] as num?)?.toDouble();
 
     // Extract current_item_id and elapsed time from current_media
     // current_media often has the more accurate position after seeks
@@ -71,8 +144,12 @@ class Player {
       if (currentMedia != null) {
         currentItemId ??= currentMedia['queue_item_id'] as String?;
 
-        final currentMediaElapsedTime = (currentMedia['elapsed_time'] as num?)?.toDouble();
-        final currentMediaLastUpdated = (currentMedia['elapsed_time_last_updated'] as num?)?.toDouble();
+        // Try multiple field names for position
+        final currentMediaElapsedTime = (currentMedia['elapsed_time'] as num?)?.toDouble()
+            ?? (currentMedia['position'] as num?)?.toDouble()
+            ?? (currentMedia['media_position'] as num?)?.toDouble();
+        final currentMediaLastUpdated = (currentMedia['elapsed_time_last_updated'] as num?)?.toDouble()
+            ?? (currentMedia['position_updated_at'] as num?)?.toDouble();
 
         // Prefer current_media elapsed_time when available - it reflects actual playback position
         // after seek operations, while top-level elapsed_time may lag behind

lib/providers/player_provider.dart

@@ -212,6 +212,9 @@ class PlayerProvider with ChangeNotifier {
   Future<void> _reportLocalPlayerState() async {
     if (_api == null) return;
 
+    // Don't try to report state if not authenticated - avoids spamming errors
+    if (_api!.currentConnectionState != MAConnectionState.authenticated) return;
+
     final playerId = await SettingsService.getBuiltinPlayerId();
     if (playerId == null) return;
 

lib/screens/album_details_screen.dart

@@ -545,6 +545,47 @@ class _AlbumDetailsScreenState extends State<AlbumDetailsScreen> with SingleTick
     }
   }
 
+  /// Show fullscreen album art overlay
+  void _showFullscreenArt(String? imageUrl) {
+    if (imageUrl == null) return;
+
+    Navigator.of(context).push(
+      PageRouteBuilder(
+        opaque: false,
+        barrierColor: Colors.black87,
+        barrierDismissible: true,
+        pageBuilder: (context, animation, secondaryAnimation) {
+          return FadeTransition(
+            opacity: animation,
+            child: GestureDetector(
+              onTap: () => Navigator.of(context).pop(),
+              onVerticalDragEnd: (details) {
+                if (details.primaryVelocity != null && details.primaryVelocity!.abs() > 300) {
+                  Navigator.of(context).pop();
+                }
+              },
+              child: Scaffold(
+                backgroundColor: Colors.transparent,
+                body: Center(
+                  child: InteractiveViewer(
+                    minScale: 0.5,
+                    maxScale: 3.0,
+                    child: CachedNetworkImage(
+                      imageUrl: imageUrl,
+                      fit: BoxFit.contain,
+                      memCacheWidth: 1024,
+                      memCacheHeight: 1024,
+                    ),
+                  ),
+                ),
+              ),
+            ),
+          );
+        },
+      ),
+    );
+  }
+
   @override
   Widget build(BuildContext context) {
     // CRITICAL FIX: Use select() instead of watch() to reduce rebuilds
@@ -607,35 +648,38 @@ class _AlbumDetailsScreenState extends State<AlbumDetailsScreen> with SingleTick
                 mainAxisAlignment: MainAxisAlignment.center,
                 children: [
                   const SizedBox(height: 60),
-                  Hero(
-                    tag: HeroTags.albumCover + (widget.album.uri ?? widget.album.itemId) + _heroTagSuffix,
-                    child: Container(
-                      width: 280, // Increased size
-                      height: 280,
-                      decoration: BoxDecoration(
-                        color: colorScheme.surfaceVariant,
-                        borderRadius: BorderRadius.circular(16), // Slightly more rounded
-                        boxShadow: [
-                          BoxShadow(
-                            color: Colors.black.withOpacity(0.3),
-                            blurRadius: 20,
-                            offset: const Offset(0, 10),
-                          ),
-                        ],
-                        image: imageUrl != null
-                            ? DecorationImage(
-                                image: CachedNetworkImageProvider(imageUrl),
-                                fit: BoxFit.cover,
+                  GestureDetector(
+                    onTap: () => _showFullscreenArt(imageUrl),
+                    child: Hero(
+                      tag: HeroTags.albumCover + (widget.album.uri ?? widget.album.itemId) + _heroTagSuffix,
+                      child: Container(
+                        width: 280, // Increased size
+                        height: 280,
+                        decoration: BoxDecoration(
+                          color: colorScheme.surfaceVariant,
+                          borderRadius: BorderRadius.circular(16), // Slightly more rounded
+                          boxShadow: [
+                            BoxShadow(
+                              color: Colors.black.withOpacity(0.3),
+                              blurRadius: 20,
+                              offset: const Offset(0, 10),
+                            ),
+                          ],
+                          image: imageUrl != null
+                              ? DecorationImage(
+                                  image: CachedNetworkImageProvider(imageUrl),
+                                  fit: BoxFit.cover,
+                                )
+                              : null,
+                        ),
+                        child: imageUrl == null
+                            ? Icon(
+                                Icons.album_rounded,
+                                size: 120,
+                                color: colorScheme.onSurfaceVariant,
                               )
                             : null,
                       ),
-                      child: imageUrl == null
-                          ? Icon(
-                              Icons.album_rounded,
-                              size: 120,
-                              color: colorScheme.onSurfaceVariant,
-                            )
-                          : null,
                     ),
                   ),
                 ],
@@ -960,7 +1004,7 @@ class _AlbumDetailsScreenState extends State<AlbumDetailsScreen> with SingleTick
                 childCount: _tracks.length,
               ),
             ),
-          const SliverToBoxAdapter(child: SizedBox(height: 140)), // Space for bottom nav + mini player
+          const SliverToBoxAdapter(child: SizedBox(height: 164)), // Space for bottom nav + mini player
         ],
       ),
       ),

lib/services/animation_debugger.dart

@@ -12,7 +12,7 @@ import 'debug_logger.dart';
 /// 4. Logs will show frame timing, jank detection, and summary stats
 class AnimationDebugger {
   static final _logger = DebugLogger();
-  static bool _enabled = true;
+  static bool _enabled = false; // Disabled for release - enable for debugging animation jank
 
   // Session tracking
   static String? _currentSession;

lib/services/audio/massiv_audio_handler.dart

@@ -15,17 +15,28 @@ class MassivAudioHandler extends BaseAudioHandler with SeekHandler {
   // This allows us to update the notification when metadata arrives late
   MediaItem? _currentMediaItem;
 
-  // Callbacks for skip actions (wired up by MusicAssistantProvider)
+  // Callbacks for actions (wired up by MusicAssistantProvider)
   Function()? onSkipToNext;
   Function()? onSkipToPrevious;
+  Function()? onPlay;
+  Function()? onPause;
+  Function()? onSwitchPlayer;
+
+  // Track whether we're in remote control mode (controlling MA player, not playing locally)
+  bool _isRemoteMode = false;
+
+  // Custom control for switching players (uses stop action with custom icon)
+  static const _switchPlayerControl = MediaControl(
+    androidIcon: 'drawable/ic_switch_player',
+    label: 'Switch Player',
+    action: MediaAction.stop,
+  );
 
   MassivAudioHandler({required this.authManager}) {
     _init();
   }
 
   Future<void> _init() async {
-    _logger.log('MassivAudioHandler: Initializing...');
-
     // Configure audio session
     final session = await AudioSession.instance;
     await session.configure(const AudioSessionConfiguration.music());
@@ -70,8 +81,6 @@ class MassivAudioHandler extends BaseAudioHandler with SeekHandler {
         mediaItem.add(_currentMediaItem);
       }
     });
-
-    _logger.log('MassivAudioHandler: Initialized');
   }
 
   /// Broadcast the current playback state to the system
@@ -84,7 +93,7 @@ class MassivAudioHandler extends BaseAudioHandler with SeekHandler {
         MediaControl.skipToPrevious,
         if (playing) MediaControl.pause else MediaControl.play,
         MediaControl.skipToNext,
-        // Note: We intentionally omit MediaControl.stop to avoid the white square icon issue
+        _switchPlayerControl, // Switch player button
       ],
       // System-level actions (for headphones, car stereos, etc.)
       systemActions: const {
@@ -98,7 +107,8 @@ class MassivAudioHandler extends BaseAudioHandler with SeekHandler {
         MediaAction.skipToPrevious,
       },
       // Which buttons to show in compact notification (max 3)
-      androidCompactActionIndices: const [0, 1, 2],
+      // Show: play/pause (1), skip-next (2), switch-player (3)
+      androidCompactActionIndices: const [1, 2, 3],
       processingState: {
         ProcessingState.idle: AudioProcessingState.idle,
         ProcessingState.loading: AudioProcessingState.loading,
@@ -116,16 +126,28 @@ class MassivAudioHandler extends BaseAudioHandler with SeekHandler {
   // --- Playback control methods ---
 
   @override
-  Future<void> play() => _player.play();
+  Future<void> play() async {
+    if (_isRemoteMode) {
+      onPlay?.call();
+    } else {
+      await _player.play();
+    }
+  }
 
   @override
-  Future<void> pause() => _player.pause();
+  Future<void> pause() async {
+    if (_isRemoteMode) {
+      onPause?.call();
+    } else {
+      await _player.pause();
+    }
+  }
 
   @override
   Future<void> stop() async {
-    await _player.stop();
-    // Don't call super.stop() which would end the service
-    // Just stop playback and let the notification remain for resuming
+    // Stop action is used for switching players (both local and remote modes)
+    onSwitchPlayer?.call();
+    // Note: We don't actually stop playback - this button is repurposed for player switching
   }
 
   @override
@@ -133,27 +155,18 @@ class MassivAudioHandler extends BaseAudioHandler with SeekHandler {
 
   @override
   Future<void> skipToNext() async {
-    _logger.log('MassivAudioHandler: skipToNext requested');
-    if (onSkipToNext != null) {
-      onSkipToNext!();
-    }
+    onSkipToNext?.call();
   }
 
   @override
   Future<void> skipToPrevious() async {
-    _logger.log('MassivAudioHandler: skipToPrevious requested');
-    if (onSkipToPrevious != null) {
-      onSkipToPrevious!();
-    }
+    onSkipToPrevious?.call();
   }
 
   // --- Custom methods for Ensemble ---
 
   /// Play a URL with the given metadata
   Future<void> playUrl(String url, MediaItem item, {Map<String, String>? headers}) async {
-    _logger.log('MassivAudioHandler: Playing URL: $url');
-    _logger.log('MassivAudioHandler: Metadata: ${item.title} by ${item.artist}');
-
     _currentMediaItem = item;
     mediaItem.add(item);
 
@@ -166,10 +179,8 @@ class MassivAudioHandler extends BaseAudioHandler with SeekHandler {
 
       await _player.setAudioSource(source);
       await _player.play();
-      _logger.log('MassivAudioHandler: Playback started');
-    } catch (e, stackTrace) {
+    } catch (e) {
       _logger.log('MassivAudioHandler: Error playing URL: $e');
-      _logger.log('MassivAudioHandler: Stack trace: $stackTrace');
       rethrow;
     }
   }
@@ -178,7 +189,6 @@ class MassivAudioHandler extends BaseAudioHandler with SeekHandler {
   /// This can be called when metadata arrives after playback starts
   @override
   Future<void> updateMediaItem(MediaItem item) async {
-    _logger.log('MassivAudioHandler: Updating media item: ${item.title} by ${item.artist}');
     _currentMediaItem = item;
     mediaItem.add(item);
   }
@@ -188,6 +198,82 @@ class MassivAudioHandler extends BaseAudioHandler with SeekHandler {
     await _player.setVolume(volume.clamp(0.0, 1.0));
   }
 
+  /// Set remote playback state (for controlling MA players without local playback)
+  /// This shows the notification and responds to media controls without playing audio locally.
+  void setRemotePlaybackState({
+    required MediaItem item,
+    required bool playing,
+    Duration position = Duration.zero,
+    Duration? duration,
+  }) {
+    _isRemoteMode = true;
+    _currentMediaItem = item;
+    mediaItem.add(item);
+
+    playbackState.add(playbackState.value.copyWith(
+      controls: [
+        MediaControl.skipToPrevious,
+        if (playing) MediaControl.pause else MediaControl.play,
+        MediaControl.skipToNext,
+        _switchPlayerControl,
+      ],
+      systemActions: const {
+        MediaAction.play,
+        MediaAction.pause,
+        MediaAction.skipToNext,
+        MediaAction.skipToPrevious,
+        MediaAction.stop,
+      },
+      // Which buttons to show in compact notification (max 3)
+      // Show: play/pause (1), skip-next (2), switch-player (3)
+      androidCompactActionIndices: const [1, 2, 3],
+      processingState: AudioProcessingState.ready,
+      playing: playing,
+      updatePosition: position,
+      bufferedPosition: duration ?? Duration.zero,
+      speed: 1.0,
+    ));
+  }
+
+  /// Clear remote playback state and hide notification
+  void clearRemotePlaybackState() {
+    _isRemoteMode = false;
+    _currentMediaItem = null;
+
+    playbackState.add(playbackState.value.copyWith(
+      controls: [],
+      processingState: AudioProcessingState.idle,
+      playing: false,
+    ));
+  }
+
+  /// Switch to local playback mode (when builtin player is selected)
+  void setLocalMode() {
+    _isRemoteMode = false;
+  }
+
+  /// Update notification for local mode (builtin player) without switching to remote mode
+  /// This allows the notification to show the correct player/track info while keeping
+  /// pause working for local audio playback.
+  void updateLocalModeNotification({
+    required MediaItem item,
+    required bool playing,
+    Duration? duration,
+  }) {
+    // Keep local mode - DON'T set _isRemoteMode = true
+    // Only update mediaItem if it changed - avoid unnecessary notification refreshes
+    // that cause blinking. The playbackState is managed by _broadcastState which
+    // responds to actual player events.
+    if (_currentMediaItem?.id != item.id ||
+        _currentMediaItem?.title != item.title ||
+        _currentMediaItem?.artist != item.artist) {
+      _currentMediaItem = item;
+      mediaItem.add(item);
+    }
+  }
+
+  bool get isRemoteMode => _isRemoteMode;
+
   // --- Expose player state for provider ---
 
   bool get isPlaying => _player.playing;

lib/services/error_handler.dart

@@ -71,6 +71,18 @@ class ErrorHandler {
       );
     }
 
+    // Unavailable content errors - these won't resolve with retry
+    if (errorStr.contains('no playable') ||
+        errorStr.contains('lack available providers') ||
+        errorStr.contains('no available providers')) {
+      return ErrorInfo(
+        type: ErrorType.playback,
+        userMessage: 'These tracks are unavailable. The music provider may not have them available for streaming.',
+        technicalMessage: error.toString(),
+        canRetry: false,
+      );
+    }
+
     // Playback errors
     if (errorStr.contains('queue') ||
         errorStr.contains('player') ||

lib/services/hardware_volume_service.dart

@@ -0,0 +1,86 @@
+import 'dart:async';
+import 'package:flutter/services.dart';
+import 'debug_logger.dart';
+
+/// Service to intercept hardware volume button presses
+/// and route them to the selected Music Assistant player.
+///
+/// For MA players: intercept buttons and send volume commands via API
+/// For builtin player: let native volume work (don't intercept)
+class HardwareVolumeService {
+  static final HardwareVolumeService _instance = HardwareVolumeService._internal();
+  factory HardwareVolumeService() => _instance;
+  HardwareVolumeService._internal();
+
+  static const _channel = MethodChannel('com.musicassistant.music_assistant/volume_buttons');
+  final _logger = DebugLogger();
+
+  final _volumeUpController = StreamController<void>.broadcast();
+  final _volumeDownController = StreamController<void>.broadcast();
+
+  Stream<void> get onVolumeUp => _volumeUpController.stream;
+  Stream<void> get onVolumeDown => _volumeDownController.stream;
+
+  bool _isListening = false;
+  bool get isListening => _isListening;
+
+  bool _isIntercepting = false;
+  bool get isIntercepting => _isIntercepting;
+
+  /// Initialize the service and start listening for volume button events
+  Future<void> init() async {
+    if (_isListening) return;
+
+    _channel.setMethodCallHandler((call) async {
+      switch (call.method) {
+        case 'volumeUp':
+          _volumeUpController.add(null);
+          break;
+        case 'volumeDown':
+          _volumeDownController.add(null);
+          break;
+      }
+    });
+
+    try {
+      await _channel.invokeMethod('startListening');
+      _isListening = true;
+      _isIntercepting = true;
+    } catch (e) {
+      _logger.error('Failed to start volume button listening', context: 'VolumeService', error: e);
+    }
+  }
+
+  /// Enable or disable volume button interception.
+  /// When disabled, hardware volume buttons control device volume normally.
+  /// When enabled, volume button events are sent to Flutter for MA player control.
+  Future<void> setIntercepting(bool intercept) async {
+    if (!_isListening || _isIntercepting == intercept) return;
+
+    try {
+      if (intercept) {
+        await _channel.invokeMethod('startListening');
+        _isIntercepting = true;
+      } else {
+        await _channel.invokeMethod('stopListening');
+        _isIntercepting = false;
+      }
+    } catch (e) {
+      _logger.error('Failed to set volume interception', context: 'VolumeService', error: e);
+    }
+  }
+
+  /// Stop listening for volume button events
+  Future<void> dispose() async {
+    if (!_isListening) return;
+
+    try {
+      await _channel.invokeMethod('stopListening');
+      _isListening = false;
+      _isIntercepting = false;
+      _logger.info('Hardware volume button listening stopped', context: 'VolumeService');
+    } catch (e) {
+      _logger.error('Failed to stop volume button listening', context: 'VolumeService', error: e);
+    }
+  }
+}

lib/services/local_player_service.dart

@@ -84,11 +84,9 @@ class LocalPlayerService {
   Future<void> initialize() async {
     if (_isInitialized) return;
 
-    _logger.log('LocalPlayerService: Initializing with audio_service...');
     // The audioHandler is already initialized in main.dart
     // Just mark ourselves as initialized
     _isInitialized = true;
-    _logger.log('LocalPlayerService: Initialized (using global audioHandler)');
   }
 
   /// Set metadata for the current track (for notification display)
@@ -100,22 +98,13 @@ class LocalPlayerService {
   Future<void> playUrl(String url) async {
     // Ensure player is initialized before playing
     if (!_isInitialized) {
-      _logger.log('LocalPlayerService: Not initialized, initializing now...');
       await initialize();
     }
 
     try {
-      _logger.log('LocalPlayerService: Loading URL: $url');
-
       // Get auth headers from AuthManager
       final headers = authManager.getStreamingHeaders();
 
-      if (headers.isNotEmpty) {
-        _logger.log('LocalPlayerService: Added auth headers to request: ${headers.keys.join(', ')}');
-      } else {
-        _logger.log('LocalPlayerService: No authentication needed for streaming');
-      }
-
       // Create MediaItem from current metadata
       final mediaItem = _currentMetadata?.toMediaItem(url) ?? MediaItem(
         id: url,
@@ -123,19 +112,13 @@ class LocalPlayerService {
         artist: 'Unknown Artist',
       );
 
-      _logger.log('LocalPlayerService: Playing with audio_service');
-      _logger.log('LocalPlayerService: Metadata: ${mediaItem.title} by ${mediaItem.artist}');
-
       await audioHandler.playUrl(
         url,
         mediaItem,
         headers: headers.isNotEmpty ? headers : null,
       );
-
-      _logger.log('LocalPlayerService: Playback started with notification');
     } catch (e, stackTrace) {
       _logger.log('LocalPlayerService: Error playing URL: $e');
-      _logger.log('LocalPlayerService: Stack trace: $stackTrace');
       rethrow;
     }
   }
@@ -156,24 +139,18 @@ class LocalPlayerService {
       artworkUrl: artworkUrl,
       duration: duration,
     );
-
-    _logger.log('LocalPlayerService: Metadata updated for notification');
   }
 
   /// Update the notification while audio is already playing.
   /// With audio_service, we can update the MediaItem directly without
   /// re-setting the audio source.
   Future<void> updateNotificationWhilePlaying(TrackMetadata metadata) async {
-    _logger.log('LocalPlayerService: Updating notification mid-playback: ${metadata.title} by ${metadata.artist}');
-
     final currentItem = audioHandler.currentMediaItem;
     final id = currentItem?.id ?? 'unknown';
 
     final newMediaItem = metadata.toMediaItem(id);
     audioHandler.updateMediaItem(newMediaItem);
     _currentMetadata = metadata;
-
-    _logger.log('LocalPlayerService: Notification updated successfully');
   }
 
   Future<void> play() async {

lib/services/metadata_service.dart

@@ -251,9 +251,82 @@ class MetadataService {
     return null;
   }
 
+  // Cache for album images
+  static final Map<String, String?> _albumImageCache = {};
+
+  /// Fetches album cover URL from Deezer (free, no API key required)
+  /// Returns the image URL if found, null otherwise
+  static Future<String?> getAlbumImageUrl(String albumName, String? artistName) async {
+    // Build cache key
+    final cacheKey = 'albumImage:${artistName ?? ""}:$albumName';
+    if (_albumImageCache.containsKey(cacheKey)) {
+      return _albumImageCache[cacheKey];
+    }
+
+    // Use Deezer API (free, no key, excellent coverage)
+    try {
+      // Search with both album and artist if available for better matching
+      final query = artistName != null && artistName.isNotEmpty
+          ? '$artistName $albumName'
+          : albumName;
+
+      final uri = Uri.https(
+        'api.deezer.com',
+        '/search/album',
+        {
+          'q': query,
+          'limit': '5', // Get a few results to find best match
+        },
+      );
+
+      final response = await http.get(uri).timeout(const Duration(seconds: 5));
+
+      if (response.statusCode == 200) {
+        final data = json.decode(response.body);
+        final albums = data['data'] as List?;
+        if (albums != null && albums.isNotEmpty) {
+          // Try to find exact match first
+          Map<String, dynamic>? bestMatch;
+          for (final album in albums) {
+            final deezerAlbumName = (album['title'] as String?)?.toLowerCase();
+            final deezerArtistName = (album['artist']?['name'] as String?)?.toLowerCase();
+
+            if (deezerAlbumName == albumName.toLowerCase()) {
+              // Album name matches
+              if (artistName == null || artistName.isEmpty ||
+                  deezerArtistName == artistName.toLowerCase()) {
+                // And artist matches (or we don't have artist to match)
+                bestMatch = album;
+                break;
+              }
+              // Album matches but artist doesn't - keep as candidate
+              bestMatch ??= album;
+            }
+          }
+
+          // Fall back to first result if no good match
+          final album = bestMatch ?? albums[0] as Map<String, dynamic>;
+
+          // Use cover_xl for high quality, fall back to cover_medium
+          final imageUrl = album['cover_xl'] ?? album['cover_big'] ??
+              album['cover_medium'] ?? album['cover'];
+          _albumImageCache[cacheKey] = imageUrl;
+          return imageUrl;
+        }
+      }
+    } catch (e) {
+      _logger.warning('Deezer album image error: $e', context: 'Metadata');
+    }
+
+    // Cache the null result to avoid repeated failed lookups
+    _albumImageCache[cacheKey] = null;
+    return null;
+  }
+
   /// Clears the metadata cache
   static void clearCache() {
     _cache.clear();
     _artistImageCache.clear();
+    _albumImageCache.clear();
   }
 }

lib/services/music_assistant_api.dart

@@ -1045,7 +1045,20 @@ class MusicAssistantAPI {
   /// If clearQueue is true, replaces the queue (default behavior)
   /// If startIndex is provided, only tracks from that index onwards will be queued
   Future<void> playTracks(String playerId, List<Track> tracks, {int? startIndex, bool clearQueue = true}) async {
-    return await RetryHelper.retryCritical(
+    return await RetryHelper.retry(
+      maxAttempts: 3,
+      initialDelaySeconds: 1,
+      maxDelaySeconds: 4,
+      // Don't retry errors about missing/unavailable tracks - those won't resolve with retries
+      shouldRetry: (error) {
+        final errorStr = error.toString().toLowerCase();
+        if (errorStr.contains('no playable') ||
+            errorStr.contains('no tracks') ||
+            errorStr.contains('lack available')) {
+          return false;
+        }
+        return true;
+      },
       operation: () async {
         // If startIndex is provided, slice the tracks list to start from that index
         // This is a workaround since Music Assistant ignores the start_item parameter
@@ -1053,8 +1066,36 @@ class MusicAssistantAPI {
             ? tracks.sublist(startIndex)
             : tracks;
 
+        if (tracksToPlay.isEmpty) {
+          throw Exception('No tracks to play');
+        }
+
+        // Filter to only tracks with available provider mappings
+        final playableTracks = tracksToPlay.where((track) {
+          if (track.providerMappings == null || track.providerMappings!.isEmpty) {
+            _logger.log('⚠️ Track "${track.name}" has no provider mappings');
+            return false;
+          }
+          final hasAvailable = track.providerMappings!.any((m) => m.available);
+          if (!hasAvailable) {
+            _logger.log('⚠️ Track "${track.name}" has no available providers');
+          }
+          return hasAvailable;
+        }).toList();
+
+        if (playableTracks.isEmpty) {
+          _logger.log('❌ No playable tracks found (${tracksToPlay.length} tracks had no available providers)');
+          throw Exception('No playable tracks - all ${tracksToPlay.length} tracks lack available providers');
+        }
+
+        if (playableTracks.length < tracksToPlay.length) {
+          _logger.log('⚠️ ${tracksToPlay.length - playableTracks.length} tracks skipped (no available providers)');
+        }
+
         // Build array of URI strings (not objects!)
-        final mediaUris = tracksToPlay.map((track) => _buildTrackUri(track)).toList();
+        final mediaUris = playableTracks.map((track) => _buildTrackUri(track)).toList();
+
+        _logger.log('🎵 Playing ${mediaUris.length} tracks: ${mediaUris.take(3).join(", ")}${mediaUris.length > 3 ? "..." : ""}');
 
         final option = clearQueue ? 'replace' : 'play';
 
@@ -1458,6 +1499,14 @@ class MusicAssistantAPI {
     return _eventStreams['player_updated']!.stream;
   }
 
+  /// Stream of player_added events (for refreshing player list when new players join)
+  Stream<Map<String, dynamic>> get playerAddedEvents {
+    if (!_eventStreams.containsKey('player_added')) {
+      _eventStreams['player_added'] = StreamController<Map<String, dynamic>>.broadcast();
+    }
+    return _eventStreams['player_added']!.stream;
+  }
+
   /// Register this device as a player with retry logic
   /// CRITICAL: This creates a player config in MA's settings.json
   /// The server expects: player_id and player_name
@@ -1703,6 +1752,155 @@ class MusicAssistantAPI {
     }
   }
 
+  // ============================================================================
+  // SENDSPIN PLAYER MANAGEMENT (MA 2.7.0b20+ replacement for builtin_player)
+  // ============================================================================
+
+  /// Stream of Sendspin player events
+  Stream<Map<String, dynamic>> get sendspinPlayerEvents {
+    if (!_eventStreams.containsKey('sendspin_player')) {
+      _eventStreams['sendspin_player'] = StreamController<Map<String, dynamic>>.broadcast();
+    }
+    return _eventStreams['sendspin_player']!.stream;
+  }
+
+  /// Get Sendspin connection info for a player
+  /// Returns connection details including:
+  /// - local_ws_url: Direct WebSocket URL (e.g., ws://192.168.4.120:8927/sendspin)
+  /// - ice_servers: List of ICE/TURN servers for WebRTC fallback
+  /// - player_id: The player's ID
+  Future<Map<String, dynamic>?> getSendspinConnectionInfo(String playerId) async {
+    try {
+      _logger.log('Sendspin: Getting connection info for player $playerId');
+
+      final response = await _sendCommand(
+        'sendspin/connection_info',
+        args: {
+          'player_id': playerId,
+        },
+      );
+
+      final result = response['result'] as Map<String, dynamic>?;
+      if (result != null) {
+        _logger.log('Sendspin: Got connection info - local_ws_url: ${result['local_ws_url']}');
+        _logger.log('Sendspin: ICE servers count: ${(result['ice_servers'] as List?)?.length ?? 0}');
+      }
+
+      return result;
+    } catch (e) {
+      _logger.log('Sendspin: Error getting connection info: $e');
+      return null;
+    }
+  }
+
+  /// Send WebRTC offer to Sendspin server
+  /// Used when establishing WebRTC connection as fallback
+  Future<Map<String, dynamic>?> sendspinOffer(String playerId, String sdp) async {
+    try {
+      _logger.log('Sendspin: Sending WebRTC offer for player $playerId');
+
+      final response = await _sendCommand(
+        'sendspin/webrtc_offer',
+        args: {
+          'player_id': playerId,
+          'sdp': sdp,
+        },
+      );
+
+      return response['result'] as Map<String, dynamic>?;
+    } catch (e) {
+      _logger.log('Sendspin: Error sending WebRTC offer: $e');
+      return null;
+    }
+  }
+
+  /// Send WebRTC answer to Sendspin server
+  Future<void> sendspinAnswer(String playerId, String sdp) async {
+    try {
+      _logger.log('Sendspin: Sending WebRTC answer for player $playerId');
+
+      await _sendCommand(
+        'sendspin/webrtc_answer',
+        args: {
+          'player_id': playerId,
+          'sdp': sdp,
+        },
+      );
+    } catch (e) {
+      _logger.log('Sendspin: Error sending WebRTC answer: $e');
+      rethrow;
+    }
+  }
+
+  /// Send ICE candidate to Sendspin server
+  Future<void> sendspinIceCandidate(String playerId, Map<String, dynamic> candidate) async {
+    try {
+      await _sendCommand(
+        'sendspin/ice_candidate',
+        args: {
+          'player_id': playerId,
+          'candidate': candidate,
+        },
+      );
+    } catch (e) {
+      _logger.log('Sendspin: Error sending ICE candidate: $e');
+      // Don't rethrow - ICE candidate failures are common and non-fatal
+    }
+  }
+
+  /// Update Sendspin player state
+  /// Similar to updateBuiltinPlayerState but for Sendspin protocol
+  Future<void> updateSendspinPlayerState(
+    String playerId, {
+    required bool powered,
+    required bool playing,
+    required bool paused,
+    required int position,
+    required int volume,
+    required bool muted,
+  }) async {
+    try {
+      _logger.log('Sendspin: Updating player state: powered=$powered, playing=$playing, paused=$paused');
+      await _sendCommand(
+        'sendspin/update_state',
+        args: {
+          'player_id': playerId,
+          'state': {
+            'powered': powered,
+            'playing': playing,
+            'paused': paused,
+            'position': position,
+            'volume': volume,
+            'muted': muted,
+          },
+        },
+      );
+    } catch (e) {
+      _logger.log('Sendspin: Error updating player state: $e');
+      // Non-fatal, don't rethrow
+    }
+  }
+
+  /// Disconnect Sendspin player from server
+  Future<void> disconnectSendspinPlayer(String playerId) async {
+    try {
+      _logger.log('Sendspin: Disconnecting player $playerId');
+      await _sendCommand(
+        'sendspin/disconnect',
+        args: {
+          'player_id': playerId,
+        },
+      );
+    } catch (e) {
+      _logger.log('Sendspin: Error disconnecting player: $e');
+      // Non-fatal during cleanup
+    }
+  }
+
+  // ============================================================================
+  // END SENDSPIN PLAYER MANAGEMENT
+  // ============================================================================
+
   Future<void> _sendQueueCommand(String queueId, String command) async {
     try {
       final response = await _sendCommand(
@@ -1822,14 +2020,11 @@ class MusicAssistantAPI {
     final imagePath = selectedImage['path'] as String?;
     if (imagePath == null) return null;
 
-    // If path is already a full URL (from player_updated event), return it directly
-    if (imagePath.startsWith('http://') || imagePath.startsWith('https://')) {
-      return imagePath;
-    }
-
-    // Always use imageproxy endpoint to ensure images route through our server
-    // This fixes images not loading when connecting via external domain
-    // (direct URLs may contain internal IPs not reachable from outside the network)
+    // ALWAYS use imageproxy endpoint to ensure images route through MA server
+    // This fixes images not loading when connecting via external domain:
+    // - Direct URLs may contain internal IPs not reachable from outside the network
+    // - Streaming service URLs (Spotify, Tidal) may require auth or have CORS issues
+    // - MA's imageproxy fetches the image server-side and serves it through your server
 
     // Build the imageproxy URL
     var baseUrl = serverUrl;

lib/services/pcm_audio_player.dart

@@ -0,0 +1,591 @@
+import 'dart:async';
+import 'dart:typed_data';
+import 'package:flutter/foundation.dart' show unawaited;
+import 'package:flutter_pcm_sound/flutter_pcm_sound.dart' as pcm;
+import 'debug_logger.dart';
+
+/// Callback type for elapsed time updates
+typedef ElapsedTimeCallback = void Function(Duration elapsed);
+
+/// Audio format configuration matching Sendspin protocol
+class PcmAudioFormat {
+  final int sampleRate;
+  final int channels;
+  final int bitDepth;
+
+  const PcmAudioFormat({
+    this.sampleRate = 48000,
+    this.channels = 2,
+    this.bitDepth = 16,
+  });
+
+  /// Default Sendspin format: 48kHz, stereo, 16-bit PCM
+  static const sendspin = PcmAudioFormat();
+}
+
+/// Player state for PCM audio
+enum PcmPlayerState {
+  idle,
+  initializing,
+  ready,
+  playing,
+  pausing,   // Transitional state: pause requested, waiting for completion
+  paused,
+  resuming,  // Transitional state: resume requested, re-initializing
+  stopping,  // Transitional state: stop requested, cleaning up
+  error,
+}
+
+/// Error types for PCM player operations
+enum PcmPlayerError {
+  initializationFailed,
+  feedFailed,
+  pauseFailed,
+  resumeFailed,
+  streamError,
+  releaseTimeout,
+}
+
+/// Callback type for error events
+typedef PcmErrorCallback = void Function(PcmPlayerError error, String message);
+
+/// Service to play raw PCM audio data from Sendspin WebSocket stream
+/// Uses flutter_pcm_sound plugin for low-level PCM playback
+///
+/// State Machine:
+/// - idle → initializing → ready → playing ↔ paused
+/// - Any state can transition to error
+/// - Transitional states (pausing, resuming, stopping) block operations
+class PcmAudioPlayer {
+  final _logger = DebugLogger();
+
+  PcmPlayerState _state = PcmPlayerState.idle;
+  PcmAudioFormat _format = PcmAudioFormat.sendspin;
+
+  StreamSubscription<Uint8List>? _audioSubscription;
+
+  // Audio buffer for smooth playback
+  final List<Uint8List> _audioBuffer = [];
+  bool _isFeeding = false;
+  bool _isStarted = false;
+  Completer<void>? _feedCompleter;  // Tracks when current feed operation completes
+
+  // Error callback for operation failures
+  PcmErrorCallback? onError;
+
+  // Maximum chunks to feed at once to keep native buffer small (~200ms)
+  // Each chunk is ~25ms of audio, so 8 chunks = ~200ms
+  // Reduced from 12 (300ms) to 8 for faster pause response
+  static const int _maxChunksPerFeed = 8;
+
+  // Feed threshold - lower = faster pause but more risk of underruns
+  // Reduced from 8000 to 5000 frames (~104ms vs ~166ms) for faster response
+  static const int _feedThreshold = 5000;
+
+  // Stats
+  int _framesPlayed = 0;
+  int _bytesPlayed = 0;
+
+  // Elapsed time tracking for notification sync
+  Timer? _elapsedTimeTimer;
+  final _elapsedTimeController = StreamController<Duration>.broadcast();
+  ElapsedTimeCallback? onElapsedTimeUpdate;
+
+  // Track offset for pause/resume (preserves position across pause cycles)
+  int _bytesPlayedAtLastPause = 0;
+  DateTime? _playbackStartTime;
+
+  PcmPlayerState get state => _state;
+  bool get isPlaying => _state == PcmPlayerState.playing;
+  bool get isPaused => _state == PcmPlayerState.paused;
+  bool get isReady => _state == PcmPlayerState.ready || _state == PcmPlayerState.playing || _state == PcmPlayerState.paused;
+  int get framesPlayed => _framesPlayed;
+  int get bytesPlayed => _bytesPlayed;
+
+  /// Check if player is in a transitional state (operation in progress)
+  bool get isTransitioning => _state == PcmPlayerState.pausing ||
+                               _state == PcmPlayerState.resuming ||
+                               _state == PcmPlayerState.stopping;
+
+  /// Check if feeding should be blocked
+  bool get _shouldBlockFeeding => isTransitioning || _state == PcmPlayerState.paused;
+
+  /// Stream of elapsed time updates (emits every 500ms when playing)
+  Stream<Duration> get elapsedTimeStream => _elapsedTimeController.stream;
+
+  /// Calculate elapsed playback time from bytes played
+  /// For 48kHz stereo 16-bit: 4 bytes per frame, 48000 frames per second
+  Duration get elapsedTime {
+    // Bytes per frame = channels * (bitDepth / 8) = 2 * 2 = 4
+    final bytesPerFrame = _format.channels * (_format.bitDepth ~/ 8);
+    final framesFromBytes = _bytesPlayed / bytesPerFrame;
+    final elapsedSeconds = framesFromBytes / _format.sampleRate;
+    return Duration(milliseconds: (elapsedSeconds * 1000).round());
+  }
+
+  /// Get elapsed time in seconds (for convenience)
+  double get elapsedTimeSeconds {
+    final bytesPerFrame = _format.channels * (_format.bitDepth ~/ 8);
+    final framesFromBytes = _bytesPlayed / bytesPerFrame;
+    return framesFromBytes / _format.sampleRate;
+  }
+
+  /// Initialize the PCM player with the given format
+  Future<bool> initialize({PcmAudioFormat? format}) async {
+    if (_state == PcmPlayerState.initializing) return false;
+
+    _format = format ?? PcmAudioFormat.sendspin;
+    _state = PcmPlayerState.initializing;
+
+    try {
+      _logger.log('PcmAudioPlayer: Initializing (${_format.sampleRate}Hz, ${_format.channels}ch, ${_format.bitDepth}bit)');
+
+      // Setup flutter_pcm_sound with Sendspin audio format
+      await pcm.FlutterPcmSound.setup(
+        sampleRate: _format.sampleRate,
+        channelCount: _format.channels,
+      );
+
+      // Set feed threshold - request more data when buffer has fewer frames
+      // Lower threshold = lower latency but more risk of underruns
+      // Using _feedThreshold (5000 frames = ~104ms) for faster pause response
+      await pcm.FlutterPcmSound.setFeedThreshold(_feedThreshold);
+
+      // Set up feed callback for when buffer needs more data
+      pcm.FlutterPcmSound.setFeedCallback(_onFeedRequested);
+
+      // Set log level for debugging
+      await pcm.FlutterPcmSound.setLogLevel(pcm.LogLevel.standard);
+
+      _state = PcmPlayerState.ready;
+      _logger.log('PcmAudioPlayer: Initialized successfully');
+      return true;
+    } catch (e) {
+      _logger.log('PcmAudioPlayer: Initialization failed: $e');
+      _state = PcmPlayerState.error;
+      return false;
+    }
+  }
+
+  /// Callback when flutter_pcm_sound needs more audio data
+  void _onFeedRequested(int remainingFrames) {
+    // This is called from native when buffer is getting low
+    // Block feeding during pause, transitional states, or when not playing
+    if (_state != PcmPlayerState.playing) return;
+    if (_shouldBlockFeeding) return;
+    if (_audioBuffer.isEmpty || _isFeeding) return;
+
+    _feedNextChunk();
+  }
+
+  /// Connect to a Sendspin audio data stream and start playback
+  Future<bool> connectToStream(Stream<Uint8List> audioStream) async {
+    if (_state == PcmPlayerState.error || _state == PcmPlayerState.idle) {
+      _logger.log('PcmAudioPlayer: Cannot connect - player not initialized');
+      return false;
+    }
+
+    // Cancel any existing subscription
+    await _audioSubscription?.cancel();
+
+    _logger.log('PcmAudioPlayer: Connecting to audio stream');
+
+    // Subscribe to the audio stream
+    _audioSubscription = audioStream.listen(
+      _onAudioData,
+      onError: _onStreamError,
+      onDone: _onStreamDone,
+    );
+
+    return true;
+  }
+
+  /// Handle incoming audio data from the stream
+  void _onAudioData(Uint8List audioData) {
+    // Ignore data if in error state or if in transitional/paused state
+    if (_state == PcmPlayerState.error) return;
+    if (_shouldBlockFeeding) {
+      // Silently ignore audio data when paused or transitioning
+      // This prevents buffer accumulation during pause and any race conditions
+      return;
+    }
+
+    // Add to buffer
+    _audioBuffer.add(audioData);
+
+    // Start playback if not already started
+    if (!_isStarted && _state == PcmPlayerState.ready) {
+      _startPlayback();
+    }
+
+    // NOTE: Auto-resume from paused state has been removed to prevent race conditions.
+    // The provider should explicitly call play() when ready to resume.
+
+    // Feed data if not currently feeding
+    if (!_isFeeding && _isStarted) {
+      _feedNextChunk();
+    }
+  }
+
+  /// Start audio playback
+  Future<void> _startPlayback() async {
+    if (_isStarted) return;
+
+    try {
+      await pcm.FlutterPcmSound.start();
+      _isStarted = true;
+      _state = PcmPlayerState.playing;
+      _playbackStartTime = DateTime.now();
+      _startElapsedTimeTimer();
+      _logger.log('PcmAudioPlayer: Started playback');
+    } catch (e) {
+      _logger.log('PcmAudioPlayer: Error starting playback: $e');
+      _state = PcmPlayerState.error;
+    }
+  }
+
+  /// Start the elapsed time update timer
+  void _startElapsedTimeTimer() {
+    _elapsedTimeTimer?.cancel();
+    _elapsedTimeTimer = Timer.periodic(
+      const Duration(milliseconds: 500),
+      (_) => _emitElapsedTime(),
+    );
+    // Emit immediately
+    _emitElapsedTime();
+  }
+
+  /// Stop the elapsed time update timer
+  void _stopElapsedTimeTimer() {
+    _elapsedTimeTimer?.cancel();
+    _elapsedTimeTimer = null;
+  }
+
+  /// Emit the current elapsed time to listeners
+  void _emitElapsedTime() {
+    if (_state != PcmPlayerState.playing) return;
+
+    final elapsed = elapsedTime;
+    if (!_elapsedTimeController.isClosed) {
+      _elapsedTimeController.add(elapsed);
+    }
+    onElapsedTimeUpdate?.call(elapsed);
+  }
+
+  /// Feed the next chunk of audio data to the player
+  /// CRITICAL: Only feeds limited chunks to keep native buffer small (~200ms)
+  /// This enables faster pause response by minimizing buffered audio
+  Future<void> _feedNextChunk() async {
+    if (_isFeeding || _audioBuffer.isEmpty || _shouldBlockFeeding) return;
+
+    _isFeeding = true;
+    _feedCompleter = Completer<void>();
+
+    try {
+      int chunksProcessed = 0;
+
+      // CRITICAL: Only feed limited chunks to keep native buffer small
+      // This is the key to fast pause - we drain ~200ms instead of 5-8 seconds
+      while (_audioBuffer.isNotEmpty &&
+             chunksProcessed < _maxChunksPerFeed &&
+             _state == PcmPlayerState.playing &&
+             !_shouldBlockFeeding) {
+        final chunk = _audioBuffer.removeAt(0);
+
+        // Convert Uint8List (raw bytes) to Int16 samples
+        // Sendspin sends 16-bit little-endian PCM
+        final samples = _bytesToInt16List(chunk);
+
+        // Check state again before the async feed call
+        if (samples.isNotEmpty && !_shouldBlockFeeding) {
+          await pcm.FlutterPcmSound.feed(pcm.PcmArrayInt16.fromList(samples));
+
+          // Don't update stats if we got paused during the feed
+          if (!_shouldBlockFeeding) {
+            _framesPlayed++;
+            _bytesPlayed += chunk.length;
+            chunksProcessed++;
+
+            // Log periodically
+            if (_framesPlayed % 100 == 0) {
+              _logger.log('PcmAudioPlayer: Played $_framesPlayed frames (${(_bytesPlayed / 1024).toStringAsFixed(1)} KB)');
+            }
+          }
+        }
+
+        // Yield to event loop mid-feed to allow UI to respond
+        if (chunksProcessed % 4 == 0) {
+          await Future.delayed(Duration.zero);
+        }
+      }
+    } catch (e) {
+      // Don't log errors during pause/transition - expected when player is released
+      if (!_shouldBlockFeeding) {
+        _logger.log('PcmAudioPlayer: Error feeding audio: $e');
+        _emitError(PcmPlayerError.feedFailed, e.toString());
+      }
+    }
+
+    _isFeeding = false;
+    _feedCompleter?.complete();
+    _feedCompleter = null;
+  }
+
+  /// Emit an error to the callback
+  void _emitError(PcmPlayerError error, String message) {
+    _logger.log('PcmAudioPlayer: Error - $error: $message');
+    onError?.call(error, message);
+  }
+
+  /// Convert raw bytes (Uint8List) to Int16 samples
+  /// Assumes little-endian 16-bit PCM
+  List<int> _bytesToInt16List(Uint8List bytes) {
+    if (bytes.length < 2) return [];
+
+    final byteData = ByteData.sublistView(bytes);
+    final samples = <int>[];
+
+    for (int i = 0; i < bytes.length - 1; i += 2) {
+      samples.add(byteData.getInt16(i, Endian.little));
+    }
+
+    return samples;
+  }
+
+  /// Handle stream errors - notify listeners and pause playback
+  void _onStreamError(dynamic error) {
+    _logger.log('PcmAudioPlayer: Stream error: $error');
+    _emitError(PcmPlayerError.streamError, error.toString());
+
+    // Pause on stream error to prevent playback of corrupted/incomplete audio
+    if (_state == PcmPlayerState.playing) {
+      _logger.log('PcmAudioPlayer: Pausing due to stream error');
+      pause();
+    }
+  }
+
+  /// Handle stream completion
+  void _onStreamDone() {
+    _logger.log('PcmAudioPlayer: Audio stream ended');
+    // Don't stop immediately - let buffered audio finish
+  }
+
+  /// Start playback (if paused or ready)
+  /// Returns true if playback started successfully
+  Future<bool> play() async {
+    if (_state == PcmPlayerState.error) return false;
+    if (isTransitioning) {
+      _logger.log('PcmAudioPlayer: Cannot play - operation in progress (state: $_state)');
+      return false;
+    }
+
+    if (_state == PcmPlayerState.paused) {
+      // Resume from pause - need to re-initialize since we released on pause
+      _logger.log('PcmAudioPlayer: Resuming from pause at ${elapsedTime.inSeconds}s');
+      _state = PcmPlayerState.resuming;
+
+      // Re-initialize the PCM player (it was released on pause)
+      try {
+        await pcm.FlutterPcmSound.setup(
+          sampleRate: _format.sampleRate,
+          channelCount: _format.channels,
+        );
+        await pcm.FlutterPcmSound.setFeedThreshold(_feedThreshold);
+        pcm.FlutterPcmSound.setFeedCallback(_onFeedRequested);
+        await pcm.FlutterPcmSound.start();
+        _isStarted = true;
+      } catch (e) {
+        _logger.log('PcmAudioPlayer: Error re-initializing on resume: $e');
+        _emitError(PcmPlayerError.resumeFailed, e.toString());
+        _state = PcmPlayerState.error;
+        return false;
+      }
+
+      _state = PcmPlayerState.playing;
+      _startElapsedTimeTimer();
+
+      // Resume feeding - new audio will come from stream
+      if (!_isFeeding && _audioBuffer.isNotEmpty) {
+        _feedNextChunk();
+      }
+
+      _logger.log('PcmAudioPlayer: Resumed playback');
+      return true;
+    } else if (_state == PcmPlayerState.ready) {
+      await _startPlayback();
+      _logger.log('PcmAudioPlayer: Started playback');
+
+      // Start feeding
+      if (!_isFeeding && _audioBuffer.isNotEmpty) {
+        _feedNextChunk();
+      }
+      return true;
+    }
+
+    return false;
+  }
+
+  /// Pause playback - stops feeding and releases player for instant stop
+  /// Position is preserved via _bytesPlayed tracking
+  /// Uses release() to clear native buffer for instant audio stop
+  /// Returns true if pause was successful
+  Future<bool> pause() async {
+    if (_state != PcmPlayerState.playing) {
+      _logger.log('PcmAudioPlayer: Cannot pause - not playing (state: $_state)');
+      return false;
+    }
+
+    _logger.log('PcmAudioPlayer: Pause requested');
+
+    // Set pausing state FIRST to stop feed loop from starting new feeds
+    _state = PcmPlayerState.pausing;
+
+    // Clear our buffer - no more data will be fed
+    _audioBuffer.clear();
+
+    // Clear feed callback to prevent native from triggering more feeds
+    pcm.FlutterPcmSound.setFeedCallback(null);
+
+    // Mark as not feeding
+    _isFeeding = false;
+
+    // Save position and stop timer
+    _bytesPlayedAtLastPause = _bytesPlayed;
+    _stopElapsedTimeTimer();
+
+    // Schedule release() to clear native buffer - use Future.delayed to yield control
+    // This allows UI to update before the potentially blocking release() call
+    unawaited(Future.delayed(Duration.zero, () async {
+      try {
+        await pcm.FlutterPcmSound.release().timeout(
+          const Duration(milliseconds: 500),
+          onTimeout: () {
+            _logger.log('PcmAudioPlayer: Release timed out');
+            _emitError(PcmPlayerError.releaseTimeout, 'release() timed out');
+          },
+        );
+        _isStarted = false;
+        _logger.log('PcmAudioPlayer: Player released for instant stop');
+      } catch (e) {
+        _logger.log('PcmAudioPlayer: Release error (expected if already released): $e');
+      }
+    }));
+
+    // Transition to paused state
+    _state = PcmPlayerState.paused;
+    _logger.log('PcmAudioPlayer: Paused playback at ${elapsedTime.inSeconds}s');
+    return true;
+  }
+
+  /// Stop playback (clears buffer and resets position)
+  /// Returns true if stop was successful
+  Future<bool> stop() async {
+    if (_state == PcmPlayerState.idle) return true;
+
+    _logger.log('PcmAudioPlayer: Stop requested');
+
+    // Set stopping state to block any in-flight feed operations
+    _state = PcmPlayerState.stopping;
+    _isStarted = false;
+    _stopElapsedTimeTimer();
+
+    // Clear the feed callback to prevent native code from triggering new feeds
+    pcm.FlutterPcmSound.setFeedCallback(null);
+
+    // Wait for any in-progress feed operation to complete (with timeout)
+    final completer = _feedCompleter;
+    if (completer != null && !completer.isCompleted) {
+      await completer.future.timeout(
+        const Duration(milliseconds: 500),
+        onTimeout: () {
+          _logger.log('PcmAudioPlayer: Feed wait timed out on stop');
+        },
+      );
+    }
+
+    _audioBuffer.clear();
+    _isFeeding = false;
+
+    try {
+      await pcm.FlutterPcmSound.release();
+    } catch (e) {
+      _logger.log('PcmAudioPlayer: Error releasing: $e');
+    }
+
+    _state = PcmPlayerState.ready;
+    _framesPlayed = 0;
+    _bytesPlayed = 0;
+    _bytesPlayedAtLastPause = 0;
+    _playbackStartTime = null;
+    _logger.log('PcmAudioPlayer: Stopped playback');
+
+    // Re-initialize for next playback
+    await initialize(format: _format);
+    return true;
+  }
+
+  /// Reset position to zero (for new track) without stopping playback
+  void resetPosition() {
+    _framesPlayed = 0;
+    _bytesPlayed = 0;
+    _bytesPlayedAtLastPause = 0;
+    _playbackStartTime = DateTime.now();
+    _logger.log('PcmAudioPlayer: Position reset to 0');
+    _emitElapsedTime();
+  }
+
+  /// Disconnect from audio stream
+  Future<void> disconnect() async {
+    await _audioSubscription?.cancel();
+    _audioSubscription = null;
+    await stop();
+    _logger.log('PcmAudioPlayer: Disconnected from stream');
+  }
+
+  /// Release all resources
+  Future<void> dispose() async {
+    _logger.log('PcmAudioPlayer: Disposing...');
+
+    // Set stopping state to block any feed operations
+    _state = PcmPlayerState.stopping;
+    _isStarted = false;
+    _stopElapsedTimeTimer();
+
+    // Clear the feed callback first
+    pcm.FlutterPcmSound.setFeedCallback(null);
+
+    // Wait for any in-progress feed operation
+    final completer = _feedCompleter;
+    if (completer != null && !completer.isCompleted) {
+      await completer.future.timeout(
+        const Duration(milliseconds: 500),
+        onTimeout: () {
+          _logger.log('PcmAudioPlayer: Feed wait timed out on dispose');
+        },
+      );
+    }
+
+    _isFeeding = false;
+    await _audioSubscription?.cancel();
+    _audioSubscription = null;
+    _audioBuffer.clear();
+
+    try {
+      await pcm.FlutterPcmSound.release().timeout(
+        const Duration(milliseconds: 500),
+        onTimeout: () {
+          _logger.log('PcmAudioPlayer: Release timed out on dispose');
+        },
+      );
+    } catch (e) {
+      _logger.log('PcmAudioPlayer: Error releasing: $e');
+    }
+
+    if (!_elapsedTimeController.isClosed) {
+      await _elapsedTimeController.close();
+    }
+
+    _state = PcmPlayerState.idle;
+    _logger.log('PcmAudioPlayer: Disposed');
+  }
+}

lib/services/position_tracker.dart

@@ -0,0 +1,242 @@
+import 'dart:async';
+import 'package:flutter/foundation.dart';
+import 'debug_logger.dart';
+
+/// Single source of truth for playback position tracking.
+///
+/// This service eliminates race conditions by:
+/// 1. Being the ONLY place that calculates interpolated position
+/// 2. Using consistent interpolation (no mode switching mid-stream)
+/// 3. Capping position at track duration
+/// 4. Broadcasting position updates via a single stream
+///
+/// All consumers (UI, notification) should listen to [positionStream]
+/// instead of calculating position themselves.
+class PositionTracker {
+  final DebugLogger _logger = DebugLogger();
+
+  // Current state
+  String? _playerId;
+  bool _isPlaying = false;
+  Duration _duration = Duration.zero;
+
+  // Position tracking - we anchor to a known position and interpolate from there
+  double _anchorPosition = 0.0;  // Position in seconds at anchor time
+  DateTime _anchorTime = DateTime.now();  // When we set the anchor
+
+  // Interpolation timer
+  Timer? _interpolationTimer;
+
+  // Stream controller for position updates
+  final _positionController = StreamController<Duration>.broadcast();
+
+  // Last emitted position (to avoid redundant updates)
+  int _lastEmittedSeconds = -1;
+
+  /// Stream of position updates (emits every second when playing)
+  Stream<Duration> get positionStream => _positionController.stream;
+
+  /// Current position (can be called synchronously)
+  Duration get currentPosition {
+    if (!_isPlaying) {
+      return Duration(seconds: _anchorPosition.round());
+    }
+
+    final now = DateTime.now();
+    final elapsed = now.difference(_anchorTime).inMilliseconds / 1000.0;
+    final interpolated = _anchorPosition + elapsed;
+
+    // Cap at duration to prevent overflow
+    final capped = _duration.inSeconds > 0
+        ? interpolated.clamp(0.0, _duration.inSeconds.toDouble())
+        : interpolated.clamp(0.0, double.infinity);
+
+    return Duration(seconds: capped.round());
+  }
+
+  /// Current position in seconds (for compatibility)
+  double get currentPositionSeconds {
+    if (!_isPlaying) {
+      return _anchorPosition;
+    }
+
+    final now = DateTime.now();
+    final elapsed = now.difference(_anchorTime).inMilliseconds / 1000.0;
+    final interpolated = _anchorPosition + elapsed;
+
+    // Cap at duration
+    if (_duration.inSeconds > 0) {
+      return interpolated.clamp(0.0, _duration.inSeconds.toDouble());
+    }
+    return interpolated.clamp(0.0, double.infinity);
+  }
+
+  /// Update with fresh data from server.
+  ///
+  /// [playerId] - The player this update is for
+  /// [position] - Current position in seconds from server
+  /// [isPlaying] - Whether the player is currently playing
+  /// [duration] - Track duration (null if unknown)
+  /// [serverTimestamp] - Server's timestamp for when position was recorded (optional)
+  void updateFromServer({
+    required String playerId,
+    required double position,
+    required bool isPlaying,
+    Duration? duration,
+    double? serverTimestamp,
+  }) {
+    final bool playerChanged = _playerId != playerId;
+    final bool playStateChanged = _isPlaying != isPlaying;
+    final bool durationChanged = duration != null && _duration != duration;
+
+    _playerId = playerId;
+    _duration = duration ?? _duration;
+
+    // Calculate the best anchor position
+    double anchorPos = position;
+    bool hasStaleTimestamp = false;
+
+    // If server provides timestamp, use it to calculate current position more accurately
+    if (serverTimestamp != null && isPlaying) {
+      final now = DateTime.now().millisecondsSinceEpoch / 1000.0;
+      final serverAge = now - serverTimestamp;
+
+      // Only use server timestamp if it's reasonably fresh (< 30 seconds)
+      // and not in the future (clock skew)
+      if (serverAge >= 0 && serverAge < 30) {
+        anchorPos = position + serverAge;
+      } else {
+        // Timestamp is stale - mark this so we don't blindly trust the position
+        hasStaleTimestamp = true;
+      }
+    }
+
+    // Cap at duration
+    if (_duration.inSeconds > 0) {
+      anchorPos = anchorPos.clamp(0.0, _duration.inSeconds.toDouble());
+    }
+
+    // Detect if position jumped significantly (more than 3 seconds difference)
+    // This helps identify seeks or track changes
+    final currentInterpolated = currentPositionSeconds;
+    final positionDiff = (anchorPos - currentInterpolated).abs();
+    final isBackwardJump = anchorPos < currentInterpolated;
+    final isJumpToNearZero = anchorPos < 3.0;
+
+    // Detect suspicious backward jumps to 0 - likely bad server data
+    // This happens when some player types don't report elapsed_time correctly
+    final isSuspiciousReset = !playerChanged
+        && !playStateChanged
+        && !durationChanged
+        && isPlaying
+        && _isPlaying
+        && isBackwardJump
+        && isJumpToNearZero
+        && currentInterpolated > 3.0;
+
+    // Always update anchor when:
+    // 1. Player changed
+    // 2. Play state changed
+    // 3. Position jumped significantly (seek or track change) - BUT NOT if it's a suspicious reset
+    //    AND NOT if the timestamp is stale (stale data shouldn't override interpolated position)
+    // 4. We're not playing (paused state should reflect server position)
+    //
+    // Key insight: When timestamp is stale, the raw position from server is likely outdated.
+    // Our interpolated position is probably more accurate, so don't let stale data override it.
+    final shouldUpdateAnchor = playerChanged
+        || playStateChanged
+        || (positionDiff > 2 && !isSuspiciousReset && !hasStaleTimestamp)
+        || !isPlaying;
+
+    if (shouldUpdateAnchor) {
+      _anchorPosition = anchorPos;
+      _anchorTime = DateTime.now();
+    }
+
+    _isPlaying = isPlaying;
+
+    // Manage interpolation timer
+    if (isPlaying) {
+      _startInterpolationTimer();
+    } else {
+      _stopInterpolationTimer();
+      // Emit current position for paused state
+      _emitPosition();
+    }
+  }
+
+  /// Handle seek - immediately update position without waiting for server
+  void onSeek(double positionSeconds) {
+    _anchorPosition = positionSeconds;
+    _anchorTime = DateTime.now();
+    _lastEmittedSeconds = -1; // Force emit
+    _emitPosition();
+  }
+
+  /// Handle track change - reset position to 0
+  void onTrackChange(String playerId, Duration? newDuration) {
+    _playerId = playerId;
+    _duration = newDuration ?? Duration.zero;
+    _anchorPosition = 0.0;
+    _anchorTime = DateTime.now();
+    _lastEmittedSeconds = -1;
+    _emitPosition();
+  }
+
+  /// Handle player selection change
+  void onPlayerSelected(String playerId) {
+    if (_playerId != playerId) {
+      _playerId = playerId;
+      // Don't reset position - let updateFromServer handle it with actual data
+      _lastEmittedSeconds = -1;
+    }
+  }
+
+  /// Clear tracker state (e.g., when disconnecting)
+  void clear() {
+    _stopInterpolationTimer();
+    _playerId = null;
+    _isPlaying = false;
+    _anchorPosition = 0.0;
+    _duration = Duration.zero;
+    _lastEmittedSeconds = -1;
+  }
+
+  void _startInterpolationTimer() {
+    if (_interpolationTimer != null) return;
+
+    _interpolationTimer = Timer.periodic(const Duration(milliseconds: 250), (_) {
+      _emitPosition();
+    });
+
+    // Emit immediately
+    _emitPosition();
+  }
+
+  void _stopInterpolationTimer() {
+    _interpolationTimer?.cancel();
+    _interpolationTimer = null;
+  }
+
+  void _emitPosition() {
+    final pos = currentPosition;
+    final seconds = pos.inSeconds;
+
+    // Only emit if second changed (reduces unnecessary updates)
+    if (seconds != _lastEmittedSeconds) {
+      _lastEmittedSeconds = seconds;
+      _positionController.add(pos);
+    }
+  }
+
+  /// Check if position has reached or exceeded duration (track ended)
+  bool get hasReachedEnd {
+    if (_duration.inSeconds <= 0) return false;
+    return currentPositionSeconds >= _duration.inSeconds;
+  }
+
+  void dispose() {
+    _stopInterpolationTimer();
+    _positionController.close();
+  }
+}

lib/services/sendspin_service.dart

@@ -0,0 +1,616 @@
+import 'dart:async';
+import 'dart:convert';
+import 'dart:io';
+import 'dart:typed_data';
+import 'package:web_socket_channel/web_socket_channel.dart';
+import 'package:web_socket_channel/io.dart';
+import 'debug_logger.dart';
+import 'settings_service.dart';
+import 'device_id_service.dart';
+
+/// Connection state for Sendspin player
+enum SendspinConnectionState {
+  disconnected,
+  connecting,
+  connected,
+  error,
+}
+
+/// Callback types for Sendspin events
+typedef SendspinPlayCallback = void Function(String streamUrl, Map<String, dynamic> trackInfo);
+typedef SendspinPauseCallback = void Function();
+typedef SendspinStopCallback = void Function();
+typedef SendspinSeekCallback = void Function(int positionSeconds);
+typedef SendspinVolumeCallback = void Function(int volumeLevel);
+typedef SendspinAudioDataCallback = void Function(Uint8List audioData);
+typedef SendspinStreamStartCallback = void Function(Map<String, dynamic>? trackInfo);
+typedef SendspinStreamEndCallback = void Function();
+
+/// Service to manage Sendspin WebSocket connection for local playback
+/// Sendspin is the replacement for builtin_player in MA 2.7.0b20+
+///
+/// Connection strategy (smart fallback for external access):
+/// 1. If server is HTTPS, try external wss://{server}/sendspin first
+/// 2. Fall back to local_ws_url from API (ws://local-ip:8927/sendspin)
+/// 3. WebRTC fallback as last resort (requires TURN servers)
+class SendspinService {
+  final String serverUrl;
+  final _logger = DebugLogger();
+
+  WebSocketChannel? _channel;
+  Timer? _heartbeatTimer;
+  Timer? _reconnectTimer;
+
+  // Connection state
+  SendspinConnectionState _state = SendspinConnectionState.disconnected;
+  SendspinConnectionState get state => _state;
+
+  final _stateController = StreamController<SendspinConnectionState>.broadcast();
+  Stream<SendspinConnectionState> get stateStream => _stateController.stream;
+
+  // Player info
+  String? _playerId;
+  String? _playerName;
+  String? _connectedUrl;
+
+  String? get playerId => _playerId;
+  String? get playerName => _playerName;
+
+  // Event callbacks
+  SendspinPlayCallback? onPlay;
+  SendspinPauseCallback? onPause;
+  SendspinStopCallback? onStop;
+  SendspinSeekCallback? onSeek;
+  SendspinVolumeCallback? onVolume;
+  SendspinAudioDataCallback? onAudioData;
+  SendspinStreamStartCallback? onStreamStart;
+  SendspinStreamEndCallback? onStreamEnd;
+
+  // Audio data stream for raw PCM frames
+  final _audioDataController = StreamController<Uint8List>.broadcast();
+  Stream<Uint8List> get audioDataStream => _audioDataController.stream;
+
+  // Track audio streaming state
+  bool _isStreamingAudio = false;
+  int _audioFramesReceived = 0;
+
+  // Player state for reporting to server
+  bool _isPowered = true;
+  bool _isPlaying = false;
+  bool _isPaused = false;
+  int _position = 0;
+  int _volume = 100;
+  bool _isMuted = false;
+
+  bool _isDisposed = false;
+
+  SendspinService(this.serverUrl);
+
+  /// Initialize and connect to Sendspin server
+  /// Uses persistent player ID and username-based naming
+  Future<bool> connect() async {
+    if (_isDisposed) return false;
+    if (_state == SendspinConnectionState.connected) return true;
+
+    _updateState(SendspinConnectionState.connecting);
+
+    try {
+      // Get persistent player ID and name
+      _playerId = await DeviceIdService.getOrCreateDevicePlayerId();
+      _playerName = await SettingsService.getLocalPlayerName();
+
+      _logger.log('Sendspin: Connecting as "$_playerName" (ID: $_playerId)');
+
+      // Try connection strategies in order
+      bool connected = false;
+
+      // Strategy 1: If server is HTTPS, try external wss:// first
+      if (_isHttpsServer()) {
+        final externalUrl = _buildExternalSendspinUrl();
+        _logger.log('Sendspin: Trying external URL: $externalUrl');
+        connected = await _tryConnect(externalUrl, timeout: const Duration(seconds: 3));
+      }
+
+      // Strategy 2: If external failed or server is HTTP, try local connection
+      // Note: We would need local_ws_url from getSendspinConnectionInfo API
+      // For now, skip this step and fall back to WebRTC (handled by provider)
+
+      if (!connected) {
+        _logger.log('Sendspin: External connection failed, WebRTC fallback needed');
+        _updateState(SendspinConnectionState.error);
+        return false;
+      }
+
+      return true;
+    } catch (e) {
+      _logger.log('Sendspin: Connection error: $e');
+      _updateState(SendspinConnectionState.error);
+      return false;
+    }
+  }
+
+  /// Connect with a specific WebSocket URL (called by provider with local_ws_url)
+  Future<bool> connectWithUrl(String wsUrl) async {
+    if (_isDisposed) return false;
+    if (_state == SendspinConnectionState.connected) return true;
+
+    _updateState(SendspinConnectionState.connecting);
+
+    try {
+      _playerId = await DeviceIdService.getOrCreateDevicePlayerId();
+      _playerName = await SettingsService.getLocalPlayerName();
+
+      _logger.log('Sendspin: Connecting with URL: $wsUrl');
+
+      final connected = await _tryConnect(wsUrl, timeout: const Duration(seconds: 5));
+
+      if (!connected) {
+        _updateState(SendspinConnectionState.error);
+        return false;
+      }
+
+      return true;
+    } catch (e) {
+      _logger.log('Sendspin: Connection error: $e');
+      _updateState(SendspinConnectionState.error);
+      return false;
+    }
+  }
+
+  /// Attempt to connect to a specific WebSocket URL
+  Future<bool> _tryConnect(String url, {Duration timeout = const Duration(seconds: 5)}) async {
+    try {
+      // Connect to the base URL without query params - we send player info in hello message
+      _logger.log('Sendspin: Connecting to $url');
+
+      // Create WebSocket connection
+      final webSocket = await WebSocket.connect(url).timeout(timeout);
+
+      _channel = IOWebSocketChannel(webSocket);
+      _connectedUrl = url;
+
+      // Set up message listener BEFORE sending hello
+      _channel!.stream.listen(
+        _handleMessage,
+        onError: _handleError,
+        onDone: _handleDone,
+      );
+
+      // Send client/hello message immediately after connecting
+      // This is required by the Sendspin protocol - server waits for this
+      // Message format follows aiosendspin protocol spec
+      _logger.log('Sendspin: Sending client/hello with player_id=$_playerId');
+      _sendMessage({
+        'type': 'client/hello',
+        'payload': {
+          'client_id': _playerId,
+          'name': _playerName,
+          'version': 1,  // Protocol version (integer)
+          'supported_roles': ['player@v1'],
+          'player_support': {
+            'supported_formats': [
+              {
+                'codec': 'pcm',
+                'channels': 2,
+                'sample_rate': 48000,
+                'bit_depth': 16,
+              },
+            ],
+            'buffer_capacity': 1048576,  // 1MB buffer
+            'supported_commands': ['volume', 'mute'],
+          },
+        },
+      }, allowDuringHandshake: true);
+
+      // Wait for server acknowledgment (server sends welcome/registered after hello)
+      final ackReceived = await _waitForAck().timeout(
+        const Duration(seconds: 5),
+        onTimeout: () => false,
+      );
+
+      if (!ackReceived) {
+        _logger.log('Sendspin: No acknowledgment from server after hello');
+        await _channel?.sink.close();
+        _channel = null;
+        return false;
+      }
+
+      _logger.log('Sendspin: Connected and registered successfully');
+      _updateState(SendspinConnectionState.connected);
+      _startHeartbeat();
+
+      return true;
+    } catch (e) {
+      _logger.log('Sendspin: Connection attempt failed: $e');
+      return false;
+    }
+  }
+
+  /// Wait for server acknowledgment after connection
+  Completer<bool>? _ackCompleter;
+
+  Future<bool> _waitForAck() async {
+    _ackCompleter = Completer<bool>();
+    return _ackCompleter!.future;
+  }
+
+  /// Handle incoming WebSocket messages
+  /// WebSocket can send text frames (JSON control messages) or binary frames (PCM audio data)
+  void _handleMessage(dynamic message) {
+    // Check if this is binary audio data (Uint8List) or text (String)
+    if (message is List<int>) {
+      _handleBinaryAudioData(Uint8List.fromList(message));
+      return;
+    }
+
+    // Handle text messages (JSON)
+    if (message is! String) {
+      _logger.log('Sendspin: Unexpected message type: ${message.runtimeType}');
+      return;
+    }
+
+    try {
+      final data = jsonDecode(message) as Map<String, dynamic>;
+      final type = data['type'] as String?;
+
+      _logger.log('Sendspin: Received message type: $type');
+
+      switch (type) {
+        case 'server/hello':
+          // Server acknowledged our client/hello - we're registered!
+          _logger.log('Sendspin: Received server/hello - connection successful');
+          final payload = data['payload'] as Map<String, dynamic>?;
+          if (payload != null) {
+            _logger.log('Sendspin: Server name: ${payload['name']}, version: ${payload['version']}');
+            _logger.log('Sendspin: Active roles: ${payload['active_roles']}');
+          }
+          if (_ackCompleter != null && !_ackCompleter!.isCompleted) {
+            _ackCompleter!.complete(true);
+          }
+          // Send initial client/state immediately after handshake (required by spec)
+          // Note: These must use allowDuringHandshake since state is still 'connecting'
+          _sendInitialState();
+          // Also send initial time sync
+          _sendClientTime(allowDuringHandshake: true);
+          break;
+
+        case 'server/time':
+          // Server responded to our time sync - can be used to calculate clock offset
+          // For now, just log it (proper sync would use Kalman filter)
+          _logger.log('Sendspin: Received server/time response');
+          break;
+
+        case 'group/update':
+          // Group state update - store for reference but no response needed
+          _logger.log('Sendspin: Received group/update');
+          final groupPayload = data['payload'] as Map<String, dynamic>?;
+          if (groupPayload != null) {
+            _logger.log('Sendspin: Group state: ${groupPayload['playback_state']}');
+          }
+          break;
+
+        case 'stream/start':
+          // Server is starting to send audio data
+          _logger.log('Sendspin: Audio stream starting');
+          _isStreamingAudio = true;
+          _audioFramesReceived = 0;
+          _isPlaying = true;
+          _isPaused = false;
+          // Notify provider to start PCM player and foreground service
+          final streamPayload = data['payload'] as Map<String, dynamic>?;
+          onStreamStart?.call(streamPayload);
+          break;
+
+        case 'stream/end':
+          // Server finished sending audio data
+          _logger.log('Sendspin: Audio stream ended (received $_audioFramesReceived frames)');
+          _isStreamingAudio = false;
+          _isPlaying = false;
+          // Notify provider to stop PCM player
+          onStreamEnd?.call();
+          break;
+
+        case 'ack':
+        case 'connected':
+        case 'registered':
+          // Legacy/fallback acknowledgment types
+          if (_ackCompleter != null && !_ackCompleter!.isCompleted) {
+            _ackCompleter!.complete(true);
+          }
+          break;
+
+        case 'play':
+          // Server wants us to play audio (URL-based, not raw PCM)
+          final streamUrl = data['url'] as String?;
+          final trackInfo = data['track'] as Map<String, dynamic>? ?? {};
+          if (streamUrl != null && onPlay != null) {
+            _isPlaying = true;
+            _isPaused = false;
+            onPlay!(streamUrl, trackInfo);
+          }
+          break;
+
+        case 'pause':
+          _isPaused = true;
+          _isPlaying = false;
+          onPause?.call();
+          break;
+
+        case 'stop':
+          _isPlaying = false;
+          _isPaused = false;
+          _isStreamingAudio = false;
+          onStop?.call();
+          break;
+
+        case 'seek':
+          final position = data['position'] as int?;
+          if (position != null) {
+            _position = position;
+            onSeek?.call(position);
+          }
+          break;
+
+        case 'volume':
+          final level = data['level'] as int?;
+          if (level != null) {
+            _volume = level;
+            onVolume?.call(level);
+          }
+          break;
+
+        case 'ping':
+          // Respond to server ping
+          _sendMessage({'type': 'pong'});
+          break;
+
+        case 'error':
+          final errorMsg = data['message'] as String?;
+          _logger.log('Sendspin: Server error: $errorMsg');
+          break;
+
+        default:
+          _logger.log('Sendspin: Unknown message type: $type');
+      }
+    } catch (e) {
+      _logger.log('Sendspin: Error handling JSON message: $e');
+    }
+  }
+
+  /// Handle binary audio data (PCM frames from server)
+  /// Sendspin binary frame format:
+  /// - Byte 0: message type (uint8) - Type 4 = audio data
+  /// - Bytes 1-8: timestamp (int64 microseconds, little-endian) for synchronization
+  /// - Bytes 9+: actual PCM audio data (16-bit stereo 48kHz)
+  void _handleBinaryAudioData(Uint8List frame) {
+    // Minimum frame size: 1 (type) + 8 (timestamp) + 2 (at least one sample)
+    if (frame.length < 11) {
+      _logger.log('Sendspin: Binary frame too short: ${frame.length} bytes');
+      return;
+    }
+
+    // Parse header
+    final messageType = frame[0];
+
+    // Type 4 = audio data, other types may be used for other purposes
+    if (messageType != 4) {
+      _logger.log('Sendspin: Unexpected binary message type: $messageType');
+      return;
+    }
+
+    // Extract timestamp (bytes 1-8, little-endian int64)
+    final timestampBytes = ByteData.sublistView(frame, 1, 9);
+    final timestamp = timestampBytes.getInt64(0, Endian.little);
+
+    // Extract actual PCM audio data (everything after the 9-byte header)
+    final audioData = Uint8List.sublistView(frame, 9);
+
+    _audioFramesReceived++;
+
+    // Log periodically to avoid spam
+    if (_audioFramesReceived == 1) {
+      _logger.log('Sendspin: Receiving audio data (first frame: ${frame.length} bytes, audio: ${audioData.length} bytes, ts: $timestamp)');
+    } else if (_audioFramesReceived % 100 == 0) {
+      _logger.log('Sendspin: Received $_audioFramesReceived audio frames');
+    }
+
+    // Emit only the PCM audio data (without header) to stream for consumers
+    if (!_audioDataController.isClosed) {
+      _audioDataController.add(audioData);
+    }
+
+    // Call callback if registered
+    onAudioData?.call(audioData);
+  }
+
+  /// Handle WebSocket errors
+  void _handleError(dynamic error) {
+    _logger.log('Sendspin: WebSocket error: $error');
+    _updateState(SendspinConnectionState.error);
+    _scheduleReconnect();
+  }
+
+  /// Handle WebSocket close
+  void _handleDone() {
+    _logger.log('Sendspin: WebSocket closed');
+    _updateState(SendspinConnectionState.disconnected);
+    _scheduleReconnect();
+  }
+
+  /// Send a JSON message to the server
+  /// allowDuringHandshake: set to true to send messages before connection is established (e.g., hello)
+  void _sendMessage(Map<String, dynamic> message, {bool allowDuringHandshake = false}) {
+    if (_channel == null) return;
+
+    // During handshake, we need to send hello even though state is still 'connecting'
+    if (!allowDuringHandshake && _state != SendspinConnectionState.connected) return;
+
+    try {
+      final json = jsonEncode(message);
+      _logger.log('Sendspin: Sending message: ${message['type']}');
+      _channel!.sink.add(json);
+    } catch (e) {
+      _logger.log('Sendspin: Error sending message: $e');
+    }
+  }
+
+  /// Report current player state to server
+  /// Uses Sendspin protocol 'client/state' message format
+  void reportState({
+    bool? powered,
+    bool? playing,
+    bool? paused,
+    int? position,
+    int? volume,
+    bool? muted,
+  }) {
+    if (powered != null) _isPowered = powered;
+    if (playing != null) _isPlaying = playing;
+    if (paused != null) _isPaused = paused;
+    if (position != null) _position = position;
+    if (volume != null) _volume = volume;
+    if (muted != null) _isMuted = muted;
+
+    // Determine player state for Sendspin protocol
+    // 'synchronized' = ready/playing, 'idle' = not playing
+    final playerState = _isPlaying || _isPaused ? 'synchronized' : 'idle';
+
+    _sendMessage({
+      'type': 'client/state',
+      'payload': {
+        'player': {
+          'state': playerState,
+          'volume': _volume,
+          'muted': _isMuted,
+        },
+      },
+    });
+  }
+
+  /// Check if server URL is HTTPS
+  bool _isHttpsServer() {
+    return serverUrl.startsWith('https://') ||
+           serverUrl.startsWith('wss://') ||
+           (!serverUrl.contains('://') && !serverUrl.contains(':'));
+  }
+
+  /// Build external Sendspin WebSocket URL from server URL
+  String _buildExternalSendspinUrl() {
+    var url = serverUrl;
+
+    // Convert HTTP(S) to WS(S)
+    if (url.startsWith('https://')) {
+      url = 'wss://${url.substring(8)}';
+    } else if (url.startsWith('http://')) {
+      url = 'ws://${url.substring(7)}';
+    } else if (!url.startsWith('ws://') && !url.startsWith('wss://')) {
+      url = 'wss://$url';
+    }
+
+    // Remove trailing slash and add /sendspin path
+    url = url.replaceAll(RegExp(r'/+$'), '');
+
+    // Remove any existing path and add /sendspin
+    final uri = Uri.parse(url);
+    return Uri(
+      scheme: uri.scheme,
+      host: uri.host,
+      port: uri.hasPort ? uri.port : null,
+      path: '/sendspin',
+    ).toString();
+  }
+
+  /// Start heartbeat timer using Sendspin's client/time for clock synchronization
+  void _startHeartbeat() {
+    _stopHeartbeat();
+    _heartbeatTimer = Timer.periodic(const Duration(seconds: 30), (_) {
+      _sendClientTime();
+    });
+  }
+
+  /// Send client/time message for clock synchronization (Sendspin protocol)
+  void _sendClientTime({bool allowDuringHandshake = false}) {
+    final timestampMicroseconds = DateTime.now().microsecondsSinceEpoch;
+    _sendMessage({
+      'type': 'client/time',
+      'payload': {
+        'timestamp': timestampMicroseconds,
+      },
+    }, allowDuringHandshake: allowDuringHandshake);
+  }
+
+  /// Send initial client/state immediately after handshake (required by Sendspin spec)
+  /// Must use allowDuringHandshake since state is still 'connecting' at this point
+  void _sendInitialState() {
+    _logger.log('Sendspin: Sending initial client/state');
+    _sendMessage({
+      'type': 'client/state',
+      'payload': {
+        'player': {
+          'state': 'synchronized',
+          'volume': _volume,
+          'muted': _isMuted,
+        },
+      },
+    }, allowDuringHandshake: true);
+  }
+
+  /// Stop heartbeat timer
+  void _stopHeartbeat() {
+    _heartbeatTimer?.cancel();
+    _heartbeatTimer = null;
+  }
+
+  /// Schedule reconnection attempt
+  void _scheduleReconnect() {
+    if (_isDisposed) return;
+
+    _reconnectTimer?.cancel();
+    _reconnectTimer = Timer(const Duration(seconds: 5), () {
+      if (!_isDisposed && _state != SendspinConnectionState.connected) {
+        _logger.log('Sendspin: Attempting reconnection...');
+        if (_connectedUrl != null) {
+          connectWithUrl(_connectedUrl!);
+        }
+      }
+    });
+  }
+
+  /// Update connection state
+  void _updateState(SendspinConnectionState newState) {
+    if (_state != newState) {
+      _state = newState;
+      _stateController.add(newState);
+    }
+  }
+
+  /// Disconnect from server using Sendspin's client/goodbye message
+  Future<void> disconnect() async {
+    _stopHeartbeat();
+    _reconnectTimer?.cancel();
+
+    if (_channel != null) {
+      // Send graceful goodbye per Sendspin protocol
+      _sendMessage({
+        'type': 'client/goodbye',
+        'payload': {
+          'reason': 'user_request',
+        },
+      });
+      await _channel!.sink.close();
+      _channel = null;
+    }
+
+    _updateState(SendspinConnectionState.disconnected);
+  }
+
+  /// Dispose the service
+  void dispose() {
+    _isDisposed = true;
+    _stopHeartbeat();
+    _reconnectTimer?.cancel();
+    _channel?.sink.close();
+    _stateController.close();
+    _audioDataController.close();
+  }
+}

lib/widgets/album_card.dart

@@ -7,8 +7,9 @@ import '../screens/album_details_screen.dart';
 import '../constants/hero_tags.dart';
 import '../theme/theme_provider.dart';
 import '../utils/page_transitions.dart';
+import '../services/metadata_service.dart';
 
-class AlbumCard extends StatelessWidget {
+class AlbumCard extends StatefulWidget {
   final Album album;
   final VoidCallback? onTap;
   final String? heroTagSuffix;
@@ -20,26 +21,82 @@ class AlbumCard extends StatelessWidget {
     this.heroTagSuffix,
   });
 
+  @override
+  State<AlbumCard> createState() => _AlbumCardState();
+}
+
+class _AlbumCardState extends State<AlbumCard> {
+  String? _fallbackImageUrl;
+  bool _triedFallback = false;
+  bool _maImageFailed = false;
+  String? _cachedMaImageUrl;
+
+  @override
+  void initState() {
+    super.initState();
+    _initFallbackImage();
+  }
+
+  void _initFallbackImage() {
+    // Check if MA has an image after first build, then fetch fallback if needed
+    WidgetsBinding.instance.addPostFrameCallback((_) {
+      if (!mounted) return;
+      final maProvider = context.read<MusicAssistantProvider>();
+      final maImageUrl = maProvider.api?.getImageUrl(widget.album, size: 256);
+      _cachedMaImageUrl = maImageUrl;
+
+      if (maImageUrl == null && !_triedFallback) {
+        _triedFallback = true;
+        _fetchFallbackImage();
+      }
+    });
+  }
+
+  Future<void> _fetchFallbackImage() async {
+    final fallbackUrl = await MetadataService.getAlbumImageUrl(
+      widget.album.name,
+      widget.album.artistsString,
+    );
+    if (fallbackUrl != null && mounted) {
+      setState(() {
+        _fallbackImageUrl = fallbackUrl;
+      });
+    }
+  }
+
+  void _onImageError() {
+    // When MA image fails to load, try Deezer fallback
+    if (!_triedFallback && !_maImageFailed) {
+      _maImageFailed = true;
+      _triedFallback = true;
+      _fetchFallbackImage();
+    }
+  }
+
   @override
   Widget build(BuildContext context) {
     final maProvider = context.read<MusicAssistantProvider>();
-    final imageUrl = maProvider.api?.getImageUrl(album, size: 256);
+    // Use cached URL if available, otherwise get fresh
+    final maImageUrl = _cachedMaImageUrl ?? maProvider.api?.getImageUrl(widget.album, size: 256);
     final colorScheme = Theme.of(context).colorScheme;
     final textTheme = Theme.of(context).textTheme;
 
-    final suffix = heroTagSuffix != null ? '_$heroTagSuffix' : '';
+    final suffix = widget.heroTagSuffix != null ? '_${widget.heroTagSuffix}' : '';
+
+    // Use fallback if MA image failed or wasn't available
+    final imageUrl = (_maImageFailed || maImageUrl == null) ? _fallbackImageUrl : maImageUrl;
 
     return RepaintBoundary(
       child: GestureDetector(
-        onTap: onTap ?? () {
+        onTap: widget.onTap ?? () {
           // Update adaptive colors immediately on tap
           updateAdaptiveColorsFromImage(context, imageUrl);
           Navigator.push(
             context,
             FadeSlidePageRoute(
               child: AlbumDetailsScreen(
-                album: album,
-                heroTagSuffix: heroTagSuffix,
+                album: widget.album,
+                heroTagSuffix: widget.heroTagSuffix,
               ),
             ),
           );
@@ -51,7 +108,7 @@ class AlbumCard extends StatelessWidget {
             AspectRatio(
               aspectRatio: 1.0,
               child: Hero(
-                tag: HeroTags.albumCover + (album.uri ?? album.itemId) + suffix,
+                tag: HeroTags.albumCover + (widget.album.uri ?? widget.album.itemId) + suffix,
                 child: ClipRRect(
                   borderRadius: BorderRadius.circular(12.0),
                   child: Container(
@@ -64,11 +121,19 @@ class AlbumCard extends StatelessWidget {
                             memCacheHeight: 256,
                             fadeInDuration: const Duration(milliseconds: 150),
                             placeholder: (context, url) => const SizedBox(),
-                            errorWidget: (context, url, error) => Icon(
-                              Icons.album_rounded,
-                              size: 64,
-                              color: colorScheme.onSurfaceVariant,
-                            ),
+                            errorWidget: (context, url, error) {
+                              // Try fallback on error (only for MA URLs, not fallback URLs)
+                              if (!_maImageFailed && url == maImageUrl) {
+                                WidgetsBinding.instance.addPostFrameCallback((_) {
+                                  _onImageError();
+                                });
+                              }
+                              return Icon(
+                                Icons.album_rounded,
+                                size: 64,
+                                color: colorScheme.onSurfaceVariant,
+                              );
+                            },
                           )
                         : Center(
                             child: Icon(
@@ -84,11 +149,11 @@ class AlbumCard extends StatelessWidget {
           const SizedBox(height: 8),
           // Album title
           Hero(
-            tag: HeroTags.albumTitle + (album.uri ?? album.itemId) + suffix,
+            tag: HeroTags.albumTitle + (widget.album.uri ?? widget.album.itemId) + suffix,
             child: Material(
               color: Colors.transparent,
               child: Text(
-                album.name,
+                widget.album.name,
                 maxLines: 1,
                 overflow: TextOverflow.ellipsis,
                 style: textTheme.titleSmall?.copyWith(
@@ -100,11 +165,11 @@ class AlbumCard extends StatelessWidget {
           ),
           // Artist name
           Hero(
-            tag: HeroTags.artistName + (album.uri ?? album.itemId) + suffix,
+            tag: HeroTags.artistName + (widget.album.uri ?? widget.album.itemId) + suffix,
             child: Material(
               color: Colors.transparent,
               child: Text(
-                album.artistsString,
+                widget.album.artistsString,
                 maxLines: 1,
                 overflow: TextOverflow.ellipsis,
                 style: textTheme.bodySmall?.copyWith(

lib/widgets/artist_avatar.dart

@@ -28,7 +28,10 @@ class ArtistAvatar extends StatefulWidget {
 
 class _ArtistAvatarState extends State<ArtistAvatar> {
   String? _imageUrl;
+  String? _maImageUrl;
+  String? _fallbackImageUrl;
   bool _triedFallback = false;
+  bool _maImageFailed = false;
 
   @override
   void initState() {
@@ -41,6 +44,8 @@ class _ArtistAvatarState extends State<ArtistAvatar> {
 
     // Try MA first
     final maUrl = provider.getImageUrl(widget.artist, size: widget.imageSize);
+    _maImageUrl = maUrl;
+
     if (maUrl != null) {
       if (mounted) {
         setState(() {
@@ -51,16 +56,30 @@ class _ArtistAvatarState extends State<ArtistAvatar> {
       return;
     }
 
-    // Fallback to external sources
-    if (!_triedFallback) {
-      _triedFallback = true;
-      final fallbackUrl = await MetadataService.getArtistImageUrl(widget.artist.name);
-      if (fallbackUrl != null && mounted) {
-        setState(() {
-          _imageUrl = fallbackUrl;
-        });
-        widget.onImageLoaded?.call(fallbackUrl);
-      }
+    // Fallback to external sources (MA returned null)
+    _fetchFallbackImage();
+  }
+
+  Future<void> _fetchFallbackImage() async {
+    if (_triedFallback) return;
+    _triedFallback = true;
+
+    final fallbackUrl = await MetadataService.getArtistImageUrl(widget.artist.name);
+    _fallbackImageUrl = fallbackUrl;
+
+    if (fallbackUrl != null && mounted) {
+      setState(() {
+        _imageUrl = fallbackUrl;
+      });
+      widget.onImageLoaded?.call(fallbackUrl);
+    }
+  }
+
+  void _onImageError() {
+    // When MA image fails to load, try Deezer fallback
+    if (!_maImageFailed) {
+      _maImageFailed = true;
+      _fetchFallbackImage();
     }
   }
 
@@ -68,13 +87,49 @@ class _ArtistAvatarState extends State<ArtistAvatar> {
   Widget build(BuildContext context) {
     final colorScheme = Theme.of(context).colorScheme;
 
-    final avatar = CircleAvatar(
-      radius: widget.radius,
-      backgroundColor: colorScheme.surfaceVariant,
-      backgroundImage: _imageUrl != null ? CachedNetworkImageProvider(_imageUrl!) : null,
-      child: _imageUrl == null
-          ? Icon(Icons.person_rounded, color: colorScheme.onSurfaceVariant)
-          : null,
+    // Use fallback if MA image failed
+    final displayUrl = (_maImageFailed && _fallbackImageUrl != null)
+        ? _fallbackImageUrl
+        : _imageUrl;
+
+    Widget avatarContent;
+    if (displayUrl != null) {
+      avatarContent = ClipOval(
+        child: CachedNetworkImage(
+          imageUrl: displayUrl,
+          width: widget.radius * 2,
+          height: widget.radius * 2,
+          fit: BoxFit.cover,
+          placeholder: (context, url) => Container(
+            color: colorScheme.surfaceVariant,
+            child: Icon(Icons.person_rounded, color: colorScheme.onSurfaceVariant),
+          ),
+          errorWidget: (context, url, error) {
+            // Try fallback on error (only for MA URLs, not fallback URLs)
+            if (!_maImageFailed && url == _maImageUrl) {
+              WidgetsBinding.instance.addPostFrameCallback((_) {
+                _onImageError();
+              });
+            }
+            return Container(
+              color: colorScheme.surfaceVariant,
+              child: Icon(Icons.person_rounded, color: colorScheme.onSurfaceVariant),
+            );
+          },
+        ),
+      );
+    } else {
+      avatarContent = CircleAvatar(
+        radius: widget.radius,
+        backgroundColor: colorScheme.surfaceVariant,
+        child: Icon(Icons.person_rounded, color: colorScheme.onSurfaceVariant),
+      );
+    }
+
+    final avatar = SizedBox(
+      width: widget.radius * 2,
+      height: widget.radius * 2,
+      child: avatarContent,
     );
 
     if (widget.heroTag != null) {

lib/widgets/artist_card.dart

@@ -32,6 +32,7 @@ class _ArtistCardState extends State<ArtistCard> {
   static final _logger = DebugLogger();
   String? _fallbackImageUrl;
   bool _triedFallback = false;
+  bool _maImageFailed = false;
   String? _cachedMaImageUrl;
 
   @override
@@ -57,6 +58,16 @@ class _ArtistCardState extends State<ArtistCard> {
     });
   }
 
+  void _onImageError() {
+    // When MA image fails to load, try Deezer fallback
+    if (!_triedFallback && !_maImageFailed) {
+      _maImageFailed = true;
+      _triedFallback = true;
+      _logger.debug('MA image failed for "${widget.artist.name}", trying fallback', context: 'ArtistCard');
+      _fetchFallbackImage();
+    }
+  }
+
   @override
   Widget build(BuildContext context) {
     final maProvider = context.read<MusicAssistantProvider>();
@@ -67,8 +78,8 @@ class _ArtistCardState extends State<ArtistCard> {
 
     final suffix = widget.heroTagSuffix != null ? '_${widget.heroTagSuffix}' : '';
 
-    // Use MA image if available, otherwise try fallback
-    final imageUrl = maImageUrl ?? _fallbackImageUrl;
+    // Use fallback if MA image failed or wasn't available
+    final imageUrl = (_maImageFailed || maImageUrl == null) ? _fallbackImageUrl : maImageUrl;
 
     return RepaintBoundary(
       child: GestureDetector(
@@ -113,11 +124,19 @@ class _ArtistCardState extends State<ArtistCard> {
                                   memCacheHeight: 256,
                                   fadeInDuration: const Duration(milliseconds: 150),
                                   placeholder: (context, url) => const SizedBox(),
-                                  errorWidget: (context, url, error) => Icon(
-                                    Icons.person_rounded,
-                                    size: size * 0.55,
-                                    color: colorScheme.onSurfaceVariant,
-                                  ),
+                                  errorWidget: (context, url, error) {
+                                    // Try fallback on error (only for MA URLs, not fallback URLs)
+                                    if (!_maImageFailed && url == maImageUrl) {
+                                      WidgetsBinding.instance.addPostFrameCallback((_) {
+                                        _onImageError();
+                                      });
+                                    }
+                                    return Icon(
+                                      Icons.person_rounded,
+                                      size: size * 0.55,
+                                      color: colorScheme.onSurfaceVariant,
+                                    );
+                                  },
                                 )
                               : Icon(Icons.person_rounded, size: size * 0.55, color: colorScheme.onSurfaceVariant),
                         ),

lib/widgets/expandable_player.dart

@@ -51,9 +51,8 @@ class ExpandablePlayerState extends State<ExpandablePlayer>
   PlayerQueue? _queue;
   bool _isLoadingQueue = false;
 
-  // Progress timer for elapsed time updates
-  Timer? _progressTimer;
-  double? _seekPosition;
+  // Progress tracking - uses PositionTracker stream as single source of truth
+  StreamSubscription<Duration>? _positionSubscription;
   final ValueNotifier<int> _progressNotifier = ValueNotifier<int>(0);
   final ValueNotifier<double?> _seekPositionNotifier = ValueNotifier<double?>(null);
 
@@ -130,14 +129,15 @@ class ExpandablePlayerState extends State<ExpandablePlayer>
     _controller.addStatusListener((status) {
       if (status == AnimationStatus.forward) {
         _loadQueue();
-        _startProgressTimer();
       } else if (status == AnimationStatus.dismissed) {
-        _progressTimer?.cancel();
         // Close queue panel when player collapses
         _queuePanelController.reverse();
       }
     });
 
+    // Subscribe to position tracker stream - single source of truth for playback position
+    _subscribeToPositionTracker();
+
     // Auto-refresh queue when panel is open
     _queuePanelController.addStatusListener((status) {
       if (status == AnimationStatus.completed) {
@@ -170,7 +170,7 @@ class ExpandablePlayerState extends State<ExpandablePlayer>
     _controller.dispose();
     _queuePanelController.dispose();
     _slideController.dispose();
-    _progressTimer?.cancel();
+    _positionSubscription?.cancel();
     _queueRefreshTimer?.cancel();
     _progressNotifier.dispose();
     _seekPositionNotifier.dispose();
@@ -212,18 +212,14 @@ class ExpandablePlayerState extends State<ExpandablePlayer>
     );
   }
 
-  void _startProgressTimer() {
-    _progressTimer?.cancel();
-    // Use local player report interval for progress updates (1 second)
-    // Update only the progress notifier to avoid rebuilding the entire widget tree
-    _progressTimer = Timer.periodic(Timings.localPlayerReportInterval, (_) {
-      if (mounted && isExpanded) {
-        final maProvider = context.read<MusicAssistantProvider>();
-        final selectedPlayer = maProvider.selectedPlayer;
-        if (selectedPlayer != null) {
-          _progressNotifier.value = selectedPlayer.currentElapsedTime.toInt();
-        }
-      }
+  void _subscribeToPositionTracker() {
+    _positionSubscription?.cancel();
+    // Subscribe to position tracker stream - single source of truth
+    // This eliminates race conditions between multiple timers
+    final maProvider = context.read<MusicAssistantProvider>();
+    _positionSubscription = maProvider.positionTracker.positionStream.listen((position) {
+      if (!mounted) return;
+      _progressNotifier.value = position.inSeconds;
     });
   }
 
@@ -330,27 +326,69 @@ class ExpandablePlayerState extends State<ExpandablePlayer>
 
     try {
       if (_isCurrentTrackFavorite) {
-        // Remove from favorites
-        final libraryItemId = currentTrack.itemId;
-        if (libraryItemId is int) {
-          await maProvider.api!.removeFromFavorites('track', libraryItemId);
-        } else if (libraryItemId is String) {
-          final parsed = int.tryParse(libraryItemId);
-          if (parsed != null) {
-            await maProvider.api!.removeFromFavorites('track', parsed);
+        // Remove from favorites - need library_item_id (numeric)
+        int? libraryItemId;
+
+        if (currentTrack.provider == 'library') {
+          // If provider is library, itemId is the library ID
+          libraryItemId = int.tryParse(currentTrack.itemId.toString());
+        } else if (currentTrack.providerMappings != null) {
+          // Find the library mapping to get the library ID
+          final mappings = currentTrack.providerMappings as List<dynamic>?;
+          if (mappings != null) {
+            for (final mapping in mappings) {
+              if (mapping.providerInstance == 'library') {
+                libraryItemId = int.tryParse(mapping.itemId.toString());
+                break;
+              }
+            }
           }
         }
+
+        if (libraryItemId != null) {
+          await maProvider.api!.removeFromFavorites('track', libraryItemId);
+        } else {
+          throw Exception('Could not determine library ID for this track');
+        }
       } else {
-        // Add to favorites
-        final provider = currentTrack.provider as String? ?? 'library';
-        final itemId = currentTrack.itemId?.toString() ?? '';
-        await maProvider.api!.addToFavorites('track', itemId, provider);
+        // Add to favorites - use the source provider (not library)
+        String actualProvider = currentTrack.provider?.toString() ?? 'library';
+        String actualItemId = currentTrack.itemId?.toString() ?? '';
+
+        if (currentTrack.providerMappings != null) {
+          final mappings = currentTrack.providerMappings as List<dynamic>?;
+          if (mappings != null && mappings.isNotEmpty) {
+            // Find a non-library provider mapping
+            for (final mapping in mappings) {
+              if (mapping.available == true && mapping.providerInstance != 'library') {
+                actualProvider = mapping.providerInstance;
+                actualItemId = mapping.itemId;
+                break;
+              }
+            }
+            // Fallback to first available if no non-library found
+            if (actualProvider == 'library') {
+              for (final mapping in mappings) {
+                if (mapping.available == true) {
+                  actualProvider = mapping.providerInstance;
+                  actualItemId = mapping.itemId;
+                  break;
+                }
+              }
+            }
+          }
+        }
+
+        await maProvider.api!.addToFavorites('track', actualItemId, actualProvider);
       }
 
       // Toggle local state
       setState(() {
         _isCurrentTrackFavorite = !_isCurrentTrackFavorite;
       });
+
+      // Invalidate home cache so favorites are updated
+      maProvider.invalidateHomeCache();
     } catch (e) {
       // Show error feedback
       if (mounted) {
@@ -364,6 +402,50 @@ class ExpandablePlayerState extends State<ExpandablePlayer>
     }
   }
 
+  /// Show fullscreen album art overlay
+  void _showFullscreenArt(BuildContext context, String? imageUrl) {
+    if (imageUrl == null) return;
+
+    Navigator.of(context).push(
+      PageRouteBuilder(
+        opaque: false,
+        barrierColor: Colors.black87,
+        barrierDismissible: true,
+        pageBuilder: (context, animation, secondaryAnimation) {
+          return FadeTransition(
+            opacity: animation,
+            child: GestureDetector(
+              onTap: () => Navigator.of(context).pop(),
+              onVerticalDragEnd: (details) {
+                if (details.primaryVelocity != null && details.primaryVelocity!.abs() > 300) {
+                  Navigator.of(context).pop();
+                }
+              },
+              child: Scaffold(
+                backgroundColor: Colors.transparent,
+                body: Center(
+                  child: Hero(
+                    tag: 'fullscreen_album_art',
+                    child: InteractiveViewer(
+                      minScale: 0.5,
+                      maxScale: 3.0,
+                      child: CachedNetworkImage(
+                        imageUrl: imageUrl,
+                        fit: BoxFit.contain,
+                        memCacheWidth: 1024,
+                        memCacheHeight: 1024,
+                      ),
+                    ),
+                  ),
+                ),
+              ),
+            ),
+          );
+        },
+      ),
+    );
+  }
+
   /// Get available players sorted alphabetically (consistent with device selector)
   List<dynamic> _getAvailablePlayersSorted(MusicAssistantProvider maProvider) {
     // Use the provider's already-sorted list, filter for available only
@@ -506,11 +588,14 @@ class ExpandablePlayerState extends State<ExpandablePlayer>
   /// Animate committing to the next/previous player
   void _animateCommit(int direction, VoidCallback onSwitch) {
     if (_isSliding) return;
-    _isSliding = true;
 
-    // Mark transition BEFORE animation - this keeps peek content visible
-    // and hides main content to prevent any flash
-    _inTransition = true;
+    // Mark transition state in setState to ensure rebuilds happen properly
+    setState(() {
+      _isSliding = true;
+      // Mark transition BEFORE animation - this keeps peek content visible
+      // and hides main content to prevent any flash
+      _inTransition = true;
+    });
 
     final startOffset = _slideOffset;
     final targetOffset = direction < 0 ? -1.0 : 1.0;
@@ -696,6 +781,19 @@ class ExpandablePlayerState extends State<ExpandablePlayer>
         // Update favorite status when track changes
         _updateFavoriteStatus(currentTrack);
 
+        // Sync progress notifier with position tracker
+        // This ensures the progress bar shows correct position on expand,
+        // after seek, or when switching players
+        final currentPosition = maProvider.positionTracker.currentPosition.inSeconds;
+        if (_progressNotifier.value != currentPosition) {
+          // Use addPostFrameCallback to avoid updating during build
+          WidgetsBinding.instance.addPostFrameCallback((_) {
+            if (mounted) {
+              _progressNotifier.value = currentPosition;
+            }
+          });
+        }
+
         return AnimatedBuilder(
           animation: Listenable.merge([_expandAnimation, _queuePanelAnimation]),
           builder: (context, _) {
@@ -821,6 +919,8 @@ class ExpandablePlayerState extends State<ExpandablePlayer>
     final collapsedBg = themeProvider.adaptiveTheme && adaptiveScheme != null
         ? adaptiveScheme.primaryContainer
         : colorScheme.primaryContainer;
+    // Create a darker shade for the "unplayed" portion of progress bar
+    final collapsedBgUnplayed = Color.lerp(collapsedBg, Colors.black, 0.3)!;
     final expandedBg = adaptiveScheme?.surface ?? const Color(0xFF121212);
     // Only update if we have adaptive colors, otherwise keep previous value
     if (adaptiveScheme != null) {
@@ -828,7 +928,9 @@ class ExpandablePlayerState extends State<ExpandablePlayer>
     } else if (_currentExpandedBgColor == null) {
       _currentExpandedBgColor = expandedBg; // First time fallback
     }
-    final backgroundColor = Color.lerp(collapsedBg, expandedBg, t)!;
+    // When collapsed, use the darker unplayed color as base (progress bar will overlay the played portion)
+    // When expanded, transition to the normal background
+    final backgroundColor = Color.lerp(t < 0.5 ? collapsedBgUnplayed : collapsedBg, expandedBg, t)!;
 
     final collapsedTextColor = themeProvider.adaptiveTheme && adaptiveScheme != null
         ? adaptiveScheme.onPrimaryContainer
@@ -999,9 +1101,8 @@ class ExpandablePlayerState extends State<ExpandablePlayer>
       child: GestureDetector(
         // Use translucent to allow child widgets (like buttons) to receive taps
         behavior: HitTestBehavior.translucent,
-        onTap: () {
-          if (!isExpanded) expand();
-        },
+        // Only handle tap when collapsed - when expanded, let children handle their own taps
+        onTap: isExpanded ? null : expand,
         onVerticalDragUpdate: (details) {
           if (details.primaryDelta! < -10 && !isExpanded) {
             expand();
@@ -1061,6 +1162,46 @@ class ExpandablePlayerState extends State<ExpandablePlayer>
             child: Stack(
               clipBehavior: Clip.none,
               children: [
+                // Mini player progress bar background (collapsed only)
+                // Shows played portion with brighter color, unplayed with darker
+                // Starts after album art so progress is visible
+                // Slides with content during swipe, hidden during transition if peek available
+                if (t < 0.5 && currentTrack?.duration != null && !(_inTransition && t < 0.1 && _peekPlayer != null))
+                  Positioned(
+                    left: _collapsedArtSize + miniPlayerSlideOffset,
+                    top: 0,
+                    width: width - _collapsedArtSize,
+                    bottom: 0,
+                    child: ValueListenableBuilder<int>(
+                      valueListenable: _progressNotifier,
+                      builder: (context, elapsedSeconds, _) {
+                        final totalSeconds = currentTrack!.duration!.inSeconds;
+                        if (totalSeconds <= 0) return const SizedBox.shrink();
+                        final progress = (elapsedSeconds / totalSeconds).clamp(0.0, 1.0);
+                        // Fade out as we expand
+                        final progressOpacity = (1.0 - (t / 0.5)).clamp(0.0, 1.0);
+                        final progressAreaWidth = width - _collapsedArtSize;
+                        return Opacity(
+                          opacity: progressOpacity,
+                          child: ClipRRect(
+                            borderRadius: BorderRadius.only(
+                              topRight: Radius.circular(borderRadius),
+                              bottomRight: Radius.circular(borderRadius),
+                            ),
+                            child: Align(
+                              alignment: Alignment.centerLeft,
+                              child: Container(
+                                width: progressAreaWidth * progress,
+                                height: height,
+                                color: collapsedBg,
+                              ),
+                            ),
+                          ),
+                        );
+                      },
+                    ),
+                  ),
+
                 // Peek player content (shows when dragging OR during transition)
                 // Show when: actively dragging (slideOffset != 0) OR in transition state
                 // Must have peek data to render
@@ -1084,45 +1225,53 @@ class ExpandablePlayerState extends State<ExpandablePlayer>
 
                 // Album art - with slide animation when collapsed
                 // Hidden during transition to prevent flash (peek content shows instead)
+                // FALLBACK: Show main content if transition is active but peek content unavailable
+                // This prevents showing only the progress bar with no content
                 // GPU PERF: Use conditional instead of Opacity to avoid saveLayer
-                if (!(_inTransition && t < 0.1))
+                if (!(_inTransition && t < 0.1 && _peekPlayer != null))
                   Positioned(
                     left: artLeft + miniPlayerSlideOffset,
                     top: artTop,
-                    child: Container(
-                      width: artSize,
-                      height: artSize,
-                      decoration: BoxDecoration(
-                        borderRadius: BorderRadius.circular(artBorderRadius),
-                        // GPU PERF: Fixed blur/offset, only animate shadow opacity
-                        boxShadow: t > 0.3
-                            ? [
-                                BoxShadow(
-                                  color: Colors.black.withOpacity(0.25 * ((t - 0.3) / 0.7).clamp(0.0, 1.0)),
-                                  blurRadius: 20,
-                                  offset: const Offset(0, 8),
-                                ),
-                              ]
-                            : null,
-                      ),
-                      // Use RepaintBoundary to isolate art repaints during animation
-                      child: RepaintBoundary(
-                        child: ClipRRect(
+                    child: GestureDetector(
+                      behavior: HitTestBehavior.opaque,
+                      // Use onTapUp instead of onTap - resolves immediately and wins
+                      // the gesture arena against the outer vertical drag detector
+                      onTapUp: t > 0.5 ? (_) => _showFullscreenArt(context, imageUrl) : null,
+                      child: Container(
+                        width: artSize,
+                        height: artSize,
+                        decoration: BoxDecoration(
                           borderRadius: BorderRadius.circular(artBorderRadius),
-                          child: imageUrl != null
-                              ? CachedNetworkImage(
-                                  imageUrl: imageUrl,
-                                  fit: BoxFit.cover,
-                                  // Fixed cache size to avoid mid-animation cache thrashing
-                                  memCacheWidth: 512,
-                                  memCacheHeight: 512,
-                                  fadeInDuration: Duration.zero,
-                                  fadeOutDuration: Duration.zero,
-                                  placeholderFadeInDuration: Duration.zero,
-                                  placeholder: (_, __) => _buildPlaceholderArt(colorScheme, t),
-                                  errorWidget: (_, __, ___) => _buildPlaceholderArt(colorScheme, t),
-                                )
-                              : _buildPlaceholderArt(colorScheme, t),
+                          // GPU PERF: Fixed blur/offset, only animate shadow opacity
+                          boxShadow: t > 0.3
+                              ? [
+                                  BoxShadow(
+                                    color: Colors.black.withOpacity(0.25 * ((t - 0.3) / 0.7).clamp(0.0, 1.0)),
+                                    blurRadius: 20,
+                                    offset: const Offset(0, 8),
+                                  ),
+                                ]
+                              : null,
+                        ),
+                        // Use RepaintBoundary to isolate art repaints during animation
+                        child: RepaintBoundary(
+                          child: ClipRRect(
+                            borderRadius: BorderRadius.circular(artBorderRadius),
+                            child: imageUrl != null
+                                ? CachedNetworkImage(
+                                    imageUrl: imageUrl,
+                                    fit: BoxFit.cover,
+                                    // Fixed cache size to avoid mid-animation cache thrashing
+                                    memCacheWidth: 512,
+                                    memCacheHeight: 512,
+                                    fadeInDuration: Duration.zero,
+                                    fadeOutDuration: Duration.zero,
+                                    placeholderFadeInDuration: Duration.zero,
+                                    placeholder: (_, __) => _buildPlaceholderArt(colorScheme, t),
+                                    errorWidget: (_, __, ___) => _buildPlaceholderArt(colorScheme, t),
+                                  )
+                                : _buildPlaceholderArt(colorScheme, t),
+                          ),
                         ),
                       ),
                     ),
@@ -1130,8 +1279,9 @@ class ExpandablePlayerState extends State<ExpandablePlayer>
 
                 // Track title - with slide animation when collapsed
                 // Hidden during transition to prevent flash
+                // FALLBACK: Show if transition active but no peek content available
                 // GPU PERF: Use conditional instead of Opacity to avoid saveLayer
-                if (!(_inTransition && t < 0.1))
+                if (!(_inTransition && t < 0.1 && _peekPlayer != null))
                   Positioned(
                     left: titleLeft + miniPlayerSlideOffset,
                     top: titleTop,
@@ -1155,8 +1305,9 @@ class ExpandablePlayerState extends State<ExpandablePlayer>
 
                 // Artist name - with slide animation when collapsed
                 // Hidden during transition to prevent flash
+                // FALLBACK: Show if transition active but no peek content available
                 // GPU PERF: Use conditional instead of Opacity to avoid saveLayer
-                if (!(_inTransition && t < 0.1))
+                if (!(_inTransition && t < 0.1 && _peekPlayer != null))
                   Positioned(
                     left: titleLeft + miniPlayerSlideOffset,
                     top: artistTop,
@@ -1196,6 +1347,42 @@ class ExpandablePlayerState extends State<ExpandablePlayer>
                     ),
                   ),
 
+                // Audio source/format info (expanded only, when Sendspin active)
+                // Shows "Playing from Sendspin" and audio format
+                if (t > 0.5 && maProvider.isSendspinConnected)
+                  Positioned(
+                    left: contentPadding,
+                    right: contentPadding,
+                    top: expandedAlbumTop + (currentTrack.album != null ? 24 : 0),
+                    child: FadeTransition(
+                      opacity: _expandAnimation.drive(
+                        Tween(begin: 0.0, end: 1.0).chain(
+                          CurveTween(curve: const Interval(0.5, 1.0, curve: Curves.easeIn)),
+                        ),
+                      ),
+                      child: Row(
+                        mainAxisAlignment: MainAxisAlignment.center,
+                        children: [
+                          Icon(
+                            Icons.graphic_eq_rounded,
+                            size: 14,
+                            color: primaryColor.withOpacity(0.7),
+                          ),
+                          const SizedBox(width: 6),
+                          Text(
+                            maProvider.currentAudioFormat ?? 'PCM Audio',
+                            style: TextStyle(
+                              color: primaryColor.withOpacity(0.7),
+                              fontSize: 12,
+                              fontWeight: FontWeight.w500,
+                              letterSpacing: 0.3,
+                            ),
+                          ),
+                        ],
+                      ),
+                    ),
+                  ),
+
                 // Progress bar (expanded only)
                 // GPU PERF: Use FadeTransition instead of Opacity
                 if (t > 0.5 && currentTrack.duration != null)
@@ -1245,7 +1432,6 @@ class ExpandablePlayerState extends State<ExpandablePlayer>
                                           } finally {
                                             if (mounted) {
                                               _seekPositionNotifier.value = null;
-                                              _seekPosition = null;
                                             }
                                           }
                                         },
@@ -1634,6 +1820,56 @@ class ExpandablePlayerState extends State<ExpandablePlayer>
     );
   }
 
+  /// Build peek player progress bar that slides in during swipe
+  Widget _buildPeekProgressBar({
+    required double slideOffset,
+    required bool inTransition,
+    required double collapsedWidth,
+    required double progressAreaWidth,
+    required double height,
+    required double borderRadius,
+    required Color color,
+  }) {
+    // Calculate peek progress bar position (mirrors _buildPeekContent positioning)
+    double peekProgressLeft;
+    if (inTransition && slideOffset.abs() < 0.01) {
+      peekProgressLeft = _collapsedArtSize;
+    } else {
+      final isFromRight = slideOffset < 0;
+      final peekProgress = slideOffset.abs();
+      peekProgressLeft = _collapsedArtSize + (isFromRight
+          ? collapsedWidth * (1 - peekProgress)
+          : -collapsedWidth * (1 - peekProgress));
+    }
+
+    // Get peek player's elapsed time - safely handle null/invalid values
+    final peekElapsed = _peekPlayer?.currentElapsed ?? 0.0;
+    final peekTotal = _peekTrack?.duration?.inSeconds ?? 0;
+    if (peekTotal <= 0) return const SizedBox.shrink();
+    final peekProgressValue = (peekElapsed / peekTotal).clamp(0.0, 1.0);
+
+    return Positioned(
+      left: peekProgressLeft,
+      top: 0,
+      width: progressAreaWidth,
+      bottom: 0,
+      child: ClipRRect(
+        borderRadius: BorderRadius.only(
+          topRight: Radius.circular(borderRadius),
+          bottomRight: Radius.circular(borderRadius),
+        ),
+        child: Align(
+          alignment: Alignment.centerLeft,
+          child: Container(
+            width: progressAreaWidth * peekProgressValue,
+            height: height,
+            color: color,
+          ),
+        ),
+      ),
+    );
+  }
+
   Widget _buildPlaceholderArt(ColorScheme colorScheme, double t) {
     return Container(
       color: Color.lerp(colorScheme.surfaceVariant, const Color(0xFF2a2a2a), t),

pubspec.yaml

@@ -1,7 +1,7 @@
 name: ensemble
 description: A minimalistic Music Assistant client built with Flutter
 publish_to: 'none'
-version: 1.8.0+9
+version: 2.0.0-beta+15
 
 environment:
   sdk: '>=3.0.0 <4.0.0'
@@ -38,6 +38,9 @@ dependencies:
   audio_session: ^0.1.18
   flutter_volume_controller: ^1.3.2
 
+  # Raw PCM Audio Playback (for Sendspin streaming)
+  flutter_pcm_sound: ^3.3.3
+
 dev_dependencies:
   flutter_test:
     sdk: flutter