tvoverlord 0.9.18

TV Overlord is a command line tool to download and manage TV shows from newsgroups or bittorent

___________________

README

Sheldon McGrandle
___________________


Table of Contents
_________________

1 Features
2 Install
..... 2.0.1 Setup the post download script
3 Config file
4 How to use
..... 4.0.1 Add new
..... 4.0.2 Show missing
..... 4.0.3 Download
..... 4.0.4 Calendar
..... 4.0.5 History
..... 4.0.6 Info
..... 4.0.7 Search and download non tracked
..... 4.0.8 Edit db info
5 Configure
.. 5.1 Configuration file sections
6 Screenshots
7 Usefull shell commands
8 A note on pirating


[http://i.imgur.com/S9hlqg0.png]

TV Overlord is a command line tool to download and manage TV shows from
newsgroups or bittorent. It will download nzb files or magnet links.

TV Overlord keeps track of which shows have been downloaded and what
shows are available to download.

For each new episode of a tv show you are tracking, you are given a list
of possible downloads to choose. If you use a torrent search provider,
a magnet link is passed to the default bittorent client. If it is an
NZB search, an NZB file is placed in a folder that is configured in the
configuration file.

For torrent files, you can also have your shows organized after
downloading. If you use transmission or deluge, those clients can be
configured to call a script when each torrent is complete. This script
will extract the video file from the downloaded folder, rename it, and
put it in a seperate folder organized into sub folders named for each tv
show.

There are several bittorent search providers and two NZB search
providers and new ones can be added fairly easily. See the search
providers [README.org], or by making a feature request in issues or a
pull request.


[README.org]
https://github.com/8cylinder/tv-overlord/tree/master/tv/search_providers


1 Features
==========

+ Keeps track of downloaded shows
+ Show a list of shows available for download
+ Gives you a list of torrents or nzbs you can choose from
+ You can add new shows from the command line
+ Will display info showing what show will be next and how many days
till broadcast. This list can be filtered and sorted in various
ways
+ Displays a calendar of upcoming episodes. You can also specify a
range of days to display, past or future.


2 Install
=========

TV Overlord has been tested on Linux and Mac. It would probably not
be to hard to make it work on windows, and if anyone is interested, I
can take a look at making it work or alternatively send me a pull
request.

TV Overlord is a python 3 application and can be installed via pip3.
If this method is used, all dependencies will be taken care of.

,----
| sudo pip3 install tvoverlord
`----

If you use Bash as your shell, you can have completions. Add this to
your .bashrc file:

,----
| eval "$(_TVOL_COMPLETE=source tvol)"
`----

After its installed, you run it by typing:

,----
| tvol --help
`----

The first time it's run, it will create the apropriate config dir for
your platform and put the database and config.ini there.

After that you can start to use it, type:

,----
| tvol addnew 'Doctor Who'
`----

If this is the wrong show, try again but add the year:

,----
| tvol addnew 'Doctor Who 2005'
`----

Then

,----
| tvol download
`----


2.0.1 Setup the post download script
------------------------------------

If you use Tranmission or Deluge as your bittorent client there is a
script for each called transmission_done and deluge_done. These will
take the episode that was downloaded and copy it to a folder where it
will be organized by show titles.

If you set the "clean torrents" setting in config.ini to "yes", the
largest file (which is the video file) will be extracted and renamed
to "show title SxxExx resolution.ext". for example: "Fear the Walking
Dead S02E06 720p.mkv". Otherwise whatever was downloaded gets copied.

To set this up in transmission, go to preferences, then downloading
and select the "call script when torrent is completed" then find the
"transmission_done" script. Its location can be found by typing:

,----
| which transmission_done
`----

For Deluge use the execute plugin. More information is available
here: [http://dev.deluge-torrent.org/wiki/Plugins/Execute]


3 Config file
=============

The config file has several settings.

In "App Settings" there is ip, clean torrents and search type.

The ip setting is there to warn you if you are using it without a vpn
running. If you have a vpn account then set the ip setting to what
your ip address is without the vpn running. Then if you download,
tvol will compare this ip address with what your current ip address
and if different, it will warn you.

The "clean torrents" setting can be "yes" or "no"

The "search type" will set if newsgroup search engines are used or
bittorent searches are done.

The "File Locations" section has "tv dir" and "staging" settings.

The "tv dir" setting is where the transmission_done and deluge_done
scripts send the files

The "staging" location is where the NZB files get downloaded to. This
is usually a dir that is watched by your nzb client.


4 How to use
============

4.0.1 Add new
-------------

,----
| tvol addnew SHOWNAME
`----

TV Overlord will search thetvdb.com for a match to your show name. If
it can't find the show you are looking for, it usually helps to add
the year to the name: `tvol addnew 'show name year';'.


4.0.2 Show missing
------------------

,----
| tvol showmissing [--today]
`----

This will list any shows that are available to download.

+ `--no-cache' will use fresh info from thetvdb.com instead of using
the cached data (which is valid for 4 hours)
+ `--today' will show info for today instead of the usuall which is to
only show yesterday's and older


4.0.3 Download
--------------

,----
| tvol download [--today] [--ignore-warning] [--count NUM]
| [--location FILEPATH] [--provider NAME] [SHOWNAME]
`----

For each show thats ready to download, it will ask you which one you
want to download.

+ `--count' sets the number of results to display, the default is 5.
+ `--location' sets the dir to download the nzb files to if you are
using an nzb search engine. This can be set in the ini file
+ `--provider' will set the provider to use. Look in the ini file to
see how that can be specified there. NAME can be a partial name
+ `--no-cache' will use fresh info from thetvdb.com instead of using
the cached data (which is valid for 4 hours)
+ `--today' will show info for today instead of the usuall which is to
only show yesterday's and older
+ `--ignore-warning' does not check if you are connected to a vpn.
This is documented in the tv_config.ini section


And finally, you can specify a single show to only download that show
instead of downloading all.


4.0.4 Calendar
--------------

,----
| tvol calendar [--today] [--sort-by-next]
| [--no-color] [--days DAYS[,AFTER]] [SHOWNAME]
`----

Display a calendar of all the current shows in your database. It
defaults to the width of the console.

+ `--sort-by-next' sorts by order of next episode instead of by name.
+ `--days DAYS' will narrow the calendar to DAYS days. For example,
`--days 10' will show the next 10 days only.
+ `--days DAYS,AFTER' will display from DAYS to AFTER days. For
example, `--days 10,5' will display from the 10th day to the 15th
day.
+ `--no-cache' will use fresh info from thetvdb.com instead of using
the cached data (which is valid for 4 hours)
+ `--today' will show info for today instead of the usuall which is to
only show yesterday's and older


4.0.5 History
-------------

,----
| tvol history (list [-w FIELDS]|copy|redownload) [CRITERIA]
`----

- `CRITERIA' can be days, a date or a title or partial title
- `FIELDS' is a comma seperated list if fields to show that only works
with the list command. It may be any combination of these: date,
title, season, episode, magnet, oneoff, complete, filename,
destination. If not specified it defaults to
='date,title,complete,destination'=.

The `list' command generates a tab seperated list. This is usefull
for piping to various unix commands or for import into a spreadsheet.
For example this command will format the output into columns.

,----
| tvol history list -w 'title,date,complete' | column -ts$'\t'
`----

`copy' and `redownload' show a list where the user can choose an
episode to redownload or recopy a file to the destination set in the
ini file.


4.0.6 Info
----------

,----
| tvol info [--today] [--sort-by-next] [--show-links]
| [--synopsis] [--ask-inactive] [SHOWNAME]
`----

This will show you what shows are next, and how many days till they
are broadcast. Called without arguments, it lists all show except
shows marked inactive, in alphabetical order. A single show can be
specified also.

+ `--sort-by-next' this will sort the shows by order of which episodes
are next
+ `--show-links' will display links to imdb.com and thetvdb.com for
each show
+ `--synopsis' will show a show synopsis for each show
+ `--ask-inactive' When a show has been completely downloaded, and it
has been cancelled or ended, it will ask you if you want to mark it
inactive.


4.0.7 Search and download non tracked
-------------------------------------

,----
| tvol nondbshow [--count NUM] [--location FILEPATH]
| [--provider NAME] SEARCHTERM
`----

This will show you matches to your search. Anything downloaded this
way will not be recorded in your database.

+ `--count' is the number of search results to display
+ `--location' is where to download nzb files to
+ `--provider' will set the provider to use. NAME can be a partial
name


4.0.8 Edit db info
------------------

,----
| tvol editdbinfo SHOWNAME
`----

Edit the data in the database for show name. You can manually set a
show as 'inactive' here if you wish.


5 Configure
===========

TV Overlord looks for the database and `config.ini' in the appropriate
directory for your platform. When tvoverlord is first run, it will
create a tvoverlord directory there.

+ OSX will use ~/Library/Application Support/tvoverlord
+ Linux will use ~/.config/tvoverlord


5.1 Configuration file sections
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

`[App Settings]'
+ `ip: xxx.xxx.xxx.xxx'
If used, TV Overlord will issue a warning if not connected to a
vpn. This should be you ip address when *not* connected to a vpn,
so if your current ip matches this one, the program stops. It uses
[http://api.ipify.org] to get the current ip address.

+ `clean torrents: (yes|no)'
If yes, the video file is extracted from the downloaded dir and
renamed. For example:
`Z.Nation.2x09.INTERNAL.720p.HDTV.x264-KILLERS[ettv].mkv' will be
renamed to "`Z Nation S02E09 720p.mkv'" and then copied to the "`tv
dir'" (description below). If that directory doesn't have a dir
called "Z Nation", it's created.

If no, then whatever was downloaded gets copied to the "tv dir" and
put into the "Z Nation" directory

+ `search type: (torrent|newsgroup)'
search type can be torrent or newsgroup. If it's unspecified, it
will use torrent

`[File Locations]'
+ `tv dir: FILEPATH'
If you use the transmission_done or deluge_done scripts, then
this is where the finished video files will be copied to and
organized into folders under the show's name

+ `staging: FILEPATH'
If using NZB searches, this is where the NZB files will be put.


6 Screenshots
=============

[http://i.imgur.com/jMP4T3h.gif]
This screenshot shows the providers list command and downloading using
an NZB search provider.

[http://i.imgur.com/umS1DqH.gif]
This shows using a bittorrent search provider to download.

[http://i.imgur.com/sBFl5sg.gif]
This shows the calendar.

[http://i.imgur.com/eg0Ui7U.gif]
This show the info command.


7 Usefull shell commands
========================

`tvol calendar --days -$(date '+%u'),7 -x'
This will show all the available shows for the current week from Sun
to Sat.

`tvol history list 1 | column -ts$'\t';'
Todays downloads formated into columns

`tvol history list 365 > shows.tab'
All episodes downloaded in the last year in a file that can be
imported into any spreadsheet program


8 A note on pirating
====================

Downloading shows via the Internet is much easier than watching them
on cable. The shows are displayed in XBMC in a list and only the
shows I want to watch are listed. This isn't about saving money, but
convenience.

The problem is that I don't want to be a thief by getting these shows
for free. So, to make this work, I pay for the biggest cable package
I can, but I don't use it. As far as I'm concerned, this is the same
as using TiVo and skipping the commercials.

If you want to download shows, you should do this too.