ecasound(1) Multimedia software ecasound(1)NAMEecasound - sample editor, multitrack recorder, fx-processor, etc.
SYNOPSISecasound [ 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 ecasound options and Global
options, can be used in ecasound chainsetup files (.ecs).
ECASOUND OPTIONS
These options are parsed and handled by the ecasound frontend
binary and are not passed to backend library. This means that
these options may not work in other applications that use eca‐
sound libraries for their functionality.
-c Starts ecasound in interactive mode. In interactive mode you can
control ecasound with simple commands ("start", "stop", "pause",
etc.). See ecasound-iam .
-C Disables ecasound’s interactive mode (see ’-c’ and ’-K’).
-D Print all debug information to stderr (unbuffered, plain output
without ncurses).
-s[:]chainsetup-file
Create a new chainsetup from file ’chainsetup-file’ and add it
to the current session. Chainsetup files commonly have a file‐
name 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).
-E "cmd1 [[args] ; cmd2 args ; ... ; cmdN]"
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 com‐
mands 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.
--server
Enables the so called NetECI mode, in which ecasound can be con‐
trolled remotely over a socket connection. When activated,
clients can connect to the running ecasound session, and use
interactive mode commands to control and observe ecasound pro‐
cessing.
The NetECI protocol is defined in Ecasound’s Programmer Guide
One example client using this feature is ecamonitor(1). This
utility is included in the Ecasound distribution package
(requires a working Python environment).
Warning! If the machine running ecasound, is connected to a pub‐
lic network, be sure to block ecasound’s port in your firewall!
As there is no access control implemented for incoming connec‐
tions, anyone can otherwise connect, control and observe your
ecasound sessions. This option replaces ’--daemon’ (deprecated
in 2.6.0).
--server-tcp-port=NNN
Set the TCP port used by the daemon mode. By default ecasound
will use port number 2868. This option replaces ’--daemon-port’
(deprecated in 2.6.0).
--no-server
Disable ecasound’s daemon mode. This is the default. This
option replaces ’--nodaemon’ (deprecated in 2.6.0).
--osc-udp-port=NNN
Enables support for Open Source Control (OSC). Ecasound will
listen for incoming OSC messages on UDP port NNN. Ecasound’s OSC
interface is documented at: <http://ecasound.git.source‐
forge.net/git/gitweb.cgi?p=ecasound/ecasound;a=blob;f=Documenta‐
tion/ecasound_osc_interface.txt;hb=HEAD>
Note that OSC support is still experimental and the interface
might change in later versions of Ecasound.
This option was added to ecasound 2.7.0.
--keep-running,-K
Do not exit when processing is finished/stopped. Only affects
non-interactive operating mode (see -c/-C). Option added to
ecasound 2.4.2.
--help,-h
Show this help.
--version
Print version info.
GLOBAL OPTIONS
-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 with the following classes: errors (1), info (2), subsys‐
tems (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.
-R[:]path-to-file
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 query‐
ing both global and user (if exists) resource files.
-q Quiet mode, no output. Same as -d:0.
GENERAL CHAINSETUP OPTIONS
-a:chainname1, chainname2, ...
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 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 (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’, pro‐
cessing will be halted if an under/overrun occurs. ’-z:multi‐
track’ 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,off‐
set-in-samples’. The offset is the amount of samples skipped
when recording from real-time inputs. ’-z:psr’ enables the pre‐
cise-sample-rates 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 ecasoundrc man page.
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 processing engine buffer size in samples. The size must
be an exponent of 2, and it is independent of channel count
(e.g. -b:1024 at 48kHz will result in 21.333ms buffer length
whether input is mono, stereo or 5.1).
This is an important option as this defines the length of one
processing engine iteration and affects ecasound behaviour in
many ways. If not explicitly specified, ecasound will try to
choose an optimal value based on current buffering mode (see -B
option). For real-time processing, you can try to 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 circum‐
stances (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), larger values may help to avoid buffer overruns, lower
CPU usage and/or otherwise improve performance.
Note that when any JACK input/outputs are used, the buffer size
setting is overridden and set to period/buffer size reported by
JACK server (e.g. jackd’s ’-p’ option). It is not possible to
turn off this behaviour.
If not explicitly specified, the default buffer size is chosen
based on current buffering mode (see -B).
-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. A special-case value of ’-1’ will
set the chainsetup length according to the longest input object.
-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
See ecasound user’s guide for more detailed documentation.
-G:mgrtype,optstring
Sets options for audio object manager type ’mgrtype’. For
available options, see "OBJECT TYPE SPECIFIC NOTES" below.
-f:sample_format,channel,sample-rate,interleaving
Sets the audio stream parameters for subsequent audio objects.
To set different parameters for different audio objects, multi‐
ple ’-f’ options have to be specified (note the ordering, the
’-f’ options should precede the audio objects for them to have
any effect). See documentation for ’-i’ and ’-o’ options.
When an audio object is opened (e.g. a file or sound device is
opened, or connection is made to a sound server), the audio
stream parameters are passed to the object. It should be noted
that not all audio objects allow to set any or all of the param‐
eters. For instance when opening existing audio files, many
file formats have a header describing the file audio parameters.
In these cases the audio file header overrides the parameters
passed with ’-f’ option. Similarly when creating JACK inputs and
outputs, the JACK server mandates the sampling rate and sample
format.
If no ’-f’ option is specified, or some of the argument fields
are left empty (e.g. ’-f:,2,44100’), ecasound will use default
values. These default values are defined in ecasoundrc configu‐
ration file. See ecasoundrc(5) manual page.
Note that ecasound opens out files by default in update mode.
Unless option ’-x’ (overwrite outputs) option is given, audio
parameters of an existing audio file take preference over the
params set with ’-f’.
Sample format is given as 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 endianness 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". An empty string ""
picks the system default sample format.
The 4th parameter defines the channel layout. The available
options are ’i’ (interleaved’ and ’n’ (noninterleaved). With the
noninterleaved setting, ecasound will process samples one chan‐
nel at a time, and the blocksize is set with ’-b’. The default
setting is ’i’.
-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[,params]
Specifies a new input source that is connected to all selected
chains (chains are selected with ’-a:...’). Connecting multiple
inputs to the same chain is not possible, but one input can be
connected to multiple chains. 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 back‐
quotes to avoid confusing the parser. Currently supported for‐
mats are RIFF WAVE files (.wav), audio-cd tracks (.cdr), eca‐
sound EWF files (.ewf), RAW audio data (.raw) and MPEG audio
files (.mp2,.mp3). More audio formats are supported via libau‐
diofile and libsndfile libraries (see documentation below). 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; 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 sub‐
system. 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[,params]
Works in the same way as the -i option. If no outputs are speci‐
fied, 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, many object
types do not support output (e.g. MikMod, MIDI and many others).
OBJECT TYPE SPECIFIC NOTES
ALSA devices - ’alsa’
When using ALSA drivers, instead of a device filename, you need
to use the following option syntax: -i[:]alsa,pcm_device_name.
ALSA direct-hw and plugin access - ’alsahw’, ’alsaplugin’
It’s also possible to use a specific card and device combination
using the following notation: -i[:]alsahw,card_num‐
ber,device_number,subdevice_number. 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 -i[:]alsaplugin,card_num‐
ber,device_number,subdevice_number.
aRts input/output - ’arts’
If enabled at compile-time, ecasound supports audio input and
output using aRts audio server. Option syntax is -i:arts,
-o:arts.
Audio file sequencing - ’audioloop’, ’select’, ’playat’
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 spe‐
fific time, and other such operation.
Looping is possible with -i:audioloop,file.ext,params. 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 param‐
eters given are passed unaltered to the file object. Parameters
3...N are passed as is to the child object (i.e. "-i audi‐
oloop,foo.wav,bar1,bar2" will pass parameters "bar1,bar2" to the
"foo.wav" object.
To select and use only a specific segment of an audio object,
the -i:select,start-time,duration,file.ext,params 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.
To play an audio object at a given moment in time, the
-i:playat,play-at-time,file.ext,params 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.
Ecasound Wave Files (EWF) - ’*.ewf’
A special file format that allows one to slice and loop full (or
segments) of audio files. This format is specific to Ecasound.
See ecasound user’s guide for more detailed information.
See also audio object types ’audioloop’, ’select’ and ’playat’.
JACK input/outputs - Overview
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.
JACK input/outputs - ’jack’
Ecasound provides multiple ways to communicate with JACK
servers. To create a JACK input or output object, one should use
-i jack and -o jack. These create JACK client ports "eca‐
sound:in_N" and "ecasound:out_n" respectively (’N’ is replaced
by the channel number). Ecasound automatically creates one JACK
port for each channel (number of channels is set with
-f:bits,channels,rate option).
It is important to note that by default JACK ports are not con‐
nected anywhere (e.g. to soundcard input/outputs, or to other
apps). One thus has to connect the ports with an external pro‐
gram (e.g. "QJackCtl" or "jack_connect").
JACK input/outputs - ’jack,clientname,portprefix’
"jack,clientname" For simple use scanerios, ecasound provides a
way to autoconnect the ecasound ports. This can be done with by
giving the peer client name as the second parameter to the
"jack" object, e.g. -o jack,clientname. As an example, -o
jack,system will create an output that is automatically con‐
nected to outputs of the default system soundcard. The client
parameter can be omitted, in which case no automatic connections
are made.
If one needs to change the port prefix (e.g. "in" in client name
"ecasound:in_N"), the prefix can be specified as the third
parameter to "jack" object, e.g. -o jack,,fxout. Also the third
parameter can be omitted, in which case the default prefixes
"in" and "out" are used.
JACK input/outputs - ’jack_multi’
A variant of ’jack’ object type is ’jack_multi’. The full object
syntax is jack_multi,destport1,...,destportN. When a
’jack_multi’ object is connected to a JACK server, first channel
of the object is connected to JACK port ’destport1’, second to
’destport2’ and so forth. For instance "-f:32,2,44100 -o
jack_multi,foo:in,bar:in" creates a stereo ecasound output
object, with its left and right channels routed to two differ‐
ence JACK clients. The destination ports must be active when the
ecasound engine is launched, or otherwise the connections cannot
be established. If destination ports are not specified for all
channels, or zero length strings are given, those ports are not
connected at launch by ecasound.
JACK input/outputs - ’jack_alsa’, ’jack_auto’, ’jack_generic’ (**depre‐
cated since 2.6.0**)
Ecasound 2.5 and older supported "jack_alsa", "jack_auto" and
"jack_generic" object types, but these are now replaced by a
more generic "jack" interface, and thus are now deprecated (they
work but are no longer documented).
JACK input/outputs - client options
Additionally global JACK options can be set using
-G:jack,client_name,operation_mode option. ’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" which is a
combination of the two previous modes.
If not explicitly set, in interactive mode (’-c’ option), the
default mode is "sendrecv", while in batchmode default is
"notransport". In both cases the mode can be changed with -G
option as described above.
More details about ecasound’s JACK support can be found from
Ecasound User’s Guide.
Libaudiofile - ’audiofile’
If libaudiofile support was enabled at compile-time, this option
allows you to force Ecasound to use libaudiofile for read‐
ing/writing a certain audio file. Option syntax is
-i:audiofile,foobar.ext (same for -o).
Libsndfile - ’sndfile’
If libsndfile support was enabled at compile-time, this option
allows you to force Ecasound to use libsndfile for reading/writ‐
ing a certain audio file. Option syntax is -i:sndfile,foo‐
bar.ext[,.format-ext] (same for -o). The optional third parame‐
ter "format" can be used to override the audio format (for exam‐
ple you can create an AIFF file with filename "foo.wav").
Loop device - ’loop’
Loop devices make it possible to route (loop back) data between
chains. Option syntax is -[io][:]loop,tag. 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.
Note: this ’loop’ device is different from ’audioloop’ (latter
added to ecasound v2.5.0).
Mikmod - ’mikmod’
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 -i:mikmod,foobar.ext.
Null inputs/outputs - ’null’
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 - ’resample’
Object type ’resample’ can be used to resample audio object’s
audio data to match the sampling rate used in the active chain‐
setup. For example, ecasound -f:16,2,44100 -i resam‐
ple,22050,foo.wav -o /dev/dsp, 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, ecasound -f:16,2,44100 -i resam‐
ple,auto,foo.wav -o /dev/dsp.
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.
If ecasound was compiled with support for libsamplerate, you can
use ’resample-hq’ to use the highest quality resampling algo‐
rithm available. To force ecasound to use the internal resam‐
pler, ’resampler-lq’ (low-quality) can be used.
Reverse - ’reverse’
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.
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.
System standard streams and named pipes - ’stdin’, ’stdout’
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.
Tone generator - ’tone’
To generate a test tone, input -i:tone,type,freq,duration-secs
can be used. Parameter ’type’ specifies the tone type: currently
only ’sine’ is supported. The ’freq’ parameter sets the fre‐
quency 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.
Typeselect - ’typeselect’
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.
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.
MIDI SETUP
MIDI I/O devices - general
If no MIDI-device is specified, the default MIDI-device is used
(see ecasoundrc(5)).
-Md:rawmidi,device_name
Add a rawmidi MIDI I/O device to the setup. ’device_name’ can be
anything that can be accessed using the normal UNIX file opera‐
tions 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 nor‐
mal files.
-Md:alsaseq,sequencer-port
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").
-Mms:device_id
Sends MMC start ("Deferred Play") and stop ("Stop") with device
ID ’device_id’.
While Ecasound does not directly support syncing transport state
to incoming MMC messages, this can be achieved by connecting
Ecasound to JACK input/outputs, and using a tool such as JackMMC
and JackCtlMMC ( see <http://jackctlmmc.sourceforge.net/>) to
convert MMC messages into JACK transport change events.
-Mss Sends MIDI-sync (i.e. "MIDI Start" and "MIDI Stop" system real‐
time messages) .to the selected MIDI-device. Notice that as Eca‐
sound will not send MIDI-clock, but only the start and stop mes‐
sages.
EFFECT SETUP
PRESETS
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 detailed information.
-pf:preset_file.eep
Uses the first preset found from file ’preset_file.eep’ as a
chain operator.
-pn:preset_name
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.
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’ (amplify). A statistical summary,
containing info about the stereo-image and distribution of sam‐
ple values, is printed out at the end of processing.
-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%
Adjusts the signal amplitude to ’amplify%’ percent (linear
scale, i.e. individual samples are multiplied by
’amplify%/100’). See also ’-eadb’.
-eac:amplify%,channel
Amplifies signal of channel ’channel’ by amplify-% percent (lin‐
ear scale, i.e. individual samples are multiplied by
’amplify%/100’). ’channel’ ranges from 1...n where n is the
total number of channels. See also ’-eadb’.
-eadb:gain-dB[,channel]
Adjusts signal level by ’gain-dB’, with a gain of 0dB having no
effect to the signal, negative gains attenuating the signal and
positive gain values amplifying it. The ’channel’ parameter
(1...n) is optional. If ’channel’ parameter is specified, and
its value is nonzero, gain is only applied to the given channel
(1...n).
-eaw:amplify%,max-clipped-samples
Amplifies signal by amplify-% percent (linear scale, i.e. indi‐
vidual samples are multiplied by ’amplify%/100’). If number of
consecutive clipped samples (resulting sample value is outside
the nominal [-1,1] range), a warning will be issued.
-eal:limit-%
Limiter effect. Limits audio level to ’limit-%’ (linear scale)
with values equal or greater than 100% resulting in no change to
the signal.
-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-sec, fast-crate, crate
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 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:thresh‐
old-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).
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 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.
CHANNEL MIXING / ROUTING
-chcopy:from-channel, to-channel
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.
-chmove:from-channel, to-channel
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.
-chorder:ch1,...,chN
Reorder, omit and/r duplicate chain channels. The resulting
audio stream has total of ’N’ channels. Each parameter specifies
the source channel to use for given output channel. As an exam‐
ple, ’-chorder:2,1’ would reverse the channels of a stereo
stream (’out1,out2’ = ’in2,in1’). Specifying the same source
channel multiple times is allowed. For example, ’-chorder:2,2’
would route the second channel to both two output channels
(’out1,out2’ = ’in2,in2’). If ’chX’ is zero, the given channel
’X’ will be muted in the output stream. Option added to ecasound
2.7.0.
-chmix:to-channel
Mix all source channels to channel ’to_channel’. If ’to_chan‐
nel’ doesn’t exist, it is created. Channel indexing starts from
1. Option added to ecasound 2.4.5.
-chmute:channel
Mutes the channel ’channel’. Channel indexing starts from 1.
Option added to ecasound 2.4.5.
-erc:from-channel,to-channel
Deprecated, see -chcopy.
-erm:to-channel
Deprecated, see -chmix.
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-%’ expresses the mix balance
between the original and delayed signal, with 0 meaning no
delayed signal, 100 meaning no original signal, and 50 (the
default) achieving an equal balance. ’feedback-%’ represents
how much of the signal is recycled in each delay or, if you pre‐
fer, at what rate the repeated snippet of delayed audio fades.
Note that sufficiently low feedback values may result in a num‐
ber 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 ver‐
sion (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.
-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.
LADSPA-PLUGINS
-el:plugin_unique_name,param-1,...,param-N
Ecasound supports LADSPA-effect plugins (Linux Audio Developer’s
Simple Plugin API). Parameters 1..N are set as values of the
plugin’s control ports.
If plugin has more than one audio input and/or output port, only
one plugin is instance is created, and the chain channels are
fed to the same plugin instance. If plugin has at most one input
and at most one output audio port, a separate plugin instance is
created for each channel of the ecasound chain (e.g. for a
stereo audio channel, two LADSPA plugins of same type are cre‐
ated, with one per channel).
Plugins are located in shared library (.so) files. Ecasound
looks for plugins in @prefix@/lib/ladspa (e.g.
"/usr/local/lib/ladspa"), directories listed in environment
variable LADSPA_PATH. Plugin search path can be configured also
via ecasoundrc, see ecasoundrc(5) 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 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 (-el) expect plugin’s unique id-number is used. It
is guaranteed that these id-numbers are unique among all LADSPA
plugins.
LV2 PLUGINS
-elv2:plugin-id-uri,param-1,...,param-N
Ecasound also supports LV2 audio plugins. LV2 plugins are iden‐
tified by a globally unique, case-sensitive identifier.
If plugin has more than one audio input and/or output port, only
one plugin is instance is created, and the chain channels are
fed to the same plugin instance. If plugin has at most one input
and at most one output audio port, a separate plugin instance is
created for each channel of the ecasound chain (e.g. for a
stereo audio channel, two LV2 plugins of same type are created,
with one per channel).
LV2 is a plugin standard for audio systems.
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,reopen-count
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, 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 buf‐
fers 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.
-gm:state
Manual gate. If ’state’ is 1, gate is open and all samples are
passed through. If ’state’ is zero, gate is closed an no samples
are let through. This chain operator is useful when writing to
an output needs to be stopped dynamically (without stopping the
whole engine).
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. For examples,
look at the the EXAMPLES section.
-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,first-value,last-value,pos1,value1,...
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.
’first-value’ and ’last-value’ are used as border values (values
for position 0.0/first and position 1.0/last). All ’posN’ and
’valueN’ must be between 0.0 and 1.0. Also, for all ’posN’ val‐
ues ’pos1 < pos2 < ... < posN’ must be true.
-kf:fx-param,start-value,end-value,freq,mode,genosc-number
Generic oscillator. ’genosc_number’ is the number of the oscil‐
lator 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 man page).
-kl:fx-param,start-value,end-value,time-seconds
Linear envelope that starts from ’start_value’ and linearly
changes to ’end_value’ during ’time_in_seconds’. Can be used for
fadeins and fadeouts.
-kl2:fx-param,start-value,end-value,1st-stage-length-sec,2nd-stage-length-sec
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.
-klg:fx-param,low-value,high-value,point_count,pos1,value1,...,posN,val‐
ueN
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’).
-km:fx-param,start-value,end-value,controller,channel
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 recom‐
mended 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 -Md
option. Otherwise the default MIDI-device is used as specified
in ~ecasound/ecasoundrc (see ecasoundrc man page). Defaults to
/dev/midi.
-ksv:fx-param,start-value,end-value,stamp-id,rms-toggle
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.
-kx This is a special switch that can be used when you need to con‐
trol 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.
INTERACTIVE MODE
See ecasound-iam(1) man page.
ENVIRONMENT
ECASOUND
If defined, some utility programs and scripts will use the ECA‐
SOUND environment as the default path to ecasound executable.
ECASOUND_LOGFILE
Output all debugging messages to a separate log file. If
defined, ECASOUND_LOGFILE defines the logfile path. This is a
good tool for debugging ECI/EIAM scripts and applications.
ECASOUND_LOGLEVEL
Select which messages are written to the logfile defined by ECA‐
SOUND_LOGFILE. The syntax for -d:level is used. If not defined,
all messages are written. Defaults to -d:319 (everything else
but ’functions (64)’ and ’continuous (128)’ class messages).
COLUMNS
Ecasound honors the COLUMNS environment variable when formatting
printed trace messages. If COLUMNS is not set, a default of 74
is used.
TMPDIR Some functions of Ecasound (e.g. "cs-edit" interactive command)
require creation of temporary files. By default, these files are
created under "/tmp", but this can be overridden by setting the
TMPDIR environment variable.
RETURN VALUES
In interactive mode, ecasound always returns zero.
In non-interactive (batch) mode, a non-zero value is returned
for the following errors:
1 Unable to create a valid chainsetup with the given parameters.
Can be caused by invalid option syntax, etc.
2 Unable to start processing. This can be caused by insufficient
file permissions, inability to access some system resources,
etc.
3 Error during processing. Possible causes: output object has run
out of free disk space, etc.
4 Error during process termination and/or cleanup. See section on
’SIGNALS’ for further details.
SIGNALS
When ecasound receives any of the POSIX signals SIGINT (ctrl-c),
SIGHUP, SIGTERM or SIGQUIT, normal cleanup and exit procedure is initi‐
ated. Here normal exit means that e.g. file headers are updated before
closing, helper processes are terminated in normal way, and so forth.
If, while doing the cleanup described above, ecasound receives another
signal (of the same set of POSIX signals), ecasound will skip the nor‐
mal cleanup procedure, and terminate immediately. Any remaining cleanup
tasks will be skipped. Depending on the runtime state and configura‐
tion, this brute force exit may have some side-effects. Ecasound will
return exit code of ’4’ if normal cleanup was skipped.
Special case handling is applied to the SIGINT (ctrl-c) signal. If a
SIGINT signal is received during the cleanup procedure, ecasound will
ignore the signal once, and emit a notice to ’stderr’ that cleanup is
already in progress. Any subsequent SIGINT signals will no longer get
special handling, and instead process will terminate immediately (and
possibly without proper cleanup).
FILES
~/.ecasound The default directory for ecasound user resource files.
See the ecasoundrc (5) man page man page.
*.ecs Ecasound Chainsetup files. Syntax is more or less the same as
with command-line arguments.
*.ecp Ecasound Chain Preset files. Used for storing effect and chain
operator presets. See ecasound user’s guide for more better documenta‐
tion.
*.ews Ecasound Wave Stats. These files are used to cache waveform data.
EXAMPLES
Examples of how to perform common tasks with ecasound can be found at
http://nosignal.fi/ecasound/Documentation/examples.html.
SEE ALSO
ecatools (1) man page, ecasound-iam (1) man page ecasoundrc (5) man
page, "HTML docs in the Documentation subdirectory"
BUGS
See file BUGS. If ecasound behaves weirdly, try to increase the debug
level to see what’s going on.
AUTHOR
Kai Vehmanen, <kvehmanen -at- eca -dot- cx <kvehmanen -at- eca -dot-
cx>>
05.05.2011 ecasound(1)
