> 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/synchronization/media-clients/nuvio.md).

# Nuvio

Synchronize the Nuvio Library, watched history, and resume progress with other supported CrossWatch providers.

Nuvio is a separate CrossWatch sync provider. It is not a traditional media server or tracker. You can select it as either source or target in a pair.

{% hint style="warning" %}
**Experimental**

The Nuvio sync adapter is experimental. Nuvio API contracts may change and temporarily affect synchronization.
{% endhint %}

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

### What Nuvio can synchronize

The Nuvio sync adapter supports:

1. Watchlist
2. History
3. Progress

Ratings and playlists are not supported.

### Supported media types

#### Watchlist

Watchlist synchronization supports movies and shows.

Nuvio does not provide a separate watchlist. CrossWatch uses the Nuvio Library as the Nuvio watchlist.

Adding an item to the CrossWatch watchlist adds it to the Nuvio Library. Removing an item removes it from the Nuvio Library.

Seasons and episodes cannot be added through the Watchlist feature.

#### History

History synchronization supports movies and episodes.

Shows and seasons cannot be synchronized as watched items. For episodes, CrossWatch uses the show identity, season number, and episode number.

#### Progress

Progress synchronization supports movies and episodes.

Shows and seasons cannot have their own progress records. Progress requires both a playback position and the item’s full duration.

### Before creating a pair

1. Open **Settings** → **Connections** → **Clients**.
2. Connect Nuvio.
3. Approve the temporary Nuvio login code.
4. Select the Nuvio profile CrossWatch should use.
5. Save the connection.
6. Configure TMDb under **Settings** → **Metadata**.

TMDb metadata is strongly recommended when Nuvio is a target. It converts IMDb and TVDb identities into Nuvio’s common TMDb identities.

### Create a Nuvio pair

Open **Settings** → **Synchronization**, then create a new pair. Nuvio can be selected on either side.

#### Nuvio as source

Use Nuvio as the source when it provides the authoritative state.

Examples:

1. Nuvio Library to Trakt Watchlist.
2. Nuvio watched history to Plex.
3. Nuvio resume progress to Jellyfin.

In a one-way pair, CrossWatch applies Nuvio changes to the target. Target-only changes are not copied back.

#### Nuvio as target

Use Nuvio as the target when another provider controls the Nuvio state.

Examples:

1. Trakt Watchlist to the Nuvio Library.
2. Plex watched history to Nuvio.
3. Emby resume progress to Nuvio.

When **Watchlist Remove** is enabled, removing a source item can remove it from the Nuvio Library.

#### Two-way synchronization

Nuvio supports two-way synchronization. CrossWatch reads both providers and applies its standard merge and conflict rules.

Start with one-way synchronization. Use two-way synchronization only after validating matching and removal behavior.

### Recommended first pair

1. Set **Mode** to **One way**.
2. Enable one feature only.
3. Enable **Add**.
4. Keep **Remove** disabled.
5. Enable **Dry run**.
6. Run the pair manually.
7. Review the plan and unresolved items.
8. Disable **Dry run** after confirming the result.

Test features in this order:

1. Watchlist
2. History
3. Progress

### Watchlist behavior

CrossWatch reads the complete Nuvio Library when building its watchlist snapshot.

When writing changes, CrossWatch preserves existing Library entries and available metadata. It reads the library again afterward and confirms each requested change.

Do not change the Nuvio Library during an active Watchlist run. Library updates replace the complete library and simultaneous changes can conflict.

### History behavior

CrossWatch reads watched movie and episode records from the selected Nuvio profile.

Each watched item needs a valid watched timestamp. CrossWatch skips writes when Nuvio already has the same or newer timestamp.

When **History Remove** is enabled, CrossWatch can remove movie and episode history. This removes the watched state, not the Library title.

### Progress behavior

CrossWatch reads Nuvio’s resume position, duration, and last watched timestamp.

A progress write requires:

1. A supported movie or episode identity.
2. A valid playback position.
3. A valid duration.
4. A valid progress timestamp.

CrossWatch compares source and target timestamps before updating. It can skip writes when the target has the same or newer progress state.

You can also manage these records in **Continue Watching**. It uses the same Nuvio progress data.

### Removal safety

**Remove** is disabled by default in most CrossWatch configurations.

Removal requires permission from:

1. The global synchronization settings.
2. The pair’s feature settings.
3. The selected synchronization mode.

Start with **Add** enabled and **Remove** disabled. Take extra care with Watchlist removals because the CrossWatch Watchlist represents the complete Nuvio Library.

### Matching requirements

Nuvio works best with TMDb and IMDb identities. CrossWatch can process TMDb, IMDb, and TVDb IDs.

A direct TMDb identity is preferred. IMDb and TVDb identities may need configured TMDb metadata before CrossWatch can write them to Nuvio.

Items without a usable identity appear as unresolved and are not written.

### Troubleshooting

#### Nuvio is unavailable in the pair selector

Confirm that Nuvio is connected and that you selected a Nuvio profile. Both authentication and profile selection are required.

#### The pair reports `profile_unavailable`

The selected Nuvio profile no longer exists or cannot be returned. Open the Nuvio connection and select another profile.

#### Watchlist items are unresolved

Check for a TMDb, IMDb, or TVDb ID. Configure TMDb metadata when the source provides only IMDb or TVDb.

#### Episode history is unresolved

Confirm CrossWatch has:

1. A usable show identity.
2. A season number.
3. An episode number.

This adapter does not expose absolute episode or anime episode mappings.

#### Progress reports `duration_missing`

The source lacks a usable runtime or duration. CrossWatch cannot calculate or write resume progress without it.

#### Changes repeat during every run

Confirm that Nuvio returned the written item during verification. Also check for missing IDs, profile changes, API availability issues, or manual changes during synchronization.

#### Nuvio service unavailable

Retry the run. An experimental adapter may require a newer CrossWatch release after a Nuvio API change.
{% endtab %}

{% tab title="Power users" %}

### Module overview

| Item             | Value                                |
| ---------------- | ------------------------------------ |
| Provider name    | `NUVIO`                              |
| Module           | `providers/sync/_mod_NUVIO.py`       |
| Watchlist module | `providers/sync/nuvio/_watchlist.py` |
| History module   | `providers/sync/nuvio/_history.py`   |
| Progress module  | `providers/sync/nuvio/_progress.py`  |
| Shared logic     | `providers/sync/nuvio/_common.py`    |

### Provider contract

The Nuvio module implements the standard CrossWatch sync provider interface:

1. `health()`
2. `build_index(feature)`
3. `add(feature, items)`
4. `remove(feature, items)`

The module is bidirectional, experimental, read-after-write verified, and able to provide canonical external IDs.

`index_semantics` is `present`. Each Nuvio index represents current provider state, not a delta.

### Feature manifest

#### Watchlist

* **Enabled:** `true`
* **Types:** movies and shows.
* **Unsupported:** seasons and episodes.
* **Operations:** read, add, remove, and observed deletes.

#### History

* **Enabled:** `true`
* **Types:** movies and episodes.
* **Unsupported:** shows and seasons.
* **Operations:** read, add, remove, and observed deletes.

#### Progress

* **Enabled:** `true`
* **Types:** movies and episodes.
* **Unsupported:** shows and seasons.
* **Operations:** read, add or update, remove, and observed deletes.

Progress writes require duration.

#### Ratings and playlists

Ratings and playlists are disabled: `false`.

### Nuvio RPC endpoints

The adapter uses authenticated RPC requests.

| Purpose               | Endpoint                                                                             |
| --------------------- | ------------------------------------------------------------------------------------ |
| Profile validation    | `sync_pull_profiles`                                                                 |
| Watchlist and Library | `sync_pull_library`, `sync_push_library`                                             |
| History               | `sync_pull_watched_items`, `sync_push_watched_items`, `sync_delete_watched_items`    |
| Progress              | `sync_pull_watch_progress`, `sync_push_watch_progress`, `sync_delete_watch_progress` |

All requests use the selected Nuvio profile ID.

### Watchlist implementation

The Watchlist feature operates on the complete Nuvio Library.

Read flow:

1. Pull Library pages from Nuvio.
2. Normalize movies and series.
3. Convert identities into canonical CrossWatch keys.
4. Build a present-state index.

Write flow:

1. Pull the current Library.
2. Resolve requested items.
3. Merge additions with existing rows.
4. Preserve available Nuvio metadata.
5. Remove permitted items.
6. Push the complete resulting Library.
7. Pull the Library again.
8. Verify each requested change.

A lock prevents concurrent Library writes for the same CrossWatch and Nuvio profiles. It cannot prevent external Nuvio changes.

### Library metadata

Existing Nuvio Library metadata is preserved where possible. New entries can use configured TMDb metadata.

Supported enrichment includes name, poster, background, description, release information, and genres.

### Content identity

Nuvio content IDs currently use formats such as `tmdb:550` and `tt0137523`.

CrossWatch prefers TMDb for writes. For non-episode items, it checks:

1. Existing Nuvio content identity.
2. Direct TMDb identity.
3. Direct IMDb identity.
4. TMDb metadata resolution from IMDb or TVDb.

Episodes use the show identity, content ID, season number, episode number, and video ID. Without an existing video ID, CrossWatch creates a canonical identifier from the content ID, season, and episode.

### History implementation

History uses paginated `sync_pull_watched_items` calls. The default internal page size is 900. The maximum accepted value is 1000.

Rows are rejected without a supported identity, watched timestamp, or valid episode numbering. For duplicate canonical records, CrossWatch retains the newest watched timestamp.

CrossWatch rebuilds the Nuvio history index after writes to verify them.

### Progress implementation

Progress uses `sync_pull_watch_progress`. Pagination uses `last_watched` as a cursor.

A valid row requires a content ID, video ID, position, duration, and last watched timestamp. CrossWatch calculates percentage from position and duration.

Before writing, the standard progress policy compares source and target timestamps, positions, and durations. After writing, it confirms the resulting position and timestamp.

### Pagination

* Library reads use a maximum page size of 500.
* History reads use a maximum page size of 1000.
* Progress reads use a maximum page size of 1000.

Pagination stops when a page has fewer records than requested. Invalid responses fail the feature read rather than returning a partial snapshot.

### Configuration namespace

The default Nuvio connection is stored under `nuvio.*`.

| Key                   | Purpose                                           |
| --------------------- | ------------------------------------------------- |
| `nuvio.base_url`      | API base URL. Defaults to `https://api.nuvio.tv`. |
| `nuvio.access_token`  | Current access token.                             |
| `nuvio.refresh_token` | Refresh token.                                    |
| `nuvio.expires_at`    | Access-token expiry timestamp.                    |
| `nuvio.profile_id`    | Selected Nuvio profile ID.                        |
| `nuvio.profile_name`  | Selected profile display name.                    |

The adapter has no separate feature-tuning keys. Authentication, profile selection, pair settings, and global synchronization controls determine behavior.

### Provider profiles

Additional CrossWatch provider profiles can maintain independent Nuvio connections. Each stores separate tokens, profile selection, and connection state.

Pairs select a CrossWatch provider profile through `source_instance` or `target_instance`.

Do not confuse the CrossWatch provider profile with the Nuvio viewer profile. The provider profile identifies the complete connection. The Nuvio profile ID identifies the viewer within that account.

### Health check

The health check validates:

1. Authentication exists.
2. A Nuvio profile is selected.
3. The selected profile remains available.
4. Progress, history, and Library data can be queried.

It does not intentionally write provider data.

Possible statuses:

`not_configured`, `ok`, `token_refresh_failed`, `auth_failed`, `profile_unavailable`, `invalid_response`, and `service_unavailable`.

### Verification behavior

The adapter enables read-after-write verification for supported features. An API success response alone is not confirmation.

CrossWatch confirms Library additions and removals, history additions and removals, progress positions and timestamps, and progress removals. Failed verification returns an unresolved or failed operation.

### Removal semantics

The module reports observed-delete support for Watchlist, History, and Progress. Actual removal still depends on standard CrossWatch safety controls:

1. Global remove enablement.
2. Pair feature removal settings.
3. One-way removal mode.
4. Drop guard.
5. Mass-delete protection.
6. Observed-delete processing.

The Nuvio module does not bypass orchestrator safety controls.

### Current technical limitations

1. The API integration is experimental.
2. Ratings and playlists are unavailable.
3. Watchlist uses and replaces the complete merged Nuvio Library payload.
4. History and progress do not support standalone shows or seasons.
5. Progress requires duration.
6. Anime-specific and absolute episode numbering are unavailable.
7. Items without a resolvable TMDb or IMDb identity cannot be written.
8. IMDb and TVDb input may require TMDb metadata resolution.
9. Nuvio is not a real-time Watcher source or tracker scrobble target.
   {% 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, and the optional `goal` query parameter:

```
GET https://wiki.crosswatch.app/crosswatch/settings/synchronization/media-clients/nuvio.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.