
ARMANGIL'S VODCATCHER
=====================

Armangil's vodcatcher is a vodcast client for the command line. It provides 
several download strategies, supports BitTorrent, offers cache management, 
and generates playlists for video player applications. It accepts subscription 
documents (in OPML or iTunes PCAST format) or feed documents (RSS or Atom)
as argument. Also included: a search function for subscribing to feeds.

BitTorrent vodcasts are supported both internally (through the RubyTorrent
library) and externally (.torrent files are downloaded, but the user handles
them using another BitTorrent application). The latter is currently the most
reliable method, as RubyTorrent is still in alpha phase.

Concurrency is not handled: simultaneous executions of this program should
target different directories.                                               

See http://en.wikipedia.org/wiki/Vodcast for more information.

Usage1: vodcatcher [options] subscription-or-feed-url-or-filename+ 
Usage2: vodcatcher [options] (subscription or feed from standard input) 
Usage3: vodcatcher -F search [options] query subscription-or-feed-url-or-filename+
Usage4: vodcatcher -F search [options] query (subscription from standard input) 

Options:
    -F, --Function FUNCTION          used function (download search );
                                     when using the search function (which
                                     generates an OPML document), the only
                                     relevant options are -v, -r and -f
                                     (default value: download)

    -d, --dir DIR                    Query for caching files
                                     and storing application state
                                     (default value: current directory)

    -s, --size SIZE                  Size of media file cache in MB; 
                                     0 means infinite; default value is 500

    -m, --memsize N                  Remember last N downloaded media files,
                                     and do not download them again; 
                                     0 means infinite; default value is 1000

    -t, --type TYPE                  Playlist type (m3u smil pls asx tox xspf ) 
                                     (default value: m3u)

    -S, --strategy S                 Strategy to use for downloading vodcasts
                                     (new one back_catalog all cache ):
                                     * back_catalog: download any show that
                                     has not been downloaded before; prefer
                                     the most recent shows of top-most feeds
                                     in the OPML/PCAST documents.
                                     * new: ignore vodcast back-catalogs; this 
                                     is like back_catalog, except that only the
                                     most recent show of each feed is 
                                     considered.
                                     * one: download one unlistened show of
                                     each feed, with a preference for recent
                                     shows
                                     * all: download all show; even already
                                     downloaded shows are downloaded once 
                                     again. 
                                     * cache: play shows that are already in
                                     cache (default value: new)

    -f, --feeds N                    Do not download more than N feeds
                                     (when using the download function);
                                     or return the first N relevant feeds
                                     (when using the search function);
                                     0 means no limits (default value: 1000)

    -r, --retries N                  Try downloading files (media, RSS/Atom or
                                     or OPML/PCAST) at most N times before
                                     giving up (default value: 1)

    -T, --Torrentdir DIR             Copy torrent files to directory DIR;
                                     handling torrents through an external 
                                     BitTorrent client is left to the user;  
                                     if this option is not used, torrents are 
                                     handled internally (if RubyTorrent is 
                                     installed), or else ignored

    -U, --Uploadrate N               Maximum upload rate (kilobytes per second)
                                     for the internal BitTorrent client 
                                     (default: no limit)

    -i, --itemsize N                 If a downloaded show is less than N MB in
                                     size (where N is an integer), fetch other
                                     shows of that same feed until this size is
                                     reached (default: 0)

    -p, --[no-]perfeed               Create one subfolder per feed in cache

    -c, --[no-]cache                 Play already cached files,
                                     DEPRECATED (use -S cache)

    -e, --[no-]empty                 Delete all previously downloaded 
                                     files

    -a, --[no-]asif                  Do not download media files
                                     (useful for testing)

    -v, --[no-]verbose               Run verbosely

        --version                    Display current version

    -h, --help                       Show this message


Usage examples:
    vodcatcher -d ~/vodcasts feeds.opml http://host/second.opml > latest.m3u

    vodcatcher -d ~/vodcasts -S cache > cache.m3u

    cat feeds.opml | vodcatcher -d ~/vodcasts > latest.m3u

    vodcatcher -vd ~/vodcasts -s 500 -m 10_000 -t asx feeds.opml > latest.asx

    vodcatcher -vF search -f 44 'video vlog' http://www.podfeed.net/opml/directory.opml > results.opml


Requirements
------------
Ruby 1.8.2 or later.


Installation
------------
1. Install the most recent Ruby distribution. Ruby is available on many
operating systems such as Windows, MacOS and Linux. A good starting point
is http://www.ruby-lang.org/en/ , and for Linux it is worth taking a look 
at an RPM repository such as http://www.rpmseek.com/ (package name ruby).

2. Extract to disk the vodcatcher directory from the TGZ file.

3. (Optional, for internal BitTorrent support) Download the most recent
RubyTorrent release from http://rubyforge.org/projects/rubytorrent/ , 
add its installation directory to $RUBYLIB (for Linux).

4. (Optional, for Linux users) Add the vodcatcher directory to $PATH
for easy access.


Support
-------
Please submit bug reports, feature or help requests to the forum
accessible from the Armangil's vodcatcher site at 
http://vodcatcher.rubyforge.org/ . Also, please do not hesitate to help
other users who post there (I check the forum regularly, but would not
mind having some backup).

Alternatively, you can send me an email to the address listed below.


License
-------
Armangil's vodcatcher is released under the GNU General Public Licence. Please see 
http://opensource.org/licenses/gpl-license.php for more information.


Author
------
Doga Armangil, armangild@yahoo.com

[January 2006]
