目录

使用命令行

许多 Wwise 操作可通过 Wwise 的命令行界面完成,包括生成 SoundBank。这个功能在自动化过程中集成 Wwise 时会非常有用,例如在游戏的每日例行构建(daily build)中一并构建声音资源。

Wwise 命令行

以下是调用 Wwise 命令行可执行文件 WwiseCLI.exe 的两种不同方式,分别对应 Windows 和 Mac 运行环境。

Windows
对于 Windows,直接在 "%WWISEROOT%\Authoring\x64\Release\bin" 下调用 WwiseCLI.exe。命行令参数应遵循这一基本结构,其中 projectoperation 是必需的:
WwiseCLI.exe project.wproj -operation [-option1 [parameters]] [-option2 [parameters]] ...
Mac
对于 Mac,通过 WwiseCLI.sh Shell 脚本间接调用 WwiseCLI.exe。为了能够在 Mac 上成功运行 WwiseCLI.sh Shell 脚本,想要运行 WwiseCLI.sh Shell 脚本的每位用户必须:
  1. 启动 Wwise.app 并安装 MS VC++ redistributable。
  2. 退出 Wwise.app。
然后便可使用 Unix 或 Windows 式路径在 Terminal(终端)中调用 WwiseCLI.sh Shell 脚本命令行参数,这些参数与其对应的 Windows 命令行相同。
Unix 路径示例:
 MAC:~ username$ /Path/to/Authoring/Wwise.app/Contents/Tools/WwiseCLI.sh "/Volumes/Drive/Path/to/project.wproj" -operation [-option1 [parameters]] [-option2 [parameters]]
Windows 路径示例:
 MAC:~ username$  /Path/to/Authoring/Wwise.app/Contents/Tools/WwiseCLI.sh "Z:\Volumes\Drive\Path\to\project.wproj" -operation [-option1 [parameters]] [-option2 [parameters]]

包含空格的任何字符串参数应使用引号括起来,如此 示例 中所示。 所有路径参数只能使用反斜杠指定,路径结尾不带反斜杠。

操作

在命令行上必须指定以下操作中的一个且只能指定一个。

Operation Description Applicable Options
-ConvertExternalSources External Sources conversion. 如果 -GenerateSoundBanks 还触发了External Source,则可使用 -ConvertExternalSources 来处理 Wwise 工程中不包含的源。此操作有两个可选参数:平台和 WSOURCES 文件路径。如果提供一个平台,则将只生成该平台上的 SoundBank。如果提供 WSOURCE 文件,则将覆盖 Project settgings(工程设置)中针对给定平台的 External Source 输入文件路径(如果没有指定平台,则将面向所有平台)。此操作不可与 -Save 选项并用。示例:
  • -ConvertExternalSources使用工程设置中提供的源列表对所有平台做转码
  • -ConvertExternalSources Windows仅对 Windows 平台的源进行转码。
  • -ConvertExternalSources Windows -ConvertExternalSources XBoxOne 仅针对 Windows 和 Xbox One 进行转码。
  • -ConvertExternalSources MySources.wsources 对所有平台上指定的列表进行转码。
  • -ConvertExternalSources Windows MySources.wsources 对 Windows 上的所有文件进行转码,并使用指定的文件列表。
  • -ConvertExternalSources -ExternalSourcesOutput ..\..\YourNewExternalSourceFolder 所有平台均不沿用默认外部源输出文件夹。
  • -ConvertExternalSources Windows -ExternalSourcesOutput ..\..\YourNewExternalSourceFolderForWindows Windows 平台不沿用默认外部源输出文件夹。
-CreateNewProject Create a blank new project. 工程必须不存在。文件夹的名称必须与 WPROJ 文件相同。如果文件夹不存在,则创建一个。须使用 -Platform 至少定义一个用于工程的平台。您可以定义多个平台。
-LoadProject 加载工程。不会执行任何其他操作,在加载工程后会直接退出。可结合运用 -Save 来迁移和保存工程。
-GenerateSoundBanks 生成 SoundBank。SoundBank 生成操作遵循工程中存储的设置;在从命令行启动 SoundBank 生成操作时,将忽略自定义用户设置。然而在命令行中,其中一些设置可以被覆盖。
Note.gif
Note:-Platform、-Bank -Language 标志被忽略时,应用程序会为所有平台或语言生成 SoundBank。
-SoundFrameServer Start a command-line SoundFrame server, to which client applications using the Sound Frame library can connect. 可指定可选的数字形式的进程 ID 作为此选项的参数,以便此服务器只接受来自给定进程的连接。服务器将保持运行,直至收到 CTRL-C 信号。
-TabDelimitedImport Import a tab-delimited file to create and modify different objects hierarchy. 如果不指定选项 -Save,则不会持久保存导入用制表符分割的文件时对工程产生的更改。
-Waapi Start a command-line Wwise Authoring API server, to which client applications using the Wwise Authoring API can connect.
Note.gif
Note: 正如 Supported by 部分所示,有些 Wwise Authoring API Reference “WAAPI 函数”只有在运行 Wwise 设计工具的 GUI 界面时才起作用。

选项

各个选项仅可应用于特定 操作 。无效选项将被忽略。

  • -AbortOnLoadIssues 如果检测到工程加载问题,则放弃原始命令,例如 -GenerateSoundBanks 。所有被记录的工程加载问题都会打印到屏幕上。
  • -AudioSourceFromOriginal 一个工程可能已经包含一些音频源文件,它们的名字和导入的音频源文件一样。在这样的情况下,通过添加这个标志,操作将会使用那些工程中已存在的音频源文件,而不会用制表符分割的文件中描述的音频源文件来替换。
  • -Bank 指定将要生成的 SoundBank。此选项后面必须紧跟将要生成的 SoundBank 的名称。可以指定多个 SoundBank。如果不指定任何 SoundBank,则将生成所有的 SoundBank。还有一种方法是指定一个包含 SoundBank 名称列表的文本文件,方法是输入该文本文件的完整路径,包括扩展名“.txt”。
  • -Cache 不沿用工程的缓存文件夹路径,而使用此命令指定的相对路径。
  • -ClearAudioFileCache 在转码源文件和生成 SoundBank 前,删除 Wwise 音频文件缓存文件夹的内容,确保所有源文件都会重新转码。如果未指定标志 -GenerateSoundBanks ,则将忽略此选项。注意,不管是否使用 -Platform 参数,所有平台的整个缓存都会清空。
  • -ContinueOnError 如果在导入定义文件时发生错误,而您想在出错时继续执行,则使用此选项。
  • -CustomGlobalClosingCmd 不沿用 Wwise 中定义的全局结束步骤。此选项后面必须紧跟新的命令行(如果命令中有空格,则要用引号括起来)。如果把命令行指定为空字符串(""),则代表将不执行全局结束步骤。
  • -CustomGlobalOpeningCmd 不沿用 Wwise 中定义的全局开始步骤。此选项后面必须紧跟新的命令行(如果命令中有空格,则要用引号括起来)。如果把命令行指定为空字符串(""),则表示将不执行全局起始步骤。
  • -CustomPostGenCmd 不沿用 Wwise 中为此平台定义的自定义生成后步骤命令行。此选项后面必须紧跟平台标识符(见上文列表),后面再紧跟新的命令行(如果命令中有空格,则要用引号括起来)。若要不沿用另一平台的自定义 post-generation step 命令行,则可再写一遍选项 -CustomPostGenCmd,并在后面紧跟另一平台的标识符及其新命令行。如果把命令行指定为空字符串(""),则代表将不执行生成前步骤。
  • -CustomPreGenCmd 不沿用 Wwise 中为此平台定义的自定义 pre-generation step 命令行。此选项后面必须紧跟平台标识符(见上文列表),后面再紧跟新的命令行(如果命令中有空格,则要用引号括起来)。若不想沿用另一平台的自定义 pre-generation step 命令行,则可再写一遍选项 -CustomPreGenCmd,并在后面紧跟另一平台的标识符及其新命令行。如果把命令行指定为空字符串(""),则代表将不执行生成前步骤。
  • -ExternalSourcesOutput 不沿用 Project Settings 中为已转码的 External Source 文件设置的输出路径。此选项有两个参数:平台(可选)和路径(须为相对路径)。此选项只有结合 -ConvertExternalSources 使用时才有效。
  • -HeaderFile 指定此命令选项后,即使工程设置中没有指定此选项,也会生成头文件 Wwise_IDs.h。如果不指定选项-GenerateSoundBanks ,此选项将被忽略。
  • -HeaderFilePath 替代工程设置中指定的头文件路径。此选项后面必须紧跟将写入头文件(Wwise_IDs.h)的路径(绝对或相对路径)。只有需要创建头文件时,此选项才有用。
  • -ImportDefinitionFile 导入 SoundBank Definition File(SoundBank 定义文件)。此选项后面必须紧跟将要导入的 SoundBank Definition File 的完整路径。可指定多个文件。如果不指定选项 -Save,则不会持久保存导入定义文件后对工程的更改。
  • -ImportLanguage 可以用制表符分割导入操作来进行语音导入。此标志是用于指定导入语音的语言。此选项之后须附加 -Language 标志所列语言标识符之一。注意,此操作中仅添加音频文件;将忽略同时执行的所有其他操作(比如音量调整)。
    Warning.gif
    Warning:-ImportLanguage 标志被省略时,导入操作会将所有音频源文件视为音效而不是语音。
  • -Language 指定要生成 SoundBank 的语言。该选项后面必须加上工程中定义的语言标识符。各个指定语言必须使用此选项作为前缀。如果不指定选项-GenerateSoundBanks ,此选项将被忽略。
  • -NoDecode 避免在 .cache 文件夹中生成 DECODED(解码后)文件,这可以为 Wwise 工程节省 CPU 和磁盘空间。它还将缩短 SoundBank 的生成时间。
    Warning.gif
    Warning: 注意,如果您不生成 DECODED 文件,在 Wwise authoring 中播放这些声音可能导致播放过期内容或者根本无法播放。建议在使用此选项后清空文件缓存。
  • -NoWwiseDat 在转码音频文件时禁用隐藏的“wwise.dat”文件。从已经处理了文件依赖的构建工具中调用 WwiseCLI 时,结合 -ConvertExternalSources 使用这个选项会非常有用,这可以启动多个 Wiwse 程序来同时并行转码输出到同一目录,而无任何冲突。
  • -Platform 指定要生成 SoundBank 的平台。此选项后面必须紧跟平台标识符(见下面列表)。各个指定平台必须使用此选项作为前缀。
  • Android
    • iOS
    • Mac
    • PS4
    • Windows
    • XboxOne
  • -Quiet 禁用所有控制台文本输出中的非错误信息。
  • -Save 启用保存 Wwise 工程。结合 -ImportDefinitionFile 还是 -TabDelimitedImport 使用此选项时,由于导入 SoundBank 而产生的工程更改将保存在 Work Unit 中。启用保存功能还可使工程的迁移操作(Migration)能通过命令行进行。注意,在保存工程时,用户要负责确保工程文件不是“只读”,即在执行命令行请求前,用户要负责执行从版本控制软件中执行“check-out”操作。
  • -SoundBankPath 替代工程设置中为此平台指定的 SoundBank 路径。此选项后面必须紧跟平台标识符(见上文列表),再紧跟新路径(绝对或相对路径,如果路径中有空格,则要用引号括起来)。要不沿用另一平台的路径,则要再使用一次选项-SoundBankPath ,并在后面紧跟另一平台的标识符及其新路径。
  • -TabDelimitedOperation 决定如何执行导入时的对象创建。对每个创建的对象:
    • CreateNew 会创建一个新对象;若可能,该对象会被命名为想要的名称,否则将会使用一个新的不重名的名称。
  • UseExisting 如果对象存在则会使用该对象,更新指定的属性;否则会创建一个新的对象。
  • ReplaceExisting 会创建一个新对象;如果已有对象的名称与其一样,则消除原有对象。
    Note.gif
    Note:-TabDelimitedOperation 标志被省略时,导入操作会默认为 UseExisting
  • -Verbose 启用额外的控制台文本输出。
  • -WaapiAllowedAddr 指定允许连接到 WAAPI 的 IP(IPv4 或 IPv6)地址。该选项后面必须加上逗号分隔的清单,比如:127.0.0.1,::1。使用 * 允许连接任意主机。
    Caution.gif
    Caution: 使用 * 可能会带来安全问题。请参阅 网络安全 了解有关安全使用 WAAPI 的更多内容。
  • -WaapiAllowedOrigin 指定允许连接到 WAAPI 的主机。该选项后面必须加上逗号分隔的清单,比如:www.myhost.com,www.myhost2.com。在 HTTP 标头(header) Origin 上会执行验证。始终允许未提供 Origin 标头的连接以及基于文件的连接(如 file://)。使用 * 允许连接任意主机。
    Caution.gif
    Caution: 使用 * 可能会带来安全问题。请参阅 网络安全 了解有关安全使用 WAAPI 的更多内容。
  • -WaapiHttpPort 当使用HTTP POST时,确定Wwise Authoring API使用的端口号。这一选项后面必须跟随一个介于0到65,535之间的端口号。使用0的话会让服务器无法运行。
  • -WaapiWampPort 当使用WAMP时, 确定Wwise Authoring API使用的端口号。这一选项优先于User Preferences,后面必须跟随一个介于0到65,535之间的端口号使用0的话会让服务器无法运行。

示例

下面是使用命令行生成 SoundBank 的一个示例。它为 Windows 平台生成英语(美国)和法语(加拿大)语言的 SoundBank。此示例还定义了特定的自定义 post-generation 命令,此命令不沿用工程设置和用户设置中定义的 post-generation 步骤。

"%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 Source转码示例

以下是使用命令行转码 External Sources 的一个示例。此转码仅针对 Xbox One。

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

创建新的工程 – 示例

以下示例阐述了如何通过命令行为 Windows 和 Mac 平台创建新的 Wwise 工程。请注意,必须确保尚无 Wwise 工程文件夹。

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

迁移工程 – 示例

以下示例阐述了如何通过命令行来迁移 Wwise 工程。

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

制表符分割导入示例

这个例子展示了导入描述对象层级结构的用制表符分割的文件,这个层级结构包含美式英语语音。它会将会替换已存在的对象,但会使用最初的音频源文件。

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

错误代码

在使用命令行工作时,WwiseCLI.exe 将返回以下返回代码之一:

  • WWISE_ERROR_CODE_SUCCESS 0
  • WWISE_ERROR_CODE_ERROR 1(遇到 Fatal Error 即致命错误)或 Error 即错误时)
  • WWISE_ERROR_CODE_WARNING 2(遇到 Warning 即警告时)

虽然发生警告后还是可以正常生成 SoundBank,但是强烈建议您将这些警告当成错误对待。例如,当缺少源文件时,WwiseCLI.exe 会返回错误代码。虽然缺少的源文件不会妨碍生成 SoundBank,但由此产生的 SoundBank 可能不完整。

您可以在 Wwise 中通过访问 Project Settings > Logs 来更改在 SoundBank 生成期间遇到的大多数消息的严重性设置(Severity)。更改消息的严重性将会影响返回码。

错误跟踪

在使用命令行应用程序工作时,所有错误通过 stdout 进行报告。

使用命令行打开 Wwise 设计工具

除 Wwise 命令行界面 (WwiseCLI.exe) 外,用户也可在命令行中使用 Wwise.exe 调用 Wwise 设计工具。这样做有 3 个目的:

  • -AutomationMode:在 Wwise 中启用自动化模式。这样可以减少由消息框和对话框造成的潜在中断。比如,在启用自动化模式后,将自动允许迁移工程、保存工程加载日志、接受 EULA、工程许可协议和一般弹出消息框。
  • -SetTitleBarText 指定要附加到 Wwise 设计工具主窗口标题栏的文本行。此选项后面必须紧跟要附加的文本,如果文本中有空格,则必须使用引号括起来。
  • -ShowNewProject 在打开Wwise Authoring Tool的时候打开新工程窗口。