Adapter: Plex

Plex adapter lets CrossWatch sync with Plex. It supports watchlist, history, and ratings. It prefers stable external IDs.

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

What it supports

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

• Features:

  • Watchlist (via Plex Discover)

  • History (via Plex Media Server)

  • Ratings (via Plex Media Server)

  • Playlists (not supported)

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

How matching works

CrossWatch tries to match by provider IDs first.

• Watchlist: GUID / external IDs from Plex Discover

• History + ratings: PMS items enriched with external IDs when available

If external IDs are missing, matches get weaker. Enable the experimental fallback only if you accept the trade-offs.

Watchlist behavior

• Read: pulls your watchlist from Plex Discover.

• Write: add/remove via Discover actions.

• No fuzzy title matching.

History behavior

• Read: PMS play history for the selected user.

• Write:

  • Add = scrobble with watched_at

  • Remove = unscrobble

Plex has “play history” and “marked watched”. Marked watched is optional and add-only. See below.

Ratings behavior

• Read: scans libraries and keeps items with userRating.

• Write:

  • Add = rate (1–10)

  • Remove = clear rating (rating 0)

Settings (advanced)

Common keys and knobs

Workers:

• plex.rating_workers (1–64)

• plex.history_workers (1–64)

Library filters:

• plex.ratings.libraries (section IDs)

• plex.history.libraries (section IDs)

Watchlist:

• plex.watchlist_query_limit

• plex.watchlist_write_delay_ms

• plex.watchlist_allow_pms_fallback

History:

• plex.history_ignore_local_guid

• plex.history_ignore_guid_prefixes (example: local://)

• plex.history_require_external_ids

• plex.history.include_marked_watched

Experimental:

• plex.fallback_GUID

Marked Watched (Plex “checkmark”) behavior

Plex has two different signals:

• Play history: real play events

• Marked watched: manual “mark as watched” state

If plex.history.include_marked_watched = true:

• CrossWatch also scans your libraries for items Plex considers watched

• It merges those into history only if Plex provides a timestamp (lastViewedAt / viewedAt)

This is add-only:

• Mark watched in Plex → can sync out

• Unmark watched in Plex → CrossWatch will not unwatch on other services

Marked Watched is intended for the PMS owner / Plex Home users. Avoid enabling it when syncing “friend” accounts.

Experimental: GUID fallback

Fallback tries to recover IDs when PMS hydration fails (404) or IDs are missing.

Enable with plex.fallback_GUID = true.

Used for:

• History rows that can’t be hydrated by ratingKey

• Rated items missing external IDs

Strategy (best-effort):

1. Query Plex metadata service for external IDs

2. For episodes, also hydrate the show via grandparentRatingKey

3. Use Discover title+year search as a last resort

To keep it fast and quiet, results are memoized:

• /config/.cw_state/plex_fallback_memo.json

Delete the file to force retries.

Diagnostics

Unresolved (freeze) files

Items that can’t be matched or written are frozen to avoid repeat retries:

• Watchlist: /config/.cw_state/plex_watchlist.unresolved.json

• History: /config/.cw_state/plex_history.unresolved.json

• Ratings: /config/.cw_state/plex_ratings.unresolved.json

Notes and limitations

• Prefer external IDs and stable libraries.

• Start one-way. Run one feature. Then expand.