Streaming and media
This page covers the endpoints a media app uses most. Every endpoint, with its parameters and response schema, is in the API reference.
Browsing
Collections are listed with GET endpoints that share one set of pagination parameters:
| Endpoint | Returns |
|---|---|
/api/v1/music/tracks | Tracks |
/api/v1/music/releases | Releases (albums, EPs, singles) |
/api/v1/music/artists | Artists |
/api/v1/photos | Photos |
/api/v1/photo-albums | Photo albums |
| Parameter | Default | Meaning |
|---|---|---|
take | 12 | Page size |
skip | 0 | Number of items to skip |
orderBy | Varies | Field to sort by. Allowed values differ per endpoint. |
order | ASC or DESC |
A list responds with a two-item array: the page of items, then the total number of matching items.
Search
The three music lists also take a search parameter: a track's title, a release's title, or an artist's name. Matching ignores case, finds the term anywhere in the text, and treats % and _ as plain characters. It combines with pagination, sorting, and the other filters.
GET /api/v1/music/artists?search=radio&take=20
[
[ { "musicTrackId": "a826e28d-...", "title": "...", ... } ],
1532
]
Each item has a string ID named after its type (musicTrackId, musicReleaseId, musicArtistId, photoId). Use these IDs in other endpoints. Single items are fetched with /api/v1/music/track/{id}, /api/v1/music/release/{id}, /api/v1/music/artist/{id}, and /api/v1/photo/{id}.
Streaming audio
GET /api/v1/music/stream/{musicTrackId}
The endpoint streams the track and supports HTTP range requests: a request with a Range header gets a 206 Partial Content response, which is what lets a player seek and resume.
| Parameter | Values | Meaning |
|---|---|---|
transcode | Absent, false or 0: off. Present with no value, true or 1: on. | Whether to transcode the track to MP3 |
bitrate | kbps, default 320 | The MP3 bitrate when transcoding |
Without transcode, the server sends the original file with its real content type. A client that cannot play the original format, for example FLAC on some platforms, should ask for MP3:
GET /api/v1/music/stream/{musicTrackId}?transcode&bitrate=192
Transcoding runs in real time on the server's CPU. Prefer direct streams wherever the client can play the format.
Playing a stream in a browser
An <audio> element cannot send an Authorization header, so pass the credential as the token query parameter:
<audio controls src="http://192.168.1.40:24900/api/v1/music/stream/a826e28d-...?token=cardinal_pat_..."></audio>
Native players that accept request headers should send the Authorization header instead, which keeps the token out of URLs and logs.
For a complete player, with the server-side queue and play history, see Playback and the queue.
Cover art
GET /api/v1/music/releases/{musicReleaseId}/cover?size=medium_nocrop
size | Meaning |
|---|---|
small_nocrop (default) | A small thumbnail, uncropped |
medium_nocrop | A larger thumbnail, uncropped |
Responds with the image, or 404 when the release has no cover of that size. Thumbnails are made by the Album art thumbnails job.
Each response carries an ETag. Send it back as If-None-Match and an unchanged cover answers 304 Not Modified with no body. An <img> element needs the token query parameter, the same as an <audio> element.
Waveforms
GET /api/v1/music/track/{musicTrackId}/waveform
| Status | Meaning |
|---|---|
200 | The body is the track's waveform: its shape, loudness, and leading and trailing silence. |
202 | No current waveform exists. The server has started generating one, and the body is empty. |
After a 202, wait for the music.waveform_ready event, whose payload carries the musicTrackId and the finished waveform. See Generate waveforms for what the data describes.
Photos
| Endpoint | Returns |
|---|---|
GET /api/v1/photo/{id} | The photo's data and metadata |
GET /api/v1/photo/{id}/thumbnail?size=small_nocrop | A thumbnail, in small_nocrop (default) or medium_nocrop |
GET /api/v1/photo/{id}/blob | The full image |
GET /api/v1/photos/coordinates | [id, photoId, latitude, longitude] for every geotagged photo |
The full image is the original file, except for HEIC/HEIF photos requested by a client whose User-Agent does not indicate HEIF support: those are converted to JPEG, and the response carries Cardinal-Converted-Photo-From and Cardinal-Converted-Photo-To headers. Pass autoConvert=false to always get the original. See Viewing HEIF/HEIC images.
Albums are managed with the /api/v1/photo-album endpoints.
Movies and TV
The API does not serve movies or TV shows yet.
Was this article helpful?