Configuration is done in three parts: options, key bindings, and colors.
Options, bindings and colors can be set at runtime by entering command mode (default binding :) or can be
preset in a configuration file.
Configuration files are loaded in a specific order in line (almost) with the XDG Base Directory
Specification (http://standards.freedesktop.org/basedir-spec/basedir-spec-0.6.html). Possible
directories are collected from the environment variables XDG_CONFIG_DIRS and XDG_CONFIG_HOME (the former
defaults in PMS to /usr/local/etc/xdg:/etc/xdg rather than just /etc/xdg as in the spec, the latter
defaults to $HOME/.config as in the spec).
Each path in order from lowest priority (the last entry in XDG_CONFIG_DIRS) to highest (XDG_CONFIG_HOME)
is suffixed with /pms/rc and if this file exists it is loaded. Finally, if a configuration file was
specified on the commandline this file is loaded.
Settingoptions
String, integer and enumerated options are set with
setoption=value
Boolean options are set with
setoption
and reset with
setnooption
They can be toggled with
setoption!
or
setinvoption
Values can be retrieved with
setoption?se is an alias for set and : can be used in place of =.
Settingbindings
Key bindings are set with
bindkeycommand
and removed with
unbindkeykey can be any single character, in addition to these special characters: up, down, left, right,
pageup, pagedown, home, end, space, delete, insert, backspace, return, kpenter, tab and F1 through
F63. When unbinding, you can specify all as a parameter to remove all bindings.
map is an alias for bind, while unmap and unm are aliases for unbind.
Settingcolors
Colors are defined with
coloritemforeground[background]colour is an alias for color.
OPTIONShost=string
The hostname to connect to. Default: localhostport=integer
The port on the MPD server to connect to. Default: 6600password=string
The password to give to the MPD server. Default: none
libraryroot=string
Optional path to the library's root. See !string below. If used, it should have a trailing
slash. Default: empty string (nothing is prepended)
xtermtitle=string
If set, the XTerm window title will be set to the specified string. Default: PMS:%playstate%%ifcursong%%artist%–%title%%endif%reconnectdelay=integer
If a connection is lost, this is how many seconds between each connection retry. Default:
30msg_buffer_size=integerHowmanyloglinestokeepintheconsole.Avalueof0keepsalllines.Default:1024mpd_timeout=integer
Sets MPD connection timeout in seconds. Leave this lower than your MPD setting. Default: 30debug (boolean)
Turn debugging mode on or off. Default: setrepeat=enum
Choosebetweensingleorabooleanvalue.Default:offstopdelay=integer
MPD does not support manual progression within the playlist. A hack is necessary to stop
when the song is done. If manual song progression is not working correctly, increase this
value. Default: 1nextinterval=integer
This setting controls how many seconds from the current song ends until PMS automatically
adds the next song to MPD's playlist. Default: 5crossfade=integerSetcrossfadetimeinseconds.0turnscrossfadeoffcompletely.Default:MPD'ssettingsonplaylistfinish=string
Specify a shell command to run when the playlist finishes and playback stops. Default: none
addtoreturns (boolean)
If set, the add-to command will return focus to the original window. Else, the destination
will be focused. Default: unsetfollowplayback (boolean)
If set, the cursor will go to the currently playing song and playlist when it changes.
Default: unsetfollowwindow (boolean)
If set, playback will continue in the active window. Default: unsetfollowcursor (boolean)
If set, playback will follow cursor position. Default: unsetnextafteraction (boolean)
Move cursor to next item after the song is selected, unselected or added to a playlist.
Default: setstartuplist=enum
The list which is activated and shown at program startup. This can be playlist, library or
an arbitrary name of an existing playlist. Default: playlistregexsearch(boolean)
Use regular expressions for search terms. Default: setignorecase(boolean)
Ignore case when sorting and searching. The alias ic can also be used. Default: setscroll=enum
Set scroll mode
The following modes are available:
normal The list only scrolls when the cursor is about to go off the top or bottom of
the window. See the scrolloff option.
centered
The cursor is always in the middle of the window except when it is near the
top or bottom of the list. The spelling centred is also accepted.
relative
The position of the cursor in the confines of the window is proportional to
the position of the visible songs relative to the whole song list. Try it out
to get a better idea of how it works.
Default: normalscrolloff=integer
When scroll is set to normal, try to keep this many songs above and below the cursor at all
times. The alias so can also be used. Default: 0playmode=enum
Set song progression mode to manual, linear or random. In manual progression mode playback
will stop at the end of each song. Default: linearresetstatus=integer
Set how many seconds before resetting the statusbar text. Default: 3sort=field[field[...]]
Fields by which to sort the library. You can specify multiple fields, separated by
whitespace. See FIELDS below. Default: trackdiscalbumalbumartistsortcolumns=column [column [...]]
Columns to show in the list. See FIELDS below. Default: artisttracktitlealbumlengthstatus_unknown=stringstatus_play=stringstatus_pause=stringstatus_stop=string
Status strings. Defaults: ??, |>, ||, [] or, when Unicode is available, single characters
which I can't figure out how to print in this manpage.
mouse (boolean)
If set, the mouse is active. Mouse support is incomplete and the slightly hacky mousewheel
support available with standard versions of ncurses is less than ideal, but the actions
below have been implemented.
Mouse actions:
topbar Click to toggle play/pause, doubleclick to stop, mousewheel down to skip to
the next track, mousewheel up to skip to the previous track, control-
mousewheel to turn volume up or down
header ('Playlist', 'Library' etc)
Click or scroll mousewheel down to switch to the next window, doubleclick or
scroll mousewheel up to switch to the previous window
playlist
Click to place the cursor, control-click or click right button to place
cursor and toggle selection, doubleclick to place cursor and play,
tripleclick to place cursor and add to playlist (if there is a selection, the
selection will be added and the song clicked will just be selected), scroll
mousewheel to scroll the list up and down
statusbar
Click to enter command mode
Default: unsettopbarspace (boolean)
Whether or not to leave an extra space at the end of fixed-width columns. Default: settopbarvisible (boolean)
If set, the topbar is visible. Default: settopbarborders (boolean)
Whether or not to draw borders on the topbar window. Default: unsetcolumnspace (boolean)
Whether or not to leave a blank row between the topbar and the playlist windows. Default:
settopbarclear (boolean)
Start out with an empty topbar. Default: unsettopbar[1-99].(left|center|right)=string
Modify what is displayed in the topbar. The spelling centre is also accepted. See TOPBAR
below for format syntax, available fields and defaults.
TOPBAR
Available variables to put in the topbar:
librarysize, listsize, queuesize, livequeuesize, time_elapsed, time_remaining,
progresspercentage, progressbar, playstate, volume, repeat, repeatshort, random,
randomshort, mute, muteshort, manual, manualshort, bitrate, samplerate, bits, channels
All FIELDS below can also be used.
Conditionals (if-else) are supported. Currently available conditionals:
ifcursong, ifplaying, ifpaused, ifstopped
See the defaults below for how conditionals are used.
The topbar syntax allows free customization of the top area of the display. The best way to
understand the syntax is to take a look at the defaults:
set topbar1.left=%time_elapsed% %playstate% %time%%ifcursong% (%progresspercentage%%%)%endif%
set topbar1.center=%ifcursong%%artist%%endif%
set topbar1.right=Vol: %volume%%% Mode: %muteshort%%repeatshort%%randomshort%%manualshort%
set topbar2.center=%ifcursong%==> %title% <==%else%No current song%endif%
set topbar3.left=%listsize%
set topbar3.center=%ifcursong%%album% (%year%)%endif%
set topbar3.right=Q: %livequeuesize%
FIELDS
Available fields are:
num, file, artist, artistsort, albumartist, albumartistsort, title, album, track,
trackshort, time, date, year, name, genre, composer, performer, disc, commentCOLORS
Items available for coloring:
background, foreground, statusbar, error, position, borders, headers, title, current,
cursor, selection, lastlist, playinglist, fields.*topbar.foreground, topbar.time_elapsed,
topbar.time_remaining, topbar.progresspercentage, topbar.progressbar, topbar.repeat,
topbar.random, topbar.mute, topbar.repeatshort, topbar.randomshort, topbar.muteshort,
topbar.librarysize, topbar.listsize, topbar.queuesize, topbar.livequeuesize,
topbar.playstate, topbar.fields.*
Replace the wildcard * with any of the FIELDS described above.
The following colors can be used only as foreground colors:
gray, brightred, brightgreen, yellow, brightblue, brightmagenta, brightcyan
The following colors can be used either for background or foreground colors:
black, red, green, brown, blue, magenta, cyan, brightgray
The special color trans can only be used as a background color, and provides a transparent
background.
The alternative spelling grey can be used in the place of gray, and light can be used in place of
bright.
COMMANDSPlaybackplay Play the song under the cursor
add Add the selected song(s) to the playlist
If a playlist is selected in windowlist mode, that list is appended to the playlist.
add-to Add the selected song(s) to a chosen playlist
next Play the next song from the playlist or library based on current play mode
really-next
Play the next song from playlist or library, regardless of play mode
prev Play previous song
pause Pause playback or play if playback was paused; do nothing if playback is stopped
stop Stop playback
playmode
Rotate mode of playback through linear, random from playlist and manual (stop when
each track finishes)
toggle-play
Toggle playback
Play from the current song if playback was stopped or paused, otherwise pause.
volume[string]
Set volume
string can be delta (+/-value, for instance +4) or absolute value (0~100). If run
without any parameters, return the current volume.
mute Toggle mute
crossfade[integer]Setcrossfadetimeinseconds.Ifnointegerisgiven,orintegeris0,togglecrossfade.Ifsettoanegativevalue,turncrossfadeoff.seekintegerSeekintegerseconds(canbenegative)intheplayingsong.repeat Rotate repeat mode through none, repeat one and repeat list
Addingandplayingplay-album
Play all songs from the album of the song under the cursor
play-artist
Play all songs from the selected artist
play-random[n]Playoneornrandomsongsfromthelibraryorvisiblelist.add-album
Add all songs from the selected album to playlist
add-all
Add all songs from the currently visible list to playlist
If part of the album already is at the bottom of the playlist the remainder is
added.
add-artist
Add all songs from the selected artist to the playlist
add-random[n]Addoneornrandomsongsfromthevisiblelisttotheplaylist.remove Remove selected song from playlist
Playlistmanagementcreatestring
Create a new empty playlist with given name
savestring
Saves the current list view into a new playlist file with given filename
delete-list[string]
Permanently delete the named playlist if given or else the current playlist
activate-list
Activate currently viewed list for playback
crop Crop the current playlist to the currently playing song
cropsel
Crop the current playlist to the selected songs, or song under cursor
clear Clear the playlist
shuffle
Shuffle the playlist
moveinteger
Move the selected songs by the given offset
A positive offset moves songs down; a negative offset moves songs up.
update[string]AskMPDtoupdatethemusiclibrary.stringcanbeafileinthemusiclibrary,oroneofthis,thisdir,currentorcurrentdir.select[string]unselect[string]toggle-select[string]
Select, unselect or toggle selection of songs matching a search term
If no parameter is given, the song under the cursor is affected.
clear-selection
Unselect all songs in the playlist
Applicationinfo Show info in the status bar about the current song
help Show current key bindings
command-mode
Enter command mode, where you can enter configuration options or perform other
commands (including those which are not mapped to any key)
change-windowenum
Change the active window to playlist, library or windowlistnext-window
Move to the next window
prev-window
Move to the previous window
last-window
Switch to the previously viewed window
redraw Force screen redraw
rehash Reload the configuration file
version
Show version information
clear-topbar[integer]
Clear out all contents of the topbar or, if a parameter is given, only that line
!string
Run a shell command
Some vim-like placeholders are available:
% The current song's file path, not escaped in any way
# The currently highlighted song's file path, not escaped in any way
## The file path of each of the songs in the current selection or, if
there is no selection, each song in the currently visible list. Each
path is enclosed in double quotes.
Examples:
!echo"%"|xclip
Copy the current song's file path to the X clipboard
!rox-filer"$(dirname"#")"
Browse the directory containing the currently highlighted song with
Rox-filer
!transcribe##
Open the selected songs (or, with no selection, all songs on the
playlist) in Transcribe
!cp##/media/removabledrive
Copy the selected songs (or, with no selection, all songs on the
playlist) to a USB stick or portable media player
All paths are prefixed with the string in the config variable libraryroot.
quit, q
Exit PMS
Movementandsearchmove-up
Move the cursor up
In command or quick-find mode move to the previous item in command or search
history.
move-down
Move the cursor down.
In command or quick-find mode move to the next item in command or search history.
move-halfpgup
Move the cursor one half screen up
move-halfpgdn
Move the cursor one half screen down
move-pgup
Move the cursor one screen up
move-pgdn
Move the cursor one screen down
move-home
Move the cursor to the start of the list
move-end
Move the cursor to the end of the list
scroll-up
Scroll the list up one line (only acts differently from move-up if scroll is set to
normal)
scroll-down
Scroll the list down one line (only acts differently from move-up if scroll is set
to normal)
center-cursor
Scroll the list such that the cursor is centered (only has an effect when scroll is
set to normal)
filter Enter filter mode: type to filter the current view for songs. Songs that don't match
are removed from the view. Use the clear-filters command to return to the original
view.
clear-filters
Clear all filters from the current playlist.
quick-find
Enter quick-find mode: type to jump to next matched song
next-result
Find the next search result from the last quick-find
prev-result
Find the previous search result from the last quick-find
next-ofstring
Parameter should be a field name (see FIELDS above) – jump to the next track in the
list for which the field differs
prev-ofstring
Parameter should be a field name (see FIELDS above) – jump up the list to the first
(topmost) of a set of tracks which have in common the next differing value of the
given field
To put that another way, the cursor moves up until the given field changes, then
keeps going until just before it would change again.
goto-current
Jumps to the current playing song, if any
goto-random
Jump to a random song in the playlist
Install Now
PNG Icons
