| 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 lightweight music player interface for [Music Player Daemon |
| 9 | (MPD)](https://www.musicpd.org/). Browse your library, manage the play queue, |
| 10 | work with playlists, and control playback without leaving the terminal. |
| 11 | |
| 12 |  |
| 13 | |
| 14 | ## Highlights |
| 15 | |
| 16 | - **Three focused views:** browse your music library, control the current queue, |
| 17 | and inspect saved playlists. |
| 18 | - **Metadata at a glance:** see artist, track, title, album, and duration in |
| 19 | the browser and queue. |
| 20 | - **Fuzzy, repeatable search:** search the current view with `/`; in the song |
| 21 | browser, keep the query and cycle matching folders and songs with `n` and |
| 22 | `N`. |
| 23 | - **Playlist tools:** load playlists, add selected tracks or folders to a |
| 24 | playlist, create playlists, and rename them. |
| 25 | - **Queue control:** play, remove, reorder, and append tracks. |
| 26 | - **Responsive MPD updates:** the client uses MPD's asynchronous `idle` |
| 27 | notifications instead of regularly polling the server. |
| 28 | - **Direct MPD connection:** speaks MPD's standard text protocol over |
| 29 | asynchronous TCP; no `mpd` crate or WebSocket proxy is required. |
| 30 | |
| 31 | ## Requirements |
| 32 | |
| 33 | - A running MPD server with its music library configured. |
| 34 | - Rust and Cargo to build from source. |
| 35 | |
| 36 | ## Install |
| 37 | |
| 38 | From a local checkout, run the installer to build the release executable and |
| 39 | copy it to `/usr/local/bin/rmptui`: |
| 40 | |
| 41 | ```sh |
| 42 | ./install.sh |
| 43 | ``` |
| 44 | |
| 45 | The script uses `sudo` for the system-directory operations when needed. It |
| 46 | requires Rust and Cargo to build from source. To use a different binary |
| 47 | directory or uninstall rmptui: |
| 48 | |
| 49 | ```sh |
| 50 | ./install.sh --bin-dir "$HOME/.local/bin" |
| 51 | ./install.sh --uninstall |
| 52 | ``` |
| 53 | |
| 54 | Uninstall from a custom directory with |
| 55 | `./install.sh --uninstall --bin-dir "$HOME/.local/bin"`. Run |
| 56 | `./install.sh --help` for usage. |
| 57 | |
| 58 | ## Build from source |
| 59 | |
| 60 | ```sh |
| 61 | git clone https://github.com/krolyxon/rmptui.git |
| 62 | cd rmptui |
| 63 | cargo run --release |
| 64 | ``` |
| 65 | |
| 66 | To build and run without installing, use `cargo run --release`. |
| 67 | |
| 68 | On first launch, rmptui creates a default configuration file at |
| 69 | `$CONFIG_HOME/rmptui/config.toml`. If `CONFIG_HOME` is not set, it uses |
| 70 | `$XDG_CONFIG_HOME/rmptui/config.toml`, then `~/.config/rmptui/config.toml`. |
| 71 | Edit the file and restart rmptui to apply changes: |
| 72 | |
| 73 | ```toml |
| 74 | [mpd] |
| 75 | host = "127.0.0.1" |
| 76 | port = 6600 |
| 77 | password = "" # Set this only if your MPD server requires a password. |
| 78 | |
| 79 | [playback] |
| 80 | seek_seconds = 2 |
| 81 | volume_step = 2 |
| 82 | |
| 83 | [keybindings] |
| 84 | quit = ["q", "Ctrl+c"] |
| 85 | clear_queue = ["c", "C"] |
| 86 | toggle_pause = ["p"] |
| 87 | pause = ["s"] |
| 88 | toggle_repeat = ["r"] |
| 89 | toggle_random = ["z"] |
| 90 | open_playlist_menu = ["a"] |
| 91 | seek_forward = ["f"] |
| 92 | seek_backward = ["b"] |
| 93 | cycle_tabs = ["Tab"] |
| 94 | select_queue = ["1"] |
| 95 | select_browser = ["2"] |
| 96 | select_playlists = ["3"] |
| 97 | next_track = [">"] |
| 98 | previous_track = ["<"] |
| 99 | volume_up = ["=", "+"] |
| 100 | volume_down = ["-"] |
| 101 | toggle_mute = ["m"] |
| 102 | update_database = ["U"] |
| 103 | search = ["/"] |
| 104 | toggle_selected_item = ["Space"] |
| 105 | search_next = ["n"] |
| 106 | search_previous = ["N"] |
| 107 | move_down = ["j", "Down"] |
| 108 | move_up = ["k", "Up"] |
| 109 | activate = ["Enter", "l", "Right"] |
| 110 | go_back = ["h", "Left"] |
| 111 | go_to_top = ["g"] |
| 112 | go_to_bottom = ["G"] |
| 113 | queue_delete = ["d"] |
| 114 | queue_move_down = ["J"] |
| 115 | queue_move_up = ["K"] |
| 116 | playlist_rename = ["R"] |
| 117 | playlist_focus_contents = ["Right", "l"] |
| 118 | playlist_focus_list = ["Left", "h"] |
| 119 | playlist_delete_song = ["d"] |
| 120 | playlist_move_song_down = ["J"] |
| 121 | playlist_move_song_up = ["K"] |
| 122 | playlist_delete = ["D"] |
| 123 | playlist_load = ["Space", "Enter"] |
| 124 | popup_close = ["q", "Esc"] |
| 125 | popup_select = ["Enter"] |
| 126 | input_cancel = ["Esc"] |
| 127 | input_backspace = ["Backspace"] |
| 128 | input_cursor_left = ["Left"] |
| 129 | input_cursor_right = ["Right"] |
| 130 | input_submit = ["Enter"] |
| 131 | ``` |
| 132 | |
| 133 | Runtime errors and panic details are appended to `/tmp/rmptui.log`. If logging |
| 134 | cannot be initialized, rmptui prints a warning and continues without a log |
| 135 | file. |
| 136 | |
| 137 | Every listed action is configurable in `[keybindings]`; each value is an array |
| 138 | so actions can have multiple aliases. Remove an alias or set an action to `[]` |
| 139 | to disable it. A key can be a single character or a named key such as `Enter`, |
| 140 | `Esc`, `Tab`, `Space`, `Up`, `Down`, `Left`, `Right`, or `Backspace`. Add |
| 141 | modifiers with `Ctrl+`, `Alt+`, or `Shift+`, for example `Ctrl+x` or |
| 142 | `Alt+Enter`. Bindings are matched in the current UI context, so avoid assigning |
| 143 | the same key to different actions that can be active in the same context. |
| 144 | Characters typed into search and playlist-name fields remain text unless |
| 145 | configured as an input action. |
| 146 | |
| 147 | `playback.seek_seconds` sets the `seek_forward`/`seek_backward` distance, and |
| 148 | `playback.volume_step` sets the `volume_up`/`volume_down` amount. Supported |
| 149 | audio formats remain built in. The config stores an MPD password as plain text; |
| 150 | newly created config files are restricted to the current user. |
| 151 | |
| 152 | The MPD connection settings can also be overridden with environment variables: |
| 153 | |
| 154 | | Variable | Default | Description | |
| 155 | | --- | --- | --- | |
| 156 | | `MPD_HOST` | Config file | MPD hostname or address. Use `password@host` to set both host and password. | |
| 157 | | `MPD_PORT` | Config file | MPD port; an explicit port in `MPD_HOST` takes precedence. | |
| 158 | |
| 159 | For example: |
| 160 | |
| 161 | ```sh |
| 162 | MPD_HOST=192.168.1.20 MPD_PORT=6600 ./target/release/rmptui |
| 163 | ``` |
| 164 | |
| 165 | Or, for a password-protected local server: |
| 166 | |
| 167 | ```sh |
| 168 | MPD_HOST='secret@localhost' ./target/release/rmptui |
| 169 | ``` |
| 170 | |
| 171 | ## Controls |
| 172 | |
| 173 | The keys below are the defaults; edit the `[keybindings]` table above to change |
| 174 | them. |
| 175 | |
| 176 | ### Navigation |
| 177 | |
| 178 | | Key | Action | |
| 179 | | --- | --- | |
| 180 | | `Tab` | Cycle between Queue, Browser, and Playlists | |
| 181 | | `1` / `2` / `3` | Open Queue / Browser / Playlists | |
| 182 | | `j` / `Down` | Move selection down | |
| 183 | | `k` / `Up` | Move selection up | |
| 184 | | `g` / `G` | Jump to the top / bottom of the current list | |
| 185 | | `Enter` / `l` / `Right` | Activate the selected item | |
| 186 | | `h` / `Left` | Go to the parent directory in the browser | |
| 187 | | `q` / `Ctrl+C` | Quit | |
| 188 | |
| 189 | ### Search |
| 190 | |
| 191 | 1. Press `/` and type a query. |
| 192 | 2. In the browser, press `Enter` to keep the query and return to the list. |
| 193 | 3. Press `n` for the next fuzzy match or `N` for the previous match. Results |
| 194 | wrap around when you reach either end. |
| 195 | 4. Press `/` to start a new search, or `Esc` to cancel search input. |
| 196 | |
| 197 | Search matches the names shown in the current view. Browser search includes |
| 198 | both folders and songs. |
| 199 | |
| 200 | ### Playback and queue |
| 201 | |
| 202 | | Key | Action | |
| 203 | | --- | --- | |
| 204 | | `p` | Toggle play/pause | |
| 205 | | `s` | Pause | |
| 206 | | `>` / `<` | Play next / previous track | |
| 207 | | `f` / `b` | Seek forward / backward by two seconds | |
| 208 | | `+` / `=` / `-` | Increase / decrease volume | |
| 209 | | `m` | Toggle mute | |
| 210 | | `r` / `z` | Toggle repeat / random | |
| 211 | | `d` | Remove the selected queue item | |
| 212 | | `Space` | Remove a queue item; toggle a browser song in the queue | |
| 213 | | `J` / `K` | Move the selected queue item down / up | |
| 214 | | `c` | Clear the queue | |
| 215 | | `a` | Open the add-to-playlist menu | |
| 216 | | `U` | Rescan the MPD music database | |
| 217 | |
| 218 | ### Playlists |
| 219 | |
| 220 | The Playlists view has a playlist pane and a contents pane. Select a playlist |
| 221 | with `j`/`k` and press `Space` or `Enter` to load it into the queue and start |
| 222 | playback. Press `Right` or `l` to focus its songs and `Left` or `h` to return |
| 223 | to the playlist pane. In the contents pane, `j`/`k` selects a song, `Enter` |
| 224 | plays it, `d` removes it from the saved playlist, and `J`/`K` moves it |
| 225 | down/up. `D` deletes the selected saved playlist. `R` renames a playlist. |
| 226 | |
| 227 | Press `a` to open the add-to-playlist menu; choose **Current Playlist**, **New |
| 228 | Playlist**, or a saved playlist. When creating a playlist, type its name and |
| 229 | press `Enter` to save. Playlist contents update after each edit. |
| 230 | |
| 231 | ## License |
| 232 | |
| 233 | rmptui is distributed under the |
| 234 | [GNU Affero General Public License v3.0](LICENSE). |