TVNamer is a Python application that will automatically renames TV episode files to a clean, consistent, and useful format. If you rip your DVDs, or download torrents (for shame!) on your server, you might find the “tvnamer” Python script very useful. I am running this on my Ubuntu 10.04 Lucid Lynx server right now, and I am very happy with it.

How It Works

I thought I would have to write a complex regular expressions script to reformat the junky file names I end up with. TVNamer does this behind the scenes, and goes one very useful step beyond that: it compares the file names you pass it to the TVDB database, via the TVDB API, to ensure you get a good match. The TVDB is an open database that stores the show titles, episode numbers, and so on, for nearly any show you can think of. As long as your file name contains the series title (in some format or another), and the season and episode numbers (S01E01, for example), TVNamer will rename them nicely.

Installation

TVNamer requires Python 2.6. If you don’t have it, install it as follows:

apt-get install python2.6

The tvnamer program is simple to install on Ubuntu (I run Ubuntu Server 10.04 Lucid Lynx) via Python’s “easy_install” command. (This probably works on all platforms that Python runs on, too.)

$ sudo easy_install tvnamer

Running Manually

You can run tvnamer on one file…

$ tvnamer seriesname.s01e01.crap.you.do.not.care.about.in.the.file.name.mkv

…or on an entire folder.

$ tvnamer ~/media/tv/

It can also recursively run on any folder tree that you pass to it. I have found this to be the default behavior, though, so the –recursive argument does not appear to be necessary. (I tend to use the argument in my cron jobs, in case future versions of tvnamer start to require it.)

$ tvnamer --recursive ~/media/tv/

Note that when you run the program as written above, it will run in interactive mode. For each file you pass to it, you will have to verify the series name and verify that you wish to rename the file.

Running Automatically on a Schedule

Fortunately, you can also run tvnamer in batch mode. Batch mode will not prompt the user at all, and will automatically select the most-relevant series title and will automatically rename each file. This is the mode to run tvnamer via a cron job or a shell script.

Batch mode:

$ tvnamer --batch ~/media/tv/

To schedule a cron job to run this script hourly, run:

$ crontab -e

and then add the following line to your crontab:

@hourly tvnamer --batch --recursive ~/media/tv/

and finally save the crontab file.