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.
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).
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.
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 themessage.
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.
annotation_name [symbol] (default: )
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.
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. prefer attribute will be used to preferentially load one type of plug-in before other available formats when using the message. Note that the variations , , and can also be used to override the specified preference.
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. ). In String mode (1), the object will send the parameter's index followed by a symbol value (e.g. ). In Both mode (2), the object will send the parameter's index followed by a floating-point value and a symbol value (e.g. ).
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
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.adds the object to the background layer, 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.
Sets the type style used by the object. The options are:
0 = 'regular'
1 = 'bold'
2 = 'italic'
3 = 'bold italic'
Sets the object's font.
Sets the object's font size (in points).
hidden [int] (default: 0)
Toggles whether an object is hidden when the patcher is locked.
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.
patching_rect [4 floats] (default: 0. 0. 100. 0.)
Sets the position and size of the object in the patcher window.
position [2 floats]
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]
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]
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.
Sets the justification for the object's text.
0 = 'left'
1 = 'center'
2 = 'right'
When the containing patcher is saved, the state of this object's snapshots will also be saved.
Multichannel Group Attributes
The chans attribute sets the number of channels and instances in the MC wrapper object. If you want a fixed number of channels regardless of what is connected to the object, you could set chans via a typed-in argument, for example typing would create 100 instances of a cycle~ object inside the MC wrapper. If chans is 0, the wrapper object will auto-adapt to the number of channels in its input multichannel signals (using the maximum of all connected signals). For objects without connected multichannel signals, the chans attribute will need to have a non-zero value if you want more than one instance.
If chans is changed while the audio is on, the number of instances will not updated until audio is restarted. However, if chans is reduced while the audio is on, any extra channels will no longer process audio and will output a zero signal.
The values attribute only applies to object creation time so it must be set via typed-in argument syntax. values sets the first (and only the first) initial argument for successive instances in the MC wrapper. For example, typing would assign an initial frequency to the cycle~ instances inside the wrapper. The first instance would be assigned a frequency of 50, the second a frequency of 60, the third 70, and the fourth 80. Note that values does not determine the actual instance count; this can be done using the chans attribute. If there are more instances than elements for the values attribute, those instances are instantiated with the default value.
If you want to set a default initial value for all instances, simply type it as an argument before any typed-in attributes. For example, modifying our example above: . In this example, the first four instances are set as before, but the next six are created with a frequency argument of 100.
To change instance values or attributes after the wrapper object has been created, use the , , or messages.
When replicate is enabled, input single-channel or multichannel signals containing fewer channels than the number instances in the MC wrapper object are repeated to fill all input channels. For example, when replicate is enabled and you connect a two-channel multichannel signal to the input of an MC wrapper object with four instances, channel 1 of the input will be repeated to channel 3, and channel 2 of the input will be repeated to channel 4. If replicate were disabled, channels 3 and 4 of the input would be set to zero.
The target attribute sets a voice index for targeting specific wrapper instances. Subsequent messages are directed to an individual instance instead of all instances. It is strongly recommended you use the more reliable message instead of the target attribute. The voice index of will override the current setting of target. When target is 0, incoming messages are sent to all instances. When target is -1, incoming messages do nothing.
When usebusymap is enabled, the MC wrapper controls whether individual instances process audio using a busy map maintained by either an mc.noteallocator~ or mc.voiceallocator~ object. When a channel in the busy map is marked as "free" or "released" no audio processing occurs by any instance on the channel corresponding to the voice index. When usebusymap is disabled, instances in the MC wrapper process audio at all times. This will also be true if usebusymap is enabled and there is no local or named busy map available. (See the busymapname attribute for a description of local and named busy maps).
When the zero attribute is enabled, channels in the MC wrapper due to the use of a busy map output zero signals. To save a small amount of CPU at the risk of loud and unpleasant noises due to uncleared signal data, you can disable zero. In this case, disabled channels in the MC wrapper do nothing to their output channels. If usebusymap is disabled or there is no active local or named busy map available, the setting of the zero attribute has no effect.
Conveniently, when usebusymap is enabled in mc.mixdown~ object, disabled channels are not mixed to the output. When unused signals from wrapped objects with zero disabled feed into mc.mixdown~, they will be ignored, reducing the risk of unpleasantness getting past the mix output.
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
Parameter Mode Enable (not available from Parameters window)
Link to Scripting Name
When checked, the Scripting Name is linked to the Long Name attribute.
The long name of the parameter. This name must be unique per patcher hierarchy.
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.
Specifies the data type. The data types used in Max for Live are:
Enum (enumerated list)
Note: By convention, the Live application uses floating point numbers for its calculations; the native integer representation is limited to a range of 0-255 (similar to the char data type used in Jitter). When working with Live UI objects whose integer values are likely to be outside of the 0-255 range, the Type attribute should be set to Float, and the Unit Style attribute should be set to Int.
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).
Sets the Modulation Mode used by the Live application. The modulation modes are:
This parameter is only used with the Absolute modulation mode. It specifies defines the range of values used.
When checked (set to 1), the UI object can store an initialization value. The value is set using the Initial attribute (see below).
Sets the initial value to be stored and used when the Initial Enable attribute is checked.
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)
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
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").
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.
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.
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)
Speed limits values triggered by automation.
Defer Automation Output
Defers values triggered by automation.
If a symbol argument is provided, and the symbol corresponds to the name of a parameter, the 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 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 message outputs a list with the first element specifying the number argument and the remaining elements specifying the following information:
the plug-in's number of inputs
the plug-in's number of outputs
the plug-in's number of programs (VST) or factory presets (Audio Unit)
the plug-in's number of parameters
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
1 if the plug-in has its own edit window, 0 if it doesn't
1 if the plug-in is a synth plug-in, 0 if it isn't
the unique ID of the plug-in as an integer value
four integer values representing the left, top, right, and bottom coordinates of the desired rectangle of the plug-in UI edit window
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
the plug-in's number of user preset files (Audio Unit only)
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.
Multichannel Group Messages
message arguments [list]
high channel [int]
message arguments [list]
Out fifth-from-right outlet: Parameter values or plug-in informational values in response to themessage.
Out fifth-from-right outlet: Parameter values or plug-in informational values in response to the
Out fourth-from-right outlet: Raw MIDI bytes received by the plug-in (but not any MIDI messages received using the message).
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 themessage.
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).
Out sixth-from-right outlet: The plug-in's parameters are sent out as a series of symbols in response to the
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 message. If there are no program names, the message 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 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 message.
|rewire~||Host ReWire devices|
|amxd~||Host Max for Live devices|