Skip to content

Wrapping your CLAP ‐ A Developer Guide

Jump to bottom Edit New page
Paul edited this page Sep 24, 2023 · 9 revisions

Overview

The clap-wrapper project provides a set of tools which allow CLAP plugin authors to present their plugins to hosts which do not support the CLAP protocol. It accomplishes this by creating a plugin which presents an appropriate host protocol (VST3, AUv2, etc...) and translating that protocol with the best possible fidelity to your CLAP plugin. In short the clap-wrapper acts as a clap host to your plugin, and as a foreign protocol plugin to the host in question.

flowchart TD
    A[Plugin Host] -->|API - VST3, AUv2, etc| B(API Implementation)
    subgraph cw[ ]
    B --> C(API to CLAP translation)
    C -->D[Your CLAP]
    end
Loading

The clap-wrapper also provides extensive CMake support to allow you to build and deploy your wrapped CLAP in a variety of contexts. The clap-wrapper project also provides simple standalone executables which can re-house your clap as an application. Finally, the clap-wrapper provides a set of clap extensions and factories which allow your clap to configure the way it is wrapped.

We have implemented the clap-wrapper project with multiple methods of loading, locating, hosting, and running your CLAP.

This page serves as developer documentation for using and deploying clap-wrapper to re-host your CLAP in other protocols.

How the clap-wrapper finds your CLAP

The single most important question in deploying the clap-wrapper is determining how your wrapped plugin finds your original clap and its associated clap-entry. Broadly you have two choices

  1. Your wrapper instance is a 'thin' wrapper which searches the filesystem for the wrapped CLAP using a variety of techniques to determine the name and the path. This makes very light generic wrappers, but also can prove fragile if the wrapper is present but the underlying clap is moved or removed.

  2. Your wrapper instance is a 'thick' wrapper which contains both the wrapper code and entry point and the code and entry point for your clap linked into the same dll or bundle. This makes for wrapped products which are robust standalone plugins, but creates larger plugins and requires your build system cooperate with the wrapper project.

The 'thin' pattern and lookup rules

flowchart TD
    subgraph cw[plugin.vst3]
    B(Wrapper Init) --> C(Search Clap Paths for 'plugin.clap')
    end
    subgraph yc[plugin.clap]
    C -->D[clap_entry]
    end
Loading

The 'thick' pattern

flowchart TD
    subgraph cw[plugin.vst3]
    B(Wrapper Init) --> C(dlopen self for `clap_entry`)
    C -->D[clap_entry]
    end
Loading 
flowchart TD
    subgraph cw[plugin.vst3 - macOS Bundle]
    B(Wrapper Init) --> C(Search Bundle PlugIns)
    C -->D(load CLAP from Bundle Plugins)
    D -->E[clap_entry]
    end
Loading

Using CMake and wrapper extensions to build and configure the clap-wrapper

Locating Subordinate SDKs

'Thin' builds

'Thick' builds

Using the clap-wrapper extensions in your CLAP

The wrapper will only use CLAP features and should be sufficent for 99% of the plugins out there, but sometimes vendor specific contracts have to be exposed. For instance, you may want to pick a VST3 TUID or configure midi ports or note expressions. We are taking the strategy that these features are exposed through CMake in some cases and through extensions in others.

Each of the plugin-specific CMake flags and extensions are documented in the Particular Formats section below. To link the extensions to your CLAP use the following CMake fragment.

add_subdirectory("clap-wrapper" EXCLUDE_FROM_ALL)
target_link_libraries(${project} PRIVATE clap-wrapper-extensions)

Particular Formats

VST3

AUv2

Standalones

clap-first development

foo

Status as of Sep 24, 2023

** BELOW STILL NEEDS TO BE CLEANED UP AND REWRITTEN FROM OLD README **

How to build

git clone https://github.com/free-audio/clap-wrapper.git
mkdir build
cmake -B build -DCLAP_SDK_ROOT={path to clap sdk} -DVST3_SDK_ROOT={path to vst3 sdk}

You can also determine the output name of the resulting VST3 plugin by using the CLAP_WRAPPER_OUTPUT_NAME CMake variable:

Build it for your clap, assuming it is named "fruit":

git clone https://github.com/free-audio/clap-wrapper.git
mkdir build
cmake -B build -DCLAP_SDK_ROOT={path to clap sdk} -DVST3_SDK_ROOT={path to vst3 sdk} -DCLAP_WRAPPER_OUTPUT_NAME=fruit

Renaming the resulting binary will also work, the name is not being used anywhere in the code, just for the binary output name.

The CLAP_SDK_ROOT and VST3_SDK_ROOT arguments can be omitted if the SDKs are present in the parent folder, the same base folder or in a ./libs folder. In this case the cmake script will detect and use them automatically.

You can also add the wrapper(s) to your existing project. Assume you've added the clap-wrapper repository into a libs subdirectory, you can just add these lines to your CMakeLists.txt file:

# this assumes that ${PROJECT_NAME} is set to the actual plugin final filename 
set(CLAP_WRAPPER_OUTPUT_NAME ${PROJECT_NAME})
add_subdirectory(libs/clap-wrapper )

How to use

The VST3 binary can be placed into the VST3 plugin folders. When the VST3 host opens the plugin, the wrapper will try to find a CLAP plugin with the exact same name in the CLAP folders. If the binary is placed as {VST3-Pluginfolder}/vendorname/plugin.vst3 it will look at {CLAP-Pluginfolder}/plugin.clap and also {CLAP-Pluginfolder}/vendorname/plugin.clap. It automatically translates all functions to VST3 then.

Add a custom footer
Add a custom sidebar
Clone this wiki locally