| 1 | # rmptui |
| 2 | |
| 3 |  |
| 4 | [](https://github.com/krolyxon/rmptui/releases) |
| 5 | |
| 6 | **A fast, keyboard-driven MPD client for your terminal.** |
| 7 | |
| 8 | rmptui is a terminal interface for [Music Player Daemon |
| 9 | (MPD)](https://www.musicpd.org/) that looks and feels like ncmpcpp. Browse your |
| 10 | library, manage the queue and playlists, edit tags, read synced lyrics and |
| 11 | watch a music visualizer without leaving the terminal. |
| 12 | |
| 13 |  |
| 14 | |
| 15 | <table> |
| 16 | <tr> |
| 17 | <td width="50%"><img src="assets/playlist-editor-screen.png" alt="system tab"><br> |
| 18 | <sub><b>Playlist Editor</b> · Manage your playlists</sub></td> |
| 19 | <td width="50%"><img src="assets/lyrics-screen.png" alt="system tab"><br> |
| 20 | <sub><b>Lyrics Screen</b> · Fetched lyrics with synchronization</sub></td> |
| 21 | </tr> |
| 22 | </table> |
| 23 | |
| 24 | ## Screens |
| 25 | |
| 26 | | Key | Screen | What it does | |
| 27 | | --- | --- | --- | |
| 28 | | `1` | **Playlist** | The play queue as a table (Artist, Track, Title, Album, Time). Play, remove, reorder, mark, shuffle or save it as a playlist. `L` shows a synced lyrics pane next to it. | |
| 29 | | `2` | **Browse** | Your music folders. Folders (`[name]`) span the whole row, songs use the same columns as the queue, and stored playlists are listed at the bottom of the root folder. | |
| 30 | | `3` | **Playlist editor** | Stored playlists and their songs: load, play from a song, remove or reorder songs, rename or delete playlists. | |
| 31 | | `4` | **Media library** | Album artists → albums (with year) → songs. `t` switches between AlbumArtist and Artist. | |
| 32 | | `5` | **Tag editor** | Directories, tag types and tags, like ncmpcpp: edit Title, Artist, Album Artist, Album, Date, Track, Genre, Composer, Performer, Disc and Comment of one or many songs, rename files, fix letter case, then save. | |
| 33 | | `6` | **Music visualizer** | ncmpcpp-style wave, filled wave, spectrum and ellipse visualizers fed by an MPD fifo output; `Space` cycles them. | |
| 34 | | `7` | **Lyrics** | Synced lyrics that follow playback, or plain lyrics you can scroll. | |
| 35 | |
| 36 | Every screen shares ncmpcpp's frame: the screen title and volume on top |
| 37 | (active modes such as `[rz]` appear on the line below), and at the bottom a |
| 38 | progress bar above `Playing: "Title" by Artist in Album (Year)` with the |
| 39 | bitrate and elapsed/total time. |
| 40 | |
| 41 | Other highlights: |
| 42 | |
| 43 | - **Instant controls.** All MPD traffic runs in background tasks over MPD's |
| 44 | `idle` notifications, so seeking, volume changes and skipping never wait for |
| 45 | the UI, and the UI never waits for the server. |
| 46 | - **Fuzzy search everywhere.** `/` searches the focused list; `n`/`N` cycle |
| 47 | through the matches. |
| 48 | - **Marks.** `v` marks items; queue removal, add-to-playlist and tag edits |
| 49 | then apply to every marked item. |
| 50 | - **Mouse support.** Click to select, double-click to play/open, scroll with |
| 51 | the wheel and click the progress bar to seek. |
| 52 | - **TCP or Unix socket**, with password support and automatic reconnection. |
| 53 | |
| 54 | ## Requirements |
| 55 | |
| 56 | - A running MPD server with its music library configured. |
| 57 | - Rust 1.88 or newer and Cargo to build from source. |
| 58 | |
| 59 | ## Install |
| 60 | |
| 61 | Prebuilt binaries for Linux (x86_64 and aarch64, glibc and static musl) and |
| 62 | macOS are attached to each [release](https://github.com/krolyxon/rmptui/releases). |
| 63 | To download and install the right one for your machine: |
| 64 | |
| 65 | ```sh |
| 66 | curl --proto '=https' --tlsv1.2 -LsSf https://github.com/krolyxon/rmptui/releases/latest/download/rmptui-installer.sh | sh |
| 67 | ``` |
| 68 | |
| 69 | To build and install from a local checkout instead, run the installer to build the release executable and |
| 70 | copy it to `/usr/local/bin/rmptui`: |
| 71 | |
| 72 | ```sh |
| 73 | ./install.sh |
| 74 | ``` |
| 75 | |
| 76 | The script uses `sudo` for the system-directory operations when needed. To use |
| 77 | a different binary directory or uninstall rmptui: |
| 78 | |
| 79 | ```sh |
| 80 | ./install.sh --bin-dir "$HOME/.local/bin" |
| 81 | ./install.sh --uninstall |
| 82 | ``` |
| 83 | |
| 84 | Uninstall from a custom directory with |
| 85 | `./install.sh --uninstall --bin-dir "$HOME/.local/bin"`. Run |
| 86 | `./install.sh --help` for usage. |
| 87 | |
| 88 | ## Build from source |
| 89 | |
| 90 | ```sh |
| 91 | git clone https://github.com/krolyxon/rmptui.git |
| 92 | cd rmptui |
| 93 | cargo run --release |
| 94 | ``` |
| 95 | |
| 96 | ## Configuration |
| 97 | |
| 98 | On first launch rmptui writes a fully commented configuration to |
| 99 | `$CONFIG_HOME/rmptui/config.toml`. If `CONFIG_HOME` is not set, it uses |
| 100 | `$XDG_CONFIG_HOME/rmptui/config.toml`, then `~/.config/rmptui/config.toml`. |
| 101 | Use `rmptui --config FILE` to load a different file, and |
| 102 | `rmptui --print-default-config` to see every option with its default. Restart |
| 103 | rmptui to apply changes. |
| 104 | |
| 105 | You only need to keep the settings you change: anything left out keeps its |
| 106 | default, table by table. Unknown options and conflicting key bindings are |
| 107 | reported with the file and the offending value. |
| 108 | |
| 109 | > **Upgrading from 0.1:** the configuration format changed. rmptui refuses to |
| 110 | > start with a 0.1 file and tells you so; move the old file aside, start |
| 111 | > rmptui to generate the new one, and copy your MPD settings over. |
| 112 | |
| 113 | The main sections: |
| 114 | |
| 115 | ```toml |
| 116 | [mpd] |
| 117 | host = "127.0.0.1" # or a Unix socket path such as "~/.config/mpd/socket" |
| 118 | port = 6600 |
| 119 | password = "" |
| 120 | music_directory = "" # for the tag editor and local .lrc files (see below) |
| 121 | |
| 122 | [playback] |
| 123 | seek_seconds = 5 |
| 124 | volume_step = 5 |
| 125 | |
| 126 | [ui] |
| 127 | startup_screen = "queue" |
| 128 | mouse = true |
| 129 | confirm_clear_queue = false |
| 130 | lyrics_pane = false |
| 131 | song_columns = [ # queue, browser and playlist editor |
| 132 | { field = "artist", width = 34 }, |
| 133 | { field = "track", width = 5 }, |
| 134 | { field = "title", width = 33 }, |
| 135 | { field = "album", width = 30 }, |
| 136 | { field = "duration", width = 5 }, |
| 137 | ] |
| 138 | |
| 139 | [theme] # color names, 256-color indices or "#rrggbb" |
| 140 | text = "reset" |
| 141 | dim = "darkgray" |
| 142 | selection_fg = "reset" # both "reset": reverse video, like ncmpcpp |
| 143 | selection_bg = "reset" |
| 144 | visualizer = ["blue", "cyan", "green", "yellow", "red"] |
| 145 | |
| 146 | [lyrics] |
| 147 | online = true # look up lyrics on lrclib.net |
| 148 | cache = true |
| 149 | |
| 150 | [visualizer] |
| 151 | fifo = "/tmp/mpd.fifo" |
| 152 | ``` |
| 153 | |
| 154 | The MPD connection can also be set with environment variables, which take |
| 155 | precedence over the file: |
| 156 | |
| 157 | | Variable | Description | |
| 158 | | --- | --- | |
| 159 | | `MPD_HOST` | Hostname, address or Unix socket path. Use `password@host` to set both host and password. | |
| 160 | | `MPD_PORT` | Port; an explicit port in `MPD_HOST` takes precedence. | |
| 161 | |
| 162 | ```sh |
| 163 | MPD_HOST=192.168.1.20 MPD_PORT=6600 rmptui |
| 164 | MPD_HOST='secret@localhost' rmptui |
| 165 | MPD_HOST=~/.config/mpd/socket rmptui |
| 166 | ``` |
| 167 | |
| 168 | Logs (and panic details) are appended to `/tmp/rmptui.log`. Set |
| 169 | `RMPTUI_LOG=debug` for more detail. |
| 170 | |
| 171 | ### Visualizer |
| 172 | |
| 173 | The visualizer reads raw audio from an MPD fifo output. Add this to |
| 174 | `mpd.conf` and restart MPD: |
| 175 | |
| 176 | ``` |
| 177 | audio_output { |
| 178 | type "fifo" |
| 179 | name "Visualizer feed" |
| 180 | path "/tmp/mpd.fifo" |
| 181 | format "44100:16:2" |
| 182 | } |
| 183 | ``` |
| 184 | |
| 185 | `[visualizer]` must match the `path` and `format`. The fifo is only read while |
| 186 | the Visualizer screen is visible. |
| 187 | |
| 188 | Like ncmpcpp, there are four styles: `wave` (the default), `wave_filled`, |
| 189 | `spectrum` and `ellipse`. Set the startup one with `style` and press `Space` on |
| 190 | the screen to cycle through them. With `stereo = true` the wave styles draw the |
| 191 | left channel in the top half and the right channel in the bottom half. |
| 192 | |
| 193 | ### Lyrics |
| 194 | |
| 195 | Lyrics are looked up in this order: |
| 196 | |
| 197 | 1. An `.lrc` file next to the song (`Song.flac` → `Song.lrc`), when the music |
| 198 | directory is known. |
| 199 | 2. The cache in `$XDG_CACHE_HOME/rmptui/lyrics` (`~/.cache` by default). |
| 200 | 3. [LRCLIB](https://lrclib.net), a free lyrics database. Results are cached. |
| 201 | |
| 202 | Set `lyrics.online = false` to stay offline. `F5` on the Lyrics screen fetches |
| 203 | the lyrics of the current song again. |
| 204 | |
| 205 | ### Tag editor |
| 206 | |
| 207 | MPD cannot change tags, so the tag editor writes the files directly, which |
| 208 | requires the music files to be on this machine. rmptui finds the music |
| 209 | directory in this order: `mpd.music_directory` in its config, MPD itself (only |
| 210 | answered over a Unix socket), and finally `music_directory` from the local |
| 211 | MPD's `mpd.conf` (`$XDG_CONFIG_HOME/mpd/mpd.conf`, `~/.config/mpd/mpd.conf`, |
| 212 | `~/.mpdconf`, `~/.mpd/mpd.conf` or `/etc/mpd.conf`) when MPD runs on this |
| 213 | machine. |
| 214 | |
| 215 | Highlight a directory to see its songs in the `Tags` column, which shows the |
| 216 | tag selected in `Tag types`. `Enter` on a tag type edits it for all marked |
| 217 | songs (or all songs), `Enter` on a song edits it for that song only, and |
| 218 | `Filename` renames files. Changes stay pending until you choose `Save` (or |
| 219 | press `w`); `Reset` (or `u`) discards them. After saving, rmptui asks MPD to |
| 220 | rescan the folder. |
| 221 | |
| 222 | ## Key bindings |
| 223 | |
| 224 | These are the defaults; every binding is configurable in the `[keys.*]` tables |
| 225 | of the config. `?` shows the active bindings inside rmptui. |
| 226 | |
| 227 | Bindings are grouped by context. A key is looked up in the focused popup or |
| 228 | screen first, then in `navigation`, then in `global`, so screen bindings |
| 229 | shadow global ones on that screen (for example `R` renames a playlist on the |
| 230 | Playlists screen and toggles consume elsewhere). |
| 231 | |
| 232 | ### Global |
| 233 | |
| 234 | | Key | Action | |
| 235 | | --- | --- | |
| 236 | | `1`–`7` | Switch screen | |
| 237 | | `Tab` / `Shift+Tab` | Next / previous screen | |
| 238 | | `p` | Toggle play/pause | |
| 239 | | `s` / `x` | Pause / stop | |
| 240 | | `>` / `<` | Next / previous track | |
| 241 | | `f` / `b` | Seek forward / backward | |
| 242 | | `+` `=` / `-` | Volume up / down | |
| 243 | | `m` | Toggle mute | |
| 244 | | `r` `z` `y` `R` | Toggle repeat, random, single, consume | |
| 245 | | `c` | Clear the queue | |
| 246 | | `U` | Rescan the music database | |
| 247 | | `?` `F1` | Show key bindings | |
| 248 | | `q` `Ctrl+c` | Quit | |
| 249 | |
| 250 | ### Lists |
| 251 | |
| 252 | | Key | Action | |
| 253 | | --- | --- | |
| 254 | | `j` `k` / arrows | Move down / up | |
| 255 | | `g` `G` / `Home` `End` | Top / bottom | |
| 256 | | `Ctrl+d` `Ctrl+u`, `PageDown` `PageUp` | Half page / page | |
| 257 | | `h` `l` / arrows | Back or previous column / open or next column | |
| 258 | | `Enter` | Play or open the selected item | |
| 259 | | `Space` | Add to the queue (toggles songs in the browser) | |
| 260 | | `a` | Add to the queue, a new playlist or an existing one | |
| 261 | | `v` / `V` | Mark item / clear marks | |
| 262 | | `/`, `n` / `N` | Search, next / previous match | |
| 263 | |
| 264 | ### Screens |
| 265 | |
| 266 | | Screen | Key | Action | |
| 267 | | --- | --- | --- | |
| 268 | | Queue | `d` `Delete` | Remove the song (or all marked songs) | |
| 269 | | Queue | `J` / `K` | Move the song down / up | |
| 270 | | Queue | `Z` / `S` | Shuffle / save as playlist | |
| 271 | | Queue | `o` | Jump to the playing song | |
| 272 | | Queue | `L` | Toggle the lyrics pane | |
| 273 | | Playlists | `d`, `J` / `K` | Remove / move the selected song | |
| 274 | | Playlists | `R` / `D` | Rename / delete the playlist | |
| 275 | | Library | `t` | Switch between AlbumArtist and Artist | |
| 276 | | Tags | `Enter` | Edit a tag, rename a file, or run the highlighted action | |
| 277 | | Tags | `w` / `u` | Write / discard pending changes | |
| 278 | | Lyrics | `F5` | Fetch lyrics again | |
| 279 | |
| 280 | In text fields, `Enter` submits, `Esc` cancels, `Ctrl+w` deletes a word and |
| 281 | `Ctrl+a` / `Ctrl+e` jump to the start / end. |
| 282 | |
| 283 | ## License |
| 284 | |
| 285 | rmptui is distributed under the |
| 286 | [GNU Affero General Public License v3.0](LICENSE). |