Name: django-icecast-auth
Author: Jay Wineinger <[email protected]>
Date: 2011-03-26

A Django app providing a backend compatible with icecast2 URL auth. Proper
icecast mount configuration coupled with this app should allow you to
dynamically grant access to an icecast mouth to users with specific 
credentials and for specific windows of time.

You grant access to a mount by adding an Authorization model instance.
You specify the mount, a user name, a password, and a start and end time
for the authorization.  When a user connects to a mount which is
configured to use URL authentication with the sample below, the icecast2 
server will check the user's credentials against the username and password
while also verifying that the current time is within the specified
authorization timeframe.  Additionally, if the user is granted access, the 
Django view will set the timelimit header to the end of the authorization
window for that user.

The app also provides a Listener model.  Instances of this are created when a
listener is removed from a mount.  This is purely for record keeping. Again,
you will not see any instances of this model until a user is removed from the
mount.

Note: this stuff only works if the icecast client in use supports
authorization.  VLC does.

INSTALLATION
==============================
1. Download the app and place it on your python path.  The following
   instructions assume you name it "django_icecast_auth".

   git clone git://github.com/jwineinger/django-icecast-auth.git django_icecast_auth

2. Add "django_icecast_auth" to your INSTALLED_APPS.
3. Add the following line to your root URL conf:
    (r'^icecast/', include("django_icecast_auth.urls")),

ICECAST2 CONFIGURATION
==============================
This is mostly left as an exercise for you, but the following mount
authorization configuration works for me. It is up to you to configure the
mount to actually play some audio (but see the "intro" config option for a 
quick test).

<mount>
 <mount-name>/mount_name</mount-name>
 <authentication type="url">
  <option name="listener_add" value="http://your-django.tld/icecast/listener/add/"/>
  <option name="listener_remove" value="http://your-django.tld/icecast/listener/remove/"/>
  <option name="auth_header" value="icecast-auth-user: 1"/>
  <option name="timelimit_header" value="icecast-auth-timelimit:"/>
 </authentication>
</mount>

USAGE
==============================
1. Setup a icecast2 mount using the above XML as a guide. You will need to 
   customize the URLs for listener_add and listener_remove. If you change
   anything except the domain there, be sure to adjust the Django URL patterns
   appropriately.
2. Create "Mount" instances with the same mount-name as defined in your
   icecast server configuration.  Do include the leading slash
   (eg: /mount_name)
3. Create "Authorization" instances for the specific mounts, user/password,
   and allowed window.
4. Try to connect to the mount with your icecast client.  If all goes well,
   you should be prompted for a username and password.  Assuming you have 
   created an Authorization instance for the current time, provide your
   credentials and hopefully you'll start streaming.