Shelf

Scope: write (since v0.120), although it is a GET: it exists only to add a record to the shelf, and it spends rate-limited Discogs and MusicBrainz lookups doing it, so a token that can only read the shelf has no use for it. GET /api/v1/art/library makes the same call.

Discogs first when configured — it catalogues pressings, so a barcode usually resolves to the exact edition, often with real side letters that MusicBrainz lacks. Falls back to MusicBrainz.

Barcodes may be sent with or without the printed spacing; the unspaced form a scanner produces matches slightly more often.

Session-only. shelf.json (pressings, purchase dates, tracklists and an image manifest), plays.csv (every side played, oldest first, gear named), gear.json (equipment and chains with purchase dates) and scans/ — the images the user uploaded, one directory per pressing.

Images that live at the Cover Art Archive or Discogs are listed with their URLs rather than copied in: they are not the user's to redistribute and they are still there to fetch. Their own scans exist nowhere else, which is why those are the ones in the file.

This exists separately from GET /api/v1/backup for a concrete reason: a backup is a VACUUM INTO snapshot of the database, and uploaded scans are files beside it rather than rows inside it. A backup and this export together are the whole shelf.

Session-only, multipart/form-data, 256 MB maximum. The counterpart of GET /api/v1/physical/export, and deliberately not a database restore: it brings back the objects — pressings, tracklists, gear, the sides played, and your own scans.

What it cannot bring back is the listening. A shelf export holds no scrobbles, so the listens a side generated are not in the file, and the chain hours derived from them do not return with the objects. The response says so rather than leaving it to be discovered.

Everything is matched before it is inserted, so importing the same archive twice changes nothing the second time. A pressing is matched on its barcode or release MBID when it has one, and otherwise on artist, title and medium together; a side played is matched on its side and timestamp, so re-importing cannot double the wear on a stylus.

Signal chains are matched by name, never created — the same rule [[gear:…]] follows. A chain is something you build step by step, and conjuring an empty one from a name in a file would silently attribute listens to a chain with no components. Gear is created, since a piece of equipment is fully described by the file.

Nothing is written until shelf.json parses, so an unrelated or truncated zip fails before it has half-populated a shelf.

Scope: write (since v0.120), for the reason the barcode lookup is: it is the second half of adding a record, and it spends a Discogs request.

Scope: read (since v0.120).

Derived from physical_plays. A duplicate submission is not counted as wear.

Session-only. Never returns the credential itself.

Session-only. Accepts either a personal access token or a consumer key/secret pair — either is enough, since Tapedeck only reads the public database. The three-legged OAuth flow is deliberately not implemented: it exists so an app can act as a user, and registering an app hands you a key and secret that work directly. Stored encrypted.

Session-only, and necessary rather than a nicety: Discogs does not reject a bad credential. With a bogus key and secret, /releases/1 and /database/search both return a normal 200 with real data, and the rate-limit header reads the authenticated 60 — the limit is raised for the presence of an Authorization header without checking its contents. /users/{username} is the one endpoint that actually verifies, and is what this calls. Without it, a typo is indistinguishable from a working credential.

Scope: write (since v0.120). Its own route rather than a field on the push, because it is also what cancelling a side means and that has no track to name. Clears only entries this shelf reported — an idle turntable must not wipe a now-playing the user's phone is currently sending over ingest.

Scope: read (since v0.120). Returns { "spin": null } when nothing is on.

The shelf is the one source where the browser is the player, so the countdown runs in the page — but what is on and when it started live here. That is what lets a second device see the record, and what makes a side survive a browser crash.

A spin whose release has since been deleted is cleared and reported as nothing on, rather than returned as a dangling id.

Scope: write (since v0.120). One deck per user — the table's primary key is the user, because nobody listens to two records at once, so starting a second side replaces the first rather than erroring.

The whole state is sent every time rather than a patch per field: it is half a dozen small numbers, it changes only on real events (start, pause, skip, next track), and a partial update would let two devices interleave into a state neither of them meant.

Scope: write (since v0.120). Clears the now-playing entry as well, so the two cannot disagree. Recording a side (POST /api/v1/physical/{id}/play) clears it too — otherwise reopening the page would offer to resume a side that has already been logged, which is how one gets logged twice.

Scope: write (since v0.120).

Session-only, deliberately, for the reason removing a shelf item is: an uploaded file is deleted from disk with the row and cannot be recovered, and no backup holds it. A provider's image is only unlinked and can be fetched again.

Scope: read (since v0.120), and scoped to the caller by (id, user_id) — these are photographs of someone's own possessions and ids must not be walkable, the same rule the artwork proxy keeps.

Cached hard, because a scan never changes once uploaded, but private: it is per-user, and a shared cache holding it would serve it to the next person through the proxy. A provider-hosted image 404s here — it has a URL of its own and this server is not in front of it.

Scope: read (since v0.120).

Scope: write (since v0.120). Seed from a barcode lookup, or supply the tracklist yourself.

Scope: read (since v0.120).

Scope: write (since v0.120). When it was bought, what it is normally played through, and the note beside it.

Every field distinguishes absent from null: omitting one leaves the column alone, and an explicit null clears it. That is not decoration — a bare optional reads a misspelled key as an explicit null, so a typo would clear the chain it was trying to set and answer 200. Same shape and the same reason as default_chain_id on PATCH /admin/tokens/{id}.

chain_id and equipment_id are checked against the caller's own rows before they are stored.

kind is the exception to the absent/null rule — a format has no "cleared" state, so a plain optional is correct. Changing it rewrites the tracklist's sides, because what a side is depends on the medium: a record has a break assign_sides has to place by playing time, and a disc has none at all. The response reports sides_rewritten so a client knows the tracklist it is holding is stale.

Session-only, deliberately, although the rest of the shelf takes a write token: its plays and its images go with it, and any scan files the user uploaded are removed from disk — nothing else knows those files exist, so leaving them would orphan them permanently. Scans are not in GET /api/v1/backup, so this is the one shelf operation a lost phone could make unrecoverable, which is the line DELETE /api/v1/scrobbles sits on.

Scope: write (since v0.120). Sides are not reliably available from any provider — MusicBrainz records a vinyl track number as "A1" only when an editor entered one. When there is no explicit side letter the split is guessed by playing time, not track count, because a mastering engineer balances sides and a nine-minute closer would otherwise land on the wrong one. It is still a guess, which is why this endpoint exists.

None of that applies to a disc. A CD or SACD plays start to finish, so its tracks are numbered one unit per disc with no guessing at all — splitting a CD by playing time would invent a break that is not there. The medium's own format string decides which rule applies, not what was searched for.

It is also how a running time is typed in, which for a pressing no provider carries is the only way one is ever known. That is not cosmetic: scrobbles.duration is what every hours readout sums and physical_plays.duration_secs is what the stylus meter reads, so this corrects both alongside the tracklist rather than leaving three answers free to disagree. Whole-side plays only — a partial records how many tracks ran and never which, so its wear cannot be reconstructed.

Unlike POST /durations, a value here overwrites a stored one. That is the whole difference between the two: there the source is another pressing and a hand-typed figure must survive it, here the source is the person, and refusing their correction would make the field pointless.

Preview only — nothing is written. Session-only.

Exists because a record catalogued from Discogs often has no running times at all, which used to leave the deck showing three minutes a track as though it were a length. The lookup is a search (MusicBrainz id if the record has one, else barcode, else artist and title), so whatever comes back is a different pressing and may be ordered differently or carry bonus tracks — tracks are therefore matched by title, never by position.

complete: true means every track already has a duration and there is nothing to do. An empty durations with a null source means nothing with running times was found, which is a normal answer.

Session-only. Takes the proposals back rather than searching again, so what lands is what was on the screen — a preview that applies something else is worse than no preview.

Only fills a duration the record does not already have: one that was typed in, or that an earlier lookup got right, is never overwritten by a later fetch.

The listens already recorded from those sides are given the same figures, because every hours readout derives from scrobbles.duration. Their timestamps are not touched — physical_plays records when a side started and nothing about when it ended, so where the tracks fell is unrecoverable, and re-spacing them would assume the side ran uninterrupted.

Scope: write (since v0.120). Writes one listen per track, not one per side — every counting query in Tapedeck is over listens, so a side-shaped row would be invisible to all of them.

Timestamps are the one inferred thing here: you observed when the side started, so tracks are spaced by their running times. A track of unknown length gets three minutes — wrong but bounded, where stacking them on one instant would break session grouping and the hour-of-day heatmap outright.

Per-track outcomes from the browser deck are taken as authoritative: a side laid out from a start time can only describe an uninterrupted play. A skipped track is stored, excluded from every count, and never forwarded — and does not accrue gear hours.

Scope: write (since v0.120). The shelf is the one source where the browser is the player: the clock runs in front of the turntable, in localStorage, and nothing server-side can derive a playhead from a stack of rows. So the deck pushes here, where Plex, Jellyfin and Navidrome are polled.

Call it on every track change, on pause and resume, and on a heartbeat of about ten seconds. The heartbeat is not optional: the registry expires an entry by running past the end of the track it knows about, so a paused record would drop off the dashboard one track length after it was paused.

Now-playing is forwarded to the user's Last.fm and ListenBrainz only when the track actually changed, and never while paused — their now-playing is a one-shot that expires on its own, so re-sending it on every heartbeat is noise aimed at someone else's servers. The listens themselves are written by /play when the side comes off; this endpoint stores nothing.

Scope: read (since v0.120). A record has a side you reach for and a side you rarely turn over, and the release's own totals cannot say which is which.

Everything here is derived from the sides played on read — never a counter — so it cannot drift from the plays it counts, and deleting a play takes its wear back with it. secs is the running time of the tracks that actually played, which is the same figure the stylus is charged for: a side started at track four counts four tracks' worth. It is nominal rather than wall clock.

Only sides with plays are returned. A side that has never been played is not an entry with zeros — the caller holds the tracklist and fills those in. That also means a side may appear that is not on the tracklist at all: re-filing a release rewrites its sides (a vinyl A/B becomes a CD's 1) while its plays keep the label they were recorded with, and dropping those would leave the sides summing to less than the release total with nothing to say why.

Scope: read (since v0.120). Sleeves, labels, obi strips and booklet pages — the parts of a record you actually hold, which is why they are rows rather than one more artwork_url column. The Cover Art Archive carries 29 for a typical CD, 19 of them booklet pages.

Each entry carries a single src and thumb whichever provenance it came from: a provider's image is its own URL, an uploaded scan is a Tapedeck URL that checks who is asking. The server's own file layout is never in the response.

Scope: write (since v0.120). multipart/form-data: any number of file fields, plus optional kind and caption text fields that apply to all of them — which is what makes uploading a booklet in one go work, since the files land in the order they are sent.

The declared content type decides the stored extension; a filename from the client never reaches the path. Max 24 MB per image.

Uploads are files on the server rather than blobs in the database, so GET /api/v1/backup does not carry them — GET /api/v1/physical/export is what does.

Scope: write (since v0.120). Runs when the user asks rather than on a clock: the archive is not going to change under a record that has been on a shelf for thirty years, and the one case that does — an editor uploading the booklet you were missing — is exactly the case where the user knows and Tapedeck cannot.

Idempotent on the provider's own image id, so re-running this adds what is new and leaves the rest alone rather than stacking a second copy of all nineteen booklet pages on top of the first.

Discogs runs second and only when a credential is configured; it says only "primary" or "secondary" about an image, so everything but the cover lands in other for the user to file. A pressing with no MusicBrainz id is not an error — it comes back with a note saying there is nothing to look it up by.