Obsessive metadata extraction & gathering for TV shows
Switch branches/tags
Nothing to show
Pull request Compare This branch is even with ieure:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


What is OCDTV?

Imagine that you’ve downloaded a number of episodes of your favorite TV show. You’d like to watch these shows on your iDevice, but you can’t because they’re in the wrong format: XviD/AVI or x264/MKV. Perhaps you’d also like to use iTunes’ newest/oldest unwatched options when you sync these episodes to your device, so you have episodes you haven’t seen yet. You can’t, since this requires metadata: the show name, season and episode number.

OCDTV fixes all this. One command will locate video files, determine their metadata, transcode them (if necessary), and import them into iTunes for your viewing pleasure.


I’m crazy about metadata. I like my stuff to be organized, particularly when it’s digital. I could have sucked it up and fixed up metadata by hand for the nth time, or I could have spent even more time making sure I never had to do that again. I chose the latter.

Installing OCDTV

$ sudo setup.py install

Or, if you’re as OCD about your workstation as your metadata:

$ virtualenv –no-site-packages . $ python setup.py develop


$ ocdtv ~/Downloads/TV

If no path is given, it defaults to the directory you’re running OCDTV from.


To transcode, you need a copy of the HandBrake CLI. You can put it anywhere you want, but OCDTV looks in /Applications by default.

OCDTV only transcodes to a HandBrake preset, so make sure you have a suitable one configured. The AppleTV preset is a good choice which works on most modern Apple devices (iPhone, iPad, Apple TV, etc).

Limitations & known issues

May fails to recognize some filenames

While OCDTV can cope with most sensibly-named files, there’s a lot of crap out there, and are likely to be some cases where it fails to extract the correct information from files.

Feel free to contribute test cases which at least document the shortcomings. If you aren’t comfortable enough with Python, to do this, just open an issue on GitHub.

Does not handle dated shows

Certain shows (The Daily Show etc) don’t have the usual SEASONxEP structure, but are purely date-based. OCDTV does not handle these at all.

Does not handle movies

It would be awesome if OCDTV also coped with films, but it currently doesn’t.

Does not detect dupes in iTunes

If the show is already in iTunes, OCDTV does not yet notice that and skip adding it.

Copes poorly with different defaults

If you invoke OCDTV thusly:

$ ocdtv -p AppleTV ~/Downloads/stuff

Then again with:

$ ocdtv -p iPad ~/Downloads/stuff

OCDTV will add the AppleTV transcoded files again, rather then transcoding with the new preset and adding those.