Bazarr+

Media Servers (Emby & Silo) v2.7

Bazarr+ v2.7 (Atlas) connects to as many Emby and Silo servers as you run, not one of each. When a subtitle is written, every server whose folders cover that file is told about it, so the track appears without you triggering a full library rescan, and one server being down does not hold up the rest.

What a media server connection does

Bazarr+ writes a subtitle next to your video. Your media server does not notice on its own: it indexed that folder some time ago and has no reason to look again until its next scheduled scan. So the subtitle exists on disk and does not exist as far as the player is concerned, sometimes for hours.

A media server connection closes that window. After Bazarr+ writes the file it tells the server which item changed, and the server re-reads just that item. Seven kinds of change do this: download, upload, delete, sync, translate, combine and edit. All seven work for movies and for episodes, on both servers.

It is not a library scanner. Bazarr+ does not index your library for the server, import anything, or change metadata. It sends one refresh for one item and stops. A server that is unreachable simply does not get told, and Bazarr+ keeps the refresh to retry rather than losing it.
Jellyfin and Plex are not on this page yet. They have their own connections in Bazarr+ today and they work differently from the two below. They join this page as sections of their own once they move onto the same shared layer.

Connecting several servers

In Bazarr+, go to Settings > Connections and open the Emby or Silo tab. Each has two parts: one master switch, and any number of instances under it.

  1. Turn Enabled on. That is the master switch for this kind of server; with it off, none of its instances do anything.
  2. Click Add instance. Give it a Name you will recognise in a list, since everything else on the card is reported against that name.
  3. Instance enabled is per instance. Turning one off leaves its siblings untouched.
  4. Server URL: the full URL including any path prefix, for example http://emby:8096. Credentials belong in the API key field, not in the URL.
  5. API Key: stored encrypted at rest and never returned by the API. Editing an instance lets you keep, replace or clear it.
  6. Verify SSL certificate: applies to HTTPS connections only.
  7. Test. It uses the fields in front of you, including unsaved changes. On Silo, Load libraries does too. Note what Test does and does not prove: "Test checks access, not refresh permission."
  8. Add path mappings, below, then Save.

Every instance owns its own enabled state, URL, key, TLS setting, path mappings, Silo library choices, queued refreshes, status and retry action. Nothing is shared between two instances of the same kind.

Both are new in v2.7. Neither Emby nor Silo existed in any earlier Bazarr+ release, so there is no single-server setup to carry over and nothing to migrate. Every instance here is one you add.

Path mappings, and when you need them

Bazarr+ and your media server both see the same files, usually at different paths, because each container mounts the library where it likes. A mapping is one pair: the folder as Bazarr+ sees it, and the same folder as that server sees it.

Mappings do two jobs, and the second one is the one people miss:

  • They translate the path, so the server is told about a file at an address it can actually resolve.
  • They select which videos notify this instance. A file outside every mapping on an instance is not that instance's file, and it is skipped silently rather than reported as an error. This is how two servers holding different halves of a library stay out of each other's way.

So you add a mapping for each media folder even when both paths are identical. An instance with no mapping covering a file never hears about it.

A path that matches several instances refreshes every one of them. Where two mappings on the same instance both match, the more specific one wins; two equally specific mappings that both match are ambiguous and the refresh is refused rather than guessed at.

On Silo, a mapping also names a library. Load libraries first, then pick the Silo library that contains that server folder for each mapping. Silo addresses media by library and path, so a mapping with no library selected cannot be used.

Emby

Emby answers every question Bazarr+ can ask, so it climbs the full ladder and stops at the first rung that resolves the item. In order:

  1. Provider ID. IMDb, plus TMDB for a movie or TVDB for a series, matched through Emby's AnyProviderIdEquals filter. First because an identifier names the item on its own, which is what survives a wrong path mapping. An episode carries no identifier of its own, so this rung finds the series and the season and episode numbers pick the file underneath it.
  2. Exact path. Second because it is the only thing that proves one specific file.
  3. Title and year. After the path, because two metadata fields are a guess and a guess must not pre-empt proof. The candidate still has to hold the file for this rung to accept it.
  4. Library refresh. Last, because it is the broadest thing any server can be asked to do. It is what reaches a file Emby has not indexed yet at all.

Movies and episodes both, and all seven publication types. Emby support is new in v2.7, so there is no older behaviour to unlearn: this is how it has always worked.

Silo

Silo climbs two rungs: the exact path, then a library scan. Movies and episodes both, and all seven publication types, exactly like Emby.

The path rung is a real per-file scan on Silo's own native API, and Bazarr+ watches it through to completion, so a Silo refresh is confirmed rather than merely requested. When Silo answers that it cannot scan that path, which it does for a path it cannot place in a library or a container its scanner does not read, Bazarr+ climbs to a library scan. That one is submitted rather than watched: a full scan outlives any deadline worth holding a worker on. A batch that lands every file on this rung submits one scan for the library rather than one per video.

Two things Silo cannot do. Both are Silo's ceilings, not decisions Bazarr+ made, and both are stated here so the behaviour is not mistaken for a bug in Bazarr+:

  • No identifier or title matching. Silo's Jellyfin-compatible API returns items with no ProviderIds field at all, confirmed against Silo 10.12.0, so there is nothing for a provider-ID or a title match to compare against. That is why the path is the first rung Silo can climb rather than the second.
  • No Jellyfin-style per-item refresh. Silo's compatibility layer does not route POST /Items/{id}/Refresh at all, answering 404, so the request a Jellyfin client would make does not exist there. Filed upstream as Silo-Server/silo-server#1013. Bazarr+ works around it by using Silo's own native scan endpoint instead, which is why the path rung works at all, with the library scan as the fallback beneath it.
Silo only sees sidecar subtitles. Silo refreshes subtitles stored beside the video file. If your subtitle folder setting puts them somewhere else, Silo has nothing to find, and the instance reports exactly that: "Silo only refreshes subtitles stored beside the video file. Move the subtitle there, then retry."

Sports

Sports recordings publish to both servers as well, on a shorter ladder: a sports event carries no provider identifiers, so the identity rungs cannot answer for one. Silo keeps its full path rung, because its file scan takes only a library and a path and does not care what kind of media it is, so a recording scans exactly as a movie does. Emby is left with the library refresh, because the typed item lookup its other rungs use has no sports item type to ask for.

Reading the status on an instance card

Each instance card carries its own refresh state. Five states, and they mean different amounts:

  • No pending refreshes. Nothing is queued for this instance.
  • Refresh pending. Queued but not yet sent, with the number of queued refreshes beside it.
  • Refresh sent. The server accepted the request. This is as far as a submitted request can be known.
  • Refresh confirmed. The refresh was observed through to completion, which Silo's watched file scan can prove. Read it precisely, and the card says so too: "Confirmation means the server finished a scan, not that it found the subtitle."
  • Refresh unconfirmed. The request went out and Bazarr+ could not establish that it finished. Worth a look; not the same as a failure. On Silo there is one cause you can actually fix, and the card names it: "When Silo runs across machines, synchronize the application/event-publisher and database clocks so refresh completion can be confirmed."

Retry pending drains the queue for that instance, using the saved connection settings, not whatever is typed into the form. Save your changes first, and if the instance or its master switch is off, turn them on and save before retrying.

Queue overflow. If the queue for one instance overflows, the card says so: retrying covers the refreshes it kept, but the ones it dropped need a fresh change to be re-sent. It does not silently pretend they went out.

One bad server does not break the others

Each server with queued work gets its own background worker. A server that is paused, stopped or simply slow confines the problem to its own instance: the others carry on refreshing, and the failed instance keeps its queue for Retry pending to drain once it is back. Disabling one instance leaves its siblings untouched, and a mapping mistake fails only on the instance that is miswired.

Changing an instance's connection settings stops the refresh that was already in flight against the old settings rather than letting it finish against the new ones. The queued work is kept and marked, not thrown away, so Retry pending sends it under the settings you actually saved.

Troubleshooting

Nothing reaches a server, and no error appears. Almost always path mappings: a file outside every mapping on that instance is deliberately skipped in silence. Check that a mapping covers the folder the video is in, as Bazarr+ sees it.

Test passes but refreshes fail. Test checks access, not refresh permission, and it says so on the form. An API key that can read the server may still not be allowed to trigger a refresh.

Silo reports that a subtitle is unsupported. The subtitle is not beside the video file. See the warning under Silo above.

Silo mappings show as unavailable. The Silo library a mapping points at is gone, disabled, or was never loaded. Press Load libraries and pick the library again. Saved mappings are preserved when a library load fails.

"No supported libraries found" on Silo. Silo only offers movie and series libraries here, and only enabled ones. Enable one in Silo, and check that the API key can see it.

Silo refreshes stay unconfirmed. When Silo runs across machines, synchronize the application/event-publisher and database clocks so refresh completion can be confirmed. Bazarr+ watches Silo's scan events and matches them against the scan it asked for; clocks that disagree between the application, the event publisher and the database make that match impossible, so a scan that really did finish is reported as unconfirmed.

Emby refreshes the wrong item. That is what the ladder's ordering exists to prevent, and the most likely cause is a mapping that points two instances at overlapping folders. A path that matches several instances refreshes each of them, by design.

Next steps