Wwise SDK 2018.1.11

命令扩展概述

命令扩展方便为 Wwise 设计工具定义新的命令。每个命令都与 Wwise 触发的外部程序关联。所执行的程序可接收来自当前所选对象的各种预定义参数。

可通过不同方式触发扩展命令：

键盘快捷方式
上下文菜单
主菜单
控制器
WAAPI（使用 ak.wwise.ui.commands.execute ）

可在多个级别定义扩展命令：

用户数据目录中：APPDATA%\Audiokinetic\Wwise\Add-ons\Commands 下
安装文件夹中：Authoring\Data\Add-ons\Commands 下
工程文件夹中：Add-ons\Commands 下
使用 ak.wwise.ui.commands.register

info

Note: 在存在 id 冲突时，只注册所加载的第一个命令。系统会按照上述顺序加载命令。

info

Note: 在启动 Wwise 时，加载安装文件夹或用户数据目录中指定的命令扩展。在加载工程时，加载工程文件夹中指定的命令扩展。

另外，每次在 Wwise 中执行命令时，WAAPI 都会使用 ak.wwise.ui.commands.executed 通知订阅服务器传递所选对象并遵守 WAAPI 返回选项。在定义扩展命令时，可设为不执行任何程序。因此，您可以使用发布事件在 WAAPI 客户端中执行自编代码。

命令扩展的定义

定义字段

使用以下字段描述命令：

id： 为命令定义用户可读的唯一 ID。为了降低 ID 冲突风险，请结合使用作者姓名、产品名称和命令名称。
displayName： 定义用户界面中显示的名称。
program： 定义执行命令时要运行的程序或脚本。在 args 中定义参数。
args： 定义参数。如需了解支持的内置变量，请参阅相关文档。注意，在执行多选时，将根据 startMode 字段扩展变量。
cwd： 定义用于执行程序的当前工作目录。
defaultShortcut： 定义此命令默认使用的快捷方式。若快捷方式存在冲突，则不使用。可在 Keyboard Shortcut Manager 中更改此快捷方式。
startMode： 指定在 Wwise 用户界面中执行多选时如何扩展参数字段中的变量。
- SingleSelectionSingleProcess： 仅支持单选，启动程序一次。
- MultipleSelectionSingleProcessSpaceSeparated： 启动程序一次，并将变量扩展为空格分隔的参数（每个变量都加上双引号）。
- MultipleSelectionMultipleProcesses： 每选中一项启动程序一次（并行执行）。每次运行实例接收一个选定项。
contextMenu
- basePath： 为父级子菜单定义正斜杠分隔的路径。若为空，则在第一个级别插入菜单。
- enabledFor： 为已启用项定义逗号分隔的对象类型名列表。如需了解支持的类型名称列表，请参阅 Wwise Objects Reference 。若为空，则允许任意类型。
- visibleFor： 为可见项对应的对象类型名称定义逗号分隔的列表。如需了解支持的类型名称列表，请参阅 Wwise Objects Reference 。若为空，则允许任意类型。
mainMenu
- basePath： 为父级子菜单定义正斜杠分隔的路径。该字段至少要定义一层路径，并与顶层菜单关联。

参数变量

args 字段（程序参数）可使用以下预定义变量。在执行多选时，请参阅 startMode 以便了解这些变量如何解析。

变量	类型	说明
${id}	string	对象 ID (GUID)。
${name}	string	对象名称。
${notes}	string	对象备注。
${type}	string	对象类型。有关可用类型的详细信息，请参阅 Wwise Objects Reference 。
${path}	string	工程根目录下的对象路径。例如：'\\Actor-Mixer Hierarchy\\Default Work Unit\\Sound1'
${isPlayable}	boolean	若对象可在 Transport 中播放，则返回 True。
${shortId}	integer	对象短 ID。
${classId}	integer	对象类 ID。
${category}	string	对象类别。例如：Actor-Mixer Hierarchy
${filePath}	string	对象所在文件的路径。该路径可为 Work Unit 文件或工程文件。
${childrenCount}	number	对象的子对象数量。
${sound:originalWavFilePath}	string	原始 WAV 文件的绝对路径。仅适用于 Sound 和 Audio Source 对象。
${sound:convertedWemFilePath}	string	转码后 WEM 文件的绝对路径。指定选项中的平台。仅适用于 Sound 和 Audio Source 对象。
${soundbank:bnkFilePath}	string	所生成的 SoundBank 文件的绝对路径，该文件与 SoundBank 对象关联。仅适用于 SoundBank 对象。
${workunit:isDefault}	boolean	若 Work Unit 为默认工作单元，则返回 True。
${workunit:type}	string	Work Unit 的类型。请注意，物理文件夹与 Work Unit 一样，类型都是 WorkUnit。物理文件夹的 workunit:type 为 folder。可能的值：folder、rootFile、nestedFile
${workunit:isDirty}	boolean	若 Work Unit 或工程（wproj 文件）未清理（即修改了而没保存），则返回 True。

命令扩展示例

示例 – 使用命令定义文件

若要创建新的命令，请在“ 定义命令扩展 ”中列出的其中一个目录下创建 JSON 文件。请注意，很多第三方都可能会在这些目录下创建文件。为了降低文件名冲突风险，建议使用以下命名规范：companyname_productname.json

示例： mycompany_myproduct.json

{
    "commands":[
        {
            "id":"ak.edit_in_vscode",
            "displayName":"Edit in Visual Studio Code",
            "defaultShortcut":"C",
            "program":"code",
            "startMode":"MultipleSelectionSingleProcessSpaceSeparated",
            "args":"${filePath}",
            "cwd":"",
            "contextMenu":{
                    "basePath":"Editors",
                    "enabledFor":"Sound,ActorMixer,SwitchContainer,RandomSequenceContainer"
                },          
            "mainMenu":{
                    "basePath":"Extra"
                }
        },
        {
            "id":"ak.open_in_wavosaur",
            "displayName":"Edit in My Wav Editor",
            "defaultShortcut":"W",
            "program":"c:\\MyWavEditor\\WavEditor.exe",
            "args":"${sound:originalWavFilePath}",
            "cwd":"",
            "contextMenu":{}
        }          
    ]
}

示例 – 使用 WAAPI

在向当前 Wwise 进程添加新命令时，可将上述相同的 JSON 命令代码传给 WAAPI ak.wwise.ui.commands.register 。

请注意，系统不会保留通过 ak.wwise.ui.commands.register 添加的命令。一旦 Wwise 进程终止，这些命令马上就会被删除。所以，下次需要重新注册。

结合 WAAPI 使用扩展命令

扩展命令可用于执行 WAAPI 脚本或程序。这样方便用户访问 Wwise 功能和工程数据。有关如何使用 WAAPI 的信息，请参阅“ 使用 Wwise Authoring API（WAAPI） ”。

在 Mac 上使用扩展命令

在 Mac 上，使用以下格式执行扩展命令：

/bin/sh -c

. 可直接在 program 中指定可执行程序或脚本。若要打开应用程序，则必须使用 open 命令。若路径包含空格，则必须在其前后加上单引号。

示例： mycompany_myproduct_forMac.json

{
    "commands":[
        {
            "id":"ak.edit_in_audacity",
            "displayName":"Open wav in Audacity",
            "defaultShortcut":"A",
            "program":"open -n -a /Applications/Audacity.app",
            "startMode":"SingleSelectionSingleProcess",
            "args":"${sound:originalWavFilePath}",
            "cwd":"",
            "contextMenu": {
                "basePath":"Editors",
                "enabledFor":"Sound"
            }
        },
        {
            "id":"ak.edit_in_script",
            "displayName":"Open in script",
            "defaultShortcut":"A",
            "program":"'/path/to/folder with spaces/myScript.sh'",
            "startMode":"SingleSelectionSingleProcess",
            "args":"${sound:originalWavFilePath}",
            "cwd":"",
            "contextMenu": {
                "basePath":"Editors",
                "enabledFor":"Sound"
            }
        }
    ]
}

此页面对您是否有帮助？

需要技术支持？

仍有疑问？或者问题？需要更多信息？欢迎联系我们，我们可以提供帮助！

查看我们的“技术支持”页面

介绍一下自己的项目。我们会竭力为您提供帮助。

来注册自己的项目，我们帮您快速入门，不带任何附加条件！

开始 Wwise 之旅