> 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
> 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. CrossWatch works with Nuvio cloud and with self-hosted Nuvio backends.
Nuvio is an open-source media center and library companion. It is not a media server or tracker. CrossWatch connects to the Nuvio account service and uses the selected profile's data.
{% hint style="warning" %}
Nuvio support is experimental. API changes can temporarily affect this integration.
{% endhint %}
{% hint style="info" %}
TMDb Metadata is basically required for Nuvio. Without it, synchronization is severely limited.
{% endhint %}
### End users
#### 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.
#### Nuvio server
CrossWatch can connect to two kinds of Nuvio servers:
* **Nuvio cloud:** the official Nuvio service. This is the default.
* **Self-hosted:** your own Nuvio backend, set up with the [Nuvio self-host](https://github.com/NuvioMedia/self-host) project.
Each CW provider profile has its own server choice. You can use Nuvio cloud on one profile and a self-hosted backend on another.
#### Connect Nuvio
1. Open **Settings → Connections → Clients → Nuvio**.
2. Under **Nuvio server**, choose **Nuvio cloud** or **Self-hosted**.
3. For self-hosted, enter your **Backend URL** and click **Check server**. See [Self-hosted Nuvio](#self-hosted-nuvio).
4. Click **Connect Nuvio**.
5. Approve the displayed temporary code on the Nuvio approval page.
6. Return to CrossWatch after approval is detected.
7. Select the Nuvio profile to synchronize.
8. 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.
#### Self-hosted Nuvio
Enter the same Backend URL you use in your Nuvio apps, for example `https://nuvio.example.com`. When you leave out `https://`, CrossWatch adds it.
When you click **Check server** or **Connect Nuvio**, CrossWatch reads the discovery endpoint of your backend:
`https://nuvio.example.com/.well-known/nuvio`
From that endpoint CrossWatch takes the backend URL and the public client key. You do not have to enter a key yourself.
The approval page for a self-hosted backend is `/tv-login`. It opens on your own server, not on nuvio.tv. Log in there with your self-hosted Nuvio account.
Requirements:
* The backend must be reachable from the machine that runs CrossWatch. When CrossWatch runs in Docker or on a NAS, `localhost` points to that machine, not to your Nuvio server.
* The backend must support TV login. Current Nuvio self-host releases do.
* Use the address the backend reports as its public URL. CrossWatch uses the `backend_url` from the discovery endpoint for all requests.
{% hint style="info" %}
**Local mode:** a Nuvio backend set up without `--domain` only listens on localhost, and the approval page is served on the account dashboard (port `3000`) instead of the backend (port `8000`). CrossWatch then shows an extra link to open the approval page on port 3000. Local mode is meant for testing. For normal use, set up Nuvio with `--domain`.
{% endhint %}
#### Change the Nuvio server
Tokens only work on the server that issued them. To switch between Nuvio cloud and self-hosted, or to another backend:
1. Click **Disconnect Nuvio**.
2. Choose the new server.
3. Click **Connect Nuvio** and complete the login again.
The server choice is locked while Nuvio is connected.
#### 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.
Nuvio profiles work the same on Nuvio cloud and self-hosted backends.
#### Recommended first setup
1. Configure TMDb Metadata.
2. Choose the Nuvio server, 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.
**Could not reach the Nuvio server**
CrossWatch cannot connect to the Backend URL. Check the address and port, and make sure the backend is reachable from the machine that runs CrossWatch. `localhost` only works when CrossWatch and Nuvio run on the same machine.
**Not a valid self-hosted Nuvio server**
The address did not return a valid Nuvio discovery document. Use the Backend URL from your Nuvio setup, not the account dashboard or another service.
**That is the Nuvio cloud server**
You entered the official Nuvio address as a self-hosted backend. Choose **Nuvio cloud** instead.
**This Nuvio server does not support TV login**
The backend does not offer TV login. CrossWatch only supports TV login. Update your Nuvio self-host installation.
**Disconnect Nuvio before changing the server**
The server cannot change while Nuvio is connected. See [Change the Nuvio server](#change-the-nuvio-server).
**The approval page shows an error on a self-hosted backend**
When Nuvio runs in local mode (setup without `--domain`), use the extra link to open the approval page on port 3000.
### Power users
#### Provider capabilities
The Nuvio module is bidirectional. It verifies changes after writing them. Nuvio cloud and self-hosted backends use the same module.
**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 its own server choice, tokens and selected Nuvio profile.
Pairs select a provider profile using `source_instance` or `target_instance`.
#### Config keys
Stored under `nuvio.*`:
* `nuvio.server_mode` — `cloud` or `self_hosted`. Defaults to `cloud`.
* `nuvio.base_url` — API base URL. Defaults to `https://api.nuvio.tv`. For self-hosted, the `backend_url` from the discovery endpoint.
* `nuvio.publishable_key` — public client key from the discovery endpoint. Only stored for `self_hosted`.
* `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.
For Nuvio cloud, CrossWatch supplies the required client details. For self-hosted, CrossWatch takes them from the discovery endpoint. There is no manual client key setting.
Set the server through the connection window, not by editing `server_mode`, `base_url` or `publishable_key` by hand.
Do not copy tokens between Nuvio profiles, CrossWatch provider profiles, or Nuvio servers.
#### Discovery endpoint
A self-hosted backend answers `GET /.well-known/nuvio` with:
```json
{
"version": 1,
"service": "nuvio",
"self_hosted": true,
"backend_url": "https://nuvio.example.com",
"publishable_key": "",
"capabilities": {
"email_password_auth": true,
"tv_login": true
}
}
```
CrossWatch accepts the document only when:
* `version` is `1`, `service` is `nuvio` and `self_hosted` is `true`.
* `backend_url` is a plain `http` or `https` URL without credentials, query or fragment.
* `publishable_key` is not empty.
* `capabilities.tv_login` is `true`.
* The response is not larger than 64 KB.
The official Nuvio address is rejected as a self-hosted backend.
#### Server check reasons
The server check can return:
* `invalid_url`
* `official_server`
* `connection_failed`
* `http_error`
* `invalid_document`
* `unsupported_version`
* `wrong_service`
* `not_self_hosted`
* `missing_configuration`
* `response_too_large`
* `tv_login_unsupported`
* `disconnect_first`
#### 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.
Tokens are refreshed against the server that issued them.
#### 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.
* Self-hosted backends must support TV login. Email and password login is not supported.
* Changing the Nuvio server requires disconnecting first.
* Nuvio API changes can require a CrossWatch update.
#### Related docs
* Profiles
* Configure Pairs
* TMDb Metadata
* [Nuvio self-host](https://github.com/NuvioMedia/self-host)
---
# 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=&goal=
```
`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.
