Repository navigation
π― Overview
Complete architectural overhaul of the Spotify integration with true crossfade, modular API client, and stability improvements across the entire playback stack.
π΅ Spotify Integration β Complete Rewrite
New Modular Architecture (auth/, net/, models/, parser/, mapping/, matching/)
- Single entry point: Spotify facade class β UI never touches raw DTOs, GraphQL, or auth tokens
- CQRS-lite separation: Read APIs (SpotifyLibraryQueryApi, SpotifyPlaylistQueryApi, SpotifyFeedApi, SpotifyAlbumApi, SpotifyArtistApi) vs Write APIs (SpotifyPlaylistMutationApi)
- High-level library facade: SpotifyLibraryApi combines query + mutation for liked tracks, saved albums, followed artists, playlists
- Cross-service track matching: TrackMatcher with Jaro-Winkler similarity for Spotify β YouTube Music / local deduplication
GraphQL Persisted Queries with Auto-Recovery
- HashProvider: In-memory + SharedPreferences caching with versioning
- HashDiscovery: Scrapes open.spotify.com JS bundles for operation hashes
- HashRefresher: Automatic invalidation/retry on PersistedQueryNotFound (400) with exponential backoff
- Validates hashes before caching via test requests
Authentication & Session Management
- TOTP generator (HmacSHA1) for Spotify Web Player token auth
- sp_dc cookie encrypted via Tink AES-256-GCM + Android Keystore
- Session auto-refresh with token exchange
- Client token caching (1-hour TTL) for GraphQL X-Spotify-Client-Token
Serialization & Parsing
- kotlinx.serialization across all DTOs with @contextual for recursive types
- Defensive JSON parser (SpotifyJsonParser) with fallback image extraction
- Mapper converts DTOs β clean domain models (HybridTrack, SongItemClean, SpotifyPlaylistSummary)
π True Crossfade β Native C++ Mixer
Dual-Deck Architecture (BitChord-inspired)
- Two ExoPlayer instances (Deck A active, Deck B standby) feeding native ring buffers
- Standby deck plays at volume 0 during priming β no pause/seek cycle
- Equal-power curves (cos/sin) for constant perceived loudness
- Automix EQ sweep: HPF 20 Hz β 350 Hz on outgoing deck during crossfade
- Backpressure monitoring: 80% buffer threshold signals ExoPlayer to throttle
Fixed "Fade Out But No Fade In" Bug
- Root cause: Native crossfade started before Deck B's buffer had audio data
- Fix: Async wait (β€100ms) for Deck B fill ratio >10% before triggering native crossfade
- Applied to both NativeCrossfadeController and NativeCrossfadeIntegration
Crossfade Metrics & Recovery
- CrossfadeMetrics: plan β start β overlap β handoff β finish lifecycle
- CrossfadeRecovery: automatic fallback on buffer underrun / decode failure
- TransitionScheduler: prepares next track early, starts fade at exact remaining-time moment
π Playback & Media Session
Media3 1.6.1 Session APIs
- MediaSessionCoordinator delegates to BackgroundPlaybackCoordinator
- Fixed seekToNextWindow/seekToPreviousWindow overrides (API removed in Media3)
- Android Auto / notification playback controls work correctly
Background Playback Coordinator
- Command-ledger pattern for play/pause/seek/queue mutations
- Crossfade integration via tick() called from existing player sampler
π Search & Library
Native Spotify Browsing in Main App
- Search uses new Spotify facade β REST fallback β SpotifyJsonParser
π Search & Library
Native Spotify Browsing in Main App
- Search uses new Spotify facade β REST fallback β SpotifyJsonParser
- Library tabs (Liked Songs, Playlists, Albums, Artists) β SpotifyLibraryApi
- Removed "Native Spotify" placeholder under login β full browsing now in-app
YouTube Shorts-Style Dynamic Recommendations
- "Your Daily Mix" shelf: personalized via PlayedSongHistory.getPersonalizedRecommendations()
- Mood/genre/artist preferences + discovery mode (Conservative/Balanced/Explorer)
- "Spotted, Not Started", "First Encounters", "For Your Mood" shelves