library

type FavoriteChanged = {
  uri: string;
  liked: boolean;
};

type LibraryErrorReply = {
  error: LibraryError;
};

Pages through one folder of the library tree, or the root menu. Root results are held for 5 minutes.

type LibraryBrowse = {
  nodeId?: string; // A `nodeId` from an earlier result. Null browses the root.
  limit: number; // Capped at 100.
  offset: number;
  sections?: number; // Root only. Null returns every folder.
  preview?: number; // Root only. Preview children per folder; `0` returns ids and titles only.
};

type LibraryBrowseReply = {
  result: BrowseResult;
};

type LibrarySearch = {
  query: string;
  kinds?: ItemKind[]; // Null searches every kind.
  limit: number; // Capped at 100.
  offset: number;
};

type LibrarySearchReply = {
  result: SearchResult;
};

type LibraryRecommendations = {
  seeds: ItemRef[]; // Only the first 5 are used.
  kind?: ItemKind; // Null lets the companion app choose from the seeds.
  limit: number; // Capped at 100.
  offset: number;
};

type LibraryRecommendationsReply = {
  result: RecommendationsResult;
};

Resolves a context uri, such as PlayerState.context.uri, into a name and an artwork id.

type LibraryResolveContext = {
  uri: string;
};

Fields are null when the companion app cannot name the uri.

type LibraryResolveContextReply = {
  name?: string;
  artworkId?: string;
  subtitle?: string;
};

Pages the user's saved items, mixed across kinds.

type LibraryFavoritesList = {
  limit: number; // Capped at 100.
  offset: number;
};

type LibraryFavoritesListReply = {
  page: FavoritesPage;
};

Checks which uris the user has saved. The reply's liked lines up with uris.

type LibraryFavoritesContains = {
  uris: string[]; // Only the first 50 are used.
};

type LibraryFavoritesContainsReply = {
  liked: boolean[]; // Lines up with the `uris` you sent.
};

type FavoritesToggle = {
  item: ItemRef;
};

type FavoritesSet = {
  item: ItemRef;
  liked: boolean;
};

type FavoritesSetMany = {
  entries: FavoritesSet[];
};

type LibraryError =
  | 'notFound' // The uri or node id names nothing in the library.
  | 'notSupported' // The music source offers no such operation.
  | 'unauthorized' // The signed-in account permits no such operation.
  | 'noGateway' // No phone is connected.;

Page by raising offset while hasMore is true.

type BrowseResult = {
  entries: BrowseEntry[];
  total?: number;
  hasMore: boolean;
};

search and recommendations take a list of these to constrain their results.

type ItemKind =
  | 'track'
  | 'album'
  | 'playlist'
  | 'podcastEpisode'
  | 'show'
  | 'artist'
  | 'station';

Ranked best first. Page by raising offset while hasMore is true.

type SearchResult = {
  items: LibraryItem[];
  kinds: ItemKind[]; // The kinds the search honored. Compare it against the kinds you asked for.
  total?: number;
  hasMore: boolean;
};

A reference to a library item. Pass it to favoritesToggle, or pass its uri to player.play.

type ItemRef = {
  uri: string;
  kind: ItemKind;
  persistentId?: string; // Opaque. Null when the source has none.
};

Page by raising offset while hasMore is true.

type RecommendationsResult = {
  items: LibraryItem[];
  total?: number;
  hasMore: boolean;
};

Mixed kind. Page by raising offset while hasMore is true.

type FavoritesPage = {
  items: LibraryItem[];
  total?: number;
  hasMore: boolean;
};

A folder can be browsed further; an item can be played.

type BrowseEntry =
  | { type: 'folder'; data: BrowseFolder }
  | { type: 'item'; data: LibraryItem };

Branch on type to read the payload.

type LibraryItem =
  | { type: 'track'; data: Track }
  | { type: 'album'; data: Album }
  | { type: 'playlist'; data: Playlist }
  | { type: 'podcastEpisode'; data: PodcastEpisode }
  | { type: 'show'; data: Show }
  | { type: 'artist'; data: Artist }
  | { type: 'station'; data: Station };

Pass its nodeId to browse to descend into it.

type BrowseFolder = {
  nodeId: string;
  title: string;
  subtitle?: string;
  artworkId?: string;
  total?: number; // Null when the source reports no count.
  previewChildren?: BrowseEntry[]; // The first few children, when the source returns them alongside the folder.
};

A track with its album and artist resolved. Library search and browse return these.

type Track = {
  id: string;
  name: string;
  album: Album;
  artist: Artist; // Primary credited artist.
  artists: Artist[]; // All credited artists, in order.
  durationMs: number;
  imageId: string; // Opaque artwork asset id. Pass it to `asset.get` for the bytes.
  saved: boolean;
};

type Album = {
  id: string;
  name: string;
  artworkId?: string; // Opaque artwork asset id. Pass it to `asset.get` for the bytes.
};

type Playlist = {
  uri: string;
  name: string;
  ownerName?: string; // Who the source credits, such as an owner or a curator.
  trackCount?: number; // Null when the source reports no count.
  artworkId?: string;
};

type PodcastEpisode = {
  uri: string;
  name: string;
  showName?: string;
  durationMs?: number;
  publishedAtUnixS?: number; // Null when the source reports none.
  artworkId?: string;
};

type Show = {
  uri: string;
  name: string;
  publisher?: string;
  episodeCount?: number; // Null when the source reports no count.
  artworkId?: string;
};

type Artist = {
  id: string;
  name: string;
  artworkId?: string; // Opaque artwork asset id. Pass it to `asset.get` for the bytes.
};

type Station = {
  uri: string;
  name: string;
  seed?: string; // URI the station was built from, such as an artist or a track.
  artworkId?: string;
};