Download!
http://github.com/dbr/tvdb_api/tarball/master - Always the latest version as .tar)
So what is it?
I'm going to go out my way and assume you have downloaded a TV episode at some point. I'm sure you will have noticed the filenames are rather horrible.
I understand why the files are named along the lines of show.name.s01e02.dsr.xvid-grp.avi - it describes the showname, what episode, what source it came from, the format, and group that captured/released it... All very efficient, but they are hardly very nice to look at..
I initially manually renamed the downloads, going to Wikipedia or TV.com to get episode names. This got tedious very quickly, and was very error prone.
Then, one day I discovered http://www.thetvdb.com - "an open-directory of television shows for HTPC software". I emailed the creator of the site (Scott Zsori) who kindly sent back a Perl script that ran all .avi files in the current folder though, grabbed the episode name and renamed the file using this data.
I was using a modified version of this script until recently - it worked fine, but used an old version of the TVDB API, and had a many other flaws. Long story short, I rewrote it in Python.
Say you(r friend) has a file named "scrubs.s03e02.avi", you could manually rename it, go to tv.com, search for the correct show, find the right season, look for the name of episode two, copy the name and paste it into the filename.. Or simply run..
tvnamer -b scrubs.s03e02.avi
and it will rename the file to "Scrubs - [03x02] - My Journey.avi"
Oh, I keep TV episodes in the following format: "Show Name - [01x23] - Episode Name.avi"
and if no episode name can be found: "Show Name - [01x23]"
The output filename is easily changeable in the script (but it defaults to my preferred naming scheme, obviously)
The scripts
The script comprises of to parts:
tvdb_api.py - grabs data from thetvdb.com. You can get the name of season 2/episode 10 of scrubs by doing:
i = tvdb_api.tvdb(interactive=False) print i['Scrubs'][2][10]['name]
Then, the interesting part, tvnamer.py. It's a command-line tool which you pass one or more television show files, and it processes the file, giving you nicely named files.
How to use
The usage is quite simple:
tvnamer scrubs.s03e02.avi
Will then look for "some show" on TVDB, grab the name of season 1, episode 2 and rename the file as follows:
Scrubs - [03x02] - My Journey.avi
The script works on a wide range of filenames - as long as it has the showname, the season and episode numbers, it should work it out.
The output name is customizable in the script, should you have another naming scheme you prefer.
If you have multiple files, you can specify a directory:
tvnamer mydownloads/
or the current directory:
tvnamer .
It will prompt you to select the correct show (enter the corresponding number and hit enter), then it will ask you to confirm the new name. (y to accept, n no skip that file, a to rename the rest of the files, q to abort)
The way I tend to use it is to run "tvnamer .", select the correct show name, confirm the first few episodes are being named right, then hit "a" to magically name the rest of the files.
How to install
If you use Linux or OS X, the bare minimum you have to do is:
python ~/Downloads/dbr-tvdb_api-*/tvnamer.py tv.ep.s01e02.avi
On OS X/Linux, you can make it far nicer to use by marking the script as executable, and putting it somewhere in your PATH. Since the script needs BeautifulSoup and the tvdb_api.py modules, they must be in the Python module path, or the same directory.
cd ~/Downloads/dbr-tvdb_api-*/ mv tvnamer.py tvnamer chmod +x tvnamer sudo cp *.py tvnamer /usr/local/bin/
Now you can simply run "tvnamer ." in any folder and it'll start nice'ifying the names.
A better way to install the script, and keep it up-to-date would be to use git, checkout the Github project and sym-link the script to /usr/local/bin/tvnamer:
mkdir ~/code/ cd ~/code/ git clone git://github.com/dbr/tvdb_api.git cd tvdb_api chmod +x tvnamer.py sudo ln -s ~/code/tvdb_api/tvnamer.py /usr/local/bin/tvnamer
Sorry it's not entirely simple to install yet - when I am happier with the code I will improve the installation (probably to easy_install tvdb_api, at the very minimum "python setup.py install")
Example use
If you have no idea what I just wrote, and/or don't want to install it, but are still curious - here's what it does:
$ tvnamer My.Name.is.Earl.S03E20.HDTV.XviD-LOL.[VTV].avi Scrubs.S07E11.PDTV.XviD-LOL.avi #################### # Starting tvnamer # Processing 2 files # ..got tvdb mirrors # Starting to process files 1 -> My Name Is Earl (tvdb id: 75397) Enter choice (first number): 1 #################### Old name: My.Name.is.Earl.S03E20.HDTV.XviD-LOL.[VTV].avi New name: My Name is Earl - [03x20] - Girl Earl.avi Rename? (y/n/a/q) y ..renamed 1 -> Scrubs (tvdb id: 76156) Enter choice (first number): 1 #################### Old name: Scrubs.S07E11.PDTV.XviD-LOL.avi New name: Scrubs - [07x11] - My Princess.avi Rename? (y/n/a/q) y ..renamed
Advanced usage
There are a few command-line flags, which you can see by running python :tvnamer.py --help"
These will only be useful if something isn't working right, or you want to run the tvnamer from a script or similar.
--debug shows a bunch of debugging information, surprisingly. --interactive is the default behavior, whereby it asks the user to select the correct show name. --batch uses the first showname from the TVDB search. --always doesn't prompt before renaming files (but it will still ask you to confirm it has detected the correct show). --force will not check if renaming a file will overwrite another file (not recommended) --tests will run the unittests, useful to check everything is working, or if you want to write extra regexs to match unsupported filename formats.
It broke!
Leave a comment, or join the neverfear IRC channel and describe what the problem is, if it's a problem with the code, I'll be happy to fix it.
If you see something broken in the code, either let me know in the comments/IRC, or fork the project on Github ( http://github.com/dbr/tvdb_api ), make the fixes and send a pull request to me ( http://github.com/guides/pull-requests )
The future
The TVDB API is incredibly simple to use - to integrate it with anything written in Python would be trivial. I am considering writing a wx (GUI) application to name files, but to be honest, the command line interface is most useful for me.
I have another script, checkTvEps which verifies naming schemes are consistent - I plan to integrate tvnamer with this to fix bad filenames. With a small amount of scripting, it could: correctly name newly downloaded TV episodes, then put them in the correct directory (video/tv/$showname/season $season_number/)
I also plan to allow the API to grab more than just episode names - this is of low priority to me since I'm only using the API to name files currently. I do however plan to impliment show banners/episode thumbnail grabbing. So you could do download_url( t['Scrubs']['banner'] ) to get the series banner, or download_url( t['Scrubs'][2]['banner'] ) to get the season 2 banner (or box art).
Any suggestions
Download
or (if you have git installed)
git clone git://github.com/dbr/tvdb_api.git
