Rust TUI music player for Navidrome/Subsonic (fork of TMPlayer): Discord RPC, album art, lyrics. Also builds on Android under Termux.
  • Rust 99.3%
  • Shell 0.7%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
ghomistty 7c2df8a285 README: split the page into upstream's work, this fork's work, and the bugs
The page described nvdplayer as if it were written from scratch, and the one
line crediting upstream had gone missing along the way. Both halves of that
are wrong for anyone deciding whether to use this: the local player,
equalizer, lyrics, cover art and visualization are TMPlayer's, unchanged,
and the Navidrome client, session rule and media keys are this fork's.

So the features are now two lists, each claimed by whoever wrote it, and the
bug fixes are a third table - each row is upstream behaviour as it was and
what happens here instead. The rows are read out of the commits that made
the changes: the MPRIS server, the session policy, prefetch, stall
detection, position clamping, the decoder thread, the lyrics fixes, the
folderless-library paths, the Termux build fixes, Arc<str> titles with cache
eviction, and the shuffle. The 0.2.5 removals (Discord RPC, Zipline, the
share key, SSH deletion) are stated once rather than left to be discovered.

The controls table was missing `d`, the playlist's Ctrl+arrow keys and Esc.

The Chinese README is deleted rather than left to disagree with this one. It
was a translation of the pre-fork page, so every feature list in it, and the
whole install section, described software this repository no longer is. The
fork notice points at TMPlayer, which is where upstream's own docs live.
2026-10-14 16:03:38 +03:00
.config 更新均衡器,添加本地音频内嵌封面支持 2025-12-16 20:45:01 +08:00
about Refresh nvdplayer dependencies for 0.2.6 2026-10-11 22:44:32 +03:00
config Prepare nvdplayer 0.2.5 release 2026-10-11 18:07:08 +03:00
src Refresh nvdplayer dependencies for 0.2.6 2026-10-11 22:44:32 +03:00
themes first upload 2025-12-12 22:10:00 +08:00
.gitignore Navidrome fork: Discord RPC, album art, lyrics fixes, and an Android port 2026-10-08 04:00:13 +03:00
.SRCINFO Refresh nvdplayer dependencies for 0.2.6 2026-10-11 22:44:32 +03:00
build.rs 更改项目名称 2026-03-13 17:45:15 +08:00
Cargo.lock Refresh nvdplayer dependencies for 0.2.6 2026-10-11 22:44:32 +03:00
Cargo.toml Refresh nvdplayer dependencies for 0.2.6 2026-10-11 22:44:32 +03:00
install.sh Refresh nvdplayer dependencies for 0.2.6 2026-10-11 22:44:32 +03:00
LICENSE first upload 2025-12-12 22:10:00 +08:00
logo.svg first upload 2025-12-12 22:10:00 +08:00
overview.png 更新readme 2025-12-16 17:47:22 +08:00
PKGBUILD Refresh nvdplayer dependencies for 0.2.6 2026-10-11 22:44:32 +03:00
README.md README: split the page into upstream's work, this fork's work, and the bugs 2026-10-14 16:03:38 +03:00
THIRD_PARTY_NOTICES.md 更改项目名称 2026-03-13 17:45:15 +08:00

nvdplayer

A keyboard-first terminal music player for local files and Navidrome/Subsonic libraries.

nvdplayer is a fork of TMPlayer (AGPL-3.0) by professor-lee. Upstream is a local-file Linux TUI player. This fork keeps that player whole — local playback, equalizer, lyrics, cover art, visualization — and adds a Navidrome client, media keys, and a session rule, and fixes a set of upstream bugs. The three sections after the controls separate what came from where.

Install

AUR notice: Registration is temporarily paused while Arch handles automated account creation. nvdplayer is not listed yet; I’ll submit it as soon as registration reopens. The installer below does not use the AUR, so it works while registration is paused.

The installer detects Arch, Debian/Ubuntu, Fedora, openSUSE, and Alpine, installs native build dependencies, then builds with Cargo. It asks for sudo/doas only when needed.

curl -fsSL https://git.ghomistty.com/misty/nvdplayer/raw/branch/main/install.sh | sh

Uninstall, preserving your settings and playback data:

curl -fsSL https://git.ghomistty.com/misty/nvdplayer/raw/branch/main/install.sh | sh -s -- uninstall

On Arch, you can also install directly with an AUR helper:

yay -S nvdplayer

Or build the AUR package manually:

sudo pacman -S --needed base-devel git
git clone https://aur.archlinux.org/nvdplayer.git
cd nvdplayer && makepkg -si

Until the AUR listing is available, Arch users can build directly with Cargo:

sudo pacman -S --needed base-devel cargo pkgconf alsa-lib dbus chromaprint
cargo install --git https://git.ghomistty.com/misty/nvdplayer.git --tag v0.2.6 --locked --bin nvdplayer

.pkg.tar.zst is Arch-only, not a cross-distro installer. On unsupported distributions, install Rust/Cargo plus pkg-config, ALSA, D-Bus, and Chromaprint development packages, then run cargo install --git https://git.ghomistty.com/misty/nvdplayer.git --tag v0.2.6 --locked --bin nvdplayer.

First run

Run nvdplayer. Press Ctrl+F to choose a local music folder or Ctrl+N to connect Navidrome. Enter the server URL, username, and password, then press Enter; credentials are saved in ~/.config/tmplayer/config/navidrome.toml as plaintext, with owner-only permissions. Use HTTPS over untrusted networks. Saved servers reconnect on startup by default.

Controls

Key Action
Space Play/pause
← / → Previous/next track
↑ / ↓ Volume
m Repeat mode
p Playlist
t Settings
e Equalizer
d Delete the playing local file (asks first; server tracks are refused)
Ctrl+F Open local folder
Ctrl+N Navidrome library
Ctrl+P Navidrome playlists
/ Search Navidrome
Ctrl+K Help
Esc Close the open overlay
q Quit

With the playlist open, Ctrl+↑ / Ctrl+↓ move a row and Ctrl+← / Ctrl+→ step albums. The mouse also works for transport controls, progress, volume, and playlist rows.

Features inherited from TMPlayer

Everything in this list is upstream's work, unchanged in behaviour:

  • Local playback, the playlist panel, the four repeat modes, and the equalizer
  • MPRIS as a client: reads and commands other players on the session bus
  • Lyrics display, with embedded or same-name .lrc files (including an lrc/ folder) read first and asynchronous LRCLIB lookup as the fallback
  • Cover art from embedded tags or a cover/ folder, then asynchronous MusicBrainz + Cover Art Archive lookup; ASCII art by default, Kitty graphics protocol if requested
  • Chromaprint fingerprint + AcoustID lookup when metadata is missing
  • Spectrum bars and oscilloscope, rendered from cava's stereo bars
  • Settings modal: theme, transparent background, album border, visualization mode, bar settings, Kitty graphics, cover quality, lyrics/cover fetch and download, audio fingerprinting, AcoustID key, resume last position, About
  • Catppuccin (latte/frappe/macchiato/mocha) and system themes, Nerd Font icons, mouse support
  • The bundle-cava Cargo feature, which builds cava from source during the build
  • Config under ~/.config/tmplayer/, state under ~/.local/share/tmplayer/, and the TMPLAYER_ASSET_DIR / TMPLAYER_DATA_DIR overrides. The crate is still named tmplayer so rebases against upstream stay clean; only the binary is called nvdplayer

Features added by nvdplayer

  • Navidrome/Subsonic client speaking Subsonic 1.16.1: Ctrl+N to connect, / to search, Ctrl+P for server playlists. Auth is the u/t/s md5 token that every Subsonic server accepts, with auth = "plain" as an escape hatch. Optional server-side transcode with a bitrate ceiling (transcode, max_bitrate).
  • The whole library as one queue. Albums are fetched via search3 with an empty query (match-everything), paged by songOffset. The album-list-then-getAlbum route measured 20s for the same library; this one takes ~600ms.
  • Progressive streaming with an on-disk cache (cache_mb, default 2048). A track plays while it downloads; a completed download is marked, and a marked file replays indistinguishably from a local one, seeking included. Eviction runs after each completed track and skips files in flight or pinned by the current track.
  • Next-track prefetch. The following track is warmed while the current one plays, so a track change takes the cache-hit path — measured 0ms against ~500ms cold.
  • Server lyrics via getLyricsBySongId, synced sets preferred and sorted by timestamp, falling back to LRCLIB only where the server has none.
  • Scrobbling: "now playing" when a track starts, and the counted play at halfway or four minutes, whichever comes first. Fire and forget; a failed scrobble never interrupts playback.
  • Per-server state and cache, keyed by url + username so two accounts never share one.
  • Auto-connect on launch (navidrome_auto_connect), fire and forget so an unreachable server delays nothing.
  • Media keys and desktop integration through an MPRIS server that registers org.mpris.MediaPlayer2.nvdplayer (see the bug table below).
  • session_policy — coexist (default), exclusive, yield — for sharing the audio session with other players.
  • Startup settings: startup_volume_percent (30), startup_repeat_mode (shuffle), autoplay_on_start, open_playlist_on_start.
  • Equal-airtime shuffle, the same algorithm nvdroid uses: one turn per artist per round, fewest-plays-first with random ties, never the artist that just played.
  • Delete the playing local file with d and a confirmation.
  • Android/Termux builds: aarch64-linux-android compiles, with the Linux-only dependencies gated behind the target.
  • Packaging: the multi-distro install.sh, a PKGBUILD, and the renamed binary.

Not in this fork: earlier 0.2.x builds carried Discord Rich Presence, a Zipline cover uploader, a copy-the-bot's-text key, and deletion of server tracks over SSH. All four were removed in 0.2.5; stale config keys are dropped when the config is read.

TMPlayer bugs fixed in nvdplayer

Each row is upstream behaviour as it was, and what this fork does instead.

TMPlayer behaviour In nvdplayer
Media keys did nothing: upstream is an MPRIS client only and exposes no interface of its own An MPRIS server serves PlayPause/Play/Pause/Stop/Next/Previous and the properties desktop widgets read. No session bus (a TTY login) means no media keys, and nothing else breaks.
Any MPRIS client reporting "playing" paused this player and switched the whole UI over to monitoring it. A background browser tab, or a player that exited without deregistering from the bus, was enough — and its last track, position and volume could be painted in while this player sat idle. session_policy decides. coexist (default) ignores other players, exclusive pauses them and keeps the session, yield restores upstream's behaviour exactly. The player's own bus name is filtered out of every client lookup, poll and command, so it cannot pause itself.
Because the rule was one-directional, a paused nvdplayer still silenced anything that started playing, and startup claimed the device unconditionally The rule is symmetric: a paused or stopped player leaves other players completely alone. Startup loads quietly and says so if something else is playing, instead of pausing it.
~500ms of silence between songs: a fresh HTTP request plus a 256KB prebuffer on every track change The next track is prefetched while the current one plays; the switch is a cache hit, measured at 0ms.
A mid-track rebuffer was read as the end of the track, because an empty sink was taken for EOF, and auto-advanced mid-song Stall detection is its own decision, separate from end-of-stream, and is gated so local playback is provably unchanged.
Position was extrapolated from wall-clock time, so it kept advancing while audio was stalled: lyrics drifted and the duration fallback eventually ended the track Position is clamped to the decoder's actual sample count. The progress bar freezes during a rebuffer rather than lying.
The decoder could be pulled from the audio callback thread, a blocking read inside the cpal callback — an underrun at best, a wedged device at worst Decoding runs on its own thread behind a bounded queue (~0.75s in flight) for streamed tracks.
Scraped page titles served as lyrics (1 Contributor<Song> Lyrics) were rendered verbatim. Navidrome serves these for instrumental tracks, where the lyrics source has nothing real to return. Recognised and dropped, with a debug log line.
Plain, unsynced lyrics kept only the first two lines, silently discarding the rest of the track's words Every line is kept.
Code that assumed a local folder exists: with a streamed library the browse list never synced into the play queue and Enter-to-play copied nothing, so Next and shuffle advanced from a stale index Both paths compare the folder options directly and handle a folderless library.
Android/Termux builds failed: cpal's JNI buffer-size probe panics without a JavaVM, which is every Termux process; oboe linked a static libc++ that Termux does not ship; cava retried 28 times a second when it was absent; and the temp directory was hardcoded to /tmp Linux-only dependencies are target-gated, oboe is linked against libc++_shared, cava backs off when missing, and the platform temp directory is used.
The queue is deep-cloned on every arrow keypress, which with String titles meant an allocation per track per keystroke, and the stream cache had no eviction at all Titles are Arc<str> (tested under 5ms per clone for a 20k-track queue) and eviction is wired to cache_mb.
Shuffle was clock_nanos % len — a uniform random index, so an artist holding a third of the library played a third of the time, and no reordering could fix that Equal-airtime shuffle, ported from nvdroid. Same algorithm on both clients, same artist key: first credit, case-folded.

Build from source

Requires Rust, Cargo, and the system libraries above:

cargo test --bin nvdplayer
cargo build --release
./target/release/nvdplayer

80 unit tests, several of them live against a real Navidrome server and #[ignore]d so the default run stays offline.

The optional bundle-cava Cargo feature builds cava from source during compilation; see build.rs and install its build dependencies first.

cava and Chromaprint are optional at runtime. Without them, playback still works; visualization and audio fingerprint lookup are unavailable.

License

AGPL-3.0, the same license as upstream TMPlayer. Third-party notices: THIRD_PARTY_NOTICES.md.