# Subtitle process — changelog

## v1 — 2026-05-09

Initial recipe. Drafted while running on American Dad. Distilled from doc
03-subtitles.md (Futurama work) and the actual AD run.

Approach: Jellyfin RemoteSearch/Subtitles/eng → pick best non-HI/non-MT match
via Python filter → POST download → docker cp metadata cache → media folder →
delete cache dupes → validation refresh.

Scope: works on shows whose library season/episode numbering matches
OpenSubtitles' indexed numbering. Verified passing on AD S01 (7/7 episodes).

### Known break — added 2026-05-09 same day

After S01 passed, S02 returned 0 results for every episode probed (E01, E02,
E08, E13). Quota was fine (13 downloads remaining). Cause:

> Jellyfin metadata for American Dad uses **Hulu/DSP season ordering**
> (S1=7, S2=16, S3=19, S4=16). OpenSubtitles indexes by **Fox original-airing
> order** where S1 has 23 episodes. The plugin queries OS by
> `(parent_imdb_id, season_number, episode_number)`. For library S02E01
> "Bullocks to Stan" the plugin sends `S=2,E=1` but OS catalogues that
> episode as `S=1,E=8`. Result: 0 hits.

Each library episode has its own correct per-episode IMDB id (e.g.
`tt0511631` for "Bullocks to Stan") which would resolve directly via OS REST
`imdb_id=` parameter, but the plugin doesn't expose that path.

### v2 — pending design

Two paths under consideration:

- **A. Direct OpenSubtitles REST** — bypass plugin for fetch, use per-episode
  IMDB id lookup. Requires registering a free API key at
  `opensubtitles.com/consumers`. Process becomes a Python script (or extends
  the existing helper) that logs in with `Caveman5` creds and uses the API
  key for searches. Survives any season-numbering mismatch.

- **B. Library re-numbering** — re-scan AD with metadata indexer using Fox
  airing order so library aligns with OpenSubtitles. Risk: re-orders existing
  files and breaks user's mental model of the library. Doesn't help if the
  next show has its own numbering quirk.

Recommendation: **A**. It's the more general fix; the next show with weird
numbering won't break it. It also unblocks higher-quality manual pick (filter
by `feature_id`, `imdb_id`, hash) which the plugin filters out today.