Kodi Sync

Kodi Sync

Sync your Kodi movie library into Tonkatsu Box over your local network. Movies are matched against TMDB, with watch status, ratings, and metadata tracking.

What gets synced

Kodi data	Tonkatsu Box
Movies in VideoLibrary	Movies matched to TMDB
TMDB ID / IMDB ID	Used for matching
Watch status (watched)	Status "Completed"
Partially watched	Status "In Progress"
Unwatched	Status "Planned"
User rating (1-10)	Saved as rating
Last played date	Saved as last played date
Movie sets	Optional sub-collections (e.g. "Harry Potter Collection (kodi)")
Metadata	Saved as user comment

Requirements

• Kodi with remote control enabled over the network. Both devices must be on the same Wi-Fi or LAN.
• TMDB API key - needed to match movies. Set up TMDB

How to set up Kodi

Enable remote control in Kodi so Tonkatsu Box can connect:

1. Open Kodi
2. Go to Settings > Services > Control
3. Enable "Allow remote control via HTTP"
4. Note the Port (default: 8080)
5. Optionally set a Username and Password

How to find Kodi's IP address

You need the local IP of the device running Kodi. Both devices (Kodi and Tonkatsu Box) must be on the same Wi-Fi / LAN network.

Option 1 - Inside Kodi:

1. Go to Settings > System Information > Network
2. The IP address is shown on screen (e.g. 192.168.1.105)

Option 2 - On the Kodi device itself:

• Windows: open Command Prompt → type ipconfig → look for IPv4 Address under your Wi-Fi or Ethernet adapter
• Linux: open terminal → type ip a or hostname -I
• Android (Kodi on a TV box): Settings > Network > Wi-Fi > tap connected network → IP address
• macOS: System Preferences > Network → the IP is shown for the active connection

Tip: The IP usually looks like 192.168.x.x or 10.0.x.x. If you're connecting from a phone, make sure it's on the same Wi-Fi network as Kodi - not on mobile data.

How to set up sync

1. In Tonkatsu Box: go to Settings > Integrations > Kodi
2. Enter Host - the IP address you found above (e.g. 192.168.1.105)
3. Enter Port (default: 8080)
4. Enter Username and Password (if set in Kodi)
5. Click Test connection to verify the connection works
6. Select a target collection:
   • Create new collection - creates a new collection for Kodi movies
   • Use existing collection - select from dropdown
7. Configure sync options:
   • Sync interval, how often the app checks Kodi for changes
   • Sub-collections - toggle to create sub-collections from Kodi movie sets
   • Import ratings - toggle to sync Kodi ratings (1-10 scale)
8. Enable the sync toggle to start syncing

How syncing works

Tonkatsu Box checks your Kodi library at the chosen interval:

1. Reads the movie list from Kodi.
2. Matches each movie to TMDB by the TMDB ID stored in Kodi.
3. Falls back to IMDB ID if there's no TMDB ID.
4. Adds matched movies to the chosen collection.
5. Updates watch status, ratings, last played dates, and comments.

First sync vs. subsequent syncs

• First sync populates the target collection with all movies from Kodi
• Subsequent syncs update existing items - watch status, ratings, last played dates, and comments are refreshed with the latest data from Kodi

Sub-collections

When the sub-collections option is enabled:

• Kodi movie sets (e.g. "Harry Potter", "The Lord of the Rings") are created as separate sub-collections
• Sub-collection names include a "(kodi)" suffix to distinguish them
• Movies belonging to a set appear in both the main collection and their sub-collection

Ratings

When the import ratings option is enabled:

• Kodi user ratings (1-10 scale) are synced to Tonkatsu Box
• Ratings always overwrite - the latest Kodi rating takes priority
• Disable this option if you want to manage ratings manually in Tonkatsu Box

Status badge in top bar

When Kodi sync is configured and enabled, a small Kodi icon appears in the top bar (desktop only), between the search field and the settings gear.

• Colored (Kodi blue) - sync timer is running
• Gray - sync is stopped
• Pulsing - a sync cycle is in progress right now
• Click to toggle: stop the sync timer or restart it
• Hover for a tooltip with the current status

This lets you quickly see if Kodi sync is active and pause/resume it without opening Settings.

Auto-stop

If the target collection is deleted from Tonkatsu Box, the Kodi sync automatically stops. Re-enable sync by selecting a new target collection in settings.

Tips

• Make sure Kodi and Tonkatsu Box are on the same local network
• Use Test connection before enabling sync to catch configuration issues early
• You can change the target collection at any time - the next sync will use the new collection
• Sub-collections are a convenient way to keep movie series organized without manual sorting
• If Kodi is not reachable during a sync cycle, the service will retry on the next interval