21 Aug 2020 - The wiki is undergoing a major cleanup. If you arrived here from a search engine and cannot find the page, please use the wiki search instead (top right corner of page)
More info can be found on the forum
TheTVDB.com 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.
To install this add-on you must do so from the Add-on manager from within Kodi by going to
- The home screen
- Information providers (v16 and higher)
- TV information
- The TVDB
2 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.
2.1 Season ordering
To get a match for episodes you need to understand thetvdb.com 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 thetvdb.com 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. http://www.thetvdb.com/index.php?tab=seasonall&id=71361&lid=7&order=absolute the other options in this case were DVD and aired.
It is also important to understand thetvdb.com 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 thetvdb.com, that data may not be available to the scraper due to the way thetvdb.com feeds that data out - see the section on debugging show matching (yet to be completed).
3 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 content.eg. 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 content.eg. 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 thtvdb.com 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 thetvdb.com - 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 thetvdb.com 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 'http://www.thetvdb.com/api/1D62F2F90030C444/series/71361/all/en.zip' using The TVDB scraper (file: 'C:\Users\Me\AppData\Roaming\XBMC\addons\metadata.tvdb.com', content: 'tvshows', version: '1.4.5')
The number following /series/ ie. 71361 is in fact the unique show identifier on thetvdb.com, and if you search thetvdb.com you can see that number in the results, eg. http://www.thetvdb.com/?string=inuyasha&searchseriesid=&tab=listseries&function=Search. 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 thetvdb.com, this is that en.zip 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. http://www.thetvdb.com/api/1D62F2F90030C444/series/71361/all/en.zip . Open en.zip and you will typically see 3 files;
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\metadata.tvdb.com\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">http://www.thetvdb.com/api/1D62F2F90030C444/series/71361/all/en.zip</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.