Core API — Mopidy 1.0.8 documentation

# 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, audio=None)
  `get_uri_schemes`()

    Get list of URI schemes we can handle

  `get_version`()

    Get version of the Mopidy core API

  `history` = None

    The playback history controller. An instance of `mopidy.core.HistoryController`.

  `library` = None

    The library controller. An instance of `mopidy.core.LibraryController`.

  `mixer` = None

    The mixer controller. An instance of `mopidy.core.MixerController`.

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

    Deprecated since version 1.0: Use `get_uri_schemes()` instead.

  `version`

    Deprecated since version 1.0: Use `get_version()` instead.

## 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`(backends, core)
  `current_tl_track`

    Deprecated since version 1.0: Use `get_current_tl_track()` instead.

  `current_track`

    Deprecated since version 1.0: Use `get_current_track()` instead.

  `get_current_tl_track`()

    Get the currently playing or selected track.

    Returns a `mopidy.models.TlTrack` or `None`.

  `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`.

  `get_mute`()

    Deprecated since version 1.0: Use `core.mixer.get_mute()` instead.

  `get_state`()

    Get The playback state.

  `get_stream_title`()

    Get the current stream title or `None`.

  `get_time_position`()

    Get time position in milliseconds.

  `get_volume`()

    Deprecated since version 1.0: Use `core.mixer.get_volume()` instead.

  `mute`

    Deprecated since version 1.0: Use `core.mixer.get_mute()` and `core.mixer.set_mute()` instead.

  `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.

  `pause`()

    Pause playback.

  `play`(tl_track=None)

    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

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

  `set_mute`(mute)

    Deprecated since version 1.0: Use `core.mixer.set_mute()` instead.

  `set_state`(new_state)

    Set the playback state.

    Must be `PLAYING`, `PAUSED`, or `STOPPED`.

    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" ] }

  `set_volume`(volume)

    Deprecated since version 1.0: Use `core.mixer.set_volume()` instead.

  `state`

    Deprecated since version 1.0: Use `get_state()` and `set_state()` instead.

  `stop`()

    Stop playing.

  `time_position`

    Deprecated since version 1.0: Use `get_time_position()` instead.

  `volume`

    Deprecated since version 1.0: Use `core.mixer.get_volume()` and `core.mixer.set_volume()` instead.

## 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, uris=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 `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 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`

    New in version 1.0: The `uris` argument.

    Deprecated since version 1.0: The `tracks` and `uri` arguments. Use `uris`.

  `clear`()

    Clear the tracklist.

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

  `consume`

    Deprecated since version 1.0: Use `get_consume()` and `set_consume()` instead.

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

  `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.
  `get_length`()

    Get length of the tracklist.

  `get_random`()

    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 mode.

    `True`
      The tracklist is played repeatedly.
    `False`
      The tracklist is played once.
  `get_single`()

    Get single mode.

    `True`
      Playback is stopped after current song, unless in `repeat` mode.
    `False`
      Playback continues after current song.
  `get_tl_tracks`()

    Get tracklist as list of `mopidy.models.TlTrack`.

  `get_tracks`()

    Get tracklist as list of `mopidy.models.Track`.

  `get_version`()

    Get the tracklist version.

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

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

    Deprecated since version 1.0: Use `get_length()` instead.

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

    Deprecated since version 1.0: Use `get_random()` and `set_random()` instead.

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

    Deprecated since version 1.0: Use `get_repeat()` and `set_repeat()` instead.

  `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.
  `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.
  `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.
  `set_single`(value)

    Set single mode.

    `True`
      Playback is stopped after current song, unless in `repeat` mode.
    `False`
      Playback continues after current song.
  `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`

    Deprecated since version 1.0: Use `get_single()` and `set_single()` instead.

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

    Deprecated since version 1.0: Use `get_tl_tracks()` instead.

  `tracks`

    Deprecated since version 1.0: Use `get_tracks()` instead.

  `version`

    Deprecated since version 1.0: Use `get_version()` instead.

## History controller

Keeps record of what tracks have been played.

class `mopidy.core.` `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

  `get_length`()

    Get the number of tracks in the history.

    Returns: | the history length
    Return type: | int

## Playlists controller

Manages persistence of playlists.

class `mopidy.core.` `PlaylistsController`(backends, core)
  `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.

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

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

    Deprecated since version 1.0: Use `as_list()` and filter yourself.

  `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.

  `get_playlists`(include_tracks=True)

    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`, the `last_modified` field of the returned playlists is no longer set.

    Deprecated since version 1.0: Use `as_list()` and `get_items()` instead.

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

    Deprecated since version 1.0: Use `as_list()` and `get_items()` instead.

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

## 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`

    New in version 0.18.

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

    Search the library for tracks where `field` is `values`.

    Deprecated since version 1.0: Use `search()` with `exact` set.

  `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) – One of `track`, `artist`, `albumartist`, `album`, `composer`, `performer`, `date``or ``genre`. 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.

  `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) – list of URIs to find images for
    Return type: | {uri: tuple of `mopidy.models.Image`}

    New in version 1.0.

  `lookup`(uri=None, uris=None)

    Lookup the given URI.

    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 a {uri: list of `mopidy.models.Track`} if uris was set.

    New in version 1.0: The `uris` argument.

    Deprecated since version 1.0: The `uri` argument. Use `uris` instead.

  `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, exact=False, **kwargs)

    Search the library for tracks where `field` contains `values`.

    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.

    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`

    New in version 1.0: The `exact` keyword argument, which replaces `find_exact()`.

## Mixer controller

Manages volume and muting.

class `mopidy.core.` `MixerController`(mixer)
  `get_mute`()

    Get mute state.

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

  `get_volume`()

    Get the volume.

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

    The volume scale is linear.

  `set_mute`(mute)

    Set mute state.

    `True` to mute, `False` to unmute.

    Returns `True` if call is successful, otherwise `False`.

  `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`.

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

  `stream_title_changed`(title)

    Called whenever the currently playing stream title changes.

    MAY be implemented by actor.

  `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]