Wwise SDK 2022.1.7
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 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:
|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:
Additionally, queries take options which can specify:
The from statement provides several points for the query to start:
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.
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:
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.
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'.
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:
If an item of the return expression is incompatible or not present in the returned object, it won't be part of the results.
The ak.wwise.core.object.get function, as well as other functions take an option object, which defines:
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.
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:
Return the ID and name of every object in the Actor-Mixer Hierarchy starting with 'My', using a regular expression:
To learn more about WAQL, refer to Using the Wwise Authoring Query Language (WAQL)