File_Naming

Under kmttg configuration File Settings tab there is a File Naming setting that defines how kmttg will create file names for downloaded shows. There is quite an extensive set of keywords you can use to define the file naming convention to suit your needs. This Wiki provides details and examples.

File Naming

• This defines how file names will look for downloaded shows. Certain keywords are provided which you specify within square brackets that will be substituted accordingly. The choices for those you can see in the Available keywords cyclic. Choosing an entry from Available keywords will insert it in the File Naming field. You can use almost any other characters you want (avoid quotes!) and arrange the keywords in any order you like.

• EXAMPLE: Let’s say you have a recorded show as follows:

  Mon 3/24/2008 at 8:00pm called “The Big Bang Theory – The Loobenfeld Decay” on 702=KCBSDT, Duration=30 mins, EpisodeNumber=302, originalAirDate=2007-11-20

Keywords in this example are:

[title] = The Big Bang Theory – The Loobenfeld Decay
[mainTitle] = The Big Bang Theory
[episodeTitle] = The Loobenfeld Decay
[channelNum] = 702
[channel] = KCBSDT
[min] = 00
[hour] = 20
[wday] = Mon
[mday] = 24
[month] = Mar
[monthNum] = 03
[year] = 2008
[originalAirDate] = 2007-11-20
[oad_no_dashes] = 20071120
[season] = 03
[episode] = 02
[EpisodeNumber] = 302
[SeriesEpNumber] = s03e02
[startTime] = 2008-03-24-2000

So continuing with above example, if I set:

File Naming = [title] (Recorded [month] [mday],[year],[channel])

The .TiVo file name would become:

The Big Bang Theory – The Loobenfeld Decay (Recorded Mar 17,2008,KABCDT).TiVo

The [/] keyword is a folder separator which allows you to create custom sub-folder names as part of the output file definition. Continuing above example:

File Naming = [mainTitle][/][year]_[monthNum]_[mday] [episodeTitle]

The .TiVo file name would become (using Windows folder structure note the resulting sub-folder structure)

The Big Bang Theory\2008_03_24 The Loobenfeld Decay.TiVo

• [originalAirDate]
  • For titles for which kmttg does not have originalAirDate, kmttg will use [year]-[monthNum]-[mday] construct instead.
• [startTime]
  • This is available only from extended metadata information and represents the actual start time of a recording. So, for example for partial recordings it will reflect the actual start time of the recording instead of the scheduled start time for that show.
    • The syntax used for startTime is yyyy-MM-dd_HHmm
    • So for example for a recording starting 10:21 am it would become something like: 2013-02-17-1021

NOTE: If you are not careful with file naming and don't include keywords that are always present for every show it is possible you end up with an empty file. So for example if you only use episodeTitle keyword then shows that don't have episode titles will result in an empty string. Starting with version 0p7c kmttg will now issue an error and not process files that end up as an empty string with just a file extension. In previous releases kmttg would continue anyway.

NOTE: There are several special characters that are not allowed by kmttg for various reasons to be part of file names. The following set of characters are discarded from file names (note some of these starting only in release v0p7h):

    * " ' : ; ! ? \ $ [ ] \` ^

In addition the following characters are mapped as indicated:

/ < > | map to _
& maps to and

Advanced File Naming

By request some more advanced keyword processing was introduced to allow for conditional text.
* You can define multiple space separated fields within square brackets.
* Fields surrounded by quotes are treated as literal text.
* A single field with no quotes should be supplied which represents a conditional keyword
* If that keyword is available for the show in question then the keyword value along with any literal text surrounding it will be included in file name.
* If the keyword evaluates to null then the entire advanced keyword becomes null.
* For example:

[mainTitle]["_Ep#" EpisodeNumber]_[wday]_[month]_[mday]

The advanced keyword is highlighted in bold and signifies only include “_Ep#xxx” if EpisodeNumber exists for the show in question. “_Ep#” is literal string to which the evaluated contents of EpisodeNumber keyword are appended. If EpisodeNumber does not exist then the whole advanced keyword evaluates to empty string.

As another example, I have my File Naming set to the following so as to contain season and episode information in the name for episodic shows and movie year in the name for movies:

[mainTitle] [" (" movieYear ")] [" (" SeriesEpNumber ") "][" - " episodeTitle]

Which using above show would become in this case:

    The Big Bang Theory (s03e02) - The Loobenfeld Decay

FILE NAME TEMPLATE FOR PLEX

[mainTitle][/][SeriesEpNumber] - [episodeTitle]