xaizek / pms (License: GPLv3+) (since 2018-12-07)
Older version of Practical Music Search written in C++.
Clone URLs: https://code.reversed.top/user/xaizek/pms ssh://rocketgit@code.reversed.top/user/xaizek/pms
0.42 c experimental gh-pages legacy libmpdclient master
Commit a2c3e35f0bdb351875e957df617b754519db0b02

Start porting manpage to markdown format
Author: Kim Tore Jensen
Author date (UTC): 2015-08-29 23:04
Committer name: Kim Tore Jensen
Committer date (UTC): 2015-08-29 23:04
Parent(s): c911966c8c4b847bfec0abe242595127a0268159
Signing key:
Tree: 3fdee2f223079db03a6e05adbcc173981cf3bf41
File Lines added Lines deleted
doc/manpage.md 610 0
File doc/manpage.md added (mode: 100644) (index 0000000..370c74d)
1 % PMS(1) Practical Music Search
2 % Kim Tore Jensen <kimtjen@gmail.com>
3 % August 29, 2015
4
5 # NAME
6
7 pms − Practical Music Search, a Vim-like MPD client based on ncurses
8
9 # SYNOPSIS
10
11 pms [*−?*] [*−v*] [*−d*] [*−h hostname*] [*−c configfile*] [*−p port*] [*−P password*]
12
13 # DESCRIPTION
14
15 Practical Music Search aims to be a highly accessible and configurable client
16 to the Music Player Daemon. It features key mapping, customized colors, a
17 command-line mode, several modes of play, and an easy but powerful interface.
18
19 # OPTIONS
20
21 -?, \--help
22 : Show command-line options and exit
23
24 -v
25 : Print version and exit
26
27 -d
28 : Turn on debugging output to standard error. If you use this command-line
29 option, you should redirect output to a log file lest you clutter up the
30 screen.
31
32 -h *hostname*
33 : Connect to MPD server hostname
34
35 -c *configfile*
36 : Use configfile as an additional configuration file
37
38 -p *port*
39 : Connect to port on MPD server
40
41 -P *password*
42 : Specify password for the MPD server
43
44 # CONFIGURATION
45
46 Configuration is done in three parts: options, key bindings, and colors.
47
48 Options, bindings and colors can be set at runtime by entering command mode
49 (default binding *:*) or can be preset in a configuration file.
50
51 Configuration files are loaded in a specific order in line (almost) with the
52 XDG Base Directory Specification
53 <http://standards.freedesktop.org/basedir-spec/basedir-spec-0.6.html>. Possible
54 directories are collected from the environment variables *XDG_CONFIG_DIRS* and
55 *XDG_CONFIG_HOME* (the former defaults in PMS to /usr/local/etc/xdg:/etc/xdg
56 rather than just /etc/xdg as in the spec, the latter defaults to $HOME/.config
57 as in the spec).
58
59 Each path in order from lowest priority (the last entry in *XDG_CONFIG_DIRS*) to
60 highest (*XDG_CONFIG_HOME*) is suffixed with `/pms/rc` and if this file exists
61 it is loaded. Finally, if a configuration file was specified on the commandline
62 this file is loaded.
63
64 ## Configuring options
65
66 String, integer and enumerated options are set with
67
68 set option=value
69
70 Boolean options are set with
71
72 set option
73
74 and reset with
75
76 set nooption
77
78 They can be toggled with
79
80 set option!
81
82 or
83
84 set invoption
85
86 Values can be retrieved with
87
88 set option?
89
90 *se* is an alias for *set* and *:* can be used in place of *=*.
91
92 ## Configuring keybindings
93
94 Key bindings are set with
95
96 bind key command
97
98 and removed with
99
100 unbind key
101
102 key can be any single character, in addition to these special characters: *up*,
103 *down*, *left*, *right*, *pageup*, *pagedown*, *home*, *end*, *space*,
104 *delete*, *insert*, *backspace*, *return*, *kpenter*, *tab* and *F1* through
105 *F63*.
106
107 When unbinding, you can specify *all* as a parameter to remove all bindings.
108
109 *map* is an alias for *bind*, while *unmap* and *unm* are aliases for *unbind*.
110
111 ## Configuring colors
112
113 Colors are defined with
114
115 color item foreground [background]
116
117 *colour* is an alias for *color*.
118
119 # OPTIONS
120
121 ## Configuration options
122
123 host=*string*
124 : The hostname to connect to. Default: localhost
125
126 port=*integer*
127 : The port on the MPD server to connect to. Default: 6600
128
129 password=*string*
130 : The password to give to the MPD server. Default: none
131
132 libraryroot=*string*
133 : Optional path to the library’s root. See !string below. If used, it should have a trailing slash. Default: empty string (nothing is prepended)
134
135 xtermtitle=*string*
136 : If set, the XTerm window title will be set to the specified string. Default: PMS: %playstate%%ifcursong% %artist% – %title%%endif%
137
138 reconnectdelay=*integer*
139 : If a connection is lost, this is how many seconds between each connection retry. Default: 30
140
141 mouse (*boolean*)
142 : 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. Default: unset
143
144 msg_buffer_size=*integer*
145 : How many log lines to keep in the console. A value of 0 keeps all lines. Default: 1024
146
147 mpd_timeout=*integer*
148 : Sets MPD connection timeout in seconds. Leave this lower than your MPD setting. Default: 30
149
150 debug (*boolean*)
151 : Turn debugging mode on or off. Default: set
152
153 stopdelay=*integer*
154 : 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
155
156 nextinterval=*integer*
157 : This setting controls how many seconds from the current song ends until PMS automatically adds the next song to MPD’s playlist. Default: 5
158
159 crossfade=*integer*
160 : Set crossfade time in seconds. 0 turns crossfade off completely. Default: MPD’s settings
161
162 onplaylistfinish=*string*
163 : Specify a shell command to run when the playlist finishes and playback stops. Default: none
164
165 addtoreturns (*boolean*)
166 : If set, the add-to command will return focus to the original window. Else, the destination will be focused. Default: unset
167
168 followplayback (*boolean*)
169 : If set, the cursor will go to the currently playing song and playlist when it changes. Default: unset
170
171 followwindow (*boolean*)
172 : If set, playback will continue in the active window. Default: unset
173
174 followcursor (*boolean*)
175 : If set, playback will follow cursor position. Default: unset
176
177 nextafteraction (*boolean*)
178 : Move cursor to next item after the song is selected, unselected or added to a playlist. Default: set
179
180 startuplist=*"playlist|library|..."*
181 : 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
182
183 regexsearch (*boolean*)
184 : Use regular expressions for search terms. Default: set
185
186 ignorecase (*boolean*)
187 : Ignore case when sorting and searching. The alias ic can also be used. Default: set
188
189 scroll=*SCROLL MODE*
190 : Set scroll mode; see *SCROLL MODES* below. Default: normal
191
192 scrolloff=*integer*
193 : 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
194
195 resetstatus=*integer*
196 : Set how many seconds before resetting the statusbar text. Default: 3
197
198 sort=tag [tag [...]]
199 : Tags by which to sort the library. You can specify multiple tags, separated by whitespace; see *TAGS*. Default: track disc album albumartistsort
200
201 columns=column [column [...]]
202 : Columns to show in the list; see *TAGS*. Default: artist track title album length
203
204 status_unknown=*string*
205 : Topbar status string when status is unknown. Default: ??
206
207 status_play=*string*
208 : Topbar status string when playing. Default: |>
209
210 status_pause=*string*
211 : Topbar status string when paused. Default: ||
212
213 status_stop=*string*
214 : Topbar status string when stopped. Default: []
215
216 topbarspace (*boolean*)
217 : Whether or not to leave an extra space at the end of fixed-width columns. Default: set
218
219 topbarvisible (*boolean*)
220 : If set, the topbar is visible. Default: set
221
222 topbarborders (*boolean*)
223 : Whether or not to draw borders on the topbar window. Default: unset
224
225 columnspace (*boolean*)
226 : Whether or not to leave a blank row between the topbar and the playlist windows. Default: set
227
228 columnborders (*boolean*)
229 : If set, draw borders between columns. Default: unset
230
231 topbarclear (*boolean*)
232 : Start out with an empty topbar. Default: unset
233
234 topbar[1-99].(left|center|right)=*string*
235 : Modify what is displayed in the topbar. The spelling *centre* is also accepted. See *Configuring the topbar* for format syntax, available tags and defaults.
236
237 ## Configuring the topbar
238
239 Available variables to put in the topbar:
240
241 bitrate, bits, channels, librarysize, listsize, livequeuesize, manual,
242 manualshort, mute, muteshort, playstate, progressbar, progresspercentage,
243 queuesize, random, randomshort, repeat, repeatshort, samplerate,
244 time_elapsed, time_remaining, volume
245
246 All *TAGS* can also be used.
247
248 Conditionals (if-else) are supported. Currently available conditionals:
249
250 ifcursong, ifplaying, ifpaused, ifstopped
251
252 See the defaults below for how conditionals are used.
253
254 The topbar syntax allows free customization of the top area of the display. A good way to understand the syntax is to take a look at the defaults:
255
256 set topbar1.left=%time_elapsed% %playstate% %time%%ifcursong% (%progresspercentage%%%)%endif%
257 set topbar1.center=%ifcursong%%artist%%endif%
258 set topbar1.right=Vol: %volume%%% Mode: %muteshort%%repeatshort%%randomshort%%manualshort%
259 set topbar2.center=%ifcursong%==> %title% <==%else%No current song%endif%
260 set topbar3.left=%listsize%
261 set topbar3.center=%ifcursong%%album% (%year%)%endif%
262 set topbar3.right=Q: %livequeuesize%
263
264 # COMMANDS
265
266 ## Playback
267
268 play
269 : Play the song under the cursor
270
271 add
272 : Add the selected song(s) to the playlist. If a playlist is selected in windowlist mode, that list is appended to the playlist.
273
274 add-to
275 : Add the selected song(s) to a chosen playlist
276
277 next
278 : Play the next song from the playlist or library based on current play mode
279
280 really-next
281 : Play the next song from playlist or library, regardless of play mode.
282
283 prev
284 : Play previous song
285
286 pause
287 : Pause playback or play if playback was paused; do nothing if playback is stopped
288
289 stop
290 : Stop playback
291
292 toggle-play
293 : Toggle playback. Play from the current song if playback was stopped or paused, otherwise pause.
294
295 volume [string]
296 : Set volume. *string* can be delta (+/-value, for instance +4) or absolute value (0~100). If run without any parameters, return the current volume.
297
298 mute
299 : Toggle mute
300
301 crossfade [integer]
302 : 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.
303
304 seek integer
305 : Seek integer seconds (can be negative) in the playing song.
306
307 repeat
308 : Rotate repeat mode through none, repeat one and repeat list
309
310 ## Adding and playing
311
312 play-album
313 : Play all songs from the album of the song under the cursor
314
315 play-artist
316 : Play all songs from the selected artist
317
318 play-random [n]
319 : Play one or n random songs from the library or visible list.
320
321 add-album
322 : Add all songs from the selected album to playlist
323
324 add-all
325 : Add all songs from the currently visible list to playlist. If part of the album already is at the end of the playlist, the remainder is added.
326
327 add-artist
328 : Add all songs from the selected artist to the playlist
329
330 add-random [n]
331 : Add one or n random songs from the visible list to the playlist.
332
333 remove
334 : Remove selected song from playlist
335
336 ## Playlist management
337
338 create string
339 : Create a new empty playlist with given name
340
341 save string
342 : Saves the current list view into a new playlist file with given filename
343
344 delete-list [string]
345 : Permanently delete the named playlist if given or else the current playlist
346
347 activate-list
348 : Activate currently viewed list for playback
349
350 crop
351 : Crop the current playlist to the currently playing song
352
353 cropsel
354 : Crop the current playlist to the selected songs, or song under cursor
355
356 clear
357 : Clear the playlist
358
359 shuffle
360 : Shuffle the playlist
361
362 move integer
363 : Move the selected songs by the given offset. A positive offset moves songs down; a negative offset moves songs up.
364
365 update [string]
366 : Ask MPD to update the music library. string can be a file in the music library, or one of this, thisdir, current or currentdir.
367
368 select [string]
369 : Select songs matching a search term. If no parameter is given, the song under the cursor is affected.
370
371 unselect [string]
372 : Unselect songs matching a search term. If no parameter is given, the song under the cursor is affected.
373
374 toggle-select [string]
375 : Toggle selection of songs matching a search term. If no parameter is given, the song under the cursor is affected.
376
377 clear-selection
378 : Unselect all songs in the playlist
379
380 ## Application
381
382 info
383 : Show info in the status bar about the current song
384
385 help
386 : Show current key bindings
387
388 command-mode
389 : Enter command mode, where you can enter configuration options or perform other commands (including those which are not mapped to any key)
390
391 change-window *playlist|library|windowlist*
392 : Change the active window to playlist, library or windowlist
393
394 next-window
395 : Move to the next window
396
397 prev-window
398 : Move to the previous window
399
400 last-window
401 : Switch to the previously viewed window
402
403 redraw
404 : Force screen redraw
405
406 rehash
407 : Reload the configuration file
408
409 version
410 : Show version information
411
412 clear-topbar [integer]
413 : Clear out all contents of the topbar or, if a parameter is given, only that line
414
415 !string
416 : Run a shell command
417
418 Some vim-like placeholders are available:
419
420 % The current song’s file path, not escaped in any way
421
422 # The currently highlighted song’s file path, not escaped in any way
423
424 ## 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.
425
426 Examples:
427
428 !echo "%" | xclip
429
430 Copy the current song’s file path to the X clipboard
431
432 !rox-filer "$(dirname "#")"
433
434 Browse the directory containing the currently highlighted song with Rox-filer
435
436 !transcribe ##
437
438 Open the selected songs (or, with no selection, all songs on the playlist) in Transcribe
439
440 !cp ## /media/removabledrive
441
442 Copy the selected songs (or, with no selection, all songs on the playlist) to a USB stick or portable media player
443
444 All paths are prefixed with the string in the config variable libraryroot.
445
446 quit, q
447 : Exit PMS
448
449 ## Movement and search
450
451 move-up
452 : Move the cursor up. In command or quick-find mode move to the previous item in command or search history.
453
454 move-down
455 : Move the cursor down. In command or quick-find mode move to the next item in command or search history.
456
457 move-halfpgup
458 : Move the cursor one half screen up
459
460 move-halfpgdn
461 : Move the cursor one half screen down
462
463 move-pgup
464 : Move the cursor one screen up
465
466 move-pgdn
467 : Move the cursor one screen down
468
469 move-home
470 : Move the cursor to the start of the list
471
472 move-end
473 : Move the cursor to the end of the list
474
475 scroll-up
476 : Scroll the list up one line (only acts differently from move-up if scroll is set to normal)
477
478 scroll-down
479 : Scroll the list down one line (only acts differently from move-up if scroll is set to normal)
480
481 center-cursor
482 : Scroll the list such that the cursor is centered (only has an effect when scroll is set to normal)
483
484 filter
485 : 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.
486
487 clear-filters
488 : Clear all filters from the current playlist.
489
490 quick-find
491 : Enter quick-find mode: type to jump to next matched song
492
493 next-result
494 : Find the next search result from the last quick-find
495
496 prev-result
497 : Find the previous search result from the last quick-find
498
499 next-of string
500 : Parameter should be a field name (see *TAGS*) – jump to the next track in the list for which the field differs
501
502 prev-of string
503 : Parameter should be a field name (see *TAGS*) – 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.
504
505 goto-current
506 : Jumps to the current playing song, if any
507
508 goto-random
509 : Jump to a random song in the playlist
510
511 # TAGS
512
513 Tags are used for sorting, columns, topbar, and several other things.
514
515 The following tags can be used everywhere *TAGS* are supported:
516
517 album, albumartist, albumartistsort, artist, artistsort, comment, composer,
518 date, disc, file, genre, name, num, performer, time, title, track,
519 trackshort, year
520
521 # COLORS
522
523 The following colors can be configured:
524
525 background, borders, current, cursor, error, fields.*, foreground, headers,
526 lastlist, playinglist, position, selection, statusbar, title,
527 topbar.fields.*, topbar.foreground, topbar.librarysize, topbar.listsize,
528 topbar.livequeuesize, topbar.mute, topbar.muteshort, topbar.playstate,
529 topbar.progressbar, topbar.progresspercentage, topbar.queuesize,
530 topbar.random, topbar.randomshort, topbar.repeat, topbar.repeatshort,
531 topbar.time_elapsed, topbar.time_remaining
532
533 Replace the wildcard * with any of the *TAGS* described above.
534
535 The following colors can be used only as foreground colors:
536
537 gray, brightred, brightgreen, yellow, brightblue, brightmagenta, brightcyan
538
539 The following colors can be used either for background or foreground colors:
540
541 black, red, green, brown, blue, magenta, cyan, brightgray
542
543 The special color *trans* can only be used as a background color, and provides a transparent background.
544
545 The alternative spelling *grey* can be used in the place of *gray*, and *light* can be used in place of *bright*.
546
547 # MOUSE ACTIONS
548
549 topbar
550 : 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
551
552 header
553 : Click or scroll mousewheel down on the window title to switch to the next window. Doubleclick or scroll mousewheel up to switch to the previous window.
554
555 playlist
556 : 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.
557
558 statusbar
559 : Click to enter command mode
560
561 # SCROLL MODES
562
563 normal
564 : The list only scrolls when the cursor is about to go off the top or bottom of the window. See the *scrolloff* option.
565
566 centered
567 : 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.
568
569 relative
570 : 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.
571
572 # FILES
573
574 * /etc/xdg/pms/rc
575 * /usr/local/xdg/pms/rc
576 * ~/.config/pms/rc
577
578 Default paths to configuration files, loaded in this order (see the configuration section above).
579
580 # ENVIRONMENT
581
582 HOME
583 : Used to generate the default path to the configuration file if *XDG_CONFIG_HOME* is not set or empty
584
585 XDG_CONFIG_HOME
586 : The prefix for the user-specific configuration file
587
588 XDG_CONFIG_DIRS
589 : Prefixes for system-wide configuration files
590
591 MPD_HOST
592 : Specifies the host which MPD runs on
593
594 MPD_PORT
595 : Specifies the port on which MPD listens
596
597 MPD_PASSWORD
598 : Specifies a password to send to MPD on connection
599
600 # AUTHORS
601
602 Copyright (c) 2006-2015 Kim Tore Jensen <kimtjen@gmail.com>.
603
604 Written by Kim Tore Jensen <kimtjen@gmail.com> and Bart Nagel <bart@tremby.net>.
605
606 The newest version can be obtained at <https://ambientsound.github.io/pms/>.
607
608 # SEE ALSO
609
610 mpd(1)
Hints
Before first commit, do not forget to setup your git environment:
git config --global user.name "your_name_here"
git config --global user.email "your@email_here"

Clone this repository using HTTP(S):
git clone https://code.reversed.top/user/xaizek/pms

Clone this repository using ssh (do not forget to upload a key first):
git clone ssh://rocketgit@code.reversed.top/user/xaizek/pms

You are allowed to anonymously push to this repository.
This means that your pushed commits will automatically be transformed into a pull request:
... clone the repository ...
... make some changes and some commits ...
git push origin master