mock.data — resource data

Shared resource sources and dataclasses used by the data configuration surface.

Configuration surface

DataSources dataclass

DataSources(songs: SongsSource = None, albums: AlbumsSource = None, playlists: PlaylistsSource = None, artists: ArtistsSource = None, music_videos: MusicVideosSource = None, stations: StationsSource = None, curators: CuratorsSource = None, genres: GenresSource = None, record_labels: RecordLabelsSource = None, groupings: GroupingsSource = None, personal_recommendations: PersonalRecommendationsSource = None, library_songs: LibrarySongsSource = None, library_albums: LibraryAlbumsSource = None, library_playlists: LibraryPlaylistsSource = None, library_artists: LibraryArtistsSource = None, library_music_videos: LibraryMusicVideosSource = None)

Shared resource sources read by multiple endpoints.

Each field accepts an id-keyed mapping. Callable lookups are also accepted where per-id resolution is sufficient; genres, record_labels, and personal_recommendations require the dict form because their endpoints enumerate ids. Fields default to None; reading an unset source raises ValueError.

Attributes:

Name	Type	Description
songs	SongsSource	Catalog song source.
albums	AlbumsSource	Catalog album source.
playlists	PlaylistsSource	Catalog playlist source.
artists	ArtistsSource	Catalog artist source.
music_videos	MusicVideosSource	Catalog music-video source.
stations	StationsSource	Catalog radio-station source.
curators	CuratorsSource	Catalog curator source (apple-curators and curators).
genres	GenresSource	Catalog genre source.
record_labels	RecordLabelsSource	Catalog record-label source.
groupings	GroupingsSource	Catalog grouping source (editorial categories).
personal_recommendations	PersonalRecommendationsSource	User recommendation row source.
library_songs	LibrarySongsSource	User-library song source.
library_albums	LibraryAlbumsSource	User-library album source.
library_playlists	LibraryPlaylistsSource	User-library playlist source.
library_artists	LibraryArtistsSource	User-library artist source.
library_music_videos	LibraryMusicVideosSource	User-library music-video source.

Catalog resources

Song dataclass

Song(title: str, artist: str, album: str, duration_ms: int, artwork: Artwork, genres: list[str], has_lyrics: bool, audio_locale: str, audio_traits: list[str], has_time_synced_lyrics: bool, is_apple_digital_master: bool, is_mastered_for_itunes: bool, is_vocal_attenuation_allowed: bool, url: str, hls_layout: HlsLayout, hls_segment: bytes, preview_audio: bytes, bitrate: int, sample_rate: int, file_size: int, release_date: str | None = None, track_number: int | None = None, disc_number: int | None = None, composer: str | None = None, isrc: str | None = None, content_rating: str | None = None, play_assets: list[StationContextPlayAsset] | None = None, album_ids: list[str] | None = None, artist_ids: list[str] | None = None, composer_ids: list[str] | None = None, genre_ids: list[str] | None = None, music_video_ids: list[str] | None = None, station_id: str | None = None, library_song_id: str | None = None)

Apple Music catalog song.

Holds the audio bytes the mock returns for HLS playback and preview, plus the layout the mock needs to compose the HLS manifest at serve time. The from_file constructor sources these from an audio file on disk.

Attributes:

Name	Type	Description
title	str	Display title of the song.
artist	str	Display name of the primary artist.
album	str	Display name of the album the song belongs to.
duration_ms	int	Duration in milliseconds.
artwork	Artwork	Cover artwork.
genres	list[str]	Display names of the song's genres.
has_lyrics	bool	Whether lyrics are available.
audio_locale	str	BCP-47 locale tag of the recorded audio.
audio_traits	list[str]	Audio capability tags (lossless, dolby-atmos, etc.).
has_time_synced_lyrics	bool	Whether time-synced lyrics are available.
is_apple_digital_master	bool	Apple's "Apple Digital Master" badge.
is_mastered_for_itunes	bool	Apple's "Mastered for iTunes" badge.
is_vocal_attenuation_allowed	bool	Whether vocal attenuation (Sing) is allowed.
url	str	Song landing-page URL on Apple Music.
hls_layout	HlsLayout	fMP4 segment layout for the HLS manifest.
hls_segment	bytes	Raw bytes of the fMP4 segment served for HLS playback.
preview_audio	bytes	Raw bytes the mock serves as the preview asset.
bitrate	int	Bitrate in kilobits per second.
sample_rate	int	Sample rate in hertz.
file_size	int	Source file size in bytes.
release_date	str | None	ISO-8601 release date.
track_number	int | None	Track number within the album.
disc_number	int | None	Disc number when part of a multi-disc album.
composer	str | None	Display name of the primary composer.
isrc	str | None	International Standard Recording Code.
content_rating	str | None	Apple content-rating tag.
play_assets	list[StationContextPlayAsset] | None	Per-bit-rate play-asset variants surfaced in station track-info responses.
album_ids	list[str] | None	Catalog album ids the song belongs to. Emitted as shallow refs in relationships.albums, or as deep inline resources when ?include=albums is requested.
artist_ids	list[str] | None	Catalog artist ids credited on the song. Emitted in relationships.artists with the same shallow/deep rule.
composer_ids	list[str] | None	Catalog artist ids credited as composers. Emitted in relationships.composers with the same shallow/deep rule.
genre_ids	list[str] | None	Catalog genre ids the song belongs to.
music_video_ids	list[str] | None	Catalog music-video ids associated with the song.
station_id	str | None	Catalog station id of the song's radio station.
library_song_id	str | None	Library song id when the song has a counterpart in the user's library.

from_file classmethod

from_file(audio_path: str, fallback: SongMetadataFallback | None = None, *, preview: PreviewRange | bytes | None = None) -> Song

Build a song by reading metadata and audio bytes from a file on disk.

Reads tags and audio data from the file at audio_path and populates every field of the result, including HLS segment bytes and layout. Missing tag fields are filled from fallback when supplied; fields with neither a tag nor a fallback raise.

Parameters:

Name	Type	Description	Default
audio_path	str	Filesystem path to the source audio file.	required
fallback	SongMetadataFallback | None	Metadata defaults applied when tags are missing the corresponding field. Leave unset to require every field to be present in the file's tags.	None
preview	PreviewRange | bytes | None	Either an explicit byte payload to serve as the preview, or a time window to extract from the source audio. Leave unset to use the full source audio as the preview.	None

Returns:

Type	Description
Song	A fully-populated song built from the file.

Album dataclass

Album(name: str, artist_name: str, artwork: Artwork, genre_names: list[str], track_count: int, is_compilation: bool, is_complete: bool, is_mastered_for_itunes: bool, is_single: bool, is_prerelease: bool, audio_traits: list[str], url: str, release_date: str | None = None, copyright: str | None = None, record_label: str | None = None, upc: str | None = None, track_ids: list[str] | None = None, artist_ids: list[str] | None = None, content_rating: str | None = None, editorial_notes: EditorialNotes | None = None, editorial_artwork: dict[str, Artwork] | None = None, genre_ids: list[str] | None = None, record_label_ids: list[str] | None = None, library_album_id: str | None = None)

Apple Music catalog album.

Attributes:

Name	Type	Description
name	str	Display title of the album.
artist_name	str	Display name of the primary artist.
artwork	Artwork	Cover artwork.
genre_names	list[str]	Display names of the album's genres.
track_count	int	Number of tracks on the album.
is_compilation	bool	Whether the album is a compilation.
is_complete	bool	Whether the album release is complete (vs. partial).
is_mastered_for_itunes	bool	Apple's "Mastered for iTunes" badge.
is_single	bool	Whether the release is a single.
is_prerelease	bool	Whether the release is a pre-release.
audio_traits	list[str]	Audio capability tags (lossless, dolby-atmos, etc.).
url	str	Album landing-page URL on Apple Music.
release_date	str | None	ISO-8601 release date.
copyright	str | None	Copyright line.
record_label	str | None	Display name of the record label.
upc	str | None	Universal Product Code identifying the release.
track_ids	list[str] | None	Catalog song ids composing the album. The mock resolves these into full track resources at response time.
artist_ids	list[str] | None	Catalog artist ids credited on the album. Resolved into full artist resources at response time.
content_rating	str | None	Apple content-rating tag (e.g. clean, explicit).
editorial_notes	EditorialNotes | None	Editorial copy shown alongside the album.
editorial_artwork	dict[str, Artwork] | None	Treatment-keyed artworks emitted only when a request asks for them via ?extend=editorialArtwork.
genre_ids	list[str] | None	Catalog genre ids the album belongs to.
record_label_ids	list[str] | None	Catalog record-label ids associated with the album.
library_album_id	str | None	Library album id when the album has a counterpart in the user's library, used to resolve ?include=library.

Artist dataclass

Artist(name: str, genre_names: list[str], url: str, artwork: Artwork | None = None, album_ids: list[str] | None = None, genre_ids: list[str] | None = None, music_video_ids: list[str] | None = None, playlist_ids: list[str] | None = None, station_id: str | None = None)

Apple Music catalog artist.

Attributes:

Name	Type	Description
name	str	Display name of the artist.
genre_names	list[str]	Display names of the artist's genres.
url	str	Artist landing-page URL on Apple Music.
artwork	Artwork | None	Hero artwork for the artist.
album_ids	list[str] | None	Catalog album ids forming the artist's discography. The mock resolves these into full album resources at response time.
genre_ids	list[str] | None	Catalog genre ids the artist is associated with.
music_video_ids	list[str] | None	Catalog music-video ids credited to the artist.
playlist_ids	list[str] | None	Catalog playlist ids credited to the artist.
station_id	str | None	Catalog station id of the artist's radio station.

Playlist dataclass

Playlist(name: str, playlist_type: Literal['user-shared', 'editorial', 'external', 'personal-mix'], curator_name: str, has_collaboration: bool, is_chart: bool, audio_traits: list[str], supports_sing: bool, url: str, artwork: Artwork | None = None, last_modified: str | None = None, track_ids: list[str] | None = None, description: Description | None = None, editorial_notes: EditorialNotes | None = None, curator_id: str | None = None, library_playlist_id: str | None = None)

Apple Music catalog playlist.

Catalog playlists curated by Apple Music's editorial team carry the apple-curators curator type — that distinction lives on the curator resource, not here.

Attributes:

Name	Type	Description
name	str	Display name of the playlist.
playlist_type	Literal['user-shared', 'editorial', 'external', 'personal-mix']	Playlist category — one of user-shared, editorial, external, or personal-mix.
curator_name	str	Display name of the curator.
has_collaboration	bool	Whether collaborative editing is enabled.
is_chart	bool	Whether the playlist is a chart playlist.
audio_traits	list[str]	Audio capability tags (lossless, dolby-atmos, etc.).
supports_sing	bool	Whether the playlist supports Apple Music Sing.
url	str	Playlist landing-page URL on Apple Music.
artwork	Artwork | None	Cover artwork.
last_modified	str | None	ISO-8601 timestamp of the last edit.
track_ids	list[str] | None	Catalog song ids in the playlist's track order.
description	Description | None	Long/short description text.
editorial_notes	EditorialNotes | None	Editorial copy shown alongside the playlist.
curator_id	str | None	Editorial or user curator id. When set, the mock emits a relationships.curator shallow ref matching Apple's default.
library_playlist_id	str | None	Library playlist id when the playlist has a counterpart in the user's library.

MusicVideo dataclass

MusicVideo(name: str, artist_name: str, artwork: Artwork, duration_ms: int, genre_names: list[str], has_4k: bool, has_hdr: bool, url: str, previews: list[Preview], video_traits: list[str], isrc: str | None = None, release_date: str | None = None, album_name: str | None = None, content_rating: str | None = None, disc_number: int | None = None, track_number: int | None = None, album_ids: list[str] | None = None, artist_ids: list[str] | None = None, genre_ids: list[str] | None = None, song_ids: list[str] | None = None, library_music_video_id: str | None = None)

Apple Music catalog music video.

Attributes:

Name	Type	Description
name	str	Display title of the music video.
artist_name	str	Display name of the primary artist.
artwork	Artwork	Cover artwork.
duration_ms	int	Duration in milliseconds.
genre_names	list[str]	Display names of the video's genres.
has_4k	bool	Whether a 4K rendition is available.
has_hdr	bool	Whether an HDR rendition is available.
url	str	Music-video landing-page URL on Apple Music.
previews	list[Preview]	Preview clip references.
video_traits	list[str]	Video capability tags (e.g. atmos, lossless).
isrc	str | None	International Standard Recording Code.
release_date	str | None	ISO-8601 release date.
album_name	str | None	Display name of the album the video belongs to.
content_rating	str | None	Apple content-rating tag.
disc_number	int | None	Disc number when part of a multi-disc album.
track_number	int | None	Track number within the album.
album_ids	list[str] | None	Catalog album ids the video belongs to.
artist_ids	list[str] | None	Catalog artist ids credited on the video.
genre_ids	list[str] | None	Catalog genre ids the video belongs to.
song_ids	list[str] | None	Catalog song ids associated with the video.
library_music_video_id	str | None	Library music-video id when the video has a counterpart in the user's library.

Station dataclass

Station(name: str, artwork: Artwork, is_live: bool, media_kind: Literal['audio', 'video'], url: str, is_tracks_station: bool, has_drm: bool, kind: str, radio_url: str, requires_subscription: bool, editorial_notes: EditorialNotes | None = None, streaming_radio_sub_type: Literal['Episode', 'Shoutcast'] | None = None, station_provider_name: str | None = None, radio_show_id: str | None = None)

Apple Music catalog radio station.

Attributes:

Name	Type	Description
name	str	Display name of the station.
artwork	Artwork	Hero artwork for the station.
is_live	bool	Whether the station is a live broadcast.
media_kind	Literal['audio', 'video']	Media kind — audio or video.
url	str	Station landing-page URL on Apple Music.
is_tracks_station	bool	Whether the station plays a track-driven playlist.
has_drm	bool	Whether the station's playback is DRM-protected.
kind	str	Apple-specific station-kind tag.
radio_url	str	HLS URL the station streams from.
requires_subscription	bool	Whether playback requires an Apple Music subscription.
editorial_notes	EditorialNotes | None	Editorial copy shown alongside the station.
streaming_radio_sub_type	Literal['Episode', 'Shoutcast'] | None	Streaming sub-type — Episode for episodic broadcasts, Shoutcast for Shoutcast streams.
station_provider_name	str | None	Display name of the third-party provider.
radio_show_id	str | None	Catalog id of the linked radio show.

Curator dataclass

Curator(name: str, type: Literal['apple-curators', 'curators'], url: str, artwork: Artwork, short_name: str | None = None, kind: str | None = None, playlist_ids: list[str] | None = None, grouping_id: str | None = None)

Apple Music catalog curator (apple-curators or curators type).

Attributes:

Name	Type	Description
name	str	Display name of the curator.
type	Literal['apple-curators', 'curators']	Curator type — apple-curators for Apple's editorial team, curators for third-party curators.
url	str	Curator landing-page URL on Apple Music.
artwork	Artwork	Hero artwork for the curator.
short_name	str | None	Optional short display name.
kind	str | None	Apple-specific kind tag.
playlist_ids	list[str] | None	Catalog playlist ids the curator owns. Surface in the curator's relationships.playlists and as the data of /v1/catalog/{sf}/{type}/{id}/playlists.
grouping_id	str | None	Editorial grouping the curator belongs to (apple-curators only). Surfaces as relationships.grouping.

Library resources

LibrarySong dataclass

LibrarySong(name: str, artist_name: str, artwork: Artwork, duration_ms: int, genre_names: list[str], has_lyrics: bool, album_name: str | None = None, disc_number: int | None = None, track_number: int | None = None, release_date: str | None = None, catalog_id: str | None = None, album_ids: list[str] | None = None, artist_ids: list[str] | None = None)

User-library song.

Attributes:

Name	Type	Description
name	str	Display title of the song.
artist_name	str	Display name of the primary artist.
artwork	Artwork	Cover artwork.
duration_ms	int	Duration in milliseconds.
genre_names	list[str]	Display names of the song's genres.
has_lyrics	bool	Whether lyrics are available.
album_name	str | None	Display name of the album the song belongs to.
disc_number	int | None	Disc number when part of a multi-disc album.
track_number	int | None	Track number within the album.
release_date	str | None	ISO-8601 release date.
catalog_id	str | None	Catalog song id linking back to the catalog counterpart, used to resolve ?include=catalog.
album_ids	list[str] | None	Library album ids the song belongs to.
artist_ids	list[str] | None	Library artist ids credited on the song.

LibraryAlbum dataclass

LibraryAlbum(name: str, artist_name: str, artwork: Artwork, genre_names: list[str], track_count: int, date_added: str | None = None, track_ids: list[str] | None = None, artist_ids: list[str] | None = None, release_date: str | None = None, catalog_id: str | None = None)

User-library album.

Attributes:

Name	Type	Description
name	str	Display title of the album.
artist_name	str	Display name of the primary artist.
artwork	Artwork	Cover artwork.
genre_names	list[str]	Display names of the album's genres.
track_count	int	Number of tracks on the album.
date_added	str | None	ISO-8601 timestamp the user added the album to their library.
track_ids	list[str] | None	Library song ids on the album.
artist_ids	list[str] | None	Library artist ids credited on the album. Surface in relationships.artists only when ?include=artists is requested.
release_date	str | None	ISO-8601 release date.
catalog_id	str | None	Catalog album id linking back to the catalog counterpart, used to resolve ?include=catalog.

LibraryArtist dataclass

LibraryArtist(name: str, album_ids: list[str] | None = None, catalog_id: str | None = None)

User-library artist.

Attributes:

Name	Type	Description
name	str	Display name of the artist.
album_ids	list[str] | None	Library album ids credited to the artist.
catalog_id	str | None	Catalog artist id linking back to the catalog counterpart, used to resolve ?include=catalog.

LibraryMusicVideo dataclass

LibraryMusicVideo(name: str, artist_name: str, artwork: Artwork, duration_ms: int, genre_names: list[str], release_date: str | None = None, track_number: int | None = None, album_ids: list[str] | None = None, artist_ids: list[str] | None = None, content_rating: str | None = None, album_name: str | None = None, catalog_id: str | None = None)

User-library music video.

Attributes:

Name	Type	Description
name	str	Display title of the music video.
artist_name	str	Display name of the primary artist.
artwork	Artwork	Cover artwork.
duration_ms	int	Duration in milliseconds.
genre_names	list[str]	Display names of the genres.
release_date	str | None	ISO-8601 release date.
track_number	int | None	Track number when part of an album.
album_ids	list[str] | None	Library album ids the video belongs to. These reference library albums (not catalog albums) — the same endpoint ?include=albums returns library-albums in relationships.
artist_ids	list[str] | None	Library artist ids credited on the video. References library artists for the same reason as the album ids.
content_rating	str | None	Apple content-rating tag.
album_name	str | None	Display name of the album the video belongs to.
catalog_id	str | None	Catalog music-video id linking back to the catalog counterpart, used to resolve ?include=catalog.

LibraryPlaylist dataclass

LibraryPlaylist(name: str, can_delete: bool, can_edit: bool, is_public: bool, has_catalog: bool, has_collaboration: bool, date_added: str | None = None, last_modified_date: str | None = None, track_ids: list[str] | None = None, artwork: Artwork | None = None, catalog_id: str | None = None)

User-library playlist.

Attributes:

Name	Type	Description
name	str	Display name of the playlist.
can_delete	bool	Whether the user can delete the playlist.
can_edit	bool	Whether the user can edit the playlist's tracks.
is_public	bool	Whether the playlist is shared publicly.
has_catalog	bool	Whether a corresponding catalog playlist exists.
has_collaboration	bool	Whether collaborative editing is enabled.
date_added	str | None	ISO-8601 timestamp the playlist was added to the library.
last_modified_date	str | None	ISO-8601 timestamp of the last edit.
track_ids	list[str] | None	Library song ids in the playlist's track order.
artwork	Artwork | None	Cover artwork.
catalog_id	str | None	Catalog playlist id linking back to the catalog counterpart, used to resolve ?include=catalog.

Personal recommendations

PersonalRecommendation dataclass

PersonalRecommendation(title: str, is_group_recommendation: bool, kind: PersonalRecommendationKind, next_update_date: str | None = None, reason: str | None = None, resource_types: list[str] | None = None, contents: list[PersonalRecommendationContent] | None = None, display: PersonalRecommendationDisplay | None = None, has_see_all: bool | None = None, version: int | None = None)

A single user-recommendation row.

Attributes:

Name	Type	Description
title	str	Editorial display name shown above the row in the UI.
is_group_recommendation	bool	Whether the row is a group recommendation.
kind	PersonalRecommendationKind	Editorial category of the row (generic music recommendation, playlist-specific recommendation, recently-played row, etc.).
next_update_date	str | None	ISO-8601 timestamp of the next refresh.
reason	str | None	Optional editorial reason copy.
resource_types	list[str] | None	Resource types featured in the row.
contents	list[PersonalRecommendationContent] | None	Catalog resource references composing the row. Each entry pairs a resource type with a catalog id so a single row can mix types.
display	PersonalRecommendationDisplay | None	Editorial-shelf display hint.
has_see_all	bool | None	Whether the row has a "see all" expansion.
version	int | None	Apple's row revision marker.

PersonalRecommendationContent dataclass

PersonalRecommendationContent(type: PersonalRecommendationContentKind, id: str)

A single content reference within a recommendation row.

A recommendation's contents can be heterogeneous (playlists, albums, stations, music videos mixed in one row), so each entry carries its own type alongside the catalog id.

Attributes:

Name	Type	Description
type	PersonalRecommendationContentKind	Resource type of the linked catalog resource.
id	str	Catalog id of the linked resource.

PersonalRecommendationDisplay dataclass

PersonalRecommendationDisplay(kind: str, decorations: list[str] | None = None)

Editorial-shelf display hint for a recommendation row.

Apple emits these values alongside the row attributes; user code can observe them via the response passthrough.

Attributes:

Name	Type	Description
kind	str	Apple-defined display style identifier.
decorations	list[str] | None	Display-treatment tags applied to the row.

Supporting types

Artwork dataclass

Artwork(url: str, width: int, height: int, bg_color: str | None = None, text_color_1: str | None = None, text_color_2: str | None = None, text_color_3: str | None = None, text_color_4: str | None = None, has_p3: bool | None = None)

Image asset metadata attached to most catalog and library resources.

Attributes:

Name	Type	Description
url	str	Image asset URL; the mock serves it verbatim. Apple's catalog format uses URL templates with {w}, {h}, {f} placeholders the consumer substitutes.
width	int	Image width in pixels at the template's max size.
height	int	Image height in pixels at the template's max size.
bg_color	str | None	Dominant background color as a hex string (without the leading #).
text_color_1	str | None	Foreground-text color hint (primary).
text_color_2	str | None	Foreground-text color hint (secondary).
text_color_3	str | None	Foreground-text color hint (tertiary).
text_color_4	str | None	Foreground-text color hint (quaternary).
has_p3	bool | None	Whether a Display-P3 wide-gamut variant is available.

Description dataclass

Description(standard: str, short: str | None = None)

Free-form long and short description text.

Attributes:

Name	Type	Description
standard	str	Long-form description.
short	str | None	Short-form summary.

EditorialNotes dataclass

EditorialNotes(name: str | None = None, short: str | None = None, standard: str | None = None, tagline: str | None = None)

Editorial copy shown next to a resource.

Attributes:

Name	Type	Description
name	str | None	Editorial display name override.
short	str | None	Short-form editorial summary.
standard	str | None	Long-form editorial copy.
tagline	str | None	One-line editorial tagline.

Genre dataclass

Genre(name: str, url: str, parent_id: str | None = None, parent_name: str | None = None)

Apple Music catalog genre.

Attributes:

Name	Type	Description
name	str	Display name of the genre.
url	str	Genre landing-page URL on Apple Music.
parent_id	str | None	Catalog id of the parent genre when this is a subgenre.
parent_name	str | None	Display name of the parent genre when this is a subgenre.

Grouping dataclass

Grouping(name: str, url: str, artwork: Artwork | None = None)

Apple Music catalog grouping (editorial category for apple-curators).

Attributes:

Name	Type	Description
name	str	Display name of the grouping.
url	str	Grouping landing-page URL on Apple Music.
artwork	Artwork | None	Hero artwork for the grouping.

Preview dataclass

Preview(url: str, hls_url: str | None = None, artwork: Artwork | None = None)

Preview asset reference (audio or video).

Attributes:

Name	Type	Description
url	str	Progressive download URL for the preview asset.
hls_url	str | None	HLS playlist URL when an HLS variant is available.
artwork	Artwork | None	Preview-specific artwork (e.g. video poster frame).

PreviewRange dataclass

PreviewRange(start_sec: float, duration_sec: float)

Time window (in seconds) to extract from the source audio as the preview.

Attributes:

Name	Type	Description
start_sec	float	Start offset in seconds from the beginning of the source.
duration_sec	float	Preview duration in seconds.

RecordLabel dataclass

RecordLabel(name: str, url: str, artwork: Artwork | None = None, description: Description | None = None)

Apple Music catalog record label.

Attributes:

Name	Type	Description
name	str	Display name of the record label.
url	str	Record-label landing-page URL on Apple Music.
artwork	Artwork | None	Hero artwork for the label.
description	Description | None	Long/short description text.

HlsChunk dataclass

HlsChunk(duration_sec: float, byte_offset: int, byte_length: int)

Byte range of one media chunk inside an HLS fMP4 segment file.

Attributes:

Name	Type	Description
duration_sec	float	Duration of this chunk in seconds.
byte_offset	int	Offset of the chunk within the segment file.
byte_length	int	Length of the chunk in bytes.

HlsLayout dataclass

HlsLayout(target_duration_sec: int, init_byte_offset: int, init_byte_length: int, chunks: tuple[HlsChunk, ...])

fMP4 segment layout describing what the HLS manifest must declare.

The mock composes the wire-format manifest at serve time so the EXT-X-KEY directive can be selected from the active key system.

Attributes:

Name	Type	Description
target_duration_sec	int	Target chunk duration declared in the manifest.
init_byte_offset	int	Offset of the initialization fragment within the segment file.
init_byte_length	int	Length of the initialization fragment in bytes.
chunks	tuple[HlsChunk, ...]	Per-chunk byte-range descriptors in playback order.

SongMetadataFallback dataclass

SongMetadataFallback(title: str | None = None, artist: str | None = None, album: str | None = None, artwork: Artwork | None = None, genres: list[str] | None = None, release_date: str | None = None, track_number: int | None = None, disc_number: int | None = None, composer: str | None = None, has_lyrics: bool | None = None, isrc: str | None = None, content_rating: str | None = None, audio_locale: str | None = None, audio_traits: list[str] | None = None, has_time_synced_lyrics: bool | None = None, is_apple_digital_master: bool | None = None, is_mastered_for_itunes: bool | None = None, is_vocal_attenuation_allowed: bool | None = None, url: str | None = None)

Metadata defaults applied when an audio file's tags are missing fields.

Each field corresponds to the same-named attribute on the song dataclass and is used only when the source file's tags do not supply the value. Fields left unset (None) provide no fallback and the loader raises if the tag is also missing.

Attributes:

Name	Type	Description
title	str | None	Display title fallback.
artist	str | None	Primary artist fallback.
album	str | None	Album-name fallback.
artwork	Artwork | None	Cover-artwork fallback.
genres	list[str] | None	Genres fallback.
release_date	str | None	ISO-8601 release-date fallback.
track_number	int | None	Track-number fallback.
disc_number	int | None	Disc-number fallback.
composer	str | None	Composer fallback.
has_lyrics	bool | None	Lyrics-availability fallback.
isrc	str | None	ISRC fallback.
content_rating	str | None	Content-rating fallback.
audio_locale	str | None	BCP-47 audio-locale fallback.
audio_traits	list[str] | None	Audio-traits fallback.
has_time_synced_lyrics	bool | None	Time-synced lyrics-availability fallback.
is_apple_digital_master	bool | None	Apple Digital Master fallback.
is_mastered_for_itunes	bool | None	Mastered for iTunes fallback.
is_vocal_attenuation_allowed	bool | None	Vocal-attenuation-allowed fallback.
url	str | None	Landing-page URL fallback.

Lookup callback context

LookupContext dataclass

LookupContext(id: str, locale: str | None)

Per-request resource lookup input.

Passed to callable data sources so user code can produce locale-aware responses. Dict sources ignore the locale (id-only mapping is the simplest contract).

Attributes:

Name	Type	Description
id	str	Catalog or library id of the resource being looked up.
locale	str | None	Request locale tag from the URL's ?l= parameter, or None when the request did not specify one. The mock does not fabricate a locale from the storefront slug or any other source.