diff --git a/docs/api/backends.rst b/docs/api/backends.rst new file mode 100644 index 00000000..365c6d85 --- /dev/null +++ b/docs/api/backends.rst @@ -0,0 +1,298 @@ +************************************* +:mod:`mopidy.backends` -- Backend API +************************************* + +.. warning:: + This is our *planned* backend API, and not the current API. + +.. module:: mopidy.backends + :synopsis: Interface between Mopidy and its various backends. + +.. class:: BaseBackend() + + .. attribute:: current_playlist + + The current playlist controller. An instance of + :class:`BaseCurrentPlaylistController`. + + .. attribute:: library + + The library controller. An instance of :class:`BaseLibraryController`. + + .. attribute:: playback + + The playback controller. An instance of :class:`BasePlaybackController`. + + .. attribute:: stored_playlists + + The stored playlists controller. An instance of + :class:`BaseStoredPlaylistsController`. + + .. attribute:: uri_handlers + + List of URI prefixes this backend can handle. + + +.. class:: BaseCurrentPlaylistController(backend) + + :param backend: backend the controller is a part of + :type backend: :class:`BaseBackend` + + .. method:: add(track, at_position=None) + + Add the track to the end of, or at the given position in the current + playlist. + + :param track: track to add + :type track: :class:`mopidy.models.Track` + :param at_position: position in current playlist to add track + :type at_position: int or :class:`None` + + .. method:: clear() + + Clear the current playlist. + + .. method:: load(playlist) + + Replace the current playlist with the given playlist. + + :param playlist: playlist to load + :type playlist: :class:`mopidy.models.Playlist` + + .. method:: move(start, end, to_position) + + Move the tracks at positions in [``start``, ``end``] to + ``to_position``. + + :param start: position of first track to move + :type start: int + :param end: position of last track to move + :type end: int + :param to_position: new position for the tracks + :type to_position: int + + .. attribute:: playlist + + The currently loaded :class:`mopidy.models.Playlist`. + + .. method:: remove(position) + + Remove the track at ``position`` from the current playlist. + + :param position: position of track to remove + :type position: int + + .. method:: shuffle(start=None, end=None) + + Shuffles the playlist, optionally a part of the playlist given by + ``start`` and ``end``. + + :param start: position of first track to shuffle + :type start: int or :class:`None` + :param end: position of last track to shuffle + :type end: int or :class:`None` + + .. attribute:: version + + The current playlist version. Integer which is increased every time the + current playlist is changed. + + +.. class:: BasePlaybackController(backend) + + :param backend: backend the controller is a part of + :type backend: :class:`BaseBackend` + + .. attribute:: consume + + :class:`True` + Tracks are removed from the playlist when they have been played. + :class:`False` + Tracks are not removed from the playlist. + + .. attribute:: current_track + + The currently playing or selected :class:`mopidy.models.Track`. + + .. method:: next() + + Play the next track. + + .. method:: pause() + + Pause playblack. + + .. attribute:: PAUSED + + Constant representing the paused state. + + .. method:: play(id=None, position=None) + + Play either the track with the given ID, the given position, or the + currently active track. + + :param id: ID of track to play + :type id: int + :param position: position in current playlist of track to play + :type position: int + + .. attribute:: PLAYING + + Constant representing the playing state. + + .. attribute:: playlist_position + + The position in the current playlist. + + .. method:: previous() + + Play the previous track. + + .. attribute:: random + + :class:`True` + Tracks are selected at random from the playlist. + :class:`False` + Tracks are played in the order of the playlist. + + .. attribute:: repeat + + :class:`True` + The current track is played repeatedly. + :class:`False` + The current track is played once. + + .. method:: resume() + + If paused, resume playing the current track. + + .. method:: seek(time_position) + + Seeks to time position given in milliseconds. + + :param time_position: time position in milliseconds + :type time_position: int + + .. attribute:: state + + The playback state. Must be :attr:`PLAYING`, :attr:`PAUSED`, or + :attr:`STOPPED`. + + .. method:: stop() + + Stop playing. + + .. attribute:: STOPPED + + Constant representing the stopped state. + + .. attribute:: time_position + + Time position in milliseconds. + + .. attribute:: volume + + The audio volume as an int in the range [0, 100]. :class:`None` if + unknown. + + +.. class:: BaseLibraryController(backend) + + :param backend: backend the controller is a part of + :type backend: :class:`BaseBackend` + + .. method:: find_exact(type, query) + + Find tracks in the library where ``type`` matches ``query`` exactly. + + :param type: 'title', 'artist', or 'album' + :type type: string + :param query: the search query + :type query: string + :rtype: list of :class:`mopidy.models.Track` + + .. method:: lookup(uri) + + Lookup track with given URI. + + :param uri: track URI + :type uri: string + :rtype: :class:`mopidy.models.Track` + + .. method:: refresh(uri=None) + + Refresh library. Limit to URI and below if an URI is given. + + :param uri: directory or track URI + :type uri: string + + .. method:: search(type, query) + + Search the library for tracks where ``type`` contains ``query``. + + :param type: 'title', 'artist', 'album', or 'uri' + :type type: string + :param query: the search query + :type query: string + :rtype: list of :class:`mopidy.models.Track` + + +.. class:: BaseStoredPlaylistsController(backend) + + :param backend: backend the controller is a part of + :type backend: :class:`BaseBackend` + + .. method:: add(uri) + + Add existing playlist with the given URI. + + :param uri: URI of existing playlist + :type uri: string + + .. method:: create(name) + + Create a new playlist. + + :param name: name of the new playlist + :type name: string + :rtype: :class:`mopidy.models.Playlist` + + .. attribute:: playlists + + List of :class:`mopidy.models.Playlist`. + + .. method:: delete(playlist) + + Delete playlist. + + :param playlist: the playlist to delete + :type playlist: :class:`mopidy.models.Playlist` + + .. method:: lookup(uri) + + Lookup playlist with given URI. + + :param uri: playlist URI + :type uri: string + :rtype: :class:`mopidy.models.Playlist` + + .. method:: refresh() + + Refresh stored playlists. + + .. method:: rename(playlist, new_name) + + Rename playlist. + + :param playlist: the playlist + :type playlist: :class:`mopidy.models.Playlist` + :param new_name: the new name + :type new_name: string + + .. method:: search(query) + + Search for playlists whose name contains ``query``. + + :param query: query to search for + :type query: string + :rtype: list of :class:`mopidy.models.Playlist`