Skip to content

Media API

The media API reads media without playing it. Use it to get the metadata of a URI as a Track. It also reads the playlist entries of a playlist document, and finds the URI to play from the URI of a radio station with find_playback_target(). To parse a playlist document that you already have as bytes, use parse_playlist_entries().

Make one reader when your backend starts, and close it when your backend stops:

import pykka

from mopidy import backend
from mopidy.media import MediaReader
from mopidy.types import DurationMs


class MyBackend(pykka.ThreadingActor, backend.Backend):
    def __init__(self, *, config, audio):
        super().__init__(config=config, audio=audio)
        self.media_reader = MediaReader.create(config=config, timeout=DurationMs(5000))

    def on_stop(self) -> None:
        self.media_reader.close()

mopidy.media

Classes:

Functions:

EmbeddedImage

Bases: BaseModel

An image that is embedded in media, such as cover art.

Methods:

  • replace –

    Return a new instance with updated fields.

  • serialize –

    Serialize the model to a dict.

Attributes:

data instance-attribute

data: bytes

The image data.

replace

replace(**updated_fields: Any) -> Self

Return a new instance with updated fields.

serialize

serialize() -> dict[str, Any]

Serialize the model to a dict.

MediaInfo

Bases: BaseModel

The media info of one URI.

Methods:

  • replace –

    Return a new instance with updated fields.

  • serialize –

    Serialize the model to a dict.

Attributes:

images class-attribute instance-attribute

images: tuple[EmbeddedImage, ...] = ()

The images that are embedded in the media.

playable instance-attribute

playable: bool

If the media info reader decoded audio.

This does not tell if the playback engine can play the URI.

seekable instance-attribute

seekable: bool

If the media allows seeking.

track instance-attribute

track: Track

The metadata as a track.

track.uri is the URI that was read. track.length is the duration, or None if the duration is not known.

replace

replace(**updated_fields: Any) -> Self

Return a new instance with updated fields.

serialize

serialize() -> dict[str, Any]

Serialize the model to a dict.

MediaReader

MediaReader(
    *,
    media_info_reader: MediaInfoReader,
    timeout: DurationMs,
    http_client: Client | None = None,
)

Reads media without playing it.

Make a reader with create(). The reader is safe to call from many threads.

Methods:

close

close() -> None

Release the resources of the reader.

create classmethod

create(*, config: Config, timeout: DurationMs) -> Self

Make a reader.

Keep the reader, and close it with close() when you do not need it anymore.

Parameters:

  • config
    (Config) –

    The Mopidy config. The reader uses the proxy config.

  • timeout
    (DurationMs) –

    The timeout for each read, in milliseconds.

find_playback_target

find_playback_target(
    uri: Uri, *, timeout: DurationMs | None = None
) -> PlaybackTarget | None

Find the playback target for a URI.

The URI can be a playlist document, nested to any depth. For each playlist document, the alternatives of each entry are tried in order, and then the next entry. A URI that was tried before is not tried again. The timeout is the deadline for all reads.

Each URI is first read as a playlist document with read_playlist_entries(), so the body of an audio stream is not read. If the URI gives no playlist entries, it is read with read_media_info().

The reasons why each URI failed are logged.

Parameters:

  • uri
    (Uri) –

    The URI to find the playback target for.

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

    The deadline for all reads. The default is the timeout of the reader.

Returns:

  • PlaybackTarget | None –

    The first playable URI. If there is none, the first URI that was

  • PlaybackTarget | None –

    fetched, but that is not a playlist document and has no playable

  • PlaybackTarget | None –

    media info, as an unverified playback target. None if nothing is

  • PlaybackTarget | None –

    found.

read_media_info

read_media_info(uri: Uri, *, timeout: DurationMs | None = None) -> MediaInfo

Read the media info of one URI.

Only the given URI is read. If the URI is a playlist document, the media info is not playable.

Parameters:

  • uri
    (Uri) –

    The URI to read.

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

    The timeout. The default is the timeout of the reader.

Raises:

read_playlist_entries

read_playlist_entries(
    uri: Uri, *, timeout: DurationMs | None = None
) -> tuple[PlaylistEntry, ...]

Read the playlist entries of a playlist document.

The playlist document is fetched from a file, http or https URI, and parsed with parse_playlist_entries(). The HTTP Content-Type is the media type hint. Nested playlist documents are not read, and the media info of the entries is not read. The fetch stops at the first chunk that is not text, such as the body of an audio stream, and then there are no playlist entries.

Parameters:

  • uri
    (Uri) –

    The URI of the playlist document.

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

    The timeout. The default is the timeout of the reader.

Returns:

  • tuple[PlaylistEntry, ...] –

    The playlist entries, in the order of the playlist document.

Raises:

  • MediaReaderError –

    If the scheme is not file, http or https, if the fetch fails, if the document is larger than 10 MiB, or on a timeout.

MediaReaderError

Bases: MopidyException

Raised when a URI cannot be read, or when a read times out.

PlaybackTarget

Bases: BaseModel

The URI to give to the playback engine, found from another URI.

Methods:

  • replace –

    Return a new instance with updated fields.

  • serialize –

    Serialize the model to a dict.

Attributes:

entry instance-attribute

entry: PlaylistEntry | None

The playlist entry that the URI came from.

This is the entry in the last playlist document, or None if the first URI was the playback target.

info instance-attribute

info: MediaInfo | None

The media info of the URI.

None if the URI could not be read, but is not a playlist document. Then the playback target is not verified, and the playback engine can still try to play it.

uri instance-attribute

uri: Uri

The URI to play.

replace

replace(**updated_fields: Any) -> Self

Return a new instance with updated fields.

serialize

serialize() -> dict[str, Any]

Serialize the model to a dict.

PlaylistEntry

Bases: BaseModel

One entry in a playlist document.

Methods:

  • replace –

    Return a new instance with updated fields.

  • serialize –

    Serialize the model to a dict.

Attributes:

  • alternatives (tuple[Uri, ...]) –

    The URIs of the entry, in the order of the playlist document.

  • track (Track) –

    The metadata of the entry as a track.

alternatives instance-attribute

alternatives: tuple[Uri, ...]

The URIs of the entry, in the order of the playlist document.

There is at least one alternative.

track instance-attribute

track: Track

The metadata of the entry as a track.

track.uri is the first alternative. track.name and track.length are set if the playlist document has them.

replace

replace(**updated_fields: Any) -> Self

Return a new instance with updated fields.

serialize

serialize() -> dict[str, Any]

Serialize the model to a dict.

parse_playlist_entries

parse_playlist_entries(
    data: bytes,
    *,
    base_uri: str,
    encoding: str = "utf-8",
    media_type: str | None = None,
    uri: str | None = None,
) -> tuple[PlaylistEntry, ...]

Parse the playlist entries of a playlist document.

The formats are M3U, with and without the #EXTM3U header, PLS, XSPF, ASX, ASX reference and URI list. The content decides the format. media_type and uri are only hints for which format to try first.

HLS and DASH documents give no entries. Content that is not a playlist document also gives no entries.

Parameters:

  • data

    (bytes) –

    The content of the playlist document.

  • base_uri

    (str) –

    The URI to join relative entries with.

  • encoding

    (str, default: 'utf-8' ) –

    The encoding of data. Bytes that do not decode are replaced.

  • media_type

    (str | None, default: None ) –

    The media type of the playlist document, such as the HTTP Content-Type.

  • uri

    (str | None, default: None ) –

    The URI of the playlist document.

Returns:

  • tuple[PlaylistEntry, ...] –

    The playlist entries, in the order of the playlist document.