← Back to branch summary

~ubuntu-branches/ubuntu/saucy/ecasound2.2/saucy

« back to all changes in this revision

Viewing changes to Documentation/ecasound-iam.1

  • Committer: Bazaar Package Importer
  • Author(s): Junichi Uekawa
  • Date: 2008-03-23 21:42:49 UTC
  • mfrom: (3.1.6 hardy)
  • Revision ID: james.westby@ubuntu.com-20080323214249-evlfv3y1o8q747la
Tags: 2.4.6.1-2
http://bugs.debian.org/454890
* Bug fix: "FTBFS with GCC 4.3: missing #includes", thanks to Martin
  Michlmayr (Closes: #454890).
- 13_gcc4: updated

Show diffs side-by-side

added added

removed removed

Lines of Context:
Documentation/ecasound-iam.1
1
 
.TH "ecasound-iam" "1" "31\&.08\&.2005" "" "Multimedia software" 
 
1
.TH "ecasound-iam" "1" "13\&.08\&.2007" "" "Multimedia software"
 
2
 
2
3
.PP 
3
 
.SH "NAME" 
 
4
.SH "NAME"
4
5
ecasound-iam \- ecasound interactive mode
5
 
.SH "SYNOPSIS" 
 
6
.SH "SYNOPSIS"
 
7
 
6
8
.PP 
7
 
.SH "DESCRIPTION" 
 
9
.SH "DESCRIPTION"
 
10
 
8
11
.PP 
9
12
Ecasound library contains an interpreter module that understands 
10
13
a set of commands aimed at controlling various library services\&. 
11
14
This is called the ecasound interactive mode (EIAM)\&. All programs 
12
15
linked to ecasound library can use this facility\&.
13
16
.PP 
14
 
.SH "ECI API and return types" 
 
17
.SH "ECI API and return types"
15
18
A special case of EIAM use is ecasound\&'s control interface (ECI), 
16
19
which is a small library providing easy access to the EIAM 
17
20
commands from outside of libecasound\&. When issuing EIAM commands using 
24
27
When an EIAM results in an error, a error string explaining the 
25
28
condition is returned\&.
26
29
.PP 
27
 
.SH "Real-time commands" 
 
30
.SH "Real-time commands"
28
31
It\&'s not possible to use all EIAM commands to modify and control 
29
32
objects that belong to a connected chainsetup\&. Commands that
30
33
do support this are: \&'start\&', \&'stop\&', \&'setpos\&', \&'rewind\&', \&'forward\&',
38
41
In addition, most non-modifying (const) commands work with 
39
42
connected setups\&.
40
43
.PP 
41
 
.SH "GENERAL" 
42
 
.IP "quit, q" 
 
44
.SH "GENERAL"
 
45
.IP "quit, q"
43
46
Quit ecasound session\&. What this means in practice depends on the 
44
47
client (library throws an exception)\&. \fI[-]\fP
45
48
.IP 
46
 
.IP "start, t" 
47
 
Processing is started (play)\&. \fI[-]\fP
 
49
.IP "start, t"
 
50
Processing is started (play)\&. Error string is return if any errors upon 
 
51
startup are encountered\&. \fI[e]\fP
48
52
.IP 
49
 
.IP "stop, s" 
 
53
.IP "stop, s"
50
54
Stop processing\&. \fI[-]\fP
51
55
.IP 
52
 
.IP "run" 
53
 
Like \&'start\&' but blocks until processing is finished\&. \fI[-]\fP
 
56
.IP "run"
 
57
Like \&'start\&' but blocks until processing is finished\&. Error string
 
58
is return if any errors upon startup, or during process, are 
 
59
encountered\&. \fI[e]\fP
54
60
.IP 
55
 
.IP "debug \&'debug-level\&'" 
 
61
.IP "debug \&'debug-level\&'"
56
62
Set debug level to \&'debug-level\&'\&. Notice that client programs can
57
63
reimplement the debug routines\&. \fI[-]\fP
58
 
.PP 
59
 
.IP "help\&', \&'h\&'" 
 
64
 
 
65
.PP 
 
66
.IP "resource-file \&'path-to-file\&'"
 
67
Overrides the global and user resource files\&. Does not affect
 
68
already created objects\&. This command is equivalent to \&'-R\&' ecasound 
 
69
option (see ecasound (1) man page)\&. 
 
70
.PP 
 
71
.IP "-prefix:arg1,\&.\&.\&.,argN"
 
72
Equivalent to issuing \&'cs-option -prefix:arg1,\&.\&.\&.,argN)\&. See documentation
 
73
for \&'cs-option\&'\&.
 
74
.PP 
 
75
.IP "help\&', \&'h\&'"
60
76
Help! \fI[-]\fP
61
77
.PP 
62
 
.IP 
63
 
.SH "GLOBAL" 
64
 
.IP 
65
 
.PP 
66
 
.IP "engine-status" 
 
78
.SH "GLOBAL"
 
79
 
 
80
.IP 
 
81
.IP "engine-status"
67
82
Returns a string describing the engine status (running, stopped,
68
83
finished, error, not ready)\&. See also \fIcs-status\fP\&. \fI[s]\fP
69
84
.PP 
70
 
.IP "engine-launch" 
 
85
.IP "engine-launch"
71
86
Initializes and starts the engine\&. Doesn\&'t start the actual
72
87
processing\&. See also \fIstart\fP\&. \fI[-]\fP
73
88
.PP 
74
 
.IP "engine-halt" 
 
89
.IP "engine-halt"
75
90
Stops the engine\&. Does not disconnect the chainsetup that 
76
91
was running\&. See also \fIstop\fP\&. \fI[-]\fP
77
92
.PP 
78
 
.IP 
79
 
.SH "CHAINSETUPS" 
 
93
.SH "CHAINSETUPS"
80
94
Chainsetup is the central data object\&. All other objects (inputs,
81
95
outputs, chains, etc) are connected to some chainsetup\&. There can be 
82
96
many chainsetups but only one can be connected\&. Similarly only
84
98
are done on the selected chainsetup\&. Some operations also require
85
99
that selected chainsetup is not connected\&.
86
100
.IP 
87
 
.IP "cs-add \&'name\&'" 
 
101
.IP "cs-add \&'name\&'"
88
102
Adds a new chainsetup with name \&'name\&'\&. \&'name\&' is now 
89
103
the selected chainsetup\&. \fI[-]\fP
90
104
.PP 
91
 
.IP "cs-remove" 
 
105
.IP "cs-remove"
92
106
Removes currently selected chainsetup\&. \fI[-]\fP
93
107
.PP 
94
 
.IP "cs-list" 
 
108
.IP "cs-list"
95
109
Returns a list of all chainsetups\&. \fI[S]\fP
96
110
.PP 
97
 
.IP "cs-select \&'name\&'" 
 
111
.IP "cs-select \&'name\&'"
98
112
Selects chainsetup \&'name\&'\&. \fI[-]\fP
99
113
.PP 
100
 
.IP "cs-selected" 
 
114
.IP "cs-selected"
101
115
Returns the name of currently selected chainsetup\&. \fI[s]\fP
102
116
.PP 
103
 
.IP "cs-index-select \&'cs_index\&', cs-iselect \&'cs_index\&'" 
 
117
.IP "cs-index-select \&'cs_index\&', cs-iselect \&'cs_index\&'"
104
118
Selects a chainsetup based on a short index string\&. Chainsetup names
105
119
can be rather long\&. This command can be used to avoid typing
106
120
these long names\&. \&'cs_index\&' is an integer value, where \&'1\&' refers to 
107
121
the first audio input/output\&. You can use \&'cs-list\&' and \&'cs-status\&' 
108
122
to get a full list of currently available chainsetups\&. \fI[-]\fP
109
123
.PP 
110
 
.IP "cs-load \&'filename\&'" 
 
124
.IP "cs-load \&'filename\&'"
111
125
Adds a new chainsetup by loading it from file \&'filename\&'\&. 
112
126
\&'filename\&' is now the selected chainsetup\&. \fI[-]\fP
113
127
.PP 
114
 
.IP "cs-save" 
 
128
.IP "cs-save"
115
129
Saves the currently selected chainsetup to file\&. If chainsetup was loaded
116
130
from a file, the saved version will replace the original\&. If it doesn\&'t 
117
131
have a default filename, it\&'s saved to "chainsetup_name\&.ecs"\&. \fI[-]\fP
118
132
.PP 
119
 
.IP "cs-save-as \&'filename\&'" 
 
133
.IP "cs-save-as \&'filename\&'"
120
134
Saves currently selected chainsetup to file \&'filename\&'\&. \fI[-]\fP
121
135
.PP 
122
 
.IP "cs-edit" 
 
136
.IP "cs-edit"
123
137
Currently selected chainsetup is saved to a temporary file\&. This
124
 
file is loaded to an external editor (see ecasoundrc(5))\&. After
 
138
file is loaded to an external editor (see ecasoundrc (5))\&. After
125
139
editing, the chainsetup is loaded back to ecasound\&. \fI[-]\fP
126
140
.PP 
127
 
.IP "cs-is-valid" 
 
141
.IP "cs-is-valid"
128
142
Whether currently selected chainsetup is valid (=can be connected)? \fI[i]\fP
129
143
.PP 
130
 
.IP "cs-connect" 
 
144
.IP "cs-connect"
131
145
Connect currently selected chainsetup to engine\&. Only one chainsetup
132
 
can be connected at a time\&. \fI[-]\fP
 
146
can be connected at a time\&. Error string is returned if connection 
 
147
fails\&. \fI[e]\fP
133
148
.PP 
134
 
.IP "cs-disconnect" 
 
149
.IP "cs-disconnect"
135
150
Disconnect currently connected chainsetup\&. \fI[-]\fP
136
151
.PP 
137
 
.IP "cs-connected" 
 
152
.IP "cs-connected"
138
153
Returns the name of currently connected chainsetup\&. \fI[s]\fP
139
154
.PP 
140
 
.IP "cs-rewind \&'time-in-seconds\&', rewind \&'time-in-seconds\&', rw \&'time-in-seconds\&'" 
 
155
.IP "cs-rewind \&'time-in-seconds\&', rewind \&'time-in-seconds\&', rw \&'time-in-seconds\&'"
141
156
Rewinds the current chainsetup position by \&'time-in-seconds\&' seconds\&.
142
157
Position of all inputs and outputs attached to the selected chainsetup
143
158
is also affected\&. \fI[-]\fP
144
159
.PP 
145
 
.IP "cs-forward \&'time-in-seconds\&', forward \&'time-in-seconds\&', fw \&'ttime-in-seconds\&'" 
 
160
.IP "cs-forward \&'time-in-seconds\&', forward \&'time-in-seconds\&', fw \&'ttime-in-seconds\&'"
146
161
The current chainsetup position is forwarded by \&'time-in-seconds\&'
147
162
seconds\&. Position of all inputs and outputs attached to the selected chainsetup
148
163
is also affected\&. \fI[-]\fP
149
164
.PP 
150
 
.IP "cs-set-position \&'time-in-seconds\&', cs-setpos \&'time-in-seconds\&', setpos \&'time-in-seconds\&', set-position \&'time-in-seconds\&'" 
 
165
.IP "cs-set-position \&'time-in-seconds\&', cs-setpos \&'time-in-seconds\&', setpos \&'time-in-seconds\&', set-position \&'time-in-seconds\&'"
151
166
Sets the chainsetup position to \&'time-in-seconds\&' seconds from the 
152
167
beginning\&. Position of all inputs and outputs attached to the selected 
153
168
chainsetup is also affected\&. \fI[-]\fP
154
169
.PP 
155
 
.IP "cs-set-position-samples \&'time-in-samples\&'" 
 
170
.IP "cs-set-position-samples \&'time-in-samples\&'"
156
171
Sets the chainsetup position to \&'time-in-samples\&' samples from the 
157
172
beginning\&. Position of all inputs and outputs attached to the selected 
158
173
chainsetup is also affected\&. \fI[-]\fP
159
174
.PP 
160
 
.IP "cs-get-position, cs-getpos, getpos, get-position" 
 
175
.IP "cs-get-position, cs-getpos, getpos, get-position"
161
176
Returns the current chainsetup position in seconds\&. \fI[f]\fP
162
177
.PP 
163
 
.IP "cs-get-position-samples" 
 
178
.IP "cs-get-position-samples"
164
179
Returns the current chainsetup position in samples\&. \fI[li]\fP
165
180
.PP 
166
 
.IP "cs-get-length, get-length" 
 
181
.IP "cs-get-length, get-length"
167
182
Returns the chainsetup length in seconds (if known)\&. \fI[f]\fP
168
183
.PP 
169
 
.IP "cs-get-length-samples, get-length-samples" 
 
184
.IP "cs-get-length-samples, get-length-samples"
170
185
Returns the chainsetup length in samples (if known)\&. \fI[li]\fP
171
186
.PP 
172
 
.IP "cs-set-length \&'seconds\&'" 
 
187
.IP "cs-set-length \&'seconds\&'"
173
188
Sets processing time in seconds (doesn\&'t have to be an integer value)\&. 
174
189
A special-case value of \&'-1\&' will set the chainsetup length 
175
190
according to the longest input object\&. \fI[-]\fP
176
191
.PP 
177
 
.IP "cs-set-length-samples \&'samples\&'" 
 
192
.IP "cs-set-length-samples \&'samples\&'"
178
193
Sets processing time in samples\&. \fI[-]\fP
179
194
.PP 
180
 
.IP "cs-toggle-loop" 
 
195
.IP "cs-toggle-loop"
181
196
Toggle looping\&. When processing is finished, engine will start 
182
197
again from the initial position\&. It\&'s not always possible to enable looping
183
198
(for instance all inputs and outputs have infinite length and
184
199
chainsetup length is not explicitly set with \&'cs-set-length\&')\&. \fI[-]\fP
185
200
.PP 
186
 
.IP "cs-set-param" 
 
201
.IP "cs-set-param"
187
202
Interpret general chainsetup parameters like for example
188
 
"-b" (buffersize), "-n" (name), etc\&. See ecasound(1) for 
 
203
"-b" (buffersize), "-n" (name), etc\&. See ecasound (1) for 
189
204
more info\&. \fI[-]\fP
190
205
.PP 
191
 
.IP "cs-set-audio-format \&'bits,channels,sample_rate\&'" 
 
206
.IP "cs-set-audio-format \&'bits,channels,sample_rate\&'"
192
207
Set the default sample parameters for currently selected chainsetup\&. 
193
208
For example cd-quality audio would be "16,2,44100"\&. This does the
194
 
same as command-line argument "-f" (see ecasound(1))\&. \fI[-]\fP
 
209
same as command-line argument "-f" (see ecasound (1))\&. \fI[-]\fP
195
210
.PP 
196
 
.IP "cs-status, status, st" 
 
211
.IP "cs-status, status, st"
197
212
Print status info about all chainsetups\&. \fI[s]\fP
198
213
.PP 
199
 
.IP "cs-option \&'-prefix:arg1,\&.\&.\&.,argN\&'" 
 
214
.IP "cs-option \&'-prefix:arg1,\&.\&.\&.,argN\&'"
200
215
One powerful feature of the interactive-mode is that it
201
216
provides full access to ecasound\&'s command-line syntax\&. 
202
217
For instance, command "cs-option -efb:400,200" means that 
204
219
chain, with initial parameters 400 (center frequency) 
205
220
and 200 (width in Hz)\&.
206
221
.PP 
 
222
Note that session level options (such as setting debug level)
 
223
can not be used with \&'cs-option\&' (i\&.e\&. only options that modify
 
224
chainsetups)\&.
 
225
.PP 
207
226
Note! EIAM implicitly interprets all strings beginning 
208
227
with a \&'-\&' as "cs-option string"\&.
 
228
 
209
229
.IP 
210
 
.SH "CHAINS" 
 
230
.SH "CHAINS"
211
231
Chain is a simple signal flow abstraction\&. Every chain has one input
212
232
and one output\&. All chain operators and their controllers are attached
213
233
to chains\&. Chains can be muted, unmuted and be bypassed\&. If not 
214
234
otherwise stated, all operations are done to currently selected
215
235
chainsetup\&.
216
236
.IP 
217
 
.IP "c-add \&'cname1,\&.\&.\&.,cnameN\&'" 
 
237
.IP "c-add \&'cname1,\&.\&.\&.,cnameN\&'"
218
238
Adds a set of chains\&. Added chains are automatically selected\&. Note
219
239
that commas in chain names are not allowed\&. \fI[-]\fP
220
240
.PP 
221
 
.IP "c-remove" 
 
241
.IP "c-remove"
222
242
Removes selected chains\&. \fI[-]\fP
223
243
.PP 
224
 
.IP "c-list" 
 
244
.IP "c-list"
225
245
Returns a list of all chains\&. \fI[S]\fP
226
246
.PP 
227
 
.IP "c-select \&'cname1,\&.\&.\&.,cnameN\&'" 
 
247
.IP "c-select \&'cname1,\&.\&.\&.,cnameN\&'"
228
248
Selects chains\&. Other chains are automatically deselected\&. \fI[-]\fP
229
249
.PP 
230
 
.IP "c-index-select \&'index1,\&.\&.\&.,indexN\&', c-iselect \&'index1,\&.\&.\&.,indexN\&'" 
 
250
.IP "c-index-select \&'index1,\&.\&.\&.,indexN\&', c-iselect \&'index1,\&.\&.\&.,indexN\&'"
231
251
Selects a set of chains based on the list of indixes\&. Each index is
232
252
an integer value, where \&'1\&' refers to the first chain\&. You can use 
233
253
\&'c-list\&' and \&'c-status\&' to get a full list of currently available 
234
254
chains\&. \fI[-]\fP
235
255
.PP 
236
 
.IP "c-select-all" 
 
256
.IP "c-select-all"
237
257
Selects all chains\&. \fI[-]\fP
238
258
.PP 
239
 
.IP "c-select-add \&'cname1,\&.\&.\&.,cnameN\&'" 
 
259
.IP "c-select-add \&'cname1,\&.\&.\&.,cnameN\&'"
240
260
Selects more chains\&. \fI[-]\fP
241
261
.PP 
242
 
.IP "c-deselect \&'cname1,\&.\&.\&.,cnameN\&'" 
 
262
.IP "c-deselect \&'cname1,\&.\&.\&.,cnameN\&'"
243
263
Deselects chains\&. \fI[-]\fP
244
264
.PP 
245
 
.IP "c-selected" 
 
265
.IP "c-selected"
246
266
Returns a list of selected chains\&. \fI[S]\fP
247
267
.PP 
248
 
.IP "c-clear" 
 
268
.IP "c-clear"
249
269
Clear selected chains by removing all chain operators and controllers\&.
250
270
Doesn\&'t change how chains are connected to inputs and outputs\&. \fI[-]\fP
251
271
.PP 
252
 
.IP "c-rename \&'new_name\&'" 
 
272
.IP "c-rename \&'new_name\&'"
253
273
Renames the selected chain\&. When using this command, exactly one chain must
254
274
be selected\&. \fI[-]\fP
255
275
.PP 
256
 
.IP "c-muting" 
 
276
.IP "c-muting"
257
277
Toggle chain muting\&. When chain is muted, all data that goes through
258
278
is muted\&. \fI[-]\fP
259
279
.PP 
260
 
.IP "c-mute" 
 
280
.IP "c-mute"
261
281
Toggle chain muting\&. Note! Deprecated, use \fIc-muting\fP instead\&. \fI[-]\fP
262
282
.PP 
263
 
.IP "c-bypass" 
 
283
.IP "c-bypass"
264
284
Toggle chain bypassing\&. When chain is bypassed, sample data is passed 
265
285
through untouched\&. \fI[-]\fP
266
286
.PP 
267
 
.IP "c-status, cs" 
 
287
.IP "c-status, cs"
268
288
Print status info about all chains\&. \fI[s]\fP
269
289
.PP 
270
 
.IP 
271
 
.SH "AUDIO INPUT/OUTPUT OBJECTS" 
 
290
.SH "AUDIO INPUT/OUTPUT OBJECTS"
272
291
If not otherwise stated, all operations are done to currently selected
273
292
object\&. All commands with \fIai-\fP prefix operate on audio inputs,
274
293
while commands with \fIao-\fP operate on outputs\&.
275
294
.IP 
276
 
.PP 
277
 
.IP "ai-add \&'input_format_string\&'" 
278
 
Adds a new input object\&. See ecasound(1) man page for more info about 
279
 
the argument format (\&'-i\&' option)\&. \fI[-]\fP
280
 
.PP 
281
 
.IP "ao-add \&'output_format_string\&'" 
282
 
Adds a new output object\&. See ecasound(1) man page for more info about 
 
295
.IP "ai-add \&'input_format_string\&'"
 
296
Adds a new input object\&. See ecasound (1) man page for more info about 
 
297
the argument format (\&'-i\&' option)\&. Note on syntax: if any of 
 
298
the parameters (such as a filename) contains commas, the parameter 
 
299
should be enclosed in double-quotes\&. \fI[-]\fP
 
300
.PP 
 
301
.IP "ao-add \&'output_format_string\&'"
 
302
Adds a new output object\&. See ecasound (1) man page for more info about 
283
303
the argument format (\&'-o\&' option)\&. If argument is omitted, 
284
 
a default output device is added (see ecasoundrc(5))\&. \fI[-]\fP
285
 
.PP 
286
 
.IP "ao-add-default" 
287
 
Adds the default output device (see ecasoundrc(5))\&. \fI[-]\fP
288
 
.PP 
289
 
.IP "ai-describe, ao-describe" 
 
304
a default output device is added (see ecasoundrc (5))\&. Note on syntax: if any 
 
305
of the parameters (such as a filename) contains commas, the parameter 
 
306
should be enclosed in double-quotes\&. \fI[-]\fP
 
307
.PP 
 
308
.IP "ao-add-default"
 
309
Adds the default output device (see ecasoundrc (5))\&. \fI[-]\fP
 
310
.PP 
 
311
.IP "ai-describe, ao-describe"
290
312
Returns a Ecasound Option Syntax (EOS) compliant string
291
313
describing the input/output\&. See the Ecasound User\&'s Guide
292
 
for more information about EOS\&. \fI[s]\fP
 
314
for more information about EOS\&. This command was introduced in 
 
315
ecasound 2\&.4\&.4\&. \fI[s]\fP
293
316
.PP 
294
 
.IP "ai-select \&'aobject_name\&', ao-select \&'aobject_name\&'" 
 
317
.IP "ai-select \&'aobject_name\&', ao-select \&'aobject_name\&'"
295
318
Selects an audio object\&. \&'aobject_name\&' refers to the string
296
 
used when creating the object (see above)\&. Note! All input
297
 
object names are required to be unique\&. Similarly all output
298
 
names need to be unique\&. However, it\&'s possible that the same
299
 
object name exists both as an input and as an output\&. \fI[-]\fP
 
319
used when creating the object (the first argument given to ai-add/ao-add)\&. 
 
320
Note that as a important difference to ai-add/ao-add, one should not 
 
321
enclose the object name in double quotes for ai-select/ao-select\&. In the 
 
322
case a chainsetup contains multiple inputs, or outputs, with 
 
323
identical name, \&'ai-select\&' and \&'ao-select\&' will select 
 
324
the first matching instance\&. In order to select a specific
 
325
instance, the \&'ai-iselect\&' and \&'ao-iselect\&' commands need to 
 
326
be used\&. \fI[-]\fP
300
327
.PP 
301
 
.IP "ai-index-select \&'aobject_index\&', ai-iselect \&'aobject_index\&', ao-index-select \&'aobject_index\&', ao-iselect \&'aobject_index\&'" 
 
328
.IP "ai-index-select \&'aobject_index\&', ai-iselect \&'aobject_index\&', ao-index-select \&'aobject_index\&', ao-iselect \&'aobject_index\&'"
302
329
Select some audio object based on a short index string\&. Especially file
303
330
names can be rather long\&. This command can be used to avoid typing
304
331
these long names when selecting audio objects\&. \&'aobject_index\&' is
306
333
You can use \&'ai-list\&' and \&'ao-list\&' to get a full list of currently
307
334
available inputs/outputs\&. \fI[-]\fP
308
335
.PP 
309
 
.IP "ai-selected, ao-selected" 
 
336
.IP "ai-selected, ao-selected"
310
337
Returns the name of the currently selected audio object\&. \fI[s]\fP
311
338
.PP 
312
 
.IP "ai-attach, ao-attach" 
 
339
.IP "ai-attach, ao-attach"
313
340
Attaches the currently selected audio object to all selected chains\&. \fI[-]\fP
314
341
.PP 
315
 
.IP "ai-remove, ao-remove" 
 
342
.IP "ai-remove, ao-remove"
316
343
Removes the currently selected audio object from the chainsetup\&. \fI[-]\fP
317
344
.PP 
318
 
.IP "ai-forward \&'time_in_seconds\&', ai-fw \&'time_in_seconds\&', ao-forward \&'time_in_seconds\&', ao-fw \&'time_in_seconds\&'" 
 
345
.IP "ai-forward \&'time_in_seconds\&', ai-fw \&'time_in_seconds\&', ao-forward \&'time_in_seconds\&', ao-fw \&'time_in_seconds\&'"
319
346
Selected audio object is forwarded by \&'time-in-seconds\&' seconds\&. 
320
347
Time should be given as a floating point value (eg\&. 0\&.001 is the 
321
348
same as 1ms)\&. \fI[-]\fP
322
349
.PP 
323
 
.IP "ai-rewind \&'time_in_seconds\&', ai-rw \&'time_in_seconds\&', ao-rewind \&'time_in_seconds\&', ao-rw \&'time_in_seconds\&'" 
 
350
.IP "ai-rewind \&'time_in_seconds\&', ai-rw \&'time_in_seconds\&', ao-rewind \&'time_in_seconds\&', ao-rw \&'time_in_seconds\&'"
324
351
Selected audio object is rewinded by \&'time-in-seconds\&' seconds\&. 
325
352
Time should be given as a floating point value (eg\&. 0\&.001 is the 
326
353
same as 1ms)\&. \fI[-]\fP
327
354
.PP 
328
 
.IP "ai-setpos \&'time_in_seconds\&', ai-set-position \&'time_in_seconds\&', ao-setpos \&'time_in_seconds\&', ao-set-position \&'time_in_seconds\&'" 
 
355
.IP "ai-setpos \&'time_in_seconds\&', ai-set-position \&'time_in_seconds\&', ao-setpos \&'time_in_seconds\&', ao-set-position \&'time_in_seconds\&'"
329
356
Set audio object position to \&'time_in_seconds\&'\&. \fI[-]\fP
330
357
.PP 
331
 
.IP "ai-set-position-samples \&'time_in_samples\&', ao-set-position-samples \&'time_in_samples\&'" 
 
358
.IP "ai-set-position-samples \&'time_in_samples\&', ao-set-position-samples \&'time_in_samples\&'"
332
359
Set audio object position to \&'time_in_samples\&'\&. \fI[-]\fP
333
360
.PP 
334
 
.IP "ai-getpos, ai-get-position, ao-getpos, ao-get-position" 
 
361
.IP "ai-getpos, ai-get-position, ao-getpos, ao-get-position"
335
362
Returns the audio object position in seconds\&. \fI[f]\fP
336
363
.PP 
337
 
.IP "ai-get-position-samples, ao-get-position-samples" 
 
364
.IP "ai-get-position-samples, ao-get-position-samples"
338
365
Returns the audio object position in samples\&. \fI[li]\fP
339
366
.PP 
340
 
.IP "ai-get-length, ao-get-length" 
 
367
.IP "ai-get-length, ao-get-length"
341
368
Returns the audio object length in seconds\&. \fI[f]\fP
342
369
.PP 
343
 
.IP "ai-get-length-samples, ao-get-length-samples" 
 
370
.IP "ai-get-length-samples, ao-get-length-samples"
344
371
Returns the audio object length in samples\&. \fI[li]\fP
345
372
.PP 
346
 
.IP "ai-get-format, ao-get-format" 
 
373
.IP "ai-get-format, ao-get-format"
347
374
Returns the audio format of the selected audio input/output as a
348
375
formatted string\&. See documentation for \&'-f\&' command-line option\&. \fI[s]\fP
349
376
.PP 
350
 
.IP "ai-wave-edit, ao-wave-edit" 
 
377
.IP "ai-wave-edit, ao-wave-edit"
351
378
The currently selected audio object is loaded into an external
352
 
wave editor (see ecasoundrc(5))\&. \fI[-]\fP
 
379
wave editor (see ecasoundrc (5))\&. \fI[-]\fP
353
380
.PP 
354
 
.IP "ai-list, ao-list" 
 
381
.IP "ai-list, ao-list"
355
382
Returns a list of all input/output objects\&. \fI[S]\fP
356
383
.PP 
357
 
.IP "aio-register" 
 
384
.IP "aio-register"
358
385
Prints a list of registered audio object types\&. \fI[s]\fP
359
386
.PP 
360
 
.IP "aio-status" 
 
387
.IP "aio-status"
361
388
Audio object status (index strings, position, length, etc)\&. \fI[s]\fP
362
389
.PP 
363
 
.IP 
364
 
.SH "CHAIN OPERATORS" 
 
390
.SH "CHAIN OPERATORS"
365
391
Chain operators are used to process and analyze sample data\&.
366
392
They are attached to chains\&. If not otherwise stated,
367
393
currently selected chainsetup and chain are used\&. Also, 
369
395
and their parameters\&. First valid value for these parameters 
370
396
is 1\&.
371
397
.IP 
372
 
.IP "cop-add \&'cop_format_string\&'" 
373
 
Adds a new chain operator\&. Argument format is
374
 
"-<id_string>:par1,\&.\&.\&.,parN"\&. In addition to normal chain operators, 
 
398
.IP "cop-add \&'cop_format_string\&'"
 
399
Adds a new chain operator\&. In addition to normal chain operators, 
375
400
this commmand can also be used to add effect presets and various 
376
401
plugins\&. Note; it is not possible to add operators to multiple
377
402
chains at once\&. In other words only one chain should be selected
378
 
when issuing \&'cop-add\&'\&. See ecasound(1) man page for more 
379
 
info\&. \fI[-]\fP
 
403
when issuing \&'cop-add\&'\&. Argument format is 
 
404
"-<id_string>:par1,\&.\&.\&.,parN" (if parameter itself contains commas,
 
405
the parameter should be enclosed in double-quotes)\&. See 
 
406
ecasound (1) man page for more info\&. \fI[-]\fP
380
407
.PP 
381
 
.IP "cop-describe" 
 
408
.IP "cop-describe"
382
409
Returns a Ecasound Option Syntax (EOS) compliant string
383
410
describing the chain operator\&. See the Ecasound User\&'s Guide
384
 
for more information about EOS\&. \fI[s]\fP
 
411
for more information about EOS\&. This command was introduced in 
 
412
ecasound 2\&.4\&.4\&. \fI[s]\fP
385
413
.PP 
386
 
.IP "cop-remove" 
 
414
.IP "cop-remove"
387
415
Removes the selected chain operator\&. \fI[-]\fP
388
416
.PP 
389
 
.IP "cop-list" 
 
417
.IP "cop-list"
390
418
Returns a list of all chain operators attached to the currently
391
419
selected chain\&. \fI[S]\fP
392
420
.PP 
393
 
.IP "cop-select \&'param_id\&', cop-index-select \&'param_id\&', cop-iselect \&'param_id\&'" 
 
421
.IP "cop-select \&'param_id\&', cop-index-select \&'param_id\&', cop-iselect \&'param_id\&'"
394
422
Selects a chain operator\&. \fI[-]\fP
395
423
.PP 
396
 
.IP "cop-selected" 
 
424
.IP "cop-selected"
397
425
Returns the index number of currently selected chain operator\&. \fI[i]\fP
398
426
.PP 
399
 
.IP "cop-set \&'chainop_id, param_id, value\&'" 
 
427
.IP "cop-set \&'chainop_id, param_id, value\&'"
400
428
Changes the value of a single chain operator parameter\&. Unlike other
401
429
chain operator commands, this can also be used during processing\&. \fI[-]\fP
402
430
.PP 
403
 
.IP "cop-status" 
 
431
.IP "cop-status"
404
432
Returns info about chain operator status\&. \fI[s]\fP
405
433
.PP 
406
 
.IP "copp-list" 
 
434
.IP "copp-list"
407
435
Returns a list of selected chain operator\&'s parameters\&. \fI[S]\fP
408
436
.PP 
409
 
.IP "copp-select \&'param_id\&', copp-index-select \&'param_id\&', copp-iselect \&'param_id\&'" 
 
437
.IP "copp-select \&'param_id\&', copp-index-select \&'param_id\&', copp-iselect \&'param_id\&'"
410
438
Selects a chain operator parameter\&. \fI[-]\fP
411
439
.PP 
412
 
.IP "copp-selected" 
 
440
.IP "copp-selected"
413
441
Returns the index number of currently selected chain operator parameter\&. \fI[i]\fP
414
442
.PP 
415
 
.IP "copp-set \&'value\&'" 
 
443
.IP "copp-set \&'value\&'"
416
444
Sets the selected parameter value to \&'value\&'\&. \fI[-]\fP
417
445
.PP 
418
 
.IP "copp-get" 
 
446
.IP "copp-get"
419
447
Returns the selected parameter value\&. \fI[f]\fP
420
448
.PP 
421
 
.IP "cop-register" 
 
449
.IP "cop-register"
422
450
Prints a list of registered chain operators\&. \fI[s]\fP
423
451
.PP 
424
 
.IP "preset-register" 
 
452
.IP "preset-register"
425
453
Prints a list of registered effect presets\&. \fI[s]\fP
426
454
.PP 
427
 
.IP "ladspa-register" 
 
455
.IP "ladspa-register"
428
456
Prints a list of registered LADSPA plugins\&. \fI[s]\fP
429
457
.PP 
430
 
.IP 
431
 
.SH "CONTROLLERS" 
 
458
.SH "CONTROLLERS"
432
459
Controllers are used to control individual chain operator parameters\&.
433
460
They are attached to chains\&. If not otherwise stated, currently 
434
461
selected chainsetup and chains are used\&. 
435
462
.IP 
436
 
.IP "ctrl-add \&'copc_format_string\&'" 
 
463
.IP "ctrl-add \&'copc_format_string\&'"
437
464
Adds a new controller and attach it to currently selected chain 
438
465
operator\&. Argument format is "-<id_string>:<param_id>,<range_low>,
439
 
<range_high>,par1,\&.\&.\&.,parN"\&.  See ecasound(1) man page for more 
440
 
info\&. \fI[-]\fP
 
466
<range_high>,par1,\&.\&.\&.,parN" (if parameter itself contains commas,
 
467
the parameter should be enclosed in double-quotes)\&.  See ecasound (1) 
 
468
man page for more info\&. \fI[-]\fP
441
469
.IP 
442
 
.IP "ctrl-describe" 
 
470
.IP "ctrl-describe"
443
471
Returns a Ecasound Option Syntax (EOS) compliant string
444
472
describing the controller\&. See the Ecasound User\&'s Guide
445
 
for more information about EOS\&. \fI[s]\fP
 
473
for more information about EOS\&. This command was introduced in 
 
474
ecasound 2\&.4\&.4\&. \fI[s]\fP
446
475
.IP 
447
 
.IP "ctrl-remove" 
 
476
.IP "ctrl-remove"
448
477
Removes the selected controller\&. \fI[-]\fP
449
478
.IP 
450
 
.IP "ctrl-list" 
 
479
.IP "ctrl-list"
451
480
Returns a list of all controllers attached to the currently
452
481
selected chain\&. \fI[S]\fP
453
482
.IP 
454
 
.IP "ctrl-select \&'param_id\&', ctrl-index-select \&'param_id\&', ctrl-iselect \&'param_id\&'" 
 
483
.IP "ctrl-select \&'param_id\&', ctrl-index-select \&'param_id\&', ctrl-iselect \&'param_id\&'"
455
484
Selects a controller\&. \fI[-]\fP
456
485
.IP 
457
 
.IP "ctrl-selected" 
 
486
.IP "ctrl-selected"
458
487
Returns the index number of currently selected controller\&. \fI[i]\fP
459
488
.IP 
460
 
.IP "ctrl-status" 
 
489
.IP "ctrl-status"
461
490
Returns info about controller status\&. \fI[s]\fP
462
491
.IP 
463
 
.IP "ctrl-register" 
 
492
.IP "ctrl-register"
464
493
Prints a list of registered controllers\&. \fI[s]\fP
465
494
.IP 
466
 
.IP "ctrl-get-target" 
 
495
.IP "ctrl-get-target"
467
496
Returns the index number of the chain operator that is
468
497
connected to the selected controller\&. The returned index 
469
498
refers to the currently selected chain (see \&'cop-list\&')\&. \fI[i]\fP
470
499
.IP 
471
 
.IP "ctrlp-list" 
472
 
Returns a list of all controller parameters\&. \fI[S]\fP
473
 
.IP 
474
 
.IP "ctrlp-select" 
475
 
Selects a controller parameter\&. \fI[-]\fP
476
 
.IP 
477
 
.IP "ctrlp-selected" 
478
 
Returns the index number of currently selected controller parameter\&. \fI[i]\fP
479
 
.IP 
480
 
.IP "ctrlp-get" 
481
 
Returns the selected controller parameter value\&. \fI[f]\fP
482
 
.IP 
483
 
.IP "ctrlp-set" 
484
 
Sets the selected controller parameter value to \&'value\&'\&. \fI[-]\fP
485
 
.IP 
486
 
.IP 
487
 
.SH "INTERNAL COMMANDS" 
 
500
.IP "ctrlp-list"
 
501
Returns a list of all controller parameters\&. This command was introduced in 
 
502
ecasound 2\&.4\&.2\&. \fI[S]\fP
 
503
.IP 
 
504
.IP "ctrlp-select"
 
505
Selects a controller parameter\&. This command was introduced in 
 
506
ecasound 2\&.4\&.2\&. \fI[-]\fP
 
507
.IP 
 
508
.IP "ctrlp-selected"
 
509
Returns the index number of currently selected controller parameter\&. This command 
 
510
was introduced in ecasound 2\&.4\&.2\&. \fI[i]\fP
 
511
.IP 
 
512
.IP "ctrlp-get"
 
513
Returns the selected controller parameter value\&. This command was introduced in 
 
514
ecasound 2\&.4\&.2\&. \fI[f]\fP
 
515
.IP 
 
516
.IP "ctrlp-set"
 
517
Sets the selected controller parameter value to \&'value\&'\&. This command was introduced in 
 
518
ecasound 2\&.4\&.2\&. \fI[-]\fP
 
519
.IP 
 
520
.SH "INTERNAL COMMANDS"
488
521
Internal commands are not directly aimed at normal use\&. They
489
522
are primarily meant for use in scripting and frontends\&.
490
523
.IP 
491
 
.IP "int-cmd-list" 
 
524
.IP "int-cmd-list"
492
525
Returns a list of all registered EIAM commands\&. \fI[S]\fP
493
526
.IP 
494
 
.IP "int-log-history" 
 
527
.IP "int-log-history"
495
528
Returns recent log messages sent by libecasound modules\&. This
496
 
is a good tool for debugging ECI/EIAM scripts and applications\&. \fI[s]\fP
 
529
is a good tool for debugging ECI/EIAM scripts and applications\&. This 
 
530
command was introduced in ecasound 2\&.4\&.0\&. \fI[s]\fP
497
531
.IP 
498
 
.IP "int-output-mode-wellformed" 
 
532
.IP "int-output-mode-wellformed"
499
533
Select the well-format output format for log messages\&. \fI[-]\fP
500
534
.IP 
501
 
.IP "int-set-float-to-string-precision" 
 
535
.IP "int-set-float-to-string-precision"
502
536
Sets precision used in float to text conversions\&. Note that 
503
537
this can be used to control the precision of float return values 
504
538
for ECI commands\&. \fI[-]\fP
505
539
.IP 
506
 
.IP "int-set-log-history-length" 
507
 
Sets the log history length\&. Defaults to 5 items\&. \fI[-]\fP
 
540
.IP "int-set-log-history-length"
 
541
Sets the log history length\&. Defaults to 0 items\&. 
 
542
This command was introduced in ecasound 2\&.4\&.0\&. \fI[-]\fP
508
543
.IP 
509
 
.IP "int-cmd-version-string" 
 
544
.IP "int-cmd-version-string"
510
545
Returns EIAM parser version string\&. \fI[s]\fP
511
546
.IP 
512
 
.IP "int-cmd-version-lib-current" 
 
547
.IP "int-cmd-version-lib-current"
513
548
Returns EIAM library interface version (libtool)\&. \fI[i]\fP
514
549
.IP 
515
 
.IP "int-cmd-version-lib-revision" 
 
550
.IP "int-cmd-version-lib-revision"
516
551
Returns EIAM library interface revision (libtool)\&. \fI[i]\fP
517
552
.IP 
518
 
.IP "int-cmd-version-lib-age" 
 
553
.IP "int-cmd-version-lib-age"
519
554
Returns EIAM library interface age (libtool)\&. \fI[i]\fP
520
555
.IP 
521
 
.IP 
522
 
.SH "OBJECT MAPS" 
 
556
.SH "OBJECT MAPS"
523
557
Object maps are central repositories for commonly used object types\&.
524
558
By querying the maps, applications can get a list of all registered
525
559
object types and their properties\&. 
526
560
.IP 
527
 
.IP 
528
 
.IP "map-cop-list" 
 
561
.IP "map-cop-list"
529
562
Prints a list of registered chain operators using 
530
563
the format specified in section \fIOPERATOR DESCRIPTIONS\fP\&. \fI[s]\fP
531
564
.IP 
532
 
.IP "map-preset-list" 
 
565
.IP "map-preset-list"
533
566
Prints a list of registered effect presets using 
534
567
the format specified in section \fIOPERATOR DESCRIPTIONS\fP\&. \fI[s]\fP
535
568
.IP 
536
 
.IP "map-ladspa-list" 
 
569
.IP "map-ladspa-list"
537
570
Prints a list of registered LADSPA plugins using 
538
571
the format specified in section \fIOPERATOR DESCRIPTIONS\fP\&. \fI[s]\fP
539
572
.IP 
540
 
.IP "map-ladspa-id-list" 
 
573
.IP "map-ladspa-id-list"
541
574
Prints a list of registered LADSPA plugins using 
542
575
the format specified in section \fIOPERATOR DESCRIPTIONS\fP\&. 
543
576
Numerical LADPSA plugin identifiers are used\&. \fI[s]\fP
544
577
.IP 
545
 
.IP "map-ctrl-list" 
 
578
.IP "map-ctrl-list"
546
579
Prints a list of registered controllers using 
547
580
the format specified in section \fIOPERATOR DESCRIPTIONS\fP\&. \fI[s]\fP
548
581
.IP 
549
 
.IP 
550
 
.SH "DUMP COMMANDS" 
 
582
.SH "DUMP COMMANDS"
551
583
The following dump commands are not meant for normal use\&. 
552
584
Their primary purpose is to provide an easy way to get 
553
585
internal state information from libecasound\&. All dump
554
586
commands output a single line with syntax "key value"
555
587
to the selected output stream (defaults to stdout)\&. 
556
588
.IP 
557
 
.IP 
558
 
.IP "dump-target \&'filename\&'" 
 
589
.IP "dump-target \&'filename\&'"
559
590
Set target stream for dumping\&. \fI[-]\fP
560
591
.IP 
561
 
.IP "dump-status" 
 
592
.IP "dump-status"
562
593
Dumps engine status - \&'running\&', \&'stopped\&', \&'finished\&' or \&'notready\&'\&. \fI[-]\fP
563
594
.IP 
564
 
.IP "dump-position" 
 
595
.IP "dump-position"
565
596
Dumps the global position\&. Printed in seconds using a floating-point 
566
597
representation\&. \fI[-]\fP
567
598
.IP 
568
 
.IP "dump-length" 
 
599
.IP "dump-length"
569
600
Dumps the overall processing length\&. Printed in seconds using a floating-point 
570
601
representation\&. \fI[-]\fP
571
602
.IP 
572
 
.IP "dump-cs-status" 
 
603
.IP "dump-cs-status"
573
604
Dumps status string for the currently selected chainsetup - \&'connected\&', 
574
605
\&'selected\&' or an empty string\&. \fI[-]\fP
575
606
.IP 
576
 
.IP "dump-c-selected" 
 
607
.IP "dump-c-selected"
577
608
Dumps the name of currently selected chain\&. \fI[-]\fP
578
609
.IP 
579
 
.IP "dump-ai-selected" 
 
610
.IP "dump-ai-selected"
580
611
Dumps label of currently selected audio input\&. If no input is
581
612
selected, dumps an empty string\&. \fI[-]\fP
582
613
.IP 
583
 
.IP "dump-ai-position" 
 
614
.IP "dump-ai-position"
584
615
Dumps position of currently selected audio inputs\&. Printed in
585
616
seconds, using a floating-point representation\&. \fI[-]\fP
586
617
.IP 
587
 
.IP "dump-ai-length" 
 
618
.IP "dump-ai-length"
588
619
Dumps length of currently selected audio input\&. Printed in seconds,
589
620
using a floating-point representation\&. \fI[-]\fP
590
621
.IP 
591
 
.IP "dump-ai-open-state" 
 
622
.IP "dump-ai-open-state"
592
623
Dumps audio input state info\&. Either \&'open\&' or \&'closed\&'\&. \fI[-]\fP
593
624
.IP 
594
 
.IP "dump-ao-selected" 
 
625
.IP "dump-ao-selected"
595
626
Dumps label of currently selected audio output\&. If no output is
596
627
selected, dumps an empty string\&. \fI[-]\fP
597
628
.IP 
598
 
.IP "dump-ao-position" 
 
629
.IP "dump-ao-position"
599
630
Dumps position of currently selected audio outputs\&. Printed in
600
631
seconds, using a floating-point representation\&. \fI[-]\fP
601
632
.IP 
602
 
.IP "dump-ao-length" 
 
633
.IP "dump-ao-length"
603
634
Dumps length of currently selected audio output\&. Printed in seconds,
604
635
using a floating-point representation\&. \fI[-]\fP
605
636
.IP 
606
 
.IP "dump-ao-open-state" 
 
637
.IP "dump-ao-open-state"
607
638
Dumps audio output state info\&. Either \&'open\&' or \&'closed\&'\&. \fI[-]\fP
608
639
.IP 
609
 
.IP "dump-cop-value \&'chainop,param\&'" 
 
640
.IP "dump-cop-value \&'chainop,param\&'"
610
641
Dumps chain operator parameter value\&. \&'chainop\&' and \&'param\&' are 
611
642
operator and parameter index values (1\&.\&.\&.n)\&. \fI[-]\fP
612
643
.IP 
613
 
.IP 
614
 
.SH "OPERATOR DESCRIPTIONS" 
 
644
.SH "OPERATOR DESCRIPTIONS"
 
645
 
615
646
.IP 
616
647
The \fImap-xxx-list\fP commands return a string containing all registered
617
648
objects of the given type \fIxxx\fP\&. Each line of the output describes
630
661
For exact descriptions of these fields, please see
631
662
the header file emph(ecasound/libecasound/eca-operator\&.h)\&.
632
663
.IP 
633
 
.SH "SEE ALSO" 
634
 
.IP 
635
 
ecasound(1), ecatools (1), ecasoundrc(5)
636
 
.IP 
637
 
.SH "AUTHOR" 
638
 
.IP 
639
 
Kai Vehmanen, <kvehmanen -at- eca -dot- cx>
 
664
.SH "SEE ALSO"
 
665
 
 
666
.IP 
 
667
ecasound (1), ecatools (1), ecasoundrc (5)
 
668
.IP 
 
669
.SH "AUTHOR"
 
670
 
 
671
.IP 
 
672
Kai Vehmanen, <kvehmanen -at- eca -dot- cx <kvehmanen -at- eca -dot- cx>>