Table of Contents

Wwise SDK 2019.1.6
Using the Command Line

A number of Wwise operations are available from its command-line interface, including SoundBank generation. This can prove useful when integrating Wwise as part of an automated process, such as a daily game build with audio assets.

Wwise Command Line

There are two distinct ways to call WwiseCLI.exe, the Wwise command line executable, depending on whether you run it on Windows or Mac.

On Windows
For Windows, WwiseCLI.exe is called directly under "%WWISEROOT%\Authoring\x64\Release\bin". Command-line parameters should follow this basic structure, where project and operation are mandatory:
WwiseCLI.exe project.wproj -operation [-option1 [parameters]] [-option2 [parameters]] ...
On Mac
For Mac, WwiseCLI.exe is called indirectly via the WwiseCLI.sh shell script. To be able to successfully run the WwiseCLI.sh shell script on a Mac, each user who wants to run the WwiseCLI.sh shell script must:
  1. Launch Wwise.app and install the MS VC++ redistributable.
  2. Quit Wwise.app.
It is then possible to invoke the WwiseCLI.sh shell script from the Terminal passing the same command line arguments as its Windows counterpart using either Unix or Windows style paths.
Unix path example:
MAC:~ username$ /Path/to/Authoring/Wwise.app/Contents/Tools/WwiseCLI.sh "/Volumes/Drive/Path/to/project.wproj" -operation [-option1 [parameters]] [-option2 [parameters]]
Windows path example:
MAC:~ username$ /Path/to/Authoring/Wwise.app/Contents/Tools/WwiseCLI.sh "Z:\Volumes\Drive\Path\to\project.wproj" -operation [-option1 [parameters]] [-option2 [parameters]]

Any string parameter containing spaces should be wrapped in quotation marks, as illustrated in this Example. All path parameters must be specified using only backslashes, with no trailing backslashes.

Operations

One and only one of these operations must be specified on the command-line.

Operation Description Applicable Options
-ConvertExternalSources External Sources conversion. While External Sources is also triggered by -GenerateSoundBanks, -ConvertExternalSources can be used to process sources not contained in the Wwise Project. This operation has two optional parameters: the platform and a path to a WSOURCES file. Providing a platform will generate only that platform. Providing a WSOURCE file will override the External Source Input file paths in the Project Settings, for the given platform (or all if no platform is specified). This operation is not compatible with the -Save option. Examples:
  • -ConvertExternalSources: Converts all platforms, with the source lists provided in the Project Settings
  • -ConvertExternalSources Windows: Converts only the sources for the Windows platform.
  • -ConvertExternalSources Windows -ConvertExternalSources XBoxOne : Converts only Windows and Xbox One.
  • -ConvertExternalSources MySources.wsources : Converts list specified, on all platforms.
  • -ConvertExternalSources Windows MySources.wsources : Converts all files on Windows and uses the file list specified.
  • -ConvertExternalSources -ExternalSourcesOutput ..\..\YourNewExternalSourceFolder : Overrides default external sources output folder for all platforms.
  • -ConvertExternalSources Windows -ExternalSourcesOutput ..\..\YourNewExternalSourceFolderForWindows : Overrides default external sources output folder for the Windows platform.
-CreateNewProject Create a blank new project. The project must not exist already. The folder must have the same name as the WPROJ file. If the folder does not exist, it is created. -Platform must be used to define at least one platform to use for the project. You can define multiple platforms.
-LoadProject Load a project. Will not run any other operation and will simply exit after loading the project. Can be used with -Save to migrate and save the project.
-GenerateSoundBanks SoundBank generation. SoundBank generation is performed according to the settings stored in the project; custom user settings are ignored when SoundBank generation is launched from the command line. However, some of these settings can be overridden from the command line.
Note: When the -Platform, -Bank, and/or -Language flags are omitted, the application generates the SoundBanks for all platforms and/or languages.
-SoundFrameServer Start a command-line SoundFrame server, to which client applications using the Sound Frame library can connect. An optional numerical Process ID can be specified as parameter to this option, so that this server only accepts connection with a given process. The server will run until it receives a CTRL-C signal.
-TabDelimitedImport Import a tab-delimited file to create and modify different objects hierarchy. If the option -Save is not specified, the changes made to the project as a result of the imported tab-delimited file will not be persisted.
-Waapi Start a command-line Wwise Authoring API server, to which client applications using the Wwise Authoring API can connect.
Note: As indicated in the Supported by sections, some WAAPI functions only work when running Wwise Authoring as a GUI.

Options

Each option is applicable to only certain Operations. Invalid options are ignored.

  • -AbortOnLoadIssues:Aborts the original command, such as -GenerateSoundBanks, if a project load issue is detected. All logged project load issues are printed to screen.
  • -AudioSourceFromOriginal:It is possible that a project already contains some audio source files by the same name of the imported ones. In which case, by adding this flag, the operation will use those instead of replacing them with those described by the tab-delimited file.
  • -Bank:Specifies which SoundBanks will be generated. This option must be followed by the name of the SoundBank to be generated. Multiple SoundBanks can be specified. If no SoundBank is specified, all will be generated. Alternatively, a text file containing a list of SoundBank names can be specified, by passing in the full path to the text file, including the extension '.txt'.
  • -Cache:Overrides the project's cache folder path and instead uses the path (relative) specified with the command.
  • -ClearAudioFileCache:Deletes the content of the Wwise audio file cache folder prior to converting source files and generating SoundBanks, which ensures that all source files are reconverted. This option is ignored if the flag -GenerateSoundBanks is not specified. Note that the whole cache is cleared, for all platforms, regardless of the -Platform argument.
  • -ContinueOnError:Use this flag if you want to continue on error if an error occurred while importing definition files.
  • -CustomGlobalClosingCmd:Overrides the global closing step that was defined in Wwise. This option must be followed by the new command line (use quotes if there are spaces). An empty string ("") specified for the command-line means no global closing step will be executed.
  • -CustomGlobalOpeningCmd:Overrides the global opening step that was defined in Wwise. This option must be followed by the new command line (use quotes if there are spaces). An empty string ("") specified for the command-line means no global opening step will be executed.
  • -CustomPostGenCmd:Overrides the custom post-generation step command line that was defined for this platform in Wwise. This option must be followed by the platform identifier (listed above), followed again by the new command line (use quotes if there are spaces). To override the custom post-generation step command line of another platform, repeat the flag -CustomPostGenCmd followed by the other platform's identifier and its new command line. An empty string ("") specified for the command-line means no pre-generation step will be executed.
  • -CustomPreGenCmd:Overrides the custom pre-generation step command line that was defined for this platform in Wwise. This option must be followed by the platform identifier (listed above), followed again by the new command line (use quotes if there are spaces). To override the custom pre-generation step command line of another platform, repeat the flag -CustomPreGenCmd followed by the other platform's identifier and its new command line. An empty string ("") specified for the command-line means no pre-generation step will be executed.
  • -ExternalSourcesOutput:Overrides the output path set in the Project Settings for the converted external source files. This option has two parameters, the platform (optional) and the path (must be relative). This option is valid only with -ConvertExternalSources.
  • -HeaderFile:Generates the header file Wwise_IDs.h, even if this option is not specified in the project settings. This option will be ignored if the flag -GenerateSoundBanks is not specified.
  • -HeaderFilePath:Overrides the header file path specified in the project settings. This option must be followed by the path (absolute or relative) in which the header file (Wwise_IDs.h) will be written. This is only effective if the header file's creation is required.
  • -ImportDefinitionFile:Imports a SoundBank definition file. This option must be followed by the full path of the bank definition file to be imported. Multiple files can be specified. If the option -Save is not specified, the changes made to the project as a result of the imported definition file will not be persisted.
  • -ImportLanguage:With the tab-delimited import operation it is possible to import voices. This flag is used to specify the language of the imported voices. This option must be followed by one of the language identifiers listed with the -Language flag. Note that only audio files are added for this operation; any attempt to concurrently perform other operations, such as volume adjustments, will be ignored.
    Warning: When the -ImportLanguage flag is omitted, the import operation will treat all the audio source files as SFX and not voices.
  • -Language:Specifies for which languages the SoundBanks will be generated. This option must be followed by a language identifier defined in the project. Each specified language must be prefixed with this flag. This option will be ignored if the flag -GenerateSoundBanks is not specified.
  • -NoDecode:Avoids generating DECODED files in the .cache folder, which saves CPU and disk space for your Wwise project. It will also reduce the SoundBank generation time.
    Warning: Take note that if you do not generate the DECODED files, playing back these sounds in Wwise Authoring could result in an outdated playback or no playback at all. Clearing the file cache is recommended after using this option.
  • -NoWwiseDat:Disables use of hidden 'wwise.dat' file when converting audio files. This is useful in conjunction with -ConvertExternalSources when calling WwiseCLI from a build tool which already handles file dependencies, as it allows multiple instances of Wwise to convert to the same directory simultaneously without conflicting.
  • -Platform:Specifies for which platforms the SoundBanks will be generated. This option must be followed by a platform identifier (listed below). Each specified platform must be prefixed with this flag.
    • Android
    • iOS
    • Mac
    • PS4
    • Windows
    • XboxOne
  • -Quiet:Disables all non-error console text output.
  • -Save:Enables saving of the Wwise project. When used with -ImportDefinitionFile or -TabDelimitedImport, the project changes resulting from the bank importation process will be saved in the Work Units. Enabling saving also allows migration of the project to proceed from the command line. Note that when saving the project, the user is responsible for making sure the files of the project are not "read only", meaning that the user is responsible for performing any "check-out" from the source control prior to executing the command-line request.
  • -SoundBankPath:Overrides the SoundBank path specified for this platform. This option must be followed by the platform identifier (listed above), followed again by the new path (absolute or relative, use quotes if there are spaces). To override the path of another platform, repeat the flag -SoundBankPath followed by the other platform's specifier and its new path.
  • -TabDelimitedOperation:Determines how import object creation is performed. For each object created:
    • CreateNew will create a new object; the object will be given the desired name if possible, otherwise a new unique name will be used.
    • UseExisting will use the object if it exists, updating the specified properties; otherwise it will create a new object.
    • ReplaceExisting will create a new object; if an existing object has the same name then the existing object is destroyed.
      Note: When the -TabDelimitedOperation flag is omitted, the import operation will default to UseExisting.
  • -Verbose:Enables extra console text output.
  • -WaapiAllowedAddr:Specifies the IP (IPv4 or IPv6) addresses that are allowed to connect to WAAPI. This option must be followed by a comma-separated list, for example: 127.0.0.1,::1. Use * to allow any host to connect.
    Caution: Using * could present a security risk. See Network Security to learn more about using WAAPI safely.
  • -WaapiAllowedOrigin:Specifies the hosts that are allowed to connect to WAAPI. This option must be followed by a comma-separated list, for example: www.myhost.com,www.myhost2.com. Validation is performed on the HTTP header Origin. Connections that do not provide the Origin header, as well as file-based connections (for example: file://), are always allowed. Use * to allow any host to connect.
    Caution: Using * could present a security risk. See Network Security to learn more about using WAAPI safely.
  • -WaapiHttpPort:Specifies the port number used by the Wwise Authoring API when using HTTP POST. This option must be followed by a port number between 0 and 65,535. Using 0 will prevent the server from running.
  • -WaapiWampPort:Specifies the port number used by the Wwise Authoring API when using WAMP. This option, which takes precedence over the User Preferences, must be followed by a port number between 0 and 65,535. Using 0 will prevent the server from running.

Example

An example of SoundBank generation from the command line is shown below. It generates the English (US) and French (Canada) language SoundBanks for the Windows platform. The example also defines a specific custom post-generation command, which overrides the post-generation step defined in the project and user settings.

"%WWISEROOT%\Authoring\x64\Release\bin\WwiseCLI.exe" "C:\Project name.wproj" -GenerateSoundBanks -Language English(US) -Language French(Canada) -Platform Windows
-Bank BankLevel1 -Bank BankLevel2 -ImportDefinitionFile "C:\BankDefinitionFile\MyProjectDefinition.txt"
-CustomPostGenCmd Windows "\"$(WwiseExePath)\tools\FilePackager.Console.exe\" -generate -info \"$(InfoFilePath)\" -output \"$(SoundBankPath)\$(WwiseProjectName).pck\" -blocksize 16 -hideprogressui true"

External Sources Conversion Example

Here is an example for converting external sources from the command line. The conversion will be done only for the Xbox One.

"%WWISEROOT%\Authoring\x64\Release\bin\WwiseCLI.exe" "C:\Project name.wproj" -ConvertExternalSources XboxOne

Create New Project Example

Here is an example for creating a new Wwise project from the command line for the Windows and the Mac platforms. Please note that the Wwise project folder must not already exist.

"%WWISEROOT%\Authoring\x64\Release\bin\WwiseCLI.exe" "C:\ProjectName\ProjectName.wproj" -CreateNewProject -Platform Windows -Platform Mac

Migrating A Project Example

Here is an example for migrating a Wwise project from the command line.

"%WWISEROOT%\Authoring\x64\Release\bin\WwiseCLI.exe" "C:\ProjectName\ProjectName.wproj" -LoadProject -Save

Tab-delimited Import Example

This is an example for importing a tab-delimited file describing an object hierarchy that contains American English voices. It will replace the objects that already exist but will use the original audio source files.

"%WWISEROOT%\Authoring\x64\Release\bin\WwiseCLI.exe" "C:\Project name.wproj" -TabDelimitedImport "C:\tab delimited file.txt" -TabDelimitedOperation ReplaceExisting -ImportLanguage English(US) -AudioSourceFromOriginal

Error Codes

When working from the command line, WwiseCLI.exe will return one of the following return codes:

  • WWISE_ERROR_CODE_SUCCESS 0
  • WWISE_ERROR_CODE_ERROR 1 (when Fatal Error or Error are encountered)
  • WWISE_ERROR_CODE_WARNING 2 (when Warnings are encountered)

Although your SoundBanks may generate properly with warnings, it is strongly recommended that you consider these warnings as errors. For example, WwiseCLI.exe will return an error code when a source file is missing. Although a missing source file will not prevent your SoundBanks from being generated, the resulting SoundBanks will potentially be incomplete.

You can change the severity of most messages encountered during the SoundBank Generation by going to Project Settings > Logs in Wwise. Changing the severity of the messages will have an impact on the return codes.

Error Tracking

When working from the command line app, all errors are reported using stdout.

Wwise Authoring Tool from the Command Line

In addition to the Wwise command line interface (WwiseCLI.exe), users may call the Wwise Authoring tool from the command line using Wwise.exe. It has three options:

  • -AutomationMode: Enables the automation mode in Wwise. This reduces the potential interruptions caused by message boxes and dialogs. For instance, enabling the automation mode silently accept: project migration, project load log, EULA acceptance, project license display, and generic message boxes.
  • -SetTitleBarText:Specify a line of text to be appended to the title bar of the main Wwise Authoring window. This option must be followed by the text to append, which must be enclosed in quotation marks if it has spaces.
  • -ShowNewProject:Opens the New Project window upon launching the Wwise Authoring tool.