In general, VST Plug-Ins present a flat, unsorted list of parameters to the host application, and finally to the user. The VST Parameters Structure XML definition provides an easy way to structure parameters of existing VST Plug-Ins hierarchically, without having to recompile the Plug-In binary.
Windows:
The host application searches for a .vstxml file next to the Plug-In DLL (e.g. if your Plug-In is in '...\Vstplugins\MyEffect.dll' the corresponding XML file must be named '...\Vstplugins\MyEffect.vstxml').
Alternatively, the Parameter Structure XML can be embedded in the DLL as a resource (resource type VSTXML, resource identifier 1).
Please note that an external .vstxml file always overrides the embedded resource!
Mac OS X:
The .vstxml file is in the Resources Folder of the bundle and its name is constructed from the CFBundleName.
Example:
<VSTPluginProperties> <VSTParametersStructure> <!-- Value Types: --> <ValueType name="SwitchOnOff"> <Entry name="Off" value="[0, 0.5["/> <Entry name="On" value="[0.5, 1]"/> </ValueType> <!-- Templates: --> <Template name="Channel"> <Param name="Bypass" shortName="Byp." type="SwitchOnOff" id="offset+1"/> ... </Template> <!-- Global: --> <Param name="Volume" shortName="Vol." label="dB" id="0"/> <Group name="Channel 1" template="Channel" values="offset=10"/> <Group name="Channel 2" template="Channel" values="offset=20"/> ... </VSTParametersStructure> </VSTPluginProperties> |
The following tags are used to describe a parameter structure:
VSTPluginProperties | optional root tag |
VSTParametersStructure | parameters structure tag |
Param | describes a single parameter with name, label, id etc. |
Group | encloses a group of parameters, can be nested |
Template | defines a parameter group, can be "instanciated" multiple times |
ValueType | definition of an internal value type, contains a list of Entry tags |
Entry | describes a single state of a ValueType |
Advanced topics:
<Param id="..." name="..."
label="..." shortName="..." type="..." numberOfStates="..." defaultValue="..."/>
|
Describes a Plug-In parameter.
Attributes:
id |
corresponds to zero-based index in flat parameter list. can either be an integer constant (e.g. "100") or an expression which evaluates to an integer (e.g. "offset + 1"). See Relative Parameter Addressing for details. |
name | parameter name visible to the user (e.g. "Volume"). |
label | parameter label visible in generic editor or on remote control (e.g. "dB") |
shortName |
short parameter name, displayed on remote controls. can be a list of several names of different lengths, separated by colons (e.g. "OSC Frequ., OSCFrq., Frq"). The host application selects best fitting string for current remote displays. |
type |
user defined (see ValueType)
or predefined value type. Default type is a linear fader between 0.0 and 1.0 Predefined types: - switch : parameter toggles between 0 and 1 |
numberOfStates |
defines how many states this parameter can have: state N = [N / numberOfStates, (N + 1) / numberOfStates[ state N = (long)(value * numberOfStates) |
defaultValue | default value normalized between [0.0, 1.0] |
Remarks:
Most VST Plug-Ins already provide parameter attributes like name, label, etc. and support string conversion. The XML description always overwrites Plug-In -provided attributes! Everything not described in XML is taken from the Plug-In at runtime.
<Group name="..." template="..." values="..."/>
|
Groups are used to create hierarchical parameter structures. A <Group> either contains <Param> tags directly, or is defined by a Template.
Attributes:
name | group name visible to the user (e.g. "Channel 1", "LFO Section",...) |
template | Name of template defining this group (optional). |
values |
List of arguments passed to the template
(see Relative Parameter Addressing for details). Each arguments consists of a name and an integer value (e.g. "offset=100"). Multiple arguments are separated by semicolons, whitespaces are ignored (e.g. "offset1=100; offset2=100"). |
<Template name="..."/>
|
Assume a Plug-In with 16 channels, each consisting of an identical set of parameters. You only have to describe a channel once as a template and create 16 "instances" using the <Group> tag. If each channel contains let's say 20 parameters, which appear continuously in the flat parameter list, they can be addressed using an offset value instead of absolute indices (see Relative Parameter Addressing for details).
Attributes:
name | internal template name, referred to by groups. |
<ValueType name="..." label="..."/>
|
Defines an internal value type by a list of <Entry> tags.
Attributes:
name | internal value type name, referred to by parameters. |
label | value label (e.g. "dB") |
Remarks:
The label attribute is used as parameter label if the label field of a <Param> tag using this value type is empty.
<Entry name="..." value="..."/>
|
Each entry in a <ValueType> list provides a string representation for a certain parameter state. A simple example would be a toggle parameter with two states named "On" and "Off". The string "Off" should be displayed if the normalized parameter value is between 0.0 and 0.5 (exclusively), and "On" if it is >= 0.5 and <= 1.0.
Attributes:
name | name of parameter state, displayed to the user (e.g. "On", "Off", "Sine", "Square",...) |
value |
optional: describes the parameter range this state corresponds to,
using the mathematical range definition [a, b]. Exclusive range: e.g. "[0.0,0.5[" -> if value >= 0.0 and < 0.5 Inclusive range: e.g. "[0.5,1.0]" -> if value >= 0.5 and <= 1.0 |
Remarks:
The value range is optional. If not specified, the limits of a state are calculated based on the total number of entries
in the value type:
a = index / total
b = (index + 1) / total;
Relative parameter addressing is used to describe parameter IDs inside templates. Instead of assigning a parameter index directly, an expression - mostly consisting of a "base address" variable and a constant offset value - can be used. The variable is passed to the template each time it is "instanciated" as a group.
Example:
Parameter list:
... 11: Volume CH1 ... 21: Volume CH2 ... 31: Volume CH3 ... |
XML code:
|
<!-- =========================================================== --> <!-- XML definition of VST parameters for Dynamics Plug-In====== --> <!-- Draft 0.1================================================== --> <!-- Date: 14.11.2005=========================================== --> <!-- =========================================================== --> <VSTPluginProperties> <VSTParametersStructure> <!-- Create Global Params================================== --> <Param name="Routing" shortName="Rout" id="13"/> <!-- Create AutoGate Group================================= --> <Group name="AutoGate"> <Param name="On" type="switch" id="0"/> <Param name="Thresh" shortName="ThrHo" label="dB" id="3"/> <Param name="Attack" shortName="Att" label="ms" id="4"/> <Param name="Hold" label="ms" id="5"/> <Param name="Release" shortName="Rel" label="ms" id="6"/> <Param name="Auto" id="7"/> <Param name="Mode" id="9"/> <Param name="Calib" id="10"/> <Param name="LowFreq" shortName="LoFrq" label="Hz" id="11"/> <Param name="HighFreq" shortName="HiFrq" label="Hz" id="12"/> </Group> <!-- Create Compressor Group======================================= --> <Group name="Compressor"> <Param name="On" type="switch" id="1"/> <Param name="Thresh" shortName="ThrHo" label="dB" id="14"/> <Param name="Ratio" id="15"/> <Param name="Attack" shortName="Att" label="ms" id="16"/> <Param name="Release" shortName="Rel" label="ms" id="17"/> <Param name="MakeUp" shortName="MkUp" label="dB" id="18"/> <Param name="Auto" id="19"/> <Param name="RMS" id="20"/> </Group> <!-- Create Limiter Group======================================= --> <Group name="Limiter"> <Param name="On" type="switch" id="2"/> <Param name="Thresh" shortName="ThrHo" label="dB" id="21"/> <Param name="Release" shortName="Rel" label="ms" id="22"/> <Param name="Auto" id="23"/> </Group> </VSTParametersStructure> </VSTPluginProperties> |