diff --git a/docs/api/backends.rst b/docs/api/backends.rst index 0db463f5..c59b5a30 100644 --- a/docs/api/backends.rst +++ b/docs/api/backends.rst @@ -16,6 +16,9 @@ The backend and its controllers Backend API =========== +.. automodule:: mopidy.backends + :synopsis: Backend interface. + .. note:: Currently this only documents the API that is available for use by @@ -26,8 +29,54 @@ Backend API generally just implement or override a few of these methods yourself to create a new backend with a complete feature set. -.. automodule:: mopidy.backends - :synopsis: Backend interface. +.. autoclass:: mopidy.backends.BaseBackend + :members: + :undoc-members: + + +Playback controller +------------------- + +Manages playback, with actions like play, pause, stop, next, previous, and +seek. + +.. autoclass:: mopidy.backends.BasePlaybackController + :members: + :undoc-members: + + +Mixer controller +---------------- + +Manages volume. See :class:`mopidy.mixers.BaseMixer`. + + +Current playlist controller +--------------------------- + +Manages everything related to the currently loaded playlist. + +.. autoclass:: mopidy.backends.BaseCurrentPlaylistController + :members: + :undoc-members: + + +Stored playlists controller +--------------------------- + +Manages stored playlist. + +.. autoclass:: mopidy.backends.BaseStoredPlaylistsController + :members: + :undoc-members: + + +Library controller +------------------ + +Manages the music library, e.g. searching for tracks to be added to a playlist. + +.. autoclass:: mopidy.backends.BaseLibraryController :members: :undoc-members: diff --git a/mopidy/backends/__init__.py b/mopidy/backends/__init__.py index cb541c11..4ee8ec5a 100644 --- a/mopidy/backends/__init__.py +++ b/mopidy/backends/__init__.py @@ -14,6 +14,15 @@ __all__ = ['BaseBackend', 'BasePlaybackController', 'BaseLibraryController'] class BaseBackend(object): + """ + :param core_queue: a queue for sending messages to + :class:`mopidy.process.CoreProcess` + :type core_queue: :class:`multiprocessing.Queue` + :param mixer: either a mixer instance, or :class:`None` to use the mixer + defined in settings + :type mixer: :class:`mopidy.mixers.BaseMixer` or :class:`None` + """ + def __init__(self, core_queue=None, mixer=None): self.core_queue = core_queue if mixer is not None: @@ -22,7 +31,8 @@ class BaseBackend(object): self.mixer = get_class(settings.MIXER)() #: A :class:`multiprocessing.Queue` which can be used by e.g. library - #: callbacks to send messages to the core. + #: callbacks executing in other threads to send messages to the core + #: thread, so that action may be taken in the correct thread. core_queue = None #: The current playlist controller. An instance of @@ -73,14 +83,17 @@ class BaseCurrentPlaylistController(object): """ #: The current playlist version. Integer which is increased every time the - #: current playlist is changed. Is not reset before the MPD server is - #: restarted. + #: current playlist is changed. Is not reset before Mopidy is restarted. version = 0 def __init__(self, backend): self.backend = backend self._playlist = Playlist() + def destroy(self): + """Cleanup after component.""" + pass + @property def playlist(self): """The currently loaded :class:`mopidy.models.Playlist`.""" @@ -229,7 +242,7 @@ class BaseCurrentPlaylistController(object): self.playlist = self.playlist.with_(tracks=before+shuffled+after) def destroy(self): - """Cleanup after component""" + """Cleanup after component.""" pass @@ -242,6 +255,10 @@ class BaseLibraryController(object): def __init__(self, backend): self.backend = backend + def destroy(self): + """Cleanup after component.""" + pass + def find_exact(self, field, query): """ Find tracks in the library where ``field`` matches ``query`` exactly. @@ -285,10 +302,6 @@ class BaseLibraryController(object): """ raise NotImplementedError - def destroy(self): - """Cleanup after component""" - pass - class BasePlaybackController(object): """ @@ -321,9 +334,10 @@ class BasePlaybackController(object): random = False #: :class:`True` - #: The current track is played repeatedly. + #: The current playlist is played repeatedly. To repeat a single track, + #: select both :attr:`repeat` and :attr:`single`. #: :class:`False` - #: The current track is played once. + #: The current playlist is played once. repeat = False #: :class:`True` @@ -340,6 +354,10 @@ class BasePlaybackController(object): self._play_time_accumulated = 0 self._play_time_started = None + def destroy(self): + """Cleanup after component.""" + pass + @property def current_playlist_position(self): """The position of the current track in the current playlist.""" @@ -392,8 +410,9 @@ class BasePlaybackController(object): """ The previous :class:`mopidy.models.Track` in the playlist. - For normal playback this is the previous track in the playlist. If random - and/or consume is enabled it should return the current track instead. + For normal playback this is the previous track in the playlist. If + random and/or consume is enabled it should return the current track + instead. """ if self.repeat or self.consume or self.random: return self.current_track @@ -478,7 +497,12 @@ class BasePlaybackController(object): self.current_track = None def new_playlist_loaded_callback(self): - """Tell the playback controller that a new playlist has been loaded.""" + """ + Tell the playback controller that a new playlist has been loaded. + + Typically called by :class:`mopidy.process.CoreProcess` after a message + from a library thread is received. + """ self.current_track = None self._first_shuffle = True self._shuffled = [] @@ -601,10 +625,6 @@ class BasePlaybackController(object): def _stop(self): raise NotImplementedError - def destroy(self): - """Cleanup after component""" - pass - class BaseStoredPlaylistsController(object): """ @@ -616,6 +636,10 @@ class BaseStoredPlaylistsController(object): self.backend = backend self._playlists = [] + def destroy(self): + """Cleanup after component.""" + pass + @property def playlists(self): """List of :class:`mopidy.models.Playlist`.""" @@ -716,7 +740,3 @@ class BaseStoredPlaylistsController(object): :rtype: list of :class:`mopidy.models.Playlist` """ return filter(lambda p: query in p.name, self._playlists) - - def destroy(self): - """Cleanup after component""" - pass