Welcome to python-mpd-server’s documentation!

python-mpd-server permits to bind a player to a MPD server.

You can control your player with a MPD client such as Sonata, Gmpc or a command line tool mpc. This module defines a server which manages client requests, parses a request and generates a respond. A MPD command is a class that you can override.

Current supported features are:

  • Playback control (play, stop, next, ...)
  • Manage a playlist (add, move, delete, ...)
  • Store/Load playlists
  • User management via password command

Install It

Clone git repository

git clone git://git.tuxfamily.org/gitroot/pympdserver/python-mpd-server.git python-mpd-server
cd python-mpd-server
python setup.py install --user

You can also browse source code.

Getting Started

Launch a basic mpd server

python examples/mpd_server_example.py

or go http://pympdserver.tuxfamily.org/index.html#how-to-use-it .


Project Page: http://pympdserver.tuxfamily.org/

How to use it

An example of a basic use is available in Basic Example.

python-mpd-server library defines a default server in mpdserver module and some defaults commands in command_skel module.

To launch the server, you just have to create a Mpd object


This simulates a dummy mpd server which works with sonata, mpc and gmpc. To bind an existing player with mpd commmand, you then have to redefine commands. For example, to bind play command with your player

class Play(mpdserver.Command):
    def handle_args(self):yourplayer.play()

Launching python mpd server

Defining Commands

This module permits to define mpd commands. Each command inherits from Command which is a command base class. There are also some specialized subclasses of Command:

MPD songs are represented by classes:

Moreover, you can map your playlist to the mpd playlist by overriding MpdPlaylist. Then when you override this class, a lot of commands are defined (for example Move, MoveId, Delete, etc.).

MPD protocol supports playlist diff (for example command command_skel.PlChanges). This feature is internally management with PlaylistHistory.

Note: ‘command’ and ‘notcommand’ commands seems to not be used by gmpc. Then, we have to implement a lot of commands with dummy respond. However, gmpc use ‘command’ command to allow user to play, pause ...

class command_base.Command(args, playlist, frontend, player)[source]

Command class is the base command class. You can define argument format by setting formatArg. Command argument can be accessed with args dictionnary.

Each command has a playlist attribute which is given by MpdRequestHandler. This playlist must implement MpdPlaylist class and by default, this one is used.

Command contains command arguments definition via Command.formatArg. You can handle them with Command.handle_args(). An argument is :

  • an int
  • a string
  • an optionnal int (OptInt)
  • an optionnal string (OptStr)
classmethod GetCommandName()[source]

MPD command name. Command name is the lower class name. This string is used to parse a client request. You can override this classmethod to define particular commandname.


A dictionnary of received arguments from mpd client. They must be defined in formatArg.


To specify command arguments format. For example,


means command accept a optionnal string argument bound to song attribute name.


Override this method to treat commands arguments.


To treat a command. This class handle_args method and toMpdMsg method.


Override this method to send a specific respond to mpd client.

class command_base.CommandItems(args, playlist, frontend, player)[source]

This is a subclass of Command class. CommandItems is used to send items respond such as command.Status command.


Overwrite this method to send items to mpd client. This method must return a list a tuples (“key”,value).

class command_base.CommandPlaylist(args, playlist, frontend, player)[source]

This class of commands is used on mpd internal playlist.


Overide it to specify a real playlist. Should return a list of dict song informations

class command_base.CommandSongs(args, playlist, frontend, player)[source]

This is a subclass of Command class. Respond songs informations for mpd clients.


Override it to adapt this command. This must return a list of MpdPlaylistSong

class command_base.MpdLibrarySong(filename)[source]

To create a mpd library song. This is actually not used.

class command_base.MpdPlaylist[source]

MpdPlaylist is a list of song. Use it to create a mapping between your player and the fictive mpd server.

Some methods must be implemented, otherwise, NotImplementedError is raised.

To bind a playlist to this class, use overide handlePlaylist method.


Implement it to support delete* commands


This is an internal method to automatically add playlistPosition to songs in playlist.


Implement this method to bind your playlist with mpd playlist. This method should return a list of MpdPlaylistSong.

move(fromPostion, toPosition)[source]

Implement it to support move* commands


This method MUST be implemented. It permits to generate the position from a mpd song id.

class command_base.MpdPlaylistSong(file, songId, playlistPosition=None, title=' ', time=0, album=' ', artist=' ', track=0)[source]

To create a mpd song which is in a playtlist.

MPD use a song id which is unique for all song in playlist and stable over time. This field is automatically generated.

class command_base.OptInt[source]

Represent optionnal integer command argument

class command_base.OptStr[source]

Represent optionnal string command argument

class command_base.PlaylistHistory[source]

Contains all playlist version to generate playlist diff (see plchanges* commands). This class is a singleton and it is used by MpdPlaylist.

addPlaylist(version, playlist)[source]

Add playlist version if not exist in history


Return new songs in current playlist since version


Get playlist from version

Command Squeletons

class command_skel.Delete(args, playlist, frontend, player)[source]

To delete the song at songPosition from current playlist.

class command_skel.ListPlaylistInfo(args, playlist, frontend, player)[source]

List playlist ‘playlistname’ content

class command_skel.Load(args, playlist, frontend, player)[source]

Load a playlist in current playlist. Songs are added to current playlist.

class command_skel.Move(args, playlist, frontend, player)[source]

To move a song at positionFrom to postionTo.

class command_skel.Password(args, playlist, frontend, player)[source]

Set username of connexion.

class command_skel.Pause(args, playlist, frontend, player)[source]

Override handle_pause() and handle_unpause() method


When pause is set


When pause is unset

class command_skel.PlaylistId(args, playlist, frontend, player)[source]

Without song position, list all song in current playlist. With song position argument, get song details.

class command_skel.PlaylistInfo(args, playlist, frontend, player)[source]

Without song position, list all song in current playlist. With song position argument, get song details.

class command_skel.Seek(args, playlist, frontend, player)[source]

Skip to a specified point toSec in a song songPosition on the playlist

class command_skel.Status(args, playlist, frontend, player)[source]

Manage mpd status

helper_status_common(volume=0, repeat=0, random=0, xfade=0)[source]

Status is set to ‘stop’ by default. Use :method:play or :method:pause to set status

helper_status_stop(volume=0, repeat=0, random=0, xfade=0)[source]

Status is set to ‘stop’ by default. Use :method:play or :method:pause to set status

Basic Example

This is a simple example of how to use python-mpd-server.

""" This is a simple howto example."""
import mpdserver

# Define a playid command based on mpdserver.PlayId squeleton
class PlayId(mpdserver.PlayId):
    # This method is called when playid command is sent by a client
    def handle_args(self,songId):print "Play a file with Id '%d'" %songId

# Define a MpdPlaylist based on mpdserver.MpdPlaylist
# This class permits to generate adapted mpd respond on playlist command.
class MpdPlaylist(mpdserver.MpdPlaylist):
    # How to get song position from a song id in your playlist
    def songIdToPosition(self,i):
        for e in self.playlist:
            if e.id==i : return e.playlistPosition
    # Set your playlist. It must be a list a MpdPlaylistSong
    def handlePlaylist(self):
        return self.playlist
    # Move song in your playlist
    def move(self,i,j):

# Create a deamonized mpd server that listen on port 9999
# Register provided outputs command 
# Register your own command implementation
# Set the user defined playlist class

print "Starting a mpd server on port 9999"
print "Type Ctrl+C to exit\n"
if __name__ == "__main__":
        while mpd.wait(1) : pass
    except KeyboardInterrupt:
        print "Stopping mpd server"

Indices and tables