Core API¶
The core API is the interface that is used by frontends like
mopidy.http
and mopidy.mpd
. The core layer is inbetween the
frontends and the backends.
-
class
mopidy.core.
Core
(mixer=None, backends=None)[source]¶ -
library
= None¶ The library controller. An instance of
mopidy.core.LibraryController
.
-
playback
= None¶ The playback controller. An instance of
mopidy.core.PlaybackController
.
-
playlists
= None¶ The playlists controller. An instance of
mopidy.core.PlaylistsController
.
-
tracklist
= None¶ The tracklist controller. An instance of
mopidy.core.TracklistController
.
-
uri_schemes
¶ List of URI schemes we can handle
-
version
¶ Version of the Mopidy core API
-
Playback controller¶
Manages playback, with actions like play, pause, stop, next, previous, seek, and volume control.
-
class
mopidy.core.
PlaybackState
[source]¶ Enum of playback states.
-
PAUSED
= u'paused'¶ Constant representing the paused state.
-
PLAYING
= u'playing'¶ Constant representing the playing state.
-
STOPPED
= u'stopped'¶ Constant representing the stopped state.
-
-
class
mopidy.core.
PlaybackController
(mixer, backends, core)[source]¶ -
change_track
(tl_track, on_error_step=1)[source]¶ Change to the given track, keeping the current playback state.
Parameters: - tl_track (
mopidy.models.TlTrack
orNone
) – track to change to - on_error_step (int, -1 or 1) – direction to step at play error, 1 for next track (default), -1 for previous track
- tl_track (
-
current_tl_track
= None¶ The currently playing or selected
mopidy.models.TlTrack
, orNone
.
-
current_track
¶ The currently playing or selected
mopidy.models.Track
.Read-only. Extracted from
current_tl_track
for convenience.
-
mute
¶ Mute state as a
True
if muted,False
otherwise
-
next
()[source]¶ Change to the next track.
The current playback state will be kept. If it was playing, playing will continue. If it was paused, it will still be paused, etc.
-
on_end_of_track
()[source]¶ Tell the playback controller that end of track is reached.
Used by event handler in
mopidy.core.Core
.
-
on_tracklist_change
()[source]¶ Tell the playback controller that the current playlist has changed.
Used by
mopidy.core.TracklistController
.
-
play
(tl_track=None, on_error_step=1)[source]¶ Play the given track, or if the given track is
None
, play the currently active track.Parameters: - tl_track (
mopidy.models.TlTrack
orNone
) – track to play - on_error_step (int, -1 or 1) – direction to step at play error, 1 for next track (default), -1 for previous track
- tl_track (
-
previous
()[source]¶ Change to the previous track.
The current playback state will be kept. If it was playing, playing will continue. If it was paused, it will still be paused, etc.
-
seek
(time_position)[source]¶ Seeks to time position given in milliseconds.
Parameters: time_position (int) – time position in milliseconds Return type: True
if successful, elseFalse
-
state
¶ The playback state. Must be
PLAYING
,PAUSED
, orSTOPPED
.Possible states and transitions:
-
stop
(clear_current_track=False)[source]¶ Stop playing.
Parameters: clear_current_track (boolean) – whether to clear the current track _after_ stopping
-
time_position
¶ Time position in milliseconds.
-
volume
¶ Volume as int in range [0..100] or
None
if unknown. The volume scale is linear.
-
Tracklist controller¶
Manages everything related to the tracks we are currently playing.
-
class
mopidy.core.
TracklistController
(core)[source]¶ -
add
(tracks=None, at_position=None, uri=None)[source]¶ Add the track or list of tracks to the tracklist.
If
uri
is given instead oftracks
, the URI is looked up in the library and the resulting tracks are added to the tracklist.If
at_position
is given, the tracks placed at the given position in the tracklist. Ifat_position
is not given, the tracks are appended to the end of the tracklist.Triggers the
mopidy.core.CoreListener.tracklist_changed()
event.Parameters: - tracks (list of
mopidy.models.Track
) – tracks to add - at_position (int or
None
) – position in tracklist to add track - uri (string) – URI for tracks to add
Return type: list of
mopidy.models.TlTrack
- tracks (list of
-
clear
()[source]¶ Clear the tracklist.
Triggers the
mopidy.core.CoreListener.tracklist_changed()
event.
-
consume
¶ True
- Tracks are removed from the tracklist when they have been played.
False
- Tracks are not removed from the tracklist.
-
eot_track
(tl_track)[source]¶ The track that will be played after the given track.
Not necessarily the same track as
next_track()
.Parameters: tl_track ( mopidy.models.TlTrack
orNone
) – the reference trackReturn type: mopidy.models.TlTrack
orNone
-
filter
(criteria=None, **kwargs)[source]¶ Filter the tracklist by the given criterias.
A criteria consists of a model field to check and a list of values to compare it against. If the model field matches one of the values, it may be returned.
Only tracks that matches all the given criterias are returned.
Examples:
# Returns tracks with TLIDs 1, 2, 3, or 4 (tracklist ID) filter({'tlid': [1, 2, 3, 4]}) filter(tlid=[1, 2, 3, 4]) # Returns track with IDs 1, 5, or 7 filter({'id': [1, 5, 7]}) filter(id=[1, 5, 7]) # Returns track with URIs 'xyz' or 'abc' filter({'uri': ['xyz', 'abc']}) filter(uri=['xyz', 'abc']) # Returns tracks with ID 1 and URI 'xyz' filter({'id': [1], 'uri': ['xyz']}) filter(id=[1], uri=['xyz']) # Returns track with a matching ID (1, 3 or 6) and a matching URI # ('xyz' or 'abc') filter({'id': [1, 3, 6], 'uri': ['xyz', 'abc']}) filter(id=[1, 3, 6], uri=['xyz', 'abc'])
Parameters: criteria (dict, of (string, list) pairs) – on or more criteria to match by Return type: list of mopidy.models.TlTrack
-
index
(tl_track)[source]¶ The position of the given track in the tracklist.
Parameters: tl_track ( mopidy.models.TlTrack
) – the track to find the index ofReturn type: int
orNone
-
length
¶ Length of the tracklist.
-
mark_played
(tl_track)[source]¶ Private method used by
mopidy.core.PlaybackController
.
-
mark_playing
(tl_track)[source]¶ Private method used by
mopidy.core.PlaybackController
.
-
mark_unplayable
(tl_track)[source]¶ Private method used by
mopidy.core.PlaybackController
.
-
move
(start, end, to_position)[source]¶ Move the tracks in the slice
[start:end]
toto_position
.Triggers the
mopidy.core.CoreListener.tracklist_changed()
event.Parameters:
-
next_track
(tl_track)[source]¶ The track that will be played if calling
mopidy.core.PlaybackController.next()
.For normal playback this is the next track in the tracklist. If repeat is enabled the next track can loop around the tracklist. When random is enabled this should be a random track, all tracks should be played once before the tracklist repeats.
Parameters: tl_track ( mopidy.models.TlTrack
orNone
) – the reference trackReturn type: mopidy.models.TlTrack
orNone
-
previous_track
(tl_track)[source]¶ Returns the track that will be played if calling
mopidy.core.PlaybackController.previous()
.For normal playback this is the previous track in the tracklist. If random and/or consume is enabled it should return the current track instead.
Parameters: tl_track ( mopidy.models.TlTrack
orNone
) – the reference trackReturn type: mopidy.models.TlTrack
orNone
-
random
¶ True
- Tracks are selected at random from the tracklist.
False
- Tracks are played in the order of the tracklist.
-
remove
(criteria=None, **kwargs)[source]¶ Remove the matching tracks from the tracklist.
Uses
filter()
to lookup the tracks to remove.Triggers the
mopidy.core.CoreListener.tracklist_changed()
event.Parameters: criteria (dict) – on or more criteria to match by Return type: list of mopidy.models.TlTrack
that was removed
-
repeat
¶
-
shuffle
(start=None, end=None)[source]¶ Shuffles the entire tracklist. If
start
andend
is given only shuffles the slice[start:end]
.Triggers the
mopidy.core.CoreListener.tracklist_changed()
event.Parameters: - start (int or
None
) – position of first track to shuffle - end (int or
None
) – position after last track to shuffle
- start (int or
-
single
¶ True
- Playback is stopped after current song, unless in
repeat
mode. False
- Playback continues after current song.
-
slice
(start, end)[source]¶ Returns a slice of the tracklist, limited by the given start and end positions.
Parameters: Return type:
-
tl_tracks
¶ List of
mopidy.models.TlTrack
.Read-only.
-
tracks
¶ List of
mopidy.models.Track
in the tracklist.Read-only.
-
version
¶ The tracklist version.
Read-only. Integer which is increased every time the tracklist is changed. Is not reset before Mopidy is restarted.
-
Playlists controller¶
Manages persistence of playlists.
-
class
mopidy.core.
PlaylistsController
(backends, core)[source]¶ -
create
(name, uri_scheme=None)[source]¶ Create a new playlist.
If
uri_scheme
matches an URI scheme handled by a current backend, that backend is asked to create the playlist. Ifuri_scheme
isNone
or doesn’t match a current backend, the first backend is asked to create the playlist.All new playlists should be created by calling this method, and not by creating new instances of
mopidy.models.Playlist
.Parameters: Return type:
-
delete
(uri)[source]¶ Delete playlist identified by the URI.
If the URI doesn’t match the URI schemes handled by the current backends, nothing happens.
Parameters: uri (string) – URI of the playlist to delete
-
filter
(criteria=None, **kwargs)[source]¶ Filter playlists by the given criterias.
Examples:
# Returns track with name 'a' filter({'name': 'a'}) filter(name='a') # Returns track with URI 'xyz' filter({'uri': 'xyz'}) filter(uri='xyz') # Returns track with name 'a' and URI 'xyz' filter({'name': 'a', 'uri': 'xyz'}) filter(name='a', uri='xyz')
Parameters: criteria (dict) – one or more criteria to match by Return type: list of mopidy.models.Playlist
-
lookup
(uri)[source]¶ Lookup playlist with given URI in both the set of playlists and in any other playlist sources. Returns
None
if not found.Parameters: uri (string) – playlist URI Return type: mopidy.models.Playlist
orNone
-
playlists
¶ The available playlists.
Read-only. List of
mopidy.models.Playlist
.
-
refresh
(uri_scheme=None)[source]¶ Refresh the playlists in
playlists
.If
uri_scheme
isNone
, all backends are asked to refresh. Ifuri_scheme
is an URI scheme handled by a backend, only that backend is asked to refresh. Ifuri_scheme
doesn’t match any current backend, nothing happens.Parameters: uri_scheme (string) – limit to the backend matching the URI scheme
-
save
(playlist)[source]¶ Save the playlist.
For a playlist to be saveable, it must have the
uri
attribute set. You should not set theuri
atribute yourself, but use playlist objects returned bycreate()
or retrieved fromplaylists
, which will always give you saveable playlists.The method returns the saved playlist. The return playlist may differ from the saved playlist. E.g. if the playlist name was changed, the returned playlist may have a different URI. The caller of this method should throw away the playlist sent to this method, and use the returned playlist instead.
If the playlist’s URI isn’t set or doesn’t match the URI scheme of a current backend, nothing is done and
None
is returned.Parameters: playlist ( mopidy.models.Playlist
) – the playlistReturn type: mopidy.models.Playlist
orNone
-
Library controller¶
Manages the music library, e.g. searching for tracks to be added to a playlist.
-
class
mopidy.core.
LibraryController
(backends, core)[source]¶ -
browse
(uri)[source]¶ Browse directories and tracks at the given
uri
.uri
is a string which represents some directory belonging to a backend. To get the intial root directories for backends pass None as the URI.Returns a list of
mopidy.models.Ref
objects for the directories and tracks at the givenuri
.The
Ref
objects representing tracks keep the track’s original URI. A matching pair of objects can look like this:Track(uri='dummy:/foo.mp3', name='foo', artists=..., album=...) Ref.track(uri='dummy:/foo.mp3', name='foo')
The
Ref
objects representing directories have backend specific URIs. These are opaque values, so no one but the backend that created them should try and derive any meaning from them. The only valid exception to this is checking the scheme, as it is used to route browse requests to the correct backend.For example, the dummy library’s
/bar
directory could be returned like this:Ref.directory(uri='dummy:directory:/bar', name='bar')
Parameters: uri (string) – URI to browse Return type: list of mopidy.models.Ref
-
find_exact
(query=None, uris=None, **kwargs)[source]¶ Search the library for tracks where
field
isvalues
.If the query is empty, and the backend can support it, all available tracks are returned.
If
uris
is given, the search is limited to results from within the URI roots. For example passinguris=['file:']
will limit the search to the local backend.Examples:
# Returns results matching 'a' from any backend find_exact({'any': ['a']}) find_exact(any=['a']) # Returns results matching artist 'xyz' from any backend find_exact({'artist': ['xyz']}) find_exact(artist=['xyz']) # Returns results matching 'a' and 'b' and artist 'xyz' from any # backend find_exact({'any': ['a', 'b'], 'artist': ['xyz']}) find_exact(any=['a', 'b'], artist=['xyz']) # Returns results matching 'a' if within the given URI roots # "file:///media/music" and "spotify:" find_exact( {'any': ['a']}, uris=['file:///media/music', 'spotify:']) find_exact(any=['a'], uris=['file:///media/music', 'spotify:'])
Parameters: - query (dict) – one or more queries to search for
- uris (list of strings or
None
) – zero or more URI roots to limit the search to
Return type: list of
mopidy.models.SearchResult
-
lookup
(uri)[source]¶ Lookup the given URI.
If the URI expands to multiple tracks, the returned list will contain them all.
Parameters: uri (string) – track URI Return type: list of mopidy.models.Track
-
refresh
(uri=None)[source]¶ Refresh library. Limit to URI and below if an URI is given.
Parameters: uri (string) – directory or track URI
-
search
(query=None, uris=None, **kwargs)[source]¶ Search the library for tracks where
field
containsvalues
.If the query is empty, and the backend can support it, all available tracks are returned.
If
uris
is given, the search is limited to results from within the URI roots. For example passinguris=['file:']
will limit the search to the local backend.Examples:
# Returns results matching 'a' in any backend search({'any': ['a']}) search(any=['a']) # Returns results matching artist 'xyz' in any backend search({'artist': ['xyz']}) search(artist=['xyz']) # Returns results matching 'a' and 'b' and artist 'xyz' in any # backend search({'any': ['a', 'b'], 'artist': ['xyz']}) search(any=['a', 'b'], artist=['xyz']) # Returns results matching 'a' if within the given URI roots # "file:///media/music" and "spotify:" search({'any': ['a']}, uris=['file:///media/music', 'spotify:']) search(any=['a'], uris=['file:///media/music', 'spotify:'])
Parameters: - query (dict) – one or more queries to search for
- uris (list of strings or
None
) – zero or more URI roots to limit the search to
Return type: list of
mopidy.models.SearchResult
-
Core listener¶
-
class
mopidy.core.
CoreListener
[source]¶ Marker interface for recipients of events sent by the core actor.
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.
-
mute_changed
(mute)[source]¶ Called whenever the mute state is changed.
MAY be implemented by actor.
Parameters: mute (boolean) – the new mute state
-
on_event
(event, **kwargs)[source]¶ Called on all events.
MAY be implemented by actor. By default, this method forwards the event to the specific event methods.
Parameters: - event (string) – the event name
- kwargs – any other arguments to the specific event handlers
-
playback_state_changed
(old_state, new_state)[source]¶ Called whenever playback state is changed.
MAY be implemented by actor.
Parameters: - old_state (string from
mopidy.core.PlaybackState
field) – the state before the change - new_state (string from
mopidy.core.PlaybackState
field) – the state after the change
- old_state (string from
-
playlist_changed
(playlist)[source]¶ Called whenever a playlist is changed.
MAY be implemented by actor.
Parameters: playlist ( mopidy.models.Playlist
) – the changed playlist
-
playlists_loaded
()[source]¶ Called when playlists are loaded or refreshed.
MAY be implemented by actor.
-
seeked
(time_position)[source]¶ Called whenever the time position changes by an unexpected amount, e.g. at seek to a new time position.
MAY be implemented by actor.
Parameters: time_position (int) – the position that was seeked to in milliseconds
-
track_playback_ended
(tl_track, time_position)[source]¶ Called whenever playback of a track ends.
MAY be implemented by actor.
Parameters: - tl_track (
mopidy.models.TlTrack
) – the track that was played before playback stopped - time_position (int) – the time position in milliseconds
- tl_track (
-
track_playback_paused
(tl_track, time_position)[source]¶ Called whenever track playback is paused.
MAY be implemented by actor.
Parameters: - tl_track (
mopidy.models.TlTrack
) – the track that was playing when playback paused - time_position (int) – the time position in milliseconds
- tl_track (
-
track_playback_resumed
(tl_track, time_position)[source]¶ Called whenever track playback is resumed.
MAY be implemented by actor.
Parameters: - tl_track (
mopidy.models.TlTrack
) – the track that was playing when playback resumed - time_position (int) – the time position in milliseconds
- tl_track (
-
track_playback_started
(tl_track)[source]¶ Called whenever a new track starts playing.
MAY be implemented by actor.
Parameters: tl_track ( mopidy.models.TlTrack
) – the track that just started playing
-