Version
menu_open
Wwise SDK 2024.1.0
Querying the Wwise Project

The Wwise Authoring API provides a comprehensive query system allowing you to retrieve the most important aspects of the Wwise project. More specifically, it allows you to retrieve any object in the project.

The query system is built into the ak.wwise.core.object.get function. Refer to its reference documentation for more details.

Queries can take 2 different forms:

Note: We recommend using WAQL instead of the JSON query format. WAQL provides greater functionality and coverage, has better error handling and is easier to use.

WAQL queries

WAQL queries allows to specify the entire query in one unique line of text.

Tip: WAQL queries can also be used directly inside Wwise Authoring for testing. This is especially useful to verify the query syntax and results before implementing it inside your WAAPI program or script. For example, type the following WAQL query in the Wwise toolbar or List View search fields:
$ from type Event

Learn more about WAQL:

JSON queries

Note: JSON queries are not recommended. We recommend using WAQL queries instead. Refer to Using the Wwise Authoring Query Language (WAQL) and Getting Started with WAQL.

JSON Queries are structured into two parts:

  • from: Specifies the query starting point. This is the source from which the data is taken.
  • transform: Specifies a series of transformations to apply to the objects. Transformations can be added in sequence.

Additionally, queries take options which can specify:

  • return: Specifies what to return from the objects. If not specified, the default is ['id', 'name'].
  • platform: Specifies the platform to use for the query. If not specified, the default is the current platform.

from

The from statement provides several points for the query to start:

  • id: Specifies an array of object ID (GUID). It is useful for looking up an object when you already have its ID.
  • name: Specifies an array of object names qualified by their type, in the form of type:name. Only object types that have globally-unique names are supported. Refer to Wwise Objects Reference for available types.
  • search: Specifies text to search in Wwise object names and notes. This uses the same search engine as the Wwise search.
  • path: Specifies an array of paths to look up. Paths must be absolute and must start with the category name, which is equivalent to the physical folder name. For example: \Actor-Mixer Hierarchy\Default Work Unit\MySound.
  • ofType: Specifies an array of Wwise object types. This is useful for retrieving all objects of a specific object type, such as retrieving all Game Parameters. Refer to Wwise Objects Reference for available types.

transform

The transform statement provides several transformation functions that can be used to transform the objects being selected. The first transformation is applied on the objects selected by the from statement. The other transformations are applied on the results of the previous transformation.

Multiple transformations can be added in sequence.

  • select parent: For every object, it selects the parent of the object.
  • select children: For every object, it selects the list of children of the object.
  • select descendants: For every object, it selects all of the children recursively.
  • select ancestors: For every object, it selects all of the parents recursively.
  • select referencesTo: For every object, it selects all objects referencing the object.
  • where: It allows to filter the results of the previous iterator. The possible criteria are:
    • name:contains: Case-insensitive search of text in the object name.
    • name:matches: Case-insensitive regular expression search of the object name.
    • type:isIn: Filters the results of the previous iterator by keeping only objects of certain types. See Wwise Objects Reference for the list of object types.
    • category:isIn: Filters the results of the previous iterator by keeping only objects of certain categories.
  • distinct: Filters the results of the previous iterator by keeping only unique objects.

Return Options

The return expression specifies which elements of the Wwise objects to return. Any number of elements can be returned.

The return expression can contain:

Two optional prefixes exist for property and reference names:

  • '@PROPERTYNAME': Returns the value directly set on the object. This ignores the override system, and may return a value that is unused and hidden.
  • '@@PROPERTYNAME': Returns the value as resolved by the override system. It may return the value inherited from a parent, or the value of the object directly, if the object overrides the property.

When no prefix is used, it returns the value as resolved by the override system. This is the equivalent of using the @@ prefix. We recommend not using a prefix.

Examples:

  • 'volume', 'Volume', '@Volume', '@@Volume': returns the volume of the object. Since the volume is not overridable, all of these are equivalent. Note that property names are case-insensitive.
  • 'OutputBus', 'outputbus', '@@OutputBus': returns the Output Bus as resolved by the override system (using Override Parent). This is the value being used for playback. Note that reference names are case-insensitive.
  • '@OutputBus': returns the Output Bus as set on the object directly. This is also the value persisted on the Work Unit for this object. This value might not be used, and could be hidden, if the object does not have the Override Parent option checked.

When an expression resolves to a valid reference, it can be queried further for the referenced object's properties. For example, if the reference 'UserAuxSend0' on a Sound object references an existing Auxiliary Bus, it is possible to query a property of this Auxiliary Bus by appending a dot ('.'), followed by the property descriptor. Querying for the Attenuation of the referenced Auxiliary Bus would therefore simply be 'UserAuxSend0.Attenuation'.

Examples:

  • OutputBus.name: returns the name of the output bus.
  • parent.name: returns the name of the parent object.
  • parent.parent.type: returns the type of the grandparent object.
  • OutputBus.Volume: returns the volume of the output bus.
  • OutputBus.Attenuation.name: returns the name of the output bus.
  • Attenuation.path: returns the path of the output bus.
  • Effects.first.effect.id: returns the ID of the first Effect.

Some objects have properties with certain capabilities, such as randomization. To retrieve values related to these capabilities, special objects bound to the properties can be queried through function-like accessors. For example, the randomizer feature is described by a Modifier object linked to certain properties of an object. This object can be queried as 'randomizer("PropertyName")', where PropertyName is the name of a property such as 'Volume'. When the accessor provides a valid reference, the object returned can be queried further as described previously. For example, the 'Max' property of the Volume randomizer can be obtained like so: 'randomizer("Volume").@Max'.

The list possible of accessors is as follows:

  • randomizer

If an item of the return expression is incompatible or not present in the returned object, it won't be part of the results.

Other options

The ak.wwise.core.object.get function, as well as other functions take an option object, which defines:

  • the return expression (see section above)
  • the platform: the ID (guid) or name of the platform.
  • the language: the ID (guid) or name of the language.

Some of the accessors are sensitive to options. For example, when retrieving a property or reference value, you can specify the platform to get the unlinked values. If the platform is not specified, the current platform is used. The language can also be specified to retrieve language specific information, such as audio source data for a Sound object. When not specified, the current language is used.

Examples

Refer to Project Code for initialization.

More examples can be found in ak.wwise.core.object.get.

Return the ID, name, and voice volume for a list of objects:

from waapi import WaapiClient
import pprint
# Connect (default URL)
client = WaapiClient()
# Return two objects
args = {
'waql': '$ "\\Audio Devices\\Default Work Unit\\System", "{1514A4D8-1DA6-412A-A17E-75CA0C2149F3}"'
}
options = {
'return': ['id', 'name', 'Volume']
}
result = client.call("ak.wwise.core.object.get", args, options=options)
pprint.pprint(result)
# Disconnect
client.disconnect()

Return the ID and name of every object in the Actor-Mixer Hierarchy starting with 'My', using a regular expression:

from waapi import WaapiClient
import pprint
# Connect (default URL)
client = WaapiClient()
# Return all objects under the actor-mixer hierarchy with loop in the name
args = {
'waql': '$ "\Actor-Mixer Hierarchy" select descendants where name = /^My/'
}
options = {
'return': ['name', 'id']
}
result = client.call("ak.wwise.core.object.get", args, options=options)
pprint.pprint(result)
# Disconnect
client.disconnect()

To learn more about WAQL, refer to Using the Wwise Authoring Query Language (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