### Navigation

- index
- modules |
- next |
- previous |
- Mopidy 1.0.2 documentation »
- API reference »

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

  Audio output through GStreamer.

  `emit_data`(buffer_)

    Call this to deliver raw audio data to be played.

    If the buffer is `None`, the end-of-stream token is put on the playbin. We will get a GStreamer message when the stream playback reaches the token, and can then do any end-of-stream related tasks.

    Note that the URI must be set to `appsrc://` for this to work.

    Returns `True` if data was delivered.

    Parameters: | buffer (`gst.Buffer` or `None`) – buffer to pass to appsrc
    Return type: | boolean

  `emit_end_of_stream`()

    Put an end-of-stream token on the playbin. This is typically used in combination with `emit_data()`.

    We will get a GStreamer message when the stream playback reaches the token, and can then do any end-of-stream related tasks.

    Deprecated since version 1.0: Use `emit_data()` with a `None` buffer instead.

  `enable_sync_handler`()

    Enable manual processing of messages from bus.

    Should only be used by tests.

  `get_current_tags`()

    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 changes tags. After such calls users may call this function to get the updated values.

    Return type: | {key: [values]} dict for the current media.

  `get_position`()

    Get position in milliseconds.

    Return type: | int

  `mixer` = None

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

  `pause_playback`()

    Notify GStreamer that it should pause playback.

    Return type: | `True` if successfull, else `False`

  `prepare_change`()

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

  `set_about_to_finish_callback`(callback)

    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: | callback (callable) – Callback to run when we need the next URI.

  `set_appsrc`(caps, need_data=None, enough_data=None, seek_data=None)

    Switch to using appsrc for getting audio to be played.

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

    Parameters: | caps (string) – GStreamer caps string describing the audio format to expect need_data (callable which takes data length hint in ms) – callback for when appsrc needs data enough_data (callable) – callback for when appsrc has enough data seek_data (callable which takes time position in ms) – callback for when data from a new position is needed to continue playback

  `set_metadata`(track)

    Set track metadata for currently playing song.

    Only needs to be called by sources such as appsrc which do not already inject tags in playbin, e.g. when using `emit_data()` to deliver raw audio data to GStreamer.

    Parameters: | track (`mopidy.models.Track`) – the current track

  `set_position`(position)

    Set position in milliseconds.

    Parameters: | position (int) – the position in milliseconds
    Return type: | `True` if successful, else `False`

  `set_uri`(uri)

    Set URI of audio to be played.

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

    Parameters: | uri (string) – the URI to play

  `start_playback`()

    Notify GStreamer that it should start playback.

    Return type: | `True` if successfull, else `False`

  `state` = u'stopped'

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

  `stop_playback`()

    Notify GStreamer that is should stop playback.

    Return type: | `True` if successfull, else `False`

  `wait_for_state_change`()

    Block until any pending state changes are complete.

    Should only be used by tests.

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

    Called whenever the position of the stream changes.

    MAY be implemented by actor.

    Parameters: | position (int) – Position in milliseconds.

  `reached_end_of_stream`()

    Called whenever the end of the audio stream is reached.

    MAY be implemented by actor.

  static `send`(event, **kwargs)

    Helper to allow calling of audio listener events

  `state_changed`(old_state, new_state, target_state)

    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 (string from `mopidy.core.PlaybackState` field) – the state before the change new_state (string from `mopidy.core.PlaybackState` field) – the state after the change target_state (string from `mopidy.core.PlaybackState` field or `None` if this is a final state.) – the intended state

  `stream_changed`(uri)

    Called whenever the audio stream changes.

    MAY be implemented by actor.

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

  `tags_changed`(tags)

    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.

## Audio scanner

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

  Helper to get tags and other relevant info from URIs.

  Parameters: | timeout – timeout for scanning a URI in ms proxy_config – dictionary containing proxy config strings.

  `scan`(uri)

    Scan the given uri collecting relevant metadata.

    Parameters: | uri – URI of the resource to scan.
    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

`mopidy.audio.utils.``calculate_duration`(num_samples, sample_rate)

  Determine duration of samples using GStreamer helper for precise math.

`mopidy.audio.utils.``clocktime_to_millisecond`(value)

  Convert an internal GStreamer time to millisecond time.

`mopidy.audio.utils.``convert_taglist`(taglist)

  Convert a `gst.Taglist` to plain Python types.

  Knows how to convert:

  - Dates
  - Buffers
  - Numbers
  - Strings
  - Booleans

  Unknown types will be ignored and debug logged. Tag keys are all strings defined as part GStreamer under GstTagList.

  Parameters: | taglist (`gst.Taglist`) – A GStreamer taglist to be converted.
  Return type: | dictionary of tag keys with a list of values.

`mopidy.audio.utils.``convert_tags_to_track`(tags)

  Convert our normalized tags to a track.

  Parameters: | tags (`dict`) – dictionary of tag keys with a list of values
  Return type: | `mopidy.models.Track`

`mopidy.audio.utils.``create_buffer`(data, capabilites=None, timestamp=None, duration=None)

  Create a new GStreamer buffer based on provided data.

  Mainly intended to keep gst imports out of non-audio modules.

`mopidy.audio.utils.``millisecond_to_clocktime`(value)

  Convert a millisecond time to internal GStreamer time.

`mopidy.audio.utils.``setup_proxy`(element, config)

  Configure a GStreamer element with proxy settings.

  Parameters: | element (`gst.GstElement`) – element to setup proxy in. config (`dict`) – proxy settings to use.

`mopidy.audio.utils.``supported_uri_schemes`(uri_schemes)

  Determine which URIs we can actually support from provided whitelist.

  Parameters: | uri_schemes (list or set or URI schemes as strings.) – list/set of URIs to check support for.
  Return type: | set of URI schemes we can support via this GStreamer install.

### Navigation

- index
- modules |
- next |
- previous |
- Mopidy 1.0.2 documentation »
- API reference »