Settings

Session-only.

Session-only. A shallow merge: the keys sent replace the stored ones, omitted keys are left alone, and the merged object comes back.

timezone must be an IANA region, not a fixed abbreviation. The region carries the DST rules — Europe/Berlin is CET in winter and CEST in summer, switching on the right dates by itself, and a region with no summer time never shifts. Storing CET would freeze the offset and put half a European year an hour out, silently: listens would still store correctly and only "today", the hour-of-day heatmap and the trajectory buckets would be wrong.

Half the track or four minutes, whichever comes first, is only the default: it is a per-user setting, because that convention fits a three-minute pop song far better than a forty-minute raga or a ninety-second hardcore track. A client that hardcodes it disagrees with the listener's own choice, silently, and nothing anywhere errors.

Following it is not cosmetic agreement. The same threshold decides whether a track this client announced as now-playing and never scrobbled is written off as a skip — so submitting later than this rule banks the listen and leaves a skip behind it, and submitting earlier puts a listen on a permanent public record that the listener's own setting says had not been heard.

Reported as the server computes it, never as stored: the values are clamped (fraction 0.05–1.0, seconds 10–3600), so a preferences object holding nonsense reads as the number every source here actually uses. GET /api/v1/preferences serves the raw blob and is session-only.

Accepts a plain submit token, not read: this read exists only to decide a submission, and putting it behind read would make every scrobble client carry read access to the whole listening history to learn one number it is obliged to obey.

It is its own endpoint rather than more keys on /1/validate-token — the opposite call from the introspection there, and deliberately. Those keys describe the token, are asked once at setup, and stay correct when cached. This is a setting, changed from a settings screen at any time; cached from a setup handshake it would go quietly stale, which is the failure this endpoint exists to prevent. Re-read it when a session starts.

Admin, session-only. Returns the address — which is not a credential and is shown the way a source's URL is — and never the API token.

Admin, session-only — a token gets 401 and scopes never enter into it, the line /api/v1/sources already sits on. Server-wide rather than per-user: amai is one box the operator runs over one library, and every user here reads the same catalogue. Stored encrypted, and a stored value beats TAPEDECK_AMAI_URL / _TOKEN / _SERVER.

Each field is written only when present, so saving one does not wipe another; clearing is an explicit empty string. An address with no http:// or https:// scheme is a 400 rather than being guessed at — guessing http would silently downgrade an instance meant to be reached over TLS.

server names which of amai's own media servers this instance's provider ids belong to (its display name or internal id). Absent means amai's default server, which is the whole answer on a single-server install.

Admin, session-only. Two questions, reported separately, because they need completely different things doing about them and a screen that only says ok: false makes them the same colour. amai's own before_request barrier exempts /api/health and nothing else, so reachability is answerable without a credential and a bad token is a clean 401 — the inverse of the Discogs trap, where a bad credential is served as a normal 200.

A rejection is a 200 with ok: false, not an HTTP error: the request to Tapedeck succeeded and the answer is "no".

servers carries only server_id, name, server_type and is_default. amai's own response also holds a masked creds map; nothing here stores or logs it.

Admin, session-only. The measurement that decides whether anything is worth building on the sidecar, and it narrows in three steps.

The structural ceiling. A listen joins to amai on a media-server provider id, so one that never came off Plex, Jellyfin or Navidrome cannot join at all whatever amai has analysed. joinable_* is that, computed over the whole history because it is a plain string test.

What amai has, measured on the most-played tracks. Weighted by plays rather than sampled evenly, because a track played fifty times is worth fifty times as much to anything built on these vectors.

What the sample is a sample of — sample_share_of_listening — so the figure above is never read as a fact about the whole history. A share stated without its population is the fidelity-card failure.

One request per track against amai, so the handler owns a deadline rather than trusting N × the client timeout. deadline_hit says when it stopped early, and a failed ask is never counted as a miss: error carries the first one.