xmms2 (1)

Leading comments

xmms2 - The official XMMS2 command line interface

xmms2.1 - The xmms2 man page

Copyright (C) 2009 Anthony Garcia

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer
   in this position and unchanged.
2. Redistributions in binary form must reproduce the above copyright
   n...

(The comments found at the beginning of the groff file "man1/xmms2.1".)

NAME

xmms2 - The official XMMS2 command line interface

SYNOPSIS

xmms2 [command] [arguments]
xmms2 help [command]

DESCRIPTION

XMMS2 is a redesign of the XMMS (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 [-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.

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:

'${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.

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 Parameters

An 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_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.

FILES

$XDG_CACHE_HOME/xmms2/nyxmms2_history

Default command history file if HISTORY_FILE is unset.

$XDG_CONFIG_HOME/xmms2/clients/nycli.conf

The configuration file for xmms2

ENVIRONMENT

XMMS_PATH

Override 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

BUGS

Please report all bugs at bugs.xmms2.org

AUTHORS

Igor Assis, Anders Waldenborg, Anthony Garcia, Sebastien Cevey, and Jonne Lehtinen, Daniel Svensson, Raphaël Bois

See the AUTHORS file in the XMMS2 source distribution for more info.

The blame for this man page is on Anthony.

If you contributed and feel you should be listed here please send me a mail.