/usr/share/doc/ecasound/eci

<!DOCTYPE html>
<html >
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<meta name="generator" content="hevea 2.28">
<style type="text/css">
.li-itemize{margin:1ex 0ex;}
.li-enumerate{margin:1ex 0ex;}
.dd-description{margin:0ex 0ex 1ex 4ex;}
.dt-description{margin:0ex;}
.toc{list-style:none;}
.footnotetext{margin:0ex; padding:0ex;}
div.footnotetext P{margin:0px; text-indent:1em;}
.thefootnotes{text-align:left;margin:0ex;}
.dt-thefootnotes{margin:0em;}
.dd-thefootnotes{margin:0em 0em 0em 2em;}
.footnoterule{margin:1em auto 1em 0px;width:50%;}
.caption{padding-left:2ex; padding-right:2ex; margin-left:auto; margin-right:auto}
.title{margin:2ex auto;text-align:center}
.titlemain{margin:1ex 2ex 2ex 1ex;}
.titlerest{margin:0ex 2ex;}
.center{text-align:center;margin-left:auto;margin-right:auto;}
.flushleft{text-align:left;margin-left:0ex;margin-right:auto;}
.flushright{text-align:right;margin-left:auto;margin-right:0ex;}
div table{margin-left:inherit;margin-right:inherit;margin-bottom:2px;margin-top:2px}
td table{margin:auto;}
table{border-collapse:collapse;}
td{padding:0;}
.cellpadding0 tr td{padding:0;}
.cellpadding1 tr td{padding:1px;}
pre{text-align:left;margin-left:0ex;margin-right:auto;}
blockquote{margin-left:4ex;margin-right:4ex;text-align:left;}
td p{margin:0px;}
.boxed{border:1px solid black}
.textboxed{border:1px solid black}
.vbar{border:none;width:2px;background-color:black;}
.hbar{border:none;height:2px;width:100%;background-color:black;}
.hfill{border:none;height:1px;width:200%;background-color:black;}
.vdisplay{border-collapse:separate;border-spacing:2px;width:auto; empty-cells:show; border:2px solid red;}
.vdcell{white-space:nowrap;padding:0px; border:2px solid green;}
.display{border-collapse:separate;border-spacing:2px;width:auto; border:none;}
.dcell{white-space:nowrap;padding:0px; border:none;}
.dcenter{margin:0ex auto;}
.vdcenter{border:solid #FF8000 2px; margin:0ex auto;}
.minipage{text-align:left; margin-left:0em; margin-right:auto;}
.marginpar{border:solid thin black; width:20%; text-align:left;}
.marginparleft{float:left; margin-left:0ex; margin-right:1ex;}
.marginparright{float:right; margin-left:1ex; margin-right:0ex;}
.theorem{text-align:left;margin:1ex auto 1ex 0ex;}
.part{margin:2ex auto;text-align:center}
</style>
<title>Ecasound Control Interface Guide
</title>
</head>
<body >
<!--HEVEA command line is: /usr/bin/hevea -o html_ecidoc/eci_doc.html ./eci_doc.latex -->
<!--CUT STYLE article--><!--CUT DEF section 1 --><table class="title"><tr><td style="padding:1ex"><h1 class="titlemain">Ecasound Control Interface Guide</h1><h3 class="titlerest">Kai Vehmanen, Brad Bowman, Tony Leake, Jan Weil, Mario Lang</h3><h3 class="titlerest">03062006</h3></td></tr>
</table><!--TOC section id="sec1" Contents-->
<h2 id="sec1" class="section">Contents</h2><!--SEC END --><ul class="toc"><li class="li-toc">
<a href="#sec2">1&#XA0;&#XA0;Introduction</a>
</li><li class="li-toc"><a href="#sec3">2&#XA0;&#XA0;Document history</a>
</li><li class="li-toc"><a href="#sec4">3&#XA0;&#XA0;General</a>
<ul class="toc"><li class="li-toc">
<a href="#sec5">3.1&#XA0;&#XA0;What&#X2019;s it good for?</a>
</li><li class="li-toc"><a href="#sec6">3.2&#XA0;&#XA0;Services and behaviour</a>
<ul class="toc"><li class="li-toc">
<a href="#sec7">3.2.1&#XA0;&#XA0;Actions</a>
</li><li class="li-toc"><a href="#sec8">3.2.2&#XA0;&#XA0;Return values</a>
</li><li class="li-toc"><a href="#sec9">3.2.3&#XA0;&#XA0;Errors</a>
</li><li class="li-toc"><a href="#sec10">3.2.4&#XA0;&#XA0;Other</a>
</li></ul>
</li><li class="li-toc"><a href="#sec11">3.3&#XA0;&#XA0;Porting to new environments</a>
</li></ul>
</li><li class="li-toc"><a href="#sec12">4&#XA0;&#XA0;Implementations</a>
<ul class="toc"><li class="li-toc">
<a href="#sec13">4.1&#XA0;&#XA0;General</a>
<ul class="toc"><li class="li-toc">
<a href="#sec14">4.1.1&#XA0;&#XA0;Overview</a>
</li><li class="li-toc"><a href="#sec15">4.1.2&#XA0;&#XA0;Usage</a>
</li><li class="li-toc"><a href="#sec16">4.1.3&#XA0;&#XA0;Example</a>
</li></ul>
</li><li class="li-toc"><a href="#sec17">4.2&#XA0;&#XA0;Notes Concerning Standalone ECI Implementations</a>
</li><li class="li-toc"><a href="#sec18">4.3&#XA0;&#XA0;C++</a>
<ul class="toc"><li class="li-toc">
<a href="#sec19">4.3.1&#XA0;&#XA0;Overview</a>
</li><li class="li-toc"><a href="#sec20">4.3.2&#XA0;&#XA0;Usage</a>
</li><li class="li-toc"><a href="#sec21">4.3.3&#XA0;&#XA0;Example</a>
</li></ul>
</li><li class="li-toc"><a href="#sec22">4.4&#XA0;&#XA0;C</a>
<ul class="toc"><li class="li-toc">
<a href="#sec23">4.4.1&#XA0;&#XA0;Overview</a>
</li><li class="li-toc"><a href="#sec24">4.4.2&#XA0;&#XA0;Usage</a>
</li><li class="li-toc"><a href="#sec25">4.4.3&#XA0;&#XA0;Example</a>
</li></ul>
</li><li class="li-toc"><a href="#sec26">4.5&#XA0;&#XA0;Emacs</a>
<ul class="toc"><li class="li-toc">
<a href="#sec27">4.5.1&#XA0;&#XA0;Overview</a>
</li><li class="li-toc"><a href="#sec28">4.5.2&#XA0;&#XA0;Usage</a>
</li><li class="li-toc"><a href="#sec29">4.5.3&#XA0;&#XA0;Example</a>
</li></ul>
</li><li class="li-toc"><a href="#sec30">4.6&#XA0;&#XA0;Python</a>
<ul class="toc"><li class="li-toc">
<a href="#sec31">4.6.1&#XA0;&#XA0;Overview</a>
</li><li class="li-toc"><a href="#sec32">4.6.2&#XA0;&#XA0;Usage</a>
</li><li class="li-toc"><a href="#sec33">4.6.3&#XA0;&#XA0;Example</a>
</li></ul>
</li><li class="li-toc"><a href="#sec34">4.7&#XA0;&#XA0;Perl</a>
<ul class="toc"><li class="li-toc">
<a href="#sec35">4.7.1&#XA0;&#XA0;Overview</a>
</li><li class="li-toc"><a href="#sec36">4.7.2&#XA0;&#XA0;Usage</a>
</li><li class="li-toc"><a href="#sec37">4.7.3&#XA0;&#XA0;Example</a>
</li></ul>
</li><li class="li-toc"><a href="#sec38">4.8&#XA0;&#XA0;PHP</a>
<ul class="toc"><li class="li-toc">
<a href="#sec39">4.8.1&#XA0;&#XA0;Overview</a>
</li><li class="li-toc"><a href="#sec40">4.8.2&#XA0;&#XA0;Usage</a>
</li><li class="li-toc"><a href="#sec41">4.8.3&#XA0;&#XA0;Example</a>
</li></ul>
</li><li class="li-toc"><a href="#sec42">4.9&#XA0;&#XA0;Ruby</a>
<ul class="toc"><li class="li-toc">
<a href="#sec43">4.9.1&#XA0;&#XA0;Overview</a>
</li><li class="li-toc"><a href="#sec44">4.9.2&#XA0;&#XA0;Usage</a>
</li><li class="li-toc"><a href="#sec45">4.9.3&#XA0;&#XA0;Example</a>
</li></ul>
</li></ul>
</li><li class="li-toc"><a href="#sec46">5&#XA0;&#XA0;Application development</a>
<ul class="toc"><li class="li-toc">
<a href="#sec47">5.1&#XA0;&#XA0;Tips for debugging</a>
</li></ul>
</li></ul>
<!--TOC section id="sec2" Introduction-->
<h2 id="sec2" class="section">1&#XA0;&#XA0;Introduction</h2><!--SEC END --><p>
The idea behind the Ecasound Control Interface (ECI) is to take a subset of 
functionality provided by libecasound, provide a simple API for it, and
port it to various languages. At the moment, implementations of the
ECI API are available for C, C++, elisp, Python and Ruby. These all
come by default with the Ecasound package. Additional implementations,
for example for Perl and PHP, are distributed independently. </p><p>ECI is heavily based on Ecasound&#X2019;s interactive mode (EIAM), and the 
services it provides. See <span style="font-family:monospace">ecasound-iam(1) manual page</span> for 
a detailed EIAM documentation.</p>
<!--TOC section id="sec3" Document history-->
<h2 id="sec3" class="section">2&#XA0;&#XA0;Document history</h2><!--SEC END --><ul class="itemize"><li class="li-itemize">
04.06.2006 - Added more information to the &#X201C;Tips for debugging&#X201D; section.
</li><li class="li-itemize">21.03.2005 - Updated the &#X201C;Tips for debugging&#X201D; section.
</li><li class="li-itemize">25.09.2004 - Updated the &#X201C;Return values&#X201D; section based on feedback
from Adam Linson.
</li><li class="li-itemize">02.05.2004 - &#X201C;Emacs&#X201D; section added (written by Mario Lang).
</li><li class="li-itemize">28.11.2003 - &#X201C;Ruby&#X201D; section added (written by Jan Weil).
Updated the introduction.
</li><li class="li-itemize">26.11.2003 - Fix filename for the alternative Python API (eci.py).
</li><li class="li-itemize">18.11.2003 - Typo fixes. Updated documentation to reflect the new
naming convention (ecasound refers to the binary,
		 Ecasound refers to the whole package).
</li><li class="li-itemize">26.10.2002 - Changed the C++ linking example.
</li><li class="li-itemize">24.10.2002 - Added &#X201C;Notes Concerning Standalone ECI Implementations&#X201D;
section. Added compilation examples.
</li><li class="li-itemize">06.10.2002 - Added &#X201C;Application development&#X201D; section.
</li><li class="li-itemize">05.10.2002 - Changed the libecasoundc link path.
</li><li class="li-itemize">29.09.2002 - &#X201C;PHP&#X201D; section added (written by Tony Leake).
</li><li class="li-itemize">25.04.2002 - Changed headers path from &#X201C;&lt;ecasoundc/file.h&gt;&#X201D; to 
&#X201C;&lt;file.h&gt;&#X201D; and added library version number to 
link instructions.
</li><li class="li-itemize">21.10.2001 - Added this history section. Minor changes to 
ECI examples.
</li></ul>
<!--TOC section id="sec4" General-->
<h2 id="sec4" class="section">3&#XA0;&#XA0;General</h2><!--SEC END --><p>
ECI doesn&#X2019;t provide any routines that directly manipulate audio or 
Ecasound objects. What it does provide is an easy and generic way
to issue EIAM (Ecasound Inter-Active Mode) commands, access the
command return-values and perform error handling.</p><p>This approach has two benefits. First, it is possible to keep the API 
small, and thus make it easier to port ECI to new languages. Secondly,
it&#X2019;s possible to keep ECI relatively stable. Ecasound itself is a large,
developing library. New features are added all the time, and from time
to time, older parts of the library will get rewritten to better suit
new uses. Now for application developers wanting to take advantage of
libecasound, these constant changes are very annoying, especially if
your specific app doesn&#X2019;t need the latest new features. In these
cases, ECI is the best platform for application development.</p>
<!--TOC subsection id="sec5" What&#X2019;s it good for?-->
<h3 id="sec5" class="subsection">3.1&#XA0;&#XA0;What&#X2019;s it good for?</h3><!--SEC END --><p>Specific tasks ECI is aimed at:</p><ul class="itemize"><li class="li-itemize">
1. automating (scripting in its traditional sense)
</li><li class="li-itemize">2. frontends (generic / specialized)
</li><li class="li-itemize">3. sound services to other apps
</li></ul>
<!--TOC subsection id="sec6" Services and behaviour-->
<h3 id="sec6" class="subsection">3.2&#XA0;&#XA0;Services and behaviour</h3><!--SEC END --><p>Here is a list of services provided by all ECI implementations:</p>
<!--TOC subsubsection id="sec7" Actions-->
<h4 id="sec7" class="subsubsection">3.2.1&#XA0;&#XA0;Actions</h4><!--SEC END --><dl class="description"><dt class="dt-description">
<span style="font-weight:bold">command(string)</span></dt><dd class="dd-description"> 
Issue an EIAM command.</dd><dt class="dt-description"><span style="font-weight:bold">command_float_arg(string, float)</span></dt><dd class="dd-description">
Issue an EIAM command. This function can be used instead of
<em>command(string)</em>, if the command in question requires exactly one 
numerical parameter. This way it&#X2019;s possible to avoid the extra 
string -&gt; float conversion, which would lead to lost precision.
</dd></dl>
<!--TOC subsubsection id="sec8" Return values-->
<h4 id="sec8" class="subsubsection">3.2.2&#XA0;&#XA0;Return values</h4><!--SEC END --><p>
Each EIAM command has exactly one return value type. After a command
has been issued, only one last_type() functions returns a non-empty 
value. For example, last_float() only returns a valid value if 
<em>last_type() == &#X2019;f&#X2019;</em> holds true. Not all EIAM commands return 
a value (return type is void).</p><dl class="description"><dt class="dt-description">
<span style="font-weight:bold">last_string()</span></dt><dd class="dd-description">
Returns the last string return value.</dd><dt class="dt-description"><span style="font-weight:bold">last_string_list()</span></dt><dd class="dd-description">
Returns the last collection of strings (one or more strings).</dd><dt class="dt-description"><span style="font-weight:bold">last_float()</span></dt><dd class="dd-description">
Returns the last floating-point return value. Note! last_float()
doesn&#X2019;t refer to the C/C++ type &#X2019;float&#X2019;. In most implementations, 
floats are 64bit values (doubles in C/C++).</dd><dt class="dt-description"><span style="font-weight:bold">last_integer()</span></dt><dd class="dd-description">
Returns the last integer return value. This function is also 
used to return boolean values, where non-zero means &#X2019;true&#X2019; 
and zero &#X2019;false&#X2019;.</dd><dt class="dt-description"><span style="font-weight:bold">last_long_integer()</span></dt><dd class="dd-description">
Returns the last long integer return value. Long integers are 
used to pass values like &#X2019;length_in_samples&#X2019; and &#X2019;length_in_bytes&#X2019;.
It&#X2019;s implementation specific whether there&#X2019;s any real difference
between integers and long integers.
</dd></dl>
<!--TOC subsubsection id="sec9" Errors-->
<h4 id="sec9" class="subsubsection">3.2.3&#XA0;&#XA0;Errors</h4><!--SEC END --><dl class="description"><dt class="dt-description">
<span style="font-weight:bold">error()</span></dt><dd class="dd-description">
Returns true (!= 0) if error has occured during the execution 
of last EIAM command. Otherwise returns false (= 0).</dd><dt class="dt-description"><span style="font-weight:bold">last_error()</span></dt><dd class="dd-description">
Returns a string describing the last error. If the last EIAM command
was executed successfully, last_error() returns an empty string.</dd></dl>
<!--TOC subsubsection id="sec10" Other-->
<h4 id="sec10" class="subsubsection">3.2.4&#XA0;&#XA0;Other</h4><!--SEC END --><dl class="description"><dt class="dt-description">
<span style="font-weight:bold">initialize()</span></dt><dd class="dd-description">
Reserve resources.</dd><dt class="dt-description"><span style="font-weight:bold">cleanup()</span></dt><dd class="dd-description">
Free all reserved resources.
</dd></dl>
<!--TOC subsection id="sec11" Porting to new environments-->
<h3 id="sec11" class="subsection">3.3&#XA0;&#XA0;Porting to new environments</h3><!--SEC END --><p>
Porting ECI to new languages should be easy. All there is to do is 
to implement the services listed in the previous section to the target
language. In most cases it&#X2019;s to easiest to use the C++ or C ECI 
as the underlying implementation to build upon.</p>
<!--TOC section id="sec12" Implementations-->
<h2 id="sec12" class="section">4&#XA0;&#XA0;Implementations</h2><!--SEC END -->
<!--TOC subsection id="sec13" General-->
<h3 id="sec13" class="subsection">4.1&#XA0;&#XA0;General</h3><!--SEC END -->
<!--TOC subsubsection id="sec14" Overview-->
<h4 id="sec14" class="subsubsection">4.1.1&#XA0;&#XA0;Overview</h4><!--SEC END --><p>
This section contains overview of how ECI is implemented in the 
discussed language (eg. as a single class, set of classes, set of
routines, etc).</p>
<!--TOC subsubsection id="sec15" Usage-->
<h4 id="sec15" class="subsubsection">4.1.2&#XA0;&#XA0;Usage</h4><!--SEC END --><p>
A quick tutorial to get you started.</p>
<!--TOC subsubsection id="sec16" Example-->
<h4 id="sec16" class="subsubsection">4.1.3&#XA0;&#XA0;Example</h4><!--SEC END --><p>
Implementation of the following:
</p><ol class="enumerate" type=1><li class="li-enumerate">
Setup ECI to read audio from file, apply a 100Hz lowpass filter, and 
send it to the soundcard (/dev/dsp).
</li><li class="li-enumerate">Every second, check the current position. If the stream has
been running for over 15 seconds, exit immediately. Also,
every second, increase the lowpass filter&#X2019;s cutoff frequency
by 500Hz.
</li><li class="li-enumerate">Stop the stream (if not already finished) and disconnect the 
chainsetup. Print chain operator status info.
</li></ol>
<!--TOC subsection id="sec17" Notes Concerning Standalone ECI Implementations-->
<h3 id="sec17" class="subsection">4.2&#XA0;&#XA0;Notes Concerning Standalone ECI Implementations</h3><!--SEC END --><p>The C implementation of ECI is not directly linked against the main 
Ecasound libraries. Instead, the ecasound executable is launched
on the background and command pipes are used to communicate with it.</p><p>The launched ecasound executable can be selected by using the
<em>ECASOUND</em> environment variable. If it is not defined,
the C ECI implementation will try to launch &#X201C;ecasound&#X201D; (ie.
has to be somewhere in PATH). </p><p>In addition to the C implementation, this also affects all 
ECI implementations that are based on the C version. Currently
this includes at least the Perl, PHP and Python ECI modules.</p>
<!--TOC subsection id="sec18" C++-->
<h3 id="sec18" class="subsection">4.3&#XA0;&#XA0;C++</h3><!--SEC END -->
<!--TOC subsubsection id="sec19" Overview-->
<h4 id="sec19" class="subsubsection">4.3.1&#XA0;&#XA0;Overview</h4><!--SEC END --><p>
C++ implementation is based around the ECA_CONTROL_INTERFACE class.
STL vector is used for representing collections of objects
(last_string_list()).</p>
<!--TOC subsubsection id="sec20" Usage-->
<h4 id="sec20" class="subsubsection">4.3.2&#XA0;&#XA0;Usage</h4><!--SEC END --><ol class="enumerate" type=1><li class="li-enumerate"> 
#include &lt;eca-control-interface.h&gt;
</li><li class="li-enumerate">create an instance of the ECA_CONTROL_INTERFACE class
and use its member functions
</li><li class="li-enumerate">link you app agains libecasoundc (-lecasoundc)
</li><li class="li-enumerate">compilation example: <em>c++ -o ecidoc_example ecidoc_example.cpp &#X2018;libecasoundc-config &#X2013;cflags &#X2013;libs&#X2018;</em>
</li></ol>
<!--TOC subsubsection id="sec21" Example-->
<h4 id="sec21" class="subsubsection">4.3.3&#XA0;&#XA0;Example</h4><!--SEC END --><pre class="verbatim"> 

#include &lt;iostream&gt;
#include &lt;unistd.h&gt;
#include &lt;eca-control-interface.h&gt;

int main(int argc, char *argv[])
{
  double cutoff_inc = 500.0;

  ECA_CONTROL_INTERFACE e;
  e.command("cs-add play_chainsetup");
  e.command("c-add 1st_chain");
  e.command("ai-add some_file.wav");
  e.command("ao-add /dev/dsp");
  e.command("cop-add -efl:100");
  e.command("cop-select 1");
  e.command("copp-select 1");
  e.command("cs-connect");
  e.command("start");
  while(1) {
    sleep(1);
    e.command("engine-status");
    if (e.last_string() != "running") break;
    e.command("get-position");
    double curpos = e.last_float();
    if (curpos &gt; 15.0) break;
    e.command("copp-get");
    double next_cutoff = cutoff_inc + e.last_float();
    e.command_float_arg("copp-set", next_cutoff);
  }
  
  e.command("stop");
  e.command("cs-disconnect");
  e.command("cop-status");
  cerr &lt;&lt; "Chain operator status: " &lt;&lt; e.last_string() &lt;&lt; endl;

  return(0);
}
 
</pre>
<!--TOC subsection id="sec22" C-->
<h3 id="sec22" class="subsection">4.4&#XA0;&#XA0;C</h3><!--SEC END -->
<!--TOC subsubsection id="sec23" Overview-->
<h4 id="sec23" class="subsubsection">4.4.1&#XA0;&#XA0;Overview</h4><!--SEC END --><p>
All C ECI functions are prefixed with "eci_". When returning string
values, a const pointer to a null-terminated char array (const char*)
is returned. It&#X2019;s important to keep in mind that these are "borrowed"
references. If you need to later use the data, you must copy
it to application&#X2019;s own buffers.</p><p>Returning a list of strings is implemented using two functions: 
<em>eci_last_string_list_count()</em> returns the number of strings
available, and <em>eci_last_string_list_item(int n)</em> returns a 
pointer (const char*) to the string at index <em>n</em>.</p><p><em>Note!</em> As of Ecasound 2.0.1, the C ECI implementation also 
	 provides reentrant access to the ECI API. These
	 alternative routines are marked with &#X2019;_r&#X2019; postfix.</p>
<!--TOC subsubsection id="sec24" Usage-->
<h4 id="sec24" class="subsubsection">4.4.2&#XA0;&#XA0;Usage</h4><!--SEC END --><ol class="enumerate" type=1><li class="li-enumerate">
#include &lt;ecasoundc.h&gt;
</li><li class="li-enumerate">use the eci_* routines
</li><li class="li-enumerate">link your app against libecasoundc (-lecasoundc)
</li><li class="li-enumerate">compilation example: <em>gcc -o ecidoc_example ecidoc_example.c &#X2018;libecasoundc-config &#X2013;cflags &#X2013;libs&#X2018;</em>
</li></ol>
<!--TOC subsubsection id="sec25" Example-->
<h4 id="sec25" class="subsubsection">4.4.3&#XA0;&#XA0;Example</h4><!--SEC END --><pre class="verbatim"> 

#include &lt;stdio.h&gt;
#include &lt;unistd.h&gt;
#include &lt;ecasoundc.h&gt;

int main(int argc, char *argv[])
{
  double cutoff_inc = 500.0;

  eci_init();
  eci_command("cs-add play_chainsetup");
  eci_command("c-add 1st_chain");
  eci_command("ai-add some_file.wav");
  eci_command("ao-add /dev/dsp");
  eci_command("cop-add -efl:100");
  eci_command("cop-select 1");
  eci_command("copp-select 1");
  eci_command("cs-connect");
  eci_command("start");

  while(1) {
    double curpos, next_cutoff;

    sleep(1);
    eci_command("engine-status");
    if (strcmp(eci_last_string(), "running") != 0) break;
    eci_command("get-position");
    curpos = eci_last_float();
    if (curpos &gt; 15.0) break;
    eci_command("copp-get");
    next_cutoff = cutoff_inc + eci_last_float();
    eci_command_float_arg("copp-set", next_cutoff);
  }
  
  eci_command("stop");
  eci_command("cs-disconnect");
  eci_command("cop-status");
  printf("Chain operator status: %s", eci_last_string());
  eci_cleanup();

  return(0);
}
 
</pre>
<!--TOC subsection id="sec26" Emacs-->
<h3 id="sec26" class="subsection">4.5&#XA0;&#XA0;Emacs</h3><!--SEC END -->
<!--TOC subsubsection id="sec27" Overview-->
<h4 id="sec27" class="subsubsection">4.5.1&#XA0;&#XA0;Overview</h4><!--SEC END --><p>
The Ecasound package comes with an &#X2019;Ecasound&#X2019; library for Emacs included.
ecasound.el is a implementation of the ECI API for Emacs, as well
as an interactive interface to Ecasound sessions implemented
on top of that. Simply use "M-x ecasound RET" to fire up an
interactive Ecasound session.</p><p>All Emacs Lisp ECI functions are prefixed with &#X201C;eci&#X201D;.
&#X2019;ecasound.el&#X2019; is implemented in a high level manner which means
that you won&#X2019;t find most of the commands known from libecasoundc like
last_string, last_float, etc.
Instead of that every call to function "eci-command", which accepts all
the well known IAM commands, returns ecasound&#X2019;s response in an appropriate type
automatically.
If an error occurs, e. g. there&#X2019;s a typo in a command or a file is not found,
the function returns &#X201C;nil&#X201D;. In all other cases, either an automatically
converted Lisp value is returned, or &#X201C;t&#X201D; in the case where there was no
particular value returned.</p><p>Additionally, most of the available IAM commands have their own Emacs Lisp
function including documentation and possibly a parameter list. All these
functions are interactive, so you can use them in ecasound-iam-mode simply
by invoking them via M-x or by pressing an assigned key combination.
Emacs will prompt you for the required parameters, providing completion
wherever possible.</p><p>As a convention, "eci-command" and its variants do take a buffer or process
as an optional last argument. If this is &#X201C;nil&#X201D;, the current
buffer is assumed to be the ecasound session refered to by this call.
This makes it possible to use several ECI sessions concurrently, dispatching
on the buffer or process in use.</p>
<!--TOC subsubsection id="sec28" Usage-->
<h4 id="sec28" class="subsubsection">4.5.2&#XA0;&#XA0;Usage</h4><!--SEC END --><ol class="enumerate" type=1><li class="li-enumerate">
make ecasound.el available in your &#X201C;load-path&#X201D;
</li><li class="li-enumerate">(require &#X2019;ecasound)
</li><li class="li-enumerate">create a buffer with an associated Ecasound session (&#X201C;eci-init&#X201D;)
</li><li class="li-enumerate">use &#X201C;eci&#X201D; functions with the new buffer
</li></ol>
<!--TOC subsubsection id="sec29" Example-->
<h4 id="sec29" class="subsubsection">4.5.3&#XA0;&#XA0;Example</h4><!--SEC END --><pre class="verbatim"> 
(require 'ecasound)

(defun example (file &amp;optional cutoff-increment session)
  (unless cutoff-increment (setq cutoff-increment 500.0))
  (with-current-buffer (or session (eci-init))
    (eci-cs-add "play_chainsetup")
    (eci-c-add "1st_chain")
    (eci-ai-add file)
    (eci-ao-add "/dev/dsp")
    (eci-cop-add "-efl:100")
    (eci-cop-select 1)
    (eci-copp-select 1)
    (eci-cs-connect)
    (eci-start)
    (sit-for 1)
    (while (and (string= (eci-engine-status) "running")
                (&lt;= (eci-get-position) 15))
      (eci-copp-set (+ cutoff-increment (eci-copp-get)))
      (sit-for 1))
    (eci-command "stop")
    (when (eci-cs-disconnect)
      (destructuring-bind
   ((cop n1 (copp n2 val)))
   (cdr (assoc "1st_chain" (eci-cop-status)))
 (message "%s %s is now %f" cop copp val)))))
</pre><p>NOTE: function &#X201C;eci-cop-status&#X201D; is actually a very high level function
which already converts the returned information to a nested list
structure.</p><p>For more complex examples of the Emacs Lisp ECI implementation, see function
&#X201C;eci-example&#X201D;, &#X201C;ecasound-normalize&#X201D; and &#X201C;ecasound-signalview&#X201D; in
ecasound.el.</p>
<!--TOC subsection id="sec30" Python-->
<h3 id="sec30" class="subsection">4.6&#XA0;&#XA0;Python</h3><!--SEC END -->
<!--TOC subsubsection id="sec31" Overview-->
<h4 id="sec31" class="subsubsection">4.6.1&#XA0;&#XA0;Overview</h4><!--SEC END --><p>
Python implementation is based around the ECA_CONTROL_INTERFACE class.
Lists are used for representing collections of objects.</p><p>Note! Eric S. Tiedemann has written an alternative Python interface
to ECI. You&#X2019;ll find this interface included in the main 
Ecasound packege, in &#X201C;pyecasound/eci.py&#X201D;. To use this instead
of the standard interface, just &#X2019;import eci&#X2019; and you&#X2019;re set! :)</p>
<!--TOC subsubsection id="sec32" Usage-->
<h4 id="sec32" class="subsubsection">4.6.2&#XA0;&#XA0;Usage</h4><!--SEC END --><ol class="enumerate" type=1><li class="li-enumerate">
import pyeca
</li><li class="li-enumerate">create an instance of the ECA_CONTROL_INTERFACE class
and use its member functions
</li><li class="li-enumerate">python &#X2019;yourapp.py&#X2019; and that&#X2019;s it :) 
</li></ol>
<!--TOC subsubsection id="sec33" Example-->
<h4 id="sec33" class="subsubsection">4.6.3&#XA0;&#XA0;Example</h4><!--SEC END --><pre class="verbatim"> 

#!/usr/local/bin/python
import time
from pyeca import *
e = ECA_CONTROL_INTERFACE()
e.command("cs-add play_chainsetup")
e.command("c-add 1st_chain")
e.command("ai-add some_file.wav")
e.command("ao-add /dev/dsp")
e.command("cop-add -efl:100")
e.command("cop-select 1")
e.command("copp-select 1")
e.command("cs-connect")
e.command("start")
cutoff_inc = 500.0
while 1:
    time.sleep(1)
    e.command("engine-status")
    if e.last_string() != "running": break
    e.command("get-position")
    curpos = e.last_float()
    if curpos &gt; 15: break
    e.command("copp-get")
    next_cutoff = cutoff_inc + e.last_float()
    e.command_float_arg("copp-set", next_cutoff)
e.command("stop")
e.command("cs-disconnect")
e.command("cop-status")
print "Chain operator status: ", e.last_string()
 
</pre>
<!--TOC subsection id="sec34" Perl-->
<h3 id="sec34" class="subsection">4.7&#XA0;&#XA0;Perl</h3><!--SEC END -->
<!--TOC subsubsection id="sec35" Overview-->
<h4 id="sec35" class="subsubsection">4.7.1&#XA0;&#XA0;Overview</h4><!--SEC END --><p>
Audio::Ecasound provides perl bindings to the Ecasound
control interface of the Ecasound program. You can use
perl to automate or interact with Ecasound so you don&#X2019;t
have to turn you back on the adoring masses packed into
Wembly Stadium.</p><p>Audio::Ecasound was written by Brad Bowman. At the moment this module 
is not distributed with Ecasound. To get the latest version, check the 
following <span style="font-family:monospace">CPAN link</span>.</p>
<!--TOC subsubsection id="sec36" Usage-->
<h4 id="sec36" class="subsubsection">4.7.2&#XA0;&#XA0;Usage</h4><!--SEC END --><p>
See the below example. For more info, here&#X2019;s another 
<span style="font-family:monospace">CPAN link</span>.</p>
<!--TOC subsubsection id="sec37" Example-->
<h4 id="sec37" class="subsubsection">4.7.3&#XA0;&#XA0;Example</h4><!--SEC END --><p>
use Audio::Ecasound qw(:simple);</p><pre class="verbatim"> 

eci("cs-add play_chainsetup");
eci("c-add 1st_chain");
eci("ai-add some_file.wav");
eci("ao-add /dev/dsp");
# multiple \n separated commands
eci("cop-add -efl:100
     # with comments
     cop-select 1
     copp-select 1
     cs-connect");
eci("start");
my $cutoff_inc = 500.0;
while (1) {
    sleep(1);
    last if eci("engine-status") ne "running";
    my $curpos = eci("get-position");
    last if $curpos &gt; 15;
    my $next_cutoff = $cutoff_inc + eci("copp-get");
    # Optional float argument
    eci("copp-set", $next_cutoff);
}
eci("stop");
eci("cs-disconnect");
print "Chain operator status: ", eci("cop-status");
 
</pre>
<!--TOC subsection id="sec38" PHP-->
<h3 id="sec38" class="subsection">4.8&#XA0;&#XA0;PHP</h3><!--SEC END -->
<!--TOC subsubsection id="sec39" Overview-->
<h4 id="sec39" class="subsubsection">4.8.1&#XA0;&#XA0;Overview</h4><!--SEC END --><p>
This PHP extension provides bindings to the Ecasound
control interface. It is useful both for scripting Ecasound
and for writing graphical audio applications with PHP Gtk.</p><p>The PHP Ecasound extension was written by Tony Leake. At the moment this module 
is not distributed with Ecasound. The latest version and example scripts, are 
available from <span style="font-family:monospace">http://www.webwise-data.co.uk/php_audio/php_audio_extension.html</span>.</p>
<!--TOC subsubsection id="sec40" Usage-->
<h4 id="sec40" class="subsubsection">4.8.2&#XA0;&#XA0;Usage</h4><!--SEC END --><ol class="enumerate" type=1><li class="li-enumerate">
Obtain and build the Ecasound PHP extension
</li><li class="li-enumerate">Initialise Ecasound, eci_int();
</li><li class="li-enumerate">Issue EAM commands eg, eci_command("cs-add my_chain_setup");
</li><li class="li-enumerate">Free resources, eci_cleanup();
</li></ol>
<!--TOC subsubsection id="sec41" Example-->
<h4 id="sec41" class="subsubsection">4.8.3&#XA0;&#XA0;Example</h4><!--SEC END --><pre class="verbatim"> 

Implementation of the following:

1. Setup ECI to read audio from file, apply a 100Hz lowpass filter, 
and send it to the soundcard (/dev/dsp).
2. Every second, check the current position. If the stream has been 
running for over 15 seconds, exit immediately. Also, every second, 
increase the lowpass filter's cutoff frequency by 500Hz.
3. Stop the stream (if not already finished) and disconnect the chainsetup. 
Print chain operator status info

&lt;?php

$cutoff_inc = 500.0;
$curpos=0;
$next_cutoff=0;

eci_init();
eci_command("cs-add play_chainsetup");
eci_command("c-add 1st_chain");
eci_command("ai-add /tmp/somefile.wav");
eci_command("ao-add /dev/dsp");
eci_command("cop-add -efl:10");
eci_command("cop-select 1");
eci_command("copp-select 1");
eci_command("cs-connect");
eci_command("start");

while(1) {

    sleep(1);
    
    eci_command("engine-status");    
    if (eci_last_string() !="running"){
        break;
    }

    eci_command("get-position");
    $curpos = eci_last_float();
    if ($curpos &gt; 15.0){
        break;
    }

    eci_command("copp-get");
    $next_cutoff = $cutoff_inc + eci_last_float();
    eci_command_float_arg("copp-set",$next_cutoff);
}

eci_command("stop");
eci_command("cs-disconnect");
eci_command("cop-status");

printf("Chain operator status: %s", eci_last_string());

eci_cleanup();
?&gt;
</pre>
<!--TOC subsection id="sec42" Ruby-->
<h3 id="sec42" class="subsection">4.9&#XA0;&#XA0;Ruby</h3><!--SEC END -->
<!--TOC subsubsection id="sec43" Overview-->
<h4 id="sec43" class="subsubsection">4.9.1&#XA0;&#XA0;Overview</h4><!--SEC END --><p>
The Ecasound package comes with an &#X2019;Ecasound&#X2019; module for Ruby included.
If ruby is detected during the installation process it is installed
automatically (assuming you are installing ecasound from source code).
The module contains the class definition of a native ecasound control interface
called "ControlInterface".</p><p>&#X2019;Ecasound::ControlInterface&#X2019; is implemented in a high level manner which means
that you won&#X2019;t find most of the commands known from libecasoundc like
last_string, last_float, etc.
Instead of that every call to the instance method "command", which accepts all
the well known IAM commands, returns ecasound&#X2019;s response in an appropriate type
automatically.
If an error occurs, e. g. there&#X2019;s a typo in a command or a file is not found,
an exception of type EcasoundError is raised.</p>
<!--TOC subsubsection id="sec44" Usage-->
<h4 id="sec44" class="subsubsection">4.9.2&#XA0;&#XA0;Usage</h4><!--SEC END --><ol class="enumerate" type=1><li class="li-enumerate">
require &#X2019;ecasound&#X2019;
</li><li class="li-enumerate">create an instance of Ecasound::ControlInterface
</li><li class="li-enumerate">use it&#X2019;s command method to send IAM commands to ecasound
</li><li class="li-enumerate">catch an EcasoundError if necessary
</li></ol>
<!--TOC subsubsection id="sec45" Example-->
<h4 id="sec45" class="subsubsection">4.9.3&#XA0;&#XA0;Example</h4><!--SEC END --><pre class="verbatim"> 
#!/usr/bin/env ruby
require "ecasound"

SOME_FILE = "path/to/file.wav"

e = Ecasound::ControlInterface.new()
e.command("cs-add play_chainsetup")
e.command("c-add 1st_chain")
e.command("ai-add #{SOME_FILE}")
e.command("ao-add /dev/dsp")
e.command("cop-add -efl:100")
e.command("cop-select 1")
e.command("copp-select 1")
e.command("cs-connect")
e.command("start")

cutoff_inc = 500.0

loop do
    sleep(1)
    break if e.command("engine-status") != "running"
    break if e.command("get-position") &gt; 15
    e.command("copp-set #{cutoff_inc + e.command('copp-get')}")
end

e.command("stop")
e.command("cs-disconnect")

$stdout &lt;&lt; "Chain operator status: " + e.command("cop-status") + "\n"
</pre>
<!--TOC section id="sec46" Application development-->
<h2 id="sec46" class="section">5&#XA0;&#XA0;Application development</h2><!--SEC END -->
<!--TOC subsection id="sec47" Tips for debugging-->
<h3 id="sec47" class="subsection">5.1&#XA0;&#XA0;Tips for debugging</h3><!--SEC END --><p>Here&#X2019;s a few tips what to do if the ECI app you have developed
is not working correctly.</p><ol class="enumerate" type=1><li class="li-enumerate">
Check your Ecasound installation. Try to run the &#X201C;ecasound&#X201D; 
console user-interface and verify that the basic functionality
is working (ie. something like &#X201C;ecasound -i foo.wav -o
/dev/dsp&#X201D;.</li><li class="li-enumerate">If developing in C or C++, check that your application
is correcly linked: &#X201C;ldd /path/to/myapp&#X201D;. All the libraries
should be properly found.</li><li class="li-enumerate">Check error conditions. You should remember to check 
for errors in your ECI apps using the eci_error() and
eci_last_error() functions. Especially when intializing
ECI for the first time and after important commands
like &#X201C;cs-connect&#X201D;, you should always check for errors.</li><li class="li-enumerate">Use the ECASOUND_LOGFILE environment variable to write all
engine output to a separate logfile. See ecasound(1) manpage
for details on how to use this mechanism. Requires Ecasound 
version 2.4.5 or newer.</li><li class="li-enumerate">Utilize the &#X201C;int-log-history&#X201D; ECI command added to
version 2.4.0 of Ecasound. Recent messages from the
engine can help to track down the problem. Before use, you
need to first set the history length to a non-zero value with 
&#X201C;int-set-log-history-length&#X201D;.</li><li class="li-enumerate">Launch Ecasound in interactive mode (&#X201C;ecasound -c&#X201D;), 
and issue the commands your ECI application is using, 
manually one-by-one and see what happens. If something
goes wrong, increase Ecasound&#X2019;s debug level (for instance
&#X201C;-ddd&#X201D;) and re-run the test. </li></ol><!--CUT END -->
<!--HTMLFOOT-->
<!--ENDHTML-->
<!--FOOTER-->
<hr style="height:2"><blockquote class="quote"><em>This document was translated from L<sup>A</sup>T<sub>E</sub>X by
</em><a href="http://hevea.inria.fr/index.html"><em>H</em><em><span style="font-size:small"><sup>E</sup></span></em><em>V</em><em><span style="font-size:small"><sup>E</sup></span></em><em>A</em></a><em>.</em></blockquote></body>
</html>
ecasound-doc 2.9.1-7ubuntu2 / usr / share / doc / ecasound / eci_doc.html
