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