> 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="danger" %}
Do **not** use CrossWatch Watcher or Webhooks with another plugin or application that scrobbles the same playback to the same provider. This can create duplicate or conflicting writes.

If you have issues, contact CrossWatch support. Do not contact the provider.
{% endhint %}

{% hint style="danger" %}
Do not use Watcher with remote servers or servers you do not own.

Watcher stays connected to your media server while running and can generate more traffic than Webhooks. Use Webhooks when available.
{% endhint %}

### Watcher

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

### Before you start

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

Only connected instances 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 **Settings → Scrobbler → Watcher**.
2. Select **Add watcher**.
3. Select the source provider and instance.
4. Select the destination tracker and instance.
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 instance to one sink instance:

`source instance → sink instance`

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

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

### Silo routes

To include playback from [other Silo accounts](https://wiki.crosswatch.app/crosswatch/settings/connections/media-servers/silo.md#other-silo-accounts), first select and save their profiles on the Silo connection's **Identities** tab. Then enable **Identities** on the Watcher route's **Route** tab, link each person to the destination identity and save. Only linked identities are included; selecting an Account identity on the connection alone is not enough.

### Tofa routes

Tofa can be a source or destination. Select the household profile on the connection, or enable **Identities** on the route to link selected household profiles or [shared users](https://wiki.crosswatch.app/crosswatch/settings/connections/media-servers/tofa.md#shared-users). If Tofa reports a play without a profile, CrossWatch can route it only to that user's selected primary profile.

The route's **Options** shows Tofa's watched rule. A lower route threshold may mark the destination watched before Tofa; a completion confirmed by Tofa during playback can be forwarded even with a higher route threshold. Use **Apply 90% to Tofa** (with your chosen percentage) to align the rules. Tofa supports 70–95% in steps of 5.

Destination items must exist in a selected Tofa library. Resume writes need a known runtime and at least one minute of progress; an active Tofa session is protected from incoming writes. See [Tofa setup](https://wiki.crosswatch.app/crosswatch/settings/connections/media-servers/tofa.md).

### Filters and options

Filters decide whether a route accepts playback. Available filters include a username whitelist, Plex Server UUID allowlist or blocklist, and Live TV filtering. **Ignore Plex Live TV & DVR** on Plex and **Ignore Live TV** on Jellyfin/Emby are on by default; an explicit off setting is retained. See [Filters](https://wiki.crosswatch.app/crosswatch/settings/scrobbler/filters.md#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 instance. See [Filters](https://wiki.crosswatch.app/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 (%)** — 15 to 50; global default: 25.\
  Sets the percentage-point change used to limit repeated watching updates. Lower values send more updates and use more API calls; higher values send fewer. Leave the route field blank to inherit the global value. Pause and stop handling is separate, and the watched threshold is unchanged.
* **Poll interval** — 5 to 60 seconds; global default: 10.\
  Controls how often Watcher checks Emby, Jellyfin, Kodi, and Scrob while playback is active.
* **Idle poll interval** — 5 to 120 seconds; global default: 30.\
  Controls how often Watcher checks those sources when nothing is playing.
* **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.

  This covers new watches only. To also fill in existing history on Jellyfin, turn on [**Update all copies**](https://wiki.crosswatch.app/crosswatch/settings/configure-pairs/features/history.md#update-all-copies-jellyfin) in the pair's History options.
* **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**

  Available for **CrossWatch** and **SIMKL** destinations; off by default. For CrossWatch, enable it to save separate completed plays. **Rewatch window (h)** defaults to **12**, accepts **1–168**, and is used only when rewatches are enabled. A repeat of the same movie or episode within that window counts as the same play and appears as skipped in Events. With rewatches off, a newer watch updates that title’s latest play while preserving older plays.

  SIMKL requires Pro or VIP and a 48-hour gap per movie or episode. Its configured watched threshold still applies, with a minimum of 80% for rewatches.

  These route controls are separate from the **Rewatches** option in History sync pairs.

Routes that share a source and instance use one watcher. The lowest configured poll interval wins. Playback starts, pauses, and stops are detected within one interval. Higher values reduce API load but delay detection.

### Detect manually marked watches

In the route's **Options**, **Detect manual marks** sends items you mark played by hand as watched events. It is available for Plex, Jellyfin, Emby, Silo, and Tofa sources and is on by default. Turn it off if you only want playback sessions sent to the destination.

Detection runs at the idle poll interval, capped at 30 seconds. Watcher must be running. The first successful read establishes a baseline; it does not import old watched items. Use History synchronization for a backfill.

Unmarking an item is not sent. On Plex, detection covers only the account associated with the connected token. Route filters still apply. CrossWatch checks recent playback and its own writes to avoid sending the same completion again.

### 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 instance are running.
* Confirm the destination instance 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 instance, or overlapping Plex ratings URLs.
{% endtab %}

{% tab title="Power users" %}

### Runtime model

CrossWatch groups enabled routes by source provider and instance.

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 instances, enabled state, filters, auto-remove behavior, completion overrides, and Plex ratings configuration.

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

#### 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**, then select the configured rating destinations you need. See [Plex rating support](https://wiki.crosswatch.app/crosswatch/settings/scrobbler/webhooks.md#rating-support-varies) for supported providers and media types.

Check **Tools → Events → Watching & ratings** for results per destination. An enabled destination that cannot accept episode ratings records **Skipped** with an explanation; other destinations can still receive the rating.

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

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

### 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](https://wiki.crosswatch.app/crosswatch/settings/scrobbler.md)
* [Webhook or Watcher](https://wiki.crosswatch.app/crosswatch/settings/scrobbler/webhook-or-watcher.md)
* [Webhooks](https://wiki.crosswatch.app/crosswatch/settings/scrobbler/webhooks.md)
* [Filters](https://wiki.crosswatch.app/crosswatch/settings/scrobbler/filters.md)
* [Kodi](https://wiki.crosswatch.app/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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
