Introduction

One of the main pain point with developing a VST plugin is that it is very hard to even know where to start. The recommended approach is to copy/paste one of the example plugin and modify it. But it is not very clear what should or shouldn’t be changed. Nor is it obvious which command to run and with which parameters to start the editor, run the validation steps, generate an audio unit wrapper, etc… It turns out that none of it is trivial and is either poorly or simply not documented.

Jamba was specifically designed to simplify all this by

providing a very easy way to generate a blank/skeleton plugin with all the necessary boiler plate code in the right place

providing a way to automatically download and setup the required dependencies

providing a very simple to use script (jamba.sh / jamba.bat) which takes care of invoking the proper cmake targets with the proper parameters and dependencies

Step 1 - Generate the skeleton plugin

You have 2 options to do this:

you can follow the Web steps which lets you provide the information necessary directly in the browser and generate a zip file with the plugin ready to build. This is the recommended approach since you do not have to download and/or clone anything locally

you can follow the Command Line steps which involves cloning the github repository and locally running a python script which will ask a few questions

Both options will end up generating a “blank” plugin which is a fully buildable, testable, editable and deployable plugin, which simply copies the stereo input to the stereo output so that it is easy to build from there.

Tip

Once the plugin is generated, feel free to edit/modify any file you want as the generating phase is only meant to be run once in order to quickly get a plugin with all the pieces (and boilerplate code) in place.

Step 2 - Run the configure script

The plugin contains a configure.sh script for macOS (resp. configure.bat for Windows) that you run from wherever you want the build to happen. A build subdirectory of the directory from which you run the command will be created. This script is a very small wrapper around cmake to invoke it with the proper arguments.

Please ignore the output about SMTG_MYPLUGINS_SRC_PATH not being set as it is displayed by the VST SDK but Jamba does not use it.

Tip

The main point of running this command is to download all the dependencies and setup the jamba.sh (resp. jamba.bat) main script that you will use in the next step. You should not have to rerun this command afterwards.

Tip

After this step, you can open the project in XCode (resp. Visual Studio) as the project has been created in the build folder generated (ex: Kooza.xcodeproj). Note that you can also open the project directly in CLion without even running this step since CLion natively supports cmake.

Step 3 - Build and test the plugin

The skeleton plugin main processing code simply copies the (stereo) input to the output. It is now ready to be built and tested. For this you use the jamba.sh (resp. jamba.bat) script that was generated during Step 2.

Tip

Check the jamba.sh documentation page for more details about the command.

Running jamba.sh -h (resp. jamba.bat -h) gives you the list of all commands the script understands.

Step 4 - Run the editor

Let’s now run the editor which is another tool that comes with the VST SDK and which lets you build, in a WYSIWIG fashion, the UI of your plugin.

> jamba.sh edit
...

You should see something like this (after you right click in the window and select Open UIDescription Editor).

The skeleton plugin UI only contains 2 text labels that gives you instructions on what to do:

right click to open the editor

select menu File / Save as to save the xml file (which represents the UI) with the proper name in its proper location (should be under <PLUGIN_ROOT>/resource/<PLUGIN_NAME>.uidesc as shown in the UI). After saving it the first time, you can simply select File / Save (or use the shortcut) once you make modifications.

Step 5 - Install the plugin

Now that the plugin builds properly (and pass validation), you should install it to be able to try it right away in your favorite DAW. Since the blank plugin is essentially a passthrough effect (copies input to output), you should be able to:

see the plugin listed in the list of plugins of your favorite DAW (the plugin name will be <xxx>_Debug since we are building in debug mode, for example Kooza_Debug in this example)

add the plugin as an effect to any instrument and verify that you can still hear the output of the instrument (passthrough)

Step 6 - Add your own files

You are now ready to start implementing the logic of your plugin by adding new files

Adding source files

When you add new source files, add them to the CMakeLists.txt file in the vst_sources section (feel free to change the CMakeLists.txt to your liking, for example if you want to include all files without having to explicitly add them, although not recommended, this is possible… refer to cmake for more info).

Adding (unit) test files

When you add new tests files, they are added automatically as long as they are located under test/cpp. Jamba integrates with Google Test for unit testing but feel free to use something different if you want to.

Adding resource files (GUI)

Tip

The way macOS and Windows handle GUI resources is very different (Info.plist vs .rc file). Thankfully Jamba makes it easy and will generate the right file for the right platform if you use the jamba_add_vst3_resource function as described below.

When you add new resources for the GUI (images for example), they need to be added to CMakeLists.txt:

In the UI editor when adding a bitmap and saving the xxx.uidesc file, the fullpath of the image might be recorded. Make sure to edit the xxx.uidesc and modify it to keep ONLY the filename

<!-- this is WRONG!!!!! -->
<bitmap name="background" path="/private/tmp/pongasoft-Kooza-plugin/resource/background.png"/>
<!-- this is right -->
<bitmap name="background" path="background.png"/>

Tip

cmake automatically detects changes to CMakeLists.txt so you should not have to do anything special when you make any changes.

Step 7 - Next

Here are some recommended steps:

If you have never written a VST3 plugin I would suggest reading the VST3 documentation that comes with the SDK (you can find more information on the concepts, how the editor works, etc…). At the end of the day you are still writing a VST3 plugin not a Jamba plugin! Simply open the index.html file at the root of the SDK.

Check jamba-sample-gain for documentation and explanation of the Jamba concepts and in particular:

Check <Name>.h which is where you define the Vst (and Jmb) parameters your plugin will use

Check RT/<Name>Processor.cpp which contains the main logic of the plugin

Use the editor to change the UI of the plugin (which then saves the resource/<Name>.uidesc xml file). You can edit the xml file by hand, but it is definitely recommended to use the editor to do so.

Check <Name>_VST2.cpp on instructions about how to register the VST2 plugin ID with Steinberg (unfortunately this is a manual process). You don’t have to do this right away… only when you are ready to release your plugin.

Check the VST3 SDK section so that the VST3 SDK is installed for all your plugins instead of being donwloaded with each one.

Tip

If you have followed the quickstart steps, the SDK has been downloaded during Step 2 so you can simply copy it in a more permanent location.