Ecasound Interactive Mode Engine State Changes

This article provides an overview of how Ecasound's Interactive Mode communicates real-time audio engine state changes directly to the console. It details the mechanisms Ecasound uses to report transitions between states such as running, stopped, and paused, covering both synchronous status querying and asynchronous system-level notifications.

Interactive Mode and Console Output Mechanism

When launched in interactive mode using the -c command-line option, Ecasound initiates the Ecasound Interactive Mode (EIAM). In this mode, Ecasound operates as a command-line interpreter that reads user or process inputs from standard input (stdin) and writes responses, telemetry, and status updates directly to standard output (stdout) and standard error (stderr).

Engine state reporting occurs through two distinct communication pathways: explicit interactive query responses and automatic asynchronous engine events.

Synchronous State Reporting via Interactive Commands

To report the current operational status of the processing engine on demand, Ecasound relies on built-in status commands. When an operator or wrapper script inputs commands such as engine-status or status, Ecasound evaluates the audio subsystem's internal state and writes an immediate plain-text confirmation to the console.

The engine reports one of several standardized states:

• stopped: The processing pipeline is inactive, audio devices are closed or idle, and no processing threads are active.
• running: The audio subsystem is actively streaming samples through defined chain setups, inputs, and outputs.
• paused: The engine preserves its current position in the streams, but sample processing and buffer streaming are temporarily halted.
• error: An unexpected fault (such as an audio device failure, buffer underrun/overrun, or broken pipe) has interrupted processing.

These text responses are formatted to appear directly on the line following the command, allowing parent processes or human operators to reliably verify that a requested state transition (such as start or stop) has executed successfully.

Asynchronous Event Notifications and Stream Indicators

Ecasound also pushes unprompted state changes to the console when transitions are triggered by internal processing conditions rather than explicit user input:

1. End-of-File (EOF) Transitions: When an input source reaches its end, the engine automatically terminates processing. It outputs an asynchronous notification indicating that processing has completed, followed by a transition message moving the engine status from running to stopped.
2. Buffer Errors (Xruns): If real-time audio constraints are violated, such as a buffer underrun or overrun, Ecasound outputs diagnostic warning messages to the console (typically routed to stderr or prefixed with subsystem tags such as (audioio_alsa) or (ecasound)). These messages notify the user that processing fidelity was compromised, which may precede an engine stall or automatic stop.
3. Time and Position Telemetry: While the engine is running, periodic position counters and processing progress can be written to the terminal, providing dynamic visual feedback of the active state until processing is interrupted or completed.

Programmatic State Tracking with the Ecasound Control Interface (ECI)

When Ecasound is driven programmatically in interactive mode via pipes or Unix sockets, state changes are captured through the Ecasound Control Interface protocol. Under this protocol, every state transition outputs standard return codes and text blocks to the console output descriptor. Scripts monitor these streams line by line to detect return tokens that confirm whether the engine has changed state or encountered an execution failure.