CLAP (Clever Audio Plugin)

Most CLAP features are implemented as extensions, which are C interfaces. Extensions allow hosts and plugins to exchange specialized functionality.

Accessing Extensions

Extensions are retrieved via the .extension() method on either the clap_host or clap_plugin object using a specific extension identifier.

Extension Structure

Every extension consists of:

• A header: #include <clap/ext/xxx.h>
• An extension identifier: #define CLAP_EXT_XXX "clap/XXX"
• Host interfaces: struct clap_host_xxx (if provided by the host)
• Plugin interfaces: struct clap_plugin_xxx (if provided by the plugin)
• Thread-specific method definitions.

When creating custom extensions, ensure the identifier is unique and includes versioning to prevent ABI breakage. All strings used in CLAP must be valid UTF-8.

// host extension
const clap_host_log *log = host->extension(host, CLAP_EXT_LOG);
if (log)
   log->log(host, CLAP_LOG_INFO, "Hello World! ;^)");

// plugin extension
const clap_plugin_params *params = plugin->extension(plugin, CLAP_EXT_PARAMS);
if (params)
{
   uint32_t paramsCount = params->count(plugin);
   // ...
}

These extensions are essential for implementing a basic functional plugin:

• state: Save and load plugin state.
• state-context: Save/load state with additional context (preset, duplicate, project).
• resource-directory (draft): Host-provided folder for plugin resources like multi-samples.
• params: Parameter management.
• note-ports: Define note ports.
• audio-ports: Define audio ports.
  • surround: Inspect surround channel mapping.
  • ambisonic: Inspect ambisonic channel mapping.
  • configurable-audio-ports: Request plugin to apply a specific configuration.
  • audio-ports-config: List of pre-defined audio port configurations.
  • audio-ports-activation: Activate/deactivate specific audio ports.
  • extensible-audio-ports (draft): Allow host to add audio ports dynamically.
• render: Realtime or offline rendering.
• latency: Report plugin latency.
• tail: Processing tail length.
• gui: Generic GUI controller.
• voice-info: Inform host of polyphonic voice count.
• track-info: Provide track-specific information to the plugin.
• tuning (draft): Host-provided microtuning.
• triggers (draft): Stateless plugin triggers (similar to parameters).

To create a CLAP plugin, you must export a clap_plugin_entry_t structure named clap_entry. This structure serves as the primary interface for the host to interact with your dynamic shared object (DSO).

Your implementation must provide three core functions: init, deinit, and get_factory.

Important Lifecycle Rules:

• init must be called before any other CLAP-related function or symbol in the DSO.
• init and deinit should be treated as potentially non-idempotent. As of CLAP 1.2.0, plugin authors must handle multiple calls to init before a deinit is called (e.g., by using a mutex and a reference counter).
• init must be fast, must not display a GUI, and must not perform user interaction.
• If init returns false, the host must not call deinit or any other symbols from the DSO.
• get_factory is thread-safe and can be called simultaneously by multiple threads.

The clap_plugin_entry_t struct defines the entry point interface for a CLAP plugin.

Members

• clap_version: Initialized to CLAP_VERSION to identify the version of the CLAP specification used.
• init(const char *plugin_path):
  • Initializes the DSO.
  • plugin_path is the path to the DSO (Linux/Windows) or the bundle (macOS).
  • Returns true on success.
  • Must be called once before any other symbols.
  • Must be defensive against multiple calls before a deinit (use a mutex and counter).
• deinit(void):
  • De-initializes the DSO and frees resources.
  • After calling deinit, the DSO is in the same state as if init had never been called.
• get_factory(const char *factory_id):
  • Returns a pointer to a factory for the given factory_id.
  • Returns NULL if the factory is not provided.
  • The caller must not free the returned pointer.
  • This function is thread-safe.

typedef struct clap_plugin_entry {
   clap_version_t clap_version;
   bool(CLAP_ABI *init)(const char *plugin_path);
   void(CLAP_ABI *deinit)(void);
   const void *(CLAP_ABI *get_factory)(const char *factory_id);
} clap_plugin_entry_t;