Version
menu_open
Warning: you were redirected to the latest documentation corresponding to your major release ( 2023.1.8.8601 ). Should you wish to access your specific version's documentation, please download the offline documentation from the Audiokinetic Launcher and check the Offline Documentation option in Wwise Authoring.
Wwise SDK 2023.1.8
Monitoring Errors

Most of the SDK functions return an error code when an issue occurs. The Sound Engine, however, runs on its own thread, so it is possible that errors may occur without receiving a direct notification. Before being printed to the user, error codes are parsed by translators that will change the code into a meaningful message and resolve numerical identifiers to object names. By default, messages only go through the DefaultErrorMessageTranslator. See Error Message Translators for more details.

There are several ways to detect errors in the Sound Engine. You can do any of the following:

  • Check for error codes returned by functions in the SDK.
  • Validate the error code that's sent in a callback specified on the sync call. This only applies when using asynchronous functions.
  • Call the function AK::Monitor::SetLocalOutput() to Enable/Disable local output of monitoring messages and errors. For this use case, be sure that the monitoring thread is started. Otherwise, the AkMonitor won't dispatch its notification and nothing will be sent to the local output. To start the monitoring, simply call AkMonitor::Instance()->StartMonitoring(). In the case where you don't want a separate thread running, make sure AkMonitor::Instance()->InitMonitoring() has been called and then manually call AkMonitor::Instance()->DispatchNotification().
  • Connect the Wwise authoring application to the game using either the DEBUG or PROFILE setups. Before doing so, make sure communications are properly initialized. Refer to Initializing communications for details.
  • Monitor messages posted by the game using the functions AK::Monitor::PostString() and AK::Monitor::PostCode().

Error Message Translators

Before sending error messages to the user, the Sound Engine sends an error code to the error message translators. The error message translators attempt to parse tags contained in the error code in order to create a more detailed error message. This page explains how to implement the translators in your project.

Implementing Translators

The following sections describe the two components needed when using error message translators.

Callback Function

First, a callback function must be set to receive the monitoring messages. This function has to follow the signature of AK::Monitor::LocalOutputFunc and will be the function receiving the error message after the translation. It is in this function that you should define what you want to do with an error message. For example, in IntegrationDemo, LocalErrorCallback is the callback function. In the demo, when an error message is received, the current page content is modified to show the error message in red. To set the callback function, call AK::Monitor::SetLocalOutput() and pass the callback function pointer to be used.

Error Message Translators

The Sound Engine has one default translator which transforms the error codes in readable messages. However, this translator simply prints the information it receives, such as IDs, directly in the error message, without trying to transform them into useful information, such as object names. It is highly recommended that you add other translators to the project in order to receive more detailed error messages. The translators are located in the folder SDK/tools/AkWwiseErrorHandler.

Note: Some translators may require that other libraries are added to the project. Refer to the documentation of each translator for details.

Once the translators you want to use are added to the project, create an instance of them and install them in the monitor by calling AK::Monitor::AddTranslator(). It's important to keep track of the newly created instance in order to be able to delete it.

Translator Types

There are four translator types:

  • Default: Translates error codes into messages, but prints numerical identifiers for Game Objects, Events, Audio Nodes, etc.
  • XML: Translates error codes into messages and uses the information found in SoundBanks.xml to resolve identifiers for Event, Audio Node and Media into meaningful names. Game Objects and some other entities are left in numeric format.
  • WAAPI (AkAutobahn.lib must be added in the linker->input project option): Translates error codes into messages and connects to the Wwise project (through a live Wwise instance) to resolve all identifiers into meaningful names.
  • Unity: Same as WAAPI, but also uses information from Unity. Usable only in Unity projects.

Only the Default translator can handle standard printf-style tags (i.e., those that start with %). Each translator type can redefine how Wwise tags ($) should be handled. It's not necessary to handle every tag in a given translator. fallback translator can be defined, which is called after a translation attempt fails. A translator stack can then be created in order to chain multiple translators together until the translation is successful. The translator at the end of the stack is always a Default translator.

Supported Tags

Translators use a tag system similar to the printf() function. The following tags are supported:

  • Standard tags:
    • %i: Integer
    • %f: Float
    • %u: Unsigned Integer (32 bits)
    • %llu: Unsigned Integer (64 bits)
    • %s: Strings
  • Wwise tags:
    • $b: Bank Id
    • $g: GameObject Id
    • $m: Media Id
    • $p: Plugin Id and ShareSet Id
    • $s: Switch/State Id
    • $w: WwiseObject Ids, such as an Event Id
    • $$: Escape character

Creating a New Error Message Translator

If needed, it's possible to create a new error message translator. Simply create a new class that inherits from the AssistedErrorMessageTranslator interface.

This class has two abstract methods:

  • InitConnection(): Makes sure the connection to the external source was successful (i.e., ensures the translator is ready to be used)
  • GetInfoFromExternalSource(): Determines what to do with a given tag

Your new translator doesn't need to handle all tags. It can rely on the next translator in the stack.

Note: If the new translator implements a way to handle the $p tag, make sure it handles both arguments: Plugin Id and ShareSet Id. See the ParseWwiseTag example in AkDefaultErrorMessageTranslator.cpp.

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