maolan-plugin-host

Out-of-process plugin host for the Maolan DAW.

This crate provides the reusable plugin-host library. Applications can build their own host process around it and communicate with the audio engine over shared memory and lightweight event channels. The Maolan DAW's host executable is built from maolan/src/bin/maolan-plugin-host.rs.

Supported formats

Format	Status	Platforms
CLAP	Fully supported	Linux, FreeBSD, macOS, Windows
VST3	Fully supported	Linux, FreeBSD
LV2	Fully supported	Linux, FreeBSD
Audio Unit (AUv2 and AUv3)	Fully supported	macOS

How it works

1. The DAW spawns maolan-plugin-host as a separate process for every plugin instance.
2. Both sides open a shared-memory segment and a pair of event pipes (Unix) or named events (Windows).
3. Audio buffers, parameter changes, and MIDI events are exchanged through the shared-memory protocol defined in maolan-plugin-protocol.
4. If the plugin crashes or hangs, the DAW can terminate the host process and recover without affecting the rest of the project.

Binary usage

Plugin hosting mode

The DAW normally invokes the binary automatically, but the command-line interface looks like this:

maolan-plugin-host <format> <plugin-path> <shm-name> <instance-id> <d2h-fd> <h2d-fd> [sample-rate buffer-size num-inputs num-outputs]

• format – clap, vst3, lv2, or au (macOS only).
• plugin-path – Path to the plugin library. For CLAP you can select a specific plugin inside the factory with path#plugin_id or path::plugin_id. For AU, use the component identifier au:<type>:<subtype>:<manufacturer>.
• shm-name – Name of the shared-memory segment created by the DAW.
• instance-id – Unique identifier for this instance.
• d2h-fd / h2d-fd – File descriptors (Unix) or event names (Windows) used for the event channel.
• Optional VST3/LV2/AU arguments: sample-rate, buffer-size, num-inputs, num-outputs. CLAP uses a fixed 48 kHz sample rate and 256-frame buffer.

Scan mode

Discover plugins and dump their metadata to JSON:

maolan-plugin-host --scan --format <format> --path <plugin-path> [--output <json-path>]

Example:

maolan-plugin-host --scan --format clap --path /usr/lib/clap --output clap-index.json

On macOS, use --format au to scan Audio Units registered with the system.

The generated JSON has the following shape, with any stderr diagnostics from the scan captured as errors and warnings. Each diagnostic includes the original message and, when it can be determined, the affected plugin_uri, plugin_name, and/or bundle_uri:

{
  "errors": [
    {
      "message": "error: failed to open file /usr/lib/lv2/broken.lv2/manifest.ttl (No such file or directory)",
      "bundle_uri": "file:///usr/lib/lv2/broken.lv2/"
    }
  ],
  "warnings": [],
  "data": []
}

Library usage

Add the crate to your Cargo.toml:

[dependencies]
maolan-plugin-host = "0.1.0"

The library re-exports maolan_plugin_protocol and exposes the following modules:

• clap – Low-level CLAP C FFI bindings and host extension helpers.
• au – macOS Audio Unit host, supporting both AUv2 and AUv3 components.
• cli – Process entry point used by the DAW host binary (cli::run()).
• host – Shared-memory runtime that drives a plugin instance.
• lv2 – LV2 host implementation (Unix only), built on the pure-Rust maolan-lv2 crate (no C lilv dependency).
• scan – Plugin scanner and metadata serialization.
• paths – Standard plugin installation paths for each platform.
• util – Small helpers such as SimpleMutex and AudioPort.
• vst3 – VST3 bindings and helpers.
• vst3_lv2_host – VST3/LV2 specific runtime loop and GUI support.

The DAW's maolan-plugin-host binary is a thin wrapper around cli::run(). Other applications can use the library's host, scanner, and format modules to build their own plugin-host process.

Building

Requires Rust 1.85+ (2024 edition).

cargo build --release

Platform-specific dependencies

• Linux / FreeBSD
  • X11 development libraries (for VST3 GUI support)
  • LV2 support is pure Rust (via maolan-lv2); no liblilv/lv2 system libraries are required.
• Windows
  • No extra system libraries required.