Loves

Session-only. Reading is a fact about your library and pulling spends a source's credential, so a token gets 401 here and scopes never enter into it — the same line /api/v1/sources sits on.

Every rating carries the raw number the server gave and what that number was out of, because a bare 7 means nothing: Plex counts to ten (half stars, so a 7 is three and a half), Subsonic to five, and Jellyfin/Emby's legacy Rating to ten. shown is the same rating on the display scale you chose, and is presentation only — every threshold comparison is made on the underlying fraction, so a rating that reads as four stars on a coarse scale does not thereby clear a four-star bar.

threshold comes back in the units of scale, which is what you typed.

Session-only. Does not un-love anything — a love already made is a statement that was made. To take those back, raise the threshold and apply, which is a separate and visible act.

Session-only — it spends the credential of a configured source.

Walks every enabled library source and replaces what that source said last time, so a rating raised, lowered or cleared on the server is raised, lowered or cleared here: the server is the authority on its own ratings and this is a copy of them. One source failing does not stop the others, and an error is reported separately from a count of zero — a server that could not be reached is not a library with no ratings in it.

Roon is reported as having nothing rather than returning an empty list. Its extension API publishes no rating, favourite or thumb field at all, so a source that silently returned nothing would look broken.

Ratings are stored; nothing becomes a love until /api/v1/ratings/apply.

Session-only.

dry_run is required and has no default: the two things this can do are "tell me what would happen" and "write to my Loved page", and a body that merely misspelled the key must not be read as an answer either way. A preview and a real run go through the same code, so a preview cannot describe something the apply then does differently — and a preview writes nothing at all, including no entities.

Two rules hold it safe. A rating on something you have never listened to is kept and not loved — loves point at entities and entities are things you actually played — and the count comes back as unmatched so it is visible rather than silently absent. And only loves this instance derived are ever withdrawn: one pressed by hand, or pulled from Last.fm or ListenBrainz, is outside the reach of a threshold however far it moves.

Nothing here is forwarded to Last.fm or ListenBrainz. These are loves being imported, not loves being pressed, and a threshold you are expected to try at several settings would otherwise be a broadcast at every setting.

Session-only — it uses stored service credentials. Not one code path: ListenBrainz returns only a recording MBID so an un-enriched track cannot be matched, while Last.fm returns names and can fall back to a name match. A love whose track is not in your history is skipped, never invented — loves point at entities, and entities are things you actually played. Libre.fm has no loved-tracks call and is not asked.

Scope: read (since v0.39).

Since v0.43 each row carries what the Loved page needs to render it — plays, last played, artwork and the liner note — rather than the bare entity. Four queries regardless of how many loves there are.

Scope: write (since v0.39).

Loves attach to entities, never to a listen — loving one playing of a track is a category error and is rejected.

A love of a recording is mirrored outward (Last.fm track.love, ListenBrainz recording-feedback); albums and artists stay local because neither service has the concept. ListenBrainz needs a recording MBID, so an un-enriched track is skipped rather than guessed at. The forward is spawned, not awaited — the love is already stored and the UI should not wait on Last.fm.

Scope: read (since v0.39). One request instead of one per history row.

Since v0.69 a love is published in up to three forms, and a row is loved if any key it can derive is in the set. Two players rarely spell one song identically — Plex files a listen under the record's artist while a scrobble client reports what the player displayed — so an exact match alone left the heart empty on the same track from another source.

• kind|artist|name — trimmed and lowercased, an artist's artist half empty. The exact key, as before.
• kind|artist|name folded — accents, ligatures and all punctuation removed, and the primary taken from an explicit feat. credit. Note a trailing title qualifier is not removed: "Archangel" and "Archangel (Remastered)" stay apart.
• mbid:<kind>:<mbid> — present when the entity has a MusicBrainz id. The strongest of the three; a listen row carries a recording id.

If your derivation drifts from the server's, hearts silently stop filling — nothing errors. The folded form is pinned character for character by the_folded_key_is_exactly_what_the_client_must_reproduce.