2
<title>ecasound-iam</title>
3
<link rev="made" href="mailto:kvehmanen -at- eca -dot- cx">
11
<link rev="made" href="mailto:kvehmanen -at- eca -dot- cx">
18
<title>ecasound-iam(1)</title>
19
<link rev="made" href="mailto:kvehmanen -at- eca -dot- cx">
23
<h1>ecasound-iam(1)</h1>
24
<h2> Multimedia software</h2>
29
<h2>NAME</h2>ecasound-iam - ecasound interactive mode
34
Ecasound library contains an interpreter module that understands
35
a set of commands aimed at controlling various library services.
36
This is called the ecasound interactive mode (EIAM). All programs
37
linked to ecasound library can use this facility.
39
<h2>ECI API and return types</h2>
40
A special case of EIAM use is ecasound's control interface (ECI),
41
which is a small library providing easy access to the EIAM
42
commands from outside of libecasound. When issuing EIAM commands using
43
ECI, it's possible that commands also return information. Currently
44
supported return value types are: string [s], list of strings [S]
45
(elements separated by commas; escaped if necessary), integer [i],
46
long integer [li] and floating-point number [f]. These definitions are
47
used throughout this document. Commands that return nothing (void) are
48
marked with [-]. Additionally, return type [e] marks an error condition.
49
When an EIAM results in an error, a error string explaining the
50
condition is returned.
52
<h2>Real-time commands</h2>
53
It's not possible to use all EIAM commands to modify and control
54
objects that belong to a connected chainsetup. Commands that
55
do support this are: 'start', 'stop', 'setpos', 'rewind', 'forward',
56
'c-select', 'c-muting', 'c-bypass', 'cop-select', 'copp-select',
57
'copp-value', 'ctrlp-select' and 'ctrlp-value'.
59
Another set of commands are those which can be used with connected
60
chainsetups, but not without an audible break. These are: 'cop-add',
61
'cop-remove', 'ctrl-add', 'ctrl-select', 'ctrl-remove'
63
In addition, most non-modifying (const) commands work with
68
<p><dt><strong>quit, q</strong><dd>
69
Quit ecasound session. What this means in practice depends on the
70
client (library throws an exception). <em>[-]</em>
72
<p><dt><strong>start, t</strong><dd>
73
Processing is started (play). Error string is return if any errors upon
74
startup are encountered. <em>[e]</em>
76
<p><dt><strong>stop, s</strong><dd>
77
Stop processing. <em>[-]</em>
79
<p><dt><strong>run</strong><dd>
80
Like 'start' but blocks until processing is finished. Error string
81
is return if any errors upon startup, or during process, are
82
encountered. <em>[e]</em>
84
<p><dt><strong>debug 'debug-level'</strong><dd>
85
Set debug level to 'debug-level'. Notice that client programs can
86
reimplement the debug routines. <em>[-]</em>
89
<p><dt><strong>resource-file 'path-to-file'</strong><dd>
90
Overrides the global and user resource files. Does not affect
91
already created objects. This command is equivalent to '-R' ecasound
92
option (see ecasound (1) man page).
94
<p><dt><strong>-prefix:arg1,...,argN</strong><dd>
95
Equivalent to issuing 'cs-option -prefix:arg1,...,argN). See documentation
98
<p><dt><strong>help', 'h'</strong><dd>
107
<p><dt><strong>engine-status</strong><dd>
108
Returns a string describing the engine status (running, stopped,
109
finished, error, not ready). See also <em>cs-status</em>. <em>[s]</em>
111
<p><dt><strong>engine-launch</strong><dd>
112
Starts the real-time engine. Engine will execute the currently
113
connected chainsetup (see 'cs-connect). This action does not yet
114
start actual processing (see <em>start</em> and <em>stop</em>). When
115
ecasound is used as a JACK client, issuing <em>engine-launch</em>
116
makes ecasound an active JACK client (i.e. ecasound's ports
117
can be connected to other JACK clients). <em>[-]</em>
119
<p><dt><strong>engine-halt</strong><dd>
120
Stops the engine. Does not disconnect the chainsetup that
121
was running. See also <em>cs-disconnet</em> and <em>stop</em>. When
122
ecasound is used as a JACK client, <em>engine-halt</em> will
123
cause ecasound to become a deactivated client (all JACK
124
connections are torn down). <em>[-]</em>
129
Chainsetup is the central data object. All other objects (inputs,
130
outputs, chains, etc) are connected to some chainsetup. There can be
131
many chainsetups but only one can be connected. Similarly only
132
one chainsetup can be selected. If not otherwise specified operations
133
are done on the selected chainsetup. Some operations also require
134
that selected chainsetup is not connected.
137
<p><dt><strong>cs-add 'name'</strong><dd>
138
Adds a new chainsetup with name 'name'. 'name' is now
139
the selected chainsetup. <em>[-]</em>
141
<p><dt><strong>cs-remove</strong><dd>
142
Removes currently selected chainsetup. <em>[-]</em>
144
<p><dt><strong>cs-list</strong><dd>
145
Returns a list of all chainsetups. <em>[S]</em>
147
<p><dt><strong>cs-select 'name'</strong><dd>
148
Selects chainsetup 'name'. <em>[-]</em>
150
<p><dt><strong>cs-selected</strong><dd>
151
Returns the name of currently selected chainsetup. <em>[s]</em>
153
<p><dt><strong>cs-index-select 'cs_index', cs-iselect 'cs_index'</strong><dd>
154
Selects a chainsetup based on a short index string. Chainsetup names
155
can be rather long. This command can be used to avoid typing
156
these long names. 'cs_index' is an integer value, where '1' refers to
157
the first audio input/output. You can use 'cs-list' and 'cs-status'
158
to get a full list of currently available chainsetups. <em>[-]</em>
160
<p><dt><strong>cs-load 'filename'</strong><dd>
161
Adds a new chainsetup by loading it from file 'filename'.
162
'filename' is now the selected chainsetup. <em>[-]</em>
164
<p><dt><strong>cs-save</strong><dd>
165
Saves the currently selected chainsetup to file. If chainsetup was loaded
166
from a file, the saved version will replace the original. If it doesn't
167
have a default filename, it's saved to "chainsetup_name.ecs". <em>[-]</em>
169
<p><dt><strong>cs-save-as 'filename'</strong><dd>
170
Saves currently selected chainsetup to file 'filename'. <em>[-]</em>
172
<p><dt><strong>cs-edit</strong><dd>
173
Currently selected chainsetup is saved to a temporary file. This
174
file is loaded to an external editor (see ecasoundrc (5)). After
175
editing, the chainsetup is loaded back to ecasound. <em>[-]</em>
177
<p><dt><strong>cs-is-valid</strong><dd>
178
Whether currently selected chainsetup is valid (=can be connected)? <em>[i]</em>
180
<p><dt><strong>cs-connect</strong><dd>
181
Connect currently selected chainsetup to engine. When connecting,
182
all resources (e.g. files, soundcard devices, external programs) needed
183
to execute the chainsetup are reserved. Only one chainsetup can be connected
184
at a time. Error string is returned if connection fails (for instance
185
due to error in allocating the resources). <em>[e]</em>
187
<p><dt><strong>cs-disconnect</strong><dd>
188
Disconnect currently connected chainsetup. This action will free
189
all external resources needed by the chainsetup. <em>[-]</em>
191
<p><dt><strong>cs-connected</strong><dd>
192
Returns the name of currently connected chainsetup. <em>[s]</em>
194
<p><dt><strong>cs-rewind 'time-in-seconds', rewind 'time-in-seconds', rw 'time-in-seconds'</strong><dd>
195
Rewinds the current chainsetup position by 'time-in-seconds' seconds.
196
Position of all inputs and outputs attached to the selected chainsetup
197
is also affected. <em>[-]</em>
199
<p><dt><strong>cs-forward 'time-in-seconds', forward 'time-in-seconds', fw 'ttime-in-seconds'</strong><dd>
200
The current chainsetup position is forwarded by 'time-in-seconds'
201
seconds. Position of all inputs and outputs attached to the selected chainsetup
202
is also affected. <em>[-]</em>
204
<p><dt><strong>cs-set-position 'time-in-seconds', cs-setpos 'time-in-seconds', setpos 'time-in-seconds', set-position 'time-in-seconds'</strong><dd>
205
Sets the chainsetup position to 'time-in-seconds' seconds from the
206
beginning. Position of all inputs and outputs attached to the selected
207
chainsetup is also affected. <em>[-]</em>
209
<p><dt><strong>cs-set-position-samples 'time-in-samples'</strong><dd>
210
Sets the chainsetup position to 'time-in-samples' samples from the
211
beginning. Position of all inputs and outputs attached to the selected
212
chainsetup is also affected. <em>[-]</em>
214
<p><dt><strong>cs-get-position, cs-getpos, getpos, get-position</strong><dd>
215
Returns the current chainsetup position in seconds. <em>[f]</em>
217
<p><dt><strong>cs-get-position-samples</strong><dd>
218
Returns the current chainsetup position in samples. <em>[li]</em>
220
<p><dt><strong>cs-get-length, get-length</strong><dd>
221
Returns the chainsetup length in seconds (if known). <em>[f]</em>
223
<p><dt><strong>cs-get-length-samples, get-length-samples</strong><dd>
224
Returns the chainsetup length in samples (if known). <em>[li]</em>
226
<p><dt><strong>cs-set-length 'seconds'</strong><dd>
227
Sets processing time in seconds (doesn't have to be an integer value).
228
A special-case value of '-1' will set the chainsetup length
229
according to the longest input object. <em>[-]</em>
231
<p><dt><strong>cs-set-length-samples 'samples'</strong><dd>
232
Sets processing time in samples. <em>[-]</em>
234
<p><dt><strong>cs-toggle-loop</strong><dd>
235
Toggle looping. When processing is finished, engine will start
236
again from the initial position. It's not always possible to enable looping
237
(for instance all inputs and outputs have infinite length and
238
chainsetup length is not explicitly set with 'cs-set-length'). <em>[-]</em>
240
<p><dt><strong>cs-set-param</strong><dd>
241
Interpret general chainsetup parameters like for example
242
"-b" (buffersize), "-n" (name), etc. See ecasound (1) for
243
more info. <em>[-]</em>
245
<p><dt><strong>cs-set-audio-format 'bits,channels,sample_rate'</strong><dd>
246
Set the default sample parameters for currently selected chainsetup.
247
For example cd-quality audio would be "16,2,44100". This does the
248
same as command-line argument "-f" (see ecasound (1)). <em>[-]</em>
250
<p><dt><strong>cs-status, status, st</strong><dd>
251
Prints out status information about available chainsetup.
252
Detailed information is printed out for connected (=available
253
for running) nd selected (=available for editing) chainsetups.
254
Other chainsetups are listed, but further details are
255
suppressed. To get full details of a specific chainsetup,
256
select it with 'cs-select' or 'cs-iselect', and then
257
issue 'cs-select'. <em>[s]</em>
259
<p><dt><strong>cs-option '-prefix:arg1,...,argN'</strong><dd>
260
One powerful feature of the interactive-mode is that it
261
provides full access to ecasound's command-line syntax.
262
For instance, command "cs-option -efb:400,200" means that
263
a bandpass filter is added to the currently selected
264
chain, with initial parameters 400 (center frequency)
265
and 200 (width in Hz).
267
Note that session level options (such as setting debug level)
268
can not be used with 'cs-option' (i.e. only options that modify
271
Note! EIAM implicitly interprets all strings beginning
272
with a '-' as "cs-option string".
276
Chain is a simple signal flow abstraction. Every chain has one input
277
and one output. All chain operators and their controllers are attached
278
to chains. Chains can be muted, unmuted and be bypassed. If not
279
otherwise stated, all operations are done to currently selected
283
<p><dt><strong>c-add 'cname1,...,cnameN'</strong><dd>
284
Adds a set of chains. Added chains are automatically selected. Note
285
that commas in chain names are not allowed. <em>[-]</em>
287
<p><dt><strong>c-remove</strong><dd>
288
Removes selected chains. <em>[-]</em>
290
<p><dt><strong>c-list</strong><dd>
291
Returns a list of all chains. <em>[S]</em>
293
<p><dt><strong>c-select 'cname1,...,cnameN'</strong><dd>
294
Selects chains. Other chains are automatically deselected. <em>[-]</em>
296
<p><dt><strong>c-index-select 'index1,...,indexN', c-iselect 'index1,...,indexN'</strong><dd>
297
Selects a set of chains based on the list of indixes. Each index is
298
an integer value, where '1' refers to the first chain. You can use
299
'c-list' and 'c-status' to get a full list of currently available
302
<p><dt><strong>c-select-all</strong><dd>
303
Selects all chains. <em>[-]</em>
305
<p><dt><strong>c-select-add 'cname1,...,cnameN'</strong><dd>
306
Selects more chains. <em>[-]</em>
308
<p><dt><strong>c-deselect 'cname1,...,cnameN'</strong><dd>
309
Deselects chains. <em>[-]</em>
311
<p><dt><strong>c-selected</strong><dd>
312
Returns a list of selected chains. <em>[S]</em>
314
<p><dt><strong>c-clear</strong><dd>
315
Clear selected chains by removing all chain operators and controllers.
316
Doesn't change how chains are connected to inputs and outputs. <em>[-]</em>
318
<p><dt><strong>c-rename 'new_name'</strong><dd>
319
Renames the selected chain. When using this command, exactly one chain must
320
be selected. <em>[-]</em>
322
<p><dt><strong>c-muting</strong><dd>
323
Toggle chain muting. When chain is muted, all data that goes through
324
is muted. <em>[-]</em>
326
<p><dt><strong>c-mute</strong><dd>
327
Toggle chain muting. Note! Deprecated, use <em>c-muting</em> instead. <em>[-]</em>
329
<p><dt><strong>c-bypass</strong><dd>
330
Toggle chain bypassing. When chain is bypassed, sample data is passed
331
through unprocessed (all chain operators are disabled for the given
334
<p><dt><strong>c-status, cs</strong><dd>
335
Print status info about all chains. <em>[s]</em>
339
<h2>AUDIO INPUT/OUTPUT OBJECTS</h2>
340
If not otherwise stated, all operations are done to currently selected
341
object. All commands with <em>ai-</em> prefix operate on audio inputs,
342
while commands with <em>ao-</em> operate on outputs.
346
<p><dt><strong>ai-add 'input_format_string'</strong><dd>
347
Adds a new input object. See ecasound (1) man page for more info about
348
the argument format ('-i' option). Note on syntax: if any of
349
the parameters (such as a filename) contains commas, the parameter
350
should be enclosed in double-quotes. <em>[-]</em>
352
<p><dt><strong>ao-add 'output_format_string'</strong><dd>
353
Adds a new output object. See ecasound (1) man page for more info about
354
the argument format ('-o' option). If argument is omitted,
355
a default output device is added (see ecasoundrc (5)). Note on syntax: if any
356
of the parameters (such as a filename) contains commas, the parameter
357
should be enclosed in double-quotes. <em>[-]</em>
359
<p><dt><strong>ao-add-default</strong><dd>
360
Adds the default output device (see ecasoundrc (5)). <em>[-]</em>
362
<p><dt><strong>ai-describe, ao-describe</strong><dd>
363
Returns a Ecasound Option Syntax (EOS) compliant string
364
describing the input/output. See the Ecasound User's Guide
365
for more information about EOS. This command was introduced in
366
ecasound 2.4.4. <em>[s]</em>
368
<p><dt><strong>ai-select 'aobject_name', ao-select 'aobject_name'</strong><dd>
369
Selects an audio object. 'aobject_name' refers to the string
370
used when creating the object (the first argument given to ai-add/ao-add).
371
Note that as a important difference to ai-add/ao-add, one should not
372
enclose the object name in double quotes for ai-select/ao-select. In the
373
case a chainsetup contains multiple inputs, or outputs, with
374
identical name, 'ai-select' and 'ao-select' will select
375
the first matching instance. In order to select a specific
376
instance, the 'ai-iselect' and 'ao-iselect' commands need to
377
be used. <em>[-]</em>
379
<p><dt><strong>ai-index-select 'aobject_index', ai-iselect 'aobject_index', ao-index-select 'aobject_index', ao-iselect 'aobject_index'</strong><dd>
380
Select some audio object based on a short index string. Especially file
381
names can be rather long. This command can be used to avoid typing
382
these long names when selecting audio objects. 'aobject_index' is
383
an integer value, where '1' refers to the first audio input/output.
384
You can use 'ai-list' and 'ao-list' to get a full list of currently
385
available inputs/outputs. <em>[-]</em>
387
<p><dt><strong>ai-selected, ao-selected</strong><dd>
388
Returns the name of the currently selected audio object. <em>[s]</em>
390
<p><dt><strong>ai-attach, ao-attach</strong><dd>
391
Attaches the currently selected audio object to all selected chains. <em>[-]</em>
393
<p><dt><strong>ai-remove, ao-remove</strong><dd>
394
Removes the currently selected audio object from the chainsetup. <em>[-]</em>
396
<p><dt><strong>ai-forward 'time_in_seconds', ai-fw 'time_in_seconds', ao-forward 'time_in_seconds', ao-fw 'time_in_seconds'</strong><dd>
397
Selected audio object is forwarded by 'time-in-seconds' seconds.
398
Time should be given as a floating point value (eg. 0.001 is the
399
same as 1ms). <em>[-]</em>
401
<p><dt><strong>ai-rewind 'time_in_seconds', ai-rw 'time_in_seconds', ao-rewind 'time_in_seconds', ao-rw 'time_in_seconds'</strong><dd>
402
Selected audio object is rewinded by 'time-in-seconds' seconds.
403
Time should be given as a floating point value (eg. 0.001 is the
404
same as 1ms). <em>[-]</em>
406
<p><dt><strong>ai-setpos 'time_in_seconds', ai-set-position 'time_in_seconds', ao-setpos 'time_in_seconds', ao-set-position 'time_in_seconds'</strong><dd>
407
Set audio object position to 'time_in_seconds'. <em>[-]</em>
409
<p><dt><strong>ai-set-position-samples 'time_in_samples', ao-set-position-samples 'time_in_samples'</strong><dd>
410
Set audio object position to 'time_in_samples'. <em>[-]</em>
412
<p><dt><strong>ai-getpos, ai-get-position, ao-getpos, ao-get-position</strong><dd>
413
Returns the audio object position in seconds. <em>[f]</em>
415
<p><dt><strong>ai-get-position-samples, ao-get-position-samples</strong><dd>
416
Returns the audio object position in samples. <em>[li]</em>
418
<p><dt><strong>ai-get-length, ao-get-length</strong><dd>
419
Returns the audio object length in seconds. <em>[f]</em>
421
<p><dt><strong>ai-get-length-samples, ao-get-length-samples</strong><dd>
422
Returns the audio object length in samples. <em>[li]</em>
424
<p><dt><strong>ai-get-format, ao-get-format</strong><dd>
425
Returns the audio format of the selected audio input/output as a
426
formatted string. See documentation for '-f' command-line option. <em>[s]</em>
428
<p><dt><strong>ai-wave-edit, ao-wave-edit</strong><dd>
429
The currently selected audio object is loaded into an external
430
wave editor (see ecasoundrc (5)). <em>[-]</em>
432
<p><dt><strong>ai-list, ao-list</strong><dd>
433
Returns a list of all input/output objects. <em>[S]</em>
435
<p><dt><strong>aio-register</strong><dd>
436
Prints a list of registered audio object types. <em>[s]</em>
438
<p><dt><strong>aio-status</strong><dd>
439
Audio object status (index strings, position, length, etc). <em>[s]</em>
443
<h2>CHAIN OPERATORS</h2>
444
Chain operators are used to process and analyze sample data.
445
They are attached to chains. If not otherwise stated,
446
currently selected chainsetup and chain are used. Also,
447
'chainop_id' and 'param_id' are used to select chain operators
448
and their parameters. First valid value for these parameters
452
<p><dt><strong>cop-add 'cop_format_string'</strong><dd>
453
Adds a new chain operator. In addition to normal chain operators,
454
this commmand can also be used to add effect presets and various
455
plugins. Note; it is not possible to add operators to multiple
456
chains at once. In other words only one chain should be selected
457
when issuing 'cop-add'. See ecasound (1) man page for more info. <em>[-]</em>
459
<p><dt><strong>cop-describe</strong><dd>
460
Returns a Ecasound Option Syntax (EOS) compliant string
461
describing the chain operator. See the Ecasound User's Guide
462
for more information about EOS. This command was introduced in
463
ecasound 2.4.4. <em>[s]</em>
465
<p><dt><strong>cop-remove</strong><dd>
466
Removes the selected chain operator. <em>[-]</em>
468
<p><dt><strong>cop-list</strong><dd>
469
Returns a list of all chain operators attached to the currently
470
selected chain. <em>[S]</em>
472
<p><dt><strong>cop-select 'param_id', cop-index-select 'param_id', cop-iselect 'param_id'</strong><dd>
473
Selects a chain operator. <em>[-]</em>
475
<p><dt><strong>cop-selected</strong><dd>
476
Returns the index number of currently selected chain operator. <em>[i]</em>
478
<p><dt><strong>cop-set 'chainop_id, param_id, value'</strong><dd>
479
Changes the value of a single chain operator parameter. Unlike other
480
chain operator commands, this can also be used during processing. <em>[-]</em>
482
<p><dt><strong>cop-status</strong><dd>
483
Returns info about chain operator status. <em>[s]</em>
485
<p><dt><strong>copp-list</strong><dd>
486
Returns a list of selected chain operator's parameters. <em>[S]</em>
488
<p><dt><strong>copp-select 'param_id', copp-index-select 'param_id', copp-iselect 'param_id'</strong><dd>
489
Selects a chain operator parameter. <em>[-]</em>
491
<p><dt><strong>copp-selected</strong><dd>
492
Returns the index number of currently selected chain operator parameter. <em>[i]</em>
494
<p><dt><strong>copp-set 'value'</strong><dd>
495
Sets the selected parameter value to 'value'. <em>[-]</em>
497
<p><dt><strong>copp-get</strong><dd>
498
Returns the selected parameter value. <em>[f]</em>
500
<p><dt><strong>cop-register</strong><dd>
501
Prints a list of registered chain operators. <em>[s]</em>
503
<p><dt><strong>preset-register</strong><dd>
504
Prints a list of registered effect presets. <em>[s]</em>
506
<p><dt><strong>ladspa-register</strong><dd>
507
Prints a list of registered LADSPA plugins. <em>[s]</em>
512
Controllers are used to control individual chain operator parameters.
513
They are attached to chains. If not otherwise stated, currently
514
selected chainsetup and chains are used.
516
<p><dt><strong>ctrl-add 'copc_format_string'</strong><dd>
517
Adds a new controller and attach it to currently selected chain
518
operator. The argument syntax is either "-<id_string>:par1,...,parN"
519
or just "<id_string>:par1,...,parN". If parameter itself contains
520
commas, the parameter should be enclosed in double-quotes.
521
See ecasound (1) man page for more info. <em>[-]</em>
523
<p><dt><strong>ctrl-describe</strong><dd>
524
Returns a Ecasound Option Syntax (EOS) compliant string
525
describing the controller. See the Ecasound User's Guide
526
for more information about EOS. This command was introduced in
527
ecasound 2.4.4. <em>[s]</em>
529
<p><dt><strong>ctrl-remove</strong><dd>
530
Removes the selected controller. <em>[-]</em>
532
<p><dt><strong>ctrl-list</strong><dd>
533
Returns a list of all controllers attached to the currently
534
selected chain. <em>[S]</em>
536
<p><dt><strong>ctrl-select 'param_id', ctrl-index-select 'param_id', ctrl-iselect 'param_id'</strong><dd>
537
Selects a controller. <em>[-]</em>
539
<p><dt><strong>ctrl-selected</strong><dd>
540
Returns the index number of currently selected controller. <em>[i]</em>
542
<p><dt><strong>ctrl-status</strong><dd>
543
Returns info about controller status. <em>[s]</em>
545
<p><dt><strong>ctrl-register</strong><dd>
546
Prints a list of registered controllers. <em>[s]</em>
548
<p><dt><strong>ctrl-get-target</strong><dd>
549
Returns the index number of the chain operator that is
550
connected to the selected controller. The returned index
551
refers to the currently selected chain (see 'cop-list'). <em>[i]</em>
553
<p><dt><strong>ctrlp-list</strong><dd>
554
Returns a list of all controller parameters. This command was introduced in
555
ecasound 2.4.2. <em>[S]</em>
557
<p><dt><strong>ctrlp-select</strong><dd>
558
Selects a controller parameter. This command was introduced in
559
ecasound 2.4.2. <em>[-]</em>
561
<p><dt><strong>ctrlp-selected</strong><dd>
562
Returns the index number of currently selected controller parameter. This command
563
was introduced in ecasound 2.4.2. <em>[i]</em>
565
<p><dt><strong>ctrlp-get</strong><dd>
566
Returns the selected controller parameter value. This command was introduced in
567
ecasound 2.4.2. <em>[f]</em>
569
<p><dt><strong>ctrlp-set</strong><dd>
570
Sets the selected controller parameter value to 'value'. This command was introduced in
571
ecasound 2.4.2. <em>[-]</em>
575
<h2>INTERNAL COMMANDS</h2>
576
Internal commands are not directly aimed at normal use. They
577
are primarily meant for use in scripting and frontends.
580
<p><dt><strong>int-cmd-list</strong><dd>
581
Returns a list of all registered EIAM commands. <em>[S]</em>
583
<p><dt><strong>int-log-history</strong><dd>
584
Returns recent log messages sent by libecasound modules. This
585
is a good tool for debugging ECI/EIAM scripts and applications. This
586
command was introduced in ecasound 2.4.0. <em>[s]</em>
588
<p><dt><strong>int-output-mode-wellformed</strong><dd>
589
Select the well-format output format for log messages. <em>[-]</em>
591
<p><dt><strong>int-set-float-to-string-precision</strong><dd>
592
Sets precision used in float to text conversions. Note that
593
this can be used to control the precision of float return values
594
for ECI commands. <em>[-]</em>
596
<p><dt><strong>int-set-log-history-length</strong><dd>
597
Sets the log history length. Defaults to 0 items.
598
This command was introduced in ecasound 2.4.0. <em>[-]</em>
600
<p><dt><strong>int-cmd-version-string</strong><dd>
601
Returns EIAM parser version string. <em>[s]</em>
603
<p><dt><strong>int-cmd-version-lib-current</strong><dd>
604
Returns EIAM library interface version (libtool). <em>[i]</em>
606
<p><dt><strong>int-cmd-version-lib-revision</strong><dd>
607
Returns EIAM library interface revision (libtool). <em>[i]</em>
609
<p><dt><strong>int-cmd-version-lib-age</strong><dd>
610
Returns EIAM library interface age (libtool). <em>[i]</em>
615
Object maps are central repositories for commonly used object types.
616
By querying the maps, applications can get a list of all registered
617
object types and their properties.
621
<p><dt><strong>map-cop-list</strong><dd>
622
Prints a list of registered chain operators using
623
the format specified in section <em>OPERATOR DESCRIPTIONS</em>. <em>[s]</em>
625
<p><dt><strong>map-preset-list</strong><dd>
626
Prints a list of registered effect presets using
627
the format specified in section <em>OPERATOR DESCRIPTIONS</em>. <em>[s]</em>
629
<p><dt><strong>map-ladspa-list</strong><dd>
630
Prints a list of registered LADSPA plugins using
631
the format specified in section <em>OPERATOR DESCRIPTIONS</em>. <em>[s]</em>
633
<p><dt><strong>map-ladspa-id-list</strong><dd>
634
Prints a list of registered LADSPA plugins using
635
the format specified in section <em>OPERATOR DESCRIPTIONS</em>.
636
Numerical LADPSA plugin identifiers are used. <em>[s]</em>
638
<p><dt><strong>map-ctrl-list</strong><dd>
639
Prints a list of registered controllers using
640
the format specified in section <em>OPERATOR DESCRIPTIONS</em>. <em>[s]</em>
644
<h2>DUMP COMMANDS</h2>
645
The following dump commands are not meant for normal use.
646
Their primary purpose is to provide an easy way to get
647
internal state information from libecasound. All dump
648
commands output a single line with syntax "key value"
649
to the selected output stream (defaults to stdout).
653
<p><dt><strong>dump-target 'filename'</strong><dd>
654
Set target stream for dumping. <em>[-]</em>
656
<p><dt><strong>dump-status</strong><dd>
657
Dumps engine status - 'running', 'stopped', 'finished' or 'notready'. <em>[-]</em>
659
<p><dt><strong>dump-position</strong><dd>
660
Dumps the global position. Printed in seconds using a floating-point
661
representation. <em>[-]</em>
663
<p><dt><strong>dump-length</strong><dd>
664
Dumps the overall processing length. Printed in seconds using a floating-point
665
representation. <em>[-]</em>
667
<p><dt><strong>dump-cs-status</strong><dd>
668
Dumps status string for the currently selected chainsetup - 'connected',
669
'selected' or an empty string. <em>[-]</em>
671
<p><dt><strong>dump-c-selected</strong><dd>
672
Dumps the name of currently selected chain. <em>[-]</em>
674
<p><dt><strong>dump-ai-selected</strong><dd>
675
Dumps label of currently selected audio input. If no input is
676
selected, dumps an empty string. <em>[-]</em>
678
<p><dt><strong>dump-ai-position</strong><dd>
679
Dumps position of currently selected audio inputs. Printed in
680
seconds, using a floating-point representation. <em>[-]</em>
682
<p><dt><strong>dump-ai-length</strong><dd>
683
Dumps length of currently selected audio input. Printed in seconds,
684
using a floating-point representation. <em>[-]</em>
686
<p><dt><strong>dump-ai-open-state</strong><dd>
687
Dumps audio input state info. Either 'open' or 'closed'. <em>[-]</em>
689
<p><dt><strong>dump-ao-selected</strong><dd>
690
Dumps label of currently selected audio output. If no output is
691
selected, dumps an empty string. <em>[-]</em>
693
<p><dt><strong>dump-ao-position</strong><dd>
694
Dumps position of currently selected audio outputs. Printed in
695
seconds, using a floating-point representation. <em>[-]</em>
697
<p><dt><strong>dump-ao-length</strong><dd>
698
Dumps length of currently selected audio output. Printed in seconds,
699
using a floating-point representation. <em>[-]</em>
701
<p><dt><strong>dump-ao-open-state</strong><dd>
702
Dumps audio output state info. Either 'open' or 'closed'. <em>[-]</em>
704
<p><dt><strong>dump-cop-value 'chainop,param'</strong><dd>
705
Dumps chain operator parameter value. 'chainop' and 'param' are
706
operator and parameter index values (1...n). <em>[-]</em>
710
<h2>OPERATOR DESCRIPTIONS</h2>
712
The <em>map-xxx-list</em> commands return a string containing all registered
713
objects of the given type <em>xxx</em>. Each line of the output describes
714
one registered type. The used syntax is:
716
'keyword,name,description,num_of_params,par1_def,par2_def,...'
718
<em>parX_def</em> describes one object parameter. This definition
719
is present for all parameters of the described object type.
722
'name,description,defaultvalue,upper_bound_flag,upper_bound,
723
lower_bound_flag,lower_bound,toggled_flag,integer_flag,
724
logarithmic_flag,output_flag'
726
For exact descriptions of these fields, please see
727
the header file emph(ecasound/libecasound/eca-operator.h).
731
ecasound (1), ecatools (1), ecasoundrc (5)
735
Kai Vehmanen, <<a href="mailto:kvehmanen -at- eca -dot- cx"><em>kvehmanen -at- eca -dot- cx</em></a>>
added
removed
Documentation/ecasound-iam_manpage.html.tmp
