Music Player Daemon Community Wiki


525pages on
this wiki
Add New Page
Talk0 Share

page cache from google as site is down

(or check the December 2005 version from

mpcstick: MPD Linux Joystick Client Controller

mpcstick is a simple MPD client. It allows you to easily control MPD via a Linux Joystick device (/dev/input/jsX). When mpcstick is running, it listens for input on a defined device and sends commands to MPD. Because mpcstick runs as a daemon in the background and listens specifically on a joystick device, it needs no input focus, allowing you to control audio playback without interfering with your current task.

mpcstick is customizable: you define your own button mapping for your joystick. The new version supports an optional (but default) GTK configuration program to easily create button to feature mapping for mpd. If you want to use mpcstick on a system without GTK, you can easily compile mpcstick without the GTK configuration interface. However, you will have to manually build your mpcstick XML configuration file (covered in sections below). mpcstick Rewritten: History & Future

The original mpcstick was written in April, 2004. After gaining considerable interest from the mpd community, and the realization that mpcstick could be useful on the Desktop as well as a headless box, mpcstick was rewritten in mid-November, 2004. The rewrite features an encapsulation layer for the Joystick code, a new configuration API and XML format, a more solid core, including a new mapping mechanism and more stable connection code, and most importantly, an optional GTK2 configuration interface that can build and edit the mpcstick configuration file, leaving the end user with no tedious configuration to do.

Though the history is brief, the future is broad. mpcstick will soon support tight integration with gmpc, a graphical GNOME client for mpd. It will have the ability to communicate with gmpc, so you can launch, for instance, the playlist dialog in gmpc through an mpcstick function. The ATI All In Wonder remote control support will be added to the mpcstick rewrite in a future release. Support for this device was added to the old version by Tony Howat. The mpcstick rewrite also makes it much easier to support more than just the Linux Joystick API. Soon more specific device support will be added, allowing you to more easily control mpd. Download

mpcstick is only available in source form (written in C) and is licensed under the GNU General Public License. It has only been tested under Linux, but will probably not work on other UNIX-like systems (*BSD) due to the custom Linux joystick interface dependency. I am not sure how portable the code may be. mpcstick also uses GLib, so it must be installed first. mpcstick is compatible with MPD version 0.11.x.

Note: mpcstick optionally uses GTK+-2.0 >= 2.4. If you configure mpcstick with the GTK configuration interface, make sure GTK+ 2.4 or greater is installed. Otherwise you need only GLib 2.0.

  • mpcstick version 0.11.1-beta4 - (download)
  • mpcstick version 0.11.1-beta3 - (download)
  • mpcstick version 0.11.1-beta2 - (download)


mpcstick is packaged using the standard GNU auto-build system. To install mpcstick, be sure GLib is installed first. Then extract the source tarball, and follow the standard build rules for building from source.

   $ tar zxvf mpcstick-x.xx.x.tar.gz
   $ cd mpcstick-x.xx.x
   $ ./configure
   $ make
   $ su -c "make install"

If you do not have GTK 2.4 or greater installed, you must disable the GTK configuration interface before compiling mpcstick. This will allow you to use mpcstick, but you will have to construct your own configuration file.

   $ ./configure --disable-gtk-config
   $ make
   $ su -c "make install"

About Linux Joystick Support

mpcstick will only work if you have a working joystick device. A 'joystick' is any device that shows up under /dev/input/js*. You need to enable Joystick support (at various levels, depending on your device[s]) in the Linux kernel for your joystick to work. I have only tested my devices (and I have two audio/MIDI gamepads and one USB gamepad, all of which work) under the 2.6 kernel, but they should work fine under 2.4. The main thing is just getting the device to show up and work under /dev/input/js* (can also just be /dev/js*). For instance, my USB gamepad is /dev/input/js1, but my MIDI gamepad is /dev/input/js0. Warning about analog gamepads and joysticks

It is not really advisable to use a device with analog axis support, meaning a device with variable levels of "intensity." If your device isn't calibrated properly, or it's overly sensitive, it may end up sending many events at a time or in queue. If you map an mpd feature to an analog button, you may end up sending many commands to mpd. If you are going to use an analog device, try not to map any features to the analog buttons. You may also have some difficulty with the GTK config program with analog events being fired constantly. Keep clicking the assignment button... over and over. There isn't much I can do about that.

Better support will come in future versions for dealing with analog devices, but for now, try to use a digital device. Command line options

mpcstick supports a few command-line options to control the program. Most important may be the --js-debug option. This option will print the button/axis ID to standard out when a button is pressed on the provided joystick device. This output can then be used to create your button map configuration. Option Description --help prints this help --version shows version information --configure runs the GTK configuration program --config-file <file> specify alternate config file the default is ~/.mpcstick.xml --config-dump print debug output of loaded configuration --js-debug <device_path> print joystick button IDs to screen to make it easier to discover the button mapping of a device. --standalone run mpcstick in terminal (do not fork to daemon) --shutdown-daemon nicely shutdown any mpcstick instance (daemon)

Server/Device Configuration

mpcstick now uses an XML configuration file. By default, it is located at ~/.mpcstick.xml. The configuration needs two main sections: mpd and devices. The mpd section contains information regarding the connection to an mpd server. The following are valid tags for the mpd section:

  • host - the host address of mpd
  • port - the port on which mpd is listening
  • password - the password to use to authenticate to mpd (optional)
  • timeout - server timeout in seconds
  • autoreconnect - whether to automatically reconnect to mpd if connection is lost (yes or no)

Additionally, the mpcstick configuration file needs a devices section filled with device entries. Each device entry is where the keybindings are to be defined for that device. The device entry needs at least a path property with a value of the path of the device, and optionally an active property which is an XML boolean (yes or no value). This property tells mpcstick to use that device.

Inside a device entry there may be any number of keybinding entries. A keybinding entry must have a key property whose value is the ID of a button on the corresponding device (use output from mpcstick --js-debug /dev/input/jsX, where /dev/input/jsX is the path of the device). The value for the keybinding entry is the name of the function to which the key should be mapped.

A device entry may look like this:

   <device path="/dev/input/js0" active="yes">
     <keybinding key="3">toggle_random()</keybinding>

Button Mapping & Functions

Without button mapping or key-binding, mpcstick is useless. Once you figure out the IDs for the buttons on your device, you need to create a keybinding entry in your config file under the device section for the corresponding device. You will need to map the button ID to an mpcstick function. Below is a table of available functions. Function Description previous Jump to previous track next Jump to next track volume_up Turn volume up by defined % volume_down Turn volume down by defined % playpause Play/pause/resume current track stop Stop playback seek_left Seek left in track seek_right Seek right in track close Close MPC

Sample Configuration

mpcstick requires a configuration file for button mapping and server connection settings. It will check by default for the file ~/.mpcstick


Ad blocker interference detected!

Wikia is a free-to-use site that makes money from advertising. We have a modified experience for viewers using ad blockers

Wikia is not accessible if you’ve made further modifications. Remove the custom ad blocker rule(s) and the page will load as expected.