> For the complete documentation index, see [llms.txt](https://wiki.crosswatch.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.crosswatch.app/crosswatch/settings/synchronization/media-servers/jellyfin.md).

# 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.

{% hint style="warning" %}
CrossWatch requires **Jellyfin 10.9 or newer**.

Older Jellyfin versions are not supported.
{% endhint %}

### What CrossWatch can sync

| Feature    | Read | Write | Notes                                                                                     |
| ---------- | ---- | ----- | ----------------------------------------------------------------------------------------- |
| Watchlist  | Yes  | Yes   | Library movies and shows via Favorites, a playlist or a collection.                       |
| History    | Yes  | Yes   | Library movies and episodes; watched state rather than individual rewatch events.         |
| Ratings    | No   | No    | Unsupported.                                                                              |
| Progress   | Yes  | Yes   | Resume positions for library movies and episodes.                                         |
| Playlists  | Yes  | Yes   | Playlists and collections, subject to access permissions. Custom ordering is unsupported. |
| Collection | Yes  | No    | Selected library inventory; source only. Does not add or delete media files.              |

**Read** brings data into CrossWatch; **Write** sends changes to this provider. Enable only features supported by both sides. Collection pairs are one-way only.

Connect the provider first: [Jellyfin setup](https://wiki.crosswatch.app/crosswatch/settings/connections/media-servers/jellyfin.md).

### 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`.

{% hint style="warning" %}
Strict ID matching is the default.

If external IDs are missing, CrossWatch usually treats the item as a missing peer instead of guessing by title/year.

You can relax this per pair, but false positives get more likely, especially for episodes.
{% endhint %}

### 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.

{% hint style="info" %}
Recommended: **Favorites** or **Collection**.
{% endhint %}

{% hint style="warning" %}
Jellyfin playlists can’t hold Series. Playlist mode will only cover Movies and Episodes.
{% endhint %}

### Playlist privacy

When creating a Jellyfin **Playlist** in [Playlists](https://wiki.crosswatch.app/crosswatch/main-dashboard/navigation/playlists.md#list-privacy), choose **Private** (default) or **Public**. Eligible playlists can also change privacy later. These controls do not apply to Jellyfin collections.

### Collection sync

Jellyfin is a Collection source only. This feature reads items from selected libraries.

It does not use named Jellyfin collections. Collection sync is one-way only.

### History behavior

* Reads played Movies and Episodes, sorted by `DateLastPlayed`.
* Each entry becomes a normalized event with `watched_at` in UTC (`...Z`).
* With the pair option [**Update all copies**](https://wiki.crosswatch.app/crosswatch/settings/configure-pairs/features/history.md#update-all-copies-jellyfin), every copy of a title in the selected libraries (for example HD and 4K) is marked or unmarked, and unwatched copies are filled in.

{% hint style="info" %}
Jellyfin does not expose unique play-event IDs. CrossWatch approximates event identity using item key + timestamp.
{% endhint %}

### Progress behavior

* Read: current resume position (“Continue Watching”).
* Write: set resume position.
* Clear: supported (writes progress `0`).

Related: [Progress](https://wiki.crosswatch.app/crosswatch/settings/configure-pairs/features/progress.md).

### Settings (advanced)

The UI shows these in **Synchronization** on the pair that uses Jellyfin.

<details>

<summary>Important config keys</summary>

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)

</details>

### Diagnostics

<details>

<summary>Health checks</summary>

* Ping: `GET /System/Ping`
* System info: `GET /System/Info`
* User probe: `GET /Users/{userId}`

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

</details>

<details>

<summary>State and unresolved files</summary>

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

These prevent infinite retries and make failures visible.

</details>

### 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.
* Jellyfin keeps a separate watched state for each copy of a title. Without **Update all copies**, CrossWatch marks only one copy. The Editor always removes every copy.

### Trakt rewatch resets

When paired with Trakt VIP, this server can follow show rewatch resets through the pair’s **History → Follow Trakt rewatch resets** option. It is off by default and can mark older episodes unwatched even if normal **Remove** is disabled. See [Trakt rewatch resets](https://wiki.crosswatch.app/crosswatch/settings/configure-pairs/features/history/rewatches.md#follow-trakt-rewatch-resets) before enabling it.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://wiki.crosswatch.app/crosswatch/settings/synchronization/media-servers/jellyfin.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
