Version
menu_open
Wwise SDK 2021.1.14
Getting Started with WAQL

For the purposes of this tutorial, we suggest you use the Integration Demo project, which can be found in the SDK samples after installing the SDK and a Visual Studio platform from the Audiokinetic Launcher. However, you could also use your own project, or another project from the Wwise samples, such as the Wwise Audio Lab or the Wwise Adventure Game.

Although WAQL can be used in various places, we recommend using the List View for this tutorial.

A Simple Filtering Query

Type the following in the List View search field:

$ where volume < 0

The first character is $ and tells Wwise we are writing a WAQL query. This is how Wwise distinguishes between a standard text search and a WAQL query. Everything that follows the $ defines the query itself.

In this example, we start the query with a where keyword. When starting with a where keyword, WAQL will automatically take every object of the project and filter the objects using the conditional statement defined after the where. The where keyword is a filter that only outputs the matching objects.

In summary:

$ where CONDITION

The CONDITION is a Boolean expression returning true or false. In the example above, we are comparing the volume with a numerical value. If the volume is less than zero, the query will return true. This condition will be verified on all objects of the project. The result of the query is all objects for which the volume is less than zero.

Additional exercises:

  • Try different operators: <=, >, >=, =
  • Replace volume by pitch or lowpass
  • Try to define more complex expressions by using and and or with or without parentheses
Tip: To learn about WAQL property names, refer to Wwise Objects Reference.

String Conditions

So far, we have only used numerical conditions. Let's try a string condition:

$ where name = "hello"

String conditions compare the content of two strings. The equal operator performs a case-insensitive comparison. The condition will evaluate to true when the text is the same, regardless of the case. This is useful when you are looking for something very specific.

There is also a way to compare portions of strings:

$ where name : "hello"

This query uses a colon instead of an equal comparison operator. The colon defines a word search operator. It will return true when the specified word is found inside the element we are looking into. In this specific case, it will return true when "hello" is found in the name.

Additional exercises:

  • Change the text for which you are searching
  • Try using the asterisk wildcard in the search text, for example, "*lo"
  • Replace name by notes or outputbus

Chaining Object Properties

There are two types of properties on Wwise objects:

  • Properties returning a value:
    • Volume, Pitch, Lowpass, etc: Commonly associated with a slider in Wwise, they store a numerical value. These vary depending on the object type. For example, Sound and Random Containers do not have the same set of properties.
    • Name, notes, id, path: Core elements of the Wwise object system, they often store a string value. These are found on any Wwise object.
  • Properties returning another Wwise object (also known as references):
    • OutputBus, Target, UserAuxSend0, Effect0: They point to another object and they vary depending on the object type. For example, Events and Sounds do not have the same properties.
    • Parent: pointer to the parent object.

It's possible to combine properties using the dot operator. For example:

$ where parent.name = "Music"

or

$ where parent.volume < 0

It's also possible to combine several properties:

$ where outputbus.parent.name = "Master Audio Bus"

Note: When combining properties, make sure that properties returning a value are only found after the last dot. Properties returning another object can be located anywhere in the sequence.

Additional exercises:

  • Try to filter on the outputbus's volume
  • Try to filter on Effect0's pluginname

Using a Different Source

So far, we have been filtering objects from the entire project. However, in some instances we may wish to focus our search on a narrower set of objects.

Type the following:

$ from type sound

This query will list all sound objects from the project. The from keyword defines a source from which to start our query. This is a very efficient way to narrow the search. WAQL will be able restrict the iteration to the specified source.

It's also possible to specify multiple object types:

$ from type randomsequencecontainer, switchcontainer, blendcontainer

The previous query could also be written with a filter search using the where keyword:

$ where type = "randomsequencecontainer" or type = "switchcontainer" or type = "blendcontainer"

However, the filtering would have to go through all project objects, including Events, busses, sounds, etc. The execution time will be slower.

Additional exercises:

Combining From and Where

Type the following query:

$ from type sound where volume < 0

This takes all the sound objects from the project and filters them, keeping only the sounds with a volume lower than zero.

While the from keyword can only be found at the beginning of a WAQL query, the where keyword can be appended after a from.

Additional exercises:

  • Try other object types in the from portion
  • Try other conditions in the where portion
  • Try chaining multiple where statements

From a Specific Object

WAQL can narrow a query source even further.

Type the following in the List View:

$ from object "\Actor-Mixer Hierarchy"

This query will return a single object, by using the object path.

To make it more compact, WAQL also supports omitting the 'from object' part, so you can type:

$ "\Actor-Mixer Hierarchy"

This returns the specified object.

We can also list multiple objects:

$ "\Master-Mixer Hierarchy", "\Actor-Mixer Hierarchy"

Additional exercises:

  • Hold the SHIFT key and right-click an object from the Project Explorer. Select Copy Path(s) to clipboard in the shortcut menu. Make a WAQL query from it.
  • Hold the SHIFT key and right-click multiple objects from the Project Explorer. Select Copy WAQL query to clipboard in the shortcut menu. Paste the query in the List View.
  • Hold the SHIFT key and right-click an object from the Project Explorer. Select Copy GUID(s) to clipboard in the shortcut menu. Paste the guid in the List View surrounded by double-quotes: $ "{1514A4D8-1DA6-412A-A17E-75CA0C2149F3}".
  • For Busses and Events, try using the type and the name: $ "Bus:Master Audio Bus".

Selecting Objects

Now that we are able to make a WAQL query from different sources, let's try to select objects. Selecting objects allows you to obtain other objects from the initial sequence of objects.

Type the following query in the List View:

$ "\Actor-Mixer Hierarchy\Default Work Unit" select children

This takes the Default Work Unit and returns all direct children of it.

Let's try to obtain even more objects:

$ "\Actor-Mixer Hierarchy\Default Work Unit" select descendants

This time, all descendants of the Default Work Unit will be obtained in the results. The descendants include all children, taken recursively.

Additional exercises:

  • Try to select parent
  • Try to select multiple elements separated with commas
  • Try adding a select statement to a where query from the first sections
  • Try adding where statements at the end of the select queries
  • Try to select outputbus

Playing with Events

Now that we have learned the basic concepts of WAQL, let's try to build concrete examples. In this example, we will try to enumerate all sounds that are referenced by an Event.

First, enumerate all Events from the project:

$ from type event

Then obtain the Event actions (direct children) from the Event objects:

$ from type event select children

Then obtain the targets (reference named target) of each action:

$ from type event select children select target

Then obtain the targets themselves (using the keyword this) and their descendants:

$ from type event select children select target select this, descendants

Finally, only keep the sound objects, by filtering on the type:

$ from type event select children select target select this, descendants where type = "sound"

Additional exercises:

  • Instead of starting from all Events from the project, start from a specific Event.
  • Try filtering only the Play actions (excluding other types, such as Stop). Refer to Action to learn about action properties.

Playing with Events - In Reverse

Now let's try to start from the Sound objects and list all the Events that can play them:

$ from type sound

Then obtain all the sounds themselves and all their ancestors. We care about the ancestors, because they can also be referenced by the Events. For example, a parent Random Container could be the target of an Event.

$ from type sound select this, ancestors

Then obtain all objects that have a reference to what we have obtained so far:

$ from type sound select this, ancestors select referencesTo

That is basically doing a find all references (similar to the Reference view), but we need to filter it to keep only the Event actions, because other objects like SoundBanks or SoundCaster sessions could have a reference to them:

$ from type sound select this, ancestors select referencesTo where type = "action"

Finally, let's obtain the parent of each individual action, which are the Events:

$ from type sound select this, ancestors select referencesTo where type = "action" select parent

Additional exercises:

  • Instead of starting from all sounds from the project, start from a specific sound.
  • Instead of starting from all sounds from the project, start from all objects under a specific Work Unit.
  • Try to keep only the Play actions, filtering out the other action types, like Stop.

Conclusion

Let's summarize what we learned in this tutorial.

About the composition of a WAQL query:

  • A query returns a sequence of Wwise objects.
  • A query can be decomposed into sections, defined by from, where, and select statements.
  • Each section of a query feeds the next section.
  • A query always has a source from which it starts. The source of the query is defined by a from statement.
  • When the from statement is omitted, all objects from the project are taken as the source.
  • A where statement allows you to filter out objects from the feeding sequence (i.e., the preceding section), keeping only those matching the condition.
  • A select statement allows you to obtain new objects from the feeding sequence (i.e., the preceding section).
  • The where and select statements can be appended to any sequence.

About Wwise objects:

  • Wwise objects have properties, which can be used in where statements or select statements.
  • Properties are either numerical values, Boolean, strings, or references to other objects in the project.
  • Some properties are found on any object (i.e., core properties).
  • Some properties are specific to one or many object types.
  • Properties can be combined with the dot operator.

What's next? There are many more things you can do with WAQL:

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