#use wml::tmpl::main title="ecasound.el -- An interface to Ecasound for GNU Emacs" PAGE=programming SUBPAGE=ecasound-el

<P>
<A href="http://www.wakkanet.fi/~kaiv/ecasound/welcome.html">Ecasound</A> 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 <foldoc MIDI>-CCs.  Ecasound comes with many built-in effects,
but does also include the ability to load and use <A href="http://www.ladspa.org/">LADSPA</A>
effect plugins.

<P>
One of the powerful features of Ecasound is the Ecasound Control Interface,
ECI for short.
It allows for easy remote control of Ecasound either via NetECI, or in
general, allows for easy <foldoc parsing> of Ecasound return values if in ECI
mode.
This opened the road for an in my humble opinion fairly good and robust Emacs
support for ecasound.</p>
<P>
<A href="ecasound.el">ecasound.el</A> provides a new major mode for
interacting with ecasound processes, derived from the commonly known
comint-mode.
Additionally, <A href="ecasound.el">ecasound.el</A> also provides Lisp bindings
to ECI.  This basically means that after initialising a ECI handler, you can
call ECI functions from Emacs Lisp and work with the return values of
ecasound as if they were normal Lisp values.</p>

<H2>News</H2>
<dl>
<dt>Released ecasound.el 0.8.3:
<dd>
<ul>
<li>ecasound-cli-arg:value-to-internal: Use `widget-get' instead of
(car (last elt)) to extract :value from :args which makes code compatible
to XEmacs.
<li>ecasound-cli-arg:value-to-external: Use `widget-get' instead of
`widget-apply' to fetch :arg-format.  Makes XEmacs happy.
<li>Add "-D" to the default `ecasound-arguments'.  This fixes a problem
with the TERM variable which only appeared in XEmacs and is a reasonable
default anyway.
<li>Fix `ecasound-output-filter' when "-D" is used as argument on startup.
<li>Add `comint-strip-ctrl-m' to `comint-output-filter-functions' when
we are running XEmacs.
<li>`defeci' cs-set-position.  Bound to "M-c M-s s" and in
`ecasound-iam-cs-menu'.
<li>Add some more docstrings.
<li>New interactive functions `ecasound-set-mark' and `ecasound-goto-mark'
which implement the position marker system discussed on ecasound-list.
Bound to C-c C-SPC and C-c C-j respectively.
<li>New user variable `ecasound-daemon-host' which defaults to "localhost".
<li>Record the daemon port in a buffer local variable `ecasound-daemon-port'
and therefore allow temporarily binding `ecasound-arguments' to something
different via e.g. `let' before invoking `ecasound'.
<li>Fix regexp in `eci-input-filter' to be XEmacs compatible.
</ul>
</dl>
<H2>How to use ECI from Emacs Lisp?</h2>

<P>
Following is a small example of how to use the Ecasound Control Interface
from Emacs Lisp.  This function is included in the ecasound.el file itself,
and is reproduced here since it is a small and self contained example:
<pre>
(defun ecasound-normalize (filename)
  "Normalize an audio file using ECI."
  (interactive "fFile to normalize: ")
  (let ((tmpfile (eci-make-temp-file-name ".wav")))
    (unwind-protect
        (with-current-buffer (eci-init)
          (eci-cs-add "analyze") (eci-c-add "1")
          (eci-ai-add filename) (eci-ao-add tmpfile)
          (eci-cop-add "-ev")
          (message "Analyzing sample data...")
          (eci-cs-connect) (eci-run)
          (eci-cop-select 1) (eci-copp-select 2)
          (let ((gainfactor (eci-copp-get)))
            (eci-cs-disconnect)
            (if (<= gainfactor 1)
                (message "File already normalized!")
              (eci-cs-add "apply") (eci-c-add "1")
              (eci-ai-add tmpfile) (eci-ao-add filename)
              (eci-cop-add "-ea:100")
              (eci-cop-set 1 1 (* gainfactor 100))
              (eci-cs-connect)
              (eci-run)
              (eci-cs-disconnect)
              (message "Done"))))
      (if (file-exists-p tmpfile)
          (delete-file tmpfile)))))
</pre>

<p>An additional example might be the function ecasound-signalview, also included with ecasound.el.</p>