PHP Ecasound Extension.
------------------------


The PHP Ecasound extension is currently a wrapper for Ecasound, in the future higher level
functions will be written for those who want audio processing in their PHP applications
without learning the Ecasound syntax.

The Ecasound homepage is at http://www.wakkanet.fi/~kaiv/ecasound/



What is Ecasound
-----------------

Ecasound is a very powerful audio processing library that compiles on Linux and several
other UN*X variants (See the ecasound website for further details). It can be used to create
simple sound recorders to fully fledged multitrack recorders with just a few lines of code.
Ecasound is also very good at converting from one file format to another, say from .wav to mp3.


How to build the audio extension.
---------------------------------

** PLEASE NOTE **
The ecasound extension is designed to build with ecasound 2.2.0 which is the latest release. If you 
wish to build it aginst the previous stable version 2.0.4, you will need to uncomment the line
//#define OLD_ECASOUND in the file ecasound.c however there are a number of improvements in the latter
verion and I strongly encourage you to upgrade.


The ecasound extension can either be compiled into php, or built as a shared object that then can be
loaded with the dl() function, or permenantly loaded through php.ini

NOTE. The ecasound extension expexts to find ecasound installed in it's default location.



To build the audio extension into php.
--------------------------------------

Download the tarball and unpack into your php/ext directory. In the top level php directory

run

./buildconf
./configure --with-ecasound --with-any-other-required-options
make
make install.

That's it.



Building as a shared object.
-----------------------------

unpack the tarball

cd ecasound

phpize
./configure
make

Copy the file modules/audio.so into wherever your php.ini extension_dir directive points (eg /usr/local/lib/php/extensions )

The extension can then be loaded at runtime with
dl("ecasound.so");


Note The audio extension is designed to be used by only one script at a time. Trying to use it in
more than one script will lead to unexpected results.



Getting Started.
-----------------

Read the ecasound examples page to get an idea of what ecasound can be used for. 
http://www.wakkanet.fi/~kaiv/ecasound/Documentation/examples.html

Read the Ecasound Control Intreface documentation to understand how to issue commands.
http://www.wakkanet.fi/~kaiv/ecasound/Documentation/ecasound-iam_manpage.html

The commands are issued using the functions below


Functions
----------

The ecasound extension contains tha following functions.


Void eci_initialize(Void )	
Reserve resources.

Void eci_command( String, command ) 
issue a command to the ecasound engine

Void eci_command_float_arg(String command, Double argument)
Issue an EIAM command. This function can be used instead of eci_command if the command 
in question requires exactly one numerical parameter. This way it's possible to avoid 
the extra string -> float conversion, which would lead to lost precision

String eci_last_string( Void )  
Returns the last string return value

Int eci_last_string_list_count(void)
Returns the number of strings returned by the last command

String eci_last_string_list_item(int item_number)
Returns the nth string item that was returned by eci_command

Float eci_last_float( Void )  
Returns the last floating-point return value.

Int eci_last_integer( Void )   
Returns the integer return value.

Bool eci_error( Void )   
Returns true if error has occured during the execution of last command.

String eci_last_error( Void )
Returns a string describing the last error. If the last command was executed 
succesfully returns an empty string.

Void eci_cleanup( Void ) 
Free all reserved resources


Example
--------

Implementation of the following:

1. Setup ECI to read audio from file, apply a 100Hz lowpass filter, and send it to 
the soundcard (/dev/dsp).

2. Every second, check the current position. If the stream has been running for over 
15 seconds, exit immediately. Also, every second, increase the lowpass filter's 
cutoff frequency by 500Hz.

3. Stop the stream (if not already finished) and disconnect the chainsetup. 
Print chain operator status info



<?php


	$cutoff_inc = 500.0;
	$curpos=0;
	$next_cutoff=0;


	eci_init();
	eci_command("cs-add play_chainsetup");
	eci_command("c-add 1st_chain");
	eci_command("ai-add /tmp/somefile.wav");
	eci_command("ao-add /dev/dsp");
	eci_command("cop-add -efl:10");
	eci_command("cop-select 1");
	eci_command("copp-select 1");
	eci_command("cs-connect");
	eci_command("start");

	while(1) {

		sleep(1);

		eci_command("engine-status");
		if (eci_last_string() !="running"){
			break;

		}


		eci_command("get-position");
		$curpos = eci_last_float();
		if ($curpos > 15.0){
			break;
		}


		eci_command("copp-get");
		$next_cutoff = $cutoff_inc + eci_last_float();
		eci_command_float_arg("copp-set",$next_cutoff);

	}



	eci_command("stop");
	eci_command("cs-disconnect");
	eci_command("cop-status");
	printf("Chain operator status: %s", eci_last_string());

	eci_cleanup();



?>



Acknowledgements
-----------------

The ecasound copywrite is owned by
Kai Vehmanen (kaiv AT wakkanet.fi) and
Aymeric Jeanneau (ajeanneau AT cvf.fr)



Thanks to both of them for their efforts in creating ecasound, and for agreeing
that this extension can be linked against libecasound.so (I believe that to use a GPL'd
library with PHP you need the authors permission )


Bugs.
-----

Please feel free to send any suggestions/bug reports to tony@php.net