> 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/emby.md).

# Emby

Emby adapter notes for syncing watchlist/history/ratings and handling ID/matching quirks.

Emby adapter lets CrossWatch treat Emby as a sync provider in pairs. It supports watchlist, history, and progress. It prefers external IDs for matching.

### 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.                         |
| 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: [Emby setup](https://wiki.crosswatch.app/crosswatch/settings/connections/media-servers/emby.md).

### How matching works

CrossWatch normalizes items into a common shape:

* `type`, `title`, `year`, `ids`
* Episodes also include `series_title`, `season`, `episode`

IDs come from Emby `ProviderIds` when present (IMDb/TMDb/TVDb). The Emby internal item ID is also stored as `ids.emby`.

{% 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 items in the playlist/collection.

{% hint style="warning" %}
Avoid **Playlist** mode unless you need it. It’s easier to accidentally create duplicates and churn.
{% endhint %}

### Collection sync

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

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

### History behavior

Reads recent plays for:

* Movies
* Episodes

Each play becomes a normalized event with `watched_at` in UTC (`...Z`).\
Writes mark items played, with optional backdating.

### Progress behavior

* Read: current resume position (“Continue Watching”).
* Write: set resume position.
* Clear: supported (writes progress `0`).
* Optional [Continue Watching removal sync](https://wiki.crosswatch.app/crosswatch/settings/configure-pairs/features/progress.md#sync-continue-watching-removals) hides the movie or show card while keeping its resume position. Both sides must be Emby, Plex, Tofa or Silo.

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

<details>

<summary>Important config keys</summary>

Top-level:

* `server`, `access_token`, `user_id`, `device_id`
* `timeout`, `max_retries`, `verify_ssl`

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`
* `libraries` (optional scoping)
* `force_overwrite`, `backdate`, `backdate_tolerance_s`

Ratings (future):

* `ratings_query_limit`, `libraries`
* `ratings_like_threshold`

</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 `[EMBY:feature]` (example: `[EMBY:watchlist] ...`).

</details>

<details>

<summary>State and unresolved files</summary>

* Watchlist unresolved: `/config/.cw_state/emby_watchlist.unresolved.json`
* History unresolved: `/config/.cw_state/emby_history.unresolved.json`
* Ratings unresolved: `/config/.cw_state/emby_ratings.unresolved.json`
* History shadow (merge-only): `/config/.cw_state/emby_history.shadow.json`
* Health shadow: `/config/.cw_state/emby.health.shadow.json`

These prevent infinite retries and make failures visible.

</details>

### Notes and limitations

* Prefer libraries with good external IDs.
* If writes are flaky, add a small write delay.
* Emby actions are user-scoped. Use separate pairs per Emby user.

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