On this page
Changelog
What was decided in the specifications, and when, newest first. The specifications say only the rules; this is where their history lives. Drafts keep their version until they are final, except where a change breaks files or apps: then the version moves, as Core did to 2.0 on 2026-11-11.
2026-11-22: Bandcamp artists by band id
A correction to the draft; the field and file format don't change, so no version moves.
- Core, artists: a Bandcamp profile's
refis the numeric band id, not the page's subdomain, which changes when the artist renames the page. The registry already asked for the platform's own ids. The page goes in the profile'surl.
2026-11-22: artists and titles as published
Corrections to the drafts; no field or file format changes, so no version moves.
- Core, combining: artist records with different identifiers are two artists. Their shared name suggests neither the artists nor their songs, and a shared profile only suggests.
- Core, combining: an item also looks like what its copies call it (
title,artists), so a retitled track or a one-off artist name is still suggested. - Feeds, Chorus: a reference's own
nameis the credit, on the same artist record. A track listed by reference is another copy of that recording, so compilations keep their tracks. A track'ssubtitleis part of its title. - Feeds, ActivityPub: an
Audiowithout aTrackis a recording when it has audio, a length or a place on an album, and otherwise a release when it links to a page. A plain string URL is a page, never audio.
2026-11-12: home actors
- Feeds gains Following with home actors, optional: a home may follow on ActivityPub with one
instance actor (signed fetches of public objects only) and one actor per person who turns it on
(follows, approvals, pushes). What one person's approved follow receives stays theirs. Additive,
so Feeds stays 0.3. The plan and the reasons are in
planning/service-actor.md.
2026-11-12: versions, examples, artwork
- Access 0.3 and Feeds 0.3, not 1.0 as first written: a module's version stays below 1.0 until a second home or
app implements it, and each has one implementation so far.
GET {base}answers"version": "0.3", and/melists"org.openmusiccollection.feeds": "0.3". Core stays 2.0. - Feeds: a reader may also fetch an entry's artwork images, under the same rules as the feed (
httpsonly, limits on size and rate). Core's rule against fetching URLs automatically now names feeds the person hasn't followed alongside files they haven't imported. - The Chorus example is a fictional label's feed (
examples/feeds/chorus-tidewater.json), with the same shape as published ones: label, artist, releases and tracks,$refs, media, purchase links,$deletedand a WebSub hub. No example quotes a real feed.
2026-11-11: the collection layer (Core 2.0)
MIX narrows to the one layer nobody else specifies: what a person keeps, across every platform, with its file and its app protocol. Publishing is Chorus's, ActivityPub's and the feeds'; playing is OpenSubsonic's. MIX reads them and stops defining its own versions of them. Read against Chorus, FEP-be68 and OpenSubsonic, and against a local Funkwhale 2.0 and Navidrome 0.64. These changes break files and apps, so the versions move: Core 2.0, Access 0.3, Feeds 0.3, Delivery 0.2, Folder 0.3, Catalog and Commerce 0.2.
Core 2.0
- Artists are records:
name,sort_name,disambiguation,ids(musicbrainz,isni),url,artwork_url,profiles(where the artist is on each platform),note. Optional: a collection of plain names needs none. artists,album_artistsandcomposersare credits:{ "name", "artist"?, "join"? }, the name as credited, who it is, and what joins it to the next. MusicBrainz's artist credits, and FEP-be68'sArtistCreditone to one. A producer with only strings writes[{ "name": … }].- Any link is a copy. A source's
platformis a registered name or any host name; on a host,refis the object's canonicalhttpsURL (a Chorus entity's is<feed URL>#<$id>). A source with the person's account uses its API's ids instead. A registered platform's hosts are that platform. This reverses the 2026-10-27 decision that a shop page's link goes invia: two collections holding the same link now match exactly, and an app can open or play it.viais only how something came in. - Copies gain
titleandartists, for what a source says differently (Beatport's "Extended Mix"). - Descriptors are optional. When a host has one, it is found by
rel="mix-source"(aLinkheader or a<link>), then the protocols' own advertisements, then/.well-known/mix-source.json; it listsprotocols(mix-access,opensubsonic,activitypub,chorus,feed,mix-delivery), a new registry, in place ofmodules. - A source holds what the person keeps there. What it merely lets them play (other people's libraries, a pod's public music, a catalog) is searched, never imported as theirs.
- A listen names the copy played:
origin_urlandmusic_service, ListenBrainz's own fields. - Combining: artists match by MusicBrainz id, then a shared profile, and by name only as a suggestion; the same artist on the first credit, title and length is a suggestion for recordings. A copy belongs to one item of its kind, so a single's page can be a copy of the release and of its song.
- The header's
typeismixandversion2.0;countsmay count artists. Records are written sources, artists, items, lists. A Core 2.0 reader still reads Core 1.0 files ("type": "omc"), turning artist strings into credits. Namespaces underorg.openmusiccollectionstay: they are opaque, and renaming them buys nothing. - Identifiers gain
isni. A new section relates MIX to Chorus, FEP-be68, OpenSubsonic and the feed formats.
Access 0.3
- Base
/mix/v1, cursor headerMIX-Cursor,GET {base}answers"mix": "2.0". GET /artists(by name, MusicBrainz id or profile URL),GET /artists/{id},PATCH /artists/{id};/changesreports artists.POST /itemstakes credits and keeps any link as a copy, adding a source for its host; the answer says whichcopiesit kept, andunknown_artistsfor artist ids it didn't know./mereports"core": "2.0"and Feeds when the home holds what arrives from follows.- Listens are matched to the copy they name first.
- The live check reads an artist, and with
--addchecks that a host-name copy is kept as a copy.
Feeds 0.3 is a reader's module. It defines no feed format: a follow record (kind, address
as a URL or acct: handle, artist, the feeds found there), how to find feeds at an address,
arrivals (an entry becomes held items with a copy on the publisher's host, media the publisher
gives, credits and artists), and an ingestion profile per format: Chorus 0.3, ActivityPub with
FEP-be68, RSS, Atom and JSON Feed, and a server's newest albums over OpenSubsonic. Publishing a list
shrinks to one optional profile: JSON Feed with each record in _mix (was _omc). The Atom
omc:item element and the feed-level kind are gone.
Delivery 0.2 names OpenSubsonic as the way apps play and download from a source: what of a
server is the person's own (favourites, their playlists, their uploads, a personal server's library
when they say it is theirs) and what is only searched; records from AlbumID3 and Child; stream
URLs built at play time and never stored; plays reported to the server and as listens to the home.
POST /play stays as the sketch for sources without OpenSubsonic.
Other modules
- Folder 0.3: optional artist notes in
Artists/; credits are a list of names, and credits that say more keep their data in theomcblock, with the names linked to the artists' notes. - Catalog and Commerce 0.2: a purchasing sketch (offer terms, checkout at the seller, a signed receipt sent to the home, revocation), marked as implemented nowhere.
- Share: an ActivityPub inbox is named as a future transport, not defined.
- What belongs where gains a seventh place: a protocol others already run is read through a module, never reinvented.
2026-10-27: what real tools need
A review walked the tools on deejay.tools, the DJ library converters and three demo apps built on a home's Access API through the specification. What it changed:
Core
- Items gain
note(the person's own text),composers,album_artists(display text next toalbum),release_typeon releases (album,single,ep,compilation, an open list), and the read-onlyplay_countandlast_played_at, which a home derives from listens. keyis written in ID3v2.4TKEYnotation (Am,F#,Dbm,o); enharmonic spellings are equal. Camelot and Open Key are for display.- Identifiers gain
iswc(T3452468001). filegainsaudio_hashandfingerprint(both{ "algorithm", "value" },fingerprintmoved from the DJ module). The same hash in one source is a moved file; on two sources, one item. A shared fingerprint is a suggestion.- Lists gain folders (
folder,parent,position),color, andfilterfor smart lists. A colour is a tag: an unordered list with acolor. Entries gainnote. Rolehistoryfor history playlists. No core listkind, noversion(mix name) field, no relations between tracks:iswcand catalogs cover "other versions of this song". - Ordered lists may repeat an item where the list's platform allows it.
- The platform registry gives each platform's
refform, and whether it is global or personal. A Bandcamprefis Bandcamp's numeric track or album id. - Combining adds
audio_hashas a firm match,fingerprintas a suggestion, and label plus catalogue number for releases, except represses (different copies on the same source). Lists'parentandfilterreferences follow the lists they name. - Listening history is kept by the home in ListenBrainz's format, apart from the collection.
- A home's namespace keeps everything about the collection (hidden tracks and lists too), in files and through Access alike; only the state of changes not yet sent to a source stays inside the home. Exporting and letting a new home read through Access carry the same data.
- An app may ask for what it sends to be held, and a held item keeps everything sent.
extis for what the person would miss if they left the app, never an app's cache. A guide to where a property goes (nowhere, an app's namespace, a module's, the core). A future Credits module will use DDEX's role names.- No vendor in normative text: a home's namespace is
com.example.homein examples. - A link on a registered platform (or a source with a descriptor) is a copy, on a source the home
adds if the person has none: the platform's ids are stable and shared, so the copy can be played
and matches exactly when the person later buys or saves it there. A shop page has no shared id, so
its link goes in
via. The source descriptor rule is unchanged.
Access
- Entries of ordered lists are addressed by position, with a list
version(a member andETag, never in files); a staleversionis409 version_conflict. Moving an entry is one request. Entrynotecan be changed. A repeat an ordered list's platform refuses is reported inunchanged, like every idempotent write, not asalready. GET /lists/cananswerscanfor every list in one request; every response carrying a list carriescan;/changesreports a list whosecanchanged. Smart lists answeradd: false./megainsuser.name.data_bytescovers only an app's own namespace, per app per record; module data has each module's own minimum (DJ: 1 MB per copy).- Who may write a namespace: the home's own, the home only; a module's, any app with the scope; an
app's own, that app (by its
client_iddomain, or the first app to write it). Everyone reads everything, and the person's own edits are never restricted.403 namespace_not_yours. - Apps may write
ratingas the person's value. Measured values go on the copy they came from. - Listens:
POST /listensin ListenBrainz's submit format,GET /listens, scopeslistens:writeandlistens:read. - Apps may be known by an address they own (OAuth Client ID Metadata Documents), alongside registered clients.
POST /items?hold=trueasks for the item to be held. An item needs a link or identifiers. A link on a registered platform is a copy (the home adds the source if needed); a shop's link goes invia.- Webhooks are left to each home. Device sign-in waits until an app without a web address needs it.
DJ
- DJ data lives on the copy whose audio was measured, file or stream.
- One timing basis: milliseconds from the first real sample, after the gapless header's delay and padding.
- Cue kinds
hot,memory,loop,fade_in,fade_out,load, an open list. - Compact beat grids,
[at_ms, bpm, beat_in_bar], markers only where something changes. The grid'sbpmplaces beats; the item's is for display. analysisgainsenergy,audio(previeworfull),bpmandkey.- Waveforms are never stored. Stems separated on the fly are the app's; stem files are file copies.
Other modules
- Feeds: a people's feed carries entry notes and never item notes. Recommendations are a feed.
- Folder: an item's body is its core
note, a list's is itsdescription; lists gainfolder,position,colorand a derivedparentlink;iswc,composers,album_artistsandrelease_typeare properties. - Catalog and Commerce: resolvers answer by copy as well as by identifier, for the platforms asked.
- Delivery: files on the person's own devices are out of scope.
2026-10-20
- Core. Ids are local, and collections combine by contents: sources by platform and stable
account(newaccount_namefor display;localsources never match on their own), copies by source andref, items by a shared copy, then MusicBrainz, ISRC or UPC, then title and artists as a suggestion only. Conflicts are settled by the person, never by timestamps. - A collection may be all releases. Copies gain
position(vinyl sides), and tracks on sources without track ids use<release ref>/<position>. Physical copies gainformat,format_details,conditionandlocation; releases gaincatalog_numberandcountry. - Ownership is a claim, and the person's correction wins (provenance origin
user). New rolewanted. Roles stay few; apps use namespaced values of their own (com.example.app/borrowed), shown as the nearest core value. - Dates: how item, copy and entry
added_atrelate;updated_atremoved (kept as unknown data from older files); provenance on copies and entries, with new originsestimatedandinferred. - The header carries no sync state;
countssplitsrecordingsandreleases; optional collectionname. - New modules: Share (sending music to someone) and Collector (a copy's history).
- Access. The cursor travels in the
OMC-Cursorheader of/collection, never in the file;canper app and list, never stored; lookups by content;POST /import; add-only apps (library:add); views by record type. DJ gains mixes. - Feeds. Feeds are JSON Feed 1.1 (and optionally Atom or RSS) with MIX records in their entries; push is WebSub; homes may publish a person's list as a feed.
- Folder.
omcandidreplaceomc_typeandomc_id(still read); notes made by hand (no id, a template,shelf); the collection'snamenames the folder.
2026-10-19
- Homes, apps and sources: a collection has exactly one home, apps change it in place within a view
the person gives each connection, and sources are places with their own copy that the home syncs
with. Connections, views, sync positions, change attribution and id maps are the home's state and
never appear in records or files.
viais written once, for people, on items and lists. - How core fields and extensions relate: core stands alone, an extension refines and never contradicts, core wins, a missing extension is derived from core. A host ignores writes to its own namespace instead of refusing them.
- List entries carry an optional copy
refon lists that live on a source, and an unordered list holds an item once per copy there. Found rebuilding real playlists from a home's export: Spotify Liked Songs held 38 pairs of copies the home knew as one recording each. - From a real collection of 7,567 items and 411 lists:
titlemay be empty (platforms return tracks they no longer serve without one), and a local file'srefmust at least replace the home directory with~when the producer doesn't know the source folder. The Folder module round-trips that whole collection record for record. - Access. Telling an app's own writes apart, with
byon change entries and a cursor on write responses. - Folder. Readers accept standard Markdown links and every Obsidian link style. The layout is free, so a folder per artist or letter needs no specifying. Tested on a 7,991-record collection rearranged by artist (354 repeated file names) and as a pile of randomly named notes.
2026-10-18
Found while building the reference validator, the examples and the first Access implementation:
- Lists on a source get an optional
ref(the source's own list id).savedallows one favourites list per kind of item (Spotify Liked Songs and Saved Albums). Ownership values are an open list like roles and kinds. - A host's own
extnamespace is the host's and read-only to apps; app data is everything that isn't the host's own field. PATCH is an RFC 7396 merge patch, host fields must be sent unchanged (422 field_not_writable), and host-managed dates are ignored. - A host may refuse data it can't keep (size, copies on sources it can't hold, entry data) with an error, never silently.
- The export header is per export; keeping unknown data applies to records.
- The platform registry gains
itunesandshelf. - Access scopes
library:read,lists:read,lists:write,library:write.