Wwise SDK 2021.1.9
Defining Command Add-ons

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:

Add-on commands can be defined on several levels:

  • In the user data directory, under:
    • Windows: "%APPDATA%\\Audiokinetic\\Wwise\\Add-ons\\Commands"
    • macOS: "$HOME/Library/Application Support/Audiokinetic/Wwise/Add-ons/Commands"
  • In the installation folder, under:
    • Windows: "%WWISEROOT%\\Authoring\\Data\\Add-ons\\Commands"
    • macOS: "/Library/Application Support/Audiokinetic/Wwise <version>/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 directory where the current command is defined. As mentioned above, it should be "Add-ons\\Commands".
${WwiseInstallRoot} The Wwise installation directory.
${WwiseInstallBin} The Wwise.exe directory.
${WwiseInstallAddons} Windows: "${WwiseInstallRoot}\\Authoring\\Data\\Add-ons"
macOS: "/Library/Application Support/Audiokinetic/Wwise <version>/Authoring/Data/Add-ons/Commands"
${WwiseUserAddons} Windows: "%APPDATA%\\Audiokinetic\\Wwise\\Add-ons"
macOS: "$HOME/Library/Application Support/Audiokinetic/Wwise/Add-ons/Commands"
${WwiseProjectRoot} The Wwise project directory.
${WwiseProjectAddons} "${WwiseProjectRoot}\\Add-ons"
${WwiseProjectOriginals} "${WwiseProjectRoot}\\Originals"
${WwiseProjectSoundbanks} Platform-specific generated soundbanks directory.

Argument Variables

Zero to many variables can be used in the args field (program arguments). Variables provide a way to access information from the selected objects. For example, you could retrieve an object id and pass it as an argument. Variables also provide a way to access property values from the selected objects, including Custom Properties values. To learn more about Custom Properties, refer to Defining Custom Properties.

For a complete list of possible expressions in variables, refer to the Object Expressions and Value Expressions sections in Wwise Authoring Query Language (WAQL) Reference.

When the selection is multiple, refer to startMode to learn how these variables are resolved.

Examples:

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'
${filePath} string The path to the file containing the object. The path can be a Work Unit file, or a project file.
${originalWavFilePath} string Absolute path to the original WAV file. Only valid for Sound and Audio Source objects.
${convertedWemFilePath} string Absolute path to the converted WEM file. Specify the platform in the options. Only valid for Sound and Audio Source objects.
${soundbankBnkFilePath} string Absolute path to the generated SoundBank file associated with the SoundBank object. Only valid for SoundBank objects.
${workunitIsDirty} boolean True if a Work Unit or a Project (wproj file) is dirty, meaning it is modified but not saved.
${Volume} string The Voice Volume.
${OutputBus.name} string The Output Bus name.

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

{
"version":2,
"commands":[
{
"id":"ak.edit_in_vscode",
"displayName":"Edit in Visual Studio Code",
"defaultShortcut":"C",
"program":"code",
"startMode":"MultipleSelectionSingleProcessSpaceSeparated",
"args":"${filePath}",
"cwd":"",
"contextMenu":{
"basePath":"Editors",
"enabledFor":"Sound,ActorMixer,SwitchContainer,RandomSequenceContainer"
},
"mainMenu":{
"basePath":"Extra"
}
},
{
"id":"ak.open_in_wavosaur",
"displayName":"Edit in My Wav Editor",
"defaultShortcut":"W",
"program":"c:\\MyWavEditor\\WavEditor.exe",
"args":"${sound:originalWavFilePath}",
"cwd":"",
"contextMenu":{}
}
]
}

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

/bin/sh -c

. 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

{
"version":2,
"commands":[
{
"id":"ak.edit_in_audacity",
"displayName":"Open wav in Audacity",
"defaultShortcut":"A",
"program":"open -n -a /Applications/Audacity.app",
"startMode":"SingleSelectionSingleProcess",
"args":"${sound:originalWavFilePath}",
"cwd":"",
"contextMenu": {
"basePath":"Editors",
"enabledFor":"Sound"
}
},
{
"id":"ak.edit_in_script",
"displayName":"Open in script",
"defaultShortcut":"A",
"program":"'/path/to/folder with spaces/myScript.sh'",
"startMode":"SingleSelectionSingleProcess",
"args":"${sound:originalWavFilePath}",
"cwd":"",
"contextMenu": {
"basePath":"Editors",
"enabledFor":"Sound"
}
}
]
}