musicpd namespace


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

musicpd.SOCKET_TIMEOUT = None

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

class musicpd.MPDClient[source]

MPDClient instance will look for MPD_HOST/MPD_PORT/XDG_RUNTIME_DIR environment variables and set instance attribute host, port and pwd accordingly. Regarding MPD_HOST format to expose password refer MPD client manual mpc (1).

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

Cf. musicpd.MPDClient.connect for details.

>>> from os import environ
>>> environ['MPD_HOST'] = 'pass@mpdhost'
>>> cli = musicpd.MPDClient()
>>> cli.pwd == environ['MPD_HOST'].split('@')[0]
>>> == environ['MPD_HOST'].split('@')[1]
>>> cli.connect() # will use host/port as set in MPD_HOST/MPD_PORT
  • host (str) – host used with the current connection

  • port (str,int) – port used with the current connection

  • pwd (str) – password detected in MPD_HOST environment variable


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 musicpd.MPDClient().password() 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 password() method


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

connect(host=None, port=None)[source]

Connects the MPD server

  • host (str) – hostname, IP or FQDN (defaults to localhost or socket, see below for details)

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

The connect method honors MPD_HOST/MPD_PORT environment variables.

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.


Default host/port

If host evaluate to False
  • use MPD_HOST environment variable if set, extract password if present,

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

  • else set host to localhost

If port evaluate to False
  • if MPD_PORT environment variable is set, use it for port

  • else use 6600

property socket_timeout

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


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


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