Kodi
Kodi synchronization reference.
Synchronize history, ratings and playback progress between Kodi and other supported CW providers.
The Kodi sync adapter connects directly to the Kodi video library through HTTP JSON RPC.
Experimental
The adapter is experimental and requires Kodi 21 Omega or newer.
Media-client sync warning: Review Media clients before using a media client as a source or enabling two-way sync.
What it supports
History, read, add, update and remove
Ratings, read, add, update and remove
Progress, read, add, update and remove
Movies
Episodes
One way synchronization
Two way synchronization
Separate source whitelisting for each feature
Kodi does not support watchlist or playlist synchronization.
Shows and seasons are not synchronized as separate items.
Prerequisite
Connect Kodi under Settings → Connections → Media clients before creating a synchronization pair.
CW must show the Kodi connection as connected.
The Kodi video library must already contain the movies and episodes you want to synchronize.
CW updates existing Kodi library entries. It does not add media files, scan folders or create new Kodi library entries.
Supported features
History
CW reads the Kodi play count and last played timestamp for movies and episodes.
Kodi returns lastplayed as a local timestamp without a time zone.
CW treats it as local time on the host running the CW Kodi adapter.
CW converts it to UTC internally and back to Kodi-local time when writing history.
Adding history marks the matching Kodi item as watched and writes the available watched timestamp.
Removing history clears the play count and last played timestamp.
History synchronization requires a safe match with an existing Kodi library item.
Ratings
CW reads and writes the Kodi user rating.
Kodi uses a rating scale from 1 to 10.
Ratings have no timestamps. CW synchronizes numeric values only.
Removing a rating resets the Kodi user rating to 0.
Ratings are supported for movies and episodes.
Progress
CW reads and writes the Kodi resume position for movies and episodes.
Progress contains the current playback position and the total duration when available.
Kodi does not provide a reliable watched or resumed timestamp.
CW timestamps progress in UTC when it first observes or changes during synchronization.
Removing progress resets the resume position to the beginning.
Whitelisting
Kodi whitelisting is configured under the Kodi connection.
Different video source paths can be selected for:
History
Ratings
Progress
An empty selection includes all Kodi video sources.
A selected source path also includes media stored below that path.
Whitelisting applies when Kodi is used as either the source or the target of a pair.
Configure a pair
Open Settings → Synchronization.
Create a new pair.
Select Kodi as the source or target.
Select the correct Kodi Profile.
Select the other provider and Profile.
Start with One way mode.
Enable one supported feature.
Keep Dry run enabled for the first run.
Save the configuration.
Run the pair and review unresolved items before enabling writes.
Only features supported by both providers are shown.
For example, Progress is available only when the other provider also supports Progress.
Direction recommendations
Kodi to tracker
Use Kodi as the source when Kodi contains the history or ratings you want to send to a tracker.
A common starting configuration is:
Mode, One way
Source, Kodi
Target, Trakt, SIMKL or MDBList
Feature, History or Ratings
For new playback activity, Watcher is usually more suitable than repeatedly synchronizing the entire history.
Tracker to Kodi
Use Kodi as the target when you want to apply tracker history or ratings to items in your Kodi library.
The corresponding movie or episode must already exist in Kodi and must be matched safely.
Items missing from the Kodi library remain unresolved.
Kodi to media server
Kodi can synchronize supported features with another media server when both adapters support the feature.
Use this carefully. Libraries on both sides should contain the same content and accurate identifiers.
Start with One way mode and enable removals only after validating several clean runs.
Removals
Kodi supports removals for History, Ratings and Progress.
A removal is applied only when all relevant removal controls are enabled.
This includes:
Global removal settings
The removal setting for the pair feature
The configured synchronization direction
Do not enable removals during the first run.
Removing data from Kodi changes the corresponding fields in the Kodi database.
Troubleshooting
Items remain unresolved
Confirm that the movie or episode exists in the Kodi video library.
Check whether Kodi contains an IMDb, TMDb or TVDb identifier for the item.
For episodes, check the series identifier, season number and episode number.
Ambiguous title matches are intentionally not written.
No features are available
A feature is shown only when both providers support it.
Kodi supports History, Ratings and Progress.
The selected target or source may not support the same feature.
No Kodi items are found
Check the Kodi connection.
Confirm that the correct Kodi Profile is selected.
Review the Kodi source whitelist. An incorrect path selection can exclude the entire library.
An empty whitelist includes all video sources.
Changes are not written
Confirm that Dry run is disabled.
Confirm that Add or Update is enabled for the feature.
For removals, confirm that removal is enabled globally and for the pair feature.
Review the run details for unresolved or ambiguous items.
Summary
Kodi provides bidirectional synchronization for History, Ratings and Progress.
Only movies and episodes already present in the Kodi video library can be updated.
Start with One way mode, one feature and Dry run. Review matching results before enabling additional features, two way synchronization or removals.
How matching works
CW first tries to match Kodi library items using external identifiers.
Supported identifiers include:
IMDb
TMDb
TVDb
Episodes are matched using the show identifier together with the season and episode number.
When the source item contains external identifiers, CW does not fall back to a title match if those identifiers cannot be found in Kodi.
When no external identifier is available, CW may use the title and year. The result must be unique.
Ambiguous matches remain unresolved. CW will not update an uncertain Kodi library item.
Accurate identifiers in the Kodi library are important for reliable synchronization.
Multiple Kodi clients
Kodi supports multiple CW Profiles.
Each Profile represents a separate Kodi client and stores its own:
Server URL
Credentials
SSL setting
History whitelist
Ratings whitelist
Progress whitelist
Select the correct Profile in each pair.
Limitations
The adapter is experimental.
Kodi 21 Omega or newer is required.
Only movies and episodes are supported.
Watchlists are not supported.
Playlists are not supported.
Shows and seasons are not synchronized as separate items.
Media must already exist in the Kodi video library.
Matching depends on the metadata and external identifiers stored by Kodi.
Kodi progress does not include a reliable native modification timestamp.
Kodi must remain reachable while the synchronization runs.
Last updated
Was this helpful?