Ecasound C API Chainsetup Compilation

This article explains how to initiate chainsetup compilation using the Ecasound C API, focusing on the core functions and commands that drive audio graph preparation. Readers will learn the precise C function required, the specific control command that triggers the compilation process, how the engine handles audio chain verification, and the basic implementation workflow in C code.

In the Ecasound C API (libecasoundc), chainsetup compilation is initiated using the eci_command() function with the "cs-connect" command argument. The Ecasound Control Interface (ECI) operates through a command-driven architecture, meaning that higher-level engine procedures—such as parsing, verifying, and compiling audio chains—are invoked by passing textual instructions directly to eci_command().

#include <libecasoundc/ecasoundc.h>

int main(void) {
    eci_init();

    // Create and configure a chainsetup
    eci_command("cs-add my_setup");
    eci_command("c-add chain1");
    eci_command("ai-add input.wav");
    eci_command("ao-add alsa");

    // Initiate compilation of the chainsetup
    eci_command("cs-connect");

    // Check for errors
    if (eci_last_error()) {
        /* Handle compilation or connection failure */
    }

    eci_cleanup();
    return 0;
}

When eci_command("cs-connect") is executed, Ecasound transitions the active chainsetup from the configuration state to the connected state. During this compilation phase, Ecasound performs several critical operations:

  1. Format Negotiation: It analyzes the sampling rates, channel counts, and bit depths of all configured audio inputs, audio outputs, and intermediate chains.
  2. Converter Allocation: If format mismatches exist between inputs and outputs, Ecasound automatically inserts buffering, resampling, or format conversion routines where applicable.
  3. Graph Validation: The engine verifies that every chain contains valid signal routing paths and that no circular dependencies or unassigned endpoints exist.
  4. Device Initialization: Underlying audio drivers (such as ALSA, JACK, or OSS) and disk files are opened, checked for accessibility, and pre-allocated memory buffers.

If any aspect of the audio graph is invalid or a target audio device cannot be initialized, the compilation fails. In the C API, you detect compilation errors immediately following eci_command("cs-connect") by evaluating eci_last_error(), which returns a non-zero string pointer detailing the failure reason. Once compilation successfully finishes without errors, the chainsetup is considered connected and ready for real-time transport controls, such as eci_command("start").