Plex source
Plex is the current production source. It emits movie and show observations, including typed episode coordinates, identifiers, ratings, progress, Continue Watching, replay counters, artwork, watchlist membership, collections, and playback history.
Connect an account and server
Section titled “Connect an account and server”Add Plex under Sources and choose Sign in with Plex. After the PIN flow completes, Brokerr loads the connected username, avatar, owned/shared servers, and available connection URLs. Select a reachable direct or relay URL, save the instance, select libraries, and run Check connection.
Each Plex server is currently a separate source instance. The same account can authorize multiple instances, but their libraries and webhook routing remain separate.
Instance options
Section titled “Instance options”- Server URL — selected direct, relay, or operator-provided endpoint.
- Duplicate movie strategy — how to handle physical copies of the same film:
- Highest watch state (default)
- Largest file
- First copy
- All copies
Profile scope decides which libraries participate. The source instance library selection is the default for newly created profiles.
Observations
Section titled “Observations”Movies include canonical IDs, played/unplayed/in-progress state, viewCount,
lastViewedAt, rating, watchlist membership, artwork, library identity, and
Plex metadata required for mapping.
Shows include show/season ratings and typed episode observations with season, episode, watched, in-progress, Continue Watching, rating, replay counters, and external IDs. Season 0 is ignored for AniBridge segment progress.
The source-first artwork reference is credential-free to the browser: Brokerr proxies the Plex image and stores it in the shared artwork cache.
Watchlist source
Section titled “Watchlist source”Compatible target features can choose:
- Native source watchlist — items explicitly placed on the Plex account watchlist.
- All unwatched library items — current selected-library played state.
- Native watchlist + all unwatched items — the union of both.
- Disabled, where the target feature supports it.
The account watchlist is read from Plex Discover, while library state is read from the selected Plex server. The two can therefore contain different items.
Recorded history
Section titled “Recorded history”Plex server metadata normally supplies replay counters and a latest-viewed timestamp. The optional profile feature Synchronize recorded history also reads completed playback activity retained by the connected Plex account and merges it with server history.
This feature requires Sync Watch State & Ratings to be enabled for the Plex account. Brokerr uses the Plex cloud activity API, filters activity to the connected user, follows pagination, and merges duplicate server/cloud events. Friends’ activity is discarded.
The cloud activity endpoint is not part of Plex’s stable public PMS API. Brokerr therefore treats transient failures conservatively, applies pacing and retry, and falls back without inventing diary dates. A full run can be substantially longer because history may be fetched for many films.
Synchronize recorded history
Section titled “Synchronize recorded history”This disabled-by-default Plex feature is offered only when the target can use exact dated history, currently Letterboxd diary. It enriches selected-library items with exact account playback events.
Sync watched media missing from libraries
Section titled “Sync watched media missing from libraries”This disabled-by-default feature imports mappable watched account titles that no longer exist in the selected server libraries. It is available for Letterboxd and AniList profiles, but not TMDB because TMDB has no watched-history state.
Missing-library items contain only the metadata available from Plex account activity and Discover. They may remain unmatched. Enabling recorded history as well provides exact Letterboxd diary dates; without it, a provider may receive only Watched/replay state. Large account histories can make a full run much longer.
View count and exact dates
Section titled “View count and exact dates”viewCount proves how many completed plays Plex currently reports, but not all
individual dates are necessarily retained by the server. lastViewedAt is used
as a completed playback date when valid and not already represented by an exact
event. Brokerr never invents older dates to fill a counter gap.
A partially replayed film can temporarily appear unplayed/in-progress. Durable high-water state prevents that reset from becoming a Letterboxd diary entry until Plex reports the replay completed.
Collections and custom lists
Section titled “Collections and custom lists”Plex regular and smart collections are available to the global managed custom-list feature. Bindings are selected in Brokerr and stored in SQLite. Plex labels are not read as binding markers and are never rewritten.
Webhooks
Section titled “Webhooks”The source parses completion/uncompletion, rating, and relevant playback-state events. Eligible events fan out only to profiles that use the source, include the event library, have a live baseline, and enable Process source webhooks. Short bursts are coalesced for five seconds.
See Webhooks for setup and delivery behavior.
Capabilities
Section titled “Capabilities”Plex declares artwork, collections, episode details, playback and progress, ratings, rewatch counters, watchlist, view-history summary/events/catalog, event parsing, and coalescing capabilities. Targets cannot request observations Plex does not declare.