§ 01 · Extension · One-Line Filed 2026.04.24 · Edition 01

VLSub.
Bazarr

A VLC 3.0+ Lua extension that proxies subtitle searches and downloads to a self-hosted Bazarr+ instance over its OpenSubtitles-compatible REST API. Configure subtitle providers once in Bazarr+; reuse them from every VLC on your LAN, no credentials pasted into the player.

§ 02

What / Architecture

One backend. Every media server.

Subtitle providers,
configured once.

The problem. VLC’s classic vlsub extension talks to a single subtitle site and expects your account credentials pasted into every VLC install. Swap to a different provider, manage your rate-limit budget, keep N machines in sync , it all snowballs on the client side.

Bazarr+ is a self-hosted subtitle orchestration service. It aggregates multiple subtitle providers behind a single endpoint, exposes them over an OpenSubtitles-compatible REST API at /api/v1/*, centralises credentials and rate-limit budgets, caches search results, and fans requests out in parallel with dedup and ranking. Every VLC on your LAN inherits every provider you’ve configured in Bazarr+, with zero extra setup on each machine.

This extension is the VLC side of that conversation. Point it at your Bazarr+ URL, paste its token, and every provider enabled in Bazarr+’s Settings → Subtitles Sources becomes one search away from inside VLC.

DATA FLOW per subtitle search

VLC 3.0+                    (player, user clicks Search)
   ↓  invokes extension
   ↓
VLSUB BAZARR+               (vlsubcom.lua in extensions/)
   ↓  GET /api/v1/subtitles?query=…&languages=…
   ↓  POST /api/v1/download  {file_id}
   ↓
BAZARR+                     (compat endpoint on :6767)
   ↓  parallel fan-out
   ↓
PROVIDERS                   subdl · Addic7ed · Podnapisi
                            Napiprojekt · SubDL …

API Surface: endpoints the extension calls from VLC
Method	Path	Purpose
POST	/api/v1/login	Handshake. Returns a JWT and a user object with quota info. Session cached on disk.
GET	/api/v1/infos/languages	Supported language list. Cached locally; only refetched on first run or after configuration change.
GET	/api/v1/utilities/guessit	Filename-to-metadata parse (title, season, episode) for hash-less name search.
GET	/api/v1/subtitles	Unified search across all enabled Bazarr+ providers. Returns candidates ranked by match strength.
POST	/api/v1/download	Resolves a result into a signed, short-lived stream URL plus remaining quota counters.
GET	/api/v1/download/stream/<tok>	Streams the SRT bytes back; VLC writes next to the video and auto-loads it.

§ 03

Install / One-Liner

Single command. All install types.

One line.
Linux, macOS, Windows.

Run in a terminal. The bash script detects every VLC install on the host (native, Flatpak, Snap) and drops the Lua file into each extensions dir. The PowerShell script handles the Windows %APPDATA%\vlc\lua\extensions\ path.

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

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

Copied. Paste into a terminal, then restart VLC.

§ 04

Install / Three Steps

T + 60 seconds

Step 01

Drop the Lua file

Run the one-liner from § 03, or copy vlsubcom.lua into your VLC extensions directory yourself. Native Linux: ~/.local/share/vlc/lua/extensions/. Flatpak: ~/.var/app/org.videolan.VLC/data/vlc/lua/extensions/. Snap: ~/snap/vlc/current/.local/share/vlc/lua/extensions/. macOS: ~/Library/Application Support/org.videolan.vlc/lua/extensions/. Windows: %APPDATA%\vlc\lua\extensions\.

curl | bash→all install types

Step 02

Restart VLC

VLC only scans for extensions at launch. Fully close every window and relaunch , for Flatpak, pkill -f vlc.bin first since closing the window may leave the process alive. Open the View menu; VLSub Bazarr+ now appears in the extension list.

Quit VLC→Reopen→View → VLSub Bazarr+

Step 03

Point at Bazarr+

Click ⚙️ Config inside the extension window. Paste your Bazarr+ Base URL , just scheme, host and port: http://host:6767. No path suffix. Then paste the API token from Bazarr+’s Settings → External Integration. Save. Login runs instantly and the session is cached on disk.

Config→Paste URL + Token→Save

§ 05

Requirements / Spec Sheet

Self-hosted. Homelab. LAN.

Req 01 · Host: VLC 3.0+ any-OSNative, Flatpak (org.videolan.VLC), and Snap (vlc) all work. The extension uses vlc.net.* APIs that are stable from 3.0 onwards. VLC 2.x is not supported.
Req 02 · Backend: Bazarr+ 2.2+ reachable over HTTP(S) LAN-okNeeds the External Integration endpoint enabled. Self-signed TLS is fine on a private network; VLC’s stream module will prompt once and remember.
Req 03 · Providers: At least one provider enabled in Bazarr+ Settings → Subtitles SourcesBazarr+ is the thing that actually talks to subdl / Addic7ed / Podnapisi / etc. If nothing is enabled there, searches return zero results.
Req 04 · Token: Bazarr+ API Token pasted into the extension configShown in Bazarr+ Settings → External Integration. The extension sends it as the Api-Key header on every request.

§ 06

Source & Related Projects

Plugin · Backend · Stack

§ 07

Troubleshooting

When the wire goes dark

401 UNAUTHORIZED

API token mismatch

The Bazarr+ token pasted into the extension doesn’t match the one in Bazarr+’s Settings → External Integration. Regenerate the token in Bazarr+, paste it back in Config, Save. The extension re-authenticates immediately.

405 METHOD NOT ALLOWED

Base URL is wrong

The Base URL is just scheme, host, and port: http://host:6767. No path suffix. If login 405s, the extension hit a route that doesn’t exist because the URL already included a path.

503 AT STREAM

Upstream provider fetch failed

Search returned results but /download/stream/… returned 503. That’s Bazarr+’s upstream provider call failing: missing credentials, rate-limited, or the provider itself is down. Check Bazarr+ logs (x-reason: upstream header) for the real error.

200 EMPTY RESULTS

No providers enabled

Searches succeed but return zero subtitles. Almost always means Bazarr+ has no providers enabled. Open Bazarr+’s Settings → Subtitles Sources and enable at least one (subdl, Podnapisi, Addic7ed, etc.); a background re-index may be needed before results flow.

UI FROZEN AT SAVE

Worst case is 5 seconds

VLC dialogs are single-threaded. If Save wedges for more than 5 s, the extension is running an older in-memory copy of the Lua file. Kill VLC hard (pkill -f vlc.bin for Flatpak) and relaunch , VLC only picks up Lua changes at process start.

VIEW NO VLSUB BAZARR+ ENTRY

Extensions directory mismatch

Each VLC install type reads a different directory. Flatpak uses ~/.var/app/org.videolan.VLC/data/vlc/lua/extensions/, Snap uses ~/snap/vlc/current/.local/share/vlc/lua/extensions/. The install script covers both; a manual copy to the wrong dir is silent.

LOG LIVE DEBUG

Capture [VLSub] lines

Launch VLC with --verbose=2 --file-logging --logfile=… and grep \[VLSub\] in the output. Every outbound URL is logged at WARN, and every parse failure at ERROR , enough to triage 302 / 401 / 404 / 503 against this table.

VLSub.Ba­zarr+

Subtitle providers,configured once.

One line.Linux, macOS, Windows.