Table of Contents
Wwise SDK 2021.1.1
In Wwise 2021.1, we are introducing a new API for the Authoring part of plug-ins that brings about a number of changes. This migration guide will cover those changes and provide information to help you update your plug-in code to use this new API.
Note: The new Authoring Plug-in API can be found under
In 2021.1, the plug-in API has been rewritten with a few goals in mind. The main goals are to provide a better default design that separates concerns between the backend and frontend implementations, to offer better support for backward compatibility and to minimize the requirements when creating a plug-in. These goals have been accomplished in the following ways:
- The backend and frontend of a plug-in are separate entities where a backend can exist for multiple frontends. In the context of Wwise, the responsibilities of the backend have to do with model management and bank generation, while the frontend deals with the graphical user interface (GUI) and providing monitoring feedback to the user. This separation also means that only the backend portion of a plug-in needs to be instantiated in the context of a command-line session, which has a positive effect on performance. If no frontend is provided, a default one is generated at runtime.
AK::Wwise::IAudioPluginclass has been split into smaller interfaces that are all versioned. Plug-ins are now able to request and provide services to the Authoring application by requesting service instances and implementing specific interfaces. Because there are fewer dependencies for typical plug-ins and the Authoring application has knowledge of the interface versions used, adapters for previous versions can be implemented to support them in future Wwise versions. Also, when interfaces are no longer supported, users can be informed of unsupported plug-ins. A consequence of this design is that plug-in makers will need to update their plug-ins less often to support newer Wwise versions.
- The Authoring plug-in API adopted an architecture that is based on a C API and does not depend on toolset and platform-specific structures such as Windows SDK
VARIANT. Plug-in dynamic libraries expose a simple C-defined structure that, for every plug-in, describes its components and provides pointers to implementations. For convenience, a C++ API reproducing the features of the original API produces these lower-level structures at compile time.
- Registration of plug-ins has been simplified and is now embedded in the concept of a "plug-in container", which is a structure that has descriptors of all the plug-ins of a library. Plug-in classes are added to this container and the Sound Engine portion of the plug-in is automatically registered during the construction of this global container. Only a few macros are needed to expose an Authoring plug-in: this is detailed in the Library Plug-in Container section.
In addition to the aforementioned new features, some functions have been reworked for clarity.
|Note: The Sound Engine part of the plug-in does not adopt the same design, retaining the approach of previous versions.|
A few methods that were deemed obsolete were removed from the API in 2021.1. Some other methods were not removed, but reworked by renaming and/or changing their arguments to make them clearer or easier to use.
AK::Wwise::IAudioPlugin::SetPluginPropertySet(): Removed (obsolete)
AK::Wwise::IAudioPlugin::SetPluginObjectStore(): Removed (obsolete)
AK::Wwise::IAudioPlugin::SetPluginObjectMedia(): Removed (obsolete)
AK::Wwise::IAudioPlugin::Destroy(): Removed (obsolete)
AK::Wwise::IAudioPlugin::IsPlayable(): Removed (unused)
AK::Wwise::IAudioPlugin::GetPluginMediaConverterInterface(): Removed. Replaced by a standalone
AK::Wwise::Plugin::CustomData::InitFromInstance(): Renamed, argument changed. The logic has been reversed to resemble other
Initmethods as they are mutually exclusive.
Not listed are methods that have had non-optional pointer arguments changed to references.
It is likely that your plug-in uses a subset of the features provided by the Authoring plug-in API. Each of the following sections covers the changes related to a specific feature: refer to the appropriate section based on your plug-in's usage of the API. For more advanced features of the Authoring plug-in API, refer to Common Use Cases for Requests.
|Note: This section refers to pre-2021.1 as the "original" API, and to 2021.1 and up to the "new" API.|
In the original API, the
AK::Wwise::IAudioPlugin interface contained all the features of the Authoring plug-in API. You could simply subclass
AK::Wwise::DefaultAudioPluginImplementation to empty implementations for each method, but your class still had all of these unused methods defined.
In the new API, there is a similar
AK::Wwise::Plugin::AudioPlugin interface, but its only method is
AK::Wwise::Plugin::AudioPlugin::GetBankParameters(). For a simple plug-in that has typical properties being written to a SoundBank, implementing this single interface is all that is needed. Implementing this interface also serves as an indicator that the implementing class is a backend class (as opposed to a frontend class, which is covered in the Implementing a Frontend section).
Concretely, there are few differences between an original and a new API class:
Notice that there is only a single method left to implement:
GetBankParameters. The AK::Wwise::IAudioPlugin::Destroy() function is also not necessary anymore, as instantiation and destruction is completely handled by the plug-in API. The standard C++ destructor can be use to release resources.
You may have noticed that the function
AK::Wwise::IAudioPlugin::SetPluginPropertySet() has been removed in the previous section's code example. Indeed, this function is not needed anymore thanks to the
AK::Wwise::Plugin::AudioPlugin interface that requests the property set component for you. By subclassing
AK::Wwise::Plugin::AudioPlugin interface adds a
PropertySet component requirement to the plug-in description, which will be fulfilled by the Authoring application when the plug-in is instantiated. It also adds a member variable
m_propertySet that will automatically be set to the
PropertySet component instance at instantiation. This removes the need to manually create this member variable and implement its corresponding setter.
Implementing a simple Authoring plug-in with only
GetBankParameters is therefore simplified:
Some key differences:
DataWriterargument is now a reference, as it is not optional (cannot be NULL)
- The property set is accessed through the inherited member variable
- The character string for the property name passed to the
AK::Wwise::Plugin::PropertySet::GetReal32()is of type
const char*, instead of
- The type of the property (here, Real32) is specified explicitly in the method signature of the
AK::Wwise::Plugin::PropertySetaccessors for consistency with
All of these changes make implementing this function simpler, safer and more portable.
AK::Wwise::Plugin::AudioPlugin provides the minimum implementation for SoundBank generation. However, providing only this part of the plug-in means there is no custom GUI to display, and so the Authoring application will generate one that looks similar to the Multi-Editor view.
As previously hinted, the
AudioPlugin class represents the backend of the Authoring plug-in: it can be used in a command-line context (without a GUI) and implements any custom data or state management. To display a custom GUI, a new class needs to be created that will be attached to the same plug-in identifier. This class will be instantiated separately from the backend class.
The frontend class is implemented by subclassing a frontend interface. Due to the nature of GUIs, these are permitted to be platform specific. Hence, the
AK::Wwise::Plugin::GUIWindows interface, to which the original frontend-related methods were moved, can be subclass for providing a custom plug-in GUI on Windows.
Note: If you intend to use MFC, you should also subclass
In a frontend class, you must not subclass
AK::Wwise::Plugin::AudioPlugin or implement any backend related logic, such as property value adjustments or operations affecting the result of a SoundBank generation. The frontend should be solely responsible for displaying properties and monitoring data in a user-friendly way, and update the plug-in model based on user input.
If the backend does not need to make any adjustments to values supplied by the user, the frontend can simply request the
PropertySet component by subclassing
AK::Wwise::Plugin::RequestPropertySet. However, if the backend does any value adjustments on properties, for example to implement dynamic property ranges, this should be implemented in the backend.
If the backend offers some implementations that the frontend requires, it can request the
LinkBackend service by subclassing
AK::Wwise::Plugin::RequestLinkBackend. It will provide the frontend class with a
m_backend instance representing the backend instance to which it is bound.
The reverse is also possible, where a backend class can request
LinkFrontend by subclassing
AK::Wwise::Plugin::RequestLinkFrontend. One big difference for
LinkFrontend is that there can be multiple frontends for one backend: the
m_frontend instance inherited therefore represents an array of frontends. The size of the array can be obtained by the
GetArray method and a
ForEach function is offered for convenience.
PropertySet component request is made implicitly by the
AK::Wwise::Plugin::AudioPlugin interface because it is typically needed in the context of
AK::Wwise::Plugin::AudioPlugin::GetBankParameters(), other components and services are optional and can be requested manually by subclassing any of the available
AK::Wwise::Plugin::Request[...] classes (refer to Request Components and Services). When the plug-in provides an implementation to the Authoring application, the interface is not prefixed by
Request. For example, this is the case for
The following is a list of common use cases in the original API and the corresponding services that need to be requested to obtain the same features in the new API.
Monitoring data sent by the Sound Engine counter-part of the plug-in is received through the
NotifyMonitorData method. This method has been moved to a notification interface. Subclass
AK::Wwise::Plugin::Notifications::Monitor to implement this method.
In the original API, to provide a custom handler for licensing you had to implement
AK::Wwise::IAudioPlugin::GetLicenseStatus. This function has been moved to a separate interface: subclass
AK::Wwise::Plugin::License to implement this method.
Plug-in data meant to be handled as media, typically audio files that can be encoded during a source conversion process, could be supported by implementing
AK::Wwise::IAudioPlugin::GetPluginMediaConverterInterface(). These, along with the management of media objects, have been centralized in the
AK::Wwise::Plugin::ObjectMedia. Object media methods are implemented directly inside the plug-in class. The media converter, which is still optional, is a separate interface to implement:
Refer to Adding Media to an Audio Plug-in for details on how to use these interfaces.
All plug-in data that are not managed through the PropertySet or ObjectMedia components have been centralized in a common interface
AK::Wwise::Plugin::CustomData. While most methods are the same,
CopyInto has been reworked to reverse its logic.
Init functions are mutually exclusive: one of them will be called when the plug-in is initialized depending on the context where it is loaded.
Make sure to apply this logic reversal when porting a plug-in using Custom Data to the 2021.1 Authoring Plug-in API.