# `mopidy.audio` — Audio API

The audio API is the interface we have built around GStreamer to support our specific use cases. Most backends should be able to get by with simply setting the URI of the resource they want to play, for these cases the default playback provider should be used.

For more advanced cases such as when the raw audio data is delivered outside of GStreamer or the backend needs to add metadata to the currently playing resource, developers should sub-class the base playback provider and implement the extra behaviour that is needed through the following API:

class mopidy.audio.Audio(config, mixer) → None

  Audio output through GStreamer.

  enable_sync_handler() → None

    Enable manual processing of messages from bus.

    Should only be used by tests.

    Return type:

      `None`

  get_current_tags() → dict[str, list[Any]]

    Get the currently playing media’s tags.

    If no tags have been found, or nothing is playing this returns an empty dictionary. For each set of tags we collect a tags_changed event is emitted with the keys of the changed tags. After such calls users may call this function to get the updated values.

    Return type:

      `dict`[`str`, `list`[`Any`]]

  get_position() → DurationMs

    Get position in milliseconds.

    Return type:

      `NewType`(`DurationMs`, `int`)

  mixer: SoftwareMixerAdapter | None = None

    The software mixing interface `mopidy.audio.actor.SoftwareMixerAdapter`

  on_start() → None

    Run code at the beginning of the actor’s life.

    Hook for doing any setup that should be done after the actor is started, but before it starts processing messages.

    For `ThreadingActor`, this method is executed in the actor’s own thread, while `__init__()` is executed in the thread that created the actor.

    If an exception is raised by this method the stack trace will be logged, and the actor will stop.

    Return type:

      `None`

  on_stop() → None

    Run code at the end of the actor’s life.

    Hook for doing any cleanup that should be done after the actor has processed the last message, and before the actor stops.

    This hook is not called when the actor stops because of an unhandled exception. In that case, the `on_failure()` hook is called instead.

    For `ThreadingActor` this method is executed in the actor’s own thread, immediately before the thread exits.

    If an exception is raised by this method the stack trace will be logged, and the actor will stop.

    Return type:

      `None`

  pause_playback() → bool

    Notify GStreamer that it should pause playback.

    Returns `True` if successful, else `False`.

    Return type:

      `bool`

  prepare_change() → bool

    Notify GStreamer that we are about to change state of playback.

    This function MUST be called before changing URIs or doing changes like updating data that is being pushed. The reason for this is that GStreamer will reset all its state when it changes to `Gst.State.READY`.

    Return type:

      `bool`

  set_about_to_finish_callback(callback) → None

    Configure audio to use an about-to-finish callback.

    This should be used to achieve gapless playback. For this to work the callback MUST call `set_uri()` with the new URI to play and block until this call has been made. `prepare_change()` is not needed before `set_uri()` in this one special case.

    Parameters:

      callable – Callback to run when we need the next URI.

    Return type:

      `None`

  set_position(position) → bool

    Set position in milliseconds.

    Parameters:

      position (`NewType`(`DurationMs`, `int`)) – the position in milliseconds

    Return type:

      `bool`

  set_source_setup_callback(callback) → None

    Configure audio to use a source-setup callback.

    This should be used to modify source-specific properties such as login details.

    Parameters:

      callable – Callback to run when we setup the source.

    Return type:

      `None`

  set_uri(uri, live_stream=False, download=False) → None

    Set URI of audio to be played.

    You MUST call `prepare_change()` before calling this method.

    Parameters:

      - uri (`str`) – the URI to play

      - live_stream (`bool`) – disables buffering, reducing latency for stream, and discarding data when paused

      - download (`bool`) – enables “download” buffering mode

    Return type:

      `None`

  start_playback() → bool

    Notify GStreamer that it should start playback.

    Returns `True` if successful, else `False`.

    Return type:

      `bool`

  state: PlaybackState = 'stopped'

    The GStreamer state mapped to `mopidy.audio.PlaybackState`

  stop_playback() → bool

    Notify GStreamer that it should stop playback.

    Returns `True` if successful, else `False`.

    Return type:

      `bool`

  wait_for_state_change() → None

    Block until any pending state changes are complete.

    Should only be used by tests.

    Return type:

      `None`

## Audio listener

class mopidy.audio.AudioListener

  Marker interface for recipients of events sent by the audio 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.

  position_changed(position) → None

    Called whenever the position of the stream changes.

    MAY be implemented by actor.

    Parameters:

      position (int) – Position in milliseconds.

    Return type:

      `None`

  reached_end_of_stream() → None

    Called whenever the end of the audio stream is reached.

    MAY be implemented by actor.

    Return type:

      `None`

  static send(event, **kwargs) → None

    Helper to allow calling of audio listener events.

    Return type:

      `None`

  state_changed(old_state, new_state, target_state) → None

    Called after the playback state have changed.

    Will be called for both immediate and async state changes in GStreamer.

    Target state is used to when we should be in the target state, but temporarily need to switch to an other state. A typical example of this is buffering. When this happens an event with old=PLAYING, new=PAUSED, target=PLAYING will be emitted. Once we have caught up a old=PAUSED, new=PLAYING, target=None event will be be generated.

    Regular state changes will not have target state set as they are final states which should be stable.

    MAY be implemented by actor.

    Parameters:

      - old_state (`mopidy.audio.PlaybackState`) – the state before the change

      - new_state (`mopidy.audio.PlaybackState`) – the state after the change

      - target_state (`mopidy.audio.PlaybackState` or `None` if this is a final state.) – the intended state

    Return type:

      `None`

  stream_changed(uri) → None

    Called whenever the audio stream changes.

    MAY be implemented by actor.

    Parameters:

      uri (string) – URI the stream has started playing.

    Return type:

      `None`

  tags_changed(tags) → None

    Called whenever the current audio stream’s tags change.

    This event signals that some track metadata has been updated. This can be metadata such as artists, titles, organization, or details about the actual audio such as bit-rates, numbers of channels etc.

    For the available tag keys please refer to GStreamer documentation for tags.

    MAY be implemented by actor.

    Parameters:

      tags (`set` of strings) – The tags that have just been updated.

    Return type:

      `None`

## Audio scanner

class mopidy.audio.scan.Scanner(timeout=1000, proxy_config=None) → None

  Helper to get tags and other relevant info from URIs.

  Parameters:

    - timeout (`int`) – timeout for scanning a URI in ms

    - proxy_config (`dict`[`str`, `Any`] | `None`) – dictionary containing proxy config strings.

  scan(uri, timeout=None) → _Result

    Scan the given uri collecting relevant metadata.

    Parameters:

      - uri (string) – URI of the resource to scan.

      - timeout (int) – timeout for scanning a URI in ms. Defaults to the `timeout` value used when creating the scanner.

    Return type:

      `_Result`

    Returns:

      A named tuple containing `(uri, tags, duration, seekable, mime)`. `tags` is a dictionary of lists for all the tags we found. `duration` is the length of the URI in milliseconds, or `None` if the URI has no duration. `seekable` is boolean. indicating if a seek would succeed.

## Audio utils

class mopidy.audio.utils.Signals → None

  Helper for tracking gobject signal registrations.

  clear() → None

    Clear all registered signal handlers.

    Return type:

      `None`

  connect(element, event, func, *args) → None

    Connect a function + args to signal event on an element.

    Each event may only be handled by one callback in this implementation.

    Return type:

      `None`

  disconnect(element, event) → None

    Disconnect whatever handler we have for an element+event pair.

    Does nothing it the handler has already been removed.

    Return type:

      `None`

mopidy.audio.utils.clocktime_to_millisecond(value) → DurationMs

  Convert an internal GStreamer time to millisecond time.

  Return type:

    `NewType`(`DurationMs`, `int`)

mopidy.audio.utils.millisecond_to_clocktime(value) → int

  Convert a millisecond time to internal GStreamer time.

  Return type:

    `int`

mopidy.audio.utils.setup_proxy(element, config) → None

  Configure a GStreamer element with proxy settings.

  Parameters:

    - element (`Element`) – element to setup proxy in.

    - config (`ProxyConfig`) – proxy settings to use.

  Return type:

    `None`

mopidy.audio.utils.supported_uri_schemes(uri_schemes) → set[UriScheme]

  Determine which URIs we can actually support from provided whitelist.

  Parameters:

    uri_schemes (`Iterable`[`NewType`(`UriScheme`, `str`)]) – list/set of URIs to check support for.

  Return type:

    `set`[`NewType`(`UriScheme`, `str`)]