GitHub - free-audio/clap: Audio Plugin API (original) (raw)
Learn about CLAP
CLAP stands for CLever Audio Plugin. It is an interface that provides a stable ABI to define a standard for Digital Audio Workstations and audio plugins (synthesizers, audio effects, ...) to work together.
The ABI, or Application Binary Interface, serves as a means of communication between a host and a plugin. It provides backwards compatibility, that is, a plugin binary compiled with CLAP 1.x can be loaded by any other CLAP 1.y.
To work with CLAP, include clap/clap.h. To also include the draft extensions, include clap/all.h.
The two most important objects are clap_host and clap_plugin.
src/plugin-template.c is a very minimal example which demonstrates how to wire a CLAP plugin.
Entry point
The entry point is declared in entry.h.
Extensions
Most features come from extensions, which are in fact C interfaces.
// 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); // ... }
The extensions are defined in the ext folder.
Some extensions are still in the progress of being designed and they are in the draft folder.
An extension comes with:
- a header
#include <clap/ext/xxx.h> - an extension identifier:
#define CLAP_EXT_XXX "clap/XXX" - host interfaces are named like:
struct clap_host_xxx - plugin interfaces are named like:
struct clap_plugin_xxx - each method must have a clear thread specification
You can create your own extensions and share them. Make sure that the extension identifier:
- includes versioning in case the ABI breaks
- is a unique identifier
All strings are valid UTF-8.
Fundamental extensions
This is a list of the extensions that you most likely want to implement and use to get a basic plugin experience:
- state, save and load the plugin state
- state-context, same as state but with additional context info (preset, duplicate, project)
- resource-directory, host provided folder for the plugin to save extra resource like multi-samples, ... (draft)
- params, parameters management
- note-ports, define the note ports
- audio-ports, define the audio ports
- surround, inspect surround channel mapping
- ambisonic, inspect ambisonic channel mapping
- configurable-audio-ports, request the plugin to apply a given configuration
- audio-ports-config, simple list of pre-defined audio ports configurations, meant to be exposed to the user
- audio-ports-activation, activate and deactivate a given audio port
- extensible-audio-ports, let the host add audio ports to the plugin, this is useful for dynamic number of audio inputs (draft)
- render, renders realtime or offline
- latency, report the plugin latency
- tail, processing tail length
- gui, generic gui controller
- voice-info, let the host know how many voices the plugin has, this is important for polyphonic modulations
- track-info, give some info to the plugin about the track it belongs to
- tuning, host provided microtuning (draft)
- triggers, plugin's triggers, similar to parameters but stateless
Support extensions
- thread-check, check which thread you are currently on, useful for correctness validation
- thread-pool, use the host thread pool
- log, lets the host aggregate plugin logs
- timer-support, lets the plugin register timer handlers
- posix-fd-support, lets the plugin register I/O handlers
Deeper Host integration
- remote-controls, bank of controls that can be mapped on a controlles with 8 knobs
- preset-discovery, let the host index the plugin's preset in their native file format
- preset-load, let the host ask the plugin to load a preset
- param-indication, let the plugin know when a physical control is mapped to a parameter and if there is automation data
- note-name, give a name to notes, useful for drum machines
- transport-control, let the plugin control the host's transport (draft)
- context-menu, exchange context menu entries between host and plugin, let the plugin ask the host to popup its own context menu
Third-party extensions
- cockos.reaper_extension, access the REAPER API
Adapters
- clap-wrapper, wrappers for using CLAP in other plugin environments
Resources
- clap-validator, a validator and automatic test suite for CLAP plugins.
- clapdb, a list of plugins and DAWs which supports CLAP
Examples
- clap-host, very simple host
- clap-plugins, very simple plugins
Community related projects
- clap-juce-extension, juce add-on
- MIP2, host and plugins
- Avendish, a reflection-based API for media plug-ins in C++ which supports Clap
- NIH-plug, an API-agnostic, Rust-based plugin framework aiming to reduce boilerplate without getting in your way
- iPlug2, a liberally licensed C++ audio plug-in framework that supports Clap
- signalsmith-clap-cpp, C++ example plugins, with cross-platform webview UIs (using the draft webview extension, and a helper for native platforms) and WebAssembly (WCLAP) build instructions.
Programming Language Bindings
- clap-sys, rust binding
- CLAP-for-Delphi, Delphi binding
- clap-zig-bindings, Zig bindings
- CLAP for Ada, Ada 2012 binding