> 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

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

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

Connect CW to a Kodi media client through HTTP JSON-RPC.

Kodi manages media in local or network libraries. CrossWatch connects directly to Kodi’s HTTP JSON-RPC interface.

{% hint style="warning" %}
Kodi support is experimental. It requires Kodi 21 Omega or newer and JSON-RPC 13.5.0 or newer.
{% endhint %}

{% hint style="info" %}
CW is tested with a default Kodi 21+ installation. No additional add-ons are required.

* 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 it supports

* **History:** movies and episodes.
* **Ratings:** movies and episodes.
* **Progress:** movies and episodes.
* **Watcher scrobbling:** movies and episodes.

Kodi ratings use the 1–10 user rating scale.

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

### 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. Enter the Kodi server URL, such as `http://192.168.1.50:8080`.
3. Enter the Kodi username and password when authentication is enabled.
4. Enable **Verify SSL** only for HTTPS with certificate validation.
5. Click **Connect Kodi**.
6. Confirm the detected Kodi version.
7. Click **Save**.

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

### Whitelisting

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.

### Multiple Kodi clients

Use Profiles to connect more than one Kodi client.

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

**Kodi's built-in user profiles are not supported.** They are separate from CrossWatch Profiles.

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.

#### 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 thid-party plugins.

#### Items remain unresolved

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

{% tab title="Power users" %}

### Provider capabilities

The Kodi module supports bidirectional history, ratings, and progress synchronization. It also supplies playback data to Watcher.

#### 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. CrossWatch polls active playback through HTTP JSON-RPC.

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

### 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. 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.

### 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.

### Current limitations

* The adapter is experimental.
* Kodi 21 Omega and JSON-RPC 13.5.0 are minimum requirements.
* 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.

### Related docs

* [Profiles](/crosswatch/settings/connections/profiles.md)
* [Configure Pairs](/crosswatch/settings/configure-pairs.md)
* [Watcher](/crosswatch/settings/scrobbler/watcher.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/kodi.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.