Backend API¶
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 Core API instead.
URIs and routing of requests to the backend¶
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:
- Spotify already has its own URI scheme (
spotify:track:...
,spotify:playlist:...
, etc.) used throughout their applications, and thus Mopidy-Spotify simply uses the same URI scheme. Playback is handled by pushing raw audio data into a GStreamerappsrc
element. - Mopidy-SoundCloud created it’s own URI scheme, after the model of Spotify,
and use URIs of the following forms:
soundcloud:search
,soundcloud:user-...
,soundcloud:exp-...
, andsoundcloud:set-...
. Playback is handled by converting the customsoundcloud:..
URIs tohttp://
URIs immediately before they are passed on to GStreamer for playback. - Mopidy differentiates between
file://...
URIs handled by Mopidy-Stream andlocal:...
URIs handled by Mopidy-Local. Mopidy-Stream can playfile://...
URIs pointing to tracks and playlists located anywhere on your system, but it doesn’t know a thing about the object before you play it. On the other hand, Mopidy-Local scans a predefinedlocal/media_dir
to build a meta data library of all known tracks. It is thus limited to playing tracks residing in the media library, but can provide additional features like directory browsing and search. In other words, we have two different ways of playing local music, handled by two different backends, and have thus created two different URI schemes to separate their handling. Thelocal:...
URIs are converted tofile://...
URIs immediately before they are passed on to GStreamer for playback.
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 class¶
-
class
mopidy.backend.
Backend
[source]¶ -
audio
= None¶ 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.
-
library
= None¶ The library provider. An instance of
LibraryProvider
, orNone
if the backend doesn’t provide a library.
-
playback
= None¶ The playback provider. An instance of
PlaybackProvider
, orNone
if the backend doesn’t provide playback.
-
playlists
= None¶ The playlists provider. An instance of
PlaylistsProvider
, or class:None if the backend doesn’t provide playlists.
-
uri_schemes
= []¶ List of URI schemes this backend can handle.
-
Playback provider¶
-
class
mopidy.backend.
PlaybackProvider
(audio, backend)[source]¶ Parameters: - audio (actor proxy to an instance of
mopidy.audio.Audio
) – the audio actor - backend (
mopidy.backend.Backend
) – the backend
-
change_track
(track)[source]¶ Swith to provided track.
MAY be reimplemented by subclass.
Parameters: track ( mopidy.models.Track
) – the track to playReturn type: True
if successful, elseFalse
-
get_time_position
()[source]¶ Get the current time position in milliseconds.
MAY be reimplemented by subclass.
Return type: int
-
pause
()[source]¶ Pause playback.
MAY be reimplemented by subclass.
Return type: True
if successful, elseFalse
-
play
(track)[source]¶ Play given track.
MAY be reimplemented by subclass.
Parameters: track ( mopidy.models.Track
) – the track to playReturn type: True
if successful, elseFalse
-
resume
()[source]¶ Resume playback at the same time position playback was paused.
MAY be reimplemented by subclass.
Return type: True
if successful, elseFalse
- audio (actor proxy to an instance of
Playlists provider¶
-
class
mopidy.backend.
PlaylistsProvider
(backend)[source]¶ Parameters: backend ( mopidy.backend.Backend
instance) – backend the controller is a part of-
create
(name)[source]¶ See
mopidy.core.PlaylistsController.create()
.MUST be implemented by subclass.
-
delete
(uri)[source]¶ See
mopidy.core.PlaylistsController.delete()
.MUST be implemented by subclass.
-
lookup
(uri)[source]¶ See
mopidy.core.PlaylistsController.lookup()
.MUST be implemented by subclass.
-
playlists
¶ Currently available playlists.
Read/write. List of
mopidy.models.Playlist
.
-
refresh
()[source]¶ See
mopidy.core.PlaylistsController.refresh()
.MUST be implemented by subclass.
-
save
(playlist)[source]¶ See
mopidy.core.PlaylistsController.save()
.MUST be implemented by subclass.
-
Library provider¶
-
class
mopidy.backend.
LibraryProvider
(backend)[source]¶ Parameters: backend ( mopidy.backend.Backend
) – backend the controller is a part of-
browse
(path)[source]¶ See
mopidy.core.LibraryController.browse()
.If you implement this method, make sure to also set
root_directory_name
.MAY be implemented by subclass.
-
find_exact
(query=None, uris=None)[source]¶ See
mopidy.core.LibraryController.find_exact()
.MAY be implemented by subclass.
-
lookup
(uri)[source]¶ See
mopidy.core.LibraryController.lookup()
.MUST be implemented by subclass.
-
refresh
(uri=None)[source]¶ See
mopidy.core.LibraryController.refresh()
.MAY be implemented by subclass.
-
root_directory
= None¶ 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 :meth:`LibraryProvider.browse`.
-
search
(query=None, uris=None)[source]¶ See
mopidy.core.LibraryController.search()
.MAY be implemented by subclass.
-
Backend listener¶
-
class
mopidy.backend.
BackendListener
[source]¶ 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 the core 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.