Provided by: ecasound_2.8.1-5build1_amd64 bug

NAME

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

SYNOPSIS

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

DESCRIPTION

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

OPTIONS

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

       ECASOUND OPTIONS

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

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

       -C     Disables ecasound's interactive mode (see '-c' and '-K').

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

       -s[:]chainsetup-file
              Create a new chainsetup from file 'chainsetup-file'  and  add  it  to  the  current
              session.  Chainsetup files commonly have a filename ending to the '.ecs' extension.
              A chainsetup can contain inputs, outputs,  chains,  effects,  controllers  --  i.e.
              objects  one one specific configuration of audio processing elements. A session, on
              the other hand, is a collection of  one  or  more  chainsetups.  Only  one  of  the
              chainsetups  may be connected (i.e. it can be run/processed). But it is possible to
              have another chainsetup select (i.e. can be configured) while other one is  current
              connteced (i.e. running).

       -E "cmd1 [[args] ; cmd2 args ; ... ; cmdN]"
              Execute  a  set  of  Ecasound  Interactive  mode  (EIAM)  commands at launch. These
              commands are executed immediately after ecasound is started. If  the  command  line
              contains sufficient options to create a valid chainsetup that will be executed, the
              launch commands are executed after the other command line options are  parsed,  but
              before the processing engine is started. Note that this command is a feature of the
              ecasound frontend binary and not supported by the library backend. This means  that
              other  clients  may  not support the '-E' option, and also that the launch commands
              are not saved as part of chainsetup or session state.

       --server
              Enables the so called NetECI mode, in which ecasound  can  be  controlled  remotely
              over  a  socket  connection.  When  activated,  clients  can connect to the running
              ecasound session, and use interactive mode commands to control and observe ecasound
              processing.

              The NetECI protocol is defined in Ecasound's Programmer Guide

              One example client using this feature is ecamonitor(1). This utility is included in
              the Ecasound distribution package (requires a working Python environment).

              Warning! If the machine running ecasound, is connected to a public network, be sure
              to  block  ecasound's  port  in  your  firewall!  As  there  is  no  access control
              implemented for incoming connections, anyone can  otherwise  connect,  control  and
              observe  your  ecasound  sessions.   This option replaces '--daemon' (deprecated in
              2.6.0).

       --server-tcp-port=NNN
              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).

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

       --osc-udp-port=NNN
              Enables support for Open Source Control (OSC). Ecasound will  listen  for  incoming
              OSC  messages  on  UDP  port  NNN.  Ecasound's  OSC  interface  is  documented  at:
              <http://ecasound.git.sourceforge.net/git/gitweb.cgi?p=ecasound/ecasound;a=blob;f=Documentation/ecasound_osc_interface.txt;hb=HEAD>

              Note that OSC support is still experimental and the interface might change in later
              versions of Ecasound.

              This option was added to ecasound 2.7.0.

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

       --help,-h
              Show this help.

       --version
              Print version info.

              GLOBAL OPTIONS

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

       -d:debug_level
              Set the debug level  mask  to  'debug_level'.  This  a  bitmasked  value  with  the
              following  classes:  errors  (1),  info  (2),  subsystems  (4),  module_names  (8),
              user_objects  (16),  system_objects  32,  functions  (64),  continuous  (128)   and
              eiam_return_values  (256). Default is 271 (1+2+4+8+256). See sourcode documentation
              for the ECA_LOGGER class for more detailed information.

       -R[:]path-to-file
              Use ecasound resource file (see ecasoundrc man page)  'path-to-file'  as  the  only
              source  of  setting  resource value. Specifying this option will disable the normal
              policy of querying both global and user (if exists) resource files.

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

              GENERAL CHAINSETUP OPTIONS

       -a:chainname1, chainname2, ...
              Selects active signal chains. All inputs and outputs following this '-a' option are
              assigned  to  selected  chains  (until  a  new -a option is specified). When adding
              effects, controllers and other chain operators, only one chain can be selected at a
              time.  If  no -a option has been given, chain 'default' is used instead when adding
              objects.  Chain name 'all' is also reserved. It will cause all existing  chains  to
              be  selected.  By  giving  multiple  -a  options,  you  can control to which chains
              effects, inputs and outputs are assigned to. Look at the EXAMPLES section for  more
              detailed info about the usage of this option.

       -n:name
              Sets  the  name  of  chainsetup  to  'name'.  If  not specified, defaults either to
              "command-line-setup" or  to  the  file  name  from  which  chainsetup  was  loaded.
              Whitespaces are not allowed.

       -x     Truncate  outputs.  All  output  object are opened in overwrite mode.  Any existing
              files will be truncated.

       -X     Open outputs for updating. Ecasound opens all outputs - if target format allows  it
              - in readwrite mode.

       -z:feature
              Enables  'feature'.  Most  features  can  be  disabled using notation -z:nofeature.
              '-z:db,dbsize' enables double-buffering for audio objects that support it (dbsize=0
              for  default,  otherwise  buffer size in sample frames). '-z:nodb' disables double-
              buffering.  '-z:intbuf' and '-z:nointbuf' control whether extra internal  buffering
              is  allowed  for  realtime devices. Disabling this can reduce latency times in some
              situations. With '-z:xruns', processing will be halted if an under/overrun  occurs.
              '-z:multitrack'  and  'z:nomultitrack'  can  be used to force ecasound to enable or
              disable multitrack-mode. In rare cases you  may  want  to  explicitly  specify  the
              recording  offset  with '-z:multitrack,offset-in-samples'. The offset is the amount
              of samples skipped when recording  from  real-time  inputs.  '-z:psr'  enables  the
              precise-sample-rates  mode  for  OSS-devices.  '-z:mixmode,sum' enables mixing mode
              where channels are mixed by summing all channels. The default is  '-z:mixmode,avg',
              in  which  channels  are  mixed  by averaging. Mixmode selection was first added to
              ecasound 2.4.0.  See ecasoundrc man page.

              CHAINSETUP BUFFERING AND PERFORMANCE OPTIONS

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

       -b:buffer size
              Sets  the  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.

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

       -z:feature
              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. 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.

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

       -f:sample_format,channel,sample-rate,interleaving
              Sets the audio stream parameters for subsequent audio objects.   To  set  different
              parameters  for different audio objects, multiple '-f' options have to be specified
              (note the ordering, the '-f' options should precede the audio objects for  them  to
              have any effect). See documentation for '-i' and '-o' options.

              When  an  audio  object  is  opened  (e.g.  a  file  or  sound device is opened, or
              connection is made to a sound server), the audio stream parameters  are  passed  to
              the  object.  It should be noted that not all audio objects allow 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 endianness is not specified, host byte-order is
              used.  Currently supported formats are "u8" (same as "8"), "s16_le" (same as "16"),
              "s16_be",  "s24_le",  "s24_be", "s32_le", "s32_be", "f32_le" and "f32_be". An empty
              string "" picks the system default sample format.

              The 4th parameter defines  the  channel  layout.  The  available  options  are  'i'
              (interleaved'  and  'n' (noninterleaved). With the noninterleaved setting, ecasound
              will process samples one channel at a time, and the blocksize  is  set  with  '-b'.
              The default setting is 'i'.

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

       -i[:]input-file-or-device[,params]
              Specifies a new input source that is connected to all selected chains  (chains  are
              selected  with  '-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.

       -o[:]output-file-or-device[,params]
              Works in the same way as the -i option. If no outputs are  specified,  the  default
              output  device is used (see ~/.ecasoundrc). If the object name contains any commas,
              the name must be enclosed in backquotes to avoid confusing the parser.  Note,  many
              object types do not support output (e.g. MikMod, MIDI and many others).

              OBJECT TYPE SPECIFIC NOTES

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

       ALSA direct-hw and plugin access - 'alsahw', 'alsaplugin'
              It's also possible to  use  a  specific  card  and  device  combination  using  the
              following     notation:     -i[:]alsahw,card_number,device_number,subdevice_number.
              Another option is the ALSA PCM plugin layer. It works just  like  the  normal  ALSA
              pcm-devices, but with automatic channel count and sample format conversions. Option
              syntax is -i[:]alsaplugin,card_number,device_number,subdevice_number.

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

       Audio file sequencing - 'audioloop', 'select', 'playat'
              Ecasound provides a set of special audio object types that can be used for temporal
              sequencing of audio files - i.e. looping, playing only a select portion of a  file,
              playing file at a 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 object.

       Ecasound Wave Files (EWF) - '*.ewf'
              A special file format that allows one to slice and loop full (or segments) of audio
              files. This format is specific to Ecasound.  See ecasound  user's  guide  for  more
              detailed information.

              See also audio object types 'audioloop', 'select' and 'playat'.

       JACK input/outputs - Overview
              JACK is a low-latency audio server that can be used to connect multiple independent
              audio 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" which is a combination of the two previous modes.

              If not explicitly set, in interactive mode  ('-c'  option),  the  default  mode  is
              "sendrecv", while in batchmode default is "notransport". In both cases the mode can
              be changed with -G option as described above.

              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 "foo.wav").

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

       -Md:rawmidi,device_name
              Add a rawmidi MIDI I/O device to the setup. 'device_name' can be anything that  can
              be  accessed  using  the  normal  UNIX file operations and produces raw MIDI bytes.
              Valid devices are for example  OSS  rawmidi  devices  (/dev/midi00),  ALSA  rawmidi
              devices (/dev/snd/midiC2D0), named pipes (see mkfifo man page), and normal files.

       -Md:alsaseq,sequencer-port
              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").

       -Mms:device_id
              Sends MMC start ("Deferred Play") and stop ("Stop") with device ID 'device_id'.

              While Ecasound does not directly support syncing transport state  to  incoming  MMC
              messages,  this  can  be achieved by connecting Ecasound to JACK input/outputs, and
              using    a    tool     such     as     JackMMC     and     JackCtlMMC     (     see
              <http://jackctlmmc.sourceforge.net/>)  to  convert MMC messages into JACK transport
              change events.

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

              EFFECT SETUP

       PRESETS

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

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

       -pn:preset_name
              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.

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

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

       -eadb:gain-dB[,channel]
              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
              (1...n).

       -eaw:amplify%,max-clipped-samples
              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.

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

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

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

       -enm:threshold-level-%,pre-hold,attack,post-hold,release
              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.

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

              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 [0,infinity).

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

       -efc:delay-samples,radius
              Comb filter. Allows the spikes of the comb to  pass  through.   Value  of  '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 specified in Hz. Basicly
              just another resonating bandpass filter.

              CHANNEL MIXING / ROUTING

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

       -chorder:ch1,...,chN
              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
              2.7.0.

       -chmix:to-channel
              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.

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

       -erc:from-channel,to-channel
              Deprecated, see -chcopy.

       -erm:to-channel
              Deprecated, see -chmix.

              TIME-BASED EFFECTS

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

       -etd:delay-time-msec,surround-mode,number-of-delays,mix-%,feedback-%
              Delay effect. '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.).

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

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

              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 man page). One shared library file can contain multiple
              plugin objects, but every plugin has a unique plugin name. This name  is  used  for
              selecting plugins.  See LAD mailing list web site for more info about LADSPA. Other
              useful sites are LADSPA home page and LADSPA documentation.

       -eli:plugin_unique_number,param-1,...,param-N
              Same as above 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' seconds. When closed, passing  audio  buffers
              are trucated to zero length.

       -ge:open-threshold-%,close-thold-%,volume-mode,reopen-count
              Threshold  gate.  Initially  gate  is  closed.  It  is opened when volume goes over
              '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.

       -gm:state
              Manual  gate.  If 'state' is 1, gate is open and all samples are passed through. If
              'state' is zero, gate is closed an no samples are let through. This chain  operator
              is  useful  when  writing  to  an  output  needs to be stopped dynamically (without
              stopping the whole engine).

              CONTROL ENVELOPE SETUP

              Controllers can be used to dynamically change effect parameters during  processing.
              All  controllers  are  attached  to  the  selected  (=usually  the  last  specified
              effect/controller)  effect.  The  first  three  parameters  are  common   for   all
              controllers.  '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.

       -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,freq,mode,point-pairs,start,end,pos1,value1,...
              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' and 'end' 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.

       -kf:fx-param,start-value,end-value,freq,mode,genosc-number
              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 page).

       -kl:fx-param,start-value,end-value,time-seconds
              Linear envelope that starts from 'start_value' and linearly changes to  'end_value'
              during 'time_in_seconds'. Can be used for fadeins and fadeouts.

       -kl2:fx-param,start,end,lenght1,length2
              Two-stage  linear envelope, a more versatile tool for doing fade-ins and fade-outs.
              Stays at 'start' for 'length1' seconds and  then  linearly  changes  towards  'end'
              during 'length2' seconds.

       -klg:fx-param,low,high,count,pos1,value1,...,posN,valueN
              Generic linear envelope. This controller source can be used to map custom envelopes
              to chain operator parameters. Number of envelope points is  specified  in  'count'.
              Each  envelope  point  consists of a position and a matching value. Number of pairs
              must match 'count' (i.e. 'N==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,high]'. E.g.  a value of '0' will set operator
              parameter to 'low' and a value of '1' will  set  it  to  'high'.  For  the  initial
              segment '[0,pos1]', the envelope will output value of 'value1' (e.g. 'low').

       -km:fx-param,start-value,end-value,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. As recommended by the MIDI-specification, channel numbering goes
              from 1 to 16. Possible controller numbers are values from 0 to 127. The MIDI-device
              where bytes are read from can be specified using -Md option.  Otherwise the default
              MIDI-device is used as specified in ~ecasound/ecasoundrc (see ecasoundrc man page).
              Defaults to /dev/midi.

       -ksv:fx-param,start-value,end-value,stamp-id,rms-toggle
              Volume  analyze  controller.  Analyzes  the  audio  stored in stamp '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.

       INTERACTIVE MODE

       See ecasound-iam(1) man page.

ENVIRONMENT

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

       ECASOUND_LOGFILE
              Output all debugging messages to a separate log file. If defined,  ECASOUND_LOGFILE
              defines  the  logfile  path. This is a good tool for debugging ECI/EIAM scripts and
              applications.

       ECASOUND_LOGLEVEL
              Select which messages are written to the logfile defined by  ECASOUND_LOGFILE.  The
              syntax  for -d:level is used. If not defined, all messages are written. Defaults to
              -d:319  (everything  else  but  'functions  (64)'  and  'continuous  (128)'   class
              messages).

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

       TMPDIR Some functions of Ecasound (e.g. "cs-edit" interactive command) require creation of
              temporary  files. By default, these files are created under "/tmp", but this can be
              overridden by setting the TMPDIR environment variable.

RETURN VALUES

              In interactive mode, ecasound always returns zero.

              In non-interactive (batch) mode, a non-zero value is  returned  for  the  following
              errors:

       1      Unable  to  create  a  valid chainsetup with the given parameters. Can be caused by
              invalid option syntax, etc.

       2      Unable to start processing. This can be caused by  insufficient  file  permissions,
              inability to access some system resources, etc.

       3      Error  during  processing.  Possible causes: output object has run out of free disk
              space, etc.

       4      Error during process termination and/or  cleanup.  See  section  on  'SIGNALS'  for
              further details.

SIGNALS

       When  ecasound  receives  any  of  the  POSIX  signals SIGINT (ctrl-c), SIGHUP, SIGTERM or
       SIGQUIT, normal cleanup and exit procedure is initiated. Here normal exit means that  e.g.
       file  headers  are  updated before closing, helper processes are terminated in normal way,
       and so forth.

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

FILES

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

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

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

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

EXAMPLES

       Examples   of   how   to   perform   common   tasks   with   ecasound   can  be  found  at
       http://eca.cx/ecasound/Documentation/examples.html.

SEE ALSO

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

BUGS

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

AUTHOR

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

                                            05.05.2011                                ecasound(1)