> 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.md).

# Scrobbler

Configure real-time playback scrobbling between supported media servers, clients, and trackers.

Configure real-time playback scrobbling between supported media servers, media clients, and trackers.

CrossWatch routes playback activity from a source profile to supported destinations.

{% 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="info" %}
Use Watcher for media servers you own or control. It supports flexible routing without Plex Pass or Emby Premiere.
{% endhint %}

CrossWatch supports two event sources:

* **Watcher** reads playback activity directly from supported sources.
* **Webhooks** receive playback activity through a generated CrossWatch URL.

Watcher and Webhooks can run together for separate routes. Do not send the same playback activity through both methods to the same destination.

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

### What Scrobbler does

Scrobbler processes playback activity while you watch. Depending on the route, it sends playback start, progress, pause, stop, watched status, and supported rewatches.

Plex ratings use a separate ratings webhook. Use synchronization for history backfills, watchlists, ratings, collections, and periodic alignment.

### Supported sources and destinations

Watcher supports Plex, Jellyfin, Emby, Silo, Tofa, Kodi, Scrob, and Stremio through the experimental CrossWatch add-on. Webhooks support Plex, Jellyfin, and Emby.

Tracker and local destinations include Trakt, SIMKL, MDBList, BingeBase, PunchPlay, Scrob, WeTrakr, AniList, and CW Tracker. Media server destinations include Plex, Jellyfin, Emby, Kodi, Silo, and Tofa.

AniList requires **Anime ID Mapping**. The exact source profile cannot be its own destination.

Connect profiles in **Settings → Connections** before creating routes.

### Recommended first setup

1. Connect one playback source and one destination.
2. Open **Settings → Scrobbler** and select **Add watcher**.
3. Choose the source and destination profiles.
4. Leave optional filters at their defaults.
5. Save the route and enable **Autostart** if required.
6. Start playback and check **Recent Activity** or **Logs**.

Add filters and additional routes after the first route works.

### Watcher or Webhooks

Use **Watcher** for most installations. It reads playback through the configured connection and supports profiles, filters, and media-server destinations.

Use **Webhooks** when the media server should send events to CrossWatch. Normal Watcher playback does not require Plex Pass or Emby Premiere.

{% 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 %}

{% hint style="warning" %}
Do not configure both methods for the same playback session and destination. Duplicate or competing events can result.
{% endhint %}

### Routes and filters

Each Watcher entry is a route between source and destination profiles. Create one route for every destination.

Examples:

* `Plex Home → Trakt Personal`
* `Jellyfin Default → Plex Default`
* `Plex Anime → AniList Personal`

Routes support profiles of the same provider. CrossWatch blocks routes back to their own source profile.

Filters decide whether a route accepts playback. They can include usernames, Plex Server UUID rules, Live TV and DVR exclusion, and **Ignore specials**. Ignoring specials excludes Season 0 playback.

Kodi uses its configured source-path whitelist instead of Plex route filters. Empty route filters accept supported source playback, subject to connection library restrictions.

### Libraries and copies

Connection whitelists limit source libraries before CrossWatch sends an event. An empty source whitelist allows all supported libraries.

Plex, Jellyfin, Emby, Kodi, Silo, and Tofa destinations expose a **Libraries** section. It controls destination libraries CrossWatch may update. If empty, the destination connection whitelist applies.

**Update all copies** is enabled by default. Where supported, it updates every matching movie or episode copy with the same watched date. Tofa uses the default edition instead; see [Destination Library](https://wiki.crosswatch.app/crosswatch/settings/scrobbler/destination-library.md).

### Anime mapping and rewatches

Enable **Anime ID Mapping** when normal provider IDs cannot match reliably. It is required for AniList and can improve SIMKL and CW Tracker routing.

CW Tracker offers **Track rewatches** on Watcher routes and webhook destinations. It is off by default, with a **12-hour** duplicate window adjustable from **1 to 168 hours**. See [rewatch setup](https://wiki.crosswatch.app/crosswatch/settings/scrobbler/webhooks.md#track-rewatches).

SIMKL supports explicit rewatches. It requires SIMKL Pro or VIP, is disabled by default, uses duplicate protection, and requires a 48-hour gap. The normal watched threshold applies, with an 80% minimum for rewatches.

### Related guides

* [Watcher](https://wiki.crosswatch.app/crosswatch/settings/scrobbler/watcher.md)
* [Webhooks](https://wiki.crosswatch.app/crosswatch/settings/scrobbler/webhooks.md)
* [Webhook or Watcher](https://wiki.crosswatch.app/crosswatch/settings/scrobbler/webhook-or-watcher.md)
* [Filters](https://wiki.crosswatch.app/crosswatch/settings/scrobbler/filters.md)
* [Recent Activity](https://wiki.crosswatch.app/crosswatch/settings/scrobbler/recent-activity.md)
  {% endtab %}

{% tab title="Power users" %}

### The Scrobbler page

Open **Settings → Scrobbler**. The page lists Watcher routes, webhook mappings, defaults, and runtime controls.

The summary shows configured and enabled routes, active webhook mappings, Watcher state, active sources and destinations, and runtime errors.

### Watcher routes and runtime

Each route has its own source profile, destination profile, enabled state, filters, options, libraries, and applicable Plex rating settings. CrossWatch assigns route IDs such as `R1`. Exact duplicate routes cannot be saved.

CrossWatch groups enabled routes by source provider and profile. Each playback event is evaluated independently for every route. A route requires an enabled route, running Watcher, active source, passing filters, and an available destination.

**Start** loads enabled saved routes and clears stale watching state. **Stop** stops active groups. **Reload** rebuilds groups from saved routes. **Autostart** starts enabled routes when CrossWatch starts.

### Global Watcher defaults

Routes can inherit global settings or override supported values:

* **Auto remove from Watchlists** removes completed movies from compatible watchlists.
* **Watched threshold** defaults to `90` and accepts `0`–`100`.
* **Final stop trust** defaults to `95` and accepts `0`–`100`.
* **Pause debounce** defaults to `5` seconds and accepts `0`–`3600`.
* **Suppress start** defaults to `99` and accepts `0`–`100`.
* **Progress step (%)** defaults to `25` and accepts `15`–`50`.

Lower progress steps send more watching updates and use more API capacity; higher steps reduce updates. This applies to CW Tracker as well as external destinations. Playback transitions such as pause and stop are handled separately. Progress step does not change the watched threshold or the source polling interval.

### Delivery and matching

Watcher normalizes playback into `start`, `pause`, and `stop`. It tracks progress, suppresses duplicates, tolerates small regressions, and applies completion policy before delivery.

One source can feed several destinations. A failure on one destination does not block the others. Failed deliveries can retry without blocking incoming playback.

Media-server destinations support progress and watched updates, destination libraries, update-all-copies, and provider-specific matching.

Plex resolves the active session user before applying username filters. **Unresolved user fallback** is disabled by default. Enable it only when the Plex token cannot read session users.

**PlexKodiConnect compatibility** is experimental and disabled by default. Enable it for Kodi playback originating from PlexKodiConnect.

### Plex ratings and Webhooks

Playback and Plex ratings use separate event flows. Normal Plex Watcher playback needs no inbound webhook. Rating changes require a Plex ratings webhook.

Use the global ratings webhook for shared rating destinations. Use a route-specific webhook for one route's destination set. These destination sets are additive. Regenerating a ratings URL invalidates its previous URL.

Webhook mappings link Plex, Jellyfin, or Emby source profiles to destination profiles. Their states include **Connected**, **Needs setup**, and **Disabled**. Use current profile-based URLs, not legacy URLs.

After testing a current webhook URL, select **Remove legacy URLs** and remove old server URLs.

{% hint style="danger" %}
Legacy URL cleanup is permanent. Removed legacy tokens cannot be recreated.
{% endhint %}

### Troubleshooting

Check routes in this order:

1. Confirm connected and enabled source and destination profiles.
2. Confirm Watcher is running and source filters or library restrictions allow playback.
3. Check destination libraries, provider IDs, and Anime ID Mapping.
4. Review watched threshold, final stop trust, and suppress start.
5. Check for an overlapping Watcher or Webhook route.
6. Review Watcher and destination logs.

If no progress is sent, check **Progress step**. If media updates the wrong library, check route libraries and then the destination connection whitelist. If only one copy updates, enable **Update all copies**.

For AniList, confirm Anime ID Mapping and configured anime metadata. For SIMKL rewatches, confirm Pro or VIP, enabled tracking, the watched threshold, and the rewatch gap.

### Related pages

* [Watcher](https://wiki.crosswatch.app/crosswatch/settings/scrobbler/watcher.md)
* [Webhooks](https://wiki.crosswatch.app/crosswatch/settings/scrobbler/webhooks.md)
* [Filters](https://wiki.crosswatch.app/crosswatch/settings/scrobbler/filters.md)
* [Recent Activity](https://wiki.crosswatch.app/crosswatch/settings/scrobbler/recent-activity.md)
* [Anime ID Mapping](https://wiki.crosswatch.app/crosswatch/settings/connections/metadata/anime-id-mapping.md)
* [Kodi](https://wiki.crosswatch.app/crosswatch/settings/connections/media-clients/kodi.md)
  {% endtab %}
  {% endtabs %}

### Destination accounts and results

Each route sends supported playback and rating updates to its selected destination account. If that account is missing, CrossWatch does not fall back to the provider's default account. Reconnect or correct the destination on the route, then save it.

Use **Tools → Events** to inspect the recorded destination and failed scrobbles. Supported rating updates are also recorded there. A tracker connection is not required for a route between supported media servers.


---

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