> 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/synchronization/media-clients/kodi.md). # Kodi 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. The adapter is experimental and requires Kodi 21 Omega or newer. {% tabs %} {% tab title="End users" %} ### What it supports 1. History, read, add, update and remove 2. Ratings, read, add, update and remove 3. Progress, read, add, update and remove 4. Movies 5. Episodes 6. One way synchronization 7. Two way synchronization 8. 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: 1. History 2. Ratings 3. 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 1. Open **Settings** → **Synchronization**. 2. Create a new pair. 3. Select Kodi as the source or target. 4. Select the correct Kodi Profile. 5. Select the other provider and Profile. 6. Start with One way mode. 7. Enable one supported feature. 8. Keep **Dry run** enabled for the first run. 9. Save the configuration. 10. 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: 1. Mode, One way 2. Source, Kodi 3. Target, Trakt, SIMKL or MDBList 4. 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: 1. Global removal settings 2. The removal setting for the pair feature 3. 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. {% endtab %} {% tab title="Power users" %} ### How matching works CW first tries to match Kodi library items using external identifiers. Supported identifiers include: 1. IMDb 2. TMDb 3. 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: 1. Server URL 2. Credentials 3. SSL setting 4. History whitelist 5. Ratings whitelist 6. Progress whitelist Select the correct Profile in each pair. ### Limitations 1. The adapter is experimental. 2. Kodi 21 Omega or newer is required. 3. Only movies and episodes are supported. 4. Watchlists are not supported. 5. Playlists are not supported. 6. Shows and seasons are not synchronized as separate items. 7. Media must already exist in the Kodi video library. 8. Matching depends on the metadata and external identifiers stored by Kodi. 9. Kodi progress does not include a reliable native modification timestamp. 10. Kodi must remain reachable while the synchronization runs. {% 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/synchronization/media-clients/kodi.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.