Podracer v1.4
By Lorenzo Taylor

Description:

Podracer is a podcast downloader.  It takes a file with the URLs to all your
podcast rss feeds and goes and gets the mp3s and stores them in a specified
location.  It is a BASH script with an internal BitTorrent downloader written in
Python.  See the CREDITS file for information on all the great work that helped
make Podracer the winner of the pod race.

Features:

* Catchup feature updates the log without downloading all podcasts
* Run as a cron job to automatically receive podcasts
* Properly fails (with no error message for the sake of cron) if already running
* Download podcast enclosures of any file format
* Support for BitTorrent downloading and seeding of podcasts
* Configurable seed time management and upload bandwidth management
* Background torrent seeding continues after program ends and stops automatically
* System-wide and user-specific configuration
* User-specific subscription file and podcast download directories
* Commentable subscription file - go ahead and mark it up
* Fully configurable placement of files and directories
* Support for dynamic creation of download directories, i.e. based on date/time
* Appears in podcasters' logs as a podcast aggregator
* Automatic creation of m3u playlists
* User may request that m3u not be created
* Automatic removal of empty download directories
* Your suggestions...

Requirements:

Podracer does require a few things to make it run.  here I am listing the
requirements which may not be installed on a standard Unix system:

* /bin/bash
* Python - required by BitTorrent: http://www.python.org
* BitTorrent - the original client by Bram Cohen: http://www.bittorrent.com
* Screen - required for background torrent seeding:
  ftp://ftp.uni-erlangen.de/pub/utilities/screen
* Curl - http/ftp file downloader: http://curl.haxx.se
* Timeout - run a program for a specified time: normally only available as part
  of a larger package that is used for "post-mortem analysis of a UNIX system
  after a breakin", I have included it in the Podracer distribution to be
  installed automatically if you don't already have it.

License:

This software is licensed under the MIT License.  See the LICENSE file to find
out what that means to you.  As a side note, although not required by the
license or by me, I would enjoy receiving an e-mail letting me know if you
modify Podracer in any way, letting me know how Podracer is working for you or
giving me comments or suggestions on how Podracer can be improved.  You can
reach me at lorenzo at taylor dot homelinux dot net.  Just don't send me spam. ;-)

Installation and removal

Podracer is currently packaged in two ways, a self-installing package and a
standard bzip2 tarball.  The self-installing package has an embedded script that
will both install and remove Podracer.  The tarball also has this script, but it
must be run explicitly after untarring Podracer.

Instructions for using the self-installing package:

Download the self-installing package and make it executable.  Then run it as
root with ``install'' as its only argument if you want to install it.  Keep the
package on your computer or stored on disk.  If you want to remove Podracer, run
the self-installing package as root with either ``remove'' or ``uninstall'' as
its only argument.  Or to remove both Podracer and Timeout, add ``timeout''
after ``remove'' or ``uninstall''.  Once Podracer has been removed, it is safe to
delete the package file.

Instructions for installing and removing Podracer from a tarball:

Untar Podracer and cd to the newly created directory.  Then, as root, run
./installer install
or
./installer remove [timeout]
or
./installer uninstall [timeout]
the same way as above.

Note that running either the ./installer script or the self-installing package
file as any user with no arguments or unrecognized arguments will give you a
description of Podracer and a short version of these installation and removal
instructions.

Postinstallation instructions:

You may now wish to create your subscription file.  Subscriptions are by default
placed in ~/.podracer/subscriptions, and are in the format:

Optional comment giving title or other info about this podcast
http://www.sample.com/podcasts/rss.xml optional-dirname
another podcast
http://www.podcastsample.net/samplepodcast.rss no quotes needed here
...

Note that Podracer automatically recognizes any line that begins with anything
other than a URL as a comment.  It also ignores blank lines.

If you don't create a subscription file, a sample with real podcasts may be
created for you the first time you run Podracer.

If you don't want every single podcast starting sometimes as much as a month back
to be automatically downloaded to your computer, you should run Podracer for the
first time in catchup mode:

podracer catchup

You may then wish to add the following line, or something similar, to your
crontab file:

0 */4 * * * podracer

This is not done for you, since you may not want to use it that way, although it
is highly recommended that you do run it as a cron job in order to get the full
benefit of having podcasts automatically downloaded to your computer.

The only other step is to enjoy your new podcasts and keep winning the pod race
with Podracer.
