> For the complete documentation index, see [llms.txt](https://wiki.crosswatch.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.crosswatch.app/crosswatch/settings/scrobbler/watcher.md).

# Watcher

Real-time scrobbling between supported media servers, trackers, and Scrob.

Watcher does real-time scrobbling in CW.

It reads playback from a source and sends progress to a sink.

You can run multiple media servers and trackers together.

{% hint style="success" %}
Watcher is the preferred real-time scrobble path for most setup but do not use watcher on shared servers.
{% endhint %}

### Watcher

{% tabs %}
{% tab title="End users" %}

### Before you start

1. Connect a source profile in **Settings → Connections**.
2. Connect a sink profile.
3. Confirm CW can reach the media server API.
4. Configure metadata and provider IDs when matching needs improvement.

Only connected profiles appear in route selectors.

<figure><img src="https://565675962-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3rh5THg1PdhVsBt3GALo%2Fuploads%2FbgATHaQncwSdwSexidBE%2Fimage.png?alt=media&amp;token=21e49965-4b89-4444-b5b8-50569d056bd3" alt=""><figcaption></figcaption></figure>

### Add a Watcher route

1. Open **Profile → Watcher**.
2. Select **Add watcher**.
3. Select the source provider and profile.
4. Select the destination tracker and profile.
5. Review **Filters** and **Options**.
6. Configure **Plex Ratings** only when required.
7. Select **Save changes**.
8. Start Watcher or enable **Autostart**.

Each route maps one source profile to one sink profile:

`source profile → sink profile`

CrossWatch assigns route IDs such as `R1`, `R2`, and `R3`.

Exact duplicate routes cannot be saved. Create separate routes for different destination providers or profiles.

### Filters and options

Filters decide whether a route accepts playback. Available filters include a username whitelist, Plex Server UUID allowlist or blocklist, and **Ignore Plex Live TV and DVR**.

Kodi uses its configured source-path whitelist for scrobbling. It does not support Plex-specific route filters.

Empty filters accept all supported playback from the source profile. See [Filters](/crosswatch/settings/scrobbler/filters.md).

Route options override global settings:

<figure><img src="https://565675962-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3rh5THg1PdhVsBt3GALo%2Fuploads%2FijWV61H6an5AybT2buKR%2Fimage.png?alt=media&amp;token=aa528ed0-8d3f-4c0d-ba24-39c79119e4d5" alt=""><figcaption></figcaption></figure>

* **Auto remove from Watchlists** — **Inherit**, **On**, or **Off**.
* **Watched threshold** — 0 to 100; global default: 90.\
  Progress percentage where CrossWatch treats the item as watched/completed. Also affects auto-remove from watchlists.
* **Final stop trust** — 0 to 100; global default: 95.\
  Progress percentage where a final stop event is trusted as a real completion, even if the media server event is a little noisy.
* **Pause debounce** — 0 to 3600 seconds; global default: 5.\
  Ignores very short pause/start noise so tiny playback flaps do not create false pause scrobbles.
* **Suppress start** — 0 to 100; global default: 99.\
  Ignores new start events near the end of playback, usually caused by credits, autoplay, or media server session weirdness.
* **Progress step** — 1 to 25; global default: 25.\
  Controls how frequently progress updates are sent while watching. Leave it at 25, lowering it would provide more frequent updates but significantly increase the number of API calls, while raising it would reduce API usage but make updates less frequent.
* **Unresolved user fallback**\
  When Plex does not include a playback user and CrossWatch cannot resolve one from the active Plex session, this option uses the configured Plex username as the playback user for this route.\
  \
  Leave disabled for strict user filtering. Enable for less strict user filtering especially for trusted single-user, Plex Home, or shared-server setups where Plex session user lookup is unavailable.
* **Anime ID Mapping**\
  For specific sinks (such as CW and SIMKL) you can enable Anime ID mapping for improved Anime matching. This require that Anime ID mappings in Connections/metadata is enabled.
* **Update all copies**

  When enabled, CrossWatch updates all matching copies of the same media item on Plex, Jellyfin, Emby and Kodi scrobble destinations, instead of updating only the first match found. This option is enabled by default.
* **PlexKodiConnect compatibility**

  When enabled, CrossWatch recognizes Kodi playback that originates from PlexKodiConnect and resolves it as Plex backed media. This improves ID matching and prevents playback from being missed or incorrectly matched during scrobbling.
* **Track rewatches**

  Availabe for providers that support rewatches through their scrobble endpoint. At time of writen, only SIMKL has rewatches support through scrobble. Be carefull with this option. Default is disabled. The integration applies a 48 hour gap per movie or episode. The configured watched threshold still applies, with a minimum of 80% for this rewatch behavior.

### Watcher status

Status shows running and configured route counts, Autostart, active providers, and runtime errors.

**Start** starts enabled saved routes and clears stale currently-watching state.

**Stop** stops every active group. No Watcher playback is processed while stopped.

**Reload** rebuilds groups from saved routes. Use it after connection changes.

Autostart starts saved enabled routes when CrossWatch starts.

### Troubleshooting

#### Route is enabled but not running

* Confirm Watcher and the source profile are running.
* Confirm the destination profile is connected.
* Select **Reload** and review CrossWatch logs.

#### Playback is detected but not sent

* Clear filters temporarily.
* Check the selected user, Plex Server UUID, library filtering, and provider IDs.
* Confirm destination authentication.

#### Completion or duplication is wrong

Review **Watched threshold**, **Final stop trust**, and **Suppress start**.

Check for a matching webhook, another route to the same tracker profile, or overlapping Plex ratings URLs.
{% endtab %}

{% tab title="Power users" %}

### Runtime model

CrossWatch groups enabled routes by source provider and profile.

For example, three Plex Home routes share one Plex watcher group. Each event is evaluated and dispatched independently per route.

A route runs only when it is enabled, Watcher is started, its source group runs, and its destination is valid.

### Route modal

Each route has its own profiles, enabled state, filters, auto-remove behavior, completion overrides, and Plex ratings configuration.

The duplicate check uses source provider and profile plus destination provider and profile.

#### Plex ratings

Normal playback requires no inbound webhook. Plex ratings require a ratings webhook because rating changes are not playback events.

Choose **Off** or **Custom route webhook**. Select Trakt, SIMKL, MDBList, or any combination.

The route URL is generated after saving. Use a custom route webhook only for a different destination set.

### Global Watcher defaults

**Auto remove from Watchlists** controls routes using **Inherit**.

**Watched threshold** ranges from `0` to `100` and defaults to `90`. It marks items watched or completed at this progress. It also affects automatic watchlist removal.

**Final stop trust** ranges from `0` to `100` and defaults to `95`. It trusts final stop events at this progress, even with minor media-server noise.

**Pause debounce** ranges from `0` to `3600` seconds and defaults to `5`. It ignores brief pause and start noise, preventing false pause scrobbles.

**Suppress start** ranges from `0` to `100` and defaults to `99`. It ignores new starts near playback completion, including credits, autoplay, and media-server session anomalies.

Watcher normalizes activity into `start`, `pause`, and `stop`. It supports movies and episodes.

CrossWatch suppresses duplicate actions, tolerates small progress regressions, and applies watched-threshold and final-stop handling.

### Multiple routes and conflicts

Create one route per destination:

* Plex Home → Trakt Personal
* Plex Home → SIMKL Personal
* Plex Home → MDBList Personal
* Plex Home → BingeBase Personal

Use username whitelists to route shared-server users to separate tracker profiles.

Avoid near-duplicate routes that target one tracker profile during simultaneous playback. Do not also configure a webhook for the same source and tracker profiles.

### Plex ratings URLs

Use the global ratings webhook when all Plex routes share destinations.

Use the route **Ratings** tab when a route needs custom destinations. Global and route-specific destinations are additive.

Do not send the same rating through both URLs. Regenerating a URL invalidates the old URL.

### Related pages

* [Scrobbler](/crosswatch/settings/scrobbler.md)
* [Webhook or Watcher](/crosswatch/settings/scrobbler/webhook-or-watcher.md)
* [Webhooks](/crosswatch/settings/scrobbler/webhooks.md)
* [Filters](/crosswatch/settings/scrobbler/filters.md)
* [Kodi](/crosswatch/settings/connections/media-clients/kodi.md)
  {% endtab %}
  {% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://wiki.crosswatch.app/crosswatch/settings/scrobbler/watcher.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.