1NAME 2 Audio::Ecasound - Perl binding to the ecasound sampler, recorder, 3 fx-processor 4 5SYNOPSIS 6 One function interface: 7 8 use Audio::Ecasound qw(:simple); 9 10 eci("cs-add play_chainsetup"); 11 eci("c-add 1st_chain"); 12 eci("-i:some_file.wav"); 13 eci("-o:/dev/dsp"); 14 # multiple \n separated commands 15 eci("cop-add -efl:100 16 # with comments 17 cop-select 1 18 copp-select 1 19 cs-connect"); 20 eci("start"); 21 my $cutoff_inc = 500.0; 22 while (1) { 23 sleep(1); 24 last if eci("engine-status") ne "running"; 25 26 my $curpos = eci("get-position"); 27 last if $curpos > 15; 28 29 my $next_cutoff = $cutoff_inc + eci("copp-get"); 30 # Optional float argument 31 eci("copp-set", $next_cutoff); 32 } 33 eci("stop"); 34 eci("cs-disconnect"); 35 print "Chain operator status: ", eci("cop-status"); 36 37 Object Interface 38 39 use Audio::Ecasound; 40 41 my $e = new Audio::Ecasound; 42 $e->on_error(''); 43 $e->eci("cs-add play_chainsetup"); 44 # etc. 45 46 Vanilla Ecasound Control Interface (See Ecasound's Programmer Guide): 47 48 use Audio::Ecasound qw(:std); 49 50 command("copp-get"); 51 $precise_float = last_float() / 2; 52 command_float_arg("copp-set", $precise_float); 53 warn last_error() if error(); 54 55 IAM Interface, pretend interactive mode commands are functions. 56 57 use Audio::Ecasound qw(:iam :simple); 58 59 # iam commands as functions with s/-/_/g 60 my $val = copp_get; 61 copp_set $val+0.1; # floats are stringified so beware 62 eci("-i /dev/dsp"); # not all commands are exported 63 64DESCRIPTION 65 Audio::Ecasound provides perl bindings to the ecasound control interface 66 of the ecasound program. You can use perl to automate or interact with 67 ecasound so you don't have to turn you back on the adoring masses packed 68 into Wembly Stadium. 69 70 Ecasound is a software package designed for multitrack audio processing. 71 It can be used for audio playback, recording, format conversions, 72 effects processing, mixing, as a LADSPA plugin host and JACK node. 73 Version >= 2.2.X must be installed to use this package. "SEE ALSO" for 74 more info. 75 76INSTALLATION 77 perl Makefile.PL 78 79 If your perl wasn't built with -Dusethreads or -D_REENTRANT you will be 80 prompted whether to continue with the install. It's in your hands... See 81 "THREADING NOTE" 82 83 make 84 make test 85 make install 86 87THREADING NOTE 88 The ecasoundc library uses pthreads so will may only work if your perl 89 was compiled with threading enabled, check with: 90 91 % perl -V:usethreads 92 93 You are welcome to try using the module with non-threaded perls (perhaps 94 -D_REENTRANT alone would work) it have worked for some. 95 96EXPORT 97 * Nothing by default as when going OO. 98 99 * :simple gives eci() which does most everything, also errmsg and 100 on_error. Or you could just import 'eci' and call the others 101 "Audio::Ecasound::errmsg()" 102 103 * :iam imports many iam commands so that you can use them as perl 104 functions. Basically everything listed by ecasound's 'int-cmd-list' 105 except the single letter commands and hyphens are replaced by 106 underscores. The list is produced at run-time and returned by 107 Audio::Ecasound::get_iam_cmds(). See "IAM COMMANDS"; 108 109 * :std to import the full ecasound control interface detailed in the 110 Ecasound Programmer's Guide. 111 112 * :raw and raw_r, C functions with minimal wrapping, _r ones are 113 reentrant and must be passed the object returned by eci_init_r(). I 114 don't know why you would use these, presumably you do. These options 115 may be removed in future. 116 117METHODS AND FUNCTIONS 118 The procedural and OO interfaces use the same functions, the differences 119 are that when called on an Audio::Ecasound object the reentrant C 120 versions are used so you can have multiple independent engine (with 121 independent options). 122 123 new() 124 Constructor for Audio::Ecasound objects, inherits the on_error and 125 other options from the current package settings (defaults if 126 untouched). 127 128 eci('ecasound command string', [$float_argument]) 129 Sends commands to the Ecasound engine. A single command may be called 130 with an optional float argument (to avoid precision loss). 131 Alternatively, multiple commands may be given separated by newlines 132 (with "#" starting a comment). 133 134 If called in non-void context the result of the last command is 135 returned, it may be an integer, float, string (ie. scalar) or a list 136 of strings. Which will depend on the ecasound command, see 137 ecasound-iam for each function's return value. 138 139 If there is an error the action given to on_error will be taken. See 140 on_error below for return value caveats when on_error = ''. Error 141 processing is performed for each command in a multiline command. 142 143 on_error('die') 144 Set the action to be taken when an error occurs from and "eci" 145 command, may be 'die', 'warn', '', 'confess', ... (default is 'warn'). 146 147 When '' is selected "return;" is used for an error, that is undef or 148 (). To disamibiguate eci will return '' or ('') for no return value 149 and no string list respectively. 150 151 errmsg() 152 The last error message from an "eci" command. It is not reset so clear 153 it yourself if required "errmsg('')". This shouldn't be necessary as 154 you can use "defined" or on_error to find out when errors occur. 155 156 The remainder of the functions/methods are the standard Ecasound Control 157 Interface methods but they come in three flavours. The bare function 158 name may be called with or without an object: 159 160 use Audio::Ecasound ':simple': 161 command($cmd); 162 # or 163 my $e = new Audio::Ecasound; 164 $e = command($cmd); 165 166 The other two flavours are low-level, reentrant and non-reentrant. These 167 are thinly wrapped C functions better documented in the ECI document 168 with the ecasound distribution. Just add 'eci_' to the names below for 169 the non-reentrant version and then add a '_r' to the end for the 170 reentrant version. The reentrant version takes an extra first argument, 171 the object returned by eci_init_r() which must be destroyed with 172 eci_cleanup_r(). 173 174 command($cmd_string) 175 eci_command_float_arg($cmd_string, $float_arg) 176 $bool = eci_error() 177 $err_str = eci_last_error() 178 $float = eci_last_float() 179 $int = eci_last_integer() 180 $lint = eci_last_long_integer() 181 $str = eci_last_string() 182 $n = eci_last_string_list_count() 183 $str_n = eci_last_string_list_item($n) 184 $type_str = eci_last_type() 's' 'S' 'i' 'li' 'f' '' 185 186IAM COMMANDS 187 When the :iam tag is imported most of the commands in ecasounds 188 interactive mode become perl functions. The '-'s become '_'s to become 189 valid perl names ('cop-get' is cop_get, etc.) The list is printed with: 190 191 use Audio::Ecasound qw(:iam :simple); 192 print join ' ', Audio::Ecasound::get_iam_cmds(); 193 194 The arguments joined together as a string and then sent to ecasound. 195 This means that float precision is lost, unlike with the two argument 196 "eci" so use it. Also use "eci" for command-line style commands like 197 "eci "-i /dev/dsp"". But most other things you can just use the iam 198 command itself (s/-/_/g): 199 200 use Audio::Ecasound qw(:iam :simple); 201 ... # setup stuff 202 print status; 203 start; 204 $v = copp_get; 205 copp_set $v + 1.2; 206 207 I would never encourage anyone to use "no strict 'subs';" but with :iam 208 you may enjoy a little less discipline. 209 210 See the iam_int.pl example file in the eg directory. 211 212EXAMPLES 213 See the "eg/" subdirectory. 214 215TROUBLESHOOTING 216 The ecasound command 'debug' could be useful, add "eci "debug 63"" to 217 the top of your program. The argument is various bits OR'd and controls 218 the amount and type of debugging information, see the ecasound 219 documentation of source or just try your favorite powers of two. 220 221FILES AND ENVIRONMENT 222 The libecasoundc library now uses the environment variable "ECASOUND" to 223 find the ecasound executable. If it is not set then the libarary will 224 print a warning. To suppress it, simply set the ECASOUND variable: eg. 225 export ECASOUND=ecasound 226 227 The ecasound library will still process ~/.ecasoundrc and other setup 228 files for default values. See the library documentation. 229 230AUTHOR 231 Copyright (C) 2001, Brad Bowman <eci-perl@bereft.net> 232 233LICENSE 234 This module is free software. You can redistribute it and/or 235 modify it under the terms of the Artistic License 2.0. 236 237 This program is distributed in the hope that it will be useful, 238 but without any warranty; without even the implied warranty of 239 merchantability or fitness for a particular purpose. 240 241SEE ALSO 242 The Ecasound Programmer's Guide and ECI doc, ecasound, ecasound-iam 243 http://eca.cx/, http://www.ladspa.org/ 244 245 The internals of libecasoundc have been rebuilt and now interact with a 246 running ecasound via a socket using a protocol defined in the 247 Programmer's Guide. The C library is now just a compatibility layer and 248 the Python version now talks directly to the socket. It would be 249 straight forward to write an equivalent Perl version should the need 250 arise. 251 252