> 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/blueprint-architecture/sync/_mod_plex/progress.md).

# progress

Related:

* Pair setting: [Progress](/crosswatch/configure-pairs/features/progress.md)
* Technical blueprint: [Progress](broken://spaces/3rh5THg1PdhVsBt3GALo/pages/6mUNmCn3Ju6CJzYTrpZR)

{% tabs %}
{% tab title="End users" %}

### What syncs

This feature syncs **resume position** ("Continue Watching") for Plex items.

### Supported media types

* Movies: ✅
* Episodes: ✅

### Reads vs writes

* Reads: Plex "Continue Watching" / resumable items.
* Writes:
  * `add` upserts resume position.
  * `remove` (clear) is **blocked** on Plex for safety.

### Key settings (per pair)

* `features.progress.enable`
* `features.progress.add`
* `features.progress.remove`: **ignored** for Plex clears
* `features.progress.min_seconds` (default `60`)
* `features.progress.delta_seconds` (default `30`)
* `features.progress.max_percent` (default `95`)

### Known limitations

* Progress **never clears from absence**.
* Near-complete items (>= `max_percent`) are skipped.
* Clearing progress on Plex is unreliable. CrossWatch blocks it.
  {% endtab %}

{% tab title="Power users" %}

### Index behavior

Primary index comes from Plex "Continue Watching":

* `viewOffset` → `progress_ms`
* `duration` → `duration_ms`
* `lastViewedAt`/`viewedAt` → `progress_at`

### Write behavior

* Upsert uses PlexAPI `updateProgress(ms, state="stopped")`.
* Fallback uses `updateTimeline` when needed.
* Clears are intentionally blocked (`remove()` returns `not_supported`).

### Planner notes

Progress uses conservative thresholds to avoid spam:

* ignore progress < `min_seconds`
* only write when delta >= `delta_seconds`
* ignore progress >= `max_percent` of duration

### Code map

* `providers/sync/plex/_progress.py`
* `cw_platform/orchestrator/_planner.py::diff_progress`

### Matching notes

Plex writes need a **rating key**.

Resolution order:

1. Use `ids["plex"]` when present.
2. Else resolve by GUID candidates derived from external IDs.

If you see repeated "unresolved" items, your external IDs are missing.
{% endtab %}
{% endtabs %}


---

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

```
GET https://wiki.crosswatch.app/blueprint-architecture/sync/_mod_plex/progress.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.