yolo/arr
3
0
Fork 0
Code Issues 12 Pull Requests Actions Packages Projects Releases Wiki Activity

Rank subtitle candidates in arr-core #185

New Issue
Closed
opened 2026-08-24 21:28:31 +01:00 by naps62-yolo · 1 comment
naps62-yolo commented 2026-08-24 21:28:31 +01:00
Owner
Copy Link
Copy Source

Rank subtitle candidates in arr-core, pure and heavily tested, alongside the
release scoring in §5.5. No IO, no provider knowledge — the input is a list of
candidates and the facts known about the media file, the output is an ordered
verdict list in the shape §9.3 already renders.

Rules, from DESIGN.md §15 (added by #183):

  • A moviehash match wins outright. It identifies the exact file and nothing
    else can beat it.
  • Then an exact release-name match, then same release group or same source,
    then uploader rating and download count as tiebreakers.
  • A forced candidate is never eligible. It covers foreign-language lines only
    and cannot satisfy a want.
  • An SDH candidate is eligible but ranks below any plain candidate for the same
    language.
  • Every rejected candidate names the rule that rejected it, as a value the API
    and UI can render — not a string built for a log line.

The verdict vocabulary mirrors the release path (eligible / rejected(rule))
so the manual view in §9.3 needs no second concept. There is no waived
bucket here: nothing about a subtitle is worth overriding by hand, and the
manual grab path (#199) lets the operator pick any candidate directly.

Non-goals: fetching, downloading, deciding what is wanted. Wantedness is a
reconcile-loop question (#196).

Depends on: #183

Rank subtitle candidates in `arr-core`, pure and heavily tested, alongside the release scoring in §5.5. No IO, no provider knowledge — the input is a list of candidates and the facts known about the media file, the output is an ordered verdict list in the shape §9.3 already renders. Rules, from DESIGN.md §15 (added by #183): - A `moviehash` match wins outright. It identifies the exact file and nothing else can beat it. - Then an exact release-name match, then same release group or same source, then uploader rating and download count as tiebreakers. - A forced candidate is never eligible. It covers foreign-language lines only and cannot satisfy a want. - An SDH candidate is eligible but ranks below any plain candidate for the same language. - Every rejected candidate names the rule that rejected it, as a value the API and UI can render — not a string built for a log line. The verdict vocabulary mirrors the release path (`eligible` / `rejected(rule)`) so the manual view in §9.3 needs no second concept. There is no `waived` bucket here: nothing about a subtitle is worth overriding by hand, and the manual grab path (#199) lets the operator pick any candidate directly. Non-goals: fetching, downloading, deciding what is wanted. Wantedness is a reconcile-loop question (#196). Depends on: #183
naps62-yolo added this to the Subtitles milestone 2026-08-24 21:28:31 +01:00
naps62-yolo added the area/coretype/featuredifficulty/moderatephase/9-subtitles labels 2026-08-24 21:28:31 +01:00
naps62-yolo added a new dependency 2026-08-24 21:29:27 +01:00
#183 Amend DESIGN.md with a subtitles section
naps62-yolo added a new dependency 2026-08-24 21:29:27 +01:00
#196 Close the subtitle gap in the reconcile loop
naps62-yolo commented 2026-08-24 21:50:34 +01:00
Author
Owner
Copy Link
Copy Source

Implemented subtitle candidate ranking in arr-core (crates/arr-core/src/subs.rs), pure and IO-free per §15. SubtitleTarget carries the known facts about the media file (moviehash, release_name, release_group, source); SubtitleCandidate carries a provider's reported evidence. rank() returns candidates ordered best-first, each paired with a SubtitleVerdict — Eligible or Rejected(SubtitleRule), mirroring the release path's verdict shape with no waived bucket. A forced candidate is always Rejected(SubtitleRule::Forced). Among eligible candidates, plain always outranks SDH for the same language (an absolute split, not a tiebreaker); within that split the order is moviehash match, then exact release-name match, then shared release group or source, then uploader rating and download count. 7 new tests cover each tier and the forced/SDH carve-outs; 130 total in arr-core, all passing.

Branch: subtitles/185-rank-subs

just ci passed (475/475 tests, clippy/fmt/machete/tokens all clean).

Findings

None outside this issue's scope.

Implemented subtitle candidate ranking in `arr-core` (`crates/arr-core/src/subs.rs`), pure and IO-free per §15. `SubtitleTarget` carries the known facts about the media file (`moviehash`, `release_name`, `release_group`, `source`); `SubtitleCandidate` carries a provider's reported evidence. `rank()` returns candidates ordered best-first, each paired with a `SubtitleVerdict` — `Eligible` or `Rejected(SubtitleRule)`, mirroring the release path's verdict shape with no `waived` bucket. A forced candidate is always `Rejected(SubtitleRule::Forced)`. Among eligible candidates, plain always outranks SDH for the same language (an absolute split, not a tiebreaker); within that split the order is `moviehash` match, then exact release-name match, then shared release group or source, then uploader rating and download count. 7 new tests cover each tier and the forced/SDH carve-outs; 130 total in `arr-core`, all passing. Branch: `subtitles/185-rank-subs` `just ci` passed (475/475 tests, clippy/fmt/machete/tokens all clean). ## Findings None outside this issue's scope.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
area/api
arr-api
 area/ci
CI and test harness
 area/compat
arr-compat
 area/core
arr-core
 area/daemon
arr-daemon
 area/db
arr-db
 area/dl
arr-dl
 area/indexer
arr-indexer
 area/infra
workspace and tooling
 area/meta
arr-meta
 area/parse
arr-parse
 area/probe
arr-probe
 area/subs
arr-subs crate: providers, extraction, translation, sync
 area/web
web/
 difficulty/easy
bounded, obvious approach, few files
 difficulty/hard
subtle correctness or cross-cutting
 difficulty/moderate
multiple files, judgement, an interface to design
 difficulty/trivial
one file, mechanical, no design decisions
 phase/1-skeleton
workspace, CI, config, database, empty API and SPA
 phase/2-logic
parsing and policy engine, pure, no network
 phase/3-sourcing
TMDB and Prowlarr, read-only
 phase/4-movies
movies end to end
 phase/5-ui
search, buckets, library views, queues
 phase/6-tv
seasons, episodes, tracking, derived status
 phase/7-people
owner tags and notifications
 phase/8-compat
Jellyseerr shim
 phase/9-subtitles
build order: subtitles, DESIGN.md §15
 type/bug
type/chore
type/feature
type/test
No labels area/core difficulty/moderate phase/9-subtitles type/feature
Milestone
No items
No Milestone Subtitles
Projects
Clear projects
No projects
Assignees
Clear assignees
hermes (Hermes (agent)) naps62 (Miguel Palhas) naps62-yolo (naps62-yolo (agent))
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Blocks
#196 Close the subtitle gap in the reconcile loop
yolo/arr
Depends on
#183 Amend DESIGN.md with a subtitles section
yolo/arr
Reference: yolo/arr#185