Wwise SDK 2018.1.11

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 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 statement (expression) is executed once at the end of all transformations or directly from the from statement if no transformation was specified. The return expression specifies what elements of the Wwise objects to return. Any number of elements can be returned.

The return expression can contain properties and references, when prefixed with '@'. For example, it could contain '@Volume' or '@OutputBus'. When prefixed with a double '@@', the return will use the source of override, which is determined by the different values of 'override parent' in the hierarchy.

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

Refer to ak.wwise.core.object.get for a complete list of possible accessors.
Refer to Wwise Objects Reference for more information on the properties and references available.

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:

var query = {
    from: { id: [
        '{A076AA65-B71A-45BB-8841-5A20C52CE727}',
        '{2028C899-8300-4667-ADD0-ED10467BD91E}',
        '{24979032-B170-43E3-A2E4-469E0193E2C3}'
    ] }
};
var options = {
    return: ['id', 'name', '@Volume']
};
session.call('ak.wwise.core.object.get', [], query, options).then(
    function (res) {
        // Print the name and volume
        var objects = res.kwargs.return;
        for(let i = 0; i < objects.length;++i ){
            console.log(`${objects[i].name}: ${objects[i]['@Volume']}`);
        }
    },
    function (error) {
        console.log(`error: ${error}`);
    }        
);

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

var query = {
    from:{path:['\\Actor-Mixer Hierarchy']},
    transform:[
        {select:['descendants']},
        {where:['name:matches','^My']}
    ]
};
var options = {
    return: ['id', 'name']
};
session.call('ak.wwise.core.object.get', [], query, options).then(
    function (res) {
        // Print the name
        var objects = res.kwargs.return;
        for(let i = 0; i < objects.length;++i ){
            console.log(`${objects[i].name}`);
        }
    },
    function (error) {
        console.log(`error: ${error}`);
    }        
);

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.

Get started with Wwise