The backend API is the interface that must be implemented when you create a backend. If you are working on a frontend and need to access the backends, see the mopidy.core — Core API instead.
When Mopidy’s core layer is processing a client request, it routes the request to one or more appropriate backends based on the URIs of the objects the request touches on. The objects’ URIs are compared with the backends’ uri_schemes to select the relevant backends.
An often used pattern when implementing Mopidy backends is to create your own URI scheme which you use for all tracks, playlists, etc. related to your backend. In most cases the Mopidy URI is translated to an actual URI that GStreamer knows how to play right before playback. For example:
If there isn’t an existing URI scheme that fits for your backend’s purpose, you should create your own, and name it after your extension’s ext_name. Care should be taken not to conflict with already in use URI schemes. It is also recommended to design the format such that tracks, playlists and other entities can be distinguished easily.
Backend API
If the backend has problems during initialization it should raise mopidy.exceptions.BackendError with a descriptive error message. This will make Mopidy print the error message and exit so that the user can fix the issue.
Parameters: |
|
---|
Actor proxy to an instance of mopidy.audio.Audio.
Should be passed to the backend constructor as the kwarg audio, which will then set this field.
The library provider. An instance of LibraryProvider, or None if the backend doesn’t provide a library.
The playback provider. An instance of PlaybackProvider, or None if the backend doesn’t provide playback.
The playlists provider. An instance of PlaylistsProvider, or class:None if the backend doesn’t provide playlists.
List of URI schemes this backend can handle.
Parameters: |
|
---|
Swith to provided track.
MAY be reimplemented by subclass.
It is unlikely it makes sense for any backends to override this. For most practical purposes it should be considered an internal call between backends and core that backend authors should not touch.
The default implementation will call translate_uri() which is what you want to implement.
Parameters: | track (mopidy.models.Track) – the track to play |
---|---|
Return type: | True if successful, else False |
Get the current time position in milliseconds.
MAY be reimplemented by subclass.
Return type: | int |
---|
Pause playback.
MAY be reimplemented by subclass.
Return type: | True if successful, else False |
---|
Start playback.
MAY be reimplemented by subclass.
Return type: | True if successful, else False |
---|
Indicate that an URI change is about to happen.
MAY be reimplemented by subclass.
It is extremely unlikely it makes sense for any backends to override this. For most practical purposes it should be considered an internal call between backends and core that backend authors should not touch.
Resume playback at the same time position playback was paused.
MAY be reimplemented by subclass.
Return type: | True if successful, else False |
---|
Seek to a given time position.
MAY be reimplemented by subclass.
Parameters: | time_position (int) – time position in milliseconds |
---|---|
Return type: | True if successful, else False |
Stop playback.
MAY be reimplemented by subclass.
Should not be used for tracking if tracks have been played or when we are done playing them.
Return type: | True if successful, else False |
---|
Convert custom URI scheme to real playable URI.
MAY be reimplemented by subclass.
This is very likely the only thing you need to override as a backend author. Typically this is where you convert any Mopidy specific URI to a real URI and then return it. If you can’t convert the URI just return None.
Parameters: | uri (string) – the URI to translate |
---|---|
Return type: | string or None if the URI could not be translated |
A playlist provider exposes a collection of playlists, methods to create/change/delete playlists in this collection, and lookup of any playlist the backend knows about.
Parameters: | backend (mopidy.backend.Backend instance) – backend the controller is a part of |
---|
Get a list of the currently available playlists.
Returns a list of Ref objects referring to the playlists. In other words, no information about the playlists’ content is given.
Return type: | list of mopidy.models.Ref |
---|
New in version 1.0.
Create a new empty playlist with the given name.
Returns a new playlist with the given name and an URI.
MUST be implemented by subclass.
Parameters: | name (string) – name of the new playlist |
---|---|
Return type: | mopidy.models.Playlist |
Delete playlist identified by the URI.
MUST be implemented by subclass.
Parameters: | uri (string) – URI of the playlist to delete |
---|
Get the items in a playlist specified by uri.
Returns a list of Ref objects referring to the playlist’s items.
If a playlist with the given uri doesn’t exist, it returns None.
Return type: | list of mopidy.models.Ref, or None |
---|
New in version 1.0.
Lookup playlist with given URI in both the set of playlists and in any other playlist source.
Returns the playlists or None if not found.
MUST be implemented by subclass.
Parameters: | uri (string) – playlist URI |
---|---|
Return type: | mopidy.models.Playlist or None |
Save the given playlist.
The playlist must have an uri attribute set. To create a new playlist with an URI, use create().
Returns the saved playlist or None on failure.
MUST be implemented by subclass.
Parameters: | playlist (mopidy.models.Playlist) – the playlist to save |
---|---|
Return type: | mopidy.models.Playlist or None |
Parameters: | backend (mopidy.backend.Backend) – backend the controller is a part of |
---|
See mopidy.core.LibraryController.browse().
If you implement this method, make sure to also set root_directory.
MAY be implemented by subclass.
See mopidy.core.LibraryController.get_distinct().
MAY be implemented by subclass.
Default implementation will simply return an empty set.
Note that backends should always return an empty set for unexpected field types.
See mopidy.core.LibraryController.get_images().
MAY be implemented by subclass.
Default implementation will simply call lookup and try and use the album art for any tracks returned. Most extensions should replace this with something smarter or simply return an empty dictionary.
See mopidy.core.LibraryController.lookup().
MUST be implemented by subclass.
See mopidy.core.LibraryController.refresh().
MAY be implemented by subclass.
mopidy.models.Ref.directory instance with a URI and name set representing the root of this library’s browse tree. URIs must use one of the schemes supported by the backend, and name should be set to a human friendly value.
MUST be set by any class that implements LibraryProvider.browse().
See mopidy.core.LibraryController.search().
MAY be implemented by subclass.
New in version 1.0: The exact param which replaces the old find_exact.
Marker interface for recipients of events sent by the backend actors.
Any Pykka actor that mixes in this class will receive calls to the methods defined here when the corresponding events happen in a backend actor. This interface is used both for looking up what actors to notify of the events, and for providing default implementations for those listeners that are not interested in all events.
Normally, only the Core actor should mix in this class.
See Backend extensions.