Wwise SDK 2023.1.8

The open architecture of Wwise supports different kinds of plug-ins:

Audio plug-ins, including:
- Source plug-ins, which generate sounds
- Effect plug-ins, which transforms sounds
- Sink plug-ins, which output sounds to some medium
Source Control plug-ins, which enable the use of source control software within Wwise

Audio Plug-ins describe their model in the form of an XML file. This allows you to quickly change any of the settings of your plug-in, including default property values, without having to recompile the code. Properties described in this model are also used to provide a default graphical interface in the form of a properties table in Wwise if no custom GUI is provided by the plug-in.

Overview of the XML File

The XML description file contains information about several aspects of a Wwise plug-in, including:

Plug-in name
Company ID and plug-in ID. Refer to Wwise Plug-in IDs for more information.
Feature supported for each platforms
Property definitions, including:
- Property name (string used to identify the property in the code and persisted files)
- Property type
- RTPC support
- Default value
- Sound engine property ID (binding this property to the code in the sound engine plug-in)
- Range restrictions or enumeration restrictions
- Dependencies on other properties
- User Interface description elements
Inner Object Types definitions, including:
- Inner Object Type name (string used to identify the inner object type)
- Inner Object Properties

When using the wp.py development tool, a default XML file is provided and is pre-filled with the information you provided at creation time. Refer to Creating Audio Plug-ins for more details.

Note: A Wwise plug-in dynamic library can contain multiple plug-ins (see Authoring Plug-in Library Format), each of which must be described in a single associated XML file.

Naming of the XML File

The XML description file for each Wwise plug-in dynamic library must have the same name as the dynamic library, except for the XML file extension and any lib prefix.

For example, if your dynamic library is named "MyPlugin.dll" or "libMyPlugin.dylib", then the plug-in description file must be named "MyPlugin.xml".

Example: XML Description File

Below is an example of a simple plug-in XML description file.

XML Description File Specific Parts

Let's look at the various parts of the XML file in detail.

XML Description File Header

Let's look at the parts of this XML file's header and discuss them in detail.

The first line of any XML file defines the XML version and encoding. In this case, the XML version is 1.0, and the encoding is UTF-8. The first line of any Wwise plug-in description file should always be exactly like the one above. The second line is an XML comment, in this case a copyright notice. You can introduce comments in various places in the XML file wherever necessary.

PluginModule Element

The main XML element in this document is named PluginModule, and encloses all of the information for the various plug-ins defined in the file.

Plug-in Type Elements

In the category of Audio plug-ins, there are four possible plug-in type elements:

SourcePlugin
EffectPlugin
SinkPlugin
MetadataPlugin

The EffectPlugin element is the main element for the definition of a single effect plug-in, while SourcePlugin, SinkPlugin and MetadataPlugin are the element names for source plug-ins, sink plug-ins and metadata plug-ins, respectively.

Note: If more than one plug-in is implemented in the dynamic library, the XML file will contain multiple plug-in elements. A dynamic library is not limited to a single type of audio plug-in.

These elements contain three required attributes:

Name (mandatory): This string specifies the display name of the plug-in as it will appear in Wwise.
CompanyID (mandatory): This string must represent a positive integer in the range 0-4095 (see wwiseplugin_xml_id_specification)
PluginID (mandatory): This string must be a positive integer in the range 0-32767. Each PluginID must be unique for a specified CompanyID.

Two optional attributes can be specified:

SupportsIsSendModeEffect (optional): (Effect plug-in only) This boolean value indicates if the plug-in supports the send mode by querying AK::IAkEffectPluginContext::IsSendModeEffect() during the initialization part. When IsSendModeEffect() returns true, the plug-in should not output the dry signal and should ignore the dry level properties.
EngineDllName (optional): This string value overrides the name of the Sound Engine dynamic library to load at game runtime (by default it will be the same name as the XML). If EngineDllName is specified, ensure that both of your Sound Engine static and dynamic libraries share the same name. Providing a DLL/so file with your plug-in is necessary to be supported in commercial game engines such as Unity and Unreal 4. This does not affect the naming of the Authoring plug-in dynamic library, which should strictly correspond to the name of your XML file.

Company and Plug-in IDs

Wwise associates plug-in model definitions and plug-in implementations using numeral IDs. These IDs are provided in the XML description of each plug-in and in the plug-in descriptor in the plug-in library.

The CompanyID is an ID corresponding to your organization. Three ranges exist:

0-63: Reserved for Audiokinetic, not available.
64-255: Unrestricted range for in-house use. A Company ID in this range cannot be used for external distribution.
256-4095: Restricted range for commercial plug-ins. These are assigned by Audiokinetic to official third-party developers. If you were assigned one of these, use it instead of a value in the 64-255 range. If not, do not use these values.

The PluginID is a unique numeral ID in the range 0-32767 that corresponds to a plug-in within a single organization.

For example, if you are developing plug-ins for in-house use only, you can pick any CompanyID between 64 and 255, and any three PluginIDs between 0 and 32767. The numbers need not be sequential.

The CompanyID and PluginID need to be passed to the Sound Engine plug-in declaration macro AK_IMPLEMENT_PLUGIN_FACTORY.

Caution: Important considerations:

You should never change the CompanyID or PluginID of an existing plug-in. Projects using this plug-in will no longer recognize it. The CompanyID and PluginID are persisted with each plug-in instance, and are used to recreate an instance of the right plug-in when the file is loaded.
If two or more PluginIDs are identical for the same CompanyID, Wwise will display an error message on startup. If this happens, change the ID for the new plug-in.
If you base your plug-in on a sample plug-in provided by Audiokinetic (Sample Plug-ins), don't forget to change the CompanyID and PluginIDs to appropriate values. Use your assigned official CompanyID if you have one, or a number between 64 and 255 if you don't. Make sure no PluginIDs are repeated for that CompanyID.

For more details on IDs, refer to Wwise Plug-in IDs.

PluginInfo Element

The PluginInfo/PlatformSupport section defines the platforms supported by your plug-in. It can contain one or more Platform elements, each of them specifying the various features supported by a plug-in on each platform. The following features can be specified:

CanBeInsertOnBusses determines whether the effect can be applied to control and master busses. Typically this will require the effect to support surround audio configuration.
CanBeInsertOnAuxBusses determines whether the effect can be applied to control and master auxiliary busses. Typically this will require the effect to support surround audio configuration. Note that if CanBeInsertOnBusses is already set, the effect is already available on Aux busses.
CanBeInsertOnAudioObjects determines whether the effect can be applied as insert to SFX (must support both mono and stereo processing).
CanBeRendered determines whether the effect can be used for offline rendering or not.
CanSendMonitorData determines whether the effect can send monitoring data. Refer to AK::Wwise::Plugin::Notifications::Monitor::NotifyMonitorData for more information.
CanBeSourceOnSound determines whether source plug-in can be a source for a sound.
CanBeInsertEndOfPipeline determines whether the effect can only be added at the end of the audio pipeline, which corresponds to the last effect slot of a top-level Audio Bus (reserved for Audiokinetic).

Your plug-in will be available only on the specified platforms within Wwise.

It is also possible to add the "Any" platform instead of listing every supported platform. Be aware though, this plug-in will then be advertised as being available on all platforms in Wwise and, if the plug-in does not provide the matching runtime libraries, the user will only notice it when porting it on this platform.

Metadata PluginInfo Element

For a metadata plug-in, it is important to set the MenuPath="Metadata" attribute to the PluginInfo node as such:

Properties Element

Each audio plug-in can define properties and references. For more information about properties and references, refer to Properties XML Description.

Inner Objects

The InnerTypes section defines the possible Inner Object Types that you can instantiate and use inside your plug-in. You can define multiple InnerType inside the InnerTypes section. Each InnerType must have a unique name, and plug-in ID. The InnerType section contains a Properties section, in which you can define properties in the exact same way you would define plug-in properties.

The Inner Types are practical whenever you need to have multiple instances of an object in your plug-in. For example, you could define the Inner Type Band for an EQ plug-in, when you have a variable number of EQ bands. Each band would have the same property definition, with different values for each band.

Note: The properties of Inner Types do not support RTPCs. Therefore, you can't use the SupportRTPCType attribute and AudioEnginePropertyID element.

Note: InnerTypes are only supported inside audio plug-ins.

To manipulate the Inner Type instances (Inner Objects) in your plug-in code, you need to request the service by deriving AK::Wwise::Plugin::RequestObjectStore in your plug-in class and using the AK::Wwise::Plugin::ObjectStore m_objectStore member. The AK::Wwise::Plugin::ObjectStore interface provides functions for creating and deleting inner objects (AK::Wwise::Plugin::ObjectStore::CreatePropertySet and AK::Wwise::Plugin::ObjectStore::DeletePropertySet). Inner Objects' properties are manipulated using the PropertySet interface (see Property Set).

When objects are created, they must be stored in a named list using the insertion (AK::Wwise::Plugin::ObjectStore::InsertPropertySet) and removal (AK::Wwise::Plugin::ObjectStore::RemovePropertySet) functions. For example, you could create an inner object of type Band, and store it in the BandList:

Note: An inner object can only be stored in a single list at any one time.

The persistence in the project Work Units is automatically handled by Wwise. However, you must implement the serialization of the inner objects in the SoundBanks and for the Sound Engine data. You must serialize the inner objects inside AK::Wwise::Plugin::CustomData::GetPluginData and AK::Wwise::Plugin::AudioPlugin::GetBankParameters.

When you add inner objects to the object store, the associated Undo mechanism is automatically created in Wwise. You don't need to implement the undo system on your side. However, to support undo events correctly, you need to update your user interface only at the reception of notifications from the framework.

Inner Objects Notifications

The interface AK::Wwise::Plugin::NotificationsObjectStore provides handlers to override that allow to act on notification events related to inner objects. These are primarily meant to update custom GUI elements on model changes that could be triggered by a user interaction, an undo event or even a WAAPI call.

For example, after calling AK::Wwise::Plugin::ObjectStore::InsertPropertySet, do not update the UI right-away. Wait for the notification AK::Wwise::Plugin::NotificationsObjectStore::NotifyInnerObjectAddedRemoved to be called on your plug-in. This notification tells you that an object was added or removed from a list.

Similarly, you can react on AK::Wwise::Plugin::NotificationsObjectStore::NotifyInnerObjectPropertyChanged, which is called when the value of a property changes in an inner object.