Provided by: xmms2-client-cli_0.8+dfsg-23ubuntu0.1_amd64 bug

NAME

       xmms2 - The official XMMS2 command line interface

SYNOPSIS

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

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 [-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 http://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.

                                                                                         XMMS2(1)