ModuleDraft 0.3, for comment

On this page
  1. Follows
  2. Finding what to follow
  3. Arrivals
  4. Ingestion profiles
  5. Chorus (0.3)
  6. ActivityPub with FEP-be68 Audio Objects
  7. RSS 2.0, Atom, JSON Feed (with Podcast and Media RSS)
  8. OpenSubsonic: a server's new releases
  9. Following with home actors
  10. Publishing a list (optional)
  11. What this module does not do
  12. Example: an app that collects new releases
  13. Open questions
  14. 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"}
FieldTypeRequiredMeaning
type"org.openmusiccollection.feeds/follow"yes
idstringyes
kindstringyesartist, label, person (someone sharing what they like), feed (anything else), server (a whole server's new releases). An open list
namestringyesWhat to show
addressstringyesWhat the person followed, as they gave it: an https URL, or a fediverse handle as acct:user@host
artiststringnoThe id of the artist record this follow is about
feedsFeed[]noWhat 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
pausedbooleannoThe person keeps the follow but wants nothing new from it
followed_attimestampno
via, extnoAs 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:

  1. acct: or @user@host: WebFinger (/.well-known/webfinger?resource=acct:…), and the link with rel="self" and type application/activity+json: the actor. Protocol activitypub.
  2. An https URL: GET it as HTML and read <link rel="alternate"> elements and Link headers 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 under protocols.
  3. The URL itself with Accept: application/activity+json: an actor or an object → activitypub.
  4. 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 (recording or release), with as much of the core as the entry gives, and provenance origin inferred for 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 artist ids where the publisher gives an entity (an ActivityPub Artist, a Chorus artist entity), 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.

ChorusMIX
the documentone 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 entitylabel 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, copyrightitem 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 labelthat 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 subtitleno 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
lastModifieda held arrival whose lastModified changed is updated
$deletedheld arrivals with those $ids are withdrawn
links[rel=websub]subscribe at the hub; otherwise poll, honouring ETag and Last-Modified
relative URLsresolved 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 / ActivityStreamsMIX
actor (from WebFinger or a URL); outbox → OrderedCollection → pagesone follow; kind from the actor: Person → person, a channel or an Artist's actor → artist, Service → server
Artist: id, name, musicbrainzId, actor, imageartist record: name, ids.musicbrainz, artwork_url, profiles: { platform: <host>, ref: <Artist id> } and, when present, { platform: <actor host>, ref: <actor id> }
ArtistCredit[]: artist, credit, joinphraseCredit[], 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, tagitem 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, musicbrainzIditem 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/audienceon 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 albumthe 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 stringa 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 outboxadd, update, withdraw. An Announce of an Album or Track is an arrival whose via names the announcer
Listening, TrackFavoritenot read in this version (the FEP has no schema for them yet)
@contextFunkwhale'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.

FeedMIX
feed title, link/home_page_url, image/icon, authorthe 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:thumbnailitem: 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_secondsmedia (every audio/* one), file from the first, duration_ms
itunes:episodetrack_number when the feed is one release; otherwise ignored
JSON Feed _mix member on an itemthe 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 audionews: 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, handle name@home), which follows, is approved, and receives. Off until the person chooses a handle.
The home MUST
DiscoveryWebFinger for both actors; NodeInfo 2.x
SigningSign every request with HTTP Signatures (rsa-sha256, (request-target) host date digest), and verify every activity it receives against the sender's key
FollowingFollow 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
ArrivalsTurn Create, Update, Delete, Announce into arrivals through the profile above, exactly as if read from the outbox. Polling may continue as a fallback
PrivacyNot 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
HonestyTell 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:

  1. 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"] and library:write.
  2. It follows what the person chooses, and reads those feeds through the profiles above.
  3. It adds each release the person keeps with POST /items?list=<its list>, copies on the publisher's host included. The home answers existing for a release the person already has, or held while the person decides.
  4. 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

  1. 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?
  2. Listening and TrackFavorite from FEP-be68 as arrivals of what a followed person plays and likes, once the FEP gives them schemas (MIX would propose ListenBrainz's fields).
  3. A profile for Canimus, Chorus's predecessor (Mirlo, Song Fight!): worth one, or read Mirlo through ActivityPub?
  4. 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.