Skip to content
rmpc
Docs Changelog

General configuration

Rmpc uses ron format for its configuration file. The file can be located at:

  • $XDG_CONFIG_HOME/rmpc/config.ron
  • $HOME/.config/rmpc/config.ron
  • Specific path specified by the --config flag

Bootstrapping a config file

Section titled “Bootstrapping a config file”

Config file can be bootstrapped by running the following command:

rmpc config > ~/.config/rmpc/config.ron

Config file structure

Section titled “Config file structure”

Below is a list of properties that can be changed.

address

Section titled “address”
address: "<ip>:<port>" | "/path/to/socket"

The address to connect to. Address can be either an IP address with a port or a UNIX domain socket path.

The order of precedence is as follows:

  1. --address and --password passed to rmpc as command line arguments
  2. $MPD_HOST and $MPD_PORT environment variables
    • If $MPD_PORT is not provided and $MPD_HOST starts with ~ or /, it is assumed to be a path to a unix socket
    • If $MPD_PORT is not provided and $MPD_HOST is an IP address and, the default port of 6600 is used
    • Password can be provided via $MPD_HOST in the password@host format.
  3. The address and password values from config file
  4. And finally, if none of the above are provided, the default of 127.0.0.1:6600 is used

Address and password from different sources cannot be mixed and matched.

password

Section titled “password”
password: "<string>"

Provide MPD with password upon connecting. Set to None or omit completely if your MPD is not configured to use a password.

cache_dir

Section titled “cache_dir”
cache_dir: None | Some("<string>")

Directory for rmpc’s cache files. Used for files downloaded for youtube and might be used for more in the future.

lyrics_dir

Section titled “lyrics_dir”
lyrics_dir: None | Some("<string>")

Directory where rmpc should search for lrc files. Please see the lyrics page for more information.

mpd_read_timeout_ms

Section titled “mpd_read_timeout_ms”
mpd_read_timeout_ms: <number>

How long to wait for response to MPD command before giving up and reconnecting. Defaults to 10_000 milliseconds.

mpd_write_timeout_ms

Section titled “mpd_write_timeout_ms”
mpd_write_timeout_ms: <number>

How long to wait for write to MPD socket to finish before giving up and reconnecting. Defaults to 5_000 milliseconds.

theme

Section titled “theme”
theme: None | Some("<string>")

Theme file to use. If set to None or absent, the default theme is used. More info at:

Configuring themes Get the default theme file and customize it

album_art

Section titled “album_art”
album_art: <other>

Various options for album art display. By default should not be needed to be specified. More info at album art page

keybinds

Section titled “keybinds”
keybinds: <keybinds>

Keybinds to use. The default keybinds are used if this property is absent. More info at:

Configuring keybinds Customize the keybinds

volume_step

Section titled “volume_step”
volume_step: <number>

Determines the step when changing volume with the volume up and down keybinds. Default is 5%.

max_fps

Section titled “max_fps”
max_fps: <number>

Rmpc batches rendered frames to save resources, meaning it could skip a render on input and make the frame a bit delayed if many frames are requested at the same time. This option sets how many frames rmpc can render in one second. Default is 30.

scrolloff

Section titled “scrolloff”
scrolloff: <number>

Minimal number of screen lines to keep above and below the cursor. Cursor will always be in the middle of the screen if set to value bigger than half the viewport height. Default is 0.

wrap_navigation

Section titled “wrap_navigation”
wrap_navigation: <bool>

Whether to wrap around on Up/Down action in queue/browser panes upon reaching bottom/top. Default is false.

enable_mouse

Section titled “enable_mouse”
enable_mouse: <bool>

Enables mouse support. Currently only seeking the currently playing song by clicking on the progress bar at the bottom of the screen and switching tabs is supported. Enabled by default.

enable_config_hot_reload

Section titled “enable_config_hot_reload”
enable_config_hot_reload: <bool>

Whether rmpc should watch its config directory and reload the config when it changes. Most options can be changed during runtime but some will still require you to restart rmpc. These include things like album art method and MPD connection information. Config hot reload is enabled by default.

status_update_interval_ms

Section titled “status_update_interval_ms”
status_update_interval_ms: None | Some(<number>)

Interval in milliseconds to update the status when a song is playing. Status means song progress, current bitrate, etc. Default is 1000ms.

select_current_song_on_change

Section titled “select_current_song_on_change”
select_current_song_on_change: <bool>

If set to true, the current song is selected in the queue table when it changes. Defaults to false if not present.

center_current_song_on_change

Section titled “center_current_song_on_change”
center_current_song_on_change: <bool>

If set to true, the current song is centered in the queue when it changes while still allowing you to move in the queue table with your normal scrolloff. Defaults to false if not present.

on_song_change

Section titled “on_song_change”
on_song_change: ["notify-send", "song changed!"]

Execute given command when the song changes. First element of the array is the command to execute and the rest are the arguments passed to the command. Nothing will be executed if left empty. Can be used to send notifications when the song changes.

on_resize

Section titled “on_resize”
on_resize: ["notify-send", "rmpc resized!"]

Execute given command when rmpc resizes. First element of the array is the command to execute and the rest are the arguments passed to the command. Nothing will be executed if left empty. Check on_resize for more info.

Section titled “search”
search: <search>

Configures what tags are searchable on the Search pane. Also sets whether the search should be case insensitive by default and what kind of search mode to perform. More detail in the Search section. If not specified, the default values are used.

artists

Section titled “artists”
artists: <artists>

Configures how albums are displayed and sorted in the Artists and AlbumArtists panes. Albums can display either only its name or include an album’s date as well. Additionally, albums can be sorted by their name or date.

Default:

artists: (
    album_display_mode: SplitByDate,
    album_sort_by: Date,
),

album_display_mode

Section titled “album_display_mode”

Can be one of the following:

  • SplitByDate - songs in the album will be split into separate album entries, one for each date and the album date will be displayed in front of the album name in the following format: (<date value>) <album name>
  • NameOnly - only one entry for an album will be created and the album date will not be displayed

album_sort_by

Section titled “album_sort_by”

Can be one of the following:

  • Name - albums are sorted by their name first and date second if their names are identical
  • Date - albums will be simply sorted by date.

browser_song_sort

Section titled “browser_song_sort”
browser_song_sort: SongPropertyKind[]

Defines how the songs are sorted in the browser panes. This is a list of song properties. Defaults to [Disc, Track, Artist, Title] which means the songs are first sorted by their Disc and Track numbers, then by Artist and by Title last.

directories_sort

Section titled “directories_sort”
directories_sort: ModifiedTime(..) | Format(..) | SongFormat(..)

Determines how the entries are sorted in the directories pane. All of the properties below take additional config options: group_directories_first and reverse which make directories grouped before entries and reverse the ordering respectively.

  • Format - Songs are sorted by their displayed format.
  • SortFormat - Similar to Format but songs are sorted by browser_song_sort.
  • ModifiedTime - Entries are sorted by their last modified time.

Defaults to SortFormat(group_directories_first: true, reverse: false).