README
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