Version
menu_open
Warning: you were redirected to the latest documentation corresponding to your major release ( 2023.1.9.8628 ). 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.9
Wwise Authoring Query Language (WAQL) Reference

Overview

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 TRANSFORM
$ SOURCE TRANSFORM, TRANSFORM, ...
$ TRANSFORM

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.

Reference

Sources

Specify the starting point of the query.

SOURCE Query Source WAQL query to execute in the IntegrationDemo project

from object OBJECT_SPECIFIER
from object OBJECT_SPECIFIER, OBJECT_SPECIFIER, ...
OBJECT_SPECIFIER
OBJECT_SPECIFIER, OBJECT_SPECIFIER

Generates a sequence of objects from the specified objects.

OBJECT_SPECIFIER refers to one of the following forms:

  • Path: Double-quoted absolute path of the object, starting with a backslash and including the top physical folder.
  • Guid: Double-quoted 128-bit GUID surrounded by curly braces.
  • Qualified unique name: Double-quoted object name, prefixed by the object type. Only possible for object types that enforce a unique name across the project: Event, Bus, Effect, GameParameter, etc...
  • Qualified unique ID: Double-quoted object ID (short ID of 32-bits), prefixed by the object type. Only possible for object types that enforce a unique name across the project: Event, Bus, Effect, GameParameter, etc...

$ from object "\Actor-Mixer Hierarchy\Default Work Unit\Hello"
$ from object "\Master-Mixer Hierarchy\Default Work Unit\Master Audio Bus"
$ from object "{1514A4D8-1DA6-412A-A17E-75CA0C2149F3}"
$ from object "Event:Play_Hello"
$ from object "Event:2952797154"
$ from object "Event:Play_Hello", "Bus:Master Audio Bus"
$ "Event:Play_Hello", "Bus:Master Audio Bus"
$ "\Actor-Mixer Hierarchy"

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 type sound
$ from type Sound
$ from type randomSequenceContainer, switchContainer, blendContainer
$ from type bus

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:

  • Path: Double-quoted absolute path of the object, starting with a backslash and including the top physical folder.
  • Guid: Double-quoted 128-bit GUID surrounded by curly braces.

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 query "{4D1B2AA5-19D8-44D3-AAE5-94024469CE7C}"

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 search "foot walk"

from project Generates a sequence of objects including all objects of the project. $ from project

Transforms

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
$ from type Sound where -1 = @Volume
$ from type Sound where @OutputBus="Bus:Master Audio Bus"
$ from type Sound where @UserAuxSend0="AuxBus:Hangar_Env"
$ from type Event select children where @Target.path : "hello"
$ from type RandomSequenceContainer where childrenCount > 2 and childrenCount <= 4
$ from type Sound where notes : "All"
$ from type Sound where notes : "*audiokinetic*"
$ from type Sound where @UserAuxSend0 != null

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
$ from object "Bus:Master Audio Bus" select children
$ from object "\Actor-Mixer Hierarchy\Default Work Unit" select descendants, this where @Volume < 0
$ from object "\Actor-Mixer Hierarchy\Default Work Unit\Hello" select @OutputBus
$ from object "{CBCD492C-982D-4EE4-AE75-0019CA6577EF}" select parent.@Attenuation

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

Expressions

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
$ from type Sound select effects
$ from type Sound select @@Effects
$ from type Sound where outputBus="Bus:Master Audio Bus"

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
$ from object "\Actor-Mixer Hierarchy\Default Work Unit" select descendants, this

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
$ from type Sound where parent.name : "*engine"

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
$ "Event:Play_Hello" 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
$ from type Effect where owner.name :"*env"

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
$ from type sound where randomizer("highpass").min < 0
$ from type sound where randomizer("lowpass").max > 0
$ from type sound where randomizer("volume").enabled = true

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
$ from type Sound where @UserAuxSendVolume0 < 0
$ from type Sound where IsLoopingEnabled = true
$ from type sound where isloopingenabled = true

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:

  • "folder": for Physical folder objects, such as "\Actor-Mixer Hierarchy".
  • "rootFile": for Work Unit objects that are located inside
  • "nestedFile"

Note: This only works with objects of type WorkUnit.

$ where workunitType = "folder"
$ where workunitType = "rootFile" and !workunitIsDefault

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

List Functions

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")

Boolean Operators

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"
$ from type sound where volume = -1
$ from type sound where inclusion = true

!= Compares two values; either string, numerical, or boolean.

$ where name != "Hello"
$ from type sound where volume != -1
$ from type sound where inclusion != true

<
<=
>
>=

Compares two numerical values.

$ from type sound where volume < 0
$ from type sound where volume > -3 and 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"
$ where name : "Hel"
$ where name : "*ello"

= /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")
$ from type sound where ! (volume < -3)

and Combines two expressions into their conjunction.

$ from type sound where name = "Hello" and volume = 0
$ from type sound where volume > -3 and volume < 0

or Combines two expressions into their disjunction.

$ where name = "Hello" or name = "Hi"
$ from type sound where volume = -3 or volume = 0

() Specifies the order of logical operations on expressions.

$ from type sound where (volume = -3 or volume = 0) and (name = "Hello" or name = "Hi")

Advanced Operators

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
return: ["path", "OutputBus.{name, shortid}"]

$ from type audiofilesource where markers.any()
return: ["path", "Markers.{time, label}"]

$ from type event
return: ["name", "children.target.{path, type}"]

OBJECT_EXPRESSION.[EXPRESSION1,EXPRESSION2,...]

Concatenation operator. Returns a new list, which is the concatenation of the enumerated lists or objects.

$ from type randomsequencecontainer
return: ["[this, ancestors].name"]

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
return : ["outputbus.name as bus", "duration.max as duration"]

$ from type event
return : ["name as event", "children.target.[this, descendants].where(type=\"Sound").originalRelativeFilePath as originals"]

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