pms(1)pms(1)NAMEpms - Practical Music Search, an ncurses-based MPD client
SYNOPSISpms [-?] [-v] [-d] [-h hostname ] [-c configfile ] [-p port ] [-P pass‐
word ]
DESCRIPTION
Practical Music Search aims to be a highly accessible and configurable
client to the Music Player Daemon. It features key mapping, customized
colors, a command-line mode, several modes of play, and an easy but
powerful interface.
OPTIONS
-? Show command-line options and exit
-v Print version and exit
-d Turn on debugging to stderr
-h hostname
Connect to MPD server hostname
-c configfile
Use configfile as an additional configuration file
-p port
Connect to port on MPD server
-P password
Specify password for the MPD server
CONFIGURATION
Configuration is done in three parts: options, key bindings, and col‐
ors.
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.freedesk‐
top.org/basedir-spec/basedir-spec-0.6.html). Possible directories are
collected from the environment variables XDG_CONFIG_DIRS and XDG_CON‐
FIG_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_CON‐
FIG_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.
Setting options
String, integer and enumerated options are set with
set option=value
Boolean options are set with
set option
and reset with
set nooption
They can be toggled with
set option!
or
set invoption
Values can be retrieved with
set option?
se is an alias for set and : can be used in place of =.
Setting bindings
Key bindings are set with
bind key command
and removed with
unbind key
key 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.
Setting colors
Colors are defined with
color item foreground [background]
colour is an alias for color.
OPTIONS
host=string
The hostname to connect to. Default: localhost
port=integer
The port on the MPD server to connect to. Default: 6600
password=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 speci‐
fied 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: 30
msg_buffer_size=integer
How many log lines to keep in the console. A value of 0
keeps all lines. Default: 1024
mpd_timeout=integer
Sets MPD connection timeout in seconds. Leave this lower
than your MPD setting. Default: 30
debug (boolean)
Turn debugging mode on or off. Default: set
repeat=enum
Choose between single or a boolean value. Default: off
stopdelay=integer
MPD does not support manual progression within the
playlist. A hack is neccessary to stop when the song is
done. If manual song progression is not working cor‐
rectly, increase this value. Default: 1
nextinterval=integer
This setting controls how many seconds from the current
song ends until PMS automatically adds the next song to
MPD's playlist. Default: 5
crossfade=integer
Set crossfade time in seconds. 0 turns crossfade off com‐
pletely. Default: MPD's settings
onplaylistfinish=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 orig‐
inal window. Else, the destination will be focused.
Default: unset
followplayback (boolean)
If set, the cursor will go to the currently playing song
and playlist when it changes. Default: unset
followwindow (boolean)
If set, playback will continue in the active window.
Default: unset
followcursor (boolean)
If set, playback will follow cursor position. Default:
unset
nextafteraction (boolean)
Move cursor to next item after the song is selected, uns‐
elected or added to a playlist. Default: set
startuplist=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: playlist
regexsearch (boolean)
Use regular expressions for search terms. Default: set
ignorecase (boolean)
Ignore case when sorting and searching. The alias ic can
also be used. Default: set
scroll=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 posi‐
tion of the visible songs relative to the
whole song list. Try it out to get a better
idea of how it works.
Default: normal
scrolloff=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: 0
playmode=enum
Set song progression mode to manual, linear or random. In
manual progression mode playback will stop at the end of
each song. Default: linear
resetstatus=integer
Set how many seconds before resetting the statusbar text.
Default: 3
sort=field [field [...]]
Fields by which to sort the library. You can specify mul‐
tiple fields, separated by whitespace. See FIELDS below.
Default: track disc album albumartistsort
columns=column [column [...]]
Columns to show in the list. See FIELDS below. Default:
artist track title album length
status_unknown=string
status_play=string
status_pause=string
status_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 previ‐
ous track, control-mousewheel to turn vol‐
ume 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 tog‐
gle 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: unset
topbarspace (boolean)
Whether or not to leave an extra space at the end of
fixed-width columns. Default: set
topbarvisible (boolean)
If set, the topbar is visible. Default: set
topbarborders (boolean)
Whether or not to draw borders on the topbar window.
Default: unset
columnspace (boolean)
Whether or not to leave a blank row between the topbar
and the playlist windows. Default: set
topbarclear (boolean)
Start out with an empty topbar. Default: unset
topbar[1-99].(left|center|right)=string
Modify what is displayed in the topbar. The spelling cen‐
tre 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, pro‐
gressbar, 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 condi‐
tionals:
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%%repeat‐
short%%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, albumartist‐
sort, title, album, track, trackshort, time, date, year,
name, genre, composer, performer, disc, comment
COLORS
Items available for coloring:
background, foreground, statusbar, error, position, bor‐
ders, headers, title, current, cursor, selection,
lastlist, playinglist, fields.* topbar.foreground, top‐
bar.time_elapsed, topbar.time_remaining, topbar.pro‐
gresspercentage, topbar.progressbar, topbar.repeat, top‐
bar.random, topbar.mute, topbar.repeatshort, topbar.ran‐
domshort, topbar.muteshort, topbar.librarysize, top‐
bar.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, bright‐
magenta, brightcyan
The following colors can be used either for background or fore‐
ground 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.
COMMANDS
Playback
play 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 parame‐
ters, return the current volume.
mute Toggle mute
crossfade [integer]
Set crossfade time in seconds. If no integer is
given, or integer is 0, toggle crossfade. If set
to a negative value, turn crossfade off.
seek integer
Seek integer seconds (can be negative) in the
playing song.
repeat Rotate repeat mode through none, repeat one and
repeat list
Adding and playing
play-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]
Play one or n random songs from the library or
visible list.
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]
Add one or n random songs from the visible list to
the playlist.
remove Remove selected song from playlist
Playlist management
create string
Create a new empty playlist with given name
save string
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
move integer
Move the selected songs by the given offset
A positive offset moves songs down; a negative
offset moves songs up.
update [string]
Ask MPD to update the music library. string can be
a file in the music library, or one of this, this‐
dir, current or currentdir.
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 cur‐
sor is affected.
clear-selection
Unselect all songs in the playlist
Application
info Show info in the status bar about the current song
help Show current key bindings
command-mode
Enter command mode, where you can enter configura‐
tion options or perform other commands (including
those which are not mapped to any key)
change-window enum
Change the active window to playlist, library or
windowlist
next-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 con‐
fig variable libraryroot.
quit, q
Exit PMS
Movement and search
move-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 differ‐
ently 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-of string
Parameter should be a field name (see FIELDS
above) – jump to the next track in the list for
which the field differs
prev-of string
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
FILES
/etc/xdg/pms/rc, /usr/local/xdg/pms/rc, ~/.config/pms/rc
Default paths to configuration files, loaded in this order (see
the configuration section above)
ENVIRONMENT
HOME Used to generate the default path to the configuration file if
XDG_CONFIG_HOME is not set or empty
XDG_CONFIG_HOME
The prefix for the user-specific configuration file
XDG_CONFIG_DIRS
Prefixes for system-wide configuration files
MPD_HOST
Specifies the host which MPD runs on
MPD_PORT
Specifies the port on which MPD listens
MPD_PASSWORD
Specifies a password to send to MPD on connection
AUTHOR
Written by Kim Tore Jensen <kimtjen@gmail.com> with help from Bart
Nagel <bart@tremby.net>.
The newest version can be obtained at <http://pms.sourceforge.net>.
SEE ALSOmpd(1)pms(1)
