===============================================================================
                     RadioMate - Radio Automation Made Easy
===============================================================================

RadioMate is a Free Engine for Distributed Web Radios, i.e. Web Radios in which
the users can broadcast from home or wherever there is a connection to the
Internet.

While Savonet Liquidsoap [http://savonet.sourceforge.net] already provides a
scriptable language and engine for Web Radios with a centralized schedule,
RadioMate wraps and extends it to be used for Web Radios in which the schedule
is managed in an horizontal and distributed way.

Website: http://radiomate.org
Mailing List: https://lists.subsignal.org/mailman/listinfo/radiomate


Structure
=========

At the moment, RadioMate has two main components: the radiomate.cgi CGI script
and the radiomated daemon.

radiomate.cgi accepts JSON requests, made with the POST method, interacts with
the database, and returns JSON responses, as described in the JsonAPI.txt file. 

Through the JSON API, the user can:
- manage roles, i.e. groups of users, with different level of permissions
- manage users, each user must have a role, created in advance
- manage mediafiles, i.e. audio (for the moment) files, which must be already 
  present in the server's filesystem
- manage playlists, which are collections of mediafiles
- manage timeslots. Each timeslot represents a time interval reserved for a 
  transmission. The slottype parameter must correspond to a defined JukeSlot 
  type (described later).

The radiomated daemon retrieves the reserved timeslots from the database and
schedules the transmissions, launching the appropriate JukeSlots.

JukeSlots are an abstraction for liquidsoap instances: the main JukeSlot
manages the global fallback playlist, the actual transmission stream and the
takeover stream. The global fallback playlist is played when there are no
scheduled transmissions, while the takeover stream can be used to override the
normal webradio schedule.

A LiveJukeSlot (slottype:"simplelive") istance represents a transmission in
which a WJ can connect with her client and transmit/perform live, while in a
PlayListJukeSlot (slottype:"simpleplaylist") a predefined playlist (or a
prerecorded transmission) is played.

New JukeSlots can be added, plug-in-wise, as described in the "Plugging in New
JukeSlot Types" section below.


Installation and Configuration
==============================

For system requirements and installation instructions please refer to the
INSTALL file. 

For what concerns configuration, radiomate will look for a file called
radiomateconfig.py inside the /etc/ directory. A sample configuration file,
radiomateconfig.sample.py, is provided, which contains commented sample
configuration parameters.


Plugging in New JukeSlot Types
==============================

The range of supported JukeSlots can be extended by developers that have some
skills in the Savonet liquidsoap scripting language (very little knowledge of
Python is required). The steps can be summarized in:

- creating a new file in which a new Python Class, derived from JukeSlot(), is
  defined and in which the liquidsoapcode() method is overridden. This may
  sound complicated to non-Python developers, but is not: just have a look at 
  the simplelive.py and simpleplaylist.py files, inside the radiomate/jukeslots
  directory and use them as template for the new JukeSlot classes.

  Write your own liquidsoap code inside the liquidsoapcode() method. The code
  must contain a variable named "radio". The stream correspondig to this 
  variable will be forwarded (at runtime) to the main jukeslot istance.

- be sure to add a JUKESLOTTYPEDICT entry at the end of the file. For example,
  at the end of simplelive.py we have the line:

JUKESLOTTYPEDICT['simplelive'] = LiveJukeSlot

  where 'simplelive' is the name that will be used for the timeslot types 
  through the JSON interface, and LiveJukeSlot is the name of the newly 
  defined class.

- put the new file, with .py extension, in the radiomate/jukeslots directory

- edit the radiomate/jukeslots/all.py and add a line similar to this one:

from simplelive import *

  where simplelive corresponds to the filename that contains the new class,
  with the .py extension omitted

- for non-Python developers: be careful with tabs!!! :)  

- restart the radiomated daemon

For any issue please write to the RadioMate mailing list.