pms(1)

NAME

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

SYNOPSIS

pms [-?] [-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 configuration file instead of default

-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 the configuration file (~/.pms/rc).

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)

reconnectdelay=integer

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

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

repeatonedelay=integer

MPD does not support the '1-repeat' mode, and a hack is neccessary. If repeat-1 is not working for you, increase this value. Default: 1

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 correctly, increase this value. Default: 1

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

follow (boolean)

Set both followwindow and followcursor to selected value.

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

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. 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: ??, |>, ||, []

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

topbarvisible (boolean)

If set, the topbar is visible. Default: set

topbarborders (boolean)

Whether or not to draw borders on the topbar window. Default: unset

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

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

mute Toggle mute

crossfade [integer]

Set crossfade time in seconds or turn crossfade on and 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

Play a random song from the library

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

Add a random song from the library to playlist

remove Remove selected song from playlist

Playlist management

create string

Create a new empty playlist with given name

save string

Saves the playlist 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 Ask MPD to update the music library

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 Roxfiler

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

quick-find

Enter quick-find mode: type to search for songs

next-result

Find the next search result from the last quickfind

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

~/.pms/rc

Configuration file

ENVIRONMENT

HOME The configuration file is read from $HOME/.pms/rc

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

These environment variables are overridden by command-line switches and the config file.

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)