Ecasound Chainsetup Operational Lifecycle Guide

This article provides a comprehensive overview of the operational lifecycle of a chainsetup in Ecasound, tracking its path from initial instantiation to complete destruction. It covers how a chainsetup is defined, configured with signal processing chains, bound to physical audio endpoints, processed by the execution engine, and cleanly decommissioned.

1. Creation and Instantiation

The lifecycle begins when a chainsetup is instantiated, either via command-line parameters or through Ecasound's Interactive Mode (EIAM). In interactive mode, this is achieved using the cs-add command followed by cs-select. At this stage, the chainsetup acts as an empty container allocated in memory, establishing the configuration scope for all subsequent chains, inputs, outputs, and effect operators.

2. Configuration and Topology Definition

Once created, the chainsetup enters the configuration phase. Here, the audio routing topology is constructed:

  • Chains: Individual signal paths are declared using c-add (or -a).
  • Inputs and Outputs: Audio sources (sound files, ALSA/JACK devices) are attached to specific chains using ai-add / ao-add (or -i / -o).
  • Operators and Controllers: DSP plugins (LADSPA, native Ecasound effects) and continuous parameter controllers (envelopes, oscillators) are assigned to the chains.

Throughout this state, the chainsetup remains purely descriptive. No physical audio hardware is locked, no files are opened, and sample rate negotiation has not yet taken place.

3. Connection and Resource Allocation

To transition from a static configuration to an active processing graph, the chainsetup must be connected using the cs-connect command (or automatically when starting processing). During this phase:

  • Device interfaces (such as ALSA, JACK, or OSS) and audio files are opened and validated.
  • Format negotiation occurs, aligning sample rates, channel counts, and sample formats across the graph.
  • Required processing buffers and intermediate memory allocations are locked in place.
  • If any invalid routing, missing file, or format mismatch is detected, the process fails, returning the chainsetup to the unconnected configuration state.

4. Real-Time Processing (Execution)

With the chainsetup connected, it can be executed by starting the Ecasound transport engine using start or run. During execution:

  • Audio buffers are continuously pulled from inputs, routed through chain-specific DSP operators, and pushed to outputs.
  • Controllers dynamically modify effect parameters in real time.
  • The engine supports state transitions between running and paused (stop) without releasing system resources, allowing repositioning via transport commands (seek, setpos).

5. Disconnection

When processing finishes or the graph needs structural reconfiguration, the chainsetup is disconnected using cs-disconnect. During disconnection:

  • All open file handles are flushed and closed properly.
  • Connections to audio servers (e.g., JACK ports) and hardware drivers (e.g., ALSA handles) are released.
  • Internal processing buffers are freed. The chainsetup remains in memory in an editable state, allowing parameter changes or topology updates before reconnecting.

6. Destruction

The final stage of the lifecycle is complete destruction, executed via the cs-remove command or when exiting Ecasound (quit). The engine checks that the chainsetup is disconnected, then systematically deallocates all associated chains, operators, controllers, and metadata from system memory. Once destroyed, the chainsetup reference ceases to exist, concluding its operational lifecycle.