Architecture at a glance
Sublarr sits as a webhook receiver between Sonarr/Radarr and your subtitle source. On every import the *arr webhook triggers a search; Sublarr queries 28 provider adapters in parallel, scores the hits, downloads the best match and stores it as a sidecar file next to the media. Sublarr then triggers a targeted refresh on the media server: Jellyfin and Emby re-read the item, Plex scans only the episode's or film's folder.
Supported integrations
| Service | Connection | Notes |
|---|---|---|
| Sonarr | Webhook (On Import / On Upgrade) | Multi-instance, tag-based profiles |
| Radarr | Webhook (On Import / On Upgrade) | Multi-instance, tag-based profiles |
| Jellyfin | Library scan via API | Sidecar detection, refresh trigger |
| Emby | Library scan via API | Sidecar detection, refresh trigger |
| Plex | Partial scan via API | Scans only the episode's or film's folder |
| Kodi | JSON-RPC | Scan of the affected folder |
| Shoko Server | Rescan via API | Picks up the file's new subtitles, supplies AniDB episode data |
| AniDB | Episode mapping | Absolute ↔ season/episode numbers |
| Webhooks (out) | HTTP POST after download | Discord, Gotify, custom |
Sonarr & Radarr — webhook setup
In Sonarr/Radarr go to Settings → Connect → +Add → Webhook and create an entry. URL: http://<sublarr-host>:5765/api/v1/webhook/sonarr or /radarr. Triggers: On Import and On Upgrade. Sublarr receives episode/movie IDs, paths and tags and triggers a subtitle search immediately — no polling, no delay.
Multi-instance & tag-based profiles
You can register multiple Sonarr or Radarr instances in Sublarr — ideal for setups with separate stacks for anime, movies or documentaries. Each instance is wired to tag mappings: a tag in Sonarr selects the language profile in Sublarr. Example configuration:
| Sonarr tag | Languages | Format preference | Translation backend |
|---|---|---|---|
| anime | DE + EN | Prefer ASS | Optional (Ollama / DeepL) |
| movies | DE | Prefer SRT | DeepL |
| docu | DE + EN | Prefer SRT | DeepL |
| kids | DE | SRT, hardcoded ok | MyMemory (fallback) |
This way every library gets exactly the subtitles that fit its workflow — without global settings that are always wrong for half of your media collection.
Media servers — targeted refresh
As soon as Sublarr has placed a subtitle file, it calls the Jellyfin or Emby API to trigger a targeted library refresh for the affected item. You don't need cron scans — the new subtitle track shows up in the UI within seconds. Plex gets a scan of just the folder the episode or film lives in; Kodi and Shoko are triggered just as precisely. If the media server sees the files under other paths than Sublarr, the path mapping translates them — with several pairs separated by ; when each library lives under its own root; the longest matching pair wins. If Sublarr still can't find the item, the server scans the library as a fallback.
AniDB mapping for anime
Anime subtitle providers often work with absolute episode numbers (episode 137 instead of S07E12). Sublarr queries AniDB for every anime title and translates between Sonarr season/episode and AniDB absolute number transparently — you don't need to maintain anything manually. Special cases like splits (e.g. "Naruto Shippuden" as a separate series instead of a season continuation) are resolved automatically via AniDB IDs.
Detailed setups in the Integrations docs.