feat: move to TheIntroDB API v4 with TVDB-first lookups

README.md

@@ -6,9 +6,9 @@
 
 Kodi service add-on that gets intro, recap, credits, and preview segments from **[TheIntroDB](https://theintrodb.org)** for movies and TV shows and shows a skip button or auto skips for you!
 
-**Requirements:** Kodi 19+. **TMDb metadata is recommended** for best accuracy. IMDb works as a fallback for supported items.
+**Requirements:** Kodi 19+. **TVDB metadata is recommended**: TVDB is the API's identity, so it is what the add-on asks with first (TMDB, then IMDb, are fallbacks).
 
-**Important:** Lookups happen when playback starts. If the current item does not expose a usable **TMDb** or **IMDb** ID, the add-on cannot match it with TheIntroDB.
+**Important:** Lookups happen when playback starts. If the current item does not expose a usable **TVDB**, **TMDb** or **IMDb** ID, the add-on cannot match it with TheIntroDB.
 
 **Troubleshooting (no skip button):** See the Metadata Requirements and Installation sections below.
 
@@ -39,13 +39,17 @@ Kodi service add-on that gets intro, recap, credits, and preview segments from *
 
 ### Metadata Requirements
 
-**TMDB is recommended.** The add-on prefers TMDB IDs for matching. If TMDB is unavailable, it can fall back to IMDb `tt...` IDs.
+**TVDB is recommended.** TVDB is TheIntroDB's identity, so it is what the add-on asks with first; **TMDB** is next, then **IMDb** `tt...`. When the item exposes several, the add-on uses the best one and falls back to the others if the first finds nothing.
+
+Alongside the id, an episode's own **TVDB episode id** is sent when Kodi has one. It is the add-on's way of saying which exact episode record it means; note that the API currently answers `/media` from the season/episode numbers rather than that id (measured 2026-10-17: a pinned id naming a different episode than the numbers returns the *numbers'* episode), so the numbering is still what decides the answer. The id is sent for when that precedence is honoured.
 
 For TV episodes, the playing item also needs valid **season** and **episode** numbers. If your source add-on or library does not expose provider IDs, TheIntroDB cannot match the item.
 
+Known limitation: for a series whose episode numbers follow a release order rather than TVDB's default (streaming rips, absolute-numbered anime, some specials), a lookup is answered from the numbers as TVDB's *default* order, which can be a different episode than the one you are watching. Kodi does not expose which order its numbers came from, so the add-on cannot pass an order to convert; if your library is scraped in a non-default order, prefer a source that carries a TVDB id and check the result against the episode you are watching.
+
 ## How It Works
 
-On each new playback, the add-on reads what Kodi exposes for the current item through JSON-RPC `Player.GetItem` and `VideoInfoTag`: **TMDb ID** when available, otherwise **IMDb** `tt...` ID, plus **season** and **episode** for TV content.
+On each new playback, the add-on reads what Kodi exposes for the current item through JSON-RPC `Player.GetItem` and `VideoInfoTag`: **TVDB ID** when available, otherwise **TMDb ID**, otherwise **IMDb** `tt...` ID, plus **season**, **episode** and (for episodes) the **TVDB episode ID**.
 
 It then calls TheIntroDB, retrieves segment **start** and **end** times, waits until the segment window begins, and either shows the skip overlay or seeks automatically depending on your settings.