Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
ecasound(1)		      Multimedia software		   ecasound(1)

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

       ecasound	 [  general_options ] {	[ chain_setup ]	[ effect_setup ] [ in-
       put_setup ] [ output_setup ] }

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

       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  eca-
	      sound 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 file-
	      name 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 com-
	      mands  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 con-
	      trolled remotely	over  a	 socket	 connection.  When  activated,
	      clients can connect to the running ecasound session, and use in-
	      teractive	mode commands to control and observe ecasound process-

	      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  (re-
	      quires a working Python environment).

	      Warning! If the machine running ecasound,	is connected to	a pub-
	      lic network, be sure to block ecasound's port in your  firewall!
	      As  there	 is no access control implemented for incoming connec-
	      tions, 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  op-
	      tion 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:	  <http://ecasound.git.source-;a=blob;f=Documenta-

	      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.


       -d, -dd,	-ddd
	      Increase the amount of printed debug messages. -d	adds some ver-
	      bosity, 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),  subsys-
	      tems  (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	query-
	      ing 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,  de-
	      faults  either  to "command-line-setup" or to the	file name from
	      which chainsetup was loaded. Whitespaces are not allowed.

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

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

	      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',  pro-
	      cessing  will  be	 halted	if an under/overrun occurs. '-z:multi-
	      track' and 'z:nomultitrack' can be used to force ecasound	to en-
	      able  or	disable	multitrack-mode. In rare cases you may want to
	      explicitly specify the recording offset with '-z:multitrack,off-
	      set-in-samples'.	The  offset  is	 the amount of samples skipped
	      when recording from real-time inputs. '-z:psr' enables the  pre-
	      cise-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' (de-
	      fault), 'nonrt', 'rt', 'rtlowlatency'.

	      Sets the processing engine buffer	size in	samples. The size must
	      be  an  exponent	of  2,	and it is independent of channel count
	      (e.g. -b:1024 at 48kHz will result  in  21.333ms	buffer	length
	      whether input is mono, stereo or 5.1).

	      This  is	an  important option as	this defines the length	of one
	      processing engine	iteration and affects  ecasound	 behaviour  in
	      many  ways.  If  not  explicitly specified, ecasound will	try to
	      choose an	optimal	value based on current buffering mode (see  -B
	      option).	For  real-time	processing, you	can try	to set this as
	      low as possible to reduce	the processing	delay.	Some  machines
	      can  handle  buffer values as low	as 64 and 128. In some circum-
	      stances (for instance when  using	 oscillator  envelopes)	 small
	      buffer  sizes  will  make	envelopes act more smoothly.  When not
	      processing in real-time  (all  inputs  and  outputs  are	normal
	      files),  larger  values may help to avoid	buffer overruns, lower
	      CPU usage	and/or otherwise improve performance.

	      Note that	when any JACK input/outputs are	used, the buffer  size
	      setting  is overridden and set to	period/buffer size reported by
	      JACK server (e.g.	jackd's	'-p' option).  It is not  possible  to
	      turn off this behaviour.

	      If  not  explicitly specified, the default buffer	size is	chosen
	      based on current buffering mode (see -B).

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

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


	      Sets  processing	time in	seconds	(doesn't have to be an integer
	      value).  If processing time isn't	set, engine stops when all in-
	      puts   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.


       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,	multi-
	      ple '-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	param-
	      eters.  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

	      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 configu-
	      ration 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  en-
	      dian,  "_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 op-
	      tions are	'i' (interleaved' and 'n' (noninterleaved).  With  the
	      noninterleaved  setting, ecasound	will process samples one chan-
	      nel 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 back-
	      quotes to	avoid confusing	the parser. Currently  supported  for-
	      mats  are	 RIFF  WAVE files (.wav), audio-cd tracks (.cdr), eca-
	      sound EWF	files (.ewf), RAW audio	data  (.raw)  and  MPEG	 audio
	      files  (.mp2,.mp3).  More	audio formats are supported via	libau-
	      diofile and libsndfile libraries (see documentation below). Mik-
	      Mod  is  also  supported (.xm, .mod, .s3m, .it, etc). MIDI files
	      (.mid) are supported using  Timidity++.	Similarly  Ogg	Vorbis
	      (.ogg)  can be read, and written if ogg123 and vorbize tools are
	      installed; 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 sub-
	      system.  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	speci-
	      fied,  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,de-
	      vice_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,sub-

       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 spe-
	      fific 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	param-
	      eters given are passed unaltered to the file object.  Parameters
	      3...N  are  passed  as  is  to the child object (i.e.  "-i audi-
	      oloop,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	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  pro-
	      fessional	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 "eca-
	      sound: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 con-
	      nected anywhere (e.g. to soundcard input/outputs,	 or  to	 other
	      apps).  One  thus	has to connect the ports with an external pro-
	      gram (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  con-
	      nected  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  pa-
	      rameter  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  ob-
	      ject,  with its left and right channels routed to	two difference
	      JACK clients. The	destination ports must be active when the eca-
	      sound 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' (**depre-
       cated 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 'op-
	      eration_mode' is "notransport",  ecasound	will ignore any	trans-
	      port 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 com-
	      bination of the two previous modes.

	      If not explicitly	set, in	interactive mode  ('-c'	 option),  the
	      default  mode  is	"sendrecv", while in batchmode default is "no-
	      transport". 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 read-
	      ing/writing a  certain  audio  file.  Option  syntax  is	-i:au-
	      diofile,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/writ-
	      ing  a  certain  audio  file.  Option  syntax is -i:sndfile,foo-
	      bar.ext[,.format-ext] (same for -o).  The	optional third parame-
	      ter "format" can be used to override the audio format (for exam-
	      ple 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 al-
	      lows 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"  ob-
	      jects, 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	chain-
	      setup.   For   example,	ecasound   -f:16,2,44100   -i	resam-
	      ple,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	resam-
	      ple,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	 algo-
	      rithm  available.	 To  force ecasound to use the internal	resam-
	      pler, '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  ob-
	      jects  is	 not  supported.  Note!	Trying to reverse audio	object
	      types with really	slow seek  operation  (like  mp3),  works  ex-
	      tremely 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 fre-
	      quency 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 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	opera-
	      tions 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 nor-
	      mal 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	 real-
	      time messages) .to the selected MIDI-device. Notice that as Eca-
	      sound will not send MIDI-clock, but only the start and stop mes-



       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.


       -ev    Analyzes sample data to find out how much	the signal can be  am-
	      plified  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 sam-
	      ple values, is printed out at the	end of processing.

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

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


	      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  'am-
	      plify%/100'). See	also '-eadb'.

	      Amplifies	signal of channel 'channel' by amplify-% percent (lin-
	      ear  scale,  i.e.	 individual  samples  are  multiplied  by 'am-
	      plify%/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.	 indi-
	      vidual  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 domi-
	      nant release time	controls, but the actual release time  is  de-
	      pendent  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 in-
	      finity 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 pro-
	      cessed separately). When signal amplitude	falls  below  'thresh-
	      old_level_%' percent (100% means maximum amplitude), gate	is ac-
	      tivated. 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).


       -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	multi-
	      plier (1.0 is the	normal level). With high resonance  values  it
	      often is useful to reduce	the gain value.

       -ef4:cutoff, resonance
	      Resonant	lowpass	filter (3rd-order, 36dB, original algorithm by
	      Stefan M.	Fendt).	Simulates an analog active RC-lowpass  design.
	      Cutoff  is  a  value  between  [0,1], while resonance is between

	      Allpass filter. Passes all frequencies with no change in	ampli-
	      tude.   However,	at the same time it imposes a frequency-depen-
	      dent 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 be-
	      tween  [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 spec-
	      ified in Hz. Basicly just	another	resonating bandpass filter.


       -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 au-
	      dio stream has total of 'N' channels. Each  parameter  specifies
	      the  source channel to use for given output channel. As an exam-
	      ple, '-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_chan-
	      nel'  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.



	      Delay  effect.  'delay  time' is the delay time in milliseconds.
	      'surround-mode' is a integer with	following meanings: 0  =  nor-
	      mal,  1 =	surround, 2 = stereo-spread. 'number_of_delays'	should
	      be obvious. Beware that large number of delays  and  huge	 delay
	      times need a lot of CPU power. 'mix-%' expresses the mix balance
	      between the original and delayed signal, with 0 meaning  no  de-
	      layed  signal,  100  meaning no original signal, and 50 (the de-
	      fault) achieving an equal	balance.  '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 ver-
	      sion (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). Parameters 1..N are set  as  values  of  the
	      plugin's control ports.

	      If plugin	has more than one audio	input and/or output port, only
	      one plugin is instance is	created, and the  chain	 channels  are
	      fed to the same plugin instance. If plugin has at	most one input
	      and at most one output audio port, a separate plugin instance is
	      created  for  each  channel  of  the  ecasound chain (e.g. for a
	      stereo audio channel, two	LADSPA plugins of same type  are  cre-
	      ated, with one per channel).

	      Plugins  are  located  in	 shared	 library (.so) files. Ecasound
	      looks  for  plugins  in  @prefix@/lib/ladspa   (e.g.   "/usr/lo-
	      cal/lib/ladspa"),	 directories  listed  in  environment variable
	      LADSPA_PATH. Plugin search path can be configured	also via  eca-
	      soundrc, see ecasoundrc(5) man page. One shared library file can
	      contain multiple plugin objects, but every plugin	has  a	unique
	      plugin name. This	name is	used for selecting plugins.

	      See  LAD mailing list web	site for more info about LADSPA. Other
	      useful sites are LADSPA home page	and LADSPA documentation.

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

	      LV2 PLUGINS

	      Ecasound also supports LV2 audio plugins.	LV2 plugins are	 iden-
	      tified by	a globally unique, case-sensitive identifier.

	      If plugin	has more than one audio	input and/or output port, only
	      one plugin is instance is	created, and the  chain	 channels  are
	      fed to the same plugin instance. If plugin has at	most one input
	      and at most one output audio port, a separate plugin instance is
	      created  for  each  channel  of  the  ecasound chain (e.g. for a
	      stereo audio channel, two	LV2 plugins of same type are  created,
	      with one per channel).

	      LV2 is a plugin standard for audio systems.


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

	      Threshold	gate. Initially	gate is	closed.	It is opened when vol-
	      ume  goes	over 'othreshold' percent. After this, if volume drops
	      below 'cthold' percent, gate  is	closed	and  won't  be	opened
	      again,  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 buf-
	      fers 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 're-
	      open-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 re-
	      liable settings for your equipment.

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


	      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.
	      'first-value' and	'last-value' are used as border	values (values
	      for  position  0.0/first and position 1.0/last).	All 'posN' and
	      'valueN' must be between 0.0 and 1.0. Also, for all 'posN'  val-
	      ues 'pos1	< pos2 < ... < posN' must be true.

	      Generic  oscillator. 'genosc_number' is the number of the	oscil-
	      lator 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).

	      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 en-
	      velope 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' pa-
	      rameters 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 seg-
	      ment '[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	recom-
	      mended 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

	      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 con-
	      trol 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  ECA-
	      SOUND environment	as the default path to ecasound	executable.

	      Output  all  debugging  messages	to a separate log file.	If de-
	      fined, 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 ECA-
	      SOUND_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.

       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.

	      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	initi-
       ated.  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 nor-
       mal cleanup procedure, and terminate immediately. Any remaining cleanup
       tasks  will  be skipped.	 Depending on the runtime state	and configura-
       tion, 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 documenta-

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

				  05.05.2011			   ecasound(1)


Want to link to this manual page? Use this URL:

home | help