Wwise SDK 2023.1.9

The open architecture of Wwise supports three kinds of plug-ins: source plug-ins, which generate sounds; effect plug-ins, which enhance sounds; and source control plug-ins, which enable the use of source control software within Wwise. The first two kinds of plug-ins use an XML plug-in description file which allows you to quickly change some of the settings of your plug-in, including default property values, without having to recompile the code. A Wwise plug-in DLL can contain multiple plug-ins, each of which must be described in the associated XML file. The XML description file for each Wwise plug-in DLL must have the same name as the DLL, except for the XML file extension. For example, if your DLL is named "MyPlugin.dll", then the plug-in description file must be named "MyPlugin.xml".

The Wwise open architecture also allows to define custom properties for Wwise objects. In much the same way as defining plug-ins, Wwise properties are controlled through XML descriptions. Refer to Defining Custom Properties for more information.

Properties Element

<Properties>
    ...
</Properties>

The Properties section defines the properties and references of your plug-in. Property and Reference elements will be ordered in the user interface as they are in the XML.

The properties correspond to the controls, such as sliders and check boxes, that can be manipulated by the user in your plug-in's user interface, and to the values that the sound engine plug-in code can use to make its computations.
The references correspond to fields containing a reference to a Wwise object. For example, a reference could point to a Game Parameter object defined in the project.

A Property is typically defined as follows:

<Property Name="GainBand1" Type="Real32" SupportRTPCType="Exclusive" DataMeaning="Decibels" DisplayName="Band 1 Gain">
    <UserInterface Step="0.5" Fine="0.1" Decimals="1" />
    <DefaultValue>0</DefaultValue>
    <AudioEnginePropertyID>1</AudioEnginePropertyID>
    <Restrictions>
        <ValueRestriction>
            <Range Type="Real32">
                <Min>-24</Min>
                <Max>24</Max>
            </Range>
        </ValueRestriction>
    </Restrictions>
    <Dependencies>
        <PropertyDependency Name="OnOffBand1" Action="Enable">
            <Condition>
                <Enumeration Type="bool">
                    <Value>1</Value>
                </Enumeration>
            </Condition>
        </PropertyDependency>
    </Dependencies>
</Property>

A Reference is typically defined as follows:

<Reference Name="OutputGameParameter" DisplayName="Output Game Parameter">
    <Restrictions>
        <TypeEnumerationRestriction>
            <Type Name="GameParameter" />
        </TypeEnumerationRestriction>
    </Restrictions>
</Reference>

The Property and Reference elements can contain several attributes:

Name [Property, Reference] (type:string, mandatory): This is the string ID used in the Wwise plug-in to identify the property. It is used in the following places:

Binding of properties to controls: This is the name you must specify in your plug-in's dialog resources (Prop=<Property Name>) to bind the control to this property.
Persistence: This is the name that will appear in the Property element in Wwise Project files to persist data related to this property.

Caution: Never change the name of an existing property. Projects using your plug-in will lose any value, randomizer, or RTPC the user might have set on that property.
in_szPropertyName parameter in:
- AK::Wwise::Plugin::NotificationsPropertySet::NotifyPropertyChanged()
- AK::Wwise::Plugin::PropertyDisplayName::DisplayNameForProp()
- AK::Wwise::Plugin::PropertyDisplayName::DisplayNamesForPropValues()

Note: The Property Name is not a name that appears in the UI, but you should still make it meaningful because a user might see it in a Project file. The name that appears in the UI is specified by the DisplayName attribute.

Note: When defining custom properties, the Name attribute must be prefixed with "Custom:". Refer to Defining Custom Properties for more information.

DisplayName [Property, Reference] (type: string, default: empty): Defines the display name of the Property, to be displayed at many places in Wwise. This attribute supersedes the function AK::Wwise::Plugin::PropertyDisplayName::DisplayNameForProp.
DisplayGroup [Property, Reference] (type: string, default: empty): Defines a slash separated path used to organize properties or references in a Tree. Ex: "Audio/HDR"
IsVisible [Property, Reference] (type: boolean, default: true, optional): Default value is true. If absent, the property will be visible in generic editors. Set the IsVisible to false when the property and its value are not meaningful for the user or you don't want the user to see or modify it in generic editors (for example, in the List View).
Type [Property] (mandatory): This is the property type. Possible values are:
- bool: Boolean
- int16: 16-bit integer
- Uint16: 16-bit unsigned integer
- int32: 32-bit integer
- Uint32: 32-bit unsigned integer
- int64: 64-bit integer
- Uint64: 64-bit unsigned integer
- Real32: Single-precision float (32-bit)
- Real64: Double-precision float (64-bit)
- string: UTF-8, null-terminated character string
Plug-ins write properties to SoundBanks using the AK::Wwise::Plugin::DataWriter service, which supports writing any of the types listed above. Strings are serialized as null-terminated UTF-8 c-strings. Bool values are serialized as 1-byte values, where 1 stands for true and 0 for false.
In the case of custom properties added to a Wwise project, the values supported in SoundBanks are restricted to:
- int32: 32-bit integer
- Real32: Single-precision float (32-bit)
The bool type can still be used as custom properties, however values are interpreted as int32 where 1 stands for true and 0 for false. However, custom properties typed as Strings are not exported to SoundBanks because they cannot be represented numerically.
SupportLink [Property, Reference] (type: boolean, default: false, optional): Defines if the Property or Reference supports the Link/Unlink functionality.
SupportStates [Property] (type: boolean, default: true, optional): Defines if the Property supports State mapping to control its value. Note that State mapping is only supported if the property also defines SupportRTPCType as either Additive or Boolean.
SupportRTPCType [Property] (type: string, default: undefined, optional): If not specified, the property will not support RTPCs. If specified, possible values are:
- Additive: The value computed from the RTPC curve will be added to the base property value of the object and to other RTPCs on the same property.
- Multiplicative: The value computed from the RTPC curve will be multiplied by the base property value of the object and by other RTPCs on the same property.
- Exclusive: The value computed from the RTPC curve has exclusive control over the property's value, completely overriding the value set in the property's control within the dialog. (That control will be disabled to make it clear to the Wwise user that it does not have any effect on the property.)
- Boolean: Equivalent logical operations are applied to enable or disable boolean properties. This attribute also enables State mapping to affect the property's value when the RTPC type is either Additive or Boolean.
ForceRTPCCurveSegmentShape [Property] (type: string, default: undefined, optional, used with SupportRTPCType): Restricts the possible segment shapes used in RTPC curves on this property. If not specified, then the user has the freedom to change the shape of any segment within the curve. If specified, possible values are:
- Constant: All segments in the curve will use constant interpolation (between two adjacent points, the Y value is the same as that of the left-most point of the pair). Use this when the property represents discreet values such as booleans or enumerations.
DataMeaning [Property] (type: string, default: undefined, optional): If defined, specifies that the property represents some special type of data, such as decibels.

Possible values are:
- Decibels: This property represents decibels. RTPC curves will use decibel scaling by default, though the user has the option to change between decibel and linear scaling. Decibel scaling affects the way values are interpolated between points. For example, if you have a point at 0 dB and one at -96.3 dB, a linear curve segment evaluated exactly between the two points will produce a value of -48.15 dB when using linear scaling, and around -6 dB when using decibel scaling (corresponding to a halving of amplitude).
- Frequency: This property represents a frequency in Hz. Frequency scaling affects the way values are interpolated between points. For example, if you have a point at 1000 Hz and one at 4000 Hz (two octaves above), a linear curve segment evaluated exactly between the two points will produce a value of 2500 Hz when using linear scaling, and a value of 2000 Hz (one octave above) when using frequency scaling.

Note: If you want the sound or effect produced by your plug-in to be set by the Wwise user, and not change during a game, do not set it to support RTPCs.

The DefaultValue element specifies the default value for a property. This default value represents the initial value when creating new instances, and value to which the property is reset when the user clicks on the property's control while holding the CTRL key. This value must match the type (as specified with the Type attribute in the Property element) and range (below) of the property.

Tip: XML files can be edited with any text or XML editor. They are located in the same folder as the plug-in DLLs, in the "plugins" folder under the main Wwise installation folder. Wwise users who have custom plug-ins can edit the XML file for their plug-ins to change the default value of a plug-in property without recompiling the plug-in. Developer expertise is not required to make this change.

The AudioEnginePropertyID element identifies this property in the Sound Engine. It must be a positive integer in the range 0-32767, except for the wcustomproperties file, in which case the range must be 0-150. The value you set in the AudioEnginePropertyID element corresponds to the AkFXParamID parameter in AK::IAkEffectParam::SetParam(), so make sure you keep your property IDs in sync between your implementation of AK::IAkEffectParam::SetParam() and your plug-in description file.

UserInterface

The UserInterface element defines attribute that relates to user interface behavior and appearance. The following attributes are all optional and can be set on the UserInterface element:

DisplayName (type: string, default: empty): (Deprecated) Defines the display name of the Property, to be displayed at many places in Wwise. This attribute is replaced by the DisplayName attribute defined in the Property or Reference element.
Decimals (type: integer, default: 0): Defines the number of digits to display after the decimal point. This value must be a non-negative integer number. If set to 0, then no decimal digits and no point will be displayed.
Step (type: float, default: 1): Defines the amount by which the numeric value changes when moving a slider. This value can be an integer or decimal number, depending on the type of property the control is bound to.
Fine (type: float, default: 1): Defines the amount by which the numeric value changes when moving a slider while holding the SHIFT key. This value can be an integer or decimal number, depending on the type of property the control is bound to.
SliderType (type: integer, default: 0): Defines the mapping of the values across a slider range.
- 0: Linear (default)
- 1: Pseudo-Logarithmic, from -96.3 dB to 0 dB
- 2: Pseudo-Logarithmic, from -96.3 dB to 96.3 dB
- 4: Pseudo-Logarithmic, from 20 Hz to 20000 Hz
- 5: Pseudo-Logarithmic, from 20 Hz to 12000 Hz
- 6: Pseudo-Logarithmic, from -96.3 dB to 12 dB
- 11: Pseudo-Logarithmic, from 0.02 Hz to 20000 Hz
- 12: Pseudo-Logarithmic, from 0.02 Hz to 20 Hz
- 15: Pseudo-Logarithmic, from -24 dB to 24 dB
- 16: Pseudo-Logarithmic, from -96.3 dB to 24 dB
Mid (type: float, default: 0): Defines the value in the [min,max] range that is considered neutral. This value affects the drawing of a slider control.
UIMin (type: float, default: Range's Min): Defines the minimum value that can initially be set by using the slider. If this value is greater than the one specified with the Min attribute, then the user can force it to a lower value by entering a value that is smaller than the one specified by this attribute, thus enlarging the range of the control.
UIMax (type: float, default: Range's Max): Defines the maximum value that can initially be set by using the slider. If this value is lower than the one specified with the Max attribute, then the user can force it to a larger value by entering a value that is larger than the one specified by this attribute, thus enlarging the range of the control.
AutoUpdate (type: boolean, default: false): Defines if the value is updated while moving a slider. Set this attribute to false when updating the value too often because of audio performance glitches.
LRMixDisplay (type: boolean, default: false): Defines if the value is shown as a special Left-Right balance range style. The value range must be between -100 and +100 and map to a Left to Right balance/mix, where 0 is the Center.
ControlClass (type: string, default: empty): Defines the user interface control that must be used for the property in views such as the List View or the Multi Editor. Possible values are:
- ColorPicker: A color picker.
- ReadOnlyText: The value of the property is read-only in the user interface.
DropDown (type: string, default: empty): When used with a numerical enumeration (for example, Enumeration of type int16), this allows you to specify how each value of the Enumeration will be represented in the menu. Possible values are:
- Menu: Displays a shortcut menu for the corresponding enum values instead of a drop down. The path of the menu is defined by the DisplayName of the Value in the Enumeration. For example, a DisplayName of value "/Bus Volume/Reset Bus Volume" will display a menu with Bus Volume in which the submenu Reset Bus Volume, once clicked, will set the property to the value 14.
- CurveIn: For corresponding values 0 to 8, it displays a curve (positive slope) for the following functions: Logarithmic (Base 3), Sine, Logarithmic (Base 1.41), Inverted S-Curve, Linear, S-Curve, Exponential (Base 1.41), Reciprocal Sine, and Exponential (Base 3).
- CurveOut: For corresponding values 0 to 8, it displays a curve (negative slope) for the following functions: Logarithmic (Base 3), Sine, Logarithmic (Base 1.41), Inverted S-Curve, Linear, S-Curve, Exponential (Base 1.41), Reciprocal Sine, and Exponential (Base 3).

Tip: The purpose of the UIMin and UIMax attributes is to make the initial range of the control's slider more usable in cases where the property range is really big. If one of your properties has a big theoretical range, but in general users will use a more restricted range, use the Min/Max attributes to set the real range, and the UIMin/UIMax attributes to set the initial range of the slider.

Restrictions

The Wwise XML descriptions can specify Property Restrictions and Reference Restrictions.

Property Restrictions

A property can optionally have any of the two following restrictions for its data values.

In a Range restriction (Restrictions/ValueRestriction/Range section), you can define the range of numeric properties.

<Restrictions>
    <ValueRestriction>
        <Range Type="Real64">
            <Min>0</Min>
            <Max>100</Max>
        </Range>
    </ValueRestriction>
</Restrictions>

In an Enumeration restriction (Restrictions/ValueRestriction/Enumeration section), you can define a list of possible values and the display name for each one.

<Restrictions>
    <ValueRestriction>
        <Enumeration Type="int32">
            <Value DisplayName="Low Pass">0</Value>
            <Value DisplayName="High Pass">1</Value>
            <Value DisplayName="Band Pass">2</Value>
            <Value DisplayName="Notch">3</Value>
            <Value DisplayName="Low Shelf">4</Value>
            <Value DisplayName="High Shelf">5</Value>
            <Value DisplayName="Peaking">6</Value>
        </Enumeration>
    </ValueRestriction>
</Restrictions>

bool and string properties do not need a range. This range is used in various places in Wwise, such as the RTPC Curve Editor, to define the range of the graph on the Y-axis.

The format of this file is described formally in the Plugin.xsd XML Schema file found in the "/Authoring/Data/Schemas" folder under the main Wwise installation folder.

Reference Restrictions

A reference can optionally have a list of any of the following restrictions for referenced objects:

TypeEnumerationRestriction: Defines a list of valid Wwise object types for the reference.

<Restrictions>
    <TypeEnumerationRestriction>
        <Type Name="GameParameter" />
        ...
    </TypeEnumerationRestriction>
</Restrictions>

Type Name can be: ActorMixer, RandomSequenceContainer, SwitchContainer, BlendContainer, Sound, Bus, Event, SwitchGroup, Switch, State, GameParameter, MidiParameter, SoundBank, Effect, MusicSegment, MusicTrack, MusicTrackSequence, MusicPlaylistContainer, MusicSwitchContainer, Trigger, Attenuation, DialogueEvent, MotionBus, MotionFX, Conversion, AuxBus, ModulatorLfo, ModulatorEnvelope.

CategoryEnumerationRestriction: Defines a list of valid Wwise object categories for the reference.

<Restrictions>
    <CategoryEnumerationRestriction>
        <Category Name="AudioObjects" />
        ...
    </CategoryEnumerationRestriction>
</Restrictions>

Category Name can be: Busses, AudioObjects, Events, Switches, States, SoundBanks, GameParameters, Effects, AudioDevices, Presets, SoundcasterSessions, MixingSessions, Queries, InteractiveMusic, Triggers, Attenuations, DynamicDialogue, Conversions, Modulators, ControlSurfaceSessions.

PlayableRestriction: Defines if the object must be playable.

<Restrictions>
    <PlayableRestriction />
</Restrictions>

NotNullRestriction: Defines if the object must not be null.

<Restrictions>
    <NotNullRestriction />
</Restrictions>

Dependencies

Properties or references can have zero or many dependencies. Dependencies allow to link properties together, so a property can be enabled or disabled based on the value of another property.

Please note the dependencies are currently only used in the following contexts:

Property Editor - All Properties tab
Default User Interface for Effects (but not sources)
List View
Multi Editor
Query View
Reference View

The dependencies are not being used in the Effect Editor if you implement your own user interface by providing a dialog in AK::Wwise::Plugin::AudioPlugin::GetDialog(). Enabled or disabled States must be implemented in the user interface of the plug-in.

The following example adds a dependency from "GainBand1" to "OnOffBand1". The "GainBand1" property will be enabled when "OnOffBand1" is set to "True".

<Property Name="GainBand1" ...>
    <...>
    <Dependencies>
        <PropertyDependency Name="OnOffBand1" Action="Enable">
            <Condition>
                <Enumeration Type="bool">
                    <Value>True</Value>
                </Enumeration>
            </Condition>
        </PropertyDependency>
    </Dependencies>
</Property>

The Condition element can either contain an Enumeration element or a Range element. The Action attribute specified in the PropertyDependency element must be "Enable". It specifies the property will be enabled when the condition is matching.

Enumeration condition:

<Enumeration Type="int32">
    <Value>0</Value>
    <Value>1</Value>
</Enumeration>

Range condition:

<Range Type="Real32">
    <Min>-24</Min>
    <Max>24</Max>
</Range>

Additionally, a Context attribute can be specified on a PropertyDependency to change the object on which the Condition will be evaluated. The Context attribute can be set to either "Parent" or "Self", and defaults to "Self" when it is not explicitely given.

Continuing from the previous example, adding a context to the PropertyDependency will cause the "GainBand1" property to be enabled when "OnOffBand1" is set to "True" on the parent of the current object.

<Property Name="GainBand1" ...>
    <...>
    <Dependencies>
        <PropertyDependency Name="OnOffBand1" Action="Enable" Context="Parent">
            <Condition>
                <Enumeration Type="bool">
                    <Value>True</Value>
                </Enumeration>
            </Condition>
        </PropertyDependency>
    </Dependencies>
</Property>