Skip to content

Using the application

Erik Massop edited this page Nov 4, 2017 · 1 revision

Please also view the manual pages - if you have the XMMS2 source they're in doc/xmms2.1 and doc/xmms2d.8. They can also be viewed at


  • By default, a small client - xmms2-et is installed and set up to be launched whenever xmms2d is started. The purpose of this client is to send the developers some information about the plugins and versions of XMMS2 being used out there, so that new releases can be planned based on this testing data. You should know that this program does not send any personally identifiable information - if in doubt, check the source code yourself (src/clients/et/xmms2-et.c). xmms2-et does not affect the operation of the XMMS2 daemon in any significant way - you can safely disable it by removing ~/.config/xmms2/startup.d/ (substitute '~/.config/xmms2' as appropriate for your xmms2 configuration directory).

Quick Start

  1. Start the daemon: xmms2-launcher
  2. Add some music: xmms2 add /home/foo/music/awesome.ogg
  3. Play: xmms2 play

The Daemon

xmms2d can be started by typing 'xmms2d' after installing the application. (To daemonise the process, use xmms2-launcher instead of xmms2d) You can then interact with the daemon using one of many clients

Configuring the daemon

Changing output plugin:

xmms2 server config output.plugin oss-or-alsa-or-whatever-plugin-you-should-use

Making xmms2d listen for requests via TCP:

xmms2 server config core.ipcsocket tcp:// 

and then restart xmms2d. (replace with your IP address as appropriate) xmms2d will then listen on that port for requests from remote clients.

Once you change the value of core.ipcsocket, you need to let your xmms2 clients know about the new IPC path by setting the XMMS_PATH environment variable.

It is possible to get the daemon to listen on multiple sockets by setting core.ipcsocket to


Note that, when using ipv6 and wildcards (address "::"), you might get problems depending on your system. Under Linux, letting a socket listen on "::" also means to listen on ipv4 (unless /proc/sys/net/ipv6/bindv6only is set to 1).

The clients

You can interact with the daemon using the 'xmms2' command-line client, which comes in the source tree, or other clients.

xmms2 client options

The basic CLI (command line interface) xmms2 client can use alternative paths for IPC. Simply set the XMMS_PATH environment variable to the appropriate path and then use the client.

Alternative Unix socket path (using Bash shell):

 XMMS_PATH="unix:///tmp/my-socket" xmms2 list


 export XMMS_PATH="unix:///tmp/my-socket"  xmms2 list

for (t)csh users:

 setenv XMMS_PATH "unix:///tmp/my-socket"  xmms2 list

Example usage of xmms2 client

Add all files in a directory to the medialib (recursively adds files in subdirectories as well):

 xmms2 server import /path/to/music

Add files to the playlist:

 xmms2 add /some/path/*.ogg


 xmms2 play

Query the medialib database (e.g. your favourite band):

 xmms2 search artist:"Kultiration"

Query the medialib database and add the result to your playlist:

 xmms2 add -t artist:"Kultiration"

Note that search is case insensitive and that you can use "*" and "?" as wildcards (* being 0 or more wild characters, ? being 0 or 1 wild character):

 xmms2 search artist:"red hot*"

Will find all artists that begin with "red hot"

 xmms2 search artist:"red?hot"

Will match "redhot" and "red hot".

Listen to a shoutcast stream (assuming curl plugin is installed) using the direct url (ie NOT a playlist file, but the url inside the playlist file, the playlist importing code is currently disabled). If you don't require a proxy, skip the "config" lines:

 xmms2 server config curl.proxyaddress  xmms2 server config curl.useproxy 1  xmms2 add  xmms2 play

Enabling an effect:

 xmms2 server config effect.order.0 some-effect-name  xmms2 server config some-effect-name.enabled 1

Example of enabling replaygain. When enabled, adjusts volume to normalized level when replaygain metadata found in flac, mad, mp3, mp4, musepack, vorbis and wavpack files, inserted by mp3gain, aacgain, vorbisgain, metaflac etc utilities. When metadata is not found no adjustment is done.

 xmms2 server config effect.order.0 replaygain  xmms2 server config replaygain.enabled 1  xmms2 play

Clone this wiki locally
You can’t perform that action at this time.