Version
Wwise SDK 2023.1.6
|
The Wwise Authoring Query Language (WAQL) allows for querying of a Wwise project and its objects. To learn more about the different concepts in WAQL, refer to Using the Wwise Authoring Query Language (WAQL). Queries have one of the following forms:
Synopsis | Description |
$ SOURCE |
SOURCE refers to an object generator, which outputs a sequence of objects. Refer to the table below for more information on the different possible sources. TRANSFORM refers to a sequence transformation. The transform takes an input sequence and outputs another sequence. Note: When the source is not specified, all objects defined in the project are implicitly taken as the source. |
Specify the starting point of the query.
SOURCE | Query Source | WAQL query to execute in the IntegrationDemo project |
---|---|---|
from object OBJECT_SPECIFIER |
Generates a sequence of objects from the specified objects. OBJECT_SPECIFIER refers to one of the following forms:
|
$ from object "\Actor-Mixer Hierarchy\Default Work Unit\Hello" |
from type OBJECT_TYPE from type OBJECT_TYPE, OBJECT_TYPE, ... |
Generates a sequence of objects from the specified types. One or many object types can be specified. OBJECT_TYPE refers to a Wwise object type. Refer to Wwise Objects Reference for the complete list of object types. The type is case-insensitive.
|
$ from type Event |
from query QUERY_SPECIFIER |
Generates a sequence of objects from the result of executing a Wwise Query defined in the Query Editor. QUERY_SPECIFIER refers to one of the following forms:
Note: This generator requires a memory allocation equal to the size of the sequence it generates. |
$ from query "\Queries\Factory Queries\Audio Source\Audio Source - Format = Vorbis" |
from search TEXT |
Generates a sequence of objects from the result of a text search on the whole project. TEXT refers to a double-quoted string of text. Each word specified in the search's text are matched to words inside the project objects. Note: The results are the same as the Wwise toolbar search. |
$ from search "gun" |
from project | Generates a sequence of objects including all objects of the project. | $ from project |
Change a sequence of objects into another one.
TRANSFORM | Chainable Transformations | Examples |
---|---|---|
where BOOLEAN_EXPRESSION |
Filters objects of the input sequence by rejecting objects that don't match the specified expression. BOOLEAN_EXPRESSION refers to an expression that returns true or false. The expression will be executed on each object of the input sequence and will reject the objects with an expression returning false. Refer to the expressions section for more information. |
$ from type Sound where @Volume < 0 |
skip COUNT |
Bypasses a specified number of objects in the input sequence and then returns the remaining objects. COUNT refers to the number of elements to skip. | $ from type Sound skip 10 |
take COUNT |
Returns a specified number of contiguous objects from the start of the input sequence. COUNT refers to the number of elements to take. | $ from type Sound take 10 |
select OBJECT_EXPRESSION |
Projects each object of the input sequence into a new form. OBJECT_EXPRESSION refers to an expression that returns zero to many objects. The expression will be executed on each object of the input sequence and will project the result of the expression in a new sequence. Refer to the expressions section for more information. |
$ from object "{1514A4D8-1DA6-412A-A17E-75CA0C2149F3}" select parent |
orderby VALUE_EXPRESSION orderby VALUE_EXPRESSION reverse |
Sorts the objects of the input sequence in ascending order and returns them. To sort in descending order, add reverse after the expression. VALUE_EXPRESSION refers to the expression used to compare objects together in the sort algorithm. The expression must return a comparable value, such as string, numerical, or boolean values. Note: For the sort to occur, orderby requires a memory allocation equal to the size of the input sequence. | $ from type Sound orderby name $ from type Sound orderby name reverse $ from type Bus orderby @BusVolume $ from type Action orderby @Target.name |
distinct |
Returns only the distinct objects of the input sequence. Duplicated object entries will be reduced to one entry, resulting in each object being unique in the sequence. Note: distinct will change the order of the sequence. For this reason, it is preferable to place the orderby statement after the distinct statement. Note: For the operation to occur, distinct requires a memory allocation equal to the size of the input sequence. |
$ from object "\Actor-Mixer Hierarchy" select descendants select @OutputBus distinct |
Select other objects, or values associated with the objects, in the sequence.
Object Expressions | Expression returning zero to many objects | Examples |
---|---|---|
OBJECT_EXPRESSION OBJECT_EXPRESSION.OBJECT_EXPRESSION... | Chain zero to many object expressions to return a Wwise object. Separate each expression with a dot. | $ from object "Event:Play_Hello" select parent.parent |
REFERENCE_NAME @REFERENCE_NAME @@REFERENCE_NAME |
Returns the object being referenced by the current object for a specific reference name. When using @, the reference directly defined on the object is used. Without the @, the override settings are used to find the reference value. This is the actual value used at playback. If there is an accessor of the same name, it will take precedance; in those rare cases, @@ must be used before the reference name. REFERENCE_NAME refers to the name of a reference for the current object. Refer to Wwise Objects Reference for the complete list of object types and their references. The name is case-insensitive. |
$ from type Sound select OutputBus |
children | Returns the direct children of the object. | $ from object "\Actor-Mixer Hierarchy\Default Work Unit" select children |
descendants |
Returns all descendants of the object in a single sequence. The descendants include all children recursively. Note: The current object is not included. To include the current object use: select descendants, this |
$ from object "\Actor-Mixer Hierarchy\Default Work Unit" select descendants |
this | Returns the current object. | $ from object "\Master-Mixer Hierarchy\Default Work Unit\Master Audio Bus" select this, descendants |
parent | Returns the direct parent of the object. Returns no object if the object does not have a parent. |
$ from type Sound select parent |
ancestors |
Returns all ancestors of the object in a single sequence. The descendants include all parents recursively. Note: The current object is not included. To include the current object use: select ancestors, this | $ from object "Event:Play_Hello" select ancestors $ from object "Event:Play_Hello" select ancestors, this |
referencesTo | Returns all objects having a reference to the current object. |
$ from type Effect select referencesTo |
owner |
Returns the owner of the object. The owner is only set for "Custom" objects defined inside other objects. Shareset objects don't have an owner. They have a parent (parent), and they have objects referring to them (referencesTo). For example, the owner of a "Custom" effect is the object that contains the effect as an insert. | $ from type Effect select owner |
randomizer("PROPERTY_NAME") |
Returns the randomizer object associated with the specified property. Use the following properties on the randomizer object: min, max, enabled. PROPERTY_NAME refers to the name of a property for the current object. Refer to Wwise Objects Reference for the complete list of object types and their properties. The name is case-insensitive. | $ from type sound where randomizer("pitch") != null |
workunit | Returns the Work Unit object used to persist with the current object. | $ from type Effect select workunit |
musicTransitionRoot |
(DEPRECATED) Returns the Music Transition root object associated with the current object. This is deprecated. The TransitionRoot reference should be used instead. Note: This only works with objects of type MusicSegment, MusicTrack, MusicPlaylistContainer and MusicSwitchContainer. | $ from project select musicTransitionRoot |
musicPlaylistRoot |
(DEPRECATED) Returns the Music Playlist root object associated with the current object. This is deprecated. The PlaylistRoot reference should be used instead. Note: This only works with objects of type MusicPlaylistContainer. | $ from project select musicPlaylistRoot |
maxDurationSource |
Returns a JSON object containing the id of the Audio Source object that has the maximum playback duration (in seconds) for all descendants of the current object. The JSON object also includes the maximum duration value itself. Note: This only works with Actor-Mixer Hierarchy objects, Interactive-Music Hierarchy Object, and Events. | $ from object "\Actor-Mixer Hierarchy" select maxDurationSource |
maxDurationSourceObject |
Returns the Audio Source object that has the maximum playback duration (in seconds) for all descendants of the current object. Note: This only works with Actor-Mixer Hierarchy objects, Interactive-Music Hierarchy Object, and Events. | $ from object "\Actor-Mixer Hierarchy" select maxDurationSource |
maxRadiusAttenuation |
Returns a JSON object containing the id of the attenuation object that has the maximum radius distance in all descendants of the current objects. The JSON object also contains the maximum radius distance value itself. Note: This only works with Actor-Mixer Hierarchy objects, Interactive-Music Hierarchy Object, and Events. | $ from type Sound select maxRadiusAttenuation |
maxRadiusAttenuationObject |
Returns the attenuation object that has the maximum radius distance in all descendants of the current objects. Note: This only works with Actor-Mixer Hierarchy objects, Interactive-Music Hierarchy Object, and Events. | $ from type Sound select maxRadiusAttenuation |
audioSourceLanguage |
Returns the language object that is used for the current Audio Source. Note: This only works with Audio Source objects. | $ from type AudioFileSource select audioSourceLanguage |
switchContainerChildContext |
Returns the Switch Container context object associated with the current Switch Container object. The Switch Container context objects hold settings about the Switch Container associations. Note: This only works with objects of type SwitchContainer. | $ from project select switchContainerChildContext |
Value Expressions | Expression returning a number, string or boolean | Examples |
OBJECT_EXPRESSION.VALUE_EXPRESSION OBJECT_EXPRESSION.OBJECT_EXPRESSION. VALUE_EXPRESSION | Chain zero to many object expression, followed by a value expression to return a value on the chained object. Separate each expression with a dot. | $ where OutputBus.id = "{1514A4D8-1DA6-412A-A17E-75CA0C2149F3}" |
PROPERTY_NAME @PROPERTY_NAME @@PROPERTY_NAME |
Returns the value of the property for a specific object. Without the @, the override settings are used to find the property value. This is the actual value used at playback (i.e. the effective value). If there is an accessor of the same name, it will take precedence; in those rare cases, @@ must be used before the property name. When using @, the property directly defined on the object is used, even if it is not overridden. @@ is the same as no @. PROPERTY_NAME refers to the name of a property for the current object. Refer to Wwise Objects Reference for the complete list of object types and their properties. The name is case-insensitive. |
$ from type Sound where volume < 0 |
id |
Returns a 128-bit GUID string of the form: "{0CB93450-E995-40E5-98A5-239F15B1F1D4}". This is a unique identifier for the object in the project. | $ where id = "{1514A4D8-1DA6-412A-A17E-75CA0C2149F3}" |
shortId |
Returns a numeric 32-bit short ID for the object. This is the ID being used in the Sound Engine. Note: The scope over which a short ID is unique depends on the type of object. Certain object types, like busses, events, effects, and game syncs have an ID that is unique across all objects of the same type. Others, like sounds and containers, are unique across the project. | $ where shortId = 1588715066 |
name | Returns the name of the object as a string. | $ from type Event where name : "*hello*" $ where name = "Play_Hello" |
notes | Returns the notes of the object as a string (also known as comments). |
$ where notes : "audiokinetic" |
type |
Returns the type of the object as a string. Refer to Wwise Objects Reference for the complete list of object types. | $ where type = "Sound" |
nodeType |
Returns the type of the node as a string. Refer to Wwise Nodes Reference for the complete list of node types. |
$ where nodeType = "Sound SFX" |
classId |
Returns the classID of the object. The classID is a numerical value representing the type of object and the type of effect, source or conversion plug-in. Refer to Wwise Objects Reference for the complete list of classIDs. | $ where classId = 8847363 |
category |
Returns the category of the object. Possible categories are the top folder names found under the project root folder. | $ where category = "Actor-Mixer Hierarchy" $ where category = "Interactive Music Hierarchy" $ where category = "Master-Mixer Hierarchy" $ where category = "Events" |
filePath | Returns the file path associated with the Work Unit or project. This is the absolute path of the wwu or wproj file. | $ where type = "WorkUnit" and filePath : "*wwu" |
path | Returns the path of the project inside the Wwise project. This path includes the category, which is the top folder name. | $ where path : "microphone" |
activeSource | Returns the active source associated to a sound object. | $ from type Sound select activeSource |
isPlayable | Returns true if the object can be played in the transport, or inside an Event. Returns false otherwise. | $ where isPlayable $ where isPlayable = false $ where !isPlayable |
childrenCount | Returns the number of children for the current object. | $ where childrenCount > 10 $ where type = "RandomSequenceContainer" and childrenCount > 5 |
pluginName |
Returns the name of the plug-in as provided by the vendor of the plug-in. The plug-in name is available for Effects plug-ins, Source plug-ins, Audio Devices and Metadata objects. Note that the plug-in name is different from the name of the object. | $ where pluginName = "" |
convertedFilePath |
Returns the absolute path of the converted file associated with the current object. Note: This only works with objects of type Sound and AudioSource. | $ from type Sound where convertedFilePath : "hello" |
originalFilePath |
Returns the absolute path of the original file associated with the current object. Note: This only works with objects of type Sound, AudioSource, Music Clip and Music Clip MIDI. | $ from type Sound where originalFilePath : "hello" |
originalRelativeFilePath |
Returns the path of the original file associated with the current object, relative to the project's Originals folder. Note: This only works with objects of type Sound, AudioSource, Music Clip, and Music Clip MIDI. | $ from type Sound where originalFilePath : "hello" |
soundbankBnkFilePath |
Returns the absolute path of the BNK file associated with the current object. Note: This only works with objects of type SoundBank. | $ where soundbankBnkFilePath : "car" |
mediaId |
Unique value given to file. Used by the sound engine to identify the file. Note: This only works with objects of type AudioSource, MidiFileSource and PluginMediaSource. | $ where mediaId > 0 |
conversionHash |
The hash of everything in the project that affects a file's conversion (Conversion ShareSet, file modifications in the Source Editor, and so on). Note: This only works with objects of type AudioSource, MidiFileSource and PluginMediaSource. | $ where conversionHash > 0 |
contentHash |
The hash of the conversionHash and the hash of the original file's contents. Note: This only works with objects of type AudioSource, MidiFileSource and PluginMediaSource. | $ where contentHash != "" |
workunitIsDefault |
Returns true if the Work Unit object is the default work unit for its category. Note: This only works with objects of type WorkUnit. | $ where workunitIsDefault |
workunitType |
Returns the type of the current Work Unit object. This can be one of the following values:
Note: This only works with objects of type WorkUnit. |
$ where workunitType = "folder" |
workunitIsDirty |
Returns true if the Work Unit has unsaved changes. Note: This only works with objects of type WorkUnit. | $ where workunitIsDirty |
isExplicitMute |
Returns true if the object is muted explicitly. | $ where isExplicitMute |
isExplicitSolo |
Returns true if the object is soloed explicitly. | $ where isExplicitSolo |
isImplicitMute |
Returns true if the object is muted implicitly. | $ where isImplicitMute |
isImplicitSolo |
Returns true if the object is soloed implicitly. | $ where isImplicitSolo |
isIncluded |
Returns true if the object is included. If one or more of the object's ancestors is excluded, the object is excluded as well. | $ where isIncluded |
stateProperties |
Returns which properties are used for the states of the associated object. This represents the visible columns in the States tab. The return is a list of strings. Note: This can only be used in a return expression. | |
stateGroups |
Returns which state groups are used for the states of the associated object. This represents the state groups added in the States tab. The return is a list of objects. Note: This can only be used in a return expression. | |
validity |
Returns a JSON object representing the status of validity. There are 3 fields in the object: isValid (boolean), details (string), severity (string). The details and severity fields are only available when isValid is false. This can be used with Effect Slots, Events and Actions. | $ where validity.isValid |
maxDurationSource.id |
Returns the ID (GUID) of the audio source object with the longest duration. | $ where maxDurationSource.id = "{1514A4D8-1DA6-412A-A17E-75CA0C2149F3}" |
maxDurationSource.trimmedDuration |
Returns the duration in seconds of the longest trimmed source. | $ where maxDurationSource.trimmedDuration >= 2 |
duration.min |
Returns the minimum possible time playback can take. Note: This applies to all objects that can contain Audio Source objects, either directly as a source or indirectly through descendants. | $ where duration.min = 3 |
duration.max |
Returns the maximum possible time playback can take. Note: This applies to all objects that can contain Audio Source objects, either directly as a source or indirectly through descendants. | $ where duration.max = 5 |
duration.type |
Returns the type of duration, which can be "infinite", "mixed", "oneShot" or "unknown". | $ where duration.type = "oneShot" |
loudness.integrated |
Returns the integrated loudness measurement in LUFS for the entire associated audio file. | $ from type sound where loudness.integrated > -14 |
loudness.momentaryMax |
Returns the momentary max measurement in LUFS for the associated audio file. The value represents the highest loudness value obtained with a very short (100ms) window evaluation. | $ from type sound where loudness.momentaryMax > -14 |
audioSourceTrimValues.trimBegin |
Returns the beginning of the range of time for which the audio source is trimmed. | $ where audioSourceTrimValues.trimBegin = 2 |
audioSourceTrimValues.trimEnd |
Returns the end of the range of time for which the audio source is trimmed. | $ where audioSourceTrimValues.trimEnd = 5 |
maxRadiusAttenuation.id |
Returns the ID (GUID) of the attenuation object with the largest radius. Note: This only works with Actor-Mixer Hierarchy objects, Interactive-Music Hierarchy Object, and Events. | $ where maxRadiusAttenuation.id = "{1514A4D8-1DA6-412A-A17E-75CA0C2149F3}" |
maxRadiusAttenuation.radius |
Returns the radius of the attenuation object with the largest radius. Note: This only works with Actor-Mixer Hierarchy objects, Interactive-Music Hierarchy Object, and Events. | $ where maxRadiusAttenuation.radius > 100 |
Perform conditional logic or select specific elements on all items of the list at once. You can use list functions on object lists and other lists provided by WAQL, such as children, descendants, ancestors, and referencesTo.
Refer to Wwise Objects Reference to learn more about the object lists available in the different object types.
List Functions | Description | Examples |
---|---|---|
count | Returns the number of items in the list that match the specified condition, otherwise returns false. The condition statement is optional. | $ where children.count() > 3 $ where effects.count(effect.pluginname:"eq") > 0 |
any | Returns true if any items match the condition, otherwise returns false. Returns false if empty. The condition statement is optional. | $ where rtpc.any() $ where children.any(type = "Sound") |
all | Returns true if all items in the list match the specified condition, otherwise returns false. Returns false if empty. The condition statement is mandatory. | $ where children.all(type = "Sound") |
first | Returns the first item thats matches the specified condition. The condition statement is optional. | $ where effects.first(effect.pluginname :"EQ") != null $ where children.first().type = "Sound" |
last | Returns the last item that matches the specified condition. The condition statement is optional. | $ where effects.last(effect.pluginname :"EQ") != null $ where children.last().type = "Sound" |
take | Takes the specified number of items, and returns them in a new list. | $ select children.take(2) |
skip | Skips the specified number of items, and returns the rest in a new list. | $ select effects.skip(1) |
at | Returns the item at the specified index in the list. | $ select effects.at(0) |
where | Returns the items that match the specified condition in a new list. | $ select effects.where(effect.pluginname :"EQ") |
Evaluate a boolean expression and return true or false.
Conditional and Logical Operators | Description | Examples |
---|---|---|
= | Compares two values; either string, numerical, or boolean. |
$ where name = "Hello" |
!= | Compares two values; either string, numerical, or boolean. |
$ where name != "Hello" |
< | Compares two numerical values. |
$ from type sound where volume < 0 |
: |
Compares two string values and returns true if a word partially matches, starting with the specified text. Wildcards can also be used to match the end of a word. |
$ where name : "Hello" |
= /REGEX/ |
Returns true if the specified regular expression matches the current string. ECMAScript regular expressions are used. | $ where name = /Hello/ $ where name = /llo$/ $ where name = /[a-z][0-9]/ |
! | Negates an expression. |
$ where ! (name = "Hello") |
and | Combines two expressions into their conjunction. |
$ from type sound where name = "Hello" and volume = 0 |
or | Combines two expressions into their disjunction. |
$ where name = "Hello" or name = "Hi" |
() | Specifies the order of logical operations on expressions. |
$ from type sound where (volume = -3 or volume = 0) and (name = "Hello" or name = "Hi") |
Perform complex data manipulations.
Synopsis | Description | Examples |
---|---|---|
OBJECT_EXPRESSION.{EXPRESSION1,EXPRESSION2,...} |
Composition operator. Returns a new JSON object composed of the enumerated expressions. The enumerated expressions become keys on the resulting objects, with corresponding values. You can use this operator to control which elements to obtain on Wwise objects. Note: This operator can only be used in return expressions. |
$ from type sound $ from type audiofilesource where markers.any() $ from type event |
OBJECT_EXPRESSION.[EXPRESSION1,EXPRESSION2,...] |
Concatenation operator. Returns a new list, which is the concatenation of the enumerated lists or objects. |
$ from type randomsequencecontainer |
EXPRESSION as NAME |
Alias keyword. Renames the specified expression to another name, which becomes the key in the results. You can use this keyword to rename complex assessors. Note: This keyword can only be used in return expressions. |
$ from type sound $ from type event |
Questions? Problems? Need more info? Contact us, and we can help!
Visit our Support pageRegister your project and we'll help you get started with no strings attached!
Get started with Wwise