Skip to content
Go back

Bazarr + Whisper: Subtitles on Autopilot

By KingPin 15 min read
Bazarr + Whisper: Subtitles on Autopilot
Contents

Movie Night, Zero Subtitles

You grabbed an obscure 2009 documentary, hit play, and the dialogue is a mumble in a language you do not speak. No subtitle file. You open a browser, search three sites, download a .srt that is 40 seconds out of sync, and give up halfway through. Meanwhile your Sonarr and Radarr libraries hold thousands of files that will each need the same treatment someday.

Bazarr does this chore for you. It watches your *arr libraries, asks subtitle providers for matching files, and drops the .srt next to the media. Providers should be your first choice. For the files no provider has (home video, odd releases, foreign content with no community subs), Bazarr can ask a self-hosted Whisper container to transcribe the audio instead.

My verdict: providers first, Whisper as the fallback. Providers are fast and human-made. Whisper is slow, needs real hardware, and can only translate into English. Together they cover almost everything without breaking a sweat.

This post assumes your *arr stack already runs. Jellyfin and Plex both pick up the .srt files Bazarr writes next to your media, so there is nothing to configure on the player side beyond a library rescan.

The Compose File

Bazarr ships as a linuxserver.io image, port 6767. The Whisper side is onerahmet/openai-whisper-asr-webservice, port 9000. As of November 2026, the latest Bazarr release is v1.6.2.

docker-compose.yml
services:
bazarr:
image: lscr.io/linuxserver/bazarr:latest
container_name: bazarr
environment:
- PUID=1000
- PGID=1000
- TZ=Etc/UTC
volumes:
- /srv/docker/bazarr/config:/config
- /data/media:/data/media
ports:
- 6767:6767
restart: unless-stopped
whisper:
image: onerahmet/openai-whisper-asr-webservice:latest
container_name: whisper
environment:
- ASR_MODEL=small
- ASR_ENGINE=faster_whisper
volumes:
- /srv/docker/whisper/cache:/root/.cache
ports:
- 9000:9000
restart: unless-stopped

A few notes on this file.

GPU or CPU

The Whisper project publishes a latest tag for CPU and a latest-gpu tag for NVIDIA cards. For a GPU, swap the image and add a device reservation:

docker-compose.yml (whisper, GPU variant)
whisper:
image: onerahmet/openai-whisper-asr-webservice:latest-gpu
container_name: whisper
environment:
- ASR_MODEL=medium
- ASR_ENGINE=faster_whisper
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: 1
capabilities: [gpu]
volumes:
- /srv/docker/whisper/cache:/root/.cache
ports:
- 9000:9000
restart: unless-stopped

The Bazarr wiki calls the GPU route “recommended”, and I agree. CPU works, but a feature-length film on CPU is a long wait. Time one episode on small before you point your whole library at it.

Picking an engine and a model

Two environment variables on the Whisper container matter:

If you only watch English audio, the .en models (small.en, medium.en) are an option. The Whisper docs say they tend to do better on English, with the gap shrinking at small.en and above.

Check that the container is alive before you wire it up. The service exposes a Swagger page at /docs:

Terminal window
docker compose up -d
curl -s -o /dev/null -w "%{http_code}\n" http://192.168.1.50:9000/docs

A 200 means the service is up. The model downloads on first use, so the first transcription is slower than the rest.

Connecting Sonarr and Radarr

Open Bazarr at http://192.168.1.50:6767 and go to the Sonarr settings page. You need four things: address, port (8989 by default), API key (Sonarr under Settings, General, Security), and the SSL toggle if you use HTTPS. Radarr works the same way on its own page.

One trap here: when Bazarr and Sonarr run in separate containers, you cannot use localhost or 127.0.0.1 as the address. The Bazarr wiki says so directly. Use the container name (sonarr) on a shared Docker network, or the host’s LAN address. Hit Test Connection before you do anything else.

Path mappings: the number one failure

Sonarr tells Bazarr “episode lives at /tv/Show/S01E01.mkv”. Bazarr then looks for that exact path inside its own container. If Bazarr sees the same files at a different path, it finds nothing, and your “Wanted” list fills with files that exist but cannot be reached.

There are two fixes:

  1. Mount the same path everywhere. If Sonarr, Radarr, and Bazarr all see /data/media, no mapping is needed. This is what the compose file above does, and it is the setup the Bazarr wiki points to (it links the TRaSH hardlink guide for it).
  2. Add a path mapping. If the paths differ, add an entry under the Sonarr or Radarr path mappings section: the path Sonarr uses on the left, the path Bazarr uses on the right.

Do not do both. The wiki warns that a mapping with the same path on both sides is not needed and causes an error. Pick one.

Your 2 AM self will thank you for checking this first. When subtitles do not appear, look at paths before you blame providers.

Languages and Profiles

Bazarr does nothing for a series until it has a language profile. Create one under Settings, Languages, on the Profiles tab. A profile holds a name and a list of language rows. In v1.6.2 each row has two options:

The profile also has one Cutoff selector. Once that language is found, Bazarr stops searching the others.

A practical setup for English-speaking households: one English row set to “Non-HI only”, plus a second English row set to “Forced (foreign part only)”. The default “Normal or hearing-impaired” also accepts SDH files, so pick Non-HI if the [DOOR SLAMS] captions annoy you. For other languages, subtitles that duplicate the audio are clutter, so “no audio track matches” is the setting to use.

Two related settings save a lot of clicking:

If you enable “Deep analyze media file to get audio tracks language” under the same Languages settings, Bazarr reads the audio track languages with ffprobe or mediainfo. Turn it on. The Whisper provider guesses badly without it, because with an unknown language it only listens to the first 30 seconds.

Providers

Under Settings, Providers, enable the sources you want. Enable several. Different providers have different coverage, and Bazarr searches all of them.

OpenSubtitles.com is the big one. It needs an account, and the limits matter at library scale. As of November 2026, OpenSubtitles’ own help page says API downloads are limited to 5 per day without an account and 20 per day with a free account. The limit rises with contributor rank and VIP status, but a new free account starts low. Twenty downloads per day is a slow crawl across a large library. Bazarr’s backlog will work through at that pace, but do not expect a new library to be fully subtitled in an afternoon.

Other providers (Addic7ed, Podnapisi, and more) sit in the same list. Some are free, some need accounts, and some need a paid anti-captcha service. Read the label next to each provider before you enable it.

If you want translation of an existing subtitle, there is also a separate Translation tab on the providers page, where you pick a translator service (Google Translate, Gemini, or Lingarr). The default is Google Translate.

Score Thresholds and Upgrades

Every candidate subtitle gets a score based on how well it matches your file: filename, release name, and so on. Settings, Subtitles, on the Search tab has the two knobs:

Both are percentages from 0 to 100. Bazarr only downloads automatically when a candidate scores at least that high. The wiki’s guidance:

I keep both in the balanced band. Lowering the threshold fills the “missing” list faster and also lets in subtitles for the wrong release.

Upgrade previously downloaded subtitles

Right above the scores is Upgrade Previously Downloaded Subtitles, with a “Number of Days to Go Back” value up to 30 (default 7). With 14 days, Bazarr rechecks subtitles it downloaded in the last two weeks and swaps in a higher-scoring one if a provider has since posted it. This is useful for new releases, where the first subtitle on a provider is often a rough match and a better one lands days later.

Adaptive searching

Also on the Search tab, Adaptive Searching stops Bazarr from hammering providers for files it searched recently. The wiki gives defaults of a 3 week delay before adaptive mode starts and 1 week between searches after that. Given the 20 per day OpenSubtitles limit, leave it on.

Sync, Forced, HI, and Embedded Subs

Audio synchronization

A subtitle that matches the right release can still drift. Bazarr can fix timing with ffsubsync. The setting is Enable Automatic Subtitles Audio Synchronization, under Settings, Subtitles, on the Processing tab.

The wiki warns that sync can add minutes per subtitle. On a NAS with a weak CPU, set the threshold low so only bad matches get synced.

Forced and hearing-impaired files

Both are controlled by the profile options above. For naming, the Files tab has a Hearing-Impaired Subtitles Extension setting with .hi, .sdh, or .cc. With .sdh, an English HI file is saved as movie.en.sdh.srt. Jellyfin and Plex read the language code and the suffix, so pick one and stay with it.

If you would rather strip the [DOOR SLAMS] noise from subtitles, the Sub-Zero modifications on the Processing tab include a Hearing Impaired option that removes those tags.

Embedded subtitles

If a file already has an embedded subtitle in your language, searching providers is wasted effort. Treat Embedded Subtitles as Downloaded (Files tab) tells Bazarr to count embedded tracks as satisfying the language requirement. Turn it on and Bazarr skips the search when a matching embedded track exists. Turn it off and it searches anyway.

Under the same section, you can ignore embedded PGS (Blu-ray bitmap), VobSub (DVD bitmap), or ASS tracks. Ignore PGS when you want a text subtitle to replace an image-based one.

Where the files go

Subtitle Folder defaults to the recommended “AlongSide Media File”. A file like Inception.en.srt sits next to Inception.mkv, which is exactly where Jellyfin and Plex look. Leave it there.

Adding Whisper as the Fallback

Now the second half. Whisper catches what providers miss.

Add the Whisper provider under Settings, Providers. The wiki says to set the endpoint to the host running the Whisper container, and to raise the timeout if long movies keep timing out. The endpoint must start with http://. With the compose file from earlier:

Endpoint: http://whisper:9000

If Whisper runs on another machine, use that machine’s LAN address, for example http://192.168.1.50:9000.

Then go to Settings, Subtitles, Processing tab, and find the Whisper As Fallback section:

The provider also has two timeouts. In v1.6.2 the connection timeout defaults to 5 seconds and the transcription timeout to 3600 seconds. A long film on a slow CPU can pass an hour, so raise the second one before you blame Whisper.

The score trap

Whisper subtitles come with a fixed score. The wiki gives 220/360 (about 61%) for episodes and 60/180 (about 33%) for movies, because Whisper only ever matches series, season, and episode (or just the title for movies). At a 75% minimum, a plain provider result at those scores never clears the bar.

The fallback toggles get around that. In Bazarr v1.6.2’s source, the fallback runs only after no provider result reached the minimum score, and the Whisper subtitle it picks skips the score check. So with Use Whisper as Fallback for Automated Searches on, leave your thresholds in the balanced band. Do not drop the movie minimum to 33%: that lets weak provider matches through for every file in the library, and the fallback does not need it.

The trap is enabling the Whisper provider without the fallback toggle. Then Whisper is one more provider, its 33% movie score loses to the threshold, and nothing happens. Test with one file no provider has: run a missing-subtitles search and read the History page to confirm Bazarr used the Whisper result.

Language detection

Whisper only uses the first 30 seconds of audio to guess the language when Bazarr does not tell it. A cold open with music or a long silence gives a wrong guess and a gibberish transcript. The fix is the deep analyze setting from the Languages section, so Bazarr passes the right language.

You can test the service by hand with the same API Bazarr uses. The /asr endpoint takes an audio_file upload, and output=srt returns a subtitle file:

Terminal window
curl -X POST -H "content-type: multipart/form-data" \
-F "audio_file=@/data/media/home-videos/birthday.mp4" \
"http://192.168.1.50:9000/asr?output=srt&language=en" > birthday.en.srt

If that returns a sensible .srt, the container works and any remaining problem lives in Bazarr’s settings.

Translation limits

Whisper transcribes many languages but translates only into English. The Bazarr wiki says so, and the /asr endpoint’s translate task matches: it produces an English transcript regardless of the spoken language. For French audio with Spanish subtitles, Whisper cannot help. Use a provider, or the translation service on the Providers page.

Why Providers First

A provider subtitle is written by a person who watched the film. It gets character names right, handles slang, and arrives fast. A Whisper subtitle is machine output. It is good on clean speech and worse on mumbling, overlapping dialogue, music, and proper nouns. It also costs minutes to hours of compute per file, on a box that might be doing something else.

So the order is clear. Providers for anything with a release behind it. Whisper for the leftovers: your own recordings, obscure imports, anime nobody ever subbed, and foreign films with no English subs, where transcribing the original language and then translating to English with Whisper beats having nothing.

Once Bazarr writes the .srt, Jellyfin and Plex pick it up on the next library scan. Bazarr’s Jellyfin integration can refresh the item after a download, so you rarely need to rescan by hand.

Common Questions

Does Bazarr work with Jellyfin?

Yes. Bazarr saves .srt files next to the media file, and Jellyfin reads external subtitle files from there. Bazarr also has a Jellyfin integration that refreshes the item after a download, so new subtitles appear without a manual library scan.

Do I need a GPU to run the Whisper container?

No. The latest image runs on CPU, and the latest-gpu image uses an NVIDIA card. The Bazarr wiki recommends the GPU. A CPU can handle small models, but a full movie takes much longer, so benchmark one episode before you enable the fallback for a whole library.

Why does Bazarr say my files are missing when Sonarr has them?

The cause is almost always mismatched paths. Sonarr reports a file path, and Bazarr must see the same path inside its own container. Mount the media at the same path in both containers, or add a path mapping. Using both together causes errors.

Can Whisper translate subtitles into languages other than English?

No. Whisper transcribes many languages but translates only into English. For other target languages, Bazarr needs a subtitle provider that has the file, or the translation service on the Providers settings page. Whisper still helps by producing a transcript in the original spoken language.


Share this post on:

Send a Webmention

Written about this post on your own site? Send a webmention and it'll show up above once verified.


Next Post
Proxmox Backup Server: Prune and Verify

Discussion

Powered by Garrul . Sign in with GitHub or Google, or post anonymously.

Related Posts