rmptui

A fast, keyboard-driven MPD client for your terminal.

rmptui is a terminal interface for Music Player Daemon (MPD) in the spirit of ncmpcpp and rmpc. Browse your library, manage the queue and playlists, edit tags, read synced lyrics and watch a spectrum visualizer without leaving the terminal.

Screens

Other highlights:

• Instant controls. All MPD traffic runs in background tasks over MPD's idle notifications, so seeking, volume changes and skipping never wait for the UI, and the UI never waits for the server.
• Fuzzy search everywhere. / searches the focused list; n/N cycle through the matches.
• Marks. v marks items; queue removal, add-to-playlist and tag edits then apply to every marked item.
• Mouse support. Click to select, double-click to play/open, scroll with the wheel, click a tab to switch screens and click the progress bar to seek.
• TCP or Unix socket, with password support and automatic reconnection.

Requirements

• A running MPD server with its music library configured.
• Rust 1.88 or newer and Cargo to build from source.

Install

From a local checkout, run the installer to build the release executable and copy it to /usr/local/bin/rmptui:

./install.sh

The script uses sudo for the system-directory operations when needed. To use a different binary directory or uninstall rmptui:

./install.sh --bin-dir "$HOME/.local/bin"
./install.sh --uninstall

Uninstall from a custom directory with ./install.sh --uninstall --bin-dir "$HOME/.local/bin". Run ./install.sh --help for usage.

Build from source

git clone https://github.com/krolyxon/rmptui.git
cd rmptui
cargo run --release

Configuration

On first launch rmptui writes a fully commented configuration to $CONFIG_HOME/rmptui/config.toml. If CONFIG_HOME is not set, it uses $XDG_CONFIG_HOME/rmptui/config.toml, then ~/.config/rmptui/config.toml. Use rmptui --config FILE to load a different file, and rmptui --print-default-config to see every option with its default. Restart rmptui to apply changes.

You only need to keep the settings you change: anything left out keeps its default, table by table. Unknown options and conflicting key bindings are reported with the file and the offending value.

Upgrading from 0.1: the configuration format changed. rmptui refuses to start with a 0.1 file and tells you so; move the old file aside, start rmptui to generate the new one, and copy your MPD settings over.

The main sections:

[mpd]
host = "127.0.0.1"      # or a Unix socket path such as "~/.config/mpd/socket"
port = 6600
password = ""
music_directory = ""    # needed for the tag editor and local .lrc files

[playback]
seek_seconds = 5
volume_step = 5

[ui]
startup_screen = "queue"
mouse = true
lyrics_pane = false
queue_columns = [
    { field = "artist", width = 25 },
    { field = "track", width = 5 },
    { field = "title", width = 35 },
    { field = "album", width = 30 },
    { field = "duration", width = 7 },
]

[theme]
accent = "magenta"      # color names, 256-color indices or "#rrggbb"
visualizer = ["blue", "cyan", "green", "yellow", "red"]

[lyrics]
online = true           # look up lyrics on lrclib.net
cache = true

[visualizer]
fifo = "/tmp/mpd.fifo"

The MPD connection can also be set with environment variables, which take precedence over the file:

MPD_HOST=192.168.1.20 MPD_PORT=6600 rmptui
MPD_HOST='secret@localhost' rmptui
MPD_HOST=~/.config/mpd/socket rmptui

Logs (and panic details) are appended to /tmp/rmptui.log. Set RMPTUI_LOG=debug for more detail.

Visualizer

The visualizer reads raw audio from an MPD fifo output. Add this to mpd.conf and restart MPD:

audio_output {
    type   "fifo"
    name   "Visualizer feed"
    path   "/tmp/mpd.fifo"
    format "44100:16:2"
}

[visualizer] must match the path and format. The fifo is only read while the Visualizer screen is visible.

Lyrics

Lyrics are looked up in this order:

1. An .lrc file next to the song (Song.flac → Song.lrc), when the music directory is known.
2. The cache in $XDG_CACHE_HOME/rmptui/lyrics (~/.cache by default).
3. LRCLIB, a free lyrics database. Results are cached.

Set lyrics.online = false to stay offline. F5 on the Lyrics screen fetches the lyrics of the current song again.

Tag editor

MPD cannot change tags, so the tag editor writes the files directly. That requires the music files to be on this machine: set mpd.music_directory, or connect through MPD's Unix socket so rmptui can ask MPD for it. After saving, rmptui asks MPD to rescan the edited folders.

Key bindings

These are the defaults; every binding is configurable in the [keys.*] tables of the config. ? shows the active bindings inside rmptui.

Bindings are grouped by context. A key is looked up in the focused popup or screen first, then in navigation, then in global, so screen bindings shadow global ones on that screen (for example R renames a playlist on the Playlists screen and toggles consume elsewhere).

Global

Lists

Screens

In text fields, Enter submits, Esc cancels, Ctrl+w deletes a word and Ctrl+a / Ctrl+e jump to the start / end.

License

rmptui is distributed under the GNU Affero General Public License v3.0.