Generating Banks from the Command Line

Introduction

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.

Command Line

There are two distinct ways to call WwCLI.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\Win32\Release\bin" (for the 32-bit version) or "%WWISEROOT%\Authoring\x64\Release\bin" (for the 64-bit version). 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:

1. First, if not already installed, install the Authoring application by unzipping Wwise.app in the Applications folder.
2. Then, individually, 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:

• -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 overriden 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.

• -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). 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 XBox360 :Converts only Windows & XBox
  • -ConvertExternalSources MySources.wsources :Convert list specified, on all platforms
  • -ConvertExternalSources Windows MySources.wsources :Converts all files on Windows and uses the file list specified

• -SoundFrameServer: Start a command-line Sound Frame 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.

  Note: The methods of AK::SoundEngine::ISoundFrame related to Sound Engine Operations are only functional when running Wwise Authoring as a GUI.

Options

• -Cache: Overrides the project's cache folder path and instead uses the path 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 re-converted. 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.

• -Language: Specifies for which languages the SoundBanks will be generated. This option must be followed by one of the language identifiers listed below. Each specified language must be prefixed with this flag. This option will be ignored if the flag "-GenerateSoundBanks" is not specified.
  • Arabic
  • Bulgarian
  • Chinese(HK)
  • Chinese(PRC)
  • Chinese(Taiwan)
  • Czech
  • Danish
  • Dutch
  • English(Australia)
  • English(India)
  • English(UK)
  • English(US)
  • Finnish
  • French(Canada)
  • French(France)
  • German
  • Greek
  • Hebrew
  • Hungarian
  • Indonesian
  • Italian
  • Japanese
  • Korean
  • Latin
  • Norwegian
  • Polish
  • Portuguese(Brazil)
  • Portuguese(Portugal)
  • Romanian
  • Russian
  • Slovenian
  • Spanish(Mexico)
  • Spanish(Spain)
  • Spanish(US)
  • Swedish
  • Turkish
  • Ukrainian
  • Vietnamese

• -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.
  • 3DS
  • Android
  • iOS
  • Mac
  • PS3
  • PS4
  • VitaSW
  • VitaHW
  • Wii
  • WiiUSW
  • Windows
  • WindowsPhone
  • Xbox360
  • XboxOne

• -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.

• -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.

• -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.

• -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.

• -Bank: Specifies which SoundBanks will be generated. This option must be followed by the name of the bank to be generated. Multiple banks can be specified. If no bank is specified, all banks 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'.

• -HeaderFile: Generates the header file Wwise_IDs.h, even if this option is not specified in the projet 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.

• -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.

• -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.

• -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.

• -Save: Enables saving of the Wwise project. When used with "-ImportDefinitionFile", 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.

• -ContinueOnError: Use this flag if you want to continue on error if an error occured while importing definition files.

• -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. This option is valid only with -ConvertExternalSources.

• -Verbose: Enable extra console text output.

• -Quiet: Disable all non-error console text output.

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\Win32\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\AkFilePackager.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 XBox360.

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

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.