Version
menu_open

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\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, 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 overridden from the command line.
Note.gif
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 XBoxOne :Converts only Windows & XBox One
    • -ConvertExternalSources MySources.wsources :Convert list specified, on all platforms
    • -ConvertExternalSources Windows MySources.wsources :Converts all files on Windows and uses the file list specified
  • -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.
  • -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.
  • -Waapi: Start a command-line Wwise Authoring API server, to which client applications using the Wwise Authoring API can connect.
    Note.gif
    		Note: As indicated in the Supported by sections, some WAAPI functions only work when running Wwise Authoring as a GUI.
  • -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.

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 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.
  • -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
    • VitaSW
    • VitaHW
    • Windows
    • 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.
  • -AbortOnLoadIssues: Aborts the original command, such as -GenerateSoundBanks, if a project load issue is detected. All logged project load issues are printed to screen.
  • -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 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'.
  • -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.
  • -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.
  • -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.
  • -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.gif
      		Note: When the -TabDelimitedOperation flag is omitted, the import operation will default to UseExisting.
  • -ImportLanguage: With the tab-delimited import operation it is possible to do voice import. This flag is used to specify the language of the imported voices. This option must be followed by one of the language identifiers listed at the -Language flag.
    Warning.gif
    		Warning: When the -ImportLanguage flag is omitted, the import operation will treat all the audio source files as SFX and not voices.
  • -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 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.
  • -ContinueOnError: Use this flag if you want to continue on error if an error occurred 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: Enables extra console text output.
  • -Quiet: Disables all non-error console text output.
  • -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.gif
    		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.
  • -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.
  • -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.
  • -WaapiAllowedOrigin: Specifies the hosts that are allowed to connect to WAAPI. This option must be followed by a comma-separated list, for example: #unknown,#file,www.myhost.com. Validation is performed on the HTTP header Origin. Use #unknown to allow connections which do not provide the Origin header, #file to allow file-based connections (for example: file://), and * to allow any host to connect.
    Caution.gif
    		Caution: Using * could present a security risk. See Network Security to learn more about using WAAPI safely.

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 Xbox One. 

"%WWISEROOT%\Authoring\Win32\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 platform. 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

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\Win32\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, which has a single option:

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

Was this page helpful?

Need Support?

Questions? Problems? Need more info? Contact us, and we can help!

Visit our Support page

Tell us about your project. We're here to help.

Register your project and we'll help you get started with no strings attached!

Get started with Wwise