README: what Final Track is, its API, who sees what, development, running it

72b0c51 · gmorell · 2026-11-18 21:38

1 files +135 -12

Files changed

modified README.md
+135 −12
@@ -1,18 +1,141 @@
1 −# FinalTrack
1 +# Final Track
2 2
3 −To start your Phoenix server:
3 +A self-hosted scrobble server for you and your people. Phones running
4 +[Scropple](https://gg.neiam.co/r/neiam/scropple-android) (or anything that
5 +speaks its HTTP backend's JSON) post what they play; members see charts by
6 +day, week, month and year, a library of every artist and album with its
7 +numbers, and a live wall of album art on the front page.
4 8
5 −* Run `mix setup` to install and setup dependencies
6 −* Start Phoenix endpoint with `mix phx.server` or inside IEx with `iex -S mix phx.server`
9 +Running at **https://finaltrack.neiam.org** (deployment:
10 +`argo-01-bos/finaltrack`). Phoenix 1.8 / LiveView, PostgreSQL.
7 11
8 −Now you can visit [`localhost:4000`](http://localhost:4000) from your browser.
12 +## What's in it
9 13
10 −Ready to run in production? Please [check our deployment guides](https://phoenix.hexdocs.pm/deployment.html).
14 +- **Scrobbling API.** `POST /api/v1/scrobble` and `/api/v1/now-playing`,
15 + the same contract ircd's ScrobbleServ accepts, so one phone can feed both
16 + (and Last.fm) at once. Per-device bearer tokens, made and revoked on the
17 + Scrobbling page; only their hashes are stored.
18 +- **Charts** (`/charts`): top artists, albums and tracks for any day, week,
19 + month or year, plays over time, who's listening now, latest plays.
20 + Periods follow the viewer's time zone (Postgres does the zone math).
21 + Everyone's, or just yours.
22 +- **Library** (`/artists`, `/albums`): everything that's been played, with
23 + plays, listeners, tracks, first and last played. Sort, search, scroll.
24 +- **Landing grid** (`/`): the latest plays as album art, live. Public:
25 + visitors see what was played, members also see who.
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).
28 +- **Private marks**: mark an artist, album or track private and your plays
29 + of it are only ever shown to you — past ones included, everywhere,
30 + fediverse posts too.
31 +- **Fediverse** (optional, off by default): a member can give their plays
32 + an account (`@name@host`) that Mastodon, Pixelfed and others can follow;
33 + each non-private play is posted with its cover, followers-only or public.
34 + `/@name` is the profile.
35 +- **Accounts**: invite-only registration, email/password and magic links
36 + (`phx.gen.auth`), optional OpenID Connect sign-in via
37 + [`neiam_auth`](https://gg.neiam.co/neiam/neiam_auth).
11 38
12 −## Learn more
39 +## The scrobbling API
13 40
14 −* Official website: https://www.phoenixframework.org/
15 −* Guides: https://phoenix.hexdocs.pm/overview.html
16 −* Docs: https://phoenix.hexdocs.pm
17 −* Forum: https://elixirforum.com/c/phoenix-forum
18 −* Source: https://github.com/phoenixframework/phoenix
41 +```sh
42 +curl -X POST https://HOST/api/v1/scrobble \
43 + -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
44 + -d '[{"artist": "Pink Floyd", "track": "Time",
45 + "album": "The Dark Side of the Moon",
46 + "durationSec": 413, "timestamp": 1763494445}]'
47 +```
48 +
49 +- Body: one object, a bare array, or `{"scrobbles": [...]}` (up to 500).
50 + `artist` and `track` are required; `album`, `albumArtist`, `durationSec`
51 + and `timestamp` (Unix seconds, when the play started) are optional.
52 +- Answers `200 {"accepted": n, "rejected": m}`; all invalid is a `422`. A
53 + retried batch adds nothing: plays are unique per user, track and time.
54 +- `POST /api/v1/now-playing` takes one object and answers `204`.
55 +- Every bad or missing token is the same `401`.
56 +
57 +## Who sees what
58 +
59 +| Viewer | Sees |
60 +|---|---|
61 +| Anyone | the landing grid: what was played and when, never by whom |
62 +| Members | charts, library, album and artist pages, who played what |
63 +| Fediverse followers | a member's non-private plays, if they turned an account on |
64 +| You | everything you've played |
65 +
66 +Everything shared is filtered by `FinalTrack.Privacy.visible_to/2` at read
67 +time, which is why marking something private also hides the past.
68 +
69 +## Development
70 +
71 +```sh
72 +podman compose up -d # Postgres on localhost:54330 (docker works too)
73 +mix setup # deps, database, assets
74 +mix phx.server # http://localhost:4000
75 +mix final_track.invite # a registration link (invite-only by default)
76 +```
77 +
78 +Before committing: `mix precommit` (warnings as errors, unused deps,
79 +format, tests). Tests use the compose Postgres too; `POSTGRES_PORT=5432`
80 +points them at a host Postgres instead. Outbound HTTP (MusicBrainz, other
81 +fediverse servers) is stubbed with `Req.Test` in tests.
82 +
83 +In dev, covers are stored under `priv/uploads/` and fetched automatically,
84 +so scrobbling locally makes real requests to MusicBrainz.
85 +
86 +## Running it
87 +
88 +The image is built by `.forgejo/workflows/image.yml` on every push to
89 +master: `ggr.neiam.co/neiam/final_track:{master,latest,sha-…}`. The release
90 +(`mix release`) ships these scripts in `bin/`:
91 +
92 +| Script | |
93 +|---|---|
94 +| `server` | start the app (`PHX_SERVER=true`) |
95 +| `migrate` | run migrations (an init container in Kubernetes) |
96 +| `invite [--email E] [--note N] [--days D] [--by E]` | print a single-use registration link |
97 +| `invite-link EMAIL` | a fresh link for an invite addressed to EMAIL |
98 +| `final_track rpc 'FinalTrack.Covers.retry_misses()'` | look up covers again for albums that never matched |
99 +
100 +The About page has copy-ready Podman/Docker commands for a single box.
101 +
102 +### Configuration (env, read at boot)
103 +
104 +| Variable | Default | |
105 +|---|---|---|
106 +| `PHX_HOST` | — | public host; also the domain fediverse accounts live on |
107 +| `SECRET_KEY_BASE` | — | required, 64+ bytes |
108 +| `POSTGRES_HOST`, `_PORT`, `_USER`, `_PASSWORD`, `_DB` | — | preferred (passwords with URL characters survive) |
109 +| `DATABASE_URL` | — | used when `POSTGRES_HOST` isn't set |
110 +| `PORT`, `POOL_SIZE` | `4000`, `10` | |
111 +| `FINAL_TRACK_COVERS_DIR` | `/var/lib/final_track/covers` | shared between replicas |
112 +| `FINAL_TRACK_AUTO_FETCH_COVERS` | `true` | look up a cover the first time an album is played |
113 +| `FINAL_TRACK_COVER_INTERVAL_MS` | `2200` | between MusicBrainz requests, per pod (its limit is ~1/s per IP) |
114 +| `FINAL_TRACK_MUSICBRAINZ_USER_AGENT` | `FinalTrack/0.1 (self-hosted scrobble server)` | put a URL or address to reach you in it |
115 +| `FINAL_TRACK_ACTIVITYPUB` | `false` | fediverse accounts; settle `PHX_HOST` first |
116 +| `SMTP_RELAY`, `SMTP_PORT`, `SMTP_USERNAME`, `SMTP_PASSWORD`, `SMTP_SSL`, `SMTP_TLS`, `SMTP_AUTH` | — | mail. Optional: without a relay (and, if it needs auth, a password) mail is off — no emailed links, registration takes a password |
117 +| `MAIL_FROM_ADDRESS`, `MAIL_FROM_NAME` | `noreply@PHX_HOST`, `Final Track` | |
118 +| `OIDC_ENABLED`, `OIDC_ISSUER`, `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET`, … | off | see `neiam_auth`'s README; `OIDC_LOGIN_MODE` picks how SSO and passwords coexist |
119 +| `CLUSTER_NAMESPACE`, `POD_IP`, `RELEASE_COOKIE` | — | clustering in Kubernetes (below) |
120 +
121 +### Clustering
122 +
123 +With `CLUSTER_NAMESPACE` set, libcluster lists that namespace's pods
124 +labelled `name=finaltrack` and connects to `final_track@<pod ip>`
125 +(`rel/env.sh.eex`, from `POD_IP`); `RELEASE_COOKIE` must match across
126 +pods. PubSub then spans every replica, so a scrobble landing on one pod
127 +updates pages served by another. Each pod runs its own cover-lookup queue
128 +and ActivityPub deliveries; covers must be on a volume all pods share.
129 +
130 +## Where things are
131 +
132 +| | |
133 +|---|---|
134 +| `FinalTrack.Scrobbles` | the API's validation, recording, now playing, tokens |
135 +| `FinalTrack.Catalog` | artists, albums, tracks (matched on normalised names) |
136 +| `FinalTrack.Charts` (+ `Charts.Period`) | every count: periods, timelines, library, summaries |
137 +| `FinalTrack.Privacy` | private marks and the visibility rule |
138 +| `FinalTrack.Covers` (+ `Fetcher`, `Queue`, `Store`, `Image`) | cover upload, lookup, storage |
139 +| `FinalTrack.Federation` (+ `Objects`, `HTTP`, `HTTPSignature`, `Delivery`) | ActivityPub; signatures and guarded HTTP ported from angler |
140 +| `FinalTrack.Accounts` | users, invites, display names |
141 +| `FinalTrack.Release` | what `bin/migrate`, `bin/invite` run |

Parents: 78e775b