Ubuntu Manpage: ecasound - sample editor, multitrack recorder, fx-processor, etc.

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 processing. It  can  be  used
       for  simple  tasks  like  audio playback, recording and format conversions, as well as for
       multitrack effect processing, mixing, recording and signal recycling. Ecasound supports  a
       wide  range of audio inputs, outputs and effect algorithms.  Effects and audio objects can
       be combined in various ways, and their parameters can be controlled  by  operator  objects
       like  oscillators and MIDI-CCs. A versatile console mode user-interface is included in the
       package.

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 ecasound 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 filename ending to the ’.ecs’ extension.
A chainsetup can contain inputs, outputs, chains, effects, controllers -- i.e.
objects one one specific configuration of audio processing elements. A session, on
the other hand, is a collection of one or more chainsetups. Only one of the
chainsetups may be connected (i.e. it can be run/processed). But it is possible to
have another chainsetup select (i.e. can be configured) while other one is current
connteced (i.e. running).

-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 commands are executed after the other command line options are parsed, but
before the processing engine is started. Note that this command is a feature of the
ecasound frontend binary and not supported by the library backend. This means that
other clients may not support the ’-E’ option, and also that the launch commands
are not saved as part of chainsetup or session state.

--server
Enables the so called NetECI mode, in which ecasound can be controlled 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
processing.

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 public network, be sure
to block ecasound’s port in your firewall! As there is no access control
implemented for incoming connections, 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.sourceforge.net/git/gitweb.cgi?p=ecasound/ecasound;a=blob;f=Documentation/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 verbosity, 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), subsystems (4), module_names (8),
user_objects (16), system_objects 32, functions (64), continuous (128) and
eiam_return_values (256). Default is 271 (1+2+4+8+256). See sourcode documentation
for the ECA_LOGGER class for more detailed information.

-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 querying 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 target 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’, processing will be halted if an under/overrun
occurs. ’-z:multitrack’ and ’z:nomultitrack’ can be used to force ecasound to
enable or disable multitrack-mode. In rare cases you may want to explicitly specify
the recording offset with ’-z:multitrack,offset-in-samples’. The offset is the
amount of samples skipped when recording from real-time inputs. ’-z:psr’ enables
the precise-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 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), 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 ecasound 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, multiple ’-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 parameters. 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 configuration 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 channel 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 backquotes to avoid confusing the parser. Currently
supported formats are RIFF WAVE files (.wav), audio-cd tracks (.cdr), ecasound EWF
files (.ewf), RAW audio data (.raw) and MPEG audio files (.mp2,.mp3). More audio
formats are supported via libaudiofile and libsndfile libraries (see documentation
below). MikMod is also supported (.xm, .mod, .s3m, .it, etc). MIDI files (.mid) are
supported using Timidity++. Similarly Ogg Vorbis (.ogg) can be read, and written
if ogg123 and vorbize tools are installed; FLAC files (.flac) with flac
command-line tools or using libsndfile; and AAC files (.aac/.m4a/.mp4) with
faad2/faac tools. Supported realtime devices are OSS audio devices (/dev/dsp*),
ALSA audio and loopback devices and JACK audio subsystem. If no inputs are
specified, the first non-option (doesn’t start with ’-’) command line argument is
considered to be an input.

-o[:]output-file-or-device[,params]
Works in the same way as the -i option. If no outputs are specified, the default
output device is used (see ~/.ecasoundrc). If the object name contains any commas,
the name must be enclosed in backquotes to avoid confusing the parser. Note, 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_number,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_number,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 spefific 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 parameters given are passed unaltered to the file object. Parameters
3...N are passed as is to the child object (i.e. "-i audioloop,foo.wav,bar1,bar2"
will pass parameters "bar1,bar2" to the "foo.wav" object.

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
professional 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 "ecasound: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 connected anywhere (e.g.
to soundcard input/outputs, or to other apps). One thus has to connect the ports
with an external program (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 connected 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 difference 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’ (**deprecated 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 reading/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/writing a certain audio file. Option syntax
is -i:sndfile,foobar.ext[,.format-ext] (same for -o). The optional third parameter
"format" can be used to override the audio format (for example you can create an
AIFF file with filename "foo.wav").

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 chainsetup. For example, ecasound
-f:16,2,44100 -i resample,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 resample,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 algorithm available. To force ecasound to use
the internal resampler, ’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 frequency of the generated tone and ’duration-secs’ the
length of the generated stream. Specifying zero, or a negative value, as the
duration will produce an infinite stream. This feature was first added to Ecasound
2.4.7.

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 operations and produces raw MIDI bytes.
Valid devices are for example OSS rawmidi devices (/dev/midi00), ALSA rawmidi
devices (/dev/snd/midiC2D0), named pipes (see mkfifo man page), and normal files.

-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 realtime messages) .to
the selected MIDI-device. Notice that as Ecasound will not send MIDI-clock, but
only the start and stop messages.

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 sample values, is printed out at the end of processing.

-evp Peak amplitude watcher. Maintains peak information for each processed 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 (linear 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. individual 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 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.

-enm:threshold-level-%,pre-hold-time-msec,attack-time-msec,post-hold-time-msec,release-time-msec
Noise gate. Supports multichannel processing (each channel processed separately).
When signal amplitude falls below ’threshold_level_%’ percent (100% means maximum
amplitude), gate is activated. If the signal stays below the threshold for
’th_time’ ms, it’s faded out during the attack phase of ’attack’ ms. If the signal
raises above the ’threshold_level’ and stays there over ’hold’ ms the gate is
released during ’release’ ms.

-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
multiplier (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 amplitude. However, at
the same time it imposes a frequency-dependent 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 specified 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 example, ’-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_channel’ 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 = 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-%’ 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 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.

-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 created, 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 identified 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’ seconds. 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 volume goes over
’othreshold’ percent. After this, if volume drops below ’cthold’ percent, gate is
closed and won’t be opened again, unless the ’reopen-count’ is set to anything
other than zero. If ’value_mode’ is ’rms’, average RMS volume is used. Otherwise
peak average is used. When closed, passing audio buffers are trucated to zero
length. If the ’reopen-count’ is set to a positive number, then the gate will
restart its operation that many times. So for example, a reopen count of 1 will
cause up to 2 openings of the gate. A negative value for ’reopen-count’ will result
in the gate reopening indefinitely. The ’reopen-count’ is invaluable in recording
vinyl and tapes, where you can set things up and then recording starts whenever the
needle is on the vinyl, and stops when it’s off. As many sides as you like can be
recorded in one session. You will need to experiment with buffer lengths and
start/stop levels to get reliable settings for your equipment.

-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’ values ’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 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 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,valueN
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 recommended by the MIDI-specification, channel numbering goes
from 1 to 16. Possible controller numbers are values from 0 to 127. The MIDI-device
where bytes are read from can be specified using -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 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.

INTERACTIVE MODE

See ecasound-iam(1) man page.

ENVIRONMENT

       ECASOUND
              If  defined, some utility programs and scripts will use the ECASOUND 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  ECASOUND_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 initiated. 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 normal cleanup procedure, and terminate
       immediately. Any remaining cleanup tasks will be skipped.  Depending on the runtime  state
       and  configuration, 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 documentation.

       *.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.

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)