Page tree
Skip to end of metadata
Go to start of metadata

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".

Basic Conception

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


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.

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.

Initialize

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 is 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.

Creation and Initialize 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 to separate component from controller :-(
	if (processorComponent->queryInterface (Vst::IEditController::iid, (void**)&editController) != kResultTrue)
	{
		// editController is now created, we have the ownership, which means that we have to release it when not used anymore FUID controllerCID;

		// ask for the associated controller class ID (could be called before processorComponent->initialize ())
		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))
			{
				// initialize the component with our context
				res = (editController->initialize (gStandardPluginContext) == kResultOk);

				// now processorComponent and editController are initialized... :-)
			}
		}
	}
}
//------------------------------------------------------------------------

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.

Persistence

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

See also

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::getStateSteinberg::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
      When the processor is configured, it has to be activated. The activation call signals that all configurations have been finished. 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

  2. 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.

The Editing Part

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

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.

Private Communication

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


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 be created 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...:-)
}
Please note that you CANNOT rely on the implementation detail that the connection is done directly between the processor component and the edit controller!

On this page:

Related pages:

  • No labels