On this page
- Follows
- Finding what to follow
- Arrivals
- Ingestion profiles
- Chorus (0.3)
- ActivityPub with FEP-be68 Audio Objects
- RSS 2.0, Atom, JSON Feed (with Podcast and Media RSS)
- OpenSubsonic: a server's new releases
- Following with home actors
- Publishing a list (optional)
- What this module does not do
- Example: an app that collects new releases
- Open questions
- Prior art
Feeds module (draft 0.3)
Status: draft for comment. Namespace: org.openmusiccollection.feeds. Needs: Core 2.0.
Artists, labels and people already publish what's new, in formats that exist and work: Chorus feeds, ActivityPub objects (FEP-be68, as Funkwhale and Bandwagon publish them), RSS, Atom and JSON Feed. This module defines no feed format. It defines the other end: how a collection follows a publisher, and how what the publisher puts out arrives in the collection as items the person can keep, play and put in lists, matched against what they already have.
Three things, in order of importance: the follow record, the arrival rules, and one ingestion profile per format. A short optional profile at the end says how a home may publish a person's list, for publishers who want to use MIX records in a feed.
Follows
Who the person follows MAY travel with the collection, as module records, so a change of home keeps them:
{"type":"org.openmusiccollection.feeds/follow","id":"f1","kind":"artist","name":"Lumen Arcade",
"address":"https://tidewater-tapes.example/","artist":"a1",
"feeds":[{"protocol":"chorus","url":"https://tidewater-tapes.example/chorus.json"},
{"protocol":"feed","url":"https://tidewater-tapes.example/feed"}],
"followed_at":"2026-11-11T10:00:00Z"}
| Field | Type | Required | Meaning |
|---|---|---|---|
type | "org.openmusiccollection.feeds/follow" | yes | |
id | string | yes | |
kind | string | yes | artist, label, person (someone sharing what they like), feed (anything else), server (a whole server's new releases). An open list |
name | string | yes | What to show |
address | string | yes | What the person followed, as they gave it: an https URL, or a fediverse handle as acct:user@host |
artist | string | no | The id of the artist record this follow is about |
feeds | Feed[] | no | What the app found at the address: { "protocol", "url", "hub"? }, protocol from the core's protocol registry (chorus, activitypub, feed). A cache, written so another app needn't look again; an app MAY look again |
paused | boolean | no | The person keeps the follow but wants nothing new from it |
followed_at | timestamp | no | |
via, ext | no | As on items |
A follow is what the person chose. Which entries the person has seen, kept or turned away is the home's state (as what is held is), never in the record.
Finding what to follow
Given an address, an app resolves it to one or more feeds:
acct:or@user@host: WebFinger (/.well-known/webfinger?resource=acct:…), and the link withrel="self"and typeapplication/activity+json: the actor. Protocolactivitypub.- An
httpsURL:GETit as HTML and read<link rel="alternate">elements andLinkheaders by type:application/Chorus+json→chorus;application/activity+json→activitypub;application/feed+json,application/atom+xml,application/rss+xml→feed. A MIX descriptor may list the same underprotocols. - The URL itself with
Accept: application/activity+json: an actor or an object →activitypub. - Conventional paths:
/chorus.json,/feed.json,/feed,/rss,/atom.xml.
When several are found, prefer chorus (made for music), then activitypub (objects with
credits), then JSON Feed, Atom, RSS. An app SHOULD show the person what it found and let them
choose. A host that answers an OpenSubsonic ping is a server to connect as a source, not a feed to
follow (the Delivery module); an app MAY offer that instead.
Arrivals
An arrival is one entry of a followed feed, turned into MIX records. Every profile below ends in the same thing:
- one item (
recordingorrelease), with as much of the core as the entry gives, andprovenanceorigininferredfor what the app guessed; - at least one copy, on the publisher's host:
{ "platform": "<host>", "ref": "<canonical URL>", "url": "…", "ownership": "none" }(Core: A link is a copy). Links the entry gives to the same music elsewhere (a purchase link to Mirlo, a listen link to a streaming platform) are further copies on those hosts. A link on a registered platform becomes a copy there once the reader has the platform's id, and is left out until then; - media, where the entry carries audio the world may play: on the copy,
file(mime,size_bytes,bitrate_kbps) and, in this module's namespace,"ext": { "org.openmusiccollection.feeds": { "media": [{ "url": "…", "mime": "audio/mpeg" }] } }. Media URLs are the publisher's; an app plays them as plain HTTP audio and keeps nothing; via:{ "name": "<publisher>", "url": "<feed or address>" };- credits, with
artistids where the publisher gives an entity (an ActivityPubArtist, a Chorusartistentity), and the matching artist records; - a playlist entry (an ActivityPub
Playlist, a feed of a person's picks) becomes a list arrival: an ordered list whose entries are item arrivals.
Arrivals are held (Core: Held): nothing enters the collection until the person
keeps it, and a feed never adds to the collection on its own. A home MUST match each arrival
against the collection by the core's combining rules before
showing it, so what the person already has is shown as such, not offered again. An arrival the
publisher later deletes (Chorus $deleted, an ActivityPub Delete, an entry gone from a feed) is
withdrawn while held; a kept item is never removed by its feed.
An app or home that reads feeds MUST treat them as untrusted input: https only; nothing
fetched but the feed, its entries' artwork images and, on the person's request, its media; no HTML
rendered; limits on size and rate for all of it
(Core: Security and privacy).
Identity of an arrival (so that a refetch doesn't duplicate it): the feed's URL and the entry's
own id ($id, ActivityPub id, <guid>/<id>, JSON Feed id), kept by the home as its own state.
Ingestion profiles
The reference mapper (tools/feeds in the specification repository) implements the Chorus,
ActivityPub and JSON Feed profiles, and its tests map a fictional Chorus feed and a Funkwhale-shaped
outbox page.
Chorus (0.3)
Spec: https://mecagorp.com/chorus/0.3.2. A single JSON document, label → artist → release →
track, with permanent $ids and a $deleted list. Artists and labels publish it from their own sites today; a fictional feed of the same shape is examples/feeds/chorus-tidewater.json in the specification repository.
| Chorus | MIX |
|---|---|
| the document | one follow; the feed's host is the platform of the copies below; every entity's canonical URL is <feed URL>#<$id> |
artist entity: $id, name, url, images.thumb, links[rel=social] | artist record: name, url, artwork_url, profiles: { platform: <host>, ref: "<feed>#<$id>", url } plus one per social link (its host, its URL) |
label entity | label on its releases; an artist record only if the person follows the label |
release: name, subtitle, releaseDate, artist (a name or a $ref), featuring[], label, tags[rel=genre], images.main, url, license, copyright | item release: title (name, and subtitle after " - "), release_date (the date part), artists (a credit for artist, or for the artist entity the release is listed under, then one per featuring, joined by " feat. "), label, genres, artwork_url; copy { platform: <host>, ref: "<feed>#<$id>", url }, with license, copyright and the other tags (instrument, mood…) in the copy's module ext |
a reference with a name ({ "$ref", "name" }) as artist, in featuring, or as composer, lyricist or label | that name is the name as credited here. The artist record is the referenced entity's and keeps the entity's own name: a one-off name is still that artist |
release.links[rel=purchase] | one more copy per link, on the link's host |
a track in a release's $items by $ref, with an optional name or subtitle | no new item: one more copy on the referenced recording, ref = <feed URL>#<release $id>/<track $id>, release = this release, track_number = its position here (inferred), and title when it is called something else here. A track defined outside any release takes the first release that lists it as its own |
track: name, subtitle, trackNum, discNum, duration (seconds), artist, featuring, composer, lyricist, tags[rel=genre], media[]{src, contentType, size} | item recording: title (name, and subtitle after " - "), duration_ms, artists (as on the release; absent → the release's), composers (composer and lyricist, each name once), genres, album; copy release, track_number (the position in $items when trackNum is absent, marked inferred), disc_number, file from the first audio/* medium, media = every audio/* medium (audio/mp3 is audio/mpeg). A track's purchase link that its release also has stays on the release |
lastModified | a held arrival whose lastModified changed is updated |
$deleted | held arrivals with those $ids are withdrawn |
links[rel=websub] | subscribe at the hub; otherwise poll, honouring ETag and Last-Modified |
| relative URLs | resolved against the feed's URL |
ActivityPub with FEP-be68 Audio Objects
Spec: https://codeberg.org/petitminion/fep/src/branch/fep-be68/fep/be68/fep-be68.md (draft).
Publishers: Funkwhale (actors at /federation/actors/{name}; channels publish through their outbox,
and also as RSS at /api/v2/channels/{name}/rss), Bandwagon (albums typed ["Album","Article"]
with the same artist_credit). Reading needs no actor of one's own for public objects: GET with
Accept: application/activity+json. A server that requires signed fetches answers 401: a home
with an instance actor (below) signs and retries; otherwise the app MUST tell the person that
this server only talks to fediverse accounts, and MUST NOT pretend to follow. Sending a
Follow, reading restricted libraries and receiving pushes need an actor of the home's own:
Following with home actors.
| be68 / ActivityStreams | MIX |
|---|---|
actor (from WebFinger or a URL); outbox → OrderedCollection → pages | one follow; kind from the actor: Person → person, a channel or an Artist's actor → artist, Service → server |
Artist: id, name, musicbrainzId, actor, image | artist record: name, ids.musicbrainz, artwork_url, profiles: { platform: <host>, ref: <Artist id> } and, when present, { platform: <actor host>, ref: <actor id> } |
ArtistCredit[]: artist, credit, joinphrase | Credit[], one to one: artist (the artist record above), name = credit, join = joinphrase when not empty. In the order given (Bandwagon adds index) |
Album: id, name, released, artist_credit, musicbrainzId, image, tag | item release: title, release_date, artists, ids.musicbrainz, artwork_url, genres; copy { platform: <host>, ref: <Album id>, url: <its page, else the id> } |
Track: id, name, position, disc, album, artist_credit, musicbrainzId | item recording: title, artists (absent → the album's), album, ids.musicbrainz; copy ref = the Track's id, release (the Album's item), track_number = position, disc_number |
Audio: url{href, mediaType}, size, bitrate (bits per second), duration (ISO 8601 or seconds), track, library, to/audience | on the Track's copy: file: { mime, size_bytes, bitrate_kbps } and the item's duration_ms; media = the audio/* link, only when the Audio is public (addressed to as:Public, or read unsigned without an audience that says otherwise). Otherwise the copy has no media, and the app says why |
Audio with no track, and with an audio link, a duration, a position or an album | the Audio is the recording (as Funkwhale channels publish it): mapped as a Track and its own Audio |
Audio with no track and none of those, only a page (as stores announce a release) | item release, kind inferred: title = name, release_date = the date part of published (estimated), genres from tag, artwork_url from image; copy ref = the Audio's id, url = the page; no media. artists from artist_credit, else the followed actor's name (inferred) when the Audio is attributedTo that actor, else empty |
a url that is a plain string | a page. It has no media type, so it is never media |
Playlist: name, attributedTo, items → PlaylistTrack (track, index) | a list arrival: ordered, name, entries in index order, each an item arrival of its Track |
Create, Update, Delete, Announce in the outbox | add, update, withdraw. An Announce of an Album or Track is an arrival whose via names the announcer |
Listening, TrackFavorite | not read in this version (the FEP has no schema for them yet) |
@context | Funkwhale's terms and Bandwagon's differ; readers match on type and property names, not on context URIs |
RSS 2.0, Atom, JSON Feed (with Podcast and Media RSS)
Publishers: Faircamp (Atom, RSS, Podcast RSS, Media RSS), Funkwhale channels, blogs, newsletters.
These feeds are not made for music, so the mapping guesses, and marks what it guessed inferred.
| Feed | MIX |
|---|---|
feed title, link/home_page_url, image/icon, author | the follow's name, via; kind feed unless the person says artist |
entry id/guid, title, link/url, published/pubDate/date_published, image, itunes:image, media:thumbnail | item: title, release_date (the date part of published, estimated), artwork_url; kind release unless the entry has exactly one audio enclosure (then recording); artists from itunes:author or author when it isn't the feed's own name, else empty; copy { platform: <link host>, ref: <link URL>, url } |
enclosure, media:content, JSON Feed attachments[] with an audio/* type; itunes:duration, duration_in_seconds | media (every audio/* one), file from the first, duration_ms |
itunes:episode | track_number when the feed is one release; otherwise ignored |
JSON Feed _mix member on an item | the record as published (a Core 2.0 item, copies by platform): no guessing. See Publishing a list |
entries in a feed that carries _mix records, without one and without audio | news: not an arrival |
hubs[] / <link rel="hub"> | WebSub; otherwise poll with ETag and Last-Modified, at most hourly unless ttl or sy:updatePeriod says otherwise |
OpenSubsonic: a server's new releases
Not a feed, but often wanted as one: "what's new on my pod". A follow of kind: server on a server
the person has connected as a source (Delivery) reads getAlbumList2?type=newest and
turns the albums the collection lacks into release arrivals, mapped as the Delivery module maps
AlbumID3, with copies on that source. That list holds everything the server lets the person play,
not only what is theirs, which is why its albums arrive held and never come in on their own
(Core: Sources). A server the person isn't signed in to can't be followed this
way.
Following with home actors
Optional. A home MAY take part in ActivityPub so its follows are real ones: the publisher sees a follower, approves it when its content isn't public, and pushes what's new instead of waiting to be polled. Two kinds of actor, both served by the home itself (no separate server per person):
- One instance actor (
Application), which MUST only sign fetches of public objects. It MUST NOT follow anyone or receive anything addressed to it privately: an approval granted to the home would open a library to everyone on it. - One actor per person who turns it on (
Person, handlename@home), which follows, is approved, and receives. Off until the person chooses a handle.
| The home MUST | |
|---|---|
| Discovery | WebFinger for both actors; NodeInfo 2.x |
| Signing | Sign every request with HTTP Signatures (rsa-sha256, (request-target) host date digest), and verify every activity it receives against the sender's key |
| Following | Follow from the person's actor; Undo when they unfollow or turn the actor off; a follow waiting on Accept is shown as waiting, a Reject or Block as such |
| Arrivals | Turn Create, Update, Delete, Announce into arrivals through the profile above, exactly as if read from the outbox. Polling may continue as a fallback |
| Privacy | Not show what reached one person through an approved non-public follow to anyone else on the home. Public objects may be fetched once and shared among the home's followers of the same publisher |
| Honesty | Tell the person, before they follow, which handle the publisher will see. Publish nothing on their behalf beyond the actor, its follows and Undos |
Who integrates: a home (Tangle). Publishers do nothing: to them it is one more fediverse account.
Publishing a list (optional)
A home MAY publish one of the person's lists at a URL the person chooses to share. The
recommended form is JSON Feed 1.1 with each item carrying its MIX record in _mix, so a plain
feed reader shows entries and a MIX app gets records it can keep:
{ "version": "https://jsonfeed.org/version/1.1", "title": "Anna's picks",
"home_page_url": "https://home.example/anna/picks", "feed_url": "https://home.example/anna/picks/feed.json",
"hubs": [{ "type": "WebSub", "url": "https://hub.example/" }],
"items": [{ "id": "e1", "url": "https://tidewater-tapes.example/releases/glass-tides", "title": "Glass Tides",
"content_text": "Start here.", "date_published": "2026-11-10T08:00:00Z",
"_mix": { "type": "item", "id": "e1", "kind": "recording", "title": "Glass Tides",
"artists": [{ "name": "Lumen Arcade" }],
"copies": [{ "platform": "tidewater-tapes.example", "ref": "https://tidewater-tapes.example/chorus.json#track-5f1c2a90-0d1e-4c8b-9a77-1b2c3d4e5f60",
"url": "https://tidewater-tapes.example/releases/glass-tides", "ownership": "none" }] } }] }
Newest additions come first. Each entry is the item as the home has it, with copies by platform
(a feed has no sources), and without the person's own data: no via, no item note, no other
apps' namespaces, no personal refs such as file paths. The list entry's note is the exception: it
is the blurb the person wrote for this list, so it travels, in content_text. A home publishing a
list of releases SHOULD also offer it as a Chorus document, so Chorus readers can follow it
without knowing MIX. Discovery is the feeds' own: <link rel="alternate" type="application/feed+json">.
A home that publishes a list is a publisher like any other: it is followed through the profiles above, and its records arrive like everyone else's. Recommendations are published the same way: music the person doesn't have yet is a feed they follow, so their collection never fills with music nobody chose.
What this module does not do
Define a feed format of its own; put the person's unseen entries anywhere but the home's state; post, reply or publish anything to the fediverse on the person's behalf (home actors only follow and receive); define offers or prices (the Catalog and Commerce module); define sending music to a person (the Share module).
Example: an app that collects new releases
An app that brings music into the person's collection, built only from public pieces:
- The person connects it to their home with
library:add(Access); the app makes its list, "New from labels I follow", and, to keep follows in the collection, asks for a view with"records": ["org.openmusiccollection.feeds/follow"]andlibrary:write. - It follows what the person chooses, and reads those feeds through the profiles above.
- It adds each release the person keeps with
POST /items?list=<its list>, copies on the publisher's host included. The home answersexistingfor a release the person already has, orheldwhile the person decides. - Its list is an ordinary list. Any other app the person uses shows it, and it moves with the collection.
An app that reads the person's email (with its own access to their mailbox) works the same way,
marking what it guesses inferred. Music sent to the person, rather than fetched by an app, is the
Share module.
Open questions
- Should a home that publishes lists also publish them as an ActivityPub actor with an outbox (so fediverse users can follow a MIX home), and would that be this module or a new one?
ListeningandTrackFavoritefrom FEP-be68 as arrivals of what a followed person plays and likes, once the FEP gives them schemas (MIX would propose ListenBrainz's fields).- A profile for Canimus, Chorus's predecessor (Mirlo, Song Fight!): worth one, or read Mirlo through ActivityPub?
- Should publishers sign feeds, so an app can show "published by the artist"?
What was decided, and when, is in the changelog.
Prior art
RSS, Atom, JSON Feed and WebSub; the Podcasting 2.0 namespace (which extended RSS rather than replacing it); Chorus and Canimus; FEP-be68 and Funkwhale's federation; Bandcamp's fan feed.