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=None, mixer=None, backends=None, audio=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, uri=None, uris=None)[source]¶ Add 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
uris
is given instead ofuri
ortracks
, the URIs are looked up in the library and the resulting tracks are added to the tracklist.If
at_position
is given, the tracks are inserted 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
orNone
) -- tracks to add - at_position (int or
None
) -- position in tracklist to add tracks - uri (string or
None
) -- URI for tracks to add - uris (list of string or
None
) -- list of URIs for tracks to add
Return type: list of
mopidy.models.TlTrack
New in version 1.0: The
uris
argument.Deprecated since version 1.0: The
tracks
anduri
arguments. Useuris
.- tracks (list of
-
TracklistController.
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 removedDeprecated since version 1.1: Providing the criteria via
kwargs
.
-
TracklistController.
clear
()[source]¶ Clear the tracklist.
Triggers the
mopidy.core.CoreListener.tracklist_changed()
event.
-
TracklistController.
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:
-
TracklistController.
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
Current state¶
-
TracklistController.
get_tl_tracks
()[source]¶ Get tracklist as list of
mopidy.models.TlTrack
.
-
TracklistController.
index
(tl_track=None, tlid=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: - tl_track (
mopidy.models.TlTrack
orNone
) -- the track to find the index of - tlid (
int
orNone
) -- TLID of the track to find the index of
Return type: int
orNone
New in version 1.1: The tlid parameter
- tl_track (
-
TracklistController.
get_version
()[source]¶ Get the tracklist version.
Integer which is increased every time the tracklist is changed. Is not reset before Mopidy is restarted.
-
TracklistController.
get_tracks
()[source]¶ Get tracklist as list of
mopidy.models.Track
.
-
TracklistController.
slice
(start, end)[source]¶ Returns a slice of the tracklist, limited by the given start and end positions.
Parameters: Return type:
-
TracklistController.
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]}) # 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']})
Parameters: criteria (dict, of (string, list) pairs) -- on or more criteria to match by Return type: list of mopidy.models.TlTrack
Deprecated since version 1.1: Providing the criteria via
kwargs
.
Future state¶
-
TracklistController.
get_eot_tlid
()[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()
.Return type: int
orNone
New in version 1.1.
-
TracklistController.
get_next_tlid
()[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.
Return type: int
orNone
New in version 1.1.
-
TracklistController.
get_previous_tlid
()[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.
Return type: int
orNone
New in version 1.1.
-
TracklistController.
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
-
TracklistController.
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
-
TracklistController.
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
Options¶
-
TracklistController.
get_consume
()[source]¶ Get consume mode.
True
- Tracks are removed from the tracklist when they have been played.
False
- Tracks are not removed from the tracklist.
-
TracklistController.
set_consume
(value)[source]¶ Set consume mode.
True
- Tracks are removed from the tracklist when they have been played.
False
- Tracks are not removed from the tracklist.
-
TracklistController.
get_random
()[source]¶ Get random mode.
True
- Tracks are selected at random from the tracklist.
False
- Tracks are played in the order of the tracklist.
-
TracklistController.
set_random
(value)[source]¶ Set random mode.
True
- Tracks are selected at random from the tracklist.
False
- Tracks are played in the order of the tracklist.
-
TracklistController.
get_repeat
()[source]¶ Get repeat mode.
True
- The tracklist is played repeatedly.
False
- The tracklist is played once.
-
TracklistController.
set_repeat
(value)[source]¶ Set repeat mode.
To repeat a single track, set both
repeat
andsingle
.True
- The tracklist is played repeatedly.
False
- The tracklist is played once.
Playback controller¶
Playback control¶
-
PlaybackController.
play
(tl_track=None, tlid=None)[source]¶ Play the given track, or if the given tl_track and tlid is
None
, play the currently active track.Note that the track must already be in the tracklist.
Parameters: - tl_track (
mopidy.models.TlTrack
orNone
) -- track to play - tlid (
int
orNone
) -- TLID of the track to play
- tl_track (
-
PlaybackController.
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.
Current track¶
-
PlaybackController.
get_current_tl_track
()[source]¶ Get the currently playing or selected track.
Returns a
mopidy.models.TlTrack
orNone
.
-
PlaybackController.
get_current_track
()[source]¶ Get the currently playing or selected track.
Extracted from
get_current_tl_track()
for convenience.Returns a
mopidy.models.Track
orNone
.
Playback states¶
-
PlaybackController.
set_state
(new_state)[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" ] "PAUSED" -> "PLAYING" [ label="resume" ] "PAUSED" -> "STOPPED" [ label="stop" ] }
Library controller¶
-
class
mopidy.core.
LibraryController
¶
-
LibraryController.
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 passNone
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
New in version 0.18.
-
LibraryController.
search
(query=None, uris=None, exact=False, **kwargs)[source]¶ Search the library for tracks where
field
containsvalues
.field
can be one ofuri
,track_name
,album
,artist
,albumartist
,composer
,performer
,track_no
,genre
,date
,comment
orany
.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']}) # 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: Return type: list of
mopidy.models.SearchResult
New in version 1.0: The
exact
keyword argument, which replacesfind_exact()
.Deprecated since version 1.0: Previously, if the query was empty, and the backend could support it, all available tracks were returned. This has not changed, but it is strongly discouraged. No new code should rely on this behavior.
Deprecated since version 1.1: Providing the search query via
kwargs
is no longer supported.
-
LibraryController.
lookup
(uri=None, uris=None)[source]¶ Lookup the given URIs.
If the URI expands to multiple tracks, the returned list will contain them all.
Parameters: - uri (string or
None
) -- track URI - uris (list of string or
None
) -- track URIs
Return type: list of
mopidy.models.Track
if uri was set or {uri: list ofmopidy.models.Track
} if uris was set.New in version 1.0: The
uris
argument.Deprecated since version 1.0: The
uri
argument. Useuris
instead.- uri (string or
-
LibraryController.
refresh
(uri=None)[source]¶ Refresh library. Limit to URI and below if an URI is given.
Parameters: uri (string) -- directory or track URI
-
LibraryController.
get_images
(uris)[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.
Parameters: uris (list of string) -- list of URIs to find images for Return type: {uri: tuple of mopidy.models.Image
}New in version 1.0.
-
LibraryController.
get_distinct
(field, query=None)[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.
Parameters: Return type: set of values corresponding to the requested field type.
New in version 1.0.
Playlists controller¶
-
class
mopidy.core.
PlaylistsController
¶
-
PlaylistsController.
get_uri_schemes
()[source]¶ Get the list of URI schemes that support playlists.
Return type: list of string New in version 2.0.
Fetching¶
-
PlaylistsController.
as_list
()[source]¶ Get a list of the currently available playlists.
Returns a list of
Ref
objects referring to the playlists. In other words, no information about the playlists' content is given.Return type: list of mopidy.models.Ref
New in version 1.0.
-
PlaylistsController.
get_items
(uri)[source]¶ Get the items in a playlist specified by
uri
.Returns a list of
Ref
objects referring to the playlist's items.If a playlist with the given
uri
doesn't exist, it returnsNone
.Return type: list of mopidy.models.Ref
, orNone
New in version 1.0.
-
PlaylistsController.
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
-
PlaylistsController.
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
Manipulating¶
-
PlaylistsController.
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 must be created by calling this method, and not by creating new instances of
mopidy.models.Playlist
.Parameters: - name (string) -- name of the new playlist
- uri_scheme (string) -- use the backend matching the URI scheme
Return type: mopidy.models.Playlist
orNone
-
PlaylistsController.
save
(playlist)[source]¶ Save the playlist.
For a playlist to be saveable, it must have the
uri
attribute set. You must 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 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
None
is returned.Parameters: playlist ( mopidy.models.Playlist
) -- the playlistReturn type: mopidy.models.Playlist
orNone
-
PlaylistsController.
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.
Returns
True
if deleted,False
otherwise.Parameters: uri (string) -- URI of the playlist to delete Return type: bool
Changed in version 2.2: Return type defined.
Mixer controller¶
-
class
mopidy.core.
MixerController
¶
-
MixerController.
set_mute
(mute)[source]¶ Set mute state.
True
to mute,False
to unmute.Returns
True
if call is successful, otherwiseFalse
.
History controller¶
-
class
mopidy.core.
HistoryController
¶
-
HistoryController.
get_history
()[source]¶ Get the track history.
The timestamps are milliseconds since epoch.
Returns: the track history Return type: list of (timestamp, mopidy.models.Ref
) tuples
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)[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
-
playlist_deleted
(uri)[source]¶ Called whenever a playlist is deleted.
MAY be implemented by actor.
Parameters: uri (string) -- the URI of the deleted 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
-
stream_title_changed
(title)[source]¶ Called whenever the currently playing stream title changes.
MAY be implemented by actor.
Parameters: title (string) -- the new stream title
-
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
-
Deprecated API features¶
Warning
Though these features still work, they are slated to go away in the next major Mopidy release.
Core¶
-
Core.
version
¶ Deprecated since version 1.0: Use
get_version()
instead.
-
Core.
uri_schemes
¶ Deprecated since version 1.0: Use
get_uri_schemes()
instead.
TracklistController¶
-
TracklistController.
tl_tracks
¶ Deprecated since version 1.0: Use
get_tl_tracks()
instead.
-
TracklistController.
tracks
¶ Deprecated since version 1.0: Use
get_tracks()
instead.
-
TracklistController.
version
¶ Deprecated since version 1.0: Use
get_version()
instead.
-
TracklistController.
length
¶ Deprecated since version 1.0: Use
get_length()
instead.
-
TracklistController.
consume
¶ Deprecated since version 1.0: Use
get_consume()
andset_consume()
instead.
-
TracklistController.
random
¶ Deprecated since version 1.0: Use
get_random()
andset_random()
instead.
-
TracklistController.
repeat
¶ Deprecated since version 1.0: Use
get_repeat()
andset_repeat()
instead.
-
TracklistController.
single
¶ Deprecated since version 1.0: Use
get_single()
andset_single()
instead.
PlaybackController¶
-
PlaybackController.
get_mute
()[source]¶ Deprecated since version 1.0: Use
core.mixer.get_mute()
instead.
-
PlaybackController.
get_volume
()[source]¶ Deprecated since version 1.0: Use
core.mixer.get_volume()
instead.
-
PlaybackController.
current_tl_track
¶ Deprecated since version 1.0: Use
get_current_tl_track()
instead.
-
PlaybackController.
current_track
¶ Deprecated since version 1.0: Use
get_current_track()
instead.
-
PlaybackController.
state
¶ Deprecated since version 1.0: Use
get_state()
andset_state()
instead.
-
PlaybackController.
time_position
¶ Deprecated since version 1.0: Use
get_time_position()
instead.
-
PlaybackController.
mute
¶ Deprecated since version 1.0: Use
core.mixer.get_mute()
andcore.mixer.set_mute()
instead.
-
PlaybackController.
volume
¶ Deprecated since version 1.0: Use
core.mixer.get_volume()
andcore.mixer.set_volume()
instead.
LibraryController¶
PlaylistsController¶
-
PlaylistsController.
filter
(criteria=None, **kwargs)[source]¶ Filter playlists by the given criterias.
Examples:
# Returns track with name 'a' filter({'name': 'a'}) # Returns track with URI 'xyz' filter({'uri': 'xyz'}) # Returns track with name 'a' and URI 'xyz' filter({'name': 'a', 'uri': 'xyz'})
Parameters: criteria (dict) -- one or more criteria to match by Return type: list of mopidy.models.Playlist
Deprecated since version 1.0: Use
as_list()
and filter yourself.
-
PlaylistsController.
get_playlists
(include_tracks=True)[source]¶ Get the available playlists.
Return type: list of mopidy.models.Playlist
Changed in version 1.0: If you call the method with
include_tracks=False
, thelast_modified
field of the returned playlists is no longer set.Deprecated since version 1.0: Use
as_list()
andget_items()
instead.
-
PlaylistsController.
playlists
¶ Deprecated since version 1.0: Use
as_list()
andget_items()
instead.