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 size of buffer in samples (must be an exponent of
2). This is quite an important option. For real-time processing, you
should set this as low as possible to reduce the processing delay. Some
machines can handle buffer values as low as 64 and 128. In some
circumstances (for instance when using oscillator envelopes) small buffer
sizes will make envelopes act more smoothly. When not processing in
real-time (all inputs and outputs are normal files), values between 512 -
4096 often give better results. Default is 1024.
- -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://eca.cx/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>>