Ecasound MIDI Program Change Chainsetup Mapping

This article explains how Ecasound captures incoming MIDI Program Change events and translates them into chainsetup transitions for dynamic real-time audio routing. It covers the underlying control architecture, the index-based mapping mechanism, and the execution cycle Ecasound uses to disconnect, select, and connect chainsetups seamlessly during live operation.

Ecasound Chainsetups and MIDI Control

In Ecasound, a chainsetup represents an entire audio routing configuration, consisting of inputs, outputs, chains, and signal processing operators. While multiple chainsetups can be loaded into memory simultaneously, only one can be connected and actively processing audio on an audio device at a single time.

Ecasound includes a MIDI control subsystem that allows external MIDI hardware and software sequencers to drive its internal engine. When configured to listen to MIDI control input, Ecasound interprets incoming MIDI messages through its command interpreter, bypassing the need for manual interactive command-line entry.

Capturing MIDI Program Change Events

To map MIDI events to engine actions, Ecasound must be initialized with a MIDI control interface using the -M or --midi-controller options. When enabled:

1. Port Binding: Ecasound registers an ALSA MIDI or OSS MIDI sequencer port.
2. Channel Filtering: The engine listens on a designated MIDI channel or responds globally in omni mode depending on configuration.
3. Message Parsing: The internal parser isolates MIDI Program Change (PC) messages from standard Continuous Controller (CC) and Note events.

While Continuous Controllers are typically assigned to continuous audio parameters (such as volume levels or filter cutoffs via the -km controller mechanism), Program Change messages are structurally treated as state-selection commands.

The Mapping Mechanism: Program Numbers to Chainsetups

Ecasound treats loaded chainsetups as an indexed array. The mapping between incoming MIDI Program Change values (typically 0–127 or 1–128) and chainsetups is established through sequential registration:

• Index Matching: Each loaded chainsetup is assigned an internal identifier and a sequential index based on the order it was defined or loaded via command-line arguments or ECI (Ecasound Control Interface) scripts.
• Direct Integer Correlation: An incoming Program Change value maps directly to the corresponding index in the chainsetup list. For example, Program Change 1 selects the first loaded chainsetup, Program Change 2 selects the second, and so on.

The Chainsetup Transition Lifecycle

When a valid Program Change event is received, Ecasound executes a sequence of internal commands equivalent to its interactive control protocol:

1. Engine Pause / Disconnect (cs-disconnect): The engine temporarily halts processing on the current chainsetup. Buffers are flushed, and active input/output streams tied exclusively to the active setup are disconnected to release hardware or driver locks.
2. Setup Selection (cs-select): The internal pointer switches from the active chainsetup identifier to the target chainsetup matching the Program Change index.
3. Setup Connection (cs-connect): Ecasound binds the newly selected chainsetup to the physical sound drivers and system inputs/outputs, initializing internal effect states and allocating required buffers.
4. Engine Resume (start): If continuous playback or processing was active prior to the transition, the engine restarts processing instantly under the new chainsetup configuration.

Through this execution sequence, Ecasound enables hands-free re-routing of complex audio graphs, switching instrument processing, or changing live performance configurations in real time via standard MIDI controllers.