Quickstart - iPlug2

Get up and running with iPlug2 by creating a simple audio effect plugin. This guide will walk you through duplicating an example project and building your first plugin.

Prerequisites

Before starting, ensure you have:

A C++ development environment (Xcode on macOS or Visual Studio 2019+ on Windows)
CMake 3.14 or later
Git (for cloning the repository)
Basic understanding of C++ and audio programming concepts

Make sure you’ve completed the installation steps before proceeding.

Create Your First Plugin

Clone the iPlug2 repository

Start by cloning the iPlug2 repository to your local machine:

git clone https://github.com/iPlug2/iPlug2.git
cd iPlug2

Download required SDKs

Download the VST3, CLAP, and WAM SDKs (these are free and publicly available):

cd Dependencies/IPlug
./download-iplug-sdks.sh
cd ../..

AAX (Pro Tools) requires manually downloading the SDK from Avid’s developer portal. AUv2/AUv3 formats are macOS-only and require no additional SDKs.

Duplicate the example project

Use the duplicate script to create your plugin from the IPlugEffect template:

cd Examples
./duplicate.py IPlugEffect MyGainPlugin YourCompany

This creates a new project at Examples/MyGainPlugin/ with all files renamed and configured.

macOS/Linux
Windows

./duplicate.py IPlugEffect MyGainPlugin YourCompany

python duplicate.py IPlugEffect MyGainPlugin YourCompany

Build with CMake

Build your plugin using CMake:

macOS
Windows

cd MyGainPlugin
mkdir build && cd build
cmake -G Ninja -DCMAKE_BUILD_TYPE=Release ..
ninja

cd MyGainPlugin
mkdir build && cd build
cmake -G "Visual Studio 17 2022" -A x64 ..
cmake --build . --config Release

By default, plugins are automatically deployed to system plugin folders. Find them in:

macOS: ~/Library/Audio/Plug-Ins/VST3, ~/Library/Audio/Plug-Ins/CLAP
Windows: %LOCALAPPDATA%\Programs\Common\VST3, %LOCALAPPDATA%\Programs\Common\CLAP

Test your plugin

Open your DAW (Reaper, Ableton Live, Logic Pro, etc.) and scan for new plugins. Your plugin should appear as “MyGainPlugin” by “YourCompany”.

Understanding the Code

Your new plugin consists of three main files:

config.h

Defines plugin metadata and configuration:

config.h

#define PLUG_NAME "MyGainPlugin"
#define PLUG_MFR "YourCompany"
#define PLUG_VERSION_HEX 0x00010000
#define PLUG_UNIQUE_ID 'Mgpl'  // Auto-generated unique 4-char ID
#define PLUG_MFR_ID 'Ycmp'
#define PLUG_CHANNEL_IO "1-1 2-2"  // Supports mono and stereo

MyGainPlugin.h

Declares the plugin class and parameter enum:

MyGainPlugin.h

#pragma once

#include "IPlug_include_in_plug_hdr.h"

const int kNumPresets = 1;

enum EParams
{
  kGain = 0,
  kNumParams
};

using namespace iplug;
using namespace igraphics;

class MyGainPlugin final : public Plugin
{
public:
  MyGainPlugin(const InstanceInfo& info);

#if IPLUG_DSP
  void ProcessBlock(sample** inputs, sample** outputs, int nFrames) override;
#endif
};

MyGainPlugin.cpp

Implements the plugin constructor and audio processing:

MyGainPlugin.cpp

#include "MyGainPlugin.h"
#include "IPlug_include_in_plug_src.h"
#include "IControls.h"

MyGainPlugin::MyGainPlugin(const InstanceInfo& info)
: iplug::Plugin(info, MakeConfig(kNumParams, kNumPresets))
{
  // Initialize parameter (name, default, min, max, step, unit)
  GetParam(kGain)->InitDouble("Gain", 0., 0., 100.0, 0.01, "%");

#if IPLUG_EDITOR
  mMakeGraphicsFunc = [&]() {
    return MakeGraphics(*this, PLUG_WIDTH, PLUG_HEIGHT, PLUG_FPS, 
                        GetScaleForScreen(PLUG_WIDTH, PLUG_HEIGHT));
  };
  
  mLayoutFunc = [&](IGraphics* pGraphics) {
    pGraphics->AttachCornerResizer(EUIResizerMode::Scale, false);
    pGraphics->AttachPanelBackground(COLOR_GRAY);
    pGraphics->LoadFont("Roboto-Regular", ROBOTO_FN);
    
    const IRECT bounds = pGraphics->GetBounds();
    const IRECT innerBounds = bounds.GetPadded(-10.f);
    
    // Add title text
    pGraphics->AttachControl(
      new ITextControl(innerBounds.GetMidVPadded(50), 
                       "Hello iPlug 2!", 
                       IText(50))
    );
    
    // Add gain knob linked to parameter
    pGraphics->AttachControl(
      new IVKnobControl(innerBounds.GetCentredInside(100).GetVShifted(-100), 
                        kGain)
    );
  };
#endif
}

#if IPLUG_DSP
void MyGainPlugin::ProcessBlock(sample** inputs, sample** outputs, int nFrames)
{
  const double gain = GetParam(kGain)->Value() / 100.;
  const int nChans = NOutChansConnected();
  
  for (int s = 0; s < nFrames; s++) {
    for (int c = 0; c < nChans; c++) {
      outputs[c][s] = inputs[c][s] * gain;
    }
  }
}
#endif

The ProcessBlock method must be realtime-safe: no memory allocations, no locks, no file I/O, no system calls.

Key Concepts

Parameters

Parameters are fixed at compile time and indexed by enum. Use non-normalized values (e.g., 0-100 for percentage).

ProcessBlock

The audio processing callback. Must be realtime-safe with no allocations or blocking operations.

IGraphics

Optional GUI toolkit with NanoVG (fast) or Skia (high quality) backends. Can be replaced with SwiftUI, WebView, etc.

Cross-platform

Single codebase targets VST3, CLAP, AUv2, AUv3, AAX, and standalone apps on macOS, Windows, iOS, and Web.

Next Steps

Explore Examples

Check out IPlugInstrument for a synthesizer template and IPlugControls for UI widgets.

API Documentation

Browse the complete API reference with detailed class documentation.

Community Forum

Join the iPlug2 community for help, tips, and discussion.

Discord Server

Chat with other developers in real-time on the iPlug2 Discord.

Customizing Your Plugin

Add More Parameters

Expand the EParams enum and initialize new parameters:

enum EParams
{
  kGain = 0,
  kPan,      // New parameter
  kNumParams
};

// In constructor:
GetParam(kPan)->InitDouble("Pan", 0., -100., 100., 0.01, "%");

Modify Audio Processing

Implement your DSP algorithm in ProcessBlock:

void MyGainPlugin::ProcessBlock(sample** inputs, sample** outputs, int nFrames)
{
  const double gain = GetParam(kGain)->Value() / 100.;
  const double pan = GetParam(kPan)->Value() / 100.;  // -1 to 1
  const int nChans = NOutChansConnected();
  
  if (nChans == 2) {
    // Stereo panning
    const double leftGain = gain * (pan <= 0 ? 1.0 : 1.0 - pan);
    const double rightGain = gain * (pan >= 0 ? 1.0 : 1.0 + pan);
    
    for (int s = 0; s < nFrames; s++) {
      outputs[0][s] = inputs[0][s] * leftGain;
      outputs[1][s] = inputs[1][s] * rightGain;
    }
  } else {
    // Mono processing
    for (int s = 0; s < nFrames; s++) {
      for (int c = 0; c < nChans; c++) {
        outputs[c][s] = inputs[c][s] * gain;
      }
    }
  }
}

Add UI Controls

Add more controls in the mLayoutFunc lambda:

// Add pan knob
pGraphics->AttachControl(
  new IVKnobControl(bounds.GetCentredInside(100).GetVShifted(50), 
                    kPan, 
                    "Pan")
);

// Add ADSR sliders
pGraphics->AttachControl(
  new IVSliderControl(bounds.GetGridCell(0, 1, 4), kAttack, "Attack")
);

Use pGraphics->EnableLiveEdit(true) during development to adjust UI layout in real-time without recompiling.

Build Options

Build Specific Formats

Build only the formats you need:

# Build only VST3
ninja MyGainPlugin-vst3

# Build only standalone app
ninja MyGainPlugin-app

# Build VST3 and CLAP
ninja MyGainPlugin-vst3 MyGainPlugin-clap

Universal Binary (macOS)

Build for both Intel and Apple Silicon:

cmake -G Ninja -DIPLUG2_UNIVERSAL=ON -DCMAKE_BUILD_TYPE=Release ..
ninja

Debug Build

Build in debug mode for better error messages:

cmake -G Ninja -DCMAKE_BUILD_TYPE=Debug ..
ninja

Debug builds are much larger and slower. Use Release builds for distribution.

Troubleshooting

Plugin doesn't appear in DAW

Verify the build succeeded without errors
Check the plugin was deployed to the correct folder
Rescan plugins in your DAW
On macOS, you may need to clear the Audio Unit cache:

killall -9 AudioComponentRegistrar

Build errors about missing SDKs

Ensure you ran download-iplug-sdks.sh in Dependencies/IPlug/
Check that Dependencies/IPlug/VST3_SDK/ exists
For AAX, download the SDK manually from Avid

CMake can't find iPlug2

Ensure IPLUG2_DIR points to the iPlug2 root directory:

cmake -DIPLUG2_DIR=/path/to/iPlug2 ..

Audio glitches or clicks

Ensure ProcessBlock is realtime-safe (no allocations)
Check buffer size handling
Use std::atomic for thread-safe parameter access
Enable the tracer build to profile performance: cmake -DIPLUG2_TRACER=ON ..

Alternative Build Systems

While CMake is recommended, iPlug2 also supports:

Xcode projects (macOS): Open projects/MyGainPlugin-macOS.xcodeproj
Visual Studio projects (Windows): Open projects/MyGainPlugin-vst3.vcxproj
Makefiles (Web/WASM): Use .mk files in projects/

CMake is the most flexible option and works across all platforms. The Xcode/VS projects are auto-generated and easier for beginners.

​Prerequisites

​Create Your First Plugin

​Understanding the Code

​config.h

​MyGainPlugin.h

​MyGainPlugin.cpp

​Key Concepts

Parameters

ProcessBlock

IGraphics

Cross-platform

​Next Steps

Explore Examples

API Documentation

Community Forum

Discord Server

​Customizing Your Plugin

​Add More Parameters

​Modify Audio Processing

​Add UI Controls

​Build Options

​Build Specific Formats

​Universal Binary (macOS)

​Debug Build

​Troubleshooting

​Alternative Build Systems

Prerequisites

Create Your First Plugin

Understanding the Code

config.h

MyGainPlugin.h

MyGainPlugin.cpp

Key Concepts

Next Steps

Customizing Your Plugin

Add More Parameters

Modify Audio Processing

Add UI Controls

Build Options

Build Specific Formats

Universal Binary (macOS)

Debug Build

Troubleshooting

Alternative Build Systems