Version
menu_open
Wwise SDK 2023.1.9
Testing Audio Plug-ins

This document is provided to help you make your plug-ins compatible with all aspects of the Wwise platform. We provide a set of guidelines and a list of specific tests that will make sure you are covering all areas of the software. The tests and guidelines listed here should be considered as requirements when deploying your plug-ins to a large audience.

By passing this series of tests, your plug-ins will be more stable and will have a greater chance of working with the complete feature set of Wwise.

Guidelines

User Interface

  • Maximum Size: The content of your plug-in UI should fit in a size of 1000x650 pixels to accommodate smaller laptop screens.
  • Resizable: Handling of the WM_SIZE message in the WindowProc function is recommended. This allows the user to obtain a smaller or a larger workspace depending on the emphasis given to the plug-in. It also helps the plug-in to better adapt to the Wwise layout system.
  • Usage of the default controls: Using the default control is not mandatory, but it has several advantages:
    • The RTPC icon automatically appears for properties that support it.
    • Control interaction is standard across Wwise (slider behavior, keyboard modifiers, context menus, and so on).
    • Link/Unlink is supported (for Source plug-ins only).
    • Slider ranges are automatically adjusted based on the property definitions.
  • Capitalization: For text (labels, check-boxes, radio buttons, buttons, tooltips, and so on) use sentence-style capitalization.
  • Modeless Dialog: Do not create modeless dialogs (non-child) from the plug-in window. This will conflict with Wwise's layout system and could potentially create bugs. Use modal dialogs instead, but restrict their usage to a minimum (For Open/Save file dialogs, User/System Settings, Message Boxes, and so on).
  • Avoid flickering: When resizing the plug-in window, no flickering should occur.

Functionality

  • Support for RTPCs: Whenever this is possible and make sense, you should try to support RTPCs for your properties. This allows binding game inputs to plug-in properties and brings more flexibility.
  • Non-linear sliders: For sliders that have non linear audible distribution of their value range, such as volume sliders in decibels, use non-linear distribution of the pixel range versus the property range.

  • Use the property restrictions: When defining the properties in the XML plug-in definition, define, whenever this is possible, a restriction range or enumeration for your properties. These restrictions are used to:

    • Automatically adjust slider ranges
    • Determine the RTPC range in the RTPC graph
    • Validate and adjust the property values at project load, to ensure the integrity of the project.

Coding (3rd-Party)

3rd-party plugin vendors must comply to the following requirements. We recommend that in-house title programmers follow them as well.

  • Stability: Your plugin must not crash, assert, freeze, or leak memory.
  • Memory allocation: Never call new() or malloc() in the Sound Engine part of your plugin. Always allocate memory through the AK::IAkPluginMemAlloc allocator that is passed to your plugin by the Wwise sound engine, by using the macros AK_PLUGIN_NEW, AK_PLUGIN_DELETE, AK_PLUGIN_ALLOC and AK_PLUGIN_FREE defined in IAkPlugin.h.
  • Verify allocated memory: In the Sound Engine part of your plugin, always verify that memory allocation was successful before using it. If memory allocation fails, your plugin should return gracefully with AK_Fail (if applicable).
  • Declare supported channel configurations: The Sound Engine part of your plugin should return AK_UnsupportedChannelConfig for channel configurations that it does not support.
  • Plugin performance: The run-time performance of your plugin should be reasonably constant across all calls to AK::IAkInPlaceEffectPlugin::Execute() (or equivalent) during its lifetime.
    • Initialization, termination, and all other functions of the Sound Engine plugins API should also not take significantly longer than Execute().
    • This restriction does not apply when non-RTPC-able parameters are edited in the Wwise authoring tool and applied live in your plugin. In the worst case, changing such a parameter should take no more than the time it takes to teardown and reinitialize the Sound Engine part of the plugin.
  • Assertions: Use the AKASSERT macro instead of native assert.
    • Add the following line of code in the main cpp file of the Wwise part of your plugin: DEFINEDUMMYASSERTHOOK;
    • This macro is defined in AudioPlugin.h, and ensures that the Sound Engine part of your plugin links properly when built inside the DLL used by the Wwise authoring tool.
  • Usability: Your plugin should be functional as soon as it is inserted in the authoring tool. By functional, we mean that it should be able to play and will not cause errors during soundbank generation, without having to rely on the user to perform any action, like opening the Effect Editor for example.
  • Concurrent execution: Your plugin should allow for concurrent execution of the Execute() method on separate instances (see eventmgrthread_taskscheduling). Any data sharing across instances needs to be made thread-safe.

Unity 3D and Unreal4

Both official Wwise integration into these game engines are using dynamic libraries for the effects. If you intend to distribute your plugin to a wide audience, you should provide dynamic libraries for all platforms you support. Please read more about plug-ins' dynamic libraries in Creating Dynamic Libraries.

Tests

New Instance (Source plug-ins)

  1. In the Project Explorer, create a new Sound
  2. In the Contents Editor, create a new Instance of your source plug-in
  3. Double-click the newly created source
  4. Verify that the default values are set
  5. Play the source
  6. Verify that the source plays correctly

New Instance (Effect plug-ins)

  1. In the Project Explorer, double-click an existing sound
  2. In the Property Editor, switch to the Effects tab
  3. On effect ID=0, click the ">>" button.
  4. In the effect sub-menu, select "New..."
  5. Select a work-unit
  6. Click Edit
  7. Verify that the default values are set
  8. Play the Sound
  9. Verify that the Sound plays with the effect applied
  1. In the Project Explorer, double-click an existing sound
  2. In the Property Editor, switch to the Effects tab
  3. On effect ID=0, click the ">>" button.
  4. In the effect sub-menu, select "Default (Custom)"
  5. Click Edit
  6. Verify that the default values are set
  7. Play the Sound
  8. Verify that the Sound plays with the effect applied

Effect Mode Change (Effect plug-ins)

  1. In the Project Explorer, double-click an existing sound
  2. In the Property Editor, switch to the Effects tab
  3. On effect ID=0, click the ">>" button.
  4. In the effect sub-menu, select "New..."
  5. Select a work-unit
  6. Click Edit
  7. Modify the property values
  8. On the Effect tab of the Property Editor, change the Effect mode to "Define custom"
  9. Click Edit
  10. Verify that the effect has the modified property values

Parent Copy (Effect plug-ins)

  1. Create a Sound with an effect
  2. Modify the property values of the effect
  3. In the Project Explorer, copy the Sound (CTRL+C)
  4. In Project Explorer, paste it somewhere (CTRL+V)
  5. Verify that the effect is applied to the copied Sound and has the modified property values

Parent Copy (Source plug-ins)

  1. Create a Sound with a source plug-in
  2. Modify the property values of the source
  3. In the Project Explorer, copy the Sound (CTRL+C)
  4. In the Project Explorer, paste it somewhere (CTRL+V)
  5. Verify that the copied Sound contains a Source with the modified property values

Delete Effect (Effect plug-ins)

  1. Create a Sound with an effect
  2. Modify the property values of the effect
  3. On the Effects tab of the Property Editor, remove the effect
  4. Undo (CTRL+Z)
  5. Verify that the effect has been restored with the modified property values
  6. Redo (CTRL+Y)

Delete Sound (Effect plug-ins)

  1. Create a Sound with an effect
  2. Modify the property values of the effect
  3. In the Project Explorer, delete the Sound
  4. Undo (CTRL+Z)
  5. Verify that the effect has been restored with the modified property values
  6. Redo (CTRL+Y)

Delete Sound (Source plug-ins)

  1. Create a Sound with a source plug-in
  2. Modify the property values of the source
  3. In the Contents Editor, delete the source
  4. Undo (CTRL+Z)
  5. Verify that the source has been restored with the modified property values
  6. Redo (CTRL+Y)

Delete Sound (Source plug-ins)

  1. Create a Sound with a source plug-in
  2. Modify the property values of the source
  3. In the Project Explorer, delete the Sound
  4. Undo (CTRL+Z)
  5. Verify that the source has been restored with the modified property values
  6. Redo (CTRL+Y)

Property Undo

  1. For each property or modifiable element:
    1. Modify the value
    2. Open the Edit menu - Verify the name of the Undo event
    3. Undo
    4. Redo

Persistence

  1. Create an effect or source plug-in with a modified property
  2. Save the Project
  3. Close the Project
  4. Reopen the Project
  5. Verify that the source or effect exists with the modified property values

RTPC Property Names

  1. Create a Sound with a Source/Effect
  2. In the plug-in RTPC tab, click the ">>"
  3. Make sure all properties that support RTPCs are listed
  4. Make sure all property names use sentence-style capitalization

RTPC Property Ranges

  1. Create a Sound with a Source/Effect
  2. Add all properties to the RTPC list
  3. For each property:
    1. Verify that the range is correct
    2. Verify that the default value is correct

RTPC Changes At Playback

  1. Create a Sound with a Source/Effect
  2. For each property supporting an RTPC:
    1. Add property to RTPC list
    2. Play the parent Sound
    3. While playing, change the Game Parameter bound to the Property

Property Changes At Playback

  1. Create a Sound with a Source/Effect
  2. Play the Sound containing the effect/source (make the Sound looping if the Sound is too short)
  3. While playing, for each property:
    1. Change the value

Sound Looping

  1. Create a Sound with a Source/Effect
  2. Enable Looping on the Sound (set to Infinite)
  3. Play the sound
  4. Make sure no glitches are heard
  5. Re-do test with different plug-in property values

Container Looping

  1. Create a Sound with a Source/Effect
  2. Place the parent Sound in a Random Container
  3. Set the Random Container to: PlayMode=Continuous, Loop=Infinite
  4. Play the Random Container
  5. Make sure no glitches are heard
  6. Re-do test with different plug-in property values

Container Looping with Sample Accuracy

  1. Create a Sound with a Source/Effect
  2. Place the parent Sound in a Random Container
  3. Set the Random Container to: PlayMode=Continuous, Loop=Infinite
  4. Set the Random Container to: Transition=Sample Accurate
  5. Play the Random Container
  6. Make sure no glitches are heard
  7. Re-do test with different plug-in property values

Virtual Voices (Source Plug-ins)

  1. In the Project Settings dialog, set the Volume Threshold to -5 db
  2. Create a Sound with a Source
  3. On the Advanced Settings tab of the Property Editor, set WhenBelowVolumeThreshold=SendToVirtualVoice
  4. Play the Sound
  5. Set Sound Volume=-6 db
  6. Make sure no glitches are heard
  7. Set Sound Volume=0 db
  8. Make sure no glitches are heard
  9. Re-do test with different plug-in property values

Multi-channel Effect on Sound (Effect Plug-ins)

  1. For Sounds with the following channel configuration: 0.1, 1.0, 1.1, 2.0, 2.1, 4.0, 4.1, 5.0, 5.1
  2. Place an effect on Sound
  3. Play the Sound

Multi-channel Effect on Bus (Effect Plug-ins)

  1. Create a Bus with an Effect
  2. For Sounds with the following channel configuration: 0.1, 1.0, 1.1, 2.0, 2.1, 4.0, 4.1, 5.0, 5.1
  3. Route a Sound to this Bus
  4. Play the Sound

Multiple Playback of Sound with Effect (Effect Plug-ins)

  1. Create a Sound with an Effect
  2. Using the SoundCaster, play the Sound multiple times simultaneously

Effect on Bus with Multiple Sounds (Effect Plug-ins)

  1. Create a Bus with an Effect
  2. Route several Sounds to this Bus
  3. Using the SoundCaster, play multiple Sounds (routed to the bus) simultaneously

In-Game Tests

Testing your plug-in in-game is required to cover areas that can't be tested in Wwise, such as:

  • Code running on other platforms: PS4, Xbox One, and so on
  • SoundBank generating/loading of plug-in parameters
  • Rendered effects
  • Environmental effects

To facilitate in-game testing, the Game Simulator can be used to build test scripts. Here are the steps required to make a script and run it in the Game Simulator.

  1. In your project:
    1. Create a SoundBank
    2. Create an event that plays your Sound
    3. Add your event to the SoundBank
    4. Generate your SoundBank
  2. Install the Game Simulator (must be the same version of Wwise that you are using)
  3. Make a copy of AkSampleNoCoroutines.lua or AkSampleWithCoroutines.lua from the Scripts folder in the Game Simulator install directory.
  4. Modify the lua script so it loads your own bank, and plays your event.
  5. Run the lua script by using the appropriate Game Simulator, on the selected platform.

Rendered Effects (Effect Plug-ins)

  1. Create a Sound with an Effect
  2. On the Effects Tab of the Property Editor, enable "Render" for the effect.
  3. Play the Sound in-game

Enable Console Output for Debugging (Windows)

On Windows, you can enable console output to help with debugging.

To view console output

  1. Add an AK_OUTPUT_REDIRECT environment variable and set the value to 1.
  2. Open a console, and launch Wwise from the command line.
  3. Keep the console open while you use Wwise. Error messages and other information are displayed in the console. You can use print functions (wprintf, fwprintf, printf, and so on) to print the console output.

Troubleshooting

Help is available in Wwise Source and Effect Plug-in Troubleshooting Guide if you run into any problem.

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