> 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/crosswatch/settings/connections/media-clients.md).

# Media clients

Media clients add library, history, ratings, progress, and watchlist data to CW pairs.

{% hint style="danger" %}

### Media-client sync warning

Media clients are best used as sync destinations.

Nuvio, Kodi, and Stremio are playback and library clients. They are not perfect history authorities. When used as a source, some data can be incomplete or approximate. Some data uses when CW first observed a change.

This matters most for history dates:

* Kodi uses `lastplayed` for watched history. Ratings and resume progress lack event timestamps. CrossWatch tracks when it first sees or changes those values.
* Nuvio provides watched and progress timestamps when available. Items without required dates are skipped or marked unresolved.
* Stremio stores exact watched dates for movies, but not individual episodes. Episode watched state syncs, but exact episode dates cannot be recovered.

For the safest setup, sync one-way from a provider to the media client. Only use media-client-to-provider or two-way sync if incomplete or approximate dates can sync back to providers.

Start with **Dry run**. Enable one feature at a time. Keep removals disabled until the plan looks correct.
{% endhint %}

### Available media clients

<table data-view="cards"><thead><tr><th>Client</th><th data-card-target data-type="content-ref">Open</th></tr></thead><tbody><tr><td><strong>Kodi</strong><br>Sync existing library items, watched state, ratings, and progress.</td><td><a href="/spaces/3rh5THg1PdhVsBt3GALo/pages/EXPqYai39u3gbg8AL0sd">/spaces/3rh5THg1PdhVsBt3GALo/pages/EXPqYai39u3gbg8AL0sd</a></td></tr><tr><td><strong>Nuvio</strong><br>Sync selected-profile history, progress, and library entries.</td><td><a href="/spaces/3rh5THg1PdhVsBt3GALo/pages/0o7ACTLUstQN2Fvkwxxy">/spaces/3rh5THg1PdhVsBt3GALo/pages/0o7ACTLUstQN2Fvkwxxy</a></td></tr><tr><td><strong>Stremio</strong><br>Sync History, Progress, Watchlist, and supported Ratings.</td><td><a href="/spaces/3rh5THg1PdhVsBt3GALo/pages/vSqNM9MDlwnSSeHRS3Hy">/spaces/3rh5THg1PdhVsBt3GALo/pages/vSqNM9MDlwnSSeHRS3Hy</a></td></tr></tbody></table>

### Supported features

| Client  | History        | Ratings               | Progress       | Watchlist      |
| ------- | -------------- | --------------------- | -------------- | -------------- |
| Kodi    | Read and write | Read and write        | Read and write | Not supported  |
| Nuvio   | Read and write | Not supported         | Read and write | Read and write |
| Stremio | Read and write | Write to Stremio only | Read and write | Read and write |

History and progress support movies and individual episodes. Watchlists support movies and shows. Seasons are not synchronized separately.

{% hint style="danger" %}
Media clients can store less detail than trackers or Media servers. Start with one-way sync, then run **Dry run** before writing data.
{% endhint %}

### What you can lose

<table><thead><tr><th width="107.333251953125">Client</th><th>Key limitation</th></tr></thead><tbody><tr><td><strong>Kodi</strong></td><td>Separate plays collapse into one play count and latest date. Decimal ratings are rounded. Missing library items cannot be added.</td></tr><tr><td><strong>Nuvio</strong></td><td>Repeated plays become one history record. Progress needs a position, duration, and timestamp. Episodes and seasons cannot enter the watchlist.</td></tr><tr><td><strong>Stremio</strong></td><td>Episode watched dates are lost. Numeric ratings become reactions. Only one unfinished episode per series retains progress.</td></tr></tbody></table>

{% hint style="info" %}
Keep a tracker as the source of truth when exact dates, ratings, or several active episodes matter.
{% endhint %}

### Data handling reference

Support does not guarantee full fidelity. Some clients retain the latest state only. Others retain dated events. Review these limits before configuring a pair.

#### What can be lost or changed

| Client  | Feature         | When used as source                                                        | When used as destination                                                       | What you may lose                                                                     |
| ------- | --------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
| Kodi    | History         | CW reads the watched state, play count and `lastplayed` value              | CW writes the play count and last played date to an existing Kodi library item | Separate play events are not preserved, only the current play count and latest date   |
| Kodi    | History         | A watched item can exist without a usable `lastplayed` value               | When the source has no usable date, Kodi receives the current date and time    | The original watched date                                                             |
| Kodi    | History         | Only items in the selected Kodi libraries are available                    | The movie or episode must already exist in Kodi                                | Items that cannot be matched remain unresolved                                        |
| Kodi    | Ratings         | Kodi provides a rating from 1 to 10                                        | Kodi accepts an integer rating from 1 to 10                                    | Decimal ratings are rounded                                                           |
| Kodi    | Ratings         | Kodi does not provide the original rating date                             | CW records when the rating was first observed or changed                       | The actual date on which the user rated the item                                      |
| Kodi    | Progress        | Kodi provides the resume position and duration                             | CW writes the resume position to an existing library item                      | The original progress timestamp is not available                                      |
| Kodi    | Progress        | CW records when progress was first observed or changed                     | Completion behaviour depends on the Kodi completion setting                    | A high resume position may be treated as completed by Kodi                            |
| Kodi    | Watchlist       | Not available                                                              | Not available                                                                  | Watchlists cannot be synchronized through Kodi                                        |
| Nuvio   | History         | Nuvio provides a watched date for movies and episodes                      | Nuvio accepts the watched date provided by the source                          | Separate repeated plays are not preserved as separate events                          |
| Nuvio   | History         | Data is read from the selected Nuvio profile                               | Data is written to the selected Nuvio profile                                  | Data belonging to other Nuvio profiles is not included                                |
| Nuvio   | History         | Movies and episodes require usable identifiers                             | CW must resolve the matching Nuvio content and episode                         | Items with missing or incorrect mapping remain unresolved                             |
| Nuvio   | Ratings         | Not available                                                              | Not available                                                                  | Ratings cannot be synchronized through Nuvio                                          |
| Nuvio   | Progress        | Nuvio provides position, duration and a progress timestamp                 | All three values are required when writing progress                            | Progress without a duration or timestamp cannot be written                            |
| Nuvio   | Progress        | Progress is linked to a specific movie or episode                          | Progress at 90 percent or higher falls under the Nuvio completion policy       | High progress can be treated as completed                                             |
| Nuvio   | Watchlist       | The Nuvio Library is used as the watchlist                                 | Movies and shows are added to the Nuvio Library                                | Nuvio does not have a separate CW watchlist model                                     |
| Nuvio   | Watchlist       | Movies and shows are supported                                             | Episodes and seasons are not supported                                         | Episode and season list entries are ignored or unresolved                             |
| Stremio | Movie history   | Stremio provides the latest movie watched date and watched state           | Stremio stores one latest movie watched date                                   | Separate historical play events are not preserved                                     |
| Stremio | Movie history   | Stremio has a watched count, but CW synchronizes the current watched state | CW marks the movie watched and stores one latest date                          | The exact number and dates of previous plays                                          |
| Stremio | Episode history | Stremio stores watched episodes in a bitfield                              | Stremio stores only whether each episode is watched                            | Every individual episode watched date                                                 |
| Stremio | Episode history | CW can identify which episodes are watched, but not when they were watched | A source episode date cannot be stored in the Stremio bitfield                 | Episode dates cannot survive a round trip through Stremio                             |
| Stremio | Ratings         | Stremio cannot be used as a ratings source                                 | Ratings from another provider are converted to Stremio reactions               | The original numeric rating and rating date                                           |
| Stremio | Ratings         | No ratings are read from Stremio                                           | Ratings from 6 are written as `liked`, ratings from 8 are written as `loved`   | Ratings below 6 do not create a reaction                                              |
| Stremio | Ratings         | Episode ratings are not available                                          | Only movies and shows can receive reactions                                    | Episode ratings                                                                       |
| Stremio | Progress        | A movie can expose its current resume position                             | Stremio requires a position and duration                                       | Progress without a duration cannot be written                                         |
| Stremio | Progress        | A series record exposes one active episode and resume position             | Writing progress for another episode changes the active episode                | Multiple unfinished episodes from the same series cannot be retained at the same time |
| Stremio | Watchlist       | The Stremio Library is treated as the watchlist                            | Movies and shows are added to the Stremio Library                              | There is no separate want to watch list                                               |
| Stremio | Watchlist       | All listed movies and shows can appear as watchlist items                  | Episodes and seasons are not supported                                         | Watched library items may also be included when Stremio is the source                 |
| Stremio | All features    | Reliable matching normally requires an IMDb identifier                     | CW may use TMDb metadata to resolve an IMDb identifier                         | Items without a usable mapping remain unresolved                                      |

#### Important history differences

**Exact history versus watched state**

Trackers can store dated history events.

Media clients usually store a current state, such as watched or not watched, together with no date or only one latest date.

When a client does not provide the original date, CW cannot recreate it.

The destination will either use its own import date, use another fallback or leave the item unresolved, depending on the destination provider.

**Multiple watches**

Kodi, Nuvio and Stremio are synchronized as one current history record per movie or episode.

A tracker may contain several separate plays for the same item.

When tracker history is synchronized to a media client, those separate plays can collapse into one watched state.

A later sync back to the tracker cannot restore the original individual events.

#### Common pair examples

| Pair                        | What is synchronized                                        | Main risk                                                                                            |
| --------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| Stremio to Plex             | Movie and episode watched state                             | Stremio episodes have no individual watched date, Plex marks them watched using the import date      |
| Plex to Stremio             | Movie history, episode watched state and supported progress | Individual Plex episode dates are discarded after they are written to Stremio                        |
| Stremio to Trakt            | Movie dates and episode watched state                       | The original episode dates are unavailable                                                           |
| Trakt to Stremio            | Movie and episode watched state                             | Separate Trakt plays collapse into one state, episode dates are not retained                         |
| Provider to Stremio Ratings | Movie and show ratings                                      | Numeric ratings become `liked` or `loved`, ratings below the configured threshold create no reaction |
| Kodi to a tracker           | Watched state, latest watched date, ratings and progress    | Missing Kodi dates and synthetic rating or progress timestamps are not historical source data        |
| Tracker to Kodi             | History, ratings and progress for matching library items    | Missing watched dates become the current date, decimal ratings are rounded                           |
| Nuvio to a tracker          | Watched dates and progress from the selected profile        | Repeated plays are represented as one current item and other profiles are excluded                   |
| Tracker to Nuvio            | History, progress and watchlist                             | High progress may be treated as completed                                                            |
| Any provider to Kodi        | Supported data for movies and episodes already in Kodi      | CW cannot add missing media to the Kodi library                                                      |
| Any provider to Nuvio       | Supported data for resolvable movies and episodes           | Incorrect content or episode mapping prevents the write                                              |
| Any provider to Stremio     | Supported data using Stremio compatible identifiers         | Episode history dates, exact ratings and multiple episode progress entries can be lost               |

#### Two-way sync risks

Two-way sync can send reduced data back to the provider that originally contained more detail.

For example, a tracker can send exact episode dates to Stremio. Stremio stores only the watched state. During a later sync from Stremio to the tracker, those original dates are no longer available.

The same applies to exact ratings converted into Stremio reactions and multiple episode progress entries reduced to one active Stremio episode.

Two-way sync is not recommended when a client stores less information.

{% hint style="warning" %}
Do not use Stremio as a ratings source. Keep exact episode dates and ratings authoritative elsewhere.
{% endhint %}

For adapter-level behavior, see [Media clients synchronization](/crosswatch/settings/synchronization/media-clients.md).


---

# 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/crosswatch/settings/connections/media-clients.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.