Classes (extension) | UGens > FX

VSTPlugin : MultiOutUGen : UGen : AbstractFunction : Object

load VST plugins as UGens
Source: VSTPlugin.sc


This UGen represents a single VST plugin instance on the Server. See the helpfile of VSTPluginController for how to control it from the SuperCollider language.

VSTPlugin also has class methods to scan a Server for plugins and cache the info in the Client, see Plugin Management.

Class Methods

VSTPlugin.ar(input, numOut: 1, bypass: 0, params, id, info, blockSize)

create a UGen instance.

NOTE: The method signature has changed in v0.5!



The UGen inputs for the plugin to process.

Possible types:

  • a single UGen (= mono)

  • an Array of UGens (= stereo/multichannel)

  • nil (= no input, e.g. VST instruments).
  • an Array Ref (= multi-bus, see below)

Multiple input busses

Some VST3 plugins have multiple input busses. If you pass an Array of UGens, they will be automatically distributed over several busses.


Alternatively, you can pass a Ref to an Array of inputs. This allows you to pick a subset of channels for each bus. Also, you can skip a bus with 0 or nil.

NOTE: You can check the available input busses with VSTPluginDesc: -inputs.

The number of output channels.

In the simple case, this is a fixed number greater than 0.

The result is either a single OutputProxy (mono) or an Array of OutputProxies (stereo/multichannel), just like a regular MultiOutUGen.

Multiple output busses

If the plugin has multiple output busses, the UGen outputs will be automatically distributed over several busses.


Alternatively, you can pass a Ref to an Array of channel numbers. This allows you to pick a subset of channels for each bus. Also, you can skip a bus with 0 or nil.

The result is an Array of output busses, where each bus is an Array of OutputProxy.

NOTE: Skipped output busses are omitted from the Array!
NOTE: You can check the available output busses with VSTPluginDesc: -outputs.

change the bypass state. If bypass is non-zero, then processing is suspended and each input is passed straight to its corresponding output.

0off (processing)
1hard 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.
2soft bypass; if the plugin has a tail (e.g. reverb or delay), it will fade out. This doesn't call the plugin's bypass method, so we can always do a nice crossfade.

An optional Array of parameter controls in pairs of index and value. Both can be automated.

You can set the index to a negative value to "unmap" the parameter.

NOTE: params overrides any automation of the same parameters by VSTPluginController: -set, but it can itself be overriden with VSTPluginController: -map.

You can automate parameters with either control and audio rate UGens, but the latter is more CPU expensive and only makes sense if the plugin actually supports sample accurate automation (some, but not all VST3 plugins).


A Symbol which uniquely identifies the UGen within the SynthDef, so it can be found by VSTPluginController.

NOTE: If this is the only VSTPlugin instance in the SynthDef, the id argument can be omitted.

An optional VSTPluginDesc instance; the plugin must have been successfully probed (e.g. with VSTPlugin: *search).

Alternatively, you can provide a plugin key as a Symbol, in which case the VSTPluginDesc will be taken from the default Server's plugin dictionary.

If you know in advance which VST plugin you want to load, this allows you to use parameter names instead of indices

Also, you can omit the path argument when opening plugins:


Run the plugin with a certain block size (in samples). The default is nil (= no reblocking).

Some plugins run more efficiently with larger blocksizes. (This is generally true for bridged/sandboxed plugins.) Instead of globally changing the Server block size, you can selectively reblock VSTPlugin instances.

NOTE: Reblocking causes a delay of N - M samples, where N is the desired block size and M is the Server block size.

Plugin Management

All VST plugin information is cached in the Client. This is done mainly for performance reasons but it can be also handy for end users because it's possible to investigate plugins without actually creating any instances.

The plugin info is stored as a VSTPluginDesc instance under its key (see VSTPluginDesc: -key) and can be retrieved with *plugins.


get information about (probed) VST plugins on a Server.



the Server. If this is nil, the default Server is assumed.


an IdentityDictionary containing the descriptions of all VST plugins on the Server as instances of VSTPluginDesc.


The dictionary can be simply indexed with plugin keys (see VSTPluginDesc: -key).

VSTPlugin.pluginList(server, sorted: false)

get all available plugins on a Server.



the Server. If nil, the default Server is assumed.


whether the Array should be sorted alphabetically (by name).


an Array of VSTPluginDesc instances.


get the keys of all plugins on a given Server.



the Server. If nil, the default Server is assumed.


an Array of plugin keys.


This method only considers the keys stored in the plugin descriptions, not the additional keys in the plugin dictionary.


post all available plugins.



the Server. If nil, the default Server is assumed.


The plugins are posted in alphabetical order in the following format:

key (vendor) [path]

Searching for plugins

VSTPlugin.search(server, dir, options, verbose: true, wait: -1, action)

Scan a local or remote Server for VST plugins and cache the info in the Client.

NOTE: The method signature has changed in v0.5!



The server to scan for plugins. If nil, the default Server is used.


an (optional) Array of custom plugin directories.

If nil, the standard VST search paths are used:

VST 2.x
  • %ProgramFiles%\VSTPlugins
  • %ProgramFiles%\Steinberg\VSTPlugins
  • %ProgramFiles%\Common Files\VST2
  • %ProgramFiles%\Common Files\Steinberg\VST2

  • ~/Library/Audio/Plug-Ins/VST
  • /Library/Audio/Plug-Ins/VST

  • ~/.vst
  • /usr/local/lib/vst
  • /usr/lib/vst

VST 3.x
  • %ProgramFiles%\Common Files\VST3

  • ~/Library/Audio/Plug-Ins/VST3
  • /Library/Audio/Plug-Ins/VST3

  • ~/.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.

an (optional) Event with advanced search options.

  • \save (Boolean)

    write results to the cache file (default: true).

  • \parallel (Boolean)

    probe plugins in parallel (default: true).

    This can be significantly faster, but it can also make your computer almost unresponsive for the duration of the search because of the full CPU utilization.

  • \timeout (Float)

    the number of seconds to wait for a single plugin before it is regarded as being stuck and ignored; default is nil (= no timeout).

  • \exclude (Array)

    a list of directories or files to exclude from the search.



post a message for each found plugin.

The message contains the file path, name and probe result ("ok" or error message).


The wait time between OSC messages.

-1 allows an OSC roundtrip between packets.

0 is not safe with UDP, but is probably ok with TCP.

NOTE: This is only relevant for remote Servers (local Servers will send the plugin description via temp files).

a function to be called after the search has finished.


Directories are searched recursively. For each valid VST plugin, the information is stored in a dictionary on the Client and can be retrieved with its key (see Plugin Management).

If a plugin can't be probed ("... failed!") it either means it's not a valid VST plugin, dependencies are missing or it has the wrong CPU architecture (and can't be bridged).

A new search doesn't automatically clear the dictionary, but existing keys are overwritten. You can clear the dictionary explicitly with *clear.

For efficiency, search results are written to a cache file (on the Server's computer) to significantly speed up subsequent searches (cached plugins don't have to probed again). Many DAWs use a similar strategy. If you want to search directories without updating the cache, set save to false.

NOTE: The very first search in a directory usually takes a couple of seconds, but if you have many (heavy) plugins, the process can take significantly longer. However, subsequent searches will finish very quickly because the info has been cached.
WARNING: Shell plugins like "Waves" contain hundreds of (heavy) sub-plugins. On my machine, the very first search takes several minutes(!), so be patient :-)

VSTPlugin.searchMsg(dir, options, verbose: false, dest)



(see above)


(see above)


(see above)


a) nil: don't write search results (the default)

a) String: name of a temp file where the search results should be written to.

b) Buffer or bufnum: the plugin will fill the Buffer on the Server, the Client can then read the data (each float representing a single byte) and free the Buffer. The Buffer should be initially empty!


the message for a search command (see *search).


Sending the message to the Server will not update any info in the Client! Mostly useful for NRT synthesis.


Stop a running search.



the Server. If nil, the default Server is assumed.



the message for a stopSearch command (see *stopSearch).


get the descriptions of all locally cached plugins. For this to work, you have to call *search at least once (with save: true), then the plugin description will be available without starting a Server.


an IdentityDictionary containing all plugin descriptions as VSTPluginDesc instances.

VSTPlugin.clear(server, remove: true)

Deletes all cached plugin descriptions for a given Server.



the Server. If this is nil, the default Server is assumed.


whether you want to also remove the cache file.

VSTPlugin.clearMsg(remove: true)



(see above)


the message for a clear command (see *clear).


Sending the message to the Server will not clear the Client plugin dictionary!

Bridging and Sandboxing

Usually, you can only run plugins with the same CPU architecture as the host application.

Since VSTPlugin v0.4, however, it is possible to run 32-bit plugins on a 64-bit Server and vice versa! Such incompatible plugins will automatically run in a shared subprocess (= bit bridging), which incurs some CPU overhead.

Since VSTPlugin v0.5 it is also possible to run Windows plugins on Linux with Wine.

NOTE: Bridging/sandboxing can also be explictly enabled for native plugins, see the mode argument in VSTPluginController: -open.

For more information, see the Bridging/sandboxing section in the README.

Inherited class methods

Undocumented class methods




Instance Methods

Inherited instance methods

Undocumented instance methods


.desc = value


.id = value


.info = value



.synthIndex = index

From superclass: UGen