71
71
not support the \&'-E\&' option, and also that the launch
72
72
commands are not saved as part of chainsetup or session
76
Enable ecasound\&'s daemon mode\&. If this option is given,
77
ecasound will allow clients to connect to the running
78
ecasound session using a TCP/IP network connection\&.
79
The clients can both observe and control the session\&.
81
\fIWarning!\fP As there is no access control implemented,
82
be sure to block ecasound\&'s port in your firewall
83
if the machine running ecasound is connected to
84
a public network! Otherwise anyone can connect to
85
your ecasound sessions\&.
76
Enables the so called NetECI mode, in which ecasound can
77
be controlled remotely over a socket connection\&. When
78
activated, clients can connect to the running ecasound
79
session, and use interactive mode commands to control and
80
observe ecasound processing\&.
82
One example client using this feature is ecamonitor(1)\&. This
83
utility is included in the Ecasound distribution package (requires
84
a working Python environment)\&.
86
\fIWarning!\fP If the machine running ecasound, is connected to
87
a public network, be sure to block ecasound\&'s port in your
88
firewall! As there is no access control implemented for incoming
89
connections, anyone can otherwise connect, control and observe your
91
This option replaces \&'--daemon\&' (deprecated in 2\&.6\&.0)\&.
93
.IP "--server-tcp-port=NNN"
88
94
Set the TCP port used by the daemon mode\&. By default
89
95
ecasound will use port number \fI2868\fP\&.
96
This option replaces \&'--daemon-port\&' (deprecated in 2\&.6\&.0)\&.
92
99
Disable ecasound\&'s daemon mode\&. This is the default\&.
100
This option replaces \&'--nodaemon\&' (deprecated in 2\&.6\&.0)\&.
94
102
.IP "--keep-running,-K"
95
103
Do not exit when processing is finished/stopped\&. Only affects
96
104
non-interactive operating mode (see -c/-C)\&.
97
105
Option added to ecasound 2\&.4\&.2\&.
100
108
Show this help\&.
103
111
Print version info\&.
105
113
\fBGLOBAL OPTIONS\fP
107
115
.IP "-d, -dd, -ddd"
225
233
For available options, see "OBJECT TYPE SPECIFIC NOTES" below\&.
227
235
.IP "-f:sample_format,channel,sample-rate,interleaving"
228
Sets default sampling parameters\&. These are used for all following
229
input and output files or until another -f is specified\&. If no -f
230
option is present, ecasound will use the default audio parameters (see
231
ecasoundrc man page)\&. Notice that when opening existing audio objects,
232
either for input or output, the default audio parameters set with -f are
233
ignored if objects provide sufficient header information (as
234
is the case for wav, aiff, etc formats)\&. For output objects, the
235
-x option can be used to completely overwrite existing files
236
(in other words, with -x, default audio parameters set with -f are used)\&.
238
Sample format is given as a a formatted string\&. The first letter is
236
Sets the audio stream parameters for subsequent audio objects\&.
237
To set different parameters for different audio objects, multiple
238
\&'-f\&' options have to be specified (note the ordering, the \&'-f\&'
239
options should precede the audio objects for them to have any
240
effect)\&. See documentation for \&'-i\&' and \&'-o\&' options\&.
242
When an audio object is opened (e\&.g\&. a file or sound device
243
is opened, or connection is made to a sound server), the audio
244
stream parameters are passed to the object\&. It should be noted that
245
not all audio objects allow to set any or all of the parameters\&.
246
For instance when opening existing audio files, many file formats
247
have a header describing the file audio parameters\&. In
248
these cases the audio file header overrides the parameters
249
passed with \&'-f\&' option\&. Similarly when creating JACK inputs and
250
outputs, the JACK server mandates the sampling rate and sample
253
If no \&'-f\&' option is specified, or some of the argument fields
254
are left empty (e\&.g\&. \&'-f:,2,44100\&'), ecasound will use default values\&. These
255
default values are defined in ecasoundrc configuration file\&. See
256
ecasoundrc(5) manual page\&.
258
Note that ecasound opens out files by default in update mode\&.
259
Unless option \&'-x\&' (overwrite outputs) option is given,
260
audio parameters of an existing audio file take preference over
261
the params set with \&'-f\&'\&.
263
Sample format is given as a formatted string\&. The first letter is
239
264
either "u", "s" and "f" (unsigned, signed, floating point)\&. The
240
265
following number specifies sample size in bits\&. If sample is
241
266
little endian, "_le" is added to the end\&. Similarly if big endian,
242
267
"_be" is added\&. If endianess is not specified, host byte-order is used\&.
243
268
Currently supported formats are "u8" (same as "8"), "s16_le" (same
244
269
as "16"), "s16_be", "s24_le", "s24_be", "s32_le", "s32_be", "f32_le"
270
and "f32_be"\&. An empty string "" picks the system default sample
247
The 4th parameter \&'interleaving\&' should either be \&'i\&' (default) for
248
interleaved stream format, or \&'n\&' for noninterleaved\&.
273
The 4th parameter defines the channel layout\&. The available
274
options are \&'i\&' (interleaved\&' and \&'n\&' (noninterleaved)\&. With
275
the noninterleaved setting, ecasound will process samples
276
one channel at a time, and the blocksize is set with \&'-b\&'\&.
277
The default setting is \&'i\&'\&.
251
280
Sets starting position for last specified input/output\&. If
253
282
use the \fI\&.ewf\fP format\&.
255
284
.IP "-i[:]input-file-or-device[,params]"
256
Specifies a new input source that is connected to all selected chains\&.
257
Connecting multiple inputs to the same chain isn\&'t possible\&. Input
258
can be a a file, device or some other audio object (see below)\&.
259
If the input is a file, its type is determined using the file name
260
extension\&. If the object name contains any commas, the name must be
261
enclosed in backquotes to avoid confusing the parser\&. Currently supported
262
formats are RIFF WAVE files (\&.wav), audio-cd tracks (\&.cdr), ecasound
263
EWF files (\&.ewf), RAW audio data (\&.raw) and MPEG files (\&.mp2,\&.mp3)\&. Also,
264
formats supported by the SGI audiofile library: AIFF (\&.aiff, \&.aifc, \&.aif) and
265
Sun/NeXT audio files (\&.au, \&.snd)\&. MikMod is also supported (\&.xm, \&.mod, \&.s3m,
266
\&.it, etc)\&. MIDI files (\&.mid) are supported using Timidity++\&. Similarly
267
Ogg Vorbis (\&.ogg) can be read and written if ogg123 and vorbize tools
268
are installed, FLAC files (\&.flac) with flac command-line tools or using
269
libsndfile, and AAC files (\&.aac/\&.m4a/\&.mp4) with faad2/faac tools\&. Supported
285
Specifies a new input source that is connected to all selected chains (chains
286
are selected with \&'-a:\&.\&.\&.\&')\&. Connecting multiple inputs to the same chain is
287
not possible, but one input can be connected to multiple chains\&. Input can be
288
a a file, device or some other audio object (see below)\&. If the input is
289
a file, its type is determined using the file name extension\&. If the object
290
name contains any commas, the name must be enclosed in backquotes to avoid
291
confusing the parser\&. Currently supported formats are RIFF WAVE files (\&.wav),
292
audio-cd tracks (\&.cdr), ecasound EWF files (\&.ewf), RAW audio data (\&.raw) and
293
MPEG audio files (\&.mp2,\&.mp3)\&. More audio formats are supported via libaudiofile
294
and libsndfile libraries (see documentation below)\&. MikMod is also supported (\&.xm,
295
\&.mod, \&.s3m, \&.it, etc)\&. MIDI files (\&.mid) are supported using Timidity++\&.
296
Similarly Ogg Vorbis (\&.ogg) can be read, and written if ogg123 and vorbize tools
297
are installed; FLAC files (\&.flac) with flac command-line tools or using
298
libsndfile; and AAC files (\&.aac/\&.m4a/\&.mp4) with faad2/faac tools\&. Supported
270
299
realtime devices are OSS audio devices (/dev/dsp*), ALSA audio and loopback
271
300
devices and JACK audio subsystem\&. If no inputs are specified, the first
272
301
non-option (doesn\&'t start with \&'-\&') command line argument is considered
276
305
Works in the same way as the -i option\&. If no outputs are specified,
277
306
the default output device is used (see ~/\&.ecasoundrc)\&. If the object
278
307
name contains any commas, the name must be enclosed in backquotes to
279
avoid confusing the parser\&. Note, you can\&'t output to module formats
280
supported by MikMod (this should be obvious)\&.
308
avoid confusing the parser\&. Note, many object types do not support
309
output (e\&.g\&. MikMod, MIDI and many others)\&.
282
311
\fIOBJECT TYPE SPECIFIC NOTES\fP
312
.IP "ALSA devices - \&'alsa\&'"
284
313
When using ALSA drivers, instead of a device filename, you need to
285
314
use the following option syntax: \fB-i[:]alsa,pcm_device_name\fP\&.
287
.IP "ALSA direct-hw and plugin access"
316
.IP "ALSA direct-hw and plugin access - \&'alsahw\&', \&'alsaplugin\&'"
288
317
It\&'s also possible to use a specific card and device combination
289
318
using the following notation: \fB-i[:]alsahw,card_number,device_number,subdevice_number\fP\&.
290
319
Another option is the ALSA PCM plugin layer\&. It works just like
335
364
See also audio object types \&'audioloop\&', \&'select\&' and \&'playat\&'\&.
337
.IP "JACK input/outputs"
366
.IP "JACK input/outputs - Overview"
338
367
JACK is a low-latency audio server that can be used to connect
339
368
multiple independent audio application to each other\&.
340
369
It is different from other audio server efforts in that
341
370
it has been designed from the ground up to be suitable for low-latency
342
371
professional audio work\&.
344
Ecasound provides multiple ways to communicate with JACK servers\&. To
345
directly input or output to soundcard, use \fB-i jack_alsa\fP and \fB-o
346
jack_alsa\fP\&. To communicate with other apps, use
347
\fBjack_auto,remote_clientname\fP\&. To just create ports without making
348
any automatic connections, there are \fBjack\fP and
349
\fBjack_generic,local_portprefix\fP\&.
373
.IP "JACK input/outputs - \&'jack\&'"
374
Ecasound provides multiple ways to communicate with JACK
375
servers\&. To create a JACK input or output object, one should use \fB-i jack\fP and
376
\fB-o jack\fP\&. These create JACK client ports "ecasound:in_N" and
377
"ecasound:out_n" respectively (\&'N\&' is replaced by the channel number)\&.
378
Ecasound automatically creates one JACK port for each channel (number
379
of channels is set with \fB-f:bits,channels,rate\fP option)\&.
381
It is important to note that by default JACK ports are not connected
382
anywhere (e\&.g\&. to soundcard input/outputs, or to other apps)\&. One thus
383
has to connect the ports with an external program (e\&.g\&. "QJackCtl"
384
or "jack_connect")\&.
386
.IP "JACK input/outputs - \&'jack,clientname,portprefix\&'"
387
\fB"jack,clientname"\fP For simple use scanerios, ecasound provides a way to autoconnect
388
the ecasound ports\&. This can be done with by giving the peer client
389
name as the second parameter to the "jack" object, e\&.g\&. \fB-o jack,clientname\fP\&.
390
As an example, \fB-o jack,system\fP will create an output that is
391
automatically connected to outputs of the default system soundcard\&.
392
The client parameter can be omitted, in which case no automatic
393
connections are made\&.
395
If one needs to change the port prefix (e\&.g\&. "in" in client name
396
"ecasound:in_N"), the prefix can be specified as the third parameter to
397
"jack" object, e\&.g\&. \fB-o jack,,fxout\fP\&. Also the third parameter can be
398
omitted, in which case the default prefixes "in" and "out" are used\&.
400
.IP "JACK input/outputs - \&'jack_multi\&'"
401
A variant of \&'jack\&' object type is \&'jack_multi\&'\&. The full object syntax
402
is \fBjack_multi,destport1,\&.\&.\&.,destportN\fP\&. When a \&'jack_multi\&' object
403
is connected to a JACK server, first channel of the object is connected
404
to JACK port \&'destport1\&', second to \&'destport2\&' and so forth\&. For
405
instance "-f:32,2,44100 -o jack_multi,foo:in,bar:in"
406
creates a stereo ecasound output object, with its left and right
407
channels routed to two difference JACK clients\&. The destination ports
408
must be active when the ecasound engine is launched, or otherwise
409
the connections cannot be established\&. If destination ports are not
410
specified for all channels, or zero length strings are given, those
411
ports are not connected at launch by ecasound\&.
413
.IP "JACK input/outputs - \&'jack_alsa\&', \&'jack_auto\&', \&'jack_generic\&' (**deprecated since 2\&.6\&.0**)"
414
Ecasound 2\&.5 and older supported "jack_alsa", "jack_auto" and "jack_generic" object
415
types, but these are now replaced by a more generic "jack" interface, and thus are
416
now deprecated (they work but are no longer documented)\&.
418
.IP "JACK input/outputs - client options"
351
419
Additionally global JACK options can be set using
352
\fB-G:jack,client_name,operation_mode\fP\&. \&'client_name\&'
420
\fB-G:jack,client_name,operation_mode\fP option\&. \&'client_name\&'
353
421
is the name used when registering ecasound to the JACK system\&.
354
422
If \&'operation_mode\&' is "notransport", ecasound will ignore
355
423
any transport state changes in the JACK-system; in mode
356
"send" it will send all start, stop and
357
position-change events to other JACK clients; in
358
mode "recv" ecasound will follow JACK start, stop and
359
position-change events; and mode "sendrecv" (the default) which
360
is a combination of the two previous modes\&.
424
"send" it will send all start, stop and position-change events to
425
other JACK clients; in mode "recv" ecasound will follow JACK start,
426
stop and position-change events; and mode "sendrecv" (the default)
427
which is a combination of the two previous modes\&.
362
429
More details about ecasound\&'s JACK support can be found
363
from ecasound user\&'s guide\&.
430
from Ecasound User\&'s Guide\&.
432
.IP "Libaudiofile - \&'audiofile\&'"
366
433
If libaudiofile support was enabled at compile-time, this
367
434
option allows you to force Ecasound to use libaudiofile
368
435
for reading/writing a certain audio file\&. Option syntax
369
436
is \fB-i:audiofile,foobar\&.ext\fP (same for \fB-o\fP)\&.
438
.IP "Libsndfile - \&'sndfile\&'"
372
439
If libsndfile support was enabled at compile-time, this
373
440
option allows you to force Ecasound to use libsndfile
374
441
for reading/writing a certain audio file\&. Option syntax
389
456
Note: this \&'loop\&' device is different from \&'audioloop\&' (latter
390
457
added to ecasound v2\&.5\&.0)\&.
459
.IP "Mikmod - \&'mikmod\&'"
393
460
If mikmod support was enabled at compile-time, this
394
461
option allows you to force Ecasound to use Mikmod
395
462
for reading/writing a certain module file\&. Option syntax
396
463
is \fB-i:mikmod,foobar\&.ext\fP\&.
398
.IP "Null inputs/outputs"
465
.IP "Null inputs/outputs - \&'null\&'"
399
466
If you specify "null" or "/dev/null" as the input or output,
400
467
a null audio device is created\&. This is useful if you just want
401
468
to analyze sample data without writing it to a file\&. There\&'s
402
469
also a realtime variant, "rtnull", which behaves just like "null"
403
470
objects, except all i/o is done at realtime speed\&.
405
.IP "Resample - access object of different sample rates"
472
.IP "Resample - \&'resample\&'"
406
473
Object type \&'resample\&' can be used to resample audio
407
474
object\&'s audio data to match the sampling rate used
408
475
in the active chainsetup\&. For example,
864
939
\fBINTERACTIVE MODE\fP
866
See \fIecasound-iam man page\fP\&.
941
See \fIecasound-iam(1)\fP man page\&.
868
943
.SH "ENVIRONMENT"
872
947
If defined, some utility programs and scripts will use
873
948
the \fIECASOUND\fP environment as the default path to
874
949
ecasound executable\&.
876
951
.IP "ECASOUND_LOGFILE"
877
952
Output all debugging messages to a separate log file\&. If defined,
878
953
\fIECASOUND_LOGFILE\fP defines the logfile path\&. This is a good tool for
879
954
debugging ECI/EIAM scripts and applications\&.
881
956
.IP "ECASOUND_LOGLEVEL"
882
957
Select which messages are written to the logfile defined by
883
958
\fIECASOUND_LOGFILE\fP\&. The syntax for \fI-d:level\fP is used\&. If not
884
959
defined, all messages are written\&. Defaults to -d:319 (everything else
885
960
but \&'functions (64)\&' and \&'continuous (128)\&' class messages)\&.
888
963
.SH "RETURN VALUES"
891
966
In interactive mode, ecasound always returns zero\&.
893
968
In non-interactive (batch) mode, a non-zero value is returned
894
969
for the following errors:
897
972
Unable to create a valid chainsetup with the given parameters\&. Can be
898
973
caused by invalid option syntax, etc\&.
901
976
Unable to start processing\&. This can be caused by insufficient file
902
977
permissions, inability to access some system resources, etc\&.
905
980
Error during processing\&. Possible causes: output object has run
906
981
out of free disk space, etc\&.
911
986
\fI~/\&.ecasound\fP
912
987
The default directory for ecasound user resource files\&.
913
988
See the ecasoundrc (5) man page man page\&.
916
991
Ecasound Chainsetup files\&. Syntax is more or less the
917
992
same as with command-line arguments\&.
920
995
Ecasound Chain Preset files\&. Used for storing effect
921
996
and chain operator presets\&. See ecasound user\&'s guide for
922
997
more better documentation\&.
925
1000
Ecasound Wave Stats\&. These files are used to cache
926
1001
waveform data\&.
931
1006
Examples of how to perform common tasks with ecasound can
933
1008
http://eca\&.cx/ecasound/Documentation/examples\&.html\&.
938
1013
ecatools (1) man page,
939
1014
ecasound-iam (1) man page
940
1015
ecasoundrc (5) man page,
941
1016
"HTML docs in the Documentation subdirectory"
946
1021
See file BUGS\&. If ecasound behaves weirdly, try to
947
1022
increase the debug level to see what\&'s going on\&.
952
1027
Kai Vehmanen, <kvehmanen -at- eca -dot- cx <kvehmanen -at- eca -dot- cx>>
added
removed
Documentation/ecasound.1
