Provided by: pms_0.42-1_amd64 bug

NAME

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

SYNOPSIS

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

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

       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 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: 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
                     necessary to stop when the song is done.  If manual song progression is  not
                     working correctly, 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  completely.  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 original  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, unselected 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 position 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  multiple  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
                                   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: 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  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,
                     comment

       COLORS

              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.

       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 parameters, 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, thisdir, 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 cursor 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 configuration 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  config  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 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-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 ALSO

       mpd(1)

                                                                                           pms(1)