Version
menu_open
Warning : Some protected information on this page is not displayed.
Ensure you are logged in if you are a licensed user for specific platforms.
Wwise SDK 2023.1.8
Important Migration Notes 2021.1

As a consequence of some of the new features in 2021.1, you will need to pay attention to a few things when migrating to Wwise 2021.1.

Spatial Audio

Wwise Spatial Audio has standardized the usage of the term transmission loss to define an occlusion factor due to sound transmission through rooms or through geometry, both in the API and in the Authoring tool. Consequently, AkRoomParams::WallOcclusion has been renamed to AkRoomParams::TransmissionLoss, and AkAcousticSurface::occlusion has been renamed to AkAcousticSurface::transmissionLoss.

In an effort to simplify the design and implementation of physically plausible sound propagation, all options to enable diffraction and transmission processing have been combined into a single option.

  • In the Positioning tab, Enable Diffraction has been renamed to Enable Diffraction and Transmission.
  • The initialization setting bEnableTransmission has been removed; transmission simulation is always enabled for sounds that have Enable Diffraction and Transmission selected in the Authoring tool. If sound transmission is not expected to play a significant role in your game, use the default transmission loss coefficient of 1.0 for all rooms and geometries, and use the default occlusion curve, which renders a transmission loss coefficient of 100% inaudible.

Furthermore, to simplify the setup of Spatial Audio, the following fields of AkSpatialAudioInitSettings have changed:

  • AkDiffractionFlags has been removed with the following substitutions:
    • DiffractionFlags_UseBuiltInParam is effectively always true. The Diffraction built-in parameter can now be used without explicit configuration.
    • DiffractionFlags_UseObstruction has been replaced by a boolean, AkSpatialAudioInitSettings::bUseObstruction, with the same logic.
    • DiffractionFlags_CalcEmitterVirtualPosition has been replaced by a boolean, AkSpatialAudioInitSettings::bCalcEmitterVirtualPosition, with the same logic.
  • bEnableDirectPathDiffraction has been renamed to AkSpatialAudioInitSettings::bEnableGeometricDiffractionAndTransmission to provide a more accurate description of the option.
  • fDiffractionShadowAttenFactor and fDiffractionShadowDegrees have been removed. These options were complicated to use and not recommended for physically plausible sound rendering.

3D Audio

In Wwise versions 2019.2 and prior, the built-in System Audio Device supported up to 7.1 channels of audio. It was necessary to use a variety of plug-ins to go beyond this limit and access the 3d audio output capabilities available on certain platforms.

In Wwise 2021.1, these plug-ins have been incorporated into the System Audio Device. Combined with the newly introduced Audio Objects Bus Configuration, this greatly simplifies the management of 3d audio output.

The following sections serve as a guide to migrate a Wwise project using the now-deprecated 3d audio plug-ins, and benefit from the improvements in 2021.1.

Plug-in Equivalences

Platform-specific documentation describes the old plug-ins and explains where the equivalent functionality is found in Wwise 2021.1.

Microsoft Spatial Sound Platform Output [deprecated]

Migrating

Into A Single Output

A Wwise project using a dual-output strategy to split Spatial and Passthrough mixes should be modified to use a single System Audio Device instead, which can now produce both mixes from a single Audio Object stream.

Let the Objects Flow

Instances of the 3d audio mixer plug-ins should be removed and replaced with the use of the Audio Objects Bus Configuration, allowing the Audio Objects to flow to the top bus and into the System Audio Device. Use of the Same as parent Bus Configuration is recommended in order to automatically inherit the Audio Object configuration from the System Audio Device when operating in 3D Audio mode.

Any non-3d mono or stereo stream will be automatically directed to the Passthrough Mix by the System Audio Device. It is possible to force any other type of object to be sent to the Passthrough Mix by setting the Mix Behavior to Mix To Passthrough in the Wwise System Output Settings Metadata.

Embrace Automatic Configuration

Use of game-side logic was necessary to detect 3d audio and properly switch between Headphone and Surround mode: for example, binding “Bypass all” and “Passthrough objects” object panner settings.

The System Audio Device now performs this detection and automatically enables Audio Objects and Passthrough Mix based on whether or not 3D audio is active. It is also possible to pick separate configurations for the Main Mix when targeting Headphones or Surround. Finally, any bus can inherit from the Main Mix or Passthrough Mix using the Same as main mix or Same as passthrough mix Bus Configurations.

A Practical Example

In the Wwise SDK Integration Demo, there is a new page demonstrating the target setup described in the previous sections.

Refer to: Positioning Demo > 3D Audio Objects and Spatialized Bed.

Legacy Wwise Command Line Interface (WwiseCLI) End-of-Life Announcement

We announce that Wwise 2021.1 will be the last major version to support the legacy Wwise command line interface, known as WwiseCLI.exe. Minor versions of 2021.1 will also support it, but future major versions won't include it. Refer to Using the Command Line to learn more about the Wwise Console, which replaces the legacy Wwise command line interface.

SoundFrame End-of-Life Announcement

We announce that Wwise 2021.1 will be the last major version to support the SoundFrame. Minor versions of 2021.1 will also support it, but future major versions won't include it. Refer to Using the Wwise Authoring API (WAAPI) to learn more about the Wwise Authoring API (WAAPI), which replaces the SoundFrame.

Migrating from a Wwise Version Earlier Than 2013.1

Support has been removed for the migration of Wwise projects from versions earlier than 2013.1. It remains possible to migrate such projects to 2021.1 by first migrating to 2019.2.

WAAPI Changes That Affect Backward Compatibility

Calling ak.wwise.core.object.get with an unknown property in the return options used to give no result. It now generates a WAAPI error. Please note that this error will occur when using a property that is not defined in the XML. It will not generate an error when using a known property on an object that does not support it.

C++14 Compiler is Now Required

The Wwise SDK headers and source now require C++14 to compile properly. See Platform Requirements for a list of supported compilers.

Height Spread

Spread and Focus curves are now evaluated against the real distance between the emitter and listener, while they used to be evaluated against the distance of the emitter-listener vector projected on the plane defined by the listener's top vector.

The old behavior typically increased the spread of 3D sounds passing above or below the listener, and thus helped smooth out their panning on planar speaker configurations (5.1, 7.1, and so on). Unfortunately, this behavior is not very realistic with panning on 3D configurations like binaural stereo or 7.1.4. For example, a 3D sound flying by would suddenly become omnidirectional as it passed over the listener.

In order to evaluate Spread based on the real distance without losing the smoothing effect when panning on planar configurations, a new property called Height Spread has been introduced. It automatically computes a minimal spread based on elevation, if and only if panning occurs on a planar configuration, or based on negative elevation alone if panning occurs on hemispherical configurations, like 7.1.4.

The property is true by default, and is located in the Attenuation Editor. You may opt out of this behavior by deselecting the check box. If there is no attenuation on the sound, you will need to create an Attenuation ShareSet specifically for this purpose, with a flat Output Bus volume curve.

Renaming of Secret Platforms

The new, previously-secret platforms have been renamed to PlayStation 5 and Xbox Series X. If you had one of these platforms in your Wwise project already, a migration step will be performed to rename them from the codename they had before to "PS5" and "XboxSeriesX". If your definitions for the platforms, such as name, GeneratedSoundBanks, and ExternalSourceFilePaths, were set to their default values, then they will be automatically renamed as well, where appropriate.

The PlayStation 5 platform, previously referred to by the codename "Pellegrino", is now known as "PS5". The following should be noted in particular:

  • AK_PELLEGRINO has been renamed to AK_PS5.
  • AK::IAkPellegrinoContext has been renamed to AK::IAkPS5Context.

Microsoft Game Core platforms have been renamed:

  • The Xbox One Game Core platform, previously referred to by the codename "GX" is now known as "XboxOneGC".
  • The Xbox Series X|S platform, previously referred to by the codename "Chinook", is now known as "XboxSeriesX".
  • Elements of the Microsoft Game Core software that are shared across the Xbox line of consoles are referred to as "XboxGC".
  • The Windows Game Core platform, previously referred to by the codename "GDX", is now known as "WinGC".

The following should be noted in particular:

  • AK_CHINOOK has been renamed to AK_XBOXSERIESX.
  • AK_XBOXONEGC now defines Xbox One Game Core.
  • AK::IAkGXContext has been renamed to AK::IAkXboxGCContext.

Support for XAudio2 and DirectSound

Microsoft platforms now only support WASAPI. Support for XAudio2 and DirectSound has been discontinued for 2021.1.

AkAudioAPIWindows has been removed. AkPlatformInitSettings::eAudioAPI has been removed for Windows.

Memory Manager Changes

Falign and ReallocAligned

AK::MemoryMgr::Falign and AK::MemoryMgr::dFalign have been removed. Memory allocated with AK::MemoryMgr::Malign (or dMalign) can now be freed using AK::MemoryMgr::Free (or dFree) or reallocated using AK::MemoryMgr::ReallocAligned or (dReallocAligned).

Memory Manager Debugging

  • AkMemDebugCheckForOverwrite has been removed in favor of AkMemSettings::uMemoryDebugLevel, which can now be used to check for overwrite and memory stomps.
  • New memory functions are available for debugging: AkCrtAllocator* and AkStompAllocator*

Plug-in Memory Allocator

  • IAkPluginMemAlloc::Malloc and IAkPluginMemAlloc::Malign now take a file name and line number to track memory allocations. Note that this is handled automatically by the AK_PLUGIN_ALLOC and AK_PLUGIN_ALLOC_ALIGN macros, and it is recommended to use those macros where appropriate.
  • AK_PLUGIN_REALLOC and AK_PLUGIN_REALLOC_ALIGN have been added and call IAkPluginMemAlloc::Realloc and IAkPluginMemAlloc::ReallocAligned, respectively.
  • IAkPluginMemAlloc:dMalloc and IAkPluginMemAlloc::dMalign have been removed. The debug version of these functions will now be called automatically according to AkMemSettings::uMemoryDebugLevel.

MIDI API Changes

The MIDI API functions have seen several additions. These additions are:

  • AK::SoundEngine::PostMIDIOnEvent has parameters more akin to PostEvent:
    • Returns playing ID
    • Specifies optional playing ID (to use an existing one)
    • Can specify callback function, with flags and cookie
  • Offsets specified in AkMIDIPost can now be relative (as before), or absolute. This is specified via a new parameter to PostMIDIOnEvent.
  • A new type of AkMIDIEvent: AK_MIDI_EVENT_TYPE_WWISE_CMD. This provides Wwise specific MIDI events:
    • AK_MIDI_WWISE_CMD_PLAY
    • AK_MIDI_WWISE_CMD_STOP
    • AK_MIDI_WWISE_CMD_PAUSE
    • AK_MIDI_WWISE_CMD_RESUME
    • AK_MIDI_WWISE_CMD_SEEK_MS
    • AK_MIDI_WWISE_CMD_SEEK_SAMPLES
  • The returned playing ID can be used with existing playing ID functions (e.g. ExecuteActionOnPlayingID).

IAkGlobalPluginContext::PostMIDIOnEventSync and IAkGlobalPluginContext::StopMIDIOnEventSync have been updated to reflect this API change.

Miscellaneous API Changes

Some unused platform-specific alignment defines have been removed:

  • AK_ALIGN
  • AK_ALIGN_DMA
  • AK_ALIGN_FASTDMA
  • AK_ALIGN_SIZE_FOR_DMA
  • AK_OS_STRUCT_ALIGNED
  • AK_64B_OS_STRUCT_ALIGNED
  • AK_ALIGN_ACM

AK/SoundEngine/Platforms/Android/AkAndroidSoundEngine.h:

  • Unused AkPlatformInitSettings::uChannelMask has been removed.

AK/SoundEngine/Common/IAkPlugin.h:

  • IAkEffectPluginContext::GetNodeID(), IAkSourcePluginContext::GetNodeID(), and IAkMixerPluginContext::GetBusID() have been replaced with IAkPluginContextBase::GetAudioNodeID().
  • IAkMixerInputContext::GetAudioNodeID has been removed.
  • IAkGlobalPluginContext::MixNinNChannels, Mix1inNChannels, MixChannel were moved to a plug-in service: IAkPluginServiceMixer (IAkPluginService of type PluginServiceType_Mixer).

AK/SoundEngine/Common/AkSpeakerConfig.h: AK/SoundEngine/Common/AkCommonDefs.h:

  • AkChannelConfig::IsChannelConfigSupported() has been removed.
  • AkAudioFormat::IsChannelConfigSupported has been removed.

AK/Wwise/Utilities.h:

  • AK::Wwise::IWriteData::WritePascalString has been deprecated in favor of AK::Wwise::IWriteData::WriteUtf16String

Wwise Authoring Plug-in API Changes

Wwise 2021.1 marks the release of a brand-new Wwise Authoring Plug-in API. This rewritten API addresses some issues enabling many features of the Wwise Authoring application, such as frontend separation and backward compatibility. Dependencies on platform and toolset-specific features have also been greatly reduced. The new API can be found under <Wwise>/SDK/include/AK/Wwise/Plugin.

A dedicated migration guide covers the main steps in porting your plug-in to the new API. Refer to Migrating to 2021.1 Authoring Plug-in API.

Note: The new C++ API requires a C++17 capable compiler.

To ease the transition, the previous "original" API is still offered in Wwise 2021.1 at the same location (<Wwise>/SDK/include/AK/Wwise) and plug-ins built with it are supported by Wwise 2021.1. However, it is now marked as legacy and will not receive updates in future releases of Wwise. All plug-in developers are encouraged to migrate their plug-in to this new API.

The Sound Engine Plug-in API, e.g., <Wwise>/SDK/AK/SoundEngine/Common/IAkPlugin.h, remains current and is not considered legacy. The new API only covers the Wwise Authoring side of a Wwise plug-in. Refer to Overview of a Plug-in for more details.

The final changes to the original API for Wwise 2021.1 are as follows:

  • The signature of AK::Wwise::IAudioPlugin::NotifyMonitorData has changed to support a new timestamp argument, provided in milliseconds. This is in conjunction with the new Meter History feature that allows metering at all times.
  • The functions AK::Wwise::IWriteData::WriteUtf16String and AK::Wwise::IWriteData::WritePascalString, deprecated in Wwise 2019.2, have now been removed. When interacting with the Wwise Authoring Plug-in API, UTF-8 is now exclusively used for data strings. Note that path string arguments have been migrated from LPCWSTR to generic AkOSChar buffers in the new API.

Removed iZotope Trash Box Modeler's boxmodel.wav

The external file boxmodel.wav is no longer needed by the iZotope Trash Box Modeler plug-in and has been removed.

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.

Register your project and we'll help you get started with no strings attached!

Get started with Wwise