Table of Contents
Wwise SDK 2019.2.8
|
Command Add-ons Overview
Command add-ons allow to define new commands for Wwise Authoring. Each command is associated with an external program that is being triggered by Wwise. Programs that are executed can receive a variety of predefined arguments that are derived from the currently selected objects.
Add-on commands can be triggered in different ways:
- Keyboard Shortcut
- Contextual Menu
- Main Menu
- Control Surface
- WAAPI using ak.wwise.ui.commands.execute
Add-on commands can be defined on several levels:
- In the user data directory, under "%APPDATA%\\Audiokinetic\\Wwise\\Add-ons\\Commands"
- In the installation folder, under "Authoring\\Data\\Add-ons\\Commands"
- In the project folder, under "Add-ons\\Commands"
- Using ak.wwise.ui.commands.register
![]() |
Note: In case of id conflict, only the first command loaded will be registered. The commands are loaded in the order specified above. |
![]() |
Note: Command add-ons specified in the installation folder or in the user data directory are loaded at Wwise startup. Command add-ons specified under the project are loaded at project load time. |
Additionally, every time a command is executed in Wwise, WAAPI will notify the subscribers with ak.wwise.ui.commands.executed, passing the selected objects and honoring WAAPI return options. Add-on commands can be defined with no program to execute, so you could use the publication event to execute your own code in a WAAPI client.
Definition of Command Add-ons
Definition Fields
A command is described by the following fields:
- id: Defines a human readable unique ID for the command. To reduce the risk of ID conflicts, please use a concatenation of the author name, the product name, and the command name.
- displayName: Defines the name displayed in the user interface.
- program: Defines the program or script to run when the command is executed. Arguments are specified in 'args'.
- args: Defines the arguments. Refer to the documentation for the supported built-in variables. Note that in the case of multiple selection, the variables are expanded based on the startMode field.
- cwd: Defines the current working directory to execute the program.
- defaultShortcut: Defines the shortcut to use by default for this command. If the shortcut conflicts, it won't be used. This shortcut can be changed in the Keyboard Shortcut Manager.
- redirectOutputs: Defines if the standard output streams of the program (stdout + stderr) should be redirected and logged to Wwise on termination. Note that this feature should only be used for short-living programs. The value is of boolean type and false by default.
-
startMode: Specifies how to expand variables in the arguments field in case of multiple selection in the Wwise user interface. Possible values are:
- SingleSelectionSingleProcess: Only supports single selection, will start the program once.
- MultipleSelectionSingleProcessSpaceSeparated: Program is started once with variables expanded to space separated arguments, each enclosed in double-quotes.
- MultipleSelectionMultipleProcesses: Program is started once per item selected, in parallel. Each running instance receives one selected item.
-
contextMenu: Specifies where the command will appear in the context menus and for which object types the command will be available. This field can include any of the following items:
- basePath: Defines a forward-slash separated path for the parent sub-menus. If empty, the menu is inserted at the first level.
- enabledFor: Defines a comma-separated list of the object type names for which the item is enabled. Refer to Wwise Objects Reference for the list of type names supported. If empty, any type is allowed.
- visibleFor: Defines a comma-separated list of the object type names for which the item is visible. Refer to Wwise Objects Reference for the list of type names supported. If empty, any type is allowed.
-
mainMenu: Specifies where the command will appear in the Wwise menus.
- basePath: Defines a forward-slash separated path for the parent sub-menus. It must at least define one level, which is associated with the top menu.
Common Directories
The following predefined directories should be used in the program
field to avoid machine-specific absolute paths. They can also be used in the args
field to pass a path as an argument to the program and in the cwd
field to define the current working directory.
Variable | Referenced Location |
---|---|
${CurrentCommandDirectory} | The current command directory. As mentioned above, it should be "Add-ons\\Commands". |
${WwiseInstallRoot} | The Wwise installation directory. |
${WwiseInstallBin} | The Wwise.exe directory. |
${WwiseInstallAddons} | "${WwiseInstallRoot}\\Authoring\\Data\\Add-ons" |
${WwiseUserAddons} | "%APPDATA%\\Audiokinetic\\Wwise\\Add-ons" |
${WwiseProjectRoot} | The Wwise project directory. |
${WwiseProjectAddons} | "${WwiseProjectRoot}\\Add-ons" |
${WwiseProjectOriginals} | "${WwiseProjectRoot}\\Originals" |
${WwiseProjectSoundbanks} | Platform-specific generated soundbanks directory. |
Argument Variables
The following predefined variables can be used in the args
field (program arguments). When a multiple selection is used, please refer to startMode
to learn how these variables resolve.
Variable | Type | Description |
---|---|---|
${id} | string | The object ID (GUID). |
${name} | string | The object name. |
${notes} | string | The object notes. |
${type} | string | The object type. Refer to Wwise Objects Reference for more information on the types available. |
${path} | string | The object path from the project root. Ex: '\\Actor-Mixer Hierarchy\\Default Work Unit\\Sound1' |
${isPlayable} | boolean | True if the object can be played in Transport. |
${shortId} | integer | The object short ID. |
${classId} | integer | The object class ID. |
${category} | string | The object category. For example: 'Actor-Mixer Hierarchy' |
${filePath} | string | The path to the file containing the object. The path can be a Work Unit file, or a project file. |
${childrenCount} | number | The number of children for the object. |
${sound:originalWavFilePath} | string | Absolute path to the original WAV file. Only valid for Sound and Audio Source objects. |
${sound:convertedWemFilePath} | string | Absolute path to the converted WEM file. Specify the platform in the options. Only valid for Sound and Audio Source objects. |
${soundbank:bnkFilePath} | string | Absolute path to the generated SoundBank file associated with the SoundBank object. Only valid for SoundBank objects. |
${workunit:isDefault} | boolean | True if the Work Unit is the default. |
${workunit:type} | string | The type of the Work Unit. Please note that, like Work Units, physical folders have the type "WorkUnit". Physical folders will have the workunit:type "folder". Possible values : "folder", "rootFile", "nestedFile" |
${workunit:isDirty} | boolean | True if a Work Unit or a Project (wproj file) is dirty, meaning it is modified but not saved. |
Command Add-ons Examples
Examples Using a Command Definition File
To create new commands, create a JSON file under one of the directories listed in Defining Command Add-ons and specify the version to be 2. Please be aware that multiple 3rd parties can create files under these directories. In order to reduce the risk of filename conflicts, we recommend using the following convention for the filenames: companyname_productname.json
Example: mycompany_myproduct.json
Example Using WAAPI
The exact same JSON command code as above can be passed to WAAPI ak.wwise.ui.commands.register, to add new commands to the current Wwise process.
Please note that commands added with ak.wwise.ui.commands.register are not persisted. They will remain until the Wwise process terminates. You will have to register them again next time.
Using Add-on Commands in Conjunction with WAAPI
Add-on commands can be used to execute WAAPI scripts or programs. This gives you access to Wwise functionalities and project data. Refer to Using the Wwise Authoring API (WAAPI) to learn what you can do with WAAPI.
Using Add-on Commands on Mac
Add-on commands are executed on Mac using
. Any executable or script can be directly specified in program
. To open an app, you must use the open
command. Paths with spaces are expected to be enclosed with single quotes.
Example: mycompany_myproduct_forMac.json