# Kodi

The **Simkl Add-On for Kodi** allows you to automatically track what you’re watching on your media player.

It connects your local playback data to your **Simkl account**, so when you watch a TV show, anime, or movie, Simkl updates your progress in real-time.

Whether you’re binging a new season or watching offline files, Simkl makes sure your watch history stays perfectly synced.

{% embed url="<https://simkl.com/apps/kodi/>" %}

{% embed url="<https://github.com/SIMKL/script.simkl>" %}

## How Does It Work

When you watch **70% of a video** on Kodi (default threshold, configurable in Add-On settings), the Simkl Add-On sends a ping to the **Simkl API**, marking that episode or movie as “watched” on your profile.

Simkl’s add-on can:

* Detect and track **TV Shows**, **Anime Episodes**, and **Movies**.
* Recognize files using **TVDB and TMDB metadata**.
* Fall back on **filename recognition** for unmatched videos (great for anime or custom library names).

> Even if Kodi fails to identify a title, Simkl can still detect it through its filename and database matching ensuring your progress is never lost.

<figure><img src="/files/hQrPdEHF5fnQhygvCn70" alt=""><figcaption></figcaption></figure>

## Installing Simkl on Kodi

Simkl features an official Kodi addon that you can install from the Kodi official repository.

Follow these steps to install the Simkl addon on Kodi:

1. Open Kodi

<figure><img src="/files/f5yLEM2PXKnWc7mO6QKE" alt=""><figcaption></figcaption></figure>

2. Navigate to Settings:\
   `System → Settings → Add-ons → Install from repository → Kodi Add-on repository → Services → Simkl TV Tracker`

<figure><img src="/files/a5HEOwy3zNAe9Ri5Wbjw" alt=""><figcaption></figcaption></figure>

3. &#x20;Select the **Addons** folder.

<figure><img src="/files/GzA0rGZyF1Qp7xhys63k" alt=""><figcaption></figcaption></figure>

4. Click **Install from repository**.

<figure><img src="/files/WCWYrwFXHgM9TwPZ3EnP" alt=""><figcaption></figcaption></figure>

5. Select **Kodi Addon Repository**.

<figure><img src="/files/dLzWqw6LROxWOeSIQH7A" alt=""><figcaption></figcaption></figure>

6. Click on **Services**.

<figure><img src="/files/xBiwKtTnYpwrRJuqCdkK" alt=""><figcaption></figcaption></figure>

7. Choose **Simkl TV Tracker**.

<figure><img src="/files/BC6a1fMoCFIPaEa2YsyF" alt=""><figcaption></figcaption></figure>

8. Click **Install** to download the SIMKL TV Tracker addon.

<figure><img src="/files/VWFU87WjXtyq2tHwOWIW" alt=""><figcaption></figcaption></figure>

9. The addon will be downloaded in a few seconds. You should see a **Simkl TV Tracker Addon Installed** notification at the top right.
10. You’ll be prompted to authorize your Simkl account with Kodi using a **code**.

{% hint style="warning" %}
*If the login prompt doesn’t appear:*

* Go to `Settings → Add-ons → My Add-ons → Services → Simkl → Configure → LogIn`
  {% endhint %}

<figure><img src="/files/rUfPv3xMfuVtfMyPui0l" alt=""><figcaption></figcaption></figure>

11. Visit [**https://simkl.com/pin**](https://simkl.com/pin) on your phone or computer browser.
12. You’ll be prompted to log in to your Simkl account.

<figure><img src="/files/gaNPopZZ80rJKyyY88ET" alt=""><figcaption></figcaption></figure>

13. Once you have signed in, Simkl will ask you to allow Kodi Scrobbler to use your account. Select **Yes**.

<figure><img src="/files/etrM12dsXrBRK0gpjyPa" alt=""><figcaption></figcaption></figure>

14. You’ll see a **Congratulations** notification.
15. Kodi Addon is now connected to your Simkl account.

<figure><img src="/files/gSdTQwCrxWxX6T2ljRic" alt=""><figcaption></figcaption></figure>

Simkl’s main TV metadata source is **TheTVDB**, with connected **TMDB IDs** linked internally.&#x20;

To ensure accurate scrobbling:

* Switch to **TVDB** under your Kodi library settings.
* Keep your Simkl add-on logged in and active.

***

## Configuring Simkl Add-On Settings

After installation, you can adjust how the Simkl Add-On behaves:

1. Open Kodi & Navigate to Settings Page

<figure><img src="/files/iUiGjJP2FaJlxvNGWDC6" alt=""><figcaption></figcaption></figure>

2. Select the **Addons** folder.

<figure><img src="/files/mwtAdKUYxssL36PiUpk1" alt=""><figcaption></figcaption></figure>

4. Select My add-ons.

<figure><img src="/files/9oKNHTPDp7fZz5VlCIDZ" alt=""><figcaption></figcaption></figure>

5. Scroll down, to find Services

<figure><img src="/files/U9mreOorDu3lKUGvxkhr" alt=""><figcaption></figcaption></figure>

6. Here select SIMKL TV Tracker

<figure><img src="/files/bYOAgDRaMLVwmzcvC0Nq" alt=""><figcaption></figcaption></figure>

7. Click Configure

<figure><img src="/files/HIwY2Mgsnm2gARc7a7T9" alt=""><figcaption></figcaption></figure>

### Tune how tracking works (Options tab)

Open the **Options** tab. Each setting below is live as soon as you click **OK**.

<figure><img src="/files/FfUZgGQbLPbMxjrAtft3" alt=""><figcaption></figcaption></figure>

#### A) Auto-scrobble

* **What it does:** If ON, Kodi automatically marks what you watch as “watched” on your Simkl profile, no buttons to press.
* **Recommended:** **ON** (default). Turn OFF only if you want to scrobble manually.

#### B) Scrobble at percentage

* **What it does:** Sets how much of the video must be watched before Simkl marks it as watched.
* **Default:** **70%**
* **When to change:**
  * **60–70%** if you often skip credits and want reliable scrobbles.
  * **80–90%** if you want stricter completion (e.g., you pause a lot or scrub around).
* **Example:** A 120-minute movie at **70%** will scrobble after \~84 minutes watched.

#### C) Show bubble when scrobbled

* **What it does:** Shows a small on-screen confirmation bubble when Simkl records the watch.
* **Recommended:** **ON** while testing; turn **OFF** later if you prefer a clean screen.

#### D) Minimum file length for scrobbling (minutes)

* **What it does:** Ignores short clips under this duration to avoid logging trailers, promos, or intros.
* **Default:** **5 minutes**
* **Good ranges:**
  * **3–5 min** if you watch a lot of short-form anime/OVAs.
  * **8–10 min** if you frequently open trailers or bonus clips and don’t want them scrobbled.

#### E) Save your changes

* Click **OK** (top-right of the dialog) to apply.
* **Defaults** restores the add-on’s original values.
* **Cancel** discards any changes you made.

{% hint style="warning" %}

### Troubleshooting (common fixes)

* **Nothing scrobbles at all**
  * Re-open **Configure → LogIn** and sign in again.
  * Ensure **Auto-scrobble** is **ON**.
  * Confirm you watched past the **Scrobble at percentage** threshold.
  * Increase **Minimum file length** if trailers are being logged; decrease it if short episodes aren’t.
  * Verify your device has internet access when playback ends.
* **Episodes marked incorrectly / not found**
  * Switch the Kodi TV source to **TVDB** (especially for anime and multi-cut shows).
  * Make sure your files have clean names (season/episode tags help: `Show.Name.S01E03`).
* **Double scrobbles or odd duplicates**
  * Avoid stopping/starting around the threshold repeatedly.
  * Keep **Scrobble at percentage** at least **60%** to prevent edge triggers.
    {% endhint %}


---

# Agent Instructions: 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:

```
GET https://docs.simkl.org/how-to-use-simkl/advanced-usage/platform-integration/linking-simkl-with-popular-media-centers/kodi.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.