mopidy.core — Core API
The core API is the interface that is used by frontends like
mopidy.http and Mopidy-MPD. The core layer is in between the
frontends and the backends. Don’t forget that you will be accessing core
as a Pykka actor. If you are only interested in being notified about changes
in core see CoreListener.
Changed in version 1.1: All core API calls are now type checked.
Changed in version 1.1: All backend return values are now type checked.
- class mopidy.core.Core(config, *, mixer=None, backends, audio=None) None[source]
- tracklist
Manages everything related to the list of tracks we will play. See
TracklistController.
- playback
Manages playback state and the current playing track. See
PlaybackController.
- library
Manages the music library, e.g. searching and browsing for music. See
LibraryController.
- playlists
Manages stored playlists. See
PlaylistsController.
- mixer
Manages volume and muting. See
MixerController.
- history
Keeps record of what tracks have been played. See
HistoryController.
Tracklist controller
Manipulating
- TracklistController.add(tracks=None, at_position=None, uris=None) list[TlTrack][source]
Add tracks to the tracklist.
If
urisis given instead oftracks, the URIs are looked up in the library and the resulting tracks are added to the tracklist.If
at_positionis given, the tracks are inserted at the given position in the tracklist. Ifat_positionis not given, the tracks are appended to the end of the tracklist.Triggers the
mopidy.core.CoreListener.tracklist_changed()event.- Parameters:
- Return type:
Added in version 1.0: The
urisargument.Deprecated since version 1.0: The
tracksargument. Useuris.
- TracklistController.remove(criteria) list[TlTrack][source]
Remove the matching tracks from the tracklist.
Uses
filter()to lookup the tracks to remove.Triggers the
mopidy.core.CoreListener.tracklist_changed()event.Returns the removed tracks.
- TracklistController.clear() None[source]
Clear the tracklist.
Triggers the
mopidy.core.CoreListener.tracklist_changed()event.- Return type:
- TracklistController.move(start, end, to_position) None[source]
Move the tracks in the slice
[start:end]toto_position.Triggers the
mopidy.core.CoreListener.tracklist_changed()event.
- TracklistController.shuffle(start=None, end=None) None[source]
Shuffles the entire tracklist. If
startandendis given only shuffles the slice[start:end].Triggers the
mopidy.core.CoreListener.tracklist_changed()event.
Current state
- TracklistController.get_tl_tracks() list[TlTrack][source]
Get tracklist as list of
mopidy.models.TlTrack.
- TracklistController.index(tl_track=None, tlid=None) int | None[source]
The position of the given track in the tracklist.
If neither tl_track or tlid is given we return the index of the currently playing track.
- Parameters:
- Return type:
Added in version 1.1: The tlid parameter
- TracklistController.get_version() int[source]
Get the tracklist version.
Integer which is increased every time the tracklist is changed. Is not reset before Mopidy is restarted.
- Return type:
- TracklistController.get_tracks() list[Track][source]
Get tracklist as list of
mopidy.models.Track.
- TracklistController.slice(start, end) list[TlTrack][source]
Returns a slice of the tracklist, limited by the given start and end positions.
- TracklistController.filter(criteria) list[TlTrack][source]
Filter the tracklist by the given criteria.
Each rule in the criteria consists of a model field and a list of values to compare it against. If the model field matches any of the values, it may be returned.
Only tracks that match all the given criteria are returned.
Examples:
# Returns tracks with TLIDs 1, 2, 3, or 4 (tracklist ID) filter({'tlid': [1, 2, 3, 4]}) # Returns track with URIs 'xyz' or 'abc' filter({'uri': ['xyz', 'abc']}) # Returns track with a matching TLIDs (1, 3 or 6) and a # matching URI ('xyz' or 'abc') filter({'tlid': [1, 3, 6], 'uri': ['xyz', 'abc']})
Future state
- TracklistController.get_eot_tlid() int | None[source]
The TLID of the track that will be played after the current track.
Not necessarily the same TLID as returned by
get_next_tlid(). :rtype:int|NoneAdded in version 1.1.
- TracklistController.get_next_tlid() int | None[source]
The tlid of 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. :rtype:
int|NoneAdded in version 1.1.
- TracklistController.get_previous_tlid() int | None[source]
Returns the TLID of 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. :rtype:
int|NoneAdded in version 1.1.
- TracklistController.eot_track(tl_track) TlTrack | None[source]
The track that will be played after the given track.
Not necessarily the same track as
next_track().Deprecated since version 3.0: Use
get_eot_tlid()instead.
- TracklistController.next_track(tl_track) TlTrack | None[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.
Deprecated since version 3.0: Use
get_next_tlid()instead.
- TracklistController.previous_track(tl_track) TlTrack | None[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.
Deprecated since version 3.0: Use
get_previous_tlid()instead.
Options
- TracklistController.get_consume() bool[source]
Get consume mode.
- Return type:
TrueTracks are removed from the tracklist when they have been played.
FalseTracks are not removed from the tracklist.
- TracklistController.set_consume(value) None[source]
Set consume mode.
- Return type:
TrueTracks are removed from the tracklist when they have been played.
FalseTracks are not removed from the tracklist.
- TracklistController.get_random() bool[source]
Get random mode.
- Return type:
TrueTracks are selected at random from the tracklist.
FalseTracks are played in the order of the tracklist.
- TracklistController.set_random(value) None[source]
Set random mode.
- Return type:
TrueTracks are selected at random from the tracklist.
FalseTracks are played in the order of the tracklist.
- TracklistController.get_repeat() bool[source]
Get repeat mode.
- Return type:
TrueThe tracklist is played repeatedly.
FalseThe tracklist is played once.
- TracklistController.set_repeat(value) None[source]
Set repeat mode.
To repeat a single track, set both
repeatandsingle.- Return type:
TrueThe tracklist is played repeatedly.
FalseThe tracklist is played once.
Playback controller
Playback control
- PlaybackController.play(tlid=None) None[source]
Play a track from the tracklist, specified by the tracklist ID.
Note that the track must already be in the tracklist.
If no tracklist ID is provided, resume playback of the currently active track.
Removed in version 4.0: The
tl_trackargument. Usetlidinstead.
- PlaybackController.next() None[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.
- Return type:
- PlaybackController.previous() None[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.
- Return type:
Current track
- PlaybackController.get_current_tl_track() TlTrack | None[source]
Get the currently playing or selected track.
Returns a
mopidy.models.TlTrackorNone.
- PlaybackController.get_current_track() Track | None[source]
Get the currently playing or selected track.
Extracted from
get_current_tl_track()for convenience.Returns a
mopidy.models.TrackorNone.
- PlaybackController.get_current_tlid() TracklistId | None[source]
Get the currently playing or selected tracklist ID.
Extracted from
get_current_tl_track()for convenience. :rtype:Optional[NewType(TracklistId,int)]Added in version 1.1.
Playback states
- PlaybackController.get_state() PlaybackState[source]
Get The playback state.
- Return type:
PlaybackState
- PlaybackController.set_state(new_state) None[source]
Set the playback state.
Must be
PLAYING,PAUSED, orSTOPPED.Possible states and transitions:
digraph state_transitions { "STOPPED" -> "PLAYING" [ label="play" ] "STOPPED" -> "PAUSED" [ label="pause" ] "PLAYING" -> "STOPPED" [ label="stop" ] "PLAYING" -> "PAUSED" [ label="pause" ] "PLAYING" -> "PLAYING" [ label="play" ] }- Return type:
-
”PAUSED” -> “PLAYING” [ label=”resume” ] “PAUSED” -> “STOPPED” [ label=”stop” ]
Library controller
- class mopidy.core.LibraryController
- LibraryController.browse(uri) list[Ref][source]
Browse directories and tracks at the given
uri.uriis a string which represents some directory belonging to a backend. To get the intial root directories for backends passNoneas the URI.Returns a list of
mopidy.models.Refobjects for the directories and tracks at the givenuri.The
Refobjects 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
Refobjects 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
/bardirectory could be returned like this:Ref.directory(uri='dummy:directory:/bar', name='bar')
Added in version 0.18.
- LibraryController.search(query, uris=None, exact=False) list[SearchResult][source]
Search the library for tracks where
fieldcontainsvalues.If
urisis 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']}) # Returns results matching artist 'xyz' in any backend search({'artist': ['xyz']}) # Returns results matching 'a' and 'b' and artist 'xyz' in any # backend 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:']) # Returns results matching artist 'xyz' and 'abc' in any backend search({'artist': ['xyz', 'abc']})
- Parameters:
query (
dict[Union[Literal['uri','track_name','album','artist','albumartist','composer','performer','track_no','genre','date','comment','disc_no','musicbrainz_albumid','musicbrainz_artistid','musicbrainz_trackid'],Literal['any']],Iterable[str|int]]) – one or more queries to search foruris (
Iterable[NewType(Uri,str)] |None) – zero or more URI roots to limit the search toexact (
bool) – if the search should use exact matching
- Return type:
Added in version 1.0: The
exactkeyword argument.
- LibraryController.lookup(uris) dict[Uri, list[Track]][source]
Lookup the given URIs.
If the URI expands to multiple tracks, the returned list will contain them all.
- LibraryController.refresh(uri=None) None[source]
Refresh library. Limit to URI and below if an URI is given.
- LibraryController.get_images(uris) dict[Uri, tuple[Image, ...]][source]
Lookup the images for the given URIs.
Backends can use this to return image URIs for any URI they know about be it tracks, albums, playlists. The lookup result is a dictionary mapping the provided URIs to lists of images.
Unknown URIs or URIs the corresponding backend couldn’t find anything for will simply return an empty list for that URI.
Added in version 1.0.
- LibraryController.get_distinct(field, query=None) set[Any][source]
List distinct values for a given field from the library.
This has mainly been added to support the list commands the MPD protocol supports in a more sane fashion. Other frontends are not recommended to use this method.
Returns set of values corresponding to the requested field type.
- Parameters:
field (
Literal['uri','track_name','album','artist','albumartist','composer','performer','track_no','genre','date','comment','disc_no','musicbrainz_albumid','musicbrainz_artistid','musicbrainz_trackid']) – Any one ofuri,track_name,album,artist,albumartist,composer,performer,track_no,genre,date,comment,disc_no,musicbrainz_albumid,musicbrainz_artistid, ormusicbrainz_trackid.query (
dict[Union[Literal['uri','track_name','album','artist','albumartist','composer','performer','track_no','genre','date','comment','disc_no','musicbrainz_albumid','musicbrainz_artistid','musicbrainz_trackid'],Literal['any']],Iterable[str|int]] |None) – Query to use for limiting results, seesearch()for details about the query format.
- Return type:
Added in version 1.0.
Playlists controller
- class mopidy.core.PlaylistsController
- PlaylistsController.get_uri_schemes() list[UriScheme][source]
Get the list of URI schemes that support playlists. :rtype:
list[NewType(UriScheme,str)]Added in version 2.0.
Fetching
- PlaylistsController.as_list() list[Ref][source]
Get a list of the currently available playlists.
Returns a list of
Refobjects referring to the playlists. In other words, no information about the playlists’ content is given. :rtype:list[Ref]Added in version 1.0.
- PlaylistsController.get_items(uri) list[Ref] | None[source]
Get the items in a playlist specified by
uri.Returns a list of
Refobjects referring to the playlist’s items.If a playlist with the given
uridoesn’t exist, it returnsNone. :rtype:list[Ref] |NoneAdded in version 1.0.
- PlaylistsController.lookup(uri) Playlist | None[source]
Lookup playlist with given URI in both the set of playlists and in any other playlist sources. Returns
Noneif not found.
- PlaylistsController.refresh(uri_scheme=None) None[source]
Refresh the playlists in
playlists.If
uri_schemeisNone, all backends are asked to refresh. Ifuri_schemeis an URI scheme handled by a backend, only that backend is asked to refresh. Ifuri_schemedoesn’t match any current backend, nothing happens.
Manipulating
- PlaylistsController.create(name, uri_scheme=None) Playlist | None[source]
Create a new playlist.
If
uri_schemematches an URI scheme handled by a current backend, that backend is asked to create the playlist. Ifuri_schemeisNoneor doesn’t match a current backend, the first backend is asked to create the playlist.All new playlists must be created by calling this method, and not by creating new instances of
mopidy.models.Playlist.
- PlaylistsController.save(playlist) Playlist | None[source]
Save the playlist.
For a playlist to be saveable, it must have the
uriattribute set. You must not set theuriatribute 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 must 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
Noneis returned.
Mixer controller
- class mopidy.core.MixerController
- MixerController.get_mute() bool | None[source]
Get mute state.
Trueif muted,Falseunmuted,Noneif unknown.
- MixerController.set_mute(mute) bool[source]
Set mute state.
Trueto mute,Falseto unmute.Returns
Trueif call is successful, otherwiseFalse.- Return type:
History controller
- class mopidy.core.HistoryController
Core events
- 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) None[source]
Called whenever the mute state is changed.
MAY be implemented by actor.
- Parameters:
mute (boolean) – the new mute state
- Return type:
- on_event(event, **kwargs) None[source]
Called on all events.
MAY be implemented by actor. By default, this method forwards the event to the specific event methods.
- Parameters:
event (
Literal['track_playback_paused','track_playback_resumed','track_playback_started','track_playback_ended','playback_state_changed','tracklist_changed','playlists_loaded','playlist_changed','playlist_deleted','options_changed','volume_changed','mute_changed','seeked','stream_title_changed']) – the event namekwargs (
Any) – any other arguments to the specific event handlers
- Return type:
- options_changed() None[source]
Called whenever an option is changed.
MAY be implemented by actor.
- Return type:
- playback_state_changed(old_state, new_state) None[source]
Called whenever playback state is changed.
MAY be implemented by actor.
- Parameters:
old_state (string from
mopidy.core.PlaybackStatefield) – the state before the changenew_state (string from
mopidy.core.PlaybackStatefield) – the state after the change
- Return type:
- playlist_changed(playlist) None[source]
Called whenever a playlist is changed.
MAY be implemented by actor.
- Parameters:
playlist (
mopidy.models.Playlist) – the changed playlist- Return type:
- playlist_deleted(uri) None[source]
Called whenever a playlist is deleted.
MAY be implemented by actor.
- Parameters:
uri (string) – the URI of the deleted playlist
- Return type:
- playlists_loaded() None[source]
Called when playlists are loaded or refreshed.
MAY be implemented by actor.
- Return type:
- seeked(time_position) None[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.
- static send(event, **kwargs) None[source]
Helper to allow calling of core listener events.
- Return type:
- stream_title_changed(title) None[source]
Called whenever the currently playing stream title changes.
MAY be implemented by actor.
- Parameters:
title (string) – the new stream title
- Return type:
- track_playback_ended(tl_track, time_position) None[source]
Called whenever playback of a track ends.
MAY be implemented by actor.
- track_playback_paused(tl_track, time_position) None[source]
Called whenever track playback is paused.
MAY be implemented by actor.
- track_playback_resumed(tl_track, time_position) None[source]
Called whenever track playback is resumed.
MAY be implemented by actor.
- track_playback_started(tl_track) None[source]
Called whenever a new track starts playing.
MAY be implemented by actor.