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)

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

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)

change_track(tl_track, on_error_step=1)

Change to the given track, keeping the current playback state.

Parameters:

• tl_track (mopidy.models.TlTrack or None) – 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

current_tl_track = None

The currently playing or selected mopidy.models.TlTrack, or None.

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

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

Tell the playback controller that end of track is reached.

Used by event handler in mopidy.core.Core.

on_tracklist_change()

Tell the playback controller that the current playlist has changed.

Used by mopidy.core.TracklistController.

pause()

Pause playback.

play(tl_track=None, on_error_step=1)

Play the given track, or if the given track is None, play the currently active track.

Parameters:

• tl_track (mopidy.models.TlTrack or None) – 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

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.

resume()

If paused, resume playing the current track.

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

state

The playback state. Must be PLAYING, PAUSED, or STOPPED.

Possible states and transitions:

stop(clear_current_track=False)

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)

add(tracks=None, at_position=None, uri=None)

Add the track or list of tracks to the tracklist.

If uri is given instead of tracks, 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. 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) – 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

clear()

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)

The track that will be played after the given track.

Not necessarily the same track as next_track().

Parameters:tl_track (mopidy.models.TlTrack or None) – the reference track Return type:mopidy.models.TlTrack or None

filter(criteria=None, **kwargs)

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)

The position of the given track in the tracklist.

Parameters:tl_track (mopidy.models.TlTrack) – the track to find the index of Return type:int or None

length

Length of the tracklist.

mark_played(tl_track)

Private method used by mopidy.core.PlaybackController.

mark_playing(tl_track)

Private method used by mopidy.core.PlaybackController.

mark_unplayable(tl_track)

Private method used by mopidy.core.PlaybackController.

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

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.

Parameters:tl_track (mopidy.models.TlTrack or None) – the reference track Return type:mopidy.models.TlTrack or None

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.

Parameters:tl_track (mopidy.models.TlTrack or None) – the reference track Return type:mopidy.models.TlTrack or None

random

True

Tracks are selected at random from the tracklist.

False

Tracks are played in the order of the tracklist.

remove(criteria=None, **kwargs)

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

True

The tracklist is played repeatedly. To repeat a single track, select both repeat and single.

False

The tracklist is played once.

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

single

True

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

False

Playback continues after current song.

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

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)

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 should 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

delete(uri)

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)

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)

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

playlists

The available playlists.

Read-only. List of mopidy.models.Playlist.

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

save(playlist)

Save the playlist.

For a playlist to be saveable, it must have the uri attribute set. You should 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 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 playlist Return type:mopidy.models.Playlist or None

Library controller

Manages the music library, e.g. searching for tracks to be added to a playlist.

class mopidy.core.LibraryController(backends, core)

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

find_exact(query=None, uris=None, **kwargs)

Search the library for tracks where field is values.

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 passing uris=['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)

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)

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)

Search the library for tracks where field contains values.

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 passing uris=['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

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

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

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]