Real-Time Sync

Librariarr keeps a live WebSocket connection to each enabled media server, so it reacts to what happens on your servers within seconds instead of waiting for the next scheduled poll.

This runs alongside — not instead of — the scheduled sync. Scheduled full syncs remain the source of truth and reconciliation backstop; real-time events just make the app react sooner between them.

What it powers

Capability	Without real-time	With real-time
Active sessions view	Refreshes every 5s	Pushes within ~2s of a play/pause/stop
Maintenance / blackout / transcode enforcement	New streams seen up to 30s late	New streams seen within ~½s, so the termination delay starts promptly
New / removed / updated media	Appears on the next scheduled sync	Syncs just the changed/removed items seconds after the server’s scan settles
Watch state (played / unplayed, last watched)	Refreshed on the next full sync	Refreshed shortly after a play finishes

Real-time library changes carry the specific items that changed, so Librariarr fetches and updates only those items (and deletes the removed ones) instead of re-scanning the whole server. It falls back to a full sync when a change is too large (100+ items at once), can’t be mapped to a library, or a full sync is already running — and the scheduled full sync remains the periodic reconciliation backstop. Either way the normal in-app “sync completed” refresh applies, so updated listings surface automatically.

Only changes that are actually library media are applied. Two kinds are skipped:

• Containers — a Plex collection, a Jellyfin/Emby box set, a playlist. This matters most for Librariarr’s own collection sync: writing a collection to Plex makes Plex report a library change, which would otherwise pull that collection straight back in as a phantom item.
• The levels above the item that changed — adding one episode makes a server report the episode, its season and its show as changed. A series library stores episodes (and a music library stores tracks), so only the episode is applied; the show and season would otherwise appear as phantom rows until the next full sync cleared them.

Supported servers

All three server types are supported, and each connected server gets its own independent connection — including multiple servers of the same type (several Plex, Jellyfin, or Emby instances all connect in parallel).

Server	Endpoint
Plex	/:/websockets/notifications (play, library timeline, scan activity)
Jellyfin	/socket (sessions, LibraryChanged, UserDataChanged)
Emby	/embywebsocket (same protocol as Jellyfin)

How it behaves

• Self-healing. If a connection drops, Librariarr reconnects automatically with exponential backoff (1s up to 60s). On reconnect it re-reads current state so nothing is missed.
• Debounced. A library scan that emits hundreds of change events is coalesced — the changed item IDs are accumulated and applied in a single incremental pass; a burst of playback progress events is throttled so your server isn’t hammered.
• Reconciled. Adding, editing, enabling/disabling, or removing a server immediately opens or closes its connection. A safety re-check also runs every minute.

Enabling / disabling

Real-time sync is on by default. Toggle it in Settings → General → Display → Real-time server sync.

Turn it off to rely on scheduled polling only. This is useful when a reverse proxy in front of your server doesn’t allow WebSocket upgrades — in that case the connection would fail and reconnect in the background, and disabling it avoids the churn.

Tip

If a server sits behind a reverse proxy, make sure the proxy forwards WebSocket upgrade headers (Upgrade / Connection) for the notification endpoint. Without that, real-time events won’t arrive even though normal (HTTP) sync still works.

Note

Real-time connections run in the app’s single background process (the same one that runs the job queue and enforcers). No extra container or configuration is required.