XBMC will be renamed to Kodi for v14. Read here for more details

Naming video files/TV shows

From Kodi
Jump to: navigation, search
The basic steps for adding
videos to the library:

1. Naming video files

Movies
TV shows
Music videos

2. Adding video sources
3. Set content and scan

Home icon grey.png   ▶ Video library ▶ Management ▶ Naming video files ▶ TV shows
Important: THIS IS THE MOST IMPORTANT STEP TO A SUCCESSFUL LIBRARY SCAN!


In order for the media scrapers to pick up the correct information your file names must follow a certain format:


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 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 shouldn't be mixed in the same folder name. Note also the caution below regarding file names with periods.

Note: Flat structures with files for different shows in a single directory are not supported.

Contents

1 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. Castle (2009) (in cases of duplicate titles), or the country of origin, e.g. 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.

1.1 Simple

Typically, you will add the top-level directory as a source and set the content to TV shows when you add it.

Example
TV Shows                  <<Source folder, Content: TV shows>>
   |----TV Show 1
   |       |----Season #
   |            |--Files
   |----TV Show 2 (year)
   |       |--Files
   |----TV Show 3
   |       |----2008
   |            |--Files

1.2 Complex

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'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.

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.

2 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 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 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.

2.1 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.

All the examples will be read as season 1, episode 2.

With season
The most common scenario.
anything_s01e02.ext (1)
anything_s1e2.ext (1)
anything_s01.e02.ext (1)
anything_s01_e02.ext (1)
anything_1x02.ext (5)
anything_102.ext (6)
Without 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.
anything_ep02.ext (2)
anything_ep_02.ext (2)
You may also use Roman numerals (I, IV, XI, etc.), often used for mini-series or short documentary series.
anything_part.II.ext (7)
anything_pt.II.ext (7)
anything_pt_II.ext (7)
By date
Common for long-running daily shows, you can also use the date the episode aired.
anything_1996.11.14.ext (3)
anything_1996-11-14.ext (3)
anything_14.11.1996.ext (4)

2.2 Multi-episode

Note: When you use a single video file for multiple episodes you can now tell XBMC when each episode starts using episode bookmarks.

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
anything.s01e01 1x02.ext (mixed patterns do not work)
anything.ep01.ep02.ext

The remainder will also be checked against a shorter form 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.

2.3 Split-episode

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.

Examples
anything.s01e01.1.s01e01.2.ext
anything.1x01.1x01.2.ext (note this is (1x01.1)x(01.2) not (1x01).(1x01.2))
anything.ep01a_01b.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, e.g.
Nikita.S01E02.2.0.mkv
24.1x02.1.00.am-2.00.am.avi
anything.1x01.1x02.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
24.1x02_1.00.am-2.00.am.avi
anything.1x01 1x02.ext (i.e. (1x01) (1x02) )

2.4 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, BlackAdder's Christmas Carol should have a file name that matches season 0 episode 3, e.g.:

BlackAdder.s00e03.BlackAdder's Christmas Carol.mkv

3 The TVDB scraper

The default TV show scraper uses 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.

Aired order
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.
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.

4 Advanced usage

4.1 Supplemental tools

A variety of supplemental tools exist to automatically rename files and folders into XBMC compatible formats.


4.2 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:

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

4.3 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 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 (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 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.

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 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.

Note: 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]))?

4.3.1 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 [day]_[month]_[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.

5 Troubleshooting


5.1 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 tvshow.nfo with the url of the show's page on the scraped site.

5.2 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.

Videos                           <<Source folder, Content: TV Shows>>
    |----TV                      <<Scanned as "Al TV">>
    |     |----TV Show 1         <<Ignored>>
    |     |       |--Files
    |     |----TV Show 2         <<Ignored>>
    |     |       |--Files

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 here).

5.3 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 the split-episode section.

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.

Example
The show Castle is a six episode documentary series about castles, not the multi-season 2009 crime drama. Any file numbered s01e07 or higher will not be added if XBMC thinks the latter is the former.


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.
To fix this you can:

  • Use a different scraper. The TV addon XEM allows you to choose use between four different sources.
  • 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.


Personal tools
Namespaces

Variants
Actions
Navigation
Wiki help
Toolbox