Google

Ecasound Control Interface documentation

Kai Vehmanen

09072001

Table of Contents

1: Introduction

2: General

2.1: What's it good for?

2.2: Services and behaviour

2.2.1: Actions
2.2.2: Return values
2.2.3: Errors
2.2.4: Other

2.3: Porting to new environments

3: Implementations

3.1: General

3.1.1: Overview
3.1.2: Usage
3.1.3: Example

3.2: C++

3.2.1: Overview
3.2.2: Usage
3.2.3: Example

3.3: C

3.3.1: Overview
3.3.2: Usage
3.3.3: Example

3.4: Python

3.4.1: Overview
3.4.2: Usage
3.4.3: Example

3.5: Perl

3.5.1: Overview
3.5.2: Usage
3.5.3: Example


1: Introduction

Idea behind the Ecasound Control Interface (ECI) is to take a subset of functionality provided by libecasound, write a simple API for it, and port it to various languages. At the moment, at least C++, C and Python implementations of the ECI API are available and part of the main ecasound distribution. ECI is heavily based on ecasound's interactive mode (EIAM), and the services it provides. See ecasound-iam(1) manual page for detailed EIAM documentation.

2: General

ECI doesn't provide any routines that directly manipulate audio or ecasound objects. What is does provide is an easy and generic way to issue EIAM (ecasound interactive mode) commands, access to the command return-values and error handling.

This approach has two benefits. First, it's possible to keep the API small, and thus make it easier to port ECI to new languages. Secondly, it'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't need the latest new features. In these cases, ECI is the best choice.

2.1: What's it good for?

Specific tasks ECI is aimed at:

  • 1. automating (scripting in its traditional sense)
  • 2. frontends (generic / specialized)
  • 3. sound services to other apps

    • 2.2: Services and behaviour

    Here's a list of services provided by all ECI implementations:

    2.2.1: Actions

    command(string)
    Issue an EIAM command.

    command_float_arg(string, float)
    Issue an EIAM command. This function can be used instead of command(string), if the command in question requires exactly one numerical parameter. This way it's possible to avoid the extra string -> float conversion, which would lead to lost precision.

    2.2.2: Return values

    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. Not all EIAM commands return a value (return type is void).

    last_string()
    Returns the last string return value.

    last_string_list()
    Returns the last collection of strings (one or more strings).

    last_float()
    Returns the last floating-point return value. Note! last_float() doesn't refer to the C/C++ type 'float'. In most implementations, floats are 64bit values (doubles in C/C++).

    last_integer()
    Returns the last integer return value. This function is also used to return boolean values, where non-zero means 'true' and zero 'false'.

    last_long_integer()
    Returns the last long integer return value. Long integers are used to pass values like 'length_in_samples' and 'length_in_bytes'. It's implementation specific whether there's any real difference between integers and long integers.

    2.2.3: Errors

    error()
    Returns true (!= 0) if error has occured during the execution of last EIAM command. Otherwise returns false (= 0).

    last_error()
    Returns a string describing the last error. If the last EIAM command was executed succesfully, last_error() returns an empty string.

    2.2.4: Other

    initialize()
    Reserve resources.

    cleanup()
    Free all reserved resources.

    2.3: Porting to new environments

    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's to easist to use the C++ or C ECI as the underlying implementation.

    3: Implementations

    3.1: General

    3.1.1: Overview

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

    3.1.2: Usage

    A quick tutorial to get you started.

    3.1.3: Example

    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.

    3.2: C++

    3.2.1: Overview

    C++ implementation is based around the ECA_CONTROL_INTERFACE class. STL vector is used for representing collections of objects (last_string_list()).

    3.2.2: Usage

    1. #include <ecasound/eca-control-interface.h>
    2. create an instance of the ECA_CONTROL_INTERFACE class and use its member functions
    3. link you app agains libecasound (-lecasound)

    3.2.3: Example

    
#include <iostream>
#include <unistd.h>
#include <ecasound/eca-control-interface.h>

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("-i:some_file.wav");
  e.command("-o:/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 > 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 << "Chain operator status: " << e.last_string() << endl;

  return(0);
}

    3.3: C

    3.3.1: Overview

    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'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's own buffers.

    Returning a list of strings is implemented using two functions: eci_last_string_list_count() returns the number of strings available, and eci_last_string_list_item(int n) returns a pointer (const char*) to the string at index n.

    Note! As of ecasound 2.0.1, the C ECI implementation also provides reentrant access to the ECI API. These alternative routines are marked with '_r' postfix.

    3.3.2: Usage

    1. #include <ecasound/ecasoundc.h>
    2. use the eci_* routines
    3. link your app against libecasoundc (-lecasoundc)

    3.3.3: Example

    
#include <stdio.h>
#include <unistd.h>
#include <ecasound/ecasoundc.h>

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("-i:some_file.wav");
  eci_command("-o:/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 > 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);
}

    3.4: Python

    3.4.1: Overview

    Python implementation is based around the ECA_CONTROL_INTERFACE class. Lists are used for representing collections of objects.

    Note! Eric S. Tiedemann has written an alternative Python interface to ECI. You'll find this interface included in the main ecasound packege, in pyecasound/esteci.py. To use this instead of the standard interface, just 'import eci' and you're set! :)

    3.4.2: Usage

    1. import pyeca
    2. create an instance of the ECA_CONTROL_INTERFACE class and use its member functions
    3. python 'yourapp.py' and that's it :)

    3.4.3: Example

    
#!/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("-i:some_file.wav")
e.command("-o:/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 > 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()

    3.5: Perl

    3.5.1: Overview

    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't have to turn you back on the adoring masses packed into Wembly Stadium.

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

    3.5.2: Usage

    See the below example. For more info, here's another CPAN link.

    3.5.3: Example

    use Audio::Ecasound qw(:simple); 

    
eci("cs-add play_chainsetup");
eci("c-add 1st_chain");
eci("-i:some_file.wav");
eci("-o:/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 > 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");