getTV: an automated TV episode getter
getTV uses public APIs (currently only one) to find magnet links for episodes of TV shows after they air.
How to Use (quick, defaults)
getTV has two running modes:
- run once (default)
- run forever (run with
-f) with a delay (
-i) between query attempts
If you want to run
getTV from cron or your own job system, use the default
mode. Otherwise, it's useful to run
getTV continuously and let it self-manage
If you want your own show list, create
SHOWS.local and add your show
names there. If
SHOWS.local exists, it will be used instead of
the defaults in
resolution specific download hierarchy
- supports: 480p, 720p, 1080p, 2160p
- specify multiple resolutions you want to download in the configuration file
- e.g. 720 1080
- if a 1080p version is available before a 720p version, the 1080p version will download first and the 720p version will be ignored because a higher quality version was already selected for download.
- the main reason to have multiple resolutions is sometimes lower resolution versions appear before higher resolution versions. If you're trying to watch shows the same night they air, you may not want to wait the extra 20-60 minutes for a higher quality version. Though, over the past few years, 1080p versions are often being posted first for many releases. Plus, some shows only appear as 720p until released on media months later. More resolutions tend to get you a wider selection quicker.
non-duplication of downloads
getTVmaintains an internal database of previously accepted episodes to prevent duplicate downloads.
getTVwill select episodes at your preferred resolution(s) only once per resolution even if multiple releases and versions appear.
- example: a recent episode of The Simpsons had 7 versions posted:
The.Simpsons.S28E07.WEB-DL.x264-RARBG The.Simpsons.S28E07.Havana.Wild.Weekend.720p.WEB-DL.DD5.1.H264-iT00NZ[rartv] The.Simpsons.S28E07.Havana.Wild.Weekend.1080p.WEB-DL.DD5.1.H264-iT00NZ[rartv] The.Simpsons.S28E07.1080p.HDTV.x264-CROOKS[rartv] The.Simpsons.S28E07.HDTV.x264-KILLERS[ettv] The.Simpsons.S28E07.HDTV.x264-KILLERS[rartv] The.Simpsons.S28E07.720p.HDTV.x264-KILLERS[rartv]
You don't want seven copies of the same episode, so
- first filters by resolution(s) you want downloaded
- then selects your preferred resolution out of the filtered set
- then downloads one episode at the highest resolution available
If your resolution selector is "720 1080" you may still often end up with both 720p and 1080p downloads because it's common for 720p downloads to appear minutes/hours/days before 1080p downloads. We can only select the highest resolution we've seen at the time an episode appears since we don't have future oracle vision.
getTV remembers which shows and episode numbers it downloads. Only
the first available versions at your preferred resolutions will launch
a new download (though
getTV will re-download episodes in two cases:
a PROPER release is posted fixing previous encoding problems and also
if an UNCENSORED language version is posted (i.e. no bleeps added)).
getTV is not a historical show downloader. It only processes lists of the
100 most recently posted episodes in publicly visible archives.
The goal is to enable unattended episode downloading of same-day shows shortly after they air.
If you can't run
getTV locally within a few hours of shows airing, it probably
won't see your shows since they'll scroll out of the most recently posted 100
episodes. The only solution there is to run
getTV on a remote server capable
of running in forever query mode.
How to Use (full)
getTV is known to work against
You may need
pip3 install -r requirements.txt to pick up dependencies.
Command Line Arguments
% ./getTV.py -h usage: getTV.py [-h] [-c CONFIG] [-f] [-i INTERVAL] optional arguments: -h, --help show this help message and exit -c CONFIG, --config CONFIG config filename (default: tv.conf) -f, --forever continuously check for new episodes (default: off) -i INTERVAL, --interval INTERVAL seconds between new episode queries in forever mode (default: 120)
The base configuration file is
tv.conf. You can copy
and make any changes there so your settings won't conflict with future repository updates.
You can specify a specific config filename with the
-c option, but
will always both be consulted (and both files are optional if you are fine with
the in-code defaults). Any options in the
.local config overwrite the same setting
in the default
The configuration file specifies locations of two additional files:
SHOWSis a text file with show names to download.
- one show per line
- shows are prefix-matched, so "The Sim" would match "The Simpsons"
- If you create
.localfile will be used instead of
- (Not modifying the repository-maintained
SHOWSfile can help with updates since the repository will never include a
- (Not modifying the repository-maintained
downloads.dbis a sqlite3 database recording previous downloads
- the database is required so we don't duplicate selections across each run
The configuration file does not specify a download location where files go
getTV does not download anything — it just passes magnet links
to another application.
On OS X,
getTV opens magnet links directly with whichever app you've registered to
handle magnet links. For the best experience, configure your torrent application with
start-on-add and with a default download location so you don't get popups on every addition.
speakDownload enables or disables audible notices of new
episode downloads. (enabled by default, just 'cause)
transmission-remote to add the magnet link
Set login details matching your
transmission-daemon instance in the configuration file.
The current API
or image captchas rendering your server-side scripts useless. If cloudflare decides
to hate you, you can workaround it by:
- using proxy servers cloudflare doesn't hate (see configuration file)
getTVon a remote server without cloudflare blocks, then point the
transmission-remotelogin details back to your main download server
The current show API doesn't pick up all shows because not all shows get posted. If you need certain non-US shows or some animated series not showing up in the feed, you'll have to continue using alternative sources for now (tvteam, loadstone2k12, horriblesubs).
getTV doesn't distinguish between TV and WEB releases or overall bitrate
quality. Downloads are only selected based on resolution tagged in the filename.
Code changes welcome.
The main feature missing is pulling from multiple listing sources. We can eventually add multiple API providers for wider show coverage (e.g. parse TPB user pages sorted by date for alternative public feeds).
One meta-feature could also be a common service to front these APIs. An external service would run the API collector for real-time feeds then publish a combined feed with all recent episodes from multiple sources. Some services already attempt to do that (plus weird RSS formats), but their show/format selections tend to be weak, their long term maintenance dodgy, and they don't solve the no-duplicate-downloads problem. The meta-service could also run a high performance publish/subscribe front-end so subscribers wouldn't have to poll the service, but instead register their interest in a few dozen shows and get real-time push notifications of magnet links when new episodes of interest appear (then on the user-side, the script would perform deduplication of previous downloads as necessary).
getTV uses external API providers for episode listings,
there's no control over when or even if shows appear.
Sometimes shows are late (or sometimes they are early if
airing in weird canadian timezones), but in any case, we can't control
selection or quality.
getTV just consumes public streams from kind upstream