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	none
Subf2m	broad	none
YIFYSubtitles	movies	none
BetaSeries	French / EU	optional
Titlovi	Balkan languages	none

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.
Test	Round-trips a known query; reports auth + reachability.
Health stats	Success rate, last response time, average response time, consecutive failures, auto-disable status.
Cache	Per-provider cached search results count + clear button.
Stats	Lifetime downloads.

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

New in 1.10.0. 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.