Configuring Non-Blocking I/O in Ecasound

Ecasound manages input and output (I/O) execution flow, thread latency, and stream synchronization through command-line interface (CLI) flags that govern buffering modes, internal buffer toggles, and audio engine sizing. While low-level non-blocking I/O is tied directly to underlying operating system drivers and audio subsystems (such as ALSA or JACK), Ecasound provides specific runtime flags—specifically -B, -z:nointbuf, -z:intbuf, and -b—to determine whether audio processing blocks on full/empty buffers or operates in an unbuffered, real-time, non-blocking manner.

The Buffering Mode Flag (-B)

The primary mechanism for selecting between blocking and non-blocking streaming behavior in Ecasound is the buffering mode option:

-B:buffering_mode

Ecasound supports three parameters for this option:

  • -B:realtime: Forces the engine into low-latency, real-time mode. When set to realtime, Ecasound optimizes audio streams for continuous throughput without waiting for slow consumers or producers. If an I/O subsystem fails to deliver or consume frames in time, Ecasound flags buffer overruns or underruns (xruns) rather than allowing the processing loop to block indefinitely.
  • -B:non-realtime: Enforces traditional blocking I/O behavior. The processing engine waits synchronously until input buffers have data available to read and output buffers have space available to write. This mode is optimal for file conversion, batch processing, and situations where no frames should ever be dropped.
  • -B:auto: The default setting. Ecasound inspects the configured inputs and outputs. If real-time audio devices (like sound cards or JACK ports) are present, it selects real-time streaming; if only static audio files are involved, it falls back to blocking non-realtime execution.

Disabling and Enabling Internal Buffering (-z)

Ecasound implements an internal software buffering layer between the engine processing loop and hardware audio drivers. You can manipulate this layer using the -z flag family:

  • -z:nointbuf: Disables extra internal buffering. This forces Ecasound to write to and read from audio endpoints directly via the primary engine buffers. Removing the secondary layer reduces latency and eliminates intermediate blocking stages, making operations behave as close to raw non-blocking hardware I/O as possible.
  • -z:intbuf: Explicitly enables the internal buffering layer (standard default behavior). This smooths out intermittent I/O jitter by letting consumer/producer threads block temporarily against an intermediate FIFO queue rather than stalling the core audio pipeline.

Engine Buffer Size Control (-b)

Buffer sizes dictate how many samples Ecasound transfers per processing cycle:

-b:buffer_size

Setting a smaller buffer size (e.g., -b:128 or -b:256) minimizes the frame residency time inside the I/O pipeline, complementing -B:realtime and -z:nointbuf to maintain non-blocking execution boundaries. Conversely, larger buffer sizes (e.g., -b:2048) favor blocking throughput stability.

Real-Time Scheduling (-r)

To prevent blocking conditions caused by operating system thread scheduling, Ecasound includes the real-time priority flag:

-r
-r:sched_priority

Using -r elevates the Ecasound process using POSIX real-time scheduling policies (SCHED_FIFO or SCHED_RR). When combined with -B:realtime, it prevents kernel-level thread preemption from converting a timely non-blocking audio exchange into a delayed, blocking state.

Practical CLI Examples

Enabling Non-Blocking, Real-Time Audio Streaming:

ecasound -B:realtime -z:nointbuf -b:256 -r -i alsa,default -o alsa,default

In this command, -B:realtime ensures the engine does not block on transfer delays, -z:nointbuf bypasses secondary internal caching, -b:256 keeps sample packets small, and -r runs the engine with real-time process priority.

Enabling Synchronous, Blocking File Processing:

ecasound -B:non-realtime -z:intbuf -b:1024 -i input.wav -o output.wav

This configuration ensures that reading and writing block sequentially until every sample is accurately processed, preventing any dropped frames during file operations.