vst~ Reference

Host VST, VST3 and Audio Unit plug-ins

vst~

Description

Use the vst~ object to load a real-time VST, VST3 or Audio Unit plug-in and use its audio processing in MSP. When vst~ is instantiated as mcs.vst~, the plug-in's audio inputs are combined into a single multichannel inlet and its audio outputs are combined into a single multichannel outlet.

Examples

Process an audio signal with a plug-in

Discussion

Some plug-ins have their own editing window, which is visible when you double-click on the object. Otherwise, double-clicking on the object displays a default parameter editing window. The number of signal inputs and outputs default to 2, but the number required by the plug-in may be less than that. If you want to specify a larger number of inputs and outputs, you can supply them as optional arguments.
Audio plug-ins loaded into a vst~ object can be synchronized by enabling the global transport (choose GlobalTransport from the Extras menu and click on the global transport's Activate button).

Arguments

number-of-inputs/outputs [int]

Optional

If the first or first and second arguments are numbers, they set the number of audio inputs and outputs. If there is only one number, it sets the number of outlets. If there are two numbers, the first one sets the number of inlets and the second sets the number of outlets.

VST-plugin-filename [symbol]

Optional

Sets the name of a VST or Audio Unit plug-in file to load when the object is created. You can load a plug-in after the object is created (or replace the one currently in use) with the plug message.

preset-effects-name [symbol]

Optional

After the plug-in name, a name containing preset effects for the plug-in can be specified. If found, it will be loaded after the plug-in has been loaded.

Attributes

annotation_name [symbol] (default: )

Annotation Name

bypass [int] (default: 0)

Bypasses plug-in processing and passes all audio through the vst~ object.

enablehscroll [int] (default: 0)7.0.0

Enable Horizontal Scrollbar

enablevscroll [int] (default: 1)7.0.0

Enable Vertical Scrollbar

genericeditor [int] (default: 0)7.0.0

Use a generic editor interface for a plug-in. Note that some Audio Unit plug-ins will not show generic interfaces.

mcisolate [int] (default: 0)

Isolate parameter changes to a specified channel.

parameter_enable [int]

Enables use of this object with Max for Live Parameters and allows for setting initial parameter values in the Max environment.

prefer [symbol] (default: VST)

In the absence of other information, such as an absolute path to a plug-in file or an explicit typed plug-in path (e.g. C74_VST:/[pluginname], C74_VST3:/[pluginname], or C74_AU:/[pluginname] on OSX), the prefer attribute will be used to preferentially load one type of plug-in before other available formats when using the plug message. Note that the variations plug_vst, plug_vst3, and plug_au can also be used to override the specified preference.

Possible values:

'VST'
'VST3'
'AudioUnit'

valuemode [int] (default: 0)

Determines the output at the vst~ object's fifth-from-right outlet. In Value mode (the default: 0), the object will send the parameter's index followed by a floating-point value between 0. and 1. (e.g. 2 0.25). In String mode (1), the object will send the parameter's index followed by a symbol value (e.g. 2 -6dB). In Both mode (2), the object will send the parameter's index followed by a floating-point value and a symbol value (e.g. 2 0.25 -6dB).

Possible values:

0 = 'Value' ( Output parameter's normalized value (0. - 1.) )
1 = 'String' ( Output parameter's symbolic value )
2 = 'Both' ( Output parameter's normalized value followed by the symbolic value )

Common Box Attributes

annotation [symbol]

Sets the text that will be displayed in the Clue window when the user moves the mouse over the object.

background [int] (default: 0)

Adds or removes the object from the patcher's background layer. background 1 adds the object to the background layer, background 0 removes it. Objects in the background layer are shown behind all objects in the default foreground layer.

color [4 floats]

Sets the color for the object box outline.

fontface [int]

Sets the type style used by the object. The options are:

plain
bold
italic
bold italic

Possible values:

0 = 'regular'
1 = 'bold'
2 = 'italic'
3 = 'bold italic'

fontname [symbol]

Sets the object's font.

fontsize [float]

Sets the object's font size (in points).

Possible values:

'8'
'9'
'10'
'11'
'12'
'13'
'14'
'16'
'18'
'20'
'24'
'30'
'36'
'48'
'64'
'72'

hidden [int] (default: 0)

Toggles whether an object is hidden when the patcher is locked.

hint [symbol]

Sets the text that will be displayed in as a pop-up hint when the user moves the mouse over the object in a locked patcher.

ignoreclick [int] (default: 0)

Toggles whether an object ignores mouse clicks in a locked patcher.

jspainterfile [symbol]

JS Painter File

patching_rect [4 floats] (default: 0. 0. 100. 0.)

Sets the position and size of the object in the patcher window.

position [2 floats]

g/s(set)

Sets the object's x and y position in both patching and presentation modes (if the object belongs to its patcher's presentation), leaving its size unchanged.

presentation [int] (default: 0)

Sets whether an object belongs to the patcher's presentation.

presentation_rect [4 floats] (default: 0. 0. 0. 0.)

Sets the x and y position and width and height of the object in the patcher's presentation, leaving its patching position unchanged.

rect [4 floats]

g/s(set)

Sets the x and y position and width and height of the object in both patching and presentation modes (if the object belongs to its patcher's presentation).

size [2 floats]

g/s(set)

Sets the object's width and height in both patching and presentation modes (if the object belongs to its patcher's presentation), leaving its position unchanged.

textcolor [4 floats]

Sets the color for the object's text in RGBA format.

textjustification [int]

Sets the justification for the object's text.

Possible values:

0 = 'left'
1 = 'center'
2 = 'right'

varname [symbol]

Sets the patcher's scripting name, which can be used to address the object by name in pattr, scripting messages to thispatcher, and the js object.

Snapshot Attributes

autosave [int]

g/s(set)

When the containing patcher is saved, the state of this object's snapshots will also be saved.

Parameter Attributes

Order

Typeint

Sets the order of recall of this parameter. Lower numbers are recalled first. The order of recall of parameters with the same order number is undefined.

Parameter Mode Enable

Typeint

Parameter Mode Enable (not available from Parameters window)

Link to Scripting Name

Typeint

When checked, the Scripting Name is linked to the Long Name attribute.

Long Name

Typesymbol

The long name of the parameter. This name must be unique per patcher hierarchy.

Short Name

Typesymbol

Sets the short name for the object's visual display. The maximum length varies according to letter width, but is generally in a range of 5 to 7 characters.

Type

Typeint

Specifies the data type. The data types used in Max for Live are:

Float
Int
Enum (enumerated list)
Blob

Note: By convention, the Live application uses floating point numbers for its calculations; the native integer representation is limited to 256 values, with a default range of 0-255 (similar to the char data type used in Jitter). When working with Live UI objects whose integer values will exceed this range, the Type attribute should be set to Float, and the Unit Style attribute should be set to Int.

Range/Enum

Typelist

When used with an integer or floating point data type, this field is used to specify the minimum and maximum values of the parameter.
When used with an enumerated list (Enum) data type, this field contains a space-delimited list of the enumerated values (if list items contain a space or special characters, the name should be enclosed in double quotes).

Modulation Mode

Typeint

Sets the Modulation Mode used by the Live application. The modulation modes are:

None
Unipolar
Bipolar
Additive
Absolute

Modulation Range

Typelist

This parameter is only used with the Absolute modulation mode. It specifies defines the range of values used.

Initial Enable

Typeint

When checked (set to 1), the UI object can store an initialization value. The value is set using the Initial attribute (see below).

Initial

Typelist

Sets the initial value to be stored and used when the Initial Enable attribute is checked.

Unit Style

Typeint

Sets the unit style to be used when displaying values. The unit style values are: Int: displays integer values
Float: displays floating point values
Time: displays time values in milliseconds (ms)
Hertz: displays frequency values (Hz/kHz).
deciBel: displays loudness (dB)
%: Percentage
Pan: displays Left and Right values
Semitones: displays steps (st)
MIDI: displays pitch corresponding to the MIDI note number
Custom: displays custom data type
Native: defaults to floating point values

Custom Units

Typesymbol

Sets the units to be used with the 'Custom' unit style (see "Unit Style", above). Custom unit strings may be simple symbols (e.g. "Harmonic(s)"), in which case the parameter's value will be displayed in its 'Native' display mode, followed by the symbol (e.g. "12 Harmonic(s)" for an Int-typed parameter or "12.54 Harmonic(s)" for a Float-typed parameter). For additional control over the numerical component displayed, a sprintf-style string may be used (e.g. "%0.2f Bogon(s)", which would display a value such as ".87 Bogons").

Exponent

Typefloat

When set to a value other than 1., the parameter's input and output values will be exponentially scaled according to the factor entered in this column.

Steps

Typeint

The number of steps available between the minimum and maximum values of a parameter. For instance, if the parameter has a range from 0.-64., with Steps set to 4, the user can only set the parameter to 0, 21.33, 42.66 and 64.

Parameter Visibility

Typeint

For automatable parameters (Int, Float, Enum), 'Stored Only' disables automation, although parameter values are stored in presets. 'Hidden' causes the parameter's value to be ignored when storing and recalling data. Non-automatable parameters (Blob) are 'Stored Only' by default, and can be set to 'Hidden', if desired.

Update Limit (ms)

Typeint

Speed limits values triggered by automation.

Defer Automation Output

Typeint

Defers values triggered by automation.

Messages

int

Arguments

effect-program [int]
In left inlet: Changes the effect program of the currently loaded plug-in. The first program is number 1.

float

Arguments

effect-program [float]
In left inlet: Floating point values are converted to int values and used to change the effect program of the currently loaded plug-in. The first program is number 1.

list

Arguments

plugin-parameter [symbol]
setting [float]
In left inlet: Changes a parameter value in the currently loaded plug-in. The first list element is the parameter number (starting at 1) and the second element is the parameter value. The second number should be a float between 0 and 1, where 0 is the minimum value of the parameter and 1 is the maximum.

anything

Arguments

plugin-parameter [symbol]
setting [float]
A symbol that names a plug-in parameter followed by a float between 0 and 1 set the value of the parameter.

(drag)

When a plug-in file is dragged from the file browser to a vst~ object, the plug-in will be loaded.

(mouse)

Double-clicking on a vst~ object opens the plug-in's edit window.

disable

Arguments

mute-flag (0 or nonzero) [int]
The word disable, followed by a non-zero argument, stops any further processing by the currently loaded plug-in and outputs a zero signal. disable 0 enables processing for the plug-in.

get

Arguments

parameter-data-query-index or parameter-name [int or symbol]
The word get, followed by a number or symbol argument, reports parameter values and plug-in information. This is output from the fifth-from-right outlet of vst~ as a list with the query index (or plug-in info index) as the first element and the desired information as the second element.

If a symbol argument is provided, and the symbol corresponds to the name of a parameter, the get message outputs the current parameter value (a float between 0 and 1) of the named parameter. Otherwise, nothing is output.

If a number argument is provided, and the number argument is between 1 and the number of parameters of the currently loaded plug-in (inclusive), the get message outputs the current parameter value (a float between 0 and 1) of the numbered parameter. If the argument is 0 nothing is output.

If a negative number argument is provided, the get message outputs a list with the first element specifying the number argument and the remaining elements specifying the following information:

get -1 the plug-in's number of inputs
get -2 the plug-in's number of outputs
get -3 the plug-in's number of programs (VST) or factory presets (Audio Unit)
get -4 the plug-in's number of parameters
get -5 whether the plug-in's canMono flag is set. This indicates that the plug-in can be used in either a stereo or mono context
get -6 1 if the plug-in has its own edit window, 0 if it doesn't
get -7 1 if the plug-in is a synth plug-in, 0 if it isn't
get -8 the unique ID of the plug-in as an integer value
get -9 four integer values representing the left, top, right, and bottom coordinates of the desired rectangle of the plug-in UI edit window
get -10 an integer value representing the initial delay of the plug-in in samples to allow you to automatically compensate for the plugin's latency in your patch
get -11 the plug-in's number of user preset files (Audio Unit only)

getsubnames

In left inlet: When using the vst~ object to host a VST shell plug-in (e.g., WaveShell) that is not instantiated with a specific plug-in name, the word getsubnames causes a list of sub plug-in names to be sent out the second-from-right outlet of the vst~ object.

midievent

Arguments

MIDI-message (2 to 4 numbers) [list]
The word midievent, followed by two to four numbers, sends a MIDI event to the plug-in. The first three number arguments are the bytes of the MIDI message. The fourth, optional, argument is a detune parameter used for MIDI note messages. The value ranges from -63 to 64 cents, with 0 being the default.

mpeevent

Arguments

MPE-messages [list]
Send MPE messages to the hosted VST, VST3, or Audio Unit plug-in.

open

Arguments

window-coordinates [list]
The word open with no arguments opens the plug-in's edit window. If the window was previously opened then the edit window location will persist. The word open followed by two integer values specifying the left and top window coordinates respectively will open or move the plug-in's edit window to the given coordinates.

params

The word params causes a list of the plug-in's parameters to be sent out the sixth-from-right outlet.

pgmnames

The word pgmnames causes a list of the plug-in's current program names to be sent out the right outlet.

plug

Arguments

plug-in-name [symbol]
In left inlet: The word plug with no arguments opens a standard open file dialog allowing you to choose a new VST or Audio Unit plug-in to host. The word plug followed by a symbol argument searches for plug-in with the specified name in the Max search path. If a new plug-in is opened and found, the old plug-in (if any) is discarded and the new one loaded. An optional second argument to the plug message can be used to specify a plug-in name within a shell plug-in (e.g., WaveShell). This can either be a symbolic plug-in name or an associated ID value as displayed by the printids message).

For mc.vst~, if the attribute @mcisolate is set to 1, sending a plug message will allow the user to load a VST for each instance individually. When @mcisolate is set to 0, any plug message received loads that plug-in to all instances.

When the Max application starts up, the system VST folder will be added to the max search path. On the Macintosh this is generally /Library/Audio/Plug-ins/VST/ and on windows this is the folder specified in the VSTPluginsPath string value under the registry key HKLM\Software\VST. On Mac OS, Audio Unit plug-ins will be scanned and .auinfo files for Apple built-in and user-installed plug-ins will be added to the search path.

plug_au

Arguments

filename [list]
Attempt to load an AudioUnit plug-in by name. Equivalent to plug C74_AU:/<plug-in name>.

plug_vst

Arguments

filename [list]
Attempt to load a VST plug-in by name. Equivalent to plug C74_VST:/<plug-in name>.

plug_vst3

Arguments

filename [list]
Attempt to load a VST3 plug-in by name. Equivalent to plug C74_VST3:/<plug-in name>.

presetnames

For Audio Unit plug-ins only, the word presetnames causes a list of the plug-in's user preset filenames to be sent out the right outlet.

printids

In left inlet: When using the vst~ object to host a VST shell plug-in (e.g., WaveShell) that is not instantiated with a specific plug-in name, the word printids causes a list of sub plug-in IDs to be displayed in the Max Console.

read

Arguments

filename [symbol]
With no arguments, read opens a standard open file dialog prompting for a file of effect programs, either in bank or individual program format. read accepts an optional symbol argument where it looks for a VST plug-in bank or effect program file in the Max search path.

scan

Arguments

scan type [int]
Re-scan the system VST folders for new plug-ins. On the Macintosh this is generally /Library/Audio/Plug-ins/VST/ and on windows this is the folder specified in the VSTPluginsPath string value under the registry key HKLM\Software\VST. On Mac OS, Audio Unit plug-ins will be scanned and .auinfo files for Apple built-in and user-installed plug-ins will be added to the search path. The optional arguments 0, 1, 2, or 3, set the scan type to 0=default, 1=partial, 2=full, and 3=reset.

set

Arguments

effect-program-name [symbol]
In left inlet: The word set, followed by a symbol, changes the name of the current effect program to the symbol.

signal

Input to be processed by the plug-in. If the plug-in is an instrument plug-in, the input will be ignored.

subname

Arguments

plug-in-name [symbol]
In left inlet: The word subname, followed by a plug-in name or plug-in ID, will cause a shell VST plug-in (e.g., WaveShell) to be re-instantiated with the specified name/ID.

wclose

Closes the plug-in's edit window.

write

Arguments

file/pathname [symbol]
For VST plug-ins, with no arguments, write opens a standard Save As dialog box prompting you to choose the name and type of the effect program file (single program or bank). write accepts an optional symbol argument that specifies a full or partial destination pathname. An individual program file is written in this case. For Audio Unit plug-ins, the filename argument is required, and specifies the name of a user preset that will be written to a standard plug-in user preset location.

writebank

Arguments

program-bank-file/pathname [symbol]
With no arguments, writebank opens a standard Save As dialog box prompting you to choose the name of the effect program bank file. writebank accepts an optional symbol argument that specifies a full or partial destination pathname. For Audio Unit plug-ins, the writebank message is the same as write and saves only the current settings to a named file.

writepgm

Arguments

inividual-effect-program-file/pathname [symbol]
With no arguments, writepgm opens a standard Save As dialog box prompting you to choose the name of the individual effect program file. writepgm accepts an optional symbol argument that specifies a full or partial destination pathname. For Audio Unit plug-ins, the writepgm message is the same as write and saves the current settings to a named file.

Snapshot Messages

snapshot7.0.0

Arguments

file-name [symbol]
Create a snapshot. When embedsnapshot is on it will be saved into the current patcher. Otherwise it will be saved in an external file. You can determine the filename by an argument to this message.

restore7.0.0

Arguments

file-name [symbol]
Restore a snapshot. When embedsnapshot is on, the snapshot that is embedded in the current patcher will be used. Otherwise it will be loaded from an external file. You can determine the filename by an argument to this message.

addsnapshot

Arguments

userpath [String]
index [Number]
name [String]
Add a new snapshot. If there are no arguments, it will append the new snapshot to the current list of snapshots. If the first argument is a string containing a file path, Max will try to save a .maxsnap file to that location. If the first argument is a number, it will save the snapshot to that slot, incrementing subsequent slots. If the second argument is a string, it will set the name of the snapshot.

deletesnapshot

Arguments

index [Number]
Delete a snapshot at the given index, decrementing subsequent slots.

exportsnapshot

Arguments

index [Number]
filename [String]
Exports a snapshot from the given index, specified by the first argument. The second argument specifies the file name and path to export a maxsnap file to. If the second argument is empty, a File dialog box will open, allowing you to specify a file name and location.

importsnapshot

Arguments

index [Number]
filename [String]
Imports a snapshot to the given index, specified by the first argument. The second argument specifies the file name and path to load a maxsnap file from. If the second argument is empty, a File dialog box will open, allowing you to choose a file.

setsnapshotname

Arguments

index [Number]
name [String]
Set the name of the snapshot at the given index.

setembedsnapshot

Arguments

index [Number]
embedstate [Number]
Set the embed state of the snapshot at the index.

movesnapshot

Arguments

srcindex [Number]
dstindex [Number]
Change a snapshot's index.

Output

float

Out fifth-from-right outlet: Parameter values or plug-in informational values in response to the get message.

int

Out fifth-from-right outlet: Parameter values or plug-in informational values in response to the get message.

Out fourth-from-right outlet: Raw MIDI bytes received by the plug-in (but not any MIDI messages received using the midievent message).

list

Out second-from-right outlet: When a VST shell plug-in (e.g., WaveShell) is instantiated without specifying a plug-in name, a list of symbols specifying sub plug-in IDs are sent out the seventh outlet in response to the printids message.

signal

Out left outlet (and other signal outlets as defined by the number of outputs argument): Audio output from the plug-in. The left outlet is the left channel (or channel 1).

symbol

Out sixth-from-right outlet: The plug-in's parameters are sent out as a series of symbols in response to the params message.
Note: Some plug-ins, especially those with their own editors, fail to name the parameters.

Out third-from-right outlet: A series of symbols are sent out in response to the pgmnames message. If there are no program names, the message pgmnames: Default is output.

Out second-from-right outlet: When a VST shell plug-in (e.g., WaveShell) is instantiated without specifying a plug-in name, a series of symbols specifying plug-in names are sent out the seventh outlet in response to the getsubnames message.

Out right outlet: An Audio Unit plug-in's user preset files are sent out as a series of symbols in response to the presetnames message.

See Also

Name Description
Sound Processing Techniques Sound Processing Techniques
MIDI MIDI
MC MC
rewire~ Host ReWire devices
amxd~ Host Max for Live devices