Kodi
Connect Kodi through HTTP JSON-RPC for library sync and playback scrobbling.
Media-client sync warning: Review Media clients before using a media client as a source or enabling two-way sync.
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.
Kodi support is experimental. It requires Kodi 21 Omega or newer and JSON-RPC 13.5.0 or newer.
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
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
Open Kodi.
Open Settings → Services → Control.
Enable Allow remote control via HTTP.
Note the configured port.
Keep Require authentication enabled. Configure a username and password.
Confirm the CW host can reach the Kodi address and port.
Kodi disables its web server by default. Do not expose the Kodi web server to the internet.
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
Open Settings → Connections → Media clients → Kodi.
Enter the Kodi server URL, such as
http://192.168.1.50:8080.Enter the Kodi username and password when authentication is enabled.
Enable Verify SSL only for HTTPS with certificate validation.
Click Connect Kodi.
Confirm the detected Kodi version.
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.
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.serverkodi.usernamekodi.passwordkodi.verify_sslkodi.history.librarieskodi.ratings.librarieskodi.progress.librarieskodi.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
Last updated
Was this helpful?