neiam
/final_track
public · Issues · Pulls · Labels · Forks · Compare · Actions success · Badges · Packages
⭐
Log in to mark this repository.
README: what Final Track is, its API, who sees what, development, running it
72b0c51 · gmorell · 2026-11-18 21:38
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