# tivomirror - Download recordings from a TiVo to the local disk

## Requirements

Python 3.4 or newer needs to be installed.

`tivodecode` needs to be available on the path. [wmcbrine/tivodecode-ng](https://github.com/wmcbrine/tivodecode-ng)
appears to be working well; the original
[TiVo File Decoder](http://tivodecode.sourceforge.net) has trouble
decoding some files and fails silently.

## Installing

Create a virtual environment and install the required packages:

* `python -m venv .venv` or `virtualenv .venv`
* `. .venv/bin/activate`
* `pip install -r requirements.txt`

## Shell Wrapper

To make it easier to run tivomirror from cron, the shell wrapper
[`tivomirror`](./tivomirror) will activate the venv and then run
`tivomirror.py`.

## Configuration

`tivomirror` reads a config file, by default `~/.tivo/config.yaml`.  The
config file can contain the following keys:
* `cookies`: filename of the cookie jar, relative to `~/.tivo`.
* `host`: hostname of the Tivo.
* `ignoreepisodetitle`: Only use the series' title; default *false*. See
  also command line paramter `-T`.
* `mak`: the Media Access Key for your Tivo account.
* `minfree`: if there's less space in `targetdir` than these many gigabytes,
  do not download anything.
* `proxies`: hash of `http` and `https` proxy URLs to use for talking to the
  Tivo. See the
  [Requests](http://docs.python-requests.org/en/master/user/advanced/#proxies)
  package for details.
* `shows`: a Hash of series' titles for which episodes should be downloaded. 
  Can contain an optional sub-hash, with these keys:
  * `short`: a shorter name for the series, to be used when constructing the
    file name for an episode to be downloaded.
* `targetdir`: store downloaded shows here.
* `tivodecode`: path to tivodecode binary; default `tivodecode`.
* `useragent`; the user agent to use when talking to the Tivo.

You will need to define at least one `shows` element for tivomirror to
download anything.

## Command Line Options

`tivomirror` accepts the following command line options:
* `-c` / `--config`: name of the config file; default `~/.tivo/config.yaml`.
* `-d`/ `--debug`: print debugging output to the log file at
  `~/.tivo/tivomirror.log`.
* `-v` / `--verbose`: print output to stderr as well as to the log file.
* `-u` / `--update`: load new table of contents irrespective of the age of
  the current cached copy.
* `-T` / `--ignoreepisodetitle`: Only use the series' title for the download
  file name, not the combination of series and episode titles.

`tivomirror` accepts the following commands:
* `list`: list all episodes stored on the Tivo, with an indication of:
  * `download`: episode will be downloaded the next time `mirror` runs.
  * `already`: the episode was downloaded successfully previously.
  * `not included`: the series has not been selected for download, that is,
    there's no entry for it in the `shows` hash in the config.
  * `recording`: this episode is currently being recorded; it can be
    downloaded after the recording is finished.
  * `not available`: the Tivo does not make this episode available for
    download; it might be watchable directly on the Tivo.
* `mirror`: download all episodes selected through `shows` that haven't been
  downloaded successfully previously.
* `mirrorone`: download the first show of all shows to be downloaded, exit
  after.

## Database Utility

`tivodb` can be used to list, add or remove entries from the download database at
`~/.tivo/downloads.db`:
* `-a`: add the named entry to the database.
* `-d`: delete the named entry from the database.
* `-l`: list all entries in the database.