Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
pms(1)			    General Commands Manual			pms(1)

       pms - Practical Music Search, an	ncurses-based MPD client

       pms [-?]	[-v] [-d] [-h hostname ] [-c configfile	] [-p port ] [-P pass-
       word ]

       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.

       -?     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  is  done in three	parts: options,	key bindings, and col-

       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-   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!
		     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

       Setting colors
	      Colors are defined with
		     color item	foreground [background]

	      colour is	an alias for color.


		     The hostname to connect to. Default: localhost

		     The port on the MPD server	to connect to. Default:	6600

		     The password to give to the MPD server. Default: none

		     Optional  path  to	the library's root. See	!string	below.
		     If	used, it should	have a trailing	slash. Default:	 empty
		     string (nothing is	prepended)

		     If	 set, the XTerm	window title will be set to the	speci-
		     fied   string.   Default:	 PMS:	%playstate%%ifcursong%
		     %artist% -	%title%%endif%

		     If	a connection is	lost, this is how many seconds between
		     each connection retry. Default: 30

		     How many log lines	to keep	in the console.	A value	 of  0
		     keeps all lines. Default: 1024

		     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

		     Choose between single or a	boolean	value. Default:	off

		     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

		     This  setting  controls how many seconds from the current
		     song ends until PMS automatically adds the	next  song  to
		     MPD's playlist. Default: 5

		     Set crossfade time	in seconds. 0 turns crossfade off com-
		     pletely. Default: MPD's settings

		     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.  De-
		     fault: 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.  De-
		     fault: unset

	      followcursor (boolean)
		     If	 set,  playback	 will follow cursor position. Default:

	      nextafteraction (boolean)
		     Move cursor to next item after the	song is	selected, uns-
		     elected or	added to a playlist. Default: set

		     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

		     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.

				   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.

				   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

		     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

		     Set song progression mode to manual, linear or random. In
		     manual progression	mode playback will stop	at the end  of
		     each song.	Default: linear

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

				   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

				   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. De-
		     fault: 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

		     Modify what is displayed in the topbar. The spelling cen-
		     tre is also accepted. See TOPBAR below for	format syntax,
		     available fields and defaults.


	      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,  bi-
		     trate, samplerate,	bits, channels

		     All FIELDS	below can also be used.

	      Conditionals (if-else) are supported. Currently available	condi-
		     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%
	      set  topbar1.right=Vol:  %volume%%%   Mode:  %muteshort%%repeat-
	      set>	 %title%  <==%else%No  current
	      set topbar3.left=%listsize%
	      set (%year%)%endif%
	      set topbar3.right=Q: %livequeuesize%


	      Available	fields are:
		     num,  file, artist, artistsort, albumartist, albumartist-
		     sort, title, album, track,	trackshort, time, date,	 year,
		     name, genre, composer, performer, disc, comment


	      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,
		     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.



		     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

			    Play  the  next song from playlist or library, re-
			    gardless 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

			    Rotate  mode  of  playback	through	linear,	random
			    from playlist and manual  (stop  when  each	 track

			    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 all songs from	the album of  the  song	 under
			    the	cursor

			    Play all songs from	the selected artist

		     play-random [n]
			    Play  one  or  n  random songs from	the library or
			    visible list.

			    Add	all songs from the selected album to playlist

			    Add	all songs from the currently visible  list  to

			    If	part  of the album already is at the bottom of
			    the	playlist the remainder is added.

			    Add	all songs from	the  selected  artist  to  the

		     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 currently viewed list for playback

		     crop   Crop the current playlist to the currently playing

			    Crop  the  current playlist	to the selected	songs,
			    or song under cursor

		     clear  Clear the playlist

			    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.

			    Unselect all songs in the playlist


		     info   Show info in the status bar	about the current song

		     help   Show current key bindings

			    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

			    Move to the	next window

			    Move to the	previous window

			    Switch to the previously viewed window

		     redraw Force screen redraw

		     rehash Reload the configuration file

			    Show version information

		     clear-topbar [integer]
			    Clear out all contents of the topbar or, if	a  pa-
			    rameter is given, only that	line

			    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.


				   !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-

				   !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 the cursor up

			    In command or quick-find mode move to the previous
			    item in command or search history.

			    Move the cursor down.

			    In	command	 or  quick-find	 mode move to the next
			    item in command or search history.

			    Move the cursor one	half screen up

			    Move the cursor one	half screen down

			    Move the cursor one	screen up

			    Move the cursor one	screen down

			    Move the cursor to the start of the	list

			    Move the cursor to the end of the list

			    Scroll the list up one line	(only acts differently
			    from move-up if scroll is set to normal)

			    Scroll  the	 list down one line (only acts differ-
			    ently from move-up if scroll is set	to normal)

			    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 all filters from the current playlist.

			    Enter  quick-find  mode:  type  to	jump  to  next
			    matched song

			    Find  the  next search result from the last	quick-

			    Find the previous  search  result  from  the  last

		     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.

			    Jumps to the current playing song, if any

			    Jump to a random song in the playlist

       /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)

       HOME   Used  to	generate the default path to the configuration file if
	      XDG_CONFIG_HOME is not set or empty

	      The prefix for the user-specific configuration file

	      Prefixes for system-wide configuration files

	      Specifies	the host which MPD runs	on

	      Specifies	the port on which MPD listens

	      Specifies	a password to send to MPD on connection

       Written by Kim Tore Jensen  <>	with  help  from  Bart
       Nagel <>.

       The newest version can be obtained at <>.




Want to link to this manual page? Use this URL:

home | help