Synchronization policies

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

End users

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

Two-way sync and mirror removals can spread bad matches and unwanted deletes.

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

Two-way sync and mirror can spread bad matches and unwanted deletions.

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.

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.

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.

Use two-way sync only when matching is reliable on both providers.

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:

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.

Power users

Configuration summary

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:

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:

membership: managed_only
order: ignore
allow_mass_delete: false