Wwise SDK 2022.1.8
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.
|Tip: A brief video tutorial on WAQL usage in the List View is available. See Finding Objects using WAQL.|
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.
$ 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.
|Tip: To learn about WAQL property names, refer to Wwise Objects Reference.|
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.
There are two types of properties on Wwise objects:
It's possible to combine properties using the dot operator. For example:
$ where parent.name = "Music"
$ 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.|
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.
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.
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"
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.
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"
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
Let's summarize what we learned in this tutorial.
About the composition of a WAQL query:
About Wwise objects:
What's next? There are many more things you can do with WAQL: