Adapter: Jellyfin

Jellyfin adapter notes for syncing watchlist/history/ratings and handling missing external IDs.

Jellyfin adapter lets CrossWatch sync with your Jellyfin server. It supports watchlist, history, and progress. It prefers external IDs for matching.

What it supports

• Direction: source or target in a pair (one-way or two-way)

• Features:

  • Watchlist (favorites, playlist, or collection mode)

  • History (played movies and episodes)

  • Progress (resume position)

  • Playlists (not supported yet)

• Indexing: present-state snapshot (reads “what exists now”)

Connect Jellyfin first. Use: Jellyfin (Authentication provider).

How matching works

CrossWatch normalizes items into a common shape:

• type, title, year, ids

• Episodes can include show_ids, season, episode

IDs are pulled from Jellyfin ProviderIds when available (IMDb/TMDb/TVDb). For episodes, the adapter tries to include show context in show_ids.

If external IDs are missing, matching can fall back to title/year. This is less reliable, especially for episodes.

Watchlist behavior

Pick one watchlist mode:

1. Favorites (default) Uses the user IsFavorite flag for Movies and Series.

2. Playlist Uses a playlist (default name: Watchlist) as the watchlist container.

3. Collection Uses a named collection as the watchlist container.

Reads enumerate the chosen container. Writes toggle favorites or add/remove from the playlist/collection.

Recommended: Favorites or Collection.

Jellyfin playlists can’t hold Series. Playlist mode will only cover Movies and Episodes.

History behavior

• Reads played Movies and Episodes, sorted by DateLastPlayed.

• Each entry becomes a normalized event with watched_at in UTC (...Z).

Jellyfin does not expose unique play-event IDs. CrossWatch approximates event identity using item key + timestamp.

Progress behavior

• Read: current resume position (“Continue Watching”).

• Write: set resume position.

• Clear: supported (writes progress 0).

Related: Progress.

Settings (advanced)

The UI mirrors these under Settings → Synchronization Providers → Pairs (with Jellyfin).

Important config keys

Watchlist:

• mode: favorites | playlist | collection

• playlist_name

• watchlist_query_limit, watchlist_write_delay_ms

• watchlist_guid_priority

History:

• history_query_limit, history_write_delay_ms

• history_guid_priority

• history_libraries (optional include-list of library IDs)

Diagnostics

Health checks

• Ping: GET /System/Ping

• System info: GET /System/Info

• User probe: GET /Users/{userId}

Logs are prefixed with [JELLYFIN:feature] (example: [JELLYFIN:history] ...).

State and unresolved files

• History shadow (merge-only): managed by the module/orchestrator

These prevent infinite retries and make failures visible.

Notes and limitations

• Missing external IDs reduces match quality.

• If writes are flaky, add a small write delay.

• Jellyfin actions are user-scoped. Use separate pairs per Jellyfin user.