# Subtitlarr

Subtitlarr is a self-hosted companion for Bazarr that translates existing subtitles into missing languages using a local or cloud large language model. It is open source and self-hosted, installable on Unraid.

Canonical page: https://ourlocalhost.com/app/3361/subtitlarr

## Description

Subtitlarr is a self-hosted companion for Bazarr that translates existing subtitles into missing languages using a local or cloud large language model. It polls Bazarr's wanted-subtitle list, checks for preferred source subtitles, and writes translated subtitles through Bazarr's API without mounting your media folders.

## Platform availability

Available on 1 of 10 platforms: Unraid.

## Health score

55/100 (Fair), based on 3 of 4 factors.
- Maintained: 91 (last commit 18 days ago)
- Popular: 12 (3 GitHub stars)
- Easy to install: 35 (1 install platform, install notes, Docker image)

## Links

- Unraid: https://ca.unraid.net/apps/subtitlarr-0ejd54j1xpuckv?q=Subtitlarr
- Documentation: https://gerardumbert.github.io/Subtitlarr

## Common questions

### How do I set the initial password or recover access if I am locked out of Subtitlarr?

Use the seeded admin/admin account on first start and set a real password. If you are locked out, run subtitlarr --reset-admin from the container console.

### Which volume should I persist and back up for Subtitlarr?

Map only the /data volume, which holds its SQLite database. Do not mount media folders because subtitle reads and writes go through Bazarr's API.

### How does Subtitlarr handle multiple translation engines and failures?

You build an ordered cascade of local or cloud engine instances, and Subtitlarr tries the next one if an engine rate-limits, errors, or has blocked output. An engine with three consecutive failures gets a 24-hour cooldown and is skipped until it clears or you clear it manually.

### Will Subtitlarr create subtitles when none already exist?

No, it only translates an existing subtitle in one of your preferred source languages. Items with no subtitle in any language are skipped, because finding or downloading subtitles is Bazarr's job.

### Can Subtitlarr fix subtitles that are already out of sync?

No, translation is text-only and reuses the source subtitle's original timestamps. If a subtitle is out of sync before translation, it stays out of sync after.

### What happens if the LLM returns well-formed text in the wrong language?

Subtitlarr's structural checks may not catch a well-formed but wrong response. The Jobs page Language Check audits recently completed items against their detected output language and resets mismatches to pending for a real retry.

---
Source: Our Local Host (https://ourlocalhost.com/app/3361/subtitlarr), the self-hosted and open-source app directory.
