Config reference

Every key, with the default applied when it is absent. subtrace config init prints this same set as a commented file.

`[[library]]`

Repeatable. At least one is required; there are no built-in paths.

Key	Type	Default	Notes
`path`	string	—	Required. Cleaned and, in a container, the path inside the container.
`kind`	string	—	Required: `"movie"` or `"tv"`. Seeds the guess; an `SxxEyy` in the filename still wins.
`name`	string	basename of `path`	Label used in logs and Plex section matching only.

[[library]]
path = "/media/Movies"
kind = "movie"

[[library]]
path = "/media/TV Shows"
kind = "tv"

Roots must not overlap and must not repeat — both are rejected at load.

`[scan]`

What counts as a media file, and what the walk skips.

Key	Type	Default	Notes
`video_extensions`	list	`[".mkv", ".mp4", ".avi", ".m4v", ".mov", ".ts", ".mpg", ".mpeg", ".wmv"]`	Normalized to lowercase with a leading dot.
`ignore_dirs`	list	`["@eaDir", ".AppleDouble", "@Recycle", "lost+found", "#recycle", ".Trash-1000"]`	Exact directory-name matches, pruned entirely.
`ignore_patterns`	list	`[]`	Globs — see Ignore patterns.
`min_file_size_mb`	int	`50`	Files smaller than this are skipped: samples, clips, stray extras.
`follow_symlinks`	bool	`false`	Off by default so a symlink farm is not walked twice.

Dot-directories are always skipped, whether or not they are listed.

@eaDir is Synology’s per-directory metadata folder. Without it in the list, every file on such a NAS is counted twice.

`[subtitles]`

Key	Type	Default	Notes
`languages`	list	`["en"]`	ISO 639-1, in priority order. Each language is tracked separately.
`naming`	string	`"{basename}.{lang}.srt"`	Output template. Must contain `{basename}`; `{lang}` and `{ext}` also expand.
`extensions`	list	`[".srt", ".ass", ".ssa", ".sub", ".vtt"]`	Sidecar extensions that count as “already have this”.
`skip_if_any_language`	bool	`false`	`true`: any existing subtitle satisfies the video, whatever its language.
`prefer_hearing_impaired`	bool	`false`	Nudges ranking toward (or away from) HI/SDH releases.
`overwrite`	bool	`false`	`true`: fetch even when a sidecar already exists, replacing it.

How the “already has subtitles” test works in detail is on Naming and matching.

`[providers]`

Key	Type	Default	Notes
`order`	list	`["opensubtitles", "subdl"]`	Tried left to right. Unknown names are rejected at load.

`[providers.opensubtitles]`

Key	Type	Default	Env override
`enabled`	bool	`true`	—
`api_key`	string	`""`	`SUBTRACE_OPENSUBTITLES_API_KEY`
`username`	string	`""`	`SUBTRACE_OPENSUBTITLES_USERNAME`
`password`	string	`""`	`SUBTRACE_OPENSUBTITLES_PASSWORD`
`daily_cap`	int	`100`	`SUBTRACE_OPENSUBTITLES_DAILY_CAP`

`[providers.subdl]`

Key	Type	Default	Env override
`enabled`	bool	`true`	—
`api_key`	string	`""`	`SUBTRACE_SUBDL_API_KEY`
`daily_cap`	int	`100`	`SUBTRACE_SUBDL_DAILY_CAP`

daily_cap is a local guard enforced from subtrace’s own counter. Keep it at or below your account’s real quota so runs stop on their own terms instead of collecting rejections. A cap of 0 or less means “no local limit”. See Providers.

`[run]`

Key	Type	Default	Env override
`db_path`	string	`/config/subtrace.db` if `/config` exists, else `$XDG_DATA_HOME/subtrace/subtrace.db` (`~/.local/share/...`)	`SUBTRACE_DB_PATH`
`concurrency`	int	`4`	`SUBTRACE_CONCURRENCY`
`max_per_run`	int	`50`	`SUBTRACE_MAX_PER_RUN`
`retry_after_hours`	int	`168`	—
`max_attempts`	int	`5`	—
`interval`	duration string	`"12h"`	`SUBTRACE_INTERVAL`

max_per_run bounds one fetch; --limit overrides it for a single run.
retry_after_hours is how long a not_found or failed item waits before it is eligible again; max_attempts is when it is given up on entirely.
interval drives subtrace watch. An unparseable value falls back to 12h at runtime, but config validate flags it.

The database directory is created if missing. SQLite runs in WAL mode, so subtrace status is safe to run during a fetch.

`[plex]`

Key	Type	Default	Env override
`enabled`	bool	`false`	implied `true` when `SUBTRACE_PLEX_TOKEN` is set
`url`	string	`"http://localhost:32400"`	`SUBTRACE_PLEX_URL`
`token`	string	`""`	`SUBTRACE_PLEX_TOKEN`

`[notify]`

Key	Type	Default	Env override
`urls`	list	`[]`	`SUBTRACE_NOTIFY_URLS` (comma-separated)
`on`	list	`["run_complete", "error"]`	—

urls are shoutrrr service URLs; every configured service receives every enabled event. Valid on values are run_complete and error. See Integrations.

Environment variables