Repository navigation
Releases
KILO 3.5.0-Hybrid Client
🎯 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
KILO v3.4.5 — Browse Compilation Fix
KILO v3.4.5
This hotfix focuses on sound consistency, interface polish, and a Browse compilation fix.
Audio
- Refined loudness handling to help reduce volume differences between tracks.
- Kept the existing sound presets.
Interface
- Polished the player and appearance experience.
Fixes
- Corrected a missing scope closure in Browse that caused cascading Kotlin compilation errors and unresolved screen references.
KILO 3.4.0 — Adaptive Player, Home Layouts & Sound Improvements
This update makes KILO more comfortable to use across phone sizes and gives listeners more control over the Home screen and playback level.
- Adaptive full-screen player: artwork, spacing, and controls adjust to the available screen size. Track titles stay concise, and playback buttons have larger touch targets.
- Player volume slider: adjust output volume from the full-screen player. Your chosen level is retained when tracks change.
- Sound-level improvements: the Original profile keeps its EQ flat, with a modest output-level boost and conservative loudness matching when track analysis is available.
- Home layout choices: select Balanced, Editorial, Quick Play, Discovery, Library First, or Compact layouts. Custom Layout lets you reorder and hide Home sections.
- Faster Home feed: cached content can appear sooner while new catalog results load. Visible-track preparation is limited to 10 tracks per request.
- Setup flow: personalization is an optional setup step, and source sign-in remains optional.
KILO v3.3.0 — A Major Playlist and Playback Update
A better way to explore playlists
KILO v3.3.0 makes playlists easier to discover and more useful once you find them. Open a playlist from Home, Browse, or Search to see its tracks, then choose how you want to listen.
Playlist improvements
- Added playlist detail pages with a track list and playlist artwork.
- Added Play All, Like Tracks, and Smart Shuffle to playlist details.
- Search results now open playlist details when selected. The play button still starts playback directly.
- Added playlist shortcuts to Home and Browse.
- Kept playlist actions such as saving and downloading available from playlist options.
Playback reliability
- Improved recovery when a stream URL is rejected, so KILO can request a fresh source instead of repeatedly retrying the rejected one.
- Kept stream refresh work separate from the active playback path to reduce interruptions.
This release brings playlist browsing and playback recovery together in a more complete listening experience.
KILO v3.2.0 — Personalised Discovery, Playlist Tools and Playback Reliability
KILO v3.2.0
This release brings more personal music discovery, easier playlist management and playback reliability improvements.
- More personalised recommendations: Mood, genre and language selections now guide music results more closely, with stronger use of listening preferences.
- Improved Browse categories: Category results are better matched to the selected language, mood or genre, with refresh available for more results.
- Better playlist management: Save searched playlists to your library and use playlist options to manage or download all tracks.
- More reliable playback: Active streams refresh in the background, audio is cached further ahead, and expired or rejected streams recover more smoothly.
- Improved retries: A failed track start can be retried without repeated taps.
KILO v3.1.0 — A More Seamless Listening Experience
KILO v3.1.0 brings smoother transitions, richer lyrics, and a more personal Home feed.
What’s new
- True crossfade: Songs can overlap with a gradual, equal-power transition. KILO prepares the next track in the background while keeping the existing player and queue in control.
- Expanded lyrics: Enjoy synced lyrics, karaoke support, and improved lyrics caching.
- A more personal Home feed: New-release highlights, compact Quick Picks and Trending sections, and Play all actions make recommendations easier to explore.
Improvements
- Standby playback failures are isolated so they don’t take audio focus from the active player.
- Improved playback transition handling and general stability.
KILO v3.2.1 {HOTFIX}— Browse & Mood Discovery Improvements
KILO v3.2.1
Browse improvements
- Added personalized Songs for you and Listen again sections to Browse.
- Expanded sparse mood, genre, and language pages with additional relevant results.
- Improved Hindi results when tracks lack language tags, while respecting explicit language metadata.
Mood discovery
- Refined mood recommendations to provide a fuller set of relevant songs.
- Improved Choose My Mood recommendations.
KILO v3.0.1 Hotfix — Improved Song Recovery
- Fixed a recovery issue that could prevent some songs from loading after a stream URL was rejected.
- KILO now refreshes the failed stream and retries through the existing playback system.
- Preserved the current queue and autoplay intent during recovery.
KILO 2.8.0 — Better Discovery, Lyrics, and Android Auto
KILO 2.8.0
- Browse moods, genres, and languages through dedicated song pages.
- Added an Artists destination, with followed artists shown first.
- Search now includes public YouTube playlists alongside community playlists and saved YouTube Music playlists.
- Added synced current-line lyrics to the full-screen player and Android Auto.
- Added optional DJ queue ordering when track analysis is available.
- Added AudD song recognition with a one-time microphone disclosure.
- Added Drive Recap for Android Auto sessions, with skipped tracks left out.
- Added “Not for this mood” feedback that only affects the selected mood.
The existing playback engine, queue, downloads, and Android Auto playback flow remain in place.
KILO v3.0.0 — Audio Engine & Sound Profile Update
KILO v3.0.0
This release adds a sound profile layer with presets for different listening setups. The Original profile keeps a flat EQ and adds a modest volume boost, with peak limiting on supported Android versions. Existing sound presets remain available.
The audio enhancements connect to KILO’s existing player and audio session.
Changes
- Added output-aware sound profiles.
- Kept the Original profile’s tone flat while boosting its level.
- Preserved the existing EQ presets.
- Fixed audio session ID references in the sound profile layer.