- Kotlin 100%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
There was nowhere on the page to get the app from - it explained how to compile it and left the APK unmentioned, and the newest release is the thing most people opening this page want. /releases/latest is a 303 to whichever tag is newest (checked: it currently lands on v0.2.1), so the link does not need editing when a release ships. Forgejo has no /releases/latest/download/<asset> route - that 404s - so the link goes to the release rather than straight at the file, and the asset name is versioned anyway. |
||
| app | ||
| .gitignore | ||
| build.gradle.kts | ||
| gradle.properties | ||
| README.md | ||
| settings.gradle.kts | ||
nvdroid
An Android client for Navidrome and other Subsonic-compatible music servers.
Install
Latest APK — sideload the
nvdroid-<version>.apk attached to the newest tag. That link resolves to whichever release
is newest, so it does not go stale.
Where this comes from
The app is new code — Kotlin, Jetpack Compose, Media3. No TMPlayer or nvdplayer code is compiled into it. What it takes from that lineage is a look and two algorithms.
From the nvdplayer TUI, which is a fork of TMPlayer:
- The palette, taken from nvdplayer's
themes/system.toml, which upstream TMPlayer wrote - Monospace type throughout,
[ bracket ]controls,┌ PANEL ┐frames, the tree's real connector lines, and spectrum bars
From nvdplayer specifically:
- The Subsonic auth scheme (
u/t/smd5 token, no plaintext password on the wire) and the whole-library load: onesearch3with an empty query, paged 500 songs at a time. That is what makes the library one shuffleable queue rather than an album at a time. - The scrobble rule: "now playing" when a track starts, the counted play at halfway or four minutes, whichever comes first, and only the four-minute rule when the length is unknown.
New here: the entire Android side — the Media3 service, Compose UI, Keystore-backed password storage, FFT spectrum, and cover art.
The equal-airtime shuffle in Shuffle.kt was written for this app first, and nvdplayer
adopted the same algorithm afterwards. It is the one TMPlayer defect this app fixes:
upstream's shuffle was a uniform random index, so an artist holding a third of the library
played a third of the time, and no reordering could change that — a permutation has to
contain every track. The queue here is a session instead, one turn per artist per round. The
other bugs nvdplayer fixes are in its playback, MPRIS, lyrics and terminal code, none of
which has an equivalent here.
Connect
- Open the app.
- Enter your server's base URL, username, and password.
- Tap TEST AND SAVE. The connection is checked before anything is stored; your library loads once it succeeds.
Passwords are encrypted with an Android Keystore key (AES-GCM); plaintext preferences written by earlier builds are migrated on first read and then removed. App backup is disabled because that key cannot be transferred to another device.
Cleartext HTTP is allowed, which is what a server on the LAN without TLS needs. Use HTTPS when connecting over an untrusted network.
Use
- LIBRARY — the artist > album > song tree, drawn with real connector lines. Tapping an artist queues that artist, an album queues that album, a song queues the whole library from that point.
- NOW PLAYING — cover art, seek as
────○────, volume asVOL ███░░░, the shuffle toggle, the up-next list, and bracketed transport buttons. - Playback continues in the background through a Media3 foreground service: notification, lock screen, and headset controls, with audio focus handled by Media3.
- Every play is scrobbled to the server — the "now playing" ping at the start and the counted play at halfway or four minutes. The app holds no Last.fm credentials; anything the server forwards is the server's business.
- The spectrum bars are driven by a real FFT of this app's own output session
(
android.media.audiofx.Visualizer). Denying the audio permission costs the bars and nothing else. - Tracks are streamed from the server as they play (
streamwithformat=raw, so the original file, not a transcode this app cannot decode).
Build
Requires JDK 17 and the Android SDK (platform 34, build-tools 34.0.0):
gradle testDebugUnitTest
gradle assembleDebug
27 JVM tests, no device needed — the Subsonic client, the shuffle and the scrobble rule are
all plain functions, tested against mockwebserver.
Release builds are unsigned unless signing values are supplied through environment variables. Keep the keystore and passwords outside the repository:
export NVDROID_KEYSTORE=/path/to/release.jks
export NVDROID_KEY_ALIAS=nvdroid
export NVDROID_KEYSTORE_PASSWORD='...'
export NVDROID_KEY_PASSWORD='...'
gradle assembleRelease
Known limits
- Android 8.0+ (minSdk 26), sideloaded APK, no store listing and no auto-update.
- Streaming only: there is no offline cache, so playback needs the server reachable.
- Navigation is the library tree alone — no search box, no server-playlist view. The album endpoints the client can speak are not wired to a grid.
- Shuffle builds one session when you press it and does not adapt as you listen. Equal airtime cuts both ways: a large artist's catalogue is mostly left alone in a session while single-track artists repeat.
- No license file yet, so default copyright applies.