Settings — Sync Engines

This page tunes the fallback chain for automatic subtitle sync — what runs first, what runs if it fails, when the chain bails out. The user-facing sync workflow lives at Multi-Engine Sync; this page configures the global defaults that workflow uses.

Engine order

Sublarr ships four sync engines. The order determines which gets tried first; if it fails or its result fails the sanity check, the next engine runs.

Engine	Best for	Speed
ffsubsync	Most cases — phonetic alignment between subtitle and audio.	Medium (~ 2-5 min per file).
alass	Hard cases — handles large drift and mid-file resync points.	Slow (~ 5-15 min).
framerate	Fixed PAL ↔ NTSC offset (24 vs 23.976 fps).	Instant.
chapter	Container has chapter markers — align cues to chapter boundaries.	Instant.

Default order: ffsubsync → framerate → chapter → alass. Reorder via drag-and-drop in the engine list.

Sanity threshold

After every sync attempt, Sublarr compares the original cue boundaries to the synced output. If the result differs by more than the threshold from a sanity-checked alignment, the engine’s output is rejected and the chain falls through to the next engine.

Setting	Default	Values	Effect
Sanity threshold (s)	2.5	0.5–10.0	Maximum acceptable divergence between expected and produced timing at any cue boundary.
Sanity sample size	10	5–50	Number of cues spot-checked. Larger = stricter.

If every engine fails the sanity check, the chain aborts and the original (unsynced) subtitle is kept; the failure is reported to Activity → Sync and as a sync_failed notification event.

Tip

A threshold of 2.5s is a defensible default — it accepts normal sync results while rejecting “engine returned garbage”. If you have heavily-drifted source material (e.g. fan-subbed releases mismatched against retail releases), raise to 5.0s so legitimate large corrections aren’t rejected.

Per-engine settings

ffsubsync

Setting	Default	Values	Effect
Max offset (s)	60	1–600	Maximum offset ffsubsync will consider. Cap to avoid runaway alignments on noisy audio.
Use VAD	on	toggle	Voice Activity Detection — improves accuracy on dialogue.
Encoding override	empty	encoding name	Force a specific subtitle encoding. Empty = auto-detect.

alass

Setting	Default	Values	Effect
Split penalty	7	0–20	Higher = fewer split points (one offset for the whole file). Lower = aggressive resync at scene changes.
No-split flag	off	toggle	Force single-offset alignment regardless of split penalty.
Sub FPS override	empty	float	Source subtitle’s frame rate. Empty = auto-detect.

framerate

Setting	Default	Values	Effect
PAL ↔ NTSC factor	25 / 23.976	float	Conversion factor. Override for non-standard pairs.
Detect direction	auto	auto / pal-to-ntsc / ntsc-to-pal	Which direction to convert. auto infers from container metadata.

chapter

Setting	Default	Values	Effect
Min chapters	3	1–20	Skip the engine if the file has fewer than this many chapter markers.
Anchor mode	first-cue	first-cue / chapter-spacing	Whether to align based on the first cue’s chapter or use chapter spacing as the metric.

When engines run

Sync runs in three contexts:

Trigger	Behaviour
Library → Sidecar pill → Sync	One-off; user picks engines or uses default chain.
Auto-sync on download	Right after a successful download. Enable in Settings → Automation → Auto-sync.
Auto-sync on extract	Right after extracting an embedded subtitle, when the embedded timing differs from the container.

Audio extraction cache

Sync engines need access to the audio track. Sublarr extracts audio once per video and caches the result:

Setting	Default	Effect
Cache audio extracts	on	Re-use the audio file for repeated sync attempts on the same video.
Cache directory	/config/cache/audio	Where extracted audio lives.
Cache size limit (GB)	10	LRU eviction when exceeded.
Cache TTL (days)	7	Drop audio extracts older than this regardless of size.

Engine selection per series

Sometimes you know a series is consistently mis-synced in a specific way (e.g. always 24/25 fps PAL conversion). Override per-series:

Surface	Effect
Library → Series detail → Sync override	Force a specific engine and skip the chain.
Profile → Default sync engine	Per-profile default for the chain start.

When sync gives wrong-but-consistent results

If every sync run produces output that’s offset by exactly the same amount (e.g. always 100 ms early), the issue is usually:

Cause	Fix
Different audio delay between videos	Adjust Settings → Subtitles → Stream Management → Audio offset compensation.
Subtitle source has consistent drift	Apply a one-time global offset in the editor; don’t re-sync every episode.
Container metadata claims wrong fps	Force the framerate engine first with the correct factor.