Documentation
Documentation
subtrace is a single Go binary (and a container image) that walks the media
libraries you configure, finds videos with no subtitle sidecar, and downloads
.srt files next to them.
Everything about a library comes from the TOML config — nothing is compiled in.
Start here
Install, write a config, do a first run.
Why folder names decide whether subtrace can find anything.
Every key, every environment variable, ignore patterns.
scan, fetch, watch, status, config — and their flags.
Going deeper
opensubtitles.com and subdl.com: credentials, quotas, fallback.
The pipeline, ranking, and the item status lifecycle.
Why a big library takes months, and how to control it.
Plex refresh and shoutrrr notifications.
Permissions, missing ids, parked providers, container paths.
Dev loop, and how to add a provider.
The one thing to know first
Matching is driven by the external id embedded in your folder names. A library
named the Plex / TRaSH way —
Heat (1995) {tmdb-949} — matches exactly. A
library without ids falls back to a title-and-year query, which is much less
reliable. See Naming and matching.