Settings — Providers

This page is the provider control surface: 29 built-in provider adapters, 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 (29)

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

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 since 1.14.2

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 from before 1.14.2 carry non-numeric ids and 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
Subliminal TVSubtitles	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.

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. Multi-key pool for providers that support rotation.
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.

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.