<html><head>
<title>ecasound</title>
<link rev="made" href="mailto:kvehmanen -at- eca -dot- cx">
</head>
<body>
<hr>
<h1>ecasound</h1>
<h2>16.08.2008</h2>
<html><head>
<link rev="made" href="mailto:kvehmanen -at- eca -dot- cx">
</head>
<body>
<hr>
<h1></h1>
<html><head>
<title>ecasound(1)</title>
<link rev="made" href="mailto:kvehmanen -at- eca -dot- cx">
</head>
<body>
<hr>
<h1>ecasound(1)</h1>
<h2> Multimedia software</h2>
<h2>16.08.2008</h2>
<p>
<h2>NAME</h2>ecasound - sample editor, multitrack recorder, fx-processor, etc.
<p>
<h2>SYNOPSIS</h2>
<strong>ecasound</strong> [ general_options ] { [ chain_setup ] [ effect_setup ] [ input_setup ] [ output_setup ] }
<p>
<h2>DESCRIPTION</h2>
<p>
Ecasound is a software package designed for multitrack audio
processing. It can be used for simple tasks like audio playback,
recording and format conversions, as well as for multitrack effect
processing, mixing, recording and signal recycling. Ecasound supports
a wide range of audio inputs, outputs and effect algorithms.
Effects and audio objects can be combined in various ways, and their
parameters can be controlled by operator objects like oscillators
and MIDI-CCs. A versatile console mode user-interface is included
in the package.
<p>
<h2>OPTIONS</h2>
<p>
Note! All options except those mentioned in <em>ecasound options</em> and
<em>Global options</em>, can be used in ecasound chainsetup files (.ecs).
<p>
<strong>ECASOUND OPTIONS</strong>
<p>
These options are parsed and handled by the ecasound frontbed binary and
are not passed to backend library. This means that these options may
not work in other applications that use ecasound libraries for their
functionality.
<p>
<dl>
<p><dt><strong>-c</strong><dd>
Starts ecasound in interactive mode. In interactive mode you can
control ecasound with simple commands ("start", "stop", "pause",
etc.). See <a href="ecasound-iam_manpage.html">ecasound-iam </a>.
<p>
<p><dt><strong>-C</strong><dd>
Disables ecasound's interactive mode (see '-c' and '-K').
</dl>
<p>
<p><dt><strong>-D</strong><dd>
Print all debug information to stderr (unbuffered, plain output
without ncurses).
<p>
<p><dt><strong>-s[:]chainsetup-file</strong><dd>
Create a new chainsetup from file 'chainsetup-file' and add
it to the current session. Chainsetup files commonly have
a filename ending to the '.ecs' extension. A chainsetup can
contain inputs, outputs, chains, effects, controllers -- i.e.
objects one one specific configuration of audio processing
elements. A session, on the other hand, is a collection of
one or more chainsetups. Only one of the chainsetups may be
connected (i.e. it can be run/processed). But it is possible
to have another chainsetup select (i.e. can be configured)
while other one is current connteced (i.e. running).
<p>
<p><dt><strong>-E "cmd1 [[args] ; cmd2 args ; ... ; cmdN]"</strong><dd>
Execute a set of Ecasound Interactive mode (EIAM) commands
at launch. These commands are executed immediately after
ecasound is started. If the command line contains sufficient
options to create a valid chainsetup that will be executed,
the launch commands are executed after the other command
line options are parsed, but before the processing engine
is started. Note that this command is a feature of
the ecasound frontend binary and not supported by
the library backend. This means that other clients may
not support the '-E' option, and also that the launch
commands are not saved as part of chainsetup or session
state.
<p>
<p><dt><strong>--daemon</strong><dd>
Enable ecasound's daemon mode. If this option is given,
ecasound will allow clients to connect to the running
ecasound session using a TCP/IP network connection.
The clients can both observe and control the session.
<p>
<em>Warning!</em> As there is no access control implemented,
be sure to block ecasound's port in your firewall
if the machine running ecasound is connected to
a public network! Otherwise anyone can connect to
your ecasound sessions.
<p>
<p><dt><strong>--daemon-port</strong><dd>
Set the TCP port used by the daemon mode. By default
ecasound will use port number <em>2868</em>.
<p>
<p><dt><strong>--nodaemon</strong><dd>
Disable ecasound's daemon mode. This is the default.
<p>
<p><dt><strong>--keep-running,-K</strong><dd>
Do not exit when processing is finished/stopped. Only affects
non-interactive operating mode (see -c/-C).
Option added to ecasound 2.4.2.
<p>
<p><dt><strong>--help,-h</strong><dd>
Show this help.
<p>
<p><dt><strong>--version</strong><dd>
Print version info.
<p>
<strong>GLOBAL OPTIONS</strong>
<p>
<dl>
<p>
<p><dt><strong>-d, -dd, -ddd</strong><dd>
Increase the amount of printed debug messages. <em>-d</em> adds
some verbosity, while <em>-ddd</em> results in very detailed
output.
<p>
<p><dt><strong>-d:debug_level</strong><dd>
Set the debug level mask to 'debug_level'. This a bitmasked value with
the following classes: errors (1), info (2), subsystems (4), module_names (8),
user_objects (16), system_objects 32, functions (64), continuous (128) and
eiam_return_values (256). Default is 271 (1+2+4+8+256). See sourcode
documentation for the ECA_LOGGER class for more detailed information.
<p>
<p><dt><strong>-R[:]path-to-file</strong><dd>
Use ecasound resource file (see ecasoundrc man page) 'path-to-file' as
the only source of setting resource value. Specifying this option
will disable the normal policy of querying both global and user (if exists)
resource files.
<p>
<p><dt><strong>-q</strong><dd>
Quiet mode, no output. Same as <em>-d:0</em>.
<p>
</dl>
<p>
<strong>GENERAL CHAINSETUP OPTIONS</strong>
<dl>
<p>
<p><dt><strong>-a:chainname1, chainname2, ...</strong><dd>
Selects active signal chains. All inputs and outputs following
this '-a' option are assigned to selected chains (until a new -a
option is specified). When adding effects, controllers and other
chain operators, only one chain can be selected at a time. If no -a option
has been given, chain 'default' is used instead when adding objects.
Chain name 'all' is also reserved. It will cause all existing chains
to be selected. By giving multiple -a options, you can control to which
chains effects, inputs and outputs are assigned to. Look at the <strong>EXAMPLES</strong>
section for more detailed info about the usage of this option.
<p>
<p><dt><strong>-n:name</strong><dd>
Sets the name of chainsetup to 'name'. If not specified, defaults
either to "command-line-setup" or to the file name from which
chainsetup was loaded. Whitespaces are not allowed.
<p>
<p><dt><strong>-x</strong><dd>
Truncate outputs. All output object are opened in overwrite mode.
Any existing files will be truncated.
<p>
<p><dt><strong>-X</strong><dd>
Open outputs for updating. Ecasound opens all outputs - if target
format allows it - in readwrite mode.
<p>
<p><dt><strong>-z:feature</strong><dd>
Enables 'feature'. Most features can be disabled using notation
<em>-z:nofeature</em>. '-z:db,dbsize' enables double-buffering for audio
objects that support it (dbsize=0 for default, otherwise buffer
size in sample frames). '-z:nodb' disables double-buffering.
'-z:intbuf' and '-z:nointbuf' control whether extra internal buffering
is allowed for realtime devices. Disabling this can reduce
latency times in some situations. With '-z:xruns', processing will be
halted if an under/overrun occurs. '-z:multitrack' and
'z:nomultitrack' can be used to force ecasound to enable or disable
multitrack-mode. In rare cases you may want to explicitly specify
the recording offset with '-z:multitrack,offset-in-samples'. The
offset is the amount of samples skipped when recording from
real-time inputs. '-z:psr' enables the <em>precise-sample-rates</em> mode
for OSS-devices. '-z:mixmode,sum' enables mixing mode where channels
are mixed by summing all channels. The default is '-z:mixmode,avg',
in which channels are mixed by averaging. Mixmode selection was first
added to ecasound 2.4.0.
See <a href="ecasoundrc_manpage.html">ecasoundrc man page</a>.
<p>
</dl>
<p>
<strong>CHAINSETUP BUFFERING AND PERFORMANCE OPTIONS</strong>
<dl>
<p>
<p><dt><strong>-B:buffering_mode</strong><dd>
Selects the default buffering mode. Mode is one of: 'auto' (default),
'nonrt', 'rt', 'rtlowlatency'.
<p>
<p><dt><strong>-b:buffer size</strong><dd>
Sets the size of buffer in samples (must be an exponent of 2). This
is quite an important option. For real-time processing, you should
set this as low as possible to reduce the processing delay. Some
machines can handle buffer values as low as 64 and 128. In some
circumstances (for instance when using oscillator envelopes) small
buffer sizes will make envelopes act more smoothly. When not processing
in real-time (all inputs and outputs are normal files), values between
512 - 4096 often give better results. Default is 1024.
<p>
<p><dt><strong>-r:sched_priority</strong><dd>
Use realtime scheduling policy (SCHED_FIFO). This is impossible if
ecasound doesn't have root priviledges. Beware! This gives better
performance, but can cause total lock-ups if something goes wrong.
The 'sched_priority' can be omitted (0=omitted). If given,
this is the static priority to the highest priority ecasound thread.
Other ecasound threads run with priority 'sched_priority-1...n'.
Value '-1' can be used to disable raised-priority mode.
<p>
<p><dt><strong>-z:feature</strong><dd>
Relevant features are -z:db,xxx (-z:nodb) and -z:intbuf (-z:nointbuf).
See section <em>General chainsetup options</em> for details.
<p>
</dl>
<p>
<strong>PROCESSING CONTROL</strong>
<dl>
<p><dt><strong>-t:seconds</strong><dd>
Sets processing time in seconds (doesn't have to be an integer value).
If processing time isn't set, engine stops when all inputs are
finished. This option is equivalent to the 'cs-set-length' EIAM
command. A special-case value of '-1' will set the chainsetup length
according to the longest input object.
<p>
<p><dt><strong>-tl</strong><dd>
Enables looping. When processing is finished, engine will start
again from beginning. This option is equivalent to the 'cs-loop'
EIAM command.
<p>
</dl>
<p>
<strong>INPUT/OUTPUT SETUP</strong>
<p>
See <a href="users_guide/html_uguide/users_guide.html">ecasound user's guide</a> for
more detailed documentation.
<p>
<dl>
<p><dt><strong>-G:mgrtype,optstring</strong><dd>
Sets options for audio object manager type 'mgrtype'.
For available options, see "OBJECT TYPE SPECIFIC NOTES" below.
<p>
<p><dt><strong>-f:sample_format,channel,sample-rate,interleaving</strong><dd>
Sets default sampling parameters. These are used for all following
input and output files or until another -f is specified. If no -f
option is present, ecasound will use the default audio parameters (see
ecasoundrc man page). Notice that when opening existing audio objects,
either for input or output, the default audio parameters set with -f are
ignored if objects provide sufficient header information (as
is the case for wav, aiff, etc formats). For output objects, the
-x option can be used to completely overwrite existing files
(in other words, with -x, default audio parameters set with -f are used).
<p>
Sample format is given as a a formatted string. The first letter is
either "u", "s" and "f" (unsigned, signed, floating point). The
following number specifies sample size in bits. If sample is
little endian, "_le" is added to the end. Similarly if big endian,
"_be" is added. If endianess is not specified, host byte-order is used.
Currently supported formats are "u8" (same as "8"), "s16_le" (same
as "16"), "s16_be", "s24_le", "s24_be", "s32_le", "s32_be", "f32_le"
and "f32_be".
<p>
The 4th parameter 'interleaving' should either be 'i' (default) for
interleaved stream format, or 'n' for noninterleaved.
<p>
<p><dt><strong>-y:seconds</strong><dd>
Sets starting position for last specified input/output. If
you need more flexible control over audio objects, you should
use the <em>.ewf</em> format.
<p>
<p><dt><strong>-i[:]input-file-or-device[,params]</strong><dd>
Specifies a new input source that is connected to all selected chains.
Connecting multiple inputs to the same chain isn't possible. Input
can be a a file, device or some other audio object (see below).
If the input is a file, its type is determined using the file name
extension. If the object name contains any commas, the name must be
enclosed in backquotes to avoid confusing the parser. Currently supported
formats are RIFF WAVE files (.wav), audio-cd tracks (.cdr), ecasound
EWF files (.ewf), RAW audio data (.raw) and MPEG files (.mp2,.mp3). Also,
formats supported by the SGI audiofile library: AIFF (.aiff, .aifc, .aif) and
Sun/NeXT audio files (.au, .snd). MikMod is also supported (.xm, .mod, .s3m,
.it, etc). MIDI files (.mid) are supported using Timidity++. Similarly
Ogg Vorbis (.ogg) can be read and written if ogg123 and vorbize tools
are installed, FLAC files (.flac) with flac command-line tools or using
libsndfile, and AAC files (.aac/.m4a/.mp4) with faad2/faac tools. Supported
realtime devices are OSS audio devices (/dev/dsp*), ALSA audio and loopback
devices and JACK audio subsystem. If no inputs are specified, the first
non-option (doesn't start with '-') command line argument is considered
to be an input.
<p>
<p><dt><strong>-o[:]output-file-or-device[,params]</strong><dd>
Works in the same way as the -i option. If no outputs are specified,
the default output device is used (see ~/.ecasoundrc). If the object
name contains any commas, the name must be enclosed in backquotes to
avoid confusing the parser. Note, you can't output to module formats
supported by MikMod (this should be obvious).
<p>
<em>OBJECT TYPE SPECIFIC NOTES</em>
<p><dt><strong>ALSA devices</strong><dd>
When using ALSA drivers, instead of a device filename, you need to
use the following option syntax: <strong>-i[:]alsa,pcm_device_name</strong>.
<p>
<p><dt><strong>ALSA direct-hw and plugin access</strong><dd>
It's also possible to use a specific card and device combination
using the following notation: <strong>-i[:]alsahw,card_number,device_number,subdevice_number</strong>.
Another option is the ALSA PCM plugin layer. It works just like
the normal ALSA pcm-devices, but with automatic channel count and
sample format conversions. Option syntax is
<strong>-i[:]alsaplugin,card_number,device_number,subdevice_number</strong>.
<p>
<p><dt><strong>aRts input/output</strong><dd>
If enabled at compile-time, ecasound supports audio input and
output using aRts audio server. Option syntax is <strong>-i:arts</strong>,
<strong>-o:arts</strong>.
<p>
<p><dt><strong>Audio file sequecing</strong><dd>
Ecasound provides a set of special audio object types that
can be used for temporal sequencing of audio files - i.e. looping,
playing only a select portion of a file, playing file at a spefific
time, and other such operation.
<p>
Looping is possible with <strong>-i:audioloop,file.ext,params</strong>. The
file name (or any object type understood by Ecasound) given
as the second parameter is played back continuously looping
back to the beginning when the end of file is reached. Any additional
parameters given are passed unaltered to the file object.
Parameters 3...N are passed as is to the child object (i.e.
"-i audioloop,foo.wav,bar1,bar2" will pass parameters
"bar1,bar2" to the "foo.wav" object.
<p>
To select and use only a specific segment of an audio object,
the <strong>-i:select,start-time,duration,file.ext,params</strong> can
be used. This will play "duration" of "file.ext", starting at
"start-time". The time values should be given as seconds (e.g.
"2.25", or as samples (e.g. "25000sa"). Parameters 4...N are
passed as is to the child object.
<p>
To play an audio object at a given moment in time,
the <strong>-i:playat,play-at-time,file.ext,params</strong> can be
used. This will play "file.ext" after position reaches
"play-at-time". The time values should be given as seconds (e.g.
"2.25", or as samples (e.g. "25000sa"). Parameters 2...N are
passed as is to the child object.
<p>
<p><dt><strong>Ecasound Wave Files (EWF) - .ewf</strong><dd>
A special file format that allows to slice and loop full (or segments)
of audio files. This format is specific to Ecasound.
See <a href="users_guide/html_uguide/users_guide.html">ecasound user's guide</a> for more
detailed information.
<p>
See also audio object types 'audioloop', 'select' and 'playat'.
<p>
<p><dt><strong>JACK input/outputs</strong><dd>
JACK is a low-latency audio server that can be used to connect
multiple independent audio application to each other.
It is different from other audio server efforts in that
it has been designed from the ground up to be suitable for low-latency
professional audio work.
<p>
Ecasound provides multiple ways to communicate with JACK servers. To
directly input or output to soundcard, use <strong>-i jack_alsa</strong> and <strong>-o
jack_alsa</strong>. To communicate with other apps, use
<strong>jack_auto,remote_clientname</strong>. To just create ports without making
any automatic connections, there are <strong>jack</strong> and
<strong>jack_generic,local_portprefix</strong>.
<p>
Additionally global JACK options can be set using
<strong>-G:jack,client_name,operation_mode</strong>. 'client_name'
is the name used when registering ecasound to the JACK system.
If 'operation_mode' is "notransport", ecasound will ignore
any transport state changes in the JACK-system; in mode
"send" it will send all start, stop and
position-change events to other JACK clients; in
mode "recv" ecasound will follow JACK start, stop and
position-change events; and mode "sendrecv" (the default) which
is a combination of the two previous modes.
<p>
More details about ecasound's JACK support can be found
from ecasound user's guide.
<p>
<p><dt><strong>Libaudiofile</strong><dd>
If libaudiofile support was enabled at compile-time, this
option allows you to force Ecasound to use libaudiofile
for reading/writing a certain audio file. Option syntax
is <strong>-i:audiofile,foobar.ext</strong> (same for <strong>-o</strong>).
<p>
<p><dt><strong>Libsndfile</strong><dd>
If libsndfile support was enabled at compile-time, this
option allows you to force Ecasound to use libsndfile
for reading/writing a certain audio file. Option syntax
is <strong>-i:sndfile,foobar.ext[,.format-ext]</strong> (same for <strong>-o</strong>).
The optional third parameter "format" can be used to
override the audio format (for example you can create an
AIFF file with filename "foo.wav").
<p>
<p><dt><strong>Loop device</strong><dd>
Loop devices make it possible to route (loop back) data between
chains. Option syntax is <strong>-[io][:]loop,tag</strong>. If you add
a loop output with tag '1', all data written to this output is routed
to any loop input with tag '1'. The tag can be either numerical
(e.g. '-i:loop,1') or a string (e.g. "-i:loop,vocals"). Like
with other input/output objects, you can attach the same loop
device to multiple chains and this way split/mix the signal.
<p>
Note: this 'loop' device is different from 'audioloop' (latter
added to ecasound v2.5.0).
<p>
<p><dt><strong>Mikmod</strong><dd>
If mikmod support was enabled at compile-time, this
option allows you to force Ecasound to use Mikmod
for reading/writing a certain module file. Option syntax
is <strong>-i:mikmod,foobar.ext</strong>.
<p>
<p><dt><strong>Null inputs/outputs</strong><dd>
If you specify "null" or "/dev/null" as the input or output,
a null audio device is created. This is useful if you just want
to analyze sample data without writing it to a file. There's
also a realtime variant, "rtnull", which behaves just like "null"
objects, except all i/o is done at realtime speed.
<p>
<p><dt><strong>Resample - access object of different sample rates</strong><dd>
Object type 'resample' can be used to resample audio
object's audio data to match the sampling rate used
in the active chainsetup. For example,
<strong>ecasound -f:16,2,44100 -i resample,22050,foo.wav -o /dev/dsp</strong>,
will resample file from 22.05kHz to 44.1kHz and write the
result to the soundcard device. Child sampling rate can be
replaced with keyword 'auto'. In this case ecasound will try
to query the child object for its sampling rate. This works with
files formats such as .wav which store meta information about
the audio file format. To use 'auto' in the previous example,
<strong>ecasound -f:16,2,44100 -i resample,auto,foo.wav -o /dev/dsp</strong>.
<p>
Parameters 4...N are passed as is to the child object (i.e.
"-i resample,22050,foo.wav,bar1,bar2" will pass parameters
"bar1,bar2" to the "foo.wav" object.
<p>
If ecasound was compiled with support for libsamplerate, you can
use 'resample-hq' to use the highest quality resampling algorithm
available. To force ecasound to use the internal resampler,
'resampler-lq' (low-quality) can be used.
<p>
<p><dt><strong>Reverse - process audio data backwards</strong><dd>
Object type 'reverse' can be used to reverse audio
data coming from an audio object. As an example,
<strong>ecasound -i reverse,foo.wav -o /dev/dsp</strong> will play
'foo.wav' backwards. Reversing output objects is not
supported. Note! Trying to reverse audio object types with really
slow seek operation (like mp3), works extremely badly.
Try converting to an uncompressed format (wav or raw)
first, and then do reversation.
<p>
Parameters 3...N are passed as is to the child object (i.e.
"-i reverse,foo.wav,bar1,bar2" will pass parameters
"bar1,bar2" to the "foo.wav" object.
<p>
<p><dt><strong>System standard streams and named pipes</strong><dd>
You can use standard streams (stdin and stdout) by giving <strong>stdin</strong>
or <strong>stdout</strong> as the file name. Audio data is assumed to be in
raw/headerless (.raw) format. If you want to use named pipes,
create them with the proper file name extension before use.
<p>
<p><dt><strong>Tone generator</strong><dd>
To generate a test tone, input <strong>-i:tone,type,freq,duration-secs</strong>
can be used. Parameter 'type' specifies the tone type: currently
only 'sine' is supported. The 'freq' parameter sets the frequency
of the generated tone and 'duration-secs' the length of the generated
stream. Specifying zero, or a negative value, as the duration will
produce an infinite stream. This feature was first added to Ecasound
2.4.7.
<p>
<p><dt><strong>Typeselect - overriding object type settings</strong><dd>
The special 'typeselect' object type can be used to override
how ecasound maps filename extensions and object types. For
instance <strong>ecasound -i typeselect,.mp3,an_mp3_file.wav -o /dev/dsp</strong>.
would play the file 'an_mp3_file.wav' as an mp3-file and not
as an wav-file as would happen without typeselect.
<p>
Parameters 4...N are passed as is to the child object (i.e.
"-i typeselect,.au,foo.wav,bar1,bar2" will pass parameters
"bar1,bar2" to the "foo.wav" object.
<p>
</dl>
<p>
<strong>MIDI SETUP</strong>
<p>
<dl>
<p><dt><strong>MIDI I/O devices - general</strong><dd>
If no MIDI-device is specified, the default MIDI-device is
used (see ecasoundrc ).
<p>
<p><dt><strong>-Md:rawmidi,device_name</strong><dd>
Add a rawmidi MIDI I/O device to the setup. 'device_name' can be anything
that can be accessed using the normal UNIX file operations and
produces raw MIDI bytes. Valid devices are for example OSS rawmidi
devices (/dev/midi00), ALSA rawmidi devices (/dev/snd/midiC2D0), named
pipes (see mkfifo man page), and normal files.
<p>
<p><dt><strong>-Md:alsaseq,sequencer-port</strong><dd>
Adds a ALSA MIDI sequencer port to the setup. 'sequencer-port' identifies
a port to connect to. It can be numerical (e.g. 128:1), or a client
name (e.g. "KMidimon").
<p>
<p><dt><strong>-Mms:device_id</strong><dd>
Sends MMC start and stop to MIDI device-id 'device_id'.
<p>
<p><dt><strong>-Mss</strong><dd>
Sends MIDI-sync to the selected MIDI-device. Note! Ecasound will not
send <em>MIDI-clock</em>, but only <em>start</em> and <em>stop</em> messages.
<p>
</dl>
<p>
<strong>EFFECT SETUP</strong>
<p>
<em>PRESETS</em>
<p>
Ecasound has a powerful effect preset system that allows you create
new effects by combining basic effects and controllers. See
<a href="users_guide/html_uguide/users_guide.html">ecasound user's guide</a> for more
detailed information.
<p>
<dl>
<p>
<p><dt><strong>-pf:preset_file.eep</strong><dd>
Uses the first preset found from file 'preset_file.eep' as
a chain operator.
<p>
<p><dt><strong>-pn:preset_name</strong><dd>
Find preset 'preset_name' from global preset database and use
it as a chain operator. See ecasoundrc man page for info about the
preset database.
<p>
</dl>
<p>
<em>SIGNAL ANALYSIS</em>
<p>
<dl>
<p>
<p><dt><strong>-ev</strong><dd>
Analyzes sample data to find out how much the signal can
be amplified without clipping. The resulting percent value
can be used as a parameter to -ea and -eas effects. Also prints
a statistics table containing info about stereo-image and
how different sample values are used.
<p>
<p><dt><strong>-evp</strong><dd>
Peak amplitude watcher. Maintains peak information for
each processed channels. Peak information is resetted
on every read.
<p>
<p><dt><strong>-ezf</strong><dd>
Finds the optimal value for DC-adjusting. You can use the result
as a parameter to -ezx effect.
<p>
</dl>
<p>
<em>GENERAL SIGNAL PROCESSING ALGORITHMS</em>
<dl>
<p><dt><strong>-eS:stamp-id</strong><dd>
Audio stamp. Takes a snapshot of passing audio data and stores
it using id 'stamp-id' (integer number). This data can later be
used by controllers and other operators.
<p>
<p><dt><strong>-ea:amplify-%</strong><dd>
Amplifies signal by amplify-% percent (linear scale, i.e. individual
samples are multiplied by 'amplify-%/100').
<p>
<p><dt><strong>-eac:amplify-%,channel</strong><dd>
Amplifies signal of channel 'channel' by amplify-% percent (linear
scale, i.e. individual samples are multiplied by 'amplify-%/100').
'channel' ranges from 1...n where n is the total number of channels.
<p>
<p><dt><strong>-eaw:amplify-%,max-clipped-samples</strong><dd>
Amplifies signal by amplify-% percent. If number of consecutive
clipped samples (resulting sample has the largest amplitude
possible) reaches 'max-clipped-samples', a warning will be issued.
<p>
<p><dt><strong>-eal:limit-%</strong><dd>
Limiter effect. Limits audio level to 'limit-%'.
<p>
<p><dt><strong>-ec:rate,threshold-%</strong><dd>
Compressor (a simple one). 'rate' is the compression rate in
decibels ('rate' dB change in input signal causes 1dB change
in output). 'threshold' varies between 0.0 (silence) and
1.0 (max amplitude).
<p>
<p><dt><strong>-eca:peak-level-%, release-time-sec, fast-crate, crate</strong><dd>
A more advanced compressor (original algorithm by John S. Dyson).
If you give a value of 0 to any parameter, the default is used.
'peak-level-%' essentially specifies how hard the peak limiter
is pushed. The default of 69% is good. 'release_time' is given
in seconds. This compressor is very sophisticated, and actually
the release time is complex. This is one of the dominant release
time controls, but the actual release time is dependent on a lot of
factors regarding the dynamics of the audio in. 'fastrate' is the
compression ratio for the fast compressor. This is not really
the compression ratio. Value of 1.0 is infinity to one, while the
default 0.50 is 2:1. Another really good value is special cased in
the code: 0.25 is somewhat less than 2:1, and sounds super smooth.
'rate' is the compression ratio for the entire compressor chain.
The default is 1.0, and holds the volume very constant without many nasty
side effects. However the dynamics in music are severely restricted,
and a value of 0.5 might keep the music more intact.
<p>
<p><dt><strong>-enm:threshold-level-%,pre-hold-time-msec,attack-time-msec,post-hold-time-msec,release-time-msec</strong><dd>
Noise gate. Supports multichannel processing (each channel
processed separately). When signal amplitude falls below
'threshold_level_%' percent (100% means maximum amplitude), gate
is activated. If the signal stays below the threshold for
'th_time' ms, it's faded out during the attack phase of
'attack' ms. If the signal raises above the 'threshold_level'
and stays there over 'hold' ms the gate is released during
'release' ms.
<p>
<p><dt><strong>-ei:pitch-shift-%</strong><dd>
Pitch shifter. Modifies audio pitch by altering its length.
<p>
<p><dt><strong>-epp:right-%</strong><dd>
Stereo panner. Changes the relative balance between the first
two channels. When 'right-%' is 0, only signal on the left
(1st) channel is passed through. Similarly if it is '100',
only right (2nd) channel is let through.
<p>
<p><dt><strong>-ezx:channel-count,delta-ch1,...,delta-chN</strong><dd>
Adjusts the signal DC by 'delta-chX', where X is the
channel number. Use -ezf to find the optimal delta
values.
<p>
</dl>
<p>
<em>ENVELOPE MODULATION</em>
<dl>
<p>
<p><dt><strong>-eemb:bpm,on-time-%</strong><dd>
Pulse gate (pulse frequency given as beats-per-minute).
<p>
<p><dt><strong>-eemp:freq-Hz,on-time-%</strong><dd>
Pulse gate.
<p>
<p><dt><strong>-eemt:bpm,depth-%</strong><dd>
Tremolo effect (tremolo speed given as beats-per-minute).
<p>
</dl>
<p>
<em>FILTER EFFECTS</em>
<dl>
<p><dt><strong>-ef1:center_freq, width</strong><dd>
Resonant bandpass filter. 'center_freq' is the center frequency. Width
is specified in Hz.
<p>
<p><dt><strong>-ef3:cutoff_freq, reso, gain</strong><dd>
Resonant lowpass filter. 'cutoffr_freq' is the filter cutoff
frequency. 'reso' means resonance. Usually the best values for
resonance are between 1.0 and 2.0, but you can use even bigger values.
'gain' is the overall gain-factor. It's a simple multiplier (1.0
is the normal level). With high resonance values it often is useful
to reduce the gain value.
<p>
<p><dt><strong>-ef4:cutoff, resonance</strong><dd>
Resonant lowpass filter (3rd-order, 36dB, original algorithm by Stefan
M. Fendt). Simulates an analog active RC-lowpass design. Cutoff is a
value between [0,1], while resonance is between [0,infinity).
<p>
<p><dt><strong>-efa:delay-samples,feedback-%</strong><dd>
Allpass filter. Passes all frequencies with no change in amplitude.
However, at the same time it imposes a frequency-dependent
phase-shift.
<p>
<p><dt><strong>-efc:delay-samples,radius</strong><dd>
Comb filter. Allows the spikes of the comb to pass through.
Value of 'radius' should be between [0, 1.0).
<p>
<p><dt><strong>-efb:center-freq,width</strong><dd>
Bandpass filter. 'center_freq' is the center frequency. Width
is specified in Hz.
<p>
<p><dt><strong>-efh:cutoff-freq</strong><dd>
Highpass filter. Only frequencies above 'cutoff_freq' are passed
through.
<p>
<p><dt><strong>-efi:delay-samples,radius</strong><dd>
Inverse comb filter. Filters out the spikes of the comb. There
are 'delay_in_samples-2' spikes. Value of 'radius' should be
between [0, 1.0). The closer it is to the maximum value,
the deeper the dips of the comb are.
<p>
<p><dt><strong>-efl:cutoff-freq</strong><dd>
Lowpass filter. Only frequencies below 'cutoff_freq' are passed
through.
<p>
<p><dt><strong>-efr:center-freq,width</strong><dd>
Bandreject filter. 'center_freq' is the center frequency. Width
is specified in Hz.
<p>
<p><dt><strong>-efs:center-freq,width</strong><dd>
Resonator. 'center_freq' is the center frequency. Width is specified
in Hz. Basicly just another resonating bandpass filter.
<p>
</dl>
<p>
<em>CHANNEL MIXING / ROUTING</em>
<dl>
<p>
<p><dt><strong>-chcopy:from-channel, to-channel</strong><dd>
Copy channel 'from_channel' to 'to_channel'. If 'to_channel'
doesn't exist, it is created. Channel indexing starts from 1.
Option added to ecasound 2.4.5.
<p>
<p><dt><strong>-chmove:from-channel, to-channel</strong><dd>
Copy channel 'from_channel' to 'to_channel', and mutes the source
channel 'from_channel'. Channel indexing starts from 1.
Option added to ecasound 2.4.5.
<p>
<p><dt><strong>-chmix:to-channel</strong><dd>
Mix all channels to channel 'to_channel'. If 'to_channel'
doesn't exist, it is created. Channel indexing starts from 1.
Option added to ecasound 2.4.5.
<p>
<p><dt><strong>-chmute:channel</strong><dd>
Mutes the channel 'channel'. Channel indexing starts from 1.
Option added to ecasound 2.4.5.
<p>
<p><dt><strong>-erc:from-channel,to-channel</strong><dd>
Deprecated, see <em>-chcopy</em>.
<p>
<p><dt><strong>-erm:to-channel</strong><dd>
Deprecated, see <em>-chmix</em>.
<p>
</dl>
<p>
<em>TIME-BASED EFFECTS</em>
<dl>
<p>
<p><dt><strong>-etc:delay-time-msec,variance-time-samples,feedback-%,lfo-freq</strong><dd>
Chorus.
<p>
<p><dt><strong>-etd:delay-time-msec,surround-mode,number-of-delays,mix-%,feedback-%</strong><dd>
Delay effect. 'delay time' is the delay time in milliseconds.
'surround-mode' is a integer with following meanings: 0 = normal,
1 = surround, 2 = stereo-spread. 'number_of_delays' should be
obvious. Beware that large number of delays and huge delay times
need a lot of CPU power. 'mix-%' determines how much effected (wet)
signal is mixed to the original. 'feedback-%' represents how much of
the signal is recycled in each delay or, if you prefer, at what rate
the repeated snippet of delayed audio fades. Note that sufficiently
low feedback values may result in a number of audible repetitions
lesser than what you have specified for 'number_of_delays', especially
if you have set a low value for 'mix-%'. By default the value for this
parameter is 100% (No signal loss.).
<p>
<p><dt><strong>-ete:room_size,feedback-%,wet-%</strong><dd>
A more advanced reverb effect (original algorithm by Stefan M. Fendt).
'room_size' is given in meters, 'feedback-%' is the feedback level
given in percents and 'wet-%' is the amount of reverbed signal added
to the original signal.
<p>
<p><dt><strong>-etf:delay-time-msec</strong><dd>
Fake-stereo effect. The input signal is summed to mono. The
original signal goes to the left channels while a delayed
version (with delay of 'delay time' milliseconds) is goes to
the right. With a delay time of 1-40 milliseconds this
adds a stereo-feel to mono-signals.
<p>
<p><dt><strong>-etl:delay-time-msec,variance-time-samples,feedback-%,lfo-freq</strong><dd>
Flanger.
<p>
<p><dt><strong>-etm:delay-time-msec,number-of-delays,mix-%</strong><dd>
Multitap delay. 'delay time' is the delay time in milliseconds.
'number_of_delays' should be obvious. 'mix-%' determines how much
effected (wet) signal is mixed to the original.
<p>
<p><dt><strong>-etp:delay-time-msec,variance-time-samples,feedback-%,lfo-freq</strong><dd>
Phaser.
<p>
<p><dt><strong>-etr:delay-time,surround-mode,feedback-%</strong><dd>
Reverb effect. 'delay time' is the delay time in milliseconds.
If 'surround-mode' is 'surround', reverbed signal moves around the
stereo image. 'feedback-%' determines how much effected (wet)
signal is fed back to the reverb.
<p>
</dl>
<p>
<em>LADSPA-PLUGINS</em>
<dl>
<p><dt><strong>-el:plugin_unique_name,param-1,...,param-N</strong><dd>
Ecasound supports LADSPA-effect plugins (Linux Audio Developer's Simple
Plugin API). Plugins are located in shared library (.so) files in
/usr/local/share/ladspa (configured in ecasoundrc man page). One shared
library file can contain multiple plugin objects, but every plugin
has a unique plugin name. This name is used for selecting plugins.
See <a href="http://www.linuxdj.com/audio/lad">LAD mailing list web site</a> for
more info about LADSPA. Other useful sites are <a href="http://www.ladspa.org">LADSPA home
page</a> and <a href="http://www.ffem.org/gdam/ladspa-doc/ladspa.html">LADSPA
documentation</a>.
<p>
<p><dt><strong>-eli:plugin_unique_number,param-1,...,param-N</strong><dd>
Same as above expect plugin's unique id-number is used. It
is guaranteed that these id-numbers are unique among all
LADSPA plugins.
<p>
</dl>
<p>
<strong>GATE SETUP</strong>
<p>
<dl>
<p>
<p><dt><strong>-gc:start-time,len</strong><dd>
Time crop gate. Initially gate is closed. After 'start-time' seconds
has elapsed, gate opens and remains open for 'len' seconds. When
closed, passing audio buffers are trucated to zero length.
<p>
<p><dt><strong>-ge:open-threshold-%,close-thold-%,volume-mode,reopen-count</strong><dd>
Threshold gate. Initially gate is closed. It is opened when volume
goes over 'othreshold' percent. After this, if volume drops below
'cthold' percent, gate is closed and won't be opened again, unless the
'reopen-count' is set to anything other than zero.
If 'value_mode' is 'rms', average RMS volume is used. Otherwise
peak average is used. When closed, passing audio buffers are trucated
to zero length.
If the 'reopen-count' is set to a positive number, then the gate will
restart its operation that many times. So for example, a reopen count
of 1 will cause up to 2 openings of the gate. A negative value for 'reopen-count'
will result in the gate reopening indefinitely. The 'reopen-count' is invaluable
in recording vinyl and tapes, where you can set things up and then recording
starts whenever the needle is on the vinyl, and stops when it's off. As many sides
as you like can be recorded in one session. You will need to experiment with
buffer lengths and start/stop levels to get reliable settings for your equipment.
<p>
</dl>
<p>
<strong>CONTROL ENVELOPE SETUP</strong>
<dl>
<p>
Controllers can be used to dynamically change effect parameters
during processing. All controllers are attached to the selected
(=usually the last specified effect/controller) effect. The first
three parameters are common for all controllers. 'fx_param'
specifies the parameter to be controlled. Value '1' means
the first parameter, '2' the second and so on. 'start_value'
and 'end_value' set the value range. For examples, look at the
the <strong>EXAMPLES</strong> section.
<p>
<p><dt><strong>-kos:fx-param,start-value,end-value,freq,i-phase</strong><dd>
Sine oscillator with frequency of 'freq' Hz and initial phase
of 'i_phase' times pi.
<p>
<p><dt><strong>-kog:fx-param,freq,mode,point-pairs,start-value,end-value,pos1,value1,...</strong><dd>
Generic oscillator. Frequency 'freq' Hz, mode either '0' for
static values or '1' for linear interpolation. 'point-pairs'
specifies the number of 'posN' - 'valueN' pairs to include.
'start-value' and 'end-value' are used as border values.
All 'posN' and 'valueN' must be between 0.0 and 1.0. Also,
for all 'posN' values 'pos1 < pos2 < ... < posN' must be true.
<p>
<p><dt><strong>-kf:fx-param,start-value,end-value,freq,mode,genosc-number</strong><dd>
Generic oscillator. 'genosc_number' is the number of the
oscillator preset to be loaded. Mode is either '0' for
static values or '1' for linear interpolation. The location for
the preset file is taken from ./ecasoundrc (see <em>ecasoundrc man page</em>).
<p>
<p><dt><strong>-kl:fx-param,start-value,end-value,time-seconds</strong><dd>
Linear envelope that starts from 'start_value' and linearly
changes to 'end_value' during 'time_in_seconds'. Can
be used for fadeins and fadeouts.
<p>
<p><dt><strong>-kl2:fx-param,start-value,end-value,1st-stage-length-sec,2nd-stage-length-sec</strong><dd>
Two-stage linear envelope, a more versatile tool for doing fade-ins
and fade-outs. Stays at 'start_value' for '1st_stage_length' seconds
and then linearly changes towards 'end_value' during
'2nd_stage_length' seconds.
<p>
<p><dt><strong>-klg:fx-param,low-value,high-value,point_count,pos1,value1,...,posN,valueN</strong><dd>
Generic linear envelope. This controller source can be
used to map custom envelopes to chain operator parameters. Number of
envelope points is specified in 'point_count'. Each envelope point
consists of a position and a matching value. Number of pairs must
match 'point_count' (i.e. 'N==point_count'). The 'posX' parameters are given
as seconds (from start of the stream). The envelope points are specified as
float values in range '[0,1]'. Before envelope values are mapped to operator
parameters, they are mapped to the target range of '[low-value,high-value]'. E.g.
a value of '0' will set operator parameter to 'low-value' and a value of
'1' will set it to 'high-value'. For the initial segment '[0,pos1]', the envelope
will output value of 'value1' (e.g. 'low-value').
<p>
<p><dt><strong>-km:fx-param,start-value,end-value,controller,channel</strong><dd>
MIDI continuous controller (control change messages).
Messages on the MIDI-channel 'channel' that are coming from
controller number 'controller' are used as the controller
source. As recommended by the MIDI-specification, channel
numbering goes from 1 to 16. Possible controller numbers
are values from 0 to 127. The MIDI-device where bytes
are read from can be specified using <em>-Md</em> option.
Otherwise the default MIDI-device is used as specified in
<em>~ecasound/ecasoundrc</em> (see <em>ecasoundrc man page</em>).
Defaults to <em>/dev/midi</em>.
<p>
<p><dt><strong>-ksv:fx-param,start-value,end-value,stamp-id,rms-toggle</strong><dd>
Volume analyze controller. Analyzes the audio stored in
stamp 'stamp-id' (see '-eS:id' docs), and creates
control data based on the results. If 'rms-toggle' is non-zero,
RMS-volume is used to calculate the control value. Otherwise
average peak-amplitude is used.
<p>
<p><dt><strong>-kx</strong><dd>
This is a special switch that can be used when you need
to control controller parameters with another controller.
When you specify <em>-kx</em>, the last specified controller
will be set as the control target. Then you just add
another controller as usual.
</dl>
<p>
<strong>INTERACTIVE MODE</strong>
<p>
See <em>ecasound-iam man page</em>.
<p>
<h2>ENVIRONMENT</h2>
<p>
<dl>
<p><dt><strong>ECASOUND</strong><dd>
If defined, some utility programs and scripts will use
the <em>ECASOUND</em> environment as the default path to
ecasound executable.
<p>
<p><dt><strong>ECASOUND_LOGFILE</strong><dd>
Output all debugging messages to a separate log file. If defined,
<em>ECASOUND_LOGFILE</em> defines the logfile path. This is a good tool for
debugging ECI/EIAM scripts and applications.
<p>
<p><dt><strong>ECASOUND_LOGLEVEL</strong><dd>
Select which messages are written to the logfile defined by
<em>ECASOUND_LOGFILE</em>. The syntax for <em>-d:level</em> is used. If not
defined, all messages are written. Defaults to -d:319 (everything else
but 'functions (64)' and 'continuous (128)' class messages).
</dl>
<p>
<h2>RETURN VALUES</h2>
<p>
In interactive mode, ecasound always returns zero.
<p>
In non-interactive (batch) mode, a non-zero value is returned
for the following errors:
<p>
<dl>
<p><dt><strong>1</strong><dd>
Unable to create a valid chainsetup with the given parameters. Can be
caused by invalid option syntax, etc.
<p>
<p><dt><strong>2</strong><dd>
Unable to start processing. This can be caused by insufficient file
permissions, inability to access some system resources, etc.
<p>
<p><dt><strong>3</strong><dd>
Error during processing. Possible causes: output object has run
out of free disk space, etc.
<p>
<h2>FILES</h2>
<p>
<em>~/.ecasound</em>
The default directory for ecasound user resource files.
See the <a href="ecasoundrc_manpage.html">ecasoundrc (5) man page</a> man page.
<p>
<em>*.ecs</em>
Ecasound Chainsetup files. Syntax is more or less the
same as with command-line arguments.
<p>
<em>*.ecp</em>
Ecasound Chain Preset files. Used for storing effect
and chain operator presets. See <a href="users_guide/html_uguide/users_guide.html">ecasound user's guide</a> for
more better documentation.
<p>
<em>*.ews</em>
Ecasound Wave Stats. These files are used to cache
waveform data.
<p>
<h2>EXAMPLES</h2>
<p>
Examples of how to perform common tasks with ecasound can
be found at
<a href="http://eca.cx/ecasound/Documentation/examples.html">http://eca.cx/ecasound/Documentation/examples.html</a>.
<p>
<h2>SEE ALSO</h2>
<p>
<a href="ecatools_manpage.html">ecatools (1) man page</a>,
<a href="ecasound-iam_manpage.html">ecasound-iam (1) man page</a>
<a href="ecasoundrc_manpage.html">ecasoundrc (5) man page</a>,
<a href="index.html">"HTML docs in the Documentation subdirectory"</a>
<p>
<h2>BUGS</h2>
<p>
See file BUGS. If ecasound behaves weirdly, try to
increase the debug level to see what's going on.
<p>
<h2>AUTHOR</h2>
<p>
Kai Vehmanen, <<a href="mailto:kvehmanen -at- eca -dot- cx"><em>kvehmanen -at- eca -dot- cx</em></a>>
