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

# Adapter: Emby

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 it supports

* Direction: one-way or two-way (depends on the pair)
* Features:
  * **Watchlist** (favorites, playlist, or collection mode)
  * **History** (mark played, read played)
  * **Progress** (resume position)
  * **Ratings** (not supported yet)
  * **Playlists** (not supported yet)
* Indexing: present-state snapshot (reads “what exists now”)

{% hint style="info" %}
Connect Emby first. Use: [Emby (Authentication provider)](/crosswatch/providers/authentication/auth-media-servers/auth-emby.md).
{% endhint %}

### 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 %}

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

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

### Settings (advanced)

The UI mirrors these under **Settings → Synchronization Providers → Pairs (with 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.


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://wiki.crosswatch.app/crosswatch/providers/synchronization/adapter-emby.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.