radiocgi V1.0 release notes
===========================


What is this?
=============

radiocgi is a CGI interface to the linux /dev/radio subsystem. That is, it
allows a computer's radio tuner to be controlled remotely using a Web browser.
This is handy if a number of computer users share a tuner and need to control
it remotely, or if you would simply like a browser interface to the tuner. All
radio operations are carried out using the video4linux API, so any tuner board
with a video4linux driver should work. There are, however, some limitations,
which are discussed below. 


Pre-requisites
==============

To use radiocgi you will need:

- A Web server that supports CGI (e.g., Apache)
- An FM radio tuner with Video4Linux driver support
- A working Video4Linux installation

This software has been tested using Redhat 7.0 (2.2.16 kernel), 
Apache, and Mediaforte SF16-FMR tuner. 

To compile radiocgi you will need, in addition:

- GNU C++ compiler or equivalent (radiocgi is written in C++)
- Video4Linux development files (supplied with most modern
  Linux distributions, but usually not installed as a default).


Compilation
===========

You should find a pre-compiled binary `radiocgi.cgi' with this package; this is
for Intel architecture, 2.2 kernels. If you have anything else, or want to
modify the program, you will need to recompile. Ideally compilation consists of
running `make' in the distribution directory.

The compilation process is as follows.

1. Unpack the distribution if you have not already done so, and
change to the radiocgi-1.0 directory:

% tar xvfz radiocgi-1.0.tar.gz 
% cd radiocgi-1.0

2. Edit `Makefile' for your system. The defaults are:
  - The CGI binary goes in /home/httpd/cgi-bin
  - The initial settings file goes in /etc and is called `radiocgirc'
Note that newer linux distributions tend not to use '/home/httpd/' as the root
for Web content, but something like `/var/www/' instead. radiocgi never writes
the initial settings file, so it does not need to go in a directory with write
access to HTTTPD.

Installation
============

From the distribution directory do `make install'; alternatively
do the following, which amount to the same thing.

1. Copy the CGI program radiocgi.cgi' to your Web server's CGI directory
2. Create the initial settings file, containing the names and frequencies of
the stations to appear in the station list. Use the supplied `radiocgirc' as a
template.

You can then create or modify a Web page to link to the 
program. For example, add the following link to any page:

<a href=http://myserver/cgi-bin/radiocgi.cgi>Radio tuner</a> 


Use
===

I hope the use of this software is self-explanatory. 


Troubleshooting
===============

If you get the message `Can't open device /dev/radio', check that this device
really exists, and that the account that owns the Web server can read and write
it.  Typically: `chmod ugo+rw /dev/radio'. Check the driver using a stand-alone
program, e.g., `xawtv' first, to verify that the drivers are loaded and the
hardware functions correctly. Check the Web server error log.


Bugs and limitations
====================

There are no known bugs, but this only means that the software has not been
tested thoroughly enough. The main limitation is that radiocgi works only for
tuners that tune at 100 kHz intervals. This applies to most of Europe and the
USA, but I can't be sure about other regions.  Another limitation is that the
source code is very ugly and inadequately documented. Sorry.


Author and copyright
====================

radiocgi was written by Kevin Boone. It is (c)2001 Kevin Boone, distributed
under the terms of the CNU public license.  Please see the file COPYING for 
licensing information. In short, feel free to do anything you like with this
software except to claim it as as your own work. The author can be contacted
by e-mail: kb@kevinboone.com.


Disclaimer
==========

This software is distributed free of charge in the hope that it will be
useful. There is absolutely no warranty of any kind.