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

Add the arr-subs crate with the provider trait #184

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

Create crates/arr-subs, the crate that owns everything subtitle-shaped that
touches the outside world: providers, extraction, translation backends and the
alass wrapper. Selection and ranking rules stay pure in arr-core (#185),
the same way arr-probe shells out to ffprobe while the policy engine that
consumes its output does not.

Scope for this issue is the skeleton the rest of the milestone builds on:

  • Workspace member, [lints] workspace = true, dependencies referenced by name
    from [workspace.dependencies] per CLAUDE.md.
  • The domain types a provider deals in: a subtitle language (carrying the
    pt-PT / pt-BR distinction arr-probe's language module already resolves),
    a candidate with the fields ranking needs — provider, hash match, release
    name, group, source, rating, download count, forced flag, SDH flag — and the
    fetched result.
  • A Provider trait: search for candidates for a media file, download one by
    id. Async, error type per the crate's own error.rs, no provider
    implementations yet.
  • The cargo feature skeleton for translation backends, with every feature
    declared and no backend behind them yet.

Non-goals: any provider implementation, any translation code, any ranking
logic. Those are separate issues and this one must not anticipate their
interfaces beyond the trait above.

See DESIGN.md §15 (added by #183) for the wanted-set and provider decisions.

Depends on: #183

Create `crates/arr-subs`, the crate that owns everything subtitle-shaped that touches the outside world: providers, extraction, translation backends and the `alass` wrapper. Selection and ranking rules stay pure in `arr-core` (#185), the same way `arr-probe` shells out to `ffprobe` while the policy engine that consumes its output does not. Scope for this issue is the skeleton the rest of the milestone builds on: - Workspace member, `[lints] workspace = true`, dependencies referenced by name from `[workspace.dependencies]` per `CLAUDE.md`. - The domain types a provider deals in: a subtitle language (carrying the pt-PT / pt-BR distinction `arr-probe`'s `language` module already resolves), a candidate with the fields ranking needs — provider, hash match, release name, group, source, rating, download count, forced flag, SDH flag — and the fetched result. - A `Provider` trait: search for candidates for a media file, download one by id. Async, error type per the crate's own `error.rs`, no provider implementations yet. - The cargo feature skeleton for translation backends, with every feature declared and no backend behind them yet. Non-goals: any provider implementation, any translation code, any ranking logic. Those are separate issues and this one must not anticipate their interfaces beyond the trait above. See DESIGN.md §15 (added by #183) for the wanted-set and provider decisions. Depends on: #183
naps62-yolo added this to the Subtitles milestone 2026-08-24 21:28:31 +01:00
naps62-yolo added the area/substype/featuredifficulty/moderatephase/9-subtitles labels 2026-08-24 21:28:31 +01:00
naps62-yolo added a new dependency 2026-08-24 21:29:17 +01:00
#183 Amend DESIGN.md with a subtitles section
naps62-yolo added a new dependency 2026-08-24 21:29:27 +01:00
#187 Fetch subtitles from OpenSubtitles.com
naps62-yolo added a new dependency 2026-08-24 21:29:27 +01:00
#188 Fetch subtitles from Podnapisi
naps62-yolo added a new dependency 2026-08-24 21:29:27 +01:00
#189 Extract text subtitle streams to sidecar SRT
naps62-yolo added a new dependency 2026-08-24 21:29:27 +01:00
#190 Translate subtitles through a pluggable backend
naps62-yolo added a new dependency 2026-08-24 21:29:27 +01:00
#194 Sync subtitles with alass
naps62-yolo commented 2026-08-24 21:46:58 +01:00
Author
Owner
Copy Link
Copy Source

Added crates/arr-subs as a workspace member with [lints] workspace = true and dependencies referenced by name from [workspace.dependencies]. The crate carries the domain types a provider deals in — ProviderId and CandidateId newtypes, MediaRef/MediaFile/SearchRequest for the file being searched for, Candidate with the facts §15's ranking needs (hash match, release name, group, source, rating, download count, forced, SDH), and Fetched with a SubtitleFormat. Language is arr_core::Language, so the pt-PT / pt-BR distinction arr-probe's language module already resolves is reused rather than duplicated. The Provider trait has id, search and download, using boxed futures like arr-daemon's Action trait so it stays object safe — the enabled provider set is a database setting (#198), not a compile-time fact. Errors live in error.rs, each variant naming the provider, with RateLimited split out so #197 can render a cap as a queue state rather than a failure. The four translation-backend cargo features (translate-openai, translate-deepl, translate-google, translate-command) are declared with no backend behind them. No provider implementation, no translation code, no ranking.

Branch: subtitles/184-subs-crate

just ci passed: 473 tests, clippy clean, cargo machete clean, web-check clean.

Findings

  • #187 and this trait disagree about what a download returns. #187 says "download a chosen candidate to a temporary path"; the trait returns the bytes in Fetched.content instead. Bytes were chosen because what happens next is not the provider's call — alass runs over it (#194) before it gets a name and a place in the title folder (#195), and a provider that writes temp files also owns cleaning them up. If the temp-path shape is wanted, it should change here rather than in one provider.
  • arr_core::SubtitleTrack cannot express a forced embedded track. It carries only language. §15 says a forced track never satisfies a want, so #186 and #189 will record a forced embedded track as satisfying its language and the reconcile loop will stop looking. #189 already covers adding the codec to that struct (text versus bitmap); the forced disposition flag is not in any issue I can find and probably belongs to the same probe change.
Added `crates/arr-subs` as a workspace member with `[lints] workspace = true` and dependencies referenced by name from `[workspace.dependencies]`. The crate carries the domain types a provider deals in — `ProviderId` and `CandidateId` newtypes, `MediaRef`/`MediaFile`/`SearchRequest` for the file being searched for, `Candidate` with the facts §15's ranking needs (hash match, release name, group, source, rating, download count, forced, SDH), and `Fetched` with a `SubtitleFormat`. Language is `arr_core::Language`, so the pt-PT / pt-BR distinction `arr-probe`'s `language` module already resolves is reused rather than duplicated. The `Provider` trait has `id`, `search` and `download`, using boxed futures like `arr-daemon`'s `Action` trait so it stays object safe — the enabled provider set is a database setting (#198), not a compile-time fact. Errors live in `error.rs`, each variant naming the provider, with `RateLimited` split out so #197 can render a cap as a queue state rather than a failure. The four translation-backend cargo features (`translate-openai`, `translate-deepl`, `translate-google`, `translate-command`) are declared with no backend behind them. No provider implementation, no translation code, no ranking. Branch: `subtitles/184-subs-crate` `just ci` passed: 473 tests, clippy clean, `cargo machete` clean, web-check clean. ## Findings - **#187 and this trait disagree about what a download returns.** #187 says "download a chosen candidate to a temporary path"; the trait returns the bytes in `Fetched.content` instead. Bytes were chosen because what happens next is not the provider's call — `alass` runs over it (#194) before it gets a name and a place in the title folder (#195), and a provider that writes temp files also owns cleaning them up. If the temp-path shape is wanted, it should change here rather than in one provider. - **`arr_core::SubtitleTrack` cannot express a forced embedded track.** It carries only `language`. §15 says a forced track never satisfies a want, so #186 and #189 will record a forced embedded track as satisfying its language and the reconcile loop will stop looking. #189 already covers adding the codec to that struct (text versus bitmap); the `forced` disposition flag is not in any issue I can find and probably belongs to the same probe change.
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/subs 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
#187 Fetch subtitles from OpenSubtitles.com
yolo/arr
#188 Fetch subtitles from Podnapisi
yolo/arr
#189 Extract text subtitle streams to sidecar SRT
yolo/arr
#190 Translate subtitles through a pluggable backend
yolo/arr
#194 Sync subtitles with alass
yolo/arr
Depends on
#183 Amend DESIGN.md with a subtitles section
yolo/arr
Reference: yolo/arr#184