Settings — Subtitle Automation

The Subtitle Automation page configures the drain worker — a background loop that picks up new library items, decides whether to extract embedded subtitles, and runs post-extract cleanup. It’s the system that takes “Sonarr just imported episode E07” all the way to “subtitle is on disk and the foreign tracks are gone”, with no manual click.

The drain queue

When the library scan or webhook discovers a new item, an entry is pushed onto the drain queue. The drain worker pulls items off the queue at the configured interval and runs the pipeline.

The queue holds two kinds of work, and one item can be waiting for both at once:

Task type	Queued when	What the worker does
Embedded extract	The file has an embedded subtitle track in the target language	Copies the track out of the container into a sidecar
Sidecar translate	The file has an external subtitle in some other language sitting next to it, and translation is on	Translates that sidecar into the target language

Sidecar translation is queued here rather than run during the wanted search on purpose. A single translation takes minutes, and the search job holds a global lock while it runs — doing translations inline meant one search could block every later search for hours, so downloads stopped while translation kept going. Queueing the work lets the search finish in seconds and gives the translation the queue’s retry, backoff and cancellation handling.

Note

If Enabled is off, nothing drains the queue, so the wanted search keeps translating local sidecars itself. In that mode it works through them for at most ten minutes per run and picks the rest up on the next run, so a large backlog cannot stall provider searches.

Setting	Default	Values	Effect
Enabled	off	toggle	Master switch for the whole automation pipeline. Off by default — nothing below runs until you turn this on.
Queue enabled	on	toggle	The drain worker itself. Leaving this on while Enabled is off changes nothing; turning it off stops the queue from being drained even when automation is on, which is the switch to use if you want to pause draining without losing the queued items.
Drain interval (min)	2	1–60	Minutes between drain ticks. This is what the subtitle_automation scheduler job runs on — the most frequent job Sublarr has.
Auto-extract embedded	on	toggle	When the file has an embedded subtitle in the target language, extract it instead of searching providers.
Fallback to provider search	on	toggle	If the file has no usable embedded subtitle, fall through to provider search.

The Auto-Extract Queue card also has Copy ASS tracks unchanged (off by default). On, embedded ASS/SSA tracks are extracted by stream copy instead of being re-encoded, which is faster and avoids stalls on complex tracks; a failed copy falls back to the encoder.

Extraction also reads the text of an SRT: a track whose words are English but whose name says German (or the other way round) is dropped instead of being saved as .de.srt, and stays in the video. Extracted tracks, manual extractions and translations go through the same post-processing as downloads.

The Foreign-Track Cleanup section further down this same page controls whether embedded subtitle tracks in other languages get stripped after a successful download or extract, and which variants of a kept language survive (track variant mode, keep forced, keep SDH, sidecar policy) — see Cleanup → Foreign-Track Removal for the full config table (keep-languages, keep-und, track variant policy, per-series and per-movie overrides).

Tip

Embedded subtitles are usually higher quality than what providers ship. Keep Auto-extract embedded on unless you specifically prefer provider releases (e.g. you trust Erai-raws timing more than the official streamer’s).

Pipeline order

For each item the worker pulls off the queue:

1. Probe the container for embedded subtitle streams.
2. If a stream in the target language exists and Auto-extract is on → extract.
3. If extract fails or no embedded stream → search providers.
4. If a provider returns a candidate that beats the cutoff → download.
5. If Strip by default (Foreign-Track Cleanup, further down this page) is on → queue a separate automation task that strips the non-kept embedded subtitle tracks from the container shortly afterwards and then refreshes the media server.
6. If translation is enabled and the item still lacks the target language → queue translation.
7. Write the result to the database; emit websocket event for the UI.

Each step writes to Activity → History with timing, so you can audit which step took how long.

Probe vs. extract

Probing is cheap (reads the container header); extraction copies bytes. The worker probes every queued item but only extracts when the result will be used:

Probe outcome	Action
Has target-language embedded stream	Extract.
Has target-language embedded stream but it’s image-based (PGS / VOBSUB)	Skip extract; image subs need OCR which is a separate pipeline.
No target-language embedded	Skip extract; fall through to provider search.
Container too damaged to probe	Log warning; mark item as probe_failed; skip the rest.

Concurrency

Setting	Default	Values	Effect
Drain workers	2	1–8	How many items can be in-flight concurrently.
Max concurrent extracts	2	1–8	Cap on parallel mkvextract invocations.

Extract is bounded by both knobs — min(drain_workers, max_concurrent_extracts) is the effective limit.

Webhook integration

When inbound webhooks are configured (Settings → Connections → Webhooks → Auto-translate on import), the webhook receiver pushes the item directly into the drain queue, bypassing the next scheduled tick. The worker still respects the concurrency limits, but you don’t wait the full drain interval before the work starts.

Per-series override

The Auto-extract embedded flag can be overridden per series under Library → Series detail → Processing override. Useful for series where you specifically want provider subtitles (better translation quality, additional cues, etc.) even when an embedded track exists.

Skipping items

Items can be excluded from drain processing:

Surface	Effect
Library → Series → Pause	Drain queue skips this series until unpaused.
Wanted → Skip	Drain queue ignores this item permanently.
Scan ignore patterns	Files matching the patterns never enter the queue.

Resurrection

Items that ended in failed state can be re-queued in batch:

Action	Effect
Settings → Subtitle Automation → Resurrect failed	Pulls every failed item back to pending and re-queues. Confirm prompt shows count.
Library → Wanted → Filter: failed → Resurrect selected	Same, scoped to selection.

Caution

Resurrection re-runs the full pipeline — providers, translation, cleanup. On a 5,000-item failed-batch this can take hours and incur translation cost. Confirm the count before clicking.

Slow mode

The drain worker has no slow mode of its own; it is paced by Drain interval and the concurrency limits above. Slow mode in Sublarr refers to wanted items that keep finding nothing and are then searched only about once a month — see Wanted → Slow mode.

Statistics

The page header shows live drain stats:

Tile	Counts
Queued	Items waiting to be processed.
Running	Currently in-flight.
Completed (24h)	Successful drains in the last 24 hours.
Failed (24h)	Items that ended in failed state.
Average duration	Median wall-clock time per item over the last 24h.

Decision log

Setting	Default	Effect
decision_log_enabled	on	Records why each search picked what it picked. Turn off to skip the per-search JSON snapshot.

With the setting on, every search stores its provider list, filter-stage rejections and score breakdown, reachable via the why? action in History. See Decision log.