Wwise SDK 2023.1.9

Due to some of the new features in 2023.1 (refer to New Features Overview 2023.1), there are several important things to be aware of before you migrate to Wwise 2023.1.

WwiseConsole Arguments Are Now Always Relative to the CWD

Previously, WwiseConsole's convert-external-source and generate-soundbank commands sometimes resolved arguments as paths relative to the project's directory. All paths passed to WwiseConsole are now resolved as relative to the console's current working directory.

Executable Location Changed

The executables previously located under Authoring/x64/Release/bin/Tools are now located in the same directory as Wwise.exe at Authoring/x64/Release/bin. If your project used the FilePackager as a SoundBank Post-Generation step, you must update the path to the FilePackager.Console.exe executable.

Low-Level I/O Hook Breaking Change

The Low-Level I/O Hook interface was changed significantly in 23.1 to improve the efficiency of streaming interfaces on high-latency devices such as Web applications. Also, a general refactor of the interface was done to integrate previous changes into a more coherent interface. The major changes that can break the game build are described in the following sections.

Removal of AK::StreamMgr::IAkIOHookBlocking and CAkDefaultIOHookBlocking

The blocking I/O hook sample has been removed. Although the blocking I/O calls were made in a separate thread, this prevented out-of-order execution of I/O calls, which added unnecessary latency to file access on some systems. If your game used this sample, replace it with CAkDefaultIOHookDeferred. The API is the same.

Interfaces Merged

The AK::StreamMgr::IAkLowLevelIOHook, AK::StreamMgr::IAkIOHookDeferred, and AK::StreamMgr::IAkIOHookDeferredBatch interfaces were merged into AK::StreamMgr::IAkLowLevelIOHook. Previously, these interfaces were separated to allow the "blocking" variant, but now that this isn't supported, there is no reason to maintain such divisions. If your I/O hook derived from IAkIOHookBlocking, IAkIOHookDeferred, or IAkIOHookDeferredBatch, replace it with IAkLowLevelIOHook and implement any missing functions.

AK::StreamMgr::IAkFileLocationResolver::Open() Function Replaced by AK::StreamMgr::IAkLowLevelIOHook::BatchOpen()

If the game already uses the default CAkDefaultIOHookDeferred sample class, this section is not relevant because all necessary changes were made to the sample.

If your game implements its own I/O hook or file location resolver, the most important change is the relocation and rename of AK::StreamMgr::IAkFileLocationResolver::Open() to the I/O device-specific interface. In the new interface, the AK::StreamMgr::IAkLowLevelIOHook::BatchOpen() function accepts multiple file open requests at the same time, instead of just one. It can either perform the operation immediately (synchronous) or dispatch it and notify later (asynchronous). Like the BatchRead() function, BatchOpen() now receives a callback function pointer to send a notification of the operation result. For more information about this change, refer to Deferred Opening.

If your game handles multiple I/O devices, be aware of the implementation of the new AK::StreamMgr::IAkFileLocationResolver::GetNextPreferredDevice function. For single-device games it can return AK_NotImplemented and the system behaves correctly. However, for multiple devices you must either use the CAkDefaultLowLevelIODispatcher sample or read more about the subject here: File Location Resolver

AkDeviceSettings.uSchedulerTypeFlags Removed

The uSchedulerTypeFlags member of AkDeviceSettings used in the creation of I/O devices is no longer used and has been removed. The associated AK_SCHEDULER_BLOCKING and AK_SCHEDULER_DEFERRED_LINED_UP constants have also been removed. If your code refers to any of these symbols, delete the associated code.

AkFileDesc Life Cycle Changes

The AkFileDesc structure that identifies a file for the Streaming Manager must now be created by the AK::StreamMgr::IAkLowLevelIOHook::BatchOpen() function, and deleted by the AK::StreamMgr::IAkLowLevelIOHook::Close() function.

AkFileDesc "Custom" Members Removed

The AkFileDesc::pCustomParam and AkFileDesc::uCustomParamSize members were removed because their usage was unclear when used in child classes of CAkDefaultIOHookDeferred. If your I/O hook needs to keep additional data along the AkFileDesc, derive from the base structure. As explained in the previous section, the I/O hook now creates and destroys AkFileDesc structures.

For I/O hooks that derive from the CAkDefaultIOHookDeferred sample, the AkFileDescType typedef is available for child classes to also derive the AkFileDesc type, and intermediate child classes, if necessary. Override the CAkDefaultIOHookDeferred::CreateDescriptor function as well to create the right type, if AkFileDesc is extended.

Removal of Mixer Plug-ins

As announced in Important Migration Notes 2022.1, Mixer plug-ins have been removed from Wwise 2023.1.

Updating Custom Mixer Plug-ins

You must convert Mixer plug-ins to Effect plug-ins:

The plug-in must implement the IAkOutOfPlaceObjectPlugin interface, which replaces the previous IAkMixerEffectPlugin interface.
Move the code that was previously located in the ConsumeInput function to the Execute function.
Replace the Attachables node in the plug-in XML file with a MetadataPlugin node. A MetadataPlugin node is a Plug-in Type Element.

Note: The in_objects.ppObjects[i]->arCustomMetadata contains the metadata that is passed to the function. This effectively replaces the removed GetInputParam function.

AK Channel Router Plug-in Migration

The AK Channel Router plug-in has been transformed from a Mixer plug-in to an Effect plug-in, which is inserted in the Effects tab of the Property Editor. The Effect can only be inserted on a bus that has its Bus Configuration set to Audio Objects.

The Audio Objects bus configuration has two notable properties:

Some Effects that were already present on the bus might be incompatible with this bus configuration. Refer to Using Effects with Audio Objects for more information.
This type of bus configuration cannot be applied to top-level busses.

The migration removes all instances of the Ak Channel Router Mixer plug-in but doesn't automatically replace them with an AK Channel Router Effect plug-in. You must manually add the AK Channel Router Effect to the appropriate busses. A new type of metadata, Channel Router Settings, replaces the existing AttachableMixerInput of the Ak Channel Router Mixer plug-in. The migration removes all instances of AttachableMixerInput and replaces them with the new metadata.

Deprecation of the Sample Subversion Source Control Plug-In

The sample Subversion source control plug-in has been deprecated and will be removed in a future version of Wwise.

Source Control Silent Mode

It is now possible to perform Source Control operations without a user interface. When Silent Mode is enabled, dialog boxes do not appear when WAAPI requests interact with Source Control. To implement this change, the AK::Wwise::ISourceControlProgress class (formerly AK::Wwise::ISourceControlOperationProgress) was redesigned. The following methods have been changed or added:

Renamed ShowProgress() method to BeginOperation()
Renamed OperationCompleted() method to EndOperation()
Added IsSilent() method
Added IsAutoCheckout() method

WAAPI Default Values

The autoAddToSourceControl argument is now true by default for the following WAAPI functions:

Note that because of issue WG-61743, the following functions already behaved as if autoAddToSourceControl were true by default in most cases:

The bypassSave argument is now true by default for the following WAAPI functions:

WAAPI Command Identifier Changes

The following command identifiers have been renamed:

WorkgroupAddWAV -> SourceControlAddWAV
WorkgroupAddWWU -> SourceControlAddWWU
WorkgroupCheckoutWAV -> SourceControlCheckoutWAV
WorkgroupCheckoutWWU -> SourceControlCheckoutWWU
WorkgroupCommitWAV -> SourceControlCommitWAV
WorkgroupCommitWWU -> SourceControlCommitWWU
WorkgroupDiffWAV -> SourceControlDiffWAV
WorkgroupDiffWWU -> SourceControlDiffWWU
WorkgroupRefreshIcons -> SourceControlRefreshIcons
WorkgroupRevertWAV -> SourceControlRevertWAV
WorkgroupRevertWWU -> SourceControlRevertWWU
WorkgroupUpdateWAV -> SourceControlUpdateWAV
WorkgroupUpdateWWU -> SourceControlUpdateWWU

Refer to Wwise Authoring Command Identifiers for more information.

(Spatial Audio) Revised Room and Portal Wet Path Signal Model

Attenuation, Occlusion, Obstruction, Transmission Loss, and Diffraction of the wet path are now applied to the Emitter-Room connection, using the attenuation specified on the emitter. Attenuation curves on Room Auxiliary Busses no longer have any effect and need to be moved to the source sound. The output of a Room Auxiliary Bus is always 0db unless modified in the project or through the API.

Diffraction on the wet path is now calculated per emitter, based on the paths between the emitter and the listener. Wet path diffraction cannot exceed dry path diffraction.

Geometric Transmission Loss now applies to the wet path, using the maximum Transmission Loss value of all surfaces intersected by the ray between the emitter and the listener. Room Transmission Loss is the minimum value between all possible paths from the emitter to the listener. The Transmission Loss for a single path is the maximum value of the Transmission Loss of all Rooms on that path.

Rays in the the Room-Listener connection are now only used for spatialization and do not contribute to the volume of the connection. Therefore, they no longer appear in the Voice Inspector.

An emitter that has the Enable Game-Defined Sends check box selected now sends to its own Room's bus as well as all adjacent Rooms that have active paths back to the listener. If an emitter is in the same Room as the listener, it sends to all adjacent rooms.

AkSpatialAudioInitSettings::uMaxEmitterRoomAuxSends has been added to limit the number of Emitter-Room connections to adjacent Rooms created per emitter. The default value of 0 disables the limit. If a limit is set, the most prominent sends are kept, based on spread to adjacent portals from the emitters perspective. A limit of 1 sends exclusively to the Room the emitter is in, and to the Room an emitter is transitioning to, while in a portal.

New AVAudioEngine-Based Sink for Apple Platforms

The System Audio Device in Wwise now supports AVAudioEngine for audio output to the system, which provides flexibility in channel configurations and synergy between macOS and iOS/tvOS platforms.

Consequently, AkPlatformInitSettings::eAudioAPI has been added for Apple platforms. The default value, AkAudioAPI_Default, automatically selects AVAudioEngine for operating systems that support it (macOS 10.15 or higher, and iOS/tvOS 13 or higher). Any Wwise installations that run on older operating systems continue to use the AudioUnit API, which only offers basic functionality.

Refer to Audio Output on Platforms for more information on the new behavior of the AVAudioEngine-based sink.

Additionally, on iOS/tvOS, AK::SoundEngine::GetPlatformInitSettings returns the Audio Session's default sample rate instead of a fixed 48000Hz.

Finally, on iOS/tvOS, the AudioInputCallbackFunc function signature has been updated to enforce const-ness on the audio buffers.

Because of this change, your application must now link with AVFoundation.framework.

AK::SoundEngine::Suspend No Longer Influences the State of AK::Comm

On some platforms, the AK::SoundEngine::Suspend() and AK::SoundEngine::WakeupFromSuspend() calls used to suspend and wake up the AK::Comm module automatically, and disconnected any connected Wwise Profilers. Now, clients must manage AK::Comm separately. Refer to Handling System-Specific Events to learn how to manage the AK::Comm module in the context of application lifecycle events for your supported platforms.

HF Damping Return Value Range Update

The range of the HF Damping value returned by AK::SpatialAudio::ReverbEstimation::EstimateHFDamping() has been doubled and is now -1 to 1. RTPCs mapped to this value now range from -1 to 1.

New Source Control Methods in SDK

The new ISourceControl::Connect() and ISourceControl::Disconnect() methods support source control login from the ak.wwise.core.sourceControl.setProvider WAAPI function. To ensure compatibility with this version of Wwise, you must add these methods to your ISourceControl and rebuild its plug-in.

If your source control implementation does not support connections, these methods return OperationResult_NotImplemented.

Using maxRadiusAttenuation and maxDurationSource in WAQL

It is no longer possible to use maxRadiusAttenuation and maxDurationSource in a WAQL query to refer directly to the object itself, for example when using "select". For those cases, please use the new accessors maxRadiusAttenuationObject and maxDurationSourceObject respectively.

Errors and warning during audio file import

When using ak.wwise.core.audio.import, it no longer reports an error through WAAPI when a warning or an error is found in the import log. The import log is now being returned by the call and should be parsed to detect import errors and warnings.

Was this page helpful?

Need Support?

Questions? Problems? Need more info? Contact us, and we can help!

Visit our Support page

Tell us about your project. We're here to help.

Get started with Wwise

Wwise SDK

Important Migration Notes 2023.1