CLAP Developers Guide | ECOSYSTEM Research

CLAP Plugin Developer's Guide Introduction CLAP (CLever Audio Plugin) was designed from the ground up to address the limitations of older formats. Its advanced features—particularly around polyphonic modulation, MIDI 2.0, and multi-core processing—make it the most capable plugin format available today. This guide focuses on how to implement these features in your plugins. --- 1. Polyphonic (Per-Note) Modulation This is CLAP's killer feature. Unlike VST3, where modulation is global, CLAP allows modulation to target specific notes using noteid. 1.1 Declaring Polyphonic Modulation Support First, inform the host that your plugin supports polyphonic modulation: The PolyModulationConfig tells the host the maximum number of voices your plugin will use and whether it supports overlapping voices (voice stacking). 1.2 Parameter Flags for Modulation When defining your parameters, set the appropriate flags: Key flags include: - CLAPPARAMISAUTOMATABLE – Can be automated - CLAPPARAMISMODULATABLE – Can be modulated - Additional flags for per-note, per-key, per-channel, and per-port variations 1.3 The Two-Value System: Base + Modulation CLAP parameters have two components: - Base value – Set via CLAPEVENTPARAMVALUE - Modulation amount – Applied via CLAPEVENTPARAMMOD Key insight: Use noteid to target specific notes. Wildcards (-1) apply globally. 1.4 Processing Per-Note Modulation in Your Audio Thread Here's a practical example from the Nakst tutorial: This pattern—global parameter value + per-voice offset—is the foundation of CLAP's polyphonic modulation system. --- 2. Note Expressions & MIDI 2.0 CLAP supports three protocols for per-note expression: 1. MIDI 2.0 protocol messages 2. CLAP note expressions (native) 3. MPE (MIDI Polyphonic Expression) 2.1 Supported Note Expressions CLAP note expressions support per-note: - Pitch Bend - Volume - Pan - Expression - Brightness - Vibrato Depth - Aftertouch 2.2 Implementing Note Ports Your plugin must implement the note port extension to receive note input: The host will then send events via the appropriate protocol. You can choose to support MIDI 2.0, CLAP note expressions, or MPE—or all three. 2.3 Working with Note Expression Events When processing note events, you'll receive per-note expression values: --- 3. Multi-Core Processing with the Thread Pool CLAP provides a thread pool extension that lets plugins leverage modern multi-core CPUs efficiently. 3.1 Declaring Thread Pool Support 3.2 Using the Host's Thread Pool In your process() function, request parallel execution: Important considerations: - Using a thread pool may break hard real-time rules due to synchronization overhead - The host may decide not to provide this interface under real-time pressure - requestexec() blocks until all tasks complete and must be called from the audio thread --- 4. Parameter Synchronization Between Threads CLAP plugins typically run on two threads: the audio thread (real-time) and the main/GUI thread. Proper synchronization is critical. 4.1 Thread-Safe Parameter Access Pattern From the Nakst tutorial: Pro tip: While mutexes work, consider lock-free structures for production code to avoid priority inversion. 4.2 The flush() Mechanism When the GUI changes a parameter, call requestflush(): --- 5. Undo Integration CLAP's undo extension enables seamless integration with the host's undo system: This makes your plugin feel as native as the host's own devices and improves crash recovery. --- 6. Remote Controls & Hardware Mapping The remote controls extension (draft) allows plugins to define custom pages for hardware controllers: --- 7. Best Practices & Performance Tips 7.1 Use the clap-saw-demo as a Reference The Surge Synthesizers team created a clap-saw-demo that demonstrates: - Polyphonic parameter modulation - Note expression support - VSTGUI integration without frameworks Start with clap-saw-demo.h to understand the modulation system. 7.2 Rapid Plugin Scanning CLAP doesn't use manifests (unlike VST3), resulting in significantly faster startup times. 7.3 Thread Checking Use the thread-check extension to validate thread correctness during development: 7.4 Parameter Rescan When parameter definitions change dynamically, call: 7.5 Gesture Events Wrap parameter changes with gesture begin/end events for smooth host automation: --- 8. Summary: CLAP's Advanced Feature Set | Feature | Benefit | |---------|---------| | Per-note modulation | Individual expression per voice—unmatched by VST3 | | MIDI 2.0 / MPE | Full next-generation MIDI support | | Thread pool | Efficient multi-core processing | | Undo integration | Native-feeling undo across host and plugin | | Open source (MIT) | No royalties, no license fees | | Future-proof | Extensible design for emerging standards | --- Resources for Further Learning 1. Official CLAP SDK: github.com/free-audio/clap 2. clap-saw-demo: github.com/surge-synthesizer/clap-saw-demo – Reference implementation with polyphonic modulation 3. Nakst Tutorial: nakst.gitlab.io/tutor…