There are several ways of creating Wwise objects with the Wwise Authoring API.
Creating Wwise Objects
It is possible to create most Wwise Objects using ak.wwise.core.object.create and ak.wwise.core.object.set. To learn more about the limitations, refer to Limitations with ak.wwise.core.object.create and ak.wwise.core.object.set.
Understanding the name conflict modes
When calling ak.wwise.core.object.create, or ak.wwise.core.object.set, it is possible to specify one of the four name conflict modes.
If an object already exists at destination with the same name:
- fail: The create function returns an error.
- replace: The object at destination is deleted (including its children), and a new object is created.
- rename: A new unique name is automatically assigned for the new object, appending numbers to it.
- merge: The object at destination is re-used, and the specified properties, references and children are merged to the destination leaving untouched the rest of the object.
Understanding lists and list modes
Lists are generic containers for storing objects. The objects in a given list are typically of the same type. Lists provide a convenient mechanism for populating and retrieving objects through WAAPI that are "owned" by another object. For example, the RTPCs for a given object are contained in the "RTPC" list of that object.
When calling ak.wwise.core.object.set, it is possible to specify one of two list modes.
If a list already contains objects:
- append: Add the new objects to the list if possible, keeping existing objects. Some lists might not permit duplicate equivalent objects: e.g., some properties of RTPCs in the RTPC list are exclusive so there can only be one RTPC with that property.
- replaceAll: Remove all existing objects and add the new objects, with the duplicate restriction.
For empty lists the behavior is to append.
Limitations with ak.wwise.core.object.create and ak.wwise.core.object.set
Sounds
It is possible to create Sound objects using ak.wwise.core.object.create and ak.wwise.core.object.set. However, there are significant limitations:
- It is not possible to associate an original WAV or MIDI file with a child Audio File Source object.
- It is not possible to associate a language with a child Audio File Source object.
- It is, however, possible to associate a Source plug-in with a child of a Sound object using ak.wwise.core.object.set.
For this reason, we don't recommend using ak.wwise.core.object.create and ak.wwise.core.object.set to create Sound objects that use WAV or MIDI files until these limitations are resolved in a future release of Wwise. Instead refer to Importing Audio Files and ak.wwise.core.audio.import.
Work Units
Creating Work Units with ak.wwise.core.object.create and ak.wwise.core.object.set requires the undo/redo history and the clipboard to be cleared. The Work Unit will also be saved upon creation, effectively creating a corresponding WWU file in the project.
- The
onNameConflict argument must be either 'fail', 'merge' or 'rename'. The 'replace' mode is not supported.
Queries
It is not possible to create Query objects with ak.wwise.core.object.create and ak.wwise.core.object.set.
Plug-ins
It is not possible to create plug-ins of the type Source, Effect, or Metadata with ak.wwise.core.object.create.
Lists
It is not possible to create objects to populate the "Metadata" and "Clips" lists with ak.wwise.core.object.set.
- Metadata are plug-ins which cannot be created.
- Clips require an AudioSourceRef which cannot be specified.
Due to the limitations below we do not recommend creating objects in the "Sequences" and "Stingers" lists with ak.wwise.core.object.set.
- Without the ability to assign a Segment to a stinger through WAAPI we do not recommend creating a Stinger in the "Stingers" list.
- Without the ability to create a MusicClip through WAAPI we do not recommend creating a MusicSequence in the "Sequences" list.
Using ak.wwise.core.object.create to create a single Actor-Mixer:
Refer to ak.wwise.core.object.create for more information.
{
"parent": "{a9129d80-07e0-11e7-93ae-92361f002671}",
"type": "ActorMixer",
"name": "My Actor-Mixer",
"children": []
}
| info | Note: The parent field indicates where to create the object in the project. The parent field, like most Wwise object fields, supports object ids (GUID) and object paths. To retrieve an object ID, refer to ak.wwise.core.object.get. You could, for example, retrieve the object ID by its project path. |
| info | Note: To retrieve an object ID from a Wwise project, you can hold the key SHIFT while right-clicking an object, then select Copy GUID(s) to clipboard. |
Using ak.wwise.core.object.create to create a hierarchy of objects with properties:
Refer to ak.wwise.core.object.create for more information.
{
"parent": "{a9129d80-07e0-11e7-93ae-92361f002671}",
"type": "ActorMixer",
"name": "Weapons",
"@Volume": "-2",
"children": [
{
"type": "RandomSequenceContainer",
"name": "BigGun",
"@RandomOrSequence": "1",
"children": [
{
"type": "Sound",
"name": "Gun1",
},
{
"type": "Sound",
"name": "Gun2",
}
]
}
]
}
Using ak.wwise.core.object.create to create Events
Refer to ak.wwise.core.object.create for more information.
{
"parent": "\\Events\\Default Work Unit",
"type": "Folder",
"name": "WAAPI",
"onNameConflict": "merge",
"children": [
{
"type": "Event",
"name": "Play_SFX",
"children": [
{
"name": "",
"type": "Action",
"@ActionType": 1,
"@Target": "\\Actor-Mixer Hierarchy\\Default Work Unit\\SFX"
}
]
}
]
}
Refer to Action for the list of possible event properties and action types.
Using ak.wwise.core.object.set to create a single Actor-Mixer
Refer to ak.wwise.core.object.set for more information.
{
"objects": [
{
"object": "{a9129d80-07e0-11e7-93ae-92361f002671}",
"children": [
{
"type": "ActorMixer",
"name": "My Actor-Mixer"
}
]
}
]
}
| info | Note: The object field indicates where to create the object in the project. The object field, like most Wwise object fields, supports object IDs (GUID) and object paths. To retrieve an object ID, refer to ak.wwise.core.object.get. You could, for example, retrieve the object ID by its project path. |
| info | Note: To retrieve an object ID from a Wwise project, you can hold the Shift key while right-clicking an object, then select Copy GUID(s) to clipboard. |
Using ak.wwise.core.object.set to create a hierarchy of objects with properties
Refer to ak.wwise.core.object.set for more information.
{
"objects": [
{
"object": "{a9129d80-07e0-11e7-93ae-92361f002671}",
"children": [
{
"type": "ActorMixer",
"name": "Weapons",
"@Volume": "-2",
"children": [
{
"type": "RandomSequenceContainer",
"name": "BigGun",
"@RandomOrSequence": "1",
"children": [
{
"type": "Sound",
"name": "Gun1"
},
{
"type": "Sound",
"name": "Gun2"
}
]
}
]
}
]
}
]
}
Using ak.wwise.core.object.set to create Events
Refer to ak.wwise.core.object.set for more information.
{
"objects": [
{
"object": "\\Events\\Default Work Unit",
"children": [
{
"type": "Folder",
"name": "WAAPI",
"children": [
{
"type": "Event",
"name": "Play_SFX",
"children": [
{
"name": "",
"type": "Action",
"@ActionType": 1,
"@Target": "\\Actor-Mixer Hierarchy\\Default Work Unit\\SFX"
}
]
}
]
}
]
}
],
"onNameConflict": "merge"
}
Refer to Action for the list of possible Event properties and Action types.
Using ak.wwise.core.object.set to create an RTPC with curve in the RTPC list using a Custom Control Input
Refer to ak.wwise.core.object.set for more information.
{
"objects": [
{
"object": "\\Actor-Mixer Hierarchy\\Default Work Unit\\My Sound",
"@RTPC": [
{
"type": "RTPC",
"name": "",
"@Curve": {
"type": "Curve",
"points": [
{ "x": 100.0, "y": -20.82785, "shape": "Linear" },
{ "x": 10000.0, "y": 21.8509, "shape": "Linear" }
]
},
"notes": "Property: OutputBusLowpass, ControlInput: RPM",
"@PropertyName": "OutputBusLowpass",
"@ControlInput": {
"type": "ModulatorLfo",
"name": "RAND",
"@LfoWaveform": 5
}
}
]
}
]
}
Using ak.wwise.core.object.set to create objects under multiple parents in one operation
Refer to ak.wwise.core.object.set for more information.
{
"objects": [
{
"object": "{a9129d80-07e0-11e7-93ae-92361f002671}",
"children": [
{
"type": "ActorMixer",
"name": "My Actor-Mixer"
}
]
},
{
"object": "{a9129d80-07e0-11e7-93ae-92361f002671}",
"children": [
{
"type": "ActorMixer",
"name": "Weapons",
"@Volume": "-2",
"children": [
{
"type": "RandomSequenceContainer",
"name": "BigGun",
"@RandomOrSequence": "1",
"children": [
{
"type": "Sound",
"name": "Gun1"
},
{
"type": "Sound",
"name": "Gun2"
}
],
"@RTPC": [
{
"type": "RTPC",
"name": "",
"@Curve": {
"type": "Curve",
"points": [
{ "x": 100.0, "y": -20.82785, "shape": "Linear" },
{ "x": 10000.0, "y": 21.8509, "shape": "Linear" }
]
},
"notes": "RTPC on BigGun. Property: OutputBusLowpass, ControlInput: RPM",
"@PropertyName": "OutputBusLowpass",
"@ControlInput": "{E31BAE21-CFA6-4655-81F6-E6FBDC802E9D}"
}
]
}
]
}
]
}
]
}
Using ak.wwise.core.object.set to set the Name, the Notes, a property, and a reference of an Object
Refer to ak.wwise.core.object.set for more information.
{
"objects": [
{
"object": "\\Actor-Mixer Hierarchy\\Default Work Unit\\MySound",
"name": "new name",
"notes": "This object's notes are set.",
"@Volume": 5.7,
"@OutputBus": "\\Master-Mixer Hierarchy\\Default Work Unit\\Master Audio Bus\\Environment Bus"
}
]
}
Using ak.wwise.core.object.set to set the Effect0 of a sound to a newly created Custom RoomVerb Effect plug-in
Refer to ak.wwise.core.object.set for more information.
{
"objects": [
{
"object": "\\Actor-Mixer Hierarchy\\Default Work Unit\\MySound",
"@Effect0": {
"type": "Effect",
"name": "myCustomEffect",
"classId": 7733251,
"@PreDelay": 24,
"@RoomShape": 99
}
}
]
}
Importing Audio Files
Audio files can be imported using the Wwise Authoring API by means of the same importation processor available through the Tab Delimited import in the Audio File Importer.
Using the Wwise Authoring API allows complete automation of the importation process and provides direct control in the programming language of your choice.
The import format allows great flexibility. You can import:
At a glance, the audio file importation allows:
- Importation and localization of audio files
- Automatic creation of actor mixer hierarchies
- Creation of Events
- Property Value assignation, such as Volume
- Reference assignation, such as the Output Bus
For more information about it, refer to https://www.audiokinetic.com/library/edge/?source=Help&id=importing_media_files_from_tab_delimited_text_file.
Examples:
Importing a WAV file, and creating the associated Sound object.
Using ak.wwise.core.audio.import to import audio files
Refer to ak.wwise.core.audio.import for more information.
Importing multiple sounds:
{
importOperation: "createNew",
default: {
importLanguage: "SFX"
},
imports: [
{
objectPath: "\\Actor-Mixer Hierarchy\\Default Work Unit\\<Sound>MyNewSound1",
audioFile: "C:\\sources\\1.wav",
"@Volume": 0.42
},
{
objectPath: "\\Actor-Mixer Hierarchy\\Default Work Unit\\<Sound>MyNewSound2",
audioFile: "C:\\sources\\2.wav",
"@Volume": 0.1
}
]
}
Importing multiple Audio Sources in the same Sound SFX object. Note that an underscore prefix was added to one of the Audio Source to ensure it stays first when sorted and becomes the active source:
{
importOperation: "replaceExisting"
default: {
importLanguage: "SFX"
},
imports: [
{
audioFile: "D:\\sources\\Version1.wav",
objectPath: "\\Actor-Mixer Hierarchy\\Default Work Unit\\<Sound SFX>MySound\\<AudioFileSource>_MyActiveSource"
},
{
audioFile: "D:\\sources\\Version2.wav",
objectPath: "\\Actor-Mixer Hierarchy\\Default Work Unit\\<Sound SFX>MySound\\<AudioFileSource>OtherSource"
}
]
}
Using ak.wwise.core.audio.import to localize audio files
Refer to ak.wwise.core.audio.import for more information.
To import a Sound Voice in English:
{
importOperation: "useExisting",
default: {
importLanguage: "English(US)"
},
imports: [
{
objectPath: "\\Actor-Mixer Hierarchy\\Default Work Unit\\<Sound>MyVoice",
audioFile: "C:\\sources\\en\\Hello.wav"
}
]
}
To localize a Sound Voice in French:
{
importOperation: "useExisting",
default: {
importLanguage: "French"
},
imports: [
{
objectPath: "\\Actor-Mixer Hierarchy\\Default Work Unit\\<Sound>MyVoice",
audioFile: "C:\\sources\\fr\\Hello.wav"
}
]
}
Import several Audio Sources of different languages in the same Sound Voice at the same time:
{
importOperation: "useExisting",
imports: [
{
audioFile: "D:\\sources\\hello_en.wav",
objectPath: "\\Actor-Mixer Hierarchy\\Default Work Unit\\<Sound Voice>hello\\<AudioFileSource>hello_en",
importLanguage:"EN_US"
},
{
audioFile: "D:\\sources\\hello_fr.wav",
objectPath: "\\Actor-Mixer Hierarchy\\Default Work Unit\\<Sound Voice>hello\\<AudioFileSource>hello_fr",
importLanguage:"FR_CA"
}
]
}
| info | Note: Make sure the language exists in your project, and make sure the case is also matching. |