music.mpd

music.mpd#

Description#

This plugin allows you to interact with an MPD/Mopidy music server.

MPD is a flexible server-side protocol/application for handling music collections and playing music, mostly aimed to manage local libraries.

Mopidy is an evolution of MPD, compatible with the original protocol and with support for multiple music sources through plugins (e.g. Spotify, TuneIn, Soundcloud, local files etc.).

Note

If you use Mopidy, and unless you have quite specific use-cases (like you don’t want to expose the Mopidy HTTP interface, or you have some legacy automation that uses the MPD interface), you should use the platypush.plugins.music.mopidy.MusicMopidyPlugin plugin instead of this. The Mopidy plugin provides a more complete and feature-rich experience, as not all the features of Mopidy are available through the MPD interface, and its API is 100% compatible with this plugin. Also, this plugin operates a synchronous/polling logic because of the limitations of the MPD protocol, while the Mopidy plugin, as it uses the Mopidy Websocket API, can operate in a more efficient way and provide real-time updates.

Note

As of Mopidy 3.0 MPD is an optional interface provided by the mopidy-mpd extension. Make sure that you have the extension installed and enabled on your instance to use this plugin if you want to use it with Mopidy instead of MPD.

Configuration#

music.mpd:
  # [Required]
  # MPD IP/hostname.
  host:   # type=str

  # [Optional]
  # MPD port (default: 6600).
  # port: 6600  # type=int

  # [Optional]
  # Polling interval in seconds. If set, the plugin
  # will poll the MPD server for status updates and trigger change
  # events when required. Default: 20 seconds.
  # poll_interval: 20.0  # type=Optional[float]

  # [Optional]
  # How long we should wait for any running
  # threads/processes to stop before exiting (default: 5 seconds).
  # stop_timeout: 5  # type=Optional[float]

  # [Optional]
  # If set to True then the plugin will not monitor
  # for new events. This is useful if you want to run a plugin in
  # stateless mode and only leverage its actions, without triggering any
  # events. Defaults to False.
  # disable_monitor: False  # type=bool

Dependencies#

pip

pip install python-mpd2

Debian

apt install python3-mpd

Fedora

yum install python3-mpd2

Arch Linux

pacman -S python-mpd2

Triggered events#

Actions#

Module reference#

class platypush.plugins.music.mpd.MusicMpdPlugin(host: str, port: int = 6600, poll_interval: float | None = 20.0, **kwargs)[source]#

Bases: MusicPlugin, RunnablePlugin

This plugin allows you to interact with an MPD/Mopidy music server.

MPD is a flexible server-side protocol/application for handling music collections and playing music, mostly aimed to manage local libraries.

Mopidy is an evolution of MPD, compatible with the original protocol and with support for multiple music sources through plugins (e.g. Spotify, TuneIn, Soundcloud, local files etc.).

Note

If you use Mopidy, and unless you have quite specific use-cases (like you don’t want to expose the Mopidy HTTP interface, or you have some legacy automation that uses the MPD interface), you should use the platypush.plugins.music.mopidy.MusicMopidyPlugin plugin instead of this. The Mopidy plugin provides a more complete and feature-rich experience, as not all the features of Mopidy are available through the MPD interface, and its API is 100% compatible with this plugin. Also, this plugin operates a synchronous/polling logic because of the limitations of the MPD protocol, while the Mopidy plugin, as it uses the Mopidy Websocket API, can operate in a more efficient way and provide real-time updates.

Note

As of Mopidy 3.0 MPD is an optional interface provided by the mopidy-mpd extension. Make sure that you have the extension installed and enabled on your instance to use this plugin if you want to use it with Mopidy instead of MPD.

__init__(host: str, port: int = 6600, poll_interval: float | None = 20.0, **kwargs)[source]#
Parameters:

  • host – MPD IP/hostname.

  • port – MPD port (default: 6600).

  • poll_interval – Polling interval in seconds. If set, the plugin will poll the MPD server for status updates and trigger change events when required. Default: 20 seconds.

add(resource: str, *_, position: int | None = None, **__)[source]#

Add a resource (track, album, artist, folder etc.) to the current playlist.

Parameters:

  • resource – Resource path or URI.

  • position – Position where the track(s) will be inserted (default: end of the playlist).

add_to_playlist(playlist: str, resources: str | Collection[str], **_)[source]#

Add one or multiple resources to a playlist.

Parameters:

  • playlist – Playlist name

  • resources – URI or path of the resource(s) to be added

back()[source]#

Go backward by 15 seconds

browse(uri: str | None = None)[source]#

Browse the items under the specified URI.

Parameters:

uri – URI to browse (default: root directory).

clear(**__)[source]#

Clear the current playlist

consume(value: bool | None = None)[source]#

Set consume mode.

Parameters:

value – If set, set the consume state this value (true/false). Default: None (toggle current state)

current_track(*_, **__)[source]#
Returns:

The currently played track.

Example response:

output = {
    "file": "spotify:track:7CO5ADlDN3DcR2pwlnB14P",
    "time": "255",
    "artist": "Elbow",
    "album": "Little Fictions",
    "title": "Kindling",
    "date": "2017",
    "track": "10",
    "pos": "9",
    "id": "3061",
    "albumartist": "Elbow",
    "x-albumuri": "spotify:album:6q5KhDhf9BZkoob7uAnq19"
}
currentsong()[source]#

Legacy alias for current_track().

delete(positions)[source]#

Delete the playlist item(s) in the specified position(s).

Parameters:

positions (list[int]) – Positions of the tracks to be removed

Returns:

The modified playlist

delete_playlist(playlist: str | Collection[str])[source]#

Permanently remove playlist(s) by name

Parameters:

playlist (str or list[str]) – Name or list of playlist names to remove

find(filter: dict, *args, **kwargs)[source]#

Find in the database/library by filter.

Parameters:

filter – Search filter (e.g. {"artist": "Led Zeppelin", "album": "IV"})

Returns:

list[dict]

findadd(filter: dict, *args, **kwargs)[source]#

Find in the database/library by filter and add to the current playlist.

Parameters:

filter – Search filter (e.g. {"artist": "Led Zeppelin", "album": "IV"})

Returns:

list[dict]

forward()[source]#

Go forward by 15 seconds

get_images(resources: Iterable[str], **__) → Dict[str, str | None]#

Get the images for a list of URIs.

Note

This is an optional action, and it may not be implemented by all plugins. If the plugin doesn’t implement this action, it will return an empty dictionary.

Parameters:

uris – List of URIs.

Returns:

Dictionary in the form {uri: image_url}.

get_playlist(playlist: str, *_, **__)[source]#

Get the tracks in a playlist.

Parameters:

playlist – Name of the playlist

get_playlists(*_, **__)[source]#
Returns:

The playlists available on the server as a list of dicts.

Example response:

output = [
    {
        "playlist": "Rock",
        "last_modified": "2018-06-25T21:28:19Z"
    },
    {
        "playlist": "Jazz",
        "last_modified": "2018-06-24T22:28:29Z"
    },
    {
        # ...
    }
]
get_tracks(*_, **__)[source]#
Returns:

The tracks in the current playlist as a list of dicts.

Example output:

output = [
    {
        "file": "spotify:track:79VtgIoznishPUDWO7Kafu",
        "time": "355",
        "artist": "Elbow",
        "album": "Little Fictions",
        "title": "Trust the Sun",
        "date": "2017",
        "track": "3",
        "pos": "10",
        "id": "3062",
        "albumartist": "Elbow",
        "x-albumuri": "spotify:album:6q5KhDhf9BZkoob7uAnq19"
    },
    {
        "file": "spotify:track:3EzTre0pxmoMYRuhJKMHj6",
        "time": "219",
        "artist": "Elbow",
        "album": "Little Fictions",
        "title": "Gentle Storm",
        "date": "2017",
        "track": "2",
        "pos": "11",
        "id": "3063",
        "albumartist": "Elbow",
        "x-albumuri": "spotify:album:6q5KhDhf9BZkoob7uAnq19"
    },
]
load(playlist, play=True)[source]#

Load and play a playlist by name

Parameters:

  • playlist (str) – Playlist name

  • play (bool) – Start playback after loading the playlist (default: True)

main()[source]#

Implementation of the main loop of the plugin.

move(start: int | None = None, end: int | None = None, position: int | None = None, from_pos: int | None = None, to_pos: int | None = None)[source]#

Move the playlist items from the positions start to end to the new position position.

You can pass either:

  • start, end and position to move a slice of tracks from start to end to the new position position.

  • from_pos and to_pos to move a single track from from_pos to to_pos.

Parameters:

  • start – Start position of the selection.

  • end – End position of the selection.

  • position – New position.

  • from_pos – Alias for start - it only works with one track at the time.

  • to_pos – Alias for position - it only works with one track at the time.

next(*_, **__)[source]#

Play the next track

pause(*_, **__)[source]#

Pause playback

pause_if_playing()[source]#

Pause playback only if it’s playing

play(resource: str | None = None, **__)[source]#

Play a resource by path/URI.

Parameters:

resource (str) – Resource path/URI

play_if_paused()[source]#

Play only if it’s paused (resume)

play_if_paused_or_stopped()[source]#

Play only if it’s paused or stopped

play_or_stop()[source]#

Play or stop (play state toggle)

play_pos(pos: int)[source]#

Play a track in the current playlist by position number.

Parameters:

pos – Position number.

playlist_clear(name: str)[source]#

Clears all the elements from the specified playlist.

Parameters:

name – Playlist name.

playlist_move(playlist: str, from_pos: int, to_pos: int, *_, **__)[source]#

Change the position of a track in the specified playlist.

Parameters:

  • playlist – Playlist name

  • from_pos – Original track position

  • to_pos – New track position

plchanges(version: int)[source]#

Show what has changed on the current playlist since a specified playlist version number.

Parameters:

version – Version number

Returns:

A list of dicts representing the songs being added since the specified version

previous(**__)[source]#

Play the previous track

random(value: bool | None = None)[source]#

Set random mode.

Parameters:

value – If set, set the random state this value (true/false). Default: None (toggle current state).

remove_from_playlist(playlist: str, resources: int | Collection[int], *_, **__)[source]#

Remove one or multiple tracks from a playlist.

Parameters:

  • playlist – Playlist name

  • resources – Position or list of positions to remove

rename_playlist(playlist: str, new_name: str)[source]#

Rename a playlist.

Parameters:

  • playlist – Original playlist name or URI

  • new_name – New playlist name

repeat(value: bool | None = None)[source]#

Set repeat mode.

Parameters:

value – If set, set the repeat state this value (true/false). Default: None (toggle current state)

save(name: str)[source]#

Save the current tracklist to a new playlist with the specified name.

Parameters:

name – Name of the playlist

search(*args, query: str | dict | None = None, filter: dict | None = None, **kwargs)[source]#

Free search by filter.

Parameters:

  • query – Free-text query or search structured filter (e.g. {"artist": "Led Zeppelin", "album": "IV"}).

  • filter – Structured search filter (e.g. {"artist": "Led Zeppelin", "album": "IV"}) - same as query, it’s still here for back-compatibility reasons.

Returns:

list[dict]

searchadd(filter: dict, *args, **kwargs)[source]#

Free search by filter and add the results to the current playlist.

Parameters:

filter – Search filter (e.g. {"artist": "Led Zeppelin", "album": "IV"})

Returns:

list[dict]

searchaddplaylist(name: str)[source]#

Search and add a playlist by (partial or full) name.

Parameters:

name – Playlist name, can be partial.

seek(position: float, **__)[source]#

Seek to the specified position

Parameters:

position – Seek position in seconds, or delta string (e.g. ‘+15’ or ‘-15’) to indicate a seek relative to the current position

set_volume(volume: int, **__)[source]#

Set the volume.

Parameters:

volume – Volume value (range: 0-100).

shuffle()[source]#

Shuffles the current playlist.

single(value: bool | None = None)[source]#

Set single mode.

Parameters:

value – If set, set the consume state this value (true/false). Default: None (toggle current state)

start()#

Start the plugin.

status(*_, **__)[source]#
Returns:

The current state.

Example response:

output = {
    "volume": "9",
    "repeat": "0",
    "random": "0",
    "single": "0",
    "consume": "0",
    "playlist": "52",
    "playlistlength": "14",
    "xfade": "0",
    "state": "play",
    "song": "9",
    "songid": "3061",
    "nextsong": "10",
    "nextsongid": "3062",
    "time": "161:255",
    "elapsed": "161.967",
    "bitrate": "320"
}
stop(*_, **__)[source]#

Stop playback

voldown(step: float | None = None, **kwargs)[source]#

Turn down the volume.

Parameters:

step – Volume down step (default: 5%).

volup(step: float | None = None, **kwargs)[source]#

Turn up the volume.

Parameters:

step – Volume up step (default: 5%).

wait_stop(timeout=None)#

Wait until a stop event is received.