Timeshift
=========

``timeshift`` is a python program for recording Internet radio streams and saving
them for later listening (`<https://en.wikipedia.org/wiki/Timeshifting>`_).
This is "fair use" of the copyrighted material that is being broadcast and is
perfectly legal as long as the files are not made publicly available. 

Quick Start
-----------

::

  $ easy_install timeshift
  $ cat << EOF > timeshift.conf 
  [DEFAULT]
  basedir = /tmp
  baseurl = http://localhost/tmp

  [NPR]
  title = "National Public Radio"
  url = http://npr.ic.llnwd.net/stream/npr_live24
  duration = 60
  feedfile = npr.atom
  EOF
  $ python timeshift.py NPR


Installation
------------

The simplest installation method is to use Python's ``easy_install`` or
``pip`` to install the package from `PyPI
<https://pypi.python.org/pypi/timeshift>`_::

  pip install timeshift

To install from source, you can clone the project from `BitBucket
<http://bitbucket.org/nmb/timeshift>`_::

  hg clone https://bitbucket.org/nmb/timeshift

Configuration
-------------

``timeshift`` uses a configuration file by default named ``timeshift.conf`` in
the current directory.  To specify a different file use the ``--config=FILE``
option.  The configuration file specifies a global location and URL::

    [DEFAULT]
    basedir = /tmp
    baseurl = http://localhost/tmp

where ``basedir`` is the local directory where files will be saved and
``baseurl`` is the URL where those files can be accessed.

Each source is specified by a separate stanza in the configuration file::

  [NPR]
  title = "National Public Radio"
  url = http://npr.ic.llnwd.net/stream/npr_live24
  duration = 60
  feedfile = npr.atom

where ``title`` is a long name for source, ``url`` is the location to record
from, ``duration`` is the time in *seconds* to record, and ``feedfile`` is the
name of the file in ``basedir`` to write an `Atom
<http://tools.ietf.org/html/rfc4287>`_ feed to (for use with podcasting
software).

The ``url`` for the source is the location from which to download the stream.
This can often be found by *downloading* the MP3 playlist of the stream and
looking for the ``File1`` value inside.

Usage
-----

Simply run the ``timeshift.py`` script with the name of the section that you
wish to record: ``python timeshift.py NPR``.  That will record for the
specified number of seconds to a suitably named file in ``basedir`` and will
add that file to the specified Atom feed in the same directory.

To record at regular intervals, use the ``cron`` facility under Unix.  For
example, to record at 17:00 every saturday you could use the crontab line::

  # m h  dom mon dow   command
  0 17 * * SAT python /path/to/timeshift.py --config=/path/to/timeshift.conf NPR

Acknowledgments
---------------

Timeshift incorporates the Python `feedparser library
<https://pypi.python.org/pypi/feedparser/>`_ and the `rfc3339 module
<http://henry.precheur.org/projects/rfc3339>`_.  Thanks to the authors of
those projects.

License
-------

Copyright 2013 Neil Martinsen-Burrell <neilmartinsenburrell@gmail.com>

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
