Ecasound ECI: Informational Messages vs Engine Errors

This article provides an overview of how the Ecasound Control Interface (ECI) differentiates between routine informational messages and fatal engine errors. It outlines the architecture ECI relies on to process internal events, covering error flags, message severity streams, engine state transitions, and the specific API calls used by controlling applications to intercept critical failures without mistaking them for benign notifications.

The primary mechanism the ECI uses to distinguish between informational messages and fatal errors is the separation of API return states from the diagnostic logging stream. When a command is executed through the ECI, the interface evaluates the command's outcome immediately. Informational messages—such as sample rate confirmations, format detections, or chainsetup status updates—are treated as successful command results or standard log events. They do not raise an internal error condition, leaving the interface's error state unset.

In contrast, fatal engine errors alter the internal state of the ECI runtime. When the underlying audio engine encounters a fatal condition (such as an unrecoverable ALSA/JACK buffer underrun, an unreadable audio device, or missing resources), the engine triggers an error flag. Within the ECI API, this differentiation is exposed through explicit inspection routines:

• Error State Polling: The function eci_error() returns a boolean value indicating whether the previous command caused an error or if the engine entered a fault state. Informational output leaves this value at zero (false), whereas fatal and non-recoverable errors set it to true.
• Error String Isolation: When an error condition exists, eci_last_error() retrieves the specific failure message generated by the engine. Routine informational output is never placed into this buffer; instead, non-error strings are returned directly via standard data retrieval functions, such as eci_last_string().

The engine also categorizes messages by severity levels within its internal event subsystem:

1. Diagnostic and Informational Streams: Normal status updates, processing progress, and trace logs are directed to standard output or a designated message buffer, depending on the client application's configuration. These streams do not disrupt real-time playback or recording.
2. Fatal Execution Errors: Severe engine faults bypass normal processing flow, immediately transition the engine out of the running state (often forcing it into stopped or error), and flush fatal diagnostics to the standard error stream and the ECI error stack.

By combining discrete API error-checking functions (eci_error() and eci_last_error()) with state-machine transitions that stop audio processing only when severe exceptions occur, the ECI ensures client applications can cleanly separate background operational feedback from fatal failures.