Subtitle Health

A subtitle file can be present and still be wrong: it shows literal \N instead of line breaks, claims to be German while the text is English, was saved in the wrong encoding so accented characters turn into mojibake, or runs so fast no one can read it. These defects don’t stop a file from being downloaded — they only surface when you actually watch.

Subtitle Health scans your subtitles for these content defects and repairs the safe ones, across both embedded tracks and on-disk sidecars. Every fix writes a full, reversible backup, so nothing is ever changed beyond recovery.

Note

Subtitle Health checks the content of a subtitle, not whether one exists. For “is a subtitle missing?” see Wanted; for removing unwanted tracks see Cleanup and Signs & Forced Removal.

What it checks

Nine checkers flag problems across formatting, language, encoding and timing. Representative findings:

Finding	What it means
Leaked escape codes	Literal \N / \h (ASS escape sequences) bled into the visible text instead of rendering as a line break or hard space.
Language mislabel	The sidecar’s language token (or the embedded track’s language tag) doesn’t match the language the text is actually written in.
Broken encoding	The file isn’t valid UTF-8 — Windows-1252 / Latin-1 bytes produce mojibake (ä for ä).
Format mismatch	The extension says one format but the bytes are another (e.g. an .srt that’s really ASS markup).
Timing errors	Overlapping cues, negative durations, or out-of-order timestamps.
High CPS	Characters-per-second so high the line can’t be read in the time it’s shown — flagged as an advisory, not auto-fixed.
Control characters	Stray control bytes or a misplaced BOM inside the cue text.

Each finding has a matching fixer where a safe automatic repair exists. A few — such as a high-CPS warning — are advisories: Sublarr surfaces them but leaves the decision to you.

Where findings appear

The same checks run at three scopes, so you can work at whatever level fits:

• Per episode — expand an episode to its track panel in the Library. Each defect shows inline next to the affected track or sidecar.
• Per series — a bulk scan on the series detail page checks every episode at once.
• Library-wide — Settings → System → Subtitle Health scans the whole library and lists every finding, grouped by type.

A scheduled sweep can run library-wide on a timer and auto-apply the safe fixes (see Scheduler). Advisories are never auto-applied.

Fixing a finding

Every finding offers contextual actions:

Action	Effect
Fix	Applies the matching repair (re-encode to UTF-8, unescape \N, correct the language tag, …). Writes a reversible backup first.
Strip track	For an embedded defect, removes that subtitle stream from the container via remux.
Open in editor	Jumps to the Subtitle Editor for manual work.
Re-align to audio	For a sidecar timing finding, runs a sync against the audio directly from the finding.
Dismiss	Accepts an advisory (e.g. a deliberate high-CPS karaoke track) so it stops being reported.

Tip

Every automatic fix is backed up. To undo one, use the Restore action on the finding, or manage the snapshots under Subtitle Backups. Removed tracks go to the Trash and stay recoverable.

Embedded vs. sidecar — no duplicate noise

When a clean sidecar of a given language exists, defects on the embedded track of the same language are automatically suppressed — you’ve already got a good copy, so Sublarr stops nagging about the version you no longer watch. Likewise, an advisory you dismiss (such as an accepted high-CPS warning) stays dismissed and doesn’t reappear on the next scan.

Configuration

Setting	Where	Effect
Subtitle Health sweep	Scheduler	Enables the recurring library-wide scan and which safe fixes it auto-applies.
Library-wide scan	Settings → System → Subtitle Health	On-demand full-library scan with per-finding actions.

Note

Fixes that change a file always create a .bak snapshot first, identical to the backups produced by the in-place editing pipeline — so Subtitle Health fixes are as reversible as any other change Sublarr makes.

AI quality check (experimental)

New in 1.10.0, off by default.

An optional advisory pass that asks a language model to judge a downloaded subtitle — is the translation coherent, does it read as machine output, are lines garbled? The verdict appears as a badge on the History entry. It is advisory only: nothing is deleted, replaced or re-downloaded because of it.

Setting	Default	Effect
ai_quality_enabled	off	Master switch for the check.
ai_quality_model	(empty)	Model to ask. Empty falls back to the configured translation backend’s model.
ai_quality_max_cues	30	How many cues are sampled per subtitle. Higher means a better judgement and a larger prompt.

Configure it under Settings → System → Subtitle Health.

Caution

Every check costs a model call. On a cloud backend that is billable, and on a local one it competes with translation for the same GPU. Raise ai_quality_max_cues deliberately — the cost scales with it.