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

Provided by: libaudio-ecasound-perl_1.01-5build4_amd64

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.