table of contents
XMMS2(1) | General Commands Manual | XMMS2(1) |
NAME¶
xmms2 - The official XMMS2 command line interfaceSYNOPSIS¶
xmms2 [command] [arguments]DESCRIPTION¶
XMMS2 is a redesign of the XMMS (http://legacy.xmms2.org) music player. It features a client-server model, allowing multiple (even simultaneous!) user interfaces, both textual and graphical. All common audio formats are supported using plugins. On top of this, there is a flexible media library to organise your music. xmms2 is the official CLI XMMS2 client.INVOCATION¶
Inline mode¶
If xmms2 is passed a command as an argument, that command will be interpreted and xmms2 will exit after it is finished.Interactive mode¶
xmms2 features a powerful shell-like environment via readline that allows the user to enter commands at a prompt and have the usual cool features such as pathname expansion and line editing.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 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.
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.
POSITION PATTERN¶
Position patterns are used together with commands that operate on playlist content.- M_N
Select playlist entries ranging from M
positions before the current song, to N positions after. Both M
and N may be omitted and will then default to 0.
- -N
Select the song N positions before the
current song.
- +N
Select the song N positions after the
current song.
- pos0,pos1,...,posN
Select one to many playlist positions.
FORMAT STRING¶
Commands that output formatted metadata can be customized with the help of user-defined format strings like the following:- 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.
ALIASES¶
A list of command aliases are read from the configuration file in the section [alias] at runtime. The syntax of xmms2 aliases are somewhat similar to bash and other shells. An alias is defined by a list of semi-colon separated commands and arguments. Parameter expansion is supported (see Expansion below).- The default configuration includes the following aliases:
- addpls
add -f -P $@
- clear
playlist clear
- status
current -f $1
- ls
list
- mute
server volume 0
- quit
server shutdown
- repeat
seek 0
- scap
stop ; playlist clear ; add $@ ; play
Expansion¶
Positional ParametersAn alias can use positional parameters, for
example:
foo = add -f $1 $3
foo ctkoz.ogg and slre.ogg
Will result in:
add -f ctkoz.ogg slre.ogg
Special Parameters
$@
This expands to all parameters passed to the
alias.
CONFIGURATION¶
All control characters are interpreted as expected, including ANSI escape sequences. AUTO_UNIQUE_COMPLETEBoolean, 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.
FILES¶
$XDG_CACHE_HOME/xmms2/nyxmms2_historyDefault command history file if HISTORY_FILE
is unset.
$XDG_CONFIG_HOME/xmms2/clients/nycli.conf
The configuration file for xmms2
ENVIRONMENT¶
XMMS_PATHOverride the default connection path.
- To connect via IPv4
- tcp://IPv4-Address:port
- To connect via IPv6
- tcp://[IPv6-Address]:port
- To connect via unix socket
- unix:///path/to/socket