External Integration (Jellyfin & VLSub) v2.2

Bazarr+ v2.2 (Synapse) ships an OpenSubtitles-compatible REST endpoint that lets external clients query your Bazarr+ instance as a federated subtitle service. Two first-party clients ship alongside it: a Jellyfin plugin and a VLC extension.

Moved in v2.4. The endpoint and its tokens now live in the Distribution Hub. The old Settings > External Integration page has been removed, and /settings/external redirects to /distribution-hub. Existing clients keep working without changes: your old shared token was auto-seeded as an "Unlimited Default" Distribution Hub key. To enable the endpoint, use the Distribution Hub Settings tab; to create or reveal tokens, use the API Keys tab. You can now hand each client its own named key with its own tier and provider scope.

What is External Integration

Bazarr+ already searches and downloads subtitles from your configured providers (OpenSubtitles.com, OpenSubtitles.org (native Provider Hub plugin), Subscene, Addic7ed, and many more) according to your priority order, your hashes, your language profiles, and your filters.

External Integration exposes that pipeline over a stable REST API at /api/v1/*. Any client that speaks the OpenSubtitles wire format can talk to Bazarr+ and use your provider configuration. No provider keys leave your server, no rate limit gets shared with the public OpenSubtitles API.

Two first-party clients are published and ready to use:

  • Jellyfin plugin: Bazarr+ Subtitles — subtitle search and download from inside Jellyfin 10.11+, served by your Bazarr+ providers.
  • VLSub Bazarr+ — VLC 3.0+ Lua extension. Hash-based and title-based search inside VLC; downloads load straight into the current playback.
What it is not. External Integration is not a way to share your library publicly. The endpoint is bearer-token authenticated, rate-limited per token, and SSRF-guarded. Only clients that have your token can search.

Enabling the endpoint in Bazarr+

  1. In Bazarr+, open the Distribution Hub from the main menu and go to the Settings tab.
  2. Toggle Enable on (and accept the consent prompt). Bazarr+ generates the JWT and HMAC secrets on first enable.
  3. If a restart-required banner appears, click Restart Bazarr+ so the /api/v1 endpoint mounts.
  4. Switch to the API Keys tab. Create a named key per client (the token is shown once, copy it immediately), or use Reveal token on the legacy "Unlimited Default" key to recover the shared token. You will paste this into the Jellyfin plugin and the VLSub configuration.
One key per client. Instead of sharing a single token, give each client its own named key in the API Keys tab. Each key carries its own tier (rate limits and per-window metering) and its own allowed/excluded provider list, so you can scope a client to a subset of your providers. See the Distribution Hub guide for tiers, metering, and provider scoping.
Treat the token like a password. Anyone who has the token can search and download via your Bazarr+ instance. Don't paste it into chat threads, public configs, or screenshots. Rotate it (next section) if you ever suspect it leaked.

Rotating or revoking the token

In the Distribution Hub API Keys tab, each key has a rotate action that mints a fresh token and revokes the previous one immediately. (For the legacy "Unlimited Default" key, the inline regenerate flow does the same and reveals the new shared token.) Old clients will start getting 401s and need the new token pasted in. Use this when:

  • The token has been exposed (committed to a repo, posted in a screenshot, sent over an unencrypted channel).
  • You are decommissioning a client and want to make sure it can't talk to Bazarr+ any more.
  • You just want to rotate periodically as good hygiene.

The signed download tokens (which are minted per /api/v1/download and used to fetch subtitle bytes) are tied to the JWT they were issued under. Regenerating invalidates outstanding download URLs as well.

Installing the Jellyfin plugin

The recommended path is the plugin repository. Jellyfin can install and update from a manifest URL.

  1. In Jellyfin, go to Dashboard > Plugins > Repositories and click the + button.
  2. Add a repository:
    • Name: Bazarr+ Subtitles
    • URL: https://LavX.github.io/jellyfin-plugin-bazarr-plus/manifest.json
  3. Open the Catalog tab. Under Subtitles, find Bazarr+ Subtitles and click Install.
  4. Restart Jellyfin when prompted.
  5. Go to Dashboard > Plugins > My Plugins > Bazarr+ Subtitles > Settings.
  6. Fill in:
    • Bazarr+ URL: e.g. https://bazarr.example.com or http://bazarr.local:6767.
    • Bazarr+ API Token: paste a token from the Distribution Hub API Keys tab (a named key for this client, or the legacy Default key via Reveal token).
  7. Save.
  8. Enable the provider per library at Dashboard > Libraries > [your library] > Subtitle Downloaders.
  9. Scan a library or click Find Subtitles on an item to verify end to end.

Manual install (downloading the release ZIP and dropping it into Jellyfin's plugins/ directory) and build-from-source instructions are in the plugin README.

Installing VLSub Bazarr+

VLSub Bazarr+ is a single Lua extension file plus a small library tree. The provided installer scripts handle both native VLC installs and Flatpak/Snap setups across Linux, macOS, and Windows.

Linux and macOS

Shell 
curl -sSL https://raw.githubusercontent.com/LavX/vlsub-bazarr-plus/main/scripts/install.sh | bash

Windows

PowerShell 
iwr -useb https://raw.githubusercontent.com/LavX/vlsub-bazarr-plus/main/scripts/install.ps1 | iex

Configure VLSub

  1. Restart VLC after install so the new extension is picked up.
  2. In VLC, open View > VLSub Bazarr+.
  3. Click Config in the extension window.
  4. Fill in:
    • Bazarr+ URL: e.g. http://bazarr.local:6767.
    • API Token: paste a token from the Distribution Hub API Keys tab.
    • Languages: pick up to three.
  5. Save and close. From now on, View > VLSub Bazarr+ while a video is playing searches by hash first, then by title, and downloads the chosen result next to the video file.

The full installer detects native, Flatpak, and Snap VLC installations and writes to the right location for each. Manual install steps are in the VLSub Bazarr+ README.

How the pipeline works

When a Jellyfin or VLSub client searches:

  1. The client calls /api/v1/subtitles on Bazarr+ with an IMDB id (or a title + season/episode + language).
  2. Bazarr+ runs your configured providers in parallel, with a bounded thread pool and dogpile coalescing so identical concurrent searches share a single backend call.
  3. The compat layer normalizes provider responses into the OpenSubtitles wire format the client expects, with download counts, ratings, FPS, HD flag, hash-match indicator, and language metadata.
  4. When the user picks a result, the client calls /api/v1/download. Bazarr+ returns a one-shot HMAC-signed stream URL with a TTL.
  5. The client follows the stream URL. Bazarr+ validates the token and rate-limits per JWT before serving the bytes.

For TVDB-keyed providers like Gestdown, Bazarr+ hydrates season/episode and TVDB series id from an IMDB id so they "just work". The OMDB refiner (broken since the Python 3 migration upstream) is also revived and can be enabled with a free OMDB API key. As of v2.4, OMDB is offered as a selectable Provider Hub integration (alongside entries like AniDB).

Security notes

  • Bearer-token auth with jti revocation. Logout immediately revokes the active JWT.
  • Rate limited per token with a sliding window on /api/v1/download, so a misbehaving client cannot eat the whole pool.
  • Signed download tokens with a TTL. The client never sees raw provider URLs.
  • SSRF guard with DNS rebinding protection on every outbound URL the compat layer touches. Loopback, RFC1918, and link-local addresses are blocked, and any IP that fails revalidation post-DNS resolution is refused.
  • Encryption at rest for the compat endpoint secrets and every other sensitive credential (provider keys, Sonarr/Radarr keys, Plex token, OpenRouter key). See the v2.2 release notes for the full list.

Troubleshooting

Jellyfin shows "Bazarr+ Subtitles" in the catalog as 404. The plugin manifest is published from the plugin repo. If you see a 404, no plugin release has been published yet for your Jellyfin version. Use the manual install path in the plugin README.

Plugin returns 401 from Bazarr+. The API token is wrong or has been rotated. Copy the current token from the Distribution Hub > API Keys tab (a named key, or the Default key via Reveal token) and paste it again into the plugin settings.

VLSub finds nothing for hash searches. Hash-based search only works if at least one of your enabled providers supports the file's hash. Try a title-based search as a fallback (VLSub auto-falls back when hash search returns empty).

The "Distribution Hub" menu item is missing. You're on a build older than v2.4. On v2.2 and v2.3 the toggle lives under Settings > External Integration instead; on anything older than v2.2.0 the endpoint does not exist. Pull ghcr.io/lavx/bazarr:latest and restart to get the Distribution Hub.

Next steps