TVDB Renamer

This program queries TheTVDB.com for information about an episode of a TV show, in order to rename a given file to include the season and episode number information in the file (ie, S01E01). This is particularly useful for software such as XBMC or Boxee which in turn use thetvdb to look up metadata such as fan art, synopses, etc. based on that season/episode information, if properly encoded into the filename.

Assuming you have Java 6 installed, run "java -jar tvdb-renamer-with-deps.jar <filename>"

    USAGE: TVFileRenamer fileToRename [baseTVShowsDirectory]
  
    This program will use theTVDB.com to parse a file of name "Series Name - Episode Name (Date)*"
    to "Series Name.SnnEmm.Episode Name (Date)*"

    Where nn = season number and mm = episode number

    If baseTVShowsDirectory is specified, it will place the file in the "baseTVShowsDirectory/Series Name" directory
  

Currently, the program expects a specific file naming scheme. Files should be named "Series Name - Episode Name (Anything Else)". If the file given to tvdb renamer is not in that format, it won't process it. If it does find the relevant match in TheTVDB, it will rename the file to "Series Name.SnnEmm.Episode Title.(Anything Else)".

In addition, if you supply the optional [baseTVShowsDirectory] argument, TVDB Renamer will place the renamed file in the "baseTVShowsDirectory/Series Name" directory. If the "Series Name" subdirectory doesn't exist, it will be created.

Examples

Assume you have a file in your incoming c:\Tivo directory that you want renamed to include season/episode information:

      > java -jar tvdb-renamer-with-deps.jar "c:\Tivo\Chuck - Chuck Versus the Anniversary (09_20_2010).mpeg"
      
      Renamed c:\Tivo\Chuck - Chuck Versus the Anniversary (09_20_2010).mpeg to c:\Tivo\Chuck.S04E01.Chuck Versus the Anniversary.(09_20_2010).mpeg
    

Now let's assume you want to put the file into a "Chuck" directory under c:\TVShows:

      > java -jar tvdb-renamer-with-deps.jar "c:\Tivo\Chuck - Chuck Versus the Anniversary (09_20_2010).mpeg" c:\TVShows
      
      Renamed c:\Tivo\Chuck - Chuck Versus the Anniversary (09_20_2010).mpeg to c:\TVShows\Chuck\Chuck.S04E01.Chuck Versus the Anniversary.(09_20_2010).mpeg
    

If there is no match in TheTVDB for the Series or Episode, then the file will remain unchanged.

Usage with KMTTG

I wrote TVDB Renamer to I could use it as a custom job within the excellent kmttg application so that downloaded TiVo files would be sorted and named appropriately.

The first thing to do is make sure that kmttg is naming your downloaded files according to TVDB Renamer's expected filename pattern. In kmttg's config -> File Settings, under File Naming, I use

    [title] ([monthNum]_[mday]_[year])
    

Note that you can use whatever you want within the ()'s but currently you do need some parenthesis for the match to work.

I wrote a small Windows command file to wrap the invocation of TVDB Renamer and called it tvdb.cmd and put it in my /bin directory:

      @echo off
      java -jar [path_to_tvdb-renamer_jar]/tvdb-renamer-with-deps.jar %*
    

Next step is to configure the custom job in kmttg. In the kmttg configuration dialog, under the "Programs" tab, I have added the following as a custom command: c:\bin\tvdb.cmd [mpegFile] g:\tvshows

Custom Mappings

For various reasons, sometimes the name of the series you download doesn't match the name in theTVDB.

For example, "Law & Order: Special Victims Unit", as it is known in theTVDB, cannot be written as a filename in Unix because of the & and the : and in Windows because of the :. So your file will probably be something more like "Law and Order Special Victims Unit."

To work around this, you can specify a custom mapping file to TVDB Renamer. You can tell it either which "real" Series Name to use, or which TVDB series IDs to use. So you could do:

    Law and Order Special Victims Unit=Law & Order: Special Victims Unit
    

or

    Law and Order Special Victims Unit=75692
    

The only character you can't specify in a series title is "=", which is what divides the two values in a mapping file. Leading and Trailing whitespace is ignored.

To supply the file to TVDB Renamer, use a Java system property called "map". So to modify the Windows command file example above, I might create a mapping file at c:\mappings.txt (any file name will do) and modify my script as follows:

      @echo off
      java -Dmap=c:/mappings.txt -jar [path_to_tvdb-renamer_jar]/tvdb-renamer-with-deps.jar %*
    

Multiple Series Matches

The biggest assumption TVDB Renamer makes is that you are interested in the most recent series for which there is a series name match. In the above example, when we search TheTVDB for a series with the name "Chuck", we get back many hits: Chuck, Chuck Finn, Chuck Woolery: Naturally Stoned, Laurel & Hardy & Chuck!, etc. So TVDB Renamer makes the assumption that you are interested in the series with the most recent "First Aired" date, so it chooses plain old "Chuck".

If it cannot find an episode name match against the series "Chuck", TVDB Renamer will then look to the next most recent series, and keep trying. Series with no listed "First Aired" date are checked last.

Multiple Episode Matches

I personally haven't run into this issue yet, but if a series were to have two episodes with the same name, TVDB Renamer will choose the latest aired episode.

Original File Naming

Obviously, currently, the required file naming scheme is very specific and limited. In the future, it could be extended to allow for more flexible filename parsing. The requirement for use of parentheses at the end of the file is simply in place because TVDB Renamer needs to know where the end of the episode name ends and any other metadata begins.

Destination File Naming

The format for the renamed file is also hard-coded and could benefit from some configuration to drive its format.