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:
-
EmbeddedImage–An image that is embedded in media, such as cover art.
-
MediaInfo–The media info of one URI.
-
MediaReader–Reads media without playing it.
-
MediaReaderError–Raised when a URI cannot be read, or when a read times out.
-
PlaybackTarget–The URI to give to the playback engine, found from another URI.
-
PlaylistEntry–One entry in a playlist document.
Functions:
-
parse_playlist_entries–Parse the playlist entries of a playlist document.
EmbeddedImage
Bases: BaseModel
An image that is embedded in media, such as cover art.
Methods:
Attributes:
MediaInfo
Bases: BaseModel
The media info of one URI.
Methods:
Attributes:
-
images(tuple[EmbeddedImage, ...]) –The images that are embedded in the media.
-
playable(bool) –If the media info reader decoded audio.
-
seekable(bool) –If the media allows seeking.
-
track(Track) –The metadata as a track.
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.
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.
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–Release the resources of the reader.
-
create–Make a reader.
-
find_playback_target–Find the playback target for a URI.
-
read_media_info–Read the media info of one URI.
-
read_playlist_entries–Read the playlist entries of a playlist document.
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:
-
(configConfig) –The Mopidy config. The reader uses the proxy config.
-
(timeoutDurationMs) –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:
-
(uriUri) –The URI to find the playback target for.
-
(timeoutDurationMs | 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.
Noneif 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:
-
(uriUri) –The URI to read.
-
(timeoutDurationMs | None, default:None) –The timeout. The default is the timeout of the reader.
Raises:
-
MediaReaderError–If the URI cannot be read, or on a timeout.
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:
-
(uriUri) –The URI of the playlist document.
-
(timeoutDurationMs | 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,httporhttps, 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:
Attributes:
-
entry(PlaylistEntry | None) –The playlist entry that the URI came from.
-
info(MediaInfo | None) –The media info of the URI.
-
uri(Uri) –The URI to play.
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.
PlaylistEntry
Bases: BaseModel
One entry in a playlist document.
Methods:
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
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.
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:
-
(databytes) –The content of the playlist document.
-
(base_uristr) –The URI to join relative entries with.
-
(encodingstr, default:'utf-8') –The encoding of
data. Bytes that do not decode are replaced. -
(media_typestr | None, default:None) –The media type of the playlist document, such as the HTTP
Content-Type. -
(uristr | None, default:None) –The URI of the playlist document.
Returns:
-
tuple[PlaylistEntry, ...]–The playlist entries, in the order of the playlist document.