On this page
Delivery module (draft 0.2)
Status: draft for comment. Namespace: org.openmusiccollection.delivery. Needs: Core 2.0.
Delivery is how an app plays or downloads a copy from a source it has no integration of its own for: a self-hosted server, a pod, a store, an artist's site. It is level 3 (Media) of conformance.
OpenSubsonic is the delivery protocol
Servers already agree on one API for exactly this: the OpenSubsonic API
(Navidrome, Funkwhale, Ampache, Gonic, and Bandcamp's collection server). A source that speaks it
says so in its descriptor, "protocols": { "opensubsonic": { "base_url": "…" } }, or is found by GET {base}/ping.view?f=json (an answer with openSubsonic: true, type and serverVersion). Apps then use that API directly. This module adds only what makes
it a MIX source.
What the person keeps there
A server lets the person play far more than they keep: other people's public libraries, the libraries they follow, a pod's shared music. Its album list and its search answer all of that. So a home imports only what is the person's own (Core: Sources), and offers the rest through search:
| What | How to read it | In the collection |
|---|---|---|
| Their favourites | getStarred2 | the saved list, copies ownership: none unless they are also the person's own |
| Their own playlists | getPlaylists, keeping those whose owner is the person (the call also answers other people's public playlists) | lists with source and ref |
| What they uploaded, on a server where people upload | the server's own API, where it has one (Funkwhale: GET /api/v2/tracks/?scope=me, and albums, with a token for the same account) | the library list, copies ownership: file |
| A personal server's whole library | getAlbumList2 (paged) and getAlbum, only when the person says the server's library is theirs | the library list, copies ownership: file |
| A store's collection (Bandcamp) | getAlbumList2 and getAlbum: there, the list is the person's purchases | the library list, copies ownership: digital |
| Everything else the server can play | search3 | not imported: search results, which the person may keep one by one |
Records
| OpenSubsonic | MIX |
|---|---|
the server and the person's credentials (u/t/s or apiKey) | a source with platform = the server's host (or the registered name where the host is one: bandcamp), account = the user name |
AlbumID3: id, musicBrainzId, artists[], displayArtist, genres[], recordLabels[], releaseDate, originalReleaseDate, isCompilation, releaseTypes[], created | item release: ids.musicbrainz, artists (one credit per artists[] entry, else one for displayArtist), genres, label (the first recordLabels[].name), release_date, release_type (compilation when isCompilation, else the first of releaseTypes[]); copy ref = the album's id, added_at = created |
Child (a song): id, musicBrainzId, isrc[], artists[], track, discNumber, duration, bitRate, samplingRate, bitDepth, contentType, size, bpm, genres[], starred, created | item recording: ids.isrc (the first), ids.musicbrainz, bpm, genres, duration_ms; copy ref = the song's id, release, track_number, disc_number, file: { mime, size_bytes, bitrate_kbps, sample_rate_hz, bit_depth }. Some servers give no isrc (Funkwhale): such songs match by musicbrainz, then as suggestions |
an artist in artists[] | an artist record when the server has a page for it, with the profile { platform: <host>, ref: <that page's URL> } |
playCount | the server's own count: not the core's play_count, which comes from listens |
Refs are the server's own ids, since the source has the person's account
(Core: A link is a copy); a copy's url is the server's web page for
it, when there is one. Where a server's id wraps a store's own id (Bandcamp's t:<id> and a:<id>),
the copy's ref is the store's id in its registered form, so it matches the same purchase seen any
other way.
Playing
| OpenSubsonic | MIX |
|---|---|
stream, download, getCoverArt | an app builds the URL at play time with a fresh salt (or the API key), and MUST NOT store, cache, export or log it. A copy's url is never a stream URL |
the answer to stream | plain audio with 200 (Navidrome and Funkwhale do this) or a redirect to a CDN (Bandcamp): apps MUST handle both |
scrobble | an app that plays SHOULD report the play to the server, and MUST send the home a listen whose origin_url is the copy's url and music_service the source's platform (Core: Listens) |
getOpenSubsonicExtensions | apiKeyAuthentication: offer API-key sign-in; formPost: send credentials in a POST body; transcoding: ask for format=raw when the person wants the original file |
Media in feeds
Audio a publisher gives in a feed (Chorus media, a public FEP-be68 Audio, an enclosure) is
played as plain HTTP audio from the URL the Feeds module puts in the copy's media. No
protocol and no token: the publisher chose to publish it.
Sources without OpenSubsonic
A source that won't run an OpenSubsonic server may offer one play endpoint instead, declared as
"protocols": { "mix-delivery": { "base_url": "…" } }:
POST {base}/play { "ref": "https://music.example.net/night-drive", "intent": "stream" }
→ { "url": "https://cdn.music.example.net/…", "expires_at": "…", "mime": "audio/flac", "kind": "full" }
intent is preview, stream or download; kind says what the person's account actually got
(preview or full). The URL is short-lived and points at plain HTTP audio or HLS. Consent is the
source's own OAuth, or a token the person pastes. This is a sketch until a second source wants it.
Files on the person's own devices are out of scope: a home's own app on the device that sees the folder adds them as file copies.
Open questions
- Offline downloads from subscription sources: allowed, and with what expiry? (OpenSubsonic's
downloadgives the file; the source's terms decide.) - One consent for collection access and playback, or separate? (OpenSubsonic credentials are per server; Access is per home. Two today.)
Answered in 0.2: plays are reported back to the source (scrobble) and to the home (a listen naming
the copy played).
Prior art
The OpenSubsonic API and the servers that speak it, HLS, and the way podcast apps play any feed's audio.