LADSPA Plugin Default Parameters in Ecasound

This article explains how the Ecasound digital audio workstation determines and assigns default control parameter values when instantiating LADSPA (Linux Audio Developer's Simple Plugin API) plugins. When operators are initialized without explicit user-defined values, Ecasound queries the plugin’s binary metadata, evaluates defined port range hints, calculates bounded or sample-rate-dependent values, and falls back to safe primitives where metadata is absent.

The LADSPA Metadata System

LADSPA plugins are distributed as compiled shared libraries (.so files) that expose a descriptor function returning a LADSPA_Descriptor structure for each plugin type. Control parameters are represented as input control ports.

Because the LADSPA specification avoids runtime configuration dialogues, all parameter boundaries and default guidelines are embedded directly into the descriptor metadata via the LADSPA_PortRangeHint structure. Each control port contains a HintDescriptor bitmask alongside LowerBound and UpperBound floating-point numbers.

Port Range Hints Evaluation

When Ecasound instantiates an effect using the -el (enable LADSPA) or -eli (enable LADSPA by index) chain operators, it parses any parameters passed on the command line or via the Ecasound Control Interface (ECI). If a user specifies fewer parameters than the plugin requires, Ecasound consults the LADSPA_PortRangeHint for each missing control input.

The API specifies several explicit default flags within the HintDescriptor bitmask. Ecasound resolves defaults by checking these flags:

  • Fixed Constant Defaults: Flags such as LADSPA_HINT_DEFAULT_0, LADSPA_HINT_DEFAULT_1, LADSPA_HINT_DEFAULT_100, and LADSPA_HINT_DEFAULT_440 instruct Ecasound to assign the literal values 0.0, 1.0, 100.0, or 440.0 (standard concert pitch).
  • Bound-Relative Defaults: Flags like LADSPA_HINT_DEFAULT_MINIMUM or LADSPA_HINT_DEFAULT_MAXIMUM resolve directly to the port's declared LowerBound or UpperBound.
  • Calculated Midpoints: The flags LADSPA_HINT_DEFAULT_LOW, LADSPA_HINT_DEFAULT_MIDDLE, and LADSPA_HINT_DEFAULT_HIGH represent values positioned at 25%, 50%, and 75% between the lower and upper bounds.

Linear vs. Logarithmic Calculation

When calculating low, middle, and high defaults, Ecasound accounts for the scale of the parameter:

  • Linear Ports: If LADSPA_HINT_LOGARITHMIC is not set, Ecasound applies linear interpolation between the lower and upper bounds. For example, LADSPA_HINT_DEFAULT_MIDDLE is calculated as LowerBound + 0.5 * (UpperBound - LowerBound).
  • Logarithmic Ports: If the LADSPA_HINT_LOGARITHMIC flag is active (common for frequency and decibel controls), Ecasound evaluates the values exponentially: \(\text{exp}(\text{ln}(\text{LowerBound}) + 0.5 \times (\text{ln}(\text{UpperBound}) - \text{ln}(\text{LowerBound})))\).

Sample-Rate Dependency

If a port includes the LADSPA_HINT_SAMPLE_RATE flag, its boundaries are treated as multipliers of the current processing sample rate (e.g., cutoff frequencies). Ecasound multiplies the declared bounds by the active chainsetup's sample rate before computing bound-relative defaults or midpoints.

Missing Hints and Fallbacks

If a plugin author sets the default hint to LADSPA_HINT_DEFAULT_NONE, or fails to provide valid hint flags for a control port, Ecasound applies a standard fallback strategy. In these cases, Ecasound generally falls back to the port's LowerBound, or to 0.0 if the bounds are indeterminate, ensuring that unassigned memory does not lead to unpredictable floating-point values during processing.