Ecasound is a text-mode sound processing program that can do
various tasks from basic editing and effect processing to multitrack
recording. Although the user interface may seem a bit cryptic, one of
the main design goals of this project has been to create an
easy-to-use, creative utility for recording and mixing purposes.
Because of the simple interface, batch files can be used to automate
complex editing tasks.
OPTIONS
Notice that the order of parameters given on the command
line is important!
GLOBAL OPTIONS
-c
Starts ecasound in interactive mode. In interactive mode you can
control ecasound with simple commands ("start", "stop", "pause",
etc.).
-d:debug level
Set the debug level. Default is 0.
-q
Quiet mode, no output.
CHAINSETUP OPTIONS
-n:name
Set 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 in 'name'.
-s chainsetup-file
Create a new chainsetup from the 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 active at a time, you can switch between them on-the-fly.
GENERAL
-a:chainname1, chainname2, ...
Sets active signal chains. All effects, inputs and outputs are assigned to
these chains. If there are no -a options given, default chain is used.
Chain name 'all' is reserved and means that all chains are active. 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.
-b:buffer size
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.
-m:mix-mode
Force ecasound to use mix mode 'mix_mode'. 'auto' = automatic (default),
'simple' = only one input/chain/output, 'normal' = normal single-threaded
mode and 'mthreaded' = multithreaded mixing. In most cases, ecasound is
able to find out the correct mode automatically.
-r
Raise process priority. Improves realtime performance.
INPUT/OUTPUT SETUP
-i input-file-or-device
Specifies a new input source. It is assigned to the active chains.
Assigned multiple inputs to the same chain is currently not possible.
The given input can be a normal file or an audio device. File format
is determined using the file name extension. Currently supported
formats are RIFF WAVE files (.wav), audio-cd tracks (.cdr), ecasound
ewf-files (.ewf), MPEG files (.mp2,.mp3), ecasynth configuration files
(.ess), OSS audio devices (/dev/dsp*) and ALSA audio devices
(/dev/snd/pcm*). If no inputs are specified, the first non-option on
the command line (if any) is considered to be a input. Notice! When
using ALSA drivers, you can also you the following option syntax
-i[:]alsa,card_number,device_number.
-o output-file-or-device
Acts in the same way as the -i option. If no no outputs are specified,
the default output device is used (see ˜/.ecasoundrc).
System standars streams
You can use standard stream (stdin and stdout) by giving "stdin"
or "stdout" as the file name. The format is the same as with
raw/headerless (.raw) audio files.
-f:bits,channel,sample-rate
Sets active sampling parameters. These are used for all following input and
output files or until another -f is spesified. If no -f option is
present, ecasound tries to get the parameters from the audio object
(for instance RIFF WAVE header). If no valid sample parameters are
found, defaults are used (16 bits, 2 channels, 44100 samples per
second).
EFFECT SETUP
-ps:preset_name
Insert single-chain preset 'preset_name' to active chains.
See ecasoundrc(5) for info about the preset file.
SIGNAL ANALYSIS
-ev
Normalize sample data by finding 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.
-ezf
Find the optimal value for DC-adjusting. You can use the result
as a parameter to -ezx effect.
GENERAL SIGNAL PROCESSING ALGORITHMS
-ea:amplify-%,max-clipped-samples
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.
-eas:amplify-%
Otherwise like -ea, but doesn't warn about clipped samples.
-ec:rate,threshold
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).
-eca:peak-level-%, release_time, fastrate, rate
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
is 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 (mono-summed signal used to control the gate).
When signal amplitude falls below 'threshold_level_%' percent
(100% means maximum amplitude) the 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.
-epp:right-%
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 -f option to force conversion to mono before panning.
-ezx:left-dc-fix-value,right-dc-fix-value
Adjusts the signal DC by 'dc-fix-value'. Use -ezf to find the
optimal value.
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.
-etr:delay-time,surround-mode,feedback-%
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.
-etf:delay_time
Fake-stereo effect. The input signal is summed to mono. The
original signal goes to the left channels while a delayd
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.
FILTER EFFECTS
-ef1:center_freq, width
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.
-efb:center_freq,width
Bandpass filter. 'center_freq' is the center frequency. Width
is specified in Hz.
-efh:cutoff_freq
Highpass filter. Only frequencies above 'cutoff_freq' are passed
through.
-efi:delay_in_samples,radius
Inverse comb filter. Allows the spikes of the comb to pass through.
The comb consists of 'delay_in_samples/2' spikes. The maximum
value for 'radius' is 1.0. The closer it is to the maximum value,
the deeper the dips of the comb.
-efl:cutoff_freq
Lowpass filter. Only frequencies below 'cutoff_freq' are passed
through.
-efr:center_freq,width
Bandreject filter. 'center_freq' is the center frequency. Width
is specified in Hz.
-efs:center_freq,width
Resonator. 'center_freq' is the center frequency. Width is specified
in Hz. Basicly just another resonating bandpass filter.
GATE SETUP
-gc:start-time,len
Time crop gate. Initially gate is closed. After 'start-time' seconds
has elapse, gate opens and remains open for 'len' seconds.
-ge:othreshold%, cthold%,volume_mode
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.
CONTROL ENVELOPE SETUP
Controllers can be used to dynamically change effect parameters
during processing. All controllers are attached to the active
(=the last effect/chainop you specified) effect. The first
three parameters are ommon for all controllers. 'fx_param'
specifies the parameter to be controlled. Value '1' means
the first parameter, '2' the second and so on. 'low_range'
and 'high_range' set the value range. You really should see
example.html for some more info.
-kos:fx_param,low_range,high_range,freq,i_phase
Sine oscillator with frequency of 'freq' Hz and initial phase
of 'i_phase' times pi.
-kf:fx_param,low_range,high_range,genosc_number
Generic oscillator. 'genosc_number' is the number of the
oscillator preset to be loaded. The location for the preset
file is taken from ./ecasoundrc (see ecasoundrc(5).
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.
INTERACTIVE MODE
The interactive mode of ecasound is launched with the -c option. In
this mode, ecasound reacts to the following commands:
'quit', 'q'
Quits ecasound.
'exec'
Ecasound starts the processing engine. Normally you don't need to use
this.
'end'
Ecasound exits the processing engine, but doesn't exit the interactive
mode. Normally you don't need to use this.
'start', 't'
Processing is started (play).
'stop', 's'
Stops processing.
'rewind time-in-seconds', 'rw time-in-seconds'
Rewind the current position by 'time-in-seconds' seconds.
'forward time-in-seconds', 'fw time-in-seconds'
The current position is forwarded by 'time-in-seconds' seconds.
'setpos time-in-seconds'
Sets the current position to 'time-in-seconds' seconds from the
beginning.
'status','st','u'
General status info.
'cstatus','cs','a'
Status info about the effect chains.
'estatus', 'es','x'
Status info about effects and controller envelopes.
'fstatus', 'fs','l'
Status info about open files and devices.
'sfx'
Enable/disable the sound effects section.
'chain chainname', 'c chainname'
Enable/disable the the chain 'chainname'.
'loop'
Start/stop looping.
'loop_start seconds_from_start'
Set the start point for looping.
loop_end seconds_from_start'
Set the end point for looping.
'load file_name'
Load a chainsetup from file 'file_name' and set it active.
'save file_name'
Save the active chainsetup to file 'file_name'.
'help', 'h'
Help!
FILES
~/.ecasoundrc
The default ecasound resource file. See ecasoundrc(5)
man page.
SEE ALSO
qtecasound (1), ecasoundrc(5), "HTML docs in the Documentation subdirectory"
BUGS
Lots of... ;) See the file BUGS. If ecasound behaves weirdly, try to
increase the debug level to see what's going on.