Adapter: Plex

Plex adapter notes for syncing watchlist/history/ratings with stable external IDs.

Plex adapter lets CrossWatch (CW) sync with Plex. It supports watchlist, history, ratings, and progress. 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)

  • Progress (resume position)

  • Playlists (not supported)

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

How matching works

CW 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 = mark watched (Plex uses current server time)

  • Remove = unscrobble

Plex has no supported way to backdate a play.

If CrossWatch writes History into Plex, Plex records watched_at as now.

This affects history sync and History capture restores.

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)

Progress behavior

• Read: current resume position for items with progress.

• Write: set resume position (“Continue Watching”).

• Clear: not supported by Plex.

Related: Progress.

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:

• CW 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 → CW will not unwatch on other services

Marked Watched is intended for the PMS owner. it will automatically be disabled when used for home users or friends.

Experimental: GUID fallback

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

Enable with plex.fallback_GUID = true.

The main purpose is to preserve old data once. Then you’re done.

In practice:

1. Create a temporary Plex → provider X pair.

2. Enable Fallback GUID.

3. Run sync to move the old data to provider X.

4. Remove that pair again.

5. Clean up everything.

6. Disable Fallback GUID in your next pair.

Enable this only temporarily.

Run it once, then disable it.

It costs extra API calls and CPU time.

It can slow runs and trigger timeouts or rate limits.

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.