How Ecasound Reports XRUNs in Live Audio Capture

This article explains how Ecasound detects and reports buffer underrun and overrun (xrun) events during live audio hardware capture. It details the mechanisms through which Ecasound registers timing failures, the distinction between ALSA and JACK reporting, the role of debug verbosity flags, and how to track these events interactively using the Ecasound Control Interface (ECI).

Understanding XRUNs in Capture Mode

During live hardware capture, an xrun is almost exclusively a buffer overrun (overflow). This occurs when the hardware audio interface fills its ring buffer with incoming sample data faster than Ecasound can read and process it, resulting in dropped samples and audible clicks or gaps in the recording.

Console and Terminal Notifications

By default, Ecasound prints system state changes and critical stream warnings to standard error (stderr). When an xrun occurs during processing:

  • Real-time warnings: Ecasound intercepts the driver-level error and prints a warning directly to the terminal, typically identifying that a buffer overrun has occurred and indicating processing latency issues.
  • Status line discrepancies: In interactive or standard console mode, the real-time processing counter reflects discontinuities when frames are dropped, causing discrepancies between elapsed real time and processed audio stream duration.

Increasing Output Detail with Debug Flags

Default logging provides minimal notification to avoid causing additional I/O latency. To see precise information about xrun events, Ecasound provides the -d flag, which controls debug levels:

  • -d:1 (Errors and Warnings): Ensures that all non-fatal driver alerts, including ALSA and JACK buffer warnings, are printed.
  • -d:2 and higher (Subsystem details): Outputs granular timing information, configuration properties, and precise timestamps for when the audio engine loses synchronization with the sound card clock.

Running a capture session with elevated debugging reveals the exact point where the read pointer fell behind the write pointer.

ALSA Direct Capture Reporting

When capturing directly from ALSA hardware (e.g., -i:alsa,default or -i:alsa,hw:0), Ecasound manages the ALSA buffer pointers directly:

  • Ecasound monitors the ALSA API's snd_pcm_status() function.
  • When the kernel driver reports EPIPE (Broken pipe), Ecasound identifies the condition as an overrun.
  • It reports the event to the console, resets the ALSA capture buffer to re-synchronize the stream, and continues recording.

JACK Subsystem Reporting

When using the JACK Audio Connection Kit as the input engine (-i:jack), responsibility for xrun detection shifts to the JACK server daemon (jackd):

  • JACK implements an internal callback mechanism specifically for xruns (jack_set_xrun_callback).
  • Ecasound hooks into this callback to register whenever JACK encounters a delay.
  • The xrun is logged both by Ecasound’s messaging system and by the jackd server output, which usually reports the event in milliseconds (e.g., indicating an xrun of a specific duration).

Programmatic Reporting via ECI

For headless operation or custom recording software, Ecasound reports engine health through the Ecasound Control Interface (ECI). Using interactive commands:

  • The engine-status and cs-status commands can be issued to query the current operational state of the chainsetup.
  • Custom scripts (using Python, C, or Perl bindings) can monitor the standard output of the ECI parser to catch overrun strings as they appear.
  • If an xrun forces the engine into an error state, the ECI API allows the controlling application to detect the stoppage and issue recovery commands (start or engine-launch) automatically.