> 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 from Plex, Jellyfin, or Emby.

CrossWatch sends activity to Trakt, SIMKL, or MDBList while you watch.

{% hint style="success" %}
Use Watcher for most new setups.
{% endhint %}

CrossWatch supports two event sources:

* **Watcher** reads playback activity from the media server.
* **Webhooks** receive activity at a generated CrossWatch URL.

Watcher suits most installations. Webhooks remain fully supported.

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

<figure><img src="/files/BVGgn3Ri6uziEWT0YFEC" alt=""><figcaption></figcaption></figure>

### What Scrobbler does

Scrobbler processes playback activity as you watch.

It can send playback start, progress, pause, stop, and completion.

Plex ratings can also sync when enabled separately.

Use synchronization for history backfills and periodic alignment.

### Supported providers

**Media server sources**

* Plex
* Jellyfin
* Emby

**Tracker destinations**

* Trakt
* SIMKL
* MDBList

Connect both profiles under **Settings → Connections** before continuing.

### Recommended first setup

1. Connect one media server profile.
2. Connect one tracker profile.
3. Open **Settings → Scrobbler**.
4. Select **Add watcher**.
5. Choose the source and destination profiles.
6. Leave **Filters** empty for the first test.
7. Save the route.
8. Enable **Autostart** if needed.
9. Start playback.
10. Confirm the tracker receives activity.

Add filters and routes after the first successful test.

### Choose an event source

Use **Watcher** unless you specifically prefer server-delivered events.

See [Webhook or Watcher](/crosswatch/settings/scrobbler/webhook-or-watcher.md) for guidance.

{% hint style="warning" %}
Do not send identical playback activity through both sources.

It can create duplicate or competing scrobbles.
{% endhint %}

### Related guides

* [Watcher](/crosswatch/settings/scrobbler/watcher.md)
* [Webhooks](/crosswatch/settings/scrobbler/webhooks.md)
* [Recent Activity](/crosswatch/settings/scrobbler/recent-activity.md)
  {% endtab %}

{% tab title="Power users" %}

### The Scrobbler page

Open **Settings → Scrobbler**.

#### Summary

The summary shows active webhooks, enabled Watcher routes, and Watcher status.

#### Webhooks

Each card represents one mapping:

`media server profile → tracker profile`

Cards show the source, destination, endpoint status, and available actions.

Possible statuses are:

* **Connected** — the mapping is active.
* **Needs setup** — part of the mapping is no longer configured.
* **Disabled** — the webhook source profile is disabled.

#### Watcher routes

Each card represents one route:

`media server profile → tracker profile`

Cards show the source, destination, route ID, filters, enabled state, and runtime state.

Identical routes are not allowed. Source and destination providers and profiles must differ.

#### Watcher status

This section shows running and configured routes, Autostart, active sources and destinations, and runtime errors.

Use **Start**, **Stop**, or **Reload** to control Watcher.

Reload restarts groups from the saved route configuration.

#### Defaults

Defaults only appear when relevant:

* Watcher defaults require an enabled Watcher route.
* Webhook defaults require an enabled webhook.
* Plex ratings require an enabled Plex Watcher route.

### Entry-driven configuration

Scrobbler has no global mode selector.

An enabled Watcher route activates Watcher. An enabled webhook mapping activates Webhooks.

Removing or disabling the final entry deactivates that source.

Use **Save changes**, a toggle, or a Scrobbler control to save. Entries do not use the old global save flow.

### Using Watcher and Webhooks together

Both sources can run together when their responsibilities are separate.

For example:

* Watcher: Plex profile A → Trakt profile A
* Webhook: Jellyfin profile B → SIMKL profile B

Review [Webhook or Watcher](/crosswatch/settings/scrobbler/webhook-or-watcher.md) before enabling both.

### Global defaults

#### Watcher defaults

**Auto remove from Watchlists** removes completed movies from compatible watchlists.

Each route can inherit the global value or force it on or off.

**Pause debounce seconds** defaults to `5`. Repeated pauses inside this period are ignored.

**Suppress start percent** defaults to `99`. Starts at or above this progress are ignored.

#### Webhook defaults

**Pause debounce seconds** defaults to `5`.

**Suppress start percent** defaults to `99`.

Mappings inherit these values unless their source profile overrides them.

### Plex ratings

Playback scrobbling and Plex ratings use separate event flows.

#### Global ratings webhook

Use the global webhook when enabled Plex Watcher routes share rating destinations.

Select Trakt, SIMKL, MDBList, or any combination. Then copy the generated URL into Plex.

#### Route-specific ratings webhook

Use a route-specific webhook when one route needs different destinations.

Global and route-specific ratings are additive. Avoid the same destination in both paths.

Regenerating a ratings URL invalidates the previous URL.

### Legacy webhook cleanup

Older versions created separate Plex, Jellyfin, and Emby webhook URLs.

After every server uses the new profile URL:

1. Test playback through the new URL.
2. Confirm the correct webhook card activates.
3. Select **Remove legacy URLs**.
4. Remove old URLs from the media server.

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

### Related guides

* [Watcher](/crosswatch/settings/scrobbler/watcher.md)
* [Webhooks](/crosswatch/settings/scrobbler/webhooks.md)
* [Filters](broken://spaces/3rh5THg1PdhVsBt3GALo/pages/PH2jfcZjseHr6sFkoKAP)
  {% 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.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.