Table of Contents

Important Migration Notes 2017.2

With many new features, you will need to pay attention to several things when migrating to Wwise 2017.2.

Please thoroughly read the following important migration notes:

Some Effects and source plug-in libraries were renamed

In the SDK lib files:

  • AkSoundSeedWind.lib -> AkSoundSeedWindSource.lib
  • AkSoundSeedWoosh.lib - > AkSoundSeedWooshSource.lib
  • AkSynthOne.lib -> AkSynthOneSource.lib

In the SDK bin files:

  • AudioInput.dll -> AkAudioInput.dll
  • ParametricEQ.dll -> AkParametricEQ.dll
  • SilenceGenerator.dll -> AkSilenceGenerator.dll
  • Sine.dll -> AkSineTone.dll
  • SynthOne.dll -> AkSynthOne.dll
  • ToneGen.dll -> AkToneGen.dll

In SDK\include\AK\Plugin:

In the Authoring\x64\Release bin:

  • AudioInput.dll -> AkAudioInput.dll
  • iZHybridReverb_Plugin.dll -> iZHybridReverb.dll
  • iZTrashBoxModeler_Plugin.dll -> iZTrashBoxModeler.dll
  • iZTrashDelay_Plugin.dll -> iZTrashDelay.dll
  • iZTrashDistortion_Plugin.dll -> iZTrashDistortion.dll
  • iZTrashDynamics_Plugin.dll -> iZTrashDynamics.dll
  • iZTrashFilters_Plugin.dll -> iZTrashFilters.dll
  • iZTrashMultibandDistortion_Plugin.dll -> iZTrashMultibandDistortion.dll
  • ParametricEQ.dll -> AkParametricEQ.dll
  • SilenceGenerator.dll -> AkSilenceGenerator.dll
  • Sine.dll -> AkSineTone.dll
  • SynthOne.dll -> AkSynthOne.dll
  • ToneGen.dll -> AkToneGen.dll
  • Wind.dll -> AkSoundSeedWind.dll
  • Woosh.dll -> AkSoundSeedWoosh.dll
  • AkPerforce.dll -> Perforce.dll
  • AkSubversion.dll -> Subversion.dll

Breaking changes in audio output management, secondary outputs, and sink plug-ins

The management of outputs (Main, BGM, Game Controller Speakers, Headphones, DVR, and so on) was overhauled for 2017.2. Now, all audio sinks (the part that talks to audio hardware) use the plug-in model, including the ones provided by Audiokinetic with Wwise. Therefore, all projects now have Audio Devices ShareSets of each type added to their project, if they use at least one of the supported platforms. Each Master Bus (a bus that sits at the top of the mixing hierarchy) must now have an Audio Device attached to it to define into which output the mix will go. This function was previously done by code either during initialization (through AkInitSettings) or with AK::SoundEngine::AddSecondaryOutput. During the migration to 2017.2, existing projects will have the System device automatically added to the Master Audio Bus and to the Master Secondary Bus.

Caution: Review your usage of the Master Secondary Bus! If you used it before, you must select the proper Audio Device. You might have to split your bus hierarchy to have a separate Master Bus for another output. You can now create as many Master Busses as you need, normally one per hardware output.
Caution: If you used plug-ins for your main output (PSVR binaural plug-in for example), make sure to link them to the Master Audio Bus' Audio Device property. If this plug-in is supported only on one platform (PS4, for example), make sure to use the Link/Unlink functionality to set the property correctly on all platforms.

Additionally, Listener management with respect to Secondary Output has been changed. In general, the old code should behave the same way unchanged. However, it is worth mentioning that the system requires fewer Listeners if only one device of a given type can exist. Please read Integrating Secondary Outputs for more information.

API changes due to output management overhaul

Breaking changes in motion support

The whole motion (rumble) system was refactored to use the generic Audio Device plug-in mechanism and the new output system, instead of the old separate code path. Motion devices are now considered as Audio Devices instead of having a special status. This streamlines the code and data model for Motion objects and allows the use of all the same feature set as the audio pipeline. Therefore many changes to existing code are necessary to get the same Motion effects. Most changes to the Wwise project are done automatically and transparently. See the section Basic project migration changes: below to learn about the changes made to your project.

API changes due to Motion refactoring

All the AK::MotionEngine namespace was removed. Therefore, to replace AK::MotionEngine::AddPlayerMotionDevice, you must now call AK::SoundEngine::AddOutput, with the proper Audio Device ShareSet name (usually Wwise_Motion). This Audio Device should have been added automatically to your project.

Also, the Listener management related to Motion has changed. Instead of calling AK::MotionEngine::SetListenerPipeline, you need to provide the listener linked to the player as a parameter to AK::SoundEngine::AddOutput. Note that this listener is optional now, if you only have one player in the game. Multiplayer games will still need to manage listeners properly.

Please read more about how to implement motion in your game in the SDK help here: Integrating Wwise Motion and about Secondary Outputs in general here: Integrating Secondary Outputs.

Basic project migration changes:

Existing projects will be migrated to the new system automatically. Here's the list of changes to look for in your project:

  • In the Master-Mixer Hierarchy a Motion Bus becomes an Audio Bus.
  • A Motion FX becomes a Sound FX with the Motion Bus reference changed to an Output Bus reference, and the Output Bus parent override is enabled (if it has a parent); now that we use an Output Bus reference we must ensure the routing occurs.
  • A Motion Source becomes a Source Plugin with the SFX Language specification added. DeviceCompanyID and DevicePluginID are removed.
  • As we wish motion to work as seamlessly as possible following migration, we automatically add the new Wwise Motion ShareSet in the Audio Devices Default Work Unit if at least one platform in the project is supported by Wwise Motion. See the note below for an exception.
  • The Audio Device ShareSet reference for the Master Audio Bus, Master Secondary Bus, and Master Control Bus are set to System, the default.
  • If supported in the project, the Wwise Motion ShareSet is assigned to the Master Motion Bus or Motion Master Bus. See the note below for an exception.
  • The Motion tab in the Property Editor of the Wwise Authoring application has been removed.
Note: If motion was not used in a project (there is no reference to a Motion Bus), all Motion Busses in the project will be deleted. Additionally, the Wwise Motion ShareSet will not be added, even for projects that support it.

Audio-To-Motion Migration:

  • The Motion Bus reference is now a User Aux Send to an Auxiliary Bus child of the original (Motion) bus (which has been migrated to a regular Audio Bus). Implicit in this is that we enable the user aux send override for the migrated object to ensure the "motion" aux send takes effect. Implications of this are detailed below in Implications of switching from a Motion Bus reference to a User Auxiliary Send for Audio-to-Motion.
  • The Motion Low Pass property becomes an auxiliary send LPF.
  • The Motion Volume Offset property becomes an auxiliary send volume.

Implications of switching from a Motion Bus reference to a User Auxiliary Send for Audio-to-Motion

A few scenarios arise because we are now using a basic user aux bus send rather than a separate Motion Bus path:

  • If the Sound SFX or Music Track already has 4 user aux sends, then the audio-to-motion will not be migrated.
  • In the process of converting the Motion Bus reference to a user aux send reference, we "clean" the user aux sends for the object in question.
    • If there are any user aux sends defined and the Override parent is not enabled, we remove them. This can help to reduce the number of times an audio-to-motion migration fails because of the number of existing user aux sends.
Note: For the subsections below: In the process of copying a user aux send we copy the bus reference, the volume, and the LPF. Any RTPC, Modulator LFO, Modulator Envelope, and Curve or Modifier on the volume or LPF is copied as well. Any IDs (unique ID and ShortID) are regenerated to mitigate ID clashes when loading the migrated project. For any clashes that remain (more likely with the ShortID) the Wwise project load procedure will resolve them (with a warning in the Project Load Log).
Warning: Any copying of user aux sends from a node to a descendant has the (initial) equivalent effect of setting the descendant to inherit the node's aux send, but if any change is made to the node's aux send it will not be reflected in the descendant.

Migrating an Audio-to-Motion object that did not have 'Override parent' for its user aux sends enabled

  • The override is enabled.
  • User aux sends of the ancestor from which the migrated object inherited are copied to the object. If the ancestor has an aux send stemming from a migrated audio-to-motion it is not copied.
    • Because of the limitation of 4 aux sends on an object, it is possible that not all of the ancestor's aux sends would be copied. In this case the audio-to-motion will not be migrated as priority is given to maintaining existing audio behavior.

Migrating an Audio-to-Motion object that did have 'Override parent' for its user aux sends enabled

  • The override remains enabled.
  • As it was already overriding its parent, there is no need to copy user aux sends from above.

Migrating an Audio-to-Motion on an object with descendants

  • If a descendant already overrides its (migrated) parent's user aux sends and doesn't have its own (overriding) audio-to-motion we copy the migrated node's new "motion" aux send to the descendant. If the descendant already has 4 aux sends the copy is not performed. The downward traversal through descendants stops when we reach a node with an audio-to-motion as it is the source for its descendants.
  • If a descendant does not override its parent's user aux sends there is no need to copy to the descendant - it will inherit the "motion" from above.

Additional limitations/changes of motion migration

  • Nested Work Units are not treated correctly - we do not traverse up the node hierarchy through nested Work Units when determining if an object is a top-level object. Consequences:
    • Some nodes will be considered top-level when they are not, so they may be considered as having audio-to-motion when they do not. This can occur if there is a Motion Bus reference and the Override Motion Output is disabled.
  • We delete motion related info in Presets. That is, we don't try to migrate it. This covers:
    • Motion FX and Motion Source objects
    • Motion Volume, Motion Lowpass, and Override Motion Output properties
    • Motion Bus references
  • The references to these in the Wwise Authoring application have been removed.
  • We delete motion-related info in queries. This covers:
    • Motion Volume, Motion Lowpass, and Override Motion Output properties
    • MotionBus, Motion FX, and Motion Source object types
    • Motion Output Bus routing
    • Motion Device sources
  • The references to these in the Wwise Authoring application have been removed.

Renamed WAAPI functions

The following functions have been renamed to better reflect their intended usage:

  • ak.wwise.core.plugin.getList was renamed ak.wwise.core.object.getTypes
  • ak.wwise.core.plugin.getProperties was renamed ak.wwise.core.object.getPropertyNames
  • ak.wwise.core.plugin.getProperty was renamed ak.wwise.core.object.getPropertyInfo

The previous names were deprecated and should not be used in new code.

WAAPI C++ SampleClient changed

  • Usage of the Client class will not compile if you provided a timeout in the constructor. The timeout is no longer the same for all method calls to the client, it must be provided at each call.
  • The version of the Autobahn library that was used in the SampleClient, called AkAutobahn, is now built independently of SampleClient as a static library. It is now available as part of the Wwise SDK. Please see the SampleClient source code for usage examples.

Wwise Authoring 32-bit removal

The 32-bit Wwise Authoring was removed. Now both Windows and macOS Wwise Authoring are only compiled with 64-bit support.

Please note that 32-bit support is still available for the Wwise SDK libraries.

Obstruction and occlusion with user-defined positioning

While revamping the built-in LPF/HPF pipeline, we removed the arbitrary condition restricting obstruction/occlusion to game-defined positioning. If you relied on the fact that sounds with 3D user-defined positioning were always unobstructed/unoccluded, you will have to use a different game object for those sounds.

Aux busses will now process the dry signal

In Wwise 2017.2, Auxiliary Busses will now process the dry signal; it will not be ignored. A migration was put in place to mute the dry signal of affected Effects that are placed on aux busses. The Effects affected by this change are:

  • Wwise RoomVerb
  • Wwise Convolution Reverb
  • Wwise Matrix Reverb
  • Wwise Reflect
  • Wwise Delay
  • Wwise Harmonizer
  • Wwise Pitch Shifter
  • Wwise Stereo Delay
  • iZotope Hybrid Reverb
Caution: If an Effect is applied to an aux bus and another type of medium, it will also be muted, which may change the behavior of your project.

Spatial Audio

Geometry-driven Spread

Users must delete the Spread curve of the Attenuation ShareSet used on aux busses (portals) in order to benefit from Spatial Audio's geometry-driven spread calculation.

Room aux sends

AK::SpatialAudio::SetEmitterAuxSendValue should no longer be called for sending to Rooms' aux sends, as this is now specified in AkRoomParams and managed entirely by Spatial Audio. AK::SpatialAudio::SetEmitterAuxSendValue adds its sends to those of Rooms and can thus be used for customizing or implementing more complex reverberation regions within the same room.