(Voir README.fr.md pour une version française.)

pytoutv is a TOU.TV client library written in Python 3.

This repository also holds a command line interface.

pytoutv, thanks to TOU.TV's public API (see toutv/config.py for public URLs), is able to retrieve lists of emissions (shows) and episodes, get emissions and episodes informations and fetch any video file publicly distributed by the TOU.TV service. Informations, including video files, downloaded using pytoutv are for personal use only and should not be redistributed unless otherwise authorized by TOU.TV owners.

The pytoutv project is not affiliated, connected or associated with the Canadian Broadcasting Corporation or CBFT-DT. The Canadian Broadcasting Corporation or CBFT-DT do not sponsor, approve of, or endorse pytoutv.

Note: although this is pytoutv 2, there's no such thing as pytoutv 1. This project was previously known as Tou.tv-console-application and targeted at Python 2. Its refactoring and renaming to pytoutv led to its version 2. The CLI remains mostly compatible with the previous version.

Dependencies

pytoutv needs:

Python 3.3+, with:

Optional dependencies:

termcolor (available on PyPI): colors in terminal (CLI)
PyQt4: Qt interface

pytoutv is known to work on Ubuntu, Debian, Fedora, Arch Linux and Mac OS X.

Installing

There are several ways to install pytoutv, the easiest being using pip.

Please note that you need Python 3.3+ whatever the method you choose.

Install dependencies

The pip and setup.py install methods will automatically install Python dependencies for you. However, it might be a better idea to have them installed using your package manager if you have any.

On Debian and Ubuntu, here's how it's done:

$ sudo aptitude install python3-crypto python3-requests python3-setuptools

On Fedora:

$ sudo yum install python3-crypto python3-requests python3-setuptools

On Arch Linux:

$ sudo pacman -Sy python-crypto python-requests python-setuptools

Using pip

Make sure you have pip and setuptools. Your favorite distribution should provide a way to get both.

Then install pytoutv using pip:

$ sudo pip install pytoutv

Ubuntu and Debian

On Debian and Ubuntu, pip uses the Python 2 dependencies by default. To fix this, you can download the Python 3 version of pip:

$ sudo aptitude install python3-pip

You can then run the installation using this package:

$ sudo pip3 install pytoutv

Fedora

On Fedora, pip uses the Python 2 dependencies by default. To fix this, you can download the Python 3 version of pip:

$ sudo yum install python3-pip

You can then run the installation using this package:

$ sudo python3-pip install pytoutv

Mac OS X

First, make sure you have the latest version of Python installed. Apple provides their own build of Python 2.7, but you'll need 3.3 or more for pytoutv.

You can download the latest build for your version of Mac OS X on here: https://www.python.org/download/

To check if it has installed correctly, simply run 'python3.X' (where X is the subversion, like '3.4').

If you have the Python prompt with the correct version stated, you're ready for the next step!

Exit the Python prompt (if not back to your usual terminal) and run:

$ sudo pip3 install pytoutv

Now, have fun!

PLEASE NOTE: It seems the autoinstall script doesn't add pytoutv's path to the global paths file. Add "/Library/Frameworks/Python.framework/Versions/3.4/bin" to "/etc/paths/" and you should be in business!

Using setup.py

As long as you have setuptools, you may install pytoutv directly using its setup.py script:

Clone the repo:

$ git clone https://github.com/bvanheu/pytoutv && cd pytoutv
Run the setup script:

$ sudo ./setup.py install

Library

Package documentation is not available yet.

CLI

The command line tool is simply called toutv. Commonly used commands are:

list: list available shows or available episodes of a show
info: output informations about a show or episode
fetch: fetch (download) a show or all episodes of a show
search: search for a keyword amongst shows and episodes
login: provide credentials for Tou.TV Extra

See toutv -h and toutv <command> -h for more complete information about commands and their usage.

Proxy

Please note toutv honors the HTTP_PROXY and HTTPS_PROXY environment variables, which should contain the full URLs of HTTP(S) proxies to use, including the scheme (http://, https://).

Examples

Here are a few CLI usage examples.

Login to the extra section of tou.tv

This is required to be able to download 720p files, and to fetch any episode only available to Extra members, but otherwise optional.

 $ toutv login <USERNAME>
 Password: <PASSWORD>
 Login successful
 Token: c3458d85-6094-4030-9454-114380b2dec0

Listing all emissions

Note: this will list all emissions, including those only available to Extra members.

$ toutv list
2416249839: 2030, Le Big Bang démographique
2424965959: 26 lettres
1735242576: 30 vies
2415880603: Ainsi soient-ils
2284422575: Air de famille (Un)
2424965905: Alain Bashung faisons envie
2424966134: Alfred Hitchcock : Agent secret
2424966154: Alfred Hitchcock : Aventure malgache
...

Listing episodes of a given emission

$ toutv list 'physique ou chimie'
Physique ou chimie:

  * 2160477711: S01E01 Des choses à faire avant de mourir
  * 2160477623: S01E02 Agir ou laisser faire
  * 2160483636: S01E03 Uniquement sexuel
  * 2160483351: S01E04 Dommages collatéraux
  * 2160490365: S01E05 Une victoire très curieuse
  * 2160490718: S01E06 Il en faut du courage
  * 2160497332: S01E07 Aller de l’avant
  * 2160497534: S01E08 Le prix de la liberté
  * 2161200777: S01E09 Égoïsme raisonnable
  * 2161201111: S01E10 Réactions en chaîne
  ...

Getting information about an emission

$ toutv info 'physique ou chimie'
Physique ou chimie  [Unknown country]

Blanche, Irène, Jonathan et Rock, professeurs au Collège Zurbarán à Madrid, sont
censés servir de guides à leurs étudiants, alors qu'eux-mêmes ont une vie
compliquée. Ils découvriront assez rapidement qu'enseigner est la meilleure
façon d'apprendre la vie. Entre amours, amitiés, trahisons et déceptions, la
série espagnole Physique ou chimie met de l’avant les hauts et les bas que
vivent les élèves et les professeurs.


Infos:

  * Tags: jeunesse, rogers

Getting information about an episode

$ toutv info 'Série noire' S01E08
Série noire
Épisode 8  [S01E08]

Ébranlés par les récentes découvertes, Denis et Patrick tentent d’en savoir
davantage sur l’identité de la mystérieuse femme corpulente. Charlène et Judith
les aideront-elles à éclaircir cette nouvelle piste? Victimes d’un kidnapping,
Denis et Patrick découvrent, au péril de leur vie, les motivations étonnantes de
l’organisation criminelle de Bruno.


Infos:

  * Air date: 2014-03-03
  * Available bitrates:
    * 461 kbps
    * 561 kbps
    * 925 kbps
    * 1324 kbps

Fetching an episode

$ toutv fetch Enquete S2014E11
Enquête.S2014E11.La.guerre.d...    28.8 MiB    24/260 [##-----------------]   9%

Fetching an episode at maximum available video quality

$ toutv fetch -q MAX 'série noire' s01e05
Série.noire.S01E05.Épisode.5...    63.7 MiB    38/260 [###----------------]  14%

Fetching all episodes of a given emission at average quality

$ toutv fetch 'en audition avec simon'
En.audition.avec.Simon.S01E01...    16.5 MiB   15/15 [####################] 100%
En.audition.avec.Simon.S03E47...    24.9 MiB   23/23 [####################] 100%
En.audition.avec.Simon.S01E17...     9.9 MiB    9/27 [#######-------------]  33%
...

Using URL instead of emission or episode name

You can use tou.tv URLs instead of emission or episode names, for the fetch, info, and list commands.

$ toutv fetch http://ici.tou.tv/le-show-cache-2
$ toutv fetch http://ici.tou.tv/le-show-cache-2/S2014E02
$ toutv info http://ici.tou.tv/le-show-cache-2
$ toutv info http://ici.tou.tv/le-show-cache-2/S2014E02
$ toutv list http://ici.tou.tv/le-show-cache-2

Searching for episodes and emissions

$ toutv search politique
Effective query: politique

Episode: Loi 101 : Le malaise de René Lévesque (1re partie)  [1481687502]

  * Air date: 2010-04-27
  * Emission ID: 1480980995

  En 1976, le Parti québécois remporte pour la première fois les élections sur
  la promesse d’être un bon gouvernement. Sans avoir mis la question de la
  langue au cœur du débat électoral, René Lévesque avait promis de revoir la loi
  22. Il confie ce mandat à Camille Laurin.


Episode: Loi 101 : le combat de Camille Laurin (2e partie)  [1485812723]

  * Air date: 2010-05-04
  * Emission ID: 1480980995

  La loi 101 sera, pour Camille Laurin, le combat de sa vie. Il s’entoure
  d’abord des meilleurs esprits de son temps pour rédiger la Charte de la langue
  française. René Lévesque lui demande d’aller convaincre la population
  québécoise. Il affronte alors la colère de la communauté anglaise. À force de
  ruse et de détermination, Camille Laurin dépose finalement le projet de loi
  qui transformera le paysage linguistique du Québec.


Episode: Sommet des Amériques et Sommet des peuples  [1498400939]

  * Air date: 2010-05-18
  * Emission ID: 1480980995

  En 2001, un sommet parallèle s’organise dans la basse-ville de Québec pour
  répliquer aux négociations officielles d’un traité de libre-échange des trois
  Amériques. Le Sommet des peuples accueille 2000 représentants syndicaux, des
  organismes sociaux et féministes, d’ici et d’ailleurs en Amérique. Cinquante
  mille personnes sortent dans la rue pour s’opposer pacifiquement. D’autres
  manifestants préfèrent affronter la police.


Episode: L'humour politique II : Les années 70  [1573008143]

  * Air date: 2010-08-17
  * Emission ID: 1480980995

  Les années 70 sont fertiles en bouleversements. C’est l’ère des imitateurs, de
  la montée du féminisme et le début de l’humour au féminin. Invités : Jean-Guy
  Moreau, Claude Landré et Clémence DesRochers.

...

Bugs

pytoutv is known to work as of the date of the last repo commit. Should you encounter any problem, please create an issue and give details about your situation and what's not working as expected.

Contributing

To contribute to any part of this project, send us a GitHub pull request. Make sure your Python code follows PEP-8, except for long lines that cannot be broken (e.g. long strings).

Python workflow

The best way to develop pytoutv locally without installing it globally is to create a virtualenv. If you don't have virtualenv, get it now (most distributions provide it as a package).

In the root of the repo, create the virtualenv:

$ virtualenv virt
Activate the virtualenv:

$ . ./virt/bin/activate
Use the develop command of setup.py:

$ ./setup.py develop

The first time this executes, if you don't have any of the dependencies, they will be downloaded and installed (locally, in virt).

After step 3, you may execute toutv (which now resolves to the local version of the command). You may as well launch ipython and import toutv modules; the local modules will be imported.

Semantic versioning

pytoutv follows semantic versioning. If you submit a bugfix patch, we'll bump the patch version. If you submit a new feature, we'll bump the minor version. No version 3 of pytoutv is planned.