> For the complete documentation index, see [llms.txt](https://wiki.crosswatch.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.crosswatch.app/getting-started/support-matrix/pair-synchronization.md).

# Pair synchronization

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 | CrossWatch local, Plex, Jellyfin, Emby, Nuvio, Trakt, SIMKL, MDBList, PublicMetaDB, AniList, TMDb | CrossWatch local, Plex, Jellyfin, Emby, Nuvio, Trakt, SIMKL, MDBList, PublicMetaDB, AniList, TMDb |
| Ratings   | CrossWatch local, Plex, Trakt, SIMKL, MDBList, PublicMetaDB, AniList, TMDb                        | CrossWatch local, Plex, Trakt, SIMKL, MDBList, PublicMetaDB, AniList, TMDb                        |
| History   | CrossWatch local, Plex, Jellyfin, Emby, Nuvio, Trakt, SIMKL, MDBList, PublicMetaDB, Tautulli      | CrossWatch local, Plex, Jellyfin, Emby, Nuvio, Trakt, SIMKL, MDBList, PublicMetaDB                |
| Progress  | CrossWatch local, Plex, Jellyfin, Emby, Nuvio, PublicMetaDB                                       | CrossWatch local, Plex, Jellyfin, Emby, Nuvio, PublicMetaDB                                       |

### Pair behavior

| Pair behavior                    |                                            Supported | Notes                                                                  |
| -------------------------------- | ---------------------------------------------------: | ---------------------------------------------------------------------- |
| One-way sync                     | <i class="fa-check" style="color:green;">:check:</i> | Source writes to destination                                           |
| Two-way sync                     | <i class="fa-check" style="color:green;">:check:</i> | Both sides are compared and synced                                     |
| Per-feature enablement           | <i class="fa-check" style="color:green;">:check:</i> | Watchlist, ratings, history, and progress can be enabled independently |
| Per-feature additions            | <i class="fa-check" style="color:green;">:check:</i> | Add and update writes can be enabled independently                     |
| Per-feature removals             | <i class="fa-check" style="color:green;">:check:</i> | Removal writes can be enabled independently                            |
| Multiple named provider profiles | <i class="fa-check" style="color:green;">:check:</i> | Source and destination profile IDs are preserved                       |
| Dry run                          | <i class="fa-check" style="color:green;">:check:</i> | Plans and logs changes without remote writes                           |
| Verify after write               |                                              Limited | Runs only when the destination provider supports verification          |

### Matching and identity resolution

#### Global identity and fallback

| Capability                 | Scope             |                                            Supported | Notes                                    |
| -------------------------- | ----------------- | ---------------------------------------------------: | ---------------------------------------- |
| Canonical identity mapping | Global            | <i class="fa-check" style="color:green;">:check:</i> | Normalizes provider IDs into common keys |
| IMDb IDs                   | Global            | <i class="fa-check" style="color:green;">:check:</i> | Used for matching and export             |
| TMDb IDs                   | Global            | <i class="fa-check" style="color:green;">:check:</i> | Primary identity for PublicMetaDB        |
| TVDB IDs                   | Global            | <i class="fa-check" style="color:green;">:check:</i> | Used where available                     |
| Trakt IDs                  | Global            | <i class="fa-check" style="color:green;">:check:</i> | Used where available                     |
| SIMKL IDs                  | Global            | <i class="fa-check" style="color:green;">:check:</i> | Used where available                     |
| MDBList IDs                | Global            | <i class="fa-check" style="color:green;">:check:</i> | Used where available                     |
| Provider native IDs        | Provider-specific | <i class="fa-check" style="color:green;">:check:</i> | Preserved for provider-specific matching |
| Title and year fallback    | General matching  | <i class="fa-check" style="color:green;">:check:</i> | Used when strict ID matching is disabled |

#### Provider-specific matching

| Capability                       | Scope                |                                            Supported | Notes                                                                  |
| -------------------------------- | -------------------- | ---------------------------------------------------: | ---------------------------------------------------------------------- |
| Strict ID matching               | Plex, Jellyfin, Emby | <i class="fa-check" style="color:green;">:check:</i> | Disables title and year search fallback                                |
| Plex Discover watchlist matching | Plex                 | <i class="fa-check" style="color:green;">:check:</i> | Primary Plex watchlist path                                            |
| Plex PMS metadata match          | Plex                 | <i class="fa-check" style="color:green;">:check:</i> | Can resolve external IDs through the selected server                   |
| Plex PMS watchlist fallback      | Plex                 |                                             Optional | Disabled by default for strict Discover behavior                       |
| Plex fallback GUID search        | Plex                 |                                             Optional | Searches beyond visible libraries. Best for temporary troubleshooting. |

#### Anime and metadata enrichment

| Capability                    | Scope         |                                            Supported | Notes                                           |
| ----------------------------- | ------------- | ---------------------------------------------------: | ----------------------------------------------- |
| AniBridge local anime mapping | AniList pairs | <i class="fa-check" style="color:green;">:check:</i> | Enriches IDs for watchlist and ratings          |
| Anime-only filtering          | AniList pairs | <i class="fa-check" style="color:green;">:check:</i> | Skips content that cannot be confirmed as anime |
| Metadata locale               | TMDb metadata | <i class="fa-check" style="color:green;">:check:</i> | Default is `en-US`                              |
| Metadata cache                | TMDb metadata | <i class="fa-check" style="color:green;">:check:</i> | Default cache lifetime is 720 hours             |

### Synchronization controls

#### Write controls

| Control                  |                                            Supported | Default or behavior                                      |
| ------------------------ | ---------------------------------------------------: | -------------------------------------------------------- |
| Global addition gate     | <i class="fa-check" style="color:green;">:check:</i> | Enabled                                                  |
| Global removal gate      | <i class="fa-check" style="color:green;">:check:</i> | Disabled                                                 |
| Pair feature additions   | <i class="fa-check" style="color:green;">:check:</i> | Pair setting overrides the global default                |
| Pair feature removals    | <i class="fa-check" style="color:green;">:check:</i> | Pair setting overrides the global default                |
| Source delete mode       | <i class="fa-check" style="color:green;">:check:</i> | Removes only when the source deletion is observed        |
| Mirror delete mode       | <i class="fa-check" style="color:green;">:check:</i> | Destination is forced to follow the source. Destructive. |
| Include observed deletes | <i class="fa-check" style="color:green;">:check:</i> | Enabled                                                  |
| Tombstone retention      | <i class="fa-check" style="color:green;">:check:</i> | Default 1 day                                            |
| Dry run                  | <i class="fa-check" style="color:green;">:check:</i> | Disabled                                                 |
| Verify after write       |                                              Limited | Disabled. Requires provider support.                     |

#### Safety and guardrails

| Control                             |                                            Supported | Default or behavior                             |
| ----------------------------------- | ---------------------------------------------------: | ----------------------------------------------- |
| Drop guard                          | <i class="fa-check" style="color:green;">:check:</i> | Disabled                                        |
| Mass delete permission              | <i class="fa-check" style="color:green;">:check:</i> | Enabled                                         |
| Suspect inventory shrink guard      | <i class="fa-check" style="color:green;">:check:</i> | Applies after a minimum previous inventory size |
| Blackbox unresolved item quarantine | <i class="fa-check" style="color:green;">:check:</i> | Enabled                                         |
| Pair-scoped blackbox                | <i class="fa-check" style="color:green;">:check:</i> | Enabled                                         |
| Blackbox addition blocking          | <i class="fa-check" style="color:green;">:check:</i> | Enabled                                         |
| Blackbox removal blocking           | <i class="fa-check" style="color:green;">:check:</i> | Enabled                                         |
| Blackbox cooldown                   | <i class="fa-check" style="color:green;">:check:</i> | Default 30 days                                 |
| Unresolved and freeze state         | <i class="fa-check" style="color:green;">:check:</i> | Prevents repeated unsafe writes                 |
| Flapper protection                  | <i class="fa-check" style="color:green;">:check:</i> | 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               | Plex, Jellyfin, Emby  | Per-feature and scrobble library allowlists             |
| Ignore dropped shows            | Trakt, SIMKL, MDBList | Optional history filter                                 |
| Trakt Collection write          | Trakt                 | Optional when adding history                            |
| Include manually marked watched | Plex                  | Optional. Enabled by default.                           |

#### Progress-specific controls

| Control                        | Scope                                 | Default or behavior                                  |
| ------------------------------ | ------------------------------------- | ---------------------------------------------------- |
| Progress minimum seconds       | All supported progress pairs          | Default `60`. Ignores tiny offsets                   |
| Progress change threshold      | All supported progress pairs          | Default `30`. Avoids unnecessary writes              |
| Ignore near-completed progress | All supported progress pairs          | Default `95` percent. Lets history own watched state |
| Replay watched items           | Plex, Jellyfin, and Emby destinations | Default off. Allows rewatches to restore progress    |
| Progress timestamp tolerance   | Plex, Jellyfin, and Emby destinations | Default `30` seconds. Accepted range `0` to `300`    |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://wiki.crosswatch.app/getting-started/support-matrix/pair-synchronization.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.