1 Using the client library
2 =========================
7 The client library can be used as follows:
11 client = musicpd.MPDClient() # create client object
12 client.connect() # use MPD_HOST/MPD_PORT if set else
13 # test ${XDG_RUNTIME_DIR}/mpd/socket for existence
14 # fallback to localhost:6600
15 # connect support host/port argument as well
16 print(client.mpd_version) # print the mpd protocol version
17 print(client.cmd('foo', 42)) # print result of the request "cmd foo 42"
18 # (nb. for actual command, see link to the protocol below)
19 client.disconnect() # disconnect from the server
21 In the example above `cmd` in not an actual MPD command, for a list of
22 supported commands, their arguments (as MPD currently understands
23 them), and the functions used to parse their responses see :ref:`commands`.
25 See the `MPD protocol documentation`_ for more details.
30 The client honors the following environment variables:
32 * ``MPD_HOST`` MPD host (:abbr:`FQDN (fully qualified domain name)`, socket path or abstract socket) and password.
34 | To define a password set MPD_HOST to "`password@host`" (password only "`password@`")
35 | For abstract socket use "@" as prefix : "`@socket`" and then with a password "`pass@@socket`"
36 | Regular unix socket are set with an absolute path: "`/run/mpd/socket`"
37 * ``MPD_PORT`` MPD port, relevant for TCP socket only, ie with :abbr:`FQDN (fully qualified domain name)` defined host
38 * ``MPD_TIMEOUT`` timeout for connecting to MPD and for waiting for MPD’s response in seconds
39 * ``XDG_RUNTIME_DIR`` path to look for potential socket: ``${XDG_RUNTIME_DIR}/mpd/socket``
44 * If ``MPD_HOST`` is not set, then look for a socket in ``${XDG_RUNTIME_DIR}/mpd/socket``
45 * If there is no socket use ``localhost``
46 * If ``MPD_PORT`` is not set, then use ``6600``
47 * If ``MPD_TIMEOUT`` is not set, then uses :py:obj:`musicpd.CONNECTION_TIMEOUT`
52 Command lists are also supported using `command_list_ok_begin()` and
53 `command_list_end()` :
55 .. code-block:: python
57 client.command_list_ok_begin() # start a command list
58 client.update() # insert the update command into the list
59 client.status() # insert the status command into the list
60 results = client.command_list_end() # results will be a list with the results
65 Provide a 2-tuple as argument for command supporting ranges (cf. `MPD protocol documentation`_ for more details).
66 Possible ranges are: "START:END", "START:" and ":" :
68 .. code-block:: python
70 # An intelligent clear
71 # clears played track in the queue, currentsong included
72 pos = client.currentsong().get('pos', 0)
73 # the 2-tuple range object accepts str, no need to convert to int
74 client.delete((0, pos))
75 # missing end interpreted as highest value possible, pay attention still need a tuple.
76 client.delete((pos,)) # purge queue from current to the end
78 A notable case is the `rangeid` command allowing an empty range specified
79 as a single colon as argument (i.e. sending just ":"):
81 .. code-block:: python
83 # sending "rangeid :" to clear the range, play everything
84 client.rangeid(()) # send an empty tuple
86 Empty start in range (i.e. ":END") are not possible and will raise a CommandError.
91 Commands may also return iterators instead of lists if `iterate` is set to
94 .. code-block:: python
97 for song in client.playlistinfo():
100 Idle prefixed commands
101 ----------------------
103 Each command have a *send\_<CMD>* and a *fetch\_<CMD>* variant, which allows to
104 send a MPD command and then fetch the result later.
105 This is useful for the idle command:
107 .. code-block:: python
109 >>> client.send_idle()
110 # do something else or use function like select()
111 # http://docs.python.org/howto/sockets.html#non-blocking-sockets
112 # ex. select([client], [], [])
113 >>> events = client.fetch_idle()
115 # more complex use for example, with glib/gobject:
116 >>> def callback(source, condition):
117 >>> changes = client.fetch_idle()
119 >>> return False # removes the IO watcher
121 >>> client.send_idle()
122 >>> gobject.io_add_watch(client, gobject.IO_IN, callback)
123 >>> gobject.MainLoop().run()
125 Fetching binary content (cover art)
126 -----------------------------------
128 Fetching album covers is possible with albumart, here is an example:
130 .. code-block:: python
132 >>> cli = musicpd.MPDClient()
134 >>> track = "Steve Reich/1978-Music for 18 Musicians"
135 >>> aart = cli.albumart(track, 0)
136 >>> received = int(aart.get('binary'))
137 >>> size = int(aart.get('size'))
138 >>> with open('/tmp/cover', 'wb') as cover:
139 >>> # aart = {'size': 42, 'binary': 2051, data: bytes(...)}
140 >>> cover.write(aart.get('data'))
141 >>> while received < size:
142 >>> aart = cli.albumart(track, received)
143 >>> cover.write(aart.get('data'))
144 >>> received += int(aart.get('binary'))
145 >>> if received != size:
146 >>> print('something went wrong', file=sys.stderr)
149 A `CommandError` is raised if the album does not expose a cover.
151 You can also use `readpicture` command to fetch embedded picture:
153 .. code-block:: python
155 >>> cli = musicpd.MPDClient()
157 >>> track = 'muse/Amon Tobin/2011-ISAM/01-Amon Tobin - Journeyman.mp3'
158 >>> rpict = cli.readpicture(track, 0)
160 >>> print('No embedded picture found', file=sys.stderr)
162 >>> size = int(rpict['size'])
163 >>> done = int(rpict['binary'])
164 >>> with open('/tmp/cover', 'wb') as cover:
165 >>> cover.write(rpict['data'])
166 >>> while size > done:
167 >>> rpict = cli.readpicture(track, done)
168 >>> done += int(rpict['binary'])
169 >>> print(f'writing {rpict["binary"]}, done {100*done/size:03.0f}%')
170 >>> cover.write(rpict['data'])
173 Refer to `MPD protocol documentation`_ for the meaning of `binary`, `size` and `data`.
175 .. _MPD protocol documentation: http://www.musicpd.org/doc/protocol/