> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sdk.anghami.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Music Catalog

> Songs, albums, artists, and lyrics — the read-only Anghami music surface.

`MusicCatalogService` provides idempotent, cacheable read access to songs, albums, and artists. It's the workhorse of any music client.

## Operations

| RPC                    | What it does                                                     |
| ---------------------- | ---------------------------------------------------------------- |
| `GetSong`              | Fetch a song by `SongID`.                                        |
| `BatchGetSongs`        | Up to N songs in one call — returns a map of ID → song-or-error. |
| `GetAlbum`             | Fetch an album by `AlbumID`.                                     |
| `GetAlbumTracks`       | Paginated tracks of an album.                                    |
| `BatchGetAlbums`       | Batch albums.                                                    |
| `GetArtist`            | Fetch an artist by `ArtistID`.                                   |
| `GetArtistDiscography` | Albums by an artist (filter by album type, paginated).           |
| `GetArtistTopTracks`   | Most popular songs by an artist.                                 |
| `GetRelatedArtists`    | Similar artists.                                                 |
| `BatchGetArtists`      | Batch artists.                                                   |
| `GetLyrics`            | Time-synchronized lyrics when available, plain text otherwise.   |

Full request/response schemas live in the [API Reference](/api-reference) under the `MusicCatalogService` tag.

## Authentication

All operations are accessible with **either** an API key or an OAuth access token. Catalog data is public — there is no user context needed unless you want to enrich responses with user-specific liked/saved state (use [`LibraryService`](/library) for that).

## Batch vs single

When you need more than \~3 entities of the same kind, prefer `BatchGet*`:

* One request counts as one call against your rate limit, regardless of how many items you fetch.
* Items succeed and fail independently — the response is a map of ID → `{ song } | { error }`. See [Errors / Batch errors](/usage-errors#batch-errors).
* Network round-trip is a single TLS handshake instead of N.

```ts theme={null}
const res = await music.batchGetSongs({
  songIdList: ["123", "456", "789"].map(value => ({ value })),
});
for (const [id, result] of Object.entries(res.results)) {
  if (result.song) console.log(id, result.song.title);
  else console.warn(id, result.error?.code);
}
```

## Lyrics

`GetLyrics` returns either time-synchronized lyric lines (with millisecond timestamps suitable for karaoke-style highlighting) or plain text when sync data is unavailable. Branch on which `oneof` arm is populated.

Lyrics availability is rights-gated and varies by track and market.

## Caching

All catalog reads are idempotent and may be cached client-side for up to your application's tolerance — server responses include `Cache-Control` hints. Treat artwork URLs as immutable for the lifetime of the entity (artwork rotation creates a new URL).

## Markets

Some endpoints accept a `market` parameter (e.g. `GetArtistTopTracks`) to scope popularity to a specific country. Omit for global.

## Related

* [Music Search & Browse](/music-search) — full-text search and editorial browsing.
* [Playlists](/playlists) — read playlists, including a user's own.
* [Library](/library) — liked songs, followed artists, history.
* [Streaming & Billing](/streaming-billing) — turning a `SongID` into a playable stream URL.