Debian Codegraph @

Documentation/ecasound_manpage.html

raw ◀ ▶
Source reconstructed at patch state 0 of 1 — not the installed (fully patched) source.
1 Debian patch touch this file
1 <html><head>
2 <title>ecasound</title>
3 <link rev="made" href="mailto:kvehmanen -at- eca -dot- cx">
4 </head>
5 <body>
6 <hr>
7 <h1>ecasound</h1>
8 <h2>05.05.2011</h2>
9
10 <html><head>
11 <link rev="made" href="mailto:kvehmanen -at- eca -dot- cx">
12 </head>
13 <body>
14 <hr>
15 <h1></h1>
16
17 <html><head>
18 <title>ecasound(1)</title>
19 <link rev="made" href="mailto:kvehmanen -at- eca -dot- cx">
20 </head>
21 <body>
22 <hr>
23 <h1>ecasound(1)</h1>
24 <h2> Multimedia software</h2>
25 <h2>05.05.2011</h2>
26
27
28 <p>
29 <h2>NAME</h2>ecasound - sample editor, multitrack recorder, fx-processor, etc.
30 <p>
31 <h2>SYNOPSIS</h2>
32 <strong>ecasound</strong> [ general_options ] { [ chain_setup ] [ effect_setup ] [ input_setup ] [ output_setup ] }
33 <p>
34 <h2>DESCRIPTION</h2>
35 <p>
36 Ecasound is a software package designed for multitrack audio
37 processing. It can be used for simple tasks like audio playback,
38 recording and format conversions, as well as for multitrack effect
39 processing, mixing, recording and signal recycling. Ecasound supports
40 a wide range of audio inputs, outputs and effect algorithms.
41 Effects and audio objects can be combined in various ways, and their
42 parameters can be controlled by operator objects like oscillators
43 and MIDI-CCs. A versatile console mode user-interface is included
44 in the package.
45 <p>
46 <h2>OPTIONS</h2>
47 <p>
48 Note! All options except those mentioned in <em>ecasound options</em> and
49 <em>Global options</em>, can be used in ecasound chainsetup files (.ecs).
50 <p>
51 <dl>
52 <p>
53
54 <strong>ECASOUND OPTIONS</strong>
55 <p>
56 These options are parsed and handled by the ecasound frontend binary and
57 are not passed to backend library. This means that these options may
58 not work in other applications that use ecasound libraries for their
59 functionality.
60 <p>
61 <dl>
62 <p><dt><strong>-c</strong><dd>
63 Starts ecasound in interactive mode. In interactive mode you can
64 control ecasound with simple commands ("start", "stop", "pause",
65 etc.). See <a href="ecasound-iam_manpage.html">ecasound-iam </a>.
66 <p>
67 <p><dt><strong>-C</strong><dd>
68 Disables ecasound's interactive mode (see '-c' and '-K').
69 </dl>
70 <p>
71 <p><dt><strong>-D</strong><dd>
72 Print all debug information to stderr (unbuffered, plain output
73 without ncurses).
74 <p>
75 <p><dt><strong>-s[:]chainsetup-file</strong><dd>
76 Create a new chainsetup from file 'chainsetup-file' and add
77 it to the current session. Chainsetup files commonly have
78 a filename ending to the '.ecs' extension. A chainsetup can
79 contain inputs, outputs, chains, effects, controllers -- i.e.
80 objects one one specific configuration of audio processing
81 elements. A session, on the other hand, is a collection of
82 one or more chainsetups. Only one of the chainsetups may be
83 connected (i.e. it can be run/processed). But it is possible
84 to have another chainsetup select (i.e. can be configured)
85 while other one is current connteced (i.e. running).
86 <p>
87 <p><dt><strong>-E "cmd1 [[args] ; cmd2 args ; ... ; cmdN]"</strong><dd>
88 Execute a set of Ecasound Interactive mode (EIAM) commands
89 at launch. These commands are executed immediately after
90 ecasound is started. If the command line contains sufficient
91 options to create a valid chainsetup that will be executed,
92 the launch commands are executed after the other command
93 line options are parsed, but before the processing engine
94 is started. Note that this command is a feature of
95 the ecasound frontend binary and not supported by
96 the library backend. This means that other clients may
97 not support the '-E' option, and also that the launch
98 commands are not saved as part of chainsetup or session
99 state.
100 <p>
101 <p><dt><strong>--server</strong><dd>
102 Enables the so called NetECI mode, in which ecasound can
103 be controlled remotely over a socket connection. When
104 activated, clients can connect to the running ecasound
105 session, and use interactive mode commands to control and
106 observe ecasound processing.
107 <p>
108 The NetECI protocol is defined in
109 <a href="http://nosignal.fi/ecasound/Documentation/programmers_guide/ecasound_programmers_guide.html#neteci-various">Ecasound's Programmer Guide</a>
110 <p>
111 One example client using this feature is ecamonitor(1). This
112 utility is included in the Ecasound distribution package (requires
113 a working Python environment).
114 <p>
115 <em>Warning!</em> If the machine running ecasound, is connected to
116 a public network, be sure to block ecasound's port in your
117 firewall! As there is no access control implemented for incoming
118 connections, anyone can otherwise connect, control and observe your
119 ecasound sessions.
120 This option replaces '--daemon' (deprecated in 2.6.0).
121 <p>
122 <p><dt><strong>--server-tcp-port=NNN</strong><dd>
123 Set the TCP port used by the daemon mode. By default
124 ecasound will use port number <em>2868</em>.
125 This option replaces '--daemon-port' (deprecated in 2.6.0).
126 <p>
127 <p><dt><strong>--no-server</strong><dd>
128 Disable ecasound's daemon mode. This is the default.
129 This option replaces '--nodaemon' (deprecated in 2.6.0).
130 <p>
131 <p><dt><strong>--osc-udp-port=NNN</strong><dd>
132 Enables support for Open Source Control (OSC). Ecasound will listen
133 for incoming OSC messages on UDP port NNN. Ecasound's OSC interface
134 is documented at:
135 &lt;http://ecasound.git.sourceforge.net/git/gitweb.cgi?p=ecasound/ecasound;a=blob;f=Documentation/ecasound_osc_interface.txt;hb=HEAD&gt;
136 <p>
137 Note that OSC support is still experimental and the interface
138 might change in later versions of Ecasound.
139 <p>
140 This option was added to ecasound 2.7.0.
141 <p>
142 <p><dt><strong>--keep-running,-K</strong><dd>
143 Do not exit when processing is finished/stopped. Only affects
144 non-interactive operating mode (see -c/-C).
145 Option added to ecasound 2.4.2.
146 <p>
147 <p><dt><strong>--help,-h</strong><dd>
148 Show this help.
149 <p>
150 <p><dt><strong>--version</strong><dd>
151 Print version info.
152 <p>
153 </dl>
154 <p>
155
156 <strong>GLOBAL OPTIONS</strong>
157 <p>
158 <dl>
159 <p>
160 <p><dt><strong>-d, -dd, -ddd</strong><dd>
161 Increase the amount of printed debug messages. <em>-d</em> adds
162 some verbosity, while <em>-ddd</em> results in very detailed
163 output.
164 <p>
165 <p><dt><strong>-d:debug_level</strong><dd>
166 Set the debug level mask to 'debug_level'. This a bitmasked value with
167 the following classes: errors (1), info (2), subsystems (4), module_names (8),
168 user_objects (16), system_objects 32, functions (64), continuous (128) and
169 eiam_return_values (256). Default is 271 (1+2+4+8+256). See sourcode
170 documentation for the ECA_LOGGER class for more detailed information.
171 <p>
172 <p><dt><strong>-R[:]path-to-file</strong><dd>
173 Use ecasound resource file (see ecasoundrc man page) 'path-to-file' as
174 the only source of setting resource value. Specifying this option
175 will disable the normal policy of querying both global and user (if exists)
176 resource files.
177 <p>
178 <p><dt><strong>-q</strong><dd>
179 Quiet mode, no output. Same as <em>-d:0</em>.
180 <p>
181 </dl>
182 <p>
183
184 <strong>GENERAL CHAINSETUP OPTIONS</strong>
185 <dl>
186 <p>
187 <p><dt><strong>-a:chainname1, chainname2, ...</strong><dd>
188 Selects active signal chains. All inputs and outputs following
189 this '-a' option are assigned to selected chains (until a new -a
190 option is specified). When adding effects, controllers and other
191 chain operators, only one chain can be selected at a time. If no -a option
192 has been given, chain 'default' is used instead when adding objects.
193 Chain name 'all' is also reserved. It will cause all existing chains
194 to be selected. By giving multiple -a options, you can control to which
195 chains effects, inputs and outputs are assigned to. Look at the <strong>EXAMPLES</strong>
196 section for more detailed info about the usage of this option.
197 <p>
198 <p><dt><strong>-n:name</strong><dd>
199 Sets the name of chainsetup to 'name'. If not specified, defaults
200 either to "command-line-setup" or to the file name from which
201 chainsetup was loaded. Whitespaces are not allowed.
202 <p>
203 <p><dt><strong>-x</strong><dd>
204 Truncate outputs. All output object are opened in overwrite mode.
205 Any existing files will be truncated.
206 <p>
207 <p><dt><strong>-X</strong><dd>
208 Open outputs for updating. Ecasound opens all outputs - if target
209 format allows it - in readwrite mode.
210 <p>
211 <p><dt><strong>-z:feature</strong><dd>
212 Enables 'feature'. Most features can be disabled using notation
213 <em>-z:nofeature</em>. '-z:db,dbsize' enables double-buffering for audio
214 objects that support it (dbsize=0 for default, otherwise buffer
215 size in sample frames). '-z:nodb' disables double-buffering.
216 '-z:intbuf' and '-z:nointbuf' control whether extra internal buffering
217 is allowed for realtime devices. Disabling this can reduce
218 latency times in some situations. With '-z:xruns', processing will be
219 halted if an under/overrun occurs. '-z:multitrack' and
220 'z:nomultitrack' can be used to force ecasound to enable or disable
221 multitrack-mode. In rare cases you may want to explicitly specify
222 the recording offset with '-z:multitrack,offset-in-samples'. The
223 offset is the amount of samples skipped when recording from
224 real-time inputs. '-z:psr' enables the <em>precise-sample-rates</em> mode
225 for OSS-devices. '-z:mixmode,sum' enables mixing mode where channels
226 are mixed by summing all channels. The default is '-z:mixmode,avg',
227 in which channels are mixed by averaging. Mixmode selection was first
228 added to ecasound 2.4.0.
229 See <a href="ecasoundrc_manpage.html">ecasoundrc man page</a>.
230 <p>
231 </dl>
232 <p>
233
234 <strong>CHAINSETUP BUFFERING AND PERFORMANCE OPTIONS</strong>
235 <dl>
236 <p>
237 <p><dt><strong>-B:buffering_mode</strong><dd>
238 Selects the default buffering mode. Mode is one of: 'auto' (default),
239 'nonrt', 'rt', 'rtlowlatency'.
240 <p>
241 <p><dt><strong>-b:buffer_size</strong><dd>
242 Sets the processing engine buffer size in samples. The size must be an exponent of 2,
243 and it is independent of channel count (e.g. <em>-b:1024</em> at 48kHz will result in
244 21.333ms buffer length whether input is mono, stereo or 5.1).
245 <p>
246 This is an important option as this defines the length of one processing engine
247 iteration and affects ecasound behaviour in many ways. If not explicitly
248 specified, ecasound will try to choose an optimal value based on current
249 buffering mode (see <em>-B</em> option). For real-time processing, you can try to set this
250 as low as possible to reduce the processing delay. Some machines can handle buffer
251 values as low as 64 and 128. In some circumstances (for instance when using
252 oscillator envelopes) small buffer sizes will make envelopes act more smoothly.
253 When not processing in real-time (all inputs and outputs are normal files), larger
254 values may help to avoid buffer overruns, lower CPU usage and/or otherwise
255 improve performance.
256 <p>
257 Note that when any JACK input/outputs are used, the buffer size setting is overridden
258 and set to period/buffer size reported by JACK server (e.g. jackd's '-p' option).
259 It is not possible to turn off this behaviour.
260 <p>
261 If not explicitly specified, the default buffer size is chosen based on current
262 buffering mode (see <em>-B</em>).
263 <p>
264 <p><dt><strong>-r:sched_priority</strong><dd>
265 Use realtime scheduling policy (SCHED_FIFO). This is impossible if
266 ecasound doesn't have root priviledges. Beware! This gives better
267 performance, but can cause total lock-ups if something goes wrong.
268 The 'sched_priority' can be omitted (0=omitted). If given,
269 this is the static priority to the highest priority ecasound thread.
270 Other ecasound threads run with priority 'sched_priority-1...n'.
271 Value '-1' can be used to disable raised-priority mode.
272 <p>
273 <p><dt><strong>-z:feature</strong><dd>
274 Relevant features are -z:db,xxx (-z:nodb) and -z:intbuf (-z:nointbuf).
275 See section <em>General chainsetup options</em> for details.
276 <p>
277 </dl>
278 <p>
279
280 <strong>PROCESSING CONTROL</strong>
281 <dl>
282 <p><dt><strong>-t:seconds</strong><dd>
283 Sets processing time in seconds (doesn't have to be an integer value).
284 If processing time isn't set, engine stops when all inputs are
285 finished. This option is equivalent to the 'cs-set-length' EIAM
286 command. A special-case value of '-1' will set the chainsetup length
287 according to the longest input object.
288 <p>
289 <p><dt><strong>-tl</strong><dd>
290 Enables looping. When processing is finished, engine will start
291 again from beginning. This option is equivalent to the 'cs-loop'
292 EIAM command.
293 <p>
294 </dl>
295 <p>
296
297 <strong>INPUT/OUTPUT SETUP</strong>
298 <p>
299 See <a href="users_guide/html_uguide/users_guide.html">ecasound user's guide</a> for
300 more detailed documentation.
301 <p>
302 <dl>
303 <p><dt><strong>-G:mgrtype,optstring</strong><dd>
304 Sets options for audio object manager type 'mgrtype'.
305 For available options, see "OBJECT TYPE SPECIFIC NOTES" below.
306 <p>
307 <p><dt><strong>-f:sample_format,channel,sample-rate,interleaving</strong><dd>
308 Sets the audio stream parameters for subsequent audio objects.
309 To set different parameters for different audio objects, multiple
310 '-f' options have to be specified (note the ordering, the '-f'
311 options should precede the audio objects for them to have any
312 effect). See documentation for '-i' and '-o' options.
313 <p>
314 When an audio object is opened (e.g. a file or sound device
315 is opened, or connection is made to a sound server), the audio
316 stream parameters are passed to the object. It should be noted that
317 not all audio objects allow to set any or all of the parameters.
318 For instance when opening existing audio files, many file formats
319 have a header describing the file audio parameters. In
320 these cases the audio file header overrides the parameters
321 passed with '-f' option. Similarly when creating JACK inputs and
322 outputs, the JACK server mandates the sampling rate and sample
323 format.
324 <p>
325 If no '-f' option is specified, or some of the argument fields
326 are left empty (e.g. '-f:,2,44100'), ecasound will use default values. These
327 default values are defined in ecasoundrc configuration file. See
328 ecasoundrc(5) manual page.
329 <p>
330 Note that ecasound opens out files by default in update mode.
331 Unless option '-x' (overwrite outputs) option is given,
332 audio parameters of an existing audio file take preference over
333 the params set with '-f'.
334 <p>
335 Sample format is given as a formatted string. The first letter is
336 either "u", "s" and "f" (unsigned, signed, floating point). The
337 following number specifies sample size in bits. If sample is
338 little endian, "_le" is added to the end. Similarly if big endian,
339 "_be" is added. If endianness is not specified, host byte-order is used.
340 Currently supported formats are "u8" (same as "8"), "s16_le" (same
341 as "16"), "s16_be", "s24_le", "s24_be", "s32_le", "s32_be", "f32_le"
342 and "f32_be". An empty string "" picks the system default sample
343 format.
344 <p>
345 The 4th parameter defines the channel layout. The available
346 options are 'i' (interleaved' and 'n' (noninterleaved). With
347 the noninterleaved setting, ecasound will process samples
348 one channel at a time, and the blocksize is set with '-b'.
349 The default setting is 'i'.
350 <p>
351 <p><dt><strong>-y:seconds</strong><dd>
352 Sets starting position for last specified input/output. If
353 you need more flexible control over audio objects, you should
354 use the <em>.ewf</em> format.
355 <p>
356 <p><dt><strong>-i[:]input-file-or-device[,params]</strong><dd>
357 Specifies a new input source that is connected to all selected chains (chains
358 are selected with '-a:...'). Connecting multiple inputs to the same chain is
359 not possible, but one input can be connected to multiple chains. Input can be
360 a a file, device or some other audio object (see below). If the input is
361 a file, its type is determined using the file name extension. If the object
362 name contains any commas, the name must be enclosed in backquotes to avoid
363 confusing the parser. Currently supported formats are RIFF WAVE files (.wav),
364 audio-cd tracks (.cdr), ecasound EWF files (.ewf), RAW audio data (.raw) and
365 MPEG audio files (.mp2,.mp3). More audio formats are supported via libaudiofile
366 and libsndfile libraries (see documentation below). MikMod is also supported (.xm,
367 .mod, .s3m, .it, etc). MIDI files (.mid) are supported using Timidity++.
368 Similarly Ogg Vorbis (.ogg) can be read, and written if ogg123 and vorbize tools
369 are installed; FLAC files (.flac) with flac command-line tools or using
370 libsndfile; and AAC files (.aac/.m4a/.mp4) with faad2/faac tools. Supported
371 realtime devices are OSS audio devices (/dev/dsp*), ALSA audio and loopback
372 devices and JACK audio subsystem. If no inputs are specified, the first
373 non-option (doesn't start with '-') command line argument is considered
374 to be an input.
375 <p>
376 <p><dt><strong>-o[:]output-file-or-device[,params]</strong><dd>
377 Works in the same way as the -i option. If no outputs are specified,
378 the default output device is used (see ~/.ecasoundrc). If the object
379 name contains any commas, the name must be enclosed in backquotes to
380 avoid confusing the parser. Note, many object types do not support
381 output (e.g. MikMod, MIDI and many others).
382 <p>
383 <em>OBJECT TYPE SPECIFIC NOTES</em>
384 <p><dt><strong>ALSA devices - 'alsa'</strong><dd>
385 When using ALSA drivers, instead of a device filename, you need to
386 use the following option syntax: <strong>-i[:]alsa,pcm_device_name</strong>.
387 <p>
388 <p><dt><strong>ALSA direct-hw and plugin access - 'alsahw', 'alsaplugin'</strong><dd>
389 It's also possible to use a specific card and device combination
390 using the following notation: <strong>-i[:]alsahw,card_number,device_number,subdevice_number</strong>.
391 Another option is the ALSA PCM plugin layer. It works just like
392 the normal ALSA pcm-devices, but with automatic channel count and
393 sample format conversions. Option syntax is
394 <strong>-i[:]alsaplugin,card_number,device_number,subdevice_number</strong>.
395 <p>
396 <p><dt><strong>aRts input/output - 'arts'</strong><dd>
397 If enabled at compile-time, ecasound supports audio input and
398 output using aRts audio server. Option syntax is <strong>-i:arts</strong>,
399 <strong>-o:arts</strong>.
400 <p>
401 <p><dt><strong>Audio file sequencing - 'audioloop', 'select', 'playat'</strong><dd>
402 Ecasound provides a set of special audio object types that
403 can be used for temporal sequencing of audio files - i.e. looping,
404 playing only a select portion of a file, playing file at a spefific
405 time, and other such operation.
406 <p>
407 Looping is possible with <strong>-i:audioloop,file.ext,params</strong>. The
408 file name (or any object type understood by Ecasound) given
409 as the second parameter is played back continuously looping
410 back to the beginning when the end of file is reached. Any additional
411 parameters given are passed unaltered to the file object.
412 Parameters 3...N are passed as is to the child object (i.e.
413 "-i audioloop,foo.wav,bar1,bar2" will pass parameters
414 "bar1,bar2" to the "foo.wav" object.
415 <p>
416 To select and use only a specific segment of an audio object,
417 the <strong>-i:select,start-time,duration,file.ext,params</strong> can
418 be used. This will play "duration" of "file.ext", starting at
419 "start-time". The time values should be given as seconds (e.g.
420 "2.25", or as samples (e.g. "25000sa"). Parameters 4...N are
421 passed as is to the child object.
422 <p>
423 To play an audio object at a given moment in time,
424 the <strong>-i:playat,play-at-time,file.ext,params</strong> can be
425 used. This will play "file.ext" after position reaches
426 "play-at-time". The time values should be given as seconds (e.g.
427 "2.25", or as samples (e.g. "25000sa"). Parameters 2...N are
428 passed as is to the child object.
429 <p>
430 <p><dt><strong>Ecasound Wave Files (EWF) - '*.ewf'</strong><dd>
431 A special file format that allows one to slice and loop full (or segments)
432 of audio files. This format is specific to Ecasound.
433 See <a href="users_guide/html_uguide/users_guide.html">ecasound user's guide</a> for more
434 detailed information.
435 <p>
436 See also audio object types 'audioloop', 'select' and 'playat'.
437 <p>
438 <p><dt><strong>JACK input/outputs - Overview</strong><dd>
439 JACK is a low-latency audio server that can be used to connect
440 multiple independent audio application to each other.
441 It is different from other audio server efforts in that
442 it has been designed from the ground up to be suitable for low-latency
443 professional audio work.
444 <p>
445 <p><dt><strong>JACK input/outputs - 'jack'</strong><dd>
446 Ecasound provides multiple ways to communicate with JACK
447 servers. To create a JACK input or output object, one should use <strong>-i jack</strong> and
448 <strong>-o jack</strong>. These create JACK client ports "ecasound:in_N" and
449 "ecasound:out_n" respectively ('N' is replaced by the channel number).
450 Ecasound automatically creates one JACK port for each channel (number
451 of channels is set with <strong>-f:bits,channels,rate</strong> option).
452 <p>
453 It is important to note that by default JACK ports are not connected
454 anywhere (e.g. to soundcard input/outputs, or to other apps). One thus
455 has to connect the ports with an external program (e.g. "QJackCtl"
456 or "jack_connect").
457 <p>
458 <p><dt><strong>JACK input/outputs - 'jack,clientname,portprefix'</strong><dd>
459 <strong>"jack,clientname"</strong> For simple use scanerios, ecasound provides a way to autoconnect
460 the ecasound ports. This can be done with by giving the peer client
461 name as the second parameter to the "jack" object, e.g. <strong>-o jack,clientname</strong>.
462 As an example, <strong>-o jack,system</strong> will create an output that is
463 automatically connected to outputs of the default system soundcard.
464 The client parameter can be omitted, in which case no automatic
465 connections are made.
466 <p>
467 If one needs to change the port prefix (e.g. "in" in client name
468 "ecasound:in_N"), the prefix can be specified as the third parameter to
469 "jack" object, e.g. <strong>-o jack,,fxout</strong>. Also the third parameter can be
470 omitted, in which case the default prefixes "in" and "out" are used.
471 <p>
472 <p><dt><strong>JACK input/outputs - 'jack_multi'</strong><dd>
473 A variant of 'jack' object type is 'jack_multi'. The full object syntax
474 is <strong>jack_multi,destport1,...,destportN</strong>. When a 'jack_multi' object
475 is connected to a JACK server, first channel of the object is connected
476 to JACK port 'destport1', second to 'destport2' and so forth. For
477 instance "-f:32,2,44100 -o jack_multi,foo:in,bar:in"
478 creates a stereo ecasound output object, with its left and right
479 channels routed to two difference JACK clients. The destination ports
480 must be active when the ecasound engine is launched, or otherwise
481 the connections cannot be established. If destination ports are not
482 specified for all channels, or zero length strings are given, those
483 ports are not connected at launch by ecasound.
484 <p>
485 <p><dt><strong>JACK input/outputs - 'jack_alsa', 'jack_auto', 'jack_generic' (**deprecated since 2.6.0**)</strong><dd>
486 Ecasound 2.5 and older supported "jack_alsa", "jack_auto" and "jack_generic" object
487 types, but these are now replaced by a more generic "jack" interface, and thus are
488 now deprecated (they work but are no longer documented).
489 <p>
490 <p><dt><strong>JACK input/outputs - client options</strong><dd>
491 Additionally global JACK options can be set using
492 <strong>-G:jack,client_name,operation_mode</strong> option. 'client_name'
493 is the name used when registering ecasound to the JACK system.
494 If 'operation_mode' is "notransport", ecasound will ignore
495 any transport state changes in the JACK-system; in mode
496 "send" it will send all start, stop and position-change events to
497 other JACK clients; in mode "recv" ecasound will follow JACK start,
498 stop and position-change events; and mode "sendrecv" which is
499 a combination of the two previous modes.
500 <p>
501 If not explicitly set, in interactive mode (<strong>'-c'</strong> option), the
502 default mode is "sendrecv", while in batchmode default is
503 "notransport". In both cases the mode can be changed with <strong>-G</strong>
504 option as described above.
505 <p>
506 More details about ecasound's JACK support can be found
507 from Ecasound User's Guide.
508 <p>
509 <p><dt><strong>Libaudiofile - 'audiofile'</strong><dd>
510 If libaudiofile support was enabled at compile-time, this
511 option allows you to force Ecasound to use libaudiofile
512 for reading/writing a certain audio file. Option syntax
513 is <strong>-i:audiofile,foobar.ext</strong> (same for <strong>-o</strong>).
514 <p>
515 <p><dt><strong>Libsndfile - 'sndfile'</strong><dd>
516 If libsndfile support was enabled at compile-time, this
517 option allows you to force Ecasound to use libsndfile
518 for reading/writing a certain audio file. Option syntax
519 is <strong>-i:sndfile,foobar.ext[,.format-ext]</strong> (same for <strong>-o</strong>).
520 The optional third parameter "format" can be used to
521 override the audio format (for example you can create an
522 AIFF file with filename "foo.wav").
523 <p>
524 <p><dt><strong>Loop device - 'loop'</strong><dd>
525 Loop devices make it possible to route (loop back) data between
526 chains. Option syntax is <strong>-[io][:]loop,tag</strong>. If you add
527 a loop output with tag '1', all data written to this output is routed
528 to any loop input with tag '1'. The tag can be either numerical
529 (e.g. '-i:loop,1') or a string (e.g. "-i:loop,vocals"). Like
530 with other input/output objects, you can attach the same loop
531 device to multiple chains and this way split/mix the signal.
532 <p>
533 Note: this 'loop' device is different from 'audioloop' (latter
534 added to ecasound v2.5.0).
535 <p>
536 <p><dt><strong>Mikmod - 'mikmod'</strong><dd>
537 If mikmod support was enabled at compile-time, this
538 option allows you to force Ecasound to use Mikmod
539 for reading/writing a certain module file. Option syntax
540 is <strong>-i:mikmod,foobar.ext</strong>.
541 <p>
542 <p><dt><strong>Null inputs/outputs - 'null'</strong><dd>
543 If you specify "null" or "/dev/null" as the input or output,
544 a null audio device is created. This is useful if you just want
545 to analyze sample data without writing it to a file. There's
546 also a realtime variant, "rtnull", which behaves just like "null"
547 objects, except all i/o is done at realtime speed.
548 <p>
549 <p><dt><strong>Resample - 'resample'</strong><dd>
550 Object type 'resample' can be used to resample audio
551 object's audio data to match the sampling rate used
552 in the active chainsetup. For example,
553 <strong>ecasound -f:16,2,44100 -i resample,22050,foo.wav -o /dev/dsp</strong>,
554 will resample file from 22.05kHz to 44.1kHz and write the
555 result to the soundcard device. Child sampling rate can be
556 replaced with keyword 'auto'. In this case ecasound will try
557 to query the child object for its sampling rate. This works with
558 files formats such as .wav which store meta information about
559 the audio file format. To use 'auto' in the previous example,
560 <strong>ecasound -f:16,2,44100 -i resample,auto,foo.wav -o /dev/dsp</strong>.
561 <p>
562 Parameters 4...N are passed as is to the child object (i.e.
563 "-i resample,22050,foo.wav,bar1,bar2" will pass parameters
564 "bar1,bar2" to the "foo.wav" object.
565 <p>
566 If ecasound was compiled with support for libsamplerate, you can
567 use 'resample-hq' to use the highest quality resampling algorithm
568 available. To force ecasound to use the internal resampler,
569 'resampler-lq' (low-quality) can be used.
570 <p>
571 <p><dt><strong>Reverse - 'reverse'</strong><dd>
572 Object type 'reverse' can be used to reverse audio
573 data coming from an audio object. As an example,
574 <strong>ecasound -i reverse,foo.wav -o /dev/dsp</strong> will play
575 'foo.wav' backwards. Reversing output objects is not
576 supported. Note! Trying to reverse audio object types with really
577 slow seek operation (like mp3), works extremely badly.
578 Try converting to an uncompressed format (wav or raw)
579 first, and then do reversation.
580 <p>
581 Parameters 3...N are passed as is to the child object (i.e.
582 "-i reverse,foo.wav,bar1,bar2" will pass parameters
583 "bar1,bar2" to the "foo.wav" object.
584 <p>
585 <p><dt><strong>System standard streams and named pipes - 'stdin', 'stdout'</strong><dd>
586 You can use standard streams (stdin and stdout) by giving <strong>stdin</strong>
587 or <strong>stdout</strong> as the file name. Audio data is assumed to be in
588 raw/headerless (.raw) format. If you want to use named pipes,
589 create them with the proper file name extension before use.
590 <p>
591 <p><dt><strong>Tone generator - 'tone'</strong><dd>
592 To generate a test tone, input <strong>-i:tone,type,freq,duration-secs</strong>
593 can be used. Parameter 'type' specifies the tone type: currently
594 only 'sine' is supported. The 'freq' parameter sets the frequency
595 of the generated tone and 'duration-secs' the length of the generated
596 stream. Specifying zero, or a negative value, as the duration will
597 produce an infinite stream. This feature was first added to Ecasound
598 2.4.7.
599 <p>
600 <p><dt><strong>Typeselect - 'typeselect'</strong><dd>
601 The special 'typeselect' object type can be used to override
602 how ecasound maps filename extensions and object types. For
603 instance <strong>ecasound -i typeselect,.mp3,an_mp3_file.wav -o /dev/dsp</strong>.
604 would play the file 'an_mp3_file.wav' as an mp3-file and not
605 as an wav-file as would happen without typeselect.
606 <p>
607 Parameters 4...N are passed as is to the child object (i.e.
608 "-i typeselect,.au,foo.wav,bar1,bar2" will pass parameters
609 "bar1,bar2" to the "foo.wav" object.
610 <p>
611 </dl>
612 <p>
613
614 <strong>MIDI SETUP</strong>
615 <p>
616 <dl>
617 <p><dt><strong>MIDI I/O devices - general</strong><dd>
618 If no MIDI-device is specified, the default MIDI-device is
619 used (see ecasoundrc(5)).
620 <p>
621 <p><dt><strong>-Md:rawmidi,device_name</strong><dd>
622 Add a rawmidi MIDI I/O device to the setup. 'device_name' can be anything
623 that can be accessed using the normal UNIX file operations and
624 produces raw MIDI bytes. Valid devices are for example OSS rawmidi
625 devices (/dev/midi00), ALSA rawmidi devices (/dev/snd/midiC2D0), named
626 pipes (see mkfifo man page), and normal files.
627 <p>
628 <p><dt><strong>-Md:alsaseq,sequencer-port</strong><dd>
629 Adds a ALSA MIDI sequencer port to the setup. 'sequencer-port' identifies
630 a port to connect to. It can be numerical (e.g. 128:1), or a client
631 name (e.g. "KMidimon").
632 <p>
633 <p><dt><strong>-Mms:device_id</strong><dd>
634 Sends MMC start ("Deferred Play") and stop ("Stop") with
635 device ID 'device_id'.
636 <p>
637 While Ecasound does not directly support syncing transport state
638 to incoming MMC messages, this can be achieved by connecting Ecasound
639 to JACK input/outputs, and using a tool such as JackMMC and JackCtlMMC (
640 see &lt;http://jackctlmmc.sourceforge.net/&gt;) to convert MMC messages
641 into JACK transport change events.
642 <p>
643 <p><dt><strong>-Mss</strong><dd>
644 Sends MIDI-sync (i.e. "MIDI Start" and "MIDI Stop" system realtime
645 messages) .to the selected MIDI-device. Notice that as Ecasound will
646 not send <em>MIDI-clock</em>, but only the <em>start</em> and <em>stop</em> messages.
647 <p>
648 </dl>
649 <p>
650
651 <strong>EFFECT SETUP</strong>
652 <p>
653 <em>PRESETS</em>
654 <p>
655 Ecasound has a powerful effect preset system that allows you create
656 new effects by combining basic effects and controllers. See
657 <a href="users_guide/html_uguide/users_guide.html">ecasound user's guide</a> for more
658 detailed information.
659 <p>
660 <dl>
661 <p>
662 <p><dt><strong>-pf:preset_file.eep</strong><dd>
663 Uses the first preset found from file 'preset_file.eep' as
664 a chain operator.
665 <p>
666 <p><dt><strong>-pn:preset_name</strong><dd>
667 Find preset 'preset_name' from global preset database and use
668 it as a chain operator. See ecasoundrc man page for info about the
669 preset database.
670 <p>
671 </dl>
672 <p>
673 <em>SIGNAL ANALYSIS</em>
674 <p>
675 <dl>
676 <p>
677 <p><dt><strong>-ev</strong><dd>
678 Analyzes sample data to find out how much the signal can
679 be amplified without clipping. The resulting percent value
680 can be used as a parameter to '-ea' (amplify). A statistical
681 summary, containing info about the stereo-image and
682 distribution of sample values, is printed out at the end
683 of processing.
684 <p>
685 <p><dt><strong>-evp</strong><dd>
686 Peak amplitude watcher. Maintains peak information for
687 each processed channels. Peak information is resetted
688 on every read.
689 <p>
690 <p><dt><strong>-ezf</strong><dd>
691 Finds the optimal value for DC-adjusting. You can use the result
692 as a parameter to -ezx effect.
693 <p>
694 </dl>
695 <p>
696 <em>GENERAL SIGNAL PROCESSING ALGORITHMS</em>
697 <dl>
698 <p><dt><strong>-eS:stamp-id</strong><dd>
699 Audio stamp. Takes a snapshot of passing audio data and stores
700 it using id 'stamp-id' (integer number). This data can later be
701 used by controllers and other operators.
702 <p>
703 <p><dt><strong>-ea:amplify%</strong><dd>
704 Adjusts the signal amplitude to 'amplify%' percent (linear scale, i.e.
705 individual samples are multiplied by 'amplify%/100'). See also
706 '-eadb'.
707 <p>
708 <p><dt><strong>-eac:amplify%,channel</strong><dd>
709 Amplifies signal of channel 'channel' by amplify-% percent (linear
710 scale, i.e. individual samples are multiplied by 'amplify%/100').
711 'channel' ranges from 1...n where n is the total number of channels.
712 See also '-eadb'.
713 <p>
714 <p><dt><strong>-eadb:gain-dB[,channel]</strong><dd>
715 Adjusts signal level by 'gain-dB', with a gain of 0dB having no effect
716 to the signal, negative gains attenuating the signal and positive
717 gain values amplifying it. The 'channel' parameter (1...n) is optional.
718 If 'channel' parameter is specified, and its value is nonzero, gain is
719 only applied to the given channel (1...n).
720 <p>
721 <p><dt><strong>-eaw:amplify%,max-clipped-samples</strong><dd>
722 Amplifies signal by amplify-% percent (linear scale, i.e. individual
723 samples are multiplied by 'amplify%/100'). If number of consecutive
724 clipped samples (resulting sample value is outside the nominal
725 [-1,1] range), a warning will be issued.
726 <p>
727 <p><dt><strong>-eal:limit-%</strong><dd>
728 Limiter effect. Limits audio level to 'limit-%' (linear scale) with
729 values equal or greater than 100% resulting in no change to
730 the signal.
731 <p>
732 <p><dt><strong>-ec:rate,threshold-%</strong><dd>
733 Compressor (a simple one). 'rate' is the compression rate in
734 decibels ('rate' dB change in input signal causes 1dB change
735 in output). 'threshold' varies between 0.0 (silence) and
736 1.0 (max amplitude).
737 <p>
738 <p><dt><strong>-eca:peak-level-%, release-time-sec, fast-crate, crate</strong><dd>
739 A more advanced compressor (original algorithm by John S. Dyson).
740 If you give a value of 0 to any parameter, the default is used.
741 'peak-level-%' essentially specifies how hard the peak limiter
742 is pushed. The default of 69% is good. 'release_time' is given
743 in seconds. This compressor is very sophisticated, and actually
744 the release time is complex. This is one of the dominant release
745 time controls, but the actual release time is dependent on a lot of
746 factors regarding the dynamics of the audio in. 'fastrate' is the
747 compression ratio for the fast compressor. This is not really
748 the compression ratio. Value of 1.0 is infinity to one, while the
749 default 0.50 is 2:1. Another really good value is special cased in
750 the code: 0.25 is somewhat less than 2:1, and sounds super smooth.
751 'rate' is the compression ratio for the entire compressor chain.
752 The default is 1.0, and holds the volume very constant without many nasty
753 side effects. However the dynamics in music are severely restricted,
754 and a value of 0.5 might keep the music more intact.
755 <p>
756 <p><dt><strong>-enm:threshold-level-%,pre-hold-time-msec,attack-time-msec,post-hold-time-msec,release-time-msec</strong><dd>
757 Noise gate. Supports multichannel processing (each channel
758 processed separately). When signal amplitude falls below
759 'threshold_level_%' percent (100% means maximum amplitude), gate
760 is activated. If the signal stays below the threshold for
761 'th_time' ms, it's faded out during the attack phase of
762 'attack' ms. If the signal raises above the 'threshold_level'
763 and stays there over 'hold' ms the gate is released during
764 'release' ms.
765 <p>
766 <p><dt><strong>-ei:pitch-shift-%</strong><dd>
767 Pitch shifter. Modifies audio pitch by altering its length.
768 <p>
769 <p><dt><strong>-epp:right-%</strong><dd>
770 Stereo panner. Changes the relative balance between the first
771 two channels. When 'right-%' is 0, only signal on the left
772 (1st) channel is passed through. Similarly if it is '100',
773 only right (2nd) channel is let through.
774 <p>
775 <p><dt><strong>-ezx:channel-count,delta-ch1,...,delta-chN</strong><dd>
776 Adjusts the signal DC by 'delta-chX', where X is the
777 channel number. Use -ezf to find the optimal delta
778 values.
779 <p>
780 </dl>
781 <p>
782 <em>ENVELOPE MODULATION</em>
783 <dl>
784 <p>
785 <p><dt><strong>-eemb:bpm,on-time-%</strong><dd>
786 Pulse gate (pulse frequency given as beats-per-minute).
787 <p>
788 <p><dt><strong>-eemp:freq-Hz,on-time-%</strong><dd>
789 Pulse gate.
790 <p>
791 <p><dt><strong>-eemt:bpm,depth-%</strong><dd>
792 Tremolo effect (tremolo speed given as beats-per-minute).
793 <p>
794 </dl>
795 <p>
796 <em>FILTER EFFECTS</em>
797 <dl>
798 <p><dt><strong>-ef1:center_freq, width</strong><dd>
799 Resonant bandpass filter. 'center_freq' is the center frequency. Width
800 is specified in Hz.
801 <p>
802 <p><dt><strong>-ef3:cutoff_freq, reso, gain</strong><dd>
803 Resonant lowpass filter. 'cutoffr_freq' is the filter cutoff
804 frequency. 'reso' means resonance. Usually the best values for
805 resonance are between 1.0 and 2.0, but you can use even bigger values.
806 'gain' is the overall gain-factor. It's a simple multiplier (1.0
807 is the normal level). With high resonance values it often is useful
808 to reduce the gain value.
809 <p>
810 <p><dt><strong>-ef4:cutoff, resonance</strong><dd>
811 Resonant lowpass filter (3rd-order, 36dB, original algorithm by Stefan
812 M. Fendt). Simulates an analog active RC-lowpass design. Cutoff is a
813 value between [0,1], while resonance is between [0,infinity).
814 <p>
815 <p><dt><strong>-efa:delay-samples,feedback-%</strong><dd>
816 Allpass filter. Passes all frequencies with no change in amplitude.
817 However, at the same time it imposes a frequency-dependent
818 phase-shift.
819 <p>
820 <p><dt><strong>-efc:delay-samples,radius</strong><dd>
821 Comb filter. Allows the spikes of the comb to pass through.
822 Value of 'radius' should be between [0, 1.0).
823 <p>
824 <p><dt><strong>-efb:center-freq,width</strong><dd>
825 Bandpass filter. 'center_freq' is the center frequency. Width
826 is specified in Hz.
827 <p>
828 <p><dt><strong>-efh:cutoff-freq</strong><dd>
829 Highpass filter. Only frequencies above 'cutoff_freq' are passed
830 through.
831 <p>
832 <p><dt><strong>-efi:delay-samples,radius</strong><dd>
833 Inverse comb filter. Filters out the spikes of the comb. There
834 are 'delay_in_samples-2' spikes. Value of 'radius' should be
835 between [0, 1.0). The closer it is to the maximum value,
836 the deeper the dips of the comb are.
837 <p>
838 <p><dt><strong>-efl:cutoff-freq</strong><dd>
839 Lowpass filter. Only frequencies below 'cutoff_freq' are passed
840 through.
841 <p>
842 <p><dt><strong>-efr:center-freq,width</strong><dd>
843 Bandreject filter. 'center_freq' is the center frequency. Width
844 is specified in Hz.
845 <p>
846 <p><dt><strong>-efs:center-freq,width</strong><dd>
847 Resonator. 'center_freq' is the center frequency. Width is specified
848 in Hz. Basicly just another resonating bandpass filter.
849 <p>
850 </dl>
851 <p>
852 <em>CHANNEL MIXING / ROUTING</em>
853 <dl>
854 <p>
855 <p><dt><strong>-chcopy:from-channel, to-channel</strong><dd>
856 Copy channel 'from_channel' to 'to_channel'. If 'to_channel'
857 doesn't exist, it is created. Channel indexing starts from 1.
858 Option added to ecasound 2.4.5.
859 <p>
860 <p><dt><strong>-chmove:from-channel, to-channel</strong><dd>
861 Copy channel 'from_channel' to 'to_channel', and mutes the source
862 channel 'from_channel'. Channel indexing starts from 1.
863 Option added to ecasound 2.4.5.
864 <p>
865 <p><dt><strong>-chorder:ch1,...,chN</strong><dd>
866 Reorder, omit and/r duplicate chain channels. The resulting
867 audio stream has total of 'N' channels. Each parameter specifies
868 the source channel to use for given output channel. As an
869 example, '-chorder:2,1' would reverse the channels of
870 a stereo stream ('out1,out2' = 'in2,in1'). Specifying the same
871 source channel multiple times is allowed. For example, '-chorder:2,2'
872 would route the second channel to both two output channels
873 ('out1,out2' = 'in2,in2'). If 'chX' is zero, the given channel 'X'
874 will be muted in the output stream. Option added to ecasound 2.7.0.
875 <p>
876 <p><dt><strong>-chmix:to-channel</strong><dd>
877 Mix all source channels to channel 'to_channel'. If 'to_channel'
878 doesn't exist, it is created. Channel indexing starts from 1.
879 Option added to ecasound 2.4.5.
880 <p>
881 <p><dt><strong>-chmute:channel</strong><dd>
882 Mutes the channel 'channel'. Channel indexing starts from 1.
883 Option added to ecasound 2.4.5.
884 <p>
885 <p><dt><strong>-erc:from-channel,to-channel</strong><dd>
886 Deprecated, see <em>-chcopy</em>.
887 <p>
888 <p><dt><strong>-erm:to-channel</strong><dd>
889 Deprecated, see <em>-chmix</em>.
890 <p>
891 </dl>
892 <p>
893 <em>TIME-BASED EFFECTS</em>
894 <dl>
895 <p>
896 <p><dt><strong>-etc:delay-time-msec,variance-time-samples,feedback-%,lfo-freq</strong><dd>
897 Chorus.
898 <p>
899 <p><dt><strong>-etd:delay-time-msec,surround-mode,number-of-delays,mix-%,feedback-%</strong><dd>
900 Delay effect. 'delay time' is the delay time in milliseconds.
901 'surround-mode' is a integer with following meanings: 0 = normal,
902 1 = surround, 2 = stereo-spread. 'number_of_delays' should be
903 obvious. Beware that large number of delays and huge delay times
904 need a lot of CPU power. 'mix-%' expresses the mix balance between the original
905 and delayed signal, with 0 meaning no delayed signal, 100 meaning no
906 original signal, and 50 (the default) achieving an equal balance.
907 'feedback-%' represents how much of the signal is recycled in each delay
908 or, if you prefer, at what rate the repeated snippet of delayed audio
909 fades. Note that sufficiently low feedback values may result in a number
910 of audible repetitions lesser than what you have specified for 'number_of_delays',
911 especially if you have set a low value for 'mix-%'. By default the value
912 for this parameter is 100% (No signal loss.).
913 <p>
914 <p><dt><strong>-ete:room_size,feedback-%,wet-%</strong><dd>
915 A more advanced reverb effect (original algorithm by Stefan M. Fendt).
916 'room_size' is given in meters, 'feedback-%' is the feedback level
917 given in percents and 'wet-%' is the amount of reverbed signal added
918 to the original signal.
919 <p>
920 <p><dt><strong>-etf:delay-time-msec</strong><dd>
921 Fake-stereo effect. The input signal is summed to mono. The
922 original signal goes to the left channels while a delayed
923 version (with delay of 'delay time' milliseconds) is goes to
924 the right. With a delay time of 1-40 milliseconds this
925 adds a stereo-feel to mono-signals.
926 <p>
927 <p><dt><strong>-etl:delay-time-msec,variance-time-samples,feedback-%,lfo-freq</strong><dd>
928 Flanger.
929 <p>
930 <p><dt><strong>-etm:delay-time-msec,number-of-delays,mix-%</strong><dd>
931 Multitap delay. 'delay time' is the delay time in milliseconds.
932 'number_of_delays' should be obvious. 'mix-%' determines how much
933 effected (wet) signal is mixed to the original.
934 <p>
935 <p><dt><strong>-etp:delay-time-msec,variance-time-samples,feedback-%,lfo-freq</strong><dd>
936 Phaser.
937 <p>
938 <p><dt><strong>-etr:delay-time,surround-mode,feedback-%</strong><dd>
939 Reverb effect. 'delay time' is the delay time in milliseconds.
940 If 'surround-mode' is 'surround', reverbed signal moves around the
941 stereo image. 'feedback-%' determines how much effected (wet)
942 signal is fed back to the reverb.
943 <p>
944 </dl>
945 <p>
946 <em>LADSPA-PLUGINS</em>
947 <dl>
948 <p><dt><strong>-el:plugin_unique_name,param-1,...,param-N</strong><dd>
949 Ecasound supports LADSPA-effect plugins (Linux Audio Developer's Simple
950 Plugin API). Parameters 1..N are set as values of the plugin's control
951 ports.
952 <p>
953 If plugin has more than one audio input and/or output port,
954 only one plugin is instance is created, and the chain channels
955 are fed to the same plugin instance. If plugin has at most one
956 input and at most one output audio port, a separate plugin instance
957 is created for each channel of the ecasound chain (e.g. for a stereo
958 audio channel, two LADSPA plugins of same type are created, with
959 one per channel).
960 <p>
961 Plugins are located in shared library (.so) files. Ecasound looks
962 for plugins in @prefix@/lib/ladspa (e.g. "/usr/local/lib/ladspa"),
963 directories listed in environment variable <em>LADSPA_PATH</em>. Plugin
964 search path can be configured also via <em>ecasoundrc</em>, see
965 ecasoundrc(5) man page. One shared library file can contain multiple
966 plugin objects, but every plugin has a unique plugin name. This name is
967 used for selecting plugins.
968 <p>
969 See <a href="http://www.linuxdj.com/audio/lad">LAD mailing list web site</a> for
970 more info about LADSPA. Other useful sites are <a href="http://www.ladspa.org">LADSPA home
971 page</a> and <a href="http://www.ffem.org/gdam/ladspa-doc/ladspa.html">LADSPA
972 documentation</a>.
973 <p>
974 <p><dt><strong>-eli:plugin_unique_number,param-1,...,param-N</strong><dd>
975 Same as above (<em>-el</em>) expect plugin's unique id-number is used. It
976 is guaranteed that these id-numbers are unique among all
977 LADSPA plugins.
978 <p>
979 </dl>
980 <p>
981 <em>LV2 PLUGINS</em>
982 <dl>
983 <p><dt><strong>-elv2:plugin-id-uri,param-1,...,param-N</strong><dd>
984 Ecasound also supports LV2 audio plugins. LV2 plugins are
985 identified by a globally unique, case-sensitive identifier.
986 <p>
987 If plugin has more than one audio input and/or output port,
988 only one plugin is instance is created, and the chain channels
989 are fed to the same plugin instance. If plugin has at most one
990 input and at most one output audio port, a separate plugin instance
991 is created for each channel of the ecasound chain (e.g. for a stereo
992 audio channel, two LV2 plugins of same type are created, with
993 one per channel).
994 <p>
995 LV2 is a plugin standard for audio systems.
996 </dl>
997 <p>
998 <em>GATE SETUP</em>
999 <p>
1000 <dl>
1001 <p>
1002 <p><dt><strong>-gc:start-time,len</strong><dd>
1003 Time crop gate. Initially gate is closed. After 'start-time' seconds
1004 has elapsed, gate opens and remains open for 'len' seconds. When
1005 closed, passing audio buffers are trucated to zero length.
1006 <p>
1007 <p><dt><strong>-ge:open-threshold-%,close-thold-%,volume-mode,reopen-count</strong><dd>
1008 Threshold gate. Initially gate is closed. It is opened when volume
1009 goes over 'othreshold' percent. After this, if volume drops below
1010 'cthold' percent, gate is closed and won't be opened again, unless the
1011 'reopen-count' is set to anything other than zero.
1012 If 'value_mode' is 'rms', average RMS volume is used. Otherwise
1013 peak average is used. When closed, passing audio buffers are trucated
1014 to zero length.
1015 If the 'reopen-count' is set to a positive number, then the gate will
1016 restart its operation that many times. So for example, a reopen count
1017 of 1 will cause up to 2 openings of the gate. A negative value for 'reopen-count'
1018 will result in the gate reopening indefinitely. The 'reopen-count' is invaluable
1019 in recording vinyl and tapes, where you can set things up and then recording
1020 starts whenever the needle is on the vinyl, and stops when it's off. As many sides
1021 as you like can be recorded in one session. You will need to experiment with
1022 buffer lengths and start/stop levels to get reliable settings for your equipment.
1023 <p>
1024 <p><dt><strong>-gm:state</strong><dd>
1025 Manual gate. If 'state' is 1, gate is open and all samples are
1026 passed through. If 'state' is zero, gate is closed an no samples are
1027 let through. This chain operator is useful when writing to an output
1028 needs to be stopped dynamically (without stopping the whole engine).
1029 <p>
1030 </dl>
1031 <p>
1032
1033 <em>CONTROL ENVELOPE SETUP</em>
1034 <dl>
1035 <p>
1036 Controllers can be used to dynamically change effect parameters
1037 during processing. All controllers are attached to the selected
1038 (=usually the last specified effect/controller) effect. The first
1039 three parameters are common for all controllers. 'fx_param'
1040 specifies the parameter to be controlled. Value '1' means
1041 the first parameter, '2' the second and so on. 'start_value'
1042 and 'end_value' set the value range. For examples, look at the
1043 the <strong>EXAMPLES</strong> section.
1044 <p>
1045 <p><dt><strong>-kos:fx-param,start-value,end-value,freq,i-phase</strong><dd>
1046 Sine oscillator with frequency of 'freq' Hz and initial phase
1047 of 'i_phase' times pi.
1048 <p>
1049 <p><dt><strong>-kog:fx-param,start-value,end-value,freq,mode,point-pairs,first-value,last-value,pos1,value1,...</strong><dd>
1050 Generic oscillator. Frequency 'freq' Hz, mode either '0' for
1051 static values or '1' for linear interpolation. 'point-pairs'
1052 specifies the number of 'posN' - 'valueN' pairs to include.
1053 'first-value' and 'last-value' are used as border values (values
1054 for position 0.0/first and position 1.0/last).
1055 All 'posN' and 'valueN' must be between 0.0 and 1.0. Also,
1056 for all 'posN' values 'pos1 &lt; pos2 &lt; ... &lt; posN' must be true.
1057 <p>
1058 <p><dt><strong>-kf:fx-param,start-value,end-value,freq,mode,genosc-number</strong><dd>
1059 Generic oscillator. 'genosc_number' is the number of the
1060 oscillator preset to be loaded. Mode is either '0' for
1061 static values or '1' for linear interpolation. The location for
1062 the preset file is taken from ./ecasoundrc (see <em>ecasoundrc man page</em>).
1063 <p>
1064 <p><dt><strong>-kl:fx-param,start-value,end-value,time-seconds</strong><dd>
1065 Linear envelope that starts from 'start_value' and linearly
1066 changes to 'end_value' during 'time_in_seconds'. Can
1067 be used for fadeins and fadeouts.
1068 <p>
1069 <p><dt><strong>-kl2:fx-param,start-value,end-value,1st-stage-length-sec,2nd-stage-length-sec</strong><dd>
1070 Two-stage linear envelope, a more versatile tool for doing fade-ins
1071 and fade-outs. Stays at 'start_value' for '1st_stage_length' seconds
1072 and then linearly changes towards 'end_value' during
1073 '2nd_stage_length' seconds.
1074 <p>
1075 <p><dt><strong>-klg:fx-param,low-value,high-value,point_count,pos1,value1,...,posN,valueN</strong><dd>
1076 Generic linear envelope. This controller source can be
1077 used to map custom envelopes to chain operator parameters. Number of
1078 envelope points is specified in 'point_count'. Each envelope point
1079 consists of a position and a matching value. Number of pairs must
1080 match 'point_count' (i.e. 'N==point_count'). The 'posX' parameters are given
1081 as seconds (from start of the stream). The envelope points are specified as
1082 float values in range '[0,1]'. Before envelope values are mapped to operator
1083 parameters, they are mapped to the target range of '[low-value,high-value]'. E.g.
1084 a value of '0' will set operator parameter to 'low-value' and a value of
1085 '1' will set it to 'high-value'. For the initial segment '[0,pos1]', the envelope
1086 will output value of 'value1' (e.g. 'low-value').
1087 <p>
1088 <p><dt><strong>-km:fx-param,start-value,end-value,controller,channel</strong><dd>
1089 MIDI continuous controller (control change messages).
1090 Messages on the MIDI-channel 'channel' that are coming from
1091 controller number 'controller' are used as the controller
1092 source. As recommended by the MIDI-specification, channel
1093 numbering goes from 1 to 16. Possible controller numbers
1094 are values from 0 to 127. The MIDI-device where bytes
1095 are read from can be specified using <em>-Md</em> option.
1096 Otherwise the default MIDI-device is used as specified in
1097 <em>~ecasound/ecasoundrc</em> (see <em>ecasoundrc man page</em>).
1098 Defaults to <em>/dev/midi</em>.
1099 <p>
1100 <p><dt><strong>-ksv:fx-param,start-value,end-value,stamp-id,rms-toggle</strong><dd>
1101 Volume analyze controller. Analyzes the audio stored in
1102 stamp 'stamp-id' (see '-eS:id' docs), and creates
1103 control data based on the results. If 'rms-toggle' is non-zero,
1104 RMS-volume is used to calculate the control value. Otherwise
1105 average peak-amplitude is used.
1106 <p>
1107 <p><dt><strong>-kx</strong><dd>
1108 This is a special switch that can be used when you need
1109 to control controller parameters with another controller.
1110 When you specify <em>-kx</em>, the last specified controller
1111 will be set as the control target. Then you just add
1112 another controller as usual.
1113 </dl>
1114 <p>
1115
1116 <strong>INTERACTIVE MODE</strong>
1117 <p>
1118 See <em>ecasound-iam(1)</em> man page.
1119 <p>
1120 </dl>
1121 <p>
1122 <h2>ENVIRONMENT</h2>
1123 <p>
1124 <dl>
1125 <p><dt><strong>ECASOUND</strong><dd>
1126 If defined, some utility programs and scripts will use
1127 the <em>ECASOUND</em> environment as the default path to
1128 ecasound executable.
1129 <p>
1130 <p><dt><strong>ECASOUND_LOGFILE</strong><dd>
1131 Output all debugging messages to a separate log file. If defined,
1132 <em>ECASOUND_LOGFILE</em> defines the logfile path. This is a good tool for
1133 debugging ECI/EIAM scripts and applications.
1134 <p>
1135 <p><dt><strong>ECASOUND_LOGLEVEL</strong><dd>
1136 Select which messages are written to the logfile defined by
1137 <em>ECASOUND_LOGFILE</em>. The syntax for <em>-d:level</em> is used. If not
1138 defined, all messages are written. Defaults to -d:319 (everything else
1139 but 'functions (64)' and 'continuous (128)' class messages).
1140 <p>
1141 <p><dt><strong>COLUMNS</strong><dd>
1142 Ecasound honors the <em>COLUMNS</em> environment variable when
1143 formatting printed trace messages. If <em>COLUMNS</em> is not set,
1144 a default of 74 is used.
1145 <p>
1146 <p><dt><strong>TMPDIR</strong><dd>
1147 Some functions of Ecasound (e.g. "cs-edit" interactive command) require
1148 creation of temporary files. By default, these files are created under
1149 "/tmp", but this can be overridden by setting the <em>TMPDIR</em> environment
1150 variable.
1151 </dl>
1152 <p>
1153 <h2>RETURN VALUES</h2>
1154 <p>
1155 In interactive mode, ecasound always returns zero.
1156 <p>
1157 In non-interactive (batch) mode, a non-zero value is returned
1158 for the following errors:
1159 <p>
1160 <dl>
1161 <p><dt><strong>1</strong><dd>
1162 Unable to create a valid chainsetup with the given parameters. Can be
1163 caused by invalid option syntax, etc.
1164 <p>
1165 <p><dt><strong>2</strong><dd>
1166 Unable to start processing. This can be caused by insufficient file
1167 permissions, inability to access some system resources, etc.
1168 <p>
1169 <p><dt><strong>3</strong><dd>
1170 Error during processing. Possible causes: output object has run
1171 out of free disk space, etc.
1172 <p>
1173 <p><dt><strong>4</strong><dd>
1174 Error during process termination and/or cleanup. See section
1175 on 'SIGNALS' for further details.
1176 <p>
1177 <h2>SIGNALS</h2>
1178 <p>
1179 When ecasound receives any of the POSIX signals SIGINT (ctrl-c),
1180 SIGHUP, SIGTERM or SIGQUIT, normal cleanup and exit procedure is
1181 initiated. Here normal exit means that e.g. file headers are
1182 updated before closing, helper processes are terminated in normal
1183 way, and so forth.
1184 <p>
1185 If, while doing the cleanup described above, ecasound receives
1186 another signal (of the same set of POSIX signals), ecasound
1187 will skip the normal cleanup procedure, and terminate
1188 immediately. Any remaining cleanup tasks will be skipped.
1189 Depending on the runtime state and configuration, this brute
1190 force exit may have some side-effects. Ecasound will return
1191 exit code of '4' if normal cleanup was skipped.
1192 <p>
1193 Special case handling is applied to the SIGINT (ctrl-c) signal.
1194 If a SIGINT signal is received during the cleanup procedure,
1195 ecasound will ignore the signal once, and emit a notice to 'stderr'
1196 that cleanup is already in progress. Any subsequent SIGINT signals
1197 will no longer get special handling, and instead process will
1198 terminate immediately (and possibly without proper cleanup).
1199 <p>
1200 <h2>FILES</h2>
1201 <p>
1202 <em>~/.ecasound</em>
1203 The default directory for ecasound user resource files.
1204 See the <a href="ecasoundrc_manpage.html">ecasoundrc (5) man page</a> man page.
1205 <p>
1206 <em>*.ecs</em>
1207 Ecasound Chainsetup files. Syntax is more or less the
1208 same as with command-line arguments.
1209 <p>
1210 <em>*.ecp</em>
1211 Ecasound Chain Preset files. Used for storing effect
1212 and chain operator presets. See <a href="users_guide/html_uguide/users_guide.html">ecasound user's guide</a> for
1213 more better documentation.
1214 <p>
1215 <em>*.ews</em>
1216 Ecasound Wave Stats. These files are used to cache
1217 waveform data.
1218 <p>
1219 <h2>EXAMPLES</h2>
1220 <p>
1221 Examples of how to perform common tasks with ecasound can
1222 be found at
1223 <a href="http://nosignal.fi/ecasound/Documentation/examples.html">http://nosignal.fi/ecasound/Documentation/examples.html</a>.
1224 <p>
1225 <h2>SEE ALSO</h2>
1226 <p>
1227 <a href="ecatools_manpage.html">ecatools (1) man page</a>,
1228 <a href="ecasound-iam_manpage.html">ecasound-iam (1) man page</a>
1229 <a href="ecasoundrc_manpage.html">ecasoundrc (5) man page</a>,
1230 <a href="index.html">"HTML docs in the Documentation subdirectory"</a>
1231 <p>
1232 <h2>BUGS</h2>
1233 <p>
1234 See file BUGS. If ecasound behaves weirdly, try to
1235 increase the debug level to see what's going on.
1236 <p>
1237 <h2>AUTHOR</h2>
1238 <p>
1239 Kai Vehmanen, &lt;<a href="mailto:kvehmanen -at- eca -dot- cx"><em>kvehmanen -at- eca -dot- cx</em></a>&gt;