- Rust 99.3%
- Shell 0.7%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
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. |
||
| .config | ||
| about | ||
| config | ||
| src | ||
| themes | ||
| .gitignore | ||
| .SRCINFO | ||
| build.rs | ||
| Cargo.lock | ||
| Cargo.toml | ||
| install.sh | ||
| LICENSE | ||
| logo.svg | ||
| overview.png | ||
| PKGBUILD | ||
| README.md | ||
| THIRD_PARTY_NOTICES.md | ||
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
.lrcfiles (including anlrc/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-cavaCargo feature, which buildscavafrom source during the build - Config under
~/.config/tmplayer/, state under~/.local/share/tmplayer/, and theTMPLAYER_ASSET_DIR/TMPLAYER_DATA_DIRoverrides. The crate is still namedtmplayerso rebases against upstream stay clean; only the binary is callednvdplayer
Features added by nvdplayer
- Navidrome/Subsonic client speaking Subsonic 1.16.1:
Ctrl+Nto connect,/to search,Ctrl+Pfor server playlists. Auth is theu/t/smd5 token that every Subsonic server accepts, withauth = "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
search3with an empty query (match-everything), paged bysongOffset. The album-list-then-getAlbumroute 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
dand a confirmation. - Android/Termux builds:
aarch64-linux-androidcompiles, 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.