Subtitle Repair

A bug in Sublarr before v1.6.6 deleted ordinary words from non-English subtitles during hearing-impaired cleanup (issue #156). The words are gone from the damaged files, so they cannot be fixed in place — Subtitle Repair brings the pristine original back and re-applies your timings. Available since v1.9.1 under Settings → System → Subtitle repair.

Note

Only subtitles downloaded while HI removal was enabled are affected. Everything downloaded on v1.6.6 or later is clean. If you never enabled HI removal in auto-processing, there is nothing to repair.

Scan first — it’s free

The scan compares each tracked sidecar against the hash recorded when it was downloaded and checks whether a provably clean .bak exists. Nothing is fetched from any provider.

Scan result	Meaning
Damaged	The processing pipeline rewrote this file after download. Includes harmless rewrites (quote normalisation, timing sync) — whether words are actually missing is only knowable by fetching the original.
From backup (free)	A .bak exists that provably is the pristine original. Repairing these costs no provider quota.
Needs a re-download	The original must be re-fetched from the provider it came from.
Already repaired	Recorded from an earlier run — repaired or confirmed intact — and skipped.

How a repair is proven

Nothing is overwritten on a hunch. For every file, the repair:

1. Fetches the exact original — by the provider file id stored at download time, never by searching again. A pristine .bak is preferred where one survived.
2. Replays the old buggy pipeline over that original. The result must reproduce the file on your disk byte-exact. That proves both that it is the right original and that nobody hand-edited the file since. Because the pipeline was configurable per series, every variant that was possible is tried.
3. Transplants the pristine text onto your timings. The damage was purely textual, and your files may have been synced against the video since — the on-disk timings win. Cues the old pipeline deleted entirely are rebuilt from a time model fitted to the surviving cues. Nothing is re-synced.

If the replay cannot reproduce the file, it is reported as unprovable and left untouched: a failed replay cannot distinguish “you edited this file” from “the provider changed the file”, and the tool does not guess.

Files the pipeline touched but never damaged (only quotes normalised or timings synced) are recorded as intact and never fetched again.

Runs and quota

Every checked file that has no clean .bak costs one provider download against the daily allowance (e.g. 1,000/day on OpenSubtitles for VIP accounts).

Run type	Cost	Persists
Dry run	One download per checked file, capped by the Limit field (default 25)	Nothing — whatever it checks, a later run downloads again
Repair	One download per candidate	Everything: repaired files, intact files, progress

A real repair run over a large library usually exceeds one day’s allowance. When the quota runs out, the run stops cleanly, records its progress, and schedules itself for the moment the provider’s allowance resets — the panel shows the exact time. It continues unattended, across container restarts, until everything is done. Nothing is downloaded twice.

Caution

The dry run exists to preview what a repair would do — keep its limit small. It spends the same quota as a real run but saves none of its findings.

Status fields

Field	Meaning
Restored	Files repaired (words brought back, timings kept).
From backup	Restored from a .bak at zero quota cost.
Unprovable	Replay could not reproduce the file — left untouched.
Failed	Fetch or write error; the file is retried on the next run.

API

Endpoint	Effect
GET /api/v1/repair/scan?language=de	Scan report, optionally restricted to one language. Free.
POST /api/v1/repair/run	Start a pass. Body: {"language": "de", "dry_run": false, "limit": 25} — language and limit optional.
GET /api/v1/repair/status	Progress of the running (or last) pass, including the auto-resume time.