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

# Nuvio

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

<figure><img src="/files/ZLdKJyNXedC4UFtpyNrn" alt=""><figcaption></figcaption></figure>

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.

{% hint style="warning" %}
Nuvio support is experimental. API changes can temporarily affect this integration.
{% endhint %}

### What it supports

* **Watchlist:** movies and shows.
* **History:** movies and episodes.
* **Progress:** movies and episodes.

The CrossWatch 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**.

CrossWatch 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 CrossWatch provider profiles.

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

Each CrossWatch 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](/crosswatch/settings/connections/metadata/tmdb-metadata.md).
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.

TMDb metadata improves matching, IDs, titles, artwork, and episode resolution.

### 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.
{% endtab %}

{% tab title="Power users" %}

### 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.
* IMDb- and TVDb-only items may require TMDb metadata.
* Nuvio API changes can require a CrossWatch update.

### Related docs

* [Profiles](/crosswatch/settings/connections/profiles.md)
* [Configure Pairs](/crosswatch/settings/configure-pairs.md)
* [TMDb Metadata](/crosswatch/settings/connections/metadata/tmdb-metadata.md)
  {% 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/connections/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.