Settings — Providers

This page is the provider control surface: 28 built-in provider adapters, the opt-in catalog sources, marketplace plugins, and transcription engines as a last-resort fallback. Each row is one provider with health, credentials, priority, and rate-limit state.

Provider list shape

Each provider row shows:

Column	Effect
Name + badge	Provider name; badge for Free / API Key / Login.
Status	enabled / disabled / auto-disabled / not configured.
Priority	Numeric rank in the search order. Lower = tried first.
Health	Recent success rate over the last 200 calls.
Last response	Average latency.
Downloads	Successful subtitle downloads from this provider, lifetime.

Click a row to open the editor panel — credentials, priority drag handle, test button, cache controls.

Built-in adapters (28)

Tier 1 — most users start here

Provider	Type	Account	Best for
OpenSubtitles	API key	required (free tier)	Largest dataset; reliable backbone of any setup.
Jimaku	API key	required (free)	Anime — direct partnership with translator groups.
SubDL	API key	required (free)	Curated, fast, strong on anime.
AnimeTosho	none	none	Aggregator of anime fansub releases.
SubsDump	none	none	Additional subtitle dump source.

Tier 2 — language and niche

Provider	Languages	Account
Podnapisi	Slavic + EU	none
Kitsunekko	Japanese (ASS)	none
Napisy24	Polish	none
Titrari	Romanian	none
LegendasDivx	Portuguese (PT)	required
Addic7ed	TV series specialist	optional
Gestdown	Spanish	none
TVSubtitles	TV series multi-lang	none — tvsubtitles.net no longer resolves; keep it disabled

Tier 3 — Asian / East European

Provider	Languages	Account
Zimuku	Chinese	none
Turkcealtyazi	Turkish	required
SubSource	broad	API key
Subf2m	broad	none
YIFYSubtitles	movies	none
BetaSeries	French / EU	optional
Titlovi	Balkan languages	required

SubSource needs an API key

SubSource moved to its documented authenticated API. The key is generated in your SubSource account under My Profile, not on the API documentation page (the API reference only describes the endpoints). Save it under Settings > Providers > SubSource. Without a key the provider reports API key not configured and every search fails outright rather than returning an empty result.

Key generation was observed to be unavailable on 2026-09-15. If your profile does not hand out a key, that is on SubSource’s side and there is nothing to configure here — leave the provider disabled until it works.

SubScene is a different provider — enabling one does not enable the other. Saved SubSource results with non-numeric ids need a fresh search before they can be downloaded again.

Tier 4 — local and alternate adapters

Provider	Type	Account
Embedded	local track extractor	none
Custom HTTP/JSON	your own server (see below)	optional
Subliminal OpenSubtitles	alternate adapter	provider account if required
Subliminal OpenSubtitles.com	alternate adapter	provider account if required
Subliminal Addic7ed	alternate adapter	optional
Subliminal Gestdown	alternate adapter	none
Subliminal NapiProjekt	alternate adapter	none
Subliminal Podnapisi	alternate adapter	none

Transcription fallback

Provider	Type	Local	Account
Whisper (built-in)	transcription	yes	none
WhisperAI (OpenAI)	transcription	no	required
Subgen	transcription	yes (separate service)	optional

Transcription engines are computational, not search-based, so use them only when no real subtitle exists. Configure them under Settings → Providers → Transcription.

Catalog providers (Bazarr+)

On top of the built-in adapters, Sublarr ships 43 catalog sources taken over from the Bazarr+ Provider Hub catalog. They are off by default. To use them, switch on Catalog providers (Bazarr+) under Global provider settings on this page; the sources then appear in the provider list, and each one still has to be enabled on its own. Switching the catalog off again removes them from the search at once.

The code is a reviewed, pinned copy of the catalog (LavX/bazarr-provider-catalog, MIT), not a download at runtime: every file is checked against the SHA-256 recorded in its manifest before it is loaded, and an edited file is refused. Catalog sources that need the cloudscraper/Js2Py stack are not included, nor those that duplicate an adapter Sublarr already has.

Source	Languages	Account
AnimeKalesi	Turkish (anime)	none
AnimeSub.info	Polish (anime)	none
Assrt	Chinese, English	API token
AvistaZ	broad	session cookies (see below)
BollyNook	broad	none
BSPlayer	23 languages	none
CinemaZ	broad	session cookies (see below)
Fansubs.ru	Russian	none
GreekSubs	Greek	none
GreekSubtitles	Greek, English	none
HDBits	broad	username + passkey
iSubtitles	broad	none
Karagarga	English	username + password
Ktuvit	Hebrew	email + hashed password
Legendas.net	Portuguese (BR)	username + password
Moviesubtitles	13 languages	none
My-Subs	broad	none
Nekur	Latvian	none
Pipocas.tv	Portuguese, English, Spanish	username + password
Prijevodi-Online	Croatian, Bosnian, Serbian, Macedonian	optional
RegieLive	Romanian	none
Shooter	Chinese, English	none
Sous-Titres.eu	French, English	none
SubCentral.de	German, English	none
Subclub	Estonian	none
SubHD	Chinese and 14 more	none
Subs4Free	Greek, English	none
Subsarr	broad	your own Subsarr server (base URL)
Subs.ro	Romanian, English	API key
SubsSabBz	Bulgarian, English	none
SubsUnacs	Bulgarian, English	none
SubSynchro	French	none
Subtis	Spanish	none
SubtitleCat	broad	none
SubtitleStar	Persian	none
Subtitrari Noi	Romanian	none
Subtitri.id	Latvian	none
SubtitulamosTV	Spanish, Catalan, English	none
SubX	Spanish	API key
SuperSubtitles	Hungarian, English	none
Titulky.com	Czech, Slovak	username + password
TsukiHime	broad (anime)	none
Vladoon	Bulgarian	none

A few sources search by details the wanted search has to fetch for them:

• AvistaZ and CinemaZ need your tracker session cookies and only read the release page a file was grabbed from. Sublarr takes that page from the Sonarr/Radarr history, so they only find subtitles for files grabbed from those trackers. The history is read only while one of the two is enabled, at most once an hour per episode or movie.
• TsukiHime searches episodes by AniDB episode id and number, which only Shoko supplies — without Shoko it finds no episodes. A movie is only searched when the search carries an AniList id (from the API); Radarr has none.
• SubsSabBz, SubsUnacs and Titulky.com check the frame rate of a result; Sublarr passes the file’s frame rate from Sonarr/Radarr.

Every catalog result goes through the same season/episode check, scoring and decision log as the built-in adapters.

Per-provider edit panel

Clicking a provider opens an inline editor with:

Section	What’s there
Enabled toggle	On / off without losing config.
Credentials	API key / username / password where applicable. Text and password fields save once — when you leave the field or press Enter, not while you type; yes/no settings are checkboxes and settings with a fixed set of values are dropdowns. Optional Key pool for providers that support rotation, see Key pool. Once that list has an entry, searches use the keys from it and ignore the single credential field above; a note under the field says so.
Excluded languages	Languages this provider must never be asked for, and never serve. See Excluding a language from one provider.
Test	Round-trips a known query; reports auth + reachability. See Testing a provider for the download variant.
Health stats	Success rate, last response time, average response time, consecutive failures, auto-disable status, and the times of the last search and the last successful download — recorded separately, see below.
Cache	Per-provider cached search results count + clear button.
Stats	Lifetime downloads.

Key pool

The Key pool (optional) section holds several keys that Sublarr rotates through, for example when one reaches its daily limit. It is an addition to the API Key field, not a second heading for the same thing: as soon as a key is listed in the pool, the API Key field no longer applies. With an empty pool the API Key field applies.

Add key opens a dialog with Label, API key and Enabled, plus a Test connection button. The other fields appear only where the provider has them:

Field	Shown for
Tier	OpenSubtitles
Username and Password (both optional)	OpenSubtitles, LegendasDivx, Turkcealtyazi

Deleting the last key of a provider that needs one disables that provider. A passing Test also clears an old failure streak, so a provider no longer shows “N consecutive failures” next to “Test: OK” for searches that ran before its key was set.

Provider notes

Behaviour worth knowing for individual providers (1.20.0):

Provider	Behaviour
Jimaku	Results are limited to the series’ entries for the queried season and to files of the queried episode, and carry their episode and season match (before, a name search returned every season and every file of every episode). When the full title finds nothing, Sonarr’s alternative titles and the main title are tried. Language tags such as [JPN], [ENG] and .ja are read; a file tagged with two languages counts as unmarked. Setting Language for unmarked files: ja (default; unmarked files are read as Japanese), en (read as English) or none (skip them).
AnimeTosho	Setting Torrent-level attachments: on (default) or off. Multi-sub releases carry their subtitles on the torrent instead of on one of its files; with this on they are used when the torrent title names the episode. A season-pack search can take up to 30 s: a late answer is kept for six hours, the next search for the same episode uses it, and the scheduler searches the episode again on its next pass. Without an AniDB episode id, when the search for “Show 05” finds nothing, the season is asked for next, so BD packs of older seasons are found. Release names may use any of Sonarr’s alternative titles.
Gestdown	The subtitle request now sends the language code (en) instead of Addic7ed’s numeric ids, which the API answered with 404 for every language.
BetaSeries	Episodes are looked up first, then their subtitles are fetched by episode id. BetaSeries has no movie subtitles.
Napisy24	Follows the documented protocol: the API’s “no subtitle” answers are no longer taken for hits, and the subtitle is read from the answer itself.
OpenSubtitles	Episode searches send the series as parent_imdb_id; VIP accounts use the host their login names; a download that uses up the daily quota stops further downloads until the reset without another request; files from trusted sources count as trusted.

Since 1.19.0, credentials entered for several providers take effect as soon as they are saved, a provider can be set to “No providers” (all off) without falling back to all, and a provider that answers after the search timeout (AnimeTosho at times takes 20 to 30 s) is no longer missing from the next searches for the same episode.

Excluding a language from one provider

Two providers can both serve a language while one of them does it badly. Rather than turning the weaker provider off entirely — and losing the languages it is good at — you can exclude that one language from it.

Open the provider, pick the languages under Excluded languages, and save. From then on:

• the provider is never asked for an excluded language, and
• a result in an excluded language is dropped even if the provider returns one anyway, which some do regardless of what was requested.

If every language a search asks for is excluded for a provider, that provider is skipped for the search entirely and says so in the decision log — you will find it under Why a provider is being skipped rather than silently absent.

Exclusions are per provider, not global: excluding Serbian from OpenSubtitles has no effect on Titlovi, which is usually the point of setting one.

Note

Changing an exclusion takes effect on the next search. Results already cached from before the change are not reused, so you do not have to clear the cache by hand.

Testing a provider

Test runs a search and reports whether the provider answered and accepted your credentials. That is not the whole story: search and download often use different credentials, so a provider can pass every search while its download path is dead.

Test download is the companion action. It fetches one real subtitle and throws it away, which is the only way to prove the download path works. It is a separate button rather than part of every test because a download spends one unit of the account’s daily allowance.

Both buttons probe with the first item from your wanted list, and the query is built by the same code the scheduled search uses — metadata enrichment and AniDB resolution included. That matters for providers that match through an AniDB id rather than a title, AnimeTosho above all: they are asked the same question the real search asks them, so a no-result from the button means the provider genuinely had nothing for that episode.

Note

If your wanted list is empty there is nothing to probe with, and the test reports only reachability and authentication — it cannot exercise search or download without something to search for.

Why a provider is being skipped

A provider can answer, pass its health check, and still take part in no search at all — because something upstream of the request is holding it back. The Providers page names that gate instead of showing the provider as healthy.

Gate	What it means	Where to fix it
auto_disabled	Hard-disabled after persistent failures.	Clear the failure cause, then wait out Auto-disable cooldown or re-enable the provider.
circuit_open	The circuit breaker tripped.	It retries on its own after the cooldown; see Circuit Breaker.
rate_limited	Throttled after hitting the provider’s quota.	Wait, or raise Provider delay so you stop tripping it.
budget_exhausted	The request budget for this provider is used up.	Budget settings below, or wait for the window to roll over.
no_pool_key	The provider needs a credential and the key pool has no usable row.	Add or repair credentials in the edit panel.
languages_excluded	Every language this search asked for is excluded for this provider.	Excluded languages in the edit panel.
not_initialised	The adapter never started — usually missing configuration.	Check the credentials and re-enable.
ok	Nothing is blocking it.	—

The order matters: a provider can sit behind several gates at once, and the one named is the one the search path hits first, so fixing it is what actually changes the outcome.

Degradation alerts

A provider that quietly stops working looks exactly like a library with nothing left to find — the wanted queue simply stops moving. Provider degradation alerts (off by default) watch for that and notify once per provider per day through your configured notification channels.

Two conditions fire:

• auto_disabled — the provider was hard-disabled after repeated failures.
• downloads_stopped — the provider is still searching and has downloads in its history, but none has succeeded for 24 hours. That combination is the signature of a dead download credential while search still works.

The second condition is deliberately narrow. On a healthy install most providers legitimately never download, because they lose the scoring race — alerting on “no downloads” alone would bury the one provider that genuinely broke. A provider that has not searched for 6 hours is not reported here either: nothing is reaching it at all, which is a different fault.

Provider priority

Drag rows in the list to reorder. Lower index = tried earlier. The default ordering favors big-dataset providers (OpenSubtitles, Jimaku, SubDL) with niche providers as fall-throughs.

Setting	Default	Values	Effect
Auto-prioritise providers	on	toggle	Re-rank dynamically based on recent success rate. Manual order still respected as the seed.
Provider delay (ms)	0	0–5000	Sleep between consecutive calls to the same provider. Some throttle aggressively per-IP.

Rate limiting and circuit breaker

Sublarr protects upstream providers with a circuit breaker per provider:

Setting	Default	Values	Effect
Rate limiting enabled	on	toggle	Honor per-provider quotas declared in the provider config.
Circuit-breaker threshold	5	1–20	Consecutive failures before opening the breaker.
Circuit-breaker cooldown (s)	300	10+	How long the breaker stays open before retrying.
Auto-disable cooldown (min)	30	1–10080	Hard auto-disable after persistent failures (separate from breaker).

See Circuit Breaker for the full state-machine reference.

Cache

Setting	Default	Values	Effect
Cache TTL (min)	5	1–1440	Per-provider search-result cache lifetime.
Per-provider cache count	shown in row	n/a	Click row’s cache section → Clear to drop.
Clear all caches	header button	n/a	Drops every provider’s cache.

Concurrent searches

Setting	Default	Values	Effect
Max concurrent provider searches	3	1–10	Global cap on parallel provider calls.
Per-provider concurrency	varies	per-provider override	Some providers handle higher parallelism; others throttle.
Search timeout (s)	30	5–300	Global fallback timeout when a provider doesn’t declare its own.

Custom HTTP/JSON provider

Connect a private subtitle server — or adapt an existing REST API — without writing a plugin. The provider speaks a small documented search/download contract and is configured entirely through settings; no third-party code is executed.

Setting	Config key	Default	Effect
Base URL	customapi_base_url	(empty)	Root of your server. http/https only. Leave empty to keep the provider inactive.
Search path	customapi_search_path	/search	Appended to the base URL for searches.
Download path	customapi_download_path	/download/{id}	Appended for downloads; {id} is substituted per result.
Results path	customapi_results_path	results	Dot-notation path to the result array inside the JSON response.
Field map	customapi_field_map	(empty)	JSON object mapping Sublarr’s result fields to paths in your response. Only needed when your API uses different field names.
API key	customapi_api_key	(empty)	Sent as a header when set.
API key header	customapi_api_key_header	X-API-Key	Header name carrying the key.
Extra params	customapi_extra_params	(empty)	JSON object of additional query parameters sent on every search.
Instances	customapi_instances_json	(empty)	JSON array of further independent instances — each with its own stats, health state and circuit breaker.

Multiple instances register as customapi-<name> and behave like separate providers throughout the UI.

Note

Because you choose the URL, the download-domain allowlist that constrains the public providers does not apply here. The usual protections remain: only http/https are accepted, and cloud metadata endpoints, link-local and loopback addresses stay blocked. Ordinary LAN addresses are permitted — that is the point of a self-hosted provider.

The full request/response contract, including the field-map syntax and worked examples, lives in docs/CUSTOM_PROVIDER_API.md in the Sublarr repository.

Marketplace

The Marketplace tab on this page opens the Plugin Marketplace — install community-maintained providers from a curated list or sideload your own ZIPs.

Hidden providers

If you’ve added a provider you don’t want shown in the search but you don’t want to delete (preserving config + history), hide it:

Setting	Effect
Hidden providers	Comma-separated provider names. Hidden providers don’t appear in search dropdowns or in the priority list.

Useful for providers tied to obsolete accounts that you might re-activate later.

Reranking

After the initial provider list comes back, Sublarr can apply a re-ranking pass using extra signals (download counts, age, reviewer ratings). Configurable on this page:

Setting	Default	Values	Effect
Provider reranking	off	toggle	Master switch for the rerank pass.
Min downloads for boost	20	0–10000	Candidates with fewer downloads don’t get the recency boost.
Max modifier	50	0–100	Absolute score modifier cap.

Maximum subtitle file size

Setting	Default	Values	Effect
Max subtitle size (KB)	2048	100–10240	Reject subtitles above this size. Protects against malicious uploads and bandwidth abuse.