> 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/connections/trackers/scrob.md). # Scrob {% tabs %} {% tab title="End users" %}
Connect your self hosted [Scrob](https://github.com/ellite/scrob) instance to CW. Scrob can be used as both a source and a target in CW synchronization pairs. {% hint style="warning" %} **Scrob support is experimental.** Functionality may change as the integration improves. {% endhint %} ### What it supports | Feature | Support | | --------- | ---------------------------------------- | | Watchlist | Movies and shows | | Ratings | Movies, shows, seasons, and episodes | | History | Movies and episodes, including rewatches | | Progress | Movies and episodes | | Watcher | Source and sink | All supported features can be synchronized from or to Scrob. ### Connect Scrob Open **Settings** → **Connections** → **Trackers** → **Scrob**. Enter: * **Server URL** — the URL of your Scrob instance, such as `http://192.168.1.100:7330`. * **API Key** — your Scrob API key. * **Username** — your Scrob username. * **Password** — your Scrob password. If your account uses two-factor authentication, enter the current six-digit code. Select **Connect**. When CW reports **Connected**, save your settings. ### Using Scrob After connecting, select Scrob as a source or target when creating synchronization pairs. Examples include: `Trakt → Scrob` `Scrob → Trakt` `Plex → Scrob` Enable the features supported by both providers. For a first sync, use one-way sync, one feature at a time, and **Dry Run**. Enable writes or two-way synchronization after reviewing the result. Select Scrob as a **Watcher** source or destination for real-time playback. Watcher routes support Scrob as either a source or a sink. Webhook mappings support Scrob only as a sink. ### Playback progress Progress is a normal CW sync feature. It works like Watchlist, Ratings, and History. CW synchronizes existing playback positions with providers that support Progress. Scrob keeps Continue Watching progress between `5%` and `90%`. ### Watcher Scrob participates in CW Watcher routes. When Scrob is a source, CW reads its active playback sessions. When Scrob is a destination, CW sends playback activity to it. Use **Sync** for stored Watchlist, Ratings, History, and Progress data. Use **Watcher** for active playback and real-time scrobbling. {% endtab %} {% tab title="Power users" %} ## Power users Scrob is implemented as a native CW provider. The integration currently has experimental status. ### Architecture Scrob can operate in three CW roles: 1. **Sync provider** 2. **Watcher source** 3. **Scrobble sink** The sync adapter is bidirectional and can therefore be selected on either side of a CW sync pair. In Watcher routes, Scrob can be a source or a sink. In webhook mappings, Scrob can only be a sink. ### Sync Capabilities #### Watchlist Supported media: * Movies * Shows CW maps the Scrob watchlist to a Scrob personal list named: `Watchlist` If this list does not exist when CW needs to write to it, CW creates it as a private list. The list name can be overridden using: `watchlist_name` Supported operations: * Read * Add * Remove #### Ratings Supported media: * Movies * Shows * Seasons * Episodes Rating scale: `1 to 10` CW supports reading, creating, updating and removing ratings. Episode ratings require the episode to already be resolvable by Scrob. #### History Supported media: * Movies * Episodes Scrob stores individual play events rather than only a single watched state. CW therefore preserves: * Individual `watched_at` timestamps * Multiple plays of the same title * Rewatches * History additions * History removals This allows Scrob to operate as both a history source and a history target without reducing multiple plays to a single watched flag. #### Progress Supported media: * Movies * Episodes Progress is implemented as a native CW sync feature. It participates in normal sync pairs alongside Watchlist, Ratings and History. Supported operations: * Read progress from Scrob * Add or update progress in Scrob * Remove progress from Scrob * One way synchronization * Two way synchronization CW reads Scrob Continue Watching state and converts it into the normal CW progress model. When writing progress to Scrob, CW requires: * A supported media identifier * Playback duration * Playback percentage Scrob keeps Continue Watching progress above `5%` and below `90%`. Progress outside that range is not written as an active resume position. This Progress sync functionality is separate from CW Watcher and Scrobbler functionality. The **Progress** tab in a sync pair controls synchronization of stored playback progress between providers. ### IDs and Matching The Scrob sync adapter primarily uses TMDB identifiers. Movies and shows normally require a TMDB ID. Episode operations also use show context, including: * Show TMDB ID * Season number * Episode number TVDB and IMDb identifiers can also be used by some playback paths when available. For reliable synchronization, configure metadata resolution in CW so missing identifiers can be resolved before data reaches the Scrob adapter. ### Authentication CW stores the Scrob connection information per provider instance. Required configuration: ``` server_url api_key username password ``` The Scrob API key is sent using: ```http X-Api-Key ``` After login, CW also uses the Scrob access token: ```http Authorization: Bearer ``` CW refreshes the Scrob login when the stored access token expires. ### Two Factor Authentication TOTP based two factor authentication is supported. When Scrob requests two factor authentication, CW asks for the current 6 digit TOTP code and completes the login flow. CW can also request a new code when reauthentication is required later. ### OIDC Only Installations The current CW integration authenticates to Scrob using the Scrob username and password flow. If password login has been disabled on the Scrob server and the installation only allows OIDC authentication, CW cannot currently establish the required Scrob session. ### API Detection CW automatically checks the Scrob API using: ``` / ``` and: ``` /api/proxy ``` Normally this does not need to be configured manually. The configured Server URL must be reachable from the CW container, not only from your browser. For example, if both applications run on the same Docker network, an internal container hostname can be used. Otherwise use a reachable LAN address or reverse proxy URL. ### SSL Verification CW provides a **Verify SSL** option for Scrob. Enable this when Scrob is exposed through HTTPS using a certificate trusted by the CW container. Private installations using self signed certificates may fail verification unless the certificate chain is trusted by the CW container. ### Scrob as a Watcher Source Scrob can be selected as a CW Watcher source. CW reads active playback sessions from the Scrob Now Playing API. These sessions are converted into normal CW playback events: * Start * Pause * Resume * Progress * Stop The resulting events can then be routed to compatible CW scrobble targets. For example: ``` Scrob → Trakt Scrob → SIMKL Scrob → MDBList ``` The Scrob watcher uses polling to detect playback state and automatically backs off when the Scrob server becomes unavailable. CW also identifies sessions created by CW itself to prevent Scrob routes from immediately returning through Scrob and creating a playback loop. ### Scrob as a Scrobble Sink Scrob can also be selected as the destination of a Watcher route. For example: ``` Plex → Scrob Jellyfin → Scrob Emby → Scrob ``` CW converts its internal playback events into the playback webhook format understood by Scrob. This allows start, pause, resume, progress and stop activity to update Scrob without waiting for a normal sync run. When the configured watched threshold is reached, the final stop event can also result in a completed play in Scrob history. ### Sync Versus Watcher Sync and Watcher solve different problems. Use **Sync** for: * Watchlist * Ratings * Historical plays * Playback Progress * Existing Continue Watching state * Backfills * Periodic reconciliation Use **Watcher** for: * Active playback * Real time playback state * New completed plays * Scrobbling between providers A common setup is therefore: ``` Initial Sync ↓ Periodic Sync + Watcher for active playback ``` ### Scrob API Documentation Scrob provides its own OpenAPI documentation. On a standard Scrob installation: ``` https:///docs ``` provides Swagger UI. ``` https:///redoc ``` {% 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/connections/trackers/scrob.md?ask=&goal= ``` `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.