Resolving release names

Resolving is how the Sonarr proxy and the library’s resolve call understand names like [SubsPlease] Spy x Family - 17 (1080p). New terms are in the glossary.

Resolving turns a release name into a work and an episode. Every answer carries a confidence and a reason, so a wrong answer can be debugged from the response alone.

1. Parse. The parser pulls out the group, title, season or part token, episode (a single number, a range, or a version like 05v2), year, resolution, source, codec and flags. [SubsPlease] Spy x Family - 17 (1080p) gives group SubsPlease, title Spy x Family, episode 17.
2. Normalize the title the same way every alias was normalized: lowercase, accents and punctuation folded, × read as x, filler words (the, season, part, cour) dropped.
3. Match. Look the title up in the alias index (every title and synonym of every work). A year the parser took out of the title is tried as part of it too, since remakes carry it (“Doraemon (2005)”). With no exact hit, a trigram search finds near spellings. An alias several works share splits its weight between them.
4. Interpret the number for each candidate: a group override first; then a season token read as a TVDB season (for a long-runner, S02E70 is not episode 70); then a number within the work’s own count; then a number past it, walked through the work’s absolute sequence.
5. Score. Evidence multiplies season fit, episode fit and year fit; a tie-breaker that disagrees scores 0.05. A sequel with no season token is penalized only when the matched alias is shared with an earlier work of its chain. Title rank (a work that holds the title beats works that only list it as a synonym) and type (TV and movies over OVAs and ONAs, over specials) break remaining ties, but never overturn other evidence. A release the indexer posted in the last few weeks, when the proxy or a caller knows the date, first favors a work that is on air now over an older finished work with the same title. A release posted after a remake of a finished work premiered (Cat’s Eye, 2025, against 1983), when the tie is only on the title and every older sharer premiered years earlier in another chain, favors the remake; the same release with no posting date stays ambiguous.

The answer is ok only at 0.85 or more with a lead of at least 0.1. Otherwise it is ambiguous, with every candidate, or unmatched. Courmap never returns a low-confidence guess as ok: tools decide what to do with an ambiguous answer, and the Sonarr proxy passes such releases through unchanged.

A corpus of release names with known answers runs in CI on every change, and the pass rate may never drop.