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)

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.

get_uri_schemes()

Get list of URI schemes we can handle

get_version()

Get version of the Mopidy core API

Tracklist controller

class mopidy.core.TracklistController(core)

Manipulating

TracklistController.add(tracks=None, at_position=None, uris=None)

Add tracks to the tracklist.

If uris is given instead of tracks, 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. If at_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 or None) – tracks to add

• at_position (int or None) – position in tracklist to add tracks

• 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 argument. Use uris.

TracklistController.remove(criteria)

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, of (string, list) pairs) – one or more rules to match by

Return type:

list of mopidy.models.TlTrack that were removed

TracklistController.clear()

Clear the tracklist.

Triggers the mopidy.core.CoreListener.tracklist_changed() event.

TracklistController.move(start, end, to_position)

Move the tracks in the slice [start:end] to to_position.

Triggers the mopidy.core.CoreListener.tracklist_changed() event.

Parameters:

• start (int) – position of first track to move

• end (int) – position after last track to move

• to_position (int) – new position for the tracks

TracklistController.shuffle(start=None, end=None)

Shuffles the entire tracklist. If start and end 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

Current state

TracklistController.get_tl_tracks()

Get tracklist as list of mopidy.models.TlTrack.

TracklistController.index(tl_track=None, tlid=None)

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 or None) – the track to find the index of

• tlid (int or None) – TLID of the track to find the index of

Return type:

int or None

New in version 1.1: The tlid parameter

TracklistController.get_version()

Get the tracklist version.

Integer which is increased every time the tracklist is changed. Is not reset before Mopidy is restarted.

TracklistController.get_length()

Get length of the tracklist.

TracklistController.get_tracks()

Get tracklist as list of mopidy.models.Track.

TracklistController.slice(start, end)

Returns a slice of the tracklist, limited by the given start and end positions.

Parameters:

• start (int) – position of first track to include in slice

• end (int) – position after last track to include in slice

Return type:

mopidy.models.TlTrack

TracklistController.filter(criteria)

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']})

Parameters:

criteria (dict, of (string, list) pairs) – one or more rules to match by

Return type:

list of mopidy.models.TlTrack

Future state

TracklistController.get_eot_tlid()

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 or None

New in version 1.1.

TracklistController.get_next_tlid()

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 or None

New in version 1.1.

TracklistController.get_previous_tlid()

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 or None

New in version 1.1.

TracklistController.eot_track(tl_track)

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.

Parameters:

tl_track (mopidy.models.TlTrack or None) – the reference track

Return type:

mopidy.models.TlTrack or None

TracklistController.next_track(tl_track)

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.

Parameters:

tl_track (mopidy.models.TlTrack or None) – the reference track

Return type:

mopidy.models.TlTrack or None

TracklistController.previous_track(tl_track)

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.

Parameters:

tl_track (mopidy.models.TlTrack or None) – the reference track

Return type:

mopidy.models.TlTrack or None

Options

TracklistController.get_consume()

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)

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()

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)

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()

Get repeat mode.

True

The tracklist is played repeatedly.

False

The tracklist is played once.

TracklistController.set_repeat(value)

Set repeat mode.

To repeat a single track, set both repeat and single.

True

The tracklist is played repeatedly.

False

The tracklist is played once.

TracklistController.get_single()

Get single mode.

True

Playback is stopped after current song, unless in repeat mode.

False

Playback continues after current song.

TracklistController.set_single(value)

Set single mode.

True

Playback is stopped after current song, unless in repeat mode.

False

Playback continues after current song.

Playback controller

class mopidy.core.PlaybackController(audio, backends, core)

Playback control

PlaybackController.play(tl_track=None, tlid=None)

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.

Deprecated since version 3.0: The tl_track argument. Use tlid instead.

Parameters:

• tl_track (mopidy.models.TlTrack or None) – track to play

• tlid (int or None) – TLID of the track to play

PlaybackController.next()

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.

PlaybackController.previous()

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.

PlaybackController.stop()

Stop playing.

PlaybackController.pause()

Pause playback.

PlaybackController.resume()

If paused, resume playing the current track.

PlaybackController.seek(time_position)

Seeks to time position given in milliseconds.

Parameters:

time_position (int) – time position in milliseconds

Return type:

True if successful, else False

Current track

PlaybackController.get_current_tl_track()

Get the currently playing or selected track.

Returns a mopidy.models.TlTrack or None.

PlaybackController.get_current_track()

Get the currently playing or selected track.

Extracted from get_current_tl_track() for convenience.

Returns a mopidy.models.Track or None.

PlaybackController.get_current_tlid()

Get the currently playing or selected TLID.

Extracted from get_current_tl_track() for convenience.

Returns a int or None.

New in version 1.1.

PlaybackController.get_stream_title()

Get the current stream title or None.

PlaybackController.get_time_position()

Get time position in milliseconds.

Playback states

PlaybackController.get_state()

Get The playback state.

PlaybackController.set_state(new_state)

Set the playback state.

Must be PLAYING, PAUSED, or STOPPED.

Possible states and transitions:

class mopidy.core.PlaybackState

STOPPED = 'stopped'

PLAYING = 'playing'

PAUSED = 'paused'

Library controller

class mopidy.core.LibraryController

LibraryController.browse(uri)

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 given uri.

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, uris=None, exact=False)

Search the library for tracks where field contains values.

field can be one of uri, track_name, album, artist, albumartist, composer, performer, track_no, genre, date, comment, disc_no, musicbrainz_albumid, musicbrainz_artistid, musicbrainz_trackid or any.

If uris is given, the search is limited to results from within the URI roots. For example passing uris=['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) – one or more queries to search for

• uris (list of string or None) – zero or more URI roots to limit the search to

• exact (bool) – if the search should use exact matching

Return type:

list of mopidy.models.SearchResult

New in version 1.0: The exact keyword argument.

LibraryController.lookup(uris)

Lookup the given URIs.

If the URI expands to multiple tracks, the returned list will contain them all.

Parameters:

uris (list of string) – track URIs

Return type:

{uri: list of mopidy.models.Track}

LibraryController.refresh(uri=None)

Refresh library. Limit to URI and below if an URI is given.

Parameters:

uri (string) – directory or track URI

LibraryController.get_images(uris)

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)

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:

• field (string) – Any one of uri, track_name, album, artist, albumartist, composer, performer, track_no, genre, date, comment, disc_no, musicbrainz_albumid, musicbrainz_artistid, or musicbrainz_trackid.

• query (dict) – Query to use for limiting results, see search() for details about the query format.

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()

Get the list of URI schemes that support playlists.

Return type:

list of string

New in version 2.0.

Fetching

PlaylistsController.as_list()

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)

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 returns None.

Return type:

list of mopidy.models.Ref, or None

New in version 1.0.

PlaylistsController.lookup(uri)

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 or None

PlaylistsController.refresh(uri_scheme=None)

Refresh the playlists in playlists.

If uri_scheme is None, all backends are asked to refresh. If uri_scheme is an URI scheme handled by a backend, only that backend is asked to refresh. If uri_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)

Create a new playlist.

If uri_scheme matches an URI scheme handled by a current backend, that backend is asked to create the playlist. If uri_scheme is None 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 or None

PlaylistsController.save(playlist)

Save the playlist.

For a playlist to be saveable, it must have the uri attribute set. You must not set the uri atribute yourself, but use playlist objects returned by create() or retrieved from playlists, 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 playlist

Return type:

mopidy.models.Playlist or None

PlaylistsController.delete(uri)

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.get_mute()

Get mute state.

True if muted, False unmuted, None if unknown.

MixerController.set_mute(mute)

Set mute state.

True to mute, False to unmute.

Returns True if call is successful, otherwise False.

MixerController.get_volume()

Get the volume.

Integer in range [0..100] or None if unknown.

The volume scale is linear.

MixerController.set_volume(volume)

Set the volume.

The volume is defined as an integer in range [0..100].

The volume scale is linear.

Returns True if call is successful, otherwise False.

History controller

class mopidy.core.HistoryController

HistoryController.get_history()

Get the track history.

The timestamps are milliseconds since epoch.

Returns:

the track history

Return type:

list of (timestamp, mopidy.models.Ref) tuples

HistoryController.get_length()

Get the number of tracks in the history.

Returns:

the history length

Return type:

int

Core events

class mopidy.core.CoreListener

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)

Called whenever the mute state is changed.

MAY be implemented by actor.

Parameters:

mute (boolean) – the new mute state

on_event(event, **kwargs)

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

options_changed()

Called whenever an option is changed.

MAY be implemented by actor.

playback_state_changed(old_state, new_state)

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

playlist_changed(playlist)

Called whenever a playlist is changed.

MAY be implemented by actor.

Parameters:

playlist (mopidy.models.Playlist) – the changed playlist

playlist_deleted(uri)

Called whenever a playlist is deleted.

MAY be implemented by actor.

Parameters:

uri (string) – the URI of the deleted playlist

playlists_loaded()

Called when playlists are loaded or refreshed.

MAY be implemented by actor.

seeked(time_position)

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

static send(event, **kwargs)

Helper to allow calling of core listener events

stream_title_changed(title)

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)

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

track_playback_paused(tl_track, time_position)

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

track_playback_resumed(tl_track, time_position)

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

track_playback_started(tl_track)

Called whenever a new track starts playing.

MAY be implemented by actor.

Parameters:

tl_track (mopidy.models.TlTrack) – the track that just started playing

tracklist_changed()

Called whenever the tracklist is changed.

MAY be implemented by actor.

volume_changed(volume)

Called whenever the volume is changed.

MAY be implemented by actor.

Parameters:

volume (int) – the new volume in the range [0..100]