ModuleDraft 0.2, for comment

On this page
  1. OpenSubsonic is the delivery protocol
  2. What the person keeps there
  3. Records
  4. Playing
  5. Media in feeds
  6. Sources without OpenSubsonic
  7. Open questions
  8. Prior art

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:

WhatHow to read itIn the collection
Their favouritesgetStarred2the saved list, copies ownership: none unless they are also the person's own
Their own playlistsgetPlaylists, 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 uploadthe 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 librarygetAlbumList2 (paged) and getAlbum, only when the person says the server's library is theirsthe library list, copies ownership: file
A store's collection (Bandcamp)getAlbumList2 and getAlbum: there, the list is the person's purchasesthe library list, copies ownership: digital
Everything else the server can playsearch3not imported: search results, which the person may keep one by one

Records

OpenSubsonicMIX
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[], createditem 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, createditem 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> }
playCountthe 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

OpenSubsonicMIX
stream, download, getCoverArtan 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 streamplain audio with 200 (Navidrome and Funkwhale do this) or a redirect to a CDN (Bandcamp): apps MUST handle both
scrobblean 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)
getOpenSubsonicExtensionsapiKeyAuthentication: 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

  1. Offline downloads from subscription sources: allowed, and with what expiry? (OpenSubsonic's download gives the file; the source's terms decide.)
  2. 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.