# Using the client library

The client library can be used as follows:

    >>> from mpd import MPDClient
    >>> client = MPDClient()               # create client object
    >>> client.timeout = 10                # network timeout in seconds (floats allowed), default: None
    >>> client.idletimeout = None          # timeout for fetching the result of the idle command is handled seperately, default: None
    >>> client.connect("localhost", 6600)  # connect to localhost:6600
    >>> print(client.mpd_version)          # print the MPD version
    >>> print(client.find("any", "house")) # print result of the command "find any house"
    >>> client.close()                     # send the close command
    >>> client.disconnect()                # disconnect from the server

A list of supported commands, their arguments (as MPD currently understands them), and the functions used to parse their responses can be found in Commands. See the MPD protocol documentation for more details.

Command lists are also supported using command_list_ok_begin() and command_list_end():

    >>> client.command_list_ok_begin()       # start a command list
    >>> client.update()                      # insert the update command into the list
    >>> client.status()                      # insert the status command into the list
    >>> results = client.command_list_end()  # results will be a list with the results

Commands may also return iterators instead of lists if iterate is set to True:

    client.iterate = True
    for song in client.playlistinfo():
        print song["file"]

Each command have a send_ and a fetch_ variant, which allows to send a MPD command and then fetch the result later. This is useful for the idle command:

    >>> client.send_idle()
    # do something else or use function like select(): http://docs.python.org/howto/sockets.html#non-blocking-sockets
    # ex. select([client], [], []) or with gobject: http://jatreuman.indefero.net/p/python-mpd/page/ExampleIdle/
    >>> events = client.fetch_idle()

Some more complex usage examples can be found here

Some commands support integer ranges as argument. This is done in python-mpd2 by using two element tuple:

    # move the first three songs
    # after the last in the playlist
    >>> client.status()
    ['file: song1.mp3',
     'file: song2.mp3',
     'file: song3.mp3',
     'file: song4.mp3']
    >>> client.move((0,3), 1)
    >>> client.status()
    ['file: song4.mp3'
     'file: song1.mp3',
     'file: song2.mp3',
     'file: song3.mp3',]

Second element can be omitted. MPD will assumes the biggest possible number then (don’t forget the comma!):: NOTE: mpd versions between 0.16.8 and 0.17.3 contains a bug, so omitting doesn’t work.

    >>> client.delete((1,))     # delete all songs, but the first.