# CrossWatch(CW) Self-hosted sync hub with real-time scrobble (watcher/webhook) and much more.
Website GitHub Support Need to report something? [Bugs](https://github.com/cenodude/CrossWatch/issues) · [Feature requests](https://github.com/cenodude/CrossWatch/issues) {% hint style="info" %} **IMPORTANT:**\ \ If CW shows stale data, modals fail to open, or anything behaves unexpectedly, **refresh the page** Also mark your CW URL as trusted in your browser. This prevents blocked redirects. {% endhint %} ### Providers
### Blueprint
### Quick start * [Installation](/getting-started/installation) * [First-time setup](/getting-started/first-time-setup) * [Connect services](/crosswatch/settings/connections) ### Common tasks * [Configure pairs](/crosswatch/settings/configure-pairs) * [Syncing vs scrobbling](/crosswatch/settings/scrobbler) * [Set up real-time scrobbling](/crosswatch/settings/scrobbler/watcher) * [Debug sync issues](/crosswatch/main-dashboard/tools) # About CrossWatch Self-hosted watchlist, history, ratings, and resume progress sync plus real-time scrobbling CW is a self-hosted **all-in-one tool** for sync, scrobbling, captures, and recovery. It keeps **watchlists**, **history**, **ratings**, and **progress** aligned across your media servers and trackers. Run it in Docker. Keep control of your data. Manage everything from one web UI. {% hint style="success" %} CW is easy to start and flexible enough to grow with your setup. {% endhint %} ### What makes it flexible * Use **profiles**, **pairs**, and **Watcher routes** for multi-account setups. * Improve matching with **TMDb** and **Anime ID Mapping**. * Recover more safely with local state and **captures**. ### Flexible real-time scrobbling **Watcher** uses **routes mode**. Each route maps one media server profile to one tracker profile. That means you can: * send playback from one server to multiple tracker targets * split users or servers into separate routes * run multiple media servers and trackers in one setup ### How it works * **Providers** connect media servers and trackers. * **Profiles** group multiple accounts or servers under one provider. * **Pairs**, **runs**, and local **state** drive sync planning and scheduling. ### Start here * [Installation](/getting-started/installation) * [First-time setup](/getting-started/first-time-setup) * [Configure Pairs](/crosswatch/settings/configure-pairs) # Limitations Soft size guidance, provider plan limits, and request-throttling limits that affect CrossWatch behavior. CrossWatch is **not** built for very large libraries. It is a UI-first tool with metadata enrichment, images, and safety checks. **It is not a bulk-sync engine.** Big libraries create heavy API traffic and large JSON files. {% hint style="warning" %} If your main goal is syncing massive datasets fast, CW is the wrong fit. {% endhint %} ### Size guidance These are **approximate** limits. Provider behavior matters more than hardware. On a normal machine or NAS, overall library size is rarely the first bottleneck. The tighter limits below are about API pressure and JSON file sizes CW recommends these rough upper bounds for normal use: * **Watchlist**: `~2,500` * **History**: `~10,000` * **Ratings**: `~10,000` Lower counts are better. Higher counts may still work, but they are less tested and harder on providers. ### Large `state.json` files CW stores sync state, history data, and provider mappings in `state.json`. This file stays small during normal use. Large histories, watchlists, ratings, or provider datasets can grow it significantly. Large files can slow the Web UI, API responses, and startup after a restart. They also increase memory use while CW reads or rewrites state. Views that scan, filter, or summarize state feel this most. Multiple browser tabs can make the slowdown more noticeable. As a rough guide, `75–100 MB+` may affect responsiveness on systems. Background syncs can still complete successfully. Local state may have grown beyond the size CW currently optimizes for. For large libraries: * Sync history once then use watcher after you cleaned the state through Maintenance ### Provider account limits Some limits come from the provider, not CW itself. If you have large watchlist volumes, disable TMDb enrichment first. ### Provider request limits CW also throttles upstream APIs to reduce `429 Too Many Requests` errors. Default request limits: * **SIMKL**: `10` GET/sec, `1` write/sec * **Nuvio**: `100` GET/sec, `100` write/sec * **MDBList**: `10` GET/sec, `1` write/sec * **PublicMetaDB**: `20` GET/sec, `3` write/sec, plus hourly rating quotas * **Trakt**: `3.33` GET/sec, `1` write/sec Most installs should keep these defaults. Only tune them if you see repeated `429`, temporary `5xx`, or timeout errors. See [Provider rate limiting](/crosswatch/advanced-and-api/rate-limiting-and-retries) for the short version and the full tuning reference. # Installation Choose an installation path for Docker or Unraid. Choose the install path that fits your environment. CrossWatch supports standard Docker setups and Unraid Community Apps. ### Install paths {% columns %} {% column %} #### Installation Use this for standard Docker, Docker Compose, Portainer, or NAS container UIs. [View Installation](/getting-started/installation/docker-setup) {% endcolumn %} {% column %} #### Unraid Apps Use this if you install CrossWatch from the Unraid Community Apps catalog. [View Unraid Apps](/getting-started/installation/unraid-apps) {% endcolumn %} {% endcolumns %} ### Quick guidance Pick **Installation** if you want full control over volumes, ports, and runtime settings. Pick **Unraid Apps** if you want the Unraid template to prefill the container basics. After install, continue with [First-time setup](/getting-started/first-time-setup). # Docker setup Run CW in Docker and persist state by mounting /config. Run CW in Docker. Always persist `/config`. Expose `8787`. Use either a Docker volume or a bind mount for `/config`. Both options work fine. If you use Portainer or a NAS container UI, use these same values. {% hint style="info" %} We do **not** provide support for installing or troubleshooting container runtimes. These pages assume Docker (or your NAS container manager) is already installed and working. If Docker itself is broken, use your platform docs first. {% endhint %} {% hint style="success" %} Fastest path for most users: * use a Docker volume * keep port `8787` * set only `TZ` {% endhint %} {% columns %} {% column %} #### Docker volume Best when you want the simplest setup. Docker manages the storage path. {% endcolumn %} {% column %} #### Bind mount Best when you want a fixed host folder. You manage host permissions yourself. {% endcolumn %} {% endcolumns %} ### Quick start {% stepper %} {% step %} ### Pick storage Choose either a Docker volume or a bind mount for `/config`. Volumes are simpler. {% endstep %} {% step %} ### Start the container Use either the `docker run` or Docker Compose example below. Expose `8787`. {% endstep %} {% step %} ### Open the UI Open `http://localhost:8787`. Continue with [First-time setup](/getting-started/first-time-setup). {% endstep %} {% endstepper %} ### Which should I use? Both options are perfectly fine. Pick the one that fits your setup. Pick a Docker volume if you want: * the simplest setup * Docker to manage storage for you Pick a bind mount if you want: * files in a known host path * a NAS share or fixed folder layout {% hint style="info" %} Quick rule: * Use a Docker volume for simpler Docker-managed storage * Use a bind mount for a specific host folder {% endhint %} {% hint style="warning" %} Bind mounts need correct host permissions. CW must be able to write to the mounted directory. {% endhint %} ### Before you run * Pick one storage type for `/config`. * Docker volume: `crosswatch` * Bind mount: `/srv/crosswatch/config` * Decide which port to expose. * Default UI port: `8787` * Set your timezone. * Example: `TZ=Europe/Amsterdam` {% hint style="warning" %} Do not run without persistent storage on `/config`. You will lose state when the container is recreated. {% endhint %} ### Health check CW exposes `GET /healthz`. Expected response: ```json {"ok":true,"status":"ok"} ``` It returns success when the app is ready. The default examples below stay minimal. If you want container health status, use the separate examples later on this page. ### Option A: Docker volume Create the volume once: ```bash docker volume create crosswatch ``` Run CW: {% tabs %} {% tab title="Docker" %} ```bash docker run -d \ --name crosswatch \ -p 8787:8787 \ -v crosswatch:/config \ -e TZ=Europe/Amsterdam \ --restart unless-stopped \ ghcr.io/cenodude/crosswatch:latest ``` Open `http://localhost:8787`. {% endtab %} {% tab title="Docker Compose" %} ```yaml services: crosswatch: image: ghcr.io/cenodude/crosswatch:latest container_name: crosswatch ports: - "8787:8787" environment: TZ: Europe/Amsterdam volumes: - type: volume source: crosswatch target: /config restart: unless-stopped volumes: crosswatch: ``` {% endtab %} {% endtabs %} ### Option B: Bind mount Create a host directory first (below is just an example!): ```bash mkdir -p /srv/crosswatch/config ``` {% hint style="warning" %} Check permissions before you start. CW must be able to read and write the host directory. By default, the container runs as UID `1000` and GID `1000`. If needed, either: * change the host directory owner to `1000:1000`, or * set `APP_UID` and `APP_GID` to match the host directory owner {% endhint %} Run CW: {% tabs %} {% tab title="Docker" %} ```bash docker run -d \ --name crosswatch \ -p 8787:8787 \ -v /srv/crosswatch/config:/config \ -e TZ=Europe/Amsterdam \ --restart unless-stopped \ ghcr.io/cenodude/crosswatch:latest ``` Open `http://localhost:8787`. {% endtab %} {% tab title="Docker Compose" %} ```yaml services: crosswatch: image: ghcr.io/cenodude/crosswatch:latest container_name: crosswatch ports: - "8787:8787" environment: TZ: Europe/Amsterdam volumes: - type: bind source: /srv/crosswatch/config target: /config restart: unless-stopped ``` {% endtab %} {% endtabs %} ### Container user and permissions CW runs as a dedicated user inside the container. It does not run the application as root. Default container identity: ``` APP_USER=appuser APP_GROUP=appuser APP_UID=1000 APP_GID=1000 ``` #### Docker managed volume When `/config` uses a Docker managed volume, permission setup is usually not required. Keep the defaults. You can omit all four `APP_*` variables. Example: ```yaml volumes: - crosswatch:/config ``` CW creates the runtime user and group. It prepares `/config` and applies the required ownership automatically. #### Host directory bind mount When `/config` maps to a host directory, the CW user must be able to read and write that directory. Set `APP_UID` and `APP_GID` to match the host directory owner. Leave `APP_USER` and `APP_GROUP` as `appuser` unless you need different names inside the container. Example: ```yaml services: crosswatch: image: ghcr.io/cenodude/crosswatch:latest environment: APP_UID: 1026 APP_GID: 100 APP_USER: appuser APP_GROUP: appuser volumes: - /volume1/docker/crosswatch:/config ``` In this example, CW runs inside the container as UID `1026` and GID `100`. #### Find the correct UID and GID Use one of these commands: ```bash id -u id -g ``` ```bash stat -c "%u:%g" /path/to/crosswatch ``` The first number is the UID. The second number is the GID. Example output: ``` 1026:100 ``` Use those values here: ```yaml environment: APP_UID: 1026 APP_GID: 100 ``` #### Quick rules * Docker managed volume: * keep the defaults * omit `APP_*` unless you have a specific reason * Host directory bind mount: * set `APP_UID` and `APP_GID` to match the host directory owner * leave `APP_USER` and `APP_GROUP` as `appuser` `APP_USER` and `APP_GROUP` are container-only names. They do not need to match names on the Docker host. #### Permission problems When CW reports permission errors for `/config`, check the host directory ownership: ```bash ls -ln /path/to/crosswatch ``` Then set `APP_UID` and `APP_GID` to the numeric owner and group shown there. Or change the host directory ownership to match your configured values: ```bash sudo chown -R 1000:1000 /path/to/crosswatch ``` Use the UID and GID that fit your environment. {% hint style="warning" %} Do not set the Docker Compose `user` property together with these variables. CW needs startup permissions to prepare `/config`. After that, it starts the application as the configured runtime user. {% endhint %} ### Optional: Docker health check Use this if you want Docker to mark the container as `healthy` or `unhealthy`. It polls `http://127.0.0.1:8787/healthz`. Defaults used below: * interval: `30s` * timeout: `5s` * retries: `3` * start period: `20s` #### Docker volume + health check {% tabs %} {% tab title="Docker" %} ```bash docker run -d \ --name crosswatch \ -p 8787:8787 \ -v crosswatch:/config \ -e TZ=Europe/Amsterdam \ --health-cmd "python -c \"import json, urllib.request; data=json.load(urllib.request.urlopen('http://127.0.0.1:8787/healthz', timeout=5)); raise SystemExit(0 if data.get('ok') is True and data.get('status') == 'ok' else 1)\"" \ --health-interval 30s \ --health-timeout 5s \ --health-retries 3 \ --health-start-period 20s \ --restart unless-stopped \ ghcr.io/cenodude/crosswatch:latest ``` {% endtab %} {% tab title="Docker Compose" %} ```yaml services: crosswatch: image: ghcr.io/cenodude/crosswatch:latest container_name: crosswatch ports: - "8787:8787" environment: TZ: Europe/Amsterdam volumes: - type: volume source: crosswatch target: /config healthcheck: test: - CMD-SHELL - >- python -c "import json, urllib.request; data=json.load(urllib.request.urlopen('http://127.0.0.1:8787/healthz', timeout=5)); raise SystemExit(0 if data.get('ok') is True and data.get('status') == 'ok' else 1)" interval: 30s timeout: 5s retries: 3 start_period: 20s restart: unless-stopped volumes: crosswatch: ``` {% endtab %} {% endtabs %} #### Bind mount + health check {% tabs %} {% tab title="Docker" %} ```bash docker run -d \ --name crosswatch \ -p 8787:8787 \ -v /srv/crosswatch/config:/config \ -e TZ=Europe/Amsterdam \ --health-cmd "python -c \"import json, urllib.request; data=json.load(urllib.request.urlopen('http://127.0.0.1:8787/healthz', timeout=5)); raise SystemExit(0 if data.get('ok') is True and data.get('status') == 'ok' else 1)\"" \ --health-interval 30s \ --health-timeout 5s \ --health-retries 3 \ --health-start-period 20s \ --restart unless-stopped \ ghcr.io/cenodude/crosswatch:latest ``` {% endtab %} {% tab title="Docker Compose" %} ```yaml services: crosswatch: image: ghcr.io/cenodude/crosswatch:latest container_name: crosswatch ports: - "8787:8787" environment: TZ: Europe/Amsterdam volumes: - type: bind source: /srv/crosswatch/config target: /config healthcheck: test: - CMD-SHELL - >- python -c "import json, urllib.request; data=json.load(urllib.request.urlopen('http://127.0.0.1:8787/healthz', timeout=5)); raise SystemExit(0 if data.get('ok') is True and data.get('status') == 'ok' else 1)" interval: 30s timeout: 5s retries: 3 start_period: 20s restart: unless-stopped ``` {% endtab %} {% endtabs %} ### Optional environment variables You normally only need `TZ`. Override these only if you know why: * `TZ` — container timezone (used for timestamps in logs and the UI). * `CONFIG_BASE` — base path for `config.json`, `state.json`, `statistics.json`, etc. * Default: `/config` (leave as-is) * `WEB_HOST` — bind address for the web UI inside the container. * Default: `0.0.0.0` * `WEB_PORT` — port for the web UI inside the container. * Default: `8787` * `APP_UID` — numeric UID for the runtime user inside the container. * Default: `1000` * `APP_GID` — numeric GID for the runtime group inside the container. * Default: `1000` * `APP_USER` — runtime username inside the container. * Default: `appuser` * `APP_GROUP` — runtime group name inside the container. * Default: `appuser` * `APP_DIR` — application directory inside the container. * Default: `/app` (leave as-is) * `RUNTIME_DIR` — runtime/config directory used by the entrypoint. * Default: `/config` (leave as-is) * `CW_RESET_AUTH_ONCE` — one-time UI auth recovery flag. * Set to `1` to clear stored auth and sessions on next start. * Remove it after the reset completes. * `RELOAD` — enable Python auto-reload for development. * Default: `no` (set to `yes` for dev only) {% hint style="info" %} Use an IANA timezone name (like `Europe/Amsterdam`), not a GMT offset. {% endhint %} ### Troubleshooting #### UI does not load * Confirm the container is running: `docker ps` * Check logs: `docker logs crosswatch --tail 200` * Confirm the port mapping matches the URL you open. * Example: `-p 8787:8787` -> `http://localhost:8787` #### `/config` is not writable This happens most often with bind mounts. * Check the host directory exists. * Check the container user can write to it. * Align the host directory owner with `APP_UID` and `APP_GID`. * On NAS platforms, also verify the shared folder ACLs. ### Next steps * [First-time setup](/getting-started/first-time-setup) - connect providers and create your first pair * [Best practices](/getting-started/best-practices) - safer defaults for your first pairs * [Settings](/crosswatch/settings) - connect providers and configure pairs # Unraid Apps Install CW from the Unraid Community Apps catalog. CW is available in the Unraid Apps store. Install and configure it from the **Apps** tab.
Unraid logo
### What the template includes The Unraid template includes: * persistent `appdata` storage * WebUI configuration * timezone support * native Unraid `UID` and `GID` defaults ### Install from Community Apps Use the official catalog entry: [Open CrossWatch in Community Apps](https://ca.unraid.net/apps/crosswatch-1w9f6bx1i195yh?q=crosswatch) ### Notes The Unraid template handles the core container settings for you. You still need to complete the app setup in CW after the container starts. ### Next steps * [First-time setup](/getting-started/first-time-setup) - connect providers and create your first pair * [Best practices](/getting-started/best-practices) - safer defaults for your first pairs * [Installation](/getting-started/installation) - use the manual container path instead of the Unraid template # First-time setup Connect providers and add TMDb metadata Use this after CrossWatch (CW) is running and the UI loads. If you still need to install it, start here: [Docker setup](/getting-started/installation). Need a platform-specific wrapper instead? See [Install scripts](/related-information/community/install-scripts) for community-maintained options. {% hint style="success" %} CW can do a lot. You do **not** need to configure everything. For most users, the **defaults are already correct**. Your first goal is a single clean run. Typical first setup: * Connect one **media server or media client** and one **tracker** * Add the Metadata provider (**TMDb**) * Create one **pair** (one-way and one feature) {% endhint %} {% hint style="warning" %} **Save often.** Most changes do nothing until you click the **red floating Save button**.\ Click **Save** after every step below.
If your watchlists, history, or ratings are far beyond the recommended ranges, stop here and read [Limitations](/getting-started/limitations). {% endhint %}
TitleTarget
Connect providers first/spaces/3rh5THg1PdhVsBt3GALo/pages/lCTegLtxemF834DhMv5R
Configure sync pairs/spaces/3rh5THg1PdhVsBt3GALo/pages/C1lNlN7T3a0xWpl0jEU5
Enable real-time playback/spaces/3rh5THg1PdhVsBt3GALo/pages/J9gNWTn8GfZMQxOd5AW2
Check exact provider support/spaces/3rh5THg1PdhVsBt3GALo/pages/xWABFdLxQZxYgpBKwn8o
If you only need real-time playback, jump to [Webhook or Watcher](/crosswatch/settings/scrobbler/webhook-or-watcher). ### Recommended order 1. Connections 2. Metadata / ID Mapping (TMDb) 3. Synchronization (optional) 4. Scrobbler (optional) {% stepper %} {% step %} ### 1) Connect providers Open **Settings → Connections**. Start with **one media server or media client** and **one tracker**. Validate one clean run. Then add more providers. Good first trackers are **Trakt**, **SIMKL**, **MDBList**, or **PublicMetaDB**. 1. Click **Connect** / **Sign In** for the provider. 2. Approve access in the new tab. 3. Return to CW. 4. Verify URLs and IDs. Use **Auto-Fetch** when available. 5. Click the **red Save button**. Related: * [Connections](/crosswatch/settings/connections) {% endstep %} {% step %} ### 2) Configure metadata (TMDb) Open **Settings → Connections**. Set up TMDb before your first real sync. It improves matching and reduces wrong links. TMDb is strongly recommended. CrossWatch uses TMDb for many features, including posters, backdrops, richer metadata, and more reliable matching. 1. Enable **TMDb**. 2. Create a TMDb API key. 3. Paste the key into CW. 4. Click the **red Save button**. Related: [Meta: TMDb](/crosswatch/settings/connections/metadata/tmdb-metadata) {% endstep %} {% step %} ### 3) Create your first pair If you want syncing, open **Synchronization**. {% hint style="info" %} Do not overthink this screen. The defaults are good for most users. You can leave **Global** and **Provider** settings unchanged. {% endhint %} Use the safest first run: * **Mode**: one-way * **Features**: enable **one** (Watchlist, History, Ratings, or Progress) * **Dry run**: enabled {% hint style="info" %} Progress shows up for **Plex**, **Emby**, **Jellyfin**, **Nuvio**, and **PublicMetaDB** pairs. {% endhint %} 1. Pick **Source** (left) and **Target** (right). 2. Enable one feature tab. 3. Keep defaults in **Global** and **Provider** settings. 4. Click the **red Save button**. Related: * [Configure Pairs](/crosswatch/settings/configure-pairs) {% endstep %} {% step %} ### 4) Run once, then iterate Run a sync. Review what it planned. Fix matching before you enable more features. Use these tools when something looks off: * [Analyzer](/crosswatch/main-dashboard/tools/analyzer) for missing peers and mismatches * [Editor](/crosswatch/main-dashboard/navigation/editor) for overrides, blocks, and cleanup When the pair is stable: * Disable **Dry run**. * Add one more feature. * Add the next pair. {% endstep %} {% step %} ### 5) Optional: enable scrobbling (Watcher) Open **Settings → Scrobbler**. Use **Watcher** by default. Use Webhooks when server-delivered events suit your setup. {% hint style="info" %} Create one route, then start Watcher or enable Autostart. {% endhint %} 1. Connect your media server and at least one tracker target. 2. Open **Settings → Scrobbler**. 3. Select **Add watcher**. 4. Select the source and destination profiles. 5. Select **Save changes**. 6. Start Watcher or enable **Autostart**. {% hint style="info" %} Most setups should use only one mode, preferable Watcher. You can run **Watcher** and **Webhooks** together when they own separate source and destination pairs. {% endhint %} Related: * [Webhook or Watcher](/crosswatch/settings/scrobbler/webhook-or-watcher) * [Watcher](/crosswatch/settings/scrobbler/watcher) {% endstep %} {% step %} ### 6) Optional: add scheduling If you want automatic periodic runs, open **Settings → Scheduling**. Start with a daily cadence. Avoid overlaps. Click the **red Save button**. Related: [Scheduling](/crosswatch/settings/scheduling) {% endstep %} {% endstepper %} ### Quick checklist * Providers are connected. * Providers show up in **Sync pairs**. * TMDb is configured and saved. * First pair is one-way and dry run. * Scrobbling is configured only if you need it. * You clicked the red **Save** button after each step. Related: [Settings](/crosswatch/settings) ### Summary Connect one media server and one tracker. Add TMDb before your first real run. ### Next steps * Lock in safe pair defaults: [Best practices](/getting-started/best-practices) * Check whether your library size is a good fit: [Limitations](/getting-started/limitations) * Deep-dive pair controls (guards, features, Blackbox): [Configure Pairs](/crosswatch/settings/configure-pairs) * Enable real-time plays once syncing is stable: [Watcher](/crosswatch/settings/scrobbler/watcher) * Debug missing peers and ID issues: [Analyzer](/crosswatch/main-dashboard/tools/analyzer) # Best practices Recommended default Use these defaults unless you have a reason to deviate. CrossWatch (CW) is safest when you start small and keep runs predictable. ### Default setup (recommended) * Direction: **Media server -> tracker** * Watchlist: start **one-way**. Can be one-way or two-way. * History: do a **one-way seed** once. Then disable History and use scrobbling. * Ratings: keep **one-way** (Media server -> tracker) * Progress: keep **one-way** (Media server -> tracker) {% hint style="warning" %} Do not switch to **tracker -> media server** unless you have a clear reason. Trackers often(always) contain items your server does not have.. For most setups, **only sync data into a media server when the item already exists in that library.** Related: [Trackers vs. Media Servers](/related-information/trackers-vs.-media-servers) and [Tracker to Media Server](/related-information/tracker-to-media-server) {% endhint %} CW supports **real bidirectional synchronization**. Changes on either platform can sync in both directions. That adds flexibility. It also adds risk. Because both sides can introduce changes, you are more likely to see: * conflicts, duplicate items, unintended overwrites, propagated deletions **Use bidirectional (two-way) sync carefully.** It may look like the better option. For most users, **one-way** sync is still the safer and more predictable ### Metadata agents (recommended) Good metadata is the difference between stable ID matching and messy title guessing. Use these defaults: * **Plex Media Server**: use the default **Plex Movie** and **Plex TV Series** metadata agents. * **Emby** and **Jellyfin**: use **TMDb** metadata. For AniList pairs specific pairs, enable **Anime ID Mapping**. Guide: [Anime ID Mapping](/crosswatch/settings/connections/metadata/anime-id-mapping) ### Changing pairs and resets Do not constantly tweak direction, mode, or enabled features. If you do, reset state so planning recalculates cleanly. #### When to rebuild sync state and retry provider items Run **Rebuild sync state** and **Retry provider items** when you make a major sync change or the next plan looks unsafe. Common triggers: * You switch **one-way ↔ two-way** * You change library filters or whitelists on an active pair * You update CW and the first plan looks wrong * You backfill history with old dates and the provider uses delta reads * You see an unexpected large remove plan # Support matrix Provider and feature compatibility across syncing, scrobbling, playback, and tooling. ### Status legend | Status | Meaning | | ------------------------------- | --------------------------------------------------------------- | | :check: | Implemented and exposed by the current code | | Limited | Implemented with provider, media type, or workflow restrictions | | Source only | Can be read as a source, but not used as a writable destination | | :xmark: | Not implemented for this function | | N/A | Not applicable | ### Quick answers {% hint style="success" %} Best-supported first path: * media server → tracker for watchlist, history, or ratings * one-way sync * TMDb enabled {% endhint %} * Normal pair-based `progress` sync is available for CrossWatch local, Plex, Jellyfin, Emby, Nuvio, Floppy, PublicMetaDB, PunchPlay, Scrob, Trakt, SIMKL, and MDBList. * Watcher supports Scrob as a source or sink. Webhooks support Scrob as a sink only. * Jellyfin and Emby do not have a native watchlist. CrossWatch maps watchlists to Favorites, Playlists, or Collections. * Tautulli is a read-only history source. It cannot receive writes. * Nuvio is an experimental media client. It supports watchlist, history, and progress. * PunchPlay is an experimental tracker. It supports watchlist, ratings, history, progress, and Watcher. * Scrob is experimental. It supports watchlist, ratings, history, rewatches, progress, and real-time scrobbling. * TMDb supports watchlist and ratings sync only. * AniList supports anime watchlist and ratings workflows only. # Providers Provider capabilities, entity support, watchlist mapping, and authentication methods. This section shows provider support for sync, watchlists, ratings, history, progress, and setup. {% hint style="success" %} Best first pair: * source: Plex, Jellyfin, or Emby * target: Trakt, SIMKL, MDBList, or PublicMetaDB * mode: one-way {% endhint %} {% hint style="warning" %} Jellyfin and Emby do not have a native watchlist. CrossWatch maps watchlists to Favorites, Playlists, or Collections. {% endhint %} {% hint style="info" %} Tautulli is read-only. Use it only as a history source. {% endhint %} ### Use this page for quick checks * Which providers can act as sources or targets * Which features each provider supports * Which entity types each feature can handle * Which auth and connection methods each provider uses ### Provider overview #### Provider roles | Provider | Category | Pair source | Pair target | Named profiles | | ---------------- | --------------- | ---------------------------------------------------: | ---------------------------------------------------: | ---------------------------------------------------: | | Emby | Media server | :check: | :check: | :check: | | Jellyfin | Media server | :check: | :check: | :check: | | Plex | Media server | :check: | :check: | :check: | | Kodi | Media client | :check: | :check: | :check: | | Nuvio | Media client | :check: | :check: | :check: | | Stremio | Media client | :check: | :check: | :check: | | AniList | Anime tracker | :check: | :check: | :check: | | Floppy | Tracker | :check: | :check: | :check: | | MDBList | Tracker | :check: | :check: | :check: | | PublicMetaDB | Tracker | :check: | :check: | :check: | | PunchPlay | Tracker | :check: | :check: | :check: | | Scrob | Tracker | :check: | :check: | :check: | | SIMKL | Tracker | :check: | :check: | :check: | | TMDb | Tracker | :check: | :check: | :check: | | Trakt | Tracker | :check: | :check: | :check: | | CrossWatch local | Local tracker | :check: | :check: | Local state | | Tautulli | Plex monitoring | Source only | :xmark: | :check: | #### Sync feature support | Provider | Watchlist sync | Ratings sync | History sync | Progress sync | | ---------------- | ---------------------------------------------------: | ---------------------------------------------------: | ---------------------------------------------------: | ---------------------------------------------------: | | CrossWatch local | :check: | :check: | :check: | :check: | | Plex | :check: | :check: | :check: | :check: | | Jellyfin | Limited | :xmark: | :check: | :check: | | Emby | Limited | :xmark: | :check: | :check: | | Floppy | :check: | :check: | :check: | :xmark: | | Nuvio | :check: | :xmark: | :check: | :check: | | Kodi | :xmark: | :check: | :check: | :check: | | Stremio | :check: | Target only | :check: | :check: | | Trakt | :check: | :check: | :check: | :xmark: | | SIMKL | :check: | :check: | :check: | :xmark: | | MDBList | :check: | :check: | :check: | :xmark: | | PublicMetaDB | :check: | :check: | :check: | :check: | | PunchPlay | :check: | :check: | :check: | :check: | | Scrob | :check: | :check: | :check: | :check: | | AniList | Limited | Limited | :xmark: | :xmark: | | TMDb | :check: | :check: | :xmark: | :xmark: | | Tautulli | :xmark: | :xmark: | Source only | :xmark: | #### Real-time and manager support | Provider | Progress Manager | Watcher source | Webhook source | Watcher sink | Webhook sink | | ---------------- | ---------------------------------------------------: | ---------------------------------------------------: | ---------------------------------------------------: | ---------------------------------------------------: | ---------------------------------------------------: | | CrossWatch local | :xmark: | :xmark: | :xmark: | :xmark: | :xmark: | | Plex | :check: | :check: | :check: | :xmark: | :xmark: | | Jellyfin | :check: | :check: | :check: | :xmark: | :xmark: | | Emby | :check: | :check: | :check: | :xmark: | :xmark: | | Floppy | :xmark: | :xmark: | :xmark: | :xmark: | :xmark: | | Nuvio | :xmark: | :xmark: | :xmark: | :xmark: | :xmark: | | Kodi | :check: | :check: | :xmark: | :xmark: | :xmark: | | Stremio | :xmark: | :xmark: | :xmark: | :xmark: | :xmark: | | Trakt | :check: | :xmark: | :xmark: | :check: | :check: | | SIMKL | :check: | :xmark: | :xmark: | :check: | :xmark: | | MDBList | :check: | :xmark: | :xmark: | :check: | :xmark: | | PublicMetaDB | :check: | :xmark: | :xmark: | :xmark: | :xmark: | | PunchPlay | :xmark: | :xmark: | :xmark: | :check: | :xmark: | | Scrob | :xmark: | :check: | :xmark: | :check: | :check: | | AniList | :xmark: | :xmark: | :xmark: | :xmark: | :xmark: | | TMDb | :xmark: | :xmark: | :xmark: | :xmark: | :xmark: | | Tautulli | :xmark: | :xmark: | :xmark: | :xmark: | :xmark: | #### Notes * Jellyfin and Emby have no native watchlist. * Jellyfin and Emby Playlist mode is episode-only. * Jellyfin and Emby ratings sync is disabled. * Floppy is experimental. It supports watchlist, ratings, and history only. * Nuvio is experimental. It supports watchlist, history, and progress only. * PunchPlay is experimental. It supports watchlist, ratings, history, progress, and Watcher. * Scrob is experimental. It supports sync, rewatches, and Watcher routes. * Kodi is experimental. It supports ratings, history, progress, and Watcher only. * Stremio is experimental. Ratings can sync to Stremio only. * AniList supports anime watchlist and ratings only. * Tautulli is read-only and history-only. * Playlist sync is not a CrossWatch feature. * Trakt, SIMKL, and MDBList support Progress Manager, not normal `progress` sync. * PublicMetaDB supports both normal `progress` sync and Progress Manager. ### Provider entity support #### Entity coverage | Provider | Watchlist entities | Rating entities | History entities | Progress entities | | ---------------- | -------------------------------- | -------------------------------- | ------------------------------------- | -------------------------------- | | CrossWatch local | Movies, shows, seasons, episodes | Movies, shows, seasons, episodes | Movies, shows, seasons, episodes | Movies, shows, seasons, episodes | | Plex | Movies, shows | Movies, shows, seasons, episodes | Movies, episodes | Movies, episodes | | Jellyfin | Movies, shows, library items | Not supported | Movies, episodes | Movies, episodes | | Emby | Movies, shows, library items | Not supported | Movies, episodes | Movies, episodes | | Floppy | Movies, shows | Movies, shows | Movies, episodes | Not supported | | Nuvio | Movies, shows | Not supported | Movies, episodes | Movies, episodes | | Kodi | Not supported | Movies, episodes | Movies, episodes | Movies, episodes | | Stremio | Movies, shows | Movies, shows (target only) | Movies, episodes | Movies, episodes | | Trakt | Movies, shows | Movies, shows, seasons, episodes | Movies, episodes | Not a normal sync feature | | SIMKL | Movies, shows, anime | Movies, shows, anime titles | Movies, episodes, anime | Not a normal sync feature | | MDBList | Movies, shows | Movies, shows, seasons, episodes | Movies, shows, seasons, episodes | Not a normal sync feature | | PublicMetaDB | Movies, shows | Movies, shows, episodes | Movies, episodes | Movies, episodes | | PunchPlay | Movies, shows | Movies, shows, seasons, episodes | Movies, episodes | Movies, episodes | | Scrob | Movies, shows | Movies, shows, seasons, episodes | Movies, episodes, including rewatches | Movies, episodes | | AniList | Anime movies, anime series | Anime movies, anime series | Not supported | Not supported | | TMDb | Movies, shows | Movies, shows, episodes | Not supported | Not supported | | Tautulli | Not supported | Not supported | Plex movies, episodes | Not supported | #### Important restrictions | Provider | Notes | | ---------------- | ----------------------------------------------------------------------------- | | CrossWatch local | Local JSON tracker with snapshots | | Plex | Uses Plex Discover. Progress removal can be limited | | Jellyfin | No native watchlist. Playlist is episode-only. Strict ID matching is optional | | Emby | No native watchlist. Playlist is episode-only. Strict ID matching is optional | | Floppy | Experimental. Requires TMDb IDs. No progress or playlists | | Nuvio | Experimental. Watchlist maps to the Nuvio Library. TMDb is recommended | | Kodi | Experimental. Writes need existing library items and unique external IDs | | Stremio | Experimental. Library acts as watchlist. Ratings are target-only | | Trakt | History writes can also add to Trakt Collections | | SIMKL | No season or episode ratings | | MDBList | Dropped shows can be excluded from history sync | | PublicMetaDB | Requires TMDb identity. Progress also needs duration | | PunchPlay | Experimental. Supports Watcher and uses provider IDs for matching | | Scrob | Experimental. Requires a reachable server, API key, and user credentials | | AniList | Anime mapping supports watchlist and ratings only | | TMDb | Requires a TMDb API key and account session | | Tautulli | Read-only source. No writes | ### Jellyfin and Emby watchlist mapping | Mode | Read | Write | Suitable content | Limitations | | ---------------- | ---------------------------------------------------: | ---------------------------------------------------: | -------------------------------------- | -------------------------------------------- | | Favorites | :check: | :check: | Movies, shows, episodes, library items | Uses the provider Favorite flag | | Playlist | :check: | :check: | Episodes | Does not represent shows. No item migration. | | Collections | :check: | :check: | Movies, shows, library items | Uses a named collection | | Native watchlist | :xmark: | :xmark: | N/A | No native watchlist | ### Authentication and connection methods #### Authentication | Provider | Authentication | Refresh support | | ---------------- | ------------------------------------- | ---------------------------------------------------: | | CrossWatch local | None | N/A | | Plex | Plex device PIN | No refresh action | | Jellyfin | Server connection and access token | Provider-dependent | | Emby | Server connection and access token | Provider-dependent | | Floppy | Server URL and API token | No | | Nuvio | Temporary login code and profile | Yes | | Kodi | HTTP JSON-RPC with Basic Auth | N/A | | Stremio | Email and password to obtain auth key | No | | Trakt | OAuth device code | :check: | | SIMKL | OAuth | Provider-dependent | | MDBList | OAuth device code, legacy API key | Yes for OAuth | | PublicMetaDB | API key | No | | PunchPlay | OAuth device code | Yes | | AniList | OAuth access token | Provider-dependent | | TMDb | API key plus user session | Session-based | | Tautulli | Server URL plus API key | No | #### Important connection options | Provider | Key options | | ---------------- | --------------------------------------------------------------------------- | | CrossWatch local | Storage path, retention, snapshots, restore selection | | Plex | Server, owner, managed users, shared users, Home profile, optional Home PIN | | Jellyfin | Server URL, user ID, device ID, optional SSL verification | | Emby | Server URL, user ID, device ID, optional SSL verification | | Floppy | Server URL, API token, SSL verification, watchlist name | | Nuvio | Selected Nuvio profile and stored authentication tokens | | Kodi | Server URL, HTTP credentials, SSL validation, source-path whitelists | | Stremio | Stored auth key, Like and Love rating thresholds | | Trakt | Client ID, client secret, access token, refresh token | | SIMKL | Client ID, client secret, access token | | MDBList | Access token, refresh token, API key fallback | | PublicMetaDB | Base URL | | PunchPlay | Device-code connection and stored refresh tokens | | AniList | Client ID, client secret, access token | | TMDb | Auto-discovered account ID | | Tautulli | Optional user filter and SSL verification | #### Authentication notes 1. CrossWatch supports multiple named provider profiles. 2. Plex supports shared tokens and separate friend or shared users. 3. TMDb has two roles: `tmdb` for metadata and `tmdb_sync` for account sync. 4. Provider secrets are redacted from public config responses. # Pair synchronization Feature compatibility, matching rules, and sync controls for standard pairs. This section covers standard pair-based synchronization. It shows which providers can act as sources or destinations, how matching works, and which safety controls affect writes. {% hint style="success" %} Safest first sync: * one-way * one feature * dry run on * source is a media server * target is a tracker {% endhint %} {% hint style="warning" %} Two-way sync and mirror delete mode are powerful. They can also spread bad matches, conflicts, and deletes. {% endhint %} ### Feature compatibility A normal connection is valid for a feature when the selected source can read that feature and the selected destination can write it. | Feature | Valid sources | Valid destinations | | --------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | Watchlist | Emby, Jellyfin, Plex; Nuvio, Stremio; AniList, Floppy, MDBList, PublicMetaDB, PunchPlay, Scrob, SIMKL, TMDb, Trakt; CrossWatch local | Emby, Jellyfin, Plex; Nuvio, Stremio; AniList, Floppy, MDBList, PublicMetaDB, PunchPlay, Scrob, SIMKL, TMDb, Trakt; CrossWatch local | | Ratings | Plex; Kodi; AniList, Floppy, MDBList, PublicMetaDB, PunchPlay, Scrob, SIMKL, TMDb, Trakt; CrossWatch local | Plex; Kodi, Stremio; AniList, Floppy, MDBList, PublicMetaDB, PunchPlay, Scrob, SIMKL, TMDb, Trakt; CrossWatch local | | History | Emby, Jellyfin, Plex; Kodi, Nuvio, Stremio; Floppy, MDBList, PublicMetaDB, PunchPlay, Scrob, SIMKL, Trakt; CrossWatch local, Tautulli | Emby, Jellyfin, Plex; Kodi, Nuvio, Stremio; Floppy, MDBList, PublicMetaDB, PunchPlay, Scrob, SIMKL, Trakt; CrossWatch local | | Progress | Emby, Jellyfin, Plex; Kodi, Nuvio, Stremio; Floppy, PublicMetaDB, PunchPlay, Scrob; CrossWatch local | Emby, Jellyfin, Plex; Kodi, Nuvio, Stremio; Floppy, PublicMetaDB, PunchPlay, Scrob; CrossWatch local | ### Pair behavior
Pair behaviorSupportedNotes
One-way sync:check:Source writes to destination
Two-way sync:check:Both sides are compared and synced
Per-feature enablement:check:Watchlist, ratings, history, and progress can be enabled independently
Per-feature additions:check:Add and update writes can be enabled independently
Per-feature removals:check:Removal writes can be enabled independently
Multiple named provider profiles:check:Source and destination profile IDs are preserved
Dry run:check:Plans and logs changes without remote writes
Verify after writeLimitedRuns only when the destination provider supports verification
### Matching and identity resolution #### Global identity and fallback
CapabilityScopeSupportedNotes
Canonical identity mappingGlobal:check:Normalizes provider IDs into common keys
IMDb IDsGlobal:check:Used for matching and export
TMDb IDsGlobal:check:Primary identity for PublicMetaDB
TVDB IDsGlobal:check:Used where available
Trakt IDsGlobal:check:Used where available
SIMKL IDsGlobal:check:Used where available
MDBList IDsGlobal:check:Used where available
Provider native IDsProvider-specific:check:Preserved for provider-specific matching
Title and year fallbackGeneral matching:check:Used when strict ID matching is disabled
#### Provider-specific matching
CapabilityScopeSupportedNotes
Strict ID matchingEmby, Jellyfin, Plex:check:Disables title and year search fallback
Plex Discover watchlist matchingPlex:check:Primary Plex watchlist path
Plex PMS metadata matchPlex:check:Can resolve external IDs through the selected server
Plex PMS watchlist fallbackPlexOptionalDisabled by default for strict Discover behavior
Plex fallback GUID searchPlexOptionalSearches beyond visible libraries. Best for temporary troubleshooting.
Stremio IMDb matchingStremio:check:Uses IMDb IDs. TMDb can enrich missing metadata.
Floppy TMDb ID matchingFloppy:check:Requires TMDb IDs for supported synchronization.
#### Anime and metadata enrichment
CapabilityScopeSupportedNotes
AniBridge local anime mappingAniList pairs:check:Enriches IDs for watchlist and ratings
Anime-only filteringAniList pairs:check:Skips content that cannot be confirmed as anime
Metadata localeTMDb metadata:check:Default is en-US
Metadata cacheTMDb metadata:check:Default cache lifetime is 720 hours
### Synchronization controls For runtime behavior, conflict resolution, deletion safeguards, and playlist mappings, see [Synchronization policies](/getting-started/support-matrix/pair-synchronization/synchronization-policies). #### Write controls
ControlSupportedDefault or behavior
Global addition gate:check:Enabled
Global removal gate:check:Disabled
Pair feature additions:check:Pair setting overrides the global default
Pair feature removals:check:Pair setting overrides the global default
Source delete mode:check:Removes only when the source deletion is observed
Mirror delete mode:check:Destination is forced to follow the source. Destructive.
Include observed deletes:check:Enabled
Tombstone retention:check:Default 1 day
Dry run:check:Disabled
Verify after writeLimitedDisabled. Requires provider support.
#### Safety and guardrails
ControlSupportedDefault or behavior
Drop guard:check:Disabled
Mass delete permission:check:Enabled
Suspect inventory shrink guard:check:Applies after a minimum previous inventory size
Blackbox unresolved item quarantine:check:Enabled
Pair-scoped blackbox:check:Enabled
Blackbox addition blocking:check:Enabled
Blackbox removal blocking:check:Enabled
Blackbox cooldown:check:Default 30 days
Unresolved and freeze state:check:Prevents repeated unsafe writes
Flapper protection:check:Integrated with blackbox behavior
#### Runtime and provider behavior | Control | Scope | Default or behavior | | ------------------------------- | --------------------- | ------------------------------------------------------- | | Provider rate limiting | All providers | Provider-specific GET and POST rates | | Retry and backoff | All providers | Provider-specific retry budgets and rate-limit handling | | Apply chunking | All providers | Global and provider-specific chunk sizes | | Snapshot reuse cache | All providers | Default 300 seconds | | Checkpoints and watermarks | Delta-capable flows | Used for incremental and delta-capable providers | | Library filtering | Emby, Jellyfin, Plex | Per-feature and scrobble library allowlists | | Ignore dropped shows | MDBList, SIMKL, Trakt | Optional history filter | | Trakt Collection write | Trakt | Optional when adding history | | Include manually marked watched | Plex | Optional. Enabled by default. | #### Progress-specific controls Progress uses pair thresholds and Destination completion policies. See [Playback progress thresholds and completion policies](/getting-started/support-matrix/pair-synchronization/synchronization-policies) for defaults, provider limits, and manual editing rules. # Synchronization policies Runtime policies for pair sync, deletions, conflicts, playlists, and provider capabilities. {% tabs %} {% tab title="End users" %} Use this reference to understand what CrossWatch (CW) reads, writes, and removes. {% hint style="warning" %} Two-way sync and mirror removals can spread bad matches and unwanted deletes. {% endhint %} CW evaluates support at runtime. It skips unavailable features and unsupported writes. ### Start here | If you want to… | Use this | | ------------------------------------- | ---------------- | | Copy one provider into another | **One-way** sync | | Keep both providers updated | **Two-way** sync | | Keep Destination-only items | `source_deletes` | | Make Destination match Source exactly | `mirror` | | Sync a playlist safely | `managed_only` | {% hint style="warning" %} Two-way sync and `mirror` can spread bad matches and unwanted deletions. {% endhint %} ### What CW does **Watchlist** copies missing items. Removals need explicit permission. **History** copies supported watch events. State-only providers preserve less event detail. **Ratings** use the Source in one-way pairs. Two-way pairs prefer newer ratings. **Progress** avoids moving resume positions backwards without newer timestamps. ### Safe defaults * Keep **Remove** disabled and use one-way syncs. * Use **Dry run** before enabling writes. * Start with a media server as the Source. See [Configure Pairs](/crosswatch/settings/configure-pairs) for pair setup and [Global settings](/crosswatch/settings/configure-pairs/global-settings) for safety controls. ### At a glance * **One-way**: the Source defines the desired state. * **Two-way**: both providers contribute state. * **Removals**: disabled by default and guarded by baselines. * **Playlists**: use explicit mappings, not standard feature sync. ### Terminology
TermMeaning
SourceThe left provider. In two-way sync, it is the final ratings and progress fallback.
DestinationThe right provider. One-way pairs write Source changes here.
SnapshotCurrent provider items for one feature.
BaselineLast stable provider state. It detects real additions and removals.
Observed deletionA prior-baseline item absent from a reliable current snapshot.
TombstoneStored delete marker that prevents immediate restoration.
Managed itemAn item CW tracks for a playlist mapping.
### Identity and matching CW normalizes provider data into canonical items before comparison. Identifier preference order: 1. TMDb 2. IMDb 3. TVDB 4. ..and the rest Movies and shows use the strongest available identifier. Seasons use a show identifier and season number. Episodes also use season and episode coordinates. When no stable identifier exists, CW can match media type, title, and year. This fallback is less reliable. Recognized alternative identifiers can still match items with different primary keys. Anime mapping can rekey or enrich items before comparison. Enable it for eligible pairs. ### Planning and safety #### Adds and removals Adds are enabled by default. Removals are disabled by default. ```yaml sync: enable_add: true enable_remove: false ``` Each feature can override these defaults with `add` and `remove`. #### Provider health and snapshots CW checks provider health and feature availability before planning writes. Authentication failures skip the affected pair. One-way pairs plan no writes when the Source is unavailable. Missing snapshots never trigger removals when either provider is unavailable. A present snapshot represents the complete current feature state. A delta snapshot contains recent changes only. CW combines delta snapshots with the prior baseline. #### First two-way run The first two-way run merges both sides. It never propagates removals because no baseline proves a deliberate deletion. #### Scope and guardrails History, ratings, and progress can use selected provider libraries. Items outside scope are excluded from reads and writes. Manual additions are merged into effective provider state. Manual blocks prevent matching additions, updates, and removals. The drop guard detects suspicious snapshot reductions. It can use the last stable baseline for planning. This protects against temporary failures and incomplete responses. Mass-deletion protection can block unsafe removal plans. Playlist mappings use the same protection. #### Unresolved items and write confirmation Items that cannot be written are stored as unresolved. CW retries their additions, updates, and removals later. An unresolved item clears only after sufficient success evidence. CW prefers confirmed item keys. It uses provider counts conservatively when keys are unavailable. Providers with verification support can refresh after a write to confirm the resulting state. ### One-way synchronization One-way synchronization runs from Source to Destination. The Source is authoritative, subject to removal mode, timestamps, capabilities, and thresholds. {% hint style="info" %} Use one-way sync when one provider should remain authoritative. {% endhint %} #### Watchlist CW adds Source watchlist items missing from the Destination. The default removal mode is `source_deletes`. In `source_deletes` mode, CW removes a Destination item only when: 1. It existed in the previous Source baseline. 2. It is absent from the current Source snapshot. 3. The snapshot is reliable. 4. Removals are enabled. This retains Destination items that the Source never managed. In `mirror` mode, CW can remove every Destination item absent from the Source. Safeguards still apply. #### History History synchronizes watch events when both providers expose timestamps. State-only providers synchronize watched history without separate rewatch events. CW copies missing Source events. With Trakt, timestamps in the same 60-second bucket represent one event. Different timestamps represent separate rewatches. Entries without usable watch timestamps are not copied as watch events. History removals use the selected one-way removal mode. #### Ratings When ratings differ, CW writes the Source rating to the Destination. Media types and rating date can limit this behavior. Unrating uses the selected removal policy. The default only propagates an unrating after CrossWatch observes a prior Source rating disappear. #### Playback progress CW writes meaningful Source resume positions. CW skips positions that are too small, too similar, or near completion. See [Playback progress synchronization](#playback-progress-synchronization) for thresholds and provider safety caps. ### Two-way synchronization Two-way synchronization compares both providers and can write to each. The left side does not always win. {% hint style="warning" %} Use two-way sync only when matching is reliable on both providers. {% endhint %} #### Watchlist Watchlist synchronization is presence-based: 1. An item on only one side is added to the other. 2. An item on both sides needs no action. 3. A confirmed deletion on either side removes the other copy when removals are enabled. Deletion handling is symmetric. The initial run merges both watchlists and suppresses removals. #### History History is event-based when both providers expose watch timestamps: 1. Copy an event that exists on only one side. 2. Treat matching item and timestamp as one event. 3. With Trakt, timestamps within 60 seconds are one event. 4. Treat different timestamps as separate events. 5. Propagate confirmed deletions when removals are enabled. 6. Synchronize a history event newer than its tombstone. History has no Source value winner. Distinct timestamps represent distinct events. #### Ratings When ratings differ, CW resolves the conflict in this order: 1. Newest `rated_at` when both timestamps differ. 2. `sync.bidirectional.source_of_truth`. 3. Pair Source as the final fallback. A missing rating is not automatically a deletion. CW needs an observed deletion or another valid removal signal. #### Playback progress CW prefers newer progress. It then prefers the furthest position. See **Power users** for the full conflict order. ### Playback progress synchronization CW synchronizes resume positions separately from watched history. Progress is intended for partially watched movies and episodes. Items close to completion are excluded from progress synchronization so that History can manage their watched state. #### Default thresholds Unless a pair contains explicit values, the CrossWatch orchestrator uses these defaults:
SettingDefaultPurpose
Minimum progress60 secondsIgnores accidental starts and very small resume positions
Change threshold30 secondsAvoids writes when the difference between providers is insignificant
Near completion threshold95%Stops synchronizing progress near completion and leaves the watched state to History
Timestamp tolerance30 secondsProtects a meaningfully newer target position from being overwritten
Progress removalDisabledResume positions are not cleared unless removal is enabled
Replay watched itemsDisabledWatched items are not unwatched to apply a resume position unless replay is enabled
#### Near completion behavior The `max_percent` setting defines when CrossWatch stops treating an item as resumable progress. With the default value of `95`: * Progress at 94% can be synchronized. * Progress at 95% or higher is ignored by Progress synchronization. * History synchronization manages the watched state. The configured value can be changed per pair. #### Provider completion limits Some providers mark an item watched when a high resume position is written. CrossWatch applies the provider's declared completion limit as a safety cap. The effective threshold is: ``` minimum of the configured max_percent and the target provider limit ``` Examples: * Configured threshold 95%, provider limit 80% → effective threshold 80%. * Configured threshold 85%, provider limit 90% → effective threshold 85%. * Configured threshold 95%, no provider limit → effective threshold 95%. A user-configured lower threshold is always respected. A higher value cannot override a provider safety limit. #### One-way pairs In a one-way pair, CrossWatch calculates the effective threshold for the Destination provider. ``` Plex → PublicMetaDB Configured max_percent: 95% PublicMetaDB completion limit: 80% Effective threshold: 80% ``` Progress below 80% can be written to PublicMetaDB. Progress at 80% or higher is left to History synchronization. #### Two-way pairs A two-way pair stores one shared `max_percent`. CrossWatch calculates the effective threshold independently for each direction. ``` Plex ↔ PublicMetaDB Configured max_percent: 95% Writes to Plex: 90% effective threshold Writes to PublicMetaDB: 80% effective threshold ``` The pair Source does not determine these thresholds. Each direction uses its target provider's capabilities. #### Provider summary * **Stremio:** keeps one active episode resume position per series. * **PublicMetaDB:** uses an 80% safety cap. * **Nuvio:** uses a 90% safety cap for normal-length content. * **Emby, Jellyfin, Kodi, and Plex:** recommend a 90% cap. * **Floppy:** uses the pair value, normally 95%. * **PunchPlay:** uses the pair value, normally 95%. * **Other providers:** use the pair value, normally 95%. See **Power users** for provider-specific behavior and configuration. ### Removals and deletion safeguards Deletion is more conservative than addition. | Rule | Behavior | | ------------------- | ---------------------------------------------------------- | | Default | Adds are enabled. Removals are disabled. | | Required evidence | A removal normally needs a baseline and reliable snapshot. | | Unsupported signals | Providers can disable observed deletions per feature. | | Two-way deletes | A deletion creates a tombstone. | | First two-way run | No removals are applied. | | Failure protection | Failed, suspicious, or incomplete reads suppress removals. | | {% endtab %} | | {% tab title="Power users" %} ### Configuration summary ```yaml sync: enable_add: true enable_remove: false include_observed_deletes: true drop_guard: false allow_mass_delete: true verify_after_write: false one_way_remove_mode: source_deletes bidirectional: source_of_truth: "" ``` Feature settings can override global values: ```yaml features: watchlist: add: true remove: false history: add: true remove: false ratings: add: true remove: false types: [movie, show, episode] from_date: "" progress: add: true remove: false min_seconds: 60 delta_seconds: 30 max_percent: 95 timestamp_tolerance_seconds: 30 replay_enabled: false propagate_timestamp_updates: false ``` ### Playback progress details Pair defaults are normalized when the pair is saved. The progress planner also applies them when values are missing. #### Provider defaults and limits | Provider | Progress write policy | Effective default | | ------------------------ | --------------------------------------------------- | -----------------------: | | Emby | Controlled by `LibraryOptions.MaxResumePct` | Pair value, normally 95% | | Jellyfin | Controlled by `MaxResumePct` | 90% recommendation | | Plex | Controlled by `Video played threshold` | 90% recommendation | | Kodi | Controlled by `playcountminimumpercent` | 90% recommendation | | Nuvio | Automatically completes normal-length items | 90% | | Stremio | Keeps one active episode resume position per series | Pair value, normally 95% | | Floppy | No documented provider completion policy | Pair value, normally 95% | | PunchPlay | No documented provider completion policy | Pair value, normally 95% | | PublicMetaDB | Automatically completes progress writes | 80% | | CrossWatch local tracker | No provider completion policy | Pair value, normally 95% | #### Scrobble thresholds Trakt, SIMKL, and MDBList use an 80% threshold for stop-scrobble behavior. This does not limit normal progress writes. CrossWatch does not lower `max_percent` to 80% for these providers. #### Nuvio duration rule Nuvio applies its 90% completion cap only when duration is at least 60 seconds. For shorter known items, CrossWatch does not apply the cap. Unknown durations use the safer 90% threshold. #### Two-way conflict handling When progress differs, CrossWatch uses this priority: 1. Newest `progress_at`. 2. Furthest position in milliseconds. 3. Highest progress percentage. 4. `sync.bidirectional.source_of_truth`. 5. Pair Source as the final fallback. For a clear versus progress conflict, the newest timestamp wins. Equal or missing timestamps use the configured source of truth, then the pair Source. Kodi first-observed timestamps are not reliable conflict timestamps. A real timestamp from the other provider wins. #### Regression protection and clears CrossWatch normally avoids moving an item backwards. A lower Source position is written only when its timestamp is clearly newer. Without reliable timestamps, CrossWatch keeps the furthest known progress. A clear is zero progress. CrossWatch propagates clears only when removal is enabled and a reliable deletion or clear signal exists. History manages items near the completion threshold. Playlist mappings use: ```yaml membership: managed_only order: ignore allow_mass_delete: false ``` {% endtab %} {% endtabs %} # Scrobbling Real-time Watcher and webhook support, routes, and playback rules. This section covers real-time scrobbling support. It shows route compatibility, Watcher and webhook behavior, and the progress thresholds that affect scrobble events. {% hint style="success" %} Use Watcher when possible. Scrob can be either a source or a sink. {% endhint %} ### Quick links
TitleOpen
Choose between Watcher and webhooks/spaces/3rh5THg1PdhVsBt3GALo/pages/1Dx9OZYvOJ6utvcFoU2A
Set up Watcher routes/spaces/3rh5THg1PdhVsBt3GALo/pages/J9gNWTn8GfZMQxOd5AW2
Set up webhook mappings/spaces/3rh5THg1PdhVsBt3GALo/pages/BxJJk2jkTcCo8ZkED8lI
Filter by user, server, or library/spaces/3rh5THg1PdhVsBt3GALo/pages/PH2jfcZjseHr6sFkoKAP
### Route support Floppy and Stremio do not provide Watcher or webhook playback sources. #### Watcher routes | Playback source | MDBList | PunchPlay | Scrob | SIMKL | Trakt | | --------------- | ---------------------------------------------------: | ---------------------------------------------------: | ---------------------------------------------------: | ---------------------------------------------------: | ---------------------------------------------------: | | Emby | :check: | :check: | :check: | :check: | :check: | | Jellyfin | :check: | :check: | :check: | :check: | :check: | | Plex | :check: | :check: | :check: | :check: | :check: | | Kodi | :check: | :check: | :check: | :check: | :check: | | Scrob | :check: | :check: | N/A | :check: | :check: | #### Webhook routes | Playback source | MDBList | Scrob | SIMKL | Trakt | | --------------- | -------------------------------------------------: | ---------------------------------------------------: | -------------------------------------------------: | ---------------------------------------------------: | | Emby | :xmark: | :check: | :xmark: | :check: | | Jellyfin | :xmark: | :check: | :xmark: | :check: | | Plex | :xmark: | :check: | :xmark: | :check: | Scrob is a webhook sink only. It cannot be a webhook source. ### Scrobbling capabilities #### Core behavior | Capability | Watcher | Webhook | Notes | | ------------------------------------------ | ---------------------------------------------------: | ---------------------------------------------------: | --------------------------------------------------------------- | | Independent enablement | :check: | :check: | Watcher and webhook can be enabled independently | | Automatic start on app boot | :check: | N/A | Available for the watcher source | | Route-based configuration | :check: | :check: | Routes connect a media source profile to a tracker sink profile | | Start, pause, and stop progress handling | :check: | :check: | Sink thresholds control pause versus completed stop | | Pause debounce | :check: | :check: | Suppresses very short pause events | | Near-completion start suppression | :check: | :check: | Suppresses credit or near-end start flapping | | Automatic watchlist removal after watching | :check: | :check: | Configurable for movie, show, and episode types | #### Filtering and routing | Capability | Watcher | Webhook | Notes | | -------------------------- | ---------------------------------------------------: | ---------------------------------------------------: | ---------------------------------------------- | | Username allowlist | :check: | :check: | Plex account or user filtering | | Server UUID allowlist | :check: | :check: | Empty means unrestricted unless blocked | | Server UUID blocklist | :check: | :check: | Always ignored when matched | | Media library allowlist | :check: | :check: | Available per Plex, Jellyfin, and Emby profile | | Kodi source-path allowlist | :check: | N/A | Configured in the Kodi connection profile | #### Plex-specific behavior | Capability | Watcher | Webhook | Notes | | ---------------------------------- | ---------------------------------------------------: | ---------------------------------------------------: | --------------------------------------------------------- | | Autoplay suppression | :xmark: | :check: | Webhook-only protection for short autoplay transitions | | Live session progress probing | :xmark: | :check: | Webhook-only session probing to improve progress accuracy | | Plex rating forwarding to Trakt | :check: | :check: | Optional | | Plex rating forwarding to SIMKL | :check: | :xmark: | Optional watcher behavior | | Plex rating forwarding to MDBList | :check: | :xmark: | Optional watcher behavior | | Plex Pass requirement for webhooks | :xmark: | :check: | Required by Plex to send webhook events | #### Emby-specific behavior | Capability | Watcher | Webhook | Notes | | -------------------------------------- | -------------------------------------------------: | ---------------------------------------------------: | --------------------------------------- | | Emby Premiere requirement for webhooks | :xmark: | :check: | Required by Emby to send webhook events | ### Scrobble progress rules {% hint style="info" %} The default thresholds reduce noisy updates and prevent early stops from marking items watched. {% endhint %} | Rule | Default | Purpose | | -------------------------------------- | ---------: | ----------------------------------------------------- | | Progress reporting step (Watcher only) | 25 percent | Reduces unnecessary sink updates from watcher polling | | Stop becomes pause below | 80 percent | Prevents an early stop from marking content watched | | Forced completed stop at | 95 percent | Treats near completion as watched | | Allowed progress regression | 5 percent | Tolerates small backward progress changes | | Pause debounce | 5 seconds | Ignores micro-pauses | | Near-end start suppression | 99 percent | Suppresses credit-related start flapping | # Playback Progress Manager Resume-item provider support, bulk actions, and live playback visibility. The Playback Progress Manager is separate from normal pair-based progress sync. Use it to inspect and manage resume items across supported providers. {% hint style="info" %} This tool works across more providers than pair-based progress sync. {% endhint %} ### Provider support #### Actions | Provider | Read resume items | Update progress | Remove progress | Mark watched | Bulk actions | | ------------ | ---------------------------------------------------: | ---------------------------------------------------: | ---------------------------------------------------: | ---------------------------------------------------: | ---------------------------------------------------: | | Plex | :check: | :check: | :check: | :check: | :check: | | Jellyfin | :check: | :check: | :check: | :check: | :check: | | Emby | :check: | :check: | :check: | :check: | :check: | | Nuvio | :check: | :check: | :check: | :check: | :check: | | Kodi | :check: | :check: | :check: | :check: | :check: | | Trakt | :check: | :check: | :check: | :check: | :check: | | SIMKL | :check: | :check: | :check: | :check: | :check: | | MDBList | :check: | :check: | :check: | :check: | :check: | | PublicMetaDB | :check: | :check: | :check: | :check: | :check: | #### Media and live support | Provider | Movies | Episodes | Anime aware | Live status overlay | | ------------ | ---------------------------------------------------: | ---------------------------------------------------: | ---------------------------------------------------: | ---------------------------------------------------: | | Plex | :check: | :check: | :xmark: | :check: | | Jellyfin | :check: | :check: | :xmark: | :check: | | Emby | :check: | :check: | :xmark: | :check: | | Nuvio | :check: | :check: | :xmark: | :xmark: | | Kodi | :check: | :check: | :xmark: | :xmark: | | Trakt | :check: | :check: | :xmark: | :xmark: | | SIMKL | :check: | :check: | :check: | :xmark: | | MDBList | :check: | :check: | :xmark: | :xmark: | | PublicMetaDB | :check: | :check: | :xmark: | :xmark: | ### Manager capabilities | Manager capability | Supported | Notes | | ----------------------------------------- | ---------------------------------------------------: | --------------------------------------------------- | | Combine progress from multiple providers | :check: | Uses canonical identity and fallback grouping | | Provider profile filtering | :check: | Individual profiles can be excluded | | Force refresh | :check: | Bypasses the short-lived progress cache | | Live playing, paused, and buffering state | :check: | Overlaid for Plex, Jellyfin, and Emby | | Sort by last updated | :check: | | | Sort by highest or lowest progress | :check: | | | Sort by remaining time | :check: | | | Sort by rating | :check: | | | Sort by title | :check: | | | Sort by provider | :check: | | | Remaining time calculation | :check: | Requires a usable duration | | Poster and backdrop enrichment | :check: | Uses provider data and TMDb metadata when available | | Provider timeout | :check: | Aggregate timeout is configurable | # Tooling and workflows App tooling, Quick Add, captures, backups, exports, scheduler, dashboard, analyzer, editor, and maintenance. This section covers the main CrossWatch tools and workflows outside of standard syncing. {% hint style="info" %} Use these tools to debug, recover, and handle edge cases without changing your main pair design. {% endhint %} ### Application tooling matrix | Tool or screen | Supported | Main capabilities | | ----------------------- | ---------------------------------------------------: | -------------------------------------------------------------------------------- | | Connections | :check: | Configure providers, profiles, and pairs | | Synchronization | :check: | Run all pairs or selected pairs in one-way or two-way mode | | Unified Watchlist | :check: | Combine configured watchlists into one view | | Quick Add | :check: | Search TMDb and write history, watchlist, and ratings | | Playback Progress | :check: | Inspect, update, clear, and complete resume items | | Captures | :check: | Create, inspect, compare, restore, and delete captures | | Analyzer | :check: | Diagnose state, artifacts, watermarks, unresolved items, and blackbox issues | | Editor | :check: | Inspect and edit tracker state, provider state, pair datasets, and manual blocks | | Backup and Restore | :check: | Create, validate, upload, download, restore, schedule, and retain ZIP backups | | Export | :check: | Create import files for supported external workflows | | Scheduler | :check: | Run standard schedules, advanced jobs, and manual triggers | | Activity | :check: | Recent sync and scrobble activity | | Output | :check: | Separate Sync, Watcher, and Debug tabs | | Health and probes | :check: | Provider configuration, authentication, and health checks | | Dashboard | :check: | Configurable media and activity widgets | | Maintenance | :check: | Clear caches and state, inspect local tracker, reset data, and restart | | Local tracker | :check: | CrossWatch itself can be a sync endpoint | | Metadata resolver | :check: | TMDb metadata, images, IDs, score, and runtime enrichment | | Anime mapping | :check: | Local AniBridge data for AniList watchlist and ratings | | Statistics | :check: | Runtime and sync statistics | | Local UI authentication | :check: | Optional username and password authentication | | HTTPS | :check: | Self-signed or custom TLS certificate | | Telemetry toggle | :check: | Usage telemetry can be disabled | ### Quick Add and manual writes | Capability | Supported | Notes | | ---------------------------- | ---------------------------------------------------: | ------------------------------------------------ | | TMDb movie search | :check: | Requires a TMDb API key | | TMDb show search | :check: | Requires a TMDb API key | | Write watched history | :check: | Only offered to providers with history support | | Add to watchlist | :check: | Only offered to providers with watchlist support | | Write a rating | :check: | Rating range is 1 to 10 | | Select multiple providers | :check: | Provider-instance aware | | Watched date today | :check: | Uses the current UTC timestamp | | Custom watched date | :check: | Uses a selected calendar date | | Release date as watched date | :check: | Fetches the release or first-air date from TMDb | | External ID enrichment | :check: | Adds TMDb, IMDb, and TVDB IDs when available | ### Captures and snapshots | Capability | Supported | Notes | | ---------------------------------- | ---------------------------------------------------: | -------------------------------------------------------------------------- | | Capture watchlist | :check: | Provider and profile-aware | | Capture ratings | :check: | Provider and profile-aware | | Capture history | :check: | Provider and profile-aware | | Capture progress | :check: | Provider and profile-aware | | Full capture | :check: | Can contain multiple feature child captures | | List captures | :check: | | | Read capture content | :check: | | | Basic comparison | :check: | Added, removed, and changed summaries | | Extended comparison | :check: | Feature selection, search, paging, kind filters, and nested change details | | Restore by merge | :check: | Adds or updates capture data | | Clear and restore | :check: | Clears the destination feature first | | Delete capture | :check: | Optional deletion of child captures | | Clear selected provider features | :check: | Maintenance operation | | Local CrossWatch tracker snapshots | :check: | Automatic snapshots before local changes | | Local retention | :check: | Days and maximum snapshot count are configurable | ### Backup and restore | Capability | Supported | Notes | | ----------------------------- | ---------------------------------------------------: | ---------------------------- | | Create manual backup | :check: | ZIP archive | | Application state scope | :check: | Default scope | | Include captures | :check: | Optional | | Include reports | :check: | Optional | | Include cache | :check: | Optional | | List backups | :check: | | | Download backup | :check: | | | Upload backup | :check: | ZIP only, size-limited | | Validate before restore | :check: | | | Restore backup | :check: | Creates a pre-restore backup | | Restart after restore | :check: | Optional | | Delete backup | :check: | | | Scheduled backups | :check: | Time and day selection | | Retention by age | :check: | | | Retention by maximum count | :check: | | | Automatic old backup deletion | :check: | Optional | ### Export compatibility #### Feature support by export target | Export target | Watchlist | History | Ratings | Combined history and ratings | | ------------- | ---------------------------------------------------: | ---------------------------------------------------: | ---------------------------------------------------: | ---------------------------------------------------: | | Letterboxd | :check: | :check: | :check: | :check: | | IMDb | :check: | :xmark: | :xmark: | :xmark: | | JustWatch | :check: | :check: | :check: | :xmark: | | Yamtrack | :check: | :check: | :xmark: | :check: | | TMDb workflow | :check: | :xmark: | :check: | :xmark: | #### Media support and limitations | Export target | Media types | Important limitations | | ------------- | ------------------------------------------------------- | -------------------------------------------------------------------- | | Letterboxd | Movies only | Watched dates are normalized. Files over 1 MB may require splitting. | | IMDb | Rows with an IMDb ID | Watchlist only | | JustWatch | Movies, shows, seasons, episodes | Export file, not a direct API sync provider | | Yamtrack | Movies, shows, seasons, episodes | Rating-only rows in combined export are skipped | | TMDb workflow | Movies, shows, seasons, episodes where identity permits | Produces account-import-compatible CSV structures | | Export control | Supported | | ------------------------------ | ---------------------------------------------------: | | Select source provider | :check: | | Select source profile | :check: | | Select feature | :check: | | Select media types | :check: | | Search and filter rows | :check: | | Preview compatibility warnings | :check: | | Missing identity filtering | :check: | | Invalid watched date reporting | :check: | ### Scheduler | Schedule mode | Supported | Notes | | ---------------------- | ---------------------------------------------------: | ---------------------------------------- | | Hourly | :check: | Standard scheduler | | Every N hours | :check: | Default is every 12 hours | | Daily at a fixed time | :check: | 24-hour time | | Custom minute interval | :check: | Minimum 15 minutes | | Advanced jobs | :check: | Multiple targeted jobs | | Scheduled backups | :check: | Stored under advanced scheduling | | Trigger now | :check: | Can execute a provided scheduler payload | | Stop scheduler | :check: | | | Replan next run | :check: | Refreshes the live worker | | Show status | :check: | | | Show next run | :check: | | ### Dashboard and interface | Capability | Supported | Notes | | ------------------------------------ | ---------------------------------------------------: | ------------------------------------------------------------ | | Flat dark theme | :check: | | | Flat light theme | :check: | | | Original theme | :check: | | | Watchlist preview | :check: | Configurable | | Now Playing card | :check: | Configurable | | Recent scrobble activity | :check: | Configurable | | Recent history widget | :check: | Configurable | | Latest ratings widget | :check: | Configurable | | Recent sync widget | :check: | Count or time-window display | | Configurable dashboard media widgets | :check: | Added on current `main` | | Quick Add desktop drawer | :check: | Configurable | | Quick Add mobile button | :check: | Configurable | | Sync output tab | :check: | Sync execution output | | Watcher output tab | :check: | Watcher and scrobble output | | Debug output tab | :check: | Provider diagnostics mirrored into the UI | | Docker stdout diagnostics | :check: | Debug diagnostics continue to be written to container output | | Responsive web interface | :check: | Desktop and mobile controls are present | ### Analyzer coverage | Diagnostic area | Supported | | ----------------------------------------------- | ---------------------------------------------------: | | Main state file | :check: | | Manual policy state | :check: | | Pair-scoped state files | :check: | | Provider watermarks | :check: | | Shadow state | :check: | | Provider indexes | :check: | | Unresolved state | :check: | | Flap state | :check: | | Blackbox state | :check: | | Provider sync modules | :check: | | Orchestrator modules | :check: | | Artifact parse failures | :check: | | Error, warning, and information severity totals | :check: | | Category and problem type totals | :check: | | Multiple selected pairs | :check: | | Safe path validation | :check: | ### Editor coverage | Editor source | Supported | Operations | | --------------------------------------------------- | ---------------------------------------------------: | ------------------------------------- | | CrossWatch tracker data | :check: | Read, edit, save, import, and export | | Current orchestrator state | :check: | Inspect baseline items | | Manual policy state | :check: | Add forced items and block items | | Provider profile state | :check: | Instance-aware | | Pair datasets | :check: | Inspect and save pair-scoped data | | Tracker snapshots | :check: | Select historical data | | Watchlist data | :check: | | | History data | :check: | | | Ratings data | :check: | | | Progress data | :check: | | | ZIP export and import | :check: | Tracker editor data exchange | | Automatic module checkpoint before provider changes | :check: | Protects state before remote mutation | ### Maintenance operations | Operation | Supported | Notes | | -------------------------------------------------------- | ---------------------------------------------------: | -------------------------------------------------------- | | Overview cleanup | :check: | Runs the standard local cleanup sequence | | Inspect provider cache | :check: | Shows files and metadata | | Retry provider items | :check: | Preserves activity files and the identity cache | | Refresh artwork and metadata | :check: | Removes local artwork and metadata cache | | Rebuild sync state | :check: | Removes saved provider baselines | | Inspect CrossWatch local tracker | :check: | Shows local state and snapshots | | Reset local tracker | :check: | Can clear tracker state files, snapshots, or both | | Clear Recent Scrobbles | :check: | Removes only local scrobble rows | | Rebuild statistics | :check: | Clears statistics, reports, and Insights cache | | Clear currently playing | :check: | Removes the local live playback session file | | Clear all captures | :check: | Deletes saved provider captures | | Factory reset | :check: | Backs up `config.json` first | | Restart CrossWatch | :check: | Exits for container or process-supervisor restart | | Remove reports, caches, and generated state during reset | :check: | Includes sync reports, tracker data, cache, and TLS data | # Operations and limits Security, storage, runtime behavior, limitations, and repository source paths. This section covers security behavior, storage layout, runtime notes, and the main repository areas behind each system. {% hint style="info" %} Use this page when you need exact paths, security behavior, or implementation map pointers. {% endhint %} ### At a glance {% columns %} {% column %} #### Covers * secret storage and config safety * state and backup paths * runtime logging and telemetry {% endcolumn %} {% column %} #### Also includes * key product limits * source-map pointers into the repo * related docs for deeper details {% endcolumn %} {% endcolumns %} ### Jump to related docs
TitleOpen
Safe defaults and operating guidance/spaces/3rh5THg1PdhVsBt3GALo/pages/aXxgMcv8AubC0CypFUTO
Size and provider fit guidance/spaces/3rh5THg1PdhVsBt3GALo/pages/Lws31PpVM04pXySTwH8d
Config file reference/spaces/3rh5THg1PdhVsBt3GALo/pages/wSx6U3V0FNJ3e2pvDywh
Provider pacing and retries/spaces/3rh5THg1PdhVsBt3GALo/pages/uIdojSHyuBmDdMI0yPFg
### Security and configuration | Capability | Supported | Notes | | --------------------------------- | --------: | --------------------------------------------------------------------- | | Encrypted stored secrets | Yes | Fernet encryption | | Generated local master key | Yes | Stored as `.cw_master_key` with restrictive permissions when possible | | External master key | Yes | `CW_CONFIG_KEY` or `CROSSWATCH_CONFIG_KEY` | | Secret redaction | Yes | Tokens, API keys, passwords, session IDs, and webhook identifiers | | Optional local UI login | Yes | Username and password | | Password hashing | Yes | PBKDF2 SHA256, 260000 iterations | | Remember session | Yes | Configurable duration | | Multiple login sessions | Yes | | | HTTP interface | Yes | | | HTTPS interface | Yes | | | Automatic self-signed certificate | Yes | Configurable hostname and validity | | Custom certificate and key | Yes | | | Provider SSL verification | Yes | Configurable for local server providers | | Atomic configuration writes | Yes | Temporary file replacement | | Configuration backup before reset | Yes | | | Backup path validation | Yes | Restricts access to managed backup paths | | Capture path validation | Yes | Restricts access to managed capture paths | ### Runtime and storage | Area | Default or support | | ----------------------------- | -------------------------------- | | Persistent configuration root | `/config` in the container image | | Main configuration | `/config/config.json` | | Main sync state | `/config/state.json` | | Manual policy state | `/config/state.manual.json` | | Provider runtime state | `/config/.cw_state` | | Local CrossWatch tracker | `/config/.cw_provider` | | Local tracker snapshots | `/config/.cw_provider/snapshots` | | Captures | `/config/snapshots` | | Backups | `/config/backups` | | Sync reports | `/config/sync_reports` | | Runtime debug logging | Supported | | HTTP access logging | Supported | | Sync module debug logging | Supported | | Provider request rate limits | Supported | | Provider retry budgets | Supported | | Usage telemetry | Enabled by default, configurable | ### Important limitations {% hint style="warning" %} Destructive removals stay off by default for a reason. Test first with dry runs. {% endhint %} 1. There is no general playlist sync feature. 2. Jellyfin and Emby ratings are not currently exposed as sync features. 3. Jellyfin and Emby watchlists are emulated through Favorites, Playlist, or Collections. 4. Jellyfin and Emby Playlist watchlist mode is episode-oriented and cannot represent shows. 5. Tautulli is a read-only history source. 6. AniList only supports anime watchlist and ratings workflows. 7. TMDb only supports watchlist and ratings sync. 8. Trakt, SIMKL, and MDBList do not participate in normal pair-based progress sync, even though they are supported by the Playback Progress Manager. 9. PublicMetaDB writes require TMDb identity, and progress writes require duration. 10. Plex progress removal may be limited by Plex behavior. 11. Destructive removals are globally disabled by default, but a pair can explicitly enable them. 12. Mirror delete mode is destructive and should be used only when the source must be authoritative. 13. Drop guard and mass-deletion settings should be configured deliberately, especially during the first sync. 14. Plex fallback GUID searching increases runtime and resource use and is intended as a temporary recovery option. 15. Provider APIs, account permissions, rate limits, and upstream behavior can still prevent an operation that the CrossWatch adapter implements. 16. PunchPlay support is experimental. Its adapter behavior may change. # Main dashboard Overview of the Main page, its actions, layout, and linked dashboard sections.

Main page overview with top actions, live status, widgets, and output.

The **Main** page is the operational home for CW. Use it to start runs, watch status, inspect output, and open the most-used tools. It is built around three jobs: 1. start and monitor work 2. review live status 3. open deeper tools when something needs attention ### Top actions The first row contains the main action buttons. Use them to jump into the most common tasks: * **Synchronize** — start a sync run * **View details** — inspect recent sync results * **Analyzer** — investigate matching and state problems * **Events** — review searchable sync history and recorded outcomes * **Exporter** — build export files from CW data These actions are for running and inspecting work. Most configuration still lives under **Settings**. ### Main page sections #### Status dashboard The status row gives you a fast operational summary. Unlike **Settings → Overview**, this area focuses on live runtime state. It covers: * monitoring status for **Scheduler**, **Watcher**, and **Webhook** * system status for **Sync pairs**, **CW Health**, and **Updates** Use [Status dashboard](/crosswatch/main-dashboard/status-dashboard) for the full reference. #### Output panel The output area shows live and recent run detail. Use it to inspect: * **Sync** output * **Watcher** output * **Debug** output Use [Output panel](/crosswatch/main-dashboard/output-panel) for the full guide. #### Dashboard widgets The widget area shows media-focused summaries from existing CW data. That includes: * **Watchlist widget** * **Recent History widget** * **Latest Ratings widget** * **Recent Scrobble widget** Use [Dashboard widgets](/crosswatch/main-dashboard/dashboard-widgets) for widget behavior, requirements, and troubleshooting. #### Recent Activity The **Main** page also shows a separate text-based activity list. This is different from the visual **Recent Scrobble** widget. Use [Recent Activity](/crosswatch/settings/scrobbler/recent-activity) for that audit trail. ### What belongs on Main Use **Main** when you want to: * start a run * confirm live service state * inspect recent output * review dashboard summaries Use **Settings** when you want to change configuration. ### Related topics * [Navigation](/crosswatch/main-dashboard/navigation) * [Status dashboard](/crosswatch/main-dashboard/status-dashboard) * [Dashboard widgets](/crosswatch/main-dashboard/dashboard-widgets) * [Watchlist](/crosswatch/main-dashboard/navigation/watchlist) * [Quick Add](/crosswatch/main-dashboard/navigation/quick-add) * [Playback](/crosswatch/main-dashboard/navigation/playback) * [Output panel](/crosswatch/main-dashboard/output-panel) * [Events](/crosswatch/main-dashboard/tools/events) * [Recent Activity](/crosswatch/settings/scrobbler/recent-activity) * [Settings](/crosswatch/settings) # Navigation Map the CrossWatch web UI and find the main settings and tools. Use the UI to connect providers, configure pairs, and run syncs. Most setup problems come from [**Connections**](/crosswatch/settings/connections), [**Pairs**](/crosswatch/settings/configure-pairs), or [**Metadata / ID Mapping**](/crosswatch/settings/connections/metadata). {% hint style="success" %} If you feel lost in the UI, start from **Settings** and **Main**. {% endhint %} {% tabs %} {% tab title="End users" %} ### Start here Use these pages most often: * [Main dashboard](/crosswatch/main-dashboard) — overview and top actions * [Status dashboard](/crosswatch/main-dashboard/status-dashboard) — live system status * [Dashboard widgets](/crosswatch/main-dashboard/dashboard-widgets) — watchlist, history, ratings, and scrobble widgets * [Watchlist](/crosswatch/main-dashboard/navigation/watchlist) — unified watchlist view * [Quick Add](/crosswatch/main-dashboard/navigation/quick-add) — manual history, watchlist, and rating actions * [Playback](/crosswatch/main-dashboard/navigation/playback) — unfinished playback records * [Output panel](/crosswatch/main-dashboard/output-panel) — Sync, Watcher, and Debug output

Main navigation with the dashboard, tools, and settings entry points.

### Common paths #### Connect providers 1. Open **Settings → Connections** 2. Connect what you need 3. Click **Save** #### Create a pair 1. Open **Synchronization** 2. Create one pair first 3. Start with **one-way** and **one feature** #### Run and check 1. Go to **Main** 2. Run a sync 3. Review the results 4. Fix mismatches in [Analyzer](/crosswatch/main-dashboard/tools/analyzer) or [Editor](/crosswatch/main-dashboard/navigation/editor) ### Saving changes * Click **Save** to persist changes. * Active runs use the next saved settings. * Some changes need a restart. {% endtab %} {% tab title="Power users" %} ### Key settings areas Most configuration lives under **Settings**. Use these pages for the deeper controls: * [Settings](/crosswatch/settings) * [Connections](/crosswatch/settings/connections) * [Metadata / ID Mapping](/crosswatch/settings/connections/metadata) * [Configure Pairs](/crosswatch/settings/configure-pairs) * [Scheduling](/crosswatch/settings/scheduling) * [Scrobble](/crosswatch/settings/scrobbler) * [Recent Activity](/crosswatch/settings/scrobbler/recent-activity) * [Maintenance](/crosswatch/settings/maintenance) * [HTTPS/TLS](/crosswatch/advanced-and-api/https-and-tls) * [Plex SSO](/crosswatch/settings/ui-settings/security/plex-sso) ### Notes Connected providers appear in **Synchronization** only after they connect. Most setup issues come from authentication, mapping, or pair rules. For feature-level behavior, use [Synchronization](/crosswatch/settings/synchronization) and [Tools](/crosswatch/main-dashboard/tools). {% endtab %} {% endtabs %} # Playback View and manage unfinished playback records across connected providers. Playback shows unfinished movies and episodes from connected providers. Use it to review, edit, complete, or remove resume records. {% hint style="info" %} Playback is available in **v0.9.23 and later**. {% endhint %}
{% tabs %} {% tab title="End users" %} ### What it shows Each card can show: * the movie or episode * current progress * time remaining * when playback last changed * provider badges When **All Providers** is selected, CrossWatch can combine matching records into one card. ### What you can do Use the toolbar to: * search * filter by provider, type, progress, age, or rating * change sorting Use the card actions to: * **Edit Progress** * **Mark as Watched** * **Remove Progress** You can also select multiple cards and run bulk actions. ### Important behavior * **Edit Progress** accepts `2` through `79` percent. * Use **Mark as Watched** for completed items. * **Remove Progress** deletes the resume record only. * On **Plex**, removing progress can also affect watched state. ### Refresh and results **Refresh** requests current provider data again. One slow provider does not block the others. Playback can still show partial results. ### Playback vs Progress **Playback** shows the current provider state. **Progress Sync** stores state only when a pair runs. Use [Progress](/crosswatch/settings/configure-pairs/features/progress) for pair-based resume syncing. Use the editor for the last stored sync state. ### Troubleshooting If nothing appears: * confirm the provider is connected * confirm it is enabled in Playback settings * use **Refresh** If **Edit Progress** is missing, the record usually cannot be updated or has no known duration. {% endtab %} {% tab title="Power users" %} ### Supported providers Playback supports: * **Trakt** * **SIMKL** * **MDBList** * **PublicMetaDB** * **Plex** * **Emby** * **Jellyfin** * **Nuvio** All supported providers can read playback records. Write support depends on the provider and record data. ### Combining logic With **All Providers**, CrossWatch groups matching records when possible. If no strong media key exists, fallback matching uses title and progress details. Records can stay separate when identifiers are weak or progress differs too much. ### Settings Playback settings let you: * include or exclude provider profiles * change **Slow provider timeout** Timeout accepts `3` through `60` seconds. The default is `12`. ### Advanced notes * CrossWatch queries enabled providers in parallel. * Up to six provider requests run at once. * **Select All Filtered Results** loads up to `250` results. * Saving Playback settings clears the Playback cache.
Config and API details Playback settings are stored in `config.json` under `playback_progress`. Useful endpoints: ``` GET /api/playback_progress/providers GET /api/playback_progress/settings GET /api/playback_progress/items POST /api/playback_progress/settings POST /api/playback_progress/actions/remove POST /api/playback_progress/actions/mark_watched POST /api/playback_progress/actions/update_progress POST /api/playback_progress/actions/bulk ``` The update action accepts only `2` through `79` percent.
### Related * Resume syncing between servers: [Progress](/crosswatch/settings/configure-pairs/features/progress) * Real-time playback handling: [Scrobble](/crosswatch/settings/scrobbler) * Main page overview: [Main dashboard](/crosswatch/main-dashboard) * UI overview: [Navigation](/crosswatch/main-dashboard/navigation) {% endtab %} {% endtabs %} # Captures Create point-in-time captures for restore, compare, and scheduled retention workflows. Captures are a **rollback tool**. A capture stores a point-in-time copy of provider data so you can restore it later. You can also compare captures or keep scheduled backup-style snapshots over time. Older builds called this feature **Snapshots**. {% hint style="warning" %} Captures are **experimental** and will stay experimental. They are **not** a core CW feature. They’re a nice-to-have service. Treat captures as best-effort: * Use with care. * Validate restores before doing destructive changes. * Create a real backup first. Use your provider’s native export/backup {% endhint %}
### Captures are not backups Captures are **not** the same as a full backup. They are a best-effort copy of: * one **provider** * one **profile** * one **dataset** (Watchlist, Ratings, History, Progress) They do **not** include: * provider credentials or tokens * CW configuration * Items outside the scope of the sync adapter * For example: **History items without a date won’t be included in a capture, but the process can still clear them.** * Plex note: this often means items that are only **Marked Watched** (the Plex “checkmark”) without a usable `viewedAt` / `lastViewedAt`. * If you want CW to also scan “Marked Watched” state, set `plex.history.include_marked_watched = true`. * This is still best-effort. Items without timestamps can’t be exported into a history capture. * More detail: [Adapter: Plex](/crosswatch/settings/synchronization/media-servers/plex). * everything your provider may store (notes, list metadata, privacy settings, etc.) {% hint style="info" %} If you want a real backup, prefer provider-native export/backup features. Captures are the fallback when those are missing. {% endhint %} ### What captures are good for Use captures before you: * run destructive tools (clear watchlist/ratings/history) * clean up lists in bulk * migrate accounts ### What a capture contains A capture is a JSON export of **one provider**, **one profile**, and **one feature**. You can also capture **All** features together. It includes: * provider id (example: `PLEX`, `TRAKT`, `SIMKL`, `ANILIST`) * provider profile or instance * feature (`watchlist`, `ratings`, `history`, `progress`, or `all`) * created timestamp and optional label * basic stats (counts and media-type breakdown where available) * the raw items needed to restore back into the same provider #### Whitelisting impacts captures (media servers) For **Plex/Jellyfin/Emby**, captures follow your library whitelists. If you whitelist specific libraries for a feature, the capture includes **only items from those libraries**. Example: * History whitelist = only those libraries are exported in a **History** capture. * Ratings whitelist = only those libraries are exported in a **Ratings** capture. If you don’t configure whitelisting, captures include **all visible libraries**. Guide: [Library Whitelisting](/crosswatch/settings/connections/library-whitelisting). ### Where captures are stored Captures are written to: `/config/snapshots/YYYY-MM-DD/` This folder name is legacy. It may still say `snapshots` on disk. Filenames include a UTC timestamp, provider, feature, and optional label: `2026-01-27T19-12-45Z__TRAKT__watchlist__before-cleanup.json` #### “All” captures If you choose **All**, CW creates: * one full capture bundle (`__all__`) that references child captures * one child capture per supported feature This is useful when you want one complete restore point across multiple features. It also keeps restore behavior predictable and lets you restore one feature later. ### Create Capture The Create Capture section lets you create a new capture manually. #### Main options * **Provider**: choose the source provider * **Profile**: choose the provider profile or instance * **Feature**: choose one feature or **All** * **Label**: optional custom name for the capture #### Available actions * **Create capture**: create the capture immediately * **Queue for scheduler**: send the current setup into Capture Scheduling Use **Queue for scheduler** when you want to turn a one-off setup into a recurring automated capture. {% hint style="info" %} Use short labels like `before-import` or `after-cleanup`. {% endhint %} ### Capture Browser The Capture Browser shows all saved captures in one place. You can: * search by provider, feature, label, or path * filter by provider * filter by feature * filter by type: * **Manual**: captures created manually * **Auto**: captures created by Capture Scheduling For full captures, the browser can group and show child captures under the main **All** capture. Click a capture to load it into **Restore** or **Compare**. Click it again to clear the selection. ### Restore Restore applies a saved capture back into a provider profile. #### Restore modes * **Merge**: add missing data from the capture without wiping the target first * **Clear restore**: clear the target feature first, then restore the captured data {% hint style="warning" %} CW restores what was captured. The target media server or tracker may still interpret that data differently afterward. {% endhint %} {% hint style="warning" %} Plex has no supported way to **backdate** a play. If CrossWatch writes **History** into Plex, Plex records `watched_at` as **now**. This affects history sync and **History** capture restores. That matters because when you later syncs history back from Plex to a tracker, CrossWatch send those Plex timestamps back to the tracker as if they were the real watch dates. This can overwrite the user’s historical watch timeline. {% endhint %} #### Restoring “All” captures If the selected capture is a bundle (`feature = all`), Restore applies the chosen mode to each supported child feature. ### Compare Compare lets you select two matching captures and see what changed. #### Rules * both captures must belong to the same provider * you can compare two single-feature captures * you can compare two **All** capture bundles that contain multiple features This is useful for checking: * items added * items removed * items updated Compare is designed to answer: “What changed between capture A and capture B?” It does **not** answer: “Which provider is correct?” or “What should sync?” More detail: [Capture Compare](/crosswatch/main-dashboard/navigation/captures/capture-compare) and [Capture Compare (Advanced)](/crosswatch/main-dashboard/navigation/captures/capture-compare-advanced). ### Tools The Tools area provides cleanup and maintenance actions for provider features. That includes clearing supported feature data directly from the target provider. {% hint style="danger" %} Provider tools write directly to the provider. Use them carefully. {% endhint %} Available tools depend on what the selected provider supports: * Clear watchlist * Clear ratings * Clear history * Clear progress * Clear all {% hint style="warning" %} **Clear ratings** trigger rating-scrobble listeners. If you enabled rating scrobbling, this can instantly send “unrate” events. That can wipe ratings on attached providers too (example: Trakt). Before using **Clear ratings**, disable rating scrobbling first: * **Settings → Scrobbler → Watcher routes → Plex ratings** * **Settings → Scrobbler → Webhooks → Ratings** Setup references: * [Watcher](/crosswatch/settings/scrobbler/watcher) * [Webhooks](/crosswatch/settings/scrobbler/webhooks) {% endhint %} If a provider doesn’t support a feature, that tool is disabled. Typical workflow: 1. Create a capture 2. Run a clear tool 3. Optional: restore a capture ### Scheduler Integration Captures now work much more closely with scheduling. You can: * create a capture manually right now * queue that setup directly into Capture Scheduling That means a manual capture setup can become a repeating automated capture schedule without re-entering the provider, profile, and feature. Related: [Scheduling](/crosswatch/settings/scheduling) ### Scheduled Capture Retention Capture schedules can manage retention automatically. Available options: * **Label template**: define how scheduled captures are named * **Keep captures for days**: delete captures older than a set age * **Max captures to keep**: keep only the newest number of captures * **Cleanup**: enable automatic pruning after each successful scheduled capture So Captures now support: * manual restore points * scheduled recurring backup-style captures * compare and restore workflows * automatic retention cleanup for scheduled captures ### Deleting captures Captures can be deleted from the UI. * Select a capture * Click **Delete** * Confirm If you delete an **All features** bundle, CW also deletes its child captures. This only deletes files on disk under `/config/snapshots/...`. It does not touch provider data. ### Notes and limitations * Providers differ. A restore can be best-effort, depending on provider APIs. * If a feature/tool is disabled, the provider does not support it (or is not configured). * Captures are local files. If you move hosts, copy `/config/snapshots` too. * Don’t forget: this is **not** a backup tool. # Capture Compare Run a read-only diff between two same-provider captures to see added, removed, updated, and unchanged items. Capture Compare is a **read-only diff** between two capture files from the **same provider**. It helps you answer: “What changed between capture A and capture B?” It does **not** decide what should sync. {% hint style="info" %} Captures are stored under `/config/snapshots/` (legacy folder name). Capture Compare never writes to your providers. {% endhint %} ### What you can compare You pick: * **Capture A** (baseline) * **Capture B** (the one you’re comparing against) Both captures should be from the **same provider**. Capture Compare supports: * **single-feature captures** * Watchlist * Ratings * History * Progress * **All** capture bundles * one set that contains multiple features in one restore point For the cleanest results, compare like-for-like: * feature vs the same feature * **All** bundle vs **All** bundle ### How to run a diff (UI) {% stepper %} {% step %} ### Open Compare Open **Tools → Captures**, then open the **Compare** panel. {% endstep %} {% step %} ### Pick two captures Pick Capture **A** and Capture **B**. Keep the provider the same. Keep the feature, or bundle type, the same when you can. {% endstep %} {% step %} ### Run Compare Click **Compare** to load results. Use the filters to focus on Added/Removed/Updated. {% endstep %} {% endstepper %} ### How to read results Compare groups items into four buckets: * **Added**: in B, not in A * **Removed**: in A, not in B * **Updated**: same key, but fields changed * **Unchanged**: same key, identical payload Updated items can be expanded to show field-level changes. {% hint style="warning" %} If you diff captures from different features, everything can look “added/removed”. That’s expected. {% endhint %} {% hint style="info" %} Compare is intended for **same-provider diffs**. If you compare different providers, results won’t be meaningful. {% endhint %} ### Limits and truncation The UI may cap how many rows it shows per section. If you expect huge diffs, tighten your comparison first. Try same provider, same feature or same bundle type, close timestamps, and a short label.
API reference (optional) #### Endpoint `GET /api/snapshots/diff` #### Query params * `a` (required): capture A path (relative under `/config/snapshots`) * `b` (required): capture B path (relative under `/config/snapshots`) * `limit` (optional, default `200`, min `1`, max `2000`): max items returned per section * `max_changes` (optional, default `25`, min `1`, max `200`): max field-level changes per updated item
How the diff works (high level) Compare is intentionally simple. It loads both capture JSON files, then compares: * the set of item keys in A vs B * the full item payload for keys present in both That produces: * Added = keys in B but not A * Removed = keys in A but not B * Updated = key in both, payload differs * Unchanged = key in both, payload identical {% hint style="info" %} This is deterministic. It does not do ID mapping or fuzzy matching. {% endhint %}
# Capture Compare (Advanced) Advanced capture diff viewer with raw JSON and field-level changes. Capture Compare (Advanced) is a **read-only diff viewer**. It’s the “power user” version of [Capture Compare](/crosswatch/main-dashboard/navigation/captures/capture-compare). Use it when you need raw proof. {% hint style="info" %} This tool never writes to providers. It only reads capture files and shows differences. {% endhint %}
### What it’s good for Use Advanced compare when you want: * Side-by-side browsing of **File A vs File B** * Field-level changes for **Updated** items * Raw JSON for both sides * Quick copy for keys and external IDs (imdb/tmdb/etc.) ### Open Advanced compare {% stepper %} {% step %} ### Open Captures Open **Tools → Captures**. {% endstep %} {% step %} ### Open Compare Open the **Compare** panel. {% endstep %} {% step %} ### Pick File A and File B Pick two captures from the same provider. You can compare one feature at a time or an **All** bundle with multiple features. Keep the feature, or bundle type, the same when you can. {% endstep %} {% step %} ### Open Advanced Open the advanced compare viewer. Use **Refresh** if the files changed on disk. {% endstep %} {% endstepper %} ### How to use the viewer #### Header summary The header shows provider + feature and four counters: * `+` Added * `-` Removed * `~` Updated * `=` Unchanged #### Filters Use filters to cut noise: * **Search**: title, key, and common external IDs * **Status chips**: Added, Removed, Updated, Unchanged * **Type**: Movies / Shows / Seasons / Episodes * **Sort**: status / title / key * **Changed only**: hide unchanged items #### Two-pane list (A vs B) The top section shows two lists: * Left = items present in **File A** * Right = items present in **File B** Selecting an item syncs selection across panes. #### Item inspector The bottom section shows details for the selected key: * Status + change count (for Updated) * Copy buttons (key, JSON A, JSON B) * For Updated: a list of changed fields (JSON path + values) * Two raw records side-by-side (A and B) {% hint style="info" %} For **Added** items, File A is empty. For **Removed** items, File B is empty. {% endhint %}
Viewer tips * Use the splitters to resize the A/B panes and the detail area. * Scroll is kept in sync in the detail panes when possible. * Clicking an ID chip copies its value. * Clipboard can be blocked by browser security policies.
### Status semantics Same rules as standard compare: * **Added**: present in B, missing in A * **Removed**: present in A, missing in B * **Updated**: present in both, payload differs * **Unchanged**: present in both, payload matches ### Performance and limits Advanced compare can load a lot of data. If it feels slow, reduce the scope: * Compare captures close in time. * Compare the same provider and the same feature or bundle type. * Hide **Unchanged**.
API reference (optional) #### Endpoint `GET /api/snapshots/diff/extended` #### Notes The API path still uses `snapshots`. The UI calls them captures.
# Editor Review stored provider data, manage manual policy and send selected items to configured providers. The **Editor** manages stored provider data and manual policy. Use it to: * review stored provider state * correct titles, years, media types, IDs, ratings, watched dates, and progress * add manual items or block future syncs * import provider state or send selected rows directly * edit supported playlist endpoints {% tabs %} {% tab title="End users" %} ### Quick start {% stepper %} {% step %} ### 1. Pick a source Choose one of the following: * **Current State** — provider baselines with manual policy * **Manual Overrides** — saved manual additions, corrections, and blocks * **Local Tracker** — CrossWatch Local Tracker data * **Playlist Endpoint** — a configured provider playlist {% endstep %} {% step %} ### 2. Pick a dataset Choose **Watchlist**, **History**, **Ratings**, or **Progress**. Playlist Endpoint uses its configured playlist data. {% endstep %} {% step %} ### 3. Pick a scope For **Current State** and **Manual Overrides**, select a provider and profile. For **Local Tracker**, select a profile and workspace. For **Playlist Endpoint**, select the configured endpoint. {% endstep %} {% step %} ### 4. Edit or select rows Edit, add, block, or select rows. {% endstep %} {% step %} ### 5. Save or send Use **Save changes** to persist changes for the current source. Use **Send to** to write selected rows to other provider profiles. {% endstep %} {% endstepper %} ### Sources #### Current State Current State shows the latest stored baseline for a provider, together with manual additions, corrections, and blocks. Current State does not query the provider live when you open the view. It shows the state stored by the most recent relevant sync or provider state import. #### What you can do 1. Review a provider baseline 2. Block baseline rows 3. Add manual rows 4. Replace incorrect baseline items with manual corrections 5. Edit existing manual corrections 6. Inspect advanced item fields 7. Send selected rows to another provider 8. Import fresh provider state, when import is enabled #### Saving Current State Baseline rows are not directly rewritten by a normal Editor save. When you save: 1. Deleted baseline rows become blocks 2. Added rows become manual additions 3. Replaced rows become manual corrections 4. Policy is written to `/config/state.manual.json` 5. Policy is also mirrored into the manual section of `/config/state.json` This separation allows policy to survive a later rebuild of provider baselines, provided that `state.manual.json` is retained. #### Manual Overrides Manual Overrides shows only the policy stored for the selected provider, profile, and dataset. It does not show the complete provider baseline. Use this source when you want to review or manage: 1. Manual additions 2. Manual metadata corrections 3. Item blocks Manual Overrides is useful when a provider baseline contains thousands of rows and you only want to inspect the changes introduced through Editor. #### Saving Manual Overrides Save writes the displayed additions and blocks to: `/config/state.manual.json` When `state.json` exists, the policy is also mirrored into its manual section. Removing a manual addition removes that correction from policy. It does not remove an item from the connected provider. #### Local Tracker Local Tracker shows data stored by the CrossWatch provider module. Local Tracker data is grouped by Profile and Workspace. A workspace normally represents a sync pair that uses Local Tracker. Supported datasets depend on the files available in that workspace and can include: Watchlist History Ratings Progress #### What Local Tracker changes mean Local Tracker rows are read from the local tracker files. Editor does not overwrite those tracker files when you click Save. Instead, Save stores corrections and blocks as policy for the CrossWatch provider. These corrections are applied when Local Tracker is used as the source of a future one way sync. Connected provider accounts are not changed by a Local Tracker save. #### Local Tracker limitations Local Tracker policy affects future one way syncs from Local Tracker. It does not rewrite an existing provider account immediately. Use Send to when selected Local Tracker rows should be written to a provider immediately. #### Playlist Endpoint Playlist Endpoint connects Editor to playlists configured on the Playlists page. Unlike Current State, Manual Overrides, and Local Tracker, this source works directly with the provider playlist. The available actions depend on the provider endpoint capabilities. An endpoint may support: 1. Reading items 2. Adding items 3. Removing items 4. Reordering items Smart or read only playlists cannot be edited. #### Saving a Playlist Endpoint Editor compares the displayed rows with the current provider playlist. Depending on endpoint support, Save can: 1. Add new items 2. Remove missing items 3. Apply a new order Provider warnings are shown where relevant. Some providers may require confirmation before removals. Playlist changes are applied directly to the connected provider. ### Send to (selective sync) Send to lets you send selected rows directly to one or more provider profiles. This is a selective write operation. It does not run a complete sync pair and does not create a permanent sync rule.
| | | | -------------------------------- | -------------------------------- | | ![](/files/93f4E1GYXtxySoIUTt4r) | ![](/files/7jwUIUiWotG0kOlnJzW8) | #### Supported datasets Send to supports: Watchlist History Ratings Progress Playlist rows can also be selected and sent as Watchlist data. #### How to use Send to 1. Open any Editor source 2. Select one or more active rows 3. Click Send to in the selection toolbar 4. Select one or more provider profiles 5. Click Send selected data 6. Review the result for each target Only active rows are sent. Blocked or deleted rows are excluded. #### Available targets Editor only shows provider profiles that: 1. Are configured 2. Support writing the selected dataset 3. Are not the provider profile currently being viewed Multiple profiles can be selected in one operation. The selected targets are remembered separately for each dataset in the browser. #### Data requirements Watchlist rows require enough metadata to identify the item. History rows require a watched timestamp. Ratings rows require a rating from 1 to 10. Progress rows require a stored progress value. Items without sufficient data are reported as invalid and are not sent. External IDs provide the most reliable matching. IMDb, TMDB, TVDB, Trakt, SIMKL, AniList, and MAL IDs may be used when supported by the source and target. Title and year matching may be available for some providers, but it is less reliable. #### What Send to changes Send to calls the target provider write operation directly. It only performs additions or updates supported by that dataset. It does not remove items from the destination. Each selected target is processed independently. One target can succeed while another returns unresolved items or errors. The result includes: Sent Attempted Skipped Unresolved Errors Invalid Confirmed items are also reflected in the target profile baseline inside Current State. This keeps the stored state aligned with the direct send where confirmation is available. Send to does not save unsaved Editor changes automatically. Save corrections first when the edited values must become part of policy. ### Import provider state Current State can import live datasets from a configured provider profile. The Import provider state panel is only shown when provider state import is enabled. This is normally controlled through debug or developer import settings. Import can be used without creating a sync pair first. #### Supported imports Depending on provider support, you can import: Watchlist History Ratings Progress Only configured providers and supported datasets are shown. #### Import modes Replace baseline, replaces the selected provider baseline for that dataset with the imported result Merge, keeps existing baseline rows and adds or updates rows returned by the provider #### How to import 1. Set Source to Current State 2. Expand Import provider state 3. Pick a Provider 4. Pick a Profile 5. Select one or more datasets 6. Choose Replace baseline or Merge 7. Click Import Import reads from the provider API and writes the result into the appropriate baseline in `state.json`. It does not modify the provider account. Existing manual additions and blocks remain in `state.manual.json`. Provider specific library filters and configured scopes are passed through the provider adapter. The exact filtering behavior therefore depends on the provider and dataset. Large imports can take time. The Editor shows import progress while the request is running. ### Blocking items Blocks are policy rules. A block applies to a specific: Provider Provider profile Dataset Item key When an item is blocked, it is excluded when that provider profile is used as the source of a future sync for that dataset. A block does not delete the item from the provider. #### Block one item 1. Set Source to Current State or Local Tracker 2. Pick a dataset 3. Pick the provider, profile, or workspace 4. Find a baseline row 5. Click the block icon 6. Click Save changes Click the block icon again before saving to unblock the row. #### Review blocked items Enable the Blocked type chip to show only blocked baseline rows. Manual Overrides also shows stored block entries, including blocks for rows that are no longer present in the current baseline. ### Block rules Block rules provide a faster way to block or unblock all baseline rows of one media type. The panel is available in policy sources for History, Ratings, and Progress. #### Use Block rules 1. Open Current State, Manual Overrides, or Local Tracker 2. Select History, Ratings, or Progress 3. Expand Block rules 4. Choose a media type 5. Click Block all or Unblock all 6. Click Save changes Block all only affects baseline rows of the selected type. Manual additions are not converted into blocks by this operation. ### Manual additions Manual additions represent items that should be treated as present in a source, even when they are not part of its current baseline. #### Add an item 1. Click Add row 2. Enter or generate a unique Key 3. Select the media Type 4. Enter a Title and Year where available 5. Add external IDs 6. Enter the dataset specific value 7. Click Save changes For History, enter a watched date. For Ratings, enter a rating. For Progress, enter playback progress. A nonempty row must have a Key before it can be saved. External IDs are strongly recommended. Rows based only on title and year may not be writable to every provider. ### Correcting baseline items Baseline rows in policy sources are protected from direct editing. This prevents accidental modification of the stored provider snapshot. To correct a baseline item, use the replace or search action. Editor then: 1. Creates a manual correction 2. Blocks the original key where required 3. Stores the correction in policy This allows the original provider baseline to remain intact while future syncs use the corrected item. ### Advanced fields Policy sources include an Advanced fields action. This view shows: 1. The row source 2. The dataset 3. The canonical key 4. The row origin 5. The complete stored item data Use Advanced fields to inspect IDs, show IDs, episode coordinates, timestamps, provider metadata, and other fields not displayed in the main table. ### Editing dataset values #### Watchlist Watchlist rows represent item presence. Supported media types are normally Movie, Show, and Anime. #### History History rows include a watched timestamp. The Extra column opens the watched date editor. Season and episode rows may also include series metadata and episode coordinates. #### Ratings Ratings rows include a rating from 1 to 10. The Extra column opens the rating editor. #### Progress Progress rows contain stored playback position or percentage data. The Extra column opens the progress editor. Progress shown in Current State or Local Tracker is stored state. It is not a live provider query. Use Import provider state or run the relevant Progress sync to refresh it. The Playback Progress Manager uses live provider queries and may therefore show different values. ### Episodes and seasons Episode rows can display the series title together with season and episode coordinates, for example: `Series Name, S01E02` Search accepts formats such as: `S01` `S01E02` Episode and season corrections can use the replacement workflow to select the correct item or coordinates. ### Filtering and sorting #### Filter The filter searches across: Title Series title Season and episode code Key Media type Year External IDs Multiple words can be entered. All entered terms must match the row search data. #### Type filters Available type filters include: Movies Shows Anime Seasons Episodes Blocked Watchlist only uses Movie, Show, and Anime. At least one regular media type remains enabled. #### Sorting Rows can be sorted by: Key Type Title Extra Extra sorting depends on the dataset. For Ratings, Extra sorts by rating. For History, Extra sorts by watched date. ### Selection Rows can be selected individually or by selecting the current page. The table shows up to 100 rows per page. Selection enables bulk actions: Send to Block or Delete Unblock or Restore Clear selection Select page only selects rows on the current page. Selection is cleared after a completed Send to operation. ### Saving Save changes behaves differently for each source. #### Current State Saves manual additions, corrections, and blocks as policy. Provider baselines are not overwritten. #### Manual Overrides Saves only the displayed policy additions and blocks. Removing a row removes that manual override. #### Local Tracker Saves corrections and blocks as CrossWatch provider policy. Local tracker data files are not overwritten. #### Playlist Endpoint Applies supported additions, removals, and reordering directly to the provider playlist. ### Policy backup and restore Policy Backup protects manual additions, corrections, and blocks. #### Export Policy Export downloads: `crosswatch-state-policy.json` The export includes policy for provider profiles and Local Tracker profiles stored in `state.manual.json`. It does not contain complete provider baselines. #### Import Policy Import merges the imported policy into the existing policy by default. Imported policy is also mirrored into `state.json` when that file exists. Use a policy backup when replacing `state.json`, moving CrossWatch to another installation, or testing large policy changes. Importing policy does not modify connected providers directly. {% endtab %} {% tab title="Power users" %} ### File locations #### Current State baseline `/config/state.json` Contains stored provider baselines, runtime state, and mirrored manual policy. #### Manual policy `/config/state.manual.json` Contains persistent manual additions, corrections, and blocks. #### Local Tracker The root is configured through: `crosswatch.root_dir` The default Docker location is: `/config/.cw_provider` Additional Local Tracker profiles are stored below: `/config/.cw_provider/profiles/` Editor discovers Local Tracker workspaces from the available Watchlist, History, Ratings, and Progress files. Editor reads these files but saves corrections separately as policy. ### Current State storage Current State reads its provider baseline from: `/config/state.json` It reads manual policy from: `/config/state.manual.json` ### Editor internals Editor combines several data layers. For Current State: Provider baseline from `state.json`, plus policy from `state.manual.json` For Manual Overrides: Policy additions and blocks only For Local Tracker: Local tracker rows, plus CrossWatch provider policy For Playlist Endpoint: A live playlist snapshot from the provider Normal Save updates policy for Current State, Manual Overrides, and Local Tracker. Selective Send calls the provider add operation directly for each selected target. Provider state import reads live provider indexes and stores them as baselines. Playlist Endpoint Save uses provider playlist add, remove, and reorder operations according to endpoint capabilities. {% endtab %} {% endtabs %} ### Related topics * [Quick Add](/crosswatch/main-dashboard/navigation/quick-add) * [Watchlist](/crosswatch/main-dashboard/navigation/watchlist) * [Main dashboard](/crosswatch/main-dashboard) # Quick Add Manually send history, ratings, and watchlist actions to one or more providers for titles watched outside your usual media server flow. Quick Add sends manual actions for a movie or show. Use it for watches that happened outside your normal server flow. {% hint style="info" %} Quick Add is available in **v0.9.18 and later**. {% endhint %} {% tabs %} {% tab title="End users" %} ### What it does Quick Add can send: * **History** * **Watchlist** * **Rating** You can send one action or combine them. Typical use cases: * cinema visits * travel or offline viewing * missed scrobbles ### How to use it {% stepper %} {% step %} ### 1. Find the title Choose **Movies** or **Shows**. Search TMDb and pick the right result. {% endstep %} {% step %} ### 2. Choose the action Select **History**, **Watchlist**, **Rating**, or a mix. {% endstep %} {% step %} ### 3. Fill the extra fields If you use **History**, choose when you watched it. If you use **Rating**, select a score. {% endstep %} {% step %} ### 4. Pick providers Select the providers that should receive the action. {% endstep %} {% step %} ### 5. Send it Click **Send to providers**. {% endstep %} {% endstepper %} ### Notes * **Desktop** uses the side launcher. * **Mobile** uses the floating button. * **Send To** starts collapsed on mobile. ### Limits * Quick Add depends on TMDb search. * Provider support differs by action. * Rating needs a valid score before sending. {% endtab %} {% tab title="Power users" %} ### Action behavior * **History** marks the item as watched. * **Watchlist** adds it to provider watchlists. * **Rating** sends the selected score. Actions are checked per provider. Unsupported actions are skipped for that provider. Nuvio supports **Watchlist** and **History** actions. It does not support ratings. ### Provider selection Only configured providers are shown. Multi-instance providers are supported. CrossWatch can restore your last provider selection. You can also use: * **Use last** * **Select all** * **Clear** ### Watched date options For **History**, you can use: * **Today** * **Release date** * **Choose date** **Release date** uses TMDb metadata. It does not represent when you personally watched the item. {% endtab %} {% endtabs %} ### Related topics * [Main dashboard](/crosswatch/main-dashboard) * [Watchlist](/crosswatch/main-dashboard/navigation/watchlist) * [Dashboard widgets](/crosswatch/main-dashboard/dashboard-widgets) # Watchlist Unified watchlist view across configured providers, with filters, local hiding, and provider-aware deletes. The **Watchlist** page shows one unified view of watchlist items across CrossWatch. It combines matching items from configured providers into one interface. Use it to review, filter, compare, hide, and remove watchlist items. {% hint style="info" %} This page shows data from the most recent CrossWatch sync. It does not continuously query every provider while open. {% endhint %} {% tabs %} {% tab title="End users" %} ### What it does The page merges matching entries from your configured providers. If the same item exists on Plex, Trakt, and SIMKL, it appears once. The page can show: * total and visible item counts * last synchronized time * poster, title, release, genre, and type * which providers currently have the item ### Coverage Pulse **Coverage Pulse** shows how well the **currently visible** watchlist is represented across active providers. It is not a sync-health check. Use it to see: * how complete the current view is * which provider has the best coverage * how filters change the coverage picture #### Sync density **Sync density** is the main percentage. Quick reading: * `100%` — every visible item exists on every active provider * `75%` — visible items exist on about three quarters of provider slots * `50%` — visible items exist on about half of provider slots Lower does not always mean sync failed. Provider differences and filters can reduce it. #### Provider cards Each active provider gets a card with: * provider name or logo * visible items found on that provider * provider coverage percentage * instance names, when available If you filter to one provider, that provider usually shows `100%`. The other cards then show how many of those same items exist elsewhere. ### Views and filters Use **List view** to compare metadata and provider presence. Use **Poster view** for a more visual scan. Main filters: * **Search** * **Type** * **Provider** Select **More** for: * release state * genre * hidden items Changing filters also recalculates **Coverage Pulse**. ### Delete vs Hide local Use **Delete** to remove selected items from one provider or all supported providers. Use **Hide local** to hide items only in the current browser. **Hide local** does not remove anything from external providers. ### Refresh **Refresh** reloads the stored CrossWatch watchlist. It does not always start a new provider sync. If you need newer provider data, run a sync from [Main dashboard](/crosswatch/main-dashboard). ### Limits Keep these in mind: * provider badges can be outdated until the next sync * missing TMDb setup means less artwork and metadata * local hidden items are browser-specific For pair behavior, see [Watchlist feature](/crosswatch/settings/configure-pairs/features/watchlist). {% endtab %} {% tab title="Power users" %} ### Data source The page reads unified watchlist items from `/api/watchlist/`. CrossWatch loads up to `5,000` items per response. Matching provider rows are normalized into one item with provider membership attached. Only active configured providers appear in the matrix and in **Coverage Pulse**. ### Sync density formula **Sync density** is calculated from the filtered visible result: ``` Provider memberships for all visible items ──────────────────────────────────────────── × 100 Visible items × Active providers ``` The result is rounded to the nearest whole percent. Example: ``` 100 visible items 3 active providers 240 memberships 240 / 300 × 100 = 80% ``` ### Provider coverage cards Each provider card uses: ``` Visible items present on provider ────────────────────────────────── × 100 Total visible items ``` Instance labels are collected from visible items only. The default instance is shown first. ### Filters and local state Coverage recalculates after changes to: * search * type * provider * release state * genre * hidden-item visibility Local UI preferences include: * list or poster view * poster size * advanced-filter visibility * release and genre filters * overlay preference * hidden-item visibility ### Metadata and limits TMDb can enrich visible items with artwork, dates, genres, overview, runtime, and trailers. Coverage Pulse does **not** prove: * provider connectivity * last sync success * correct matching * write support Use [Output panel](/crosswatch/main-dashboard/output-panel) and [Analyzer](/crosswatch/main-dashboard/tools/analyzer) for troubleshooting. {% endtab %} {% endtabs %} ### Related topics * [Navigation](/crosswatch/main-dashboard/navigation) * [Main dashboard](/crosswatch/main-dashboard) * [Dashboard widgets](/crosswatch/main-dashboard/dashboard-widgets) * [Watchlist feature](/crosswatch/settings/configure-pairs/features/watchlist) # Insights Filter the Insights dashboard by feature and provider profile. Insights is the dashboard that summarizes your data across providers.
It can show: * watchlist * ratings * history * progress
### Why this exists If you use [Profiles](/crosswatch/settings/connections/profiles), Insights totals get noisy. Insights settings let you: * hide features you don’t care about * include/exclude specific provider profiles from totals ### Where settings are stored Settings are stored **in your browser**, not on the server. * Key: `insights.settings.v1` If you open CrossWatch in a different browser/device, you’ll get defaults again. ### How profile filtering works Profiles are called **Profiles** in the UI. * If you never changed profile selections, Insights includes **all profiles**. * Once you make a selection for a provider, Insights aggregates **only those profiles**. Newly discovered profiles are auto-added to your selection. ### Reset Use the Insights settings modal to reset. That clears the local settings and reloads defaults. {% hint style="info" %} This does not change sync pairs or Watcher routes. It only changes what the dashboard displays. {% endhint %} ### Related * Profiles: [Profiles](/crosswatch/settings/connections/profiles) * API payload used by Insights: [API](/crosswatch/advanced-and-api/api-reference) # Status dashboard Live status row on the Main page for monitoring, provider health, and updates.

Status row on the Main page for monitoring, health, and update checks.

This page covers the status row on **Main**. Use [Main dashboard](/crosswatch/main-dashboard) for the full page overview. Unlike **Settings → Overview**, this row focuses on live operational state. It gives you a fast operational view of CW. It groups status into two areas: 1. **Monitoring status** — **Scheduler**, **Watcher**, and **Webhook** 2. **System status** — **Sync pairs**, **CW Health**, and **Updates** Select a status item to open its settings page or run a fresh check. ### Status indicators The dashboard uses color and motion to show state. | Indicator | Meaning | | ------------------ | -------------------------------------------------------- | | Green | Enabled and working normally | | Red | Unavailable, misconfigured, or needs attention | | Grey | Disabled, still checking, or status unavailable | | Animated indicator | Activity is currently in progress | | Progress ring | Active playback progress from **Watcher** or **Webhook** | Hover over a status item to see more detail. Tooltips can show the next scheduler run, connected providers, active playback streams, or installed version. ### Monitoring status #### Scheduler The **Scheduler** runs synchronization automatically from the saved schedule. It only appears when standard or advanced scheduling is enabled. #### States | State | Meaning | | ------------------ | ------------------------------ | | `scheduled` | Standard scheduling is enabled | | `advanced` | Advanced scheduling is enabled | | Animated indicator | A scheduled task is running | | `next