1XMMS2(1) General Commands Manual XMMS2(1)
2
6 xmms2 - The official XMMS2 command line interface
7
9 xmms2 [command] [arguments]
10 xmms2 help [command]
11
13 XMMS2 is a redesign of the XMMS (http://legacy.xmms2.org) music player.
14 It features a client-server model, allowing multiple (even simultane‐
15 ous!) user interfaces, both textual and graphical. All common audio
16 formats are supported using plugins. On top of this, there is a flexi‐
17 ble media library to organise your music.
18 xmms2 is the official CLI XMMS2 client.
20
22 Inline mode
23 If xmms2 is passed a command as an argument, that command will be
24 interpreted and xmms2 will exit after it is finished.
25 Interactive mode
27 xmms2 features a powerful shell-like environment via readline that
28 allows the user to enter commands at a prompt and have the usual cool
29 features such as pathname expansion and line editing.
30
32 All commands accept the option -h/--help which displays the command's
33 help.
34 pattern refers to a collection definition. (See PATTERN below.)
36 position is a pattern to match playlist positions. (See POSITION PAT‐
38 TERN below.)
39 General Commands
41 add [ -f [-N] [-P] [-A key=value]... ] [-p playlist] [-n | -a position]
42 [-o prop[,...]] arguments...
43 add [-p playlist] [-n | -a position] [-o prop[,...]] pattern...
44 Add media to a playlist. It will attempt to guess whether arguments
46 constitute a pattern or represent file paths. This behaviour can be
47 overridden by forcing the type with -f and -t. If file paths con‐
48 tain * or ? characters, it will attempt to expand them. Failing to
49 find a match the * and ? characters will be attempted to be added
50 as a part of the URL.
51 -f, --file
53 Force treating arguments as file paths.
54 -P, --pls
56 Force treating arguments as playlist files. This option implies
57 -f.
58 -t, --pattern
60 Force treating arguments as a pattern.
61 -N, --non-recursive
63 Do not add directories recursively.
64 -p, --playlist playlist
66 Add media to playlist instead of the active playlist.
67 -n, --next
69 Add media after the current track.
70 -a, --at position
72 Add media at the given position.
73 -A, --attribute key=value
75 Add media with given key=value attribute. May occur multiple
76 times. Only valid when adding new files to the media library.
77 -o, --order prop[,...]
79 Add media sorted by the given comma-separated list of proper‐
80 ties. If a property is prefixed by -, media are sorted in
81 reverse order on that property.
82 exit
84 Exit the shell-like interface.
86 help [-a] command
88 Show the help on command. This is equivalent to command -h. If
90 command is an alias, show the alias definition. If no command is
91 provided, list all available commands.
92 -a, --alias
94 List available aliases if command is not provided. Otherwise,
95 have no effect.
96 info [pattern | positions...]
98 Display the properties of all media matching pattern or at the
100 given positions. Without argument, display the properties of the
101 current track.
102 jump [-b] pattern|position
104 Jump to the first media matching pattern or to the given position.
106 -b, --backward
108 Jump backward to the first media matching the pattern
109 list [-p name] [pattern | positions...]
111 List the contents of a playlist (the active one by default). If
113 pattern is provided, contents are further filtered and only the
114 matching media are displayed.
115 -p, --playlist
117 List playlist, instead of the active playlist.
118 move [-p playlist] [-n | -a position] pattern | positions...
120 Move entries inside a playlist (the active one by default).
122 -p, --playlist playlist
124 The playlist to act on.
125 -n, --next
127 Move the matching tracks after the current track.
128 -a, --at position
130 Move the matching tracks by an offset or to a position.
131 next [offset]
133 Jump to the next song. If offset is provided, act like jump +off‐
135 set.
136 pause
138 Pause playback.
140 play
142 Start playback.
144 prev [offset]
146 Jump to the previous song. If offset is provided, act like jump
148 -offset.
149 remove [-p playlist] pattern | positions...
151 Remove the matching media from a playlist (the active one by
153 default).
154 -p, --playlist playlist
156 Remove from playlist, instead of the active playlist.
157 current [-r seconds] [-f format]
159 Display playback status, either continuously or once.
161 -r, --refresh seconds
163 Set the delay, in seconds, between each refresh of the current
164 playback metadata. If 0, the metadata is only printed once
165 (default) and the command exit immediately. When in refresh
166 mode, basic control is provided on the active playlist.
167 -f, --format format
169 Set the format string used to display status informations,
170 instead of the one from the configuration file (see FORMAT
171 STRING below).
172 search [-o prop1[,prop2...]] [-l prop1[,prop2...] ] pattern
174 Search and print all media matching pattern.
176 -o, --order prop1[,prop2...]
178 Display search results sorted by the given list of properties.
179 If a property is prefixed by '-', results are sorted in reverse
180 order on that property.
181 -l, --columns prop1[,prop2...]
183 List of properties to use as columns.
184 seek time | offset
186 Seek to a relative or an absolute time in the current track.
188 stop
190 Stop playback.
192 toggle
194 Toggle playback.
196 Playlist Commands
198 playlist clear [playlist]
202 Clear a playlist. By default, clear the active playlist.
204 playlist config [-t type] [-s history] [-u upcoming] [-i coll] [-j
206 playlist] [playlist]
207 Configure a playlist by changing its type, attributes, etc. By
209 default, configure the active playlist.
210 -t, --type type
212 Change the type of the playlist: list, queue, pshuffle.
213 -s, --history size
215 The size of the history of played tracks (for queue, pshuffle).
216 -u, --upcoming upcoming
218 Number of upcoming tracks to maintain (for pshuffle).
219 -i, --input collection
221 Input collection for the playlist (for pshuffle). Default to
222 'All Media'.
223 -j, --jumplist playlist
225 Jump to another playlist when the end of the playlist is
226 reached.
227 playlist create [-p playlist] name
229 Create a new playlist.
231 -p, --playlist playlist
233 Copy the content of the playlist into the new playlist.
234 playlist list [-a]
236 List all playlists.
238 -a, --all
240 Include hidden playlists.
241 playlist remove playlist
243 Remove the given playlist.
245 playlist rename [-f] [-p playlist] newname
247 Rename a playlist. By default, rename the active playlist.
249 -f, --force
251 Force the rename of the playlist, overwrite an existing
252 playlist if needed.
253 -p, --playlist
255 Rename the given playlist.
256 playlist shuffle [playlist]
258 Shuffle a playlist. By default, shuffle the active playlist.
260 playlist sort [-p playlist] [prop] ...
262 Sort a playlist. By default, sort the active playlist. Prefix prop‐
264 erties by '-' for reverse sorting.
265 -p, --playlist
267 Rename the given playlist.
268 playlist switch playlist
270 Change the active playlist.
272 Collection Commands
274 collection config collection [attrname [attrvalue]]
278 Get or set attributes for the given collection. If no attribute
280 name is provided, list all attributes. If only an attribute name
281 is provided, display the value of the attribute. If both attribute
282 name and value are provided, set the new value of the attribute.
283 collection create [-f] [-e] [-c collection] name [pattern]
285 Create a new collection. If pattern is provided, it is used to
287 define the collection. Otherwise, the new collection contains the
288 whole media library.
289 -f, --force
291 Force creating of the collection, overwrite an existing collec‐
292 tion if needed.
293 -c, --collection collection
295 Copy an existing collection to the new one.
296 -e, --empty
298 Initialize an empty collection.
299 collection list
301 List all collections.
303 collection show collection
305 Display a human-readable description of a collection.
307 collection remove collection
309 Remove a collection.
311 collection rename [-f] oldname newname
313 Rename a collection.
315 -f, --force
317 Force renaming of the collection, overwrite an existing collec‐
318 tion if needed.
319 Server Commands
321 server browse URL
325 Browse a URL via the xform plugins available in the daemon.
327 server config [name [value]]
329 Get or set configuration values. If no name or value is provided,
331 list all configuration values. If only a name is provided, display
332 the content of the corresponding configuration value. If both name
333 and a value are provided, set the new content of the configuration
334 value.
335 server import [-N] path
337 Import new files into the media library. By default, directories
339 are imported recursively.
340 -N, --non-recursive
342 Do not import directories recursively.
343 server plugins
345 List the plugins loaded in the server.
347 server property [-i | -s | -D] [-S] mid [name [value]]
349 Get or set properties for a given media. If no name or value is
351 provided, list all properties. If only a name is provided, display
352 the value of the property. If both a name and a value are pro‐
353 vided, set the new value of the property.
354 By default, set operations use source "client/xmms2-cli", while
356 list and display operations use source-preference. Use the
357 --source option to override this behaviour.
358 By default, the value will be used to determine whether it should
360 be saved as a string or an integer. Use the --int or --string flag
361 to override this behaviour.
362 -i, --int
364 Force the value to be treated as integer.
365 -s, --string
367 Force the value to be treated as a string.
368 -D, --delete
370 Delete the selected property.
371 -S, --source
373 Property source.
374 server rehash [pattern]
376 Rehash the media matched by the pattern, or the whole media library
378 if no pattern is provided
379 server remove [pattern]
381 Remove the matching media from the media library.
383 server shutdown
385 Shutdown the server.
387 server stats
389 Display statistics about the server: uptime, version, size of the
391 medialib, etc.
392 server sync
394 Immediately save collections to disk. (Otherwise only performed on
396 shutdown or 10 seconds after last change to collections.)
397 server volume [-c name] [value]
399 Get or set the audio volume (in a range of 0-100). If a value is
401 provided, set the volume to value. Otherwise, display the current
402 volume. By default, the command applies to all audio channels. Use
403 the --channel flag to override this behaviour. Relative changes to
404 the volume are possible by prefixing value by + or -.
405 -c, --channel
407 Get or set the volume only for the named channel.
408
410 Patterns are used to search for songs in the media library, some of
411 these patterns may require escaping (with '\') depending on what shell
412 is used. The properties can be found in the output of xmms2 info.
413 <property>:<string>
415 Match songs whose property matches the string. A ? in the string
417 indicates a single wildcard character, and a * indicates multiple
418 wildcard characters.
419 <property>~<string>
422 Match songs whose property fuzzily matches the string. Equal to
424 matching by <property>:*<string>*.
425 <property><operation><number>
428 The operation can be <, <=, > or >=, the pattern will match songs
430 whose property is a numerical value smaller, smaller or equal, big‐
431 ger, bigger or equal in comparison to the number.
432 +<property>
435 Match songs which has the property.
437 NOT <pattern>
440 Match the complement of the pattern.
442 <pattern> <pattern>
444 <pattern> AND <pattern>
445 Match songs that are matched by both patterns.
447 <pattern> OR <pattern>
450 Match songs that are matched by at least one of the two pattern.
452 ( <pattern> )
455 Match songs matched by the pattern, used for grouping AND and OR
457 matches.
458 <string>
461 Match songs whose artist, title or album match the string.
463 #<number>
466 Match a specific media library id.
468
471 Position patterns are used together with commands that operate on
472 playlist content.
473 M_N
475 Select playlist entries ranging from M positions before the current
477 song, to N positions after. Both M and N may be omitted and will
478 then default to 0.
479 -N
482 Select the song N positions before the current song.
484 +N
487 Select the song N positions after the current song.
489 pos0,pos1,...,posN
492 Select one to many playlist positions.
494
497 Commands that output formatted metadata can be customized with the help
498 of user-defined format strings like the following:
499 ´${artist} - ${title}´
502 When passed metadata the name of the artist and the title will be
504 inserted into the resulting string. In addition to the metadata sup‐
505 plied from the media library the following list of properties are also
506 available:
507 position
510 The current playlist position.
512 playback_status
515 The playback status as a string (Stopped, Playing, Paused,
517 Unknown).
518 playtime
521 The playtime of the currently playing song.
523 duration
526 The duration of the current song, as zero-padded minutes:seconds
528 minutes
531 The minutes part, zero-padded, of the current song duration.
533 seconds
536 The seconds part, zero-padded, of the current song duration.
538
541 A list of command aliases are read from the configuration file in the
542 section [alias] at runtime. The syntax of xmms2 aliases are somewhat
543 similar to bash and other shells. An alias is defined by a list of
544 semi-colon separated commands and arguments. Parameter expansion is
545 supported (see Expansion below).
546 The default configuration includes the following aliases:
548 addpls
550 add -f -P $@
552 clear
554 playlist clear
556 status
558 current -f $1
560 ls
562 list
564 mute
566 server volume 0
568 quit
570 server shutdown
572 repeat
574 seek 0
576 scap
578 stop ; playlist clear ; add $@ ; play
580 Expansion
582 Positional Parameters
583 An alias can use positional parameters, for example:
584 foo = add -f $1 $3
586 foo ctkoz.ogg and slre.ogg
588 Will result in:
590 add -f ctkoz.ogg slre.ogg
592 Special Parameters
594 $@
595 This expands to all parameters passed to the alias.
596
598 All control characters are interpreted as expected, including ANSI
599 escape sequences.
600 AUTO_UNIQUE_COMPLETE
602 Boolean, complete an abbreviation of a command and it's arguments.
603 For example: `serv vol 42' will complete to `server volume 42'.
604 (Note: Abbreviations must be non-ambiguous)
605 CLASSIC_LIST
607 Boolean, format list output similar to the classic cli.
608 CLASSIC_LIST_FORMAT
610 String to format classic list output with.
611 GUESS_PLS
613 Boolean, try to guess if the URL is a playlist and add accordingly.
614 (Not reliable)
615 HISTORY_FILE
617 File to save command history to.
618 PLAYLIST_MARKER
620 String to use to mark the current active entry in the playlist
621 PROMPT
623 String to use as a prompt in INTERACTIVE MODE
624 SERVER_AUTOSTART
626 Boolean, if true xmms2 will attempt to start xmms2d(1) if it's not
627 running already.
628 SHELL_START_MESSAGE
630 Boolean, if true, xmms2 will display a greeting message and basic
631 help when started in INTERACTIVE MODE
632 STATUS_FORMAT
634 String to format status output with.
635
637 $XDG_CACHE_HOME/xmms2/nyxmms2_history
638 Default command history file if HISTORY_FILE is unset.
639 $XDG_CONFIG_HOME/xmms2/clients/nycli.conf
641 The configuration file for xmms2
642
644 XMMS_PATH
645 Override the default connection path.
646 To connect via IPv4
648 tcp://IPv4-Address:port
649 To connect via IPv6
651 tcp://[IPv6-Address]:port
652 To connect via unix socket
654 unix:///path/to/socket
655
657 Please report all bugs at http://bugs.xmms2.org
658
660 Igor Assis, Anders Waldenborg, Anthony Garcia, Sebastien Cevey, and
661 Jonne Lehtinen, Daniel Svensson, Raphaël Bois
662 See the AUTHORS file in the XMMS2 source distribution for more info.
664 The blame for this man page is on Anthony.
666 If you contributed and feel you should be listed here please send me a
668 mail.
669 XMMS2(1)