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.
Note! All options except those mentioned in ecasound options and Global options, can be used in ecasound chainsetup files (.ecs).
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.
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).
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.
GENERAL CHAINSETUP OPTIONS
CHAINSETUP BUFFERING AND PERFORMANCE OPTIONS
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).
See ecasound user's guide for more detailed documentation.
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'.
OBJECT TYPE SPECIFIC NOTES
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.
See also audio object types 'audioloop', 'select' and 'playat'.
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").
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.
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.
Note: this 'loop' device is different from 'audioloop' (latter added to ecasound v2.5.0).
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.
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.
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.
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.
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.
GENERAL SIGNAL PROCESSING ALGORITHMS
CHANNEL MIXING / ROUTING
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.
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.
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.
See ecasound-iam(1) man page.
In interactive mode, ecasound always returns zero.
In non-interactive (batch) mode, a non-zero value is returned for the following errors:
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).
~/.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 of how to perform common tasks with ecasound can be found at http://nosignal.fi/ecasound/Documentation/examples.html.
ecatools (1) man page, ecasound-iam (1) man page ecasoundrc (5) man page, "HTML docs in the Documentation subdirectory"
See file BUGS. If ecasound behaves weirdly, try to increase the debug level to see what's going on.
Kai Vehmanen, <kvehmanen -at- eca -dot- cx>