Skip to content

Core API

mopidy.core

Classes:

Core 

Core(
    config: Config,
    *,
    mixer: MixerProxy | None = None,
    backends: Iterable[BackendProxy],
    audio: AudioProxy | None = None,
)

Bases: ThreadingActor, AudioListener, BackendListener, MixerListener

The main object of the Core API.

The core layer sits inbetween the frontends and the backends.

The core API is the interface that is used by frontends like mopidy-http and mopidy-mpd to control music playback.

Methods:

  • get_uri_schemes –

    Get list of URI schemes we can handle.

  • get_version –

    Get version of the Mopidy core API.

  • on_event –

    Called on all events.

  • send –

    Helper to allow calling of backend listener events.

Attributes:

history instance-attribute 

history: HistoryController = traversable(HistoryController())

The history controller.

library instance-attribute 

library: LibraryController = traversable(
    LibraryController(backends=backends, core=self)
)

The library controller.

mixer instance-attribute 

mixer: MixerController = traversable(MixerController(mixer=mixer))

The mixer controller.

playback instance-attribute 

playback: PlaybackController = traversable(
    PlaybackController(audio=audio, backends=backends, core=self)
)

The playback controller.

playlists instance-attribute 

playlists: PlaylistsController = traversable(
    PlaylistsController(backends=backends, core=self)
)

The playlists controller.

tracklist instance-attribute 

tracklist: TracklistController = traversable(TracklistController(core=self))

The tracklist controller.

get_uri_schemes 

get_uri_schemes() -> list[UriScheme]

Get list of URI schemes we can handle.

get_version 

get_version() -> str

Get version of the Mopidy core API.

on_event 

on_event(event: Any, **kwargs: Any) -> None

Called on all events.

MAY be implemented by actor. By default, this method forwards the event to the specific event methods.

Parameters:

  • event
    (Any) –

    The event name.

  • kwargs
    (Any, default: {} ) –

    Any other arguments to the specific event handlers.

send staticmethod 

send(event: str, **kwargs: Any) -> None

Helper to allow calling of backend listener events.

CoreListener

Bases: Listener

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.

Methods:

mute_changed 

mute_changed(mute: bool) -> None

Called whenever the mute state is changed.

MAY be implemented by actor.

Parameters:

  • mute
    (bool) –

    The new mute state.

on_event 

on_event(event: CoreEvent, **kwargs: CoreEventData) -> None

Called on all events.

MAY be implemented by actor. By default, this method forwards the event to the specific event methods.

Parameters:

  • event
    (CoreEvent) –

    The event name.

  • kwargs
    (CoreEventData, default: {} ) –

    Any other arguments to the specific event handlers.

options_changed 

options_changed() -> None

Called whenever an option is changed.

MAY be implemented by actor.

playback_state_changed 

playback_state_changed(
    old_state: PlaybackState, new_state: PlaybackState
) -> None

Called whenever playback state is changed.

MAY be implemented by actor.

Parameters:

playlist_changed 

playlist_changed(playlist: Playlist) -> None

Called whenever a playlist is changed.

MAY be implemented by actor.

Parameters:

  • playlist
    (Playlist) –

    The changed playlist.

playlist_deleted 

playlist_deleted(uri: Uri) -> None

Called whenever a playlist is deleted.

MAY be implemented by actor.

Parameters:

  • uri
    (Uri) –

    The URI of the deleted playlist.

playlists_loaded 

playlists_loaded() -> None

Called when playlists are loaded or refreshed.

MAY be implemented by actor.

seeked 

seeked(time_position: DurationMs) -> None

Called whenever the time position changes by an unexpected amount.

For example, at seek to a new time position.

MAY be implemented by actor.

Parameters:

  • time_position
    (DurationMs) –

    The position that was seeked to in milliseconds.

send staticmethod 

send(event: CoreEvent, **kwargs: Any) -> None

Helper to allow calling of core listener events.

stream_title_changed 

stream_title_changed(title: str) -> None

Called whenever the currently playing stream title changes.

MAY be implemented by actor.

Parameters:

  • title
    (str) –

    The new stream title.

track_playback_ended 

track_playback_ended(tl_track: TlTrack, time_position: DurationMs) -> None

Called whenever playback of a track ends.

MAY be implemented by actor.

Parameters:

  • tl_track
    (TlTrack) –

    The track that was played before playback stopped.

  • time_position
    (DurationMs) –

    The time position in milliseconds.

track_playback_paused 

track_playback_paused(tl_track: TlTrack, time_position: DurationMs) -> None

Called whenever track playback is paused.

MAY be implemented by actor.

Parameters:

  • tl_track
    (TlTrack) –

    The track that was playing when playback paused.

  • time_position
    (DurationMs) –

    The time position in milliseconds.

track_playback_resumed 

track_playback_resumed(tl_track: TlTrack, time_position: DurationMs) -> None

Called whenever track playback is resumed.

MAY be implemented by actor.

Parameters:

  • tl_track
    (TlTrack) –

    The track that was playing when playback resumed.

  • time_position
    (DurationMs) –

    The time position in milliseconds.

track_playback_started 

track_playback_started(tl_track: TlTrack) -> None

Called whenever a new track starts playing.

MAY be implemented by actor.

Parameters:

  • tl_track
    (TlTrack) –

    The track that just started playing.

tracklist_changed 

tracklist_changed() -> None

Called whenever the tracklist is changed.

MAY be implemented by actor.

volume_changed 

volume_changed(volume: Percentage) -> None

Called whenever the volume is changed.

MAY be implemented by actor.

Parameters:

  • volume
    (Percentage) –

    The new volume in the range [0..100].

HistoryController 

HistoryController()

Keeps record of what tracks have been played.

Methods:

get_history 

get_history() -> History

Get the track history.

Returns a list of two-tuples with timestamp and a reference to the track. The timestamps are milliseconds since epoch.

get_length 

get_length() -> int

Get the number of tracks in the history.

LibraryController 

LibraryController(backends: Backends, core: Core)

Manages browsing and searching for music.

Methods:

  • browse –

    Browse directories and tracks at the given uri.

  • get_distinct –

    List distinct values for a given field from the library.

  • get_images –

    Lookup the images for the given URIs.

  • lookup –

    Lookup the given URIs.

  • refresh –

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

  • search –

    Search the library for tracks where field contains values.

browse 

browse(uri: Uri | None) -> list[Ref]

Browse directories and tracks at the given uri.

uri is a string which represents some directory belonging to a backend. To get the initial root directories for backends pass None as the URI.

Returns a list of 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
    (Uri | None) –

    URI to browse.

get_distinct 

get_distinct(
    field: DistinctField, query: Query[SearchField] | None = None
) -> set[Any]

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

    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
    (Query[SearchField] | None, default: None ) –

    Query to use for limiting results, see search for details about the query format.

get_images 

get_images(uris: Iterable[Uri]) -> dict[Uri, tuple[Image, ...]]

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
    (Iterable[Uri]) –

    List of URIs to find images for.

lookup 

lookup(uris: Iterable[Uri]) -> dict[Uri, list[Track]]

Lookup the given URIs.

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

Parameters:

refresh 

refresh(uri: Uri | None = None) -> None

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

Parameters:

  • uri
    (Uri | None, default: None ) –

    Directory or track URI.

search 

search(
    query: Query[SearchField],
    uris: Iterable[Uri] | None = None,
    exact: bool = False,
) -> list[SearchResult]

Search the library for tracks where field contains values.

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
    (Query[SearchField]) –

    One or more queries to search for.

  • uris
    (Iterable[Uri] | None, default: None ) –

    Zero or more URI roots to limit the search to.

  • exact
    (bool, default: False ) –

    If the search should use exact matching.

MixerController 

MixerController(mixer: MixerProxy | None)

Manages volume and muting.

Methods:

get_mute 

get_mute() -> bool | None

Get mute state.

True if muted, False if unmuted, None if unknown.

get_volume 

get_volume() -> Percentage | None

Get the volume.

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

The volume scale is linear.

set_mute 

set_mute(mute: bool) -> bool

Set mute state.

True to mute, False to unmute.

Returns True if call is successful, otherwise False.

set_volume 

set_volume(volume: Percentage) -> bool

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.

PlaybackController 

PlaybackController(audio: AudioProxy | None, backends: Backends, core: Core)

Manages playback state and the currently playing track.

Methods:

  • get_current_tl_track –

    Get the currently playing or selected track.

  • get_current_tlid –

    Get the currently playing or selected tracklist ID.

  • get_current_track –

    Get the currently playing or selected track.

  • get_state –

    Get The playback state.

  • get_stream_title –

    Get the current stream title or None.

  • get_time_position –

    Get time position in milliseconds.

  • next –

    Change to the next track.

  • pause –

    Pause playback.

  • play –

    Play a track from the tracklist, specified by the tracklist ID.

  • previous –

    Change to the previous track.

  • resume –

    If paused, resume playing the current track.

  • seek –

    Seeks to time position given in milliseconds.

  • set_state –

    Set the playback state.

  • stop –

    Stop playing.

get_current_tl_track 

get_current_tl_track() -> TlTrack | None

Get the currently playing or selected track.

Returns a TlTrack or None.

get_current_tlid 

get_current_tlid() -> TracklistId | None

Get the currently playing or selected tracklist ID.

Extracted from get_current_tl_track for convenience.

get_current_track 

get_current_track() -> Track | None

Get the currently playing or selected track.

Extracted from get_current_tl_track for convenience.

Returns a Track or None.

get_state 

get_state() -> PlaybackState

Get The playback state.

get_stream_title 

get_stream_title() -> str | None

Get the current stream title or None.

get_time_position 

get_time_position() -> DurationMs

Get time position in milliseconds.

next 

next() -> None

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.

pause 

pause() -> None

Pause playback.

play 

play(tlid: TracklistId | None = None) -> None

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.

Parameters:

  • tlid
    (TracklistId | None, default: None ) –

    Tracklist ID of the track to play.

previous 

previous() -> None

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 

resume() -> None

If paused, resume playing the current track.

seek 

seek(time_position: DurationMs) -> bool

Seeks to time position given in milliseconds.

Returns True if successful, else False.

Parameters:

  • time_position
    (DurationMs) –

    Time position in milliseconds.

set_state 

set_state(new_state: PlaybackState) -> None

Set the playback state.

Internal API

This method is only for use by Mopidy itself and extension's test suites if it cannot be avoided.

Frontends and clients must use the play(), pause(), resume(), and stop() methods to change the playback state.

This method only maintains core's playback state and emits playback_state_changed events. It has no effect on the underlying backend or audio layers.

Possible states and transitions:

graph LR
    STOPPED -->|play| PLAYING;
    STOPPED -->|pause| PAUSED;
    PLAYING -->|stop| STOPPED;
    PLAYING -->|pause| PAUSED;
    PLAYING -->|play| PLAYING;
    PAUSED -->|resume| PLAYING;
    PAUSED -->|stop| STOPPED;

stop 

stop() -> None

Stop playing.

PlaylistsController 

PlaylistsController(backends: Backends, core: Core)

Manages stored playlists.

Methods:

  • as_list –

    Get a list of the currently available playlists.

  • create –

    Create a new playlist.

  • delete –

    Delete playlist identified by the URI.

  • get_items –

    Get the items in a playlist specified by uri.

  • get_uri_schemes –

    Get the list of URI schemes that support playlists.

  • lookup –

    Lookup playlist with given URI.

  • refresh –

    Refresh the playlists.

  • save –

    Save the playlist.

as_list 

as_list() -> list[Ref]

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.

create 

create(name: str, uri_scheme: UriScheme | None = None) -> Playlist | 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 Playlist.

Parameters:

  • name
    (str) –

    Name of the new playlist.

  • uri_scheme
    (UriScheme | None, default: None ) –

    Use the backend matching the URI scheme.

delete 

delete(uri: Uri) -> bool

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

    URI of the playlist to delete.

get_items 

get_items(uri: Uri) -> list[Ref] | None

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.

get_uri_schemes 

get_uri_schemes() -> list[UriScheme]

Get the list of URI schemes that support playlists.

lookup 

lookup(uri: Uri) -> Playlist | None

Lookup playlist with given URI.

Searches both the set of playlists and any other playlist sources. Returns None if not found.

Parameters:

  • uri
    (Uri) –

    Playlist URI.

refresh 

refresh(uri_scheme: UriScheme | None = None) -> None

Refresh the 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
    (UriScheme | None, default: None ) –

    Limit to the backend matching the URI scheme.

save 

save(playlist: Playlist) -> Playlist | None

Save the playlist.

For a playlist to be saveable, it must have the uri attribute set. You must not set the uri attribute 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:

TracklistController 

TracklistController(core: Core)

Manages the queued tracks.

Methods:

add 

add(
    tracks: Iterable[Track] | None = None,
    *,
    at_position: int | None = None,
    uris: Iterable[Uri] | None = None,
) -> list[TlTrack]

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 tracklist_changed event.

Parameters:

  • tracks
    (Iterable[Track] | None, default: None ) –

    Tracks to add.

  • at_position
    (int | None, default: None ) –

    Position in tracklist to add tracks.

  • uris
    (Iterable[Uri] | None, default: None ) –

    List of URIs for tracks to add.

clear 

clear() -> None

Clear the tracklist.

Triggers the tracklist_changed event.

eot_track 

eot_track(tl_track: TlTrack | None) -> TlTrack | None

The track that will be played after the given track.

Not necessarily the same track as next_track.

Deprecated: Use get_eot_tlid instead.

Parameters:

  • tl_track
    (TlTrack | None) –

    The reference track.

filter 

filter(criteria: Query[TracklistField]) -> list[TlTrack]

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:

get_consume 

get_consume() -> bool

Get consume mode.

True Tracks are removed from the tracklist when they have been played. False Tracks are not removed from the tracklist.

get_eot_tlid 

get_eot_tlid() -> TracklistId | None

The TLID of the track that will be played after the current track.

Not necessarily the same TLID as returned by get_next_tlid.

get_length 

get_length() -> int

Get length of the tracklist.

get_next_tlid 

get_next_tlid() -> TracklistId | None

The TLID of the next track.

The track that will be played if calling 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.

get_previous_tlid 

get_previous_tlid() -> TracklistId | None

Returns the TLID of the previous track.

The track that will be played if calling 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.

get_random 

get_random() -> bool

Get random mode.

True Tracks are selected at random from the tracklist. False Tracks are played in the order of the tracklist.

get_repeat 

get_repeat() -> bool

Get repeat mode.

True The tracklist is played repeatedly. False The tracklist is played once.

get_single 

get_single() -> bool

Get single mode.

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

get_tl_tracks 

get_tl_tracks() -> list[TlTrack]

Get tracklist as list of TlTrack.

get_tracks 

get_tracks() -> list[Track]

Get tracklist as list of Track.

get_version 

get_version() -> int

Get the tracklist version.

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

index 

index(
    tl_track: TlTrack | None = None, tlid: TracklistId | None = None
) -> int | 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
    (TlTrack | None, default: None ) –

    The track to find the index of.

  • tlid
    (TracklistId | None, default: None ) –

    TLID of the track to find the index of.

move 

move(start: int, end: int, to_position: int) -> None

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

Triggers the 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 

next_track(tl_track: TlTrack | None) -> TlTrack | None

The track that will be played if calling next.

Calls 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: Use get_next_tlid instead.

Parameters:

  • tl_track
    (TlTrack | None) –

    The reference track.

previous_track 

previous_track(tl_track: TlTrack | None) -> TlTrack | None

Returns the track that will be played if calling previous.

Calls 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: Use get_previous_tlid instead.

Parameters:

  • tl_track
    (TlTrack | None) –

    The reference track.

remove 

remove(criteria: Query[TracklistField]) -> list[TlTrack]

Remove the matching tracks from the tracklist.

Uses filter to lookup the tracks to remove.

Triggers the tracklist_changed event.

Returns the removed tracks.

Parameters:

set_consume 

set_consume(value: bool) -> None

Set consume mode.

True Tracks are removed from the tracklist when they have been played. False Tracks are not removed from the tracklist.

set_random 

set_random(value: bool) -> None

Set random mode.

True Tracks are selected at random from the tracklist. False Tracks are played in the order of the tracklist.

set_repeat 

set_repeat(value: bool) -> None

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.

set_single 

set_single(value: bool) -> None

Set single mode.

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

shuffle 

shuffle(start: int | None = None, end: int | None = None) -> None

Shuffle the entire tracklist, or a slice.

If start and end is given only shuffles the slice [start:end].

Triggers the tracklist_changed event.

Parameters:

  • start
    (int | None, default: None ) –

    Position of first track to shuffle.

  • end
    (int | None, default: None ) –

    Position after last track to shuffle.

slice 

slice(start: int, end: int) -> list[TlTrack]

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.