feat(autotag): answer whether an album has a confident match

`MatchForAlbum(albumID)` is the question the album detail page needs to
ask on open: does the autotagger already have something confident to
say about this album, and what would applying it do.

**It costs no MusicBrainz request.** Everything it needs is on disk —
`tagging_items` carries the top score and release from the background
prefetch, `tagging_candidates` durably holds the scored list. The rate
limiters here are shared with every page the user can open, so a lookup
that fires on page load must not join that queue; a folder nobody has
scored yet answers "nothing", rather than scoring it now.

**The tier is computed, not read.** `tagging_items.score` is the raw
number and `Recommend` is what turns it into a claim, capping it for an
ambiguous runner-up, an incomplete alignment or a folder too small to
corroborate itself. Filtering on the stored score would promise
confidence the scorer had explicitly withheld — which the two-track
test pins.

**Nothing is said about an album the user has already answered for.**
Only a `pending` group qualifies: `confirmed` covers both a finished
apply and an explicit "leave as is", and arguing with the second would
be actively wrong.

The join is `audio_files.group_key`, not a key derived from the folder
path, because a group carved out of a mixed-bag folder is keyed on its
tags — so a path-derived key would find nothing for exactly the
messiest libraries this helps. `GroupCount` is returned because a
multi-disc album is one group per disc: a caller that applied to "the
album" from a single button would retag one disc of three.
This commit is contained in:
2026-08-19 02:34:11 -04:00
parent fe67849e57
commit 9118c16fe3
7 changed files with 662 additions and 0 deletions
@@ -7,6 +7,7 @@ export {
};
export type {
AlbumMatchView,
AlignmentView,
ApplyResultView,
CandidateView,
@@ -1,6 +1,61 @@
// Cynhyrchwyd y ffeil hon yn awtomatig. PEIDIWCH Â MODIWL
// This file is automatically generated. DO NOT EDIT
/**
* AlbumMatchView is "the autotagger already has a confident match for
* the album you are looking at".
*
* It is deliberately not a score. The album page renders a suggestion,
* and a suggestion has to be actionable: which release, what it is
* called, and whether acting on it here would do the whole album or
* only part of it.
*/
export interface AlbumMatchView {
/**
* GroupKey is the tagging group the actions operate on.
*/
"groupKey": string;
/**
* Recommendation is the tier, as a string, for a caller that
* wants to render the strength rather than trust the filter.
*/
"recommendation": string;
/**
* Score is the top candidate's raw score, 0..1.
*/
"score": number;
/**
* ReleaseMBID is the release Apply would write.
*/
"releaseMbid": string;
/**
* Title and ArtistCredit name that release, so the banner can say
* what it is offering rather than "a match".
*/
"title": string;
"artistCredit": string;
/**
* TrackCount is the group's local track count.
*/
"trackCount": number;
/**
* GroupCount is how many tagging groups this album spans.
*
* More than one means a multi-disc album (one group per disc), and
* it is the reason this is a field rather than an implementation
* detail: applying "the album" from a single button would retag
* one disc of three and leave the folder holding a mix of old and
* new tags. The caller offers review instead.
*/
"groupCount": number;
}
/**
* AlignmentView mirrors autotag.TrackAlignment. LocalIndex of -1
* means "candidate has this track, folder doesn't" (status=missing).
@@ -160,6 +160,39 @@ export function ListPendingFolders(libraryID: number): $CancellablePromise<$mode
return $Call.ByID(617511590, libraryID);
}
/**
* MatchForAlbum answers "does the autotagger have something confident
* to say about this album", for the album detail page.
*
* Three things about it are load-bearing.
*
* **It costs no MusicBrainz request.** Everything it needs is already
* on disk: `tagging_items` carries the top score and release from the
* background prefetch, and `tagging_candidates` durably holds the
* scored list. The rate limiters here are shared with every page the
* user can open, so a lookup that fires on page load must not join
* that queue — which also means this returns nothing for a folder
* nobody has scored yet, rather than scoring it now. That is the
* right trade: the prefetch will get to it, and a page that silently
* spends a minute of somebody's MusicBrainz budget to draw a banner
* is worse than a page that says nothing.
*
* **The tier is computed, not read.** `tagging_items.score` is the raw
* number and `Recommend` is what turns it into a claim — capping it
* for an ambiguous runner-up, an incomplete alignment or a folder too
* small to corroborate itself. Filtering on the raw score would
* promise confidence the scorer had explicitly withheld.
*
* **Nothing is said about an album the user has already answered
* for.** Only a `pending` group qualifies: `confirmed` covers both a
* finished apply and an explicit "leave as is", and `skipped` is the
* user saying not now. Re-offering either is nagging, and "leave as
* is" would be actively wrong to argue with.
*/
export function MatchForAlbum(albumID: number): $CancellablePromise<$models.AlbumMatchView | null> {
return $Call.ByID(514173221, albumID);
}
/**
* RetagGroup flips a group back to 'pending' so the user can
* re-review after an apply or skip. Drops the durably-cached