Watcher

Real-time scrobbling from Plex/Emby/Jellyfin to Trakt, SIMKL and MDBList.

Watcher does real-time scrobbling in CrossWatch (CW).

It reads playback from your media server.

It pushes progress to trackers.

Watcher uses routes mode (starting in v0.9.0).

Routes are many-to-many mappings.

You can run multiple media servers and trackers together.

What it supports

Sources (providers):

• Plex

• Emby

• Jellyfin

Targets (sinks):

• Trakt

• SIMKL

• MDBList

Events:

• now playing (progress)

• pause/stop

• completion (after thresholds)

Routes mode (the important part)

Each route is:

provider(profile) → sink(profile)

That unlocks:

• Plex + Jellyfin + Emby in parallel.

• Trakt + SIMKL + MDBList at the same time.

• Multiple accounts per provider via profiles.

Profiles are called Profiles in the UI.

Profiles are documented here:

• Profiles

How sources are read (high level)

Watcher reads sources like this:

• Plex: connects via AlertListener and consumes “Playing” alerts.

• Emby: polls /Sessions?ActiveWithinSeconds=15 (every ~15s).

• Jellyfin: polls /Sessions?ActiveWithinSeconds=15 (every ~15s).

Prerequisites

• Connect your media server in Settings → Authentication.

• Connect at least one target tracker in Settings → Authentication.

Tip: If you use Emby or Jellyfin, connect Trakt too. Even if you don’t scrobble to Trakt, CW can use it as an ID fallback.

Quick start (recommended)

1

Connect providers

1. Connect a media server (Plex/Emby/Jellyfin).

2. Connect one or more targets (Trakt/SIMKL/MDBList).

3. If needed, create provider profiles.

2

Create routes

1. Open Settings → Scrobble → Watcher.

2. Add one route per mapping you want. Example: Plex → Trakt, Plex → SIMKL, Jellyfin → MDBList.

3. Pick provider and sink profiles when needed.

3

Enable Watcher and test

1. Enable Watcher.

2. Optional: enable Autostart.

3. Click the red Save button.

4. Play one title and confirm progress appears.

Route fields (what they mean)

Routes usually include:

• Enabled: turns a route on/off.

• Provider: Plex, Emby, Jellyfin.

• Provider profile: default or PLEX-P01, etc.

• Sink: Trakt, SIMKL, MDBList.

• Sink profile: default or TRAKT-P01, etc.

• Filters: per-route scrobble restrictions.

A route is identified by:

provider + provider_instance + sink + sink_instance

Avoid duplicates unless you want double-scrobbles.

Options

• Auto-remove from Watchlist: removes completed movies from watchlists.

• Ratings (Plex only): require ratings webhook helper added in Plex.

Webhook tokens (helper endpoints)

Watcher itself does not need inbound webhooks.

One exception is Plex ratings, which uses:

• POST /webhook/plexwatcher?uniqueID

This URL token is generated by CrossWatch.

If you rotate tokens in Settings → Scrobble → Watcher, the old URL stops working.

Update the webhook URL in Plex after rotating.

Filters

• Username whitelist: only scrobble listed users.

  • Supports id:<accountID> or uuid:<accountUUID>.

• Server UUID (Plex only): restrict to one server.

• User UUID (Emby/Jellyfin): restrict to one user.

Migration from legacy Watcher config

Before v0.9.0, Watcher used scrobble.watch.provider + scrobble.watch.sink.

Starting with v0.9.0, CrossWatch auto-migrates that into routes.

Use this checklist:

• Migrate to routes mode

Advanced

Playback event tuning

Pause debounce (sec) (default 5)

• Ignores rapid duplicate pause events.

• Config: scrobble.watch.pause_debounce_seconds

Suppress start @ (%) (default 99)

• Skips “start” events near the end of a title.

• Config: scrobble.watch.suppress_start_at

Regress tolerance (%) (default 5)

• Clamps progress backwards jumps (seek glitches).

• Config: scrobble.trakt.regress_tolerance_percent

Progress step (%) (default 25, range 1–25)

• Minimum progress delta before CW sends an update to sinks (trackers).

• Higher values = fewer progress updates, thus fewer API calls.

• Lower values = frequent progress updates, higher API calls.

• Example: a 60 min movie.

  • 1% ≈ 100 API calls

  • 5% ≈ 20 API calls

  • 25% ≈ 4 API calls

Stop pause threshold (%) (default 80)

• Treat STOP below this threshold as PAUSE.

• Config: scrobble.trakt.stop_pause_threshold

Force stop @ (%) (default 80)

• Treat STOP at/above this as completed.

• Config: scrobble.trakt.force_stop_at

Troubleshooting quick checks

• Nothing scrobbles: confirm Watcher is enabled and you clicked Save.

• Wrong user: tighten Username whitelist / User UUID filters.

• Wrong server (Plex): set Server UUID.

• Missing matches: add TMDb metadata: Metadata

• Slow updates: lower progress step, but expect more API calls.

Related topics

• Scrobble overview: Scrobble

• Pick Watcher vs legacy webhooks: Webhook or Watcher

• Improve matching quality: Metadata

• Legacy inbound endpoints: Webhooks (legacy)

Summary

Watcher scrobbles in real time.

Routes mode supports multiple sources and sinks.

Use profiles to scrobble multiple accounts or servers.

Use filters if you share servers with other users.

Next steps

• Decide Watcher vs legacy webhook mode: Webhook or Watcher

• Limit which libraries generate scrobbles: Library Whitelisting

• Put CW behind TLS and a proxy (recommended for remote): Reverse proxies

• Show “Now Playing” in the footer: Playing Card