Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
XMMS2(1)		    General Commands Manual		      XMMS2(1)

       xmms2 - The official XMMS2 command line interface

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

       XMMS2 is	a redesign of the XMMS ( music player.
       It features a client-server model, allowing multiple  (even  simultane-
       ous!)  user  interfaces,	 both  textual and graphical. All common audio
       formats are supported using plugins. On top of this, there is a	flexi-
       ble media library to organise your music.

       xmms2 is	the official CLI XMMS2 client.

   Inline mode
       If  xmms2  is passed a command as an argument, that command will	be in-
       terpreted and xmms2 will	exit after it is finished.

   Interactive mode
       xmms2 features a	powerful shell-like environment	via readline that  al-
       lows  the  user	to  enter commands at a	prompt and have	the usual cool
       features	such as	pathname expansion and line editing.

       All commands accept the option -h/--help	which displays	the  command's

       pattern refers to a collection definition. (See PATTERN below.)

       position	 is  a pattern to match	playlist positions. (See POSITION PAT-
       TERN 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 con-
	   tain	* 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

	   -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  proper-
	       ties.  If  a property is	prefixed by -, media are sorted	in re-
	       verse order on that property.


	   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 +off-


	   Pause playback.


	   Start playback.

       prev [offset]

	   Jump	to the previous	song. If offset	is  provided,  act  like  jump

       remove [-p playlist] pattern | positions...

	   Remove  the	matching  media	from a playlist	(the active one	by de-

	   -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 informations, in-
	       stead of	the one	from the configuration file (see FORMAT	STRING

       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	playback.


	   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 de-
	   fault, 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

       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 prop-
	   erties 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 de-
	   fine	 the  collection.   Otherwise, the new collection contains the
	   whole media library.

	   -f, --force
	       Force creating of the collection, overwrite an existing collec-
	       tion 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 collec-
	       tion 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

       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 pro-
	   vided, 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.

       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.


	   Match  songs	 whose	property matches the string. A ? in the	string
	   indicates a single wildcard character, and a	*  indicates  multiple
	   wildcard characters.


	   Match  songs	 whose	property  fuzzily matches the string. Equal to
	   matching by <property>:*<string>*.


	   The operation can be	<, <=, > or >=,	the pattern will  match	 songs
	   whose property is a numerical value smaller,	smaller	or equal, big-
	   ger,	bigger or equal	in comparison to the number.


	   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


	   Match songs whose artist, title or album match the string.


	   Match a specific media library id.

       Position	 patterns  are	used  together	with  commands that operate on
       playlist	content.


	   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.


	   Select the song N positions before the current song.


	   Select the song N positions after the current song.


	   Select one to many playlist positions.

       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 in-
       serted into the resulting string. In addition to	the metadata  supplied
       from the	media library the following list of properties are also	avail-


	   The current playlist	position.


	   The playback	status as a  string  (Stopped,	Playing,  Paused,  Un-


	   The playtime	of the currently playing song.


	   The duration	of the current song, as	zero-padded minutes:seconds


	   The minutes part, zero-padded, of the current song duration.


	   The seconds part, zero-padded, of the current song duration.

       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:


	   add -f -P $@


	   playlist clear


	   current -f $1




	   server volume 0


	   server shutdown


	   seek	0


	   stop	; playlist clear ; add $@ ; play

       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.

       All  control characters are interpreted as expected, including ANSI es-
       cape sequences.

	   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)

	   Boolean, format list	output similar to the classic cli.

	   String to format classic list output	with.

	   Boolean, try	to guess if the	URL is a playlist and add accordingly.
	   (Not	reliable)

	   File	to save	command	history	to.

	   String to use to mark the current active entry in the playlist

	   String to use as a prompt in	INTERACTIVE MODE

	   Boolean,  if	true xmms2 will	attempt	to start xmms2d(1) if it's not
	   running already.

	   Boolean, if true, xmms2 will	display	a greeting message  and	 basic
	   help	when started in	INTERACTIVE MODE

	   String to format status output with.

	   Default command history file	if HISTORY_FILE	is unset.

	   The configuration file for xmms2

	   Override the	default	connection path.

	   To connect via IPv4

	   To connect via IPv6

	   To connect via unix socket

       Please report all bugs at

       Igor  Assis,  Anders  Waldenborg,  Anthony Garcia, Sebastien Cevey, and
       Jonne Lehtinen, Daniel Svensson,	RaphaA<<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



Want to link to this manual page? Use this URL:

home | help