Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Scrob

Connect your self hosted Scrob instance to CW.

Scrob can be used as both a source and a target in CW synchronization pairs.

Scrob support is experimental. Functionality may change as the integration improves.

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.

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:

The Scrob API key is sent using:

After login, CW also uses the Scrob access token:

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:

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:

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:

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:

Scrob API Documentation

Scrob provides its own OpenAPI documentation.

On a standard Scrob installation:

provides Swagger UI.

PreviousPunchPlay
NextSIMKL

Last updated

Was this helpful?