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

Synchronization policies

Runtime policies for pair sync, deletions, conflicts, playlists, and provider capabilities.

Use this reference to understand what CrossWatch (CW) reads, writes, and removes.

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

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 for pair setup and 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

Term
Meaning

Source

The left provider. In two-way sync, it is the final ratings and progress fallback.

Destination

The right provider. One-way pairs write Source changes here.

Snapshot

Current provider items for one feature.

Baseline

Last stable provider state. It detects real additions and removals.

Observed deletion

A prior-baseline item absent from a reliable current snapshot.

Tombstone

Stored delete marker that prevents immediate restoration.

Managed item

An 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.

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.

Use one-way sync when one provider should remain authoritative.

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 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.

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:

Setting
Default
Purpose

Minimum progress

60 seconds

Ignores accidental starts and very small resume positions

Change threshold

30 seconds

Avoids writes when the difference between providers is insignificant

Near completion threshold

95%

Stops synchronizing progress near completion and leaves the watched state to History

Timestamp tolerance

30 seconds

Protects a meaningfully newer target position from being overwritten

Progress removal

Disabled

Resume positions are not cleared unless removal is enabled

Replay watched items

Disabled

Watched 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:

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.

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.

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.

Configuration summary

Feature settings can override global values:

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:

Last updated

Was this helpful?