> 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

Watcher does real-time scrobbling in CW.

It reads playback from your media server and pushes progress to trackers.

You can run multiple media servers and trackers together.

{% hint style="success" %}
Watcher is the preferred real-time scrobble path for most setups.
{% endhint %}

### Watcher

Monitor Plex, Jellyfin, or Emby playback from CrossWatch. Send real-time scrobbles to Trakt, SIMKL, or MDBList.

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

### Before you start

1. Connect a Plex, Jellyfin, or Emby profile in **Settings → Connections**.
2. Connect a Trakt, SIMKL, or MDBList profile.
3. Confirm CrossWatch 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="/files/bR7sJeb81NEoyrIjXldO" alt=""><figcaption></figcaption></figure>

### Add a Watcher route

1. Open **Settings → Scrobbler**.
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 media server profile to one tracker profile:

`media server profile → tracker 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**.

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

Route options override global settings:

* **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.

### 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

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)
  {% 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.