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

# Kodi

Connect Kodi for library sync and playback scrobbling through JSON-RPC or the add-on.

{% hint style="warning" %}
**Media-client sync warning:** Review Media clients before using a media client as a source or enabling two-way sync.
{% endhint %}

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

<figure><img src="https://565675962-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3rh5THg1PdhVsBt3GALo%2Fuploads%2FDqwyhsxqDnWwsutclLTA%2Fimage.png?alt=media&#x26;token=6d6e8847-65d7-49f0-bbb5-f3cbdf2c13e8" alt=""><figcaption></figcaption></figure>

Kodi manages media in local or network libraries. CrossWatch can connect to a Kodi device in two ways. You can use one of them or both on the same profile.

|                                    | JSON-RPC                        | Add-on                     |
| ---------------------------------- | ------------------------------- | -------------------------- |
| How it connects                    | CrossWatch calls Kodi over HTTP | Kodi reports to CrossWatch |
| Sync history, ratings and progress | Yes                             | No                         |
| Kodi as a destination              | Yes                             | No                         |
| Whitelisting                       | Yes                             | No                         |
| Scrobbling from Kodi               | Yes, by polling                 | Yes, as it happens         |
| Knows who is watching              | No                              | Yes                        |
| Needs Kodi's web server            | Yes                             | No                         |

Choose **JSON-RPC** when you want to sync your Kodi library. Choose the **Add-on** when you want scrobbling, especially when several people share one Kodi. Use both for the full setup.

{% hint style="warning" %}
Kodi support is experimental. JSON-RPC requires Kodi 21 Omega or newer and JSON-RPC 13.5.0 or newer. The add-on has its own requirements, see Kodi Add-on.
{% endhint %}

{% hint style="info" %}
CW is tested with a default Kodi 21+ installation.

* Kodi supports extensive customization, third-party add-ons, skins, and modified configurations. CrossWatch cannot support every possible Kodi setup. Disable or isolate customizations when troubleshooting a connection or sync issue.
* Kodi provides limited detailed information. CW applies additional intelligence where possible, but this remains limited by the data Kodi provides.
* **Disable other Kodi scrobble/tracking add-ons before syncing with CW**
  {% endhint %}

### What CrossWatch can sync

**Read** brings data into CrossWatch; **Write** sends changes to this provider.

| Feature    | Read | Write | Notes                                                                |
| ---------- | ---- | ----- | -------------------------------------------------------------------- |
| Watchlist  | No   | No    | Unsupported.                                                         |
| History    | Yes  | Yes   | Library movies and episodes via JSON-RPC.                            |
| Ratings    | Yes  | Yes   | Library movies and episodes via JSON-RPC.                            |
| Progress   | Yes  | Yes   | Library movies and episodes via JSON-RPC.                            |
| Playlists  | No   | No    | Unsupported.                                                         |
| Collection | Yes  | No    | Read-only video library inventory via JSON-RPC; movies and episodes. |

**Live scrobbling:** Watcher source through JSON-RPC or the add-on; scrobble destination through JSON-RPC.

See the [synchronization guide](https://wiki.crosswatch.app/crosswatch/settings/synchronization/media-clients/kodi.md) for matching rules and feature restrictions.

### What it supports

* **History:** movies and episodes. JSON-RPC only.
* **Ratings:** movies and episodes. JSON-RPC only.
* **Progress:** movies and episodes. JSON-RPC only.
* **Watcher scrobbling:** movies and episodes. JSON-RPC or add-on.
* **Viewers per route:** add-on only.

Kodi ratings use the 1–10 user rating scale.

Watchlists and playlists are not supported. Series and seasons do not synchronize separately.

### Connect with JSON-RPC

#### Prepare Kodi

1. Open Kodi.
2. Open **Settings** → **Services** → **Control**.
3. Enable **Allow remote control via HTTP**.
4. Note the configured port.
5. Keep **Require authentication** enabled. Configure a username and password.
6. Confirm the CW host can reach the Kodi address and port.

{% hint style="danger" %}
Kodi disables its web server by default. Do not expose the Kodi web server to the internet.
{% endhint %}

**Allow remote control from applications on other systems** is not required. That setting controls WebSocket, TCP, and EventServer access. CW uses authenticated HTTP.

#### Connect Kodi

1. Open **Settings** → **Connections** → **Media clients** → **Kodi**.
2. Select **JSON-RPC**.
3. Enter the Kodi server URL, such as `http://192.168.1.50:8080`.
4. Enter the Kodi username and password when authentication is enabled.
5. Enable **Verify SSL** only for HTTPS with certificate validation.
6. Click **Connect Kodi**.
7. Confirm the detected Kodi version.
8. Click **Save changes**.

CW verifies JSON-RPC, confirms the server is Kodi, and checks both required versions.

### Connect with the add-on

The add-on runs on Kodi and tells CrossWatch what is playing and who is watching. Kodi's web server is not needed for it.

Install the add-on on Kodi first. See Kodi Add-on for installation, viewers and the add-on settings.

Kodi must be able to reach CrossWatch over the network. CrossWatch does not have to reach Kodi.

#### Pairing code

This is the normal way when the profile has no JSON-RPC connection.

1. Open **Settings** → **Connections** → **Media clients** → **Kodi**.
2. Select **Add-on**.
3. Click **Connect add-on**. CrossWatch shows a 6 character code and the address to use.
4. In Kodi, open the add-on settings and select **Pair with CrossWatch**.
5. Enter the CrossWatch address, then the code.
6. Wait for **Add-on connected** in CrossWatch.
7. Click **Save changes**.

A code is valid for 10 minutes and works once. Case and spaces do not matter. Click **New code** when it has expired.

You can close the window while you walk to the TV. The same code is shown when you open it again, as long as it is still valid. **Cancel** stops the pairing and turns the add-on off again for that profile.

#### Link add-on

Link is offered when the profile already has JSON-RPC connected. CrossWatch then sends the address and a one-time code to Kodi, so nothing has to be typed.

1. Open the Kodi connection and select **Add-on**.
2. Check **CrossWatch address this Kodi can reach**. Change it when Kodi cannot use the address in your browser, for example an external address.
3. Click **Link add-on**.
4. On the TV, answer **Yes** to the question.
5. Wait for **Add-on connected** in CrossWatch.
6. Click **Save changes**.

Link always goes to the Kodi of that profile, so it cannot end up on the wrong device.

When Link does not work, open **Other ways to connect** below it. It offers the pairing code and the manual setup.

#### Manual setup

**Manual setup** shows the full add-on URL. Paste it into the **Webhook URL** setting of the add-on. It appears after you asked for a pairing code or after the add-on is connected.

**Regenerate** creates a new URL. The add-on stops working until it is paired again.

{% hint style="warning" %}
The add-on URL contains a secret token. Treat it like a password.
{% endhint %}

#### After connecting

The Add-on option shows **Add-on connected**, the device name, the add-on version and the viewer names the add-on reported.

* **Pair again** or **Link again** connects a reinstalled add-on.
* **Turn off add-on**, under **Manual setup**, removes only the add-on from that profile.
* **Delete connection** removes both the add-on and the JSON-RPC connection.

### Scrobbling with viewers

The add-on reports who is watching. Each Watcher route with Kodi as its source receives a playback once, for the viewer that matches its user filter.

1. Create one Watcher route per person, with Kodi as the source.
2. Add that person's viewer name to the route's user filter. The names the add-on reported are offered in the user picker.
3. Use the same name for the viewer in the add-on settings.

A route without a user filter receives every playback. A playback without a viewer only reaches routes without a user filter.

See Watcher for routes and Kodi Add-on for viewers.

### Using both

With JSON-RPC and the add-on on the same profile:

* The add-on is used for scrobbling. CrossWatch stops polling that Kodi while the add-on is active.
* When the add-on has been quiet for 15 minutes, polling takes over. Polling does not know viewers, so only routes without a user filter receive those playbacks.
* Sync, whitelisting and Kodi as a destination keep using JSON-RPC.

{% hint style="warning" %}
One profile is one Kodi device. Connect the add-on and JSON-RPC of the same Kodi in the same profile. CrossWatch cannot detect a mismatch.
{% endhint %}

### Whitelisting

Whitelisting needs a JSON-RPC connection.

Open the **Whitelisting** tab after connecting Kodi. Click **Load libraries** to retrieve Kodi video source paths.

Configure separate source paths for History, Ratings, Progress, and Scrobbling. An empty selection includes every Kodi video source.

Whitelisting uses the full Kodi source path. Files below a selected path are included automatically.

The Scrobbling whitelist also applies to playback reported by the add-on.

### Multiple Kodi clients

Use Profiles to connect more than one Kodi client.

Each profile has its own server URL, credentials, SSL setting, feature whitelists and add-on pairing. Pairs and Watcher routes can target a specific profile.

**Kodi's built-in user profiles are not supported for sync.** They are separate from CrossWatch Profiles. The add-on can use them to tell viewers apart, see Kodi Add-on.

Start with the default profile. Add profiles after the first connection works correctly.

### Troubleshooting

#### Kodi server is unreachable

Confirm the server URL and port. The address must be reachable from the CW host or container.

Do not use `localhost` unless Kodi shares the same container or network namespace. Check firewall rules for the Kodi HTTP port.

#### Kodi rejected the credentials

Confirm the configured username and password under **Settings** → **Services** → **Control** in Kodi. They are case sensitive.

#### Server is not Kodi

The address responded, but CW could not identify Kodi. Confirm that the URL points directly to Kodi’s HTTP server.

#### Kodi or JSON-RPC version is too old

CW requires Kodi 21 Omega and JSON-RPC 13.5.0 or newer.

#### Libraries are not shown

Add video sources in Kodi, then click **Load libraries** again. An empty whitelist includes every source. CW does not support any third-party plugins.

#### Items remain unresolved

The movie or episode must already be in Kodi’s library. Add accurate IMDb, TMDb, or TVDb identifiers.

#### The pairing code is refused

The code is wrong, already used or older than 10 minutes. Click **New code** and try again. After 10 wrong codes CrossWatch refuses new tries for a while.

#### The add-on cannot reach CrossWatch

Enter an address Kodi can reach, such as `http://192.168.1.10:8787`. An address that works in your browser does not always work from Kodi. For `https://`, see the certificate requirements on the Kodi Add-on page.

#### Link says the add-on is not installed or disabled

Install or enable the CrossWatch add-on on that Kodi, then click **Link add-on** again.

#### CrossWatch keeps waiting for the add-on

The add-on is connected after its first message. Check the Status line in the add-on settings. When it says **Not paired**, pair again.

#### The add-on is connected but nothing is scrobbled

* The Watcher must be enabled and running.
* There must be an enabled Watcher route with this Kodi profile as its source.
* The viewer name in the add-on must match the route's user filter.
* The file must be inside the Scrobbling whitelist, when one is set.

#### The add-on stopped working after a change

**Regenerate**, **Turn off add-on** and **Delete connection** all invalidate the add-on's token. Pair or link again.
{% endtab %}

{% tab title="Power users" %}

### Provider capabilities

The Kodi module supports bidirectional history, ratings, and progress synchronization over JSON-RPC. It supplies playback data to Watcher through JSON-RPC polling or the add-on.

#### History

**Supported content:** movies and episodes.

**Supported operations:** read, add, and remove watched state.

Writes apply only to matched movies and episodes already indexed by Kodi.

#### Ratings

**Supported content:** movies and episodes.

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

Kodi user ratings use an integer scale from 1 to 10.

#### Progress

**Supported content:** movies and episodes.

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

Standalone series and season progress records are unsupported.

#### Watcher scrobbling

Kodi is a Watcher source for movies and episodes. A Kodi profile is usable as a source when it has a verified JSON-RPC connection, a connected add-on, or both.

**Polling:** CrossWatch polls active playback through HTTP JSON-RPC. The account is the active Kodi profile name.

**Add-on:** the add-on posts playback events to CrossWatch. Events feed the same Watcher routes, so each route keeps its own filters, options and destination.

Live TV playback is ignored. Routes can use separate Kodi profiles and scrobble whitelists.

### Add-on behavior

#### Endpoints

* `POST /webhook/kodiwatcher` receives events. The token is sent in the `X-CrossWatch-Token` header. `?token=` is accepted as a fallback.
* `POST /webhook/kodiwatcher/pair` swaps a pairing code for the endpoint, the token and the profile name.

A wrong token gets a `401`. A wrong, used or expired code gets a `401`. Ten wrong codes within 10 minutes from one client get a `429`.

#### Pairing codes

Codes are 6 characters, capitals and digits without `0`, `O`, `1` and `I`. They are valid for 10 minutes, work once and are kept in memory only. A restart drops unused codes.

Link sends its own one-time code through `Addons.ExecuteAddon`. The token is never sent to Kodi that way.

#### Connected state

A profile's add-on counts as connected after its first message with the current token. It stays connected when the add-on is quiet, and shows when it was last seen.

#### Add-on mode

While the add-on has been heard from in the last 15 minutes, CrossWatch does not poll that Kodi. After 15 minutes of silence, polling resumes when the profile has JSON-RPC. A profile with only the add-on is never polled.

#### Viewers per route

The add-on sends a list of viewers with every playback. Each route receives the event once, as the first viewer that matches its user filter.

* A route without a user filter receives every playback.
* An empty viewer list only reaches routes without a user filter.
* Viewer names from the add-on are offered in the route's user picker.

#### Unknown progress

When Kodi does not know the duration, the add-on sends no percentage. CrossWatch never treats that as 0. The playback is shown as now playing, no progress is written, and a stop only counts as watched when the add-on marks it as completed.

#### Late stops

The add-on stores a completed watch when CrossWatch is unreachable and delivers it later. Plex, Emby and Jellyfin date it with the original time. Trackers, CrossWatch history included, date it on arrival.

#### Identifiers

The add-on sends IMDb, TMDb and TVDb identifiers. Placeholder values such as `None`, `0` and `-1` are dropped. Other namespaces are ignored.

The add-on's device id is used as the server UUID for route filters. Once known, polling uses the same id.

### Matching and library requirements

CrossWatch primarily matches Kodi movies and episodes with IMDb, TMDb, and TVDb identifiers.

Writes require an existing, uniquely matched Kodi library item. CrossWatch does not create media files or library entries.

Items without a safe match remain unresolved. Correct external identifiers in Kodi before retrying.

### Whitelisting behavior

Kodi retrieves video source paths from its library over JSON-RPC. Configure independent path allowlists for History, Ratings, Progress, and Scrobbling.

A blank allowlist includes every source. A selected source includes all files below its full Kodi path.

The Scrobbling allowlist is applied to add-on events by file path. Credentials in Kodi paths are stripped before matching.

### Profiles and instances

The default Kodi profile stores configuration under `kodi.*`.

Additional profiles are stored under `kodi.instances.<profile>.*`. Each profile stores its server URL, credentials, SSL setting, and separate feature allowlists.

Pairs and Watcher routes select a specific Kodi profile. Start with the default profile before creating additional connections.

### Config keys

Common keys are stored under `kodi.*`:

* `kodi.server`
* `kodi.username`
* `kodi.password`
* `kodi.verify_ssl`
* `kodi.history.libraries`
* `kodi.ratings.libraries`
* `kodi.progress.libraries`
* `kodi.scrobble.libraries`

Additional profiles use `kodi.instances.<profile>.*`.

### Connection validation

CrossWatch uses JSON-RPC to validate the configured endpoint. It confirms the server identity and checks Kodi and JSON-RPC versions.

Kodi can require HTTP Basic Auth for each request. Keep authentication enabled whenever possible.

Before Link, CrossWatch checks over JSON-RPC that the add-on is installed and enabled on that Kodi.

### Current limitations

* The adapter and the add-on are experimental.
* Kodi 21 Omega and JSON-RPC 13.5.0 are minimum requirements for JSON-RPC.
* Watchlists and playlists are unsupported.
* Series and seasons are not standalone sync items.
* Live TV playback is not scrobbled.
* CrossWatch never creates Kodi library entries.
* Kodi's built-in user profiles are unsupported for sync.
* A profile with only the add-on cannot sync, cannot be a destination and has no whitelisting.
* A profile with only the add-on is not shown as connected in the Connections overview.
* CrossWatch cannot verify that the add-on and JSON-RPC of one profile belong to the same Kodi device.

### Related docs

* Kodi Add-on
* Profiles
* Configure Pairs
* Watcher
  {% 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://wiki.crosswatch.app/crosswatch/settings/connections/media-clients/kodi.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
