HTTP Scrobbler for Kodi

This addon for Kodi provides a simple scrobbler sending requests for movies and episodes to any HTTP endpoint. The data is sent as JSON using a POST request.

Work on a backend for this addon is currently in progress.

Installation

Just download this repository as zip archive and install it in Kodi using "Install from zip file" in the add-on browser (Settings > Addons). NOTE requires "Enable Unknown Sources" to be enabled first.

After that, configure the backend, username and password in the Addon settings.

Settings

Most settings should be easy to understand, but the error handling section might require more details:

Retry unfinished requests on startup

In case a request is ongoing while Kodi has been shutdown or even crashed, the sent event is stored in the queue as "processing" (i.e. not pending and not successful or failed).

The request might already arrived at the configured server but it could also be dropped due to the connection beeing closed before actually sending the data.

This setting is enabled by default.

Retry failed requests on startup

In case a request fails (i.e. due to a timeout or another non-OK status code), the event is kept as "failed" in the queue.

Enabling this setting retries those failed events on the next addon initialization (i.e. the next Kodi start or if the addon is disabled and enabled again).

This setting is disabled by default.

Skip all events after sending stop/end

In some cases, sending an event like "start", "pause", "resume" or "interval" might fail due to network issues. But the "stop" or "end" event might successfully arrive.

With the normal behavior, those failed events are resent on startup if the setting "Retry failed requests on startup" is enabled.

This might give unexpected results due to events like "start" arriving after the previous "stop" or "end" event resulting in the backend service thinking that the user is currently watching something even if that's not the case.

Note: Skipped events are never processed automatically and have to be processed manually (check the SQLite database queue.db in the data directory of the addon).

This setting is disabled by default.

Data sent to the endpoint

The addon sends a HTTP POST request containing a JSON payload.

A request is sent once the playback starts, pauses, resumes or stops.

Additionally to that, it's also possible to regularly send the current progress while playing movies or episodes (i.e. not paused). This feature can be configured on the "Interval" page in the addon settings.

Available values for the event property:

Event	Description
start	Start playback
pause	Pause playback
resume	Resume playback after pausing it
stop	Playback stopped (not finished)
end	Playback finished (not stopped before reaching the end)
seek	Triggered after jumping to a specific time or chapter
interval	Triggered while playback in configured interval

Each event can be enabled or disabled individually in the addon settings.

Playback progress reporting

The progress property is especially useful in combination with the interval event as it contains the current playback progress. But the progress is also included in other events like pause, seek or stop.

There are two properties in the progress map:

• time: Contains the current playback position in seconds
• percent: Contains the current playback progress in percent

Additional to that, the duration property in the root contains the total runtime in seconds of the played back media.

Note: As the current time as well as the total time are not available anymore in the stop as well as in the end event, the last known values are used instead. Those values are updated regularly (based on the interval also used for the interval event).

Data structure

The following examples provide the usual structure which will be used for sending the data to the endpoint.

Not all of those properties might be set in every request as they might not be available for the media content being played back.

Movies

{
  "timestamp": "2026-06-12T20:16:35.185714+02:00",
  "sessionId": "dee95eeb-00c1-48f5-9ddd-ae6b7f063d47",
  "event": "start",
  "dbId": 123,
  "title": "Back to the Future",
  "mediaType": "movie",
  "year": 1985,
  "premiered": "",
  "uniqueIds": {
    "imdb": "tt0088763"
  },
  "duration": 6960,
  "progress": {
    "time": 0,
    "percent": 0.0
  }
}

Episodes

{
  "timestamp": "2026-06-12T19:07:42.637621+02:00",
  "sessionId": "39c8a16c-a000-4cb5-9e10-1840a0e4e4a3",
  "event": "start",
  "dbId": 1234,
  "title": "Member Berries",
  "mediaType": "episode",
  "year": 2016,
  "uniqueIds": {
    "tvdb": "5654976"
  },
  "duration": 1330,
  "progress": {
    "time": 0,
    "percent": 0.0
  },
  "tvShowTitle": "South Park",
  "season": 20,
  "episode": 1,
  "firstAired": "2016-09-14",
  "tvShowUniqueIds": {
    "tvdb": "75897"
  }
}