# Music API (`/api/music/*`) Platform API the mobile app uses to **stream music** and **sync a server-built library index**, so the app no longer pre-downloads whole tracks or walks/ID3-parses the library on-device. - **Source of truth for the code:** `plugins/music/sidecar/index.ts` (the `officer-music` sidecar owns all of this; the platform `/api/music/*` route is a transparent auth-ing proxy). - **Music root:** `~/Music` on the server. All `path` values are **home-relative** (e.g. `Music/Albums/AC-DC/[1980] Back in Black/01 Hells Bells.mp3`), identical to `/api/file-browser/raw`. - **``:** an album folder path **relative to the `Music` root** (e.g. `Albums/AC-DC/[1980] Back in Black`). ## Auth Every endpoint is behind the standard user auth. Two ways to pass the JWT: - **Header:** `Authorization: Bearer ` (normal fetches). - **Query:** `?token=` — for media elements / native players that can't set headers (audio, images). `401` = no token · `403` = invalid/expired token. --- ## 1. Playback — stream a track ``` GET /api/music/stream?path=&token= ``` Byte-range streaming so the player can **seek without downloading the whole file**. | Case | Status | Headers | | --------------------- | ------ | --------------------------------------------------------------------------------------------- | | No `Range` | `200` | `Content-Type`, `Content-Length`, `Accept-Ranges: bytes`, `ETag`, `Cache-Control` | | With `Range: bytes=…` | `206` | `Content-Range`, `Content-Length`, `Accept-Ranges: bytes`, `Content-Type`, `ETag` | - **`X-Audio-Duration` still ships, and no longer costs an `ffprobe`** (2026-08-19). It used to spawn one per file on the first request — measured at 50ms warm, 315ms cold, paid before the first byte. It is now read from the album's `meta.json` and cached per album: 1.5ms cold, 0.1ms warm, and the same number, because the indexer got it from ffprobe too. It was briefly removed outright, on the reasoning that nothing in the web read it and `/meta` already carried `durationSec`. The mobile player stopped playing, so it is load-bearing for at least one client and stays in the contract. New clients should still prefer `durationSec` from `/meta` — it arrives with the queue, before the first stream request. Absent when the album has not been indexed, exactly as it was absent when ffprobe failed. - **`ETag`** is `mtime-size` in base36. A whole-file request with a matching `If-None-Match` answers `304`; a Range request never does, because a 304 would answer a question about part of a file with a statement about all of it. - Errors: `400` invalid/missing path · `404` not found · `416` bad range. ``` curl -H "Authorization: Bearer $JWT" -H "Range: bytes=0-1023" \ "$BASE/api/music/stream?path=Music/Albums/AC-DC/[1980]%20Back%20in%20Black/01%20Hells%20Bells.mp3" -D - ``` --- ## 2. Library index — the synced cache The server maintains a cache tree that **mirrors the library**, one entry per album folder. The app syncs this instead of walking + ID3-parsing the library itself. Each album has a **version stamp `v`** (hash of the album's source files' names/sizes/mtimes + its cover). `v` changes **iff the album's content changed** → it's the whole basis of the diff: _unchanged `v` ⇒ skip_. **Put `v` in the URL of anything you fetch per album** — `/cover?path=…&v=`, and the same for `/meta` and `/discography`. With it the server answers `Cache-Control: immutable` and a repeat visit sends **no request at all**. Without it you get `no-cache`, which does not mean "do not store" but "ask first" — so every cover costs a conditional round trip on every load, and a grid of forty albums is forty requests that all answer `304`. The aggressive caching is conditional on `v` matching precisely so an older client cannot end up holding a cover forever: send no `v`, get the old behaviour. When an album changes, its `v` changes, the URL you build changes with it, and the stale entry is never asked for again. ### 2.1 Manifest — one call, whole library ``` GET /api/music/manifest ``` ```jsonc { "version": 1, "generatedAt": 1785034701973, // ms; when the index was last built "albums": { "Albums/AC-DC/[1980] Back in Black": { "v": "50856380f1ca8f9", "cover": true, "tracks": 10 }, "DJ Sets/Dave Clarke": { "v": "a1b2c3d4e5f6a7b", "cover": false, "tracks": 3 }, "Albums/Metallica/[1989] Live Shit": { "v": "beefbeefbeefbee", "cover": true, "tracks": 0, "videos": 2 }, "Albums/AC-DC": { "v": "c0ffee1234567890", "cover": true, "tracks": 0, "disco": true }, // … }, } ``` `404` if the index has never been built (see §3). Entries with **`tracks: 0`** are container folders (e.g. an **artist** folder). An entry with **`disco: true`** is an artist folder that has a discography — fetch its grouping via `/discography` (§2.4). **`videos: N`** (optional) counts video files (concerts, clips) that live directly in that artist/album folder — their per-file metadata is in that folder's `meta.json` (§2.2). A folder may have any mix of `tracks`, `videos`, and `disco`. ### 2.2 Album metadata ``` GET /api/music/meta?path= ``` Returns the album's `meta.json`. Sends `ETag: `; a request with `If-None-Match: ` returns `304`. ```jsonc { "path": "Albums/AC-DC/[1980] Back in Black", "cover": "cover.jpg", // present only if a cover exists "tracks": [ { "file": "01 Hells Bells.mp3", // filename within the album folder "title": "Hells Bells", "artist": "AC/DC", "albumArtist": "AC/DC", "album": "Back in Black", "track": "1", "year": "1980", "durationSec": 312, "lyrics": "lrc", // present if lyrics exist: "lrc" = synced, "txt" = plain (see §2.3.2) }, // … ], "videos": [ // present only for folders that contain video files { "file": "1989 - Seattle.mp4", // filename within the folder "title": "Live Shit: Seattle", // from the container title tag, if any "durationSec": 8130, "width": 1280, "height": 720, "poster": "posters/1989 - Seattle.mp4.jpg", // present when a poster was generated (see §2.3.1) }, // … ], } ``` All track/video fields except `file` are optional (absent when the tag/stream info is missing). `videos` is omitted entirely when the folder has none. To stream a track or video: `GET /api/music/stream?path=Music//` (byte-range; works for `.mp4`). ### 2.3 Cover ``` GET /api/music/cover?path= ``` Compressed JPEG (≤600px on the long edge, ~30–80 KB). Sends `ETag: `; `If-None-Match: ` → `304`. Only meaningful when the manifest entry has `"cover": true`. #### 2.3.1 Video poster ``` GET /api/music/poster?path=&file=