VST 3 Developer Portal

https://steinbergmedia.github.io/vst3_dev_portal/pages/
Admin
VST 3 Developer Portal is Steinberg's comprehensive resource for developers creating VST 3 audio...
Tokens:158,605
Snippets:1,213
Trust Score:9.7
Update:8 hours ago
Show doc for...
Tokens:
Raw
### Install QTCreator IDE on Linux

Source: https://steinbergmedia.github.io/vst3_dev_portal/pages/Getting+Started/How+to+setup+my+system.html

Install the QTCreator IDE, which is a recommended optional IDE for VST 3 development on Linux.

```c++
sudo apt-get install qtcreator
```

--------------------------------

### Install required Linux packages for VST 3 SDK

Source: https://steinbergmedia.github.io/vst3_dev_portal/pages/Getting+Started/How+to+setup+my+system.html

Install the required packages for building the SDK examples on Ubuntu-based Linux. On Raspbian/Debian, replace "libxcb-util-dev" with "libxcb-util0-dev".

```c++
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
```

--------------------------------

### Install optional Linux packages for VST 3 SDK

Source: https://steinbergmedia.github.io/vst3_dev_portal/pages/Getting+Started/How+to+setup+my+system.html

Install optional packages for version control and build tools. These are not required but recommended for development.

```c++
sudo apt-get install subversion git ninja-build
```

--------------------------------

### Build the plug-in with xcodebuild or CMake

Source: https://steinbergmedia.github.io/vst3_dev_portal/pages/Tutorials/Building+the+examples/Building+the+examples+included+in+the+SDK+macOS.html

Builds the plug-in using xcodebuild, or alternatively with CMake for a Release configuration.

```c++
xcodebuild
```

```c++
cmake --build . --config Release
```

--------------------------------

### Asymmetric Input-Output Arrangements (mono->Quadro) Example

Source: https://steinbergmedia.github.io/vst3_dev_portal/pages/Technical+Documentation/Change+History/3.0.0/Multiple+Dynamic+IO.html

Shows the host negotiation sequence when a plug-in only supports asymmetric input-output arrangements, specifically mono input to Quadro output.

```c++
// Host -> Plug-in: setBusArrangements (QuadroIN, QuadroOUT)

plug-in return: kResultFalse
host -> plug-in: getBusArrangement (IN) => return Mono;
host -> plug-in: getBusArrangement (OUT) => return Quadro;
host -> plug-in: setBusArrangements (MonoIN, QuadroOUT)
plug-in return: kResultOk
```

--------------------------------

### Asymmetric Input-Output Arrangements (mono->5.1) Example

Source: https://steinbergmedia.github.io/vst3_dev_portal/pages/Technical+Documentation/Change+History/3.0.0/Multiple+Dynamic+IO.html

Shows the host negotiation sequence when a plug-in only supports asymmetric input-output arrangements, specifically mono input to 5.1 output.

```c++
// Example of a Plug-in supporting only asymmetric Input-Output Arrangements (mono-> stereo to up 5.1):

host -> plug-in: setBusArrangements (5.1IN, 5.1OUT)
plug-in return: kResultFalse
host -> plug-in: getBusArrangement (IN) => return Mono;
host -> plug-in: getBusArrangement (OUT) => return 5.1;
host -> plug-in: setBusArrangements (MonoIN, 5.1OUT)
plug-in return: kResultOk
```

--------------------------------

### Asymmetric Input-Output Arrangements (mono->stereo) Example

Source: https://steinbergmedia.github.io/vst3_dev_portal/pages/Technical+Documentation/Change+History/3.0.0/Multiple+Dynamic+IO.html

Shows the host negotiation sequence when a plug-in only supports asymmetric input-output arrangements, specifically mono input to stereo output.

```c++
// Example of a Plug-in supporting only asymmetric Input-Output Arrangements (mono->stereo):

host -> plug-in: setBusArrangements (stereoIN, stereoOUT)
plug-in return: kResultFalse
host -> plug-in: getBusArrangement (IN) => return Mono;
host -> plug-in: getBusArrangement (OUT) => return Stereo;
host -> plug-in: setBusArrangements (MonoIN, stereoOUT)
plug-in return: kResultOk
```

--------------------------------

### Create build directory and navigate into it

Source: https://steinbergmedia.github.io/vst3_dev_portal/pages/Tutorials/Building+the+examples/Building+the+examples+included+in+the+SDK+Linux.html

Creates a build folder and changes into it before generating the CMake project. Run these commands from the SDK root folder.

```c++
mkdir build
cd build
```

--------------------------------

### Clone and build the helloworld example

Source: https://steinbergmedia.github.io/vst3_dev_portal/pages/Tutorials/Creating+a+plug-in+with+VST+3+SDK+as+an+external+project.html

Commands to clone the vst3_example_plugin_hello_world repository, create a build directory, configure with CMake, and build the project. Run these in a command prompt.

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

--------------------------------

### GUID declaration and factory definition in AGain example

Source: https://steinbergmedia.github.io/vst3_dev_portal/pages/FAQ/Miscellaneous.html

Shows how to declare a FUID for the processor and use it in the factory definition. The GUID must be unique and is used to identify the plug-in.

```c++
static const FUID AGainProcessorUID (0x84E8DE5F, 0x92554F53, 0x96FAE413, 0x3C935A18);

BEGIN_FACTORY_DEF (stringCompanyName, stringCompanyWeb, stringCompanyEmail)
	//---First plug-in included in this factory-------
	// its kVstAudioEffectClass component
	DEF_CLASS2 (INLINE_UID_FROM_FUID(AGainProcessorUID),
                PClassInfo::kManyInstances,	// cardinality
				kVstAudioEffectClass,	// the component category
				stringPluginName,		// here the plug-in name
				Vst::kDistributable,
				AGainVST3Category,		// Subcategory
				FULL_VERSION_STR,		// Plug-in version
				kVstVersionString,		// the VST 3 SDK version
				Steinberg::Vst::AGain::createInstance)
    //...
```

--------------------------------

### IProgress::start

Source: https://steinbergmedia.github.io/vst3_dev_portal/pages/Technical+Documentation/Change+History/3.7.0/IProgress.html

Starts a progress display for a background task. The plug-in calls this method on the host's IProgress interface to request the host to visualize a progress indicator for a task that takes time.

```APIDOC
## [CALL] IProgress::start

### Description
Starts a progress display for a background task. The plug-in calls this method on the host's IProgress interface to request the host to visualize a progress indicator for a task that takes time.

### Method
start

### Parameters
- **type** (ProgressType) - Required - The type of progress (e.g., UIBackgroundTask)
- **title** (string) - Required - A description of the task (e.g., "Load Samples...")
- **id** (IProgress::ID&) - Required - A reference to store the progress ID for later updates

### Request Example
```cpp
if (auto progress = Steinberg::U::cast<IProgress> (componentHandler))
    progress->start (IProgress::ProgressType::UIBackgroundTask, STR ("Load Samples..."), mProgressID);
```

### Response
No return value.
```

--------------------------------

### Symmetric Input-Output Arrangements Example

Source: https://steinbergmedia.github.io/vst3_dev_portal/pages/Technical+Documentation/Change+History/3.0.0/Multiple+Dynamic+IO.html

Shows the host negotiation sequence when a plug-in only supports symmetric input-output arrangements. The host first proposes a configuration; if rejected, it queries the plug-in's preferred arrangement and applies it.

```c++
// Example of a Plug-in supporting only symmetric Input-Output Arrangements:

host -> plug-in: setBusArrangements (monoIN, stereoOUT)
plug-in return: kResultFalse
host -> plug-in: getBusArrangement (IN) => return Stereo;
host -> plug-in: getBusArrangement (OUT) => return Stereo;
host -> plug-in: setBusArrangements (stereoIN, stereoOUT)
plug-in return: kResultOk
```

--------------------------------

### Host implementation: Query and use parameter function name

Source: https://steinbergmedia.github.io/vst3_dev_portal/pages/Technical+Documentation/Change+History/3.7.0/IParameterFunctionName.html

Shows how a host retrieves a parameter ID from the function name, gets its normalized value, and converts it to plain value (e.g., -6 dB). The paramID can be cached for performance.

```c++
if (auto functionName = Steinberg::U::cast<Vst::IParameterFunctionName> (mEditController->getIEditController ())
{
    Vst::ParamID paramID;
    if (functionName->getParameterIDFromFunctionName (Vst::FunctionNameType::kCompGainReduction, paramID) == kResultTrue)
    {
        // paramID could be cached for performance issue
        Vst::ParamValue norm = mEditController->getIEditController ()->getParamNormalized (paramID);
        Vst::ParamValue plain = mEditController->getIEditController ()->normalizedParamToPlain (paramID, norm);
        // plain is something like -6 (-6dB)
    }
}
```

--------------------------------

### Get current systemTime via IComponentHandlerSystemTime

Source: https://steinbergmedia.github.io/vst3_dev_portal/pages/Technical+Documentation/Change+History/3.7.9/IComponentHandlerSystemTime.html

Use this snippet in an edit controller to query the current system time from the host. It casts the component handler to IComponentHandlerSystemTime and calls getSystemTime, storing the result in a local int64 variable. The returned time is not compensated, unlike ProcessContext::systemTime.

```c++
//--------------------------------------
// we are in the editcontroller:
  
int64 systemTime = 0;

if (auto handlerSystemTime = Steinberg::U::cast<IComponentHandlerSystemTime> (componentHandler))
    handlerSystemTime->getSystemTime (systemTime);
```

--------------------------------

### Build the plug-in with make or CMake

Source: https://steinbergmedia.github.io/vst3_dev_portal/pages/Tutorials/Building+the+examples/Building+the+examples+included+in+the+SDK+Linux.html

Builds the plug-in. The first command uses make; the second (commented as an alternative for release) uses CMake's build command with the Release configuration.

```c++
make
(or alternatively, for example, for release)

cmake --build . --config Release
```

--------------------------------

### Call IProgress from the plug-in side

Source: https://steinbergmedia.github.io/vst3_dev_portal/pages/Technical+Documentation/Change+History/3.7.0/IProgress.html

Shows how an edit controller uses Vst::IProgress to start, update, and finish a progress task. Requires a member IProgress::ID mProgressID and uses Steinberg::U::cast<IProgress> on the componentHandler. The host can unload the plug-in during progress, so the plug-in must support that.

```cpp
//--------------------------------------
// we are in the editcontroller:
// as member: IProgress::ID mProgressID;
  
if (auto progress = Steinberg::U::cast<IProgress> (componentHandler))
    progress->start (IProgress::ProgressType::UIBackgroundTask, STR ("Load Samples..."), mProgressID);
  
// ...
myProgressValue += incProgressStep;
if (auto progress = Steinberg::U::cast<IProgress> (componentHandler))
    progress->update (mProgressID, myProgressValue);
  
// ...
if (auto progress = Steinberg::U::cast<IProgress> (componentHandler))
    progress->finish (mProgressID);
```

--------------------------------

### TestRemapParamIDController header (controller.h) - IRemapParamID implementation

Source: https://steinbergmedia.github.io/vst3_dev_portal/pages/Technical+Documentation/Change+History/3.7.11/IRemapParamID.html

Declares a controller class that implements IRemapParamID and overrides getCompatibleParamID and setComponentState. The DEFINE_INTERFACES block registers the IRemapParamID interface. This header is part of the example for remapping parameter IDs when replacing another plug-in.

```c++
//------------------------------------------------------------------------
class TestRemapParamIDController : public EditController, public IRemapParamID
{
public:
    //...
    //--- from IRemapParamID ---------------------------------------------
    tresult PLUGIN_API getCompatibleParamID (const TUID pluginToReplaceUID /*in*/,
                                         Vst::ParamID oldParamID /*in*/,
                                         Vst::ParamID& newParamID /*out*/) override;

    //--- from EditController --------------------------------------------
	tresult PLUGIN_API setComponentState (IBStream* state) override;

    //---Interface---------
    DEFINE_INTERFACES
    	DEF_INTERFACE (IRemapParamID)
    END_DEFINE_INTERFACES (EditController)
    DELEGATE_REFCOUNT (EditController)
    //... 
};
```

--------------------------------

### Build the plug-in with msbuild or cmake

Source: https://steinbergmedia.github.io/vst3_dev_portal/pages/Tutorials/Building+the+examples/Building+the+examples+included+in+the+SDK+Windows.html

Builds the generated solution. The first command uses msbuild on vstsdk.sln; the second uses cmake --build for a Release configuration. You can also use Visual Studio to build.

```text
msbuild.exe vstsdk.sln
```

```text
cmake --build . --config Release
```

--------------------------------

### Symmetric Arrangements with Side-chain Following Main Input Example

Source: https://steinbergmedia.github.io/vst3_dev_portal/pages/Technical+Documentation/Change+History/3.0.0/Multiple+Dynamic+IO.html

Shows the negotiation sequence for a plug-in that supports symmetric input-output arrangements and requires the side-chain input to follow the main input arrangement. The initial proposal fails because the side-chain is mono, then the plug-in requests a stereo side-chain.

```c++
// Example of a Plug-in supporting only symmetric Input-Output Arrangements and Side-chain Input following the Main Input Arrangement:

host -> plug-in: getBusArrangements (IN) => Input Main:Mono / Input Side-chain:Mono
host -> plug-in: getBusArrangements (OUT) => Output: mono
host -> plug-in: setBusArrangements (Input Main:stereo / Input Side-chain:Mono, Output: stereo)
plug-in return: kResultFalse // because we want the same arrangement for Input Main and Side-chain
host -> plug-in: getBusArrangement (IN) => return Input Main:stereo / Input Side-chain:stereo;
host -> plug-in: getBusArrangement (OUT) => return Stereo;
host -> plug-in: setBusArrangements (Input Main:stereo / Input Side-chain:stereo, Output: stereo)
plug-in return: kResultOk
```

--------------------------------

### Implement getPrefetchableSupport for IPrefetchableSupport

Source: https://steinbergmedia.github.io/vst3_dev_portal/pages/Technical+Documentation/Change+History/3.6.5/IPrefetchableSupport.html

Example implementation of the Vst::IPrefetchableSupport interface method getPrefetchableSupport. It sets the prefetchable state based on an internal mode variable, returning kResultOk. The plug-in implements this interface to dynamically change between prefetchable or not; without it, the host decides the processing mode.

```c++
//------------------------------------------------------------------------
tresult PLUGIN_API myPlug::getPrefetchableSupport (PrefetchableSupport& prefetchable)
{
    prefetchable = kIsNeverPrefetchable;
 
    switch (myPrefetchableMode)
    {
        case 0: prefetchable = kIsNeverPrefetchable; break;
        case 1: prefetchable = kIsYetPrefetchable; break;
        case 2: prefetchable = kIsNotYetPrefetchable; break;
    }
    return kResultOk;
}
```

--------------------------------

### Start Playback with ITransportControl in mycontroller.cpp

Source: https://steinbergmedia.github.io/vst3_dev_portal/pages/Technical+Documentation/Change+History/3.8.1/ITransportControl.html

Use this C++ code to request playback start from the host via the Vst::ITransportControl interface. It checks for a valid host context, queries the interface, verifies the action is supported, and then requests the action. All calls must be made from the UI thread.

```c++
bool mycontroller::startPlayback ()
{
    // the hostContext was given in the function ComponentBase::initialize (FUnknown* context)
    if (!hostContext)
        return false;

    Vst::ITransportControl* transportControl = nullptr;
    hostContext->queryInterface (Vst::ITransportControl::iid, (void**)&transportControl);

	if (transportControl && transportControl->isActionSupported (Vst::ITransportControl::PlaybackStart) == kResultTrue)
	{
        transportControl->requestAction (Vst::ITransportControl::PlaybackStart);
        return true;
    }
    return false;
}
```

--------------------------------

### TestRemapParamIDController implementation (controller.cpp) - getCompatibleParamID and setComponentState

Source: https://steinbergmedia.github.io/vst3_dev_portal/pages/Technical+Documentation/Change+History/3.7.11/IRemapParamID.html

Implements getCompatibleParamID to map old parameter IDs from the AGain plug-in to new ParamIDs, returning kResultTrue only when a mapping occurs. Also implements setComponentState to call componentHandler->restartComponent(kParamIDMappingChanged) when remapping is needed. This is the second part of the example, paired with the header.

```c++
//------------------------------------------------------------------------
tresult PLUGIN_API TestRemapParamIDController::getCompatibleParamID (const TUID pluginToReplaceUID,
                                                                     Vst::ParamID oldParamID,
                                                                     Vst::ParamID& newParamID)
{
	//--- We want to replace the AGain plug-in-------
	//--- check if the host is asking for remapping parameter of the AGain plug-in
	static const FUID AGainProcessorUID (0x84E8DE5F, 0x92554F53, 0x96FAE413, 0x3C935A18);
	FUID uidToCheck (FUID::fromTUID (pluginToReplaceUID));
	if (AGainProcessorUID != uidToCheck)
		return kResultFalse;

	//--- host wants to remap from AGain------------
	newParamID = -1;
	switch (oldParamID)
	{
		//--- map the kGainId (0) to our param kMyGainParamTag
		case 0:
		{
			newParamID = kMyGainParamTag;
			break;
		}
	}
	//--- return kResultTrue if the mapping happens------------
	return (newParamID == -1) ? kResultFalse : kResultTrue;
}

//------------------------------------------------------------------------
tresult PLUGIN_API TestRemapParamIDController::setComponentState (IBStream* state)
{
	//...
    IBStreamer streamer (state, kLittleEndian);

    // Read the state

    bool remapNeeded = false;
    // here if we decode that the state was from an older plug-in
    //...

    // then restartComponent
    if (remapNeeded)
        componentHandler->restartComponent (kParamIDMappingChanged);

    return kResultOk;
}
```

--------------------------------

### Generate Xcode project with CMake

Source: https://steinbergmedia.github.io/vst3_dev_portal/pages/Tutorials/Building+the+examples/Building+the+examples+included+in+the+SDK+macOS.html

Generates an Xcode project from the VST SDK source using the -GXcode flag.

```c++
cmake -GXcode ../vst3sdk
```

--------------------------------

### Symmetric Arrangements with Mono Side-chain Input Example

Source: https://steinbergmedia.github.io/vst3_dev_portal/pages/Technical+Documentation/Change+History/3.0.0/Multiple+Dynamic+IO.html

Shows two possible negotiation sequences for a plug-in that supports symmetric input-output arrangements and requires a mono side-chain input. The first sequence succeeds, the second fails because the side-chain is stereo.

```c++
// Example of a Plug-in supporting only symmetric Input-Output Arrangements and Side-chain Input always mono:

host -> plug-in: getBusArrangements (IN) => Input Main:Mono / Input Side-chain:Mono
host -> plug-in: getBusArrangements (OUT) => Output: mono
host -> plug-in: setBusArrangements (Input Main:stereo / Input Side-chain:Mono, Output: stereo)
plug-in return: kResultTrue

or
host -> plug-in: getBusArrangements (IN) => Input Main:Mono / Input Side-chain:Mono
host -> plug-in: getBusArrangements (OUT) => Output: mono
host -> plug-in: setBusArrangements (Input Main:stereo / Input Side-chain:stereo, Output: stereo)
plug-in return: kResultFalse // because we want mono for Side-chain
host -> plug-in: getBusArrangement (IN) => return Input Main:stereo / Input Side-chain:mono;
host -> plug-in: getBusArrangement (OUT) => return Stereo;
host -> plug-in: setBusArrangements (Input Main:stereo / Input Side-chain:mono, Output: stereo)
plug-in return: kResultOk
```

--------------------------------

### Load VST Module on Windows using LoadLibrary and GetProcAddress

Source: https://steinbergmedia.github.io/vst3_dev_portal/pages/Technical+Documentation/VST+Module+Architecture/Loading.html

Basic Windows implementation showing how to load a VST-MA plug-in library and retrieve pointers to exported functions. The InitDll and ExitDll entry functions are optional on Windows but not on macOS and Linux. The code iterates over factory classes, creates instances, and releases resources.

```cpp
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::IAudioProcessor::setProcessing

Source: https://steinbergmedia.github.io/vst3_dev_portal/pages/Technical+Documentation/API+Documentation/Index.html

Signals the start or stop of processing. The host calls this before the first process call and after the last one.

```APIDOC
## [C++] Vst::IAudioProcessor::setProcessing

### Description
Signals the start or stop of processing. The host calls this before the first process call and after the last one. When set to true, the plug-in must reset its internal processing state (e.g., clear delay buffers).

### Method
C++ method

### Endpoint
Vst::IAudioProcessor::setProcessing

### Parameters
- **state** (TBool) - Required - true to start processing, false to stop.

### Response
- **tresult** - Returns kResultTrue on success, kResultFalse on failure.
```

--------------------------------

### Vst::IAudioProcessor::setupProcessing

Source: https://steinbergmedia.github.io/vst3_dev_portal/pages/Technical+Documentation/API+Documentation/Index.html

Informs the processor about the processing setup, including the maximum block size. This is called when the processor is inactive.

```APIDOC
## [C++] Vst::IAudioProcessor::setupProcessing

### Description
Informs the processor about the processing setup, including the maximum block size. This is called when the processor is inactive and before processing starts.

### Method
C++ method

### Endpoint
Vst::IAudioProcessor::setupProcessing

### Parameters
- **setup** (ProcessSetup) - Required - The process setup containing the maximum samples per block and sample rate.

### Response
- **tresult** - Returns kResultTrue on success, kResultFalse on failure.
```
Tokens:
Raw