Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Nuvio

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

Connect Nuvio through TV login, select a profile, and synchronize your library, history, and resume progress.

Nuvio is an open-source media center and library companion. It is not a media server or tracker. CrossWatch connects to Nuvio’s account service and uses the selected profile’s data.

Nuvio support is experimental. API changes can temporarily affect this integration. TMDb Metadata is basicaly required for Nuvio. Without it, synchronization are severely limited.

What it supports

  • Watchlist: movies and shows.

  • History: movies and episodes.

  • Progress: movies and episodes.

CW Watchlist maps to the Nuvio Library.

Ratings and playlists are not supported. Nuvio is not a Watcher source or scrobble target.

Connect Nuvio

  1. Open Settings → Connections → Clients → Nuvio.

  2. Click Connect Nuvio.

  3. Approve the displayed temporary code on Nuvio’s approval page.

  4. Return to CrossWatch after approval is detected.

  5. Select the Nuvio profile to synchronize.

  6. Click Save.

CW selects the profile automatically when only one profile exists.

No API key is required. CrossWatch stores authentication tokens and your selected profile. It never stores your Nuvio password.

Nuvio profiles

Nuvio profiles differ from CW provider profiles.

A CrossWatch provider profile is a complete Nuvio connection. A Nuvio profile selects the viewer data within that connection.

Each CW provider profile can use a different Nuvio profile. If the selected profile disappears, CrossWatch marks the connection unavailable until you select another.

Recommended first setup

  1. Configure TMDb Metadata.

  2. Connect Nuvio and select the correct profile.

  3. Create a one-way pair with Nuvio as source or target.

  4. Enable one feature and keep Dry run enabled.

  5. Test Watchlist before History and Progress.

Continue Watching

Connected Nuvio profiles appear in Continue Watching.

You can view progress, change resume percentage, remove progress, and mark items watched.

Progress updates require a known duration. CrossWatch cannot reliably update items without one.

Troubleshooting

The approval page does not open

Allow popups for CrossWatch. The connection window also shows a manual approval link and code.

The login code expired

Click Connect Nuvio again to generate a new code.

Nuvio is authenticated but not connected

Select a Nuvio profile and click Save. Authentication alone is insufficient.

Selected profile unavailable

The profile was removed or Nuvio cannot return it. Reconnect Nuvio or choose another profile.

Token refresh failed

Disconnect Nuvio, then complete the connection again.

Items are unresolved

Confirm that the source has a TMDb, IMDb, or TVDb ID. Configure TMDb metadata when no direct TMDb ID exists.

Nuvio service unavailable or invalid response

Retry later and check for a newer CrossWatch version. Nuvio API changes can require an adapter update.

Provider capabilities

The Nuvio module is bidirectional. It verifies changes after writing them.

Watchlist

Supported content: movies and shows.

Supported operations: read, add, and remove.

Nuvio watchlist synchronization uses the Nuvio Library. CrossWatch reads the library, applies changes, then writes the resulting library. Existing entries and available metadata remain intact.

CrossWatch reads the library again after writing. It confirms only expected additions and removals.

Avoid manual Library changes during an active Watchlist run.

History

Supported content: movies and episodes.

Supported operations: read, add, and remove watched items.

History writes need a valid watched timestamp. Episode writes include the series ID, season number, and episode number.

Shows and seasons are not written as watched entities.

Progress

Supported content: movies and episodes.

Supported operations: read, add or update, and remove.

Progress writes require a content ID, playback position, duration, and progress timestamp.

Shows and seasons have no standalone progress records. The adapter uses standard season and episode numbering.

Matching and IDs

Nuvio content IDs use TMDb or IMDb values. TMDb is the preferred write identity:

tmdb:550

Existing Nuvio records can use IMDb IDs:

tt0137523

When the source has only IMDb or TVDb IDs, CrossWatch uses TMDb metadata to resolve a TMDb content ID.

TMDb can enrich new Nuvio Library entries with titles, release years, descriptions, genres, posters, and backgrounds.

Profiles and instances

The default provider profile stores configuration under nuvio.*.

Additional provider profiles use independent connections in the provider instances structure. Each profile has separate tokens and a selected Nuvio profile.

Pairs select a provider profile using source_instance or target_instance.

Config keys

Stored under nuvio.*:

  • nuvio.base_url — API base URL. Defaults to https://api.nuvio.tv.

  • nuvio.access_token — temporary API access token.

  • nuvio.refresh_token — token used to refresh access.

  • nuvio.expires_at — token expiry as an epoch timestamp.

  • nuvio.profile_id — selected numeric Nuvio profile ID.

  • nuvio.profile_name — selected Nuvio profile name.

There is no configurable public client key. CrossWatch supplies the required Nuvio client details.

Do not copy tokens between Nuvio profiles or CrossWatch provider profiles.

Token refresh

CrossWatch refreshes access tokens when they are missing or nearly expired.

After an authentication error, CrossWatch attempts one refresh and retries the request. Reconnect when the refresh token is invalid.

Connection health check

The health check confirms authentication, the selected profile, and read access to progress, history, and the Nuvio Library.

Possible states include:

  • missing_authentication

  • profile_unavailable

  • token_refresh_failed

  • auth_failed

  • invalid_response

  • service_unavailable

Current limitations

  • The adapter is experimental.

  • Ratings, playlists, and collections are unsupported.

  • Watchlist supports movies and shows only.

  • History and progress support movies and episodes only.

  • Progress writes require a known duration.

  • Nuvio is not a Watcher source or scrobble target.

  • TMDb Metadata is required. Without it, matching and synchronization are severely limited.

  • Nuvio API changes can require a CrossWatch update.

Related docs

PreviousKodiNextStremio

Last updated

Was this helpful?