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  process-
       ing. It can be used for simple tasks like audio playback, recording and
       format conversions, as well as for multitrack effect  processing,  mix-
       ing,  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 Global options, can be used
       in ecasound chainsetup files (.ecs).

       GLOBAL OPTIONS

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

       -C     Disables ecasound´s interactive mode (see ´-c´).

       -d, -dd, -ddd
              Increase the amount of printed debug messages. -d adds some ver-
              bosity, while -ddd results in very detailed output.

       -d:debug_level
              Set  the  debug  level  mask  to ´debug_level´. This a bitmasked
              value, that defaults to 263. See ECA_LOGGER class  documentation
              for more detailed info about various debug_level values.

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

       -q     Quiet mode, no output. Same as -d:0.

       -s[:]chainsetup-file
              Create a new chainsetup from file ´chainsetup-file´ and  add  it
              using a TCP/IP network connection.  The clients can both observe
              and control the session.

              Warning! As there is no access control implemented, be  sure  to
              block  ecasound´s  port  in your firewall if the machine running
              ecasound is connected to a public network! Otherwise anyone  can
              connect to your ecasound sessions.

       --daemon-port
              Set  the  TCP  port used by the daemon mode. By default ecasound
              will use port number 2868.

       --nodaemon
              Disable ecasound´s daemon mode. This is the default.

       --help Show this help.

       --version
              Print version info.

       GENERAL CHAINSETUP OPTIONS

       -a:chainname1, chainname2, ...
              Selects active signal chains. All effects,  inputs  and  outputs
              following  this  ´-a´  option  are  assigned  to selected chains
              (until a new -a option is specified). If no -a option  has  been
              given, chain ´default´ is used instead. Chain name ´all´ is also
              reserved and means that all chains are selected. By giving  mul-
              tiple  -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  tar-
              get 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 (dbzise=0 for default, otherwise buffer
              when  recording from real-time inputs. ´-z:psr´ enables the pre-
              cise-sample-rates mode for OSS-devices. See ecasoundrc(5).

       CHAINSETUP BUFFERING AND PERFORMANCE OPTIONS

       -B:buffering_mode
              Selects the default buffering  mode.  Mode  is  one  of:  ´auto´
              (default), ´nonrt´, ´rt´, ´rtlowlatency´.

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

       -r:sched_priority
              Use  realtime scheduling policy (SCHED_FIFO). This is impossible
              if ecasound doesn´t have root priviledges.  Beware!  This  gives
              better  performance,  but  can cause total lock-ups if something
              goes wrong.  The ´sched_priority´ can be omitted (0=omitted). If
              given,  this is the static priority to the highest priority eca-
              sound  thread.   Other  ecasound  threads  run   with   priority
              ´sched_priority-1...n´.   Value  ´-1´  can  be  used  to disable
              raised-priority mode.

       -z:feature
              Relevant  features  are  -z:db,xxx   (-z:nodb)   and   -z:intbuf
              (-z:nointbuf).   See  section  General  chainsetup  options  for
              details.

       PROCESSING CONTROL

       -t:seconds
              Sets processing time in seconds (doesn´t have to be  an  integer
              value).   If  processing  time  isn´t set, engine stops when all
              inputs are finished. This option is equivalent to  the  ´cs-set-
              length´ EIAM command.

       -tl    Enables  looping. When processing is finished, engine will start
              again from beginning. This option is equivalent to the ´cs-loop´
              EIAM command.

       INPUT/OUTPUT SETUP

              Sets default sampling parameters. These are used for all follow-
              ing  input and output files or until another -f is specified. If
              no -f option is present, ecasound  uses  s16_le/2ch/44100/inter-
              leaved  as  the  default  value. Some audio objects may override
              this altogether (for instance, RIFF WAVE inputs and outputs).

              Sample format is given as a a formatted string. The first letter
              is  either  "u", "s" and "f" (unsigned, signed, floating point).
              The following number specifies sample size in bits. If sample is
              little  endian,  "_le"  is  added  to  the end. Similarly if big
              endian, "_be" is added. If  endianess  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".

              The  4th parameter ´interleaving´ should either be ´i´ (default)
              for interleaved stream format, or ´n´ for noninterleaved.

       -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
              Specifies a new input source that is connected to  all  selected
              chains.  Connecting multiple inputs to the same chain isn´t pos-
              sible. 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. Currently supported  formats  are
              RIFF  WAVE  files  (.wav), audio-cd tracks (.cdr), ecasound ewf-
              files (.ewf), RAW audio data (.raw) and MPEG files  (.mp2,.mp3).
              Also,  formats  supported  by  the  SGI  audiofile library: AIFF
              (.aiff, .aifc, .aif) and Sun/NeXT audio files (.au, .snd).  Mik-
              Mod  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. Supported realtime  devices  are  OSS  audio  devices
              (/dev/dsp*),  ALSA  audio and loopback devices. 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
              Works in the same way as the -i option. If no outputs are speci-
              fied, the default output device  is  used  (see  ~/.ecasoundrc).
              Note!   you  can´t  output to module formats supported by MikMod
              (this should be obvious).

              OBJECT TYPE SPECIFIC NOTES

       ALSA devices
              When using ALSA drivers, instead of a device filename, you  need
              to use the following option syntax: -i[:]alsa,pcm_device_name.


       aRts input/output
              If  enabled  at  compile-time, ecasound supports audio input and
              output using  aRts  audio  server.  Option  syntax  is  -i:arts,
              -o:arts.

       Ecasound Wave Files - .ewf
              A  simple  wrapper  class for handling other audio objects.  See
              ecasound user´s guide for more detailed information.

       JACK input/outputs
              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 pro-
              fessional audio work.

              Ecasound  provides  multiple  ways  to  communicate  with   JACK
              servers.  To  directly  input  or  output  to  soundcard, use -i
              jack_alsa and -o jack_alsa. To communicate with other apps,  use
              jack_auto,remote_clientname. To just create ports without making
              any    automatic    connections,    there    are    jack     and
              jack_generic,local_portprefix.

              Additionally    global   JACK   options   can   be   set   using
              -G:jack,client_name,operation_mode. ´client_name´  is  the  name
              used  when  registering ecasound to the JACK system.  If ´opera-
              tion_mode´ is "notransport",  ecasound will ignore any transport
              state  changes  in the JACK-system; in mode "send" (the default)
              it will send all start, stop and position-change events to other
              JACK  clients;  in  mode "recv" ecasound will follow JACK start,
              stop and position-change events; and mode "sendrecv" which is  a
              combination of the two previous modes.

              More  details  about  ecasound´s  JACK support can be found from
              ecasound user´s guide.

       Loop device
              Loop devices make it possible  to  route  data  between  chains.
              Option  syntax is -[io][:]loop,id_number. If you add a loop out-
              put with id ´1´, all data written to this output  is  routed  to
              all loop inputs with id ´1´. You can attach the same loop device
              to multiple inputs and outputs.

       Null inputs/outputs
              If you specify "null" or "/dev/null" as the input or  output,  a
              null audio device is created. This is useful if you just want to
              analyze sample data without writing it to a file. There´s also a
              realtime  variant,  "rtnull",  which  behaves  just  like "null"
              objects, except all i/o is done at realtime speed.

       Resample - access object of different sample rates
              the   previous   example,   ecasound   -f:16,2,44100  -i  resam-
              ple,auto,foo.wav -o /dev/dsp.

              If ecasound was compiled with support for libsamplerate, you can
              use  ´resample-hq´  to  use the highest quality resampling algo-
              rithm available.

       Reverse - process audio data backwards
              Object type ´reverse´ can be used to reverse audio  data  coming
              from an audio object. As an example, ecasound -i reverse,foo.wav
              -o /dev/dsp will  play  ´foo.wav´  backwards.  Reversing  output
              objects  is  not supported. Note! Trying to reverse audio object
              types  with  really  slow  seek  operation  (like  mp3),   works
              extremely  badly.  Try converting to an uncompressed format (wav
              or raw) first, and then do reversation.

       System standard streams and named pipes
              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.

       Typeselect - overriding object type settings
              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.

       MIDI SETUP

       -Md:rawmidi,device_name
              Sets  the active MIDI-device. ´device_name´ can be anything that
              can be accessed using the normal UNIX file operations  and  pro-
              duces  raw MIDI bytes. Valid devices are for example OSS rawmidi
              devices (/dev/midi00), named pipes (see mkfifo(1) man page), and
              normal  files. If no MIDI-device is specified, the default MIDI-
              device is used (see ecasoundrc(5)).

       -Mms:device_id
              Sends MMC start and stop to MIDI device-id ´device_id´.

       -Mss   Sends MIDI-sync to the selected MIDI-device. Note! Ecasound will
              not send MIDI-clock, but only start and stop messages.

       EFFECT SETUP

       PRESETS


       -pn:preset_name
              Find preset ´preset_name´ from global preset database and use it
              as a chain operator. See ecasoundrc(5) for info about the preset
              database.

       SIGNAL ANALYSIS

       -ev    Analyzes sample data to find out how  much  the  signal  can  be
              amplified  without  clipping. The resulting percent value can be
              used as a parameter to -ea  and  -eas  effects.  Also  prints  a
              statistics  table  containing  info  about  stereo-image and how
              different sample values are used.

       -evp   Peak amplitude watcher. Maintains peak information for each pro-
              cessed channels. Peak information is resetted on every read.

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

       GENERAL SIGNAL PROCESSING ALGORITHMS

       -eS:stamp-id
              Audio stamp. Takes a snapshot of passing audio data  and  stores
              it  using id ´stamp-id´ (integer number). This data can later be
              used by controllers and other operators.

       -ea:amplify-%
              Amplifies signal by amplify-% percent.

       -eac:amplify-%,channel
              Amplifies signal of  channel  ´channel´  by  amplify-%  percent.
              ´channel´ ranges from 1...n where n is the total number of chan-
              nels.

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

       -eal:limit-%
              Limiter effect. Limits audio level to ´limit-%´.

       -ec:rate,threshold-%
              Compressor  (a  simple  one).  ´rate´ is the compression rate in
              limiter  is  pushed.  The default of 69% is good. ´release_time´
              is given in seconds. This compressor is very sophisticated,  and
              actually  the release time is complex.  This is one of the domi-
              nant release time controls,  but  the  actual  release  time  is
              dependent  on  a  lot  of  factors regarding the dynamics of the
              audio in. ´fastrate´ is the compression ratio for the fast  com-
              pressor.   This  is  not really the compression ratio.  Value of
              1.0 is infinity to one, while the default 0.50 is 2:1.   Another
              really good value is special cased in the code: 0.25 is somewhat
              less than 2:1, and sounds super smooth.  ´rate´ is the  compres-
              sion 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  pro-
              cessed  separately).  When signal amplitude falls below ´thresh-
              old_level_%´ percent (100% means  maximum  amplitude),  gate  is
              activated. If the signal stays below the threshold for ´th_time´
              ms, it´s faded out during the attack phase of  ´attack´  ms.  If
              the  signal  raises  above the ´threshold_level´ and stays there
              over ´hold´ ms the gate is released during ´release´ ms.

       -ei:pitch-shift-%
              Pitch shifter. Modifies audio pitch by altering its length.

       -epp:right-%
              Stereo panner. Changes the relative balance  between  the  first
              two channels. When ´right-%´ is 0, only signal on the left (1st)
              channel is passed through. Similarly if it is ´100´, only  right
              (2nd) channel is let through.

       -ezx:channel-count,delta-ch1,...,delta-chN
              Adjusts  the  signal  DC  by ´delta-chX´, where X is the channel
              number. Use -ezf to find the optimal delta values.

       ENVELOPE MODULATION

       -eemb:bpm,on-time-%
              Pulse gate (pulse frequency given as beats-per-minute).

       -eemp:freq-Hz,on-time-%
              Pulse gate.

       -eemt:bpm,depth-%
              Tremolo effect (tremolo speed given as beats-per-minute).

              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 multi-
              plier  (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 ampli-
              tude.  However, at the same time it imposes  a  frequency-depen-
              dent phase-shift.

       -efc:delay-samples,radius
              Comb  filter.  Allows  the  spikes  of the comb to pass through.
              Value of ´radius´ should be between [0, 1.0).

       -efb:center-freq,width
              Bandpass filter. ´center_freq´ is the center frequency. Width is
              specified in Hz.

       -efh:cutoff-freq
              Highpass filter. Only frequencies above ´cutoff_freq´ are passed
              through.

       -efi:delay-samples,radius
              Inverse comb filter. Filters out the spikes of the  comb.  There
              are  ´delay_in_samples-2´  spikes.  Value  of ´radius´ should be
              between [0, 1.0). The closer it is to  the  maximum  value,  the
              deeper the dips of the comb are.

       -efl:cutoff-freq
              Lowpass  filter. Only frequencies below ´cutoff_freq´ are passed
              through.

       -efr:center-freq,width
              Bandreject filter. ´center_freq´ is the center frequency.  Width
              is specified in Hz.

       -efs:center-freq,width
              Resonator. ´center_freq´ is the center frequency. Width is spec-
              ified in Hz. Basicly just another resonating bandpass filter.


       -erm:to-channel
              Mix all  channels  to  channel  ´to_channel´.   If  ´to_channel´
              doesn´t  exist,  it is created. Channel indexing is started from
              1.

       TIME-BASED EFFECTS

       -etc:delay-time-msec,variance-time-samples,feedback-%,lfo-freq
              Chorus.

       -etd:delay-time-msec,surround-mode,number-of-delays,mix-%,feedback-%
              Delay effect. ´delay time´ is the delay  time  in  milliseconds.
              ´surround-mode´  is  a integer with following meanings: 0 = nor-
              mal, 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. ´feedback-%´
              represents how much of the signal is recycled in each delay  or,
              if  you  prefer,  at  what  rate the repeated snippet of delayed
              audio fades. Note that  sufficiently  low  feedback  values  may
              result  in  a number of audible repetitions lesser than what you
              have specified for ´number_of_delays´, especially  if  you  have
              set  a  low  value  for  ´mix-%´.  By default the value for this
              parameter is 100% (No signal loss.).

       -ete:room_size,feedback-%,wet-%
              A more advanced reverb effect (original algorithm by  Stefan  M.
              Fendt).   ´room_size´  is  given  in meters, ´feedback-%´ is the
              feedback level given in percents and ´wet-%´ is  the  amount  of
              reverbed signal added to the original signal.

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

       -etl:delay-time-msec,variance-time-samples,feedback-%,lfo-freq
              Flanger.

       -etm:delay-time-msec,number-of-delays,mix-%
              Multitap  delay. ´delay time´ is the delay time in milliseconds.
              ´number_of_delays´ should be  obvious.  ´mix-%´  determines  how
              much effected (wet) signal is mixed to the original.

       -etp:delay-time-msec,variance-time-samples,feedback-%,lfo-freq
              Phaser.

       LADSPA-PLUGINS

       -el:plugin_unique_name,param-1,...,param-N
              Ecasound supports LADSPA-effect plugins (Linux Audio Developer´s
              Simple  Plugin API). Plugins are located in shared library (.so)
              files in /usr/local/share/ladspa (configured in  ecasoundrc(5)).
              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  expect plugin´s unique id-number is used. It is
              guaranteed that these id-numbers are  unique  among  all  LADSPA
              plugins.

       GATE SETUP

       -gc:start-time,len
              Time  crop  gate.  Initially  gate is closed. After ´start-time´
              seconds has elapsed, gate opens and remains open for ´len´  sec-
              onds.  When  closed,  passing audio buffers are trucated to zero
              length.

       -ge:open-threshold-%, close-thold-%,volume-mode
              Threshold gate. Initially gate is closed. It is opened when vol-
              ume  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.   When  closed,  passing  audio
              buffers are trucated to zero length.

       CONTROL ENVELOPE SETUP

              Controllers  can be used to dynamically change effect parameters
              during processing. All controllers are attached to the  selected
              (=usually  the  last  specified  effect/controller)  effect. The
              first  three  parameters  are  common   for   all   controllers.
              ´fx_param´  specifies  the parameter to be controlled. Value ´1´
              means  the  first  parameter,  ´2´  the  second   and   so   on.
              ´start_value´  and  ´end_value´  set the value range. You really
              should see examples.html for some more info.

       -kos:fx-param,start-value,end-value,freq,i-phase
              Sine oscillator with frequency of ´freq´ Hz and initial phase of
              ´i_phase´ times pi.

       -kog:fx-param,start-value,end-value,freq,mode,point-pairs,start-

                                  26.08.2003                       ecasound(1)