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. mackworth/tivodecode-ng appears to be working well; the original TiVo File Decoder 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 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 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.