GET /api/v1/stats/dashboard # Token reador Session
Dashboard counters.
Scope: read (since v0.39). "Today" and "this week" are bucketed in
the user's own timezone and honour their week-start preference.
Deliberately does not carry distinct artist, album or track counts.
It used to compute all three, each a COUNT(DISTINCT) building a temp
B-tree over the whole history, on the most-loaded page in the
application — and nothing rendered any of them. GET /api/v1/stats
answers the same question against a range control, which is where it
belongs.
Responses
application/json
object
The home screen's numbers. "Today" and "this week" are in your own
timezone, and the week starts on the day your preferences say.
today integer · int64 required
this_week integer · int64 required
total integer · int64 required
lossless_pct integer · int64 required
A whole percentage of fidelity_known, not of total.
fidelity_known integer · int64 required
Listens whose format is known — the population lossless_pct is a
share of. When that is a small slice, show the coverage rather than the
percentage: a 94% computed from 558 of 21,390 listens is a fact about
the 558.
top_artist string required
The most-played artist of the last 30 days, or — with none.
top_artist_count integer · int64 required
total_hours number · double required
today_hours number · double required
week_hours number · double required
avg_quality number · double required
Over the listens that carry a score; 0 with none.
401 No valid session cookie or token. Also returned when a token is
presented to a session-only endpoint — the endpoint does not accept
tokens at all, so the scope is irrelevant.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
{
"code": 401,
"error": "Authentication required. Log in to access this endpoint."
}
403 Authenticated, but not permitted. Either the token lacks the required
scope, or the endpoint needs the admin role. Deliberately not a 401 —
re-authenticating will not help.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
{
"code": 403,
"error": "This token does not have the 'write' scope"
}
Ranged statistics.
Scope: read (since v0.39). Totals, top lists (50 rows each), fidelity
mix, decades, a 7×24 listening heatmap, breadth, genres and languages.
The genre breakdown is a share of tag mentions, not listens — one
track carries several tags. Never present it as a percentage of plays.
Parameters
range query
The window, rolling back from now: today, d7 (or week), month
(or last30), year, or all, the default. Anything else is all time.
metric query
plays (default) or hours. How the three top lists are ranked,
not merely what number is shown. They are cut to 50 rows server-side,
so re-sorting in the client would only reorder the top 50 by plays
and would miss a long record played a handful of times — which is
exactly the row switching to hours exists to surface. Listens whose
source reported no duration count as zero and sort last.
Responses
application/json
object
Ranged statistics: totals, top lists (50 rows each), fidelity mix, decades,
a 7×24 listening heatmap, breadth, genres and languages.
totals object required
plays integer · int64 required
hours number · double required
Summed over the listens with a known length — see duration_known.
duration_known integer · int64 required
Listens hours is summed over. A listen whose source reported no
length contributes nothing, so hours is a floor rather than a total.
artists integer · int64 required
albums integer · int64 required
tracks integer · int64 required
avg_quality number · double required
0–100, averaged over quality_known listens only; 0 when there are none.
quality_known integer · int64 required
Listens avg_quality is averaged over. Only a live source ever writes a
quality score, so an imported history has none and the average is over
the same narrow population the fidelity shares are. Present it with its
coverage or not at all; at zero there is no score to show, not a score
of zero.
lossless_pct integer · int64 required
Share of fidelity_known, not of plays. A whole percentage.
dsd_pct integer · int64 required
Share of fidelity_known, not of plays. A whole percentage.
fidelity_known integer · int64 required
Listens in this window whose format is known — the denominator of the
two shares above. The fidelity array is a share of plays instead,
because it carries an Unknown bucket of its own.
skips integer · int64 required
Skipped plays in this window. Every other count in this object excludes
them; this one is about them. Not every source reports skips, so zero
means "nothing told us", not "nothing skipped".
per_day number · double required
Plays per calendar day of the window, including days with no
listening. Dividing by active days instead reports a busy afternoon's
rate as the year's.
first_listen integer | null · int64
Earliest non-skipped listen, unix seconds. A fact about the whole
history and therefore not ranged — asking it of a one-week window
would only restate the window.
loves integer · int64 required
Loved entities: tracks, records and artists together. All time, not
ranged.
top_artists array required
each item object
A top artist. Counted over everyone credited, the way the charts count.
plays integer · int64 required
hours number · double required
top_albums array required
each item object
plays integer · int64 required
hours number · double required
top_tracks array required
each item object
artist_credit string | null
Everyone credited, "; "-joined and primary first, when there is more
than one. artist is the primary alone.
album_artist string | null
Who album is filed under, which opens it.
plays integer · int64 required
hours number · double required
fidelity array required
DSD, Lossless, Lossy and Unknown, largest first. A share of
plays, because it carries the Unknown bucket of its own.
each item object
One slice of a breakdown.
plays integer · int64 required
pct integer · int64 required
A whole percentage of the breakdown's own total — which total, each
breakdown says.
decades array required
Release decades, 1970s and so on, oldest first. Only listens whose
release year has been resolved count, so pct is a share of those.
each item object
One slice of a breakdown.
plays integer · int64 required
pct integer · int64 required
A whole percentage of the breakdown's own total — which total, each
breakdown says.
genres array required
The twelve most-mentioned genres. A share of tag mentions, not
listens — one track carries several tags. Never present it as a
percentage of plays.
each item object
One slice of a breakdown.
plays integer · int64 required
pct integer · int64 required
A whole percentage of the breakdown's own total — which total, each
breakdown says.
languages array required
The twelve largest languages, over the listens that have been
classified.
each item object
pct integer · int64 required
A whole percentage of the classified listens.
heatmap array required
Seven rows of 24, counts of plays by hour, in your own timezone. Row 0
is Monday.
breadth object | null
Absent until the genre map is fetched and genres backfilled — "you play
0 genres" would be a lie about the listening rather than a statement
about the data.
genres_played integer required
genres_placed integer | null
Of those, the ones the map places.
effective_genres number | null · double
exp(H) over play counts — as varied as playing N genres equally.
evenness number | null · double
effective_genres over genres_played, 0–1. 1.0 would mean every
genre played exactly equally.
reach number | null · double
Your play-weighted spread over the map's own spread, 0–1. Null when
nothing played is on the map.
401 No valid session cookie or token. Also returned when a token is
presented to a session-only endpoint — the endpoint does not accept
tokens at all, so the scope is irrelevant.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
{
"code": 401,
"error": "Authentication required. Log in to access this endpoint."
}
403 Authenticated, but not permitted. Either the token lacks the required
scope, or the endpoint needs the admin role. Deliberately not a 401 —
re-authenticating will not help.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
{
"code": 403,
"error": "This token does not have the 'write' scope"
}
GET /api/v1/stats/graphs # Token reador Session
Statistics graphs.
Scope: read (since v0.130). Daily volume, obsession waves, the long
tail, sessions, first listens, habit-vs-burst, album spread and anchor
songs, for one range. Days are bucketed in your own timezone.
Artists are everyone credited, so the artist figures are shares of
artist credits, not of listens — a listen with two artists counts once for
each. volume and sessions count listens.
Parameters
range query
The window, rolling back from now: week, month (or last30),
year, or all, the default. Anything else is all time.
Responses
application/json
object
range string required
The range asked for: week, month, last30, year or all.
timezone string required
The IANA zone every day below is bucketed in.
capped boolean required
True when the history was longer than this server reads in one pass
(scaled to its memory). The oldest listens are the ones left out.
start_day string | null
First local day of the axis, YYYY-MM-DD. Absent when the range is
empty. Every daily array below starts here, one entry per day.
daily array required
Listens per local day, from start_day to today, including days with
none.
volume object required
plays integer · int64 required
active_days integer · int64 required
Days in the range with at least one listen.
median_active_day number · double required
Median listens on a day you listened at all. Zero-listen days are left
out on purpose: they would drag the median of a sparse history to 0.
peak object | null
The busiest day in the range.
plays integer · int64 required
waves array required
The most-credited artists in the range, with their own daily counts on
the same axis as daily.
each item object
plays integer · int64 required
Credited plays in the range.
daily array required
Credited plays per local day, aligned with StatsGraphs::daily.
long_tail object required
counts array required
Credited plays per artist, largest first. The curve is their running
sum over credits.
credits integer · int64 required
The sum of counts: artist credits, not listens — a listen with
two artists credited counts once for each.
once integer · int64 required
Artists heard exactly once in the range.
hundred_plus integer · int64 required
Artists heard 100 times or more in the range.
half integer · int64 required
How many of the top artists it takes to reach half of credits.
eighty integer · int64 required
How many of the top artists it takes to reach 80% of credits.
sessions object required
total integer · int64 required
Sessions in the range. A gap longer than gap_minutes starts a new one.
gap_minutes integer · int64 required
lengths array required
Sessions by how many listens they held, in fixed buckets.
each item object
label string required
1, 2, 3–4, 5–9, 10–19, 20–49, 50–99 or 100+.
sessions integer · int64 required
devotion object required
How much of each session went to its most-played artist.
Measured over sessions of at least min_listens, and over the primary
artist of each listen — fanning credits out here would let one session's
shares add up to more than everything played in it.
min_listens integer · int64 required
devoted integer · int64 required
One artist took 80% or more of the session.
mixed integer · int64 required
The top artist took 40–80%.
scattered integer · int64 required
No artist took as much as 40%.
first_listens array required
The range's most-credited artists, ordered by when you first heard
them — across the whole history, not the range.
each item object
plays integer · int64 required
Credited plays in the range.
first integer · int64 required
First listen ever, unix seconds — not ranged.
last integer · int64 required
Most recent listen, unix seconds — not ranged.
loyalty number · double required
0–100. High is steady, recurring listening; low is bursts.
habits array required
Daily habit or burst: how each artist's listening is spread over time.
Only artists with five or more plays on at least two different days.
each item object
plays integer · int64 required
Credited plays in the range.
active_days integer · int64 required
Days in the range this artist was played.
span_days integer · int64 required
Days from their first to their last listen in the range, inclusive.
return_rate number · double required
active_days / span_days: how often they come back. 1 = every day.
top_day_share number · double required
Share of their plays on their single biggest day. 1 = all on one day.
top_day string required
That biggest day, YYYY-MM-DD.
loyalty number · double required
0–100. High is steady, recurring listening; low is bursts.
albums array required
How each top artist's plays split across their records.
each item object
plays integer · int64 required
Credited plays in the range.
album_count integer · int64 required
Distinct records those plays were on.
albums array required
The most-played records, largest first, at most five.
each item object
album_artist string required
Who the record is filed under, which is what opens it.
plays integer · int64 required
rest_plays integer · int64 required
Plays on every other record.
no_album integer · int64 required
Plays whose source named no record at all.
anchors array required
Artists you mostly play one song from, most anchored first.
each item object
plays integer · int64 required
Credited plays in the range.
title string required
The one song most of them are.
title_plays integer · int64 required
share number · double required
tracks integer · int64 required
How many different songs of theirs were played at all.
401 No valid session cookie or token. Also returned when a token is
presented to a session-only endpoint — the endpoint does not accept
tokens at all, so the scope is irrelevant.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
{
"code": 401,
"error": "Authentication required. Log in to access this endpoint."
}
403 Authenticated, but not permitted. Either the token lacks the required
scope, or the endpoint needs the admin role. Deliberately not a 401 —
re-authenticating will not help.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
{
"code": 403,
"error": "This token does not have the 'write' scope"
}
The words to one track, as numbered lines.
Scope: read.
Numbered including blank lines. A stanza break is a line, because a
liner note refers to a line by its index — [[line:12]] or
[[line:A:3:12]] — and skipping empties would renumber every line after
one, silently re-pointing every quote already written.
Never triggers an LRCLIB fetch. That service is free and asks callers
to be considerate; the backfill is what paces it, and a screen that
fetched on open would let a page refresh drive the rate.
It does reach the user's own media server when nothing is stored yet.
Their Plex or Jellyfin has no rate limit and no shared budget to spend,
and they tag their own albums — so those words are usually right there
while the LRCLIB trickle is still hours from this track. Only when the
cache holds nothing: a stored lyric is never re-fetched on a page load.
Three answers, all real: lines, instrumental: true (a track with no
words, which is not a gap), and an empty list.
Lyrics are the provider's text. They are cached outside the listening
database, so GET /api/v1/backup does not carry them, and they are not
served by the public now-playing endpoint or by Patch.
Parameters
album query
Which record to draw the tracklist from.
Optional and resolved from the history when it is absent, because the
caller is usually a note or a history row that knows the track and not
the record it was filed under. Passed explicitly it wins, since a track
on three compilations has three honest answers and only the caller knows
which one is being read.
Responses
200 OK — including for a track nothing is held for.
application/json
object
Everything the lyric reader draws for one track: the words, and the
furniture round them.
one of option 1 object
The words, as numbered lines.
language string | null
As detected from the text.
timed boolean required
Whether any line carries a time, so the reader can follow the deck.
romanization object | null
Present when the lyric is in a script that is romanized; each line
then carries roman.
language string | null
The language it was romanized as.
indic string required
readable or iso, from the lyrics_indic_style preference.
cyrillic string required
readable or iso, from the lyrics_cyrillic_style preference.
macrons boolean required
Japanese long vowels with macrons, from the lyrics_macrons preference.
from_companion boolean required
Made from the original-script companion rather than the words shown.
kanji boolean required
Whether this build reads kanji and hanzi. Without it (a build with no
default features) kana is romanized and ideographs are left as written.
companion object | null
An LRCLIB record kept beside these words in their original script,
which romanization is made from while it lines up.
lrclib_id integer | null · int64
lines_up boolean required
Same line count as the words. When false it is held but not used.
lines array required
Numbered including blanks. A stanza break is a line, because a
note refers to a line by its index and skipping empties would
renumber every line after one.
each item object
n integer required
1-based, blanks included.
at number | null · double
Seconds into the track, when the lyric is timed.
text string required
Empty for a stanza break, which is a real line.
roman object | null
The line in Latin letters, as words and parts (one Hangul block, one
Japanese or Chinese token, one Indic word each). Absent where the line
needs none — English, a stanza break — or the lyric is not romanized.
text string required
The whole line as plain text.
words array required
each item object
A word: parts written together, words separated by a space.
parts array required
each item object
One unit drawn under its original in the interlinear view.
Deeper structure omitted. The spec is the full reference.
syl boolean
The parts are sung syllables (Korean), so the reader marks the
boundaries between them.
pin object | null
The liner note pinned to this line, if any.
note_id integer · int64 required
excerpt string required
The first 200 characters, as text.
visibility string required
updated_at integer · int64 required
quoted integer required
How many notes quote this line. Zero is sent, never omitted.
plain string | null
The stored text, for correcting it by hand.
synced string | null
The stored timed text, [mm:ss.xx] words per line.
edited boolean required
Corrected by hand, and therefore never overwritten by a lookup.
chosen boolean required
An LRCLIB record picked from Other versions — likewise never
overwritten by a lookup or a library poll, but still LRCLIB's words.
lrclib_id integer | null · int64
The LRCLIB record these words are, when they are one.
source string | null
Where the words came from — your library, LRCLIB, or you. Shown
wherever the words are, because they are not Tapedeck's.
option 2 object
A track with no words — an answer, not a gap.
instrumental boolean required
lines array required
each item object
n integer required
1-based, blanks included.
at number | null · double
Seconds into the track, when the lyric is timed.
text string required
Empty for a stanza break, which is a real line.
roman object | null
The line in Latin letters, as words and parts (one Hangul block, one
Japanese or Chinese token, one Indic word each). Absent where the line
needs none — English, a stanza break — or the lyric is not romanized.
text string required
The whole line as plain text.
words array required
each item object
A word: parts written together, words separated by a space.
parts array required
each item object
One unit drawn under its original in the interlinear view.
Deeper structure omitted. The spec is the full reference.
syl boolean
The parts are sung syllables (Korean), so the reader marks the
boundaries between them.
pin object | null
The liner note pinned to this line, if any.
note_id integer · int64 required
excerpt string required
The first 200 characters, as text.
visibility string required
updated_at integer · int64 required
quoted integer required
How many notes quote this line. Zero is sent, never omitted.
option 3 object
Nothing held for this track.
lines array required
each item object
n integer required
1-based, blanks included.
at number | null · double
Seconds into the track, when the lyric is timed.
text string required
Empty for a stanza break, which is a real line.
roman object | null
The line in Latin letters, as words and parts (one Hangul block, one
Japanese or Chinese token, one Indic word each). Absent where the line
needs none — English, a stanza break — or the lyric is not romanized.
text string required
The whole line as plain text.
words array required
each item object
A word: parts written together, words separated by a space.
parts array required
each item object
One unit drawn under its original in the interlinear view.
Deeper structure omitted. The spec is the full reference.
syl boolean
The parts are sung syllables (Korean), so the reader marks the
boundaries between them.
pin object | null
The liner note pinned to this line, if any.
note_id integer · int64 required
excerpt string required
The first 200 characters, as text.
visibility string required
updated_at integer · int64 required
quoted integer required
How many notes quote this line. Zero is sent, never omitted.
album string | null
The record the tracklist is drawn from — as asked for, or else the one
the track is filed under in your history.
plays integer · int64 required
Your plays of this track.
tracklist array required
The record's tracks, empty with no record.
each item object
plays integer · int64 required
duration integer | null · int64
track_number integer | null · int64
lyrics string | null
words or instrumental; null for a track nobody has asked about,
which is a different thing from one that has no words.
Correct the words by hand.
Scope: session only.
A value you supplied is never overwritten by a lookup — the rule the
shelf's running times already follow, and what settles the collision
between this and "newest fetch wins": between two fetches the newer one
wins, and between a fetch and something a person typed, the person does.
The row is marked as corrected and the backfill will not write over it.
Instance-wide rather than per user, like everything else in this cache:
these are one track's words, not one person's opinion of them.
The response reports the line count before and after, and
renumbered when they differ. Every reference already written is an
index, so a correction that adds or removes a line moves every quote
after it onto different words — silently, because an index cannot be
wrong, only pointed somewhere else. It is reported rather than refused:
the correction is usually the point, and the alternative is a lyric that
stays wrong for ever.
Request body required
application/json
object
plain string | null
The words, plain. Absent clears them.
synced string | null
The timed form, [mm:ss.xx] words per line.
Responses
application/json
object
A hand correction, stored.
lines_before integer required
lines_after integer required
renumbered boolean required
The line count changed, so every [[line:…]] quote past the change now
points at different words. Say so.
400 No artist, no title, or no words.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
POST /api/v1/lyrics/library # Token writeor Session
Words a player found in its own files.
Scope: write.
Not a correction. PUT /api/v1/lyrics calls set_words, which sets
edited and stamps the source as You — a claim only a person typing
gets to make, and the flag that outranks every later fetch. A client
reporting what a file contains is not correcting anything, so this goes
through the library path instead: it refuses to write over an edited row,
re-reads the language from the new words, and upserts, so a repeat send
is harmless.
Not POST /api/v1/lyrics/fetch either, which spends a shared
politeness budget at LRCLIB. This is offering words, not asking for them.
Sends nothing to any third party, and the words never leave the instance
— not in a backup, not in an export, not to a patched deck.
Request body required
application/json
object
Words a player found in its own files, offered by the player.
Deliberately not PUT /api/v1/lyrics, which is the correction path: that
one calls set_words, which sets edited and stamps the source as You.
Typing a line in is a claim only a person gets to make, and a client
reporting what a file contains is not correcting anything — so it must not
be able to mint the flag that outranks every later fetch.
Nor additional_info on a submission: a lyric is a few KB on every play of a
track already held, and ingest stays about the listening.
album string | null
Advisory. Not used to match — track_key is artist and title — and kept
out of the store for the same reason.
source string | null
Whose words these are, and required.
The reader prints "Words via X", and that sentence is the entire reason
this route exists apart from the LRCLIB one: from your own files and
from a lyrics service are different statements about whose text
somebody is reading. A client that will not say who it is should not get
to write provenance, and inventing one here would be the placeholder
User-Agent mistake in a new place.
Typed Option and required in the handler, not by serde. A missing
required field is rejected by axum's Json extractor with a 422 before
any of this runs — so the client is handed a deserialiser's sentence
about a field name instead of the reason, which is the trap
additional_info already documents. The requirement is unchanged; only
the answer is legible.
Responses
200 Stored, or left alone because the row holds a correction.
application/json
object
What became of words a player offered.
status string required
saved, or kept when the words held were corrected by hand or picked
from Other versions — either outranks a file's own tags, so those were
left alone.
why string | null
Why they were kept; null when saved.
language string | null
The language of the words now held.
lines integer required
Lines in the words now held.
400 A blank artist, title or source, or no words.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
401 No valid session cookie or token. Also returned when a token is
presented to a session-only endpoint — the endpoint does not accept
tokens at all, so the scope is irrelevant.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
{
"code": 401,
"error": "Authentication required. Log in to access this endpoint."
}
GET /api/v1/lyrics/live # Token reador Session
The words for whatever is on the deck.
Scope: read.
The reader's whole state in one request, so the lyric theatre stops
being addressed by URL. GET /api/v1/lyrics names a track, which is
right for a [[line:...]] chip and wrong for reading along: the words
stayed on whichever song the address named, so the next track left them
behind and the only way out was editing the query string.
The body is a LyricDoc with the playhead beside it, so a cold open
lands on the right line without waiting for a now-playing poll. Nothing
playing is { "playing": false } and a normal answer, not an error.
Ask it once per track, not once per poll. The document carries the
tracklist and every pin on the track; a client should watch
GET /api/v1/now-playing (which it is already polling) and re-ask this
only when the track changes.
Responses
200 The deck's track and its words, or nothing playing.
application/json
The words for whatever is on the deck, or that nothing is.
one of option 1 object
Nothing is playing — a state, not a failure.
option 2 object
The lyric document for what is playing, plus the playhead.
one of option 1 object
The words, as numbered lines.
language string | null
As detected from the text.
timed boolean required
Whether any line carries a time, so the reader can follow the deck.
romanization object | null
Present when the lyric is in a script that is romanized; each line
then carries roman.
language string | null
The language it was romanized as.
indic string required
readable or iso, from the lyrics_indic_style preference.
cyrillic string required
readable or iso, from the lyrics_cyrillic_style preference.
macrons boolean required
Japanese long vowels with macrons, from the lyrics_macrons preference.
from_companion boolean required
Made from the original-script companion rather than the words shown.
kanji boolean required
Whether this build reads kanji and hanzi. Without it (a build with no
default features) kana is romanized and ideographs are left as written.
companion object | null
An LRCLIB record kept beside these words in their original script,
which romanization is made from while it lines up.
lrclib_id integer | null · int64
lines_up boolean required
Same line count as the words. When false it is held but not used.
lines array required
Numbered including blanks. A stanza break is a line, because a
note refers to a line by its index and skipping empties would
renumber every line after one.
each item object
n integer required
1-based, blanks included.
at number | null · double
Seconds into the track, when the lyric is timed.
text string required
Empty for a stanza break, which is a real line.
roman object | null
The line in Latin letters, as words and parts (one Hangul block, one
Japanese or Chinese token, one Indic word each). Absent where the line
needs none — English, a stanza break — or the lyric is not romanized.
text string required
The whole line as plain text.
words array required
each item object
A word: parts written together, words separated by a space.
parts array required
Deeper structure omitted. The spec is the full reference.
syl boolean
The parts are sung syllables (Korean), so the reader marks the
boundaries between them.
Deeper structure omitted. The spec is the full reference.
pin object | null
The liner note pinned to this line, if any.
note_id integer · int64 required
excerpt string required
The first 200 characters, as text.
visibility string required
updated_at integer · int64 required
quoted integer required
How many notes quote this line. Zero is sent, never omitted.
plain string | null
The stored text, for correcting it by hand.
synced string | null
The stored timed text, [mm:ss.xx] words per line.
edited boolean required
Corrected by hand, and therefore never overwritten by a lookup.
chosen boolean required
An LRCLIB record picked from Other versions — likewise never
overwritten by a lookup or a library poll, but still LRCLIB's words.
lrclib_id integer | null · int64
The LRCLIB record these words are, when they are one.
source string | null
Where the words came from — your library, LRCLIB, or you. Shown
wherever the words are, because they are not Tapedeck's.
option 2 object
A track with no words — an answer, not a gap.
instrumental boolean required
lines array required
each item object
n integer required
1-based, blanks included.
at number | null · double
Seconds into the track, when the lyric is timed.
text string required
Empty for a stanza break, which is a real line.
roman object | null
The line in Latin letters, as words and parts (one Hangul block, one
Japanese or Chinese token, one Indic word each). Absent where the line
needs none — English, a stanza break — or the lyric is not romanized.
text string required
The whole line as plain text.
words array required
each item object
A word: parts written together, words separated by a space.
parts array required
Deeper structure omitted. The spec is the full reference.
syl boolean
The parts are sung syllables (Korean), so the reader marks the
boundaries between them.
Deeper structure omitted. The spec is the full reference.
pin object | null
The liner note pinned to this line, if any.
note_id integer · int64 required
excerpt string required
The first 200 characters, as text.
visibility string required
updated_at integer · int64 required
quoted integer required
How many notes quote this line. Zero is sent, never omitted.
option 3 object
Nothing held for this track.
lines array required
each item object
n integer required
1-based, blanks included.
at number | null · double
Seconds into the track, when the lyric is timed.
text string required
Empty for a stanza break, which is a real line.
roman object | null
The line in Latin letters, as words and parts (one Hangul block, one
Japanese or Chinese token, one Indic word each). Absent where the line
needs none — English, a stanza break — or the lyric is not romanized.
text string required
The whole line as plain text.
words array required
each item object
A word: parts written together, words separated by a space.
parts array required
Deeper structure omitted. The spec is the full reference.
syl boolean
The parts are sung syllables (Korean), so the reader marks the
boundaries between them.
Deeper structure omitted. The spec is the full reference.
pin object | null
The liner note pinned to this line, if any.
note_id integer · int64 required
excerpt string required
The first 200 characters, as text.
visibility string required
updated_at integer · int64 required
quoted integer required
How many notes quote this line. Zero is sent, never omitted.
album string | null
The record the tracklist is drawn from — as asked for, or else the one
the track is filed under in your history.
plays integer · int64 required
Your plays of this track.
tracklist array required
The record's tracks, empty with no record.
each item object
plays integer · int64 required
duration integer | null · int64
track_number integer | null · int64
lyrics string | null
words or instrumental; null for a track nobody has asked about,
which is a different thing from one that has no words.
position integer · int64 required
position_ms integer · int64 required
The same, in milliseconds.
position_known boolean required
Whether position is a measurement. Do not drive a highlight from a
guess.
duration integer | null · int64
POST /api/v1/lyrics/fetch # Session
Look for one track's words now.
Session only. A token is refused with 401 and its scopes never enter
into it: this spends a shared politeness budget at a free service and
writes an instance-wide cache, which is not something a scrobble client
holding read has any business doing.
The backfill runs at a few tracks a minute, most-played first, which is
the right pace for a queue nobody is watching and no use for the track
somebody is looking at. This is the button behind that, and it resolves
the track exactly as the backfill would: the user's own library first,
then LRCLIB, with cues winning.
A deliberate press is not a page load, which is why this may ask
LRCLIB where GET /api/v1/lyrics may not. It bypasses the 30-day miss
tombstone — LRCLIB fills its own gaps, so "nobody had this a fortnight
ago" is exactly the answer worth re-asking — but it will not displace
words already held: already_held: true says so, and
/api/v1/lyrics/matches is the control for disagreeing with them.
A rate limit or an unreachable LRCLIB is 200 with unavailable, not
a 5xx. Being asked to wait is not this server failing, and reporting it
as "nothing found" would be a claim about the track rather than about
the request.
Request body required
application/json
object
album string | null
Narrows the LRCLIB lookup when the caller knows it.
duration integer | null · int64
Likewise — LRCLIB matches on length, and a wrong-length record is the
usual reason a well-known song comes back with somebody else's words.
Responses
200 The whole document as it now stands, so the caller can replace what it is showing — or unavailable with a why.
application/json
A lookup's outcome: the whole lyric document, or why nobody could be asked.
one of option 1 object
LRCLIB could not be asked — rate limited or unreachable. Not "there
are no words": nothing was learned about the track.
unavailable boolean required
option 2 object
The document, as the reader should now show it.
one of option 1 object
The words, as numbered lines.
language string | null
As detected from the text.
timed boolean required
Whether any line carries a time, so the reader can follow the deck.
romanization object | null
Present when the lyric is in a script that is romanized; each line
then carries roman.
language string | null
The language it was romanized as.
indic string required
readable or iso, from the lyrics_indic_style preference.
cyrillic string required
readable or iso, from the lyrics_cyrillic_style preference.
macrons boolean required
Japanese long vowels with macrons, from the lyrics_macrons preference.
from_companion boolean required
Made from the original-script companion rather than the words shown.
kanji boolean required
Whether this build reads kanji and hanzi. Without it (a build with no
default features) kana is romanized and ideographs are left as written.
companion object | null
An LRCLIB record kept beside these words in their original script,
which romanization is made from while it lines up.
lrclib_id integer | null · int64
lines_up boolean required
Same line count as the words. When false it is held but not used.
lines array required
Numbered including blanks. A stanza break is a line, because a
note refers to a line by its index and skipping empties would
renumber every line after one.
each item object
n integer required
1-based, blanks included.
at number | null · double
Seconds into the track, when the lyric is timed.
text string required
Empty for a stanza break, which is a real line.
roman object | null
The line in Latin letters, as words and parts (one Hangul block, one
Japanese or Chinese token, one Indic word each). Absent where the line
needs none — English, a stanza break — or the lyric is not romanized.
text string required
The whole line as plain text.
words array required
each item object
A word: parts written together, words separated by a space.
parts array required
Deeper structure omitted. The spec is the full reference.
syl boolean
The parts are sung syllables (Korean), so the reader marks the
boundaries between them.
Deeper structure omitted. The spec is the full reference.
pin object | null
The liner note pinned to this line, if any.
note_id integer · int64 required
excerpt string required
The first 200 characters, as text.
visibility string required
updated_at integer · int64 required
quoted integer required
How many notes quote this line. Zero is sent, never omitted.
plain string | null
The stored text, for correcting it by hand.
synced string | null
The stored timed text, [mm:ss.xx] words per line.
edited boolean required
Corrected by hand, and therefore never overwritten by a lookup.
chosen boolean required
An LRCLIB record picked from Other versions — likewise never
overwritten by a lookup or a library poll, but still LRCLIB's words.
lrclib_id integer | null · int64
The LRCLIB record these words are, when they are one.
source string | null
Where the words came from — your library, LRCLIB, or you. Shown
wherever the words are, because they are not Tapedeck's.
option 2 object
A track with no words — an answer, not a gap.
instrumental boolean required
lines array required
each item object
n integer required
1-based, blanks included.
at number | null · double
Seconds into the track, when the lyric is timed.
text string required
Empty for a stanza break, which is a real line.
roman object | null
The line in Latin letters, as words and parts (one Hangul block, one
Japanese or Chinese token, one Indic word each). Absent where the line
needs none — English, a stanza break — or the lyric is not romanized.
text string required
The whole line as plain text.
words array required
each item object
A word: parts written together, words separated by a space.
parts array required
Deeper structure omitted. The spec is the full reference.
syl boolean
The parts are sung syllables (Korean), so the reader marks the
boundaries between them.
Deeper structure omitted. The spec is the full reference.
pin object | null
The liner note pinned to this line, if any.
note_id integer · int64 required
excerpt string required
The first 200 characters, as text.
visibility string required
updated_at integer · int64 required
quoted integer required
How many notes quote this line. Zero is sent, never omitted.
option 3 object
Nothing held for this track.
lines array required
each item object
n integer required
1-based, blanks included.
at number | null · double
Seconds into the track, when the lyric is timed.
text string required
Empty for a stanza break, which is a real line.
roman object | null
The line in Latin letters, as words and parts (one Hangul block, one
Japanese or Chinese token, one Indic word each). Absent where the line
needs none — English, a stanza break — or the lyric is not romanized.
text string required
The whole line as plain text.
words array required
each item object
A word: parts written together, words separated by a space.
parts array required
Deeper structure omitted. The spec is the full reference.
syl boolean
The parts are sung syllables (Korean), so the reader marks the
boundaries between them.
Deeper structure omitted. The spec is the full reference.
pin object | null
The liner note pinned to this line, if any.
note_id integer · int64 required
excerpt string required
The first 200 characters, as text.
visibility string required
updated_at integer · int64 required
quoted integer required
How many notes quote this line. Zero is sent, never omitted.
album string | null
The record the tracklist is drawn from — as asked for, or else the one
the track is filed under in your history.
plays integer · int64 required
Your plays of this track.
tracklist array required
The record's tracks, empty with no record.
each item object
plays integer · int64 required
duration integer | null · int64
track_number integer | null · int64
lyrics string | null
words or instrumental; null for a track nobody has asked about,
which is a different thing from one that has no words.
already_held boolean required
The words were already held, so nothing was fetched.
400 An artist or a title that is blank.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
422 The body is missing artist or title outright.
GET /api/v1/lyrics/matches # Token reador Session
The other records LRCLIB holds for a track.
Session or a read token.
Not a version history. LRCLIB has none — /api/get returns one
record and nothing behind it. These are different records for the same
song, from /api/search: other uploads, other pressings, a live take
filed under the same name. Picking a better one is how a wrong match is
fixed without typing the words out.
Records with no words are omitted. The whole gesture is "these are the
wrong words, give me the other ones", which an instrumental cannot
answer.
Adopt one with POST /api/v1/lyrics/adopt, by its id. The pick
survives every later fetch and library poll, is credited to LRCLIB, and
the response reports renumbered — which matters here more than
anywhere: a [[line:...]] reference is an index, so a different record
re-points every quote already written.
search_artist and search_title search under other names than the
track's own, for tags LRCLIB files differently. held marks the record
already stored for the track.
This reaches the network, so it belongs on a press rather than a page
load. A rate limit or an unreachable LRCLIB comes back 200 with
unavailable: true and a reason rather than a 5xx: the upstream asking
us to wait is not this server failing, and the distinction is what stops
a client reporting "no other matches" when it never managed to ask.
Parameters
artist query required
The track, as it is filed here.
search_artist query
Search LRCLIB under a different artist than the track's — for tags that
name it differently (a romanised name, a "feat." credit).
Responses
application/json
object
The records LRCLIB holds for a track.
matches array required
each item object
One LRCLIB record for the track.
id integer | null · int64
LRCLIB's id — what POST /api/v1/lyrics/adopt takes.
album string | null
The release the record was filed under — usually what tells two
uploads of one song apart.
duration integer | null · int64
synced boolean required
Timed — a timed lyric follows the deck, a plain one cannot.
language string | null
The language read off the record's script, null for Latin text. The
question this list most often answers is "is there one in the original
script", which a romanised upload and a native one look identical on
every other field.
held boolean required
This is the record already held.
synced_text string | null
unavailable boolean | null
Present, and true, when LRCLIB could not be asked. matches is then
empty and says nothing about the track.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
POST /api/v1/lyrics/adopt # Session
Hold an LRCLIB record picked from *Other versions*.
Session only. It reaches LRCLIB and writes the instance-wide cache,
which a token is not for.
The server fetches the record by id itself. The words are credited to
LRCLIB, and the pick is kept: no later fetch and no library poll
replaces it. It replaces a hand correction, since choosing is as
deliberate as typing and the later act wins; Fix the words afterwards
is a correction again.
Reports the line count before and after, and renumbered when they
differ: a [[line:…]] reference is an index, so a record with a
different count re-points every quote past the change.
A rate limit or an unreachable LRCLIB is 200 with unavailable —
nothing was changed and nothing was learned about the record.
Request body required
application/json
object
An LRCLIB record to hold for a track.
artist string required
The track, as it is filed here — not necessarily the record's own names.
id integer · int64 required
The LRCLIB record, from GET /api/v1/lyrics/matches.
original_script boolean
Keep the record beside the words held, as their original script,
rather than replacing them. For words held in Latin letters (a lyric
tagged romanised in your own files): they stay what a note quotes, and
romanization is made from this record. Refused unless it lines up.
Responses
200 Held — or unavailable with a why.
application/json
A picked record, held — or why LRCLIB could not be asked.
one of option 1 object
LRCLIB could not be asked. Nothing was changed.
unavailable boolean required
option 2 object
Kept beside the words as their original script (original_script).
option 3 object
lines_before integer required
lines_after integer required
renumbered boolean required
The line count changed, so every [[line:…]] quote past the change
now points at different words. Say so.
400 A blank artist or title, a record with no words — or, keeping it as the original script, one that does not line up with the words held.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
404 LRCLIB has no record with that id.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
422 The body is missing a field outright.
GET /api/v1/lyrics/keys # Token reador Session
Every track this instance holds words for.
Scope: read.
One request for the whole set, exactly the shape GET /api/v1/loves/keys
has and for the same reason: a history page wants to know which of fifty
rows has something to read, and fifty questions is not the way to ask.
A key is <artist>|<title>, both trimmed and lowercased — the same fold
loveKey uses for its artist half. The browser's derivation and this
one must stay in step, or "Read the words" quietly stops appearing on
rows that have lyrics and nothing errors.
Only tracks with words. An instrumental is a real answer and a finished
lookup, but there is nothing to open a reader on.
Not scoped to the caller, and it cannot be: the cache is one copy of one
track's words for the whole instance, keyed by the track rather than by
who played it.
Responses
200 OK. An instance with no lyrics cache answers an empty list rather than failing.
application/json
object
Every track this instance holds words for.
keys array required
<artist key>|<title> for each: the artist folded the way artist
pages fold names (case, accents, spacing), the title trimmed and
lowercased. Derive a row's key the same way.
Period reports — a feed of week / month / year cards, newest first.
Scope: read (since v0.41).
Reads the history once and folds it in Rust. A card carries a dozen
aggregates and every one is bucketed in the caller's own timezone, which
SQL here cannot do — a year of monthly cards would otherwise be hundreds
of round trips.
Weeks are ISO (Monday-start), deliberately not the caller's
week-start preference: that setting shapes the dashboard counter and the
heatmap rows, whereas a report is a named object and its boundary has to
stay put, or last month's report changes shape when the preference does.
avg_daily divides by calendar days — a finished period by its full
length, one still running by the days it has actually had. Dividing by
days-with-listens would report the rate of your busiest fortnight as the
month's average.
Two things deliberately absent. There is no percentile against other
users ("you out-listened 88% of listeners"): that needs other people's
listening, and on a private instance it would leak how much the rest of
the household plays. And crush is omitted for the oldest period, where
every artist is new by construction and it would just be the top artist
relabelled.
Parameters
unit query
week, month (default) or year.
limit query
How many periods to return, newest first. 12 by default, at most 60.
offset query
Periods to skip, counting back from the newest. The stepper on the
Reports page walks this one period at a time. Costs nothing extra — the
whole history is folded on every call regardless.
Responses
application/json
object
A feed of period cards, newest first.
timezone string required
The IANA zone the buckets were cut in.
periods array required
each item object
start integer · int64 required
Unix seconds — the first listen in the period.
end integer · int64 required
Unix seconds — the last listen in the period.
plays integer · int64 required
hours number · double required
avg_daily integer · int64 required
Plays per calendar day — a finished period by its full length, one
still running by the days it has actually had.
new_artists integer required
Artists with no earlier listen anywhere in the history.
top_artist object | null
Never "Various Artists", which is a filing convention, not an artist.
name string required
The latest spelling actually submitted.
plays integer · int64 required
hours number · double required
landscape_url string | null
A wide image, when you chose one for this artist. Absent otherwise —
nothing Tapedeck can reach supplies one.
top_album object | null
plays integer · int64 required
top_track object | null
artist_credit string | null
Everyone credited, "; "-joined and primary first, when there is more
than one.
plays integer · int64 required
sub array required
One level finer than the period — days across a week, weeks across a
month, months across a year.
sub_labels array required
genres array required
The six biggest genres. Shares of tag mentions, not of listens.
each item object
pct integer · int64 required
A whole percentage of tag mentions.
genre_bands object required
The period's three biggest genres by name, fixed across every
sub-bucket, plus other as the remainder. Drawn as stacked bands by the
year chapter. A sub-bucket with no tags at all is all zeroes rather than
100% other — an empty month is an absence, not a genre.
Shares of tag mentions, like genres.
shares array required
One row per sub-bucket; each row is the named shares then other.
rank integer required
Where this period sits among your own periods by plays, 1 being the
busiest. This is what fills the slot the design gave to a cross-user
percentile — there is no such thing here: it needs other people's
listening, and on a private instance it would leak how much the rest of
the household plays.
rank_of integer required
How many periods rank is out of.
colour string | null
Play-weighted blend of the period's genre colours, in linear light.
Null until the genre map is fetched.
on_repeat array required
The heaviest single days of single tracks — three plays or more.
each item object
artist_credit string | null
Everyone credited, "; "-joined and primary first, when there is more
than one.
plays integer · int64 required
crush object | null
Most-played artist never played before, with at least five plays.
Null for the oldest period, where every artist is new by construction
and it would just be the top artist relabelled.
name string required
The first spelling it arrived under.
plays integer · int64 required
since integer · int64 required
Unix seconds of the first listen.
shelf object required
Sides played off the shelf.
sides integer · int64 required
rows array required
The five most-played sides.
each item object
spins integer · int64 required
top_chain string | null
The chain most listens went through.
gear object required
What the period was listened through. unattributed and no_duration
are stated rather than folded away: on most histories the first is nearly
everything, and the hours are a floor without the second.
chains array required
each item object
plays integer · int64 required
hours number · double required
items array required
The eight pieces of gear with the most hours, each counted once per
chain even when a chain names it twice.
each item object
type string required
The component type, lowercased — dac, amp, transducer…
plays integer · int64 required
hours number · double required
unattributed integer · int64 required
Listens with no chain at all.
no_duration integer · int64 required
Chained listens whose source reported no length.
company object required
Listens marked as heard with somebody. company is null on
everything nobody has tagged, so of_plays travels as the denominator —
never present a bare share, and never read the complement as "alone".
marked_plays integer · int64 required
marked_hours number · double required
of_plays integer · int64 required
people array required
The eight people heard with most.
each item object
plays integer · int64 required
fingerprint object required
Five ratios between 0 and 1, and the same five for you, usually — every
one answerable from any history, and none of them a comparison against
another person. The baseline is the mean of your own periods, not one
shape over the whole history: variety shrinks as plays grow and
discovery is pinned at 1.0 over a whole history, so a whole-history
baseline would report every period as more varied and less exploratory
than usual.
axes array required
Variety, Repeat, Discovery, Spread, Runs.
usual_periods integer required
How many periods the baseline rests on. One is not a habit — a radar
comparing a month against itself draws two identical shapes and means
nothing by it, so decline to draw the baseline below two.
milestones array required
Sentences worth a line of their own — "your 10,000th listen".
prev object | null
The period before, for deltas. Null for the oldest.
plays integer · int64 required
hours number · double required
avg_daily integer · int64 required
offset integer required
Where this page sits, counting back from the newest.
total_periods integer required
How many periods exist at this bucket size — what tells a stepper where
the ends are.
capped boolean | null
The scan hit the analytics row cap, so the oldest periods are partial
and must not be presented as final. Absent with no listening at all.
401 No valid session cookie or token. Also returned when a token is
presented to a session-only endpoint — the endpoint does not accept
tokens at all, so the scope is irrelevant.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
{
"code": 401,
"error": "Authentication required. Log in to access this endpoint."
}
403 Authenticated, but not permitted. Either the token lacks the required
scope, or the endpoint needs the admin role. Deliberately not a 401 —
re-authenticating will not help.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
{
"code": 403,
"error": "This token does not have the 'write' scope"
}
GET /api/v1/reports/image # Session or Token read
A report chapter as a shareable PNG, rendered on the server.
Scope: read (since v0.96).
Rendered on the server on purpose. A share image is a deliverable
rather than a view: a native client asks for one instead of
reimplementing a layout, a type scale and a palette that would then be
free to drift from the web's. The fonts are embedded in the binary and
no artwork is fetched, so the same period produces the same bytes on any
host.
It computes nothing. Every figure comes from GET /api/v1/reports
with the same unit and offset, so a share cannot disagree with the
chapter it was shared from — including the rule that the only
comparison on the card is against the caller's own periods.
The card is a composition, not a screenshot of the chapter, and
each unit has its own — never one card relabelled, the same reason the
app has three chapter components:
- week — a headline, the by-day bars, the top artist and the
track of the week, the counts, the crush. Deliberately no genre
split: seven days make a thin one, which is the chapter's own
judgement.
- month — the top artist and record, the counts, the top genres,
what was on repeat, the crush. No by-week bars: five columns say less
than the ranked genre list beneath them.
- year — the by-month bars and the genre bands (the three
biggest genres tracked by name across the year, everything else folded
into
other), the artist and record of the year, what was discovered,
the crush.
A section that would not fit is left out whole rather than clipped —
a PNG has no scrollbar, so a section drawn over the footer would look
deliberate. A thin period therefore draws fewer sections rather than
empty headings, and a full year gives up its discovery line before it
gives up the crush.
Parameters
unit query
week, month (default) or year. Each has its own composition —
there is no card that is another card at a different size.
offset query
How many periods back from the newest, matching the Reports stepper.
size query
story (default), square or wide.
theme query
dark (default) or light. Asked at export time, not inherited — a
share lands on somebody else's feed rather than inside the app, so the
reader's own theme preference is not the question being answered.
format query
png (default) or svg. The SVG is the same document the PNG is
rasterised from: smaller, sharp at any size, and something a native
client can draw itself. It is not a second renderer — if the two ever
disagreed it would be because one of them was not this one.
Responses
200 The image. Cache-Control is private: it is one person's listening, and a shared cache must not hold it.
image/png
image/svg+xml
400 An unsupported unit, size or format.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
404 No report for that period — an offset past the end of the history, or an instance with nothing in it yet. A real answer, not a failure.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
GET /api/v1/reports/mixdown # Session or Token read
A report period as a short animated mixdown.
Scope: read (since v0.131).
The same facts as the chapter and its share image, told one at a time:
a few scenes, each a stack of SVG layers that fade, rise and count into
place. The server draws every layer — text is already fitted, escaped and
set in the embedded fonts' metrics — and a client only moves them.
To play it: draw background, then for the current scene draw each
layer's svg inside a group whose transform and opacity come from its
tracks at the scene's elapsed milliseconds.
- A track is a list of
{t, v} keys. Before the first key the value is
the first key's, after the last the last key's, and between two keys it
eases out: a + (b - a) * (1 - (1 - p)^3). An absent track is at rest
(opacity 1, offsets 0, scales 1).
- The group's transform is
translate(dx + ox, dy + oy) scale(scale * scale_x, scale * scale_y) translate(-ox, -oy)
where (ox, oy) is the layer's origin.
- A layer with
count carries the literal {{n}} in its svg; replace
it with the eased value between start_ms and end_ms, rounded and
written with thousands separators.
- In its last
fade_out_ms a scene's layers fade out together. The last
scene has none and is held.
Pictures. A layer may contain an <image> whose href is the top
artist's portrait, the record's cover or the track's: either a web URL
or a path on this server (fetch it with the same credentials). Each sits
over a lettered tile, so a picture that is absent or fails to load needs
no handling — draw the layer as it is.
It computes nothing: every figure comes from GET /api/v1/reports
with the same unit and offset. A scene the period has nothing to say
in is absent rather than empty, so a thin period is a shorter mixdown.
Parameters
unit query
week, month (default) or year.
offset query
How many periods back from the newest, matching the Reports stepper.
theme query
dark (default) or light. Asked for, not inherited, for the same
reason the share image asks: the result lands on somebody else's feed.
Responses
application/json
object
A mixdown, and whether this server can turn it into a video.
width integer · int32 required
height integer · int32 required
fps integer · int32 required
The video's frame rate. A player may draw more often than this.
label string required
The period's own name: "2026", "August 2026", "Week of 17 August".
background string required
SVG drawn under every scene and never animated.
scenes array required
each item object
A few seconds about one fact.
id string required
What the scene is about: intro, volume, shape, artist,
record, discovery or outro. A period with nothing to say about
one of these has no such scene.
duration_ms integer · int32 required
fade_out_ms integer · int32 required
How long the scene takes to fade into the next one, at its end. Zero
for the last scene, which is held.
layers array required
each item object
One thing on screen: a piece of SVG and how it moves.
svg string required
SVG elements in mixdown coordinates (no <svg> root). Text is already
fitted and escaped; draw it as it is.
origin array required
The point scales are taken about, in mixdown pixels.
tracks object required
How one layer moves. Every track is optional; an empty one means the
property stays at rest (opacity 1, no offset, scale 1).
Before a track's first key the value is the first key's, after its last
the last key's, and between two keys it eases out (cubic) from one to the
other.
opacity array
each item object
One point on a track: at t milliseconds into the scene the value is v.
t integer · int32 required
Deeper structure omitted. The spec is the full reference.
v number · float required
Deeper structure omitted. The spec is the full reference.
dx array
Horizontal offset in mixdown pixels.
each item object
One point on a track: at t milliseconds into the scene the value is v.
t integer · int32 required
Deeper structure omitted. The spec is the full reference.
v number · float required
Deeper structure omitted. The spec is the full reference.
dy array
Vertical offset in mixdown pixels; positive is down.
each item object
One point on a track: at t milliseconds into the scene the value is v.
t integer · int32 required
Deeper structure omitted. The spec is the full reference.
v number · float required
Deeper structure omitted. The spec is the full reference.
scale array
Uniform scale about the layer's origin.
each item object
One point on a track: at t milliseconds into the scene the value is v.
t integer · int32 required
Deeper structure omitted. The spec is the full reference.
v number · float required
Deeper structure omitted. The spec is the full reference.
scale_x array
Horizontal scale about the origin, multiplied with scale.
each item object
One point on a track: at t milliseconds into the scene the value is v.
t integer · int32 required
Deeper structure omitted. The spec is the full reference.
v number · float required
Deeper structure omitted. The spec is the full reference.
scale_y array
Vertical scale about the origin, multiplied with scale.
each item object
One point on a track: at t milliseconds into the scene the value is v.
t integer · int32 required
Deeper structure omitted. The spec is the full reference.
v number · float required
Deeper structure omitted. The spec is the full reference.
count object | null
Present when svg carries the {{n}} token.
from integer · int64 required
to integer · int64 required
start_ms integer · int32 required
end_ms integer · int32 required
fully_covered boolean required
False when a string that is drawn contains a character the embedded
fonts cannot draw. The video may then show boxes for it; a browser,
which has its own fonts, usually will not.
video_export boolean required
True when the server has an encoder and POST /api/v1/reports/mixdown/video will work. False is not an error: the
mixdown still plays, there is just nothing to download.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
404 No report for that period — an offset past the end of the himixdown, or an instance with nothing in it yet.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
POST /api/v1/reports/mixdown/video # Session or Token read
Start making a video of a mixdown.
Scope: read (since v0.131). A POST that needs only read: nothing
of yours is written, the result is a temporary file.
Returns at once with a job to poll at
GET /api/v1/reports/mixdown/video/{id}. The video is 1080×1920 H.264 at
30 frames a second with no sound, drawn from the same mixdown the GET
returns, and is kept for an hour.
Pictures are fetched by the server before the first frame, each with a
deadline. One that does not arrive, or is not a PNG, JPEG, GIF or WebP, is left
out and its lettered tile shows instead; the export does not fail.
One video is made at a time on the whole server, so queued means
somebody else's is being drawn. Each user may have one export in flight.
Parameters
unit query
week, month (default) or year.
offset query
How many periods back from the newest, matching the Reports stepper.
theme query
dark (default) or light. Asked for, not inherited, for the same
reason the share image asks: the result lands on somebody else's feed.
Responses
application/json
object
Where a video export has got to.
state string required
queued (another render is running), rendering, done or failed.
frames_done integer · int32 required
frames_total integer · int32 required
bytes integer · int64 required
The file's size once state is done, otherwise 0.
error string | null
Why it failed, when it did.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
404 No report for that period.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
409 You already have a video being made.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
501 This server has no video encoder (ffmpeg with libx264). The mixdown still plays.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
POST /api/v1/insights/lenses/{id}/mixdown/video # Token reador Session
Make a video of a season's Mixdown.
Scope: read (since v0.132). The same job as
POST /api/v1/reports/mixdown/video; poll and download it there.
Parameters
id path required
christmas, halloween or easter.
size query
story (default), square or wide. The image only.
Responses
application/json
object
Where a video export has got to.
state string required
queued (another render is running), rendering, done or failed.
frames_done integer · int32 required
frames_total integer · int32 required
bytes integer · int64 required
The file's size once state is done, otherwise 0.
error string | null
Why it failed, when it did.
401 No valid session cookie or token. Also returned when a token is
presented to a session-only endpoint — the endpoint does not accept
tokens at all, so the scope is irrelevant.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
{
"code": 401,
"error": "Authentication required. Log in to access this endpoint."
}
404 No such resource, or it belongs to another user.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
409 You already have a video being made.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
501 This server has no video encoder.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
POST /api/v1/insights/lenses/{id}/playlist # Token writeor Session
Save a season's most-played songs as a playlist.
Scope: write (since v0.132). Your own history only — up to fifty songs
you played that season, most played first. Saving the same season again
returns the playlist already made. Push it to a media server from
Playlists like any other.
Parameters
id path required
christmas, halloween or easter.
size query
story (default), square or wide. The image only.
Responses
application/json
object
id integer · int64 required
created boolean required
False when this season's playlist already existed and was returned.
401 No valid session cookie or token. Also returned when a token is
presented to a session-only endpoint — the endpoint does not accept
tokens at all, so the scope is irrelevant.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
{
"code": 401,
"error": "Authentication required. Log in to access this endpoint."
}
404 No such resource, or it belongs to another user.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
GET /api/v1/insights/anniversaries # Token reador Session
Anniversaries among what you listen to.
Scope: read (since v0.132). Births and deaths of artists and composers,
bands forming and splitting, and albums' releases — round numbers only (10,
20, 25, 30 … 100, 75, every 50), from MusicBrainz's dates. Only artists
and albums in your own history.
Parameters
year query
The year to mark; this year, in your timezone, when absent.
Responses
application/json
object
year integer · int32 required
items array required
Round anniversaries this year of artists, composers and albums in your
history, most played first.
each item object
kind string required
born, died, formed, split or released.
name string required
The artist, or the album.
artist string | null
For an album: who it is filed under.
date string required
YYYY[-MM[-DD]], as MusicBrainz has it.
years integer · int32 required
living boolean required
For a person: alive, as far as MusicBrainz knows.
today boolean required
Falls on today's date (month and day), not only in this year.
plays integer · int64 required
Your plays of them, all time.
today array required
Birthdays and deathdays falling on today's date.
each item object
kind string required
born, died, formed, split or released.
name string required
The artist, or the album.
artist string | null
For an album: who it is filed under.
date string required
YYYY[-MM[-DD]], as MusicBrainz has it.
years integer · int32 required
living boolean required
For a person: alive, as far as MusicBrainz knows.
today boolean required
Falls on today's date (month and day), not only in this year.
plays integer · int64 required
Your plays of them, all time.
revisit array required
Albums with a round anniversary this year that you have not played
for half a year — for Rediscovery.
each item object
kind string required
born, died, formed, split or released.
name string required
The artist, or the album.
artist string | null
For an album: who it is filed under.
date string required
YYYY[-MM[-DD]], as MusicBrainz has it.
years integer · int32 required
living boolean required
For a person: alive, as far as MusicBrainz knows.
today boolean required
Falls on today's date (month and day), not only in this year.
plays integer · int64 required
Your plays of them, all time.
401 No valid session cookie or token. Also returned when a token is
presented to a session-only endpoint — the endpoint does not accept
tokens at all, so the scope is irrelevant.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
{
"code": 401,
"error": "Authentication required. Log in to access this endpoint."
}
POST /api/v1/insights/overrides # Token writeor Session
Correct what kind of listen something is.
Scope: write (since v0.132). Yours only: overrides never change what
another member of this instance sees. Applied at once, from what Tapedeck
already knows — nothing is looked up.
Request body required
application/json
object
target_kind string required
work — a piece or song, every version of it (key: a row's key
from a lens or Classical, which starts w: or t:); album (key: a
Scores suggestion's key); or artist (key: the artist's name) —
everything they are credited on. Broadest first, most specific wins:
artist, then album, then piece.
target_key string required
facet string required
classical, score, ambient, christmas, halloween, easter
or score_suggested.
value boolean | null
true sets it, false clears it, null removes your override and
returns to what Tapedeck decided. Required: an absent value is a
400, so a client that forgot it cannot quietly undo a correction.
Responses
application/json
object
listens integer · int64 required
Listens the change touched, already re-applied.
400 Malformed or rejected input.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
401 No valid session cookie or token. Also returned when a token is
presented to a session-only endpoint — the endpoint does not accept
tokens at all, so the scope is irrelevant.
application/json
object
Every error body in the API has this shape.
code integer · int32 required
error string required
Human-readable. Not a stable identifier — do not branch on it.
{
"code": 401,
"error": "Authentication required. Log in to access this endpoint."
}