Table of Contents
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.
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
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:
- Launch Wwise.app and install the MS VC++ redistributable.
- 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: Windows path example:
MAC:~ username$ /Path/to/Authoring/Wwise.app/Contents/Tools/WwiseCLI.sh "/Volumes/Drive/Path/to/project.wproj" -operation [-option1 [parameters]] [-option2 [parameters]]
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.
One and only one of these operations must be specified on the command-line.
|-ConvertExternalSources||External Sources conversion. While External Sources is also triggered by
|-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.
|-LoadProject||Load a project. Will not run any other operation and will simply exit after loading the project. Can be used with
|-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.
|-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
|-Waapi||Start a command-line Wwise Authoring API server, to which client applications using the Wwise Authoring API can connect.
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
-GenerateSoundBanksis not specified. Note that the whole cache is cleared, for all platforms, regardless of the
- -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
-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
-GenerateSoundBanksis 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
-Saveis 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
-Languageflag. 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
-ImportLanguageflag 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
-GenerateSoundBanksis 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
-ConvertExternalSourceswhen 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.
- -Quiet: Disables all non-error console text output.
-Save: Enables saving of the Wwise project. When used with
-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
-SoundBankPathfollowed by the other platform's specifier and its new path.
-TabDelimitedOperation: Determines how import object creation is performed. For each object created:
CreateNewwill create a new object; the object will be given the desired name if possible, otherwise a new unique name will be used.
UseExistingwill use the object if it exists, updating the specified properties; otherwise it will create a new object.
ReplaceExistingwill create a new object; if an existing object has the same name then the existing object is destroyed.
Note: When the
-TabDelimitedOperationflag is omitted, the import operation will default to
- -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.
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"
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
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.
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
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
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.
When working from the command line app, all errors are reported using stdout.
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.