neiam
/final_track
public · Issues · Pulls · Labels · Forks · Compare · Actions success · Badges · Packages
⭐
Log in to mark this repository.
README: fediverse section (settings, posting rules, endpoints, delivery logs); who sees what on /@name and /tags
8edc7bd · gmorell · 2026-11-18 21:49
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