A native Android music streaming and offline player built with Kotlin, Jetpack Compose, Media3, and Room.
Search tracks, build local playlists, import public Spotify and YouTube playlists without logging in, follow synced lyrics, track your monthly Sound Capsule stats, and keep music cached for offline playback.
Features • Screenshots • Architecture & Stack • Install & Updates • Build • Release • Privacy & Notices
- Music-focused catalog search powered by the vendored
third_party/extractorlibrary filtered tomusic_songs, backed by an expiry-awareAudioResolutionCacheso Media3 seeks and lookahead buffering avoid redundant resolution requests. - Android Reel playback & SABR transport via
ReelPlaybackResolverand a custom Media3SabrRoutingDataSourceFactory(SabrDataSource,UmpReader,SabrSegmentAssembler) with throttling-parameter deobfuscation. - Responsive Now Playing UX featuring swipe gestures on the Mini Player for track navigation, adaptive gradient backgrounds sampled from album artwork, collapsing mini-header while scrolling through lyrics, and
MediaSessionServicenotification controls.
- Hybrid discovery radio: blends YouTube Music
WEB_REMIXautomix (SongRadioRepository) withNeighbourhoodRadiocollaborative-filtering lookups across MusicBrainz and ListenBrainz Labs (similar-recordingsandsimilar-artists). - Client-side ranking (
SongRadioMixer): promotes your liked and frequently completed tracks while gently demoting early skips without permanently hiding artists or tracks. Enforces artist spacing and window caps (ARTIST_WINDOW = 10,ARTIST_WINDOW_CAP = 2,SPACING_WINDOW = 2). - Flexible Queue & Sleep Timer: edit and reorder Up Next tracks, toggle Shuffle or Repeat (
Off/All/One), or set a Sleep Timer for a countdown duration or end of current song.
- Fetches timestamped
.lrcsynced lyrics and plain-text fallbacks from LRCLIB. - Highlights the active line automatically during playback and supports tap-to-seek to jump straight to any lyric line.
- Caches successful responses atomically on disk keyed by SHA-256, never caching transient network failures.
- Powered by Media3's persistent
DefaultDownloadIndexand a dedicatedSimpleCacheinside app storage (filesDirwithNoOpCacheEvictor) using stablesidea-trackURIs instead of short-lived stream URLs. - Manual vs. Automatic ownership: manually saved songs stay until you delete them, while automatic downloads cache songs you replay (
3+qualified listens) inside a configurable storage budget (default 500 MiB, max 25 tracked items) with an optional metered-network toggle. - Album artwork is persisted alongside offline tracks via
OfflineArtworkStoreand loaded through Coil 3'sOfflineArtworkInterceptor.
- Paste any public Spotify playlist link/ID or YouTube / YouTube Music playlist link/ID — no Spotify account or OAuth login required.
- Spotify links are parsed through public
/embed/playlist/{id}page metadata and PathfinderqueryPlaylistresponses (up to 2,000 tracks), then scored against YouTube Music candidates (scoreSpotifyCandidate) for title/artist match, duration closeness (±30s tolerance), and version consistency. - Unclear tracks are flagged as Review or Missing in an interactive review flow (
ImportScreen) so you can inspect or pick an alternate match before saving the playlist locally.
| Component | Technology / Details |
|---|---|
| Language | Kotlin 2.4.21 (JVM target 17, Coroutines 1.11.0) |
| UI | Jetpack Compose (BOM 2026.09.00), Material 3 (1.5.0-beta01), Activity Compose 1.13.0 |
| Playback & Offline | AndroidX Media3 1.11.1 (ExoPlayer, MediaSession, DataSource, Offline DownloadManager) |
| Database | Room 2.8.5 (SQLite schema v5, KSP 2.3.12) |
| Networking & Media | OkHttp 5.5.0, nanojson, Coil 3 3.6.3, custom SABR transport |
| Catalog Extractor | Vendored LevyraExtractor:v1.0.0-levyra.10 (android/third_party/extractor, GPL-3.0) |
| Build System | Gradle 9.8.1, Android Gradle Plugin 9.4.1, minSdk 26 / targetSdk 37 |
Spokify/
├── android/
│ ├── app/src/main/java/com/mitansh/sidea/
│ │ ├── MainActivity.kt # Single-activity Compose host & navigation wiring
│ │ ├── SideAApplication.kt # Coil 3 offline artwork & extractor initialization
│ │ ├── core/ # Track models, URL parsers, resolution cache
│ │ ├── data/
│ │ │ ├── history/ # Playback session timing & history policies
│ │ │ ├── imports/ # Import coordinator, session persistence, YouTube reader
│ │ │ ├── library/ # Room database (SideADatabase v5), DAOs, OnRepeatPolicy
│ │ │ ├── lyrics/ # LRCLIB client & SHA-256 disk cache
│ │ │ ├── offline/ # Media3 download cache, artwork store, budget policy
│ │ │ ├── radio/ # Radio preferences store
│ │ │ ├── similar/ # MusicBrainz & ListenBrainz NeighbourhoodRadio
│ │ │ ├── spotify/ # Public Spotify embed & Pathfinder playlist parser
│ │ │ └── youtube/ # Search, ReelPlaybackResolver, SongRadioMixer
│ │ ├── playback/
│ │ │ ├── sabr/ # SABR protocol, UMP reader, routing DataSource
│ │ │ ├── feedback/ # Skip/like feedback weights per artist & track
│ │ │ └── PlaybackService.kt # MediaSessionService, queue & sleep timer
│ │ ├── ui/ # Compose screens (Home, NowPlaying, Search, Library, Queue, etc.)
│ │ └── updates/ # GitHub Releases manifest check & APK verification
│ ├── third_party/extractor/ # Vendored LevyraExtractor Gradle composite build
│ ├── LICENSE # GNU GPL v3
│ └── THIRD_PARTY_NOTICES.md # Attribution and source notices
├── docs/screenshots/ # Emulator showcase screenshots
├── scripts/release.py # Verified APK packaging & GitHub Release publisher
└── CHANGELOG.md # Version release notes
- Download the latest APK (
spokify.apk) on your Android device (Android 8.0 / API 26 or newer) and confirm installation when prompted. - Updating an existing install with the same signing key preserves your entire Room library, playlists, listening stats, and offline downloads.
- In-app updates: Spokify checks GitHub Releases (
Mitanshp5/Spokify) once per calendar day on first app open, or manually anytime via Settings → App updates (Check for updates). - When a newer release is available, a yellow indicator dot appears on your top-bar profile button, on the Update Spokify item below Settings and privacy in the navigation drawer, and on the App updates row in Settings.
- Before launching Android's package installer, Spokify verifies the downloaded APK's SHA-256 digest, package ID (
com.mitansh.sidea), strictly higherversionCode, and matching signing certificate (AppUpdateViewModel).
- JDK 21 (project bytecode targets JVM 17)
- Android SDK Platform 37 configured via
ANDROID_HOMEor an untrackedandroid/local.properties
cd android
./gradlew :app:testDebugUnitTest :app:assembleDebug :app:assemblePerformanceOn Windows, use gradlew.bat instead of ./gradlew.
debug: unoptimized build for local development and testing (com.mitansh.sidea).performance: release-optimized build with R8 code & resource shrinking (-dontobfuscateinandroid/app/proguard-rules.prokeeps readable Kotlin symbol names for static analysis while stripping unused code and resources), signed with the developer debug key for side-loaded distribution.release: production build type with R8 shrinking enabled.
Signing Key Note: The public update channel checks that incoming updates match the original APK signing certificate (
~/.android/debug.keystoreforperformancebuilds). Back up your signing keystore if distributing updates; an APK signed by a different key cannot update an existing installation in place.
- Bump
spokify.versionCodeandspokify.versionNameinandroid/gradle.properties(every release requires a higherversionCode). - Run unit tests and assemble the
performanceAPK. - Commit and push the reviewed changes to
main. - Package and publish with Python 3.10+, Android SDK build tools, Java, and an authenticated GitHub CLI (
gh):
python scripts/release.py prepare
python scripts/release.py publish --directory android/.work/releases/v0.3.4Pass --notes path/to/notes.md to prepare to attach release notes without committing temporary note files. prepare validates the package ID, non-debuggable flag, and signer SHA-256 fingerprint before producing spokify.apk and spokify-update.json; publish uploads both to a draft release, verifies GitHub's asset SHA-256 digests, and promotes the release to latest.
- All personal data stays local: your profile name/avatar, playlists, Liked Songs, playback history, Sound Capsule stats, and offline downloads reside solely on your device in Room and app-private storage. No Spokify account or backend server exists.
- External services contacted: searches, artwork, stream playback, lyrics, radio enrichment, public playlist imports, and update checks contact their respective public upstream providers (
YouTube / YouTube Music,LRCLIB,MusicBrainz / ListenBrainz,Spotify public playlist embeds, andGitHub Releases).
See the license (GNU GPL v3), third-party notices, and the changelog.






