project name: VIRTUAL FIDELITY 1.0
release date: JAN 22, 2006
author: johnnymc -at- privateradio.org
license: GPL
project page: http://www.privateradio.org/blog/vFi/index.php


credits:
thanks to Ed Wildgoose for help with brutefir
thanks to Thomas Fuchs, http://script.aculo.us, he's scriptaculos
thanks to Anders Torger for brutefir, 
 http://www.ludd.luth.se/~torger/brutefir.html
thanks to Denis Sbragion for drc, http://freshmeat.net/projects/drc/
special thanks to Walter Zorn http://www.walterzorn.com for his
 most excellent dhtml libraries


The Virtual Fidelity project (vFi) controls jackd and brutefir via a php
script.  vFI can then be controlled via Dhtml web page.

The php script by default runs on port 8090 and 8091.

I have been running this for two weeks straight with no problems,
so it should be pretty stable.  YMMV.

Please do not hesitate to ask for help. 


INSTALL

Required:
php 4.0 or greater
php socket support
jack audio connection kit
brutefir 1.0f
alsa

Optional:
MySQL
Octave

Test if your php has socket support:

php -m

you should see 'sockets' in the list
if not, see IF YOUR PHP DOESN'T HAVE SOCKET SUPPORT below

Make sure both jackd, amixer, brutefir and jack_lsp are in your path
how to find out?
just type the commands, you should get some sort of output



INSTALL the package
tar zxvf vFi-1.0.tar.gz
cd vFi

CONFIGURE

Open conf/system.config
Edit the appropriate entries, most of them are documented in the file

MySQL is not necessary for vFi

Open conf/config.default
This is your default configuration file for presets.  It is also documented.
In most cases you can simply set your numchannels to the number of output
channels on your sound card (typically=8) and sampling rate and that's it.

** YOU SHOULD ONLY HAVE TO CHANGE A FEW ITEMS AT THE TOP OF EACH FILE **
the rest can be configured from the web interface


PROGRAM STRUCTURE
The binaries are in ./bin. The web pages for config and monitoring are in
./html.  These can be moved anywhere and live independently. If you are
running the daemon and the web pages on different servers then open up
xmlhttp.js and read instructions at top.

conf folder holds the configurations and mixer presets.
your filters (if any) should be placed in the filters folder


** NOTE: due to the large number of different sound cards and linux
distros testing is quite difficult.  I would appreciate it if you
would send me an email and tell me the type sound card and linux
distro your are using, and if you had success in running vFi.

In other words, feedback!  


USING YOUR OWN FILTERS
if you have made digital filters then do this:
put your correction filters in the corrections folder and your xovers
in xovers/BITRATE/custom
I have put some bass management filters in the xovers/BITRATE/stock for
you. These are fir linear filters that work well for me.
 

FIRING UP
The vFi daemon program is in bin, so to start it:

--> cd bin
--> php vFI-daemon.php

You probably want to run as root as the program needs access to your mixer
and jackd with privileges.

You should see the program start up jack and brutefir and report a few
things.  If you have jackd or brutefir running it will kill and restart
them automatically. 

Now point your web browser to where ever you put 'html'

http://myserver/where-I-put-html-folder/control.php

Test it out, when you are convinced it is running OK, you will want to
start it and run in the background:

--> php vFI-daemon.php > /dev/null 2>&1 &  2>/dev/null

To start a specific config run like this:

--> php vFi-daemon.php 7  > /dev/null 2>&1 &  2>/dev/null

where '7' is the preset configuration.


COMMANDS
In addition to the web interface, vFi can be controlled via sockets or mysql
Look at end of this doc.

BUGS
Report them to johnnymc -at- privateradio.org


IF YOUR PHP DOESN'T HAVE SOCKET SUPPORT

Gentoo linux:

add sockets to your USE flags in make.conf and re-emerge php

Fedora

As far as I know, Fedora should have socket support enabled by default

Other RPM based distros like Fedora
You may need to install a php-sockets RPM which will look something like this:

	php-sockets-4.x.x-1mdk.i586.html	

Other distros:

If compiling php from command line add this:   --enable-sockets



COMMANDS FOR vFi
*******************
Commands can be sent to vFi in two ways, via http get or Mysql.

An example that activates preset 3

  For mysql you would simply insert a record into the vf_commands table.
  This table is polled constantly so the command should execute immediately.
    
		example:  insert into vf_commands(cmd,params) ('activatepreset','3')

  for http get you would do this;

--> curl http://localhost:8090/?cmd=activatepreset&params=3

these commands would load preset 3 and send it to alsa mixer


Here is a list of documented commands:


-->	activatepreset ID


loads preset ID

example:  cmd=activatepreset&params=1


-->	burnpreset	ID

saves current mix to preset ID
			
example:  cmd=burnpreset&params=1
			

-->	voldn			--
increments master volume (all channels)

-->	volup 		--
decrements master volume (all channels)

-->	setlevel  CHANNEL,LEVEL

sets the level of CHANNEL to LEVEL

-->	setmute   CHANNEL,MUTE

if MUTE=1 turns mute on for CHANNEL
if MUTE=0 turns mute off for CHANNEL

-->	restart		CONFIG,RATE,LATENCY,DITHER

recreates brutefir config and restarts brutefir

RATE is 44100 or 48000
LATENCY is high,mid,low
DITHER is s,r,t or n for shaped,rectangular, triangular, or none