# ABOUT

stov is a program which allows you to subscribe to channels, playlists and search results on youtube, ZDF Mediathek, twitch.tv and vid.me. You don't need an account on these sites for the program to work since it retrieves the needed data using youtube-dl. You can for example run it as a cron job to automatically download your favourite videos.

## USAGE

see ./stov --help

## DEPENDENCIES

stov depends on the following software to be installed:

* Python 3.2 or higher
* youtube-dl (get it from http://rg3.github.com/youtube-dl/ if you don't have it yet, it is needed to download videos and retrieve information about them from youtube)
* lxml module for python

## COPYING

see LICENSE

## CONFIGURATION

By default, the configuration is defined in ~/stov/stov.json in the json format. A default config file is created for you when you run the program for the first time. The following parameters are currently available which you can alter manually:

* mailto: Recipient address used for notitifications
* mailfrom: Sender address used for notifications
* mailhost: Host name or ip address of the mail server which is used to send notifications
* auth_needed: Define if the smtp server need authentication (yes or no)
* user_name: User name to use for smtp authentication if defined
* password: Password to use for SMTP authentication
* youtube-dl: Path to the youtube-dl binary if not found automatically
* downloaddir: Path the downloaded videos are saved into
* database: File name to use for the database
* smtpport: Port used to connect to the mail server
* maxvideos: Maximum number of videos to retrieve from the youtube API for each subscription,
	default 25, maximum 50, reduce this parameter for better parsing performance
* notify: Define if you want to be notified via email about new episodes of your subscriptions,
	valid values: yes or no
* db_version: Database version (Do not change!)
* config_version: Configuration version (Do not change!)
* videocodec: Video codec used for downloaded videos (valid values: mp4, webm or flv)
* maxresolution: Maximum resolution to use for downloaded videos, please note
	that not all codecs and resolutions might be available so a lower resolution
	or other codec might be used in these cases
* maxfails: Number of times the download of a video may fail until it is marked as failed
	and won't be tried again
* check_title: Define if stov should check the title of each video in a search or channel
	with search string subscription. This works around some deficits of the youtube
	API which sometimes also returns video completely unrelated to your search.
	Videos whose titles don't match the search string will be entirely ignored.
	valid values: yes or no

## Sites

The following sites are currently supported:

* Youtube
* ZDF Mediathek
* Twitch.tv
* Vid.me

### Youtube

For this site, all features are supported, you can subscribe to users, channels (via channel ID), global searches or playlists.

### ZDF Mediathek

Only the "channel" subscription type is supported. The string you put in as the channel name will be used to select broadcasts from all of the available ones to download. Since it uses the "Sendung verpasst?" feature of the json API, you should run stov at least daily to catch all broadcasts.

### Twitch.tv

This site only supports the "channel" subscription type. You can select videos from a channel by adding an optional "search" parameter.

### Vid.me

This site only supports the "channel" subscription type. You can select videos from a channel by adding an optional "search" parameter.

## KNOWN ISSUES

Currently none, contact me if you find any.

## INSTALLATION

You can just run the main file "stov" directly from this directory by calling
it from the shell or with the python interpreter ("./stov" or "python3 stov").
Furthermore, stov uses python distutils as default installation method. Just
run "python setup.py install" to install it into your system. For further
information an options run "python setup.py --help".