Installation.

You should be able to install rivulet to any directory, as long as you keep the same subdirectory names. The example config files are meant to work with it installed at '/local/rivulet/', so use this unless you have a reason not to. There is no compiling to do - all you need to do is unpack it to the right place, and set up the external programs that it runs with.

Rivulet relies on several other programs to do the actual streaming and for various other tasks. Make sure they are installed and working before you try to get rivulet running.

• jackd http://jackit.sourceforge.net/ - jack audio connection kit daemon.
• ecasound http://eca.cx/ecasound/ - ecasound audio toolkit.
• vorbis-tools http://www.vorbis.com/ - oggenc, oggdec etc (tools for working with ogg vorbis files).
• lame http://lame.sourceforge.net/index.html - mp3 encoder.
• alsaplayer http://www.alsaplayer.org/ - media player with a jack output.
• ices http://www.icecast.org/ices.php - ogg vorbis streaming client. (or darkice or shoutcast).
• apache http://httpd.apache.org/ - web server.
• mysql http://www.mysql.com/ - SQL database.
• perl http://www.perl.com/ - general purpose scripting language.
• bash - shell language.
• php4 http://www.php.net/ - web scripting language.

You will also need a server to stream to - for the rest of the documentation, I'll assume you're using icecast with ices as the stream client, as this is the setup it was designed for, but you can rewrite the scripts to use other clients.

Directory structure:

• interface/ - the php front end for setting up the schedule and controlling the scheduler daemon. This drives a mysql backend database, which keeps records of which shows are going out at which time.
• .../controller.php - This is the front end to the stream scheduler, sched.pl. It communicates with the scheduler via two named pipe files.
• .../sql - sql files needed to build the mysql database.
• ipc/ - files used to communicate between the scheduler and the interface.
• .../daemon.out/in are named fifos which the scheduler reads commands from and writes back to.
• .../timetable is a plain text file which tells the scheduler when to start each of the programmes in the current week.
• log/ - log files.
• prerec/ - prerecorded programme files are put here - either mp3 or ogg.
• record/ - programmes that are being recorded go here first before being moved to the shows directory.
• bin/ - all the scripts needed to run the back end of the system (the scheduler daemon, and the scripts which start and stop programmes and streams). Fuller details of how each script works are in each script's header.
• .../sched.pl - This is the main scheduler daemon script, written in perl. It reads the timetable list which has been generated by the php/ mysql front end, stores it in memory, and then starts and stops programmes according to the schedule, or when sent a signal by 'controller.php'. It listens on the pipes daemon.in / out in order to talk with the controller page. When a programme is started, it sends a series of signals to the script 'source'. Firstly, the currently running show is sent a 'stop' signal, so it can turn itself off. E.g. disconnecting the feed from line in. Then the next show is sent a 'start signal'. Finally, the previous show is sent a 'poststop' signal, so that it can do any tidying up which takes too long to have running in between the start and stop events. The source scripts invoke the stream script in turn, in order to do things like updating metadata and starting/stopping recording of a show.
• .../source - this script is called by sched.pl whenever a show starts or stops. It then calls one of the scripts in sources.d, according to what type of show has been started. E.g. starting a live source will start the script called sources.d/live/connect.
• .../stream - this is called whenever something has to be done that applies to an output stream rather than the input source. The source start/stop scripts call it to do things like updating metadata, and you can also call it directly by typing a string into the controller page. e.g. 'stream start icecast'
• .../system - this script starts and stops the core streaming system. The way it is set up at the moment, it starts jackd and a copy of ecasound, which can include LADSPA plugins to modify the signal (e.g. adjust sound level) before it's sent out.
• .../ecamp3.d/ - files defining what encoder to use with ecasound at different bitrates
• .../ecaogg.d/ - same for ogg
• .../sources.d/ - scripts to start and stop different stream sources. each subdirectory is named after the type of stream (e.g. live), and contains a file called connect which starts and stops that type of source.
• misc/ - other files which are needed to set up the system.
• .../.ecasound - ecasound config file - copy this to the home directory of whatever user you are running the scripts as
• .../rivulet-init - init script to start/stop the whole system - copy this to /etc/init.d/rivulet and use '/etc/init.d/rivulet start' to start the system.
• etc/ - config files.
• .../streams.d - config files to start and stop different stream clients. each subdirectory is named after the stream name, and contains a file called config which sets any parameters needed to start that stream, plus any other files needed by the streaming client that's being used - e.g. the ices.xml file for ices streams.
• tmp/ - temporary files which can be deleted after stopping the system.
• var/ - files which are changed by the system but are kept between sessions (e.g. if you have to reboot)
• run/ - files containing process ids of programs which have been started.