Ecasound Control Interface Asynchronous Errors

This article provides an overview of how the Ecasound Control Interface (ECI) manages asynchronous error notifications during background audio processing. It explains the mechanics of decoupled engine operations, detailing how unexpected runtime failures—such as buffer underflows, broken pipes, and hardware disconnections—are flagged to client applications. You will learn how to detect these background exceptions through state polling, return code inspections, and error buffer queries.

Synchronous Commands vs. Asynchronous Engine Execution

The Ecasound Control Interface is primarily designed as a synchronous, request-response control protocol. When a client application configures inputs, outputs, or effects chains, each command executes sequentially, returning immediate success or failure strings.

However, once the processing engine is initiated via the start command, audio streaming runs independently in a real-time background thread or separate process. Errors that occur during this active execution phase cannot be returned as immediate function return values, requiring a decoupled mechanism to notify the controlling application.

State Transitions as Error Indicators

ECI handles background runtime errors primarily through internal state shifts. The engine continuously updates its internal execution status. When a critical failure occurs—such as an I/O device failure or an unrecoverable buffer underrun—the engine terminates processing and alters its status from running to error or stopped.

Controlling applications monitor for asynchronous failures by regularly polling the engine status using the engine-status command. If the engine unexpectedly transitions out of the running state without an explicit stop command issued by the client, an asynchronous failure is inferred.

The Error Buffer and Notification Retrieval

When the background engine encounters a fatal or non-fatal anomaly, Ecasound writes the diagnostic details to an internal message buffer. Because ECI does not employ interrupt-style callbacks in standard implementations, retrieval of the error message follows a polling or post-event model:

  1. State Evaluation: The client detects an abnormal state transition via engine-status or checks the general error flag using eci_error_reported().
  2. Reading the Diagnostic: Once an error condition is flagged, the application queries the last_error() routine (or eci_last_error() in the C API).
  3. Log Stream Parsing: Non-fatal asynchronous issues (such as transient xruns or dropped samples) are directed to the standard error stream or the Ecasound debug log system rather than raising a hard fatal state. Applications requiring granular tracking must parse Ecasound's message log output levels.

Asynchronous Handling in NetECI

In distributed or decoupled architectures utilizing NetECI (the socket-based implementation of ECI), asynchronous notifications rely on the underlying TCP/socket communication channel. While typical commands follow the synchronous request-response flow, unexpected engine termination breaks the active session or emits error responses to subsequent polling queries. Modern asynchronous wrappers around NetECI achieve real-time monitoring by dedicating a lightweight worker thread to continuously ping the engine state and immediately propagate exceptions to the main application thread.