Nuvio

Nuvio synchronization reference.

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.

Experimental

The Nuvio sync adapter is experimental. Nuvio API contracts may change and temporarily affect synchronization.

Media-client sync warning: Review Media clients before using a media client as a source or enabling two-way sync.

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.

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.