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 interactive mode use is ecasound's control interface (ECI),
41
which is a small library providing easy access to the interactive
42
mode commands from outside of libecasound. When issuing inter commands using
43
the control interface, it's possible that commands also return information.
44
Currently 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 interactive mode command results in an error, an error string
50
explaining the condition is returned.
52
<h2>Real-time commands</h2>
53
It's not possible to use all interactive mode commands to modify and
54
control objects that belong to a connected chainsetup. Commands that
55
do NOT support this are:
58
cs-remove, cs-set-length, cs-set-length-samples, cs-toggle-loop,
59
cs-set-param, cs-option,
60
c-add, c-remove, c-rename, c-clear,
61
ai-add, ai-remove, ai-attach, ai-forward, ai-rewind, ai-set-position,
62
ai-set-position-samples,
63
ao-add, ao-add-default, ao-remove, ao-attach, ao-forward, ao-rewind,
64
ao-set-position, ao-set-position-samples.
67
If one of these commands is issued when a chainsetup is connected,
68
ecasound will first stop and disconnect the chainsetup, process
69
the command, and the reconnect.
71
In addition, most non-modifying (const) commands work with
76
<p><dt><strong>quit, q</strong><dd>
77
Quit ecasound session. What this means in practice depends on the
78
client implementation. In ecasound interactive mode, 'quit' terminates
79
the ecasound process. When sent over ecasound server connection (aka
80
NetECI), 'quit' terminates the active network connection, but does not
81
terminate the ecasound server process. <em>[-]</em>
83
<p><dt><strong>start, t</strong><dd>
84
Processing is started (play). Error string is return if any errors upon
85
startup are encountered. <em>[e]</em>
87
<p><dt><strong>stop, s</strong><dd>
88
Stop processing. <em>[-]</em>
90
<p><dt><strong>run</strong><dd>
91
Like 'start' but blocks until processing is finished. Error string
92
is return if any errors upon startup, or during process, are
93
encountered. <em>[e]</em>
95
<p><dt><strong>debug 'debug-level'</strong><dd>
96
Set debug level to 'debug-level'. Notice that client programs can
97
reimplement the debug routines. <em>[-]</em>
100
<p><dt><strong>resource-file 'path-to-file'</strong><dd>
101
Overrides the global and user resource files. Does not affect
102
already created objects. This command is equivalent to '-R' ecasound
103
option (see ecasound (1) man page).
105
<p><dt><strong>-prefix:arg1,...,argN</strong><dd>
106
Equivalent to issuing 'cs-option -prefix:arg1,...,argN). See documentation
109
<p><dt><strong>help', 'h'</strong><dd>
118
<p><dt><strong>engine-status</strong><dd>
119
Returns a string describing the engine status (running, stopped,
120
finished, error, not ready). See also <em>cs-status</em>. <em>[s]</em>
122
<p><dt><strong>engine-launch</strong><dd>
123
Starts the real-time engine. Engine will execute the currently
124
connected chainsetup (see 'cs-connect). This action does not yet
125
start actual processing (see <em>start</em> and <em>stop</em>). When
126
ecasound is used as a JACK client, issuing <em>engine-launch</em>
127
makes ecasound an active JACK client (i.e. ecasound's ports
128
can be connected to other JACK clients). <em>[-]</em>
130
<p><dt><strong>engine-halt</strong><dd>
131
Stops the engine. Does not disconnect the chainsetup that
132
was running. See also <em>cs-disconnet</em> and <em>stop</em>. When
133
ecasound is used as a JACK client, <em>engine-halt</em> will
134
cause ecasound to become a deactivated client (all JACK
135
connections are torn down). <em>[-]</em>
140
Chainsetup is the central data object. All other objects (inputs,
141
outputs, chains, etc) are connected to some chainsetup. There can be
142
many chainsetups but only one can be connected. Similarly only
143
one chainsetup can be selected. If not otherwise specified operations
144
are done on the selected chainsetup. Some operations also require
145
that selected chainsetup is not connected.
148
<p><dt><strong>cs-add 'name'</strong><dd>
149
Adds a new chainsetup with name 'name'. 'name' is now
150
the selected chainsetup. <em>[-]</em>
152
<p><dt><strong>cs-remove</strong><dd>
153
Removes currently selected chainsetup. <em>[-]</em>
155
<p><dt><strong>cs-list</strong><dd>
156
Returns a list of all chainsetups. <em>[S]</em>
158
<p><dt><strong>cs-select 'name'</strong><dd>
159
Selects chainsetup 'name'. <em>[-]</em>
161
<p><dt><strong>cs-selected</strong><dd>
162
Returns the name of currently selected chainsetup. <em>[s]</em>
164
<p><dt><strong>cs-index-select 'cs_index', cs-iselect 'cs_index'</strong><dd>
165
Selects a chainsetup based on a short index string. Chainsetup names
166
can be rather long. This command can be used to avoid typing
167
these long names. 'cs_index' is an integer value, where '1' refers to
168
the first audio input/output. You can use 'cs-list' and 'cs-status'
169
to get a full list of currently available chainsetups. <em>[-]</em>
171
<p><dt><strong>cs-load 'filename'</strong><dd>
172
Adds a new chainsetup by loading it from file 'filename'.
173
'filename' is now the selected chainsetup. <em>[-]</em>
175
<p><dt><strong>cs-save</strong><dd>
176
Saves the currently selected chainsetup to file. If chainsetup was loaded
177
from a file, the saved version will replace the original. If it doesn't
178
have a default filename, it's saved to "chainsetup_name.ecs". <em>[-]</em>
180
<p><dt><strong>cs-save-as 'filename'</strong><dd>
181
Saves currently selected chainsetup to file 'filename'. <em>[-]</em>
183
<p><dt><strong>cs-edit</strong><dd>
184
Currently selected chainsetup is saved to a temporary file. This
185
file is loaded to an external editor (see ecasoundrc (5)). After
186
editing, the chainsetup is loaded back to ecasound. <em>[-]</em>
188
<p><dt><strong>cs-is-valid</strong><dd>
189
Whether currently selected chainsetup is valid (=can be connected)? <em>[i]</em>
191
<p><dt><strong>cs-connect</strong><dd>
192
Connect currently selected chainsetup to engine. When connecting,
193
all resources (e.g. files, soundcard devices, external programs) needed
194
to execute the chainsetup are reserved. Only one chainsetup can be connected
195
at a time. Error string is returned if connection fails (for instance
196
due to error in allocating the resources). <em>[e]</em>
198
<p><dt><strong>cs-disconnect</strong><dd>
199
Disconnect currently connected chainsetup. This action will free
200
all external resources needed by the chainsetup. <em>[-]</em>
202
<p><dt><strong>cs-connected</strong><dd>
203
Returns the name of currently connected chainsetup. <em>[s]</em>
205
<p><dt><strong>cs-rewind 'time-in-seconds', rewind 'time-in-seconds', rw 'time-in-seconds'</strong><dd>
206
Rewinds the current chainsetup position by 'time-in-seconds' seconds.
207
Position of all inputs and outputs attached to the selected chainsetup
208
is also affected. <em>[-]</em>
210
<p><dt><strong>cs-forward 'time-in-seconds', forward 'time-in-seconds', fw 'ttime-in-seconds'</strong><dd>
211
The current chainsetup position is forwarded by 'time-in-seconds'
212
seconds. Position of all inputs and outputs attached to the selected chainsetup
213
is also affected. <em>[-]</em>
215
<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>
216
Sets the chainsetup position to 'time-in-seconds' seconds from the
217
beginning. Position of all inputs and outputs attached to the selected
218
chainsetup is also affected. <em>[-]</em>
220
<p><dt><strong>cs-set-position-samples 'time-in-samples'</strong><dd>
221
Sets the chainsetup position to 'time-in-samples' samples from the
222
beginning. Position of all inputs and outputs attached to the selected
223
chainsetup is also affected. <em>[-]</em>
225
<p><dt><strong>cs-get-position, cs-getpos, getpos, get-position</strong><dd>
226
Returns the current chainsetup position in seconds. <em>[f]</em>
228
<p><dt><strong>cs-get-position-samples</strong><dd>
229
Returns the current chainsetup position in samples. <em>[li]</em>
231
<p><dt><strong>cs-get-length, get-length</strong><dd>
232
Returns the chainsetup length in seconds (if known). <em>[f]</em>
234
<p><dt><strong>cs-get-length-samples, get-length-samples</strong><dd>
235
Returns the chainsetup length in samples (if known). <em>[li]</em>
237
<p><dt><strong>cs-set-length 'seconds'</strong><dd>
238
Sets processing time in seconds (doesn't have to be an integer value).
239
A special-case value of '-1' will set the chainsetup length
240
according to the longest input object. <em>[-]</em>
242
<p><dt><strong>cs-set-length-samples 'samples'</strong><dd>
243
Sets processing time in samples. <em>[-]</em>
245
<p><dt><strong>cs-toggle-loop</strong><dd>
246
Toggle looping. When processing is finished, engine will start
247
again from the initial position. It's not always possible to enable looping
248
(for instance all inputs and outputs have infinite length and
249
chainsetup length is not explicitly set with 'cs-set-length'). <em>[-]</em>
251
<p><dt><strong>cs-set-param</strong><dd>
252
Interpret general chainsetup parameters like for example
253
"-b" (buffersize), "-n" (name), etc. See ecasound (1) for
254
more info. <em>[-]</em>
256
<p><dt><strong>cs-set-audio-format 'bits,channels,sample_rate'</strong><dd>
257
Set the default sample parameters for currently selected chainsetup.
258
For example cd-quality audio would be "16,2,44100". This does the
259
same as command-line argument "-f" (see ecasound (1)). <em>[-]</em>
261
<p><dt><strong>cs-status, status, st</strong><dd>
262
Prints out status information about available chainsetup.
263
Detailed information is printed out for connected (=available
264
for running) nd selected (=available for editing) chainsetups.
265
Other chainsetups are listed, but further details are
266
suppressed. To get full details of a specific chainsetup,
267
select it with 'cs-select' or 'cs-iselect', and then
268
issue 'cs-select'. <em>[s]</em>
270
<p><dt><strong>cs-option '-prefix:arg1,...,argN'</strong><dd>
271
One powerful feature of the interactive-mode is that it
272
provides full access to ecasound's command-line syntax.
273
For instance, command "cs-option -efb:400,200" means that
274
a bandpass filter is added to the currently selected
275
chain, with initial parameters 400 (center frequency)
276
and 200 (width in Hz).
278
Note that session level options (such as setting debug level)
279
can not be used with 'cs-option' (i.e. only options that modify
282
Note! Ecasound interactive mode implicitly interprets all strings
283
beginning with a '-' as "cs-option string".
287
Chain is a simple signal flow abstraction. Every chain has one input
288
and one output. All chain operators and their controllers are attached
289
to chains. Chains can be muted, unmuted and be bypassed. If not
290
otherwise stated, all operations are done to currently selected
294
<p><dt><strong>c-add 'cname1,...,cnameN'</strong><dd>
295
Adds a set of chains. Added chains are automatically selected. Note
296
that commas in chain names are not allowed. <em>[-]</em>
298
<p><dt><strong>c-remove</strong><dd>
299
Removes selected chains. <em>[-]</em>
301
<p><dt><strong>c-list</strong><dd>
302
Returns a list of all chains. <em>[S]</em>
304
<p><dt><strong>c-select 'cname1,...,cnameN'</strong><dd>
305
Selects chains. Other chains are automatically deselected. <em>[-]</em>
307
<p><dt><strong>c-index-select 'index1,...,indexN', c-iselect 'index1,...,indexN'</strong><dd>
308
Selects a set of chains based on the list of indixes. Each index is
309
an integer value, where '1' refers to the first chain. You can use
310
'c-list' and 'c-status' to get a full list of currently available
313
<p><dt><strong>c-select-all</strong><dd>
314
Selects all chains. <em>[-]</em>
316
<p><dt><strong>c-select-add 'cname1,...,cnameN'</strong><dd>
317
Selects more chains. <em>[-]</em>
319
<p><dt><strong>c-deselect 'cname1,...,cnameN'</strong><dd>
320
Deselects chains. <em>[-]</em>
322
<p><dt><strong>c-selected</strong><dd>
323
Returns a list of selected chains. <em>[S]</em>
325
<p><dt><strong>c-clear</strong><dd>
326
Clear selected chains by removing all chain operators and controllers.
327
Doesn't change how chains are connected to inputs and outputs. <em>[-]</em>
329
<p><dt><strong>c-rename 'new_name'</strong><dd>
330
Renames the selected chain. When using this command, exactly one chain must
331
be selected. <em>[-]</em>
333
<p><dt><strong>c-muting, c-mute</strong><dd>
334
Toggle chain muting. When chain is muted, all data that goes through
335
is muted. <em>[-]</em>
337
<p><dt><strong>c-bypass</strong><dd>
338
Toggle chain bypassing. When chain is bypassed, sample data is passed
339
through unprocessed (all chain operators are disabled for the given
342
<p><dt><strong>c-status, cs</strong><dd>
343
Print status info about all chains. <em>[s]</em>
347
<h2>AUDIO INPUT/OUTPUT OBJECTS</h2>
348
If not otherwise stated, all operations are done to currently selected
349
object. All commands with <em>ai-</em> prefix operate on audio inputs,
350
while commands with <em>ao-</em> operate on outputs.
354
<p><dt><strong>ai-add 'input_format_string'</strong><dd>
355
Adds a new input object. See ecasound (1) man page for more info about
356
the argument format ('-i' option). Note on syntax: if any of
357
the parameters (such as a filename) contains commas, the parameter
358
should be enclosed in double-quotes. <em>[-]</em>
360
<p><dt><strong>ao-add 'output_format_string'</strong><dd>
361
Adds a new output object. See ecasound (1) man page for more info about
362
the argument format ('-o' option). If argument is omitted,
363
a default output device is added (see ecasoundrc (5)). Note on syntax: if any
364
of the parameters (such as a filename) contains commas, the parameter
365
should be enclosed in double-quotes. <em>[-]</em>
367
<p><dt><strong>ao-add-default</strong><dd>
368
Adds the default output device (see ecasoundrc (5)). <em>[-]</em>
370
<p><dt><strong>ai-describe, ao-describe</strong><dd>
371
Returns a Ecasound Option Syntax (EOS) compliant string
372
describing the input/output. See the Ecasound User's Guide
373
for more information about EOS. This command was introduced in
374
ecasound 2.4.4. <em>[s]</em>
376
<p><dt><strong>ai-select 'aobject_name', ao-select 'aobject_name'</strong><dd>
377
Selects an audio object. 'aobject_name' refers to the string
378
used when creating the object (the first argument given to ai-add/ao-add).
379
Note that as a important difference to ai-add/ao-add, one should not
380
enclose the object name in double quotes for ai-select/ao-select. In the
381
case a chainsetup contains multiple inputs, or outputs, with
382
identical name, 'ai-select' and 'ao-select' will select
383
the first matching instance. In order to select a specific
384
instance, the 'ai-iselect' and 'ao-iselect' commands need to
385
be used. <em>[-]</em>
387
<p><dt><strong>ai-index-select 'aobject_index', ai-iselect 'aobject_index', ao-index-select 'aobject_index', ao-iselect 'aobject_index'</strong><dd>
388
Select some audio object based on a short index string. Especially file
389
names can be rather long. This command can be used to avoid typing
390
these long names when selecting audio objects. 'aobject_index' is
391
an integer value, where '1' refers to the first audio input/output.
392
You can use 'ai-list' and 'ao-list' to get a full list of currently
393
available inputs/outputs. <em>[-]</em>
395
<p><dt><strong>ai-selected, ao-selected</strong><dd>
396
Returns the name of the currently selected audio object. <em>[s]</em>
398
<p><dt><strong>ai-attach, ao-attach</strong><dd>
399
Attaches the currently selected audio object to all selected chains. <em>[-]</em>
401
<p><dt><strong>ai-remove, ao-remove</strong><dd>
402
Removes the currently selected audio object from the chainsetup. <em>[-]</em>
404
<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>
405
Selected audio object is forwarded by 'time-in-seconds' seconds.
406
Time should be given as a floating point value (eg. 0.001 is the
407
same as 1ms). <em>[-]</em>
409
<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>
410
Selected audio object is rewinded by 'time-in-seconds' seconds.
411
Time should be given as a floating point value (eg. 0.001 is the
412
same as 1ms). <em>[-]</em>
414
<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>
415
Set audio object position to 'time_in_seconds'. <em>[-]</em>
417
<p><dt><strong>ai-set-position-samples 'time_in_samples', ao-set-position-samples 'time_in_samples'</strong><dd>
418
Set audio object position to 'time_in_samples'. <em>[-]</em>
420
<p><dt><strong>ai-getpos, ai-get-position, ao-getpos, ao-get-position</strong><dd>
421
Returns the audio object position in seconds. <em>[f]</em>
423
<p><dt><strong>ai-get-position-samples, ao-get-position-samples</strong><dd>
424
Returns the audio object position in samples. <em>[li]</em>
426
<p><dt><strong>ai-get-length, ao-get-length</strong><dd>
427
Returns the audio object length in seconds. <em>[f]</em>
429
<p><dt><strong>ai-get-length-samples, ao-get-length-samples</strong><dd>
430
Returns the audio object length in samples. <em>[li]</em>
432
<p><dt><strong>ai-get-format, ao-get-format</strong><dd>
433
Returns the audio format of the selected audio input/output as a
434
formatted string. See documentation for '-f' command-line option. <em>[s]</em>
436
<p><dt><strong>ai-list, ao-list</strong><dd>
437
Returns a list of all input/output objects. <em>[S]</em>
439
<p><dt><strong>aio-register</strong><dd>
440
Prints a list of registered audio object types. <em>[s]</em>
442
<p><dt><strong>aio-status</strong><dd>
443
Audio object status (index strings, position, length, etc). <em>[s]</em>
447
<h2>CHAIN OPERATORS</h2>
448
Chain operators are used to process and analyze sample data.
449
They are attached to chains. If not otherwise stated,
450
currently selected chainsetup and chain are used. Also,
451
'chainop_id' and 'param_id' are used to select chain operators
452
and their parameters. First valid value for these parameters
456
<p><dt><strong>cop-add 'cop_format_string'</strong><dd>
457
Adds a new chain operator. In addition to normal chain operators,
458
this commmand can also be used to add effect presets and various
459
plugins. Note; it is not possible to add operators to multiple
460
chains at once. In other words only one chain should be selected
461
when issuing 'cop-add'. See ecasound (1) man page for more info. <em>[-]</em>
463
<p><dt><strong>cop-describe</strong><dd>
464
Returns a Ecasound Option Syntax (EOS) compliant string
465
describing the chain operator. See the Ecasound User's Guide
466
for more information about EOS. This command was introduced in
467
ecasound 2.4.4. <em>[s]</em>
469
<p><dt><strong>cop-remove</strong><dd>
470
Removes the selected chain operator. <em>[-]</em>
472
<p><dt><strong>cop-list</strong><dd>
473
Returns a list of all chain operators attached to the currently
474
selected chain. <em>[S]</em>
476
<p><dt><strong>cop-select 'param_id', cop-index-select 'param_id', cop-iselect 'param_id'</strong><dd>
477
Selects a chain operator. <em>[-]</em>
479
<p><dt><strong>cop-selected</strong><dd>
480
Returns the index number of currently selected chain operator. <em>[i]</em>
482
<p><dt><strong>cop-set 'chainop_id,param_id,value'</strong><dd>
483
Changes the value of a single chain operator parameter. Unlike other
484
chain operator commands, this can also be used during processing.
485
See also 'cop-get'. <em>[-]</em>
487
<p><dt><strong>cop-get 'chainop_id,param_id'</strong><dd>
488
Returns the current value of chain operator parameter identified by
489
'chainop_id' and 'param_id'. This command is a shorthand for
490
'cop-select chainop_id ; copp-iselect param_id ; copp-get'. <em>[f]</em>
492
<p><dt><strong>cop-status</strong><dd>
493
Returns info about chain operator status. <em>[s]</em>
495
<p><dt><strong>copp-list</strong><dd>
496
Returns a list of selected chain operator's parameters. <em>[S]</em>
498
<p><dt><strong>copp-select 'param_id', copp-index-select 'param_id', copp-iselect 'param_id'</strong><dd>
499
Selects a chain operator parameter. <em>[-]</em>
501
<p><dt><strong>copp-selected</strong><dd>
502
Returns the index number of currently selected chain operator parameter. <em>[i]</em>
504
<p><dt><strong>copp-set 'value'</strong><dd>
505
Sets the selected parameter value to 'value'. <em>[-]</em>
507
<p><dt><strong>copp-get</strong><dd>
508
Returns the selected parameter value. See also 'cop-get'. <em>[f]</em>
510
<p><dt><strong>cop-register</strong><dd>
511
Prints a list of registered chain operators. <em>[s]</em>
513
<p><dt><strong>preset-register</strong><dd>
514
Prints a list of registered effect presets. <em>[s]</em>
516
<p><dt><strong>ladspa-register</strong><dd>
517
Prints a list of registered LADSPA plugins. <em>[s]</em>
522
Controllers are used to control individual chain operator parameters.
523
They are attached to chains. If not otherwise stated, currently
524
selected chainsetup and chains are used.
526
<p><dt><strong>ctrl-add 'copc_format_string'</strong><dd>
527
Adds a new controller and attach it to currently selected chain
528
operator. The argument syntax is either "-<id_string>:par1,...,parN"
529
or just "<id_string>:par1,...,parN". If parameter itself contains
530
commas, the parameter should be enclosed in double-quotes.
531
See ecasound (1) man page for more info. <em>[-]</em>
533
<p><dt><strong>ctrl-describe</strong><dd>
534
Returns a Ecasound Option Syntax (EOS) compliant string
535
describing the controller. See the Ecasound User's Guide
536
for more information about EOS. This command was introduced in
537
ecasound 2.4.4. <em>[s]</em>
539
<p><dt><strong>ctrl-remove</strong><dd>
540
Removes the selected controller. <em>[-]</em>
542
<p><dt><strong>ctrl-list</strong><dd>
543
Returns a list of all controllers attached to the currently
544
selected chain. <em>[S]</em>
546
<p><dt><strong>ctrl-select 'param_id', ctrl-index-select 'param_id', ctrl-iselect 'param_id'</strong><dd>
547
Selects a controller. <em>[-]</em>
549
<p><dt><strong>ctrl-selected</strong><dd>
550
Returns the index number of currently selected controller. <em>[i]</em>
552
<p><dt><strong>ctrl-status</strong><dd>
553
Returns info about controller status. <em>[s]</em>
555
<p><dt><strong>ctrl-register</strong><dd>
556
Prints a list of registered controllers. <em>[s]</em>
558
<p><dt><strong>ctrl-get-target</strong><dd>
559
Returns the index number of the chain operator that is
560
connected to the selected controller. The returned index
561
refers to the currently selected chain (see 'cop-list'). <em>[i]</em>
563
<p><dt><strong>ctrlp-list</strong><dd>
564
Returns a list of all controller parameters. This command was introduced in
565
ecasound 2.4.2. <em>[S]</em>
567
<p><dt><strong>ctrlp-select</strong><dd>
568
Selects a controller parameter. This command was introduced in
569
ecasound 2.4.2. <em>[-]</em>
571
<p><dt><strong>ctrlp-selected</strong><dd>
572
Returns the index number of currently selected controller parameter. This command
573
was introduced in ecasound 2.4.2. <em>[i]</em>
575
<p><dt><strong>ctrlp-get</strong><dd>
576
Returns the selected controller parameter value. This command was introduced in
577
ecasound 2.4.2. <em>[f]</em>
579
<p><dt><strong>ctrlp-set</strong><dd>
580
Sets the selected controller parameter value to 'value'. This command was introduced in
581
ecasound 2.4.2. <em>[-]</em>
585
<h2>JACK CONNECTION MANAGEMENT</h2>
586
If Ecasound is compiled with support for <a href="http://jackaudio.org/">JACK audio server</a>,
587
the following set of commands is provided for controlling connections
592
<p><dt><strong>jack-connect 'src-port' 'dest-port'</strong><dd>
593
Make a connection between the two ports given as parameters. This command
594
is similar to the 'jack_connect' command line tool that is distributed
595
with JACK package. <em>[-]</em>
597
<p><dt><strong>jack-disconnect 'src-port' 'dest-port'</strong><dd>
598
Disconnect the two ports given as parameters. This command is similar
599
to the 'jack_disconnect' command line tool that is distributed
600
with JACK package. <em>[-]</em>
602
<p><dt><strong>jack-list-connections</strong><dd>
603
Returns a list of all JACK ports and a list of connections
604
for each port. This command is similar to the 'jack_lsp' command
605
line tool (e.g. 'jack_lsp -c') that is distributed with JACK package. <em>[s]</em>
609
<h2>INTERNAL COMMANDS</h2>
610
Internal commands are not directly aimed at normal use. They
611
are primarily meant for use in scripting and frontends.
614
<p><dt><strong>int-cmd-list</strong><dd>
615
Returns a list of all registered interactive mode commands. <em>[S]</em>
617
<p><dt><strong>int-log-history</strong><dd>
618
Returns recent log messages sent by libecasound modules. This
619
is a good tool for debugging ECI/EIAM scripts and applications. This
620
command was introduced in ecasound 2.4.0. <em>[s]</em>
622
<p><dt><strong>int-output-mode-wellformed</strong><dd>
623
Select the well-format output format for log messages. <em>[-]</em>
625
<p><dt><strong>int-set-float-to-string-precision</strong><dd>
626
Sets precision used in float to text conversions. Note that
627
this can be used to control the precision of float return values
628
for ECI commands. <em>[-]</em>
630
<p><dt><strong>int-set-log-history-length</strong><dd>
631
Sets the log history length. Defaults to 0 items.
632
This command was introduced in ecasound 2.4.0. <em>[-]</em>
634
<p><dt><strong>int-cmd-version-string</strong><dd>
635
Returns ecasound interactive mode parser version string. <em>[s]</em>
637
<p><dt><strong>int-cmd-version-lib-current</strong><dd>
638
Returns ecasound interactive mode library interface version (libtool). <em>[i]</em>
640
<p><dt><strong>int-cmd-version-lib-revision</strong><dd>
641
Returns ecasound interactive mode library interface revision (libtool). <em>[i]</em>
643
<p><dt><strong>int-cmd-version-lib-age</strong><dd>
644
Returns ecasound interactive mode library interface age (libtool). <em>[i]</em>
649
Object maps are central repositories for commonly used object types.
650
By querying the maps, applications can get a list of all registered
651
object types and their properties.
655
<p><dt><strong>map-cop-list</strong><dd>
656
Prints a list of registered chain operators using
657
the format specified in section <em>OPERATOR DESCRIPTIONS</em>. <em>[s]</em>
659
<p><dt><strong>map-preset-list</strong><dd>
660
Prints a list of registered effect presets using
661
the format specified in section <em>OPERATOR DESCRIPTIONS</em>. <em>[s]</em>
663
<p><dt><strong>map-ladspa-list</strong><dd>
664
Prints a list of registered LADSPA plugins using
665
the format specified in section <em>OPERATOR DESCRIPTIONS</em>. <em>[s]</em>
667
<p><dt><strong>map-ladspa-id-list</strong><dd>
668
Prints a list of registered LADSPA plugins using
669
the format specified in section <em>OPERATOR DESCRIPTIONS</em>.
670
Numerical LADPSA plugin identifiers are used. <em>[s]</em>
672
<p><dt><strong>map-ctrl-list</strong><dd>
673
Prints a list of registered controllers using
674
the format specified in section <em>OPERATOR DESCRIPTIONS</em>. <em>[s]</em>
678
<h2>DUMP COMMANDS</h2>
679
The following dump commands are not meant for normal use.
680
Their primary purpose is to provide an easy way to get
681
internal state information from libecasound. All dump
682
commands output a single line with syntax "key value"
683
to the selected output stream (defaults to stdout).
687
<p><dt><strong>dump-target 'filename'</strong><dd>
688
Set target stream for dumping. <em>[-]</em>
690
<p><dt><strong>dump-status</strong><dd>
691
Dumps engine status - 'running', 'stopped', 'finished' or 'notready'. <em>[-]</em>
693
<p><dt><strong>dump-position</strong><dd>
694
Dumps the global position. Printed in seconds using a floating-point
695
representation. <em>[-]</em>
697
<p><dt><strong>dump-length</strong><dd>
698
Dumps the overall processing length. Printed in seconds using a floating-point
699
representation. <em>[-]</em>
701
<p><dt><strong>dump-cs-status</strong><dd>
702
Dumps status string for the currently selected chainsetup - 'connected',
703
'selected' or an empty string. <em>[-]</em>
705
<p><dt><strong>dump-c-selected</strong><dd>
706
Dumps the name of currently selected chain. <em>[-]</em>
708
<p><dt><strong>dump-ai-selected</strong><dd>
709
Dumps label of currently selected audio input. If no input is
710
selected, dumps an empty string. <em>[-]</em>
712
<p><dt><strong>dump-ai-position</strong><dd>
713
Dumps position of currently selected audio inputs. Printed in
714
seconds, using a floating-point representation. <em>[-]</em>
716
<p><dt><strong>dump-ai-length</strong><dd>
717
Dumps length of currently selected audio input. Printed in seconds,
718
using a floating-point representation. <em>[-]</em>
720
<p><dt><strong>dump-ai-open-state</strong><dd>
721
Dumps audio input state info. Either 'open' or 'closed'. <em>[-]</em>
723
<p><dt><strong>dump-ao-selected</strong><dd>
724
Dumps label of currently selected audio output. If no output is
725
selected, dumps an empty string. <em>[-]</em>
727
<p><dt><strong>dump-ao-position</strong><dd>
728
Dumps position of currently selected audio outputs. Printed in
729
seconds, using a floating-point representation. <em>[-]</em>
731
<p><dt><strong>dump-ao-length</strong><dd>
732
Dumps length of currently selected audio output. Printed in seconds,
733
using a floating-point representation. <em>[-]</em>
735
<p><dt><strong>dump-ao-open-state</strong><dd>
736
Dumps audio output state info. Either 'open' or 'closed'. <em>[-]</em>
738
<p><dt><strong>dump-cop-value 'chainop,param'</strong><dd>
739
Dumps chain operator parameter value. 'chainop' and 'param' are
740
operator and parameter index values (1...n). <em>[-]</em>
744
<h2>OPERATOR DESCRIPTIONS</h2>
745
The <em>map-xxx-list</em> commands return a string containing all registered
746
objects of the given type <em>xxx</em>. Each line of the output describes
747
one registered type. The used syntax is:
749
'keyword,name,description,num_of_params,par1_def,par2_def,...'
751
<em>parX_def</em> describes one object parameter. This definition
752
is present for all parameters of the described object type.
755
'name,description,defaultvalue,upper_bound_flag,upper_bound,
756
lower_bound_flag,lower_bound,toggled_flag,integer_flag,
757
logarithmic_flag,output_flag'
759
For exact descriptions of these fields, please see
760
the header file <em>ecasound/libecasound/eca-operator.h</em>.
762
<h2>DEPRECATED COMMANDS</h2>
763
Use of following commands is deprecated. They still work in
764
current version of Ecasound, but will be dropped in
768
ai-wave-edit, ao-wave-edit
772
ecasound (1), ecatools (1), ecasoundrc (5)
775
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
