VST Home

Welcome to the world of VST 3

This part of the Steinberg Developer Resource is a portal dedicated to developers of VST 3 plug-ins and VST 3 hosts. Almost everything you need for developing VST 3 plug-ins is explained in the sections below.

What is VST?

Virtual Studio Technology (VST) is an audio plug-in software interface that facilitates the integration of software synthesizers and effects in digital audio workstations (DAW).

• Use cases

Main benefits of VST 3

Here, you can find a non-exhaustive list of VST 3 benefits.

What is the VST 3 SDK?

The VST 3 SDK (Virtual Studio Technology Software Development Kit) is a collection of software development tools included in one package. This allows plug-in developers to create plug-ins in VST 3 format and host developers to load VST 3 plug-ins into a DAW or audio editor.

VST 3 licensing

• Steinberg VST usage guidelines
• What are the licensing options
• Which files fall under which license?
• Developer use cases (FAQs)

Getting Started

• VST 3 Links — Important links you will need for working with VST 3
• How to setup up my system for VST 3 — In order to build VST 3 plug-ins, you need the source code of the VST 3 (API: interface definition), an IDE/compiler, cmake and a VST 3 host application.
• Preparation on Windows — Generated VST 3 Microsoft Visual Studio Projects using the cmake files included in the SDK will create by default symbolic links for each built plug-in in the official VST 3 folder, in order to allow this on Windows you have to adapt the Group Policy of Windows. See Here!

Tutorials

• Building the examples included in the SDK
  • Building the examples included in the SDK on Windows
  • Building the examples included in the SDK on macOS
  • Building the examples included in the SDK on Linux
• Using cmake for building VST 3 plug-ins
• Generate a new plug-in with the Project Generator App
• Code your first plug-in
• Use VSTGUI to design a User Interface
• Advanced VST 3 techniques
• How to use the silence flags
• Guideline for replacing a VST 2 plug-in by a VST 3 plug-in
• Strings Conversion Helper
• Creating a cmake plug-in project from scratch
• Creating a plug-in with VST 3 SDK as an external project
• Switching to another VSTGUI submodule or branch

VST 3 Forum

Visit Steinberg's VST Developer Forum in order to get help with development, to submit bug reports, to request new features and to connect to other VST 3 developers:

Technical Documentation

Browse the VST 3 SDK's technical documentation. The full VST 3 API reference is only available in the VST 3 Package that you can download or find online here.

Miscellaneous

Copyrights and Glossary

/ VST Home

What is VST?

On this page:

• VST 3: New Standard for Virtual Studio Technology
• About the VST standard
• From the technical point of view

Related pages:

• Use cases
• Main benefits of VST 3
• What is the VST 3 SDK?

VST 3: New Standard for Virtual Studio Technology

With VST (Virtual Studio Technology), Steinberg established the world’s leading and most widely supported standard for plug-ins and virtual instruments in 1996. With VST 3 Steinberg releases the next major revision of Steinberg’s Virtual Studio Technology to the audio industry. VST 3 marks an important milestone in audio technology with a completely rewritten code base providing not only many new features but also the most stable and reliable VST platform ever. This combination of the latest technology and new features is the result of Steinberg’s twelve years of development experience as the leading plug-in interface provider. VST 3 has been designed to provide a technological and creative basis for many innovative and exciting new products for the audio industry, offering a new world of creative possibilities for instrument and effect plug-in users. The VST 3 SDK is available as a free technology, open in use for any developer.

About the VST standard

The Virtual Studio Technology (VST) interface is nothing short of a revolution in digital audio. Developed by Steinberg and first launched in 1996, VST creates a full, professional studio environment on your computer.VST allows the integration of virtual effect processors and instruments into your digital audio environment. These can be software recreations of hardware effect units and instruments or new creative effect components in your VST system. All are integrated seamlessly into VST compatible host applications like digital audio workstations (DAW). VST also allows easy integration of external equipment, allowing you to put together a system tailor-made to your needs. Being an open standard, the possibilities offered by VST have steadily been growing over the past decade. New virtual effect processors and virtual instruments are constantly being developed by Steinberg and of course dozens of other companies.

From the technical point of view

A VST plug-in is an audio processing component that is utilized within a host application. This host application provides the audio or/and event streams that are processed by the plug-in's code. Generally speaking, a VST plug-in can take a stream of audio data, apply a process to the audio, and return the result to the host application. A VST plug-in normally performs its process using the processor of the computer. The audio stream is broken into a series of blocks. The host supplies the blocks in sequence. The host and its current environment control the block-size. The VST plug-in maintains the status of all its own parameters relating to the running process: The host does not maintain any information about what the plug-in did with the last block of data it processed.

From the host application's point of view, a VST plug-in is a black box with an arbitrary number of inputs, outputs (Event (MIDI) or Audio), and associated parameters. The host needs no implicit knowledge of the plug-in's process to be able to use it. The plug-in process can use whatever parameters it wants, internally to the process, but depending on the capabilities of the host, it can allow the changes to user parameters to be automated by the host.

The source code of a VST plug-in is platform independent, but the delivery system depends on the platform architecture:

• On Windows, a VST plug-in is a multi-threaded DLL (Dynamic Link Library), recently packaged into a folder structure.
• On macOS X, a VST plug-in is a Mach-O Bundle.
• On Linux, a VST plug-in is a package.

VST Home / What is VST?

Use cases

On this page:

• Why use VST 3 SDK?
• Advantages of using VST 3 SDK
• Examples of VST 3 host applications (05/10/2023)

Related pages:

• Main benefits of VST 3

Why use VST 3 SDK?

There are different use cases you can realize by using the VST 3 SDK:

1. You are a plug-in developer and you want to create audio FX or instrument plug-ins which can be included and used in a VST 3 host application.

   • an audio FX plug-in is an audio processor effect taking audio as input and creating audio as output: such as Delay, Phaser, Compressor, Reverb, …
   • an instrument plug-in is a sound/audio generator, taking as input note events and creating audio as output: such as emulations of well-known hardware synths. There are 2 kinds of instrument plug-ins: virtual sample-based (using audio samples as the basis for sound generation) and virtual synth (using different types of synthesis: physical modelling, additive, subtractive, FM, sample-based, …)

2. You are a host developer and you want to load in your application VST 3 plug-ins:

   • audio FX and/or
   • instruments plug-ins.

Advantages of using VST 3 SDK

By using VST 3 SDK directly:

• you are sure to be compliant with the VST 3 format.
• developing your plug-in based on the VST 3 format allows you to support easily new VST 3 features that improve the integration of these plug-ins inside a DAW. Some 3rd party SDKs use only a common layer between all plug-in formats, limiting in this way the possibility for a better integration, for example exclusive VST 3 features:
  • context menu
  • dirty state
  • loading differentially a preset or a project
  • note expression
  • see other benefits of VST 3
• you get optimal integration of the VSTGUI tool with VST 3.
• it includes the major plug-in format wrappers: AAX, AUv3, AU.
• the included Validator allows you to check your plug-in's conformity to the VST 3 standard.

Examples of VST 3 host applications (05/10/2023)

/ VST Home

Main benefits of VST 3

On this page:

• 1. Improved Performance with the Silence Flag
• 2. Multiple Dynamic I/Os
• 3. Sample-accurate Automation
• 4. Logical Parameter Organization
• 5. Resizeable UI Editor
• 6. Mouse Over Support
• 7. Context Menu Support
• 8. Channel Context Information
• 9. Note Expression
• 10. 3D Audio Support
• 11. Factory Concept
• 12. Support Remote control Representation
• 13. Others

Related pages:

• What is the VST 3 SDK?

Here, you can find a non-exhaustive list of VST 3 benefits.

VST 3 is a general rework of the long-serving VST plug-in interface (VST 1 & VST 2) . It is not compatible with the older VST (1 & 2) versions, but it includes some new features and possibilities. We have redesigned the API to make it not only far easier and more reliable for developers to work with, but have also provided completely new possibilities for plug-ins. These include:

1. Improved Performance with the Silence Flag

Managing large plug-in sets and multiple virtual instruments on typical studio computer systems can often be difficult because of CPU performance limits. VST 3 helps to improve overall performance by applying processing to plug-ins only when audio signals are present on their respective inputs. Instead of always processing input signals, VST 3 plug-ins can apply their processing economically and only when it is needed.

2. Multiple Dynamic I/Os

VST 3 plug-ins are no longer limited to a fixed number of inputs and outputs, and their I/O configuration can dynamically adapt to the channel configuration. Side-chains are also very easily realizable. This includes the possibility to deactivate unused busses after loading and even reactivate those when needed. This cleans up the mixer and further helps to reduce CPU load.

3. Sample-accurate Automation

VST 3 also features vastly improved parameter automation with sample accuracy and support for ramped automation data, allowing completely accurate and rapid parameter automation changes.

4. Logical Parameter Organization

The VST 3 plug-in parameters are displayed in a tree structure. Parameters are grouped into sections which represent the structure of the plug-in. Plug-ins can communicate their internal structure for the purpose of overview, but also for some associated functionality (e.g. program lists). Parameters like “Cutoff” and “Resonance” could be grouped into a section called “Filter”. This makes searching for a certain parameters easier, such as on an automation track. This also allows for assigning a group of parameters to a specific MIDI Channel input and audio output bus.

5. Resizeable UI Editor

VST 3 introduces a new approach to plug-in GUIs through window resizing, allowing for extremely flexible use of valuable screen space.

6. Mouse Over Support

The host can ask the plug-in which parameter is under the mouse.

7. Context Menu Support

VST 3 defines a way to allow the host to add its own entries in the plug-in context menu of a specific parameter.

8. Channel Context Information

A VST 3 plug-in can access channel information where it is instantiated: name, color, ...

9. Note Expression

VST 3 defines with Note Expression a new way of event controller editing. The plug-in is able to break free from the limitations of MIDI controller events by providing access to new VST 3 controller events that circumvent the laws of MIDI and provide articulation information for each individual note (event) in a polyphonic arrangement according to its noteId.

10. 3D Audio Support

VST 3 supports new speaker configurations like Ambisonic, Atmos, Auro 3D or 22.2.

11. Factory Concept

VST 3 plug-in library could export multiple plug-ins and in this way replaces the shell concept of VST 2 (kPlugCategShell).

12. Support Remote control Representation

Remote controllers for audio and MIDI software applications have become increasingly popular. VST 3 offers far more flexible control of VST plug-ins by remote controllers. Using the knobs and faders on the control surface, parameters can be recorded, renamed and edited in many ways. Parameters that cannot be edited can be routed for display purposes to the control surface, for example, to show Gain Reduction on a compressor.

13. Others

While designing VST 3, we performed a careful analysis of the existing functionality of VST and rewrote the interfaces from scratch. In doing so, we focused a lot on providing clear interfaces and their documentation in order to avoid usage errors from the deepest possible layer. Some more features implemented specifically for developers include:

• More stable technical host/plug-in environment
• Advanced technical definition of the standard
• Modular approach
• Separation of UI and processing
• UTF16 for localized parameter naming
• Advanced preset system
• Multiple plug-ins per library
• VST 3 SDK package:
  • Test Host included
  • Automated testing environment
  • Validator (small command line Test Host)
  • Plug-in and host examples code included
  • Project Generator
  • ...

/ VST Home

What is the VST 3 SDK?

On this page:

• VST 3 SDK explained
• What is included
  • The VST 3 API
  • VST 3 Implementation Helper Classes
• VST 3 Plug-ins Examples
• VST 3 Plug-in Test Host
• VST 3 Project Generator
• Validator command line
• AudioHost
• EditorHost
• VST 3 Inspector
• VSTGUI
• AAX, AUv3 and AU wrappers
• iOS Inter-App Audio support
• VST 3 Licensing
• System requirements
• Download link
• Change history

VST 3 SDK explained

The VST 3 SDK (Virtual Studio Technology Software Development Kit) is a collection of software development tools included in one package. This allows plug-in developers to create plug-ins in VST 3 format and host developers to load VST 3 plug-ins into a DAW or audio editor.

What is included

The VST 3 SDK package contains:

The VST 3 API

This is a C++ interface defining how a VST 3 plug-in communicates with a host and vice versa. The heart of VST 3.

Check the folder "pluginterfaces/vst" of the SDK!

VST 3 Implementation Helper Classes

Some helper classes are provided, implementing some VST 3 interfaces for hosting and for creating VST 3 plug-ins. Simply derived your plug-in C++ classes from these helper classes.

Check the folder "public.sdk" of the SDK!

VST 3 Plug-ins Examples

The SDK includes some Plug-ins implementation examples.

VST 3 Plug-in Test Host

The SDK provides a test application called VST3PluginTestHost for Apple macOS X (x86_64/M1) and Microsoft Windows (64bits).

VST 3 Project Generator

This open source application (Win/macOS) allows you to generate easily a new VST 3 plug-in project by just entering in a GUI some parameters.

Validator command line

The validator is a small command line host application (source code included) which can be used to check your plug-in for VST 3 conformity.

AudioHost

Simple cross-platform (only tested on Linux) host application allowing you to register a VST 3 plug-in with Jack Server.

EditorHost

Simple cross-platform (Win/macOS/Linux) host application allowing you to open the editor of a VST 3 plug-in.

VST 3 Inspector

Simple cross-platform (Win/macOS/Linux) host application, built with VSTGUI, which scans the VST 3 Folder, collects information from the factory about each VST 3 plug-in and display it in its UI.

VSTGUI

This is a user interface toolkit mainly for audio plug-ins (VST, AudioUnit, etc). Based on the XML definition of the plug-in UI, VSTGUI includes an embedded editor (UIDescription Editor) which allows the developer to create a plug-in UI just by drag & drop of the UI element.

AAX, AUv3 and AU wrappers

These wrappers allow you to create versions of your VST 3 plug-in in other plug-in formats with minimum effort.

iOS Inter-App Audio support

iOS InterApp-Audio application out of your VST 3 plug-in

VST 3 Licensing

Please sign this Steinberg VST 3 Plug-In SDK Licensing Agreement if you want to develop, release or host VST 3 plug-Ins.

System requirements

Download link

Important links you will need for working with VST 3

Change history

All released versions of the VST 3 SDK with changes and dates.

/ VST Home / What is the VST 3 SDK?

VST 3 Plug-in Examples

On this page:

• Introduction
• ADelay
• AGain
• AGain Sample Accurate
• Test Channel Context
• Data Exchange
• VST3 Host Checker
• Test Legacy MIDI CC Out
• mda plug-ins
• Note Expression Synth
• Note Expression Text
• Panner
• PitchNames
• Test Prefetchable Support
• Test Program Change
• Test Multiple Program Changes
• Test Remap ParamID
• Sync Delay
• UTF16 Name

Related pages:

• VST 3 Plug-in Test Host
• AAX, AUv3 and AU Wrappers
• Building the examples included in the SDK on Windows
• Building the examples included in the SDK on macOS
• Building the examples included in the SDK on Linux

Introduction

The SDK includes some Plug-ins implementation examples. The Legendary AGain and ADelay, thanks Paul Kellet the Open-source mda Plug-ins, a basic Note Expression Synth supporting "Note Expression Event", an example of PitchNames support Plug-in, a VST 3 Host Checker which checks if a host is VST 3 compliant and more...

Check the folder "public.sdk/samples/vst" of the SDK!

ⓘ Note
They use cmake as project generator: Using cmake for building VST 3 plug-ins
In order to add your own Plug-ins check: Generate a new plug-in with the Project Generator App

ADelay

Very simple delay plug-in:

• only one parameter (a delay)

Check the folder "public.sdk/samples/vst/adelay" of the SDK!

Classes:

• ADelayProcessor
• ADelayController

AGain

The SDK includes an AGain plug-in which is a very simple VST 3 plug-in. This plug-in:

• is multichannel compatible
• supports bypass processing
• has an automated gain parameter
• has an Event input bus (allowing to use noteOn velocity to control the gain factor)
• has a VU peak meter
• uses the VSTGUI4 library
• a version of this plug-in with side-chaining is available (showing a plug-in using the same controller and different - components)
• an AAX version is available
• a AUv3 version is available

Check the folder "public.sdk/samples/vst/again" of the SDK!

Classes:

• AGain
• AGainWithSideChain (used for side-chain version)
• AGainController

AGain Sample Accurate

Simple plug-in showing how to achieve sample-accurate processing.

Based Check the folder "public.sdk/samples/vst/again_sampleaccurate" of the SDK!

Test Channel Context

Very simple plug-in:

• showing how to use the Steinberg::Vst::ChannelContext::IInfoListener interface
• using a generic UI

Check the folder "public.sdk/samples/vst/channelcontext" of the SDK!

Data Exchange

This plug-in:

• shows how to exchange data (waveform) between processor (in the realtime thread) and controller using the VST Data Exchange API: Vst::IDataExchangeHandler
• shows how easy it is to use VSTGUI

Check the folder "public.sdk/samples/vst/dataexchange" of the SDK!

VST3 Host Checker

• Instrument, Panner and Fx plug-in checking the VST 3 support of a host
• It uses VSTGUI
• an AAX version is available

Check the folder "public.sdk/samples/vst/hostchecker" of the SDK!

Test Legacy MIDI CC Out

Very simple plug-in:

• showing how to use LegacyMIDICCOutEvent which allow to generate MIDI CC as output event
• VST parameters change which creates LegacyMIDICCOutEvent Event

Check the folder "public.sdk/samples/vst/legacymidiccout" of the SDK!

Classes:

• LegacyMIDICCOut::Plug

mda plug-ins

• Effects (stereo to stereo plug-ins):
  • Ambience: Reverb.
  • Bandisto: Multi-band Distortion.
  • BeatBox: Drum Replacer.
  • Combo: Amp and Speaker Simulator.
  • DeEsser: High frequency Dynamics Processor.
  • Degrade: Sample quality reduction.
  • Delay: Simple stereo delay with feedback tone control.
  • Detune: Simple up/down pitch shifting thickener.
  • Dither: Range of dither types including noise shaping.
  • DubDelay: Delay with feedback saturation and time/pitch modulation.
  • Dynamics: Compressor / Limiter / Gate.
  • Image: Stereo image adjustment and M-S matrix.
  • Leslie: Rotary speaker simulator.
  • Limiter: Opto-electronic style limiter.
  • Loudness: Equal loudness contours for bass EQ and mix correction.
  • MultiBand: Multi-band compressor with M-S processing modes.
  • Overdrive: Soft distortion.
  • RePsycho!: Drum loop pitch changer.
  • RezFilter: Resonant filter with LFO and envelope follower.
  • RingMod: Simple Ring Modulator.
  • Round Panner: 3D panner.
  • Shepard: Continuously rising/falling tone generator.
  • SpecMeter: Stereo 13 Bands spectral Meter.
  • Splitter: Frequency / level crossover for setting up dynamic processing.
  • Stereo Simulator: Haas delay and comb filtering.
  • Sub-Bass Synthesizer: Several low frequency enhancement methods.
  • TalkBox: High resolution vocoder.
  • TestTone: Signal generator with pink and white noise, impulses and sweeps.
  • Thru-Zero Flanger: Classic tape-flanging simulation.
  • Tracker: Pitch tracking oscillator, or pitch tracking EQ
• Instruments (1 Event input, 1 stereo Audio output):
  • DX10: Sounds similar to the later Yamaha DX synths including the heavy bass but with a warmer, cleaner tone.
  • EPiano: Simple EPiano.
  • JX10: The plug-in is designed for high quality (lower aliasing than most soft synths) and low processor usage.
  • Piano: Not designed to be the best sounding piano in the world, but boasts extremely low CPU and memory usage.

Based on the OpenSource mda plug-ins (http://mda.smartelectronix.com/), this set of plug-ins demonstrates how wrap DS- code in a VST 3 plug-in.

Check the folder "public.sdk/samples/vst/mda-vst3" of the SDK!

Classes:

• BaseProcessor
• BaseController
• BaseParameter

Note Expression Synth

• Instrument plug-in supporting note expression events
• It shows how easy it is to use VSTGUI
• a AUv3 version is available

Check the folder "public.sdk/samples/vst/note_expression_synth" of the SDK!

Classes:

• NoteExpressionSynth::Processor
• NoteExpressionSynth::Controller
• NoteExpressionSynth::Voice

Note Expression Text

• Plug-in visualizing the NoteExpression as Text
• It shows how easy it is to use VSTGUI4

Check the folder "public.sdk/samples/vst/note_expression_text" of the SDK!

Panner

• Simple Panner plug-in showing how to support Panner category (mono to Stereo)
• It shows how easy it is to use VSTGUI

Check the folder "public.sdk/samples/vst/panner" of the SDK!

Classes:

• PlugController
• PlugProcessor

PitchNames

• Instrument plug-in showing PitchNames support
• It shows how easy it is to use VSTGUI

Check the folder "public.sdk/samples/vst/pitchnames" of the SDK!

Classes:

• PitchNamesController
• PitchNamesProcessor
• PitchNamesDataBrowserSource

Test Prefetchable Support

Very simple plug-in:

• showing how to use the Steinberg::Vst::IPrefetchableSupport interface
• using a generic UI

Check the folder "public.sdk/samples/vst/prefetchablesupport" of the SDK!

Test Program Change

Very simple plug-in:

• showing how to support Program List
• using a generic UI

Test Multiple Program Changes

Very simple plug-in:

• showing how to support multiple ProgramChange parameters: 16 slots with one associated program change parameter and a program list for each slot.
• using a generic UI

Test Remap ParamID

Very simple plug-in:

• demonstrating how a VST 3 Plug-in could replace another one and remap parameters ID.
• it could replace the AGain plug-in when it is not available.
• it illustrates the use of the interface IRemapParamID (for mapping Test Remap ParamID parameters to AGain plug-in parameters) and the module info with its compatibility field.

Sync Delay

Very simple delay plug-in:

• showing how to support IProcessContextRequirements

Check the folder "public.sdk/samples/vst/syncdelay" of the SDK!

UTF16 Name

Very simple plug-in:

• with UTF16 characters in plug-in and company name

Check the folder "public.sdk/samples/vst/utf16name" of the SDK!

/ VST Home / What is the VST 3 SDK?

VST 3 Plug-in Test Host

On this page:

• Introduction
• How to use it?
• VST Player Window
  • Audio Input
  • Event Input
  • VST Rack
  • Info Window
  • Context Menu
  • Transport
• VST 3 Plug-ins Tests Window
• Preset Editor

Related pages:

• VST 3 Plug-in Examples

Introduction

The SDK provides a test application called VST3PluginTestHost for Apple macOS X (x86_64/Apple M1) and Microsoft Windows (64bits).

This application allows you to load a plug-in, simulates some inputs (Audio and Event) and acts like a small VST 3 host application based on an ASIO driver.

Included in this application is a test module which allows you to check your plug-in in regard to the VST 3 standard.

Check the folder "bin" of the SDK!

How to use it?

• View -> Open Plug-in Information Window: opens a window showing all registered component and controller VST 3 plug-ins.
• View -> Open Plug-in Unit Tests Window: opens a window where you can test your plug-in with a series of unit tests.
• View -> Open Preset Editor: allows you to open, check and modify VST 3 presets (adding meta attributes like in Instrument/- Style/Character)
• File -> Convert VST 3 Preset to VST 2 preset (fxp or fxb): allow to convert VST 3 Presets to compatible VST 2 Presets.
• File -> Overwrite Plug-in Name in VST 3 Presets: allow to rename the plug-in name in a set of VST 3 Presets.

Dark Mode version

VST Player Window

Audio Input

In this section you can select the audio source of your plug-in for the Main Input Audio Bus and for the Aux Input Audio Bus (Side-chain: if available) between:

• A sine wave
• Noise
• Silence
• ASIO Input (first stereo)
• An Audio File (in this case use the browser (... button) to choose the file (wave, aiff))

A Volume slider allows you to control the level of the source.

Event Input

This section simulates note events sent to the plug-in.

• A pattern could be defined and initialized with randomized, chromatic or manual events. (for Chromatic choose the start note in the pattern and select Chromatic in the pop-up menu).
• Active check box: enable/disable the playback of this pattern.
• You can choose different loop stepping for this pattern (1, 1/2, ...1/32)

VST Rack

This section allows you to load serialized multiple plug-ins. Each plug-in will be loaded in a slot.

• To load a plug-in (Audio or Instrument) click on the associated pop-up menu and select one plug-in.
• To unload a plug-in, click on its associated X button on its slot.

For each loaded plug-in in a slot you can:

• Enable/disable the plug-in with the On button.
• Bypass/process the plug-in with the Byp button (if available as parameter).
• Enable/disable the Side-chain bus with the Aux button (available only if the plug-in has input Side-chain).
• Open its editor with the Edit button.
• Save a Preset with the Store button.
• Load a Preset with the Load button.
• Open the information page of this plug-in with the Info button (see below).

Info Window

• Information window of AGain plug-in showing the Parameters panel:

• Information window of NoteExpressionSynth plug-in showing the Note Expression panel:

• Information window of AGain plug-in showing the Properties panel:

Context Menu

Right click on the opened plug-in opens a context menu which allows to trigger some actions:

• Switch to Generic Editor: open the generic editor instead of the one provided by the plug-in.
• Export Presets Parameters as XML: load automatically all available VST 3 Presets for this plug-in and create a readable XML file for each preset including the parameter states.

Transport

In this section you can:

• set the gain of the output audio • control the transport state (Loop/Start/Stop/Rewind) • change the tempo and signature

VST 3 Plug-ins Tests Window

In this window you can select a specific test branch for a specific plug-in. You can navigate in the test tree (left part), then click on the button Run Selected to process only the selected tests.

There are 2 kinds of tests concerning the way the plug-in is instantiated:

• Global Instance: only one instance of the plug-in will be instantiated for all tests.
• Local Instances: for each test a new instance of the plug-in will be instantiated.

We define currently 2 sets of test:

• VST 3 Conformity
• Special Features

You can run all available tests with Run All. It is possible also to disable some tests with the check box in the left view.

Error reports will be displayed in the Errors view. In the Messages View some warnings (or some plug-in limitations), test results and progress are displayed.

In this version of this Plug-in Test Host, the tests are limited to the main VST 3 features, in future version the test coverage will be extended.

Preset Editor

With this editor you can load and modify VST 3 presets created with the Store button of the VST Rack by adding some meta-attributes.

/ VST Home / What is the VST 3 SDK?

VST 3 Project Generator

On this page:

• Introduction
• Start the VST 3 Project Generator Application
  • Locate CMake
  • Locate VST SDK
  • VST SDK and cmake successfully located
• Setting the Preferences
  • Path Preferences
• Setting and creating a plug-in project
• VST3 Project Generator License

Related pages:

• Generate a new plug-in with Project Generator

Introduction

This open source application (Win/macOS) allows you to generate easily a new VST 3 plug-in project by just entering in a GUI some parameters.

Check the folder "VST3_Project_Generator" of the SDK!

The source code is available at GitHub - steinbergmedia/vst3projectgenerator: VST 3 Project Generator.

Start the VST 3 Project Generator Application

The first time you start the application, you will ask to define 2 folders where are located the VST SDK and the CMake tool. It still possible to change these folders afterward in the Preferences Tab, see Setting the Preferences.

The Visit us menu includes some useful links.

Locate CMake

If you have already downloaded the CMake tool, you just have to indicate the Project Generator where it is located, for this click on Locate CMake and choose with the file selector the cmake.exe file:

If you do not have previously installed the CMake tool, you could download it, just click on Download CMake, an internet browser will open the dedicated CMake webpage, check the Download section and install CMake.

Locate VST SDK

If you have already downloaded the VST 3 SDK, you just have to indicate the Project Generator where it is located, for this click on Locate VST SDK and choose with the folder selector the VST3_SDK folder:

If you do not have previously installed the VST 3 SDK, you could download it, just click on Download VST SDK, a dialog appears:

You have 2 possibilities to download the VST 3 SDK:

• Commercial: by clicking on it you will be redirected to the latest available SDK version to download, including all tools (check What is the VST 3 SDK?), with this variant of the SDK you are able to create and commercialize your plug-ins (See What are the licensing options for VST 3?).
• Open Source: by clicking on it you will be redirected to Steinberg Github where you will be able to clone the VST 3 SDK, this variant does not include all available tools (See What are the licensing options for VST 3?).

VST SDK and cmake successfully located

As soon as the requested 2 locations are founded, the user interface of the application should like this:

The next time you start the Project Generator application you will not asked to relocate them!

Setting the Preferences

Before creating any plug-in project, you have to define some global preferences which will be automatically saved when closing the application.

Company Information

The information included in this subsection will be used for generating Factory information associated to all plug-ins you will generate. This will be read by the host application loading your plug-ins and the host may display it to an user.

• Vendor: this is your Company name: e.g. "Steinberg Media Technologies GmbH"
• E-Mail: your email, which could be used by the host to redirect an user to your support for example: e.g. "mailto:support@steinberg.net"
• URL: the URL of your Company: e.g. "https://www.steinberg.net"
• C++ Namespace: this allows you to predefine a namespace which will be used to surround your plug-in source code: e.g. "MyWantedNamespace":

//...
namespace MyWantedNamespace {

//-----------------------------------------------------------------------
MyPluginController::MyPluginController ()
{
//...
}
} // end namespace
//...
namespace MyWantedNamespace {

Path Preferences

Like mentioned above in the subsection Path Preferences you could change several locations:

• VST 3 SDK Path: the current used VST 3 SDK you have previously downloaded.
• CMake Executable Path: the current used CMake tool

Setting and creating a plug-in project

In this tab you are defining some information for the creation of a new plug-in:

• Name: the name of the plug-in which is displayed in a host: e.g. "AGain"
• Type: this specifies the main VST 3 Sub-Category (PlugType) of your plug-in:
  • Audio Effect: (kFx) a simple audio effect Stereo→Stereo
  • Instrument: (kInstrument) a simple instrument with 1 Event input and 1 stereo Audio output
• Use VSTGUI: check this if you want to use VSTGUI as UI framework
• macOS Deployment Target: enter here the minimum requested macOS version targeted
• C++ Class Name: this specifies the basename of your plug-in classes: e.g. "AGain"

class AGainProcessor : public AudioEffect
{
    //...
};

class AGainController : public EditControllerEx1
{
    //...
};

• Bundle ID: this is the ID needed for example for the Info.plist of macOS: e.g. "com.steinberg.again"
• Filename Prefix: (optional) this will be added as file prefix to the created files: e.g. "AGain" => AGainProcessor.cpp / AGainController.h / ...
• Output Directory: you define here in which folder your project will be created
• CMake Generator: CMake tool required to define a generator in order to create configuration files for a specific build system: there are 2 kinds of generators: Command-Line and IDE. Choose the one you need for example:
  • on Windows: Visual Studio 17 2022
  • on macOS: Xcode
• CMake Platform: you could here define which target platform should be used, i.e x64 or ARM64EC (on Windows)

Once all information is set up, you could click on Create, a script will create and CMake will be used and the chosen IDE will be opened. In the bottom area the script output is displayed, you have the possibility to copy it by using the dedicated button: Copy Script Output To Clipboard.

Example of script Output

C:\Program Files\CMake\bin\CMake.exe C:\Users\YGrabit\Desktop\SDKs\VST3_SDKs\3.7.7\VST_SDK\VST3_Project_Generator\
Windows_x64\Resources\GenerateVST3Plugin.cmake 
-DSMTG_VST3_SDK_SOURCE_DIR_CLI="C:/Users/YGrabit/Desktop/SDKs/VST3_SDKs/3.7.6/VST_SDK/vst3sdk" 
-DSMTG_GENERATOR_OUTPUT_DIRECTORY_CLI="C:/Users/YGrabit/Desktop/SDKs/VST3_SDKs/3.7.7"
-DSMTG_PLUGIN_NAME_CLI="AGain" -DSMTG_PLUGIN_CATEGORY_CLI="Fx" -DSMTG_CMAKE_PROJECT_NAME_CLI="AGain"
-DSMTG_PLUGIN_BUNDLE_NAME_CLI="AGain" -DSMTG_PLUGIN_IDENTIFIER_CLI="com.steinberg.again"
-DSMTG_MACOS_DEPLOYMENT_TARGET_CLI="10.13" -DSMTG_VENDOR_NAME_CLI="Steinberg" 
-DSMTG_VENDOR_HOMEPAGE_CLI="www.steinberg.net" -DSMTG_VENDOR_EMAIL_CLI="info@steinberg.net" 
-DSMTG_PREFIX_FOR_FILENAMES_CLI="" -DSMTG_PLUGIN_CLASS_NAME_CLI="AGain" -DSMTG_ENABLE_VSTGUI_SUPPORT_CLI=ON 
 -P "C:\Users\YGrabit\Desktop\SDKs\VST3_SDKs\3.7.7\VST_SDK\VST3_Project_Generator\
 Windows_x64\Resources\GenerateVST3Plugin.cmake"
==================================================

 Steinberg Media Technologies GmbH
 VST3 Project Generator

==================================================

-- Found Git: C:/Program Files/Git/cmd/git.exe (found version "2.38.1.windows.1") 
-- SMTG_CMAKE_SCRIPT_DIR           : C:/Users/YGrabit/Desktop/SDKs/VST3_SDKs/3.7.7/VST_SDK/VST3_Project_Generator/Windows_x64/Resources
-- SMTG_ENABLE_VSTGUI_SUPPORT      : ON
-- SMTG_GENERATOR_OUTPUT_DIRECTORY : C:/Users/YGrabit/Desktop/SDKs/VST3_SDKs/3.7.7
-- SMTG_TEMPLATE_FILES_PATH        : C:/Users/YGrabit/Desktop/SDKs/VST3_SDKs/3.7.7/VST_SDK/VST3_Project_Generator/Windows_x64/Resources/cmake/templates
-- SMTG_VST3_SDK_SOURCE_DIR        : C:/Users/YGrabit/Desktop/SDKs/VST3_SDKs/3.7.6/VST_SDK/vst3sdk

-- SMTG_VENDOR_NAME            : Steinberg
-- SMTG_VENDOR_HOMEPAGE        : www.steinberg.net
-- SMTG_VENDOR_EMAIL           : info@steinberg.net
-- SMTG_SOURCE_COPYRIGHT_HEADER: Copyright(c) 2022 Steinberg.
-- SMTG_PLUGIN_NAME            : AGain
-- SMTG_PREFIX_FOR_FILENAMES   : e.g. myplugincontroller.h
-- SMTG_PLUGIN_IDENTIFIER      : com.steinberg.again, used e.g. in Info.plist
-- SMTG_PLUGIN_BUNDLE_NAME     : AGain

-- SMTG_CMAKE_PROJECT_NAME     : e.g. AGain will output AGain.vst3
-- SMTG_VENDOR_NAMESPACE       : e.g. namespace MyCompanyName {...}
-- SMTG_PLUGIN_CLASS_NAME      : e.g. class AGainProcessor : public AudioEffect {...}
-- SMTG_PLUGIN_CATEGORY        : Fx
-- SMTG_MACOS_DEPLOYMENT_TARGET: 10.13

-- SMTG_Processor_UUID         : 0x310DE7F8, 0x10DA54D2, 0x98DE9223, 0xA9933093
-- SMTG_Controller_UUID        : 0x80068D40, 0xBA125C34, 0x9B1E857C, 0xC17CD5F3

-- Configured: C:/Users/YGrabit/Desktop/SDKs/VST3_SDKs/3.7.7/AGain/CMakeLists.txt
-- Copied    : C:/Users/YGrabit/Desktop/SDKs/VST3_SDKs/3.7.7/AGain/resource/310DE7F810DA54D298DE9223A9933093_snapshot.png
-- Copied    : C:/Users/YGrabit/Desktop/SDKs/VST3_SDKs/3.7.7/AGain/resource/310DE7F810DA54D298DE9223A9933093_snapshot_2.0x.png
-- Configured: C:/Users/YGrabit/Desktop/SDKs/VST3_SDKs/3.7.7/AGain/resource/myplugineditor.uidesc
-- Configured: C:/Users/YGrabit/Desktop/SDKs/VST3_SDKs/3.7.7/AGain/resource/win32resource.rc
-- Configured: C:/Users/YGrabit/Desktop/SDKs/VST3_SDKs/3.7.7/AGain/source/version.h
-- Configured: C:/Users/YGrabit/Desktop/SDKs/VST3_SDKs/3.7.7/AGain/source/myplugincids.h
-- Configured: C:/Users/YGrabit/Desktop/SDKs/VST3_SDKs/3.7.7/AGain/source/myplugincontroller.cpp
-- Configured: C:/Users/YGrabit/Desktop/SDKs/VST3_SDKs/3.7.7/AGain/source/myplugincontroller.h
-- Configured: C:/Users/YGrabit/Desktop/SDKs/VST3_SDKs/3.7.7/AGain/source/mypluginentry.cpp
-- Configured: C:/Users/YGrabit/Desktop/SDKs/VST3_SDKs/3.7.7/AGain/source/mypluginprocessor.cpp
-- Configured: C:/Users/YGrabit/Desktop/SDKs/VST3_SDKs/3.7.7/AGain/source/mypluginprocessor.h

C:\Program Files\CMake\bin\CMake.exe -G "Visual Studio 17 2022" -A x64 -S "C:/Users/YGrabit/Desktop/SDKs/VST3_SDKs/3.7.7\AGain" -B "C:/Users/YGrabit/Desktop/SDKs/VST3_SDKs/3.7.7\AGain\build" -DSMTG_ADD_VSTGUI=ON 
-- Selecting Windows SDK version 10.0.22000.0 to target Windows 10.0.19045.
-- The C compiler identification is MSVC 19.34.31935.0
-- The CXX compiler identification is MSVC 19.34.31935.0
-- Detecting C compiler ABI info
-- Detecting C compiler ABI info - done
-- Check for working C compiler: C:/Program Files/Microsoft Visual Studio/2022/Professional/VC/Tools/MSVC/14.34.31933/bin/Hostx64/x64/cl.exe - skipped
-- Detecting C compile features
-- Detecting C compile features - done
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- Check for working CXX compiler: C:/Program Files/Microsoft Visual Studio/2022/Professional/VC/Tools/MSVC/14.34.31933/bin/Hostx64/x64/cl.exe - skipped
-- Detecting CXX compile features
-- Detecting CXX compile features - done
-- [SMTG] CMAKE_SOURCE_DIR is set to: C:/Users/YGrabit/Desktop/SDKs/VST3_SDKs/3.7.7/AGain
-- [SMTG] CMAKE_CURRENT_LIST_DIR is set to: C:/Users/YGrabit/Desktop/SDKs/VST3_SDKs/3.7.6/VST_SDK/vst3sdk
-- [SMTG] Disable all VST3 samples
-- [SMTG] SMTG_VSTGUI_SOURCE_DIR is set to: C:/Users/YGrabit/Desktop/SDKs/VST3_SDKs/3.7.6/VST_SDK/vst3sdk/vstgui4
-- Could NOT find EXPAT (missing: EXPAT_LIBRARY EXPAT_INCLUDE_DIR) 
-- VSTGUI will use the embedded Expat package!
-- [SMTG] SMTG_AAX_SDK_PATH is not set. If you need it, please download the AAX SDK!
-- Performing Test SMTG_USE_STDATOMIC_H
-- Performing Test SMTG_USE_STDATOMIC_H - Failed
-- [SMTG] Setup running moduleinfotool for AGain
-- [SMTG] Setup running validator for AGain
-- [SMTG] SMTG_PLUGIN_TARGET_PATH is set to: C:\Users\YGrabit\AppData\Local\Programs\Common\VST3
-- Configuring done
-- Generating done
-- Build files have been written to: C:/Users/YGrabit/Desktop/SDKs/VST3_SDKs/3.7.7/AGain/build

That´s it!

You can contribute to this project on https://github.com/steinbergmedia/vst3projectgenerator!

VST3 Project Generator License

BSD style

VST3ProjectGenerator LICENSE
(c) Steinberg Media Technologies, All Rights Reserved

Redistribution and use in source and binary forms, with orwithout modification,
are permitted provided that the following conditions are met:

* Redistributions of source code must retain the abovecopyright notice,
this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the abovecopyright notice,
this list of conditions and the following disclaimer inthe documentation
and/or other materials provided with the distribution.
* Neither the name of the Steinberg Media Technologies northe names of its
contributors may be used to endorse or promote productsderived from this
software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ANDCONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITEDTO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULARPURPOSE ARE DISCLAIMED.
IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BELIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIALDAMAGES (INCLUDING,
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS ORSERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSEDAND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THISSOFTWARE, EVEN IF ADVISED
OF THE POSSIBILITY OF SUCH DAMAGE.

/ VST Home / What is the VST 3 SDK?

Validator command line

On this page:

• Validator command line

Validator command line

As Cross-platform source code: The validator is a small command line host application (source code included) which can be used to check your plug-in for VST 3 conformity. You can also write your own test code and let the validator execute it.

Very nice for automatic build server integration.

/ VST Home / What is the VST 3 SDK?

AudioHost Application

On this page:

• AudioHost

AudioHost

As Cross-platform source code: Simple cross-platform (only tested on Linux) host application allowing you to register a VST 3 plug-in with Jack Server. First, you have to download the Jack Audio SDK and application server (http://www.jackaudio.org).

• Windows (not tested):

 audiohost.exe "C:\PATH_TO_PLUGIN"

• macOS (not tested)
• Linux:

audiohost PATH_TO_PLUGIN

On Windows and macOS, you can also drag and drop a VST 3 plug-in on the executable via Explorer/Finder.

Check the folder "public.sdk/samples/vst-hosting/audiohost" of the SDK!

/ VST Home / What is the VST 3 SDK?

EditorHost Application

On this page:

• EditorHost

EditorHost

As Cross-platform source code: Simple cross-platform (Win/macOS/Linux) host application allowing you to open the editor of a VST 3 plug-in (with HiDPI support on Windows/macOS). Call it from the command line:

• Windows:

 editorhost.exe "C:\PATH_TO_PLUGIN"

• macOS/Linux:

editorhost PATH_TO_PLUGIN

On Windows and macOS you can also drag and drop a VST 3 plug-in on the executable via Explorer/Finder.

Check the folder "public.sdk/samples/vst-hosting/editorhost" of the SDK!

/ VST Home / What is the VST 3 SDK?

VST 3 Inspector Application

On this page:

• VST 3 Inspector

VST 3 Inspector

As Cross-platform source code: Simple cross-platform (Win/macOS/Linux) host application, built with VSTGUI, which scans the VST 3 Folder, collects information from the factory about each VST 3 plug-in and display it in its UI.

Check the folder "public.sdk/samples/vst-hosting/inspectorapp" of the SDK!

/ VST Home / What is the VST 3 SDK?

AAX, AUv3 and AU Wrappers

On this page:

• VST 3 - AAX Wrapper
• VST 3 - Audio Unit v3 Wrapper
• VST 3 - Audio Unit Wrapper

Related pages:

• iOS Inter-App Audio support

These wrappers allow you to create versions of your VST 3 plug-in in other plug-in formats with minimum effort:

• AAX format used by Pro Tools®
• AUv3 and AU (Audio Unit) on Apple platform

Check the folders basewrapper, aaxwrapper, auv3wrapper and auwrapper in the folder "public.sdk/source/vst" of the SDK!

VST 3 - AAX Wrapper

Helper Class wrapping a VST 3 plug-in to an AAX plug-in

VST 3 - Audio Unit v3 Wrapper

Helper Class wrapping a VST 3 plug-in to an Audio Unit v3 plug-in

VST 3 - Audio Unit Wrapper

Helper Class wrapping a VST 3 plug-in to an Audio Unit v2 plug-in

/ ... / AAX, AUv3 and AU Wrappers

VST 3 - AAX Wrapper

On this page:

• Introduction
• How does it work?

Introduction

Helper Class wrapping a VST 3 plug-in to an AAX plug-in.

The VST 3 SDK comes with a helper class which wraps one VST 3 audio processor and edit controller to an AAX plug-in.

How does it work?

• Check the AGainAAX example
• AAX SDK 2.3 or higher is expected in folder external.avid.aax (located at the same level as the folder public.sdk)
• Here is the step based on the AgainAAX example:
  • In the cpp file againaax.cpp, you can define the plug-in properties: IO audio, product ID, ...
  • On Windows, copy built linker output again_aax.aaxplugin to "c:\Program Files\Common Files\Avid\Audio\Plug-Ins\again_aax.aaxplugin\Contents\x64" (the debug build does this automatically, but needs appropriate access rights (Administrator rights of your visual))
  • On OSX, copy built bundle build/Debug/again.aaxplugin to "/Library/Application Support/Avid/Audio/Plug-Ins"
• A developer version of Pro Tools is needed to load the plug-in, the release version of Pro Tools requires plug-ins to be Pace-signed (PACE Anti-Piracy Inc.: https://www.ilok.com)

/ ... / AAX, AUv3 and AU Wrappers

VST 3 - AudioUnit v3 Wrapper

On this page:

• Introduction
• How does it work?

Related pages:

• Audio Unit v3 Plug-Ins | Apple Developer Documentation

Introduction

Helper Class wrapping a VST 3 plug-in to an Audio Unit v3 plug-in.

The VST 3 SDK comes with a helper class which wraps one VST 3 audio processor and edit controller to an AU v3 plug-in.

The wrapped AudioUnit does support MPE when the VST 3 plug-in has Note Expression support. You need to implement Steinberg::Vst::INoteExpressionPhysicalUIMapping to map your Note Expression to the limited three expressions defined by MPE.

How does it work?

• Structure:
  • App (container app which initializes the AU through small Playback Engine)
  • Extension (extension which is loaded by hosts, also initializes the AU)
• How to use the VST 3 → AU v3 Wrapper with the sample code:
  • make sure you have correct code signing set up
  • build & run targets
• How to use the VST 3 → AU v3 Wrapper with your own VST plug-in:
  • duplicate either the folder again_auv3 or note_expression_synth_auv3 in public.sdk/samples/vst, rename it and edit CMakelist.txt to add your sources, resources and modified target names etc.
  • open audiounitconfig.h and change the definitions in this file.
  • also change the other files in that folder to your requirements. Code signing is required, but you can build and test with a developer only identity.
  • build & run targets

/ ... / AAX, AUv3 and AU Wrappers

VST 3 - AudioUnit v2 Wrapper

On this page:

• Introduction
• How does it work?

Related pages:

• Audio Unit v3 Plug-Ins | Apple Developer Documentation

Introduction

Helper Class wrapping a VST 3 plug-in to an Audio Unit v2 plug-in.

The VST 3 SDK comes with an AudioUnit wrapper, which can wrap one VST 3 audio processor and edit controller as an AudioUnit effect/instrument.

The wrapper is a small dynamic library which loads the VST 3 plug-in. As AudioUnits store important information in their resource fork, this library must be compiled for every VST 3 plug-in.

How does it work?

• You first need to build the SDK (check here) and then you should have the xcode project.
• You may need to download the CoreAudio SDK from Apple and point cmake to it when building the SDK with it (see here).
• Create a copy of the again AU wrapper example project directory (public.sdk/source/vst/auwrapper/again/)
• Rename the copy to your needs
• Edit the target settings of the project and change
  • Product Name
  • Library search path so that it points to the directory where libauwrapper.a exists
  • architecture setting so that it only includes architectures that the VST 3 plug-in supports
• Search in the project for AUWRAPPER_CHANGE and change the settings to your needs, especially in:
  • Edit audiounitconfig.h, see comments there
  • Edit Info.plist, see comments there
• Edit the "Make Links Script" for easier debugging/development
• Build your project
• Done ... that is all!

For the release version, you must place a copy or an alias of your VST 3 plug-in in the resource folder of the bundle named "plugin.vst3"

/ VST Home / What is the VST 3 SDK?

iOS Inter-App Audio Support

See [3.6.0] iOS Inter-App Audio

/ VST Home / What is the VST 3 SDK?

VSTGUI

On this page:

• Introduction
• VSTGUI Forum
• VSTGUI on GitHub
• VSTGUI License
• Tutorials for VSTGUI

Related pages:

• https://sdk.steinberg.net

Introduction

This is a user interface toolkit mainly for audio plug-ins (VST, AudioUnit, etc). Based on the XML definition of the plug-in UI, VSTGUI includes an embedded editor (UIDescription Editor) which allows the developer to create a plug-in UI just by drag & drop of the UI element.

First developed in-house by Steinberg Media Technologies (around 1998) for their first VST plug-ins. Later added as binary libraries to the official VST SDK. Since May 2003, VSTGUI is open source, and is hosted now at GitHub https://github.com/steinbergmedia/vstgui.

The last official release version of VSTGUI is always included in the VST 3 SDK.

Example of the VSTGUI UIDescription Editor (embedded editing WYSIWYG)

Check the folder vstgui4 of the SDK!

VSTGUI Forum

Visit Steinberg's VST Developer Forum in order to get help with development, submit bug reports, request new features and connect to other VSTGUI developers:

https://sdk.steinberg.net

VSTGUI on GitHub

https://github.com/steinbergmedia/vstgui

VSTGUI License

BSD style

VSTGUI LICENSE
(c) Steinberg Media Technologies, All Rights Reserved

Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:

* Redistributions of source code must retain the abovecopyright notice,
this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer inthe documentation
and/or other materials provided with the distribution.
* Neither the name of the Steinberg Media Technologies northe names of its
contributors may be used to endorse or promote productsderived from this
software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITEDTO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BELIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS ORSERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSEDAND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THISSOFTWARE, EVEN IF ADVISED
OF THE POSSIBILITY OF SUCH DAMAGE.

Tutorials for VSTGUI

Use VSTGUI to design a User Interface

This tutorial explains how to use VSTGUI. VSTGUI comes with a WYSIWYG editor that allows you to createstunning user interfaces for your plug-in.

/ VST Home

VST 3 Licensing

Related pages:

• Steinberg VST usage guidelines
• What are the licensing options for VST 3?
• Which files fall under which license?
• Developer use cases (FAQs)

This developer use case guide will help you to decide which VST 3 licensing model to choose. The VST 3 SDK has new Usage Guidelines to follow for all licensing models, please read them carefully!

Steinberg VST usage guidelines

Whenever VST® is used or the SDK has been used to create a product or the SDK is included (Open-source GPLv3 case), it is required to add the reference to Steinberg by using the VST compatible logo as supplied by Steinberg. Included in the VST 3 SDK, the VST compatible logo can be found in the folder VST_SDK/VST3_SDK/vst3_doc/artwork.

What are the licensing options for VST 3?

You can choose between the Proprietary Steinberg VST 3 or the Open-source GPLv3 license (dual-license) depending on how you want to distribute your VST 3 plug-in/host. The License Agreement could be found here and in the VST 3 SDK package.

Which files fall under which license?

All files describing the VST 3 interface, except VST 2 files, located in the folder "pluginterfaces" of the SDK, fall under the dual-license described previously.

Developer use cases (FAQs)

The following use cases support you to choose the right license.

/ VST Home / VST 3 Licensing

Steinberg VST usage guidelines

On this page:

• 1. Required use of VST Compatible logo
• 2. Use of VST unrelated to the VST Compatible logo
• 3. Use when claiming compatibility
• 4. Use on website
• 5. Use on package
• 6. Use in product name or logo
• 7. Use in company name
• 8. Use in social media
• 9. Use in domain
• 10. Use in logo
• 11. Use in video
• 12. Use in category
• 13. Use in combination or composition
• 14. VST Compatible logo
• 15. General guidelines for using VST trademark
• 16. Questions and suggestions

Related pages:

• VST 3 Licensing
• What are the licensing options for VST 3?
• Developer use cases (FAQs)

Whenever VST® is used or the SDK has been used to create a product or the SDK is included (Open-source GPLv3 case), it is required to add the reference to Steinberg by using the VST compatible logo as supplied by Steinberg. Included in the VST 3 SDK, the VST compatible logo can be found in the folder VST_SDK/VST3_SDK/vst3_doc/artwork.

This logo exists in different forms: with and without the trademark text, black on white and white on black. If you choose the logo without the trademark text, you have to include the following statement somewhere:

"VST is a trademark of Steinberg Media Technologies GmbH, registered in Europe and other countries."

1. Required use of VST Compatible logo

Whenever “VST” is used, or the SDK is used to create a product, or when the SDK is included, it is required to add the reference to Steinberg by using the “VST Compatible logo” as supplied by Steinberg on each of the following:

1. on package

2. on website:
   The VST Compatible logo must be shown on every webpage that relates to such a product or shows VST. Using e.g. only within the imprint is NOT sufficient.

3. all documentation, regardless of the media used, such as PDF manuals, website, printed manuals etc.

On each of the following the logo can be omitted only if not enough space is available. However, in such a case be sure to include Steinberg's copyrights notice:

1. on all advertising materials

2. in the "about box" or similar (e.g. help menu, startup screen) of the product.

2. Use of VST unrelated to the VST Compatible logo

It is allowed for all parties that have entered into the current Steinberg VST Plug-in SDK Licensing Agreement to use “VST” in regular letters to refer to compatibility as long as complying with the Agreement. This can be done on the package/website or even within the name of the product as long as the form of use is in line with the Agreement and the VST Compatible logo is always shown in the context of such. The following shall provide more guidance related to common forms of usage.

3. Use when claiming compatibility

It is allowed to use claims such as “compatible with 64-bit VST” if the VST Compatible logo is placed in context of such claim, e.g. not too far away on the same page, and the product uses or has been created using the SDK and is, in fact, compatible.

4. Use on website

It is not sufficient to include the VST Compatible logo only in the imprint or one other page. All pages that relate to a product using or created using the SDK or showing VST must show the VST Compatible logo.

5. Use on package

The VST Compatible logo must be printed on the package of any product using or created using the SDK or showing VST.

6. Use in product name or logo

Provided that the VST Compatible logo is always displayed in the context of such a product name, “VST” may be added to the basic product name, e.g. like “mycoolEngine for VST”, if set in regular type and not graphically illustrated or integrated into the product name, and if the VST Compatible logo is always shown in direct context to such a product name. It is not allowed to merge the basic product name and VST in any graphical way into one integrated visual. E.g., it is allowed to use like this:

while it is unacceptable to use it like this:

7. Use in company name

It is not allowed to include VST in the company name.

8. Use in social media

It is allowed to use VST in channels and their names/URLs and the like, if a junction is used to denote the compatibility, e.g. in “MycoolEngineForVST”, and if the channels etc. always show the VST Compatible logo.

9. Use in domain

It is allowed to use VST in domains, e.g. second level domains, if a junction is used to denote the compatibility, e.g. in “MycoolEngineForVST.com”, and if any page under such domain shows the VST Compatible logo and the domain only shows products using or created using the SDK.

10. Use in logo

It is not permitted to include VST in a company logo but it is allowed to include VST in a product logo provided that is in conformity with No. 6 (Use in product name or logo).

11. Use in video

It is allowed to use “VST” in the title of a video or in a video, e.g. a tutorial, in a way as named above, e.g. as an addition to a product name or to show the compatibility, if the VST Compatible logo is shown in the video and, if VST is included in the title of the video, on any page that shows the video and/or the title. Provided that a frame of the video is shown as still (e.g. when presenting the video while not playing it) and such frame includes VST, the frame or the direct context of the video needs to show the VST Compatible logo.

12. Use in category

It is allowed to use VST in a category or in a related URL outside of the domain, e.g. in www.myreviews.com/VSTplugins/, if such category is of generic meaning, and if under such category only forms of use and/or products in line with the SDK agreement are listed.

13. Use in combination or composition

It is not allowed to create combinations or compositions like “VSTi” or similar.

14. VST Compatible logo

The current VST Compatible logos are the following:

Minimum printing size = 20 x 18,7 mm

Minimum printing size = 15 x 10 mm

15. General guidelines for using VST trademark

On product documentation and promotional materials, use the registered trademark symbol (®) the first time the VST trademark appears in the text. Also include an attribution of Steinberg's ownership within the credit notice. Attribution:

"VST® is a trademark of Steinberg Media Technologies GmbH, registered in Europe and other countries."

16. Questions and suggestions

Questions and suggestions regarding this guide can be sent to reception@steinberg.de

/ VST Home / VST 3 Licensing

What are the licensing options

On this page:

• Proprietary Steinberg VST 3 license
• Open-source GPLv3 license
• Steinberg Dual-License file

Related pages:

• VST 3 Licensing
• Developer use cases (FAQs)
• GNU General Public License GPLv3

You can choose between the Proprietary Steinberg VST 3 or the Open-source GPLv3 license (dual-license) depending on how you want to distribute your VST 3 plug-in/host. The License Agreement could be found here and in the VST 3 SDK package.

Proprietary Steinberg VST 3 license

The "Proprietary Steinberg VST 3" license allows you to distribute your VST 3 plug-in/host in a binary form. However, please note the following requirements:

• You need written permission from Steinberg Media Technologies GmbH in order to distribute your VST 3 plug-in/host (Steinberg will send you the countersigned License agreement included in the SDK that you signed and sent to us).
• You need to mention Steinberg Media Technologies GmbH in the about box and/or documentation of your VST 3 plug-in/host and follow the Steinberg VST usage guidelines.

For more details please read the "Proprietary Steinberg VST 3" license agreement. If you accept it, please enter all required information, sign it and send it back to us, either via land mail (to the Steinberg address mentioned in the license), or via e-mail to reception@steinberg.de or via fax (+49 (0)40 210 35-300). We will countersign the license agreement and send it back to you.

ⓘ As PDF
The License agreement is part of the VST SDK package, too.

Open-source GPLv3 license

The open-source license lets you share the source code of your VST 3 plug-in/host including the VST 3 SDK's sources which are subject to the GPLv3.

ⓘ Note
Note that VST 2 sources are NOT part of the GPLv3!

For more information about GPLv3 check this link. It also permits you to change and modify the VST 3 SDK's sources as long as you share your changes and make them available for everyone (e.g. on an Internet hosting service like GitHub). Note that you have to follow the Steinberg VST usage guidelines.

Steinberg Dual-License file

//----------------------------------------------------------------------------
// LICENSE
// (c) 2024, Steinberg Media Technologies GmbH, All Rights Reserved
//----------------------------------------------------------------------------
This license applies only to files referencing this license,
for other files of the Software Development Kit therespective embedded license text
is applicable. The license can be found at: <http://www.steinberg.net/sdklicenses_vst3>

This Software Development Kit is licensed under the terms ofthe Steinberg VST 3 License,
or alternatively under the terms of the General PublicLicense (GPL) Version 3.
You may use the Software Development Kit according to eitherof these licenses as it is
most appropriate for your project on a case-by-case basis(commercial or not).

a) Proprietary Steinberg VST 3 License
The Software Development Kit may not be distributed in partsor its entirety
without prior written agreement by Steinberg MediaTechnologies GmbH.
The SDK must not be used to re-engineer or manipulate anytechnology used
in any Steinberg or Third-party application or softwaremodule,
unless permitted by law.
Neither the name of the Steinberg Media Technologies GmbH northe names of its
contributors may be used to endorse or promote productsderived from this
software without specific prior written permission.
Before publishing a software under the proprietary license, you need to obtain a copy
of the License Agreement signed by Steinberg MediaTechnologies GmbH.
The Steinberg VST SDK License Agreement can be found at:
<http://www.steinberg.net/en/company/developers.html>

THE SDK IS PROVIDED BY STEINBERG MEDIA TECHNOLOGIES GMBH "ASIS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITEDTO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULARPURPOSE ARE DISCLAIMED.
IN NO EVENT SHALL STEINBERG MEDIA TECHNOLOGIES GMBH BE LIABLEFOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIALDAMAGES (INCLUDING,
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS ORSERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSEDAND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT(INCLUDING NEGLIGENCE
OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THISSOFTWARE, EVEN IF ADVISED
OF THE POSSIBILITY OF SUCH DAMAGE.

b) General Public License (GPL) Version 3
Details of these licenses can be found at: <http://www.gnu.orglicenses/gpl-3.0.html>
//---------------------------------------------------------------------------------

/ VST Home / VST 3 Licensing

Which files fall under which license?

On this page:

• Which files of the VST 3 SDK fall under which license?
• What about VST 2?

Related pages:

• VST 3 Licensing

Which files of the VST 3 SDK fall under which license?

All files describing the VST 3 interface, except VST 2 files, located in the folder "pluginterfaces" of the SDK, fall under the dual-license described previously.

Each of these files includes this text:

//----------------------------------------------------------------------------
// This file is part of a Steinberg SDK. It is subject to thelicense terms
// in the LICENSE file found in the top-level directory ofthis distribution
// and at www.steinberg.net/sdklicenses.
// No part of the SDK, including this file, may be copied, modified, propagated,
// or distributed except according to the terms contained inthe LICENSE file.
//----------------------------------------------------------------------------

• for all other files of the VST 3 SDK, the respective embedded license text is applicable, for example:
  • all VSTGUI files fall under a BSD style license
  • all Helper files (included in base and public.sdk folders) except VST 2 files fall under a BSD style license
  • all mda-vst3 examples (public.sdk/samples/mda-vst3 folder) fall under a BSD style license: Copyright (c) 2008 Paul Kellett

What about VST 2?

The "Proprietary Steinberg VST 2" license, which is the VST 2 license agreement, allows you to distribute your VST 2 plug-in/host in a binary form. However, please note the following requirements:

• You need written permission from Steinberg Media Technologies GmbH in order to distribute your VST 2 plug-in/host (which had to be done before October 2018).
• You need to mention Steinberg Media Technologies GmbH in the about box and/or documentation of your VST 2 plug-in/host and follow the Steinberg VST usage guidelines.
• Note that the "Proprietary Steinberg VST 3" license does not include the "Proprietary Steinberg VST 2" license, you have to sign it separately! It was available in the VST 2 SDK and in the VST 3 SDK old version.
• Note that from the first of October 2018, Steinberg does not accept any more submissions of license agreement for VST 2 plug-in/host! This means:

If you do not have a license agreement signed with Steinberg before October 2018, you are not allowed to distribute VST 2 plug-ins or VST 2 hosts!

/ VST Home / VST 3 Licensing

Developer use cases (FAQs)

Related pages:

• Steinberg VST usage guidelines
• What are the licensing options for VST 3?

See Frequently Asked Questions: Licensing

/ VST Home

Getting Started

Related pages:

• VST 3 Links
• How to set up my system for VST 3
• Preparation on Windows

This section provides general information about where to find the VST 3 SDK and how to get it.

VST 3 Links

Important links you will need for working with VST 3.

How to set up my system for VST 3

In order to build VST 3 plug-ins, you need the source code of the VST 3 (interface definition), an IDE/compiler, cmake and a VST 3 host application.

/ VST Home / Getting Started

VST 3 Links

On this page:

• Getting VST 3 SDK
  • Download the full VST 3 package as zip file
  • Clone VST 3 repository from GitHub
• Online Documentation
• VST 3 Forum
• VSTGUI
• External Links to VST 3, DSP, Conferences and Plug-ins development

Related pages:

• How to set up my system for VST 3

Important links you will need for working with VST 3.

Getting VST 3 SDK

You have 2 possibilities for getting the VST 3 SDK:

Download the full VST 3 package as zip file

Download a full VST 3 SDK package which includes everything you need to build a VST 3 plug-in or host. Test your VST 3 plug-in in real-time with the included VST 3 Plug-in Test Host and execute automated tests (See What is the VST 3 SDK?):

https://www.steinberg.net/vst3sdk (direct link to zip file, ~100 MB)

Clone VST 3 repository from GitHub

Clone the VST 3 SDK repository from GitHub for easy integration into your workspace:

https://github.com/steinbergmedia/vst3sdk

ⓘ Note
Independently of the download source of the VST 3 SDK be sure that you follow the license agreement (check What are the licensing options for VST 3?)

Online Documentation

Browse the VST 3 SDK's online documentation including API reference and sample code:

https://steinbergmedia.github.io/vst3_doc

Browse the VST portal for the whole documentation and tutorials:

https://steinbergmedia.github.io/vst3_dev_portal/pages/index.html

VST 3 Forum

Visit Steinberg's VST Developer Forum in order to get help with development, submit bug reports, request new features and connect to other VST 3 developers:

https://sdk.steinberg.net

VSTGUI

When you download the VST 3 SDK, the last official release version of VSTGUI is included, but you can get it (the release and the development branches) from github:

https://github.com/steinbergmedia/vstgui

External Links to VST 3, DSP, Conferences and Plug-ins development

Here, you can find some links to external resource about VST 3, DSP and Plug-ins development:

Category	Links
YouTube	• ADC 2020: Support of MIDI2 and MIDI-CI in VST 3 instruments, Arne Scheffler and Janne Roeper • ADC 2017: VST 3 history, advantages and best practice, Yvan Grabit • ADC 2016: The Golden Rules of Audio Programming, Pete Goodliffe • How to setup the VST 3 SDK's Sample Plug-in Projects
Forums / Mailing List	• KVRAudio Forum: DSP and Plug-in Development • music-dsp mailing list at columbia.edu • music-dsp Web • Sursound mailing list at Virginia Tech • DSP Stack Overflow: DSP Developer community • Stack Overflow: Developer community
Tools / Libraries	• MATLAB®: Audio Plug-in Creation and Hosting • Blender: A free and open source 3D creation suite • Armadillo: C++ library for linear algebra & scientific computing • lapack++: Linear Algebra PACKage in C++ • dlib: Dlib is a modern C++ toolkit • Intel MKL: Intel® Math Kernel Library • CMSIS-DSP: CMSIS-DSP is an optimized compute library for Arm CPU (filtering, mathematics,...)
Books	• DSP related.com: Articles, news, and blogs about basic and modern DSP topics • Introduction to Signal Processing by Sophocles J. Orfanidis • DSP Guide by Steven W. Smithn (The Scientist and Engineer's Guide to Digital Signal Processing) • Online Books by Julius O. Smith III (Mathematics of the Discrete Fourier Transform (DFT), Introduction to Digital Filters, Physical/Spectral Audio Signal Processing) • Seeing Circles, Sines, and Signals: A visual and interactive introduction to DSP • The ART of VA Filter Design by Vadim Zavalishin (theoretical and practical aspects of the virtual analog filter design in the music DSP context) • Stackoverflow - The Definitive C++ Book Guide and List: Nice list of C++ books (for beginner to advanced levels)
Conferences	• ADC: Audio Developer Conference by Roli • DAFx: Digital Audio Effects • ICASSP: International Conference on Acoustics, Speech, and Signal Processing • ISMIR: International Society for Music Information Retrieval
Other	• VST on wikipedia • VST Story Interview • Steinberg Media Technologies

/ VST Home / Getting Started

How to setup up my system for VST 3

On this page:

• Get the source code
  • From the downloaded vstsdk.zip file
  • From GitHub:
• Get an IDE for development
  • For Windows
  • For MacOS
  • For Linux
  • Package Requirements
• Get cmake
• Get a VST 3 host application

Related pages:

• VST 3 Links
• Using cmake for building VST 3 plug-ins

In order to build VST 3 plug-ins, you need the source code of the VST 3 (interface definition), an IDE/compiler, cmake and a VST 3 host application.

Get the source code

From the downloaded vstsdk.zip file

Download the VST 3 SDK: check VST 3 SDK Download.

Unpack the zip file to a development folder on your computer.

From GitHub:

git clone --recursive https://github.com/steinbergmedia/vst3sdk.git

Get an IDE for development

For Windows

On Windows, we recommend that you to use Visual Studio C++ or Visual Studio Code. You can get it for free here https://visualstudio.microsoft.com/free.

For MacOS

On MacOS, a first choice is Xcode (available here https://developer.apple.com/xcode/).

For Linux

In order to build the SDK successfully, you need an Ubuntu-based Linux distribution. Other distributions might work as well, but are not tested.

1. Download Linux: http://www.ubuntu.com or https://www.linuxmint.com
2. Install it directly or in a virtual machine like Parallels. We used and tested on Ubuntu 22.04 LTS.

Package Requirements

Building the SDK examples requires installation of several packages:

Required:

sudo apt-get install cmake gcc "libstdc++6" libx11-xcb-dev libxcb-util-dev libxcb-cursor-dev libxcb-xkb-dev libxkbcommon-dev libxkbcommon-x11-dev libfontconfig1-dev libcairo2-dev libgtkmm-3.0-dev libsqlite3-dev libxcb-keysyms1-dev

ⓘ Note
On Raspbian/Debian, replace "libxcb-util-dev" with "libxcb-util0-dev"

Optional:

sudo apt-get install subversion git ninja-build

A recommended IDE (optional): QTCreator

sudo apt-get install qtcreator

ⓘ Note
You can also use the bash file "setup_linux_packages_for_vst3sdk.sh" included in the VST3_SDK/tools folder!

ⓘ Note\

• Instead of gcc compiler, a recent version of clang compiler will also work!
• libgtkmm3 is required for VSTGUI and the editorhost example!
• Jack Audio is required for audiohost example!

Get cmake

In order to control the compilation process and create an IDE project, VST 3 SDK uses the open-source and cross-platform tool cmake.

You can download cmake here: https://cmake.org/download/ or use a package manager for your OS (Linux).

You can use it as a command line tool or use the cmake executable with GUI. cmake-gui is included in the cmake package:

Specific on Windows

---

You have to adapt your Windows right access to allow creation of symbolic links for VST 3 plug-ins: Check HERE!

Get a VST 3 host application

You can use your favorite VST 3 host application, see here for some examples, or you can use the VST 3 Plug-in Test Host application included in the VST 3 SDK.

/ VST Home / Getting Started

Preparation on Windows

Generated VST 3 Microsoft Visual Studio Projects using the cmake included in the SDK will create by default symbolic links for each built plug-in in the official VST 3 folder (C:\Program Files\Common Files\VST3). In this folder it is not directly possible to write these symbolic links if you are allowed to do this (not Administrator for example), to solve this problem you have 4 solutions:

Solution 1

If you do not want to create these links, call cmake with this parameter:

-DSMTG_CREATE_PLUGIN_LINK=0

Solution 2

You could choose (which is the default) the new user location for VST 3 plug-ins which should have no right access issue as normal user, call cmake with this parameter:

-DSMTG_PLUGIN_TARGET_USER_PROGRAM_FILES_COMMON=1

Solution 3

In order to allow create these symbolic links on Windows you could edit the "Settings > System > For developers" by enabling the Developer Mode:

Solution 4

In order to allow create these symbolic links on Windows you have to adapt the Group Policy of Windows which is only available by default in Windows Pro but not in Windows Home. In Windows Home you have to install it before changing the right access to this folder (C:\Program Files\Common Files\VST3). For this there are some internet webpages showing you how to do this, for example this one: https://www.itechtics.com/enable-gpedit-msc-windows-11.

As soon as the group Policy editor is available you have to start it by:

• Enter run in the Windows search field and start the run App and enter gpedit.msc

or

• Enter Edit group policy in the Windows search field:

Now the Local Group Policy Editor is started:

• Navigate to:

Computer Configuration => Windows Settings => Security Settings =>Local Policies => User Rights Assignment => Create symbolic links

Here, you can set which users can create symbolic links, add your user name.

/ VST Home

Tutorials

On this page:

• Building the examples included in the SDK
  • Building the examples included in the SDK on Windows
  • Building the examples included in the SDK on macOS
  • Building the examples included in the SDK on Linux
• Using cmake for building VST 3 plug-ins
• Generate a new plug-in with the Project Generator App
• Code your first plug-in
• Use VSTGUI to design a User Interface
• Data Exchange
• Advanced VST 3 techniques
• How to use the silence flags
• Guideline for replacing a VST 2 plug-in by a VST 3 plug-in
• Strings Conversion Helper
• Creating a cmake plug-in project from scratch
• Creating a plug-in with VST 3 SDK as an external project
• Switching to another VSTGUI submodule or branch
• Tutorials on Youtube from 3rd Party developers
  • How to setup the VST 3 SDK's Sample Plugin Projects
  • VST 3 SDK Tutorial: Create your own VST 3 Synth plug-in
  • Building Your First Audio Plug-in (Windows 10)
  • Building Your First Audio Plug-in (macOS)
  • Building Your First Audio Plug-in (Linux Ubuntu)

The tutorials explain common techniques and best practices for building your plug-ins. By following the instruction step by step you will learn how to develop VST 3 plug-ins.

ⓘ Note
This section is under construction and will be extended inthe future with new tutorials.

Building the examples included in the SDK

Building the examples included in the SDK on Windows

Link

This tutorial explains how to set up your computer and create an environment for compiling the VST 3 audio plug-in examples provided with the VST 3 SDK.

Building the examples included in the SDK on macOS

Link

This tutorial explains how to set up your computer and create an environment for compiling the VST 3 audio plug-in examples provided with the VST 3 SDK.

Building the examples included in the SDK on Linux

Link

This tutorial explains how to set up your computer and create an environment for compiling the VST 3 audio plug-in examples provided with the VST 3 SDK.

Using cmake for building VST 3 plug-ins

Link

This tutorial explains how to use cmake with VST 3 SDK.

Generate a new plug-in with the Project Generator App

Link

This tutorial explains how to create a new audio plug-in by using the VST 3 Project Generator included in the VST 3 SDK.

Code your first plug-in

Link

Following the previous tutorial Generate a new plug-in with the Project Generator App, this tutorial explains how to code an audio plug-in and how to add some basic features.

Use VSTGUI to design a User Interface

Link

This tutorial explains how to use VSTGUI. VSTGUI comes with a WYSIWYG editor that allows you to create stunning user interfaces for your plug-in.

Data Exchange

Link

This tutorial explains how to send data from the realtime process to the edit controller.

Advanced VST 3 techniques

Link

In this tutorial, you will learn:

• How to add nearly sample-accurate parameter changes to an audio effect
• How to use C++ templates to write one algorithm supporting 32 bit and 64 bit audio processing
• How to set the state of the audio effect in a thread safe manner

How to use the silence flags

Link

This tutorial explains how to use silence flags.

Guideline for replacing a VST 2 plug-in by a VST 3 plug-in

Link

This guideline explains what could be done for creating a VST 3 plug-in replacing an old VST 2 plug-in.

Strings Conversion Helper

Link

The SDK provides some helpers functions to convert from UTF16 (use in VST 3 interfaces) to UTF8 (used by std::string).

Creating a cmake plug-in project from scratch

Link

This tutorial provides a step-by-step guide for building a VST 3 plug-in's CMakeLists.txt from scratch.

Creating a plug-in with VST 3 SDK as an external project

Link

This is a simple Hello World VST 3 SDK plug-in to demonstrate how to use the VST 3 SDK as an external project.

Switching to another VSTGUI submodule or branch

Link

Sometimes it is necessary to switch to another VSTGUI submodule or branch for testing purpose. This tutorial explains how to do that.

Tutorials on Youtube from 3rd Party developers

How to setup the VST 3 SDK's Sample Plugin Projects

https://www.youtube.com/watch?v=004zcWwgi1A

VST 3 SDK Tutorial: Create your own VST 3 Synth plug-in

https://www.youtube.com/watch?v=zdgytoRLKj0

Building Your First Audio Plug-in (Windows 10)

https://www.youtube.com/watch?v=4MQZyZKOPPM

Building Your First Audio Plug-in (macOS)

https://www.youtube.com/watch?v=Twcx6Sd6HBw

Building Your First Audio Plug-in (Linux Ubuntu)

https://www.youtube.com/watch?v=jXryyxEsFag

/ VST Home / Tutorials

Building the examples included in the SDK

On this page:

• Building the examples included in the SDK on Windows
• Building the examples included in the SDK on macOS
• Building the examples included in the SDK on Linux

Building the examples included in the SDK on Windows

Link

This tutorial explains how to set up your computer and create an environment for compiling the VST 3 audio plug-in examples provided with the VST 3 SDK on Windows.

Building the examples included in the SDK on macOS

Link

This tutorial explains how to set up your computer and create an environment for compiling the VST 3 audio plug-in examples provided with the VST 3 SDK on macOS.

Building the examples included in the SDK on Linux

Link

This tutorial explains how to set up your computer and create an environment for compiling the VST 3 audio plug-in examples provided with the VST 3 SDK on Linux.

/ VST Home / Tutorials / Building the examples

Building the examples included in the SDK on Windows

On this page:

• Goal
• Part 1: Getting and installing the VST 3 SDK
• Part 2: Building the examples on Windows
• Building using cmake-gui

Goal

This tutorial explains how to set up your computer and create an environment for compiling the VST 3 audio plug-in examples provided with the VST 3 SDK. These include plug-ins like simple DSP effects (Gain, compressor, delay, ...), synths instruments and some plug-ins showing how to handle some specific VST 3 features (Note Expression, Program Change, channel info context, ...).

They can be loaded into VST 3 hosts like Cubase, WaveLab, ...

Part 1: Getting and installing the VST 3 SDK

For downloading the SDK, see this section "How to set up my system for VST 3".

Download cmake from: https://cmake.org/download/ or use a package manager for your OS.

Part 2: Building the examples on Windows

• Create a folder for the build and move to this folder (using cd):

mkdir build
cd build

• Generate the solution/projects: specify the path to the project where CMakeLists.txt is located:

cmake.exe -G "Visual Studio 17 2022" -A x64 ../vst3sdk
or without symbolic links
cmake.exe -G "Visual Studio 17 2022" -A x64 ../vst3sdk-DSMTG_CREATE_PLUGIN_LINK=0

ⓘ Note
You can find the string definition for different Visual Studio Generators in the cmake online documentation (https://cmake.org/documentation/)

• You have to adapt your Windows right access to allow creation of symbolic links for VST 3 plug-ins: Check HERE!
• Build the plug-in (you can use Visual Studio too):

msbuild.exe vstsdk.sln
(or alternatively for example for release)

cmake --build . --config Release

Building using cmake-gui

• Start the cmake-gui application which is part of the cmake installation (https://cmake.org/download/)

• Browse Source...: select the folder VST3_SDK
• Browse Build...: select a folder where the outputs (projects/...) will be created. Typically a folder named build
• You can check the SMTG Options
• Press Configure and choose the generator in the window that opens: for example "Visual Studio 17 2022"

• Press Generate to create the project
• Open your targeted IDE, and compile the solution/project.

/ VST Home / Tutorials / Building the examples

Building the examples included in the SDK on macOS

On this page:

• Goal
• Part 1: Getting and installing the VST 3 SDK
• Part 2: Building the examples on macOS

Goal

This tutorial explains how to set up your computer and create an environment for compiling the VST 3 audio plug-in examples provided with the VST 3 SDK. These include plug-ins like simple DSP effects (Gain, compressor, delay, ...), synths instruments and some plug-ins showing how to handle some specific VST 3 features (Note Expression, Program Change, channel info context, ...).

They can be loaded into VST 3 hosts like Cubase, WaveLab, ...

Part 1: Getting and installing the VST 3 SDK

For downloading the SDK, see this section "How to set up my system for VST 3".

Download cmake from: https://cmake.org/download/ or use a package manager for your OS.

Part 2: Building the examples on macOS

• Create a folder for the build and move to this folder (using cd):

mkdir build
cd build

• Generate the solution/projects: specify the path to the project where CMakeLists.txt is located:

For XCode:

cmake -GXcode ../vst3sdk

Without XCode (here debug variant):

cmake -DCMAKE_BUILD_TYPE=Debug ../

• Build the plug-in (you can use XCode too):

xcodebuild
(or alternatively for example for release)

cmake --build . --config Release

/ VST Home / Tutorials / Building the examples

Building the examples included in the SDK on Linux

On this page:

• Goal
• Part 1: Getting and installing the VST 3 SDK
• Part 2: Building the examples on Linux

Goal

This tutorial explains how to set up your computer and create an environment for compiling the VST 3 audio plug-in examples provided with the VST 3 SDK. These include plug-ins like simple DSP effects (Gain, compressor, delay, ...), synths instruments and some plug-ins showing how to handle some specific VST 3 features (Note Expression, Program Change, channel info context, ...).

They can be loaded into VST 3 hosts like Cubase, WaveLab, ...

Part 1: Getting and installing the VST 3 SDK

For downloading the SDK, see this section "How to set up my system for VST 3".

Download cmake from: https://cmake.org/download/ or use a package manager for your OS.

Part 2: Building the examples on Linux

• Install the required packages: Required packages
• Create a folder for the build and move to this folder (using cd):

mkdir build
cd build

• Generate the solution/projects: specify the path to the project where CMakeLists.txt is located:

cmake ../vst3sdk

• Build the plug-in:

make
(or alternatively for example for release)

cmake --build . --config Release

/ VST Home / Tutorials

Using cmake for building VST 3 plug-ins

On this page:

• Goal
• CMake for building VST 3 plug-ins
• Command line for Windows
• Command line for macOS
• On Linux with QtCreator
• Use of cmake-gui
• Available SMTG cmake options
• Using your IDE for compiling the examples

Related pages:

• How to set up my system for VST 3
• Building the examples included in the SDK on Windows
• Building the examples included in the SDK on macOS
• Building the examples included in the SDK on Linux

Goal

This tutorial explains how to use cmake with VST 3 SDK.

CMake for building VST 3 plug-ins

The SDK provides a set of cmake files allowing you to compile the included samples and to develop new plug-ins.

• Download cmake from: https://cmake.org or use a package manager for your OS (See How to set up my system for VST 3).
• You can use the command line or the cmake editor (cmake-gui).

Command line for Windows

Example for building Microsoft Studio 17 2022 solution:

// go in to the folder where you extracted the VST 3 SDK
mkdir build
cd build
cmake.exe -G "Visual Studio 17 2022" -A x64 "..\vst3sdk"
// or without symbolic links
cmake.exe -G "Visual Studio 17 2022" -A x64 "..\vst3sdk" -DSMTG_CREATE_PLUGIN_LINK=0

// or with symbolic links but using the user location (enable by default), it does not request admin right
cmake.exe -G "Visual Studio 17 2022" -A x64 "..\vst3sdk" -DSMTG_PLUGIN_TARGET_USER_PROGRAM_FILES_COMMON=1

// note: you can find the string definition for different Visual Studio Generators in the cmake online documentation

Command line for macOS

Example for building Xcode project:

// go in to the folder where you extracted the VST 3 SDK
mkdir build
cd build
/Applications/CMake.app/Content/bin/cmake -G"Xcode" "../vst3sdk"

On Linux with QtCreator

You can use QtCreator 2.3.1 (or higher)

• start QtCreator 2.3.2
• open the CMakeLists.txt located at the top of the VST3_SDK folder
• click on the menu Build->Run CMake

Use of cmake-gui

• start the CMake (cmake-gui) application
• set Where is the source code to the location of the VST3_SDK folder
• set Where to build the binaries to a build folder of yourchoice
• click on Configure
• click on Generate for creating project/solution

Example of cmakegui application on Windows

• Compile with cmake command line

cd build
cmake --build

• Choose a specific compiler with cmake (command line on Linux)

cmake -DCMAKE_C_COMPILER=/usr/bin/clang-DCMAKE_CXX_COMPILER=/usr/bin/clang++

// or

cmake -DCMAKE_C_COMPILER=/usr/bin/gcc-DCMAKE_CXX_COMPILER=/usr/bin/g++

Available SMTG cmake options

• SMTG_AAX_SDK_PATH: Here, you can define where the AAX SDK is located (if needed)
• SMTG_ENABLE_VST3_HOSTING_EXAMPLES: Enable VST 3 Hosting Examples (default ON)
• SMTG_ENABLE_VST3_PLUGIN_EXAMPLES: Enable VST 3 Plug-in Examples (default ON)
• SMTG_ENABLE_VSTGUI_SUPPORT: Enable VSTGUI Support (default ON)
• SMTG_BUILD_UNIVERSAL_BINARY: Build universal binary (32 & 64 bit) (Mac only)
• SMTG_COREAUDIO_SDK_PATH: Here, you can define where the COREAUDIO SDK is located (Mac only, if needed)
• SMTG_CREATE_BUNDLE_FOR_WINDOWS: Create bundle on Windows for the VST 3 plug-ins (new since 3.6.10! Windows only) (default ON)
• SMTG_CREATE_MODULE_INFO: Create the moduleinfo.json file (default ON)
• SMTG_CREATE_PLUGIN_LINK: Create symbolic link for each VST 3 plug-in in ${VST3_FOLDER_NAME} folder (you need to have Administrator rights on Windows or change the Local Group Policy to allow the creation of symbolic links) (default ON)
• SMTG_CUSTOM_BINARY_LOCATION: Customize output location for binaries
• SMTG_CXX_STANDARD: C++ standard version used for plugins: 14, 17, 20
• SMTG_ENABLE_ADDRESS_SANITIZER: Enable Address Sanitizer
• SMTG_ENABLE_TARGET_VARS_LOG: Enables to log target variables for debugging (new since 3.6.11!) (default OFF)
• SMTG_ENABLE_USE_OF_JACK: Allows you to create the audiohost application using Jack (default OFF)
• SMTG_MDA_VST3_VST2_COMPATIBLE: Build the MDA examples as a replacement for their VST 2 counterpart (default ON)
• SMTG_IOS_DEVELOPMENT_TEAM: Needed for building the InterAppAudio and AUv3 examples for iOS (Mac only)
• SMTG_MYPLUGINS_SRC_PATH: Here, you can add your VST 3 plug-ins folder
• SMTG_PLUGIN_TARGET_PATH: Here, you can redefine the VST 3 plug-ins folder
• SMTG_PLUGIN_TARGET_USER_PROGRAM_FILES_COMMON: use FOLDERID_UserProgramFilesCommon as VST 3 target path (Windows only) (default ON)
• SMTG_RENAME_ASSERT: Rename ASSERT to SMTG_ASSERT to avoid conflicts with 3rd party libraries (default ON)
• SMTG_RUN_VST_VALIDATOR: Run the VST validator on VST 3 plug-ins each time they are built (default ON)
• SMTG_USE_STATIC_CRT: Use static CRuntime on Windows (option /MT) (default OFF: /MD is used) (Windows only)

Using your IDE for compiling the examples

• Solution/project (vstsdk.sln/vstsdk.xcodeproj) is generated in the "build" folder.
• The created plug-ins are located in the "build" folder, in sub-folders /VST3/Release or /VST3/Debug.
• In order to allow a DAW to find these plug-ins you have to create links from the official VST 3 Locations to them.

/ VST Home / Tutorials

Generate a new plug-in with the Project Generator App

On this page:

• Goal
• Part 1: Getting and installing the VST 3 SDK
• Part 2: Using the VST 3 plug-in Project Generator application

Goal

This tutorial explains how to create a new audio plug-in by using the VST 3 Project Generator included in the VST 3 SDK and how to add some basic features.

The artifact will be an audio plug-in that can compute a gain to an audio signal and can be loaded into VST 3 hosts like Cubase, WaveLab, ...

Part 1: Getting and installing the VST 3 SDK

For downloading the SDK, see the section "How to set up my system for VST 3".

You have the following possibilities to start a new project:

• You can use the helloworld template.
• Or, which is easier and recommended, you can use the VST 3 Project Generator application included in the VST 3 SDK. The following steps show how to use it.

Part 2: Using the VST 3 plug-in Project Generator application

The VST3 Project Generator application included in the VST 3 SDK is available for Windows and for macOS.

Start the application located in the VST3_Project_Generator folder of the VST 3 SDK.

Check that the Preferences tab has the required information: see Setting the Preferences.

In the Create Plug-in Project tab you have to enter information about the plug-in that you want create:

Check the Create Plug-in Project tab of the VST 3 Project Generator dialog for more detailed documentation.

Once you have entered all information, click Create. A script is started which creates a project with updated files in the Output directory. After this step, the IDE (Visual Studio or XCode) is launched.

Compile the project and test your new plug-in. The plug-in is created in the Output Directory, in order to make it visible to a VST 3 host you may have to copy or symbolic-link it to the official VST 3 Locations / Format.

For example, if you chose Audio Effect as Type, a simple Stereo→Stereo plug-in is created.

A good way to understand how a VST 3 plug-in works is to add breakpoints in each function in the processor and controller files:

tresult PLUGIN_API MyPluginController::initialize (FUnknown*context);
tresult PLUGIN_API MyPluginController::terminate ();
//...
tresult PLUGIN_API MyPluginProcessor::initialize (FUnknown*context);
//...

and start a VST 3 host from the debugger.

That´s it, now you could start to code, see next tutorial Code your first plug-in.

/ VST Home / Tutorials

Code your first Plug-in

On this page:

• Goal
• Part 1: Coding your plug-in
  • Add a parameter: Gain
  • Add the process applying the gain
  • Add store/restore state
• Part 2: Advanced Steps
  • Add an Event Input
  • Add a mono audio Side-chain

Goal

Following the previous tutorial Generate a new plug-in with the Project Generator App, this tutorial explains how to code an audio plug-in and how to add some basic features.

The artifact will be an audio plug-in that can compute a gain to an audio signal and can be loaded into VST 3 hosts like Cubase, WaveLab, ...

Part 1: Coding your plug-in

Now you have an automatically generated frame for your plug-in. The following sections explain how to add a new parameter, its associated processing algorithm, and other specific features like saving/loading project or presets, creating a dedicated user interface, etc.

A VST 3 plug-in contains two main classes: its PlugProcessor (performing the processing and persistence) and its PlugController (taking care of communication with the DAW, handling parameters and the UI).

Add a parameter: Gain

In this basic plug-in example, we will add a Gain parameter which modifies the volume of the audio going through the plug-in.

For this, each VST 3 parameter requires a unique identifier (a number).

1. Open the file plugids.h and enter a new id kParamGainId. In this example, assign the unique number 102 for example.

plugids.h

#include "pluginterfaces/vst/vsttypes.h"

enum GainParams : Steinberg::Vst::ParamID
{
    kParamGainId = 102, // should be a unique id...
};

2. Open the plugcontroller.cpp file, and add the gain parameter with the parameters.addParameter

plugcontroller.cpp

// Include the file where some ids are defined
#include "plugids.h"

//----------------------------------------------------------------------------
tresult PLUGIN_API PlugController::initialize (FUnknown*context)
{
    tresult result = EditController::initialize (context);
    if (result != kResultOk)
    {
        return result;
    }

    //---Create Parameters------------
    parameters.addParameter (STR16 ("Gain"), STR16 ("dB"), 0, .5, Vst::ParameterInfo::kCanAutomate, GainParams::kParamGainId, 0);

    return kResultTrue;
}

ⓘ Note\

• We add the flag kCanAutomate which informs the DAW/host that this parameter can be automated.
• A VST 3 parameter is always normalized (its value is a floating point value between [0.0, 1.0]), here its default value is set to 0.5.

3. Now adapt the processor part for this new parameter. Open the file plugprocessor.h and add a gain value Vst::ParamValue mGain. This value is used for the processing to apply the gain.

plugprocessor.h

// ... 
static FUnknown* createInstance (void*)
{
    return (Steinberg::Vst::IAudioProcessor*)new PlugProcessor ();
}
protected:
    Steinberg::Vst::ParamValue mGain = 1.;
// ...

Add the process applying the gain

1. We need to set our internal mGain with its required value from the host. This is the first step of the process method. Parse the parameter change coming from the host in the structure data.inputParameterChanges for the current audio block to process.
   ⓘ Be sure to add #include "public.sdk/source/vst/vstaudioprocessoralgo.h at top of the file plugprocessor.cpp!
   This includes some helpers to access audio buffer.

plugprocessor.cpp

#include "pluginterfaces/vst/ivstparameterchanges.h"
#include "public.sdk/source/vst/vstaudioprocessoralgo.h"

//----------------------------------------------------------------------------
tresult PLUGIN_API PlugProcessor::process (Vst::ProcessData&data)
{
    //--- First: Read inputs parameter changes-----------
    if (data.inputParameterChanges)
    {
        // for each parameter defined by its ID
        int32 numParamsChanged = data.inputParameterChanges->getParameterCount ();
        for (int32 index = 0; index < numParamsChanged; index++)
        {
            // for this parameter we could iterate the list of value changes (could 1 per audio block or more!)
            // in this example, we get only the last value (getPointCount - 1)
            Vst::IParamValueQueue* paramQueue = data.inputParameterChanges->getParameterData (index);
            if (paramQueue)
            {
                Vst::ParamValue value;
                int32 sampleOffset;
                int32 numPoints = paramQueue->getPointCount ();
                switch (paramQueue->getParameterId ())
                {
                    case GainParams::kParamGainId:
                        if (paramQueue->getPoint (numPoints - 1, sampleOffset, value) == kResultTrue)
                            mGain = value;
                        break;
                }
            }
        }
    }
    // ....
}

ⓘ Note
data.inputParameterChanges can include more than 1 change for the same parameter inside a processing audio block. Here we take only the last change in the list and apply it our mGain.

2. The real processing part:

plugprocessor.cpp

// ...

//-- Flush case: we only need to update parameter, noprocessing possible
if (data.numInputs == 0 || data.numSamples == 0)
    return kResultOk;

//--- Here, you have to implement your processing
int32 numChannels = data.inputs[0].numChannels;

//---get audio buffers using helper-functions(vstaudioprocessoralgo.h)-------------
uint32 sampleFramesSize = getSampleFramesSizeInBytes(processSetup, data.numSamples);
void** in = getChannelBuffersPointer (processSetup, data.inputs[0]);
void** out = getChannelBuffersPointer (processSetup, data.outputs[0]);

// Here could check the silent flags
// now we will produce the output
// mark our outputs has not silent
data.outputs[0].silenceFlags = 0;

float gain = mGain;
// for each channel (left and right)
for (int32 i = 0; i < numChannels; i++)
{
    int32 samples = data.numSamples;
    Vst::Sample32* ptrIn = (Vst::Sample32*)in[i];
    Vst::Sample32* ptrOut = (Vst::Sample32*)out[i];
    Vst::Sample32 tmp;
    // for each sample in this channel
    while (--samples >= 0)
    {
        // apply gain
        tmp = (*ptrIn++) * gain;
        (*ptrOut++) = tmp;
    }
}
//...

3. VST 3 includes a way for the host to inform the plug-in that its inputs are silent (using the VST 3 silence flags):

plugprocessor.cpp

// Here could check the silent flags
//---check if silence---------------
// normally we have to check each channel (simplification)
if (data.inputs[0].silenceFlags != 0)
{
    // mark output silence too
    data.outputs[0].silenceFlags = data.inputs[0].silenceFlags;

    // the plug-in has to be sure that if it sets the flags silence that the output buffer are clear
    for (int32 i = 0; i < numChannels; i++)
    {
       // do not need to be cleared if the buffers are the same (in this case input buffer are
        // already cleared by the host)
        if (in[i] != out[i])
        {
            memset (out[i], 0, sampleFramesSize);
        }
    }
    // nothing to do at this point
    return kResultOk;
}

Add store/restore state

The Processor part represents the state of the plug-in, so it is its job to implement the getState/setState method used by the host to save/load projects and presets. The Controller part gets the Processor state too in its setComponentState method which allows to synchronize its parameters too (used for example by the UI).

1. In the file plugprocessor.cpp, add the mGain value to the state stream given by the host in the getState method which will save it as a project or preset.
   The helper class IBStreamer could be used for handling the IBStream given by the host.

plugprocessor.cpp

// add this include at the top of the file
#include "base/source/fstreamer.h"

//-----------------------------------------------------------------------
tresult PLUGIN_API PlugProcessor::getState (IBStream* state)
{
    // here we need to save the model (preset or project)
    float toSaveParam1 = mGain;
    IBStreamer streamer (state, kLittleEndian);
    streamer.writeFloat (toSaveParam1);
    return kResultOk;
}

2. In the setState method, the plug-in receives a new state from the host, it is called after a project or preset is loaded.

plugprocessor.cpp

//-----------------------------------------------------------------------
tresult PLUGIN_API PlugProcessor::setState (IBStream* state)
{
    if (!state)
        return kResultFalse;

    // called when we load a preset or project, the model has to be reloaded
    IBStreamer streamer (state, kLittleEndian);
    float savedParam1 = 0.f;
    if (streamer.readFloat (savedParam1) == false)
        return kResultFalse;
    mGain = savedParam1;

    return kResultOk;
}

3. In the setComponentState method, the Controller part of the plug-in receives the same state than the one used in PlugProcessor::setState. PlugController::setComponentState is called just after PlugProcessor::setState.

plugcontroller.cpp

// add this include at the top of the file
#include "base/source/fstreamer.h"

//-----------------------------------------------------------------------
tresult PLUGIN_API PlugController::setComponentState (IBStream* state)
{
	// Here, you get the state of the component (Processor part)
	if (!state)
		return kResultFalse;

    IBStreamer streamer (state, kLittleEndian);
    float savedParam1 = 0.f;
    if (streamer.readFloat (savedParam1) == false)
        return kResultFalse;

	// sync with our parameter
	if (auto param = parameters.getParameter (GainParams::kParamGainId))
		param->setNormalized (savedParam1);

    return kResultOk;
}

Part 2: Advanced Steps

Add an Event Input

In our example we want to modify our current Gain factor with the velocity of a played "MIDI" event (noteOn).

1. If you need in your plug-in to receive not only audio but events (like MIDI), you have to add an Event input. For this you just have to add the Event input with addEventInput in the initialize method of the processor:

plugprocessor.cpp

//-----------------------------------------------------------------------
tresult PLUGIN_API PlugProcessor::initialize (FUnknown* context)
{
    //---always initialize the parent-------
    tresult result = AudioEffect::initialize (context);
    // if everything Ok, continue
    if (result != kResultOk)
    {
        return result;
    }

    //....

    //---create Event In/Out busses (1 bus with only 1 channel)------
    addEventInput (STR16 ("Event In"), 1);

    return kResultOk;
}

ⓘ Note
In this example, we add 1 input event bus, receiving only on 1 channel. If you need to receive differentiated events, for example, from different channels, just change it in the following way:

addEventInput (STR16 ("Event In"), 4); // here 4 channels

2. We create a new internal value mGainReduction (not exported to the host) which is changed by the velocity of a played noteOn, so that the harder you hit the note, the higher is the gain reduction (this is what we want here in this plug-in):

plugprocessor.h

// ... 
static FUnknown* createInstance (void*)
{
    return (Steinberg::Vst::IAudioProcessor*)new PlugProcessor ();
}
protected:
    Steinberg::Vst::ParamValue mGain= 1.;
    Steinberg::Vst::ParamValue mGainReduction = 0.;
// ...

3. Now we have to receive the event changes in the process method:

plugprocessor.cpp

//-----------------------------------------------------------------------
tresult PLUGIN_API PlugProcessor::process (ProcessData& data)
{
    //--- First: Read inputs parameter changes-----------
    //...

    //---Second: Read input events-------------
    // get the list of all event changes
    Vst::IEventList* eventList = data.inputEvents;
    if (eventList)
    {
        int32 numEvent = eventList->getEventCount ();
        for (int32 i = 0; i < numEvent; i++)
        {
            Vst::Event event;
            if (eventList->getEvent (i, event) == kResultOk)
            {
                // here we do not take care of the channel info of the event
                switch (event.type)
                {
                    //----------------------
                    case Vst::Event::kNoteOnEvent:
                        // use the velocity as gain modifier: a velocity max (1) will lead to silent audio
                        mGainReduction = event.noteOn.velocity; // value between 0 and 1
                        break;
                    
                    //----------------------
                    case Vst::Event::kNoteOffEvent:
                        // noteOff reset the gain modifier
                        mGainReduction = 0.f;
                        break;
                }
            }
        }
    }

4. Make use of this mGainReduction in our real processing part:

plugprocessor.cpp

//----------------------------------------------------------------------------
tresult PLUGIN_API PlugProcessor::process (Vst::ProcessData&data)
{
    //....

    float gain = mGain - mGainReduction;
    if (gain < 0.f)  // gain should always positive or zero
        gain = 0.f;

    // for each channel (left and right)
    for (int32 i = 0; i < numChannels; i++)
    {
        int32 samples = data.numSamples;
        Vst::Sample32* ptrIn = (Vst::Sample32*)in[i];
        Vst::Sample32* ptrOut = (Vst::Sample32*)out[i];
        Vst::Sample32 tmp;
        // for each sample in this channel
        while (--samples >= 0)
        {
            // apply gain
            tmp = (*ptrIn++) * gain;
            (*ptrOut++) = tmp;
        }
    }
    //...
}

Add a mono audio Side-chain

In our example we want to modulate our main audio input with a Side-chain audio input.

1. First, add a new side-chain audio input (busType: kAux) in the initialize call of our processor:

plugprocessor.cpp

//-----------------------------------------------------------------------
tresult PLUGIN_API PlugProcessor::initialize (FUnknown*context)
{
    //---always initialize the parent-------
    tresult result = AudioEffect::initialize (context);
    // if everything Ok, continue
    if (result != kResultOk)
    {
        return result;
    }

    //....

    //---create Event In/Out busses (1 bus with only 1 channel)------
    addEventInput (STR16 ("Event In"), 1);

    // create a Mono SideChain input bus
    addAudioInput (STR16 ("Mono Aux In"), Steinberg::Vst::SpeakerArr::kMono, Steinberg::Vst::kAux, 0);

    return kResultOk;
}

2. We want to be sure that our side-chain is handled as mono input. For this we need to overwrite the AudioEffect::setBusArrangements function:

plugprocessor.h

//-----------------------------------------------------------------------
class PlugProcessor: public AudioEffect
{
public:
    PlugProcessor ();
    
    //...
    // overwrite this function
    Steinberg::tresult PLUGIN_API setBusArrangements (Steinberg::Vst::SpeakerArrangement* inputs,
                                                    Steinberg::int32 numIns,
                                                    Steinberg::Vst::SpeakerArrangement* outputs,
                                                    Steinberg::int32 numOuts) SMTG_OVERRIDE;
    //...
};

plugprocessor.cpp

//-----------------------------------------------------------------------
tresult PLUGIN_API PlugProcessor::setBusArrangements(Vst::SpeakerArrangement* inputs, int32 numIns,
                                                    Vst::SpeakerArrangement* outputs,
                                                    int32 numOuts)
{
    // the first input is the Main Input and the second is the SideChain Input
    // be sure that we have 2 inputs and 1 output
    if (numIns == 2 && numOuts == 1)
    {
        // we support only when Main input has the same number of channel than the output
        if (Vst::SpeakerArr::getChannelCount (inputs[0]) != Vst::SpeakerArr::getChannelCount (outputs[0]))
            return kResultFalse;

        // we are agree with all arrangement for Main Input and output
        // then apply them
        getAudioInput (0)->setArrangement (inputs[0]);
        getAudioOutput (0)->setArrangement (outputs[0]);

        // Now check if sidechain is mono (we support in our example only mono Side-chain)
        if (Vst::SpeakerArr::getChannelCount (inputs[1]) != 1)
            return kResultFalse;

        // OK the Side-chain is mono, we accept this by returning kResultTrue
        return kResultTrue;
    }

    // we do not accept what the host wants: return kResultFalse !
    return kResultFalse;
}

3. Adapt our process using the side-chain input as modulation:

//-----------------------------------------------------------------------
tresult PLUGIN_API PlugProcessor::process (ProcessData& data)
{
    //--- First: Read inputs parameter changes-----------
    //...

    //---Second: Read input events-------------
    //...

    float gain = mGain - mGainReduction;
    if (gain < 0.f)  // gain should always positive or zero
        gain = 0.f;

    void** auxIn = nullptr;
    
    // Check if the Side-chain input is activated
    bool auxActive = false;
    if (getAudioInput (1)->isActive ())
    {
        auxIn = getChannelBuffersPointer (processSetup, data.inputs[1]);
        auxActive = true;
    }
    if (auxActive)
    {
        // for each channel (left and right)
        for (int32 i = 0; i < numChannels; i++)
        {
            int32 samples = data.numSamples;
            Vst::Sample32* ptrIn = (Vst::Sample32*)in[i];
            Vst::Sample32* ptrOut = (Vst::Sample32*)out[i];
            // Side-chain is mono, so take auxIn[0]: index 0
            Vst::Sample32* ptrAux = (Vst::Sample32*)auxIn[0];
            Vst::Sample32 tmp;

            // for each sample in this channel
            while (--samples >= 0)
            {
                // apply modulation and gain
                tmp = (*ptrIn++) * (*ptrAux++) * gain;
                (*ptrOut++) = tmp;
            }
        }
    }
    else
    {
        // for each channel (left and right)
        for (int32 i = 0; i < numChannels; i++)
        {
            int32 samples = data.numSamples;
            Vst::Sample32* ptrIn = (Vst::Sample32*)in[i];
            Vst::Sample32* ptrOut = (Vst::Sample32*)out[i];
            Vst::Sample32 tmp;
            // for each sample in this channel
            while (--samples >= 0)
            {
                // apply gain
                tmp = (*ptrIn++) * gain;
                (*ptrOut++) = tmp;
            }
        }
    }

That´s it!

/ VST Home / Tutorials

Use VSTGUI to design a User Interface

On this page:

• Goal
• Part 1: Preparation
• Part 2: Open the VSTGUI/WYSWYG editor
• Part 3: Parameter Binding
• Part 4: Creating Custom Views
• Part 5: Showcase

Goal

This tutorial explains how to use VSTGUI. VSTGUI comes with a WYSIWYG editor that allows you to create stunning user interfaces for your plug-in.

Part 1: Preparation

If you have created your project with the VST 3 Project Generator and check the "Use VSTGUI" you can directly jump to Part 2 of this tutorial.

Before using the inline UI editor, you must make sure that you use the Steinberg::Vst::EditController class as a base of your own edit controller and that you have used the Steinberg::Vst::Parameter class or any subclass of it for your parameters. Otherwise the inline UI editor won't work properly.

Next you have to add vstgui to your project. For cmake users, you can just add the vstgui_support library to your target:

target_link_libraries(${target} PRIVATE vstgui_support)

If you are not using cmake, you have to manually include the following source files to your project:

• vstgui/vstgui_[ios/mac/linux/win32].[cpp/mm]
• vstgui/vstgui_uidescription.cpp
• vstgui/plugin-bindings/vst3editor.cpp

After that you have to alter your project settings to add a preprocessor definition to your debug build:

• VSTGUI_LIVE_EDITING=1

With cmake, this would look like this:

target_compile_definitions(${target} PUBLIC$<$<CONFIG:Debug>:VSTGUI_LIVE_EDITING=1>)

Finally, you have to modify your edit controller class to overwrite the createView() method:

#include "vstgui/plugin-bindings/vst3editor.h"

IPlugView* PLUGIN_API MyEditController::createView (FIDStringname)
{
    if (strcmp (name, ViewType::kEditor) == 0)
    {
        return new VSTGUI::VST3Editor (this, "view", "myEditor.uidesc");
    }
    return 0;
}

Also make sure to include the vst3editor.h header.

Now you can build your plug-in and start your preferred VST 3 host to start designing your user interface.

Part 2: Open the VSTGUI/WYSWYG editor

If you now open your plug-in UI in your host, you will see a blank editor. To enter the UI editor, right-click on it and choose "Open UIDescription Editor".

After your first edits, you have to add the uidesc file you have saved to your project (already done if you have used VST 3 Project Generator). You also have to make sure to always build your project after changes to the uidesc file.

Part 3: Parameter Binding

If you've used the Parameter class provided by the VST 3 SDK, you get automatic parameter bindings between the controls of your editor and the parameters in your VST Edit Controller.

The only thing you need to do is to declare the IDs of the parameters as tags in the Tags editor (or use the 'Sync Parameter Tags' command in the Edit menu of the toolbar) and set the tags of your controls to these IDs. Your VST Edit Controller now receives the beginEdit(...)/performEdit(...)/endEdit(...) calls when the user changes the controls. If the host automates the parameter, the control also reflects these changes.

Additionally, you can modify your VST Edit Controller to return specific parameter objects in the getParameterObject(int32 paramID) method for UI only needs, which are not parameters of your VST audio processor. This way you can store view settings (like the tab which is open when the user closes the editor so that it can be restored when the user opens the editor again). You can look at the sources of the included 'uidescription test' project for more information on how this works.

Part 4: Creating Custom Views

If you need to create custom views, you can implement the VSTGUI::VST3EditorDelegate interface in your edit controller class. The createCustomView method is called if you set the 'custom-view-name' attribute in one of the views.

Another way to use your own views is to register them at runtime with the UIViewFactory. This method requires more work but has the advantage that the view is listed like the built-in views and changing attributes works on the fly. See VSTGUI::IViewCreator.

Part 5: Showcase

Here's an example video recorded while creating the new user interface for the famous Grungelizer plug-in of Cubase after it was ported from VST 2.4 to VST 3.

Create the VST 3 Grungelizer UI in 15 minutes with the UIDescriptionEditor of VSTGUI

/ VST Home / Tutorials

Data Exchange Tutorial - How to send data from the realtime process to the edit controller

On this page:

• Tutorial - How to use the Data Exchange API
  • Sending data from the audio processor
  • Receiving data in the edit controller

Related pages:

• Data Exchange

You'll find the source for this tutorial in the tutorial repository

Tutorial - How to use the Data Exchange API

In this tutorial, you learn how to use the Data Exchange API to send data from the realtime audio process method to the edit controller of your plug-in.

Sending data from the audio processor

Let's send data from the processor to the controller.

First, we need to add the required include so that we can use the wrapper class. Add the following include before you define your audio processor:

#include "public.sdk/source/vst/utility/dataexchange.h"

To prepare the AudioEffect class, you need to overwrite the following methods:

tresult PLUGIN_API initialize (FUnknown* context) override;
tresult PLUGIN_API connect (Vst::IConnectionPoint* other) override;
tresult PLUGIN_API disconnect (Vst::IConnectionPoint* other) override;
tresult PLUGIN_API setActive (TBool state) override;
tresult PLUGIN_API canProcessSampleSize (int32 symbolicSampleSize) override;
tresult PLUGIN_API process (Vst::ProcessData& data) override;

And we also have to add the wrapper class as a member of our audio processor class:

std::unique_ptr<Vst::DataExchangeHandler> dataExchange;

Now we can initialize and configure the dataExchange. We do this in:

tresult PLUGIN_API DataExchangeProcessor::connect (Vst::IConnectionPoint* other)
{
    auto result = Vst::AudioEffect::connect (other);
    if (result == kResultTrue)
    {
        auto configCallback = [this] (Vst::DataExchangeHandler::Config& config,
                                      const Vst::ProcessSetup& setup) {
            Vst::SpeakerArrangement arr;
            getBusArrangement (Vst::BusDirections::kInput, 0, arr);
            numChannels = static_cast<uint16_t> (Vst::SpeakerArr::getChannelCount (arr));
            auto sampleSize = sizeof (float);

            config.blockSize = setup.sampleRate * numChannels * sampleSize + sizeof (DataBlock);
            config.numBlocks = 2;
            config.alignment = 32;
            config.userContextID = 0;
            return true;
        };

        dataExchange = std::make_unique<Vst::DataExchangeHandler> (this, configCallback);
        dataExchange->onConnect (other, getHostContext ());
    }
    return result;
}

The configration is done via the configCallback. In this example, we configure the queue to have a block size to store exactly 1 second of audio data of all the channels of the configured speaker arrangement of the input bus. We choose two for numBlocks because we send one block per second, and in this case, two blocks should be enough. If the frequency you need to send the block is higher, you need to increase this value to prevent data drop outs. The configCallback is called when the audio processor is activated.

The next thing we have to do is to call the dataExchange object when the edit controller is disconnected and release the memory:

tresult PLUGIN_API DataExchangeProcessor::disconnect (Vst::IConnectionPoint* other)
{
    if (dataExchange)
    {
        dataExchange->onDisconnect (other);
        dataExchange.reset ();
    }
    return AudioEffect::disconnect (other);
}

And we also have to call the dataExchange object when the processor's state changes:

tresult PLUGIN_API DataExchangeProcessor::setActive (TBool state)
{
    if (state)
        dataExchange->onActivate (processSetup);
    else
        dataExchange->onDeactivate ();
    return AudioEffect::setActive (state);
}

Now we prepare the data that we want to send to the controller. To make this a little bit easier, we define a struct that specifies what should look like and move this into its own header "dataexchange.h":

// dataexchange.h

#pragma once

#include "public.sdk/source/vst/utility/dataexchange.h"
#include <cstdint>

namespace Steinberg::Tutorial {

struct DataBlock
{
    uint32_t sampleRate;
    uint16_t sampleSize;
    uint16_t numChannels;
    uint32_t numSamples;
    float samples[0];
};

} // Steinberg::Tutorial

So, we want to send the sample rate, size, the number of channels and the number of samples plus the actual samples to the controller.

To actually work with this DataBlock struct, we introduce a little helper function that we also add to this header:

inline DataBlock* toDataBlock (const Vst::DataExchangeBlock& block)
{
    if (block.blockID != Vst::InvalidDataExchangeBlockID)
        return reinterpret_cast<DataBlock*> (block.data);
    return nullptr;
}

One thing remains to be done before we can start sending the data: We need a member variable of the Vst::DataExchangeBlock struct where we store the actual block we work with while processing the audio. So we add this to our processor defintion:

class DataExchangeProcessor : public Vst::AudioEffect
{
private:
    Vst::DataExchangeBlock currentExchangeBlock {InvalidDataExchangeBlock};
}

Now let's start to implement the processing:

tresult PLUGIN_API DataExchangeProcessor::process (Vst::ProcessData& processData)
{
    if (processData.numSamples <= 0)
        return kResultTrue;
    return kResultTrue;
}

When there are no samples in the processData we jump out of the method directly.

Now the first thing we need to do is to acquire a new block from the dataExchange object:

tresult PLUGIN_API DataExchangeProcessor::process (Vst::ProcessData& processData)
{
    // ...
    if (currentExchangeBlock.blockID == Vst::InvalidDataExchangeBlockID)
        acquireNewExchangeBlock ();
    // ...
}

We only want to acquire a new block if we have not already done so. Therefore, we need to check this before we call the acquireNewExchangeBlock method that does this:

void DataExchangeProcessor::acquireNewExchangeBlock ()
{
    currentExchangeBlock = dataExchange->getCurrentOrNewBlock ();
    if (auto block = toDataBlock (currentExchangeBlock))
    {
        block->sampleRate = static_cast<uint32_t> (processSetup.sampleRate);
        block->numChannels = numChannels;
        block->sampleSize = sizeof (float);
        block->numSamples = 0;
    }
}

We ask the dataExchange object for a new block with getCurrentOrNewBlock (), check if it is valid with a call to the previously defined function toDataBlock and fill it with the sample rate, the sample size and the number of channels.

Now back to our process function. We now write the samples from the input buffer into our block until the block is filled with 1 second of audio data:

tresult PLUGIN_API DataExchangeProcessor::process (Vst::ProcessData& processData)
{
    // ...
    auto input = processData.inputs[0];
    auto output = processData.outputs[0];

    if (auto block = toDataBlock (currentExchangeBlock))
    {
        auto numSamples = static_cast<uint32> (processData.numSamples);
        while (numSamples > 0)
        {
            uint32 numSamplesFreeInBlock = block->sampleRate - block->numSamples;
            uint32 numSamplesToCopy = std::min<uint32> (numSamplesFreeInBlock, numSamples);
            for (auto channel = 0; channel < input.numChannels; ++channel)
            {
                auto blockChannelData = &block->samples[0] + block->numSamples;
                auto inputChannel =
                    input.channelBuffers32[channel] + (processData.numSamples - numSamples);
                memcpy (blockChannelData, inputChannel, numSamplesToCopy * sizeof (float));
            }
            block->numSamples += numSamplesToCopy;
            if (block->numSamples == block->sampleRate)
            {
                dataExchange->sendCurrentBlock ();
                acquireNewExchangeBlock ();
                block = toDataBlock (currentExchangeBlock);
                if (block == nullptr)
                    break;
            }
            numSamples -= numSamplesToCopy;
        }
    }
    // ...
}

When it is filled with 1 second of audio data we send the block with dataExchange->sendCurrentBlock() and directly acquire a new block afterwards.

Finally, we need to copy back the input audio buffers to the output audio buffers. The whole method looks like this then:

tresult PLUGIN_API DataExchangeProcessor::process (Vst::ProcessData& processData)
{
    if (processData.numSamples <= 0)
        return kResultTrue;

    if (currentExchangeBlock.blockID == Vst::InvalidDataExchangeBlockID)
        acquireNewExchangeBlock ();

    auto input = processData.inputs[0];
    auto output = processData.outputs[0];

    if (auto block = toDataBlock (currentExchangeBlock))
    {
        auto numSamples = static_cast<uint32> (processData.numSamples);
        while (numSamples > 0)
        {
            uint32 numSamplesFreeInBlock = block->sampleRate - block->numSamples;
            uint32 numSamplesToCopy = std::min<uint32> (numSamplesFreeInBlock, numSamples);
            for (auto channel = 0; channel < input.numChannels; ++channel)
            {
                auto blockChannelData = &block->samples[0] + block->numSamples;
                auto inputChannel =
                    input.channelBuffers32[channel] + (processData.numSamples - numSamples);
                memcpy (blockChannelData, inputChannel, numSamplesToCopy * sizeof (float));
            }
            block->numSamples += numSamplesToCopy;
            if (block->numSamples == block->sampleRate)
            {
                dataExchange->sendCurrentBlock ();
                acquireNewExchangeBlock ();
                block = toDataBlock (currentExchangeBlock);
                if (block == nullptr)
                    break;
            }
            numSamples -= numSamplesToCopy;
        }
    }
    for (auto channel = 0; channel < input.numChannels; ++channel)
    {
        if (output.channelBuffers32[channel] != input.channelBuffers32[channel])
        {
            memcpy (output.channelBuffers32[channel], input.channelBuffers32[channel],
                    processData.numSamples * sizeof (float));
        }
        output.silenceFlags = input.silenceFlags;
    }

    return kResultOk;
}

Receiving data in the edit controller

We prepare our edit controller by adding the inheritance of Vst::IDataExchangeReceiver and by providing a few methods and adding a new Vst::DataExchangeReceiverHandler member:

class DataExchangeController : public Vst::EditControllerEx1,
                               public Vst::IDataExchangeReceiver
{
public:
    // ...
    tresult PLUGIN_API notify (Vst::IMessage* message) override;
    void PLUGIN_API queueOpened (Vst::DataExchangeUserContextID userContextID,
                                 uint32 blockSize,
                                 bool& dispatchOnBackgroundThread) override;
    void PLUGIN_API queueClosed (Vst::DataExchangeUserContextID userContextID) override;
    void PLUGIN_API onDataExchangeBlocksReceived (Vst::DataExchangeUserContextID userContextID, 
                                                  uint32 numBlocks,
                                                  Vst::DataExchangeBlock* blocks, 
                                                  bool onBackgroundThread) override;

    DEFINE_INTERFACES
        DEF_INTERFACE (Vst::IDataExchangeReceiver)
    END_DEFINE_INTERFACES (EditController)
    DELEGATE_REFCOUNT (EditController)
private:
    Vst::DataExchangeReceiverHandler dataExchange {this};
}

First, we need to forward messages to the DataExchangeReceiverHandler so that it can process the data exchange messages in case the host does not support the native API:

tresult PLUGIN_API DataExchangeController::notify (Vst::IMessage* message)
{
    if (dataExchange.onMessage (message))
        return kResultTrue;
    return EditControllerEx1::notify (message);
}

In the next step, we can implement the IDataExchangeReceiver methods:

void PLUGIN_API DataExchangeController::queueOpened (Vst::DataExchangeUserContextID userContextID,
                                                     uint32 blockSize,
                                                     bool& dispatchOnBackgroundThread)
{
    FDebugPrint ("Data Exchange Queue opened.\n");
}

void PLUGIN_API DataExchangeController::queueClosed (Vst::DataExchangeUserContextID userContextID)
{
    FDebugPrint ("Data Exchange Queue closed.\n");
}

void PLUGIN_API DataExchangeController::onDataExchangeBlocksReceived (
    Vst::DataExchangeUserContextID userContextID, uint32 numBlocks, Vst::DataExchangeBlock* blocks,
    bool onBackgroundThread)
{
    for (auto index = 0u; index < numBlocks; ++index)
    {
        auto dataBlock = toDataBlock (blocks[index]);
        FDebugPrint (
            "Received Data Block: SampleRate: %d, SampleSize: %d, NumChannels: %d, NumSamples: %d\n",
            dataBlock->sampleRate, static_cast<uint32_t> (dataBlock->sampleSize),
            static_cast<uint32_t> (dataBlock->numChannels),
            static_cast<uint32_t> (dataBlock->numSamples));
    }
}

The onDataExchangeBlocksReceived() method will be called each time the processor has sent a block. You can now do whatever you want with the data.

If you want the data to be dispatched on a background thread you need to set the dispatchOnBackgroundThread variable to true in the queueOpened method.

/ VST Home / Tutorials

Advanced VST 3 techniques

On this page:

• Part 1: Sample-accurate parameter handling
• Part 2: Adding 32 and 64 bit audio processing
• Part 3: Thread safe state changes

You'll find the source for this tutorial in the tutorial repository

In this tutorial, you will learn:

• How to add nearly sample-accurate parameter changes to an audio effect
• How to use C++ templates to write one algorithm supporting 32 bit and 64 bit audio processing
• How to set the state of the audio effect in a thread safe manner

Part 1: Sample-accurate parameter handling

We will start by looking at this process function:

void MyEffect::process (ProcessData& data)
{
    handleParameterChanges (data.inputParameterChanges);

    // get the gain value for this block
    ParamValue gain = gainParameter.getValue ();

    // process audio
    AudioBusBuffers* inputs = data.inputs;
    AudioBusBuffers* outputs = data.outputs;
    for (auto channelIndex = 0; channelIndex < inputs[0].numChannels; ++channelIndex)
    {
        for (auto sampleIndex = 0; sampleIndex < data.numSamples; ++sampleIndex)
        {
            auto sample = inputs[0].channelBuffers32[channelIndex][sampleIndex];
            outputs[0].channelBuffers32[channelIndex][sampleIndex] = sample * gain;
        }
    }
}

This is straightforward and simple, we handle the parameter changes in the function handleParameterChanges, which we will see in a moment. Then we get the last gain parameter value and iterate over the input buffers and copy the samples from there to the output buffers before applying the gain factor.

If we look at the handleParameterChanges function:

void MyEffect::handleParameterChanges (IParameterChanges*changes)
{
    if (!changes)
        return;
    int32 changeCount = changes->getParameterCount ();
    for (auto i = 0; i < changeCount; ++i)
    {
        if (auto queue = changes->getParameterData (i))
        {
            auto paramID = queue->getParameterId ();
            if (paramID == ParameterID::Gain)
            {
                int32 pointCount = queue->getPointCount ();
                if (pointCount > 0)
                {
                    int32 sampleOffset;
                    ParamValue value;
                    if (queue->getPoint (pointCount - 1, sampleOffset, value) == kResultTrue)
                        gainParameter.setValue (value);
                }
            }
        }
    }
}

We see that the Gain parameter only uses the last point for the gain value.

If we now want to use all points of the Gain parameter, we can use two utility classes from the SDK.

The first one is the ProcessDataSlicer which slices the audio block into smaller pieces.

void MyEffect::process (ProcessData& data)
{
    handleParameterChanges (data.inputParameterChanges);

    ProcessDataSlicer slicer (8);
    
    auto doProcessing = [this] (ProcessData& data) {
        // get the gain value for this block
        ParamValue gain = gainParameter.getValue ();

        // process audio
        AudioBusBuffers* inputs = data.inputs;
        AudioBusBuffers* outputs = data.outputs;
        for (auto channelIndex = 0; channelIndex < inputs[0].numChannels; ++channelIndex)
        {
            for (auto sampleIndex = 0; sampleIndex < data.numSamples; ++sampleIndex)
            {
                auto sample = inputs[0].channelBuffers32[channelIndex][sampleIndex];
                outputs[0].channelBuffers32[channelIndex][sampleIndex] = sample * gain;
            }
        }
    }
    
    slicer.process<SymbolicSampleSizes::kSample32> (data, doProcessing);
}

As you see, we have moved the algorithm part into a lambda doProcessing which is passed to slicer.process. This lambda is now called multiple times with a maximum of 8 samples per call until the whole buffer is processed. This doesn't give us yet a better parameter resolution, but we can now use the second utility class to handle this.

At first, we now look at the type of the gainParameter variable, as this is our next utility class:

SampleAccurate::Parameter gainParameter;

We have to change the handleParameterChanges function to:

void MyEffect::handleParameterChanges (IParameterChanges*inputParameterChanges)
{
    int32 changeCount = inputParameterChanges->getParameterCount ();
    for (auto i = 0; i < changeCount; ++i)
    {
        if (auto queue = changes->getParameterData (i))
        {
            auto paramID = queue->getParameterId ();
            if (paramID == ParameterID::Gain)
            {
                gainParameter.beginChanges (queue);
            }
        }
    }
    
}

in order to delegate the handling of the parameter changes to the gainParameter object.

Now we just need another small change in the process lambda to use the nearly sample-accurate gain value. We have to call the gainParameter object to advance the parameter value:

auto doProcessing = [this] (ProcessData& data) {
    // get the gain value for this block
    ParamValue gain = gainParameter.advance (data.numSamples);

    // process audio
    AudioBusBuffers* inputs = data.inputs;
    AudioBusBuffers* outputs = data.outputs;
    for (auto channelIndex = 0; channelIndex < inputs[0].numChannels; ++channelIndex)
    {
        for (auto sampleIndex = 0; sampleIndex < data.numSamples; ++sampleIndex)
        {
            auto sample = inputs[0].channelBuffers32[channelIndex][sampleIndex];
            outputs[0].channelBuffers32[channelIndex][sampleIndex] = sample * gain;
        }
    }
}

Finally, we have to do some cleanup of the gainParameter at the end of the process function by calling gainParameter.endChanges.

void MyEffect::process (ProcessData& data)
{
    handleParameterChanges (data.inputParameterChanges);

    ProcessDataSlicer slicer (8);
    
    auto doProcessing = [this] (ProcessData& data) {
        // get the gain value for this block
        ParamValue gain = gainParameter.advance (data.numSamples);

        // process audio
        AudioBusBuffers* inputs = data.inputs;
        AudioBusBuffers* outputs = data.outputs;
        for (auto channelIndex = 0; channelIndex < inputs[0].numChannels; ++channelIndex)
        {
            for (auto sampleIndex = 0; sampleIndex < data.numSamples; ++sampleIndex)
            {
                auto sample = inputs[0].channelBuffers32[channelIndex][sampleIndex];
                outputs[0].channelBuffers32[channelIndex][sampleIndex] = sample * gain;
            }
        }
    }
    
    slicer.process<SymbolicSampleSizes::kSample32> (data, doProcessing);
    
    gainParameter.endChanges ();
}

Now, we have nearly sample-accurate parameter changes support in this example. At intervals of eight samples, the gain parameter will be updated to the correct value.

It's very simple to make this 100% sample-accurate, check out the AGain Sample Accurate example in the SDK.

Part 2: Adding 32 and 64 bit audio processing

The example currently only supports 32 bit processing. Now we will add 64 bit processing.

As you may have noticed above, the ProcessDataSlicer uses a template parameter for its process function. This template parameter SampleSize defines the bit depth of the audio buffers in the ProcessData structure. This is currently hard-coded to be SymbolicSampleSizes::kSample32.

In order to support SymbolicSampleSizes::kSample64 we only have to make a few changes to the code. First, we adopt the algorithm part by introducing a new templated method to our effect:

template <SymbolicSampleSizes SampleSize>
void MyEffect::process (ProcessData& data)
{
}

We mostly just move the code from the original process method to this one, except the code for handling parameter changes:

template <SymbolicSampleSizes SampleSize>
void MyEffect::process (ProcessData& data)
{
    ProcessDataSlicer slicer (8);
    
    auto doProcessing = [this] (ProcessData& data) {
        // get the gain value for this block
        ParamValue gain = gainParameter.advance (data.numSamples);

        // process audio
        AudioBusBuffers* inputs = data.inputs;
        AudioBusBuffers* outputs = data.outputs;
        for (auto channelIndex = 0; channelIndex < inputs[0].numChannels; ++channelIndex)
        {
            for (auto sampleIndex = 0; sampleIndex < data.numSamples; ++sampleIndex)
            {
                auto sample = inputs[0].channelBuffers32[channelIndex][sampleIndex];
                outputs[0].channelBuffers32[channelIndex][sampleIndex] = sample * gain;
            }
        }
    }
    
    slicer.process<SampleSize> (data, doProcessing);
}

We just change the template parameter SampleSize of the process method of the ProcessDataSlicer to use the same template parameter as in our own process function.

This will not work correctly yet, as we still work with the 32 bit audio buffers in our doProcessing lambda. In order to fix this, we have to introduce two more templated functions getChannelBuffers that will choose the correct audio buffers depending on the SampleSize template parameter, which can either be SymbolicSampleSizes::kSample32 or SymbolicSampleSizes::kSample64:

template <SymbolicSampleSizes SampleSize,
        typename std::enable_if<SampleSize == SymbolicSampleSizes::kSample32>::type* = nullptr>
inline Sample32** getChannelBuffers (AudioBusBuffers& buffer)
{
    return buffer.channelBuffers32;
}

template <SymbolicSampleSizes SampleSize,
        typename std::enable_if<SampleSize == SymbolicSampleSizes::kSample64>::type* = nullptr>
inline Sample64** getChannelBuffers (AudioBusBuffers& buffer)
{
    return buffer.channelBuffers64;
}

Now we can change our doProcessing algorithm to use these functions:

template <SymbolicSampleSizes SampleSize>
void MyEffect::process (ProcessData& data)
{
    ProcessDataSlicer slicer (8);
    
    auto doProcessing = [this] (ProcessData& data) {
        // get the gain value for this block
        ParamValue gain = gainParameter.advance (data.numSamples);

        // process audio
        AudioBusBuffers* inputs = data.inputs;
        AudioBusBuffers* outputs = data.outputs;
        for (auto channelIndex = 0; channelIndex < inputs[0].numChannels; ++channelIndex)
        {
            auto inputBuffers = getChannelBuffers<SampleSize> (inputs[0])[channelIndex];
            auto outputBuffers = getChannelBuffers<SampleSize> (outputs[0])[channelIndex];
            for (auto sampleIndex = 0; sampleIndex < data.numSamples; ++sampleIndex)
            {
                auto sample = inputBuffers[sampleIndex];
                outputBuffers[sampleIndex] = sample * gain;
            }
        }
    };
    
    slicer.process<SampleSize> (data, doProcessing);
}

As a final step, we now need to call the templated process<...> function from the normal process function:

void MyEffect::process (ProcessData& data)
{
    handleParameterChanges (data.inputParameterChanges);

    if (processSetup.symbolicSampleSize == SymbolicSampleSizes::kSample32)
        process<SymbolicSampleSizes::kSample32> (data);
    else
        process<SymbolicSampleSizes::kSample64> (data);
    
    gainParameter.endChanges ();
}

Depending on the processSetup.symbolicSampleSize we either call the 32 bit process function or the 64 bit process function.

We just have to inform the host that we can process 64 bit:

tresult PLUGIN_API MyEffect::canProcessSampleSize (int32symbolicSampleSize)
{
    return (symbolicSampleSize == SymbolicSampleSizes::kSample32 ||
            symbolicSampleSize == SymbolicSampleSizes::kSample64) ?
            kResultTrue :
            kResultFalse;
}

Now we have sample-accurate parameter changes and 32 and 64 bit audio processing.

Part 3: Thread safe state changes

One common issue in this domain is that the plug-in state coming from a preset or a DAW project is set by the host from a non realtime thread.

If we want to change our internal data model to use this state, we have to transfer this state to the realtime thread. This should be done in a realtime thread safe manner. Otherwise the model may not reflect the correct state, as parameter changes dispatched in the realtime thread and the state data set on another thread will end in an undefined state.

For this case, we have another utility class: RTTransferT

This class expects to have a template parameter StateModel describing the state data. We create a simple struct as a data model:

struct StateModel
{
    double gain;
};

using RTTransfer = RTTransferT<StateModel>;

We use RTTransfer now as a member for our MyEffect class:

class MyEffect : ....
{
    RTTransfer stateTransfer;
};

If we now get a new state from the host, we create a newStateModel and write the stateGain value into model->gain and pass it to the utility class stateTransfer:

tresult PLUGIN_API MyEffect::setState (IBStream* state)
{
    double stateGain = ... // read this out of the state stream
    
    StateModel model = std::make_unique<StateModel> ();
    model->gain = stateGain;
    
    stateTransfer.transferObject_ui (std::move (model));
    
    return kResultTrue;
}

To get the stateModel into our realtime thread, we have to change the process function in the following way:

void MyEffect::process (ProcessData& data)
{
    stateTransfer.accessTransferObject_rt ([this] (const auto& stateModel) {
        gainParameter.setValue (stateModel.gain);
    });
    
    handleParameterChanges (data.inputParameterChanges);

    if (processSetup.symbolicSampleSize == SymbolicSampleSizes::kSample32)
        process<SymbolicSampleSizes::kSample32> (data);
    else
        process<SymbolicSampleSizes::kSample64> (data);
    
    gainParameter.endChanges ();
    return kResultTrue;
}

The accessTransferObject_rt function will check if there is a new model state. If this is the case, it will call the lambda, and then we can set our gainParameter to the value of stateModel.gain.

To free up the memory in the stateTransfer object, we have to call the clear_ui method of it. In this case, where we only have one double as state model, it is OK to hold onto it until the next state is set or the effect is terminated. So we just add it to the terminate method of the plug-in:

tresult PLUGIN_API MyEffect::terminate ()
{
    stateTransfer.clear_ui ();
    return AudioEffect::terminate ();
}

If the model data uses more memory and you want to get rid of it in advance, use a timer or something similar to call the clear_ui method a little bit after the setState method was called. But this is not the scope of this tutorial.

If you want to use the utility classes, you will find them in the sdk at:

public.sdk/source/vst/utility/processdataslicer.h
public.sdk/source/vst/utility/sampleaccurate.h
public.sdk/source/vst/utility/rttransfer.h

That´s it!

/ VST Home / Tutorials

How to use the silence flags

On this page:

• Goal
• What about Silence flags?
• Plug-in receives a silent audio input
• Plug-in generates silent output
• In bypass
• Plug-in generates audio output

Goal

This tutorial explains how to use silence flags.

What about Silence flags?

It is sometime useful for plug-ins processing to know if the audio inputs really contain audio or only silence (buffer filled with 0!), it is useful too for the host to know if the plug-in will produce silence audio outputs, for example in case of an instrument plug-in which has nothing to play (no input events are coming), then the host will be able to inform following plug-ins in the processing chain this information. This helps to reduce the amount of computing and improve overall performance.

But how does it works? The following part will show you how to get this information in the process call and how to propagate it to the audio outputs of the plug-in.

The silence flags is part of the AudioBusBuffers (silenceFlags) passed from the host to the plug-in and back to the host in the process call.

Plug-in receives a silent audio input

//-----------------------------------------------------------------------
tresult PLUGIN_API AGain::process (ProcessData& data)
{
    //...

    //---check if silence---------------
    // silence flags are a bitmask where each bit corresponds to one channel of a bus
    // (for example L and R for stereo bus).
    // Here we check only if the whole first input is silent (in case of Stereo: the L and R are silent)
    if (data.inputs[0].silenceFlags != 0) // if flags is not zero => then it means that we have silent!
    {
        // in the example we are applying a gain to the input signal
        // As we know that the input is only filled with zero, the output will be then filled with zero too!
        for (int32 i = 0; i < numChannels; i++)
        {
            // do not need to clear the output buffer if they are the same than input buffer,
            // as we know that the input are filled with zero, else we need to clear the output buffers
            if (in[i] != out[i])
            {
                memset (out[i], 0, sampleFramesSize); // this is faster than applying a gain to each sample!
            }
        }

        // now we have to inform the host that our output is silent too
        // this is done simply by setting the silenceFlags of the output bus:
        data.outputs[0].silenceFlags = ((uint64)1 << numChannels) - 1; // which is 3 (in binary 0011) for stereo

        // here we are finish we could return
        return kResultTrue;
    }

ⓘ Note
The host has the responsibility to clear the input buffers (set to something near zero, like 10e-7, to prevent de-normalization issue) when it enables the silence flags (the output silence flags will be set by the host to no silence (=0)).

Plug-in generates silent output

//-----------------------------------------------------------------------
tresult PLUGIN_API AGain::process (ProcessData& data)
{
    //...

    //---check if silence---------------
    // See above


    // under certain condition our output buffer could be silent:
    // for example here our gain could be set to 0 or smaller than a threshold.
    // We have to inform the host that our output is silent too
    // this is done simply by setting the silenceFlags of the output bus:
    if (gain < 0.0000001)
    {
        for (int32 i = 0; i < numChannels; i++)
        {
            // be sure to set to zero our outputs
            memset (out[i], 0, sampleFramesSize);
        }
        // this will set to 1 all channels
        data.outputs[0].silenceFlags = ((uint64)1 << numChannels) - 1; // which is 3 (in binary 0011) for stereo
    }
    else
    {
        //...
    }

ⓘ Note
The plug-in, if it produces silence output, has the responsibility to clear (set to zero) its output buffers and to correctly set the output silence flags.

In bypass

In Bypass mode the plug-in has to be sure that its outputs have the same stand than its inputs:

//-----------------------------------------------------------------------
tresult PLUGIN_API AGain::process (ProcessData& data)
{
    //...

    //---check if silence---------------
    // See above


    //---in bypass mode outputs should be like inputs-----
    if (bBypass)
    {
        for (int32 i = 0; i < numChannels; i++)
        {
            // do not need to be copied if the buffers are the same
            if (in[i] != out[i])
            {
                memcpy (out[i], in[i], sampleFramesSize);
            }
        }
        // the input silence flags has to be forward to the output here!
        // very important for the host in order to inform next plug-in in the processing chain
        data.outputs[0].silenceFlags = data.inputs[0].silenceFlags;
    }
    else
    {
        //...
    }

Plug-in generates audio output

//-----------------------------------------------------------------------
tresult PLUGIN_API AGain::process (ProcessData& data)
{
    //...

    //---check if silence---------------
    // See above


    //---in bypass mode outputs should be like inputs-----
    if (bBypass)
    {
        //... see above
        data.outputs[0].silenceFlags = data.inputs[0].silenceFlags;
    }
    else
    {
        // here we will generate an audio output from the input which contains not only zero
        // which is the main use case of a plug-in
        //...

        // then we have to inform the host that our output is not silent
        // simply by setting the silenceFlags to zero
        data.outputs[0].silenceFlags = 0;
    }
    //...

/ VST Home / Tutorials

Guideline for replacing a VST 2 plug-in by a VST 3 plug-in

On this page:

• Goal
• VST 2 and VST 3 version of your Plug-in have the same UID
• VST 2 and VST 3 version of your Plug-in have not the same UID
  • Using the moduleinfo.json file
  • Using the IPluginCompatibility interface
• Preset/Project compatibility VST 2 <-> VST 3
• Parameters compatibility

Goal

Here, you can find some informations about how to write a VST 3 version of a plug-in which already exists as VST 2 version. How to guaranty that a Host will correctly replace the old VST 2 by the new VST 3 version of your plug-in.

For a VST 3 Host the important information is the UID of your (processor) plug-in, with this information it will find the correct VST 3 version to use.

2 scenarios are possible: The VST 3 and the VST 2 version of your plug-in have the same UID or not.

VST 2 and VST 3 version of your Plug-in have the same UID

It is possible to reuse for a VST 3 plug-in the same generated UID of a VST 2 version (based on 4 characters + its name), this should work with most VST 3 Hosts. Check the function which generates a VST 3 UID from a VST 2 UID here and reuse this value as UID for the VST 3 plug-in (processor component UID)

VST 2 and VST 3 version of your Plug-in have not the same UID

For this use case since VST 3 SDK version 3.7.5 we have 2 possibilities for a VST 3 plug-in to inform the Host about which VST 2 plug-in it could replace:

Using the moduleinfo.json file

The Compatibility json array in the moduleinfo.json allows to list the UIDs which could be replaced by the VST 3 plug-in.

Using the IPluginCompatibility interface

The plug-in should implement this interface (pluginterfaces/base/iplugincompatibility.h) when a moduleinfo.json file cannot be used (when no bundle is available for example). Check here.

Preset/Project compatibility VST 2 <-> VST 3

Check the FAQ here which shows how to use the helper function VST3::tryVst2StateLoad and read a VST 2 state into a VST 3 plug-in.

It is possible to write back for VST 2 backward compatibility by using the helper function VST3::writeVst2State (public.sdk/source/vst/utility/vst2persistence.h).

Parameters compatibility

VST 2 was using index to identify parameter, VST 3 uses an ID. It means that to be compatible the VST 3 parameter ID should be kept to same index value as the VST 2 one (starting from 0).

If the parameter range or behavior is not changed, previously parameter automation in host should be played back correctly.

If you change the meaning of a parameter (range, conversion normalized to plain value), it is recommanded to create a new ID for this parameter.

You could add in the VST 3 plug-in a structure to your parameters by using Unit.

/ VST Home / Tutorials

Strings Conversion Helper

On this page:

• Goal
• Convert a String128 string to an UTF-8 string
• Convert an UTF-8 string to a String128 string

Goal

The SDK provides some helpers functions to convert from UTF16 (use in VST 3 interfaces) to UTF8 (used by std::string).

Here some code examples:

Convert a String128 string to an UTF-8 string

#include "public.sdk/source/vst/utility/stringconvert.h"

//...
FUnknownPtr<IHostApplication> hostApp (hostContext);
if (hostApp)
{
    Vst::String128 name;
    if (hostApp->getName (name) == kResultTrue)
    {
        // Here we convert a Vst::String128 to a std::string (UTF8)
        std::string str = VST3::StringConvert::convert (name);
        //...
    }
}

Convert an UTF-8 string to a String128 string

#include "public.sdk/source/vst/utility/stringconvert.h"

//...
std::string str ("My Title");
Vst::String128 vstStr;
VST3::StringConvert::convert (str, vstStr);

/ VST Home / Tutorials

Creating a cmake plug-in project from scratch

On this page:

• Goal
• Building the CMakeLists.txt
• Add plug-in GUI editor by using VSTGUI

Goal

This tutorial provides a step-by-step guide for building a VST 3 plug-in's CMakeLists.txt from scratch. It covers the necessary steps, like defining a plug-in version number, adding C++ source files, linking to the sdk target, and setting platform-specific options.

You can also use the VST 3 project generator which generates the CMakeLists.txt.

Building the CMakeLists.txt

Make a new directory, and name it like your new plug-in, e.g. MyPlugin. Afterwards, create a CMakeLists.txt file inside the new directory, and open it in a text editor. Add the following lines to it.

Set the minimum required version of cmake. In this example, 3.15.0 is sufficient.

cmake_minimum_required(VERSION 3.15.0)

See also: https://cmake.org/cmake/help/latest/command/cmake_minimum_required.html

Name the project MyPlugin, add a VERSION and an optional DESCRIPTION.

project(MyPlugin
    VERSION 1.0.0
    DESCRIPTION "MyPlugin Effect"
)

See also: https://cmake.org/cmake/help/latest/command/project.html

Set the variable vst3sdk_SOURCE_DIR to the VST 3 SDK's directory. The directory must contain the root CMakeLists.txt of the SDK. Add the SDK as a subdirectory, and call smtg_enable_vst3_sdk right after this.

set(vst3sdk_SOURCE_DIR /path/to/vst3sdk)

add_subdirectory(${vst3sdk_SOURCE_DIR} ${PROJECT_BINARY_DIR}/vst3sdk)
smtg_enable_vst3_sdk()

Add a plug-in library and its source files by using the smtg_add_vst3plugin function.

smtg_add_vst3plugin(MyPlugin
    source/version.h
    source/myplugin_cids.h
    source/myplugin_processor.h
    source/myplugin_processor.cpp
    source/myplugin_controller.h
    source/myplugin_controller.cpp
    source/myplugin_entry.cpp
)

Link the VST 3 SDK sdk to the plug-in library.

target_link_libraries(MyPlugin
    PRIVATE
        sdk
)

Configure the plug-in version by calling smtg_target_configure_version_file. This generates a temporary projectversion.h header, which is automatically included in your project.

smtg_target_configure_version_file(MyPlugin)

Define platform-specific settings.

For macOS, this includes

• setting the BUNDLE_IDENTIFIER to org.mycompany.myplugin,
• setting a proper COMPANY_NAME to My Company and
• an executable .../VST3PluginTestHost.app to start the plug-in with in debug

For Windows, it needs

• a resource file resource/win32resource.rc,
• setting the VS_STARTUP_PROJECT to MyPlugin and
• an executable .../VST3PluginTestHost.exe to start the plug-in with in debug

if(SMTG_MAC)
    smtg_target_set_bundle(MyPlugin
        BUNDLE_IDENTIFIER org.mycompany.MyPlugin
        COMPANY_NAME My Company
    )
    smtg_target_set_debug_executable(MyPlugin
        "/Applications/VST3PluginTestHost.app"
        "--pluginfolder;$(BUILT_PRODUCTS_DIR)"
    )
elseif(SMTG_WIN)
    target_sources(MyPlugin
        PRIVATE 
            resource/win32resource.rc
    )
    if(MSVC)
        set_property(DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR} PROPERTY VS_STARTUP_PROJECT MyPlugin)

        smtg_target_set_debug_executable(MyPlugin
            "$(ProgramW6432)/Steinberg/VST3PluginTestHost/VST3PluginTestHost.exe"
            "--pluginfolder \"$(OutDir)/\""
        )
    endif()
endif()

Add plug-in GUI editor by using VSTGUI

In order to add a VSTGUI editor to the plug-in, link to the vstgui_support target.

target_link_libraries(MyPlugin
        PRIVATE
            vstgui_support
    )

Add a myplugin_editor.uisdesc file as a resource. This file needs to be created manually.

    smtg_target_add_plugin_resources(MyPlugin
        RESOURCES
            "resource/myplugin_editor.uidesc"
    )

A plug-in with a basic *.uidesc file can be created by using the VST 3 project generator.

/ VST Home / Tutorials

Creating a plug-in with VST 3 SDK as an external project

On this page:

• Goal
• Part 1: How to clone and build
• Part 2: Adapting the helloworld example

Related pages:

• Generate a new plug-in with Project Generator

Goal

This is a simple Hello World VST 3 FX plug-in to demonstrate how to use the VST 3 SDK as an external project.

This plug-in was generated with the VST 3 Project Generator and it is available here https://github.com/steinbergmedia/vst3_example_plugin_hello_world

Part 1: How to clone and build

Open a command prompt and do the following:

git clone https://github.com/steinbergmedia/vst3_example_plugin_hello_world.git
mkdir build
cd build
cmake ../vst3_example_plugin_hello_world
cmake --build .

Part 2: Adapting the helloworld example

• This example is there mainly to demonstrate how to use VST 3 SDK as an external project, we highly recommand to use the Project Generator to start from scratch.

• In the following explaination we try to show you how to modify the source code to build your plug-in on the helloworld example.

• Now you have to adapt some uids and naming to make your plug-in unique (and not a duplicate of helloworld!)

  1. Rename all strings for your plug-in from HelloWorld to MyDelay (for example):

     • HelloWorldProcessor::HelloWorldProcessor to MyDelayProcessor::MyDelayProcessor

  2. Open the file vst3_example_plugin_hello_world/include/helloworldcids.h and create new uids for processor and for controller: you can use GUID creator tools like https://www.guidgenerator.com:

  static const FUID kHelloWorldProcessorUID (0x2A0CC26C, 0xBF88964C, 0xB0BFFCB0, 0x554AF523);
  static const FUID kHelloWorldControllerUID (0xB9DBBD64, 0xF7C40A4C, 0x9C8BFB33, 0x8761E244);
  

  3. Open the file version.h and adapt the strings in the following way:

  #define stringOriginalFilename "MyDelay.vst3"
  
  #define stringFileDescription	"MyDelay VST3"
  

  4. Open the file helloworldentry.cpp and adapt string:

  #define stringPluginName "My First Delay"
  

• Now you can start to code for your effect/instrument (see Code your first plug-in for a step-by-step explanation)

  1. Add parameters in helloworldcontroller.cpp
  2. Adapt your process algorithm in helloworldprocessor.cpp
  3. Add persistence in helloworldprocessor.cpp
  4. Add UI (check SDK examples using VSTGUI)

• Happy coding!

/ VST Home / Tutorials

Switching to another VSTGUI submodule or branch

On this page:

• Goal
• Switching to another submodule
• Switching to another branch

Goal

Sometimes it is necessary to switch to another VSTGUI submodule or branch for testing purposes. This tutorial explains how to do that.

Switching to another submodule

Navigate to your local VST 3 SDK checkout, and execute the following command on the command line to switch the submodule:

git submodule set-url vstgui4 /path/to/vstgui/
git submodule sync
git submodule update --init --recursive --remote vstgui4

The path /path/to/vstgui/ should point to a valid VSTGUI repository. Be aware that the set-urlcommand changes the .gitmodules file.

Also use / as a delimiter on Windows for local paths, e.g. C:/path/to/vstgui/

Switching to another branch

Switch to any other branch by navigating to the VSTGUI submodule, and execute git checkout.

git checkout my_branch

/ VST Home

Technical Documentation

Browse the VST 3 SDK's technical documentation. The full VST 3 API reference is only available in the VST 3 Package that you can download or find online here:

https://steinbergmedia.github.io/vst3_doc

• VST 3 API Documentation
• VST Module Architecture
• Parameters and Automation
• VST 3 Units
• Presets & Program Lists
• Complex Plug-in Structures / Multi-timbral Instruments
• VST 3 Workflow Diagrams
• VST 3 Locations / Format
• About MIDI in VST 3
• Provide A Runloop On Linux

• [3.0.0] Interfaces supported by the plug-in
• [3.0.0] Multiple Dynamic I/O Support
• [3.0.0] Silence flags
• [3.0.0] Interfaces supported by the host
• [3.0.1] Parameter MIDI Mapping
• [3.0.2] Parameter Finder
• [3.1.0] Audio Presentation Latency
• [3.1.0] UI Group Editing, Dirty State & Open Editor Request
• [3.1.0] KnobMode, Open Help & Open Aboutbox
• [3.5.0] Note Expression
• [3.5.0] Key Switch
• [3.5.0] Remote Presentation of Parameters
• [3.5.0] Context Menu
• [3.5.0] Enhanced Linked Parameters
• [3.6.0] iOS Inter-App Audio
• [3.6.0] Preset Meta-Information
• [3.6.5] Channel Context Info
• [3.6.5] Unit-Bus Assignment Change
• [3.6.5] Prefetchable
• [3.6.5] Automation State
• [3.6.6] PlugView Content Scaling
• [3.6.8] Request Bus Activation
• [3.6.10] UI Snapshots
• [3.6.11] NoteExpression Physical UI Mapping
• [3.6.12] Legacy MIDI CC Out Event
• [3.6.12] MIDI Learn
• [3.6.12] Host Query Interface Support
• [3.6.12] MPE support for Wrappers
• [3.7.0] Parameter Function Name
• [3.7.0] Progress Display
• [3.7.0] Process Context Requirements
• [3.7.0] Control Voltage Bus Flag
• [3.7.5] Module Info

VST 3 API Documentation

The VST 3 API is an interface collection designed for realtime audio processing components. Such a component can be an audio effect or an audio instrument.

VST Module Architecture

VST-MA is a component model system which is used in all Steinberg host applications as the basic layer for plug-in support.

Parameters and Automation

Description of how parameters are defined and used in VST 3.

VST 3 Units

A unit is a logical section of the plug-in.

Presets & Program Lists

How presets and program lists are handled in VST 3.

Complex Plug-in Structures / Multi-timbral Instruments

How to handle complex plug-in structures and multi-timbrality.

Data Exchange

How to transfer data from the realtime process function to the edit controller.

VST 3 Workflow Diagrams

Some useful graphical call sequences a VST 3 compliant host should follow.

VST 3 Locations / Format

Formats definition of a VST 3 plug-in and its preset and where they are located on different platforms.

About MIDI in VST 3

Unlike in VST 2, MIDI is not included in VST 3.

Host Requirements for VST 3 Support

Minimum Host requirements for VST 3 support.

[3.0.0] Interfaces supported by the plug-in

List of interfaces supported/implemented by the plug-in in VST 3.0.0.

[3.0.0] Interfaces supported by the host

List of interfaces supported/implemented by the host in VST 3.0.0.

[3.0.1] Parameter MIDI Mapping

How the mapping works between MIDI CCs and parameters.

[3.0.2] Parameter Finder

How the host can retrieve the parameter where the mouse cursor is located.

[3.1.0] Audio Presentation Latency

Inform the plug-in about how long from the moment of generation/acquiring (from file or from Input) it will take for its input to arrive, and how long it will take for its output to be presented (to output or to speaker).

[3.1.0] UI Group Editing, Dirty State & Open Editor Request

Improvement of the plug-in's integration in the host (dirty state, request Open Editor, group editing).

[3.1.0] KnobMode, openHelp & openAboutBox

Extension to allow the host to inform the plug-in about the host knob mode.

[3.5.0] Note Expression

A new way to control / modify / change a specific played note during playback.

[3.5.0] Key Switch

Allows information exchange between the plug-in and the host about which key switches are currently used.

[3.5.0] Remote Presentation of Parameters

How to better support remote devices/controllers (UI and hardware) for parameters.

[3.5.0] Context Menu

A plug-in can ask the host to create a context menu for a given exported parameter ID or a generic context menu.

[3.5.0] Enhanced Linked Parameters

This allows the host to start a parameter editing action which can generate other parameter changes (like linked parameters) and this in one session (between a beginEdit and endEdit).

[3.6.0] iOS Inter-App Audio

iOS InterApp-Audio application out of your VST 3 plug-in.

[3.6.0] Preset Meta-Information

Interface to access preset meta information from stream, used, for example, in setState in order to inform the plug-in about the current context in which the preset loading occurs.

[3.6.5] Channel Context Info

Allows the host to inform the plug-in about the context in which the plug-in is instantiated, mainly channel based info (color, name, index, ...).

[3.6.5] Unit-Bus Assignment Change

The plug-in has the possibility to inform the host with notifyUnitByBusChange that something has changed in the bus - unit assignment.

[3.6.5] Prefetchable

Indicates if the plug-in supports prefetch (dynamically).

[3.6.5] Automation State

Hosts can inform the plug-in about its current automation state (Read/Write/Nothing).

[3.6.6] PlugView Content Scaling

This interface communicates the content scale factor from the host to the plug-in view on systems where plug-ins cannot get this information directly like Microsoft Windows.

[3.6.8] Request Bus Activation

Allows the plug-in to request the host to activate or deactivate a specific bus.

[3.6.10] UI Snapshots

A VST 3 bundle can contain pre-rendered snapshot images for a VST 3 host as a visual representation of the plug-in UI.

[3.6.11] NoteExpression Physical UI Mapping

With this plug-in interface, the host can retrieve the preferred physical mapping associated to note expression supported by the plug-in.

[3.6.12] Legacy MIDI CC Out Event

This kind of event is reserved for generating MIDI CC as output event for kEvent Bus during the process call.

[3.6.12] MIDI Learn

If this interface is implemented by the edit controller, the host will call this method whenever there is live MIDI-CC input for the plug-in.

[3.6.12] Host Query Interface Support

Allows a plug-in to ask the host if a given plug-in interface is supported/used by the host.

[3.6.12] MPE support for Wrappers

Implemented on wrappers that support MPE (MIDI Polyphonic Expression) to Note Expression translation.

[3.7.0] Parameter Function Name

This interface allows the host to get a parameter associated to a specific meaning (a functionName) for a given unit.

[3.7.0] Progress Display

This interface allows the plug-in to ask the host to create a progress for specific tasks which take some time.

[3.7.0] Process Context Requirements

To get accurate process context information (Vst::ProcessContext), it is now required to implement this interface.

[3.7.5] Module Info

The moduleinfo.json describes the contents of the plug-in in a JSON5 compatible format.

[3.7.9] Get Current SystemTime

This interface allows a plug-in to ask the host for the current system time.

[3.7.9] Data Transfert Between Processor/Controller

These interfaces allow you to send data with a direct and thread-safe connection from the realtime audio context of the audio processor to the non-realtime audio context of the edit controller.

[3.7.11] Remap Parameter ID

This interface allows the plug-in to ask the host to remap some parameter ID if needed.

/ VST Home / Technical Documentation

VST 3 API Documentation

On this page:

• Basic Concept
  • Initialization
  • Creation and initialization from Host point of view
  • Extensions
  • Persistence
• The Processing Part
  • IComponent
  • IAudioProcessor
• The Editing Part
• VST 3 threading model
• Communication between the components
  • Standard communication
  • Private communication
  • Initialization of communication from Host point of view

Related pages:

• VST Module Architecture

The VST 3 API is an interface collection designed for realtime audio processing components. Such a component can be an audio effect or an audio instrument. VST 3 is based on a technology called VST Module Architecture (VST-MA). Please read the VST-MA documentation to find out more about how the plug-in system works in general. The API files belonging to VST 3 are located in the folder "pluginterfaces/vst".

ⓘ If you are looking for the C API of VST 3
see https://github.com/steinbergmedia/vst3_c_api.

Basic Concept

A VST 3 audio effect or instrument basically consists of two parts: a processing part and an edit controller part. The corresponding interfaces are:

• Processor: Steinberg::Vst::IAudioProcessor + Steinberg::Vst::IComponent
• Controller: Steinberg::Vst::IEditController

The design of VST 3 suggests a complete separation of processor and edit controller by implementing two components. Splitting up an effect into these two parts requires some extra implementation efforts. However, this separation enables the host to run each component in a different context, even on different computers. Another benefit is that parameter changes can be separated when it comes to automation. While for processing these changes need to be transmitted in a sample-accurate way, the GUI part can be updated with a much lower frequency and it can be shifted by the amount that results from any delay compensation or other processing offset. A plug-in that supports this separation has to set the Steinberg::Vst::kDistributable flag in the class info of the processor component (Steinberg::PClassInfo2::classFlags). Of course not every plug-in can support this, for example if it depends deeply on resources that cannot be moved easily to another computer. So when this flag is not set, the host must not try to separate the components in any way. Although it is not recommended, it is possible to implement both the processing part and the controller part in one component class. The host tries to query the Steinberg::Vst::IEditController interface after creating an Steinberg::Vst::IAudioProcessor and on success uses it as the controller.

ⓘ Note
A host does not need to instantiate the controller part of a plug-in for processing it.

The plug-in should be prepared for processing without having the controller part instantiated.

Initialization

Both Steinberg::Vst::IComponent and Steinberg::Vst::IEditController derive from Steinberg::IPluginBase. The purpose of this basic interface is to initialize the component and to terminate it before it is destroyed.

The context parameter passed to Steinberg::IPluginBase::initialize should implement the interface Steinberg::Vst::IHostApplication. Hosts should not call other functions before initialize is called, with the sole exception of Steinberg::Vst::IComponent::setIoMode which must be called before initialize. Steinberg::Vst::IComponent::getControllerClassId can also be called before (See VST 3 Workflow Diagrams).

How can the plug-in access IHostApplication?

//-----------------------------------------------------------------------
tresult PLUGIN_API MyPluginProcessor::initialize (FUnknown*context)
{
    FUnknownPtr<IHostApplication> hostApp (hostContext);
    if (hostApp)
    {
        String128 name;
        if (hostApp->getName (name) == kResultTrue)
        {
            //...
        }
    }
    //...
}
//-----------------------------------------------------------------------

Creation and initialization from Host point of view

Here an example of a host implementation creating the component and its associated controller of a plug-in with a given classID:

//-----------------------------------------------------------------------
Vst::IComponent* processorComponent;
Vst::IEditController* editController;
IPluginFactory* factory;
// ...
// factory already initialized (after the library is loaded,see validator for example)
// ...
// create its component part
tresult result = factory->createInstance (classID,Vst::IComponent::iid, (void**)&processorComponent);
if (processorComponent && (result == kResultOk))
{
    // initialize the component with our host context (note: initialize called just after creatInstance)
    res = (processorComponent->initialize (gStandardPluginContext) == kResultOk);

    // try to create the controller part from the component
    // for Plug-ins which did not succeed in separating component from controller :-(
    if (processorComponent->queryInterface (Vst::IEditController::iid, (void**)&editController) != kResultTrue)
    {
        // This is the normal case, where the controller is separated from the component.

        // ask for the associated controller class ID (could be called before processorComponent->initialize ())
        FUID controllerCID;
        if (processorComponent->getControllerClassId (controllerCID) == kResultTrue && controllerCID.isValid ())
        {
            // create its controller part created from the factory
            result = factory->createInstance (controllerCID, Vst::IEditController::iid, (void**)&editController);
            if (editController && (result == kResultOk))
            {
                // editController is now created, we have the ownership, 
                // which means that we have to release it when not used anymore.

                // initialize the component with our context
                res = (editController->initialize (gStandardPluginContext) == kResultOk);

                // now processorComponent and editController are initialized... :-)
            }
        }
    }
    else
    {
        // editController is now created, we have the ownership, 
        // which means that we have to release it when not used anymore.
    }
}
//-----------------------------------------------------------------------

ⓘ Note
Please be aware that IPluginBase::initialize and IPluginBase::terminate must only be called once per object instance. So if an object implements both IAudioProcessor and IEditController, take care to only call them once, as in the example above.

Extensions

The functionality of the components implementing these basic interfaces can be extended by a number of optional interfaces that only need to be implemented if this extension is required.

• Processor Extensions:
  • Steinberg::Vst::IConnectionPoint
  • Steinberg::Vst::IUnitData
  • Steinberg::Vst::IProgramListData
• Edit Controller Extensions:
  • Steinberg::Vst::IConnectionPoint
  • Steinberg::Vst::IMidiMapping
  • Steinberg::Vst::IUnitInfo

Persistence

The host stores and restores the complete state of the processor and of the controller in project files and in preset files:

• Steinberg::Vst::IComponent::getState + Steinberg::Vst::IComponent::setState store and restore the DSP model.
• Steinberg::Vst::IEditController::getState + Steinberg::Vst::IEditController::setState store and restore any GUI settings that are not related to the processor (like scroll positions etc).
• Restore: When the states are restored, the host passes the processor state to both the processor and the controller (Steinberg::Vst::IEditController::setComponentState). A host must always pass that state to the processor first. The controller then has to synchronize its parameters to this state (but must not perform any IComponentHandler callbacks). After restoring a state, the host rescans the parameters (asking the controller) in order to update its internal representation.

See also

• Steinberg::IBStream
• VST 3 Interfaces to be implemented by the Plug-in
• VST 3 Interfaces to be implemented by the Host

The Processing Part

The processing part consists of two related interfaces: Steinberg::Vst::IComponent and Steinberg::Vst::IAudioProcessor. The reason for splitting the two is to use the basic interfaces Steinberg::Vst::IComponent not only for audio plug-ins but also for other kinds of media (e.g. video processing in the future). Hence the Steinberg::Vst::IAudioProcessor interface represents the audio-specific part of a processing component. Let's have a closer look at the concepts.

IComponent

The Steinberg::Vst::IComponent interface allows the host to get information about the plug-in:

1. Edit controller association: In order to enable the host to create the associated edit controller part, the processing component has to provide the matching class-ID. The host uses the module's class factory to create the controller component. See Steinberg::Vst::IComponent::getControllerClassId

2. The host can ask for bus configurations (Steinberg::Vst::BusInfo). See Steinberg::Vst::IComponent::getBusInfo

3. The host can ask for routing information (Steinberg::Vst::RoutingInfo).

4. The host can activate or deactivate a specific bus like side-chain. A deactivated bus should be not processed by the plug-in. See Steinberg::Vst::IComponent::activateBus

5. The host can activate or deactivate the plug-in (On/Off button). See Steinberg::Vst::IComponent::setActive

6. The host can store and restore the state of the plug-in (preset and project persistence). See Steinberg::Vst::IComponent::getState, Steinberg::Vst::IComponent::setState

IAudioProcessor

The Steinberg::Vst::IAudioProcessor interface extends Steinberg::Vst::IComponent by providing a state machine for processing and the process method:

1. Setup: The processor must be configured before processing can start. Configurations are only allowed when the processor is inactive (Steinberg::Vst::IComponent::setActive).
   • Process setup: The processor is informed about the parameters that cannot be changed while processing is active. (Steinberg::Vst::ProcessSetup).
   • Dynamic Speaker Arrangements: The host can try to change the number of channels of an audio bus. By default the speaker arrangement is defined by the plug-in. In order to adjust the plug-in to a context where a different speaker arrangement is used, the host can try to change it using Steinberg::Vst::IAudioProcessor::setBusArrangements
2. When the processor is configured, it has to be activated (Steinberg::Vst::IComponent::setActive). The activation call signals that all configurations have been finished.
3. In addition to that, the processor has a 'processing state'. Before a host begins to perform processing calls, it has to signal this by calling IAudioProcessor::setProcessing (true). When the host stops processing, it must call IAudioProcessor::setProcessing (false) after the last processing call. Please see also: VST 3 Workflow Diagrams
4. Process: Steinberg::Vst::IAudioProcessor::process is the method that implements the actual processing. Any data needed for processing is passed to it as a parameter Steinberg::Vst::ProcessData. This is necessary because processing is often performed in a separate thread and this is a simple way to avoid thread synchronization problems.

   • Block Size: Processing is done in blocks. The maximum number of samples to be processed in one block is set in Steinberg::Vst::IAudioProcessor::setupProcessing. The actual number of samples in a processing block is transmitted in the process call and can be different from call to call, but it must be a value between 1 and maxSamplesPerBlock.

   • Audio Buffers: For any audio bus defined by the plug-in, the host must provide buffer data - even for inactive busses. Busses are addressed by index, so leaving out inactive busses will mix up these indices. The actual data buffer can be null though (see Steinberg::Vst::AudioBusBuffers).
     Note: The channelBuffers32 (or channelBuffers64) buffer pointers can be the same or different for input and output: this has to be taken into account in the process function (for example not resetting the output before processing if input and output buffers are the same!). It can be the same for multiple inputs or multiple outputs (in the case of instrument plug-ins) all outputs (or inputs) can share the same buffer!
     Important: The host can call Steinberg::Vst::IAudioProcessor::process without buffers (numInputs and numOutputs of Steinberg::Vst::AudioBusBuffers are zeroed, numSamples too), in order to flush parameters (from host to plug-in). Parameters can only be flushed when the host needs to send parameter changes and no processing is called.

   • Parameters & Automation: Any parameter changes are transmitted in the process call through the interfaces Steinberg::Vst::IParameterChanges and Steinberg::Vst::IParamValueQueue. Simple parameter changes as a result of GUI interaction are transmitted exactly in the same way as automation. (see Parameters and Automation).

   • Context: For each processing block the host should provide information about its state. See Steinberg::Vst::ProcessContext

   • Events: Steinberg::Vst::IEventList

The Editing Part

The edit controller is responsible for the GUI aspects ofthe plug-in. Its standard interface is Steinberg::Vst::IEditController. The host has to provide acallback interface for the edit controller named Steinberg::Vst::IComponentHandler. The handler is essentialfor the communication with both the host and the processor.

• GUI: Optionally, the controller can define an editor view. The method Steinberg::Vst::IEditController::createView allows the host to specify the type of the view by passing an id-string. Currently the only type defined is "editor" (Steinberg::Vst::ViewType::kEditor), but there might be variations in future versions (e.g. "setup"). See also Steinberg::IPlugView.

• Parameters: The controller is responsible for the management of parameters. Any change to a parameter that is caused by user interaction in the plug-in GUI must be properly reported to the Steinberg::Vst::IComponentHandler. The host is responsible for transmitting the change to the processor. In order to make recording of automation work, it is necessary to call beginEdit, performEdit and endEdit in the expected order! And from the UI-Thread! With the new interface IComponentHandler2 (since VST 3.1), the plug-in (from UI) can group parameters which should use the same time-stamp in host when writing automation, by wrapping a set of beginEdit/performEdit/endEdit functions (see IComponentHandler) with startGroupEdit and finishGroupEdit. More details can be found on the page about Parameters.

• Plug-in structure: If the plug-in is composed of discrete functional parts, the edit controller should publish this structure and the parameters belonging to each part by implementing the Steinberg::Vst::IUnitInfo interface. More details can be found on the page about VST 3 Units.

VST 3 threading model

The threading model used by VST 3 is quite simple and requires that:

• All initialisation/de-initialisation are done in the UI Thread
• All function exported by the plug-in are called by the host in the UI Thread with the exception of:
  • IAudioProcessor→process: which could be called in a Audio Thread (realtime thread), avoid any memory allocation!
  • IAudioProcessor→setProcessing: which could be called in a Audio Thread (realtime thread), avoid any memory allocation!
• All function exported by the host are called by the plug-in in the UI Thread

Check the Audio Processor Call Sequence and the Edit Controller Call Sequence.

Communication between the components

The two VST 3 components (processor and controller) need a way to communicate. It is the task of the host to handle this.

Standard communication

All standard data (like parameter changes) are transmitted between processor and controller using the basic interfaces listed above.

• After creation of processor and controller, the host sets the controller component state from the processors state. This is a change from the previous SDK, where it was assumed that after creation the controller and the processor are in sync.
• When the host sets a new processor state (Steinberg::Vst::IComponent::setState), this state is always transmitted to the controller as well (Steinberg::Vst::IEditController::setComponentState). The controller then has to synchronize to this state and adjust its parameters.
• When the controller transmits a parameter change to the host, the host synchronizes the processor by passing the new values as Steinberg::Vst::IParameterChanges to the process call.
• The processor can transmit outgoing parameter changes to the host as well. (Steinberg::Vst::ProcessData::outputParameterChanges). These are transmitted to the edit controller by the call of Steinberg::Vst::IEditController::setParamNormalized.

Private communication

Data that is unknown to the host can be transmitted by means of messages. The communication interfaces are

• Steinberg::Vst::IConnectionPoint: The host establishes a connection between processor and controller.
• Steinberg::Vst::IMessage: Represents a message to send to the counterpart.
• Steinberg::Vst::IAttributeList: A list of attributes belonging to a message.

Please note that messages from the processor to the controller must not be sent during the process call, as this would not be fast enough and would break the real time processing. Such tasks should be handled in a separate timer thread.

Initialization of communication from Host point of view

Here an example of host implementation where the component and controller parts are connected and synchronized:

//-----------------------------------------------------------------------
// the component and the controller parts are previously becreated and initialized (see above)
// ...
if (editController)
{
    // set the host handler
    // the host set its handler to the controller
    editController->setComponentHandler (myHostComponentHandler);

    // connect the 2 components
    Vst::IConnectionPoint* iConnectionPointComponent = nullPtr;
    Vst::IConnectionPoint* iConnectionPointController = nullPtr;

    processorComponent->queryInterface (Vst::IConnectionPoint::iid, (void**)&iConnectionPointComponent);
    editController->queryInterface (Vst::IConnectionPoint::iid, (void**)&iConnectionPointController);

    if (iConnectionPointComponent && iConnectionPointController)
    {
        iConnectionPointComponent->connect (iConnectionPointController);
        iConnectionPointController->connect (iConnectionPointComponent);
    }

    // synchronize controller to component by using setComponentState
    MemoryStream stream; // defined in "public.sdk/source/common/memorystream.h"
    stream.setByteOrder (kLittleEndian);
    if (processorComponent->getState (&stream) == kResultTrue)
    {
        stream.rewind ();
        editController->setComponentState (&stream);
    }

    // now processorComponent and editController parts are connected and synchronized...:-)
}

ⓘ Note
Please note that you CANNOT rely on the implementation detail that the connection is done directly between the processor component and the edit controller!

/ VST Home / Technical Documentation

VST Module Architecture

On this page:

• Introduction
• Interfaces
  • FUnknown
  • IID/CID
  • Direction
  • Versioning and inheritance
  • COM Compatibility
• Plug-ins
  • Module Factory
  • Locations
  • Categories
  • IPluginBase
  • Purpose-specific interfaces
  • Unicode
    • Plug-ins for Unicode hosts
    • Migrating from non-Unicode to Unicode
• SDK backward compatibility

Related pages:

• How the host will load a VST-MA based Plug-in
• How to derive a class from an interface
• Interface Versions and Inheritance
• VST 3 API Documentation

Introduction

VST-MA is a component model system which is used in all Steinberg host applications as the basic layer for plug-in support.

It is object-oriented, cross-platform and (almost) compiler-independent.
The basics are very much like Microsoft® COM, so if you are familiar with this technology, understanding VST-MA should be quite easy.

VST-MA is provided in C++ only. Interfaces in C++ are expressed as pure virtual class (which is a class with nothing but abstract methods). Unlike COM there is no support for C or other languages yet - simply because there has been no need for this so far. But all VST-MA interfaces can be transformed into different representations in case this should be inevitable some day.
It is currently available for Windows, macOS X and Linux.

The C++ files belonging to VST-MA are located in the following folders:

• pluginterfaces/base
• pluginterfaces/gui

Note: The name 'VST Module Architecture' has only little relation to the 'Virtual Studio Technology' itself.
It describes the basic layer for any plug-in category supported in Steinberg hosts. VST-MA existed long before it was used as a base for VST 3 itself.

Interfaces

FUnknown

Steinberg::FUnknown is the basic interface of VST-MA. All other interfaces are directly or indirectly derived from it.

IID/CID

Each interface has a unique identifier (IID) of type Steinberg::FUID. It is used to retrieve a new interface from another one (Steinberg::FUnknown::queryInterface). It is important to understand the difference between interface identifier and component identifier.
A component-ID or class-ID (CID) is used to identify a concrete implementation class and is usually passed to a class factory in order to create the corresponding component.
So a lot of different classes (with different class identifiers) can implement the same interfaces.

Direction

An interface may have a direction, meaning that the interface is expected to be implemented either in the plug-in or in the host. The nature of an interface is documented in the following way:

• [host imp]: the host implements the interface
• [plug imp]: the plug-in implements the interface

When neither of these is specified, the interface can be used in both ways.

Versioning and inheritance

Unlike C++ classes, interfaces do not use inheritance to express specializations of objects. Inheritance is used for versioning only. One of the strict rules is that once an interface has been released, it must never change again. Adding new functionality to an interface requires a new version (usually an ordinal number is added to its name in this case, for example IPluginFactory3 adds new features to IPluginFactory2).
A new version inherits the old version(s) of the interface, so the old and the new methods are combined in one interface. This is why specializations need to be modeled as separate interfaces! If a specialized interface were to inherit from the basic interface as well, an implementation class that needs to implement all of these interfaces would inherit the base interface twice, causing the compiler to run into ambiguities. So the specialization relation to a basic interface can only be expressed in the documentation.

• ISpecialInterface [extends IBaseInterface] => means IBaseInterface::queryInterface (ISpecialInterface::iid, ...) can be used to retrieve the derived interface.

You can find some example code here: Interface Versions and Inheritance.

COM Compatibility

The first layer of VST-MA is binary-compatible to COM. The Vtable and interface identifier of Steinberg::FUnknown match with the corresponding COM interface IUnknown. The main difference is the organization and creation of components/plug-ins by a host application. VST-MA does not require any Microsoft® COM source file. You can find information about COM on pages like:

• https://docs.microsoft.com/en-us/windows/win32/learnwin32/what-is-a-com-interface-

Basic Interfaces

• Steinberg::FUnknown
• Steinberg::IPluginBase
• Steinberg::IPluginFactory

Helper Classes

• Steinberg::FUID
• Steinberg::FUnknownPtr

See also "How to derive a class from an interface".

Plug-ins

Module Factory

A module (Windows: Dynamic Link Library, macOS: Mach-O Bundle, Linux: package) contains the implementation of one or more components (e.g. VST 3 effects). A VST-MA module must contain a class factory where meta-data and create-methods for the components are registered.
The host has access to this factory through the Steinberg::IPluginFactory interface. This is the anchor point for the module and it is realized as a C-style export function named GetPluginFactory. You can find an export definition file in the SDK - public.sdk/source/main/winexport.def (public.sdk/source/main/macexport.exp) which can be used to export this function or you could use the macro SMTG_EXPORT_SYMBOL directly in cpp file (check public.sdk/source/main/dllmain.cpp for example).
GetPluginFactory is declared as follows:

SMTG_EXPORT_SYMBOL IPluginFactory* PLUGIN_API GetPluginFactory ();

In addition to the GetPluginFactory function the plug-in may has to export additional entry/exit functions depending on the platform:

On Windows
On Windows the entry/exit functions are named InitDll / ExitDll and are optional!

A Plug-In can export these functions and a host has to call the InitDll function directly after loading the plug-in via LoadLibrary and before calling GetPluginFactory. The ExitDll function must be called before the plug-in is unloaded via FreeLibrary or on program termination without FreeLibrary.

As Windows already has this feature (see DllMain in Microsofts documentation) the above functions are optional.

On macOS
On macOS the entry/exit functions are named bundleEntry / bundleExit and are required!

A plug-in must export these functions and a host has to call the bundleEntry function directly after loading the plug-in via CFBundleLoadExecutable and before calling GetPluginFactory.

The bundleExit function must be called before the plug-in is unloaded or on program termination.

As macOS does not have a standard entry function when loading a bundle the above functions are required and a host has to reject plug-ins not exporting these functions.

On Linux
On Linux the entry/exit functions are named ModuleEntry / ModuleExit and are required!

A plug-in must export these functions and a host has to call the ModuleEntry function directly after loading the plug-In via dlopen and before calling GetPluginFactory.

The ModuleExit function must be called before the plug-in is unloaded via dlclose or on program termination.

As Linux does not have a standard entry function when loading a dynamic library, the above functions are required and a host has to reject plug-ins not exporting these functions.

The entry function is intended for providing the plug-in with the platform specific instance handle which are needed for many platform APIs.

Plug-in developers should use these functions instead of using platform functions to get the instance handle.

Here an example when using def/exp files instead of SMTG_EXPORT_SYMBOL:

winexport.def file on Windows

EXPORTS
GetPluginFactory
InitDll
ExitDll

macexport.exp file on mac

_GetPluginFactory
_bundleEntry
_bundleExit

Locations

Component modules do not require registration like DirectX. The host application expects component modules to be located in predefined folders of the file system. These folders and their subfolders are scanned for VST-MA modules during application startup. Each folder serves a special purpose:

• The application's Components subfolder (e.g. "C:\Program Files\Steinberg\Cubase 12\Components") is used for components tightly bound to the application. No other application should use it.
• Components that are shared between all Steinberg hosts are located at:
  • Win: "/Program Files/Common Files/Steinberg/Shared Components"
  • Mac: "/Library/Application Support/Steinberg/Components/"
• For special purpose plug-in types, additional locations are defined. Please refer to the corresponding documentation to find out if additional folders are used and where to find them. For VST 3, see VST 3 Locations/Format.

Categories

Any class that the factory can create is assigned to a category. It is this category that tells the host the purpose of the class (and gives a hint of which interfaces it might implement).
A class is also described with a name and it has a unique id.

• For example, the category for import/export filters is "Project Filter" and for VST 3 audio plug-ins it is "Audio Module Class".
• "Service" is a special category. The purpose of a class of this category is completely unknown to the host. It is loaded automatically during program start (provided that the user did not deactivate it).
• Since the factory can create any number of classes, one component library can contain multiple components of any type.

IPluginBase

The entry-point interface for any component class is Steinberg::IPluginBase. The host uses this interface to initialize and to terminate the plug-in component. When the host initializes the plug-in, it has to pass a so called context. This context contains any interface to the host that the plug-in will need to work.

Purpose-specific interfaces

Each plug-in category (VST 3 Effects, Project import/export Filters, Audio Codecs, etc...) defines its own set of purpose-specific interfaces. These are not part of the basic VST-MA layer.

Unicode

Beginning with version 5 of Cubase and Nuendo, the internal structure of the host was modified for better support of internationalization. Therefore, string handling was changed to utilize Unicode strings whenever strings are passed around. As a consequence, all the interfaces to plug-ins have changed from using ASCI to Unicode strings for call and return parameters. So in turn, all plug-ins must be adapted to support Unicode. This has major consequences in that:

• Unicode hosts (Cubase 5 or later) will only work with Unicode plug-ins. When loading a plug-in, a Unicode host checks the plug-in's type and will not load any non-Unicode plug-ins.
• Unicode plug-ins will not load in non-Unicode hosts. When loading, a Unicode plug-in requests information from the host and will not load if no Unicode host is detected. Therefore, if a plug-in is supposed to work with both older and newer hosts, it is best to provide two versions of the plug-in.

Plug-ins for Unicode hosts

Writing plug-ins that are supposed to work only with Unicode hosts is easy. Use a current version of this SDK and develop a plug-in as usual. Make sure that you only ever pass Unicode UTF-16 strings to interfaces that have strings as call parameters and also be prepared that strings returned by these interfaces are always UTF-16. Therefore, to make things easier, it is recommended that Unicode strings are used throughout the plug-in's implementation, in order to avoid back and forth conversions. Also, use the Steinberg::String and Steinberg::ConstString classes from the Base module, as they have been designed to work universally on both Mac and Win.

Migrating from non-Unicode to Unicode

In Steinberg SDKs released before Cubase 5, the interface functions were using pointers of type char for passing strings to and from the host. These have been changed now to using Steinberg's defined type tchar which is equivalent to char16, i.e. 16 bit character. In theory, there are many ways for representing 16 bit characters, but we chose to use the industry standard Unicode, so strings are expected to be encoded in UTF-16.
Accordingly, also the implementation of a plug-in needs to be adapted to deal correctly with Unicode-encoded strings, as well as only ever passing Unicode strings to the host.

ⓘ Note
Changing a function from using 8 bit to 16 bit character pointers may seem as only a minor modification, but in interface design this is a major intrusion, because an interface is a contract to the outside world that is never to be changed. Therefore, classes that are changed to use Unicode strings are distinguished and also receive a new unique class ID.

SDK backward compatibility

Even with the current SDK it is still possible to develop non-Unicode plug-ins. In the file pluginterfaces/base/ftypes.h, the line "#define UNICODE_OFF" is commented out, but by uncommenting it you can revert all interfaces to using single byte ASCII strings. Alternatively, you can also specify UNICODE_OFF as a preprocessor definition in your project file.
Also, the plug-in's factory info now does not define the Unicode flag anymore, so a Unicode host sees the compiled plug-in as non-Unicode. Also, when reverting to single byte strings the plug-in's implementation also has to be changed to behave correctly.

ⓘ Note
When undefining Unicode, the class IDs also revert to the old ones.

/ ... / VST Module Architecture

How the host will load a VST-MA based Plug-in

Related pages:

• VST Module Architecture

Check the included cpp files showing how to load such Component/plug-in:

• public.sdk/source/vst/hosting/module.h
  and
• for each platform public.sdk/source/vst/hosting/module_win32.cpp, ...

Here below you could found a basic implementation on Windows showing how to load the library and get pointer to the wanted exported functions:

HMODULE hModule = LoadLibrary ("SomePlugin.dll");
if (hModule)
{
    InitModuleProc initProc = (InitModuleProc)GetProcAddress (hModule, "InitDll");
    if (initProc) // this entry function is optional on Windows, not on MacOS and Linux!
    {
        if (initProc () == false)
        {
            FreeLibrary (module);
            return false;
        }
    }

    GetFactoryProc proc = (GetFactoryProc)GetProcAddress (hModule, "GetPluginFactory");

    IPluginFactory* factory = proc ? proc () : nullptr;
    if (factory)
    {
        for (int32 i = 0; i < factory->countClasses (); i++)
        {
            PClassInfo ci;
            factory->getClassInfo (i, &ci);

            FUnknown* obj;
            factory->createInstance (ci.cid, FUnknown::iid, (void**)&obj);
            ...
            obj->release ();
        }

        factory->release ();
    }

    ExitModuleProc exitProc = (ExitModuleProc)GetProcAddress (hModule, "ExitDll");
    if (exitProc) // This exit function is optional on Windows, not on MacOS and Linux!
        exitProc ();

    FreeLibrary (hModule);
}

/ ... / VST Module Architecture

Hot to derive a class from an interface

Related pages:

• VST Module Architecture
• Interface Versions and Inheritance

In the first example we derive a class directly from FUnknown, using some of the helper macros provided by the SDK.

class CMyClass: public FUnknown
{
public:
    CMyClass ();
    virtual ~CMyClass ();

    DECLARE_FUNKNOWN_METHODS  // declares queryInterface, addRef and release
};

CMyClass::CMyClass ()
{
    FUNKNOWN_CTOR // init reference counter, increment global object counter
}

CMyClass::~CMyClass ()
{
    FUNKNOWN_DTOR // decrement global object counter
}

IMPLEMENT_REFCOUNT (CMyClass) // implements reference counting

tresult CMyClass::queryInterface (const char* iid, void** obj)
{
    QUERY_INTERFACE (iid, obj, ::FUnknown::iid, CMyClass)
    return kNoInterface;
}

Developing a class with more than one interface is done by multiple inheritance. Additionally you have to provide an appropriate cast for each interface in the queryInterface method.

class CMyMultiClass : public Steinberg::IPluginBase,
                    public Steinberg::IPlugController,
                    public Steinberg::IEditorFactory
{
public:
    DECLARE_FUNKNOWN_METHODS

    // declare the methods of all inherited interfaces here...
};

IMPLEMENT_REFCOUNT (CMyMultiClass) // implements referencecounting

tresult CMyMultiClass::queryInterface (const char* iid, void** obj)
{
    QUERY_INTERFACE (iid, obj, Steinberg::FUnknown::iid, IPluginBase)
    QUERY_INTERFACE (iid, obj, Steinberg::IPluginBase::iid, IPluginBase)
    QUERY_INTERFACE (iid, obj, Steinberg::IPlugController::iid, IPlugController)
    QUERY_INTERFACE (iid, obj, Steinberg::IEditorFactory::iid, IEditorFactory)
    *obj = 0;
    return kNoInterface;
}

/ ... / VST Module Architecture

Interface Versions and Inheritance

Related pages:

• VST Module Architecture
• How to derive a class from an interface

Unlike C++ classes, VST-MA interfaces do not use inheritance to express specializations of objects. Usually all interfaces are derived from FUnknown. This is because interfaces must never change after they have been released. The VST Module Architecture Interfaces use inheritance only for versioning! All specializations will be modeled as separate interfaces!

For example the C++ classes:

class Shape
{
public:
    void setPosition (long x, long y);
protected:
    long x;
    long y;
};
class Rect : public Shape
{
public:
    void setDimension (long width, long height);
protected:
    long width;
    long height;
};

expressed in VST-MA, define an interface for each inheritance level:

class IShape : public FUnknown
{
public:
    virtual void setPosition (long x, long y) = 0;
};
class IRect : public FUnknown
{
public:
    virtual void setDimension (long width, long height) = 0;
};

In the next program version there need to be changes to the Shape class that look like this:

class Shape
{
public:
    void setPosition (long x, long y);
    void setColor (Color color);
protected:
    long x;
    long y;
    Color color;
};

The VST-MA representation now reflect the changes to Shape by adding a new interface that inherits from IShape and looks like the following code, while the former interface definitions remain the same:

class IShape2 : public IShape
{
public:
    virtual void setColor (Color color) = 0;
};

/ VST Home / Technical Documentation

Moduleinfo

An optional moduleinfo.json file can be part of the module file package, located in the Resources folder.

The file contains the same information as the Module Factory, plus an optional list of compatible classes. The file is encoded in JSON5 format.

The Compatibility json array is used to declare a class to be treated as a replacement for another class or classes.

When used this way, the host does not need to load the component to know which classes the module provides.

This optional moduleinfo.json file was added in the VST 3 SDK version 3.7.5 and was located in the Contents folder of the bundle. In order to be compliant with code signing on macOS, this file is now (since version 3.7.8) located in the Contents/Resources folder.

SDK

The VST 3 SDK contains a command-line utility called moduleinfotool that is used to create and validate the moduleinfo.json file from a VST plug-in. See public.sdk/vst-utilities/moduleinfotool.

The moduleinfotool uses the ModuleInfoLib which can be used by hosts to read and parse the moduleinfo.json file. See public.sdk/source/vst/moduleinfo

For plug-ins built with the VST 3 SDK, the moduleinfo.json file will be automatically created during the build process.

Example

An example moduleinfo.json looks like this:

{
  "Name": "helloworld",
  "Version": "3.7.5.0",
  "Factory Info": {
    "Vendor": "Steinberg Media Technologies",
    "URL": "http://www.steinberg.net",
    "E-Mail": "mailto:info@steinberg.de",
    "Flags": {
      "Unicode": true,
      "Classes Discardable": false,
      "Component Non Discardable": false,
    },
  },
  "Classes": [
    {
      "CID": "BD58B550F9E5634E9D2EFF39EA0927B1",
      "Category": "Audio Module Class",
      "Name": "Hello World",
      "Vendor": "Steinberg Media Technologies",
      "Version": "1.0.0.1",
      "SDKVersion": "VST 3.7.5",
      "Sub Categories": [
        "Fx",
      ],
      "Class Flags": 1,
      "Cardinality": 2147483647,
      "Snapshots": [
        {
          "Scale Factor": 1,
          "Path": "Contents/Resources/Snapshots/BD58B550F9E5634E9D2EFF39EA0927B1_snapshot.png",
        },
        {
          "Scale Factor": 2,
          "Path": "Contents/Resources/Snapshots/BD58B550F9E5634E9D2EFF39EA0927B1_snapshot_2.0x.png",
        },
      ],
    },
    {
      "CID": "A0B1A6F4005D9B47967177E37A671891",
      "Category": "Component Controller Class",
      "Name": "Hello WorldController",
      "Vendor": "Steinberg Media Technologies",
      "Version": "1.0.0.1",
      "SDKVersion": "VST 3.7.5",
      "Class Flags": 0,
      "Cardinality": 2147483647,
      "Snapshots": [
      ],
    },
  ],
  "Compatibility": [
    {
		"New": "BD58B550F9E5634E9D2EFF39EA0927B1",
		"Old": [
		  "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
		  "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
		],
	},
  ],
}

Check here to learn how to create UID for old VST 2 plug-in.

/ VST Home / Technical Documentation

Parameters and Automation

On this page:

• Parameters
  • Representation of parameter values
    • Parameter styles / 'Step Count'
  • Conversion of normalized values
• Automation
  • Problems
  • Automation Recording
    • Sliders & Knobs
    • Buttons / Radio Groups / Pop-up Menus
    • Text Input
  • Automation Playback
  • GUI playback
• Informing the host about changes
  • Parameter titles, default values or flags have changed
  • Multiple parameter values have changed

Related pages:

• VST 3 Units

Description of how parameters are defined and used in VST 3.

Parameters

A plug-in requires parameters in order to control its DSP algorithm, for example, a Frequency parameter for a filter. The plug-in can export these parameters in order to make them visible to the host and allow the host to control/change/automate/remote/visualize them. Some parameters can be defined for private use only (not visible to the user) or as read-only, such as parameters associated to VU Meters.

Steinberg::Vst::IEditController::getParameterCount allows the host to identify the number of parameters that are exported by the plug-in. The plug-in must assign a unique 32-bit identifier (ID) to each exported parameter.

ⓘ Note
Up to 2^31 parameters can be exported with ID range [0, 2.147.483.647], in hexadecimal [0x0, 0x7FFFFFFF].

The range [2.147.483.648, 4.294.967.295], in hexadecimal [0x80000000, 0xFFFFFFFF], is reserved for host application.

The value kNoParamId (0xFFFFFFFF) is the default value for uninitialized parameter ID.

Please note that it is not allowed to change this assignment at any time. In particular, a plug-in must not perform any reconfigurations that lead to a different set of automatable parameters. The only allowed variation is the adding or removing of parameters in a future plug-in version. However, keep in mind that automation data can get lost when parameters are removed.

Usually, the host is unaware of a parameter's semantics. However, there are a few important exceptions that the controller must announce using the Steinberg::Vst::ParameterInfo::flags:

• kCanAutomate: This means that this parameter can be automated by the host using its automation track. [SDK 3.0.0]

• kIsBypass: If the plug-in performs bypass processing itself, it must export the corresponding parameter and flag it with kIsBypass. It is highly recommended that this bypass parameter is provided by the effect plug-in. If the plug-in does not export a bypass parameter, the host can perform bypass processing and the plug-in process call will be discontinued. Only one bypass parameter is allowed. The plug-in should save the state of this bypass parameter like other parameters (when getState and setState are used). If the plug-in does not need a bypass (like Instrument) this flag should be not used. Check this FAQ in order to understand how bypass processing works. [SDK 3.0.0]

• kIsReadOnly: This means that this parameter cannot be changed from outside the plug-in, this requires that kCanAutomate is NOT set. [SDK 3.0.0]

• kIsWrapAround: When a UI control created by the host for this parameter attempts to set its value out of the limits, this UI control will make a wrap around (useful for parameters like 360 degree rotation). [SDK 3.0.2]

• kIsList: This means that the host will display this parameter as list in a generic editor or automation editing. [SDK 3.1.0]

• kIsHidden: This means that this parameter will NOT be displayed and cannot be changed from outside the plug-in. This requires that kCanAutomate is NOT set and kIsReadOnly is set. [SDK 3.7.0]

• kIsProgramChange: If the plug-in supports program lists (see VST 3 Units, Program Lists), each 'unit' of the plug-in needs to export a program selector parameter. Such a parameter is not allowed to be automated when the affected parameters are flagged as automatable as well. A host can display program parameters at dedicated locations of its GUI. [SDK 3.0.0]

The controller must support the conversion to a string for any exported parameter. The conversion method Steinberg::Vst::IEditController::getParamStringByValue must provide a result for any possible normalized parameter value.

⚠️ Warning
Parameter values are always transmitted in a normalized floating point (64bit double) representation [0.0, 1.0].

Representation of parameter values

A plug-in parameter usually has more than one representation. The GUI of a plug-in can display something that appears to be a single parameter, but might control multiple processing parameters at the same time. Or the GUI representation displays a scale-transformed representation of a DSP-Parameter.

Somewhere on the way from the GUI to the DSP algorithm, this transformation has to be performed. The host does not need information about DSP parameters, but it is responsible for reporting parameter changes to the processor. According to this, the processor is the only place where a transformation can happen and all parameters always have to match the GUI representation.

Does this fit into the idea of separating GUI and processing? No problem so far

• it is a separation of duties, nothing more. The processor component and the controller component have to work on the same internal plug-in model. The controller knows how this model has to be presented in the GUI. The processor knows how the model has to be translated into DSP parameters.
  The VST 3 interfaces suggest a normalized value representation for a part of this model (the part that is exported as parameters). This means every value has to be inside the range from 0.0 to 1.0.

Parameter styles / 'Step Count'

Although values are transmitted in a normalized format, the host needs to know some details of the parameter's displayed GUI representation. When editing automation data, for example, the host must know the nature of a parameter expressed in its 'step count' (see Steinberg::Vst::ParameterInfo::stepCount).

Step count semantics:

• 0: A continuous parameter. Any normalized value has an exact mapping (0 = there are no steps between the values)
• 1: A discrete parameter with 2 states like (on/off) (yes/no) etc. (1 = there is one step between these states)
• 2: A discrete parameter with 3 states (0,1,2) or (3,5,7) (2 = there are two steps between these states)
• 3: etc...

Conversion of normalized values

The controller and the processor have to work with normalized parameter values.

• Step count 0: Continuous parameters simply need to be mapped accordingly

• Step count n: Discrete parameters need a little bit more care

  • Discrete Value => Normalize

  double normalized = discreteValue / (double)stepCount;
  

  • Normalize => Discrete Value (Denormalize)

  int discreteValue = min (stepCount, normalized *(stepCount + 1));
  

Example: Step Count 3

Automation

A host that supports parameter automation is dependent on a proper cooperation of the component owning these parameters. One intention in the design of the VST 3 interfaces was to reduce the amount of possible mistakes for an implementation. The separation of processor and controller enforces that all parameter changes have to be handled by the host in a defined way. Additionally, this allows the host to store the changes as automation data. Nevertheless, there are some more things to consider:

No automated parameter must influence another automated parameter!

The prime example for this is the automation of preset changes. A preset change can lead to the change of all 'normal' parameters. So if automation data already has been recorded for these parameters and the preset change is recorded as well: who wins? This question cannot be answered and the problem can only be resolved by avoiding it. This is why automation of preset changes is not allowed by default.

Problems

A fix value range from 0.0 to 1.0 simplifies the handling of parameters in some ways, but there are problems:

• Non-linear scaling
  If the DSP representation of a value does not scale in a linear way to the exported normalized representation (which can happen when a decibel scale is used, for example), the edit controller must provide a conversion to a plain representation. This allows the host to move automation data (being in GUI representation) and keep the original value relations intact. (Steinberg::Vst::IEditController::normalizedParamToPlain / Steinberg::Vst::IEditController::plainParamToNormalized).

• Changes in future plug-in versions
  Take a discrete parameter, for example, that controls an option of three choices. If the host stores normalized values as automation data and a new version of a plug-in invented a fourth choice, the automation data will be invalid now. So either the host has to store denormalized values as automation or it must recalculate the automation data accordingly.

Automation Recording

Automation recording is performed by the host. In doing so, it is essential for the host to know the start and the end of a manipulation. Therefore, the plug-in must operate the Steinberg::Vst::IComponentHandler interface in the following way and in the UI Thread!:

• The begin of a manipulation must be signaled via Steinberg::Vst::IComponentHandler::beginEdit

• Changes of parameters are reported via Steinberg::Vst::IComponentHandler::performEdit

• The end of a manipulation must be signaled via Steinberg::Vst::IComponentHandler::endEdit

The plug-in must stick to the order of these callbacks. Otherwise, automation recording cannot work correctly. However, the implementation can bring up difficulties. Each type of GUI control and the way it is operated along with the nature of the controlled parameter requires specific considerations. To address the most common cases:

Sliders & Knobs

This kind of controls usually control continuous parameters and they are usually operated with the mouse. This common case is the most simple to handle: On mouse-click-down call beginEdit (followed by performEdit when the control allows a jump), on mouse-drag call performEdit and on mouse-click-up call endEdit.

Trouble starts with the mouse wheel: There simply is nothing like a defined start or end when the wheel is operated - each wheel event arrives 'out of the blue'. The only way to enable proper automation recording in this case is the usage of a timer.

• A plug-in implementation should call beginEdit when the first wheel event is handled and start a timer (followed by the first call to performEdit). Further wheel events that arrive inside of the timeout interval are reported with performEdit and the timer is restarted. When the timeout period has passed without further events, endEdit should be called and the timer can be removed.
• But since it is the host's task to record automation data, one could argue that it should be the host's task to take care of the timer in this case. This is the reason for the following exception to the rule:
  • Mouse wheel events can be reported without beginEdit and endEdit to the host. The host must be prepared to receive a performEdit without a previous call of beginEdit for a parameter and handle the timeout itself.

Buttons / Radio Groups / Pop-up Menus

This kind of controls usually control discrete parameters and simply switch the state of something. A proper handling is to call beginEdit, performEdit and endEdit in a row. The affected parameter has to be exported to the host with the correct step count because discrete parameters are handled differently than continuous parameters in regard to automation.

Mouse wheel handling usually is not supported for buttons, but sometimes for pop-up menus. Discrete parameters do not require the usage of a timer in order to be recorded correctly.

So the plug-in should call the 3 functions in a row for each wheel event - again, the other option is to omit beginEdit and endEdit, but in this case, be sure to report the discrete nature of the parameter to the host correctly.

Text Input

For reporting the results of a text input value change for a continuous or a discrete parameter, always call beginEdit, performEdit and endEdit in a row.

Automation Playback

In VST 3, automation playback is the task of the plug-in and it is the host's task to provide the automation data. The only way for a parameter change to arrive in the processor is the processing call. Receiving parameter changes from the edit controller and playing back automation data is one and the same thing.

The need to perform all transformations, from the normalized GUI representation to the DSP representation, produces some overhead. Performing sample-accurate automation requires even more overhead, because the DSP value must be calculated for each single sample. While this cannot be avoided entirely, it is the choice of the plug-in implementation how much processing time to spend on automation accuracy. The host always transmits value changes in a way that allows a sample-accurate reconstruction of the underlying automation curve. The plug-in is responsible for the realization.

The processor gets the automation data in the processing call by using queue of parameter changes for each parameter having automation data:

A IParameterChanges has some IParamValueQueues (for a specific parameter ID) which has some Automation Points.

⚠️ Warning\

• A parameter (ID) is present only one time in the IParameterChanges list!
• Automation Points inside a IParamValueQueues are sorted per offset (position inside the audio block)!

GUI playback

The host is responsible for updating the plug-in GUI when automation data is transmitted to the processor. This is realized by frequent calls of Steinberg::Vst::IEditController::setParamNormalized in the UI Thread.

See also Steinberg::Vst::IParameterChanges, Steinberg::Vst::IParamValueQueue.

Informing the host about changes

Parameter titles, default values or flags have changed

If something happens, user interaction for example, which change the parameter styles (ParameterFlags) or title or default value of one or multiple parameters, the plug-in must call

IComponentHandler::restartComponent (kParamTitlesChanged);

to inform the host about this change (in the UI Thread). The host rescans the ParameterInfos with getParameterInfo.

Multiple parameter values have changed

As result of a program change for example, the plug-in must call:

IComponentHandler::restartComponent (kParamValuesChanged);

to inform the host about this change (in the UI Thread). The host invalidates all caches of parameter values and asks the edit controller for the current values.

If only some values have changed (less than 10) the plug-in should use the Steinberg::Vst::IComponentHandler::performEdit interface (Show the right use when automation are used: Automation Recording)

ⓘ Note
If the plug-in needs to inform the host about changes containing parameter title, default or flags and values (of multiple parameters), it could combine the restartComponent flags:

IComponentHandler::restartComponent (kParamValuesChanged|kParamTitlesChanged);

/ VST Home / Technical Documentation

VST 3 Units

On this page:

• Introduction
• Unit details
• Examples

Related pages:

• Presets & Program Lists
• Complex Plug-in Structures / Multi-timbral Instruments

Introduction

A unit is a logical section of the plug-in.

For example, an EQ section can be a unit. The purposes of units are:

• To reveal the internal logical structure of the plug-in
• To organize parameters by associating them with units
• To Support program lists
• To support handling of Complex Plug-in Structures / Multi-timbral Instruments
  • Multiple program lists (associated with a unit)
  • Access to program list data
  • Associations of MIDI tracks and units
  • Synchronization of plug-in GUI and host GUI

Unit details

• The plug-in can define any number and any kind of units. The semantics of a unit is not important.

• Units are organized in a hierarchical way. Each unit can contain sub-units.

• The root unit of this hierarchy is always present (explicit or implicit) and has ID '0'. A plug-in that does not define any further units simply consist of unit '0'.

• The plug-in has to assign a unique ID to each further unit it defines and must provide a suitable name for it to be shown in the GUI (Steinberg::Vst::UnitInfo).

• Each unit can 'contain' parameters. All parameters of the plug-in are managed and published by the Steinberg::Vst::IEditController, but each parameter can be associated with a unit. (Steinberg::Vst::ParameterInfo::unitId). A host can organize the list of parameters in a tree view reflecting the unit hierarchy as nodes.

• Each unit can be associated with a program list. (See Complex Plug-in Structures / Multi-timbral Instruments)

• A unit can be associated with specific busses. There can be any kind of combination, but the VST 3 interfaces only define queries for special situations. (See Units and Tracks)

Most things of interest in regard to units are GUI related, so the access interface Steinberg::Vst::IUnitInfo needs to be implemented as extension of the edit controller.

See also Steinberg::Vst::IUnitInfo, Presets & Program Lists.

Examples

• Example of a plug-in (MultibandCompressor from Cubase pluginset) with structured parameters list that can be used by the host, here in Cubase for selecting a parameter to automate:

  

• Example of a plug-in (VST Amp Rack from Cubase pluginset) with structured parameters list visualized in the Parameters tab of the PluginTestHost application:

  

• Example of using the unit structure of HALion Sonic SE inside Cakewalk for automation selection:

  

/ VST Home / Technical Documentation

Presets & Program Lists

On this page:

• Simple Plug-ins
• Program Lists
  • Structure of Program Lists
  • Pitch Names

Related pages:

• VST 3 Units
• Complex Plug-in Structures / Multi-timbral Instruments

How presets and program lists are handled in VST 3.

See VST 3 Locations / Format for preset format definition.

Simple Plug-ins

For a simple plug-in, the data of a preset is nothing more than its state. In this case:

• It is the job of the host to manage the preset handling for the plug-in.

• The plug-in itself does not need to provide any means in its GUI for loading presets at all and it does not need to define any program lists.

• Factory presets must be installed as files at the required location (See Preset Locations).

The host has to provide the GUI for loading and saving preset files. These files contain data that the plug-in has filled into the stream in Steinberg::Vst::IComponent::getState. VST 3 defines dedicated locations in the OS file system (see Preset Locations), so the host does not need to display a file selector dialog. It knows where to search for preset files of a specific plug-in and where to create them. So it can create a pop-up list for selecting a preset or any other GUI of its choice. After loading a preset, the host is responsible to rescan the parameters values (from the controller part). Therefore, the controller must be sure that it gets the correct parameter states when loading a preset (which is done with Steinberg::Vst::IEditController::setComponentState).

See also Communication between the components and Persistence.

Program Lists

If a plug-in uses a large pool of programs that require some kind of caching or that need to be preloaded, using preset files may not be a sufficient choice. In this case, the plug-in can define a program list. For this purpose, the edit controller has to be extended by the interface Steinberg::Vst::IUnitInfo.

• If the plug-in defines a program list to be used as pool of factory presets, it must not allow the user to change these presets by the means of parameter editing. Instead, it should load the corresponding data into a kind of working memory and store possible modifications as component state. In addition, the user can be allowed to store the modifications as preset file.

• If the plug-in defines a program list to be used as a pool of user presets that are initially in an 'empty' state, modifications can be applied to the list items directly. This way of using program lists should only be chosen if programs do require a lot of resources that need to be cached in order to achieve fast program changes (good examples for this are sample-based plug-ins).

• The plug-in can provide GUI for the selection of programs, but it must enable the host to display the list and the selected program as well. The index of the selected program in the list must be exported as program selection parameter. (Steinberg::Vst::ParameterInfo::kIsProgramChange)

• The plug-in can allow the host to read and write the program data of a list item. To support this, the plug-in must implement the Steinberg::Vst::IProgramListData interface as an extension of the component part.

Structure of Program Lists

All programs are always transmitted as a flat list to the host. But the plug-in can assign a number of attributes to each program of the list. This enables the host to organize and filter them in a very flexible way. Attribute values are queried via Steinberg::Vst::IUnitInfo::getProgramInfo. The possible attribute identifiers are defined in namespace Steinberg::Vst::PresetAttributes. The attribute identifier specifying a program category, for example, is Steinberg::Vst::PresetAttributes::kInstrument. Although the name suggests that it should be used for instruments only, it can be used for any kind of audio plug-in. The value for an instrument category of a program is "Piano" for example. But it is possible to specify a subcategory like "Acoustic Piano" as well. In this case, the strings need to be chained in the following way:
"Piano|Acoustic Piano". This allows the host to organize presets in a category tree view, for example.

Pitch Names

Pitch names are intended to be used with drum kit programs where the different drum sounds are addressed by note pitches. In order to display the name of the drum instrument assigned to a pitch in a drum editor, for example, the host calls Steinberg::Vst::IUnitInfo::hasProgramPitchNames to determine if pitch names are supported and Steinberg::Vst::IUnitInfo::getProgramPitchName to query the pitch name of a single note.

See also VST 3 Units Multi-timbral Program Lists and check out the pitchnames VST 3 plug-in example.

/ VST Home / Technical Documentation

Complex Plug-in Structures / Multi-timbral Instruments

On this page:

• The Problem
• The Simple Mode
• Multi-timbral Program Lists
• Units and Tracks
• Routing

Related pages:

• VST 3 Units

How to handle complex plug-in structures and multi-timbrality.

The Problem

A simple VST effect plug-in usually does not cause the host too many problems. It has only one audio input and output bus and a defined set of parameters that control aspects of its sound. But a VST plug-in can be a lot more complex than this. When the plug-in implements a multi-timbral musical instrument, the host is confronted with a range of problems regarding the integration of this plug-in in its GUI. To mention a few of them:

• The plug-in can define multiple event input and multiple audio outputs. How can the host know on which output a sound will emerge when a note-event is transmitted to the plug-in?

  • This may be of interest for the host in order to link a MIDI track to the corresponding audio channel.

• The plug-in can define a list of programs that the user can load from the plug-in GUI. In a multi-timbral instrument, a program only affects a certain part of the plug-in (we call this part a 'unit'). How can the host know about these parts and about the plug-in defined programs that can be loaded?

  • This may be of interest for a host in order to provide shortcuts for this functionality in its own GUI.

Since a VST plug-in unlike a hardware MIDI instrument is more than only a black box, a complex plug-in should help its host to provide a more convenient GUI integration than it is possible with hardware instruments. VST 3 uses the concept of units to describe the internal structure of the plug-in (see VST 3 Units) and a multi-timbral instrument is supposed to support the respective interfaces. But the preferred solution in VST 3 is a reduction of this complexity with the 'simple mode'.

The Simple Mode

The 'VST 3 simple mode' has the (selfish) background to support the so-called "simple instrument tracks" of Cubase. These tracks combine a MIDI track and VST audio channel (without the need to make any further assignments such as the choice of a MIDI output port or a MIDI channel). This mode is defined as 'only one input and only one output'. In 'simple mode', only MIDI channel 0 is used. Therefore, an instrument has to be mono-timbral.

The host will now work with multiple instances of the plug-in rather than using the same instance in a way that it contains multiple internal sections of the same kind. The VST-MA component model supports shared resources between multiple instances of a plug-in because usually the same module instance (dll/bundle) is used for each plug-in instance.

Yet, a plug-in has the option to support both the simple and the advanced mode with the same implementation. The host tests the general ability to support the 'simple mode' by checking the processor's class flags (Steinberg::PClassInfo2::classFlags) for the Steinberg::Vst::kSimpleModeSupported flag. If the plug-in is to be used in an instrument track (or whenever a host regards it more suitable) the Steinberg::Vst::IComponent::setIoMode method is called (before any other call!) to configure the plug-in. A mono-timbral plug-in should set this flag as well and does not need to take into account the setIoMode call.

Multi-timbral Program Lists

For a multi-timbral instrument plug-in, preset handling can be a lot more complex. In this case:

• The plug-in can define any number of program lists.

• Each unit can reference one program list (this reference must not change).

• Each unit that uses a program list references one list item.

• For each unit referencing a program list, a program selection parameter has to be exported (Steinberg::Vst::ParameterInfo::kIsProgramChange).

• The plug-in can provide GUI for the selection of programs, but it must synchronize the corresponding program selection parameter.

• A host may want to show the program list of the active unit in the same way as it shows the presets of a simple plug-in (usually in a separate control area at the top or the bottom of the window). The host must be able to display the correct list and the correct program name for the unit that has got the focus in the plug-in GUI.

To make this all work correctly, the plug-in must supply a valid implementation of Steinberg::Vst::IUnitInfo and it must operate the callback interface Steinberg::Vst::IUnitHandler accordingly.

Similar to the simple case, the host may want to save and load preset files. The component state of the plug-in is not useful here. A preset of a complex plug-in can be:

• The state of a plug-in unit

  • To support this, the plug-in must implement the Steinberg::Vst::IUnitData interface in its component part.

• The contents of an item in the program list

  • To support this, the plug-in must implement the Steinberg::Vst::IProgramListData interface in its component part.

A plug-in can support unit presets and program list presets.

See also Presets & Program Lists, Steinberg::Vst::IProgramListData, Steinberg::Vst::IUnitData.

Units and Tracks

A unit can be associated with busses (or channels of busses). In particular, a unit can have a fixed and unique connection to an input MIDI channel. For a host, it might be useful to know about this connection and which unit can be associated with a specific MIDI track as a result of this. Often, the GUI of a multi-timbral plug-in does not show the settings of all similar units at the same time. Instead, there is some kind of unit selection. The idea is to be able to synchronize the selection of units in a plug-in to the selection of tracks in the host (in both ways).

When a plug-in GUI is organized in the described way, it should support the described behavior by implementing

• Steinberg::Vst::IUnitInfo::getUnitByBus: find out the track - unit relations

• Steinberg::Vst::IUnitInfo::getSelectedUnit: let the host know which track to select

• Steinberg::Vst::IUnitInfo::selectUnit: cause the plug-in to select its unit

and by calling

• Steinberg::Vst::IUnitHandler::notifyUnitSelection: trigger the host to synchronize its GUI

Routing

For a host, it may be interesting to know which VSTi channel in the mixer is the output of a specific MIDI track if the plug-in defines multiple audio output busses (represented as VSTi mixer channels in the host). In general, the host needs to know about any input to output routing of the plug-in. So if an unambiguous relation exists between a plug-in input and an output, the following method should be implemented:

• Steinberg::Vst::IComponent::getRoutingInfo: find out the output of a given input

/ VST Home / Technical Documentation

Data Exchange

On this page:

• Introduction
• The Data Exchange API
  • IDataExchangeHandler
    • Opening a queue
    • Sending data
    • Closing a queue
    • What to do when the queue is full and no block can be locked?
  • IDataExchangeReceiver

Related pages:

• Data Exchange Tutorial

Introduction

In a modern plug-in, the UI representation and the audio processing do not share any data directly. This eliminates undefined behavior, as they run in different threads and any directly shared data would need to be protected by a mutex. But a mutex has no defined running time and may block the audio thread for too long, creating an audible glitch, which must be prevented.

The other issue with sharing data between the UI and the audio processing is that the audio is processed before the audio is streamed through the monitor boxes or headphones. Without synchronization, the visual representation is displayed earlier than the sound it represents. To synchronize the visual representation and the processing of the audio signal, the UI has to queue the visual data until the time is reached when the audio is heard.

This problem has already been solved for parameters which are automated by the host. The host delays sending the parameter change to the edit controller so that it is in sync with the audible audio.

But parameters are limited in how much data they can transfer, this may be enough for a simple peak VU meter display, but presenting an FFT curve with it is a nightmare.

Version 3.7.9 of the SDK contains the new Data Exchange API to send data from the realtime processing function to the controller in a safe and efficient way.

As this API needs support from the host and not all hosts provide this API right from the start, the SDK contains a backwards compatibility layer that either uses the API directly, if available, or an alternative method based on the IMessage API to emulate the API. See the tutorial on how to use it.

The Data Exchange API

The API consists of two interfaces, the IDataExchangeHandler which needs to be implemented by the host and the IDataExchangeReceiver which needs to be implemented by the plug-in.

IDataExchangeHandler

The IDataExchangeHandler implements a direct and thread-safe connection from the realtime audio context of the audio processor to the non-realtime audio context of the edit controller. This should be used when the edit controller needs continuous data from the audio process for visualization or other "use-cases". To circumvent the bottleneck on the main thread, it is possible to configure the connection in a way that the calls to the edit controller happen on a background thread, see IDataExchangeReceiver below.

Opening a queue

The main operation for a plug-in is to open a queue via the handler before the plug-in is activated (but it must be connected to the edit controller via the IConnectionPoint when the plug-in is using the recommended separation of edit controller and audio processor). The best place to do this is in the IAudioProcessor::setupProcessing method, as this is also the place where the plug-in identifies the sample rate and maximum block size which the plug-in may need to calculate the queue block size. When a queue is opened, the edit controller is notified of this, and the controller can decide if it wishes to receive the data on the main thread or the background thread.

Sending data

In the IAudioProcessor::process call, the plug-in can now lock a block from the handler and fill it. When done, it can free the block via the handler, which then sends the block to the edit controller. The edit controller then receives the block either on the main thread or on a background thread depending on the setup of the queue. The host guarantees that all blocks are sent before the plug-in is deactivated.

Closing a queue

The audio processor must close an open queue. This need to be done after deactivating the processor and prior to disconnecting it from the edit controller (see IConnectionPoint).

What to do when the queue is full and no block can be locked?

The plug-in needs to be prepared for this situation, as constraints in the overall system may cause the queue to fill up excessively. If you need to transfer the information to the controller, you can declare a hidden parameter, which you can set to a special value and send this parameter change in your audio process method.

IDataExchangeReceiver

The IDataExchangeReceiver interface must be implemented by the edit controller of the plug-in. The host will call the queueOpened method when an exchange queue is opened by the processor. Later when the processor closes the queue, the host will call the queueClosed method.

While the queue is open, the host will call the onDataExchangeBlocksReceived method whenever the processor has sent data.

The edit controller can decide in the call to queueOpened if the host should deliver the data on a background thread or on the UI thread.

/ VST Home / Technical Documentation

VST 3 Workflow Diagrams

Some useful graphical call sequences a VST 3 compliant host should follow.

Audio Processor Call Sequence

Edit Controller Call Sequence

Get Latency Call Sequence

Resize View Call Sequence

Bus Arrangement Setting Sequence

/ ... / VST 3 Workflow Diagrams

Audio Processor Call Sequence

Related pages:

• Edit Controller Call Sequence

stateDiagram

State0: Factory
State1: Created
State2: Initialized
State25: Connected (optional)
State3: Setup Done
State4: Activated
State5: Processing


State1: IComponent->setIoMode
State1: IComponent->getControllerClassID   

State2: IComponent->setState
State2: IComponent->getState
State2: ----------------------------------------------
State2: IConnectionPoint->connect
State2: ----------------------------------------------
State2: IAudioProcessor->setBusArrangement
State2: IAudioProcessor->getBusArrangement
State2: IAudioProcessor->canProcessSampleSize

State25: IComponent->setState
State25: IComponent->getState
State25: ----------------------------------------------
State25: IConnectionPoint->disconnect
State25: IConnectionPoint->notify
State25: ----------------------------------------------
State25: IAudioProcessor->setBusArrangement
State25: IAudioProcessor->getBusArrangement
State25: IAudioProcessor->canProcessSampleSize

State3: IComponent->getBusCount
State3: IComponent->getBusInfo
State3: IComponent->getRoutingInfo
State3: IComponent->activateBus
State3: IComponent->setState
State3: IComponent->getState
State3: ----------------------------------------------
State3: IConnectionPoint->connect
State3: IConnectionPoint->disconnect
State3: IConnectionPoint->notify
State3: ----------------------------------------------
State3: IAudioProcessor->getLatencySamples
State3: IAudioProcessor->getTailSamples
State3: IAudioProcessor->setBusArrangement
State3: IAudioProcessor->getBusArrangement
State3: IAudioProcessor->canProcessSampleSize
State3: IAudioProcessor->setupProcessing
State3: ----------------------------------------------
State3: IProcessContextRequirements->getProcessContextRequirements

State4: IComponent->getBusCount
State4: IComponent->getBusInfo
State4: IComponent->getRoutingInfo
State4: IComponent->setState
State4: IComponent->getState
State4: ----------------------------------------------
State4: IConnectionPoint->notify
State4: ----------------------------------------------
State4: IAudioProcessor->getLatencySamples
State4: IAudioProcessor->getTailSamples
State4: IAudioProcessor->getBusArrangement
State4: IAudioProcessor->canProcessSampleSize
State4: ----------------------------------------------
State4: IAudioPresentationLatency->setAudioPresentationLatency

State5: ---[Processing Thread]-------------------------------
State5: IAudioProcessor->process
State5: ---[UI Thread]---------------------------------------
State5: IComponent->getBusCount
State5: IComponent->getBusInfo
State5: IComponent->getRoutingInfo
State5: IComponent->setState
State5: IComponent->getState
State5: ---[UI Thread]---------------------------------------
State5: IConnectionPoint->notify
State5: ---[UI Thread]---------------------------------------
State5: IAudioProcessor->getLatencySamples
State5: IAudioProcessor->getTailSamples
State5: IAudioProcessor->getBusArrangement
State5: IAudioProcessor->canProcessSampleSize

State0 --> State1: createInstance
State1 --> State0: release
State1 --> State2: initialize
State2 --> State25: connect
State25 --> State2: disconnect
State2 --> State1: terminate
State2 --> State3: setupProcessing
State25 --> State3: setupProcessing
State3 --> State1: terminate
State3 --> State4: setActive(true)
State4 --> State3: setActive(false)
State4 --> State5: setProcessing(true)
State5 --> State4: setProcessing(false)

⚠️ Warning
Note about IAudioProcessor->setProcessing

• transition between Activated and Processing state
• may be called from real-time Processing Thread (must be lock-free and without memory allocation!)
• plug-in has to reset its inner processing state (for example to clean its delay buffers in order to have a defined state when the processing starts again).

/ ... / VST 3 Workflow Diagrams

Edit Controller Call Sequence

Related pages:

• Audio Processor Call Sequence

stateDiagram

State0: Factory
State1: Created
State2: Initialized
State3: Connected

State2: IEditController->setComponentHandler
State3: IConnectionPoint->notify
State3: ----------------------------------------------
State3: IEditController->setComponentState
State3: IEditController->getTailSamples
State3: IEditController->getParameterCount
State3: IEditController->getParameterInfo
State3: IEditController->getParamValueByString
State3: IEditController->normalizedParamToPlain
State3: IEditController->plainParamToNormalized
State3: IEditController->getParamNormalized
State3: IEditController->setParamNormalized
State3: IEditController->createView
State3: ----------------------------------------------
State3: IEditController2 ...
State3: ----------------------------------------------
State3: IMidiMapping ...
State3: ----------------------------------------------
State3: IEditControllerHostEditing ...
State3: ----------------------------------------------
State3: INoteExpressionController ...
State3: ----------------------------------------------
State3: IKeyswitchController ...
State3: ----------------------------------------------
State3: IXmlRepresentationController ...

State0 --> State1: createInstance
State1 --> State0: release
State1 --> State2: initialize
State2 --> State1: terminate
State2 --> State3: IConnectionPoint->connect
State3 --> State1: terminate

ⓘ Note
All Edit Controller methods must be called from the UI Thread

/ ... / VST 3 Workflow Diagrams

Get Latency Call Sequence

On this page:

• Initiated from AudioProcessor
• Initiated from EditController/UI
• without EditController

Initiated from AudioProcessor

sequenceDiagram

participant AP as AudioProcessor
participant H as Host
participant EC as EditController

autonumber

AP->>+H:    sendMessage/latency changed
H-->>-AP:   return
H->>+EC:    notify
    EC->>+H:    restatComponent
    H-->>-EC:   return
EC-->>-H:   return

H->>+AP:    setProcessing (false)
    AP-->>-H: return
H->>+AP:    setActive (false)
AP-->>-H:   return
H->>+AP:    setActive (true)
    AP->>AP:    Change/adapt internal processing Algo
AP-->>-H:   return

H->>+AP:    getLatency
AP-->>-H:   return
H->>+AP:    setProcessing (true)
AP-->>-H:   return

Initiated from EditController/UI

sequenceDiagram

participant AP as AudioProcessor
participant H as Host
participant EC as EditController

autonumber

EC->>+H:     sendMessage/latency changed
    H->>+AP:     notify
    AP-->>-H:    return
H-->>-EC:    return

EC->>+H:     restatComponent
H-->>-EC:    return
H->>+AP:     setProcessing (false)
AP-->>-H:    return
H->>+AP:     setActive (false)
AP-->>-H:    return
H->>+AP:     setActive (true)
    AP->>AP:        Change/adapt internal processing Algo
AP-->>-H:    return

H->>+AP:     getLatency
AP-->>-H:    return
H->>+AP:     setProcessing (true)
AP-->>-H:    return

without EditController

sequenceDiagram

participant AP as AudioProcessor
participant H as Host

autonumber

H->>+AP:     setupProcessing
AP-->>-H:    return

H->>+AP:     setState
AP-->>-H:    return
H->>+AP:     setActive (true)
    AP->>AP:        Change/adapt internal processing Algo
AP-->>-H:    return

H->>+AP:     getLatency
AP-->>-H:    return
H->>+AP:     setProcessing (true)
AP-->>-H:    return

/ ... / VST 3 Workflow Diagrams

Resize View Call Sequence

On this page:

• Initiated from Plug-In
• Initiated from Host

Initiated from Plug-In

sequenceDiagram

    participant P as PlugView
    participant H as Host resp. IPlugFrame

    autonumber

    Note left of P: Press e.g. "Large" button on plug-in GUI
    P->>+H:     resizeView(size)
    H->>+P:     getSize
    P-->>-H:    return
    Note right of H: Still returns the "old" size
    H->>H:      resize frame
    H->>+P:     onSize
    P->>P:      resize view
    P-->>-H:    return
    H->>+P:     getSize
    P-->>-H:    return
    Note right of H: Now returns the "new" size
    H-->>-P:    return

Initiated from Host

User drags window frame in order to resize

sequenceDiagram

    participant P as PlugView
    participant H as Host resp. IPlugFrame

    autonumber

    Note right of H: User drags window frame
    Note right of H: in order to resize
    H->>+P:     checkSizeContraints(size)
    P-->>-H:    return
    H->>+H:     resize frame to [size]
    H->>+P:     onSize(size)
    P->>P:      resize view
    P-->>-H:    return

Moving window to other screen

sequenceDiagram

    participant P as IPlugViewContentScaleSupport
    participant H as Host resp. IPlugFrame

    autonumber
    
    Note right of H:    Move window to other screen
    H->>+P:             setContentScaleFactor(factor)
    P-->>-H:            return
    Note right of H:    From here, same sequence
    Note right of H:    than "Initiated from Plug-In"
    P->>+H:             resizeView(size)
    H-->>-P:            return

/ ... / VST 3 Workflow Diagrams

Bus Arrangement Setting Sequence

On this page:

• Plug-In does accepts what the host wants as Bus Arrangements
• Plug-In does not accept what the host wants as Bus Arrangements
• Check FAQ for some use case!

Plug-In does accepts what the host wants as Bus Arrangements

sequenceDiagram

    participant H as Host
    participant P as Plug-in: IAudioProcessor

    autonumber

    H->>+P:     setProcessing (false)
    P-->>-H:    return
    H->>+P:     setActive (false)
    P-->>-H:    return

    H->>+P:     setBusArrangements (req. Ins, req. Outs)
    P-->>P:     adapt its arrangements if needed

    P-->>-H:    return kResultTrue

    H->>+P:     setActive (true)
    P-->>-H:    return
    H->>+P:     setProcessing (true)
    P-->>-H:    return

Plug-In does not accept what the host wants as Bus Arrangements

sequenceDiagram

    participant H as Host
    participant P as Plug-in: IAudioProcessor

    autonumber

    H->>+P:     setProcessing (false)
    P-->>-H:    return
    H->>+P:     setActive (false)
    P-->>-H:    return

    H->>+P:     setBusArrangements (req. Ins, req. Outs)
    P-->>P:     Adapt its busses according to the requested ones if possible
    P-->>P:     return kResultFalse if not match.

    P-->>-H:    return kResultFalse

    H->>+P:     for each Bus: getBusArrangement ()
    P-->>-H:    return kResultTrue

    H->>+P:     setActive (true)
    P-->>-H:    return
    H->>+P:     setProcessing (true)
    P-->>-H:    return

Check FAQ for some use case!

/ VST Home / Technical Documentation

VST 3 Locations / Format

On this page:

• Plug-in Format Structure
• Plug-in Locations
• Preset Format
• Preset Locations
• Snapshots
• Remote Representation Locations

Formats definition of a VST 3 plug-in and its preset and where they are located on different platforms.

Plug-in Format Structure

This section explains how a VST 3 plug-in is structured as files and folders.

Plug-in Locations

This section explains where VST 3 plug-in are located on the different supported platforms.

Preset Format

This section explains the VST 3 format for preset file.

Preset Locations

This section explains where VST 3 preset files are located on the different supported platforms.

Snapshots

Since VST 3.6.10, a VST 3 bundle can contain pre-rendered snapshot images for VST 3 host as visual representation of the plug-in UI.

Remote Representation Locations

This section explains where VST XMLs files (Remote Presentation of Parameters) are located on the different supported platforms.

/ ... / VST 3 Locations / Format

Plug-in Format Structure

On this page:

• For the macOS platform
• For the Windows platform
  • Limitation for loading Plug-in DLL in a Host (inside the same process)
• For the Linux platform
• Merged Bundle

Related pages:

• VST 3 Locations / Format
• Snapshots

For the macOS platform

On the macOS platform, VST 3 plug-in is a standard macOS bundle, its file extension is ".vst3" and has the following folder structure:

For the Windows platform

On the Windows platform, a VST 3 plug-in is organized as a bundle-like package (simple folder), its file extension is ".vst3" and has the following folder structure:

ⓘ Note
In previous SDKs, the VST 3 plug-in was defined as a single dll file with the .vst3 extension. This has been deprecated since VST 3.6.10.

The file desktop.ini should contain:

desktop.ini

[.ShellClassInfo]
IconResource=Plugin.ico,0

and you should then change their attributes with this command line (s for system to make sure that Windows will use it for the folder/bundle, r for read-only and h for hidden (optional)):

attrib +s +r +h desktop.ini
attrib +r +h Plugin.ico

Limitation for loading Plug-in DLL in a Host (inside the same process)

See Microsoft Blogs about this:

"TLDR: Please offer both Arm64EC and x64 versions of your DAWs and plug-ins, and please stay up to date with the latest developer tooling and SDKs." (Pete Brown - Microsoft)

ⓘ Note
With out-of-process/inter-process communication a host can overriden these limitations, by allowing, for example, an Arm64 Classic host to handle an Arm64EC plug-in.

ⓘ Note
To learn more about Arm64X (new type of binary that can contain both the classic Arm64 code and Arm64EC code together), click here.

For the Linux platform

On Linux, a VST 3 plug-in is organized as a bundle-like package, its file extension is ".vst3", and it has the following folder structure:

Merged Bundle

Note that all the bundles can be merged to one, which allows to have a cross-platform bundle/folder.

For example:

./MyPlugin.vst3
    ├── Contents
    │   ├── Resources
    │   │   ├── Documentation
    │   │   │   ├── Manual.pdf
    │   │   │   └── WhatsNew.pdf
    │   │   ├── Help
    │   │   │   └── helpdoc.xml
    │   │   ├── Snapshots
    │   │   │   ├── 84E8DE5F92554F5396FAE4133C935A18_snapshot.png
    │   │   │   └── 84E8DE5F92554F5396FAE4133C935A18_snapshot_2.0x.png
    │   │   ├── VST XMLs
    │   │   │   └── AGain
    │   │   │       └── 84E8DE5F92554F5396FAE4133C935A18
    │   │   │           ├── Generic 8 Cells.xml
    │   │   │           └── WK-Audio ID 8 Cells.xml
    │   │   ├── moduleinfo.json
    │   │   └── MyPlugin.srf
    │   │
    │   ├── armv7l-linux
    │   │   └── MyPlugin.so
    │   │
    │   ├── i686-linux
    │   │   └── MyPlugin.so
    │   │
    │   ├── i386-linux
    │   │   └── MyPlugin.so
    │   │
    │   ├── x86_64-linux
    │   │   └── MyPlugin.so
    │   │
    │   ├── MacOS
    │   │   └── MyPlugin
    │   │
    │   ├── x86_64-win
    │   │   └── MyPlugin.vst3
    │   │
    │   ├── arm64ec-win
    │   │   └── MyPlugin.vst3
    │   │
    │   ├── Info.plist  (macOS Only)
    │   └── PkgInfo     (macOS Only)
    │
    ├── desktop.ini    (Windows only)
    └── Plugin.ico     (Windows only)

/ ... / VST 3 Locations / Format

Plug-in Locations

On this page:

• Introduction
  • On macOS platform
  • On Windows platform
  • On Linux platform

Related pages:

• VST 3 Locations / Format
• Plug-in Format Structure

Introduction

A VST 3 plug-in should be installed at specific folder location, the following tables specify these predefined locations for different operating system.

ⓘ Note
VST 3 doesn't require a plug-in registration like it is used with DirectX.

⚠️ Warning
Links, Symbolic links or Shortcuts could be used from these predefined folders.

3 levels of folder location are defined:

• User: available only for the current logged user
• Global: available for all users of the system
• Application: available only inside a specific Audio Application (local plug-ins)

ⓘ Note
The host should scan, at first, higher level of priority. First found plug-in (for a given Processor UID) has to be used.

On macOS platform

On the macOS platform, the host application expects VST 3 plug-ins to be located in:

ⓘ Note
The host recursively scans these folders at startup in this order (Global/Application).

On Windows platform

On the Windows platform, the host application expects VST 3 plug-ins to be located in:

ⓘ Note
The host recursively scans these folders at startup in this order (Global/Application).

On Linux platform

On the Linux platform, the host application expects VST 3 plug-ins to be located in:

ⓘ Note
The host recursively scans these folders at startup in this order (User/Global/Application).

/ ... / VST 3 Locations / Format

Preset Format

Related pages:

• Preset Locations
• Presets & Program Lists

The file extension has to be .vstpreset, for example: myBestDefault.vstpreset

Specification of a VST 3 Preset file:

	VST 3 Preset File Format Definition
    ===================================

0   +---------------------------+
    | HEADER                    |
    | header id ('VST3')        |       4 Bytes
    | version                   |       4 Bytes (int32)
    | ASCII-encoded class id    |       32 Bytes 
 +--| offset to chunk list      |       8 Bytes (int64)
 |  +---------------------------+
 |  | DATA AREA                 |<-+
 |  | data of chunks 1..n       |  |
 |  ...                       ...  |
 |  |                           |  |
 +->+---------------------------+  |
    | CHUNK LIST                |  |
    | list id ('List')          |  |    4 Bytes
    | entry count               |  |    4 Bytes (int32)
    +---------------------------+  |
    |  1..n                     |  |
    |  +----------------------+ |  |
    |  | chunk id             | |  |    4 Bytes
    |  | offset to chunk data |----+    8 Bytes (int64)
    |  | size of chunk data   | |       8 Bytes (int64)
    |  +----------------------+ |
EOF +---------------------------+

Check the Steinberg::Vst::PresetFile source code which allows to read and write such presets.

/ ... / VST 3 Locations / Format

Preset Locations

On this page:

• Introduction
  • For Mac platform
  • For Windows XP/2000 platform
  • For Windows Vista/7/8/10
  • For Linux platform

Related pages:

• VST 3 Locations / Format

Introduction

VST 3 presets are located at predefined locations on the computer, depending on the operating system.

• 3 levels of preset scope are defined:
  • User: available only for the current logged user
  • Public: available for all users of the system
  • Apps: available only inside a specific audio application
• 4 types of preset are defined:
  • User: presets created by the user
  • User_Factory: like User type, but more hidden
  • Shared_Factory: factory presets installed by the plug-in installer
  • App_Factory: presets installed by an audio application installer, only visible for this specific audio application

⚠️ Warning
$COMPANY and $PLUGIN-NAME folder names contain only allowed characters for file naming (replace characters "\*?/:<>|"by "_").

ⓘ Note
Each path defined below should be scanned in the given priority, presets extracted and added to the preset list.

For Mac platform

For Windows XP/2000 platform

For Windows Vista/7/8/10

For Linux platform

/ ... / VST 3 Locations / Format

Snapshots

On this page:

Related pages:

• VST 3 Locations / Format

See [3.6.10] UI Snapshots

/ VST Home / Technical Documentation

About MIDI in VST 3

On this page:

• Related Concepts in MIDI and VST 3
• MIDI 2.0 Per-Note Controllers
• MIDI 2.0 Increased Resolution, compared to MIDI 1.0

Related pages:

• [3.0.1] Parameter MIDI Mapping
• [3.5.0] Note Expression
• [3.5.0] Key Switch
• [3.6.11] NoteExpression Physical UI Mapping
• [3.6.12] Legacy MIDI CC Out Event
• [3.6.12] MPE support for Wrappers

Unlike in VST 2, MIDI is not included in VST 3.

But VST 3 offers suitable concepts that can be translated to and from MIDI using Event:

Related Concepts in MIDI and VST 3

Relationship of concepts in MIDI 1.0 to VST 3

Additional relationships of concepts introduced in MIDI 2.0 (https://www.midi.org/) to VST 3

MIDI 2.0 Per-Note Controllers

There are many subtle differences between MIDI 2.0 Per-Note Controllers and VST 3 NoteExpression. The good thing is that plug-in developers do not have to do anything about it. It is the host's duty to translate from MIDI 2.0 to VST 3.

MIDI 2.0 Increased Resolution, compared to MIDI 1.0

MIDI 2.0 achieved a significant increase in resolution of many important values, like Velocity, Pressure, and Controllers compared to MIDI 1.0. Nevertheless, VST 3 still has superior resolution than MIDI 2.0. Plug-ins and hosts supporting VST 3 should make use of these capabilities and should not stick to a 0-127 mindset.

See the following tables to compare the resolution of specific values in MIDI 1.0, MIDI 2.0, and VST 3.

/ VST Home / Technical Documentation

Provide a RunLoop on Linux

On this page:

• Query IRunLoop from IPlugFrame
• Query IRunLoop from the host context of IPlugFactory3

On Linux, there is no global event run loop like on Windows and macOS. For this reason, the plug-in can query for an Linux::IRunLoop which must be provided by the host application in two different ways.

Query IRunLoop from IPlugFrame

The host application must provide the Linux::IRunLoop via IPlugFrame (by calling IPlugView::setFrame).

// Plug-in implementation
tresult PLUGIN_API MyPlugView::setFrame (Steinberg::IPlugFrame* frame)
{
    ...
    Steinberg::FUnknownPtr<Steinberg::Linux::IRunLoop> runLoop (plugFrame);
    if (runLoop)
    {
        runLoop->registerEventHandler (...);
    }
    ...
}

Query IRunLoop from the host context of IPlugFactory3

A plug-in also needs a way to query for an Linux::IRunLoop without IPlugFrame. This allows to register timers in case the editor is closed or unavailable.

These timers can be used inside Vst::IAudioProcessor for extra computations or sending messages within the UI thread.

The host application must call Vst::IPlugFactory3::setHostContext (context) for this and provide a context. This context can be used to query an Linux::IRunLoop interface.

// Plug-in implementation
tresult PLUGIN_API MyPlugFactory::setHostContext (FUnknown* context)
{
    ...
    Steinberg::FUnknownPtr<Steinberg::Linux::IRunLoop> runLoop (context);
    if (runLoop)
    {
        runLoop->registerTimer (...);
    }
    ...
}

/ VST Home / Technical Documentation

Minimum Host requirements for VST 3 support

VST 3 Interfaces to be implemented by a VST 3 host:

• [3.0.0] Interfaces supported by the host.
• If MIDI is supported: [3.6.12] MIDI Learn.
• [3.6.12] Host Query Interface support.
• If a plug-in implements IPluginViewContentScaleSupport, the host should follow the [3.6.6] PlugView Content Scaling requirements.

Features History

• [3.0.0] Interfaces supported by the plug-in
• [3.0.0] Multiple Dynamic I/O Support
• [3.0.0] Silence flags
• [3.0.0] Interfaces supported by the host
• [3.0.1] Parameter MIDI Mapping
• [3.0.2] Parameter Finder
• [3.1.0] Audio Presentation Latency
• [3.1.0] Dirty State, Open Editor Request and UI Group Editing Support
• [3.1.0] KnobMode, Open Help & Open Aboutbox
• [3.5.0] Note Expression
• [3.5.0] Key Switch
• [3.5.0] Remote Presentation of Parameters
• [3.5.0] Context Menu
• [3.5.0] Enhanced Linked Parameters
• [3.6.0] iOS Inter-App Audio
• [3.6.0] Preset Meta-Information
• [3.6.5] Channel Context Info
• [3.6.5] Unit-Bus Assignment Change
• [3.6.5] Prefetchable
• [3.6.5] Automation State
• [3.6.6] PlugView Content Scaling
• [3.6.8] Request Bus Activation
• [3.6.10] UI Snapshots
• [3.6.11] NoteExpression Physical UI Mapping
• [3.6.12] Legacy MIDI CC Out Event
• [3.6.12] MIDI Learn
• [3.6.12] Host Query Interface support
• [3.6.12] MPE support for Wrappers
• [3.7.0] Parameter Function Name
• [3.7.0] Progress display
• [3.7.0] Process Context Requirements
• [3.7.0] Control Voltage Bus Flag
• [3.7.5] Module Info and Plug-in Compatibility
• [3.7.9] Get Current SystemTime
• [3.7.9] Data Transfert Between Processor/Controller
• [3.7.11] Remap Parameter ID

/ VST Home / Technical Documentation

[3.0.0] Interfaces supported by the plug-in

On this page:

• IComponent
• IAudioProcessor
• IEditController
• IConnectionPoint
• IUnitInfo
• IProgramListData
• IUnitData
• IPlugView
  • Sizing of a view
  • Keyboard handling

Related pages

• [3.0.0] Interfaces supported by the host

List of interfaces supported/implemented by the plug-in in VST 3.0.0

IComponent

Component base interface.

• [plug imp]
• [released: 3.0.0]
• [mandatory]

This is the basic interface for a VST component and must always be supported. It contains the common parts of any kind of processing class. The parts that are specific to a media type are defined in a separate interface. An implementation component must provide both the specific interface and IComponent.

See also IPluginBase.

IAudioProcessor

Audio processing interface.

• [plug imp]
• [extends IComponent]
• [released: 3.0.0]
• [mandatory]

This interface must always be supported by audio processing plug-ins.

IEditController

Edit controller component interface.

• [plug imp]
• [released: 3.0.0]
• [mandatory]

The controller part of an effect or instrument with parameter handling (export, definition, conversion...).

See also IComponent::getControllerClassId, IMidiMapping.

IConnectionPoint

Connect a component with another one.

• [plug imp]
• [host imp]
• [released: 3.0.0]
• [mandatory]

This interface is used for the communication of separate components. Note that some hosts will place a proxy object between the components so that they are not directly connected.

See also Communication between the components.

IUnitInfo

Edit controller extension to describe the plug-in structure.

• [plug imp]
• [extends IEditController]
• [released: 3.0.0]
• [optional]

IUnitInfo describes the internal structure of the plug-in.

• The root unit is the component itself, so getUnitCount must return 1 at least.
• The root unit id has to be 0 (kRootUnitId).
• Each unit can reference one program list - this reference must not change.
• Each unit that uses a program list references one program of the list.

See also VST 3 Units, IUnitHandler.

IProgramListData

Component extension to access program list data.

• [plug imp]
• [extends IComponent]
• [released: 3.0.0]
• [optional]

A component can support program list data via this interface or/and unit preset data (IUnitData).

See also IUnitData, Complex Plug-in Structures / Multi-timbral Instruments.

IUnitData

Component extension to access unit data.

• [plug imp]
• [extends IComponent]
• [released: 3.0.0]
• [optional]

A component can support unit preset data via this interface or program list data (IProgramListData).

See also Presets & Program Lists.

IPlugView

Plug-in definition of a view.

• [plug imp]
• [released: 3.0.0]

Sizing of a view

After the creation of a IPlugView, the plug-in must make sure that it returns the correct size if the host asks for it (IPlugView::getSize ()).

Usually, the size of a plug-in view is fixed. But both the host and the plug-in can cause a view to be resized:

• Host: If IPlugView::canResize () returns kResultTrue, the host will set up the window so that the user can resize it. While the user resizes the window, IPlugView::checkSizeConstraint () is called, allowing the plug-in to change the size to a valid supported rectangle size. The host then resizes the window to this rect and has to call IPlugView::onSize ().

• Plug-in: The plug-in can call IPlugFrame::resizeView () and cause the host to resize the window. Afterwards, in the same callstack, the host has to call IPlugView::onSize () if a resize is needed (size was changed).

ⓘ Note
Note that if the host calls IPlugView::getSize () before calling IPlugView::onSize () (if needed), it will get the old size, not the current one!

Here the calling sequence:

• plug-in->host: IPlugFrame::resizeView (newSize)
• host->plug-in (optional): IPlugView::getSize () returns the currentSize (not the newSize!)
• host->plug-in: if newSize is different from the current size: IPlugView::onSize (newSize)
• host->plug-in (optional): IPlugView::getSize () returns the newSize

ⓘ Note
Please only resize the platform representation of the view when IPlugView::onSize() is called.

Keyboard handling

The plug-in view receives keyboard events from the host. A view implementation must not handle keyboard events by the means of platform callbacks, but let the host pass them to the view. The host depends on a proper return value when IPlugView::onKeyDown is called, otherwise the plug-in view may cause a malfunction of the host's key command handling.

See also IPlugFrame, Platform UI Types.

/ VST Home / Technical Documentation

[3.0.0] Multiple Dynamic I/O Support

On this page:

• Introduction
• Multiple Input or Output busses
• Information about busses
• Activation of busses
• What is a Side-Chain?
• How can I implement a Side-chain path into my plug-in?
• Audio bus Channel Configuration
  • How are the different Speakers located?
  • My plug-in is capable of processing all possible channel configurations
  • How are speaker arrangement settings handled for FX plug-ins?
  • How report to the host that the plug-in Arrangement has changed?
  • My plug-in has mono input and stereo output. How does VST 3 handle this?

Related pages

• Audio Processor Call Sequence
• Bus Arrangement Setting Sequence
• Complex Plug-in Structures / Multi-timbral Instruments

Introduction

VST 3 plug-ins are no longer limited to a fixed number of inputs and outputs, and their I/O configuration can dynamically adapt to the channel configuration. Side-chains are also very easily realizable. This includes the possibility to deactivate unused busses after loading and even reactivate those when needed. This cleans up the mixer and further helps to reduce CPU load.

A bus can be understood as a "collection of data channels" belonging together:

• it describes a data input (kInput) or a data output (kOutput) of the plug-in.
• 2 types of bus is supported: kAudio and kEvent
• a VST component can define any desired number of busses.
• a bus could be defined a main bus (kMain) or auxiliary bus (kAux) for sidechaining (The kMain busses have to place before any others kAux busses in the exported busses list)
• a host that can handle multiple busses, allows the user to activate busses which are initially all inactive.

Multiple Input or Output busses

A plug-in could have different reason to define multiple event input busses, for examples:

• in case of complex multitimbral instrument supporting more than 16 loaded sub-instruments at the same time by adding a kind of structure in its inputs from host perspective (simulating a kind of number of "MIDI Port" having its sub-MIDI channels)
• in case to different inputs meaning, which are distinctly visible and selectable in the host:
  • one input for playing event
  • one input for modulation event

A plug-in could have different reason to define multiple event output busses, for example:

• in case of a main event output for played event from the UI and one event output for internally generated events from an arpeggiator.

A plug-in could decide to export more than one audio input by adding a second audio input (Side-chains, see below) or more.

A typical use case for multiple audio outputs is instrument plug-ins, for examples:

• with one main audio output and some auxiliary audio outputs for FX Returns or FX Sends.
• with one main audio output for each internally loaded instrument.

Example

//------------------------------------------------------------------------
tresult PLUGIN_API MyPlugin::initialize (FUnknown* context)
{
    //---always initialize the parent-------
    tresult result = AudioEffect::initialize (context);
    // if everything Ok, continue
    if (result != kResultOk)
    {
        return result;
    }

    //---create Audio In/Out busses------
    // we want a stereo Input and a Stereo Output
    addAudioInput (STR16 ("Stereo In"), SpeakerArr::kStereo, kMain, BusInfo::kDefaultActive);
    addAudioOutput (STR16 ("Stereo Out"), SpeakerArr::kStereo, kMain, BusInfo::kDefaultActive);

    //---create Main Event In bus (1 bus with only 16 channel)------
    addEventInput (STR16 ("Event In"), 16, kMain, BusInfo::kDefaultActive);

    //---create Aux Event In bus (1 bus with only 1 channel)------
    addEventInput (STR16 ("Mod In"), 1, kAux, 0); // not default activated wanted

    //---create Event out bus (1 bus with only 1 channel)------
    addEventOutput (STR16 ("Arpeggiator"), 1, kAux, 0); // not default activated wanted

    return kResultOk;
}

Information about busses

In order to get the number and information about busses exported by the plug-in, the host uses this interface IComponent with these functions:

/** Called after the plug-in is initialized. */
virtual int32 PLUGIN_API getBusCount (MediaType type, BusDirection dir) = 0;
 
/** Called after the plug-in is initialized. */
virtual tresult PLUGIN_API getBusInfo (MediaType type, BusDirection dir, int32 index, BusInfo& bus /*out*/) = 0;

BusInfo contains information like:

• name,
• number of channel,
• ...
• and the some flags indicating:
  • kDefaultActive: The bus should be activated by the host per default on instantiation (activateBus call is requested). By default a bus is inactive. Note that if a host offers the possibility to activate/deactivate busses to the user later on, it may not follow this flag kDefaultActive and let some busses deactivated on instantiation.
  • kIsControlVoltage: The bus does not contain ordinary audio data, but data used for control changes at sample rate.
    • The data is in the same format as the audio data [-1.0, 1.0].
    • A host has to prevent unintended routing to speakers to prevent damage.
    • Only valid for audio media type busses.

Activation of busses

Dynamic usage of busses is handled in the host by activating and deactivating busses. All busses are initially inactive.

The plug-in has to define which of them have to be activated by default after instantiation of the plug-in, this is only a wish, the host is allowed to not follow it, and only activate the first bus for example.

// here default activation is wanted (but not guaranteed)
addAudioInput (STR16 ("SideChain"), SpeakerArr::kStereo, kAux, BusInfo::kDefaultActive);

In order to be use each Input bus and Output bus have to be activated, this is done by the host by using this interface implemented by the plug-in (IComponent):

//------------------------------------------------------------------------
tresult PLUGIN_API Component::activateBus (MediaType type, BusDirection dir, int32 index, TBool state)
{
    // ...

Deactivated busses do not need to be processed by the plug-in, which allows to reduce the CPU load.

Check the workflow diagrams in order to understand when this is called:

• Audio Processor Call Sequence
• Bus Arrangement Setting Sequence

What is a Side-Chain?

In audio applications, some plug-ins allow for a secondary signal to be made available to the plug-in and act as a controller of one or more parameters in the processing. Such a signal is commonly called a Side-chain Signal or Side-chain Input.

Examples:

If a recorded kick drum is considered well played, but the recording of the bass player's part shows that he regularly plays slightly ahead of the kick drum, a plug-in with a 'Gating' function on the bass part can use the kick drum signal as a side-chain to 'trim' the bass part precisely to that of the kick.

Another application is to automatically lower the level of a musical background when another signal, such as a voice, reaches a certain level. In this case a plug-in with a 'Ducking' function would be used - where the main musical signal is reduced while the voice signal is applied to the side-chain input.

A delay's mix parameter can be controlled by a side-chain input signal - to make the amount of delay signal proportional to the level of another.

The side-chain can be used as an additional modulation source instead of cyclic forms of modulation. From the plug-in's perspective, side-chain inputs and/or outputs are additional inputs and outputs which can be enabled or disabled by the host.

The host (if supported) will provide to the user a way to route some signal paths to these side-chain inputs or from side-chain outputs to others signal inputs.

What is Side-Chaining and How to Use It | Music Production For Beginners

Here an example of Side-Chaining for a Instrument in Cubase

How can I implement a Side-chain path into my plug-in?

In AudioEffect::initialize (FUnknown* context) you must add the required bus- and speaker configuration of your plug-in. For example, if your plug-in works on one input and one output bus, both stereo, the appropriate code snippet would look in the following way:

addAudioInput (USTRING ("Stereo In"), SpeakerArr::kStereo);
addAudioOutput (USTRING ("Stereo Out"), SpeakerArr::kStereo);
 
// In addition, adding a stereo side-chain bus would look in the following way:
addAudioInput (USTRING ("Aux In"), SpeakerArr::kStereo, kAux, 0); // 0 here means not activated by default wanted

Audio bus Channel Configuration

Each audio bus has its channel configuration which is a Speaker Arrangement:

Stereo (L+R)

const SpeakerArrangement kStereo = kSpeakerL | kSpeakerR;

How are the different Speakers located?

Here's an overview of the main defined speaker locations (Check enum Speakers and namespace SpeakerArr). A SpeakerArrangement is a bitset combination of speakers.

For example:

const SpeakerArrangement kStereo = kSpeakerL | kSpeakerR; // => representing in hexadecimal 0x03 and in binary 0011.

My plug-in is capable of processing all possible channel configurations

What type of speaker arrangement should I select when adding busses?

Take the configuration your plug-in is most likely to be used with. For a 5.1-surround setup that would be the following:

addAudioInput (USTRING ("Surround In"), SpeakerArr::k51);
addAudioOutput (USTRING ("Surround Out"), SpeakerArr::k51);

But when the host calls Vst::IAudioProcessor::setBusArrangements the host is informing your plug-in of the current speaker arrangement of the track it was selected in. You should return kResultOk, in the case you accept this arrangement, or kResultFalse, in case you do not.

ⓘ Note
If you reject a Vst::IAudioProcessor::setBusArrangements by returning kResultFalse, the host calls Vst::IAudioProcessor::getBusArrangement where you have the chance to give the parameter 'arrangement' the value of the speaker arrangement your plug-in does accept for this given bus.

Afterward the host can recall Vst::IAudioProcessor::setBusArrangements with the plug-in wanted Arrangements then the plug-in should return kResultOk.