Hulusubs_dl is a command line tool to download subtitles from Hulu. Made for educational purposes. Since it's Python based, it can be easily deployed on every platform (Windows, macOS, Linux/Ubuntu etc.). You can find the installation instructions in #Installation Section of this readme.
NOTE:
This tool is based around and work with your hulu account's COOKIES. But, please do remember that you should NEVER share your account cookies with anyone and anywhere. Person having access to your cookies can use your account. Even when you're sharing any script failure, remember to not share/post your account cookies.
Since Hulu has now protected their content behind an "auth" wall, we can't access the website. In layman words, we need to log in to Hulu, in order to watch anything or to be able to get basic things to extract the subtitles.
When you run the tool first time, it asks for "cookie" value. You can see it in #How To Find Hulu Cookie
section of this readme.
Also, there's a "configuration file" that is automatically made by this tool. It has some basic settings that you can use as "default" values.
Some values saved in config file are:
You can specify these values in the file once and then tool will use these defaults. You can use "arguments" to override these anytime. You would need to pass the argument with the script (described later in this readme).
This script should run on both Python 2 and 3. Check travisCI builds for exact python versions.
Using this tool can be a little tricky for some people at first, but it's pretty much straightforward. Try to follow along.
Make sure you've gone through #Prerequisites
and have proper version downloaded and installed on your system from the #Installation section.
#How To Find Hulu Cookie
again.discover.hulu.com/content/v5/me/state
According to @IRLPinkiePie , when you copy cookies from firefox, it adds an "ellipse" in the cookie. Be watchful of that. More on that here : Firefox Cookie Issue
Refer to this screenshot for some clarification:
If you're stuck somewhere or need clarification, here's an in-depth video on how to install and use this tool (Windows & Mac). Video will be sharing in a week or so from now.
If you're on windows, it's recommended that you download and use "windows exe binary" to save your time. You can download the latest windows release from RELEASE SECTION Go there and download the ".exe" file. Then follow the usage instructions in Usage. After downloading this exe file, place it in some location that you can access. Because you would need to run this script every time you want to download subtitles. Don't put this in your "Windows" or "System" folders. It might cause conflicts with permissions.
Since I cannot generate a "binary" for these distributions, you will have to install and use python version directly.
It's pretty much straightforward, you can just use pip to install hulusubs_dl.
pip install hulusubs_dl
If for some reason, you're unable to use pip
, try with easy_install
.
If everything fails, you can download code from this repository and then run.
But, now you'll need to install the dependencies yourself. After downloading, navigate to this folder in your terminal and you can see a "requirements.txt" file.
You can install all dependencies via pip install -r requirements.txt
All the external dependencies required by this tool are mentioned in that file. You can install them one by one.
Since you're doing things manually, you might need to give this file executable rights, which can be done like this:
chmod +x __main__.py
If you're on macOS, it's recommended that you download and use "macOS binary" to save your time. You can download the latest macOS release from RELEASE SECTION Go there and download the "hulusubs_dl" file. Do verify that you're not downloading "hulusubs_dl.exe". Then follow the usage instructions in Usage. After downloading this file, place it in some location that you can access. Because you would need to run this script every time you want to download subtitles. Don't put this in restricted places like "/bin/ or "System" folders. It might cause conflicts with permissions.
Currently, the script supports these arguments :
-h, --help Prints the basic help menu of the script and exits.
-url,--hulu-url Url of the Hulu video or series to download subtitles from.
--version Prints the VERSION and exits.
-v,--verbose Enables Verbose logging.
-dd,--download-directory Specifies custom download location for the subtitles.
-cookie, --set-cookie Saves/Updates Hulu Cookie
-ext, --subtitle-extension Specifies the format of final subtitle file. Default is SRT.
-lang, --subtitle-language Specifies the language of the subtitle to download (subtitle in that language should be available on Hulu).
-skip-conf, --skip-config Skips reading the config file (default values). Could be handy if you're writing batch scipts.
-proxy, --proxy If you have an http/https proxy, you can provide it here. Tool will use this proxy to make all connections to Hulu.
-config, --make-config Creates/Resets config file & exits(overwrites current default values).
Some arguments support some specific range of values. You can see them below here. Values are separated via ';'.
-lang, --subtitle-language : en (default);es
-ext, --subtitle-extension: srt (default);ttml;vtt;smi
If you're not in US region and don't want to set up a system wide VPN, then you can provide any http/https proxy and hulusubs_dl would use this proxy to make all connections to Hulu.
Using proxy is simple, you can provide it like this
python __main__.py -proxy 123.456.789.0123:4444
If you're on windows, you won't be using __main__.py
, instead you'll use hulusubs_dl.exe
. Command would become:
python hulusubs_dl.exe -proxy 123.456.789.0123:4444
You can also save proxies in the config file, so that you don't have to pass them as arguments everytime.
Trigger make config via --make-config
flag and when the tool asks for Proxy, input proxy like this:
Single Proxy : 123.456.789.0123:4444
Multiple Proxies: 123.456.789.0123:4444;2212.127.11.32:5555
(Notice how we're splitting multiple proxies based on ';')
If you provide multiple proxies, the tool randomly chooses either of the proxies for every connection. This could avoid proxy ban, if you're using this too much.
If you're opening a new Issue, please keep these points in your issue description:
-v
or --verbose
option and upload the errorlog file that tool creates. (remove your login credentials from it).If you're opening an issue to recommend some enhancements/changes, please be as detailed as possible. Also keep these things in mind:
fork
this repository and then raise a PR
after your changes.dev
branch only (don't send direct to master).You can find the version in __verion__.py
. Just update the value according to these rules.
Convention: Year.Month.Date
So, if you're making that PR on 23rd June, 2020, version would be : 2020.06.23
What if you've raised multiple PRs on same day? Simple, just append version for the day like:
Convention: Year.Month.Date.RecurrenceCount
Again, taking example of 23rd June, 2020, let's say you've made 3 different PRs, different versions would be: 2020.06.23.1
, 2020.06.23.2
and 2020.06.23.3
If you're feeling generous, you can donate some $$ via Paypal:
Paypal :
Any amount is appreciated :)