ecasound

20.07.1999

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 text-mode sound processing program that can do various tasks from basic editing and effect processing to multitrack recording. Although the user interface may seem a bit cryptic, one of the main design goals of this project has been to create an easy-to-use, creative utility for recording and mixing purposes. Because of the simple interface, batch files can be used to automate complex editing tasks.

OPTIONS

Notice that the order of parameters given on the command line is important!

GLOBAL OPTIONS

-c

Starts ecasound in interactive mode. In interactive mode you can control ecasound with simple commands ("start", "stop", "pause", etc.).

-d:debug level

Set the debug level. Default is 0.

-q

Quiet mode, no output.

CHAINSETUP OPTIONS

-s chainsetup-file: Create a new chainsetup from the file 'chainsetup-file' and add it to the current session. Chainsetup can contain inputs, outputs, chains, effects, controllers, etc. A session, on the other hand, contains all the chainsetups. Although only one chainsetup can be active at a time, you can switch between them on-the-fly.

GENERAL

-a:chainname1, chainname2, ...

Sets active signal chains. All effects, inputs and outputs are assigned to these chains. If there are no -a options given, default chain is used. Chain name 'all' is reserved and means that all chains are active. 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.

-b:buffer size

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

-m:mix-mode

Force ecasound to use mix mode 'mix_mode'. 'auto' = automatic (default), 'simple' = only one input/chain/output, 'normal' = normal single-threaded mode and 'mthreaded' = multithreaded mixing. In most cases, ecasound is able to find out the correct mode automatically.

-r

Raise process priority. Improves realtime performance.

INPUT/OUTPUT SETUP

-i input-file-or-device

Specifies a new input source. It is assigned to the active chains. Assigned multiple inputs to the same chain is currently not possible. The given input can be a normal file or an audio device. File format is determined using the file name extension. Currently supported formats are RIFF WAVE files (.wav), audio-cd tracks (.cdr), ecasound ewf-files (.ewf), MPEG files (.mp2,.mp3), ecasynth configuration files (.ess), OSS audio devices (/dev/dsp*) and ALSA audio devices (/dev/snd/pcm*). If no inputs are specified, the first non-option on the command line (if any) is considered to be a input. Notice! When using ALSA drivers, you can also you the following option syntax -i[:]alsa,card_number,device_number.

-o output-file-or-device

Acts in the same way as the -i option. If no no outputs are specified, the default output device is used (see &tilde;/.ecasoundrc).

System standars streams You can use standard stream (stdin and stdout) by giving "stdin" or "stdout" as the file name. The format is the same as with raw/headerless (.raw) audio files.

-f:bits,channel,sample-rate

Sets active sampling parameters. These are used for all following input and output files or until another -f is spesified. If no -f option is present, ecasound tries to get the parameters from the audio object (for instance RIFF WAVE header). If no valid sample parameters are found, defaults are used (16 bits, 2 channels, 44100 samples per second).

EFFECT SETUP

-ps:preset_name

Insert single-chain preset 'preset_name' to active chains. See ecasoundrc(5) for info about the preset file.

SIGNAL ANALYSIS

-ev

Normalize sample data by finding out how much the signal can be amplified without clipping. The resulting percent value can be used as a parameter to -ea and -eas effects.

-ezf

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

GENERAL SIGNAL PROCESSING ALGORITHMS

-ea:amplify-%,max-clipped-samples

Amplifies signal by amplify-% percent. If number of consecutive clipped samples (resulting sample has the largest amplitude possible) reaches 'max-clipped-samples', a warning will be issued.

-eas:amplify-%

Otherwise like -ea, but doesn't warn about clipped samples.

-ec:rate,threshold

Compressor (a simple one). 'rate' is the compression rate in decibels ('rate'dB change in input signal causes 1dB change in output). 'threshold' varies between 0.0 (silence) and 1.0 (max amplitude).

-enm:threshold_level_%,th_time,attack,hold,release

Noise gate (mono-summed signal used to control the gate). When signal amplitude falls below 'threshold_level_%' percent (100% means maximum amplitude) the gate is activated. If the signal stays below the threshold for 'th_time' ms, it's faded out during the attack phase of 'attack' ms. If the signal raises above the 'threshold_level' and stays there over 'hold' ms the gate is released during 'release' ms.

-epp:right-%

Normal pan effect. Balance value of 0 means to pan signal fully left and 100 fully right. If the panned signal is a stereo signal, left and right channels aren't mixed together. Use the -f option to force conversion to mono before panning.

-ezx:left-dc-fix-value,right-dc-fix-value

Adjusts the signal DC by 'dc-fix-value'. Use -ezf to find the optimal value.

TIME-BASED EFFECTS

-etd:delay_time,surround-mode,number_of_delays,mix-%

Delay effect. 'delay time' is the delay time in milliseconds. 'surround-mode' is a integer with following meanings: 0 = normal, 1 = surround, 2 = stereo-spread. 'number_of_delays' should be obvious. Beware that large number of delays and huge delay times need a lot of CPU power. 'mix-%' determines how much effected (wet) signal is mixed to the original.

-etr:delay-time,surround-mode,feedback-%

Reverb effect. 'delay time' is the delay time in milliseconds. If 'surround-mode' is 'surround', reverbed signal moves around the stereo image. 'feedback-%' determines how much effected (wet) signal is fed back to the reverb.

-etf:delay_time

Fake-stereo effect. The input signal is summed to mono. The original signal goes to the left channels while a delayd version (with delay of 'delay time' milliseconds) is goes to the right. With a delay time of 1-40 milliseconds this adds a stereo-feel to mono-signals.

FILTER EFFECTS

-ef1:center_freq, width

Resonant bandpass filter. 'center_freq' is the center frequency. Width is specified in Hz.

-ef3:cutoff_freq, reso, gain

Resonant lowpass filter. 'cutoffr_freq' is the filter cutoff frequency. 'reso' means resonance. Usually the best values for resonance are between 1.0 and 2.0, but you can use even bigger values. 'gain' is the overall gain-factor. It's a simple multiplier (1.0 is the normal level). With high resonance values it often is useful to reduce the gain value.

-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_in_samples,radius

Inverse comb filter. Allows the spikes of the comb to pass through. The comb consists of 'delay_in_samples/2' spikes. The maximum value for 'radius' is 1.0. The closer it is to the maximum value, the deeper the dips of the comb.

-efl:cutoff_freq

Lowpass filter. Only frequencies below 'cutoff_freq' are passed through.

-efr:center_freq,width

Bandreject filter. 'center_freq' is the center frequency. Width is specified in Hz.

-efs:center_freq,width

Resonator. 'center_freq' is the center frequency. Width is specified in Hz. Basicly just another resonating bandpass filter.

GATE SETUP

-gc:start-time,len

Time crop gate. Initially gate is closed. After 'start-time' seconds has elapse, gate opens and remains open for 'len' seconds.

-ge:othreshold%, cthold%,volume_mode

Threshold gate. Initially gate is closed. It is opened when volume goes over 'othreshold' percent. After this, if volume drops below 'cthold' percent, gate is closed and won't be opened again. If 'value_mode' is 'rms', average RMS volume is used. Otherwise peak average is used.

CONTROL ENVELOPE SETUP

Controllers can be used to dynamically change effect parameters during processing. All controllers are attached to the active (=the last effect/chainop you specified) effect. The first three parameters are ommon for all controllers. 'fx_param' specifies the parameter to be controlled. Value '1' means the first parameter, '2' the second and so on. 'low_range' and 'high_range' set the value range. You really should see example.html for some more info.

-kos:fx_param,low_range,high_range,freq,i_phase

Sine oscillator with frequency of 'freq' Hz and initial phase of 'i_phase' times pi.

-kf:fx_param,low_range,high_range,genosc_number

Generic oscillator. 'genosc_number' is the number of the oscillator preset to be loaded. The location for the preset file is taken from ./ecasoundrc (see ecasoundrc(5).

-km:fx_param,low_range,high_range,controller,channel

MIDI continuous controller (control change messages). Messages on the MIDI-channel 'channel' that are coming from controller number 'controller' are used as the controller source. The MIDI-device is specified in ./ecasoundrc (see ecasoundrc(5). Defaults to /dev/midi.

INTERACTIVE MODE

'quit', 'q'

Quits ecasound.

'exec'

Ecasound starts the processing engine. Normally you don't need to use this.

'end'

Ecasound exits the processing engine, but doesn't exit the interactive mode. Normally you don't need to use this.

'start', 't'

Processing is started (play).

'stop', 's'

Stops processing.

'rewind time-in-seconds', 'rw time-in-seconds'

Rewind the current position by 'time-in-seconds' seconds.

'forward time-in-seconds', 'fw time-in-seconds'

The current position is forwarded by 'time-in-seconds' seconds.

'setpos time-in-seconds'

Sets the current position to 'time-in-seconds' seconds from the beginning.

'status','st','u'

General status info.

'cstatus','cs','a'

Status info about the effect chains.

'estatus', 'es','x'

Status info about effects and controller envelopes.

'fstatus', 'fs','l'

Status info about open files and devices.

'sfx'

Enable/disable the sound effects section.

'chain chainname', 'c chainname'

Enable/disable the the chain 'chainname'.

'loop'

Start/stop looping.

'loop_start seconds_from_start'

Set the start point for looping.

loop_end seconds_from_start'

Set the end point for looping.

'load file_name'

Load a chainsetup from file 'file_name' and set it active.

'save file_name'

Save the active chainsetup to file 'file_name'.

'help', 'h'

Help!

FILES

~/.ecasoundrc The default ecasound resource file. See ecasoundrc(5) man page.

BUGS

Lots of... ;) See the file BUGS. If ecasound behaves weirdly, try to increase the debug level to see what's going on.

AUTHOR

Kai Vehmanen, <kaiv@wakkanet.fi>