A simple tremolo audio effect plugin (AAX/AU/CLAP/VST2/VST3) for Windows and macOS, serving as an example for the IPlug "Tale" Edition plugin framework.
To be able to build this example you will need the following (free) tools and additional projects:
Note that this readme describes the toolset we actually use at Martinic. You could probably use a different toolset, but then things will likely not work right out of the box.
For Windows we use the Microsoft Visual Studio 2022 C/C++ compiler, although any somewhat recent Microsoft C/C++ toolset should work. You can download the free Visual Studio Community edition via:
https://visualstudio.microsoft.com/downloads/
For macOS you will need the Xcode 13 or newer IDE. Before downloading Xcode first sign in to Apple Developer via:
https://developer.apple.com/account/
Then you can download Xcode (and optionally the Additional Tools for Xcode) via:
https://developer.apple.com/download/all/
Alternatively you can download Xcode from the Mac App Store.
You can download the IPlug example project (i.e. this project) from:
https://github.com/TaleTN/IPlugExample
If you use Git, then alternatively you can clone the example project:
mkdir IPlugExample
cd IPlugExample
git clone https://github.com/TaleTN/IPlugExample.git .
IPlug is a cross-platform AAX/AU/CLAP/VST2/VST3 plugin framework for Windows and macOS, on which you can build audio plug-in effects and instruments. It was originally part of the Cockos WDL library, but it has since evolved into different forks like IPlug "Tale" Edition and iPlug2 (formerly WDL-OL). Note that this example will work only with IPlug "Tale" Edition.
You can download IPlug "Tale" Edition from:
https://github.com/TaleTN/IPlug
Extract it so you have:
IPlugExample/IPlugExample.cpp, ...
IPlugExample/IPlug/IPlugBase.cpp, ... <-- IPlug goes here
If you use Git, then alternatively you can add IPlug as a remote:
git remote add iplug https://github.com/TaleTN/IPlug.git
git fetch iplug
git merge --allow-unrelated-histories iplug/main
For your own projects this is the recommended method.
WDL (whittle) is a C++ library, created and maintained by Cockos, and used for REAPER. Although IPlug "Tale" Edition will work fine with Cockos WDL, using WDL "Tale" Edition instead is recommended, because that is what we use at Martinic. 😉
You can download WDL "Tale" Edition from:
https://github.com/TaleTN/WDL
Extract it so you have:
IPlugExample/IPlugExample.cpp, ...
IPlugExample/IPlug/Containers.h, ...
IPlugExample/WDL/assocarray.h, ... <-- WDL goes here
Alternatively you can add WDL as a remote:
git remote add wdl https://github.com/TaleTN/WDL.git
git fetch wdl
git merge --allow-unrelated-histories wdl/main
For your own projects this is the recommended method.
For CLAP support you will need the CLAP ABI headers. You can download CLAP from:
https://github.com/free-audio/clap
You will only need the header files in include/clap
. Extract them and
place them in CLAP_SDK
so you have:
IPlugExample/IPlugExample.cpp, ...
IPlugExample/IPlug/Containers.h, ...
IPlugExample/WDL/assocarray.h, ...
IPlugExample/CLAP_SDK/audio-buffer.h, ... <-- CLAP_SDK goes here
For VST 2.4 support you will need only two header files from the VST 2.4
SDK: aeffect.h
and aeffectx.h
. Extract them and place them in
VST2_SDK
so you have:
IPlugExample/IPlugExample.cpp, ...
IPlugExample/IPlug/Containers.h, ...
IPlugExample/WDL/assocarray.h, ...
IPlugExample/VST2_SDK/aeffect.h, aeffectx.h <-- VST2_SDK goes here
You will find these header files in the pluginterfaces/vst2.x
directory
inside the VST 2.4 or VST 3 SDK,
but you will need v3.6 or older. You used to be able to download v3.6.6
here:
https://www.steinberg.net/sdk_downloads/vstsdk366_27_06_2016_build_61.zip
However, it would seem that it is no longer available, courtesy of Steinberg.
For VST 3 support you will need the VST 3 Audio Plug-Ins SDK from Steinberg, which you can download from here:
https://www.steinberg.net/developers/
The VST 3 SDK comes as a ZIP file, and you will need only three directories
from VST_SDK/vst3sdk/
within this ZIP: base
, pluginterfaces
, and
public.sdk
. Extract them and place them in VST3_SDK
so you have:
IPlugExample/IPlugExample.cpp, ...
IPlugExample/IPlug/Containers.h, ...
IPlugExample/WDL/assocarray.h, ...
IPlugExample/VST3_SDK/base/* <-- VST3_SDK goes here
IPlugExample/VST3_SDK/pluginterfaces/*
IPlugExample/VST3_SDK/public.sdk/*
For AAX (Pro Tools) support you will need the AAX SDK from Avid, which you can download from here:
https://my.avid.com/products/cppsdk (developer account required)
The AAX SDK comes as a ZIP file, from which you will need only three
directories: Interfaces
, Libs/AAXLibrary/include
, and
Libs/AAXLibrary/sources
. Extract them and place them in AAX_SDK
so
you have:
IPlugExample/IPlugExample.cpp, ...
IPlugExample/IPlug/Containers.h, ...
IPlugExample/WDL/assocarray.h, ...
IPlugExample/AAX_SDK/Interfaces/AAX.h, ... <-- AAX_SDK goes here
IPlugExample/AAX_SDK/Libs/AAXLibrary/include/*
IPlugExample/AAX_SDK/Libs/AAXLibrary/source/*
On Windows open the IPlugExample.sln
solution in
Visual Studio 2022, and build the CLAP plugin from within the IDE.
Alternatively you can build the CLAP plugin (as well as the other plugin
formats) from the command prompt by typing:
cd IPlugExample
nmake clap
nmake vst2
nmake vst3
nmake aax
Note that building from the command prompt should work with any somewhat recent Microsoft C/C++ toolset.
To run the plugin copy IPlugExample.clap
(CLAP), IPlugExample.dll
(VST2), or IPlugExample.vst3
(VST3) from IPlugExample/x64/Release/
to
your CLAP, VST 2.4, or VST 3 plugin path. Then launch your hosting software
of choice (e.g. REAPER or
VSTHost), and load the
IPlug Example plugin.
To run the AAX plugin copy IPlugExample.aaxplugin
from
IPlugExample/x64/Release/
to:
C:\Program Files\Common Files\Avid\Audio\Plug-Ins\IPlugExample.aaxplugin\Contents\x64\
Then launch Pro Tools Developer, and load the IPlug Example (stereo) plugin (under multichannel plug-in > Effect).
On macOS open the IPlugExample.xcodeproj
project
in Xcode, and build the AAX, AU, CLAP, and/or VST2 target from within the
IDE. If you build for running, then this will automatically copy the plugin
to the (user) audio plugins folder.
To run the plugin launch your hosting software of choice (e.g. REAPER or GarageBand), and load the IPlug Example plugin. The first time you build the AU plugin macOS might not see it unless you restart your computer, or run the following command from the terminal:
killall -9 AudioComponentRegistrar
Note that even if you build a release version of the plugin, by default it
won't have the NDEBUG
macro defined. This is great for testing, because it
means you can still use IPlugBase::DebugLog()
to log to
DebugView
(Windows) or Console (macOS).
To build a production release you can run the makedist.cmd
(Windows) or ./makedist.sh
(macOS) scripts from the command
prompt or terminal. A next step would be to bundle production releases in a
ZIP file or installer, but that is beyond the scope of this example.
WDL license, see License.txt.