Jellyfin

Jellyfin is a source provider for movies, shows, personal ratings, watched progress, and Continue Watching. Brokerr supports Jellyfin 10.10 and newer.

Primary movie images and root-series images are used as source posters. The Jellyfin API key remains server-side while Brokerr proxies or caches the image.

Before you start

Create a Jellyfin API key that can read users and the selected user’s media. The URL must be reachable from the Brokerr container and may include a subpath, for example https://media.example.com/jellyfin.

Add the source

1. Open Settings > Sources > Jellyfin and add a source.
2. Enter the server URL and API key, then choose Load users.
3. Select one user. Create another source for another user, even on the same server.
4. Choose Load libraries, enable the required movie or TV libraries, and save.
5. Choose how duplicate movie versions should be selected.
6. Run Test connection before using the source in a profile.

The API key is encrypted in SQLite and is never returned by the API or config export. Leaving the field empty while editing preserves the saved key.

Duplicate movie versions

Jellyfin can expose separate movie items for different encodes of the same release. Brokerr groups movie items that share a TMDB, IMDb, or TVDB ID and synchronizes one version:

• Highest watch state (default): Completed, then In progress, then Unwatched.
• Largest file: the version with the largest reported media-source size.
• First returned by Jellyfin: preserves Jellyfin’s response order.

Ties keep the first item. Movies without a stable external ID are not merged; title matching is intentionally not used because it could combine different movies or remakes.

Synchronized state

• Played supplies completed movies and watched episodes.
• PlayCount supplies rewatch count where the target supports it.
• PlaybackPositionTicks marks a movie or episode as started. Movie playback time is not converted into target minutes.
• Personal Rating values use the profile rating rules.
• Resume and Next Up are combined for Continue Watching behavior.
• Specials are excluded from regular episode progress.

Incremental sync reads a consistent library snapshot and then uses Brokerr’s local fingerprints. Jellyfin server-side delta scans are not used yet.

Mapping

Brokerr uses TMDB, TVDB, IMDb, AniDB, AniList, and MAL IDs exposed by Jellyfin. Direct identifiers win; AniBridge remains the anime fallback when a suitable direct anime identifier is unavailable.

When the same stable media ID exists in another source, Brokerr can reuse its thumbnail. Jellyfin items without a stable ID remain separate even when their names match.

Webhooks

Install the official Webhook plugin from the Jellyfin plugin catalog. In Dashboard > Plugins > My Plugins > Webhook, create a Generic Destination:

1. Select User Data Saved and Playback Stop, then select the same Jellyfin user as the Brokerr source.
2. Copy the source webhook URL and JSON template from Settings > Sources > Jellyfin.
3. Append ?api_key=<brokerr-api-key> when Brokerr has an API key configured.
4. Add a Content-Type header with value application/json.
5. Save the destination, then change watched state or rating for a movie or episode and inspect the source webhook events in Brokerr.

Brokerr validates the Jellyfin server and user IDs, refreshes the selected libraries, and sends only the affected normalized movie or series to every matching webhook-enabled profile. PlaybackStop captures stopped playback. For UserDataSaved, Brokerr accepts watched, rating, and resume-state changes but ignores periodic playback-progress saves to avoid excessive source scans.

If users or libraries do not load, verify the URL from inside the Brokerr container, API-key permissions, selected user access, and any reverse-proxy subpath configuration.