This document is meant for developers who want to interface with the VSTPlugin UGen from other programs or build their own client abstractions.

It describes the UGen structure (i.e. its inputs and outputs), the available OSC messages and the format in which larger data is exchanged between UGen and client(s).

Have a look at VSTPlugin.sc and VSTPluginController.sc in the classes folder for a reference implementation in Sclang.

UGen Structure

UGen inputs

name	rate
flags	ir	creation flags (reserved for future use)
blockSize	ir	desired block size or 0 (= Server block size)
bypass	ir/kr	bypass state
numInputs	ir	number of audio input busses; can be 0
inputBus...		(optional) <numInputs> audio input busses
numOutputs	ir	number of audio output busses; can be 0
outputBus...		(optional) <numOutputs> audio output busses
numParamCtls	ir	number of parameter controls; can be 0
paramCtl...		(optional) <numParamCtls> parameter controls

inputBus

The number of channels (ir), followed by the actual channel inputs (ar). Example: 2, <ch1>, <ch2>.

outputBus

The number of channels (ir).

paramCtl

A pair of <index, value>.

index is the index of the parameter to be automated. Supported rates are ir and kr. You can dynamically switch between different parameters at control rate. A negative number deactivates the control.

value is the new state for the given plugin parameter and should be a floating point number between 0.0 and 1.0. All rates are supported, but ir and kr are recommended. ar only makes sense for VST3 plugins - and only for those which actually support sample accurate automation (many VST3 plugins do not!).

NOTE: Automation via UGen inputs can be overriden by the /map and /mapa Unit commands (see below).

bypass

If a plugin is bypassed, processing is suspended and each input is passed straight to its corresponding output. The bypass parameter can have the following states:

• 0 -> off (processing)
• 1 -> hard bypass; processing is suspended immediately and the plugin's own bypass method is called (if available). Good plugins will do a short crossfade, others will cause a click. |
• 2 -> soft bypass; if the plugin has a tail (e.g. reverb or delay), it will fade out. Also, this doesn't call the plugin's bypass method, so we can always do a nice crossfade. |

---

Here is an example for a VSTPlugin instance with 2 input busses (2 and 1 channels), 2 output busses (2 and 1 channels) and 4 parameter controls:

0 0 <bypass> 2 2 <chn1> <chn2> 1 <chn1> 2 2 1 4 <index1> <value1> <index2> <value2> <index3> <value3> <index4> <value4>

UGen outputs

name	rate
outputBus...	ar	(optional) <numOutputs> output busses

Each outputBus contains one or more output channels; the number of channels is determined by the corresponding outputBus UGen input.

Realtime safety

VSTPlugin tries its best to be as realtime safe as possible. Plugins are always opened/closed asynchronously on the NRT resp. UI thread. Some Unit commands, like /reset or /program_read, offer two options via the async parameter:

2. async: true means that the plugin method is called on the NRT resp. UI thread and will never block the Server! However, plugin processing is temporarily suspended and the UGen will not accept other messages until the command has finished.

3. async: false means that the plugin method is simply called on the RT thread. Depending on the plugin, this might be just fine - or block the server. You have to test yourself! The advantage is that the action is performed synchronously and plugin processing doesn't have to be suspended.

NOTE: If the plugin is opened with the GUI editor, the async option is automatically set to true out of thread safety concerns.

OSC interface

Abbreviations for OSC data types:

name	type
int	32 bit integer
float	32 bit float
string	string
bytes	binary blob

Plugin commands

Plugin commands can be called without any UGen instance and take the following form:

/cmd <string>cmdName (arguments)...

/vst_search

Search for VST plugins.

Arguments:

type
int	a bitset of options (see below)
int/string	where to write the search results; either a buffer number or a file path; -1 means don't write results.
float	timeout (the time to wait for each plugin before it is regarded as stuck and ignored); 0.0 means no timeout.
int	the number of user supplied search paths; 0 means none.
string...	(optional) list of user supplied search paths
int	the number of exclude paths; 0 means none
string...	(optional) list of user supplied exclude paths
string	(optional) custom cache file directory

This will search the given paths recursively for VST plugins, probe them, and write the results to a file or buffer. Valid plugins are stored in a server-side plugin dictionary. If no plugin could be found, the buffer or file will be empty.

The following options can be combined with a bitwise OR operation:

value
0x1	verbose (print plugin paths and probe results)
0x2	write search results to cache file.
0x4	probe in parallel (faster, but might cause audio dropouts because of full CPU utilization)

If there are no user supplied search paths, the standard VST search paths are used instead:

• VST 2.x
  • Windows
    • %ProgramFiles%\VSTPlugins
    • %ProgramFiles%\Steinberg\VSTPlugins
    • %ProgramFiles%\Common Files\VST2
    • %ProgramFiles%\Common Files\Steinberg\VST2
  • macOS
    • ~/Library/Audio/Plug-Ins/VST
    • /Library/Audio/Plug-Ins/VST
  • Linux
    • ~/.vst
    • /usr/local/lib/vst
    • /usr/lib/vst
• VST 3.x
  • Windows
    • %ProgramFiles%\Common Files\VST3
  • macOS
    • ~/Library/Audio/Plug-Ins/VST3
    • /Library/Audio/Plug-Ins/VST3
  • Linux
    • ~/.vst3
    • /usr/local/lib/vst3
    • /usr/lib/vst3

NOTE: Here, %ProgramFiles% stands for "C:\Program Files" on a 64 bit Server and "C:\Program Files (x86)" on a 32 bit Server.

/vst_search_stop

Stop a running search. (No arguments)

/vst_query

Try to obtain a plugin description from the plugin cache.

Arguments:

type
string	plugin path/key (absolute or relative)
int/string	where to write the result; either a buffer number or a file path. -1 means don't write results.

If the plugin is not contained in the plugin cache, it is searched in the standard VST search paths and probed in a seperate process (so that bad plugins don't crash the server). On success, the plugin information is written to a file or buffer and the plugin is stored in a server-side plugin dictionary; on fail, nothing is written.

For VST 2.x plugins, you can omit the file extension. Relative paths are resolved recursively based on the standard VST directories.

The probe process can return one of the following results:

• ok -> probe succeeded
• failed -> couldn't load the plugin; possible reasons: a) not a VST plugin, b) wrong architecture, c) missing dependencies
• crashed -> the plugin crashed on initialization
• error -> internal failure

/vst_cache_read

Read the cache file from a custom location.

Arguments:

type
string	the cache file directory

/vst_clear

Clear the server-side plugin dictionary.

Arguments:

type
int	remove cache file; 1 = yes, 0 = no

/dsp_threads

Set the number of DSP threads for multi-threaded plugin processing. (By default, this is the number of logical CPUs.)

NOTE: This command only takes effect if it is sent before any (multi-threaded) plugins have been opened.

Arguments:

type
int	number of threads; 0 = default

Plugin key

Plugins are stored in a server-side plugin dictionary under its key. For VST 2.x plugins, the key is simply the plugin name; for VST 3.x plugins, the key is the plugin name plus ".vst3" extension.

If a VST2 and VST3 module contains a single plugin (as is the case with most VST2 and VST3 plugins), it can also be referenced by its file path. Since VST2 shell plugins and VST3 plugin factories contain multiple plugins in a single module, each plugin can only be referenced by its key.

On big advantage of plugin keys over file paths is that the latter can vary across systems and architectures, whereas the former is always the same!

Unit commands

Unit commands are used to control a specific UGen instance and take the following form:

/u_cmd <int>nodeID <int>synthIndex <string>cmdName (arguments)...

/open

Open a new VST plugin. This method is always asynchronous.

Arguments:

type
string	plugin key or path.
int	request VST GUI editor; 1 = yes, 0 = no
int	request multithreading; 1 = yes, 0 = no
int	mode; 0 = normal, 1 = sandbox (dedicated process), 2 = bridge (shared process)

Replies with

/vst_open
int	node ID
int	synth index
float	1.0 = success, 0.0 = fail
float	VST GUI editor; 1.0 = yes, 0.0 = no
float	initial latency in samples

/close

Close the current VST plugin.

No Arguments.

/vis

Show/hide the VST GUI editor (if enabled).

Arguments:

type
int	1 = show, 0 = hide

/pos

Set the position of the GUI editor.

Arguments:

type
int	x-coordinate
int	y-coordinate

/size

Resize the GUI editor. This only works for VST3 plugins with a resizable GUI.

Arguments:

type
int	width
int	height

/reset

Reset the VST plugin's internal state (e.g. clear delay lines).

Arguments:

type
int	asynchronous; 1 = true, 0 = false

NOTE: If the plugin is opened with the VST GUI editor, the command is always performed asynchronously and the async argument is ignored.

Parameters

/set

Set a plugin parameter to a new value.

Arguments:

type
int/string	parameter index or name
float/string	"normalized" float value between 0.0 and 0.1 or "plain" string representation. Depending on the plugin, the latter might only work for certain parameters - or not work at all.
...	(optional) additional pairs of <index>, <value>

Replies with /vst_param (see "Events" section).

You can automate several parameters at once, e.g. /u_cmd, <nodeID>, <synthIndex>, /set, 0, 0.5, 1, "12", "Wet", 0.7 will set parameters 0, 1 and "Wet".

NOTE: /set will automatically unmap the corresponding parameter(s) from any audio/control busses, see /unmap.

/setn

Like /set, but with a range of subsequent parameters.

Arguments:

type
int/string	name or index of start parameter
int	number of parameters
float/string ...	parameter values

/get

Get a single plugin parameter value.

Arguments:

type
int/string	parameter index or name

Replies with:

/vst_set
int	node ID
int	synth index
float	parameter index
float	normalized parameter value

/getn

Get a range of plugin parameter values.

Arguments:

type
int/string	parameter index or name
int	number of subsequent parameters (-1: till the end)

Replies with:

/vst_set
int	node ID
int	synth index
float	parameter start index
float	number of parameters
float ...	normalized parameter values

To get all parameter values, you can do /u_cmd, <nodeID>, <synthIndex>, /getn, 0, -1.

/param_query

Query parameter states.

Arguments:

type
int	start parameter index
int	number of parameters

Replies with a series of /vst_param messages (see "Events" section). Use this instead of /getn, if you also need the string representation, e.g. to update your client GUI after loading a new plugin, switching programs or loading a preset file.

/map

Map a subsequent range of parameters to control bus channels.

Arguments:

type
int/string	name or index of parameter
int	control bus start index
int	number of channels

For example, /u_cmd, <nodeID>, <synthIndex>, /map, 5, 4, 1 will map parameter 5 to control bus 4. /u_cmd, <nodeID>, <synthIndex>, /map, 5, 4, 2 will map parameter 5 to control bus 4 and also parameter 6 to control bus 5.

/mapa

Map a subsequent range of parameters to audio bus channels.

Arguments:

type
int/string	name or index of parameter
int	audio bus start index
int	number of channels

NOTE: Mapping a parameter to a audio/control bus has higher precedence than UGen input parameter controls (see "UGen inputs" section).

/unmap

Unmap parameters from audio/control busses.

Arguments:

type
int/string ...	names or indices of parameters to unmap. If omitted, all parameters are unmapped.

NOTE: /set will automatically unmap the corresponding parameter(s) from any audio/control busses!

Preset management

/program_set

Select program from program list.

Arguments:

type
int	program index

/program_name

Change the current program name.

Arguments:

type
string	new program name

Replies with /vst_program, see "Events" section.

/program_read

Read a VST program from a file or sound buffer.

Arguments:

type
int/string	buffer number of file path, see "Data transfer" section.
int	asynchronous; 1 = yes, 0 = no

Replies with:

/vst_program_read
int	node ID
int	synth index
float	1.0 = success, 0.0 = fail

Also sends /vst_program (see "Event" section).

/bank_read

Read a preset bank from a file or buffer.

Arguments:

type
int/string	buffer number of file path, see "Data transfer" section.
int	asynchronous; 1 = yes, 0 = no

Replies with:

/vst_bank_read
int	node ID
int	synth index
float	1.0 = success, 0.0 = fail

Also sends /vst_program and /vst_program_index (see "Events" section).

/program_write

Write a preset program to a file or buffer.

Arguments:

type
int/string	buffer number of file path, see "Data transfer" section.
int	asynchronous; 1 = yes, 0 = no

Replies with:

/vst_program_write
int	node ID
int	synth index
float	1.0 = success, 0.0 = fail

/bank_write

Write a preset bank to a file or buffer.

Arguments:

type
int/string	buffer number of file path, see "Data transfer" section.
int	asynchronous; 1 = yes, 0 = no

Replies with:

/vst_bank_write
int	node ID
int	synth index
float	1.0 = success, 0.0 = fail

/program_query

Query program names.

Arguments:

type
int	start program index
int	number of programs

Replies with a series of /vst_program messages (see "Event" section). For example, you can use this to update the program list in your client after loading a new plugin or reading a preset bank.

MIDI

/midi_msg

Send a MIDI message.

Arguments:

type
bytes	MIDI message (1-3) bytes
float	(optional) detune in cent

The optional detune argument allows to detune a single note-on or note-off message; this feature is not part of the MIDI standard and only a few VST plugins suppport it.

/midi_sysex

Send a SysEx message.

type
bytes	SysEx message

Timing and transport

/tempo

Set the tempo.

Arguments:

type
float	BPM (beats per minute)

/time_sig

Setthe time signature.

Arguments:

type
int	numerator
int	denominator

/transport_play

Set the transport state.

Arguments:

type
int	1 = play, 0 = stop

/transport_set

Set the transport position.

Arguments:

type
float	transport position in beats.

/transport_get

Get the current transport position.

Replies with:

/vst_transport
int	node ID
int	synth index
float	position in beats

VST 2.x

NOTE: The following methods only work for VST 2.x plugins and are meant for expert users. Please check the VST 2.x SDK for more information.

/can_do

Ask the plugin if it can do something.

Arguments:

type
string	what

Replies with:

/vst_can_do
int	node ID
int	synth index
float	1.0 = yes, -1.0 = no, 0.0 = don't know

/vendor_method

Call a vendor specific method.

Arguments:

type
int	index
int	value
int	ptr
int	opt
int	asynchronous; 1 = yes, 0 = no

Replies with:

/vst_vendor_method
int	node ID
int	synth index
float	result

Events

The VSTPlugin UGen may send the following events as Node reply messages:

/vst_param

A parameter has changed state.

Arguments:

type
int	node ID
int	synth index
float	parameter index
float	normalized parameter value
float ...	"plain" string representation, see "String encoding" section.

/vst_param messages are sent after /set, /setn, /param_query or when automating parameters in the VST GUI editor. They are not sent when parameters are automated via UGen input parameter controls (see "UGen inputs" section) or audio/control bus mappings (see /map), because this would lead to excessive OSC traffic.

NOTE: A single parameter change might produce several /vst_param messages, e.g. in the case of linked parameters.

/vst_program

A program name has changed.

Arguments:

type
int	node ID
int	synth index
float	program index
float ...	program name, see "String encoding" section.

This message is sent after /program_name, /program_read or /bank_read.

/vst_program_index

The current program index has changed.

Arguments:

type
int	node ID
int	synth index
float	program index

This message is sent after /program_set and /bank_read.

/vst_auto

A parameter has been automated in the VST GUI editor.

Arguments:

type
int	node ID
int	synth index
float	parameter index
float	normalized parameter value

This message is always sent together with /vst_param.

/vst_latency

The plugin's processing latency has changed. This includes the additional latency caused by multithreading (see /open).

Arguments:

type
int	node ID
int	synth index
float	latency in samples

/vst_midi

The plugin has sent a MIDI message.

Arguments:

type
int	node ID
int	synth index
float ...	MIDI message (one float per byte)

/vst_sysex

The plugin has sent a SysEx message.

Arguments:

type
int	node ID
int	synth index
float ...	SysEx message (one float per byte)

/vst_update

Multiple parameters have changed internally, e.g. because the user loaded a preset in the plugin UI.

Arguments:

type
int	node ID
int	synth index

/vst_crash

The plugin has crashed. Naturally, this message can only be sent if the plugin has been bridged or sandboxed.

Arguments:

type
int	node ID
int	synth index

String encoding

Because of limitations in the SuperCollider plugin API, Node reply messages can only contain float arguments. Our solution is to encode string arguments as a list of bytes with a length prefix ("Pascal strings"), where each byte takes up a single float.

For example, the string "Dry" is encoded as 3.0, 44.0, 72.0, 79.0.

Data transfer

To reliably exchange larger data sets between server and clients, you can use temp files or sound buffers. For locals servers, temp files should be preferred. For remote servers, you have to use sound buffers (unless you can use FTP :-). Usually, client frameworks already have abstractions to (more or less) reliably stream data from/to sound buffers.

Files are always read and written in binary. In case of sound buffers, each float corresponds to a single byte.

Whenever VSTPlugin writes data to a sound buffer, it will allocate the data for you, but because of limitations in the SuperCollider plugin API, it can't safely deallocate a sound buffer. There are two consequences:

• Whenever you ask VSTPlugin to write data, make sure that the target sound buffer is empty!
• Whenever you ask VSTPlugin to read data, it's your job to free the sound buffer after the command has finished.

VSTPlugin uses a custom format similar to .ini files to exchange plugin description data between server and clients. It is also used in the plugin cache file.

Plugin info

This is the structure of a single plugin description, as used by /vst_query:

[plugin]
id=<unique ID string>
path=<file path>
name=<plugin name>
vendor=<vendor name>
category=<category name>
version=<plugin version string>
sdkversion=<VST SDK version string>
flags=<bitset>
pgmchange=<program change parameter index in hex> (optional)
bypass=<bypass parameter index in hex> (optional)
[inputs]
n=<input bus count>
<channel count #0>, <type #0>, <name #0>
<channel count #1>, <type #1>, <name #1>
...
<channel count #N-1>, <type #N-1>, <name #N-1>
[outputs]
n=<output bus count>
<channel count #0>, <type #0>, <name #0>
<channel count #1>, <type #1>, <name #1>
...
<channel count #N-1>, <type #N-1>, <name #N-1>
[parameters]
n=<parameter count>
<name #0>, <label #0>, <ID #0>, <flags #0>
<name #1>, <label #1>, <ID #1> <flags #1>
...
<name #N-1>, <label #N-1>, <ID #N-1>, <flags #N-1>
[programs]
n=<program count>
<name #0>
<name #1>
...
<name #N-1>
[keys]
n=<number of keys>
<key #0>
<key #1>
...
<key #N-1>

String values, like plugin/parameter/program names, can contain any characters except newlines and commas (those are bashed to a replacement symbol by the UGen).

NOTE: do not rely on the order of entries in the [plugin] section! In the future we might add/insert more entries and possibly reorder them.

flags

flags is a bitset of boolean properties, written as a hexidecimal number. The following flags can be combined with a bitwise OR operation:

value
0x001	supports the GUI editor
0x002	is a VST instrument
0x004	supports single precision processing
0x008	supports double precision processing
0x010	has MIDI input
0x020	has MIDI output
0x040	has SysEx input
0x080	has SysEx output
0x100	is bridged

input/output busses

Each bus entry takes up a single line and consists of three fields, separated by a comma: <channel count>, <type>, <name>.

<type> can be either 0 (= main) or 1 (= aux). <name is always empty for VST2 plugins (because they only have a single input/output bus).

In the future we might add more fields.

parameters

Each parameter entry takes up a single line and consists of three fields, separated by a comma: <name>, <label>, <ID> <flags>.

<label> is the unit of measurement (e.g. "dB", "ms", "%"); it can be an empty string!

The parameter ID is a hexidecimal number. For VST 2.x plugins it is the same as the parameter index, but for VST 3.x plugins it can be an arbitrary 32 bit integer.

flags is a bitset of boolean properties, written as a hexidecimal number. The following flags can be combined with a bitwise OR operation:

value
0x01	is automatable

In the future we might add more fields.

programs

Every program consists of a single field, which is the program name.

NOTE: Program names can be empty strings; this means that empty lines after the [programs] section are significant and must not be ignored!

In the future we might add more fields.

---

Each plugin can be referred to by one or more keys. The primary key always comes first in the list.

EXAMPLE:

[plugin]
path=C:/Program Files/VSTPlugins/GVST/GChorus.dll
id=6779416F
name=GChorus
vendor=GVST
category=Effect
version=1200
sdkversion=VST 2.4
flags=10d
[inputs]
n=1
2,0,
[outputs]
n=1
2,0,
[parameters]
n=4
Depth,cents,0
Freq,Hz,1
R Phase,deg,2
Mix,%,3
[programs]
n=10
Subtle Insert
Wide Insert
Heavy Insert
Subtle Send
Wide Send
Heavy Send
Defaults
Defaults
Defaults
Defaults
[keys]
n=2
GChorus
C:/Program Files/VSTPlugins/GVST/GChorus.dll

Search results

This is used by /vst_search to transmit search results to the client. It has the following structure:

[plugins]
n=<number of plugins>
<plugin info #0>
<plugin info #1>
...
<plugin info #N-1>

Each <plugin info> entry has the same structure as in "Plugin info".

Plugin cache file

Probing lots of (large) VST plugins can be a slow process. To speed up subsequent searches, the search results can be written to a cache file (see /vst_search), which is located in a platform specific directory: %LOCALAPPDATA%\vstplugin\sc on Windows, ~/Library/Application Support/vstplugin/sc on macOS and $XDG_DATA_HOME/vstplugin/sc resp. ~/.local/share/vstplugin/sc on Linux. The cache file itself is named cache_<arch>.ini, so that cache files for different CPU architectures can co-exist.

The cache file structure is very similar to that in "Search results". The only difference is that it also contains a version header ([version]) and a plugin black-list ([ignore]).

[version]
<major>.<minor>.<patch>
[ignore]
n=<number of paths>
<path #0>
<path #1>
...
<path #N-1>
[plugins]
n=<number of plugins>
<plugin info #0>
<plugin info #1>
...
<plugin info #N-1>

Plugins are black-listed if the probe process failed (see /vst_query). If you want to replace a "bad" plugin with a "good" one, you have to first remove the cache file (see /vst_clear).