i c e d j

Introduction
------------
The IceDJ Suite is a set of scripts for running a Icecast radio station
with tight integration of an accompanying website. It features:
- continous random song playback
- shuffling of songs without replacement (i.e. songs are not played again
  until the playlist is exhausted)
- generation of custom webpages using simple tags. All pages are generated
  as static html, so that the server does not have re-generate content on
  each request. Check provided sample site in web/ for more info.
  Pages generated:
	- current/recent songs webpage
	- playlist webpage
	- top requests webpage
- Automatic updating of any web page with Icecast Server statistics
- Automatic scheduling of Top 10 request show and other fixed content shows
- Stream to multiple Servers at different bitrates at the same time
- Update mp3spy.com with currently playing songinfo

While IceDJ was designed primarily for Icecast, the only Icecast specific
feature is the automatic updating of webpages with Server Statistics. With
this feature disabled, IceDJ can just as well be used as a stream provider for
Shoutcast. Icecast's shout is required as a streaming tool, and we are planning
tigher integration with Icecast in the future, hence we do recommend the use of
Icecast.

Third party software required for use with IceDJ:
- Perl 5
	http://www.perl.com
- The IO::Socket, Time::HiRes and POSIX Perl modules (check CPAN or perl.com)
- Icecast or Shoutcast server
	http://www.icecast.org
	http://www.shoutcast.com
- Shout MP3 streamer
	http://www.icecast.org
- lockfile() utility for file locking (or replace the file locking routines
  in icedj.pl and request.pl with any other locking mechanism)
	ftp://ftp.informatik.rwth-aachen.de/pub/packages/procmail/procmail.tar.gz
  If you decide to use this locking routine you need to also uncomment some
  lines in the lock and unlock routines in icedj.pl and request.pl
  
	
		
License
~~~~~~~
Icedj, an icecast compatible radio management suite
Copyright (C) 1999 Arne Claassen <icedj@remixradio.com>

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA


Scripts
~~~~~~~

icedj.pl
--------
usage: icedj.pl <fullpath to icedj.conf>
The heart of the suite. It reads the playlist and maintains the playlist,
starts scheduled shows and streams all data to the Icecast server. It also
generates the history (current/recent songs), and playlist webpages.
Sending a HUP signal to icedj.pl will reload the configuration file and playlist
as well as reconnect to the server if you changed any of the information
in the configuration file.

Listens for HUP SIGNAL to reload config and playlist

request.pl
----------
usage: request.pl?conf=configfilename&uniqueID=uniqueTrackID
CGI script that manipulates the playlist to insert requested tracks. Can
block IPs, limit how many songs must elapsed before a track is played again,
limits how many songs an IP can request and allows only one request per
IP per 24 hours


propagate.pl
------------
Used to pass along mp3spy.com update information from icedj.pl in case icedj
and icecast are running on separate servers.

webadmin.pl (very much alpha, no docs)
--------------------------------------
administration page for starting/resetting/killing icedj, creating/modifying
config files and checking the last log entries.

Data Files
~~~~~~~~~~

example.conf
------------
standard config file. Look at the sample config file for configuration information.
Don't change this file directly, as webadmin.pl uses it as a template for new
configuration files

playlist
--------
music database containing filepaths of tracks for the station, as well as any other
information that should be available for information about the tracks

schedule
--------
schedule of topten show or fixed content shows. format is similar to the unix
crontab

topten
------
template for topten show

statsblock
----------
template for statistics that are updated on all site files

contacts and webpage
~~~~~~~~~~~~~~~~~~~~
The main webpage for icedj is http://www.remixradio.com/icedj
Please send any suggestions, bugfixes, or anything else to
icedj@remixradio.com
