# Scrobble

Scrobbling pushes playback progress while you watch.

It keeps “Up Next” and history in sync across devices.

### What scrobbling sends

Depending on the provider pair, CrossWatch can send:

* **Now playing** updates (progress)
* **Paused** / **Stopped**
* **Completed** when enough is watched

### Prerequisites

* A supported source: Plex, Emby, or Jellyfin.
* A supported target: Trakt, SIMKL, or MDBList.
* Good ID matching (set up [Metadata](/crosswatch/providers/metadata.md)).

{% hint style="info" %}
Prefer the **Watcher** over Webhooks.\
Watcher handles Skip Credits, autoplay, and other edge cases better.
{% endhint %}

### Choose a mode

CrossWatch supports two scrobble modes.

#### Watcher

This is the default and recommended mode.

Use it for Plex, Jellyfin, and Emby.

Why it is better:

* More reliable than legacy webhooks
* Supports multiple routes and profiles
* Handles more playback edge cases
* Does not need Plex Pass or Emby Premiere

Guide: [Watcher](/crosswatch/scrobble/watcher.md).

#### Webhooks (legacy)

This mode is deprecated.

Use it only if you have a specific webhook-based setup you still need.

Limits:

* Legacy only
* Trakt-focused
* More fragile around TLS and proxy setup

Guide: [Webhooks (legacy)](/crosswatch/scrobble/webhooks.md).

{% hint style="warning" %}
You cannot enable **Watcher** and **Webhook** at the same time.
{% endhint %}

### Recommended setup flow

#### 1) Connect providers

Open **Settings → Authentication**.

Connect:

* one media server (source)
* one or more trackers (targets)

Related: [Authentication](/crosswatch/providers/authentication.md)

#### 2) Add metadata (recommended)

Open **Settings → Metadata**.

Add **TMDb**.

Related: [Metadata](/crosswatch/providers/metadata.md)

#### 3) Enable Watcher (recommended)

Open **Settings → Scrobble → Watcher**.

1. Add one or more **routes** (provider → sink mappings).
2. Pick provider and sink **profiles** if needed.
3. Enable **Watcher**.
4. Click the **red Save button**.

#### 4) Validate with one title

Play one movie or episode.

Then verify:

* the tracker shows progress or “Now watching”
* completion is marked after the threshold
* the UI footer updates (optional): [Playing Card](/crosswatch/scrobble/playing-card.md)

### How it works (high level)

1. Detect playback on the source.
2. Resolve the item to stable IDs.
3. Send progress heartbeats.
4. Mark completed after thresholds are met.
5. Retry when the network is flaky.

### What counts as “watched”

* **Completion threshold**: time and/or percent (example: \~80%).
* **Credits handling**: optional grace so skipping credits still completes.
* **Minimum duration**: ignore very short clips unless enabled.

### Settings

Scrobble settings typically include:

* completion threshold
* heartbeat interval
* offline queue and flush
* per-provider enable/disable

### Troubleshooting quick checks

* **Never completes**: lower the threshold or ensure duration is available.
* **Duplicates**: increase heartbeat interval and verify ID mapping.
* **Progress stuck**: the player may not report positions. Prefer Watcher mode.
* **Offline periods**: enable queue/flush and retry.

### Related topics

* Deep dive into routes and filters: [Watcher](/crosswatch/scrobble/watcher.md)
* Legacy webhook setup: [Webhooks (legacy)](/crosswatch/scrobble/webhooks.md)
* Improve matching quality: [Metadata](/crosswatch/providers/metadata.md)
* Show live progress in the UI footer: [Playing Card](/crosswatch/scrobble/playing-card.md)

### Summary

Scrobbling pushes progress and completion in real time.

It’s best for new plays as they happen, not bulk backfills.

Matching quality (IDs) matters as much as playback events.

### Next steps

* Configure sources and sinks: [Watcher](/crosswatch/scrobble/watcher.md)
* Learn the deprecated path (not recommended): [Webhooks (legacy)](/crosswatch/scrobble/webhooks.md)


---

# Agent Instructions: 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:

```
GET https://wiki.crosswatch.app/crosswatch/scrobble.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.