Settings — Search & Scan

This page configures the heartbeat of Sublarr’s automation: how often the wanted scanner runs, how many providers it asks in parallel, and whether existing subtitles get upgraded when a better one appears. The defaults are sane for most installs — only tweak when you’re hitting provider rate limits or running on constrained hardware.

Wanted scanner

The scanner walks the library, identifies items missing target-language subtitles, and queues searches.

Setting	Default	Values	Effect
Scan interval (h)	0	0–168	Hours between library scans. 0 disables periodic scans; webhooks and manual scans still work.
Scan on startup	off	toggle	Run a library scan immediately when Sublarr boots.
Wanted search interval (h)	24	0–168	Hours between provider-search runs for queued wanted items. 0 disables the periodic search job.
Search on startup	on	toggle	Run a wanted search immediately when Sublarr boots.
Backoff on 429	on	toggle	Slow down when a provider rate-limits. Strongly recommended on.
Backoff base (h)	1	0.25–24	Initial backoff delay after a rate-limit.
Backoff cap (h)	168	1–168	Maximum backoff. Provider unsticks fully after this.
Adaptive backoff	on	toggle	Per-provider backoff state. Disable for predictable per-cycle behaviour.
Backlog reserve (%)	50	0–80	Once any provider has used this share of its daily budget, items marked backlog are dropped from the rest of the cycle. See How the queue is ordered.
Priority weighting	on	toggle	Sort by item priority before anything else — premium first, then standard, then backlog. Off means the search order below decides alone.
Search order	fair	fair / newest_first / weighted	Within a scan cycle, order to process items.

Tip

For active Sonarr/Radarr setups, keep periodic scans disabled and rely on webhooks plus the 24-hour wanted search sweep. Use a scan interval only when your stack cannot send webhooks reliably.

How the queue is ordered

A wanted search run cannot process everything, so two settings decide who goes first and who gets left out when provider quota runs short.

Priority weighting decides the order. Every wanted item carries a priority — premium, standard or backlog. With weighting on, that rank is applied before the search order below, so a premium item outranks a backlog item no matter which preset you picked. Turn it off and the preset decides alone.

Backlog reserve decides who gets dropped. It is a threshold on provider budget, not a share of the queue — the name is easy to read the other way round. Sublarr looks at the daily budget usage of every provider; once the busiest one has consumed this percentage of its allowance, items marked backlog stop being searched for the remainder of the cycle. Everything else keeps going.

The point is that a large backlog would otherwise burn the day’s provider quota on old items that have already failed many times, leaving nothing for the episode that aired tonight. At the default of 50, backlog work gets the first half of each provider’s daily allowance and yields the rest.

Set it to 80 to let backlog items run further into the budget, or to 0 to stop searching them as soon as any provider is used at all. Providers without a declared daily limit never trigger the gate.

Library scan

Independent of the wanted scanner — the library scan is what discovers files in the first place (Standalone mode) or syncs with Sonarr/Radarr (*arr mode).

Setting	Default	Values	Effect
Standalone scan interval (h)	6	0–168	How often Sublarr re-walks Standalone folders. 0 disables periodic Standalone scans. *arr mode uses webhooks instead.
Skip extras	on	toggle	Skip files matching the configured “extras” patterns (trailers, behind-the-scenes).
Min file size (MB)	100	0–10000	Reject files below this size as not real content.
Ignore patterns	*.tmp,*.partial,*sample*	comma-separated globs	Filenames that match any pattern are skipped.
Ignore languages	empty	comma-separated codes	Existing sidecars in these languages are ignored when computing “missing language”.
Yield (ms)	0	0–500	Sleep between file probes. Raise on slow storage to avoid IO saturation.
Min metadata workers	4	1–32	Parallel metadata lookups. Raise on fast storage + good network.
Parallel media processes	1	1–8	How many disk-heavy subprocesses (container remux, subtitle extraction, ffsubsync/alass, metadata scan batches) may run at once, process-wide. 1 serialises them so a burst of downloads cannot rewrite several multi-GB files in parallel and starve the rest of the array; raise only on SSD/NVMe storage. Metadata workers are capped by this value.

Upgrades

When Upgrade enabled is on (per-profile and globally), Sublarr replaces existing subtitles with better-scoring ones found in subsequent searches.

Setting	Default	Values	Effect
Upgrade enabled	on	toggle	Global master. Per-profile setting can disable for specific series.
Upgrade scan interval (h)	0	0–168	How often Sublarr scans for upgrade candidates. 0 disables scheduled upgrades; manual upgrade scans still work.
Upgrade min score delta	50	score points	Replace only if the new candidate beats the current by at least this.
Upgrade window (days)	7	days	Only subtitles inside this age window are considered for upgrades.
upgrade_protect_user_modified	on	toggle	Never auto-replace a subtitle you edited by hand.
Automatic repair	off	toggle	Timing check on downloads, timing repair on disk and signs-only sidecars treated as missing. See Automatic repair.

The replaced subtitle goes to Trash for the configured retention.

Protecting your own edits. Once you save a change in the subtitle editor, Sublarr marks that file as hand-edited. With upgrade_protect_user_modified on — the default — the upgrade pass skips it, so an hour spent fixing timings is not undone by a marginally better-scoring download. Turn it off only if you want automation to win unconditionally.

Caution

Lowering Upgrade min score delta too far causes Sublarr to repeatedly swap subtitles that score nearly equally — wasting bandwidth and confusing media servers. Keep the default unless you have a specific reason.

An SRT to ASS upgrade (and the “keep ASS” cleanup) no longer replaces a subtitle with one that holds less than a quarter of its lines.

Automatic repair

Off by default; an update leaves your library alone until you turn it on. One switch, Automatic repair, under Settings → Automation → Search, scan & upgrades (next to the upgrade rules). It covers three things:

• Timing check on every download. Before a downloaded subtitle is saved, it is lined up with the video: against an embedded text track (MKV and MP4 mov_text), or else against a full sidecar in another language. A subtitle that runs a constant few seconds early or late is shifted into place. One whose lines fit the video at no offset (another cut or episode) is skipped in favour of the next candidate. A sidecar used as the reference never blocks every candidate, because it may be the wrong one itself.
• Timing repair for subtitles already on disk. The nightly subtitle-health sweep runs the same check on existing sidecars. A delayed one is shifted (the original is kept as a backup); one for another cut goes to the trash, its download is blacklisted and the episode is searched again. Both act only on a certain verdict and can be undone.
• Signs-only sidecars count as missing. A full-looking .de.ass or .srt that holds only a title card and credits no longer counts as the subtitle: the wanted scans and the search treat it as missing and the episode gets its search attempts back. The file stays until a validated replacement overwrites it. A new full .de.srt also moves a signs/credits-only .de.ass of the same episode to the trash, so the player no longer offers both. .forced and signs sidecars are never touched.

Replaced files go to the trash. The health panel lists the findings whether the switch is on or not.

Concurrent searches

Sublarr caps how many provider calls run in parallel. Lower caps protect upstream providers; higher caps drain a wanted backlog faster on capable hardware.

Setting	Default	Values	Effect
Max concurrent provider searches	3	1–10	Per-Sublarr-instance global cap.
Per-provider concurrency	2	1–8	Cap per provider. Some providers throttle aggressively per-IP.
Provider delay (ms)	0	0–5000	Sleep between consecutive calls to the same provider. Use when a provider rejects rapid sequential calls.

Trigger a scan manually

Three buttons at the top of the page:

Button	Effect
Scan library now	Runs library scan once.
Search wanted now	Runs wanted scanner once.
Upgrade scan now	Runs upgrade scan once.

Manual triggers respect the same concurrency caps and rate limits as the scheduled equivalents.

Where the underlying scheduler lives

The actual jobs that run on these intervals are owned by APScheduler under Settings → System → Scheduler. This page is a high-level surface for the most-tuned settings; the Scheduler page exposes raw cron triggers, history, and per-job pause/resume.