From Official Kodi Wiki
Jump to navigation Jump to search


See this add-on on the showcase

Author: Roman V.M.
Website: link
Type: TV information
Repo: repo v21 repo v20 repo v19

License: GPL-3.0-or-later
Source: Source code
Summary: Fetch TV Show metadata from
Home icon grey.png   ▶ Add-ons ▶ TVmaze

TVmaze is a free user driven TV database curated by TV lovers all over the world. You can track your favorite shows from anywhere.
We provide an API that can be used by anyone or service like Kodi to retrieve TV Metadata, show/episode/cast images, and much more.


This add-on is installed from the Add-on browser located in Kodi as follows:

  1. Settings
  2. Add-ons
  3. Install from repository
  4. Information providers (v16 and higher)
  5. TV information
  6. TVmaze
  7. Install


TVmaze is a TV Show scraper developed in Python by {[kodi]} Team Member Roman V.M.

The TVmaze scraper accesses the following site to scrape your TV Shows, seasons and episodes:

  • TVmaze - for metadata and some artwork


This scraper uses the folder name as the search string to lookup the title at the TV Maze site.

If you are experiencing problems scraping the correct title, there are 2 methods available to force the scraper to the correct title.

Filename identifiers

Scrapers can optionally lookup via filename identifiers since Matrix (v21) if the scraper supports it. As of v21, TheMovieDB Python, TMDB TV Shows, and TV Maze scrapers support ID's in the folder or filename.

Filename identifiers are short tags added to the name of a file that directly provide metadata IDs to Kodi. This method streamlines the scraping process by giving Kodi explicit references to look for in its database. If an identifier could not be looked up using a filename identifier, Kodi falls back to the normal scraping process using title and year.

To take advantage of this feature, include the identifier within the filename and/or the folder (depending on the setting Movies are in separate folders that match the movie title in the Set Content screen) using one of the following supported formats:

  • Movie Name (Year) [sourceid=xxxx]
  • Movie Name (Year) [sourceid-xxxx]
  • Movie Name (Year) [source=xxxx]
  • Movie Name (Year) [source-xxxx]
  • Movie Name (Year) {sourceid=xxxx}
  • Movie Name (Year) {sourceid-xxxx}
  • Movie Name (Year) {source=xxxx}
  • Movie Name (Year) {source-xxxx}


sourceid / source - the appropriate site identifier of the ID (see Note below)
xxxx - the ID from the site

An example of a properly formatted filename would be:

/Blade Runner (2017) {tmdb=335984}/Blade Runner (2017) {tmdb=335984}.mkv

Note: Not all scraper sites accept all ID's. It is recommended that the sites own ID is used rather than a 3rd party site (eg imdb). 3rd party ID's at scraper sites rely on users to enter that data. It is not uncommon to have these ID's missing.

TheMovieDB for Movies and TV Shows - Use TMDB's own tmdb ID but the scapers will also accepted imdb and tvdb if that data is available at the site.
TV Maze - only acceptes tvmaze ID's
TVDB - As at the release of v21 Omega, the scraper requires updating by TheTVDB

Parsing NFO File

See: Parsing NFO Files


Scraper settings can be adjusted in three locations, each location having a different result. When adjusting the settings be mindful of where:

1. Kodi System Settings ▶ Add-ons ▶ Information Providers ▶ (Select Scraper)
Scrapers are installed with default settings. Adjusting settings in this location sets the new default settings for your scraper. From this point on any source you change to use this scraper will use the new default settings. Existing sources are not changed
If an existing source is already using this scraper, and you would like the new settings to take effect, change the source to use another scraper, save and answer no to updating the library. Then change the scraper back and the new default settings will be loaded for the source. See: Changing Scrapers
Alternatively, use the next method.
2. Videos ▶ Files ▶ Source ▶ Context Menu ▶ Change Content ▶ Settings
Changing settings at the source will affect that source only.
3. Videos ▶ Files ▶ Source ▶ Movie/TV Show folder ▶ Context Menu ▶ Change Content ▶ Settings
Changing settings on the folder containing a movie or TV show will affect only that movie or TV show.

Note: Changing scraper settings does not change the metadata or artwork already in your library. Only items scraped after the setting changes will be affected.


Image 6- General Settings

Preferred Episode Order
Most TV shows will use the Default order. If you need to use a different order for a particular TV show, select the order here. Using Settings method 3 detailed above is recommended.
See next section "Episode Orders" for more details.
Default Rating
Select which provider to be used for scraping the default rating.
Available options are TVmaze and IMDB
.NFO files include full show/episodes information
If your nfo files contain full metadata, enable this setting to ensure some data is not overridden. [1]

Episode Orders

Some TV Shows are originally broadcast in one order (default order) but the order may be different when broadcasting in a different country (La Casa De Papel), or the DVD/Bluray release may have a different screening order (Firefly).

If these orders are available at, then the alternate orders can be accessed by the scraper.

  1. Locate the TV show at TVmaze and confirm that alternate orders are available (image 1)
  2. Confirm which order you require and ensure it matches your episode files
  3. In the scraper settings, select the same order. Use Settings method 3 detailed above in Settings (image 2)
  4. Scrape as per normal.

Available Orders are:

  • Default
  • DVD/BluRay Release
  • Verbatim
  • Country Premiere
  • Streaming Premiere
  • Broadcast Premiere
  • English Language Premiere


Return to top