Adapter: Emby

Emby adapter lets CrossWatch treat Emby as a sync provider in pairs. It supports watchlist and history. 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)

  • Ratings (not supported yet)

  • Playlists (not supported yet)

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

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

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.

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

Avoid Playlist mode unless you need it. It’s easier to accidentally create duplicates and churn.

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.

Settings (advanced)

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

Important config keys

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

Diagnostics

Health checks

• Ping: GET /System/Ping

• System info: GET /System/Info

• User probe: GET /Users/{userId}

Logs are prefixed with [EMBY:feature] (example: [EMBY:watchlist] ...).

State and unresolved files

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

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.