Naming video files/TV shows: Difference between revisions

From Official Kodi Wiki
Jump to navigation Jump to search
m (Bot: automated adding of 'enclose="div"' to syntaxhighlight)
(Remove split episode files)
(45 intermediate revisions by 6 users not shown)
Line 1: Line 1:
{{:Adding videos to the library/Contents}}
{{VideoLibraryCreate}}
{{mininav|[[General topics]]|[[Video library|Videos]]|[[Video library/Management|Management]]|[[Video library/Naming files|Naming files]]}}
{{mininav|[[Video library]]|[[Naming video files]]}}
{{#lst:Adding videos to the library/Naming files|naming files}}
XBMC requires each TV show to be in its own folder, and for each file to contain a pattern from which XBMC can determine the season and episode number (e.g. "S01E01").


:'''Folder name''' = Show title
:'''File name''' = Season/Episode number


The folder name will be [[Userdata/advancedsettings.xml#.3Ccleanstrings.3E|cleaned]] of commonly used strings, such as DVDRip, 1080p, x264, etc. before being passed to the scraper. If the year of release is included, this will be [[advancedsettings.xml#.3Ccleandatetime.3E|extracted]] and used by the scraper to assist in making a match.
= Introduction =
<section begin="intro" />Setting up TV Shows correctly is a little bit more involved than the Movies section. The first part of this page will describe the '''{{Kodi}} best practice''' to name TV Shows and Episode files and to create the folder structure to save them in. These methods are proven to be the simplest and most robust method which provides the most accurate scrape.<section end="intro" />


Spaces, periods, or underscores may be used to separate words in the folder and file names, but shouldn't be mixed in the same folder name. Note also the caution [[#Split-episode|below]] regarding file names with periods.


{{Note|Flat structures with files for different shows in a single directory are '''''not supported'''''.}}
== Directories ==
You must set the content to TV Shows on the directory directly above the individual show folders.
To ensure accurate matches for your TV shows, the folder names should match the title displayed on the site being scraped. 
For the default TVDB scraper this may mean including the year of release, e.g. [http://www.thetvdb.com/?tab=series&id=83462 Castle (2009)] (in cases of duplicate titles), or the country of origin, e.g. [http://www.thetvdb.com/?tab=series&id=196921 Being Human (US)] (in cases of foreign remakes).


Below the show folder, the files may be organized how you wish, e.g. into separate season folders, or by year. These folders will be ignored.
= TV Show Folder =
=== Simple ===
[[File:Video-TVShow Folder.png|500px|right]]
Typically, you will add the top-level directory as a source and set the content to TV shows when you add it.
'''{{red|Each TV Show requires its own folder. The TV Show folder name is used to match the show at the scraper site.}}'''.
;Example
 
:{|
{{Kodi}} '''does not''' support the flat folder structure for TV Shows where all episodes from different TV Shows are in the same folder.
 
*The TV Show folders are located inside the '''''[[Naming_video_files#Source_Folder|Source folder]]'''''.
*The folder name will be '''''[[Userdata/advancedsettings.xml#.3Ccleanstrings.3E|cleaned]]''''' of commonly used strings, such as ''DVDRip, 1080p, x264,'' etc. before being passed to the scraper.  If the year of release is included, this will be '''''[[advancedsettings.xml#.3Ccleandatetime.3E|extracted]]''''' and used by the scraper to assist in making a match.
*Spaces, periods, or underscores may be used to separate words in the folder and file names, but should not be mixed. Note also the issue with Split-episodes regarding file names with periods.
 
 
Naming TV Shows follows the same guidelines as for Movies.
*Name the TV Show folder the same way as shown on the TV Show page at the scraper site.
*It is always best practice to include the year along with the title. This makes scraping more accurate and differentiates between original and remake versions.
*This guideline also applies to '''Country of Origin''' TV Shows. For example Hells Kitchen (UK), Hells Kitchen (US), Hells Kitchen (AU), Hells Kitchen (IT) etc.
*'''The title and (year) displayed at the scraper site is how you should name your show.'''
 
 
The '''best practice''' method is detailed in the image to the right. (season folders are optional)
*''Angel (1999)''- TV Show folder containing Single File episodes
*''Battlestar Galactica (1978)''- TV Show folder containing DVD folders for episodes
*''Battlestar Galactica (2004)''- TV Show folder containing Bluray folders fore episodes
 
 
== Split folders ==
Split folders are TV Shows that have episodes split between two or more folders '''located in different Sources'''. This may occur when a long running show is progressively saved on one drive but, over time, the drive has been filled with other content, forcing you to save new episodes on another drive.
 
To ensure these split TV Shows are correctly scraped as the same show, you '''must''' ensure that the TV Show folder names are identical. A slight variance could see a different show scraped for the second folder. If using NFO Files, then copy the NFO file from one location into the other split folders.
 
 
 
= Season Folder =
Season folders are optional. They are useful to reduce clutter in the main TV Show folder.
 
Even though {{kodi}} can accommodate the Season folder, it will ignore them. Instead it looks for the correctly numbered episode files.
 
As a side note, once your TV Shows have been scanned into the Library, it is possible to rename the Season folder displayed by {{kodi}}. '''''See: [[Season_rename|Season Rename]]'''''
 
 
When scraping be aware that season numbers may not be basic numbers. Many shows use the '''Year''' as the season number. This is quite common with older shows, daytime soaps and talk shows. '''Always check the site'''
<gallery mode="packed-overlay" widths="500px" heights="283px">
File:TVDB04.JPG|Image 1- Standard Season Numbers
File:TVDB03.JPG|Image 2- '''Year''' as Season Number
</gallery>
 
 
 
= Episode Files =
'''Check the site of the information provider to confirm your files are in the same order and that the episodes exist at the scraper site. If not, images and metadata will not match your episode files or your scrape will fail if the episodes do not exist.'''
 
*The episode files (or folders if using DVD or Bluray folders) are located inside the TV Show folder or inside Season folders if using them.
*The file name (or folder name) will be '''''[[Userdata/advancedsettings.xml#.3Ccleanstrings.3E|cleaned]]''''' of commonly used strings, such as ''DVDRip, 1080p, x264,'' etc. before being passed to the scraper.
*Spaces, periods, or underscores may be used to separate words in the folder and file names, but should not be mixed. Note also the issue with Split-episodes regarding file names with periods.
 
All episode files must be named and numbered correctly for the scanner to match the correct episode to the ''<episodeguide>'' URL of the TV Show downloaded from the scraper site. You cannot nominate season and episode numbering through NFO Files.  
 
The following is the simplest and most accurate way to name your episode files:
 
:{| class="prettytable"
|-
! scope="row" colspan="2"  style="width:300px; background-color:#a1f5e4; text-align:center;"| Angel (1999) S01E01.mkv<br>
|-
|Where:
|'''''Angel (1999)''''' = TV Show name
|-
|
|
<pre>
|'''''S01E01''''' = Season 1, Episode 1
TV Shows                  <<Source folder, Content: TV shows>>
|}
  |----TV Show 1
 
  |      |----Season #
 
  |            |--Files
For information on alternate or advanced episode naming conventions, see the ''Advanced Setup'' section further down this page.
  |----TV Show 2 (year)
 
  |      |--Files
For information on '''''alternate episode orders''''', see the ''Episode Groups'' section further down this page.
  |----TV Show 3
 
  |      |----2008
 
  |           |--Files
 
</pre>
== Specials Episodes ==
'''All Special Episodes use Season 00'''
:{| class="prettytable"
|-
! scope="row" ! style="width:300px; background-color:#a1f5e4; text-align:left;"| Doctor Who (2005) S00E50
|}
|}
=== Complex ===
 
They are listed at TheMovieDB in the Specials section of the Season listing.
 
Special Episdes are episodes that do not fit into the normal storyline of the TV Show. They may include items such as Christmas Specials, Season recap episodes, Made for TV Movies that extend the storyline, Unaired Pilots etc
 
Special Episodes can be displayed in amongst the regular episodes through the use of '''[[NFO_files/TV_shows|NFO Files]]'''. this is specified using the '''<displayepisode></displayepisode>''' and '''<displayseason></displayseason>''' tags.
 
 
 
= Episode Groups =
Episode Groups or Orders are listings with alternate episode orders. Some TV Shows are broadcast in one order but the DVD/Bluray release may have a different screening order. A well known example is the TV Show ''Firefly'' where the Studio opted to broadcast high action episodes for ratings first, while the Producer wanted a different order to correctly unfold the storyline.
 
 
== TheMovieDB-TV Shows ==
TheMovieDB uses Episode Groups for additional episode orders.
*Numerous Groups can be added which should cater to the different releases between countries
*Creating Groups and adding episodes is quite simplistic, using drag and drop which should encourage contributors to complete the entries
*Where available, the listings are easily accessible for viewing as shown in the images below
 
<gallery mode="traditional" widths="500px" heights="283px">
File:EpisodeGroups01.jpg|Image 1- Accessing Episode Groups
File:EpisodeGroups02.jpg|Image 2- Available Episode Groups
File:EpisodeGroups03.jpg|Image 3- Select a Group, then copy the address for use in a Parsing NFO file.
</gallery>
 
To use one of the orders for scraping, follow the images above and place the address in a '''''[[NFO_files#Parsing_nfo|Parsing NFO file]]''''' then scrape. The Parsing NFO File will point the scraper to the listing. <ref>https://forum.kodi.tv/showthread.php?tid=338467&pid=2801494#pid2801494</ref>
 
 
 
== The TVDB ==
The TVDB allows for three listing orders as detailed below.
*These are the only three orders available.
*The current web site is flawed and does not allow the display of the different orders.
 
 
;Aired Order
*This is the default order set in the scraper settings.
*TVDB lists all TV shows in the original '''Aired Order'''. The first time a show is ever broadcast, that is the listing shown. The site is not concerned with how it was broadcast the 2nd, 3rd or 15th time, or how it was broadcast in other countries, or during syndication. It only lists the order of the FIRST TIME ever broadcast, whether that be on Free To Air or Subscription Television.
*Episodes are grouped and listed into Seasons and each episode is numbered sequentially from 1, which resets for each season.
 
;DVD Order
*In many cases, DVD's are released with a different episode listing, normally being the original order envisioned by the Director. To accommodate this, the site also has a '''DVD Order''' listing.
*Episodes are grouped and listed into Seasons and each episode is numbered sequentially from 1, which resets for each season.
*There are many TV Shows on the TVDB site that do not have the DVD Order data entered. The scraper will default back to Aired Order if there is no DVD Order information listed.
*Note: As the data at TVDB is created by the open community, it is not uncommon for errors to occur with DVD Order details. As it is seen as secondary information, the errors can go unnoticed. One major error that affects the scrapers is incomplete DVD Order details. For example, some episodes have no DVD Order data, while other episodes in the same season do have the data.
*Early May 2018, TVDB upgraded their website to v2.0. Unfortunately a glitch has prevented the display of DVD Order and Absolute Order information. It is unknown when it will be rectified.
 
;Absolute Order
*This order ignores Seasons and gives each episode an incremental number starting at 1.
*This order is used for Anime type shows.
 
 
The Order you use can be set in the settings page for the TVDB Scraper.
 
 
 
----
'''{{big|{{red|The remainder of this page deals with Special Use cases and can be safely ignored. Most libraries will not require implementing the following additional name extensions.}}}}'''
----
 
<div style="{{linear-gradient|left|#a1f5e4, #f5f5a1}}">{{next|[[Adding_video_sources|'''Add Source & Scrape''']]}} </div>
 
 
 
= Advanced Setup =
The previous section details the simplest method to set up your TV Show library. It is considered the '''''best practice''''' method.
 
The sections from here onwards are alternate or advanced methods. With added complexity comes higher maintenance and more potential problems and scraping errors.
 
 
 
== TV Show folder ==
'''{{red|These other methods are available but NOT recommended. The sub-folders are easily mistaken and scraped as false TV shows. While it is possible to find and fix the ghost entries, the extra time and work involved will override any possible benefits. If you need to re-build your library at a later stage, the problems will need to be solved again.}}'''
 
In more complex situations where your top-level directory is further sub-divided before the show folders, you can add the top-level as source but not set the content, and then set the content to TV shows on each sub-folder.
In more complex situations where your top-level directory is further sub-divided before the show folders, you can add the top-level as source but not set the content, and then set the content to TV shows on each sub-folder.
;Example
;Example
:{|
 
:{| class="prettytable" style="width:500px; background-color:#a1f5e4; text-align:left;"
|
|
<pre>
<pre>
Line 50: Line 180:
</pre>
</pre>
|}
|}
It's also possible to have a sub-folder group multiple shows together in an otherwise normal directory structure.  Just change the content on the sub-folder and de-select the "Selected folder contains a single TV show" setting.
 
 
It is also possible to have a sub-folder group multiple shows together in an otherwise normal directory structure.  Just change the content on the sub-folder and de-select the "Selected folder contains a single TV show" setting.
 
;Example
;Example
:{|
 
:{| class="prettytable" style="width:500px; background-color:#a1f5e4; text-align:left;"
|
|
<pre>
<pre>
Line 66: Line 200:
</pre>
</pre>
|}
|}
In these cases, it's best to refrain from scanning the files into the library until the content is set correctly for all folders, to avoid incorrect results and the need to rescan.
In these cases, it's best to refrain from scanning the files into the library until the content is set correctly for all folders, to avoid incorrect results and the need to rescan.
== Files ==
XBMC uses a series of regular expressions to determine the season and episode numbers from the file name. 
These are checked in order with the first match being the one used.  Anything else included in the file name is ignored.


There are '''7''' default patterns, plus a separate multi-episode pattern.  Use of any other numbering scheme will require you to edit your [[advancedsettings.xml]] (see [[#Using custom file names|below]]).


{{note|In the examples we will mostly use the format:
:''anything''_'''<<pattern>>'''.ext,
where ''name'' is the title of the show, and .ext is a [[advancedsettings.xml#.3Cvideoextensions.3E|recognized video file extension]], but '''''any format''''' will work, so long as the pattern is included somewhere in it. '''''name'' is optional''' and could just as easily be after the pattern, or excluded entirely. }}
=== Single episode ===
Most of the time you will only have a single episode per file.


The order in which the patterns are checked for by XBMC is included in brackets after each example below (most patterns allow some variation, hence the duplicate numbers).  If your file name contains more than one pattern, only the first one checked for will be used.
== Seasons ==
Nil availble options. Season folders are ignored by {{kodi}} which means you can name them as you please.
 
 
 
== Single Episodes ==
Episode files are assumed to  contain a single episode. If you have files that contain two or more episodes, then read the '''''Multi-Episodes''''' section below.
 
The structure of the episode name is as follows:
 
:{| class="prettytable"
|-
! scope="row" ! style="width:300px; background-color:#a1f5e4; text-align:left;"| name <<pattern>>.ext
|}
 
:where:
:*'''name''' is the title of the show and is optional. It could just as easily be after the pattern, or excluded entirely.
:*'''<<pattern>>''' is one of the expressions in the following tables. ''S'' = Season number; ''E'' = Episode number
:*'''.ext''' is a recognized video file extension, (mkv, avi, ts, mp4, etc) or ommitted entirely if using DVD or Bluray folders.
 
Kodi uses a series of regular expressions to determine the season and episode numbers from the file name. These are checked in a pre-determined order with the first match being the one used and everything else in the file name is ignored. NFO Files are '''never''' checked for season and episode numbers.


All the examples will be read as season 1, episode 2.
There are 8 default patterns, plus a separate multi-episode pattern. Using any other numbering convention outside of the ones provided in the list below will require you to edit your advancedsettings.xml and insert your custom RegEx.
;With season
 
:The most common scenario.
Spaces, periods, or underscores may be used to separate words in the folder and file names, but shouldn't be mixed in the same name. The regex is not case-sensitive and either uppercase or lowercase may be used. The examples on this page use uppercase.
:''anything''_'''s01e02'''.ext <sup>(1)</sup>
 
:''anything''_'''s1e2'''.ext <sup>(1)</sup>
 
:''anything''_'''s01.e02'''.ext <sup>(1)</sup>
The following table lists:
:''anything''_'''s01_e02'''.ext <sup>(1)</sup>
*The pattern that {{kodi}} will search for.  
:''anything''_'''1x02'''.ext <sup>(5)</sup>
*The order of the search. ie. Patterns numbered '''1''' will be matched first and those numbered '''7''' will be matched last.
:''anything''_'''102'''.ext <sup>(6)</sup>
 
;Without season
;With Season
:The most common usage and used for nearly all TV Shows.
;No Season
:In cases where you only have one season (or are using absolute order in the TVDB scraper), you may want to forego the inclusion of the season number.
:In cases where you only have one season (or are using absolute order in the TVDB scraper), you may want to forego the inclusion of the season number.
:''anything''_'''ep02'''.ext <sup>(2)</sup>
:''anything''_'''ep_02'''.ext <sup>(2)</sup>
:You may also use Roman numerals (I, IV, XI, etc.), often used for mini-series or short documentary series.
:''anything''_'''part.II'''.ext <sup>(7)</sup>
:''anything''_'''pt.II'''.ext <sup>(7)</sup>
:''anything''_'''pt_II'''.ext <sup>(7)</sup>
;By date
;By date
:Common for long-running daily shows, you can also use the date the episode aired.
:Common for long-running daily shows, allows the use of aired date of the episode.
:''anything''_'''1996.11.14'''.ext <sup>(3)</sup>
 
:''anything''_'''1996-11-14'''.ext <sup>(3)</sup>
{| class="prettytable"
:''anything''_'''14.11.1996'''.ext <sup>(4)</sup>
|-
! colspan="2" style="background-color:#a1f5e4;" | With Season
! colspan="2" style="background-color:#a1f5e4;" | No Season
! colspan="2" style="background-color:#a1f5e4;" | By Date
|+
! style="background-color:#f5f5a1;" | Order
! style="background-color:#f5f5a1; width:200px" | Episode Naming
! style="background-color:#f5f5a1;" | Order
! style="background-color:#f5f5a1; width:200px" | Episode Naming
! style="background-color:#f5f5a1;" | Order
! style="background-color:#f5f5a1; width:200px" | Episode Naming
|-
|style="width:50px; text-align:center;"|1
|style="width:50px; text-align:left;"|''Name'' '''S01E02'''.ext
|style="width:50px; text-align:center;"|2
|style="width:50px; text-align:left;"|''Name'' '''ep02'''.ext
|style="width:50px; text-align:center;"|3
|style="width:50px; text-align:left;"|''Name'' '''yyyy.mm.dd'''.ext
|-
|style="width:50px; text-align:center;"|1
|style="width:50px; text-align:left;"|''Name'' '''S1E2'''.ext
|style="width:50px; text-align:center;"|2
|style="width:50px; text-align:left;"|''Name'' '''ep_02'''.ext
|style="width:50px; text-align:center;"|3
|style="width:50px; text-align:left;"|''Name'' '''yyyy-mm-dd'''.ext
|-
|style="width:50px; text-align:center;"|1
|style="width:50px; text-align:left;"|''Name'' '''S01.E02'''.ext
|style="width:50px; text-align:center;"|7
|style="width:50px; text-align:left;"|''Name'' '''part.II'''.ext
|style="width:50px; text-align:center;"|4
|style="width:50px; text-align:left;"|''Name'' '''dd.mm.yyyy'''.ext
|-
|style="width:50px; text-align:center;"|1
|style="width:50px; text-align:left;"|''Name'' '''S01_E02'''.ext
|style="width:50px; text-align:center;"|7
|style="width:50px; text-align:left;"|''Name'' '''pt.II'''.ext
|style="width:50px; text-align:center;"|
|style="width:50px; text-align:left;"|
|-
|style="width:50px; text-align:center;"|1
|style="width:50px; text-align:left;"|''Name'' '''S01xE02'''.ext
|style="width:50px; text-align:center;"|7
|style="width:50px; text-align:left;"|''Name'' '''pt_II'''.ext
|style="width:50px; text-align:center;"|
|style="width:50px; text-align:left;"|
|-
|style="width:50px; text-align:center;"|5
|style="width:50px; text-align:left;"|''Name'' '''1x02'''.ext
|style="width:50px; text-align:center;"|
|style="width:50px; text-align:left;"|
|style="width:50px; text-align:center;"|
|style="width:50px; text-align:left;"|
|-
|style="width:50px; text-align:center;"|6
|style="width:50px; text-align:left;"|''Name'' '''102'''.ext
|style="width:50px; text-align:left;"|
|style="width:50px; text-align:left;"|
|style="width:50px; text-align:left;"|
|style="width:50px; text-align:left;"|
|}
 
 
 
== Multi-Episodes ==
In cases where the file contains more than one episode, it is possible to specify all the episodes included in that file. Everything after the first found pattern match will be checked for further matches to the same pattern.
 
*When using a single video file for multiple episodes it is possible to tell Kodi when each episode starts using '''''[[bookmarks|Episode Bookmarks]]'''''
*Two versions are shown- Long version and Short version. Only the episodes in the file name will be added, e.g. ''name''.'''s01e01-03'''.ext will not include episode 2.
*The patterns are the same for Single Episode numbering, but extended to include multiple episodes.
 
:'''''See also: [[Userdata/advancedsettings.xml#.3Ctvmultipartmatching.3E|multi-episode pattern]]'''''
 
{| class="prettytable"
|-
! colspan="2" style="background-color:#a1f5e4;" | Complex Pattern
! colspan="2" style="background-color:#a1f5e4;" | Short Pattern
|+
! style="background-color:#f5f5a1;" | Order
! style="background-color:#f5f5a1; width:350px" | Example Name
! style="background-color:#f5f5a1;" | Order
! style="background-color:#f5f5a1; width:200px" | Example Name
|-
|style="width:50px; text-align:center;"|1
|style="width:300px; text-align:left;"|''name'' '''s01e01'''-'''s01e02'''.ext
|style="width:50px; text-align:center;"|1
|style="width:150px; text-align:left;"|''name'' '''s01e01e02'''.ext
|-
|style="width:50px; text-align:center;"|1
|style="width:300px; text-align:left;"|''name'' '''s01e01'''-''episode1.title''-'''s01e02'''-''episode2.title''.ext
|style="width:50px; text-align:center;"|1
|style="width:150px; text-align:left;"|''name'' '''s01e01-02-03'''.ext
|-
|style="width:50px; text-align:center;"|1
|style="width:300px; text-align:left;"|''name'' '''s01e01'''-'''s01e02'''-'''s01e03'''.ext
|style="width:50px; text-align:center;"|5
|style="width:150px; text-align:left;"|''name'' '''1x01x02'''.ext
|-
|style="width:50px; text-align:center;"|5
|style="width:300px; text-align:left;"|''name'' '''1x01'''-'''1x02'''.ext
|style="width:50px; text-align:center;"|2
|style="width:150px; text-align:left;"|''name'' '''ep01-02'''.ext
|-
|style="width:50px; text-align:center;"|2
|style="width:300px; text-align:left;"|''name'' '''ep01'''-'''ep02'''.ext
|style="width:50px; text-align:center;"|
|style="width:150px; text-align:left;"|
|}
 
 
 
== Split Episodes ==
{{resize|1.4em|{{note|The November 2019 upgrade of the TVDB site has removed the ''E01.1, E01.2'' type numbering of episodes. The following section no longer applies and will be removed from this page completely in due course}}}}
 
<s>'''{{red|This section applies to the TVDB site. It does not apply if you are using TheMovieDB-TV Shows scraper.}}'''<br>
'''{{red|It does not apply in all cases as the listings rely on community members applying the correct numbering which is not always the case. Check the listing first.}}'''


=== Multi-episode ===
Split-episodes are feature length episodes that were broadcast as two separate episodes. The Pilot episode can be a feature length episode for many TV Shows. These are re-combined on DVD releases as the original single episode. They are numbered by decimal sub parts eg S01E01.1, S01E01.2, S01E02 '''This is a common cause for failed scrapes of certain episodes'''. The entry must be checked at TVDB to ensure correct numbering has been applied. It is also typical for childrens cartoons, files which only contain a distinct part of an episode may be named as to which part, if the scraper supports it.
In cases where your file contains more than one episode, you can specify all the episodes included.  Everything after the first found pattern match will be checked for further matches to the same pattern.
;Examples
:''anything''_'''s01e01'''_'''s01e02'''.ext
:''anything''.'''s01e01'''.''episode1.title''.'''s01e02'''.''episode2.title''.ext
:''anything''.'''s01e01'''.'''s01e02'''.'''s01e03'''.ext
:''anything''.'''1x01'''_'''1x02'''.ext
:{{s|''anything''.'''s01e01''' 1x02.ext}} (mixed patterns do not work)
:''anything''.'''ep01'''.'''ep02'''.ext
The remainder will also be checked against a shorter form [[Userdata/advancedsettings.xml#.3Ctvmultipartmatching.3E|multi-episode pattern]].
;Examples
:''anything''.'''s01e01e02'''.ext
:''anything''.'''s01e01-02-03'''.ext
:''anything''.'''1x01x02'''.ext
:''anything''.'''ep01_02'''.ext
The '''ex-_''' are fully interchangeable and stackable, e.g. ''name''.'''1x01e02_03-x-04'''.ext is perfectly valid (if somewhat odd).


{{Note|Only the episodes in the file name will be added, e.g. ''name''.'''s01e01-03'''.ext will not include episode 2.}}
Up to 9 sub-parts are allowed (using either .1-.9 or a-i). These can also be combined with the multi-episode pattern, if your file contains all parts joined as a single episode.


=== Split-episode ===
Using the patterns from the Single Episodes section, they have been extended to include Split episodes. The Order has been ommitted.
Typical for childrens cartoons, files which only contain a distinct part of an episode may be named as to which part, if the scraper supports it (currently only TVDB using DVD order).
;Examples
:''anything''.'''s01e01.1'''.ext
:''anything''.'''s01e01a'''.ext
:''anything''.'''1x01.1'''.ext
:''anything''.'''1x01a'''.ext
:''anything''.'''ep01.1'''.ext
:''anything''.'''101.1'''.ext
Up to 9 sub-parts are allowed (using either .1-.9 or a-i).


These can also be combined with the multi-episode pattern, if your file contains all parts joined as a single episode.
{| class="prettytable"
;Examples
|-
:''anything''.'''s01e01.1.s01e01.2'''.ext
! colspan="2" style="background-color:#a1f5e4;" | Single Episodes
:''anything''.'''1x01.1x01.2'''.ext (note this is (1x01.1)x(01.2) not (1x01).(1x01.2))
! colspan="2" style="background-color:#a1f5e4;" | Multi Part Episodes
:''anything''.'''ep01a_01b'''.ext
|+
! style="background-color:#f5f5a1;" | Order
! style="background-color:#f5f5a1; width:350px" | Example Name
! style="background-color:#f5f5a1;" | Order
! style="background-color:#f5f5a1; width:200px" | Example Name
|-
|style="width:50px; text-align:center;"|
|style="width:300px; text-align:left;"|''name'' '''s01e01.1'''.ext
|style="width:50px; text-align:center;"|
|style="width:150px; text-align:left;"|''name'' '''s01e01.1.s01e01.2'''.ext
|-
|style="width:50px; text-align:center;"|
|style="width:300px; text-align:left;"|''name'' '''s01e01a'''.ext
|style="width:50px; text-align:center;"|
|style="width:150px; text-align:left;"|''name'' '''1x01.1-x01.2'''.ext
|-
|style="width:50px; text-align:center;"|
|style="width:300px; text-align:left;"|''name'' '''1x01.1'''.ext
|style="width:50px; text-align:center;"|
|style="width:150px; text-align:left;"|''name'' '''ep01a-01b'''.ext
|-
|style="width:50px; text-align:center;"|
|style="width:300px; text-align:left;"|''name'' '''1x01a'''.ext
|style="width:50px; text-align:center;"|
|style="width:150px; text-align:left;"|
|-
|style="width:50px; text-align:center;"|
|style="width:300px; text-align:left;"|''name'' '''ep01.1'''.ext
|style="width:50px; text-align:center;"|
|style="width:150px; text-align:left;"|
|-
|style="width:50px; text-align:center;"|
|style="width:300px; text-align:left;"|''name'' '''101.1'''.ext
|style="width:50px; text-align:center;"|
|style="width:150px; text-align:left;"|
|}


Each part will be added to the library just with its full episode number, the sub-part will not be displayed.
Each part will be added to the library just with its full episode number, the sub-part will not be displayed.


{{Note|If you use periods in your file names and include material after the episode number (such as the episode title), you may get a false match to a split-episode pattern if that material begins with a number below 10, e.g.
'''Note: '''If you use periods in your file names and include material after the episode number (such as the episode title), you may get a false match to a split-episode pattern if that material begins with a number below 10. This will likely lead to the episode not being added to the library.  The recommendation is to use a space or underscore instead to separate the numbers for those files, e.g.
:''Nikita''.'''S01E02.2'''.0.mkv
</s>
:''24''.'''1x02.1'''.00.am-2.00.am.avi
 
:''anything''.'''1x01.1'''x'''02'''.ext  (i.e. (1x01.1) x (02) )
 
This will likely lead to the episode not being added to the library.  The recommendation is to use a space or underscore instead to separate the numbers for those files, e.g.
 
:''Nikita''.'''S01E02'''_2.0.mkv
= Stub and Stream Files =
:''24''.'''1x02'''_1.00.am-2.00.am.avi
{{main|Media_stubs}}
:''anything''.'''1x01''' '''1x02'''.ext  (i.e. (1x01) (1x02) )
{{#lst:Media_stubs|intro}}
}}
 
=== Special episodes ===
 
Special episodes, if supported by your scraper, should be marked as being season 0.  You should check the site being scraped to see what episode number to use, as they can be fairly arbitrary. For example, [http://thetvdb.com/?tab=season&seriesid=76736&seasonid=24194&lid=7 BlackAdder's Christmas Carol] should have a file name that matches season 0 episode 3, e.g.:
{{main|Internet_video_and_audio_streams}}
:''BlackAdder''.'''s00e03'''.BlackAdder's Christmas Carol.mkv
{{#lst:Internet_video_and_audio_streams|intro}}
 
 
 
= Media Tags / Flags =
{{main|Media flags}}
 
[[File:480.png|50px]] [[File:1080.png|50px]] [[File:720.png|50px]] [[File:1080 n.png|50px]] [[File:480-1.png|50px]]
[[File:Divx.png|80px]] [[File:Xvid.png|80px]] [[File:H264.png|80px]] [[File:Bluray.png|80px]] [[File:Dvd.png|80px]] [[File:Avc1.png|80px]]
[[File:1.33.png|50px]] [[File:1.66.png|50px]] [[File:2.20.png|50px]] [[File:2.35.png|50px]]
 
 
Media flags are icons in Kodi that displays the meta-information from the media file of a movie, TV show or music title. They are skin specific, and what works in one skin, may not work in another skin. It is always best to check with the skin sub-forum which flags and tags are used.
 
'''It is important to note that the skin will display these flags even when these extensions are not used.''' The only difference being that without the extensions, the movie must be played first in order for {{kodi}} to read the audio and video codec data.
 
'''The actual audio and video codec data will override any extension used.''' This means that if you set the extension of, say, '''.ATMOS''' but the video file only has a stereo track, then the '''.ATMOS''' flag will be removed.
 
 
Example- note that movie folders are used, and the folder is simply named while the filename has been modified with extensions.
{| class="prettytable"
|-
! scope="row" ! style="width:400px; background-color:#a1f5e4; text-align:left;"| ...\Paul (2011)\Paul (2011).4K.HDR.Atmos.mkv
|}
 


== The TVDB scraper ==
The default TV show scraper uses [http://thetvdb.com The TVDB] to scan your TV shows into the library.  You should search on the site before adding a new show to ensure you're using the right title.  Caution should be taken over using aliases or alternative titles, although these will work in a website search, they don't work in the API the scraper uses.


The TVDB scraper has three possible settings for determining episode order: Aired order, DVD order, and Absolute order.  These will affect how you name your files, or vice versa, how you name your files will affect which setting you should use.
== 3D Episodes ==
;Aired order
{{Main|3D}}
:The default, episodes are ordered by season and numbered as they were originally broadcast.  For split-episodes, each part is given its own distinct episode number.
Some 3D episodes might need an additional file name extension to be identified by Kodi as 3D. See '''''[[3D]]''''' for details on that additional extension, and when it is needed.
:Visible when you click on any season link on the show page.
;DVD order
:Episodes are ordered by season and numbered as they appeared on DVD release.  Split-episodes are numbered by episode and sub-part.
:Visible when you click the "DVD Order" link on any season page for the show.
;Absolute order
:Episodes are ordered as a single season and numbered sequentially from start to finish. Split episodes have distinct episode numbers.  Commonly used for anime.
:Visible when you click the "Absolute Order" link on the All seasons page for the show.
For a list of all available settings and their meaning, see [[Add-on:The TVDB]].
== Advanced usage ==
=== Supplemental tools ===
A variety of [[supplemental tools]] exist to automatically rename files and folders into XBMC compatible formats.
* [[Supplemental tools/Linux#Rename tools|Renaming tools for Linux]]
* [[Supplemental tools/Mac OS X#Rename tools|Renaming tools for Mac OS X]]
* [[Supplemental tools/Windows#Rename tools|Renaming tools for Windows]]
{{-}}


=== Changing scraper settings for one show ===
A very common situation, when you have one or more shows that require different scraper settings (particularly episode order) to the other shows in your folder, it is possible to change the settings for individual shows.  Just navigate to the show's folder in file view and select Change content from the context menu and then alter the settings from there.  If the files have already been incorrectly added to the library, you will need to refresh the folder (e.g. from the info screen).


The classic example is Firefly, whose aired order differs greatly from its DVD order:
 
<pre>
= Custom Filenames =
TV Shows                        <<Source folder, Content: TV shows, Scraper: TVDB - default settings>>
  |----TV Show 1
  |      |----Season 1
  |            |--Files
  |----TV Show 2
  |      |--Files
  |----Firefly                  <<Scraper: TVDB - DVD order>>
  |      |----1x01.Serenity.ext
  |      |----1x02.The Train Job.ext
</pre>
=== Using custom file names ===
It's possible to use custom file names that don't match any of the default patterns by editing your [[advancedsettings.xml]] file to include a [[advancedsettings.xml#.3Ctvshowmatching.3E|tvshowmatching]] tag containing regular expressions.
It's possible to use custom file names that don't match any of the default patterns by editing your [[advancedsettings.xml]] file to include a [[advancedsettings.xml#.3Ctvshowmatching.3E|tvshowmatching]] tag containing regular expressions.


Line 199: Line 461:
:2 capturing groups = season number + episode number (in that order), no multi-episode matches will be attempted
:2 capturing groups = season number + episode number (in that order), no multi-episode matches will be attempted
:3 capturing groups = season number + episode number + multi-episode matching part (typically just the remainder of the file name)
:3 capturing groups = season number + episode number + multi-episode matching part (typically just the remainder of the file name)
(A capturing group is essentially a part of the regexp contained inside brackets.)
(A capturing group is essentially a part of the regexp contained inside brackets.)


Line 205: Line 468:
Date-based regexps are also possible, and are marked by a bydate="true" attribute in the regexp.  These also use three capturing groups, either as year-month-day or day-month-year, the lengths must be exactly 4-2-2 or 2-2-4.
Date-based regexps are also possible, and are marked by a bydate="true" attribute in the regexp.  These also use three capturing groups, either as year-month-day or day-month-year, the lengths must be exactly 4-2-2 or 2-2-4.


Your custom tvshowmatching regexps can be either checked for before the default set (action="prepend") or after (action="append").  Not including an action will result in only your regexps being tested.  Care should be taken to ensure that the right regexp matches your file names, particularly in regard to the three digit "102" pattern seen [[#single episode|above]].
Your custom tvshowmatching regexps can be either checked for before the default set using <code>action="prepend"</code>, or after using <code>action="append"</code>.  Not including an action will result in only your regexps being tested.  Care should be taken to ensure that the right regexp matches your file names, particularly in regard to the three digit "102" pattern seen [[#Single_Episodes|above]].
The regexps should be grouped together inside a single tvshowmatching tag, although you can use two if you wish to prepend ''and'' append different regexps.
The regexps should be grouped together inside a single tvshowmatching tag, although you can use two if you wish to prepend ''and'' append different regexps.
{{note|The expressions are converted to lower case before being evaluated on ''XBMC v13.0 alpha4'' and earlier versions, so Perl character classes like '\W' and '\D' can’t be used. Use bracketed character classes like '[^A-Za-z0-9_]' and '[^0-9]' instead.}}


You can also change the multi-episode matching regexp by including a [[Userdata/advancedsettings.xml#.3Ctvmultipartmatching.3E|tvmultipartmatching]] tag in your advancedsettings.xml (separate from the tvshowmatching tag).  
You can also change the multi-episode matching regexp by including a [[Userdata/advancedsettings.xml#.3Ctvmultipartmatching.3E|tvmultipartmatching]] tag in your advancedsettings.xml (separate from the tvshowmatching tag).  
Line 213: Line 475:
The tvmultipartmatching requires one capturing group for the episode number.
The tvmultipartmatching requires one capturing group for the episode number.


{{note|For simplicity, the split-episode pattern has been excluded from the examples below.}}
For simplicity, the split-episode pattern has been excluded from the examples below. To allow for split-episodes, replace the <code>[0-9]+</code> in the episode capturing group with <code>[0-9]+(?:(?:[a-i]|\.[1-9])(?![0-9]))?</code>
To allow for split-episodes, replace the <code>[0-9]+</code> in the episode capturing group with <code>[0-9]+(?:(?:[a-i]|\.[1-9])(?![0-9]))?</code>
 
==== Examples ====
 
 
== Examples ==
A fairly straightforward example to begin.
A fairly straightforward example to begin.
;Season ## - Episode ##
;Season ## - Episode ##
:"Season [season#] - Episode [episode#]" anywhere in the file name
:"Season [season#] - Episode [episode#]" anywhere in the file name
:{|
:{| class="prettytable" style="width:900px; background-color:#a1f5e4; text-align:left;"
|-
|
|
<syntaxhighlight lang="xml" enclose="div">
<syntaxhighlight lang=xml enclose="div">
  <tvshowmatching action="prepend">
  <tvshowmatching action="prepend">
  <regexp>Season ([0-9]+) - Episode ([0-9]+)([^\\/]*)$</regexp>
    <regexp>Season ([0-9]+) - Episode ([0-9]+)([^\\/]*)$</regexp>
  </tvshowmatching>
  </tvshowmatching>
</syntaxhighlight>
</syntaxhighlight>
Line 231: Line 496:




----
The entire file path is passed to the regexps, so care should be taken to ensure the matches can't occur earlier in the path, but this does mean for example, you can capture the season number from a sub-folder name.
The entire file path is passed to the regexps, so care should be taken to ensure the matches can't occur earlier in the path, but this does mean for example, you can capture the season number from a sub-folder name.
;\Season #\##
;\Season #\##
:Season [season#] at the end of the directory name, file name starts with [episode#]
:Season [season#] at the end of the directory name, file name starts with [episode#]
:{|
:{| class="prettytable" style="width:900px; background-color:#a1f5e4; text-align:left;"
|-
|
|
<syntaxhighlight lang="xml" enclose="div">
<syntaxhighlight lang=xml enclose="div">
  <tvshowmatching action="prepend">
  <tvshowmatching action="prepend">
     <regexp>Season[\._ ]([0-9]+)[\\/]([0-9]+)([^\\/]*)$</regexp>
     <regexp>Season[\._ ]([0-9]+)[\\/]([0-9]+)([^\\/]*)$</regexp>
Line 246: Line 514:




----
For numbering without a season, you should ensure that only the episode number gets matched against and not another number in the title or episode title, or a number as part of a different pattern.
For numbering without a season, you should ensure that only the episode number gets matched against and not another number in the title or episode title, or a number as part of a different pattern.
; - ## -  
; - ## -  
:" - [episode#] - " anywhere in the file name
:" - [episode#] - " anywhere in the file name
:{|
:{| class="prettytable" style="width:900px; background-color:#a1f5e4; text-align:left;"
|-
|
|
<syntaxhighlight lang="xml" enclose="div">
<syntaxhighlight lang=xml enclose="div">
  <tvshowmatching action="prepend">
  <tvshowmatching action="prepend">
     <regexp> - ()([0-9]+)((?:-[0-9]+)*) - [^\\/]*$</regexp>
     <regexp> - ()([0-9]+)((?:-[0-9]+)*) - [^\\/]*$</regexp>
Line 261: Line 532:




----
It's also possible to specify a different default season for without-season regexps.
It's also possible to specify a different default season for without-season regexps.
;\Specials\##
;\Specials\##
:Directory name is Specials, file name starts with [episode#]
:Directory name is Specials, file name starts with [episode#]
:{|
:{| class="prettytable" style="width:900px; background-color:#a1f5e4; text-align:left;"
|-
|
|
<syntaxhighlight lang="xml" enclose="div">
<syntaxhighlight lang=xml enclose="div">
  <tvshowmatching action="prepend">
  <tvshowmatching action="prepend">
     <regexp defaultseason="0">Specials[\\/]()([0-9]+)([^\\/]*)$</regexp>
     <regexp defaultseason="0">Specials[\\/]()([0-9]+)([^\\/]*)$</regexp>
Line 276: Line 550:




----
The default date-based regexps only allow for periods or hyphens as delimiters...
The default date-based regexps only allow for periods or hyphens as delimiters...
;<nowiki>####_##_##</nowiki>
;<nowiki>####_##_##</nowiki>
:[year]_[month]_[day] anywhere in the file name
:[year]_[month]_[day] anywhere in the file name
:{|
:{| class="prettytable" style="width:900px; background-color:#a1f5e4; text-align:left;"
|-
|
|
<syntaxhighlight lang="xml" enclose="div">
<syntaxhighlight lang=xml enclose="div">
  <tvshowmatching action="prepend">
  <tvshowmatching action="prepend">
     <regexp bydate="true">([0-9]{4})_([0-9]{2})_([0-9]{2})[^\\/]*$</regexp>
     <regexp bydate="true">([0-9]{4})_([0-9]{2})_([0-9]{2})[^\\/]*$</regexp>
Line 288: Line 565:
|}
|}
:'''Example:''' : \The Colbert Report\'''2005_10_17'''.avi
:'''Example:''' : \The Colbert Report\'''2005_10_17'''.avi
:The exact number of digits is specified for each group to ensure compliance. A separate [day]_[month]_[year] regexp would be needed if both formats are in use.
:The exact number of digits is specified for each group to ensure compliance. A separate [month]_[day]_[year] regexp would be needed if both formats are in use.




----
The default regexps don't allow for DVD folder structures, this can usually be remedied by replacing the final <code>$</code> with <code>(?:(?:[\\/]video_ts)?[\\/]video_ts\.ifo)$</code>
The default regexps don't allow for DVD folder structures, this can usually be remedied by replacing the final <code>$</code> with <code>(?:(?:[\\/]video_ts)?[\\/]video_ts\.ifo)$</code>
;S##E##\VIDEO_TS\VIDEO_TS.IFO
;S##E##\VIDEO_TS\VIDEO_TS.IFO
:{|
:{| class="prettytable" style="width:900px; background-color:#a1f5e4; text-align:left;"
|-
|
|
<syntaxhighlight lang="xml" enclose="div">
<syntaxhighlight lang=xml enclose="div">
  <tvshowmatching action="append">
  <tvshowmatching action="append">
     <regexp>[Ss]([0-9]+)[ ._-]*[Ee]([0-9]+)([^\\/]*)(?:(?:[\\/]video_ts)?[\\/]video_ts\.ifo)$</regexp>
     <regexp>[Ss]([0-9]+)[ ._-]*[Ee]([0-9]+)([^\\/]*)(?:(?:[\\/]VIDEO_TS)?[\\/]VIDEO_TS\.IFO)$</regexp>
  </tvshowmatching>
  </tvshowmatching>
</syntaxhighlight>
</syntaxhighlight>
Line 305: Line 585:




----
Similarly for Bluray folder structures, you can replace the final <code>$</code> with <code>(?:(?:[\\/]bdmv)?[\\/]index\.bdmv)$</code>
Similarly for Bluray folder structures, you can replace the final <code>$</code> with <code>(?:(?:[\\/]bdmv)?[\\/]index\.bdmv)$</code>
;<nowiki>#</nowiki>x##\BDMV\index.bdmv
;<nowiki>#</nowiki>x##\BDMV\index.bdmv
:{|
:{| class="prettytable" style="width:900px; background-color:#a1f5e4; text-align:left;"
|-
|
|
<syntaxhighlight lang="xml" enclose="div">
<syntaxhighlight lang=xml enclose="div">
  <tvshowmatching action="append">
  <tvshowmatching action="append">
     <regexp>[\\/\._ \[\(-]([0-9]+)x([0-9]+)([^\\/]*)(?:(?:[\\/]bdmv)?[\\/]index\.bdmv)$</regexp>
     <regexp>[\\/\._ \[\(-]([0-9]+)x([0-9]+)([^\\/]*)(?:(?:[\\/]bdmv)?[\\/]index\.bdmv)$</regexp>
Line 316: Line 599:
|}
|}
:With Bluray folders, you'll also run into trouble with the various mpls and m2ts files incorrectly matching other patterns, so you should also exclude all the other folders and files from being scanned:
:With Bluray folders, you'll also run into trouble with the various mpls and m2ts files incorrectly matching other patterns, so you should also exclude all the other folders and files from being scanned:
:{|
:{| class="prettytable" style="width:900px; background-color:#a1f5e4; text-align:left;"
|-
|
|
<syntaxhighlight lang="xml" enclose="div">
<syntaxhighlight lang=xml enclose="div">
   <video>
   <video>
     <excludetvshowsfromscan action="append">
     <excludetvshowsfromscan action="append">
Line 329: Line 613:




----
Finally, a tvmultipartmatching example.
Finally, a tvmultipartmatching example.
;S##E##+##
;S##E##+##
:Multiple episode numbers, separated by a + sign
:Multiple episode numbers, separated by a + sign
:{|
:{| class="prettytable" style="width:900px; background-color:#a1f5e4; text-align:left;"
|-
|
|
<syntaxhighlight lang="xml" enclose="div">
<syntaxhighlight lang=xml enclose="div">
  <tvmultipartmatching>^[-_EeXx+]+([0-9]+)</tvmultipartmatching>
  <tvmultipartmatching>^[-_EeXx+]+([0-9]+)</tvmultipartmatching>
</syntaxhighlight>
</syntaxhighlight>
Line 341: Line 628:
:In this case we can simply add the + sign to the default symbols, thus preserving the defaults as well.
:In this case we can simply add the + sign to the default symbols, thus preserving the defaults as well.


== Troubleshooting ==
=== The scraper picks the wrong TV show ===
The most common cause for this is that you haven't named the show's folder correctly. Check the site being scraped, and copy the title exactly as it is displayed, including anything in brackets.


If that doesn't solve the issue, or you are unable to change the folder name, you can force a match by adding a [[Import - Export Library#TV Shows 2|tvshow.nfo]] with the url of the show's page on the scraped site.
=== All files are added as a single TV show ===
This may happen if you've set content on the wrong folder, (usually the one above the one containing your TV shows). The telltale sign will be the title of the show everything is added as: "Al '''TV'''", "Genius '''Series'''", etc. The title will be derived from the name of your top-level TV folder.
<pre>
Videos                          <<Source folder, Content: TV Shows>>
    |----TV                      <<Scanned as "Al TV">>
    |    |----TV Show 1        <<Ignored>>
    |    |      |--Files
    |    |----TV Show 2        <<Ignored>>
    |    |      |--Files
</pre>
In these cases, you can either remove the source and re-add the TV shows folder as source, or change the content on the source to None, and then set the content on the correct folder (see examples [[#Complex|above]]).
=== Some files refuse to be added ===
The most obvious cause is that the files are not named correctly and don't match any of the patterns. In these cases you will need to rename the files, or add a custom tvshowmatching regexp to deal with them.


If the files appear to be correctly named, they may instead be matching the ''wrong pattern''. If you use custom tvshowmatching regexps, check carefully the order in which the regexps are being matched alongside the defaults. Also check the note in [[#Split-episode|split-episode]] above.
= advancedsettings.xml =
{{main|advancedsettings.xml}}
The following settings allow user customisation for TV Show and Episode matching.
 
* [[advancedsettings.xml#tvshowmatching|<tvshowmatching>]]
* [[advancedsettings.xml#tvmultipartmatching|<tvmultipartmatching>]]
* [[advancedsettings.xml#excludetvshowsfromscan|<excludetvshowsfromscan>]]
* [[advancedsettings.xml#cleanstrings|<cleanstrings>]]
* [[advancedsettings.xml#videoextensions|<videoextensions>]]
* [[advancedsettings.xml#discstubextensions|<discstubextensions>]]
 
 
 
= References =
<references />
 
 
 
{{top}}


Another possibility is that this is actually a case of the scraper picking the wrong TV show (the problem may be masked by the use of local artwork or lack of online artwork, although episode titles and plots should be a giveaway). In this situation even correctly named files will not get added if they lie outside the numbering of the incorrect show.
<div style="{{linear-gradient|left|#a1f5e4, #f5f5a1}}">{{next|[[Adding_video_sources|'''Add Source & Scrape''']]}} </div>
;Example
:The show [http://www.thetvdb.com/?tab=series&id=82607&lid=7 Castle] is a six episode documentary series about castles, not the [http://www.thetvdb.com/?tab=series&id=83462 multi-season 2009 crime drama]. Any file numbered s01e07 or higher will not be added if XBMC thinks the latter is the former.
<br />
A fourth cause can be that you've different season listings than the scraper you're using. E.g. your season one is S1E01-S1E20 while according to the scraper E17-20 belongs to season two. The scraper will then add E1-16 to season one, the rest won't get scraped.<br />
To fix this you can:
* Use a different scraper. The TV addon [[Add-on:XEM | XEM]] allows you to choose use between four different sources.
* [[NFO files#Create an .NFO file .28recommended.29|Create NFO files]] for the TV show.
* If you still want to add the TV show with the scraper that has different listings than you, check the scraper site and rename/move your files according to its listings.


[[Category:Video Library]]
{{updated|18}}
[[Category:XBMC Manual]]
[[Category:FAQ]]
{{frodo updated}}
[[Category:Index]]
[[Category:How-to]]
[[Category:Guides]]
[[Category:Manual]]
[[Category:Karellen]]
[[Category:Video library]]
[[Category:General topics]]
[[Category:First time user]]
[[Category:Quick Start Guide]]

Revision as of 02:17, 14 December 2019

Create Video Libraries
1. The Basics
2. Source Folder
3. Movie Setup
4a. TV Show Setup
4b. Seasons Setup
4c. Episodes Setup
5. Music Videos Setup
6. Add Source & Scrape
7. Scraping Problems
Home icon grey.png   ▶ Video library ▶ Naming video files ▶ TV shows


Introduction

Setting up TV Shows correctly is a little bit more involved than the Movies section. The first part of this page will describe the Kodi best practice to name TV Shows and Episode files and to create the folder structure to save them in. These methods are proven to be the simplest and most robust method which provides the most accurate scrape.


TV Show Folder

Video-TVShow Folder.png

Each TV Show requires its own folder. The TV Show folder name is used to match the show at the scraper site..

Kodi does not support the flat folder structure for TV Shows where all episodes from different TV Shows are in the same folder.

  • The TV Show folders are located inside the Source folder.
  • The folder name will be cleaned of commonly used strings, such as DVDRip, 1080p, x264, etc. before being passed to the scraper. If the year of release is included, this will be extracted and used by the scraper to assist in making a match.
  • Spaces, periods, or underscores may be used to separate words in the folder and file names, but should not be mixed. Note also the issue with Split-episodes regarding file names with periods.


Naming TV Shows follows the same guidelines as for Movies.

  • Name the TV Show folder the same way as shown on the TV Show page at the scraper site.
  • It is always best practice to include the year along with the title. This makes scraping more accurate and differentiates between original and remake versions.
  • This guideline also applies to Country of Origin TV Shows. For example Hells Kitchen (UK), Hells Kitchen (US), Hells Kitchen (AU), Hells Kitchen (IT) etc.
  • The title and (year) displayed at the scraper site is how you should name your show.


The best practice method is detailed in the image to the right. (season folders are optional)

  • Angel (1999)- TV Show folder containing Single File episodes
  • Battlestar Galactica (1978)- TV Show folder containing DVD folders for episodes
  • Battlestar Galactica (2004)- TV Show folder containing Bluray folders fore episodes


Split folders

Split folders are TV Shows that have episodes split between two or more folders located in different Sources. This may occur when a long running show is progressively saved on one drive but, over time, the drive has been filled with other content, forcing you to save new episodes on another drive.

To ensure these split TV Shows are correctly scraped as the same show, you must ensure that the TV Show folder names are identical. A slight variance could see a different show scraped for the second folder. If using NFO Files, then copy the NFO file from one location into the other split folders.


Season Folder

Season folders are optional. They are useful to reduce clutter in the main TV Show folder.

Even though Kodi can accommodate the Season folder, it will ignore them. Instead it looks for the correctly numbered episode files.

As a side note, once your TV Shows have been scanned into the Library, it is possible to rename the Season folder displayed by Kodi. See: Season Rename


When scraping be aware that season numbers may not be basic numbers. Many shows use the Year as the season number. This is quite common with older shows, daytime soaps and talk shows. Always check the site


Episode Files

Check the site of the information provider to confirm your files are in the same order and that the episodes exist at the scraper site. If not, images and metadata will not match your episode files or your scrape will fail if the episodes do not exist.

  • The episode files (or folders if using DVD or Bluray folders) are located inside the TV Show folder or inside Season folders if using them.
  • The file name (or folder name) will be cleaned of commonly used strings, such as DVDRip, 1080p, x264, etc. before being passed to the scraper.
  • Spaces, periods, or underscores may be used to separate words in the folder and file names, but should not be mixed. Note also the issue with Split-episodes regarding file names with periods.

All episode files must be named and numbered correctly for the scanner to match the correct episode to the <episodeguide> URL of the TV Show downloaded from the scraper site. You cannot nominate season and episode numbering through NFO Files.

The following is the simplest and most accurate way to name your episode files:

Angel (1999) S01E01.mkv
Where: Angel (1999) = TV Show name
S01E01 = Season 1, Episode 1


For information on alternate or advanced episode naming conventions, see the Advanced Setup section further down this page.

For information on alternate episode orders, see the Episode Groups section further down this page.


Specials Episodes

All Special Episodes use Season 00

Doctor Who (2005) S00E50

They are listed at TheMovieDB in the Specials section of the Season listing.

Special Episdes are episodes that do not fit into the normal storyline of the TV Show. They may include items such as Christmas Specials, Season recap episodes, Made for TV Movies that extend the storyline, Unaired Pilots etc

Special Episodes can be displayed in amongst the regular episodes through the use of NFO Files. this is specified using the <displayepisode></displayepisode> and <displayseason></displayseason> tags.


Episode Groups

Episode Groups or Orders are listings with alternate episode orders. Some TV Shows are broadcast in one order but the DVD/Bluray release may have a different screening order. A well known example is the TV Show Firefly where the Studio opted to broadcast high action episodes for ratings first, while the Producer wanted a different order to correctly unfold the storyline.


TheMovieDB-TV Shows

TheMovieDB uses Episode Groups for additional episode orders.

  • Numerous Groups can be added which should cater to the different releases between countries
  • Creating Groups and adding episodes is quite simplistic, using drag and drop which should encourage contributors to complete the entries
  • Where available, the listings are easily accessible for viewing as shown in the images below

To use one of the orders for scraping, follow the images above and place the address in a Parsing NFO file then scrape. The Parsing NFO File will point the scraper to the listing. [1]


The TVDB

The TVDB allows for three listing orders as detailed below.

  • These are the only three orders available.
  • The current web site is flawed and does not allow the display of the different orders.


Aired Order
  • This is the default order set in the scraper settings.
  • TVDB lists all TV shows in the original Aired Order. The first time a show is ever broadcast, that is the listing shown. The site is not concerned with how it was broadcast the 2nd, 3rd or 15th time, or how it was broadcast in other countries, or during syndication. It only lists the order of the FIRST TIME ever broadcast, whether that be on Free To Air or Subscription Television.
  • Episodes are grouped and listed into Seasons and each episode is numbered sequentially from 1, which resets for each season.
DVD Order
  • In many cases, DVD's are released with a different episode listing, normally being the original order envisioned by the Director. To accommodate this, the site also has a DVD Order listing.
  • Episodes are grouped and listed into Seasons and each episode is numbered sequentially from 1, which resets for each season.
  • There are many TV Shows on the TVDB site that do not have the DVD Order data entered. The scraper will default back to Aired Order if there is no DVD Order information listed.
  • Note: As the data at TVDB is created by the open community, it is not uncommon for errors to occur with DVD Order details. As it is seen as secondary information, the errors can go unnoticed. One major error that affects the scrapers is incomplete DVD Order details. For example, some episodes have no DVD Order data, while other episodes in the same season do have the data.
  • Early May 2018, TVDB upgraded their website to v2.0. Unfortunately a glitch has prevented the display of DVD Order and Absolute Order information. It is unknown when it will be rectified.
Absolute Order
  • This order ignores Seasons and gives each episode an incremental number starting at 1.
  • This order is used for Anime type shows.


The Order you use can be set in the settings page for the TVDB Scraper.



The remainder of this page deals with Special Use cases and can be safely ignored. Most libraries will not require implementing the following additional name extensions.


Next step: Add Source & Scrape


Advanced Setup

The previous section details the simplest method to set up your TV Show library. It is considered the best practice method.

The sections from here onwards are alternate or advanced methods. With added complexity comes higher maintenance and more potential problems and scraping errors.


TV Show folder

These other methods are available but NOT recommended. The sub-folders are easily mistaken and scraped as false TV shows. While it is possible to find and fix the ghost entries, the extra time and work involved will override any possible benefits. If you need to re-build your library at a later stage, the problems will need to be solved again.

In more complex situations where your top-level directory is further sub-divided before the show folders, you can add the top-level as source but not set the content, and then set the content to TV shows on each sub-folder.

Example
TV Shows                  <<Source folder, Content: None>>
   |----A-M               <<Content: TV shows>>
   |      |----TV Show 1
   |              |--Files
   |----N-Z               <<Content: TV shows>>
   |      |----TV Show 2
   |              |--Files


It is also possible to have a sub-folder group multiple shows together in an otherwise normal directory structure. Just change the content on the sub-folder and de-select the "Selected folder contains a single TV show" setting.

Example
TV Shows                  <<Source folder, Content: TV shows>>
   |----TV Show 1
   |       |----Season #
   |            |--Files
   |----Star Trek Series  <<Content:TV shows>>
   |       |----Star Trek
   |       |       |--Files
   |       |----Star Trek The Next Generation
   |               |--Files

In these cases, it's best to refrain from scanning the files into the library until the content is set correctly for all folders, to avoid incorrect results and the need to rescan.


Seasons

Nil availble options. Season folders are ignored by Kodi which means you can name them as you please.


Single Episodes

Episode files are assumed to contain a single episode. If you have files that contain two or more episodes, then read the Multi-Episodes section below.

The structure of the episode name is as follows:

name <<pattern>>.ext
where:
  • name is the title of the show and is optional. It could just as easily be after the pattern, or excluded entirely.
  • <<pattern>> is one of the expressions in the following tables. S = Season number; E = Episode number
  • .ext is a recognized video file extension, (mkv, avi, ts, mp4, etc) or ommitted entirely if using DVD or Bluray folders.

Kodi uses a series of regular expressions to determine the season and episode numbers from the file name. These are checked in a pre-determined order with the first match being the one used and everything else in the file name is ignored. NFO Files are never checked for season and episode numbers.

There are 8 default patterns, plus a separate multi-episode pattern. Using any other numbering convention outside of the ones provided in the list below will require you to edit your advancedsettings.xml and insert your custom RegEx.

Spaces, periods, or underscores may be used to separate words in the folder and file names, but shouldn't be mixed in the same name. The regex is not case-sensitive and either uppercase or lowercase may be used. The examples on this page use uppercase.


The following table lists:

  • The pattern that Kodi will search for.
  • The order of the search. ie. Patterns numbered 1 will be matched first and those numbered 7 will be matched last.
With Season
The most common usage and used for nearly all TV Shows.
No Season
In cases where you only have one season (or are using absolute order in the TVDB scraper), you may want to forego the inclusion of the season number.
By date
Common for long-running daily shows, allows the use of aired date of the episode.
With Season No Season By Date
Order Episode Naming Order Episode Naming Order Episode Naming
1 Name S01E02.ext 2 Name ep02.ext 3 Name yyyy.mm.dd.ext
1 Name S1E2.ext 2 Name ep_02.ext 3 Name yyyy-mm-dd.ext
1 Name S01.E02.ext 7 Name part.II.ext 4 Name dd.mm.yyyy.ext
1 Name S01_E02.ext 7 Name pt.II.ext
1 Name S01xE02.ext 7 Name pt_II.ext
5 Name 1x02.ext
6 Name 102.ext


Multi-Episodes

In cases where the file contains more than one episode, it is possible to specify all the episodes included in that file. Everything after the first found pattern match will be checked for further matches to the same pattern.

  • When using a single video file for multiple episodes it is possible to tell Kodi when each episode starts using Episode Bookmarks
  • Two versions are shown- Long version and Short version. Only the episodes in the file name will be added, e.g. name.s01e01-03.ext will not include episode 2.
  • The patterns are the same for Single Episode numbering, but extended to include multiple episodes.
See also: multi-episode pattern
Complex Pattern Short Pattern
Order Example Name Order Example Name
1 name s01e01-s01e02.ext 1 name s01e01e02.ext
1 name s01e01-episode1.title-s01e02-episode2.title.ext 1 name s01e01-02-03.ext
1 name s01e01-s01e02-s01e03.ext 5 name 1x01x02.ext
5 name 1x01-1x02.ext 2 name ep01-02.ext
2 name ep01-ep02.ext


Split Episodes

Note: The November 2019 upgrade of the TVDB site has removed the E01.1, E01.2 type numbering of episodes. The following section no longer applies and will be removed from this page completely in due course

This section applies to the TVDB site. It does not apply if you are using TheMovieDB-TV Shows scraper.
It does not apply in all cases as the listings rely on community members applying the correct numbering which is not always the case. Check the listing first.

Split-episodes are feature length episodes that were broadcast as two separate episodes. The Pilot episode can be a feature length episode for many TV Shows. These are re-combined on DVD releases as the original single episode. They are numbered by decimal sub parts eg S01E01.1, S01E01.2, S01E02 This is a common cause for failed scrapes of certain episodes. The entry must be checked at TVDB to ensure correct numbering has been applied. It is also typical for childrens cartoons, files which only contain a distinct part of an episode may be named as to which part, if the scraper supports it.

Up to 9 sub-parts are allowed (using either .1-.9 or a-i). These can also be combined with the multi-episode pattern, if your file contains all parts joined as a single episode.

Using the patterns from the Single Episodes section, they have been extended to include Split episodes. The Order has been ommitted.

Single Episodes Multi Part Episodes
Order Example Name Order Example Name
name s01e01.1.ext name s01e01.1.s01e01.2.ext
name s01e01a.ext name 1x01.1-x01.2.ext
name 1x01.1.ext name ep01a-01b.ext
name 1x01a.ext
name ep01.1.ext
name 101.1.ext

Each part will be added to the library just with its full episode number, the sub-part will not be displayed.

Note: If you use periods in your file names and include material after the episode number (such as the episode title), you may get a false match to a split-episode pattern if that material begins with a number below 10. This will likely lead to the episode not being added to the library. The recommendation is to use a space or underscore instead to separate the numbers for those files, e.g.


Stub and Stream Files

  • If you have a collection of DVD's and Bluray disks but do not want to rip them to a hard drive, then a Media Stub File allows you to add the collection of disks to the Kodi Video Library.
  • It is a simple text based file that is added to your Source in exactly the same way as any other Movie or TV Show, which is then scanned or scraped into the library.


Various internet video and audio streams can be played back in Kodi as if they were locally stored on your media center by using STRM files. As long as the format and streaming-method (network-protocol) is supported by Kodi, stream can be added. These are basic text files that look like <name>.strm and contain a URL to the internet stream. STRM files can also be added to the video library and can have cover art, summaries, etc.

Some internet sites may have an add-on available that can also access these media streams, rather than having to manually create STRM files. See Add-ons for more information on how to find and install add-ons.


Media Tags / Flags

480.png 1080.png 720.png 1080 n.png 480-1.png Divx.png Xvid.png H264.png Bluray.png Dvd.png Avc1.png 1.33.png 1.66.png 2.20.png 2.35.png


Media flags are icons in Kodi that displays the meta-information from the media file of a movie, TV show or music title. They are skin specific, and what works in one skin, may not work in another skin. It is always best to check with the skin sub-forum which flags and tags are used.

It is important to note that the skin will display these flags even when these extensions are not used. The only difference being that without the extensions, the movie must be played first in order for Kodi to read the audio and video codec data.

The actual audio and video codec data will override any extension used. This means that if you set the extension of, say, .ATMOS but the video file only has a stereo track, then the .ATMOS flag will be removed.


Example- note that movie folders are used, and the folder is simply named while the filename has been modified with extensions.

...\Paul (2011)\Paul (2011).4K.HDR.Atmos.mkv


3D Episodes

Some 3D episodes might need an additional file name extension to be identified by Kodi as 3D. See 3D for details on that additional extension, and when it is needed.


Custom Filenames

It's possible to use custom file names that don't match any of the default patterns by editing your advancedsettings.xml file to include a tvshowmatching tag containing regular expressions.

A tvshowmatching regexp needs up to three capturing groups:

1 capturing group = episode number (season will default to season 1), no multi-episode matches will be attempted
2 capturing groups = season number + episode number (in that order), no multi-episode matches will be attempted
3 capturing groups = season number + episode number + multi-episode matching part (typically just the remainder of the file name)

(A capturing group is essentially a part of the regexp contained inside brackets.)

To have no season but multi-episode matching, use three groups but leave the first empty.

Date-based regexps are also possible, and are marked by a bydate="true" attribute in the regexp. These also use three capturing groups, either as year-month-day or day-month-year, the lengths must be exactly 4-2-2 or 2-2-4.

Your custom tvshowmatching regexps can be either checked for before the default set using action="prepend", or after using action="append". Not including an action will result in only your regexps being tested. Care should be taken to ensure that the right regexp matches your file names, particularly in regard to the three digit "102" pattern seen above. The regexps should be grouped together inside a single tvshowmatching tag, although you can use two if you wish to prepend and append different regexps.

You can also change the multi-episode matching regexp by including a tvmultipartmatching tag in your advancedsettings.xml (separate from the tvshowmatching tag). There can be only one tvmultipartmatching expression, whatever you use will overwrite the default, so take care to only expand on the default pattern unless you are certain. The tvmultipartmatching requires one capturing group for the episode number.

For simplicity, the split-episode pattern has been excluded from the examples below. To allow for split-episodes, replace the [0-9]+ in the episode capturing group with [0-9]+(?:(?:[a-i]|\.[1-9])(?![0-9]))?


Examples

A fairly straightforward example to begin.

Season ## - Episode ##
"Season [season#] - Episode [episode#]" anywhere in the file name
 <tvshowmatching action="prepend">
     <regexp>Season ([0-9]+) - Episode ([0-9]+)([^\\/]*)$</regexp>
 </tvshowmatching>
Example : TV Shows\Scrubs\Season 1\Scrubs - Season 1 - Episode 01 - Pilot.avi
The first two capturing groups should be obvious, the third group ([^\\/]*) captures everything up to the end of the file name $, this allows for multi-part file names such as name.Season 1 - Episode 01 - Season 1 - Episode 02.ext as well as the simpler name.Season 1 - Episode 01-02.ext



The entire file path is passed to the regexps, so care should be taken to ensure the matches can't occur earlier in the path, but this does mean for example, you can capture the season number from a sub-folder name.

\Season #\##
Season [season#] at the end of the directory name, file name starts with [episode#]
 <tvshowmatching action="prepend">
     <regexp>Season[\._ ]([0-9]+)[\\/]([0-9]+)([^\\/]*)$</regexp>
 </tvshowmatching>
Example : \Battlestar Galactica (2003)\Season 3\01 - Occupation.avi (Season 3, Episode 1)
Again we use three groups here to allow for multi-episode, but in this case (obviously) only the shorter multi-episode pattern can occur, e.g. Season 1\01x02 - Episode title.ext.



For numbering without a season, you should ensure that only the episode number gets matched against and not another number in the title or episode title, or a number as part of a different pattern.

- ## -
" - [episode#] - " anywhere in the file name
 <tvshowmatching action="prepend">
     <regexp> - ()([0-9]+)((?:-[0-9]+)*) - [^\\/]*$</regexp>
 </tvshowmatching>
Example : \One Piece\One Piece - 099 - Spirit of the Fakes! Heart of the Rebel Army, Kamyu!.avi ("Season 1", Episode 99) (Using Absolute order)
Here, the first capturing group is left empty, and there is a distinct pattern before and after the episode number to ensure only it gets matched. Also instead of capturing the remainder of the file name for multi-part matching, we only capturing a single repeating pattern so only a - 01-02-03 - format will work.



It's also possible to specify a different default season for without-season regexps.

\Specials\##
Directory name is Specials, file name starts with [episode#]
 <tvshowmatching action="prepend">
     <regexp defaultseason="0">Specials[\\/]()([0-9]+)([^\\/]*)$</regexp>
 </tvshowmatching>
Example : \Firefly\Specials\04 - Browncoats Unite.mkv (Season 0, Episode 4)
A combination of the previous two examples, allowing special episodes to reside in a "Specials" folder rather than a "Season 0" folder.



The default date-based regexps only allow for periods or hyphens as delimiters...

####_##_##
[year]_[month]_[day] anywhere in the file name
 <tvshowmatching action="prepend">
     <regexp bydate="true">([0-9]{4})_([0-9]{2})_([0-9]{2})[^\\/]*$</regexp>
 </tvshowmatching>
Example: : \The Colbert Report\2005_10_17.avi
The exact number of digits is specified for each group to ensure compliance. A separate [month]_[day]_[year] regexp would be needed if both formats are in use.



The default regexps don't allow for DVD folder structures, this can usually be remedied by replacing the final $ with (?:(?:[\\/]video_ts)?[\\/]video_ts\.ifo)$

S##E##\VIDEO_TS\VIDEO_TS.IFO
 <tvshowmatching action="append">
     <regexp>[Ss]([0-9]+)[ ._-]*[Ee]([0-9]+)([^\\/]*)(?:(?:[\\/]VIDEO_TS)?[\\/]VIDEO_TS\.IFO)$</regexp>
 </tvshowmatching>
Example: \Battlestar Galactica (2003)\The Mini-Series S00E01E02\VIDEO_TS\VIDEO_TS.IFO
The VIDEO_TS folder is optional, e.g. S01E01\VIDEO_TS.IFO will also work.



Similarly for Bluray folder structures, you can replace the final $ with (?:(?:[\\/]bdmv)?[\\/]index\.bdmv)$

#x##\BDMV\index.bdmv
 <tvshowmatching action="append">
     <regexp>[\\/\._ \[\(-]([0-9]+)x([0-9]+)([^\\/]*)(?:(?:[\\/]bdmv)?[\\/]index\.bdmv)$</regexp>
 </tvshowmatching>
With Bluray folders, you'll also run into trouble with the various mpls and m2ts files incorrectly matching other patterns, so you should also exclude all the other folders and files from being scanned:
  <video>
    <excludetvshowsfromscan action="append">
      <regexp>[\\/](auxdata|backup|clipinf|playlist|stream|certificate)[\\/]</regexp>
      <regexp>movieobject\.bdmv</regexp>
    </excludetvshowsfromscan>
  </video>



Finally, a tvmultipartmatching example.

S##E##+##
Multiple episode numbers, separated by a + sign
 <tvmultipartmatching>^[-_EeXx+]+([0-9]+)</tvmultipartmatching>
Example: : \Lost\Lost.S01E23+24.Exodus.mkv
In this case we can simply add the + sign to the default symbols, thus preserving the defaults as well.


advancedsettings.xml

The following settings allow user customisation for TV Show and Episode matching.


References


Return to top


Next step: Add Source & Scrape