Man Linux: Main Page and Category List


       ecasound - sample editor, multitrack recorder, fx-processor, etc.


       ecasound  [  general_options  ]  {  [  chain_setup ] [ effect_setup ] [
       input_setup ] [ output_setup ] }


       Ecasound  is  a  software  package  designed   for   multitrack   audio
       processing.  It  can  be  used  for  simple  tasks like audio playback,
       recording and format conversions, as  well  as  for  multitrack  effect
       processing, mixing, recording and signal recycling. Ecasound supports a
       wide range of audio inputs, outputs and effect algorithms.  Effects and
       audio objects can be combined in various ways, and their parameters can
       be controlled by operator objects  like  oscillators  and  MIDI-CCs.  A
       versatile console mode user-interface is included in the package.


       Note! All options except those mentioned in ecasound options and Global
       options, can be used in ecasound chainsetup files (.ecs).


              These options are parsed and handled by  the  ecasound  frontend
              binary  and  are  not passed to backend library. This means that
              these options may  not  work  in  other  applications  that  use
              ecasound libraries for their functionality.

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

              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

              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

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

              Set the TCP port used by the daemon mode.  By  default  ecasound
              will use port number 2868.  This option replaces '--daemon-port'
              (deprecated in 2.6.0).

              Disable ecasound's daemon  mode.  This  is  the  default.   This
              option replaces '--nodaemon' (deprecated in 2.6.0).

              Enables  support  for  Open  Source Control (OSC). Ecasound will
              listen for incoming OSC messages on UDP port NNN. Ecasound's OSC
              interface              is             documented             at:

              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.

              Do not exit when processing is  finished/stopped.  Only  affects
              non-interactive  operating  mode  (see  -c/-C).  Option added to
              ecasound 2.4.2.

              Show this help.

              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.

              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.

              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.


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

              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.

              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.


              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
              outputs are normal files), values between 512 - 4096 often  give
              better results. Default is 1024.

              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.

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


              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. A special-case value of '-1' 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 'cs-loop'
              EIAM command.

              INPUT/OUTPUT SETUP

       See ecasound user's guide for more detailed documentation.

              Sets  options  for  audio  object  manager  type 'mgrtype'.  For
              available options, see "OBJECT TYPE SPECIFIC NOTES" below.

              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  to  set any or all of the
              parameters.  For instance when  opening  existing  audio  files,
              many  file  formats  have  a  header  describing  the file audio
              parameters. In these cases the audio file header  overrides  the
              parameters passed with '-f' option. Similarly when creating JACK
              inputs and outputs, the JACK server mandates the  sampling  rate
              and sample format.

              If  no  '-f' option is specified, or some of the argument fields
              are left empty (e.g. '-f:,2,44100'), ecasound will  use  default
              values.   These   default   values  are  defined  in  ecasoundrc
              configuration file. See ecasoundrc(5) manual page.

              Note that ecasound opens out files by default  in  update  mode.
              Unless  option  '-x'  (overwrite outputs) option is given, audio
              parameters of an existing audio file take  preference  over  the
              params set with '-f'.

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

              Sets  starting  position for last specified input/output. If you
              need more flexible control over audio objects,  you  should  use
              the .ewf format.

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

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


       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

       aRts input/output - 'arts'
              If enabled at compile-time, ecasound supports  audio  input  and
              output  using  aRts  audio  server.  Option  syntax  is -i: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
              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.  "-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

       Ecasound Wave Files (EWF) - '*.ewf'
              A special file format that allows 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 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 - '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 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
              "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 "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'
              A variant of 'jack' object type is 'jack_multi'. The full object
              syntax    is    jack_multi,destport1,...,destportN.    When    a
              'jack_multi' object is connected to a JACK server, first channel
              of the object is connected to JACK port 'destport1',  second  to
              'destport2'   and  so  forth.  For  instance  "-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
              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   -   'jack_alsa',   'jack_auto',   'jack_generic'
       (**deprecated since 2.6.0**)
              Ecasound 2.5 and older supported  "jack_alsa",  "jack_auto"  and
              "jack_generic"  object  types,  but  these are now replaced by a
              more generic "jack" 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. 'client_name' is  the
              name  used  when  registering  ecasound  to the JACK system.  If
              'operation_mode' is "notransport",   ecasound  will  ignore  any
              transport  state  changes  in the JACK-system; in mode "send" 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"  (the
              default) which is a combination of the two previous modes.

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

       Libaudiofile - 'audiofile'
              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 - 'sndfile'
              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  "format"  can  be  used  to override the audio
              format (for example you can create an AIFF  file  with  filename

       Loop device - 'loop'
              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"). 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).

       Mikmod - 'mikmod'
              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'
              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 - 'resample'
              Object type 'resample' can be used to  resample  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  file from
              22.05kHz to 44.1kHz  and  write  the  result  to  the  soundcard
              device. Child sampling rate can be replaced with keyword 'auto'.
              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
              '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. To  force  ecasound  to  use  the  internal
              resampler, 'resampler-lq' (low-quality) can be used.

       Reverse - 'reverse'
              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.

              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', 'stdout'
              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'
              To generate a test tone,  input  -i:tone,type,freq,duration-secs
              can be used. Parameter 'type' 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'
              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.

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

              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.

              Adds a 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").

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

       -Mss   Sends  MIDI-sync  (i.e.  "MIDI  Start"  and  "MIDI  Stop" system
              realtime messages) .to the selected MIDI-device. Notice that  as
              Ecasound  will  not send MIDI-clock, but only the start and stop

              EFFECT SETUP


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

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

              Find preset 'preset_name' 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 '-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   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.


              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.

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

              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'.

              Adjusts  signal level by 'gain-dB', with a gain of 0dB having no
              effect to the signal, negative gains attenuating the signal  and
              positive  gain  values  amplifying  it.  The 'channel' parameter
              (1...n) is optional.  If 'channel' parameter is  specified,  and
              its  value is nonzero, gain is only applied to the given channel

              Amplifies  signal  by  amplify-%  percent  (linear  scale,  i.e.
              individual  samples are multiplied by 'amplify%/100'). If number
              of  consecutive  clipped  samples  (resulting  sample  value  is
              outside the nominal [-1,1] range), a warning will be issued.

              Limiter  effect.  Limits audio level to 'limit-%' (linear scale)
              with values equal or greater than 100% resulting in no change to
              the signal.

              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

       -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.  'peak-level-%' essentially specifies how hard the peak
              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
              dominant 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
              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.   'rate'  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.

              Noise  gate.  Supports  multichannel  processing  (each  channel
              processed  separately).  When  signal  amplitude   falls   below
              'threshold_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.

              Pitch shifter. Modifies audio pitch by altering its length.

              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.

              Adjusts the signal DC by 'delta-chX', where  X  is  the  channel
              number. Use -ezf to find the optimal delta values.


              Pulse gate (pulse frequency given as beats-per-minute).

              Pulse gate.

              Tremolo effect (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 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.

       -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

              Allpass  filter.  Passes  all  frequencies  with  no  change  in
              amplitude.    However,   at   the   same   time   it  imposes  a
              frequency-dependent phase-shift.

              Comb filter. Allows the spikes of  the  comb  to  pass  through.
              Value of 'radius' should be between [0, 1.0).

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

              Highpass filter. Only frequencies above 'cutoff_freq' are passed

              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.

              Lowpass filter. Only frequencies below 'cutoff_freq' are  passed

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

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


       -chcopy:from-channel, to-channel
              Copy channel 'from_channel'  to  'to_channel'.  If  'to_channel'
              doesn't  exist,  it  is created. Channel indexing starts from 1.
              Option added to ecasound 2.4.5.

       -chmove:from-channel, to-channel
              Copy 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.

              Reorder, omit and/r  duplicate  chain  channels.  The  resulting
              audio stream has total of 'N' channels. Each parameter specifies
              the source channel to  use  for  given  output  channel.  As  an
              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  two  output  channels
              ('out1,out2'  =  'in2,in2'). If 'chX' is zero, the given channel
              'X' will be muted in the output stream. Option added to ecasound

              Mix   all   source   channels   to   channel  'to_channel'.   If
              'to_channel' doesn't exist,  it  is  created.  Channel  indexing
              starts from 1.  Option added to ecasound 2.4.5.

              Mutes  the  channel  'channel'.  Channel indexing starts from 1.
              Option added to ecasound 2.4.5.

              Deprecated, see -chcopy.

              Deprecated, see -chmix.

              TIME-BASED EFFECTS


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

              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.

              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.


              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.


              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.


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

              Same  as  above  expect plugin's unique id-number is used. It is
              guaranteed that these id-numbers are  unique  among  all  LADSPA

              GATE SETUP

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

              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,  unless  the 'reopen-count' is set to anything other than
              zero.  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.  If the  'reopen-count'  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
              'reopen-count' will result in the gate  reopening  indefinitely.
              The  'reopen-count'  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 it's 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.


              Controllers can be used to dynamically change effect  parameters
              during  processing. All controllers are attached to the selected
              (=usually the  last  specified  effect/controller)  effect.  The
              first   three   parameters   are  common  for  all  controllers.
              'fx_param' specifies the parameter to be controlled.  Value  '1'
              means   the   first   parameter,  '2'  the  second  and  so  on.
              'start_value' and 'end_value' set the value range. For examples,
              look at the the EXAMPLES section.

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

              Generic oscillator. Frequency 'freq' Hz,  mode  either  '0'  for
              static  values  or  '1'  for linear interpolation. 'point-pairs'
              specifies the number of 'posN'  -  'valueN'  pairs  to  include.
              'start-value'  and  'end-value'  are used as border values.  All
              'posN' and 'valueN' must be between 0.0 and 1.0. Also,  for  all
              'posN' values 'pos1 < pos2 < ... < posN' must be true.

              Generic   oscillator.  'genosc_number'  is  the  number  of  the
              oscillator preset to be loaded. Mode is either  '0'  for  static
              values  or  '1'  for  linear interpolation. The location for the
              preset file is  taken  from  ./ecasoundrc  (see  ecasoundrc  man

              Linear  envelope  that  starts  from  'start_value' and linearly
              changes to 'end_value' during 'time_in_seconds'. Can be used for
              fadeins and fadeouts.

              Two-stage  linear  envelope,  a  more  versatile  tool for doing
              fade-ins   and   fade-outs.   Stays   at    'start_value'    for
              '1st_stage_length'  seconds  and  then  linearly changes towards
              'end_value' during '2nd_stage_length' seconds.

              Generic linear envelope. This controller source can be  used  to
              map  custom  envelopes  to  chain operator parameters. Number of
              envelope points is specified  in  'point_count'.  Each  envelope
              point  consists  of  a  position and a matching value. Number of
              pairs must  match  'point_count'  (i.e.  'N==point_count').  The
              'posX'  parameters  are  given  as  seconds  (from  start of the
              stream). The envelope points are specified as  float  values  in
              range  '[0,1]'.  Before  envelope  values are mapped to operator
              parameters,  they  are   mapped   to   the   target   range   of
              '[low-value,high-value]'. E.g.  a value of '0' will set operator
              parameter to 'low-value' and a value  of  '1'  will  set  it  to
              'high-value'.  For  the initial segment '[0,pos1]', the envelope
              will output value of 'value1' (e.g. 'low-value').

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

              Volume analyze controller. Analyzes the audio  stored  in  stamp
              'stamp-id'  (see  '-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    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.


       See ecasound-iam(1) man page.


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

              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.

              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 'functions  (64)'  and  'continuous  (128)'
              class messages).

              Ecasound honors the COLUMNS environment variable when formatting
              printed trace messages. If COLUMNS is not set, a default  of  74
              is used.


              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,

       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
              'SIGNALS' for further details.


       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

       If,  while doing the cleanup described above, ecasound receives another
       signal (of the same set of  POSIX  signals),  ecasound  will  skip  the
       normal  cleanup  procedure,  and  terminate  immediately. Any remaining
       cleanup tasks will be skipped.  Depending  on  the  runtime  state  and
       configuration,  this  brute  force  exit  may  have  some side-effects.
       Ecasound will return exit code of '4' if normal cleanup was skipped.

       Special case handling is applied to the SIGINT (ctrl-c) signal.   If  a
       SIGINT  signal  is received during the cleanup procedure, ecasound will
       ignore the signal once, and emit a notice to 'stderr' that  cleanup  is
       already  in  progress. Any subsequent SIGINT signals will no longer get
       special handling, and instead process will terminate  immediately  (and
       possibly without proper cleanup).


       ~/.ecasound  The  default  directory  for ecasound user resource files.
       See the ecasoundrc (5) man page man page.

       *.ecs Ecasound Chainsetup files. Syntax is more or  less  the  same  as
       with command-line arguments.

       *.ecp  Ecasound  Chain  Preset files. Used for storing effect and chain
       operator  presets.  See  ecasound  user's   guide   for   more   better

       *.ews Ecasound Wave Stats. These files are used to cache waveform data.


       Examples of how to perform common tasks with ecasound can be  found  at


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


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


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

                                  10.10.2009                       ecasound(1)