TITLE:: VSTPluginController
summary:: Client-side representation of a VSTPlugin UGen instance
categories:: Server>Abstractions
related:: Classes/VSTPlugin, Classes/VSTPluginDesc, Classes/VSTPluginGui, Classes/VSTPluginMIDIProxy, Guides/HOA_IEM

DESCRIPTION::

This class is used to control a specific link::Classes/VSTPlugin:: instance in a link::Classes/Synth::, so you can
open plugins, automate parameters, change programs, send MIDI messages, etc.

Have a look at the link::#Examples:: at the bottom!

Subsection:: Introduction

Here's a quick example showing a simple insert effect on a 2-channel audio bus:

code::
(
SynthDef(\insert, { arg bus;
    ReplaceOut.ar(bus, VSTPlugin.ar(In.ar(bus, 2), 2));
}).add;
)

// search of available VST plugins in the default VST search paths
VSTPlugin.search;

// create the synth:
~synth = Synth(\insert, [\bus, 0]);
// get a handle to the VSTPlugin:
~fx = VSTPluginController(~synth);
// open a plugin by name/key (might require VSTPlugin.search!)
~fx.open("myplugin", verbose: true);
// alternatively, you can open a plugin by its file path
// (this only works if the file contains a single plugin, like most VST2.x plugins)
~fx.open("/path/to/plugin", verbose: true);

// you can do all of the above in a single line:
~fx = VSTPluginController(Synth(\insert, [\bus, 0])).open("myplugin");

// open the plugin browser:
~fx.browse;

// show the generic plugin GUI:
~fx.gui;

// show the VST editor:
~fx.editor;

// etc.
::

If you have more than one instance of VSTPlugin in your SynthDef, you need to give them unique IDs so that VSTPluginController can find the right instance:

code::
(
// two VST plugins in series:
SynthDef(\insert2, { arg bus;
    var sig;
	sig = In.ar(bus, 2);
    sig = VSTPlugin.ar(sig, 2, id: \eq);
    sig = VSTPlugin.ar(sig, 2, id: \chorus);
    ReplaceOut.ar(bus, sig);
}).add;
)
// create the synth:
~synth = Synth(\insert2, [\bus, 0]);

// get handles to the VSTPlugins:
(
~eq = VSTPluginController(~synth, \eq).open("myEQ");
~chorus = VSTPluginController(~synth, \chorus).open("myChorus");
)
// or:
(
~fx = VSTPluginController.collect(~synth); // creates a VSTPluginController for each VSTPlugin ID
~fx.eq.open("myEq");
~fx.chorus.open("myChorus");
)

// etc.
::

With JITLib you have to use link::Classes/VSTPluginNodeProxyController:::

code::
(
Ndef(\foo, \vst -> { VSTPlugin.ar(WhiteNoise.ar(0.1) ! 2, 2) }).play;
~fx = VSTPluginNodeProxyController(Ndef(\foo)).open("myFX");
)
::

subsection:: Parameter Automation

There are three different ways to automate plugin parameters (listed with increasing precedence):
list::
## with the link::#-set:: and link::#-setn:: methods
code::
// set parameter 1 to 0.5
~fx.set(1, 0.5);
::
## with the code::params:: argument of link::Classes/VSTPlugin#*ar::
code::
(
SynthDef(\insert, { arg bus, f;
    var lfo = LFSaw.kr(0.1);
    // set parameter 0 with Synth argument 'f'
	// and modulate parameter 1 with LFO
    var sig = VSTPlugin.ar(In.ar(bus, 2), 2, params: [0, f, 1, lfo]);
    ReplaceOut.ar(bus, sig);
}).add;
)
// create a VSTPlugin instance with parameter 0 set to 0.5
~fx = VSTPluginController(Synth(\insert, [\bus, 0, \f, 0.5])).open("someFX");
// now set it to 0.7
~fx.synth.set(\f, 0.7);
::
## map them to control or audio busses with link::#-map::
code::
// map parameter 2 to a control bus
~c = Bus.control;
~fx.map(2, ~c);
~c.set(0.5);
::
::

Use link::#-get:: and link::#-getn:: to obtain current parameter values:
code::
// get the current value of parameter 3 and post it to the console:
~fx.get(3, {arg f; f.postln;});
::

link::#-set::, link::#-map:: and link::#-get:: also accept parameter names instead of indices:
code::
// with the GChorus (GVST) plugin:
~fx.set(\Depth, 0.5);
~fx.get(\Depth, {arg f; f.postln;});
::

subsection:: Preset Management

Select built-in FX programs with link::#-program:::

code::
// list available programs:
~fx.info.printPrograms;
// get current program number
~fx.program;
// switch to program 4:
~fx.program_(4);
::

The easiest way to manage user presets are the link::#-savePreset:: and link::#-loadPreset:: methods. Because they use standardized preset folder locations, presets can be simply referred to by name:

code::
// list available presets
~fx.info.printPresets;

// save (new) preset
~fx.savePreset("my_preset");
// do something
~fx.gui;
// save again
~fx.savePreset;
// do something
~fx.gui;
// load preset
~fx.loadPreset("my_preset");
::

Internally, preset files use the standard code::.fxp/.fxp:: (VST2) or code::.vstpreset:: (VST3) format, recognized by most DAWs and VST hosts. You can save presets to your own folders with the following methods:
code::
// write current plugin state to a preset file.
~fx.writeProgram("mypresetfolder/test.fxp");

// ... mess around with the plugin ...
~fx.gui;

// restore previous state:
~fx.readProgram("mypresetfolder/text.fxp");
::

It's also possible to get/set the raw plugin state as an link::Classes/Int8Array:::
code::
// get plugin state as Int8Array:
~fx.getProgramData({ arg data; d = data;});

// do something
~fx.gui;

// restore previous state:
~fx.setProgramData(d);
::

The data has the same binary format as the preset files. You can use these methods to build your own preset management!

subsection:: GUI

Generally, there are two kind of GUIs:

list::
## the native VST editor, which must be explicitly requested when opening a plugin:

code::
// load a plugin
~fx.open("/path/to/plugin");
// open the VST editor window
~fx.editor;
::
This will run a native window on the Server (in a seperate thread).
note:: On macOS this only works in SuperCollider 3.11 or above!::

## a generic Qt GUI which can be opened in a new Window or embedded into existing views:
code::
// load a plugin
~fx.open("/path/to/plugin", editor: false);
// open the plugin GUI in a Window
~fx.gui;
::
You can change parameters by moving the sliders or entering values into the text fields (don't supported by all plugins).
Additionally, you can browse for plugins, select programs and read/write preset files.
See link::#-gui:: and link::Classes/VSTPluginGui:: for more information.
::

subsection:: Scheduling

Generally, emphasis::synchronous:: methods, like link::#-set:: or link::#-map::, simply send an OSC message to the Server. This is fine for interactive use, but if you need accurate timing, commands have to be scheduled as OSC bundles (see also link::Guides/ServerTiming::).

Here are two basic ways how to schedule methods with Server latency:
code::
// asking the object for the message
~fx = VSTPluginController(Synth(\foo));
s.sendBundle(s.latency, ~fx.setMsg(0, 0.5));
s.sendBundle(s.latency, ~fx.midi.noteOn(0, 60, 100));

// using automatic bundling
s.bind {
	~fx.set(0, 0.5);
	~fx.midi.noteOn(0, 60, 100);
};
::


subsection:: Sequencing

VSTPlugin defines two custom link::Classes/Event:: types which are typically used with link::Classes/Pbind::.
Like with (most) other Event types, commands are scheduled as OSC bundles with Server latency.

definitionlist::
## code::\vst_set::
|| sets one or more plugin parameters to the specified values; the interface is similar to code::\set::.
table::
## code::\vst:: || the VSTPluginController instance
## code::\params:: || an (optional) Array of parameter names or indices that should be looked up in the Event
::

a) Explicit look up (names or indices):
code::
~p2 = Pbind(
	\type, \vst_set,
	\vst, ~fx,
	\params, [\Mix, \Depth, 1], // use parameters 'Mix', 'Depth' and 1
	\Mix, Pseq([0.1, 0.2, 0.5, 0.9], inf), // value for parameter 'Mix'
	\Depth, Prand([0.3, 0.5, 0.7], inf), // value for parameter 'Depth'
	1, Pwhite(), // value for parameter 1
	\dur, Prand([0.25, 0.5, 1], inf)
);
::

b) Automatic lookup (indices only)
code::
~p1 = Pbind(
	\type, \vst_set,
	\vst, ~fx,
	1, Pwhite(0.1, 0.9), // automate parameter 1
	3, Pwhite(0.2, 0.8), // automate parameter 3
	\dur, Prand([0.25, 0.5, 1], inf)
);
::
This is slightly less efficient than explicit lookup.

warning::Before VSTPlugin v0.6, parameter emphasis::names:: have been looked up automatically if you omitted the code::\params:: key. This feature has been removed!::

Pattern composition with automatic lookup is straight forward:
code::
// add another parameter
~p3 = Pbind(
	2, Prand([0.2, 0.5, 0.7], inf)
) <> ~p1;
::

Pattern composition with explicit lookup also possible, but less flexible:

code::
// 'template' Pattern
~a = Pbind(
    \type, \vst_set,
    \vst, ~fx,
	\params, [\Depth, \Mix],
	\Mix, Pseq([0.1, 0.2, 0.5, 0.9], inf),
	// \Depth will be provided later
);

// make two different Patterns based on ~a
~b = Pbind(
	\Depth, Pwhite(0.1, 0.9),
	\dur, Prand([0.25, 0.5, 1], inf)
) <> ~a;

~c = Pbindf(
    \Depth, Pwhite(0.5, 0.7),
	\dur, Prand([0.3, 0.66, 1], inf)
) <> ~a;
::

See link::#Automation:: for more examples.

## code::\vst_midi::
|| send MIDI messages; the interface is very similar to the code::\midi:: Event type.

Event keys:
table::
## code::\vst:: || the VSTPluginController instance
## code::\midicmd:: || the MIDI method (see below)
## code::\chan:: || the MIDI channel; the default is 0
## code::\midinote:: || MIDI pitch for code::\noteOn::, code::\noteOff:: and code::\polyTouch::;

	may be a fractional value (= microtonal), see link::Classes/VSTPluginMIDIProxy#-noteOn::.
## code::\amp:: || amplitude (0.0 - 1.0) for code::\noteOn:: and code::\noteOff::
## code::\ctlNum:: || CC number for code::\control::
## code::\control:: || CC value for code::\control::
## code::\val:: || value argument for code::\touch:: and code::\bend::
## code::\polyTouch:: || touch value for code::\polyTouch::
## code::\progNum:: || program number for code::\program::
## code::\array:: || UInt8Array for code::\sysex::
::

Possible values for code::\midicmd:::
table::
## code::\noteOn:: || note-on message (= default);

automatically schedules code::\noteOff:: messages based on the note duration.

(This can be disabled by setting code::\hasGate:: to code::false::.)

## code::\noteOff:: || note-off message
## code::\control:: || CC message
## code::\bend:: || pitch bend
## code::\touch:: || channel after-touch
## code::\touch:: || polyphonic after-touch
## code::\program:: || program change
## code::\allNotesOff:: || turn all notes off
## code::\sysex:: || SysEx message
::
Each code::\midicmd:: has a corresponding method in link::Classes/VSTPluginMIDIProxy::.

See link::Tutorials/A-Practical-Guide/PG_08_Event_Types_and_Parameters#MIDI output:: for more details on MIDI commands.

See link::#VST Instruments:: for examples.

note::Always prefer code::\vst_midi:: over code::\midi:: because the latter doesn't schedule OSC bundles!::
::

strong::Tip:::
You can play Pbinds of type code::\vst_midi:: and code::\vst_set:: in parallel with link::Classes/Ppar::.


subsection:: Realtime Safety

VSTPlugin tries its best to be as realtime safe as possible. Plugins are always opened/closed asynchronously in the NRT thread.
Some methods, like link::#-loadPreset:: and link::#-savePreset::, offer two options via the code::async:: parameter:

numberedlist::
## code::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 you can't call other methods until the command has finished.
## code::async: false:: means that the plugin method is simply called on the RT thread. The advantage is that the command is performed synchronously and plugin processing doesn't have to be suspended. Depending on the plugin, this might be just fine - or block the Server. You have to test yourself!
::

note:: If the plugin is opened with the VST GUI editor, the code::async:: option is automatically set to code::true:: because of thread safety concerns.::

CLASSMETHODS::

PRIVATE:: guiClass, msg2string, prFindPlugins

METHOD:: new
Create a new VSTPluginController for a given Synth.

ARGUMENT:: synth
the link::Classes/Synth:: containing the link::Classes/VSTPlugin:: you want to control.

ARGUMENT:: id
a Symbol which uniquely identifies the link::Classes/VSTPlugin:: in the link::Classes/SynthDef::.

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

ARGUMENT:: synthDef
the synth's link::Classes/SynthDef::. You can omit this argument if the SynthDef has been added to the global link::Classes/SynthDescLib::, e.g. with link::Classes/SynthDef#-add:: or link::Classes/SynthDef#-store::. In this case, the SynthDef will be automatically deduced from the emphasis::synth:: argument.

ARGUMENT:: wait
the default wait time, see link::#-wait::.

DISCUSSION::
Initially, no VST plugin is loaded and the UGen is automatically bypassed (i.e. the input is just passed through).

METHOD:: collect
Same as link::#-new::, but returns an link::Classes/Event:: of VSTPluginControllers, with their IDs used as keys.
This is useful if you have a SynthDef containing several VSTPlugin instances.

ARGUMENT:: synth
the Synth, see link::#-new::

ARGUMENT:: ids
an Array of IDs referring to link::Classes/VSTPlugin:: instances in the link::Classes/SynthDef::, or code::nil:: (= collect all).

ARGUMENT:: synthDef
the SynthDef (optional), see link::#-new::

ARGUMENT:: wait
the default wait time, see link::#-wait::.

DISCUSSION::
code::
(
SynthDef.new(\test, { arg bus = 0;
	var sig = VSTPlugin.ar(nil, 2, id: \vsti);
	sig = VSTPlugin.ar(sig, 2, id: \fx);
	Out.ar(bus, sig);
}).add;
)

~fx = VSTPluginController.collect(Synth(\test), [\vsti, \fx]);
// or
~fx = VSTPluginController.collect(Synth(\test));

(
~fx.vsti.open("myVSTi");
~fx.fx.open("myFX");
)

::

INSTANCEMETHODS::

PRIVATE:: prFree, prCheckPlugin, prCheckLocal, prClear, init, prQuery, prQueryParams, prQueryPrograms
PRIVATE:: prGetPreset, prSendData, prReceiveData, prSetData, prGetData, prMakeOscFunc


METHOD:: open
open a VST plugin.

ARGUMENT:: path
the plugin key or file path.

- Opening plugins by strong::key:: requires that the plugin has already been probed (e.g. as a result of link::Classes/VSTPlugin#*search::).
code::
~fx.open("GChorus"); // assuming 'GChorus' is in the Server's plugin dictionary.
~fx.open("mda Delay.vst3"); // VST3 plugins always need a '.vst3' extensions
::
- Alternatively, you can use a strong::file path:: (with or without extension). Relative paths are resolved to the standard VST directories (see link::Classes/VSTPlugin#*search::); this is done recursively, which means you don't necessarily have to specify any subfolders.
code::
// absolute file path:
~fx.open("C:/Program Files/VSTPlugins/GVST/GChorus");

// since C:/Program Files/VSTPlugins/ is one of the standard VST directories,
// the plugin can also be opened like this:
~fx.open("GVST/GChorus");
~fx.open("GChorus"); // even without subfolder
::

note::This method only works for files which contain a single plugin (all VST 2.x plugins - except for shell plugins - and many VST 3 plugins).::

- If the VSTPlugin UGen holds a plugin description (see link::Classes/VSTPlugin#*ar::), the code::path:: argument can be deduced and therefore omitted.
code::
VSTPlugin.search;
(
SynthDef(\chorus, { arg bus=0;
	var plugin = VSTPlugin.plugins['GChorus'];
	ReplaceOut.ar(bus, VSTPlugin.ar(In.ar(bus, 2), 2, info: plugin));
}).add;
)
~fx = VSTPluginController(Synth(\chorus)).open; // will open 'GChorus'
::

ARGUMENT:: editor
enable/disable the VST plugin editor.

note::On macOS this only works with SuperCollider 3.11 and above!::

note::Some (buggy) plugins don't work correctly without the VST editor.::

ARGUMENT:: verbose
post the plugin info to the console if loaded successfully.

ARGUMENT:: action
a function that will be called with the object itself and a Boolean (success/fail) when the operation has completed.

code::
// open preset 'foo' after the plugin has been opened successfully:
~fx.open('GChorus', action: { |x, ok|
	ok.if { x.loadPreset('foo') }
});
::

note::You must emphasis::not:: use link::Classes/Server#-sync:: to wait for completion! If you prefer to write sequential code instead of callbacks, you may use a link::Classes/Condition:: resp. link::Classes/CondVar:: and signal it from the action function.::

ARGUMENT:: multiThreading
process the plugin in a seperate worker thread to utilize more CPU cores. See also link::Classes/VSTPlugin#*initDSPThreads::.

note::This option is ignored for Supernova, which already offers multithreading with ParGroup.::

note::Multithreading introduces a delay of 1 block!::


ARGUMENT:: mode
select a run mode.
table::
## \auto || normal mode (default).
## \sandbox || run the plugin in a dedicated subprocess. This means that the plugin can safely crash without taking down the whole Server! This is useful for buggy plugins or safe experimentation.
## \bridge || run the plugin in a shared subprocess. This uses less memory and possibly less CPU, but if one plugin crashes, it will inevitably take down all other plugins in the same process.
::
note::All run modes except for code::\auto:: incur some fixed CPU overhead, which is less significant for larger blocksizes (see link::Classes/ServerOptions#-blockSize:: or the code::blockSize:: argument in link::Classes/VSTPlugin#-ar::).::
See also link::Classes/VSTPlugin#Bridging and Sandboxing::.

DISCUSSION::
This method is realtime-safe because the VST plugin is opened asynchronously (in the NRT thread).


METHOD:: openMsg

ARGUMENT:: path
the plugin name/key or file path. Relative paths are resolved to the standard VST directories.

If the VSTPlugin UGen holds a plugin description (see link::Classes/VSTPlugin#*ar::), the code::path:: argument can be deduced and therefor ommitted.

ARGUMENT:: editor
request the VST editor.

ARGUMENT:: multiThreading
enable multithreading.

ARGUMENT:: mode
select a run mode.

RETURNS:: the message for an emphasis::open:: command (see link::#-open::).

METHOD:: isOpen
returns:: whether a plugin is currently open.

METHOD:: close
METHOD:: closeMsg
close the current plugin (but don't free the Synth!). You can open another plugin later.

DISCUSSION::
This will automatically bypass the plugin (i.e. the input is just passed through).

Just like link::#-open::, this method is realtime-safe.


METHOD:: pluginCrashed
a link::Classes/Function:: or link::Classes/FunctionList:: to be called when the plugin subprocess crashes.

discussion::
You could use this callback to automatically reopen the plugin, for example.
note::This is only meant for bridged or sandboxed plugins, because a normal plugin would simply crash the server.::

METHOD:: browse
open the plugin browser dialog.

METHOD:: editor
METHOD:: editorMsg
show/hide the VST editor window.

DISCUSSION::
The plugin has to be opened with code::editor: true::.

note::On macOS this only works on SuperCollider 3.11 and above!::

METHOD:: moveEditor
METHOD:: moveEditorMsg
move the editor window to the given position.

METHOD:: resizeEditor
METHOD:: resizeEditorMsg
resize the editor window to the given width and height.

note::This only works for VST3 plugins with a resizable editor.::

METHOD:: gui
creates a generic Qt GUI (see link::Classes/VSTPluginGui::).

ARGUMENT:: parent
the parent. If code::nil::, the GUI is created in a new toplevel window.

ARGUMENT:: bounds
the bounds.

ARGUMENT:: params
show/hide parameters. Set to code::false::, if you only need to show the preset manager!

RETURNS:: a new link::Classes/VSTPluginGui:: instance.

METHOD:: info
returns:: the (static) plugin description (see link::Classes/VSTPluginDesc::).

METHOD:: latency
returns:: the current processing latency in samples.

NOTE:: The reported value includes the additional latency caused by multithreading and reblocking (see the code::multiThreading:: and code::blockSize:: arguments for link::#-open::).::

METHOD:: latencyChanged
a link::Classes/Function:: or link::Classes/FunctionList:: to be called when the plugin's processing latency changes. The function receives the new latency as its only argument. See also link::#-latency::.

METHOD:: reset
METHOD:: resetMsg
reset the plugin state.

ARGUMENT:: async
see link::#Realtime Safety::.

DISCUSSION::
Depending on the plugin, emphasis::reset:: can involve expensive operations, like clearing a large delay line, and might not be realtime-safe, so be careful with setting code::async:: to code::false::.

METHOD:: synth
returns:: the link::Classes/Synth:: containing the currently controlled link::Classes/VSTPlugin:: instance.

METHOD:: synthIndex
returns:: the index of the link::Classes/VSTPlugin:: instance within the link::Classes/Synth::.

METHOD:: wait
the wait time between OSC messages (in seconds).

DISCUSSION::
-1 allows an OSC roundtrip between packets.

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

Some methods may require lots of OSC messages (e.g. when changing programs, the UGen has to send the new
state of all parameters). VSTPluginController waits for the given time after a certain number of bytes
to avoid messages getting dropped. This is mostly relevant for UDP connections,
especially for remote Servers, high network traffic and plugins with a large number of parameters.

The wait time can be changed anytime.

subsection:: Parameters

METHOD:: numParameters
returns:: the number of parameters.

METHOD:: set
METHOD:: setMsg
Set plugin parameters.

discussion::
This method expects pairs of parameter index/name and value. Each value should be either a number between 0.0 and 1.0
or a string/symbol.

note::
Some plugins don't support setting parameters by strings, others only allow it for certain parameters.
::

code::
// set parameter 3 to value 0.9:
~fx.set(3, 0.9);
// set parameter 'Mix' to 0.5:
~fx.set(\Mix, 0.5);
// set parameters 1 and 3:
~fx.set(1, 0.5, 3, 0.75);
// GChorus (GVST):
~fx.set(\Freq, "3.16"); // set frequency in Hz as string

::
note::
The parameter(s) will be automatically unmapped from any control bus, see link::#-map::.
::

With code::setMsg:: you can schedule emphasis::sample accurate:: parameter changes for plugins which support this (some, but not all VST3 plugins).

METHOD:: setn
METHOD:: setnMsg
set sequential ranges of parameters.

discussion::
This method expects pairs of parameter index and Array of values (numbers or strings/symbols), see link::#-set::.

code::
// this will set parameters 3, 4, 8, 9 and 10.
~fx.setn(3, [0.5, 0.75], 8, [0.1, "300", 0.3]);
::

METHOD:: map
map parameters to control or audio busses.

discussion::
This methods expects pairs of parameter index/name and bus.
In case of multi-channel busses the channels are mapped to a sequential range of parameters starting at the given index/name.

The bus argument can be simply an integer referring to a emphasis::control:: bus. If you want to map an audio bus, you have to explicitly pass an audio Bus object.

Parameters are updated whenever the data in the bus changes. Note::Only map to an audio bus if you need sample accurate automation and the plugin
actually supports it (some, but not all VST3 plugins).::
code::
~bus1 = Bus.control;
~bus2 = Bus.control(numChannels: 2);
~fx.map(\Mix, ~bus1, 5, ~bus2);
~bus1.set(0.5); // set parameter 'Mix'
~bus2.set(0.75, 0.9); // set parameters 5 and 6 (because of 2-channel control bus)

~bus3 = Bus.audio;
~fx.map(\Delay, ~bus3); // audio rate automation (assuming the 'Delay' parameter supports this)
::
Each parameter can only be mapped to one control bus channel at the time.

note::setting a parameter with link::#-set:: or link::#-setn:: will automatically unmap it from any control bus.::

note::code::map:: will override automation via UGen arguments.::

METHOD:: mapMsg
returns a emphasis::bundle:: containing control and/or audio bus mapping messages. Takes the same arguments as code::map::.

METHOD:: mapn
METHOD:: mapnMsg
map parameters to control busses. The arguments are triples of parameter index/name, control bus index and number of channels. See link::#map::.

METHOD:: mapan
METHOD:: mapanMsg
map parameters to audio busses. The arguments are triples of parameter index/name, audio bus index and number of channels. See link::#map::.

METHOD:: unmap
METHOD:: unmapMsg
Unmap parameters from a control bus.

discussion::
Pass all the parameters you want to unmap. Calling the method without arguments will unmap all parameters.
code::
// unmap parameters 4, 5, and 7
~fx.unmap(4, 5, 7);
::

METHOD:: get
get the current value of a plugin parameter.

ARGUMENT:: index
the index/name of the parameter.

ARGUMENT:: action
a function that will receive the requested value.

discussion::
code::
// get the value of parameter 4 and post it to the console:
~fx.get(4, {arg f: f.postln;});
// get the value of parameter 'Mix':
~fx.get(\Mix, {arg f: f.postln;});
::

METHOD:: getn
get a sequential range of parameter values.

ARGUMENT:: index
the starting index/name.

ARGUMENT:: count
the number of sequential parameter values. -1 will return all parameters starting from emphasis::index::.

ARGUMENT:: action
a function that will receive the requested values as an Array.

discussion::
code::
// get the values of parameters 2, 3 an 4 and post them to console:
~fx.getn(2, 3, {arg v; v.postln;});

// get all parameter values:
~fx.getn(action: {arg v; v.postln;});
::

METHOD:: parameterAutomated
a link::Classes/Function:: or link::Classes/FunctionList:: to be called when parameters are automated in the VST editor.

discussion::
The action receives the parameter index and value. This can be helpful if you want to know the index of a parameter in the editor.

note::Some plugins link parameters, so that changing one parameter will lead to several other parameters being "automated".
In that case it is not possible to determine which parameter has been automated manually.::

METHOD:: parameterCache
An Array containing the current state (code::[value, display]::) of each parameter. Only valid if a plugin is currently loaded!

subsection:: Programs

VST plugins often contain factory presets which are called emphasis::programs::.

note::Some VST2 plugins allow to change the name and state of the built-in programs and save all programs as a emphasis::bank:: file (see link::#-writeBank::).::

METHOD:: numPrograms
returns:: the number of available built-in plugin programs.

METHOD:: program
METHOD:: programMsg
select a built-in program or get the current program number.

METHOD:: programName
METHOD:: programNameMsg

get/set the name of the current program (VST2 only).

METHOD:: programCache
An Array containing the current name of each program. Only valid if a plugin is currently loaded!

subsection:: Presets

Simple preset management.

Presets are stored at pre-defined file system locations, so they can be simply referred to by name or index (see link::Classes/VSTPluginDesc#-presets::).

note::Since the VST3 preset locations are actually standardized, any VST3 presets created with VSTPlugin should be available in other applications and vice versa.::

warning::This only works with local Servers (for now)!::

METHOD:: loadPreset
METHOD:: savePreset
load/save VST presets.

ARGUMENT:: preset
a preset Event, name or index (see link::Classes/VSTPluginDesc#-presets::).

You can create a new preset by passing a non-existing preset name to code::savePreset::.

ARGUMENT:: action

a function that will be called with the object itself and a Boolean (success/fail) when the operation has completed.

ARGUMENT:: async

where to perform the plugin method, see link::#Realtime Safety::.
note::The file IO itself is always performed asynchronously!::

METHOD:: loadPresetMsg
Create an OSC message for loading a preset. See also link::#-readProgramMsg::.

note:: There is no equivalent code::savePresetMsg:: method because we wouldn't be able to update the preset list.::

ARGUMENT:: preset
a preset Event, name or index (see link::Classes/VSTPluginDesc#-presets::).

ARGUMENT:: async
see above.

METHOD:: deletePreset
delete a VST preset.

ARGUMENT:: preset
the preset Event, name or index.

RETURNS:: code::true:: on success or code::false:: on failure.

METHOD:: renamePreset
delete a VST preset.

ARGUMENT:: preset
the old preset Event, name or index

ARGUMENT:: name
the new preset name.

RETURNS:: code::true:: on success or code::false:: on failure.

METHOD:: preset

RETURNS:: the current preset (Event) or code::nil:: (= no preset).

subsection:: Preset Files

Read/write VST2 code::.fxp/.fxb:: files or VST3 code::.vstpreset:: files.

This is useful if you want to save your presets to a non-standard location, e.g. relative to your project.

The preset files are in a standard format which is recogized by every decent DAW or VST host.
This means you can freely exchange presets between different applications!


METHOD:: readProgram
METHOD:: writeProgram
read/write program files.

ARGUMENT:: path

an absolute file path.

The file extension is arbitrary but it is good practice to use emphasis::.fxp:: for VST2 program files and emphasis::.vstpreset:: for VST3 preset files.

ARGUMENT:: action

a function that will be called with the object itself and a Boolean (success/fail) when the operation has completed.

ARGUMENT:: async

where to perform the plugin method, see link::#Realtime Safety::.
note::The file/buffer IO itself is always performed asynchronously!::

METHOD:: writeBank
METHOD:: readBank

same as above, but for VST2 emphasis::.fxb:: bank files.

METHOD:: readProgramMsg
METHOD:: writeProgramMsg

Create an OSC message for reading/writing a program file, or exchanging program data via a Buffer.

ARGUMENT:: dest
table::
## String || preset file to be read or written.

## link::Classes/Buffer:: or Integer || exchange program data between a Client and a (remote) Server via a Buffer.

code::readProgramMsg::: the Buffer should contain the preset data with each float representing a single byte;
it has to be allocated and freed by the Client.

code::writeProgramMsg::: the Buffer should be initially empty. The UGen will fill the Buffer
on the Server, the Client can then read the data and free the Buffer.

::

ARGUMENT:: async
see above.

RETURNS:: the OSC message.

METHOD:: readBankMsg
METHOD:: writeBankMsg

same as above, but for VST2 emphasis::.fxb:: bank files.


subsection:: Preset Data

Set/get the raw plugin state. This is useful if you want to build your own custom preset system.

note::The emphasis::Bank:: methods only work with VST2 plugins.::

METHOD:: setProgramData
METHOD:: setBankData

set the new program/bank state as an link::Classes/Int8Array::.

ARGUMENT:: data
the raw plugin data.

ARGUMENT:: action
a function that will be called with the object itself and a Boolean (success/fail) when the operation has completed.

ARGUMENT:: async
where to perform the plugin method, see link::#Realtime Safety::.
note::The data transfer itself is always performed asynchronously!::

METHOD:: getProgramData
METHOD:: getBankData
get the current program/bank state as an link::Classes/Int8Array::.

ARGUMENT:: action
a function that will receive the data - or code::nil:: if the method failed.

ARGUMENT:: async
see above.

DISCUSSION::

Internally, the program data is exchanged via temp files.
warning::This only works with a local Server!::

METHOD:: sendProgramData
METHOD:: sendBankData
send the new program/bank state as an link::Classes/Int8Array::.

ARGUMENT:: data
the raw plugin data.

ARGUMENT:: wait
temporarily overwrites link::#-wait:: if not code::nil::.

ARGUMENT:: action
a function that will be called with the object itself and a Boolean (success/fail) when the operation has completed.

ARGUMENT:: async
where to perform the plugin method, see link::#Realtime Safety::.
note::The data transfer itself is always performed asynchronously!::

METHOD:: receiveProgramData
METHOD:: receiveBankData
receive the current program/bank state as an link::Classes/Int8Array::.

ARGUMENT:: wait
temporarily overwrites link::#-wait:: if not code::nil::.

ARGUMENT:: timeout
the number of seconds to wait before giving up.

ARGUMENT:: action
a function that will receive the data.

ARGUMENT:: async
see above.

DISCUSSION::
Contrary to link::#-setProgramData::, link::#-getProgramData:: etc., the methods above
also work with remote Servers because the data is streamed via OSC messages. This means
it is not 100% reliable when using UDP.


subsection:: MIDI

METHOD:: midi
MIDI interface for VSTPluginController.

RETURNS:: an instance of link::Classes/VSTPluginMIDIProxy::.


METHOD:: sendMidi
METHOD:: sendMidiMsg
send a raw MIDI message with 2-3 bytes (status, data1, data2) and an optional detune argument in cent (not supported by all VST instruments!). MIDI messages can be scheduled sample accurately when sent as bundles!

METHOD:: sendSysex
METHOD:: sendSysexMsg
send a system exclusive message as an link::Classes/Int8Array::.

METHOD:: midiReceived
a link::Classes/Function:: or link::Classes/FunctionList:: to be called when receiving MIDI messages from the plugin.

discussion::
The 3 bytes of the MIDI message are passed as invidual arguments:
code::
~fx.midiReceived = {arg ...msg; "got MIDI message %".format(msg)};
::

METHOD:: sysexReceived
a link::Classes/Function:: or link::Classes/FunctionList:: to be called when receiving SysEx messages from the plugin.

discussion::
The SysEx data is passed to the action as an link::Classes/Int8Array::.

subsection:: Transport

METHOD:: setPlaying
METHOD:: setPlayingMsg
set the transport playing state to true or false. Only necessary for VST plugins which do some kind of sequencing.

warning::Transport playback is emphasis::disabled:: by default!::

METHOD:: setTempo
METHOD:: setTempoMsg
set the tempo in BPM (beats per minute).

METHOD:: setTimeSignature
METHOD:: setTimeSignatureMsg
set the time signature, e.g. 3/4 -> num = 3, denom = 4.

METHOD:: setTransportPos
METHOD:: setTransportPosMsg
set the current transport position (in quarter notes).

METHOD:: getTransportPos
get the current transport position (in quarter notes).

ARGUMENT:: action
a function that will receive current transport position.

subsection:: VST2 only

METHOD:: canDo

query the plugin for special capabilities.

ARGUMENT:: what
a string describing the capability. Some of these are documented in the VST SDK, but others are not.

ARGUMENT:: action
a function that will be called with an Integer result.
table::
## 1 || yes
## -1 || no
## 0 || don't know
::

METHOD:: vendorMethod
METHOD:: vendorMethodMsg
Access special functionality of a plugin which is not available via the standard parameter interface. Check the documentation of the plugin to see what kind of data it expects.

ARGUMENT:: index
an Integer.
ARGUMENT:: value
an Integer.
ARGUMENT:: ptr
some arbitrary data as an link::Classes/Int8Array::.
ARGUMENT:: opt
a Float.

ARGUMENT:: action
a function that will be called with an Integer result. The meaning depends on the VST plugin.

ARGUMENT:: async
see link::#Realtime Safety::.

EXAMPLES::
ANCHOR::Examples::

The following code is needed for most examples:

code::
(
// a simple stereo insert FX which reads from an audio bus
// and replaces the content with the processed output:
SynthDef.new(\insert, {arg bus;
	ReplaceOut.ar(bus, VSTPlugin.ar(In.ar(bus, 2), 2));
}).add;

// load sound file
~buf = Buffer.read(s, Platform.resourceDir +/+ "sounds/a11wlk01.wav");
// soundfile player
SynthDef(\test, {arg out = 0;
    Out.ar(out,
        PlayBuf.ar(1, ~buf, BufRateScale.kr(~buf), loop: 1).dup * 0.5;
    )
}).add;
)
::

SUBSECTION:: Serial FX chains

How to build a serial FX chain on an audio bus:
code::
(
// allocate an FX bus
~fxBus = Bus.audio(s, 2);
// play test signal on FX bus
~test = Synth(\test, [\out, ~fxBus]);
// send FX bus to output
SynthDef(\output, { arg in = 0, out = 0;
	Out.ar(out, In.ar(in, 2))
}).play(~test, [\in, ~fxBus, \out, 0], addAction: \addAfter);
)

// add an insert FX to the bus (after the test signal)
~fx1 = VSTPluginController(Synth(\insert, [\bus, ~fxBus], ~test, addAction: \addAfter));
// open a plugin from the GUI and play with the parameters
~fx1.gui;

// add another insert FX (after '~fx1'):
~fx2 = VSTPluginController(Synth(\insert, [\bus, ~fxBus], ~fx1.synth, addAction: \addAfter));
// open plugin
~fx2.gui;

// change the FX order dynamically, e.g. move '~fx2' before '~fx1':
~fx2.synth.moveBefore(~fx1.synth);

~fx1.synth.free; // remove from FX chain
~fx2.synth.free; // remove from FX chain
::

You can also create fixed FX chains by using several VSTPlugins inside a SynthDef:
code::
(
// an insert FX with two plugins hardcoded in series:
SynthDef.new(\insert2, { arg bus, bypass1=0, bypass2=0;
	var sig = In.ar(bus, 2);
	sig = VSTPlugin.ar(sig, 2, bypass1, id: \fx1);
	sig = VSTPlugin.ar(sig, 2, bypass2, id: \fx2);
	ReplaceOut.ar(bus, sig);
}).add;
)

(
// insert into the FX bus
~synth = Synth(\insert2, [\bus, ~fxBus], ~test, addAction: \addAfter);
// get handles to the individual VST plugins:
~fx = VSTPluginController.collect(~synth);
)

// open plugins
~fx.fx1.browse;
~fx.fx2.browse;

// bypass FX
~synth.set(\bypass1, 1);
~synth.set(\bypass2, 1);

~synth.free; // remove FX
::

Subsection:: Master FX section

This is how you would create a simple master FX section:
code::
// Cmd + .
// add a group *after* the default group
~fxGroup = Group.after(1);
// add two stereo insert effects to the FX group (in series)
~fx1 = VSTPluginController(Synth(\insert, [\bus, 0], ~fxGroup, addAction: \addToTail));
~fx2 = VSTPluginController(Synth(\insert, [\bus, 0], ~fxGroup, addAction: \addToTail));

// open plugins
~fx1.browse;
~fx2.browse;

// play test sound
Synth(\test, [\out, 0]);
::

Subsection:: Automation

Automate parameters via control busses
note:: Parameter automation will emphasis::not:: be visible in the Qt GUI (due to performance reasons)::

code::
// Cmd + .
// play test signal
~test = Synth(\test, [\out, 0]);

// insert FX (after ~test)
~fx = VSTPluginController(Synth.new(\insert, [\bus, 0], ~test, addAction: \addAfter));
// open plugin
~fx.browse;
// create control bus
~ctl = Bus.control;
// create an LFO
~lfo = {Out.kr(~ctl, SinOsc.kr(0.25, 0, 0.5, 0.5))}.play;
// modulate the first parameter of ~fx by mapping it to ~ctl
~fx.map(0, ~ctl); // (don't move the slider of the mapped parameter in the Qt GUI or you will unmap it!)
// unmap it
~fx.unmap(0);

~fx.synth.free; // remove FX
~lfo.free;
::

Automate parameters inside the SynthDef:
code::
(
SynthDef.new(\mod, {arg bus, rate=0.25, bypass=0;
	var lfo, sig;
	lfo = SinOsc.kr(rate, 0, 0.5, 0.5);
	// parameter 0 will be modulated by a SinOsc
	sig = VSTPlugin.ar(In.ar(bus, 2), 2, bypass, params: [0, lfo]);
	ReplaceOut.ar(bus, sig);
}).add;
)

~fx = VSTPluginController(Synth.new(\mod, [\bus, 0], ~test, addAction: \addAfter));
// open plugin
~fx.browse;

~fx.synth.set(\rate, 0.9); // change modulation rate
~fx.synth.set(\bypass, 1); // bypass
~fx.synth.free; // release FX
::

Automate parameters with a Pbind of type code::\vst_set:::

code::
~fx = VSTPluginController(Synth.new(\insert, [\bus, 0], ~test, addAction: \addAfter));
// open plugin (the example uses 'GChorus' from GVST plugins)
~fx.open("GChorus");

// 1) automate parameters in parallel
(
~p = Pbind(
	\type, \vst_set,
	\vst, ~fx,
	\params, [ 0, 1, 3 ],
	0, Pexprand(0.1, 0.9),
	1, Pwhite(0.3, 0.7),
	3, Pseq([0.1, 0.2, 0.5, 0.9], inf),
	\dur, Prand([0.25, 0.5, 1], inf)
).play;
)
~p.stop;

// 2) automate parameters alternatingly
(
~lfo = (cos(Pn(Pseries(0, 0.1, 10)) * 2pi) + 1) * 0.5;

~p = (
	Pbind(
		\type, \vst_set,
		\vst, ~vst,
		\dur, 0.1
	) <> Pswitch1([
		Pbind(0, ~lfo),
		Pbind(1, ~lfo),
		Pbind(3, ~lfo)
	], Pwhite(0, 2))
).play
)
~p.stop;

// 3) choose random parameter and set it to a random value
(
~p = (
	Pbind(
		\type, \vst_set,
		\vst, ~vst,
		\dur, 0.25
	) <> Pfunc({ ( (4.rand): 1.0.rand ) })
).play
)
~p.stop;
::

Subsection:: VST Instruments

You can easily play VST instruments with a link::Classes/Pbind:: of event type code::\vst_midi:::
code::
// Cmd + .
(
SynthDef.new(\vsti, { arg out = 0;
	// VST instruments usually don't have inputs
	Out.ar(out, VSTPlugin.ar(nil, 2));
}).add;
)

// create Synth with VST instrument
~vsti = VSTPluginController(Synth(\vsti));
// open plugin
~vsti.browse;

// play the instrument with a \vst_midi Pbind
(
~p = Pbind(
    \type, \vst_midi,
    \vst, ~vsti, // the VSTPluginController instance
	\midicmd, \noteOn, // the default, can be omitted
	\chan, 0, // MIDI channel (default: 0)
	\midinote, Pseq(#[0, 2, 4, 7], inf) + Pwhite(-12, 12).stutter(Pwhite(4, 16)) + 60,
	\dur, Prand(#[0.125, 0.25, 0.5], inf),
    \legato, Pexprand(0.5, 1.0, inf),
    \amp, Pexprand(0.5, 1.0, inf)
).play(quant: 1);
)

// change programs
~vsti.program_(1);

~p.stop;

// play the instrument with your MIDI keyboard:
(
MIDIClient.init;
MIDIIn.connectAll;
MIDIFunc.noteOn({ |vel, pitch|
	~vsti.midi.noteOn(0, pitch, vel);
});
MIDIFunc.noteOff({ |vel, pitch|
    ~vsti.midi.noteOff(0, pitch, vel);
});
)
::

Subsection:: Non-Realtime Synthesis

Many methods of VSTPluginController have a corresponding emphasis::*Msg:: version,
returning a Server message which can be added to a link::Classes/Score:: for non-realtime synthesis.

The following code snippet will create a short soundfile with two random melodies played by VST instruments and processed with VST effects; it can be executed in a single block.
code::
(
// 1) temporary Server (for Node ID allocation)
~server = Server(\nrt,
    options: ServerOptions.new
    .numOutputBusChannels_(2)
);

// 2) SynthDef for playing the VSTi
SynthDef.new(\my_instrument, { arg out;
	var sig = VSTPlugin.ar(nil, 2, id: \vsti);
	sig = VSTPlugin.ar(sig, 2, id: \fx);
	Out.ar(out, sig);
}).store; // so that the subprocess can find the SynthDef!

// 3) create the VSTi Synths (in the language)

~synth = { Synth.basicNew(\my_instrument, ~server) } ! 2;

// get handles to the plugin controllers
~vst = ~synth.collect { |x| VSTPluginController.collect(x) };

// 4) create the Score:

~score = Score.new;

// search for plugins in default search paths (only needed the first time)
~score.add([0.0, VSTPlugin.searchMsg(verbose: false)]);

// create the synths:
~score.add([0.0, ~synth[0].newMsg]);
~score.add([0.0, ~synth[1].newMsg]);

// open VSTi plugins
~score.add([0.0, ~vst[0].vsti.openMsg("Dexed", editor: false)]);
~score.add([0.0, ~vst[1].vsti.openMsg("Dexed", editor: false)]);

// choose programs
~score.add([0.0, ~vst[0].vsti.programMsg(0)]);
~score.add([0.0, ~vst[1].vsti.programMsg(1)]);

// open FX plugins
~score.add([0.0, ~vst[0].fx.openMsg("GDelay", editor: false)]);
~score.add([0.0, ~vst[1].fx.openMsg("GChorus", editor: false)]);

// set some FX params
~score.add([0.0, ~vst[0].fx.setMsg(0, 0.2)]); // delay time
~score.add([0.0, ~vst[0].fx.setMsg(1, 0.5)]); // delay feedback
~score.add([0.0, ~vst[1].fx.setMsg(0, 0.9)]); // chorus depth

// make a random melody
~melody = Pbind(
	\type, \vst_midi,
	\dur, Prand(#[0.125, 0.25, 0.5, 1], inf),
	\legato, 1,
	\amp, Pexprand(0.5, 1.0, inf),
	\midinote, Pwhite(48, 72, inf)
);

// helper function for recording a Pbind to a Score
~render = { arg vsti, pbind, start, dur;
	var list = pbind.asScore(dur, start, (vst: vsti)).score;
	~score.score = ~score.score.addAll(list[1..(list.size-2)]); // we have to remove the first and last bundle (/g_new + /c_set)!
};

~render.(~vst[0].vsti, ~melody, 1, 8); // render 8 beats of the first voice, starting at beat 1
~render.(~vst[1].vsti, ~melody, 4, 7); // render 7 beats of the second voice, starting at beat 4

// finally sort the score!
~score.sort;

// 5) render as stereo aiff file

~score.recordNRT("~/nrt_test".standardizePath, "~/nrt_test.aiff".standardizePath,
	options: ~server.options, duration: 15);

// or save the Score to a file
~score.saveToFile("~/nrt_test.txt".standardizePath);

// remove temporary Server
~server.remove;
)
::