Android client for Navidrome, styled after nvdplayer (TUI). Kotlin + Compose + Media3.
  • Kotlin 100%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Misty Hehe 404fdcabd9 README: link to the latest release instead of describing a build
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.
2026-10-14 16:16:33 +03:00
app Remove the share button and SSH delete, and encrypt the password 2026-10-14 16:07:12 +03:00
.gitignore nvdroid: Navidrome client for Android, styled after nvdplayer 2026-10-08 03:57:42 +03:00
build.gradle.kts nvdroid: Navidrome client for Android, styled after nvdplayer 2026-10-08 03:57:42 +03:00
gradle.properties nvdroid: Navidrome client for Android, styled after nvdplayer 2026-10-08 03:57:42 +03:00
README.md README: link to the latest release instead of describing a build 2026-10-14 16:16:33 +03:00
settings.gradle.kts nvdroid: Navidrome client for Android, styled after nvdplayer 2026-10-08 03:57:42 +03:00

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/s md5 token, no plaintext password on the wire) and the whole-library load: one search3 with 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

  1. Open the app.
  2. Enter your server's base URL, username, and password.
  3. 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 as VOL ███░░░, 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 (stream with format=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.