ecasound (1)

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 (dqstartdq, dqstopdq, dqpausedq, etc.). See ecasound-iam .

-C

Disables ecasoundcqs interactive mode (see cq-ccq and cq-Kcq).

-D

Print all debug information to stderr (unbuffered, plain output without ncurses).

-s[:]chainsetup-file

Create a new chainsetup from file cqchainsetup-filecq and add it to the current session. Chainsetup files commonly have a filename ending to the cq.ecscq 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 dqcmd1 [[args] ; cmd2 args ; ... ; cmdN]dq

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 cq-Ecq 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 Ecasoundcqs 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 ecasoundcqs 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 cq--daemoncq (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 cq--daemon-portcq (deprecated in 2.6.0).

--no-server

Disable ecasoundcqs daemon mode. This is the default. This option replaces cq--nodaemoncq (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. Ecasoundcqs OSC interface is documented at: <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 cqdebug_levelcq. 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) cqpath-to-filecq 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 cq-acq 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 cqdefaultcq is used instead when adding objects. Chain name cqallcq 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 cqnamecq. If not specified, defaults either to dqcommand-line-setupdq 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 cqfeaturecq. Most features can be disabled using notation -z:nofeature. cq-z:db,dbsizecq enables double-buffering for audio objects that support it (dbsize=0 for default, otherwise buffer size in sample frames). cq-z:nodbcq disables double-buffering. cq-z:intbufcq and cq-z:nointbufcq control whether extra internal buffering is allowed for realtime devices. Disabling this can reduce latency times in some situations. With cq-z:xrunscq, processing will be halted if an under/overrun occurs. cq-z:multitrackcq and cqz:nomultitrackcq 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 cq-z:multitrack,offset-in-samplescq. The offset is the amount of samples skipped when recording from real-time inputs. cq-z:psrcq enables the precise-sample-rates mode for OSS-devices. cq-z:mixmode,sumcq enables mixing mode where channels are mixed by summing all channels. The default is cq-z:mixmode,avgcq, 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: cqautocq (default), cqnonrtcq, cqrtcq, cqrtlowlatencycq.

-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. jackdcqs cq-pcq 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 doesncqt have root priviledges. Beware! This gives better performance, but can cause total lock-ups if something goes wrong. The cqsched_prioritycq can be omitted (0=omitted). If given, this is the static priority to the highest priority ecasound thread. Other ecasound threads run with priority cqsched_priority-1...ncq. Value cq-1cq 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 (doesncqt have to be an integer value). If processing time isncqt set, engine stops when all inputs are finished. This option is equivalent to the cqcs-set-lengthcq EIAM command. A special-case value of cq-1cq 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 cqcs-loopcq EIAM command.

INPUT/OUTPUT SETUP

See ecasound usercqs guide for more detailed documentation.

-G:mgrtype,optstring

Sets options for audio object manager type cqmgrtypecq. For available options, see dqOBJECT TYPE SPECIFIC NOTESdq 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 cq-fcq options have to be specified (note the ordering, the cq-fcq options should precede the audio objects for them to have any effect). See documentation for cq-icq and cq-ocq 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 one 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 cq-fcq option. Similarly when creating JACK inputs and outputs, the JACK server mandates the sampling rate and sample format.

If no cq-fcq option is specified, or some of the argument fields are left empty (e.g. cq-f:,2,44100cq), 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 cq-xcq (overwrite outputs) option is given, audio parameters of an existing audio file take preference over the params set with cq-fcq.

Sample format is given as a formatted string. The first letter is either dqudq, dqsdq and dqfdq (unsigned, signed, floating point). The following number specifies sample size in bits. If sample is little endian, dq_ledq is added to the end. Similarly if big endian, dq_bedq is added. If endianness is not specified, host byte-order is used. Currently supported formats are dqu8dq (same as dq8dq), dqs16_ledq (same as dq16dq), dqs16_bedq, dqs24_ledq, dqs24_bedq, dqs32_ledq, dqs32_bedq, dqf32_ledq and dqf32_bedq. An empty string dqdq picks the system default sample format.

The 4th parameter defines the channel layout. The available options are cqicq (interleavedcq and cqncq (noninterleaved). With the noninterleaved setting, ecasound will process samples one channel at a time, and the blocksize is set with cq-bcq. The default setting is cqicq.

-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 cq-a:...cq). 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 (doesncqt start with cq-cq) 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 - cqalsacq

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 - cqalsahwcq, cqalsaplugincq

Itcqs 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 - cqartscq

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 - cqaudioloopcq, cqselectcq, cqplayatcq

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. dq-i audioloop,foo.wav,bar1,bar2dq will pass parameters dqbar1,bar2dq to the dqfoo.wavdq 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 dqdurationdq of dqfile.extdq, starting at dqstart-timedq. The time values should be given as seconds (e.g. dq2.25dq, or as samples (e.g. dq25000sadq). 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 dqfile.extdq after position reaches dqplay-at-timedq. The time values should be given as seconds (e.g. dq2.25dq, or as samples (e.g. dq25000sadq). Parameters 2...N are passed as is to the child object.

Ecasound Wave Files (EWF) - cq*.ewfcq

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 usercqs guide for more detailed information.

See also audio object types cqaudioloopcq, cqselectcq and cqplayatcq.

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 - cqjackcq

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 dqecasound:in_Ndq and dqecasound:out_ndq respectively (cqNcq 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. dqQJackCtldq or dqjack_connectdq).

JACK input/outputs - cqjack,clientname,portprefixcq

dqjack,clientnamedq 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 dqjackdq 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. dqindq in client name dqecasound:in_Ndq), the prefix can be specified as the third parameter to dqjackdq object, e.g. -o jack,,fxout. Also the third parameter can be omitted, in which case the default prefixes dqindq and dqoutdq are used.

JACK input/outputs - cqjack_multicq

A variant of cqjackcq object type is cqjack_multicq. The full object syntax is jack_multi,destport1,...,destportN. When a cqjack_multicq object is connected to a JACK server, first channel of the object is connected to JACK port cqdestport1cq, second to cqdestport2cq and so forth. For instance dq-f:32,2,44100 -o jack_multi,foo:in,bar:indq 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 - cqjack_alsacq, cqjack_autocq, cqjack_genericcq (**deprecated since 2.6.0**)

Ecasound 2.5 and older supported dqjack_alsadq, dqjack_autodq and dqjack_genericdq object types, but these are now replaced by a more generic dqjackdq 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. cqclient_namecq is the name used when registering ecasound to the JACK system. If cqoperation_modecq is dqnotransportdq, ecasound will ignore any transport state changes in the JACK-system; in mode dqsenddq it will send all start, stop and position-change events to other JACK clients; in mode dqrecvdq ecasound will follow JACK start, stop and position-change events; and mode dqsendrecvdq which is a combination of the two previous modes.

If not explicitly set, in interactive mode (cq-ccq option), the default mode is dqsendrecvdq, while in batchmode default is dqnotransportdq. In both cases the mode can be changed with -G option as described above.

More details about ecasoundcqs JACK support can be found from Ecasound Usercqs Guide.

Libaudiofile - cqaudiofilecq

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 - cqsndfilecq

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 dqformatdq can be used to override the audio format (for example you can create an AIFF file with filename dqfoo.wavdq).

Loop device - cqloopcq

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 cq1cq, all data written to this output is routed to any loop input with tag cq1cq. The tag can be either numerical (e.g. cq-i:loop,1cq) or a string (e.g. dq-i:loop,vocalsdq). 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 cqloopcq device is different from cqaudioloopcq (latter added to ecasound v2.5.0).

Mikmod - cqmikmodcq

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 - cqnullcq

If you specify dqnulldq or dq/dev/nulldq 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. Therecqs also a realtime variant, dqrtnulldq, which behaves just like dqnulldq objects, except all i/o is done at realtime speed.

Resample - cqresamplecq

Object type cqresamplecq can be used to resample audio objectcqs 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 cqautocq. 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 cqautocq 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. dq-i resample,22050,foo.wav,bar1,bar2dq will pass parameters dqbar1,bar2dq to the dqfoo.wavdq object.

If ecasound was compiled with support for libsamplerate, you can use cqresample-hqcq to use the highest quality resampling algorithm available. To force ecasound to use the internal resampler, cqresampler-lqcq (low-quality) can be used.

Reverse - cqreversecq

Object type cqreversecq 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 cqfoo.wavcq 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. dq-i reverse,foo.wav,bar1,bar2dq will pass parameters dqbar1,bar2dq to the dqfoo.wavdq object.

System standard streams and named pipes - cqstdincq, cqstdoutcq

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 - cqtonecq

To generate a test tone, input -i:tone,type,freq,duration-secs can be used. Parameter cqtypecq specifies the tone type: currently only cqsinecq is supported. The cqfreqcq parameter sets the frequency of the generated tone and cqduration-secscq 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 - cqtypeselectcq

The special cqtypeselectcq 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 cqan_mp3_file.wavcq 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. dq-i typeselect,.au,foo.wav,bar1,bar2dq will pass parameters dqbar1,bar2dq to the dqfoo.wavdq 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. cqdevice_namecq 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. cqsequencer-portcq identifies a port to connect to. It can be numerical (e.g. 128:1), or a client name (e.g. dqKMidimondq).

-Mms:device_id

Sends MMC start (dqDeferred Playdq) and stop (dqStopdq) with device ID cqdevice_idcq.

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 <jackctlmmc.sourceforge.net>) to convert MMC messages into JACK transport change events.

-Mss

Sends MIDI-sync (i.e. dqMIDI Startdq and dqMIDI Stopdq 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 usercqs guide for more detailed information.

-pf:preset_file.eep

Uses the first preset found from file cqpreset_file.eepcq as a chain operator.

-pn:preset_name

Find preset cqpreset_namecq 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 cq-eacq (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 cqstamp-idcq (integer number). This data can later be used by controllers and other operators.

-ea:amplify%

Adjusts the signal amplitude to cqamplify%cq percent (linear scale, i.e. individual samples are multiplied by cqamplify%/100cq). See also cq-eadbcq.

-eac:amplify%,channel

Amplifies signal of channel cqchannelcq by amplify-% percent (linear scale, i.e. individual samples are multiplied by cqamplify%/100cq). cqchannelcq ranges from 1...n where n is the total number of channels. See also cq-eadbcq.

-eadb:gain-dB[,channel]

Adjusts signal level by cqgain-dBcq, with a gain of 0dB having no effect to the signal, negative gains attenuating the signal and positive gain values amplifying it. The cqchannelcq parameter (1...n) is optional. If cqchannelcq 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 cqamplify%/100cq). 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 cqlimit-%cq (linear scale) with values equal or greater than 100% resulting in no change to the signal.

-ec:rate,threshold-%

Compressor (a simple one). cqratecq is the compression rate in decibels (cqratecq dB change in input signal causes 1dB change in output). cqthresholdcq 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. cqpeak-level-%cq essentially specifies how hard the peak limiter is pushed. The default of 69% is good. cqrelease_timecq 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. cqfastratecq 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. cqratecq 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 cqthreshold_level_%cq percent (100% means maximum amplitude), gate is activated. If the signal stays below the threshold for cqth_timecq ms, itcqs faded out during the attack phase of cqattackcq ms. If the signal raises above the cqthreshold_levelcq and stays there over cqholdcq ms the gate is released during cqreleasecq 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 cqright-%cq is 0, only signal on the left (1st) channel is passed through. Similarly if it is cq100cq, only right (2nd) channel is let through.

-ezx:channel-count,delta-ch1,...,delta-chN

Adjusts the signal DC by cqdelta-chXcq, 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. cqcenter_freqcq is the center frequency. Width is specified in Hz.

-ef3:cutoff_freq, reso, gain

Resonant lowpass filter. cqcutoffr_freqcq is the filter cutoff frequency. cqresocq means resonance. Usually the best values for resonance are between 1.0 and 2.0, but you can use even bigger values. cqgaincq is the overall gain-factor. Itcqs 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 cqradiuscq should be between [0, 1.0).

-efb:center-freq,width

Bandpass filter. cqcenter_freqcq is the center frequency. Width is specified in Hz.

-efh:cutoff-freq

Highpass filter. Only frequencies above cqcutoff_freqcq are passed through.

-efi:delay-samples,radius

Inverse comb filter. Filters out the spikes of the comb. There are cqdelay_in_samples-2cq spikes. Value of cqradiuscq 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 cqcutoff_freqcq are passed through.

-efr:center-freq,width

Bandreject filter. cqcenter_freqcq is the center frequency. Width is specified in Hz.

-efs:center-freq,width

Resonator. cqcenter_freqcq is the center frequency. Width is specified in Hz. Basically just another resonating bandpass filter.

CHANNEL MIXING / ROUTING

-chcopy:from-channel, to-channel

Copy channel cqfrom_channelcq to cqto_channelcq. If cqto_channelcq doesncqt exist, it is created. Channel indexing starts from 1. Option added to ecasound 2.4.5.

-chmove:from-channel, to-channel

Copy channel cqfrom_channelcq to cqto_channelcq, and mutes the source channel cqfrom_channelcq. 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 cqNcq channels. Each parameter specifies the source channel to use for given output channel. As an example, cq-chorder:2,1cq would reverse the channels of a stereo stream (cqout1,out2cq = cqin2,in1cq). Specifying the same source channel multiple times is allowed. For example, cq-chorder:2,2cq would route the second channel to both two output channels (cqout1,out2cq = cqin2,in2cq). If cqchXcq is zero, the given channel cqXcq will be muted in the output stream. Option added to ecasound 2.7.0.

-chmix:to-channel

Mix all source channels to channel cqto_channelcq. If cqto_channelcq doesncqt exist, it is created. Channel indexing starts from 1. Option added to ecasound 2.4.5.

-chmute:channel

Mutes the channel cqchannelcq. 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. cqdelay timecq is the delay time in milliseconds. cqsurround-modecq is a integer with following meanings: 0 = normal, 1 = surround, 2 = stereo-spread. cqnumber_of_delayscq should be obvious. Beware that large number of delays and huge delay times need a lot of CPU power. cqmix-%cq 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. cqfeedback-%cq 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 cqnumber_of_delayscq, especially if you have set a low value for cqmix-%cq. 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). cqroom_sizecq is given in meters, cqfeedback-%cq is the feedback level given in percents and cqwet-%cq 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 cqdelay timecq 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. cqdelay timecq is the delay time in milliseconds. cqnumber_of_delayscq should be obvious. cqmix-%cq 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. cqdelay timecq is the delay time in milliseconds. If cqsurround-modecq is cqsurroundcq, reverbed signal moves around the stereo image. cqfeedback-%cq 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 Developercqs Simple Plugin API). Parameters 1..N are set as values of the plugincqs 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. dq/usr/local/lib/ladspadq), 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 plugincqs 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 cqstart-timecq seconds has elapsed, gate opens and remains open for cqlencq 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 cqothresholdcq percent. After this, if volume drops below cqctholdcq percent, gate is closed and woncqt be opened again, unless the cqreopen-countcq is set to anything other than zero. If cqvalue_modecq is cqrmscq, average RMS volume is used. Otherwise peak average is used. When closed, passing audio buffers are trucated to zero length. If the cqreopen-countcq 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 cqreopen-countcq will result in the gate reopening indefinitely. The cqreopen-countcq 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 itcqs 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 cqstatecq is 1, gate is open and all samples are passed through. If cqstatecq 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. cqfx_paramcq specifies the parameter to be controlled. Value cq1cq means the first parameter, cq2cq the second and so on. cqstart_valuecq and cqend_valuecq 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 cqfreqcq Hz and initial phase of cqi_phasecq times pi.

-kog:fx-param,start-value,end-value,freq,mode,point-pairs,first-value,last-value,pos1,value1,...

Generic oscillator. Frequency cqfreqcq Hz, mode either cq0cq for static values or cq1cq for linear interpolation. cqpoint-pairscq specifies the number of cqposNcq - cqvalueNcq pairs to include. cqfirst-valuecq and cqlast-valuecq are used as border values (values for position 0.0/first and position 1.0/last). All cqposNcq and cqvalueNcq must be between 0.0 and 1.0. Also, for all cqposNcq values cqpos1 < pos2 < ... < posNcq must be true.

-kf:fx-param,start-value,end-value,freq,mode,genosc-number

Generic oscillator. cqgenosc_numbercq is the number of the oscillator preset to be loaded. Mode is either cq0cq for static values or cq1cq 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 cqstart_valuecq and linearly changes to cqend_valuecq during cqtime_in_secondscq. 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 cqstart_valuecq for cq1st_stage_lengthcq seconds and then linearly changes towards cqend_valuecq during cq2nd_stage_lengthcq 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 cqpoint_countcq. Each envelope point consists of a position and a matching value. Number of pairs must match cqpoint_countcq (i.e. cqN==point_countcq). The cqposXcq parameters are given as seconds (from start of the stream). The envelope points are specified as float values in range cq[0,1]cq. Before envelope values are mapped to operator parameters, they are mapped to the target range of cq[low-value,high-value]cq. E.g. a value of cq0cq will set operator parameter to cqlow-valuecq and a value of cq1cq will set it to cqhigh-valuecq. For the initial segment cq[0,pos1]cq, the envelope will output value of cqvalue1cq (e.g. cqlow-valuecq).

-km:fx-param,start-value,end-value,controller,channel

MIDI continuous controller (control change messages). Messages on the MIDI-channel cqchannelcq that are coming from controller number cqcontrollercq 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 cqstamp-idcq (see cq-eS:idcq docs), and creates control data based on the results. If cqrms-togglecq 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 cqfunctions (64)cq and cqcontinuous (128)cq 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. dqcs-editdq interactive command) require creation of temporary files. By default, these files are created under dq/tmpdq, 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 cqSIGNALScq 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 cq4cq 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 cqstderrcq 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 usercqs 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 nosignal.fi/ecasound/Documentation/examples.html

SEE ALSO

ecatools (1) man page, ecasound-iam (1) man page ecasoundrc (5) man page, dqHTML docs in the Documentation subdirectorydq

BUGS

See file BUGS. If ecasound behaves weirdly, try to increase the debug level to see whatcqs going on.

AUTHOR

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