musicpd namespace

Python Music Player Daemon client library

musicpd.VERSION = '0.9.0'

Module version

musicpd.CONNECTION_TIMEOUT = 30

Seconds before a connection attempt times out (overriden by MPD_TIMEOUT env. var.)

musicpd.SOCKET_TIMEOUT = None

Socket timeout in second > 0 (Default is None for no timeout)

musicpd.iterator_wrapper(func)

Decorator handling iterate option

exception musicpd.MPDError

Main musicpd Exception

exception musicpd.ConnectionError

Fatal Connection Error, cannot recover from it.

exception musicpd.ProtocolError

Fatal Protocol Error, cannot recover from it

exception musicpd.CommandError

Malformed command, socket should be fine, can reuse it

class musicpd.MPDClient

MPDClient instance will look for MPD_HOST/MPD_PORT/XDG_RUNTIME_DIR environment variables and set instance attribute host, port and pwd accordingly.

Then musicpd.MPDClient.connect will use host and port as defaults if not provided as args.

Regarding MPD_HOST format to expose password refer this module documentation or MPD client manual mpc (1).

>>> from os import environ
>>> environ['MPD_HOST'] = 'pass@mpdhost'
>>> cli = musicpd.MPDClient()
>>> cli.pwd == environ['MPD_HOST'].split('@')[0]
True
>>> cli.host == environ['MPD_HOST'].split('@')[1]
True
>>> cli.connect() # will use host/port as set in MPD_HOST/MPD_PORT

Note

default host:

• use MPD_HOST environment variable if set, extract password if present,

• else use XDG_RUNTIME_DIR to looks for an existing file in ${XDG_RUNTIME_DIR:-/run/}/mpd/socket

• else set host to localhost

default port:

• use MPD_PORT environment variable is set

• else use 6600

Warning

Instance attribute host/port/pwd

While musicpd.MPDClient.host and musicpd.MPDClient.port keep track of current connection host and port, musicpd.MPDClient.pwd is set once with password extracted from environment variable. Calling MPS’s password method with a new password won’t update musicpd.MPDClient.pwd value.

Moreover, musicpd.MPDClient.pwd is only an helper attribute exposing password extracted from MPD_HOST environment variable, it will not be used as default value for the MPD’s password command.

mpd_timeout

Current connection timeout value, defaults to CONNECTION_TIMEOUT or env. var. MPD_TIMEOUT if provided

mpd_version

Protocol version as exposed by the server as a str

Note

This is the version of the protocol spoken, not the real version of the daemon.

host

host used with the current connection (str)

pwd

password detected in MPD_HOST environment variable (str)

port

port used with the current connection (int, str)

connect(host=None, port=None)

Connects the MPD server

Parameters:

• host (str) – hostname, IP or FQDN (defaults to localhost or socket)

• port (str or int) – port number (defaults to 6600)

If host/port are None the socket uses host/port attributes as defaults. Cf. MPDClient for the logic behind default host/port.

The underlying socket also honors MPD_TIMEOUT environment variable and defaults to musicpd.CONNECTION_TIMEOUT (connect command only).

If you want to have a timeout for each command once you got connected, set its value in MPDClient.socket_timeout (in second) or at module level in musicpd.SOCKET_TIMEOUT.

property socket_timeout

Socket timeout in second (defaults to SOCKET_TIMEOUT). Use None to disable socket timout.

Setter:

Set the socket timeout (integer > 0)

Type:

int or None

disconnect()

Closes the MPD connection. The client closes the actual socket, it does not use the ‘close’ request from MPD protocol (as suggested in documentation).

fileno()

Return the socket’s file descriptor (a small integer). This is useful with select.select.