Wwise 버전
Wwise SDK 2021.1.4
명령어 추가 정의하기

명령어 추가 개요

명령어 추가는 Wwise Authoring의 새로운 명령어를 정의할 수 있도록 합니다. 각 명령어는 Wwise에 의해 트리거되는 외부 프로그램과 연결돼있습니다. 실행되는 프로그램은 현재 선택된 오브젝트에서 파생된 미리 정의된 여러 인자를 받을 수 있습니다.

추가 명령을 트리거하는 방법은 다양합니다.

추가 명령은 여러 레벨에서 정의할 수 있습니다.

  • In the user data directory, under:
    • Windows: "%APPDATA%\\Audiokinetic\\Wwise\\Add-ons\\Commands"
    • macOS: "$HOME/Library/Application Support/Audiokinetic/Wwise/Add-ons/Commands"
  • In the installation folder, under:
    • Windows: "%WWISEROOT%\\Authoring\\Data\\Add-ons\\Commands"
    • macOS: "/Library/Application Support/Audiokinetic/Wwise <version>/Authoring/Data/Add-ons/Commands"
  • 프로젝트 폴더 안의 "Add-ons\\Commands"
  • ak.wwise.ui.commands.register 사용
참고: ID끼리 충돌할 경우, 맨 처음으로 로딩된 명령어만 등록됩니다. 명령어는 위에서 지정한 순서로 로딩됩니다.
참고: 설치 폴더나 사용자 데이터 디렉터리에 지정된 명령어 추가는 Wwise가 시작될 때 로딩됩니다. 프로젝트 내 지정된 명령어 추가는 프로젝트가 로딩될 때 함께 로딩됩니다.

또한, Wwised에서 명령어가 실행될 때마다, WAAPI가 구독자에게 ak.wwise.ui.commands.executed 을(를) 통보하게 되는데, 선택된 오브젝트를 전달하며 WAAPI 반환 옵션을 줍니다. 추가 명령어는 어떠한 프로그램도 실행되지 않게 정의할 수 있어서 발행 이벤트를 사용하여 WAAPI 클라이언트에서 자신의 코드를 실행할 수 있습니다.

명령어 추가의 정의

정의 입력란

명령어는 다음과 같은 입력란으로 설명할 수 있습니다.

  • id: 해당 명령어에 대해 사람이 읽을 수 있는 고유 ID를 정의합니다. ID 충돌로 인한 위험을 줄이기 위해서는, 저작자 이름과 제품 이름, 명령 이름을 연속으로 이어붙여 사용하세요.
  • displayName: 사용자 인터페이스에 표시할 이름을 정의합니다.
  • program: 해당 명령이 실행될 때 작동시킬 프로그램이나 스크립트를 정의합니다. 전달인자는 'args'에 지정됩니다.
  • args: 전달인자를 정의합니다. 지원되는 내장 변수를 보시려면 Wwise 문서를 확인하세요. 여러 개를 선택하는 경우 startMode 에 따라 변수가 확장됩니다.
  • cwd: 프로그램을 실행시킬 현재 작업중인 디렉터리를 정의합니다.
  • defaultShortcut: 이 명령에 대해 기본으로 사용할 단축키를 정의합니다. 단축키가 충돌할 경우, 사용되지 않습니다. 이 단축키는 Keyboard Shortcut Manager에서 변경할 수 있습니다.
  • redirectOutputs: 프로그램의 표준 출력 스트림(stdout + stderr)이 종료시 Wwise로 돌아가 기록되는지 정의합니다. 이 기능은 수명이 짧은 프로그램에만 사용해야 한다는 점에 주의하세요. 해당 값은 boolean 타입이며 기본값은 false입니다.
  • startMode: Wwise 사용자 인터페이스에서 복수 선택을 할 경우 인자 입력란의 변수를 어떻게 확장할 지를 지정합니다. 다음은 가능한 값의 목록입니다.
    • SingleSelectionSingleProcess: 단일 선택만 지원하며 프로그램을 한 번 실행합니다.
    • MultipleSelectionSingleProcessSpaceSeparated: 큰따옴표로 감싸여 공백으로 구분되는 인자들로 확장된 변수와 함께 프로그램을 한 번 실행합니다.
    • MultipleSelectionMultipleProcesses: 프로그램이 선택된 요소별로 동시에 한 번씩 실행됩니다. 각 실행 인스턴스는 하나의 선택된 요소를 받습니다.
  • contextMenu: 명령어가 콘텍스트 메뉴의 어디에서 나타날 지 지정하며, 오브젝트 타입인 명령어를 사용할 수 있게 됩니다. 이 입력란에는 다음 요소 중 어느 것이든 적용할 수 있습니다.
    • basePath: 부모의 하위 메뉴에 대해 슬래시로 구분된 경로를 정의합니다. 비어있을 경우, 해당 메뉴가 맨 첫 단계에 삽입됩니다.
    • enabledFor: 해당 요소가 활성화된 오브젝트 타입 이름의 쉼표로 구분된 목록을 정의합니다. 지원되는 타입 이름의 목록은 Wwise Objects Reference 을(를) 참고하세요. 비어있을 경우, 어느 타입이든 가능합니다.
    • visibleFor: 해당 요소가 출력된 오브젝트 타입 이름의 쉼표로 구분된 목록을 정의합니다. 지원되는 타입 이름의 목록은 Wwise Objects Reference 을(를) 참고하세요. 비어있을 경우, 어느 타입이든 가능합니다.
  • mainMenu: 명령어가 Wwise 메뉴의 어디에서 나타날 지 지정합니다.
    • basePath: 부모의 하위 메뉴에 대해 슬래시로 구분된 경로를 정의합니다. 최소 한 단계를 정의해줘야 하며, 이는 최상위 메뉴와 연결돼있습니다.

공용 디렉터리

다음 미리 정의된 디렉터리는 특정 기기에 국한된 절대 경로를 피하기 위해 program 입력란에 사용돼야 합니다. 이 디렉터리는 또한 args 입력란에 사용해 경로를 인자로서 프로그램에 보내거나 cwd 입력란에 사용해 현재의 작업 디렉터리를 정의할 수 있습니다.

Variable 참조 위치
${CurrentCommandDirectory} 현재 명령어 디렉터리. As mentioned above, it should be "Add-ons\\Commands".
${WwiseInstallRoot} The Wwise installation directory.
${WwiseInstallBin} The Wwise.exe directory.
${WwiseInstallAddons} Windows: "${WwiseInstallRoot}\\Authoring\\Data\\Add-ons"
macOS: "/Library/Application Support/Audiokinetic/Wwise <version>/Authoring/Data/Add-ons/Commands"
${WwiseUserAddons} Windows: "%APPDATA%\\Audiokinetic\\Wwise\\Add-ons"
macOS: "$HOME/Library/Application Support/Audiokinetic/Wwise/Add-ons/Commands"
${WwiseProjectRoot} The Wwise project directory.
${WwiseProjectAddons} "${WwiseProjectRoot}\\Add-ons"
${WwiseProjectOriginals} "${WwiseProjectRoot}\\Originals"
${WwiseProjectSoundbanks} Platform-specific generated soundbanks directory.

전달인자 변수

다음 미리 정의된 변수는 args 입력란에 사용될 수 있습니다 (프로그램 인자). 복수의 선택을 사용할 경우, startMode 를 참고해 이 변수들이 어떻게 결정되는지 알아보세요.

Variable Type 설명
${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이나 Project (wproj file)가 변경됐을 경우 true, 즉 값이 수정됐으나 저장되지는 않았다는 뜻입니다.

명령어 추가 예제

명령어 정의 파일 사용 예제

새로운 명령어를 생성하기 위해서는 명령어 추가 정의하기 목록에 있는 디렉터리 중 하나에 JSON 파일을 생성하고 버전을 2로 지정합니다. 이 디렉터리에는 여러 서드 파티에서 파일을 생성할 수 있다는 점에 주의하세요. 파일 이름끼리 충돌하는 것을 방지하기 위해 '회사이름_프로젝트이름.json'의 파일명 규정을 따르기를 권장합니다.

예: mycompany_myproduct.json

{
"version":2,
"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 사용 예제

위에 나온 것과 똑같은 JSON 명령어 코드는 현재 Wwise 프로세스에 새로운 명령어를 추가하도록 WAAPI ak.wwise.ui.commands.register 로 전달될 수 있습니다.

ak.wwise.ui.commands.register로 추가된 명령어는 유지되지 않는다는 점에 유의하세요. Wwise 처리 과정이 종료될 때까지 남아있게 됩니다. 다음번에 이 명령어들을 다시 등록해야 합니다.

WAAPI와 함께 추가 명령 사용하기

추가 명령어는 WAAPI 스크립트나 프로그램을 실행하는 데 사용할 수 있습니다. 그러면 Wwise 기능과 프로젝트 데이터에 접근할 수 있습니다. WAAPI로 할 수 있는 작업에 대한 정보는 Wwise Authoring API (WAAPI, Wwise 저작 API) 사용하기 를 참고하세요.

Using Add-on Mac에서의 명령어

Mac에서 추가 명령어는 다음을 이용해 실행합니다.

/bin/sh -c

. 어떤 실행 파일이나 스크립트건 program 에 직접 지정될 수 있습니다. 앱을 열기 위해서는 open 명령어를 사용해야 합니다. 공백이 포함된 경로는 작은 따옴표로 감싸야 합니다.

예: mycompany_myproduct_forMac.json

{
"version":2,
"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"
}
}
]
}