How Ecasound Processes Incoming MIDI Control Messages

Ecasound is a powerful command-line multitrack audio processing tool capable of capturing, routing, and translating incoming MIDI Continuous Controller (CC) messages into dynamic, real-time parameters for audio effects and chain setups. By interfacing directly with low-level audio and MIDI subsystems—primarily the ALSA sequencer, raw MIDI devices, or OSS—Ecasound intercepts incoming control bytes, normalizes their values, and modulates assigned parameters such as volume, panning, and filter cutoffs on the fly.

1. Interfacing and Capturing MIDI Input

To capture incoming MIDI control messages, Ecasound establishes a connection to a hardware port or software sequencer using the -Md (MIDI device) global option. Depending on the operating system and user configuration, it supports several drivers:

  • ALSA Sequencer (-Md:alsaseq,device): Creates an ALSA sequencer client port, allowing users to connect hardware controllers or software synthesizers via utilities like aconnect.
  • ALSA Raw MIDI (-Md:rawmidi,/dev/snd/midiC0D0): Reads direct byte streams from an ALSA raw MIDI hardware interface.
  • OSS MIDI (-Md:oss,/dev/midi): Captures messages from standard Open Sound System MIDI device nodes.

During initialization, Ecasound creates a dedicated background thread or non-blocking event listener for the designated device to read incoming byte streams without interrupting the real-time audio processing loop.

2. Message Decoding and Filtering

Once the MIDI stream is active, Ecasound's event parser monitors the incoming data packets for Channel Voice messages:

  • Message Filtering: Ecasound identifies status bytes corresponding to Control Change events (typically 0xBn, where n is the MIDI channel from 0 to 15).
  • Data Extraction: When a CC event is detected, the parser extracts the subsequent two data bytes: the controller number (0–127) and the controller value (0–127). Unrelated messages, such as Note On/Off or SysEx, are ignored unless explicitly routed to other processes.

3. Controller Mapping with the -km Operator

Ecasound bridges the gap between incoming MIDI CC data and audio parameters using the MIDI control mapping operator (-km). The mapping syntax determines how a specific incoming controller modifies a chain operator parameter:

-km:param_id,controller,channel,low_val,high_val

  • param_id: Identifies which chain operator parameter is being targeted (such as an effect's cutoff frequency, wet/dry mix, or gain).
  • controller: Specifies the target MIDI CC number (e.g., CC 1 for modulation wheel, CC 7 for volume).
  • channel: The targeted MIDI channel (1–16).
  • low_val and high_val: The target parameter's range boundaries corresponding to MIDI values 0 and 127, respectively.

4. Normalization, Interpolation, and Parameter Updates

After decoding a valid CC message, Ecasound performs real-time value scaling:

  1. Value Scaling: The raw MIDI input (0 to 127) is linearly interpolated into the target parameter range defined by low_val and high_val. For instance, mapping CC 7 to an amplifier gain ranging from -40 dB to +6 dB scales input 0 to -40 dB and 127 to +6 dB.
  2. Thread-Safe Modulation: The scaled value is applied to the active chain operator via thread-safe internal pointers. Because the audio thread and MIDI capture run concurrently, updates are applied synchronously at the start of each audio processing buffer cycle, preventing audio dropouts, zipper noise, or race conditions.