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. Several
open-source audio packages, like for instance ALSA, OSS, mpg123, lame,
libaudiofile and MikMod, are directly supported. One of the advantages
of ecasound's chain-based design is that effects can easily be
combined both in series and in parallel. Oscillators and MIDI-CCs
can be used for controlling effect parameters. Included user-interfaces
are ecasound - a versatile console mode interface, qtecasound -
a Qt-based X-interface and various command-line utils suitable for
Note! All options except those mentioned in Global options, can
be used in ecasound chainsetup files (.ecs).
Starts ecasound in interactive mode. In interactive mode you can
control ecasound with simple commands ("start", "stop", "pause",
etc.). See ecasound-iam(1).
Disables ecasound's interactive mode (see '-c').
Set the debug level to 'debug_level'. This a bitmasked value,
that defaults to 3. See ECA_DEBUG class documentation for
more detailed info about various debug_level values.
Print all debug information to stderr (unbuffered, plain output
Quiet mode, no output. Same as -d:0.
Show this help.
Print version info.
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.
Create a new chainsetup from file 'chainsetup-file' and add
it to the current session. Chainsetup can contain inputs, outputs,
chains, effects, controllers, etc. A session, on the other hand,
contains all the chainsetups. Although only one chainsetup can
be connected at a time, you can switch between them on-the-fly.
GENERAL CHAINSETUP OPTIONS
-a:chainname1, chainname2, ...
Selects active signal chains. All effects, inputs and outputs following
this '-a' option are assigned to selected chains (until a new -a
option is specified). If no -a option has been given, chain 'default' is
used instead. Chain name 'all' is also reserved and means that all chains
are selected. By giving multiple -a options, you can control to which
chains effects, inputs and outputs are assigned to. Look at the EXAMPLES
section for more detailed info about the usage of this option.
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.
Forces ecasound to use mix mode 'mix_mode'. 'auto' = automatic (default),
'simple' = only one input/chain/output and 'normal' = normal
single-threaded mode. In most cases, ecasound is able to find out
the correct mode automatically.
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.
Sets internal sampling rate. This can be used to improve
realtime performance or to avoid resampling. Default is 44100
samples per second.
Truncate outputs. All output object are opened in overwrite mode.
Any existing files will be truncated.
Open outputs for updating. Ecasound opens all outputs - if target
format allows it - in readwrite mode.
Enables 'feature'. Most features can be disabled using notation
-z:nofeatures. '-z:db,dbsize' enables double-buffering for audio
objects that support it (dbzise=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:psr' enables the precise-sample-rates
mode for OSS-devices. See ecasoundrc(5).
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
Enables looping. When processing is finished, engine will start
again from the initial position. This option is equivalent to the
'cs-loop' EIAM command.
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 uses s16_le/2ch/44100/interleaved as the
default value. Some audio objects may override this altogether (for
instance, RIFF WAVE inputs and outputs).
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"
The 4th parameter 'interleaving' should either be 'i' (default) for
interleaved stream format, or 'n' for noninterleaved.
Sets starting position for last specified input/output. If
you need more flexible control over audio objects, you should
use the .ewf format.
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. 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. Supported realtime devices are OSS audio devices
(/dev/dsp*), ALSA audio and loopback devices. If no inputs are
specified, the first non-option (doesn't start with '-') command
line argument is considered to be an input.
Works in the same way as the -i option. If no outputs are specified,
the default output device is used (see ˜/.ecasoundrc). Note!
you can't output to module formats supported by MikMod (this should
be obvious) nor to ALSA's loopback device.
OBJECT TYPE SPECIFIC NOTES
When using ALSA drivers, instead of a device filename, you need to
use the following option syntax: -i[:]alsa,pcm_device_name.
Note! Pcm device naming was introduced in ALSA 0.6.x (doesn't work
with older ALSA versions; see below for the old syntax).
ALSA direct-gw and plugin access
It's also possible to use a specific card and device combination
using the following notation: -i[:]alsahw,card_number,device_number,subdevice_number.
The ALSA plugin layer works just like the normal ALSA pcm-devices, but
with automatic sample rate and format conversions. Option syntax is
ALSA loopback device
By using the ALSA loopback system, you can grab audio data from any
other pcm device. Option syntax is
Note! Only works with ALSA 0.5.x and older.
If enabled at compile-time, ecasound supports audio input and
output using aRts audio server. Option syntax is -i:arts,
Ecasound Wave Files - .ewf
A simple wrapper class for handling other audio objects.
See ecasound user's guide for more
Loop devices make it possible to route data between chains.
Option syntax is -[io][:]loop,id_number. If you add a loop
output with id '1', all data written to this output is routed
to all loop inputs with id '1'. You can attach the same loop
device to multiple inputs and outputs.
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.
System standard streams and named pipes
You can use standard streams (stdin and stdout) by giving "stdin"
or "stdout" 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.
Sets the active MIDI-device. '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), named pipes (see mkfifo(1) man page), and
normal files. If no MIDI-device is specified, the default MIDI-device
is used (see ecasoundrc(5)).
Sends MMC start and stop to MIDI device-id 'device_id'.
Sends MIDI-sync to the selected MIDI-device. Note! Ecasound will not
send MIDI-clock, but only start and stop messages.
Ecasound has a powerful effect preset system that allows you create
new effects by combining basic effects and controllers. See
ecasound user's guide for more
Uses the first preset found from file 'preset_file.eep' as
a chain operator.
Find preset 'preset_name' from global preset database and use
it as a chain operator. See ecasoundrc(5) for info about the
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.
Finds the optimal value for DC-adjusting. You can use the result
as a parameter to -ezx effect.
GENERAL SIGNAL PROCESSING ALGORITHMS
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.
Amplifies signal by amplify-% percent.
Amplifies signal of channel 'channel' by amplify-% percent. 'channel'
ranges from 1...n where n is the total number of channels.
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.
Limiter effect. Limits audio level to 'limit-%'.
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).
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.
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
Pitch shifter. Modifies audio pitch by altering its length.
Normal pan effect. Balance value of 0 means to pan signal fully
left and 100 fully right. If the panned signal is
a stereo signal, left and right channels aren't mixed together.
Use the -erm and -erc effects to force conversion to mono before
Adjusts the signal DC by 'dc-fix-value'. Use -ezf to find the
Pulse gate (pulse frequency given as beats-per-minute).
Tremolo effect (tremolo speed given as beats-per-minute).
Resonant bandpass filter. 'center_freq' is the center frequency. Width
is specified in Hz.
-ef3:cutoff_freq, reso, gain
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.
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).
Allpass filter. Passes all frequencies with no change in amplitude.
However, at the same time it imposes a frequency-dependent
Comb filter. Allows the spikes of the comb to pass through.
Value of 'radius' should be between [0, 1.0).
Bandpass filter. 'center_freq' is the center frequency. Width
is specified in Hz.
Highpass filter. Only frequencies above 'cutoff_freq' are passed
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.
Lowpass filter. Only frequencies below 'cutoff_freq' are passed
Bandreject filter. 'center_freq' is the center frequency. Width
is specified in Hz.
Resonator. 'center_freq' is the center frequency. Width is specified
in Hz. Basicly just another resonating bandpass filter.
CHANNEL MIXING / ROUTING
Copy channel 'from_channel' to 'to_channel'. If 'to_channel'
doesn't exist, it is created. Channel indexing is started from 1.
Mix all channels to channel 'to_channel'. If 'to_channel'
doesn't exist, it is created. Channel indexing is started from 1.
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.
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.
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.
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.
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(5)). 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 LAD mailing list web site for
more info about LADSPA. Other useful sites are LADSPA home
page and LADSPA
Same as above expect plugin's unique id-number is used. It
is guaranteed that these id-numbers are unique among all
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.
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.
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.
CONTROL ENVELOPE SETUP
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. You really should see
examples.html for some more info.
Sine oscillator with frequency of 'freq' Hz and initial phase
of 'i_phase' times pi.
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.
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 ecasoundrc(5)).
Linear envelope that starts from 'start_value' and linearly
changes to 'end_value' during 'time_in_seconds'. Can
be used for fadeins and fadeouts.
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
Generic linear envelope. This controller source can be
used to map custom envelopes to chain operator parameters.
All 'posX' parameters are given as seconds (from start of the stream).
'valueX' parameters must be in the range [0,1].
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. The MIDI-device is specified in ./ecasoundrc (see
ecasoundrc(5)). Defaults to /dev/midi.
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.
This is a special switch that can be used when you need
to control controller parameters with another controller.
When you specify -kx, the last specified controller
will be set as the control target. Then you just add
another controller as usual.
The default ecasound resource file. See ecasoundrc(5).
Ecasound Chainsetup files. Syntax is more or less the
same as with command-line arguments.
Ecasound Chain Preset files. Used for storing effect
and chain operator presets. See ecasound user's guide for
more better documentation.
Ecasound Wave Stats. These files are used to cache