Ecasound Control Interface Return Format

The Ecasound Control Interface (ECI) protocol, primarily utilized via Net-ECI for remote and inter-process control, communicates through a structured, text-oriented message format. This article explains how ECI formats return values and status codes, detailing the message structure, status code conventions, data type identifiers, and payload framing necessary for building a custom client or parser.

General Message Structure

Every response emitted by the Ecasound Control Interface over a network or pipe connection consists of two distinct segments: a header line and a payload body.

The structure strictly follows this syntax:

<status_code> <type_indicator> <payload_length>\r\n
<payload_body>

1. Status Code: A numeric integer indicating the execution outcome.
2. Type Indicator: A single character identifying the data type of the payload.
3. Payload Length: An integer specifying the exact size of the payload body in bytes.
4. Delimiter: A carriage return and newline sequence (\r\n) separating the header from the payload.
5. Payload Body: The raw data returned by the command, matching the byte count declared in the header.

Status Codes

ECI uses numeric status codes similar to standard network application protocols to signify whether a command succeeded or encountered an error.

• 256 (Success / OK): The standard status code indicating that the command executed successfully without errors.
• 500 (Error / Failure): Indicates an internal processing error, invalid argument, syntax failure, or execution issue within the Ecasound engine.

Return Type Indicators

The second token of the header line informs the client parser how to cast or interpret the ensuing payload bytes. The primary type characters include:

• s (String): Standard character string representing a single textual value (e.g., chainsetup status, file paths).
• i (Integer): Numeric integer value (e.g., sample rates, channel counts).
• f (Float / Double): Floating-point numeric value (e.g., playback position in seconds, volume levels).
• S (String List): A collection or list of strings, usually formatted as comma-separated or newline-delimited tokens depending on the specific command.
• e (Error): Denotes an error message payload, typically paired with the 500 status code.

Payload Length and Body Delimitation

Because return data can contain spaces, special characters, or multi-line outputs, ECI does not rely on text delimiters to end the response. Instead, it relies on the explicit <payload_length> byte count.

Parsers must read the header until the initial \r\n, extract the integer byte count, and then read precisely that number of bytes from the input stream to obtain the complete payload.

Concrete Examples

1. Integer Query (get-sample-rate)

When querying an engine integer parameter, such as the current sample rate:

256 i 5\r\n
44100

• Status: 256 (Success)
• Type: i (Integer)
• Length: 5 bytes
• Payload: 44100

2. Float Query (get-position)

When querying the current playback position:

256 f 4\r\n
1.25

• Status: 256 (Success)
• Type: f (Float)
• Length: 4 bytes
• Payload: 1.25

3. Error Response (Invalid Command)

When an invalid command or parameter is submitted:

500 e 28\r\n
ERROR: Invalid command 'xyz'

• Status: 500 (Failure)
• Type: e (Error message)
• Length: 28 bytes
• Payload: ERROR: Invalid command 'xyz'