ecasound (1)
NAME
ecasound - sample editor, multitrack recorder, fx-processor, etc.
SYNOPSIS
ecasound [ general_options ] { [ chain_setup ] [ effect_setup ] [
input_setup ] [ output_setup ] }
DESCRIPTION
Ecasound is a software package designed for multitrack audio process-
ing. It can be used for simple tasks like audio playback, recording and
format conversions, as well as for multitrack effect processing, mix-
ing, 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.
OPTIONS
Note! All options except those mentioned in Global options, can be used
in ecasound chainsetup files (.ecs).
GLOBAL OPTIONS
-c Starts ecasound in interactive mode. In interactive mode you can
control ecasound with simple commands ("start", "stop", "pause",
etc.). See ecasound-iam(1).
-C Disables ecasound´s interactive mode (see ´-c´).
-d, -dd, -ddd
Increase the amount of printed debug messages. -d adds some ver-
bosity, while -ddd results in very detailed output.
-d:debug_level
Set the debug level mask to ´debug_level´. This a bitmasked
value, that defaults to 263. See ECA_LOGGER class documentation
for more detailed info about various debug_level values.
-D Print all debug information to stderr (unbuffered, plain output
without ncurses).
-q Quiet mode, no output. Same as -d:0.
-s[:]chainsetup-file
Create a new chainsetup from file ´chainsetup-file´ and add it
using a TCP/IP network connection. The clients can both observe
and control the session.
Warning! 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.
--daemon-port
Set the TCP port used by the daemon mode. By default ecasound
will use port number 2868.
--nodaemon
Disable ecasound´s daemon mode. This is the default.
--help Show this help.
--version
Print version info.
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 mul-
tiple -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.
-n:name
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.
-x Truncate outputs. All output object are opened in overwrite
mode. Any existing files will be truncated.
-X Open outputs for updating. Ecasound opens all outputs - if tar-
get format allows it - in readwrite mode.
-z:feature
Enables ´feature´. Most features can be disabled using notation
-z:nofeature. ´-z:db,dbsize´ enables double-buffering for audio
objects that support it (dbzise=0 for default, otherwise buffer
when recording from real-time inputs. ´-z:psr´ enables the pre-
cise-sample-rates mode for OSS-devices. See ecasoundrc(5).
CHAINSETUP BUFFERING AND PERFORMANCE OPTIONS
-B:buffering_mode
Selects the default buffering mode. Mode is one of: ´auto´
(default), ´nonrt´, ´rt´, ´rtlowlatency´.
-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 out-
puts are normal files), values between 512 - 4096 often give
better results. Default is 1024.
-r:sched_priority
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 eca-
sound thread. Other ecasound threads run with priority
´sched_priority-1...n´. Value ´-1´ can be used to disable
raised-priority mode.
-z:feature
Relevant features are -z:db,xxx (-z:nodb) and -z:intbuf
(-z:nointbuf). See section General chainsetup options for
details.
PROCESSING CONTROL
-t:seconds
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.
-tl Enables looping. When processing is finished, engine will start
again from beginning. This option is equivalent to the ´cs-loop´
EIAM command.
INPUT/OUTPUT SETUP
Sets default sampling parameters. These are used for all follow-
ing input and output files or until another -f is specified. If
no -f option is present, ecasound uses s16_le/2ch/44100/inter-
leaved 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" and "f32_be".
The 4th parameter ´interleaving´ should either be ´i´ (default)
for interleaved stream format, or ´n´ for noninterleaved.
-y:seconds
Sets starting position for last specified input/output. If you
need more flexible control over audio objects, you should use
the .ewf format.
-i[:]input-file-or-device
Specifies a new input source that is connected to all selected
chains. Connecting multiple inputs to the same chain isn´t pos-
sible. 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). Mik-
Mod 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.
-o[:]output-file-or-device
Works in the same way as the -i option. If no outputs are speci-
fied, the default output device is used (see ~/.ecasoundrc).
Note! you can´t output to module formats supported by MikMod
(this should be obvious).
OBJECT TYPE SPECIFIC NOTES
ALSA devices
When using ALSA drivers, instead of a device filename, you need
to use the following option syntax: -i[:]alsa,pcm_device_name.
aRts input/output
If enabled at compile-time, ecasound supports audio input and
output using aRts audio server. Option syntax is -i:arts,
-o:arts.
Ecasound Wave Files - .ewf
A simple wrapper class for handling other audio objects. See
ecasound user´s guide for more detailed information.
JACK input/outputs
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 pro-
fessional audio work.
Ecasound provides multiple ways to communicate with JACK
servers. To directly input or output to soundcard, use -i
jack_alsa and -o jack_alsa. To communicate with other apps, use
jack_auto,remote_clientname. To just create ports without making
any automatic connections, there are jack and
jack_generic,local_portprefix.
Additionally global JACK options can be set using
-G:jack,client_name,operation_mode. ´client_name´ is the name
used when registering ecasound to the JACK system. If ´opera-
tion_mode´ is "notransport", ecasound will ignore any transport
state changes in the JACK-system; in mode "send" (the default)
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" which is a
combination of the two previous modes.
More details about ecasound´s JACK support can be found from
ecasound user´s guide.
Loop device
Loop devices make it possible to route data between chains.
Option syntax is -[io][:]loop,id_number. If you add a loop out-
put 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.
Null inputs/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.
Resample - access object of different sample rates
the previous example, ecasound -f:16,2,44100 -i resam-
ple,auto,foo.wav -o /dev/dsp.
If ecasound was compiled with support for libsamplerate, you can
use ´resample-hq´ to use the highest quality resampling algo-
rithm available.
Reverse - process audio data backwards
Object type ´reverse´ can be used to reverse audio data coming
from an audio object. As an example, ecasound -i reverse,foo.wav
-o /dev/dsp 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.
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.
Typeselect - overriding object type settings
The special ´typeselect´ object type can be used to override how
ecasound maps filename extensions and object types. For instance
ecasound -i typeselect,.mp3,an_mp3_file.wav -o /dev/dsp. would
play the file ´an_mp3_file.wav´ as an mp3-file and not as an
wav-file as would happen without typeselect.
MIDI SETUP
-Md:rawmidi,device_name
Sets the active MIDI-device. ´device_name´ can be anything that
can be accessed using the normal UNIX file operations and pro-
duces 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)).
-Mms:device_id
Sends MMC start and stop to MIDI device-id ´device_id´.
-Mss Sends MIDI-sync to the selected MIDI-device. Note! Ecasound will
not send MIDI-clock, but only start and stop messages.
EFFECT SETUP
PRESETS
-pn:preset_name
Find preset ´preset_name´ from global preset database and use it
as a chain operator. See ecasoundrc(5) for info about the preset
database.
SIGNAL ANALYSIS
-ev 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.
-evp Peak amplitude watcher. Maintains peak information for each pro-
cessed channels. Peak information is resetted on every read.
-ezf Finds the optimal value for DC-adjusting. You can use the result
as a parameter to -ezx effect.
GENERAL SIGNAL PROCESSING ALGORITHMS
-eS:stamp-id
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.
-ea:amplify-%
Amplifies signal by amplify-% percent.
-eac:amplify-%,channel
Amplifies signal of channel ´channel´ by amplify-% percent.
´channel´ ranges from 1...n where n is the total number of chan-
nels.
-eaw:amplify-%,max-clipped-samples
Amplifies signal by amplify-% percent. If number of consecutive
clipped samples (resulting sample has the largest amplitude pos-
sible) reaches ´max-clipped-samples´, a warning will be issued.
-eal:limit-%
Limiter effect. Limits audio level to ´limit-%´.
-ec:rate,threshold-%
Compressor (a simple one). ´rate´ is the compression rate in
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 domi-
nant 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 com-
pressor. 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 compres-
sion 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.
-enm:threshold-level-%,pre-hold-time-msec,attack-time-msec,post-hold-
time-msec,release-time-msec
Noise gate. Supports multichannel processing (each channel pro-
cessed separately). When signal amplitude falls below ´thresh-
old_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.
-ei:pitch-shift-%
Pitch shifter. Modifies audio pitch by altering its length.
-epp:right-%
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.
-ezx:channel-count,delta-ch1,...,delta-chN
Adjusts the signal DC by ´delta-chX´, where X is the channel
number. Use -ezf to find the optimal delta values.
ENVELOPE MODULATION
-eemb:bpm,on-time-%
Pulse gate (pulse frequency given as beats-per-minute).
-eemp:freq-Hz,on-time-%
Pulse gate.
-eemt:bpm,depth-%
Tremolo effect (tremolo speed given as beats-per-minute).
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 multi-
plier (1.0 is the normal level). With high resonance values it
often is useful to reduce the gain value.
-ef4:cutoff, resonance
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).
-efa:delay-samples,feedback-%
Allpass filter. Passes all frequencies with no change in ampli-
tude. However, at the same time it imposes a frequency-depen-
dent phase-shift.
-efc:delay-samples,radius
Comb filter. Allows the spikes of the comb to pass through.
Value of ´radius´ should be between [0, 1.0).
-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-samples,radius
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.
-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 spec-
ified in Hz. Basicly just another resonating bandpass filter.
-erm:to-channel
Mix all channels to channel ´to_channel´. If ´to_channel´
doesn´t exist, it is created. Channel indexing is started from
1.
TIME-BASED EFFECTS
-etc:delay-time-msec,variance-time-samples,feedback-%,lfo-freq
Chorus.
-etd:delay-time-msec,surround-mode,number-of-delays,mix-%,feedback-%
Delay effect. ´delay time´ is the delay time in milliseconds.
´surround-mode´ is a integer with following meanings: 0 = nor-
mal, 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.).
-ete:room_size,feedback-%,wet-%
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.
-etf:delay-time-msec
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.
-etl:delay-time-msec,variance-time-samples,feedback-%,lfo-freq
Flanger.
-etm:delay-time-msec,number-of-delays,mix-%
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.
-etp:delay-time-msec,variance-time-samples,feedback-%,lfo-freq
Phaser.
LADSPA-PLUGINS
-el:plugin_unique_name,param-1,...,param-N
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
documentation.
-eli:plugin_unique_number,param-1,...,param-N
Same as above expect plugin´s unique id-number is used. It is
guaranteed that these id-numbers are unique among all LADSPA
plugins.
GATE SETUP
-gc:start-time,len
Time crop gate. Initially gate is closed. After ´start-time´
seconds has elapsed, gate opens and remains open for ´len´ sec-
onds. When closed, passing audio buffers are trucated to zero
length.
-ge:open-threshold-%, close-thold-%,volume-mode
Threshold gate. Initially gate is closed. It is opened when vol-
ume 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.
-kos:fx-param,start-value,end-value,freq,i-phase
Sine oscillator with frequency of ´freq´ Hz and initial phase of
´i_phase´ times pi.
-kog:fx-param,start-value,end-value,freq,mode,point-pairs,start-
26.08.2003 ecasound(1)