Add-on:The TVDB

From Official Kodi Wiki
Jump to navigation Jump to search

Author: Team Kodi
Website: link
Type: TV information

License: GPL v2.0

Summary: Fetch TV show metadata from
Home icon grey.png   ▶ Add-ons ▶ The TVDB is a TV Scraper. The site is a massive open database that can be modified by anybody and contains full meta data for many shows in different languages. All content and images on the site have been contributed by their users for users and have a high standard or quality. The database schema and website are open source under the GPL.

Scraper settings

Note: When DVD Order and Absolute Order are disabled, Aired Order will be used.

Use DVD order
Uses the episode order on the DVD/Bluray instead of the Aired Order.
Note: If no DVD Order details exist for the TV Show, the scraper will fall back to using Aired Order.
Use absolute ordering (single season)
Treat show as having only one season so that file names only require episode numbers. Often used for single series and anime. S
Note: The Absolute Order data for the TV Show must exist at the TVDB in order to use this. There is no fallback when using this option and missing data means this show will not scrape.
Enable fanart
Download Fanart or not.
Language to use for summaries and other metadata.

Season ordering

To get a match for episodes you need to understand data has 3 different ways of ordering the episode numbers;

  • DVD Order
  • Absolute Order (aka Single Season)
  • Aired Order

In the configuration of the TVDB Addon if neither of the 2 tick boxes for DVD Order or Absolute Ordering are ticked then the order of episodes will be in Aired Order and this is the default listing order for the the TVDB addon.

You can see these options on at the bottom of the page and when trying to match the order with how your files are named, you can confirm it with the page URL eg. the other options in this case were DVD and aired.

Note: Even if you set the above for a global/parent folder/source for one setting, each folder, such as an individual TV show folder, can also have it's own content settings, which can be checked via Video->Files->"highlight show folder"-> context menu-> change content-> settings. The folder's setting has precedence over the global setting.

It is also important to understand does not have absolute ordering for some shows and thus ticking the Absolute Order button may result in the episode number not being found and thus no match found or an incorrect match. Additionally whilst absolute ordering may exist on, that data may not be available to the scraper due to the way feeds that data out - see the section on debugging show matching (yet to be completed).

Debugging Shows Not Found

Before delving into log files, first make sure your file and folder names are correct and that you have set the correct ordering of episodes tickboxes for the folder. The following information is presented elsewhere, but here is a quick checklist of naming vs order options;

  • If your show is in Aired season order, then name will be S[not zero]E[number] and both DVD Order and Absolute Order are not ticked for that folder's MyShow_S1E1.mkv
  • If your show is a Special, then name will be S0E[number] and both DVD order and Absolute Order are not ticked for that folder's MyShowSpecial_S0E1.mkv
  • If your show is in Absolute (aka single season) Order, then name will be ep[number] and Absolute Order is ticked and DVD order is not ticked for that folder's content. eg. Myshow_ep1.mkv
  • If your show is in DVD Order then name will be S[not zero]E[number] and Absolute Order is not ticked and DVD order is ticked for that folder's content. eg. MyShowDVD_S1E1.mkv

If that hasn't helped then you will have to check the logs.

Before doing anything else, make sure your folder and file names are done per Naming_video_files/TV_shows. Change Content of your TV Show folder to match that naming convention. Highlight folder, press I (or context->information), then do a Refresh. If that doesn't fix it then you will have to delve into your log.

Enable debugging which adds additional information to the log file. Restart Kodi, and do a Video->Files->Context(C)->Information(I)->Refresh on a folder where the episodes are not found. Close Kodi.

Open your log file in a text reader. Every fault in finding shows is going to be slightly different, but assuming your folder names match names then using the example that follows you should be able to work out what is going wrong.

Search for a line that starts DEBUG: VideoInfoScanner: Found episode match. eg.

09:15:12 T:6756   DEBUG: VideoInfoScanner: Found episode match smb://networkpc/video/tv series/inuyasha/inuyasha - 001.mkv (s0e1) [[\\/\._ -]([0-9]+)([0-9][0-9](?:(?:[a-i]|\.[1-9])(?![0-9]))?)([\._ -][^\\/]*)$]

If no "Found episode match" then check your names again because this means it could not find your show name.

In this example, it found an episode (s0e1), which means it found episode 1 and it is a special episode (which was actually wrong). If it had found s1e1 the TV Show could be in absolute order or Aired Order. In this case the show was in absolute order as is common for Anime but it is named incorrectly and should instead be named something like "Inuyasha ep01.mkv". Note specials are always in 'absolute order' but specials are identified by the name being season0 and not by the scraper settings. If the show was in Aired Order it should have been named something like "inuyasha S1E1", and XBMC would have matched (s1e1) instead - which is the default match.

So now we at least know XBMC can find an episode. Next XBMC asks the scraper to find that episode from - it may prompt you for the correct show name first, and in this example there is ambiguation with a similar show name called "Inuyasha: The Final Act" . Having found the (in theory) correct show, the scraper will download the entire show/episode list from who provide it as 3 xml files enclosed in a zip file. Scrolling further through the log file you should see a line similar to;

09:15:12 T:6756   DEBUG: ADDON::CScraper::GetEpisodeList: Searching '' 
using The TVDB scraper (file: 'C:\Users\Me\AppData\Roaming\XBMC\addons\', content: 'tvshows', version: '1.4.5')

The number following /series/ ie. 71361 is in fact the unique show identifier on, and if you search you can see that number in the results, eg. Clicking on the show, you can see the seasons, choose All, and you can see them by default in Aired Order, and at the bottom of the list you can choose to view them in Absolute Order.

So now the scraper has downloaded the full series information from, this is that file (where 'en' is english), but it still needs to match season number and episode number from the information in that file. If you still aren't getting matches you should look at the information in that zip file. Download your own copy by pasting that URL into your browser ie. . Open and you will typically see 3 files;

  1. actors.xml
  2. banners.xml
  3. en.xml

It's the last one we want to check out, which contains all the episodes information. Open in your browser or a text editor
To get a match, the scraper needs to have season match (in this case 's0') and episode number match (in this case 'e1'). To look for season it uses the episode order information you told XBMC in your content setting, ie. Absolute (includes specials but you don't tick that for specials, the name S0 sets that), DVD, or Aired. For the technically curious, you can see how the scraper is reading the en.xml by looking at c:\Program Files\XBMC\addons\\tvdb.xml but it's going to do the following;

  • If the show is not in DVD order (ie. it's Absolute or Aired) and ...
  • If the show is in Absolute order and is not a special (<absolute_number> is a number ie. not blank)
Episode Number (returned as <epnum>) will be <absolute_number> and Season will be 1 returned as <season>1</season?
  • or If the show is in Absolute order and is a special (the episode has <SeasonNumber>0</SeasonNumber>
Episode Number will be <EpisodeNumber> and Season will be 0 returned as <season>0</season>
  • or If the show is Aired order (Season is not 0 and you didn't tick Absolute or DVD order)
Episode Number will be <EpisodeNumber> and season will be <SeasonNumber>
  • or If the show is in DVD order
Episode Number will be <CombinedEpisodenumber> and season will be <Combinedseason>

The next step is to look at what is actually being returned, which can be found looking for "GetEpisodeList returned";

09:15:13 T:6756   DEBUG: scraper: GetEpisodeList returned <episodeguide><episode><id>343825</id><title>Movie 1: Affections Touching Across Time</title><aired>2001-12-22</aired><epnum></epnum><season>1</season><url cache="71361.xml"></url></episode>

The indicator that something is wrong is that <epnum></epnum> should be returning a number, eg. <epnum>1</epnum>. I had an earlier fault show up with season being 0 (s0e1) but I knew it was not a special, so now the scraper can't find an episode because I told it the show is in Absolute Order (tickbox) but there is no <absolute_number> in the en.xml for Season0 Episode 1. The solution is to rename the files correctly because the order tick boxes are actually correct in this case.

See also