README: fediverse section (settings, posting rules, endpoints, delivery logs); who sees what on /@name and /tags

8edc7bd · gmorell · 2026-11-18 21:49

1 files +37 -1

Files changed

modified README.md
+37 −1
@@ -24,7 +24,9 @@ Running at **https://finaltrack.neiam.org** (deployment:
24 24 - **Landing grid** (`/`): the latest plays as album art, live. Public:
25 25 visitors see what was played, members also see who.
26 26 - **Covers**: uploaded on the album page, or fetched from MusicBrainz and
27 − the Cover Art Archive (automatically the first time an album is played).
27 + the Cover Art Archive (automatically the first time an album is played;
28 + a collaboration credit like "Justice & Tame Impala" falls back to the
29 + main artist).
28 30 - **Private marks**: mark an artist, album or track private and your plays
29 31 of it are only ever shown to you — past ones included, everywhere,
30 32 fediverse posts too.
@@ -62,6 +64,7 @@ curl -X POST https://HOST/api/v1/scrobble \
62 64 | Viewer | Sees |
63 65 |---|---|
64 66 | Anyone | the landing grid: what was played and when, never by whom |
67 +| Anyone, for a member with a fediverse account | that account's non-private plays on `/@name` and, if it posts publicly, under `/tags/<tag>` |
65 68 | Members | charts, library, album and artist pages, who played what |
66 69 | Fediverse followers | a member's non-private plays, if they turned an account on |
67 70 | You | everything you've played |
@@ -69,6 +72,37 @@ curl -X POST https://HOST/api/v1/scrobble \
69 72 Everything shared is filtered by `FinalTrack.Privacy.visible_to/2` at read
70 73 time, which is why marking something private also hides the past.
71 74
75 +## Fediverse
76 +
77 +Off unless `FINAL_TRACK_ACTIVITYPUB=true`; then each member opts in on the
78 +Scrobbling page with a username, and chooses:
79 +
80 +- **Who sees the posts.** Followers' feeds only (unlisted, the default) or
81 + public. Pixelfed and angler show only public posts on a remote profile
82 + and only backfill public ones, so an unlisted account looks empty there
83 + although followers get every post.
84 +- **A hashtag** on every post, `#scropple` by default; empty for none.
85 +- **The artist as a hashtag** too (off by default).
86 +
87 +Each new play that isn't private becomes a Note with the album cover
88 +attached, delivered to followers about 15 seconds after the scrobble (up
89 +to a minute more if the album's first cover lookup is still running:
90 +Pixelfed drops posts without media). Plays more than 6 hours old when
91 +they arrive — a phone's offline queue draining — are recorded but not
92 +posted. Marking something private sends a `Delete` for what it now covers.
93 +
94 +Served: `/.well-known/webfinger` (`acct:user@host`, `acct:@user@host`, or
95 +the actor or `/@user` URL), `/.well-known/host-meta`, `/.well-known/nodeinfo`
96 +and `/nodeinfo/2.0`, the instance actor `/ap/actor`, accounts under
97 +`/ap/users/:name` (inbox, outbox, followers), posts at `/ap/notes/:id`, the
98 +shared inbox `/ap/inbox`. Inbound: `Follow`, `Undo` of one, `Delete` of an
99 +actor that's gone; every request's HTTP signature is checked.
100 +
101 +Every delivery is logged as a `federation:` line with the inbox and the
102 +status it got (retries included). Remote servers answer 2xx and process
103 +later in their own queues, so a post that "never showed up" may just be
104 +waiting there.
105 +
72 106 ## Development
73 107
74 108 ```sh
@@ -140,5 +174,7 @@ and ActivityPub deliveries; covers must be on a volume all pods share.
140 174 | `FinalTrack.Privacy` | private marks and the visibility rule |
141 175 | `FinalTrack.Covers` (+ `Fetcher`, `Queue`, `Store`, `Image`) | cover upload, lookup, storage |
142 176 | `FinalTrack.Federation` (+ `Objects`, `HTTP`, `HTTPSignature`, `Delivery`) | ActivityPub; signatures and guarded HTTP ported from angler |
177 +| `FinalTrackWeb.FederationController`, `ProfileController`, `TagController` | the ActivityPub endpoints, `/@name`, `/tags/:tag` |
178 +| `FinalTrackWeb.Api.ScrobbleController`, `Plugs.ScrobbleAuth` | the scrobbling API |
143 179 | `FinalTrack.Accounts` | users, invites, display names |
144 180 | `FinalTrack.Release` | what `bin/migrate`, `bin/invite` run |

Parents: 870f945