NFO files/TV shows

From Official Kodi Wiki
< NFO files(Redirected from NFO files/tvshows)
Jump to: navigation, search
NFO Contents

See also:


Return to:

Home icon grey.png   ▶ NFO files ▶ TV shows


1 Requirements

TV Shows and Episodes must abide by the standard naming conventions even if you are using nfo files. The scanner still determines the TV Show name from the folder name and Season and Episode numbering from the episode filename, not from the NFO file.

If you choose to use NFO Files, TV Shows require the following:

  1. One nfo file for the TV Show. This file holds the overall show information
  2. One nfo file for each Episode. This file holds information specific to that episode

For one TV Show with 10 episodes, you will require 11 nfo files.


The order of importing metadata is as follows:

  1. nfo file. If no nfo file exists, then
  2. Depending on your scraper settings for your source, either
    1. Online scraper sites- if a scraper is set in your source settings
    2. Nothing- if Local Info Only is set


1.1 episodeguide URL

The <episodeguide> URL is saved in the tvshow.nfo file.

When using the scrapers, the <episodeguide> URL is a critical component of the scraping process that ensures episodes are correctly scraped. The <episodeguide> URL is provided by the information provider in a format that they have designed. The URL is not interchangeable between information providers. i.e. you cannot use the TVDB URL while using TheMovieDB scraper.

When scraping, once a TV Show has been identified via the folder name, the scraper asks the site to provide the link to all the episodes for the show. This is provided in the format of the <episodeguide> URL from which all the metadata for the individual episodes is downloaded.

Without the <episodeguide> no episodes will be scraped.


When using NFO Files knowing whether to include the <episodeguide> can be tricky. Some points that hopefully will explain how and when to use it for your own scenario:

  • If you are using nfo files exclusively, then the <episodeguide> is not required in the tvshow.nfo file. Be aware that any episodes missing nfo files will not be scanned or scraped
  • If you have a mix of nfo files and no nfo files for episodes, then the <episodeguide> is required.
  • If your tvshow.nfo file does not have the <episodeguide>, and you require it, the scraper will not download it. Delete your tvshow.nfo file in which case the scraper will automatically download the <episodeguide> URL.
  • You can have episode nfo files without the tvshow.nfo file.
  • Creating your own <episodeguide> URL is tricky but you can attempt it by reading the What if I'm using NFO files? section in this thread... Forum Thread
  • If you include the <episodeguide>, then you need to have the correct scraper active. Remember that the <episodeguide> URL is not interchangeable between scrapers. Using Local Information Only will not change this requirement.
  • TheTVDB <episodeguide> used by Kodi is v2 from the v2 API. v1 is not recognised by Kodi.


1.2 Known Issues

  • v18 introduced a bug where any class of nfo file can be scanned into any part of the video library. See Issue 16112


2 TV Show

This section deals with the requirement for the tvshow.nfo file. Episode nfo files are discussed in Section 3 below.


2.1 nfo Name and Location

Regardless of what settings you have set for the source and scraper, Kodi will always search for and scan the nfo file first where available.

The tvshow.nfo file is placed inside the TV Show folder. The nfo filename is actually tvshow.nfo. Do not rename it with the title of the tv show. See image for example

Correct placement of the nfo file is essential. Failing to save the file with the correct name and in the correct location, as detailed below, will force Kodi to either:

  1. Scrape the metadata from the online source set in your scraper or,
  2. If you have Local Info Only set as your scraper, then no entry will be made into the library.



2.2 nfo Tags

The following table lists most available XML tags. [1]

Two XML tags are required and are indicated in the table below. All other tags are optional. Of course the less tags used, the less information scanned into the library.

Children tags are displayed correctly with parent tags. The list is ordered in the same order as the exported nfo file.


NFO (xml) Tag Required Multiple Notes
<tvshow></tvshow> Yes No The top level parent tag for the nfo file. All other tags must be contained within these two tags
<title></title> No No The title of the TV Show
<originaltitle></originaltitle> No No The original title, usually in the language of the country of origin.
<showtitle></showtitle> No No Not in common use, but some skins may display an alternate title
<sorttitle></sorttitle> No No Allows alternate title sort without modifying the TV Show title. Not displayed in any library listing.
 <ratings>
   <rating name="" max="10" default="">
      <value></value>
      <votes></votes>
   </rating>
 </ratings>
No No Only one rating can be set as default="true", additional ratings can be set as "false" or ommitted

Examples...

<rating name="imdb" max="10">
<rating name="metacritic" max="10">
<rating name="tomatometerallcritics" max="10">
<rating name="tomatometerallaudience" max="10">
<rating name="themoviedb" max="10" default="true">
<userrating></userrating> No No Personal rating set by the user
<top250></top250> No No Ranking in IMDB Top 250
<season></season> No No Number of seasons of this TV Show in the library
<episode></episode> No No Number of episodes of this TV Show in the library
<displayepisode></displayepisode> No No Not used
<displayseason></displayseason> No No Not used
<namedseason number="1"></namedseason> No No Not Used
<outline></outline> No No Not Used
<plot></plot> No No Can contain more information on multiple lines, will be wrapped
<tagline></tagline> No No Short TV Show slogan
<runtime></runtime> No No Not used
<thumb aspect="" preview=""></thumb>

<thumb aspect="poster" type="season" season="" preview=""></thumb>

No Yes Path to available TV Show Posters

Example use of aspect=""

<thumb aspect="banner"
<thumb aspect="clearart"
<thumb aspect="clearlogo"
<thumb aspect="landscape"
<thumb aspect="poster"

type="season" used for season specific artwork
season="2" nominates season number eg. season 2

<fanart>
    <thumb preview=""></thumb>
</fanart>
No Yes^ Path to available TV Show fanart.
^ Multiple <thumb> entries allowed between the <fanart></fanart> tags
<mpaa></mpaa> No No Country specific mpaa rating system. Check with skin author which prefix is required to diplay your country local rating system
<playcount></playcount> No No Number of times TV show has been played. Will only ever show 0 or 1. Episodes track playcounts

Setting this to 1 will mark the TV Show as watched if the importwatchedstate flag is set in advancedsettings.xml

<lastplayed></lastplayed> No No Date TV Show was last played
<episodeguide>
  <url cache=""></url>
</episodeguide>
Yes/No No Read section 1.1 episodeguide URL above

When using TVDB scraper, Kodi will only read the URL created by the TVDB v2 API [2]
When a URL is used, the corresponding scraper must be set.

<id></id> No No The default ID.

Do not use as this is a Kodi generated tag. See next item.

<uniqueid type="xxxx" default="true"></uniqueid> Yes Yes Unique Id. The ID from the scraper site.

xxxx = Identifier of the ID eg imdb, tmdb. For non-scraped items, use simple values like "home", "sport", "doco" etc
true = This will be set as the default ID. Multiple ID's are allowed but only one can be marked "true"
The value can be alpha-numeric. Typical entries tt3480556 for imdb, 286668 for tmdb, home001 for home movies etc

<genre></genre> No Yes Genre
<tag></tag> No Yes Tags. See: Video library tags
<premiered></premiered> No No Release date of TV Show. Comes from Aired Date of the first episode.

Format as 2019-01-31

<year></year> No No Release Year.

Do not use. Use <premiered> instead

<status></status> No No Continuing or Ended show
<code></code> No No Not used
<aired></aired> No No Not used
<studio></studio> No Yes Production studio
<trailer></trailer> No No Local or online path to TV Show trailer
<actor>
  <name></name>
  <role></role>
  <order></order>
  <thumb></thumb>
</actor>
No Yes The <order> tag determines where in the list the actor will appear. 0 = first in the list

Supports "clear" attribute

<namedseason number=""></namedseason> No Yes Allows naming of Seasons- eg Game of Thrones named seasons

number="" = Season number to be renamed

<resume>
  <position></position>
  <total></total>
</resume>
No No Not used for TV Show
<dateadded></dateadded> No No mTime of the playable video file. Can be altered in advancedsettings.xml


2.3 Template nfo

A template NFO File is provided below that can be copied into your own file and completed. It is a simplified file:

  • System generated tags are removed
  • Assumes local artwork is being used
  • Assumes no online information is available, so items like Ratings have no relevance
  • This will be the first time scanned into library so watched status and play counts are not required.

If any of these removed tags are required, simply add the appropriate tags, and refer to the Sample NFO File in the next section to confirm correct usage.

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<tvshow>
    <title></title>
    <plot></plot>
    <userrating></userrating>
    <mpaa></mpaa>
    <uniqueid type="" default="true"></uniqueid>
    <genre></genre>
    <premiered></premiered>
    <status></status>
    <studio></studio>
    <actor>
        <name></name>
        <role></role>
        <order></order>
        <thumb></thumb>
    </actor>
    <namedseason number="1"></namedseason>
</tvshow>


2.4 Sample nfo

Below is a sample nfo file that was exported from Kodi after scraping into the library using the default TheMovieDB-TV Shows scraper.

Press Expand at right edge of the green bar to view


3 Episodes

This section deals with the requirement for the episode nfo file.


3.1 nfo Name and Location

Regardless of what settings you have set for the source and scraper, Kodi will always search for and scan the nfo file first where available.

The episode nfo file is placed alongside each episode video file. The episode nfo filename is the same as the video filename but with the .nfo extension. See image below for examples.

Correct placement of the nfo file is essential. Failing to save the file with the correct name and in the correct location, as detailed below, will force Kodi to either:

  1. Scrape the metadata from the online source set in your scraper or,
  2. If you have Local Info Only set as your scraper, then no entry will be made into the library.



3.2 nfo Tags

The following table lists most available XML tags. [3]

Two XML tags are required and are indicated in the table below. All other tags are optional. Of course the less tags used, the less information scanned into the library.

Children tags are displayed correctly with parent tags. The list is ordered in the same order as the exported nfo file.

For multi-part episodes, add multiple <episodedetails> XML blocks in succession in the same nfo file


NFO (xml) Tag Required Multiple Notes
<episodedetails></episodedetails> Yes No The top level parent tag for the nfo file. All other tags must be contained within these two tags
<title></title> No No The title for the episode
<originaltitle></originaltitle> No No The original title, usually in the language of the country of origin.
<showtitle></showtitle> No No Name of the tv show this episode belongs to
 <ratings>
   <rating name="" max="10" default="">
      <value></value>
      <votes></votes>
   </rating>
 </ratings>
No No Only one rating can be set as default="true", additional ratings can be set as "false" or ommitted

Examples...

<rating name="imdb" max="10">
<rating name="metacritic" max="10">
<rating name="tomatometerallcritics" max="10">
<rating name="tomatometerallaudience" max="10">
<rating name="themoviedb" max="10" default="true">
<userrating></userrating> No No Personal rating set by the user
<top250></top250> No No Not used
<season></season> No No Ignored on Import. Season is read from filename
<episode></episode> No No Ignored on Import. Episode is read from filename
<displayepisode></displayepisode> No No Used to place Specials episodes in the correct episode order
<displayseason></displayseason> No No Used to place Specials episodes in the correct season
<outline></outline> No No Not used
<plot></plot> No No Can contain more information on multiple lines, will be wrapped
<tagline></tagline> No No Short slogan of the episode. No skins use this.
<runtime></runtime> No No Minutes only. Overwritten when episode played
<thumb></thumb> No Yes Path to episode artwork
<mpaa></mpaa> No No Inherited from TV Show nfo file. Ignored on import.
<playcount></playcount> No No Number of times episode has been played.

Setting this to 1 or greater will mark the episode as watched if the importwatchedstate flag is set in advancedsettings.xml

<lastplayed></lastplayed> No No Date episode was last played
<id></id> No No The default ID.

Do not use as this is a Kodi generated tag. See next item.

<uniqueid type="xxxx" default="true"></uniqueid> Yes Yes Unique Id. The ID from the scraper site.

xxxx = Identifier of the ID eg imdb, tmdb. For non-scraped items, use simple values like "home", "sport", "doco" etc
true = This will be set as the default ID. Multiple ID's are allowed but only one can be marked "true"
The value can be alpha-numeric. Typical entries tt3480556 for imdb, 286668 for tmdb, home001 for home movies etc

<genre></genre> No Yes Inherited from TV Show. Ignored on import.
<credits></credits> No Yes Field for writers.
<director></director> No Yes Director
<premiered></premiered> No No Release date of TV Show. Format as 2019-01-31

Use the <aired> field below to add the aired date of the episode.

<year></year> No No Release Year.

Do not use. Use <aired> instead

<status></status> No No Not used
<code></code> No No Not used
<aired></aired> No No Original air date of the episode
<studio></studio> No Yes Production studio. Inherited from TV Show
<trailer></trailer> No No Not used
   <episodebookmark>
       <position></position>
   </episodebookmark>
No No Episode Bookmark in seconds. See: Episode Bookmarks

Not used for Import

 <fileinfo>
    <streamdetails>
      <video>
        <codec></codec>
        <aspect></aspect>
        <width></width>
        <height></height>
        <durationinseconds></durationinseconds>
        <stereomode></stereomode>
      </video>
      <audio>
        <codec></codec>
        <language></language>
        <channels></channels>
      </audio>
      <subtitle>
        <language></language>
      </subtitle>
    </streamdetails>
 </fileinfo>
No Yes Multiple entries of <audio> and <subtitles> accepted

In v17 and prior, Kodi would overwrite these values on first play of the file.
In v18 that process was removed and values in these tags will remain.[4]

<actor>
  <name></name>
  <role></role>
  <order></order>
  <thumb></thumb>
</actor>
No Yes The <order> tag determines where in the list the actor will appear. 0 = first in the list

Supports "clear" attribute

<resume>
  <position></position>
  <total></total>
</resume>
No No
<dateadded></dateadded> No No mTime of the playable video file. Can be altered in advancedsettings.xml


3.3 Template nfo

A template NFO File is provided below that can be copied into your own file and completed. It is a simplified file:

  • System generated tags are removed
  • Assumes local artwork is being used
  • Assumes no online information is available, so items like Ratings have no relevance
  • This will be the first time scanned into library so watched status and play counts are not required.

If any of these removed tags are required, simply add the appropriate tags, and refer to the Sample NFO File in the next section to confirm correct usage.

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<episodedetails>
    <title></title>
    <showtitle></showtitle>
    <userrating></userrating>
    <plot></plot>
    <runtime></runtime>
    <uniqueid type="" default="true"></uniqueid>
    <credits></credits>
    <director></director>
    <aired></aired>
    <actor>
        <name></name>
        <role></role>
        <order></order>
        <thumb></thumb>
    </actor>
</episodedetails>


3.4 Sample nfo

Below is a sample nfo file that was exported from Kodi after scraping into the library using the default TheMovieDB-TV Shows scraper.

Press Expand at right edge of the green bar to view


4 References


Return to top