INSTALL

These are incomplete installation instructions, but should serve as a 
helping hand for getting started.  This document is a work in progress, 
so all suggestions are welcome.

This file covers the following topics:

* Building
* Configuration
* Running the software
* Troubleshooting
* Known bugs

1.  Building the code:

Since this is development code, you need the various auto* tools to 
compile it.  In particular, you need a relatively recent automake.  
1.9.6 works fine, 1.4-p6 does not.  I have not tried any versions 
inbetween.  You obviously also need a C compiler (GCC works fine) and make.

The following is a probably incomplete list of packages required to 
build PRS:

* Libtool
* PKG-Config
* libogg
* libvorbis
* libvorbisfile
* libcurl
* libspeex
* libshout
* libmysqlclient
* libxml2
* OpenSSL
* libtheora?
* TagLib C binding (libtagc0-dev on Debian/Ubuntu)

Don't forget to make sure you install development packages for required 
libraries if running on a package-based distribution such as Debian or 
Fedora.

Note that while PRS seems to link against all these libraries, it 
doesn't necessarily seem to use all of them.  Speex is one example.  
Also, it may be able to compile without some of them.

The following executables are required when running prs_server:

* madplay
* mpg123
* lame
* oggenc

The following is needed when running prs_db_builder:

* find

You also need a mysql server to hold all the data, plus PHP with mysql 
support and a webserver in order to run the web interface to the 
schedule.  The PHP interface is in the php subdirectory of the source 
tree and currently is not modified by the build process, though this may 
change.

To build, type the following:

autoreconf -i
./configure
make
make install

You will end up with two executables - prs_db_builder and prs_server.  
prs_server is the actual playout application and prs_db_builder is for 
importing information for audio files into the categorised database.

The executables will be installed in /usr/local/bin by default unless 
you change this with options to configure (which is called by autogen).  
The PHP scripts are not installed anywhere so you will have to move them 
to where you want them.

2.  Setting up PRS:

There are five steps you need to take in order to configure the system, 
as described below.

2.1.  Creating the database:

Configuring the database has to be done in two steps, due to the fact 
that you need to run prs_db_builder at least once before you can 
configure user logins to the web interface.  prs_db_builder requires an 
existing database to work with, as well as a PRS configuration file.

Each PRS instance needs its own database.  You will need to create this 
database, PRS will not create it for you.  The following mysql command 
will create a database:

create database prs;

You will also need to make sure that the user you wish to log into mysql 
as has full access to it.  This can be done like so:

grant all  on prs.* to prs identified by 'MyPassword';

If your mysql server is on the same host as PRS (recommended), you will 
probably want to specify localhost instead like so:

grant all  on prs.* to 'prs'@'localhost' identified by 'MyPassword';

The grant statement also creates the prs user if it doesn't already 
exist.  You can omit the "identified by 'MyPassword'" clause if the user 
account already exists or if you wish to not have a password associated 
with that account (not recommended).

The above commands create an empty database.  prs_db_builder will create 
most of the tables for you, and the rest will be done by prs_server when 
it runs.  However you need to configure pRS before you can run 
prs_db_builder.

2.2.  Configuring PRS:

The next step is to create prs.conf.  This file is used by all three 
parts of the PRS system so we need to make it before going any further.

I strongly recommend giving PRS its own directory to run in.  By 
default it will look for the config file prs.conf in the directory 
where you launch it, and it will generate prs.log and prs.err.

For the sake of example, I will use the directory /home/prs as the base 
directory.

A sample file prs.conf.dist can be found in the src directory of the PRS 
sources.  A complete guide to the PRS config file is located in 
doc/configuration.txt.

Most if not all of the config file is optional, however a config file 
without at least one output method *and* at least one bus won't be of 
much practical use, and of course you need to tell it where the database 
is and how to get to it.  If you don't want to use one or both of the 
compressors, comment them out or delete them from the file.  The same 
goes with the soundcard definitions.

The telnet port definition allows you to get to the PRS CLI.  I am not 
particularly sure how much of the CLI works at the moment, but if you 
mainly want automation then you won't need to worry much about this.  
The "shutdown" command in the CLI will (or at least should) cause PRS to 
terminate, so this is worth defining just for this reason alone.  Note 
that it is also possible to set up PRS in such a way that the CLI comes 
up on the console where you start PRS, but this and the telnet port are 
mutually exclusive.

It is very important to make sure that sample rates and channels match 
internally within PRS.  You can tell PRS via extra parameters (not 
currently demonstrated in the sample config) to produce a stream of a 
differing sampling rate, but if a bus expects a different sampling rate 
from what an output expects, the results can range from odd sounds 
to program termination without explanation.

Note 1: At time of writing, the example provided is quite old and 
demonstrates a connection to an Icecast 1.x server.  Changing 
"xaudiocast" to "http" should be enough to get it working with Icecast 
2.x, but it is my intention to shortly rework the example file to give a 
proper Icecast 2 example.

Note 2: My only work on the C portion of PRS so far has been a patch to 
implement logging (i.e. sending of metadata) for Icecast 2 servers.  
This patch has not been reviewed by anyone else and I would like it to 
be.  It was implemented in revision 368 of the subversion repository and 
is also in the Source Forge patch system at 
http://sourceforge.net/tracker/index.php?func=detail&aid=1837908&group_id=206263&atid=996961

If you wish to use this functionality, you can do so with an entry like 
this in the config file:

<logger type="icecast" url="localhost:8000" mount="/stream" 
username="source" password="MyPassword" />

2.3.  configuring the PHP interface:

Once you have a PRS config file, you can configure the PHP interface.

Among the PHP files is a file called config.php.dist.  This is a PHP 
fragment which defines an array giving the name of each station and a 
path to the PRS config file for that station.  Simply rename to 
config.php and edit to your needs.  This will cause your station to be 
selectable from the drop-down list on the login page of the PHP 
interface.

Note that the PHP interface will warn you if you forget to do this.

So your config.php might look like this:

<?php
$STATIONS = array (
        "test" => "/home/prs/prs.conf"
);
?>

Note that as the sample says, if you want to list more than one then all 
but the last require a comma (,) at the end of the line.

2.4.  Populating the database:

You can of course set the database up manually, but prs_db_builder is 
designed to set it up for you.  However, it does mean that you have to 
add at least one audio file to at least one category before you can do 
anything else.  Since most people will want to do this anyway, this is 
not a problem.

The syntax for prs_db_builder is as follows:

prs_db_builder [-C <configfile>] -c <category> <path>

prs_db_builder uses prs.conf in the current folder if the -C option is 
not specified.

If no category is specified, the genre (if any) of the file to be added 
is used, or a blank category is used if no genre is available.  For this 
reason, specifying a category is a very good idea.

Also note that prs_db_builder will add the path exactly as specified, so 
it's a very good idea to use absolute paths (e.g. /home/prs/content) 
rather than relative paths.

So if your station IDs are in /home/prs/content/ids then you might do 
the following:

prs_db_builder -C /home/prs/prs.conf -c IDs /home/prs/content/ids

This will recursively add the contents of /home/prs/content/ids to the 
IDs category, which you can then select in the scheduler.  It will also 
create 8 of the 10 tables required by PRS, the artist_exclude and 
recording_exclude tables will be created by prs_server when required.

You may add more files to the database either by rerunning the 
prs_db_builder command as shown above or by launching it from the web 
interface.

2.5.  Setting up user accounts for the web interface:

Finally, before you can log into the web interface, you need to specify 
at least one set of credentials.  These go into the prs_user table of 
your database, which prs_db_builder has now created.  You may add a user 
like so:

insert into prs_user (user_name, password, email, type) values 
("MyUsername", "MyPassword", "me@myprovider.com", "admin");

Note that all fields must be quoted.  The user_id field is an 
autoincrement field and will be created automatically.

as far as I know, only the type of "admin" is currently meaningful and 
the user must have this in order to use the system.

3.  Running the software:

Now that we've got everything configured, we can run the software.

The playout system and the web interface are completely separate from 
each other, they just work on the same database.

3.1. Running the playout system:

Go to your directory where ;you have your PRS config file (e.g. 
/home/prs) and type:

prs_server

This will use file prs.conf as your config file.  To use an alternate 
config file, specify it on the command line like so:

prs_server mystation.conf

PRS should spit out some output, with the last line being "Parent server 
process returning.".  Anything other than this probably indicates an 
error.

Now PRS is running and should, all things being equal, keep on running.  
You can see what it is doing by looking at prs.log.

My understanding is that if you have no schedule, PRS will keep checking 
every 5 minutes until one appears, at which point it will act on it.

You may control the running PRS process by logging into the telnet port 
as defined in the config file with the configured password.  *WARNING* 
At time of writing, the password is echoed back to you.

A list of the commands available in the CLI can be found in doc/CLI.txt.  
Of particular note are "quit" which exits the CLI, and "shutdown" which 
terminates prs_server.  An unknown command will simply be ignored.

3.2.  Using the web interface:

To use the web interface written in PHP, simply browse to the place 
where you have copied the PHP files.  It's best if you've configured 
your browser to automatically use index.php as a directory index, so 
that you could surf to www.myserver.com/prs for example.

Use the username and password as entered in section 2.5 to log into the 
system.  If you have more than one PRS station, you may select it from 
the drop-down list on the front page.  Note though that credentials are 
only relevant for the station in whose database they reside.  This means 
that if you want the same username and password to access more than one 
station, you need to enter them into the prs_user table of the database 
for each station.

A discussion of the web system and how it works will soon be available 
in doc/scheduling.txt.

4.  Troubleshooting:

PRS has a number of known quirks and some known bugs.

* I only hear loud static on my MP3 stream.

Add the -x parameter to lame to tell it to byte-swap the audio coming 
in, like so:

<encoder_arg>-x</encoder_arg>

See doc/configuration.txt for information on how to add encoder args to 
stream definitions.

* My new timeslots aren't being acted on without a restart.

PRS won't check for new timeslots in the middle of the current one.  So 
if say you want to run automation most of the time but want to be able 
to schedule one-off programs from time to time, create an automation 
template and specify it to run each day for 24 hours.  This will mean an 
interrupted song once a day, but also means that on days when you want 
to schedule something, you can schedule an automation block before and 
after and the program in question at the time you want it, and PRS wil 
just deal with it without needing to restart.

* PRS updates don't work when run from the website.

Not sure what this is exactly.  The commandline that's run looks fine.  
Certainly the web interface doesn't validate the search path, so be sure 
that's correct.

* Copy Timeslots doesn't work properly.

Copy timeslots is broken!   *Do not* use it!

5.  Known bugs:

* PRS doesn't pick up MP3 tags properly in all cases.  Hopefully this is 
just a matter of using different functions in the API.

* PRS doesn't shutdown cleanly.  You may need to kill it if it hangs on 
shutdown.

* prs_db_builder aborts if it strikes a file it doesn't like and doesn't 
even say what it is.  This is annoying.  The directory is searched in 
unsorted order (i.e. "ls --sort=none") so you may be able to figure out 
the problematic file by examining the database and seeing which file was 
processed immediately before the crash.

* The reconnect time isn't always used.  If the encoder dies for some 
reason, it repeatedly tries to reconnect without waiting the required 
length of time.

* It's not currently possible to delete a template.  There's code to do 
this but it's not been tested or hooked up to the interface.

* It's not possible to logout of the interface.  This makes it 
impossible to switch to another station.  Fortunately, sessions time out 
relatively quickly anyway, so wait about ten minutes and try again.

* It's not possible to make the interface secure.  I'm looking for ways 
to detect whether we're using HTTP or HTTPS but have had no luck so far.