Skip to content
Documentation plugin for Jamba framework: a simple gain plugin for VST2/3
C++ CMake C Other
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
archive added Audio Unit support Oct 6, 2018
audio-unit Changed plugin code to be unique Oct 6, 2018
images Added screenshot Aug 25, 2018
mac
resource use jamba_add_vst3_resource Sep 19, 2018
src/cpp Use latest Jamba 4.0.0 / C++17 Oct 26, 2019
test/cpp
.gitignore first commit - simply copy in to out Aug 10, 2018
CMakeLists.txt
LICENSE.txt first commit - simply copy in to out Aug 10, 2018
README.md Use latest Jamba 4.0.0 / C++17 Oct 26, 2019
configure.bat Upgraded to Visual Studio 16 / 2019 Oct 26, 2019
configure.sh added Audio Unit support Oct 6, 2018
jamba.cmake Use latest Jamba 4.0.0 / C++17 Oct 26, 2019
vst369.cmake Use latest Jamba 4.0.0 / C++17 Oct 26, 2019

README.md

Jamba Sample - Simple Gain plugin

The goal of this project is to serve as documentation for the Jamba framework. It shows some of the most important features of the framework. The code is heavily documented to explain the various concepts and features. The end result for this project is a plugin similar to the again example plugin provided with the VST SDK.

If you just want to build the project then skip to Configuration.

If you want to create your own plugin, check Quick Starting Guide.

This is what the plugin looks like:

JSGain

Concepts

Jamba is a set of helpers (classes, concepts, build files, etc...) built on top of the VST SDK to provide a lightweight framework to build a VST2/3 plugin.

Parameters

VST parameters are what the host DAW deal with (for example a knob is usually tied to a VST parameter). Both the GUI and the RT (Real Time) are "sharing" those parameters. As a result Jamba makes them front and center: you define them in one place and use them in the GUI and RT. Check the file JSGainPlugin.h

Note: the Jamba framework introduces a new kind of parameters that go beyond VST parameters (which are limited to a double value in the range [0.0, 1.0]).

| ID   | TITLE      | TYP | OW | TRS | SHA | DEF.N | DEF.S          | STP | FLG   | SHORT  | PRE | UID | UNS |
--------------------------------------------------------------------------------------------------------------
| 1000 | Bypass     | vst | rt |     |     | 0.000 | Off            | 1   | 65537 | Bypass | 4   | 0   |     |
--------------------------------------------------------------------------------------------------------------
| 2010 | Left Gain  | vst | rt |     |     | 0.700 | +0.00dB        | 0   | 1     | GainL  | 2   | 0   |     |
--------------------------------------------------------------------------------------------------------------
| 2011 | Right Gain | vst | rt |     |     | 0.700 | +0.00dB        | 0   | 1     | GainR  | 2   | 0   |     |
--------------------------------------------------------------------------------------------------------------
| 2012 | Link       | vst | ui |     |     | 1.000 | On             | 1   | 1     | Link   | 4   | 0   |     |
--------------------------------------------------------------------------------------------------------------
| 2020 | Reset Max  | vst | rt |     |     | 0.000 | Off            | 1   | 1     | Reset  | 4   | 0   |     |
--------------------------------------------------------------------------------------------------------------
| 2000 | VuPPM      | vst | rt | x   |     | 0.000 | 0.0000         | 0   | 1     | VuPPM  | 4   | 0   |     |
--------------------------------------------------------------------------------------------------------------
| 3000 | Stats      | jmb | rt | x   | x   |       | -oo            |     |       |        |     |     |     |
--------------------------------------------------------------------------------------------------------------
| 2030 | Input Text | jmb | ui |     |     |       | Hello from GUI |     |       |        |     |     |     |
--------------------------------------------------------------------------------------------------------------
| 3010 | UIMessage  | jmb | ui | x   | x   |       |                |     |       |        |     |     |     |
--------------------------------------------------------------------------------------------------------------

This table (generated by the plugin) shows the parameters used by the plugin.

State

Jamba helps you deal with the state. From the parameters that you declare, you then define a RTState subclass (for the Real Time / processing code) and a GUIState subclass (for the GUI). Jamba then deals with the details of reading/writing the state in a thread safe fashion. Check the file JSGainPlugin.h

This is what the JSGainRTState will read/save:

Version=1
| ID   | TITLE      |
---------------------
| 1000 | Bypass     |
---------------------
| 2010 | Left Gain  |
---------------------
| 2011 | Right Gain |
---------------------
| 2020 | Reset Max  |
---------------------

This is what the JSGainGUIState will read/save:

Version=1
| ID   | TITLE      |
---------------------
| 2012 | Link       |
---------------------
| 2030 | Input Text |
---------------------

RT Processor

The Real Time (RT) processing code is where the main logic of the plugin resides. The DAW repeatedly calls the process method (actually processInputs32Bits or processInputs64Bits in Jamba) to process a batch of samples. This is usually called a "frame". The processor uses the RTState class. You simply need to inherit from RTProcessor. Check the file JSGainProcessor.h

GUI Controller

The entry point of the GUI is the GUI controller. Jamba takes care of most of the details of the implementation for you: you simply need to inherit from GUIController. The controller uses the GUIState class (and makes it available to all the views). Check the file JSGainController.h.

Views

Each item in the UI is represented by a view (ex: a label, a knob, a slider, etc...). Jamba makes it very easy to create custom views which can implement complex behavior since they get access to the state. Check the 3 views provided as examples: JSGainStatsView.h, JSGainSendMessageView.h and LinkedSliderView.h.

Testing

Jamba also helps in providing an out of the box solution for (unit) testing using google test. Check test-JSGain.cpp (and CMakeLists.txt).

UI Editor

Once the plugin is running, you can right click on the background and select "Open UIDescription Editor" in order to enter the UI editor (only available in Debug build) that comes built-in with the VST3 SDK.

Configuration

The VST SDK will be automatically downloaded during the configure phase. This project requires C++17 and CMake 3.12+. See Jamba Requirements for more details.

Build this project

The following steps describes (for each platform) how to build the plugin.

macOS

  • For simplicity I am creating the build at the root of the source tree, but can obviously be outside the source tree entirely by running the script from anywhere

      ./configure.sh
      cd build
    
  • In order to build, test, validate, etc... simply use the jamba.sh script like this:

       ./jamba.sh -h
       Usage:  jamba.sh [-hdrn] <command>
    
         -h : usage help
         -d : use Debug build config (default)
         -r : use Release build config (Debug if not defined)
         -n : dry run (prints what it is going to do)
    
       Commands: 
         ---- VST Commands ----
         clean    : clean all builds
         build    : build the VST plugin
         edit     : start the GUI editor (Debug only)
         install  : install the VST plugin in their default location
         test     : run the unit tests
         validate : run the VST3 validator
         ---- Audio Unit Commands ----
         build-au    : build the Audio Unit wrapper plugin
         install-au  : install the Audio Unit plugin in its default location
         validate-au : run the Audio Unit validator
         ---- Generic Commands ----
         archive : generate the zip file containing the plugin(s) and README/License
         prod    : run test/validate/archive (default to Release, override with -d)
         ---- CMake target ----
         <target> : invoke cmake with the provided target
    

Note: You can load the project directly in CLion (since CLion does not support the Xcode cmake generator, you can still work on the plugin but in order to build and install the Audio Unit wrapper you will need to use the command line).

Windows

  • For simplicity I am creating the build at the root of the source tree, but can obviously be outside the source tree entirely by running the script from anywhere. Note that PowerShell is highly recommended.

      .\configure.bat
      cd build
    
  • In order to build, test, validate, etc... simply use the jamba.bat script like this:

       .\jamba.bat -h
       Usage:  jamba.bat [-hdrn] <command>
    
         -h : usage help
         -d : use Debug build config (default)
         -r : use Release build config (Debug if not defined)
         -n : dry run (prints what it is going to do)
    
       Commands: 
         ---- VST Commands ----
         clean    : clean all builds
         build    : build the VST plugin
         edit     : start the GUI editor (Debug only)
         install  : install the VST plugin in their default location
         test     : run the unit tests
         validate : run the VST3 validator
         ---- Generic Commands ----
         archive : generate the zip file containing the plugin(s) and README/License
         prod    : run test/validate/archive (default to Release, override with -d)
         ---- CMake target ----
         <target> : invoke cmake with the provided target
    

Release Notes

2019-05-20 - v1.2.1

  • updated README
  • use latest version of Jamba (v3.2.1)

2019-01-03 - v1.2.0

  • use latest version of Jamba (v3.0.0)

2018-10-06 - v1.1.0

  • use latest version of Jamba (v2.1.0)
  • Generate Audio Unit (wrapper) plugin
  • Upgraded to cmake 3.12
  • Consolidated dev scripts into a single jamba.sh (resp jamba.bat) script
  • Uses Xcode as the cmake generator on macOS

2018-08-28 - v1.0.1

  • changed build-prod.bat to use scripts

2018-08-25 - v1.0.0

  • first public release / free / open source

Misc

This project uses loguru for logging.

Licensing

GPL version 3

You can’t perform that action at this time.