mpdtui

A lazygit-style terminal UI for MPD (Music Player Daemon).

---

Bordered panels, single-key contextual actions, vim-style navigation — no mouse required. Two run modes: a full panel UI, and a lightweight single-line inline player for a shell or tmux pane.

Screenshot

Demo

_{Click the screenshot to play the demo (GitHub doesn't inline-render repo video files).}

Features

• Library — expandable directory tree (MPD's actual filesystem layout, lazily loaded per folder), or free-text tag search; o cycles name/most-recently-modified sort. Search (/, and the global f artist/album/track search) is case- and accent-insensitive, so "bruno" matches "Bruno" and "buble" matches "Bublé"
• Album art — shown for the currently playing track, updated automatically on track change. Renders as a crisp real image via the Kitty graphics protocol when the terminal supports it (detected from $TERM containing kitty, or $KITTY_WINDOW_ID being set -- covers kitty itself and kitty-compatible terminals that keep TERM as xterm-kitty, even if it's been overridden to something like xterm-256color for remote-host terminfo compatibility). Everywhere else -- including terminals that do support the Kitty protocol but don't signal it either way, e.g. some WezTerm/Konsole configurations -- falls back to a fixed 30x15 ASCII-art rendering; there's no capability probe, since one risks hanging against a terminal that never answers it. "No Album Art" is shown if MPD has none embedded or alongside the track.
• Playlists — a Name/Count table, mirroring the Queue panel's own column layout: a pinned header row, Name (🎵 icon prefix, truncated to 24 characters with "...") on the left, Count right-aligned as the last column, populated once fetched and refreshed automatically every 10 minutes in the background or on demand with R. Load, append, save, delete stored playlists; o cycles between most-recently-updated and alphabetical
• Queue — reorder, remove, clear, jump to any track; a pinned header row (Title/Album/Artist/Year/Genre/Composer/Type/Duration) stays visible while scrolling. Title is bold and colored WhatsApp green; Title/Album/ Artist/Genre/Composer are truncated (30/20/40/9/14 characters) with "..." if longer; Type shows a color-coded format badge (MP3/FLAC/M4A/ ...); Type and Duration are right-aligned
• Library stats — live total tracks/artists/playlists, shown alongside the Queue search box, refreshed on library/playlist changes
• Now Playing bar — live progress, volume, repeat/random/single/consume flags, updated instantly via MPD's idle protocol (stays in sync even when playback changes from another client, e.g. mpc); its right half shows a small playback-driven visualization (v to cycle, currently a dancing equalizer scaled by actual volume)
• Lightweight inline mode (-mini) — two live status lines (queue/ playlist counts, then track/progress), no alt-screen takeover, for tmux status panes or a quick glance
• Fuzzy pickers (-p / -t) — fzf-style playlist/track search from the shell, no panels involved
• Confirmation prompts on destructive actions (clear queue, delete playlist)

Install

Homebrew

brew tap susamn/mpdtui
brew install mpdtui

(First install of a third-party tap: if Homebrew refuses to load the formula as untrusted, run brew trust susamn/mpdtui first.)

From source

go build -o mpdtui ./cmd/mpdtui

Requires Go 1.26+ and a reachable MPD server.

Usage

./mpdtui          # full panel UI
./mpdtui -mini    # lightweight inline player
./mpdtui -p       # fuzzy-search playlists; Enter clears the queue and plays it
./mpdtui -t       # fuzzy-search tracks; Enter adds it to the queue and plays it

-mini, -p, and -t are mutually exclusive.

Connects using the same environment variables as mpc:

Variable	Default	Notes
MPD_HOST	localhost	may be password@host
MPD_PORT	6600

Press ? inside the full UI for the in-app keybinding list.

Keybindings

Global (any panel):

Key	Action
Space	Toggle play/pause
s	Stop
n / p	Next / previous track
, / .	Seek -5s / +5s
- / =	Volume down / up
z	Toggle random (shuffle)
x	Toggle repeat
c	Toggle consume
Z	Toggle single
D	Clear entire queue (confirm)
Tab, 1/2/3	Cycle / jump focus between panels
/	Search (contextual: filters Library/Playlists, jumps to a match in Queue)
f	Global search from any panel -- type a/al/p/t + a term, e.g. a queen, al hello, p oldies, t help me (artist/album/playlist/track); stays open with "no X found" if nothing matches
F	Clear any active search/filter, in every panel at once (Library search, Playlists filter) -- unlike a panel's own Esc, works regardless of which panel is currently focused
i	Track info card for the currently playing track (Track/Album/Artist/Genre/Year), anchored to the bottom-right quarter of the Queue panel
v	Cycle Now Playing visualizations (right half of the Now Playing bar)
L	Locate the currently playing track: selects it in the Queue and moves focus there, from any panel, and also reveals it in the Library tree (expanding every folder along its path and selecting it there, without moving focus away from Queue). The Queue-selecting part also happens automatically, whenever the playing track actually changes (explicit play action or natural auto-advance alike) -- except while an overlay is open, or on startup; the Library reveal is only on the explicit keypress
?	Help overlay
q	Quit

Panel-local:

Panel	Key	Action
Library	Enter	Expand/collapse a folder, or add+play a track
Library	a	Add selected folder (recursively) or track to queue (no play)
Library	Backspace	Collapse folder, or go up to its parent
Library	j/k/g/G	Native tree navigation (also J/K to jump in/out a level)
Library	o	Cycle sort: name / most recently modified (browse mode only)
Library	Esc	Clear active search
Playlists	Enter	Load playlist into queue and play
Playlists	a	Append playlist to queue
Playlists	d	Delete playlist (confirm)
Playlists	S	Save current queue as a new playlist
Playlists	R	Refresh track counts now (also happens automatically every 10 minutes in the background)
Playlists	o	Cycle sort: most recently updated / name
Playlists	Esc	Clear active filter
Queue	Enter	Play selected track
Queue	d	Remove selected track
Queue	J / K	Move selected track down / up
Queue	/	Search: focuses the always-visible "Search track:" box above the queue, Enter jumps to first match (Esc cancels)

Mini mode (-mini): Space play/pause, n/p next/prev, s stop, -/= volume, q/Ctrl-C quit.

Test

go test ./...

internal/mpdclient and internal/ui's integration tests need a reachable MPD server (they skip automatically if there isn't one).

License

MIT, see LICENSE.