Download subtitles for movies and TV shows with Hazel

In celebration of the release of the sixth season of Game of Thrones today, I'll share with you a script to automatically download subtitles using Hazel for Mac.


The script is written in Python and forked from this project using the OpenSubtitles API. This script doesn't download any illegal content and is shared in good will that the user won't use it for malicious purposes.

What's Hazel?

Hazel watches folders in your Mac and whenever a change occurs it runs the files through a set of rules, running actions on the matches. A very well-known use for Hazel is to run a paperless workflow, because it can catalog scanned files as they're dumped in a folder.

That's the common excuse, but Hazel is capable of so much more. Did you download an album from that band you love on BandCamp and want to add it to iTunes? Hazel can do that for you. Run backups after you change a presentation? Definitely. Clean up your desktop of older files? Yep. Organize your media library? 100% check.

For more on what Hazel can do, check Noodlesoft's Buzz page and consider to follow Andreas' video tutorial for € 9,98. A new version of Hazel is just around the corner and if you purchase it now the upgrade is free.

Configuring the rule

There's only one step you should need to configure and that's the subtitle languages, the script downloads a single subtitle and attempts to find the most suitable one based on uploader reputation, number of downloads and your language of preference.

We're using the ISO639 standard to assign languages and Open Subtitles has a list of supported codes, look up the second column in this text file.

Find the "Download subtitles" rule and edit it (double-click), look for the "Run shell script" action and click in "Edit Script" to open a popover with the code, then search for the following, should be on line 17 (you can paste in a code editor if you want):

language = {'en': 1, 'pb':2}

There you have a dictionary with 2 keys, one for English and the other for Brazilian Portuguese subtitles. To each key is assigned a value, higher the value, the more preferable is a subtitle in that language. So, for example, if you only want English subtitles to understand that Bane speaks in The Dark Knight Returns you could do:

language = {'en': 1}

If you speak several languages, such as Norwegian, Finnish, German and English, you can pile these together in the same dictionary:

language = {'en': 1, 'no': 3, 'fi': 4, 'de': 2}

In the previous example, the script would give preference to subtitles in Finnish, then Norwegian, German and finally English. Afterwards the script will sort the results by user rank (preferring subtitles from registered and credible users) and download counts.

You can insert your login credentials (in case you're VIP or something) but that's entirely optional, check line 32 and change it following this pattern:

resp = server.LogIn("login","password","en","MyApp") 

You can download the rule here, just double-click the file and it should prompt you to select a folder to throw it at. Make sure its checkbox is toggled on. You can also download the script on GitHub and build your own rules. For any inquiries, you can find me on Twitter