NAME

       Audio::Ecasound - Perl binding to the ecasound sampler, recorder, fx-processor

SYNOPSIS

       One function interface:

           use Audio::Ecasound qw(:simple);

           eci("cs-add play_chainsetup");
           eci("c-add 1st_chain");
           eci("-i:some_file.wav");
           eci("-o:/dev/dsp");
           # multiple \n separated commands
           eci("cop-add -efl:100
                # with comments
                cop-select 1
                copp-select 1
                cs-connect");
           eci("start");
           my $cutoff_inc = 500.0;
           while (1) {
               sleep(1);
               last if eci("engine-status") ne "running";

               my $curpos = eci("get-position");
               last if $curpos > 15;

               my $next_cutoff = $cutoff_inc + eci("copp-get");
               # Optional float argument
               eci("copp-set", $next_cutoff);
           }
           eci("stop");
           eci("cs-disconnect");
           print "Chain operator status: ", eci("cop-status");

       Object Interface

         use Audio::Ecasound;

         my $e = new Audio::Ecasound;
         $e->on_error('');
         $e->eci("cs-add play_chainsetup");
         # etc.

       Vanilla Ecasound Control Interface (See Ecasound's Programmer Guide):

         use Audio::Ecasound qw(:std);

         command("copp-get");
         $precise_float = last_float() / 2;
         command_float_arg("copp-set", $precise_float);
         warn last_error() if error();

       IAM Interface, pretend interactive mode commands are functions.

         use Audio::Ecasound qw(:iam :simple);

         # iam commands as functions with s/-/_/g
         my $val = copp_get;
         copp_set $val+0.1; # floats are stringified so beware
         eci("-i /dev/dsp"); # not all commands are exported

DESCRIPTION

       Audio::Ecasound provides perl bindings to the ecasound control interface of the ecasound
       program.  You can use perl to automate or interact with ecasound so you don't have to turn
       you back on the adoring masses packed into Wembly Stadium.

       Ecasound is a software package designed for multitrack audio processing.  It can be used
       for audio playback, recording, format conversions, effects processing, mixing, as a LADSPA
       plugin host and JACK node.  Version >= 2.2.X must be installed to use this package.  "SEE
       ALSO" for more info.

INSTALLATION

        perl Makefile.PL

       If your perl wasn't built with -Dusethreads or -D_REENTRANT you will be prompted whether
       to continue with the install.  It's in your hands... See "THREADING NOTE"

        make
        make test
        make install

THREADING NOTE

       The ecasoundc library uses pthreads so will may only work if your perl was compiled with
       threading enabled, check with:

        % perl -V:usethreads

       You are welcome to try using the module with non-threaded perls (perhaps -D_REENTRANT
       alone would work) it have worked for some.

EXPORT

       •   Nothing by default as when going OO.

       •   :simple gives eci() which does most everything, also errmsg and on_error.  Or you
           could just import 'eci' and call the others Audio::Ecasound::errmsg()

       •   :iam imports many iam commands so that you can use them as perl functions.  Basically
           everything listed by ecasound's 'int-cmd-list' except the single letter commands and
           hyphens are replaced by underscores.  The list is produced at run-time and returned by
           Audio::Ecasound::get_iam_cmds().  See "IAM COMMANDS";

       •   :std to import the full ecasound control interface detailed in the Ecasound
           Programmer's Guide.

       •   :raw and raw_r, C functions with minimal wrapping, _r ones are reentrant and must be
           passed the object returned by eci_init_r().  I don't know why you would use these,
           presumably you do.  These options may be removed in future.

METHODS AND FUNCTIONS

       The procedural and OO interfaces use the same functions, the differences are that when
       called on an Audio::Ecasound object the reentrant C versions are used so you can have
       multiple independent engine (with independent options).

       new()
         Constructor for Audio::Ecasound objects, inherits the on_error and other options from
         the current package settings (defaults if untouched).

       eci('ecasound command string', [$float_argument])
         Sends commands to the Ecasound engine. A single command may be called with an optional
         float argument (to avoid precision loss). Alternatively, multiple commands may be given
         separated by newlines (with "#" starting a comment).

         If called in non-void context the result of the last command is returned, it may be an
         integer, float, string (ie. scalar) or a list of strings. Which will depend on the
         ecasound command, see ecasound-iam for each function's return value.

         If there is an error the action given to on_error will be taken.  See on_error below for
         return value caveats when on_error = ''.  Error processing is performed for each command
         in a multiline command.

       on_error('die')
         Set the action to be taken when an error occurs from and "eci" command, may be 'die',
         'warn', '', 'confess', ... (default is 'warn').

         When '' is selected "return;" is used for an error, that is undef or ().  To
         disamibiguate eci will return '' or ('') for no return value and no string list
         respectively.

       errmsg()
         The last error message from an "eci" command.  It is not reset so clear it yourself if
         required errmsg('').  This shouldn't be necessary as you can use "defined" or on_error
         to find out when errors occur.

       The remainder of the functions/methods are the standard Ecasound Control Interface methods
       but they come in three flavours.  The bare function name may be called with or without an
       object:

         use Audio::Ecasound ':simple':
         command($cmd);
         # or
         my $e = new Audio::Ecasound;
         $e = command($cmd);

       The other two flavours are low-level, reentrant and non-reentrant.  These are thinly
       wrapped C functions better documented in the ECI document with the ecasound distribution.
       Just add 'eci_' to the names below for the non-reentrant version and then add a '_r' to
       the end for the reentrant version.  The reentrant version takes an extra first argument,
       the object returned by eci_init_r() which must be destroyed with eci_cleanup_r().

       command($cmd_string)
       eci_command_float_arg($cmd_string, $float_arg)
       $bool = eci_error()
       $err_str = eci_last_error()
       $float = eci_last_float()
       $int = eci_last_integer()
       $lint = eci_last_long_integer()
       $str = eci_last_string()
       $n = eci_last_string_list_count()
       $str_n = eci_last_string_list_item($n)
       $type_str = eci_last_type() 's' 'S' 'i' 'li' 'f' ''

IAM COMMANDS

       When the :iam tag is imported most of the commands in ecasounds interactive mode become
       perl functions.  The '-'s become '_'s to become valid perl names ('cop-get' is cop_get,
       etc.)  The list is printed with:

         use Audio::Ecasound qw(:iam :simple);
         print join ' ', Audio::Ecasound::get_iam_cmds();

       The arguments joined together as a string and then sent to ecasound.  This means that
       float precision is lost, unlike with the two argument "eci" so use it.  Also use "eci" for
       command-line style commands like "eci "-i /dev/dsp"".  But most other things you can just
       use the iam command itself (s/-/_/g):

         use Audio::Ecasound qw(:iam :simple);
         ... # setup stuff
         print status;
         start;
         $v = copp_get;
         copp_set $v + 1.2;

       I would never encourage anyone to use "no strict 'subs';" but with :iam you may enjoy a
       little less discipline.

       See the iam_int.pl example file in the eg directory.

EXAMPLES

       See the "eg/" subdirectory.

TROUBLESHOOTING

       The ecasound command 'debug' could be useful, add "eci "debug 63"" to the top of your
       program.  The argument is various bits OR'd and controls the amount and type of debugging
       information, see the ecasound documentation of source or just try your favorite powers of
       two.

       There was a bug effecting Audio::Ecasound with ecasound version 2.4.4, causing problems
       with :iam mode, and test failure ("Do you need to predeclare cs_set_length").  See
       <http://www.eca.cx/ecasound-list/2006/12/0007.html> and
       <http://www.eca.cx/ecasound-list/2006/06/0004.html>.

FILES AND ENVIRONMENT

       The libecasoundc library now uses the environment variable "ECASOUND" to find the ecasound
       executable.  If it is not set then the libarary will print a warning.  To suppress it,
       simply set the ECASOUND variable: eg. export ECASOUND=ecaosund

       The ecasound library will still process ~/.ecasoundrc and other setup files for default
       values.  See the library documentation.

AUTHOR

       (c) 2001-2007 Brad Bowman <eci-perl@bereft.net> This software may be distributed under the
       same terms as Perl itself.

SEE ALSO

       The Ecasound Programmer's Guide and ECI doc, ecasound, ecasound-iam http://eca.cx/,
       http://www.ladspa.org/

       The internals of libecasoundc have been rebuilt and now interact with a running ecasound
       via a socket using a protocol defined in the Programmer's Guide.  The C library is now
       just a compatibility layer and the Python version now talks directly to the socket.  It
       would be straight forward to write an equivalent Perl version should the need arise.