Skip to content

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

Config file can be bootstrapped by running the following command:

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

Below is a list of properties that can be changed.

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: "<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: 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: None | Some("<string>")

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

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: <number>

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

theme: None | Some("<string>")

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

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: <keybinds>

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

volume_step: <number>

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

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: <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: <bool>

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

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: <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: 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: <bool>

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

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: ["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.

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: <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,
),

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

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: 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: 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).