How Ecasound Discovers and Loads LADSPA Plugins

Ecasound locates and initializes Linux Audio Developer's Simple Plugin API (LADSPA) plugins through a standardized discovery process driven by environment variables, dynamic library inspection, and descriptor scanning. By searching designated system directories for shared object files, Ecasound dynamically registers available audio effects and makes them accessible via command-line arguments and interactive interface commands.

1. Directory Resolution via LADSPA_PATH

Ecasound determines where to look for plugins by checking the LADSPA_PATH environment variable. This variable contains a colon-separated list of directories where compiled LADSPA shared libraries (.so files) reside.

  • If LADSPA_PATH is defined, Ecasound searches only the directories specified within that string in order from left to right.
  • If LADSPA_PATH is not set, Ecasound falls back to default system directories, typically:
    • /usr/lib/ladspa
    • /usr/local/lib/ladspa
    • /usr/lib64/ladspa (on 64-bit architectures where applicable)

2. Shared Library Scanning and Dynamic Linking

Once the directories are identified, Ecasound scans them for binary dynamic shared objects (*.so). For each candidate file encountered, Ecasound utilizes dynamic linking functions (specifically dlopen() from the standard C library) to load the library into memory during startup or when plugin queries are executed.

If a shared library fails to load—due to missing dependencies, permission issues, or architecture mismatches—Ecasound ignores the file or reports an error, continuing to scan the remaining files in the path.

3. Descriptor Extraction

The LADSPA specification requires every compliant plugin library to export an entry-point function called ladspa_descriptor(). Ecasound accesses this function using dlsym() to extract structural metadata from the file:

  • Plugin Label: A unique, human-readable string identifier (e.g., amp_mono).
  • Unique ID: A numeric identifier assigned to prevent naming collisions.
  • Port Descriptors: Definitions of audio inputs, audio outputs, control inputs (parameters), and control outputs.

A single .so file can contain multiple plugins; Ecasound iterates through index numbers passed to ladspa_descriptor() until the function returns NULL, ensuring that all individual effects housed within a single file are registered.

4. Querying and Using Discovered Plugins

Once loaded into its internal registry, Ecasound maps each plugin so it can be called inside processing chains:

  • Listing Plugins: You can verify discovered plugins by running ecasound -el-list, which outputs every detected LADSPA plugin along with its ID and label.
  • Applying by Label: Plugins are invoked using the -el: operator followed by the plugin label and its parameter values (e.g., -el:amp_mono,2.0).
  • Applying by Unique ID: Alternatively, plugins can be loaded using the -eli: operator followed by the numeric ID (e.g., -eli:1048,2.0).

Through this mechanism, adding new plugins requires no recompilation of Ecasound; simply dropping a compatible .so file into a directory included in LADSPA_PATH allows Ecasound to immediately discover and utilize it.