xmms2 (1) - Linux Manuals
xmms2: offers a simple command-line interface to the XMMS2 daemon
NAME
xmms2 - offers a simple command-line interface to the XMMS2 daemonSYNOPSIS
xmms2 command xmms2 mlib command xmms2 playlist command xmms2 coll commandDESCRIPTION
XMMS2 is a redesign of the XMMS (http://www.xmms.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 organize your music.xmms2 is the official command-line interface client for XMMS2 and acts as a reference implementation for the development of new clients. xmms2 is able to issue commands to control the active playlist and playback as well as commands to control the media library.
The following commands effect the current XMMS2 playlist.
xmms2 includes many commands that allow the user to execute actions on xmms2d.
- Thesecommandsarecurrentlyrecognized:
- add [playlist] url...
- Adds URL(s) to playlist or the active playlist.
- addarg [playlist] url arguments
- Adds an URL to playlist or the active playlist, with arguments.
- addid [playlist] medialib_id...
- Adds song(s) to playlist or the active playlist using its Media Library ID.
- addpls [playlist] url
- Adds a playlist in a file to playlist or the active playlist.
- insert [playlist] pos url
- Adds a URL to playlist or the active playlist at a specific position.
- insertid [playlist] pos medialib_id
- Adds a song to playlist or the active playlist at a specific position using its Media Library ID.
- radd [playlist] directory
- Adds a directory of songs recursively to playlist or the active playlist.
- clear [playlist]
- Clears all entries from playlist or the active playlist.
- shuffle [playlist]
- Places the songs in playlist or the active playlist in a random order.
- sort property
- Sort the active playlist based on metadata from the Media Library. The metadata which is used for the sorting is based on what was given for property. An overview of the media library, and the potential properties, can be found in the MEDIA LIBRARY section of this manual page.
- sort playlist properties
- Sort playlist based on metadata from the Media Library. Separate the properties with a spaces.
- remove [playlist] playlist_position
- Removes a song from playlist or the active playlist at the position given by playlist_position.
- list [playlist]
- Lists the contents of playlist or the active playlist. An explanation of how to change the output format can be found in the FILES section of this manual page.
- play
- Starts playback of the playlist.
- stop
- Stops playback of the playlist.
- toggleplay
- Toggles playback status between play/pause
- pause
- Pauses playback of the playlist.
- next
- Skips to the next song in the playlist.
- prev
- Skips to the previous song in the playlist.
- seek [+ / -]seconds
- Seeks to a specific position in the currently playing song. The way in which seek moves in the file is based on the arguments passed to it. If + is used xmms2 will seek seconds forward in the song. If - is used xmms2 will seek seconds backwards in the song. If merely a number of seconds is given xmms2 will seek to that absolute position in the song.
- jump [+ / -]playlist_position
- Jumps to playlist_position in the playlist or playlist_position forward/backward if + or - is specified.
- move [playlist] playlist_position new_position
- Moves the song at playlist position to the position denoted by new_position in playlist or the active playlist.
- volume channel volume
- Sets the volume of channel to volume.
- volume_list
- Lists the volume for each channel.
- mlib
- Allows for the manipulation of the Media Library. The significance of the sub-commands of mlib can be found in the MEDIA LIBRARY section of this manual page.
- playlist
- Allows for the manipulation of playlists. The significance of the sub-commands of playlist can be found in the PLAYLIST section of this manual page.
- coll
- Allows for the manipulation of collections. The significance of this sub-commands of coll can be found in the COLLECTIONS section of this manual page.
- browse url
- Lists the contents of url in a list of encoded urls.
- status
- Gives a live status of the currently playing song.
- info [id]
- Gives the metadata archived by the Media Library for Media Library id id or the currently playing song.
- current [pattern]
- Gives some summary of the currently playing song's meta data. A pattern can be specified in the form "${album} - ${tracknr}". Please be aware of your shells substitution features.
- config config_key [=] value
- Sets config_key to value on xmms2d(8).
- config_list
- Lists all the configuration values of XMMS2.
- plugin_list
- Prints a list of the plugins being used by XMMS2.
- stats
- Retrieves the uptime and version from XMMS2.
- quit
- Makes xmms2d(8) quit.
- help
- Prints a concise overview of all commands offered by xmms2.
MEDIA LIBRARY
XMMS2 stores metadata about every song in the Media Library. One can retrieve data from the Media Library using the mlib command of xmms2. The Media Library is an SQL database which is created and accessed by use of the sqlite library. xmms2 mlib includes many commands for manipulating and retrieving data from the Media Library.- Thefollowing
- mlib commands are currently recognized:
- add url
- Adds a URL to the Media Library but not to the current playlist. The Media Library also fetches associated metadata for the added song.
- loadall
- Load all songs in the Media Library into the current playlist.
- searchadd pattern
- Searches the Media Library for songs that match pattern criteria and adds them to the current playlist.
- search pattern
- Searches and returns a list of songs in the Media Library that match pattern.
- For example one could execute:
- xmms2 mlib search artist:Dismantled
- The result of which would be that all songs by Dismantled in the Media Library would be listed.
- addpath path
- Adds all songs in directory path into the Media Library.
- rehash
- Force the Media Library to check whether its data is up to date.
- remove id
- Removes a song from the Media Library with the id id.
- setstr id key value [source]
- sets a string Media Library property with key key and value value for song with ID id. Optionally a source can be supplied with the source argument. If no source is defined client/xmms2-cli will be used.
- setint id key value [source]
- Sets a string Media Library property with key key and value value for song with ID id. Optionally a source can be supplied with the source argument. If no source is defined client/xmms2-cli will be used.
- rmprop id key [source]
- Removes properties from the Media Library entry with id and with key key and optionally source source.
- addcover file id
- Add a cover image for id(s) id.
The Media Library allows for any variety of keys (sometimes called properties) to be stored within. There is no set list of available keys but rather the Media Library can store any variety of different values. For this reason it is difficult to give a complete list of available keys but some examples are:
- url
- The path to the song in url
- added
- The time in seconds since UTC 00:00:00, 1 Jan 1970 that the song was added to the Media Library
- mime
- The MIME type of the song in the Media Library
- lmod
- The last time in seconds since UTC 00:00:00, 1 Jan 1970 that the song was modified
- laststarted
- The last time the song was played
- timesplayed
- The number of times the song was played
- duration
- The length of the song in milliseconds
- bitrate
- The bitrate of the song in bps
- album
- The name of the album the song is on
- artist
- The name of the artist that produced the song
- title
- The title of the song
- tracknr
- The track number of the song
- {album, artist, track}_id
- MusicBrainz ID numbers for the song
PLAYLIST
XMMS2 has support for playlists which is tightly coupled with XMMS2's Collections system. Playlist manipulation is accessible with the playlist command of xmms2. xmms2 playlist includes many commands for manipulating and retrieving data about playlists.- Thefollowing
- playlist commands are currently recognized:
- list
- Lists all currently available playlists.
- create [playlistname]
- Create a new playlist named playlistname.
- type [playlistname] [type]
- Sets type of the playlist named playlistname to type type. Descriptions of the available types can be found later in the PLAYLIST section of this manual page.
- load [playlistname]
- Load a playlist specified by playlistname from the Media Library
- remove [playlistname]
- Remove a playlist specified by playlistname from the Media Library
XMMS2 currently supports three types of playlists, each of these playlists has a number of attributes which can be set using the coll attr command described in the COLLECTIONS section of this manual page. The available playlist types are:
- list
- A simple list of medialib ids. The list has one attribute: jumplist which is the name of a playlist to jump to when the list is finished.
- queue
- A static playlist which supports a fixed length playlist where songs are removed as they are played. The queue has two attributes: jumplist which is the name of a playlist to jump to when the queue is finished history which is the number of played entries to keep before beginning to remove them
- pshuffle
- A playlist which picks a configurable number of songs from a collection at random. The pshuffle has three attributes: jumplist which is the name of a playlist to jump to when the pshuffle is finished. A pshuffle playlist only finishes when the collection from which new songs are pulled dries up, for instance when filtering on timesplayed < 1 history which is the number of played entries to keep before beginning to remove them upcoming which is the number of unplayed entries to show in the playlist
COLLECTIONS
XMMS2 includes an extremely powerful method for querying and selecting music from the Media Library called Collections. Some of the features of collections are made accessible via the xmms2 client. xmms2 coll includes many commands for manipulating and retrieving data about Collections.- Thefollowing
- coll commands are currently recognized:
- save [collname] [pattern]
- Save the pattern pattern as a Collection named collname
- rename [oldname] [newname]
- Rename a Collection from oldname to newname.
- list [namespace]
- List all Collections, or if namespace is specified list only collections in the Collections or Playlists namespace.
- query [collname] [order]
- Retrieve information about all media in the Collection named collname ordered by order
- queryadd [collname] [order]
- Add all media from the Collection collname ordered by order to the active playlist
- find [mid] [namespace]
- Find all collections in namespace that include the media referenced by mid
- get [collname]
- Display information about the Collection collname
- remove [collname]
- Remove the collection referenced by collname
- attr [collname] [attr] [val]
- Set or get an attribute of name attr to value val on Collection collname
xmms2 sometimes requires that the namespace of a Collection be specified in collname. This is done by prepending either Playlists/ or Collections/ to the beginning of the Collection name. If not specified the namespace defaults to Collections.
FILES
- $XDG_CONFIG_HOME/xmms2/clients/cli.conf or $HOME/Library/xmms2/clients/cli.conf or $HOME/.config/xmms2/clients/cli.conf
- A configuration file containing basic configuration values for xmms2, including the output format used by the list and status commands.
ENVIRONMENTAL VARIABLES
- XMMS_PATH
- The URL path to xmms2d.
- XDG_CONFIG_HOME
-
The path where the xmms2 configuration files are located
See
IPC SOCKET
in
xmms2d(8)
for details of possible values for this variable
HISTORY
The XMMS2 Project was started by Tobias Rundström and Anders Gustafsson. It is developed with their lead by a small group of contributors from all over the world.AUTHOR
This manual page was written by Alexander Botero-Lowry <alex [at] foxybanana.com>