ecasound(1)

📦
version 2.9.3 · 2 versions
, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

🌸 ecasound(1) — NAME 🌸

hey bestie, welcome to the ecasound(1) manual page, part one of six 💖 grab a snack, we're doing this.

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.

like. the range?? iconic. 👑

💅 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).

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 — the relevant features are -z:db,xxx (or -z:nodb) and -z:intbuf (or -z:nointbuf). Peep the section General chainsetup options for the deets. ✨

🔥 PROCESSING CONTROL 🔥

  • -t:seconds — sets the processing time in seconds (and bestie, it doesn't have to be an integer value, like 2.5 is totally fine). If you don't set the processing time, the engine stops when all inputs are finished. This option is equivalent to the cs-set-length EIAM command. And a special-case value of -1 will set the chainsetup length according to the longest input object. 💅
  • -tl — enables looping. When processing is finished, the engine will start again from the beginning. This option is equivalent to the cs-loop EIAM command. 🔁

🎧 INPUT/OUTPUT SETUP 🎧

See the ecasound user's guide for more detailed documentation. 📚

  • -G:mgrtype,optstring — sets options for the 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 you 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 the -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 the ecasoundrc configuration file. See ecasoundrc(5) manual page.

Note that ecasound opens out files by default in update mode. Unless the option -x (overwrite outputs) 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" or "f" (unsigned, signed, floating point). The following number specifies sample size in bits. If the 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 the starting position for the 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 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 specific time, and other such operations. 🕰️

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 applications 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 scenarios, ecasound provides a way to autoconnect the ecasound ports. This can be done 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 the "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</p> 🦋

okay so you know the jack object type? there's a lil glow-up variant called jack_multi and it's lowkey iconic. full object syntax is:

jack_multi,destport1,...,destportN

the way it works: when a jack_multi object gets connected to a JACK server, its first channel goes to JACK port destport1, its second channel goes to destport2, and so on down the line, periodt. for example:

-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 different JACK clients. split slay 💅

heads up bestie: the destination ports must be active when the ecasound engine is launched, or the connections literally cannot be established. no cap.

and if destination ports aren't specified for all channels, or you pass zero length strings in there, those ports just don't get connected at launch by ecasound. simple as.

JACK input/outputs — jack_alsa</p>, jack_auto</p>, jack_generic</p> (deprecated since 2.6.0) 💀

so Ecasound 2.5 and older used to support jack_alsa, jack_auto and jack_generic object types, but they've been replaced by the more generic jack interface. so yeah, they're deprecated now — they still work, but they're no longer documented. it's giving legacy. 🙈

JACK input/outputs — client options 🌈

plus you can set global JACK options with the -G:jack,client_name,operation_mode option. let's break it down:

  • client_name — the name used when registering ecasound to the JACK system.
  • operation_mode — pick your vibe:
    • "notransport" — ecasound ignores any transport state changes in the JACK-system.
    • "send" — ecasound sends all start, stop and position-change events to other JACK clients.
    • "recv" — ecasound follows JACK start, stop and position-change events.
    • "sendrecv" — a combination of the two previous modes. both worlds, main character energy 👑

if not explicitly set, in interactive mode (the -c option) the default mode is "sendrecv", while in batchmode the default is "notransport". either way, you can change the mode with -G like described above. ✨

more details about ecasound's JACK support can be found from the Ecasound User's Guide.

Libaudiofile — audiofile</p> 🎀

if libaudiofile support was enabled at compile-time, this option lets you force Ecasound to use libaudiofile for reading/writing a certain audio file. option syntax is:

-i:audiofile,foobar.ext

(same for -o.) 🫶

Libsndfile — sndfile</p> 🌸

if libsndfile support was enabled at compile-time, this option lets you 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 the filename "foo.wav". sneaky but valid 😌

Loop device — loop</p> 🦋

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). and 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). don't mix them up bestie.

Mikmod — mikmod</p> 🍓

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</p> 💀

if you specify "null" or "/dev/null" as the input or output, a null audio device is created. super useful when you just wanna 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</p> 🌈

object type resample can be used to resample an 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 a file from 22.05kHz to 44.1kHz and write the result to the soundcard device. 💅

the child sampling rate can be replaced with the keyword auto. in this case ecasound will try to query the child object for its sampling rate — this works with file 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. 👑 and to force ecasound to use the internal resampler, resampler-lq (low-quality) can be used.

Reverse — reverse</p> 🙈

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. iconic. but heads up: 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 the reversation. fr fr.

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</p>, stdout</p> 🎀

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</p> 🔥

to generate a test tone, use the input -i:tone,type,freq,duration-secs. the type parameter 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</p> 🦋

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. mind = blown 🤯

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</p> 🌸

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</p> 🌈

adds an 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</p> 🎀

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</p> 👑

sends MIDI-sync (i.e. "MIDI Start" and "MIDI Stop" system realtime messages) to the selected MIDI-device. notice that Ecasound will not send MIDI-clock, but only the start and stop messages. that's it, that's the whole thing 💅

✨ EFFECT SETUP ✨

PRESETS 🍓

Ecasound has a powerful effect preset system that allows you create new effects by combining basic effects and controllers. see the ecasound user's guide for more detailed information. ✨

-pf:preset_file.eep</p> 🎀

uses the first preset found from file preset_file.eep as a chain operator.

-pn:preset_name</p> 🦋

find preset preset_name from global preset database and use it as a chain operator. see the ecasoundrc man page for info about the preset database.

✨ SIGNAL ANALYSIS ✨

-ev</p> 🔥

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</p> 👑

peak amplitude watcher. maintains peak information for each processed channels. peak information is reset on every read. 🔄

-ezf</p> 🌈

finds the optimal value for DC-adjusting. you can use the result as a parameter to the -ezx effect.

✨ GENERAL SIGNAL PROCESSING ALGORITHMS ✨

-eS:stamp-id</p> 🎀

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%</p> 💅

adjusts the signal amplitude to amplify% percent (linear scale, i.e. individual samples are multiplied by amplify%/100). see also -eadb. 🔊

-eac:amplify%,channel</p> 🌸

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] — turns the volume up or down by gain-dB. A gain of 0dB is literally doing nothing to your signal, negatives attenuate it, positives amplify it. The channel param (1...n) is optional — if you pass it and it's nonzero, the gain only hits that one channel (1...n). selective slay 💜
  • -eaw:amplify%,max-clipped-samples — amplifies by amplify-% percent on a linear scale, i.e. every single sample gets multiplied by amplify%/100. If you rack up a run of consecutive clipped samples (meaning the resulting sample value lands outside the nominal [-1,1] range), it'll throw a warning at you. watch out bestie ⚠️
  • -eal:limit-% — the limiter effect. Caps the audio level at limit-% (linear scale). Values equal to or greater than 100% = no change to the signal at all. nothing happens, and that's valid ✨
  • -ec:rate,threshold-% — a compressor, and yeah, a pretty simple one. rate is the compression rate in decibels (rate dB of change on the input side → 1dB of change on the output side). threshold ranges from 0.0 (silence) to 1.0 (max amplitude). 🎚️
  • -eca:peak-level-%, release-time-sec, fast-crate, crate — the fancier compressor, original algorithm by John S. Dyson. Drop a value of 0 on any parameter and the default kicks in instead, no stress. peak-level-% is basically how hard you're shoving the peak limiter — the default 69% is a good spot. release_time is in seconds, and heads up: this compressor is very sophisticated, so the release time is genuinely complex. It's one of the dominant release-time controls, but the actual release time depends on a whole bunch of factors around the dynamics of the audio coming in. fastrate is the compression ratio for the fast compressor — and okay it's not really the compression ratio. A value of 1.0 is infinity to one, while the default 0.50 is 2:1. Another genuinely great value is special-cased right 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, default 1.0, which holds the volume very constant without many nasty side effects — but the dynamics in music get severely restricted, so 0.5 might keep your music more intact. the tradeoffs are real 💅
  • -enm:threshold-level-%,pre-hold-time-msec,attack-time-msec,post-hold-time-msec,release-time-msec — the noise gate. It supports multichannel processing, and each channel gets processed separately. When the signal amplitude drops below threshold_level_% percent (100% = maximum amplitude), the gate activates. If the signal keeps sitting below the threshold for th_time ms, it fades out during the attack phase of attack ms. And if the signal climbs back above threshold_level and stays there over hold ms, the gate releases over release ms. 🚪✨
  • -ei:pitch-shift-% — pitch shifter. Modifies the audio pitch by altering its length. 🦋
  • -epp:right-% — the stereo panner. Changes the relative balance between the first two channels. When right-% is 0, only the signal on the left (1st) channel passes through. Same energy if it's 100 — then only the right (2nd) channel gets 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, with the pulse frequency given as beats-per-minute. 🥁
  • -eemp:freq-Hz,on-time-% — pulse gate. (yes, again, but the frequency is in Hz this time bestie) 🥁
  • -eemt:bpm,depth-% — tremolo effect, with the 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 sit between 1.0 and 2.0, but you can absolutely go bigger. gain is the overall gain-factor, just a simple multiplier (1.0 is the normal level). With high resonance values it often helps to pull the gain down. balance is everything ⭐
  • -ef4:cutoff, resonance — resonant lowpass filter, 3rd-order, 36dB, original algorithm by Stefan M. Fendt. It simulates an analog active RC-lowpass design. Cutoff is a value between [0,1], while resonance is between [0,infinity). math girlies rise 💜
  • -efa:delay-samples,feedback-% — allpass filter. Passes all frequencies with no change in amplitude, but at the same time it imposes a frequency-dependent phase-shift. sneaky like that 🦋
  • -efc:delay-samples,radius — comb filter. Lets the spikes of the comb pass through. 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. radius should be between [0, 1.0). The closer it gets to the max 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. Basically just another resonating bandpass filter, ngl. 🎐

💅 CHANNEL MIXING / ROUTING 💅

  • -chcopy:from-channel, to-channel — copies channel from_channel to to_channel. If to_channel doesn't exist, it gets created. Channel indexing starts from 1. Option added to ecasound 2.4.5. 📋
  • -chmove:from-channel, to-channel — copies 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 a total of N channels, and each parameter specifies the source channel to use for that given output channel. For 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 output channels (out1,out2 = in2,in2). And if chX is zero, that given channel X gets muted in the output stream. Option added to ecasound 2.7.0. 🔀
  • -chmix:to-channel — mixes all source channels into channel to_channel. If to_channel doesn't exist, it gets 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. old news, use the new one 💀
  • -erm:to-channel — deprecated, see -chmix. same energy 💀

🎀 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 an integer with the following meanings: 0 = normal, 1 = surround, 2 = stereo-spread. number_of_delays should be obvious. Beware that a large number of delays plus huge delay times will eat a lot of CPU power. mix-% is 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-% is how much of the signal gets recycled in each delay, or if you prefer, the rate at which 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 specified for number_of_delays — especially if you set a low value for mix-%. By default this parameter is 100%, i.e. 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 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 gets summed to mono, then the original signal goes to the left channels while a delayed version (delayed by delay time milliseconds) goes to the right. With a delay time of 1-40 milliseconds this adds a stereo-feel to mono-signals. mono glow-up 🌈
  • -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 into 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, the reverbed signal moves around the stereo image. feedback-% determines how much effected (wet) signal is fed back into 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. plug-in era, we love to see it 🧚

okay so when a plugin has more than one audio input and/or output port, ecasound only spins up one single instance of that plugin, and all the channels in the chain get fed into that same instance. But if the plugin has at most one input and at most one output audio port, then a separate plugin instance gets created for <em>each</em> channel of the ecasound chain — like, for a stereo audio channel you get two LADSPA plugins of the same type, one per channel. 💅

Plugins live inside shared library (.so) files. Ecasound goes looking for them in @prefix@/lib/ladspa (so like "/usr/local/lib/ladspa"), plus whatever directories are listed in the environment variable LADSPA_PATH. You can also configure the plugin search path via ecasoundrc — go peek at ecasoundrc(5) man page bestie. 🫶 One shared library file can hold multiple plugin objects, but every plugin has a unique plugin name, and that name is what you use to select it.

Wanna know more about LADSPA? Check the LAD mailing list web site. Other useful spots are the LADSPA home page and the LADSPA documentation. 🔥

  • -eli:plugin_unique_number,param-1,...,param-N — Same energy as -el above, except you reference the plugin by its unique id-number instead. And fr fr, these id-numbers are guaranteed to be unique across <em>all</em> LADSPA plugins. ✨

🦋 LV2 PLUGINS 🦋

  • -elv2:plugin-id-uri,param-1,...,param-N — Ecasound also rocks with LV2 audio plugins! LV2 plugins are identified by a globally unique, case-sensitive identifier. Periodt. 👑

If a plugin has more than one audio input and/or output port, only one instance gets created and the chain channels all feed into that same instance. If it has at most one input and at most one output audio port, then a separate instance is made for each channel of the ecasound chain (so for a stereo channel, two LV2 plugins of the same type, one per channel). 💖

LV2 is a plugin standard for audio systems. The more you know ✨

🎀 GATE SETUP 🎀

  • -gc:start-time,len — The time crop gate. The gate starts out closed, okay? Once start-time seconds have gone by, the gate opens and stays open for len seconds. While it's closed, any audio buffers passing through get truncated to zero length. 🚪
  • -ge:open-threshold-%,close-thold-%,volume-mode,reopen-count — The threshold gate. Starts closed. It opens up when the volume goes over othreshold percent. After that, if volume drops below cthold percent, the gate closes and won't open again — unless reopen-count is set to anything other than zero, bestie. If value_mode is rms, then average RMS volume is what's used; otherwise it's peak average. When closed, passing audio buffers get truncated to zero length. 🫥

If reopen-count is a positive number, the gate restarts its whole operation that many times — so like, a reopen count of 1 gives you up to 2 openings of the gate. A negative value for reopen-count means the gate reopens indefinitely. 🌈 This is lowkey invaluable for recording vinyl and tapes: you set things up, recording starts whenever the needle hits the vinyl, and stops when it's off. As many sides as you like, all in one session. You will need to experiment with buffer lengths and start/stop levels to get settings that are actually reliable for your equipment. ngl, patience is the vibe here.

  • -gm:state — The manual gate. If state is 1, the gate is open and all samples pass through. If state is zero, the gate is closed and no samples get let through. This chain operator is iconic when writing to an output needs to be stopped dynamically — without stopping the whole engine. 💅

💜 CONTROL ENVELOPE SETUP 💜

Controllers let you dynamically change effect parameters while processing is happening. Every controller gets attached to the selected effect (which is <em>usually the last specified effect/controller</em>). The first three parameters are common across all controllers: fx_param picks which parameter gets controlled — value 1 means the first parameter, 2 means the second, and so on. start_value and end_value set the value range. For examples, go look at the the EXAMPLES section. 🧚

  • -kos:fx-param,start-value,end-value,freq,i-phase — Sine oscillator, with a frequency of freq Hz and an 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 is freq Hz, and mode is either 0 for static values or 1 for linear interpolation. point-pairs says how many posN – valueN pairs you're including. first-value and last-value act as border values (the 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 has to be true. 📈
  • -kf:fx-param,start-value,end-value,freq,mode,genosc-number — Generic oscillator again, but this time genosc_number is the number of the oscillator preset to load. Mode is either 0 for static values or 1 for linear interpolation. The location for the preset file comes from ./ecasoundrc (see the ecasoundrc man page). 📂
  • -kl:fx-param,start-value,end-value,time-seconds — Linear envelope that starts at start_value and linearly shifts to end_value over time_in_seconds. Perfect for fadeins and fadeouts. ✨
  • -kl2:fx-param,start-value,end-value,1st-stage-length-sec,2nd-stage-length-sec — Two-stage linear envelope — a way more versatile tool for doing fade-ins and fade-outs. It stays at start_value for 1st_stage_length seconds, then linearly moves toward end_value over 2nd_stage_length seconds. 🎚️
  • -klg:fx-param,low-value,high-value,point_count,pos1,value1,...,posN,valueN — Generic linear envelope. You can use this controller source to map custom envelopes onto chain operator parameters. The number of envelope points goes in point_count. Each envelope point is a position plus a matching value, and the number of pairs must match point_count (i.e. N==point_count). The posX parameters are given as seconds (from the start of the stream). Envelope points are specified as float values in the range [0,1]. Before envelope values get mapped to operator parameters, they're mapped to the target range of [low-value,high-value] — so like, a value of 0 sets the operator parameter to low-value, and a value of 1 sets it to high-value. For that initial segment [0,pos1], the envelope outputs the value of value1 (e.g. low-value). 💫
  • -km:fx-param,start-value,end-value,controller,channel — MIDI continuous controller (control change messages). Messages on MIDI-channel channel coming from controller number controller are used as the controller source. As recommended by the MIDI-specification, channel numbering runs from 1 to 16. Possible controller numbers are values from 0 to 127. The MIDI-device that bytes get read from can be set with the -Md option — otherwise the default MIDI-device is used, as specified in ~ecasound/ecasoundrc (see the ecasoundrc man page). Defaults to /dev/midi. 🎹
  • -ksv:fx-param,start-value,end-value,stamp-id,rms-toggle — Volume analyze controller. It analyzes the audio stored in stamp stamp-id (check the -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 — Ooh, this is a special switch for when you need to control controller parameters with another controller. When you specify -kx, the last specified controller becomes the control target. Then you just add another controller like normal. 🪄

🌸 INTERACTIVE MODE 🌸

Go read the ecasound-iam(1) man page. 📖

🌈 ENVIRONMENT 🌈

💖 ECASOUND

If it's defined, some utility programs and scripts will use the ECASOUND environment as the default path to the ecasound executable.

🫶 ECASOUND_LOGFILE

Outputs all debugging messages to a separate log file. If defined, ECASOUND_LOGFILE sets that logfile path. This is a great tool for debugging ECI/EIAM scripts and applications. 🐛

✨ ECASOUND_LOGLEVEL

Selects which messages get written to the logfile defined by ECASOUND_LOGFILE. The syntax for -d:level is what's used. If it's not defined, all messages get 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 isn't set, a default of 74 is used.

🦋 TMPDIR

Some functions of Ecasound (e.g. the "cs-edit" interactive command) require creating temporary files. By default these files get created under "/tmp", but you can override that by setting the TMPDIR environment variable.

👑 RETURN VALUES 👑

In interactive mode, ecasound always returns zero. No drama.

In non-interactive (batch) mode, a non-zero value gets returned for these errors:

  1. 1 — Unable to create a valid chainsetup with the given parameters. Can be caused by invalid option syntax, etc.
  2. 2 — Unable to start processing. This can be caused by insufficient file permissions, inability to access some system resources, etc.
  3. 3 — Error during processing. Possible causes: output object has run out of free disk space, etc. 💀
  4. 4 — Error during process termination and/or cleanup. See section on 'SIGNALS' for further details.

🚨 SIGNALS 🚨

Okay bestie, this is the part where you learn how to politely (or *un*politely) tell ecasound to wrap it up. 💅

When ecasound catches any of these POSIX signals — SIGINT (that's your ctrl-c, queen), SIGHUP, SIGTERM or SIGQUIT — it starts its normal cleanup-and-exit procedure. And "normal exit" here means the good stuff: file headers get updated before closing, helper processes get terminated the normal way, all of that. It's giving responsible adult energy. ✨

But listen. If, while it's doing all that cleanup, ecasound gets another signal (from that same set of POSIX signals), it will skip the normal cleanup procedure entirely and just terminate immediately. Any remaining cleanup tasks? Skipped. Gone. Not doing them. 😭 Depending on the runtime state and configuration, this brute-force exit may have some side-effects, so like... be aware.

Ecasound will return exit code of '4' if normal cleanup was skipped. Noted. Remember it. 🫶

Now for the special case handling, and it's applied to SIGINT (ctrl-c) specifically. If a SIGINT signal arrives during the cleanup procedure, ecasound will ignore the signal once, and emit a notice to 'stderr' that cleanup is already in progress. Basically it's like "girl I heard you the first time, I'm ON it." 🙈 But any subsequent SIGINT signals will no longer get special handling — instead the process terminates immediately, and possibly without proper cleanup. So mash that ctrl-c at your own risk. 💀

📁 FILES 📁

The lore. The receipts. Here's where ecasound keeps its stuff:

  • ~/.ecasound — the default directory for ecasound user resource files. See the ecasoundrc (5) man page man page for the deets. 🎀
  • *.ecs — Ecasound Chainsetup files. The syntax is more or less the same as with command-line arguments, so if you already speak command-line, you already speak this. Slay. 🌸
  • *.ecp — Ecasound Chain Preset files. These are used for storing effect and chain operator presets. See the ecasound user's guide for more better documentation. 👑
  • *.ews — Ecasound Wave Stats. These files are used to cache waveform data. Speedy vibes. ⚡

🧪 EXAMPLES 🧪

Wanna see how to actually do the common tasks with ecasound? Bestie, there's a whole page for that:

http://nosignal.fi/ecasound/Documentation/examples.html

Go. Click. Learn. Ate. 🔥

👀 SEE ALSO 👀

Your reading list, in no particular order of slay:

  • ecatools (1) man page
  • ecasound-iam (1) man page
  • ecasoundrc (5) man page
  • "HTML docs in the Documentation subdirectory"

iykyk. 🌈

🐛 BUGS 🐛

See file BUGS.

And if ecasound behaves weirdly, try to increase the debug level to see what's going on. That's it. That's the tip. Turn up the debug and watch the chaos in high definition. 💜

💖 AUTHOR 💖

Kai Vehmanen, <kvehmanen -at- eca -dot- cx <kvehmanen -at- eca -dot- cx>>

Give it up for the legend who built all this. 👑✨

and that's a wrap on the whole ecasound(1) page, bestie 🫶 This absolute icon of a manpage comes from source/version ecasound(1), dated 05.05.2011. Go make some beautiful noise, you main character. 💅🎀🦋

📦 where this page comes from