Metadata sources

Two are supported, and a comic can be matched against either. Add credentials in Settings; an admin can also set server-wide ones as a fallback for accounts without their own.

Source	Credentials	Budget
Comic Vine	a free API key	200 requests/hour per key
Metron	a free account login	5,000 requests/day

Ids are stored side by side rather than one replacing the other, so a library tagged from either stays cross-referenced with the other. Metron records the Comic Vine id for most issues, so matching there fills both in.

• Per comic: open a comic, hit "Match metadata", choose the source, pick the series, pick the issue.
• In bulk: the Match page runs through everything unmatched and applies results above a confidence threshold. Choose one source, or Any, which falls through your configured sources in order — see below.

Both go through one matching implementation, so the rules below hold whichever source answers — a fix for one cannot leave the other behind.

Falling through sources in order

Auto-match — used by Any in bulk match — tries your configured sources one at a time, in the order set on the Settings page. The first confident result decides the match: which series, which issue, which comic this is. That never changes once decided.

A later confident source can still fill in what the first left empty. Comic Vine has no genre or age_rating; Metron has no locations. Rather than stop the moment one source is confident and lose whatever the other could have added, auto-match keeps asking — in order — for as long as the record has a gap a next source might close, and copies in only the fields that were missing. A field the primary source already found is never replaced, even if a later source disagrees with it.

Only a confident source ever contributes a field — one that misses the confidence threshold is not trusted with the identity of the book (that would already have made it the primary match) and is not trusted to fill a gap in someone else's, either. A guess about the wrong book is not a safer source of detail just because it arrived second.

Once nothing is left to gain, no further source is asked. In practice, with only Comic Vine and Metron to choose between, that point is rarely reached after just one: Comic Vine has no concept of genre or age_rating, Metron has none of locations, so with both configured a confident match almost always consults both — the price of the richer record. What the "stop once nothing is missing" rule buys you is that this cost never grows further than it needs to: a hand-written record, or a future third source that turns out to be genuinely complete, is not asked pointless questions just because it answered first.

The order is reordered with plain ↑ / ↓ buttons next to each source on Settings; it is per account, never server-wide, since different libraries suit different sources first. It also decides which source a fresh single-comic match screen opens on. A source with no credentials is skipped rather than asked and refused.

If nothing is confident, the best candidate found by any source is still reported — unconfident, and un-enriched — exactly what asking a single source would have handed back — so falling through never finds less than one source would have.

How a file is matched to an issue

The series picks the volume; the issue number picks the book inside it. Where that number comes from, in order:

1. ComicInfo.xml inside the archive, if it has one.
2. An issue number in the filename — Batman 001, #12, Sandman - 001 -.
3. A volume marker with nothing else to go on — aftermath_vol2.cbz is taken as issue 2, because in a collection named that way the marker is the issue: Comic Vine calls the series the volume and numbers the books inside it 1, 2, 3.

If none of those yields a number, the comic is reported as unmatched rather than matched to something. A volume with more than one issue and no number to choose between them is genuinely ambiguous, and the only safe answer is to say so. The exception is a volume holding exactly one issue, which cannot be ambiguous.

When you correct a match by hand, the picker lists every issue in the volume and marks the one matching the number currently stored as likely. The number never filters the list — you are on that screen because it is wrong.

How the confidence score works

Candidate volumes are scored on the share of the available evidence that agrees, not on a total out of a fixed maximum. A signal counts as available only when both sides state it: a filename with no year is silent, not contradictory, so the year is left out of the sum entirely rather than scored as a partial hit.

That distinction matters because the alternative is quietly unfair. Scoring silence as a fraction of a hit holds the file that offers less evidence to a higher bar on the evidence it does offer — a name match good enough to clear the threshold with a year present would fall under it without one, and legitimate matches were being rejected for evidence they never claimed. The same applied in reverse to volumes where Comic Vine has no start year recorded.

A year present on both sides that disagrees still counts against the candidate, which is the point: absent evidence is excluded, conflicting evidence is penalised. Because the score is a ratio, each candidate in the picker shows what it was judged on — on name + year is a stronger 100% than on name.

Comic Vine allows 200 requests per hour per key and each comic costs two or three, so bulk matching manages roughly 60–90 comics an hour. That budget is why personal keys are worth setting on a shared server. Responses are cached for a week and the cache is shared, so re-running costs nothing.