Skip to content

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:

mopidy.audio

Modules:

Classes:

Functions:

Audio

Audio output API.

There is only a single implementation of this API, using GStreamer.

The primary motivation for defining this API separate from the implementation is to make it a bit easier to mock the audio layer in tests. If we ever add more implementations, changes to this API will probably be necessary.

Methods:

Attributes:

state class-attribute instance-attribute 

state: PlaybackState = STOPPED

The GStreamer state mapped to PlaybackState.

get_current_tags 

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.

get_position 

get_position() -> DurationMs

Get position in milliseconds.

pause_playback 

pause_playback() -> bool

Pause playback.

Returns True if successful, else False.

prepare_change 

prepare_change() -> bool

Notify audio layer that we are about to change playback state.

This function MUST be called before changing URIs or doing changes like updating data that is being pushed.

set_about_to_finish_callback 

set_about_to_finish_callback(callback: Callable[[], None]) -> 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:

  • callback
    (Callable[[], None]) –

    Callback to run when we need the next URI.

set_position 

set_position(position: DurationMs) -> bool

Set position in milliseconds.

set_source_setup_callback 

set_source_setup_callback(callback: Callable[[Element], None]) -> None

Configure audio to use a source-setup callback.

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

Parameters:

  • callback
    (Callable[[Element], None]) –

    Callback to run when we set up the source.

set_uri 

set_uri(uri: str, live_stream: bool = False, download: bool = 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, default: False ) –

    Disables buffering, reducing latency for streams, and discarding data when paused.

  • download
    (bool, default: False ) –

    Enables "download" buffering mode.

start_playback 

start_playback() -> bool

Start playback.

Returns True if successful, else False.

stop_playback 

stop_playback() -> bool

Stop playback.

Returns True if successful, else False.

testing_gst__enable_sync_handler 

testing_gst__enable_sync_handler() -> None

Enable manual processing of messages from bus.

Not part of the API. Only for testing of GstAudio.

testing_gst__wait_for_state_change 

testing_gst__wait_for_state_change() -> None

Block until any pending playback state changes are complete.

Not part of the API. Only for testing of GstAudio.

AudioListener

Bases: Listener

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.

Methods:

  • on_event –

    Called on all events.

  • position_changed –

    Called whenever the position of the stream changes.

  • reached_end_of_stream –

    Called whenever the end of the audio stream is reached.

  • send –

    Helper to allow calling of audio listener events.

  • state_changed –

    Called after the playback state have changed.

  • stream_changed –

    Called whenever the audio stream changes.

  • tags_changed –

    Called whenever the current audio stream's tags change.

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.

position_changed 

position_changed(position: DurationMs) -> None

Called whenever the position of the stream changes.

MAY be implemented by actor.

Parameters:

  • position
    (DurationMs) –

    Position in milliseconds.

reached_end_of_stream 

reached_end_of_stream() -> None

Called whenever the end of the audio stream is reached.

MAY be implemented by actor.

send staticmethod 

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

Helper to allow calling of audio listener events.

state_changed 

state_changed(
    old_state: PlaybackState,
    new_state: PlaybackState,
    target_state: PlaybackState | None,
) -> 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
    (PlaybackState) –

    The state before the change.

  • new_state
    (PlaybackState) –

    The state after the change.

  • target_state
    (PlaybackState | None) –

    The intended state, or None if this is a final state.

stream_changed 

stream_changed(uri: Uri) -> None

Called whenever the audio stream changes.

MAY be implemented by actor.

Parameters:

  • uri
    (Uri) –

    URI the stream has started playing.

tags_changed 

tags_changed(tags: set[str]) -> 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[str]) –

    The tags that have just been updated.

AudioProxy

Bases: ActorMemberMixin, ActorProxy[AudioActor]

Audio layer wrapped in a Pykka actor proxy.

GstAudio 

GstAudio(config: Config, mixer: MixerProxy | None)

Bases: Audio, ThreadingActor

Audio output through GStreamer.

Attributes:

state class-attribute instance-attribute 

state: PlaybackState = STOPPED

The GStreamer state mapped to PlaybackState.

supported_uri_schemes 

supported_uri_schemes(uri_schemes: Iterable[UriScheme]) -> set[UriScheme]

Determine which URIs we can actually support from provided whitelist.

Parameters:

mopidy.audio.scan

Classes:

  • Scanner –

    Helper to get tags and other relevant info from URIs.

Scanner 

Scanner(timeout: int = 1000, proxy_config: ProxyConfig | None = None)

Helper to get tags and other relevant info from URIs.

Parameters:

  • timeout

    (int, default: 1000 ) –

    Timeout for scanning a URI in milliseconds.

  • proxy_config

    (ProxyConfig | None, default: None ) –

    Dictionary containing proxy config strings.

Methods:

  • scan –

    Scan the given URI collecting relevant metadata.

scan 

scan(uri: str, timeout: float | None = None) -> _Result

Scan the given URI collecting relevant metadata.

Parameters:

  • uri
    (str) –

    URI of the resource to scan.

  • timeout
    (float | None, default: None ) –

    Timeout for scanning in milliseconds. Defaults to the timeout value used when creating the scanner.

Returns:

  • _Result –

    Named tuple: uri, tags, duration, seekable, mime, playable.

mopidy.audio.tags

Functions:

convert_taglist 

convert_taglist(taglist: TagList) -> dict[str, list[Any]]

Convert a Gst.TagList to plain Python types.

Knows how to convert:

  • Dates
  • Buffers
  • Numbers
  • Strings
  • Booleans

Unknown types will be ignored and trace logged. Tag keys are all strings defined as part of GStreamer's GstTagList.

Parameters:

  • taglist

    (TagList) –

    A GStreamer taglist to be converted.

convert_tags_to_track 

convert_tags_to_track(
    tags: dict[str, Any],
    *,
    uri: Uri,
    length: DurationMs | None = None,
    last_modified: int | None = None,
) -> Track

Convert our normalized tags to a track.

repr_tags 

repr_tags(tags: dict[str, list[Any]], max_bytes: int = 10) -> str

Returns a printable representation of a Gst.TagList.

Tag values of type bytes are truncated to the specified length to avoid large amounts of output when logging.

Parameters:

  • tags

    (dict[str, list[Any]]) –

    A converted taglist to be represented.

  • max_bytes

    (int, default: 10 ) –

    The maximum number of bytes to show for bytes tag values.