COMMANDS¶
All commands accept the option -h/--help which
displays the command's help.
pattern refers to a collection definition. (See
PATTERN below.)
position is a pattern to match playlist positions. (See
POSITION PATTERN below.)
General Commands¶
add [ -f [-N] [-P] [-A
key=value]... ] [-p playlist] [-n | -a
position] [-o prop[,...]] arguments...
add [-p playlist] [-n | -a position]
[-o prop[,...]] pattern...
Add media to a playlist. It will attempt to guess whether
arguments constitute a pattern or represent file paths. This
behaviour can be overridden by forcing the type with -f and -t.
If file paths contain * or ? characters, it will attempt to expand them.
Failing to find a match the * and ? characters will be attempted to be added
as a part of the URL.
-f, --file
Force treating arguments as file paths.
-P, --pls
Force treating arguments as playlist files. This
option implies -f.
-t, --pattern
Force treating arguments as a pattern.
-N, --non-recursive
Do not add directories recursively.
-p, --playlist playlist
Add media to playlist instead of the active
playlist.
-n, --next
Add media after the current track.
-a, --at position
Add media at the given position.
-A, --attribute key=value
Add media with given key=value attribute. May occur
multiple times. Only valid when adding new files to the media library.
-o, --order prop[,...]
Add media sorted by the given comma-separated list of
properties. If a property is prefixed by -, media are sorted in reverse order
on that property.
- exit
Exit the shell-like interface.
- help [-a]
command
Show the help on command. This is equivalent to
command -h. If command is an alias, show the alias definition.
If no command is provided, list all available commands.
-a, --alias
List available aliases if command is not provided.
Otherwise, have no effect.
- info [pattern |
positions...]
Display the properties of all media matching
pattern or at the given positions. Without argument, display the
properties of the current track.
- jump [-b]
pattern|position
Jump to the first media matching pattern or to the
given position.
-b, --backward
Jump backward to the first media matching the
pattern
- list [-p
name] [pattern | positions...]
List the contents of a playlist (the active one by
default). If pattern is provided, contents are further filtered and
only the matching media are displayed.
-p, --playlist
List playlist, instead of the active
playlist.
- move [-p
playlist] [-n | -a position] pattern |
positions...
Move entries inside a playlist (the active one by
default).
-p, --playlist playlist
The playlist to act on.
-n, --next
Move the matching tracks after the current track.
-a, --at position
Move the matching tracks by an offset or to a
position.
- next
[offset]
Jump to the next song. If offset is provided, act
like jump +offset.
- pause
Pause playback.
- play
Start playback.
- prev
[offset]
Jump to the previous song. If offset is provided,
act like jump -offset.
- remove [-p
playlist] pattern | positions...
Remove the matching media from a playlist (the active one
by default).
-p, --playlist playlist
Remove from playlist, instead of the active
playlist.
- current
[-r seconds] [-f format]
Display playback status, either continuously or
once.
-r, --refresh seconds
Set the delay, in seconds, between each refresh of the
current playback metadata. If 0, the metadata is only printed once (default)
and the command exit immediately. When in refresh mode, basic control is
provided on the active playlist.
-f, --format format
Set the format string used to display status information,
instead of the one from the configuration file (see FORMAT STRING
below).
- search [-o
prop1[,prop2...]] [-l prop1[,prop2...] ]
pattern
Search and print all media matching pattern.
-o, --order
prop1[,prop2...]
Display search results sorted by the given list of
properties. If a property is prefixed by '-', results are sorted in reverse
order on that property.
-l, --columns
prop1[,prop2...]
List of properties to use as columns.
- seek time |
offset
Seek to a relative or an absolute time in the current
track.
- stop
Stop playback.
- toggle
Toggle playback.
Playlist Commands¶
- playlist clear
[playlist]
Clear a playlist. By default, clear the active
playlist.
- playlist
config [-t type] [-s history] [-u
upcoming] [-i coll] [-j playlist]
[playlist]
Configure a playlist by changing its type, attributes,
etc. By default, configure the active playlist.
-t, --type type
Change the type of the playlist: list, queue,
pshuffle.
-s, --history size
The size of the history of played tracks (for
queue, pshuffle).
-u, --upcoming upcoming
Number of upcoming tracks to maintain (for
pshuffle).
-i, --input collection
Input collection for the playlist (for pshuffle).
Default to 'All Media'.
-j, --jumplist playlist
Jump to another playlist when the end of the
playlist is reached.
- playlist
create [-p playlist] name
Create a new playlist.
-p, --playlist playlist
Copy the content of the playlist into the new
playlist.
- playlist
list [-a]
List all playlists.
-a, --all
Include hidden playlists.
- playlist
remove playlist
Remove the given playlist.
- playlist
rename [-f] [-p playlist] newname
Rename a playlist. By default, rename the active
playlist.
-f, --force
Force the rename of the playlist, overwrite an existing
playlist if needed.
-p, --playlist
Rename the given playlist.
- playlist
shuffle [playlist]
Shuffle a playlist. By default, shuffle the active
playlist.
- playlist
sort [-p playlist] [prop] ...
Sort a playlist. By default, sort the active playlist.
Prefix properties by '-' for reverse sorting.
-p, --playlist
Rename the given playlist.
- playlist
switch playlist
Change the active playlist.
Collection Commands¶
- collection
config collection [attrname [attrvalue]]
Get or set attributes for the given collection. If no
attribute name is provided, list all attributes. If only an attribute name is
provided, display the value of the attribute. If both attribute name and value
are provided, set the new value of the attribute.
- collection
create [-f] [-e] [-c collection] name
[pattern]
Create a new collection. If pattern is provided, it is
used to define the collection. Otherwise, the new collection contains the
whole media library.
-f, --force
Force creating of the collection, overwrite an existing
collection if needed.
-c, --collection collection
Copy an existing collection to the new one.
-e, --empty
Initialize an empty collection.
- collection
list
List all collections.
- collection
show collection
Display a human-readable description of a
collection.
- collection
remove collection
Remove a collection.
- collection
rename [-f] oldname newname
Rename a collection.
-f, --force
Force renaming of the collection, overwrite an existing
collection if needed.
Server Commands¶
- server browse
URL
Browse a URL via the xform plugins available in the
daemon.
- server config
[name [value]]
Get or set configuration values. If no name or value is
provided, list all configuration values. If only a name is provided, display
the content of the corresponding configuration value. If both name and a value
are provided, set the new content of the configuration value.
- server import
[-N] path
Import new files into the media library. By default,
directories are imported recursively.
-N, --non-recursive
Do not import directories recursively.
- server
plugins
List the plugins loaded in the server.
- server property
[-i | -s | -D] [-S] mid [name
[value]]
Get or set properties for a given media. If no name or
value is provided, list all properties. If only a name is provided, display
the value of the property. If both a name and a value are provided, set the
new value of the property.
By default, set operations use source
"client/xmms2-cli", while list and display operations use
source-preference. Use the --source option to override this
behaviour.
By default, the value will be used to determine whether it should
be saved as a string or an integer. Use the --int or --string
flag to override this behaviour.
-i, --int
Force the value to be treated as integer.
-s, --string
Force the value to be treated as a string.
-D, --delete
Delete the selected property.
-S, --source
Property source.
- server rehash
[pattern]
Rehash the media matched by the pattern, or the whole
media library if no pattern is provided
- server remove
[pattern]
Remove the matching media from the media library.
- server
shutdown
Shutdown the server.
- server
stats
Display statistics about the server: uptime, version,
size of the medialib, etc.
- server
sync
Immediately save collections to disk. (Otherwise only
performed on shutdown or 10 seconds after last change to collections.)
- server volume
[-c name] [value]
Get or set the audio volume (in a range of 0-100). If a
value is provided, set the volume to value. Otherwise, display the
current volume. By default, the command applies to all audio channels. Use the
--channel flag to override this behaviour. Relative changes to the
volume are possible by prefixing value by + or -.
-c, --channel
Get or set the volume only for the named channel.
PATTERN¶
Patterns are used to search for songs in the media library, some
of these patterns may require escaping (with '\') depending on what shell is
used. The properties can be found in the output of xmms2 info.
- <property>:<string>
Match songs whose property matches the string. A ?
in the string indicates a single wildcard character, and a * indicates
multiple wildcard characters.
- <property>~<string>
Match songs whose property fuzzily matches the string.
Equal to matching by <property>:*<string>*.
- <property><operation><number>
The operation can be <, <=,
> or >=, the pattern will match songs whose property is a
numerical value smaller, smaller or equal, bigger, bigger or equal in
comparison to the number.
- +<property>
Match songs which has the property.
- NOT
<pattern>
Match the complement of the pattern.
<pattern> <pattern>
<pattern> AND <pattern>
Match songs that are matched by both patterns.
- <pattern> OR <pattern>
Match songs that are matched by at least one of the two
pattern.
- ( <pattern> )
Match songs matched by the pattern, used for grouping AND
and OR matches.
- <string>
Match songs whose artist, title or album match the
string.
- #<number>
Match a specific media library id.
Commands that output formatted metadata can be customized with the
help of user-defined format strings like the following:
´${artist} - ${title}´
When passed metadata the name of the artist and the title will be
inserted into the resulting string. In addition to the metadata supplied
from the media library the following list of properties are also
available:
- position
The current playlist position.
- playback_status
The playback status as a string (Stopped, Playing,
Paused, Unknown).
- playtime
The playtime of the currently playing song.
- duration
The duration of the current song, as zero-padded
minutes:seconds
- minutes
The minutes part, zero-padded, of the current song
duration.
- seconds
The seconds part, zero-padded, of the current song
duration.
CONFIGURATION¶
All control characters are interpreted as expected, including ANSI
escape sequences.
AUTO_UNIQUE_COMPLETE
Boolean, complete an abbreviation of a command and it's
arguments. For example: `serv vol 42' will complete to `server volume 42'.
(Note: Abbreviations must be non-ambiguous)
CLASSIC_LIST
Boolean, format list output similar to the classic
cli.
CLASSIC_LIST_FORMAT
String to format classic list output with.
GUESS_PLS
Boolean, try to guess if the URL is a playlist and add
accordingly. (Not reliable)
HISTORY_FILE
File to save command history to.
PLAYLIST_MARKER
String to use to mark the current active entry in the
playlist
PROMPT
String to use as a prompt in INTERACTIVE
MODE
SERVER_AUTOSTART
Boolean, if true xmms2 will attempt to start
xmms2d(1) if it's not running already.
SHELL_START_MESSAGE
Boolean, if true, xmms2 will display a greeting
message and basic help when started in INTERACTIVE MODE
STATUS_FORMAT
String to format status output with.
