The open architecture of Wwise supports different kinds of plug-ins:

• Audio plug-ins, including:
  • Source plug-ins, which generate sounds
  • Effect plug-ins, which transforms sounds
  • Sink plug-ins, which output sounds to some medium
• Source Control plug-ins, which enable the use of source control software within Wwise

Audio Plug-ins describe their model in the form of an XML file. This allows you to quickly change any of the settings of your plug-in, including default property values, without having to recompile the code. Properties described in this model are also used to provide a default graphical interface in the form of a properties table in Wwise if no custom GUI is provided by the plug-in.

Overview of the XML File

XML 설명 파일에는 다음과 같은 Wwise 플러그인 관련 정보가 담겨있습니다.

• 플러그인 이름
• Company ID 및 plug-in ID. 더 자세한 정보는 Wwise Plug-in ID 를 참고하세요.
• 각 플랫폼에서 지원하는 기능
• 다음을 포함한 속성 설명:
  • 속성 이름 (코드와 유지된 파일의 속성을 식별하는 데 사용되는 문자열)
  • 속성 타입
  • RTPC 지원
  • 기본 값
  • 사운드 엔진 속성 ID (사운드 엔진 플러그인에서 이 속성을 코드에 바인딩)
  • 범위 제한 또는 열거 제한
  • 다른 속성에 대한 종속성
  • 사용자 인터페이스 설명 요소
• 다음을 포함한 Inner Object Types 설명:
  • Inner Object Type 이름 (내부 오브젝트 타입을 식별하는 데 사용되는 문자열)
  • Inner Object Properties

When using the wp.py development tool, a default XML file is provided and is pre-filled with the information you provided at creation time. Refer to 오디오 플러그인 만들기 for more details.

참고: A Wwise plug-in dynamic library can contain multiple plug-ins (see 플러그인 라이브러리 형식 저작하기), each of which must be described in a single associated XML file.

Naming of the XML File

The XML description file for each Wwise plug-in dynamic library must have the same name as the dynamic library, except for the XML file extension and any lib prefix.

For example, if your dynamic library is named "MyPlugin.dll" or "libMyPlugin.dylib", then the plug-in description file must be named "MyPlugin.xml".

예시: XML 설명 파일

다음은 플러그인 XML 설명 파일의 간단한 예시입니다.

XML Description File Specific Parts

XML 파일의 다양한 부분을 자세히 살펴보겠습니다.

XML Description File Header

이 XML 파일의 헤더 부분을 살펴보고 자세한 내용을 알아봅시다.

어떤 XML 파일이든 첫 번째 라인에서는 XML 버전과 인코딩을 정의합니다. 여기서는, XML 버전은 1.0이고 인코딩은 UTF-8 입니다. 모든 Wwise 플러그인 설명 파일의 첫 번째 라인은 항상 위의 것과 같은 양식이어야 합니다. 두 번째 라인은 XML 주석으로, 여기서는 저작권 공고입니다. 필요에 따라 XML 파일 안 다양한 곳에 주석을 입력할 수 있습니다.

PluginModule Element

이 문서의 주요 XML 요소는 PluginModule 라고 이름 붙였으며, 파일 안에 정의된 다양한 플러그인의 모든 정보를 담고 있습니다.

Plug-in Type Elements

In the category of Audio plug-ins, there are four possible plug-in type elements:

• SourcePlugin
• EffectPlugin
• SinkPlugin
• MetadataPlugin

The EffectPlugin element is the main element for the definition of a single effect plug-in, while SourcePlugin, SinkPlugin and MetadataPlugin are the element names for source plug-ins, sink plug-ins and metadata plug-ins, respectively.

참고: If more than one plug-in is implemented in the dynamic library, the XML file will contain multiple plug-in elements. A dynamic library is not limited to a single type of audio plug-in.

These elements contain three required attributes:

• Name (mandatory): This string specifies the display name of the plug-in as it will appear in Wwise.
• CompanyID (mandatory): This string must represent a positive integer in the range 0-4095 (see wwiseplugin_xml_id_specification)
• PluginID (mandatory): This string must be a positive integer in the range 0-32767. 각 PluginID는 지정된 CompanyID에 대해 고유해야 합니다.

Two optional attributes can be specified:

• SupportsIsSendModeEffect (optional): (Effect plug-in only) This boolean value indicates if the plug-in supports the send mode by querying AK::IAkEffectPluginContext::IsSendModeEffect() during the initialization part. When IsSendModeEffect() returns true, the plug-in should not output the dry signal and should ignore the dry level properties.
• EngineDllName (optional): This string value overrides the name of the Sound Engine dynamic library to load at game runtime (by default it will be the same name as the XML). If EngineDllName is specified, ensure that both of your Sound Engine static and dynamic libraries share the same name. Unity나 Unreal 4와 같은 상업용 게임 엔진에서 지원될 수 있도록 하려면 반드시 자신의 플러그인과 함께 DLL/so 파일을 제공해야합니다. This does not affect the naming of the Authoring plug-in dynamic library, which should strictly correspond to the name of your XML file.

Company and Plug-in IDs

Wwise associates plug-in model definitions and plug-in implementations using numeral IDs. These IDs are provided in the XML description of each plug-in and in the plug-in descriptor in the plug-in library.

The CompanyID is an ID corresponding to your organization. Three ranges exist:

• 0-63: Reserved for Audiokinetic, not available.
• 64-255: Unrestricted range for in-house use. A Company ID in this range cannot be used for external distribution.
• 256-4095: Restricted range for commercial plug-ins. 이 숫자는 Audiokinetic이 공식 서드 파티 개발자에게 부여합니다. 만약 공식 서드 파티로 지정되었다면, 64-255 범위를 사용하지 말고 이 범위 내 숫자를 사용하세요. 반대로 그렇지 않은 경우, 이 범위를 사용하지 마시기 바랍니다.

The PluginID is a unique numeral ID in the range 0-32767 that corresponds to a plug-in within a single organization.

For example, if you are developing plug-ins for in-house use only, you can pick any CompanyID between 64 and 255, and any three PluginIDs between 0 and 32767. 이 숫자들은 연속된 숫자가 아니어도 상관 없습니다.

The CompanyID and PluginID need to be passed to the Sound Engine plug-in declaration macro AK_IMPLEMENT_PLUGIN_FACTORY.

경고: Important considerations: You should never change the CompanyID or PluginID of an existing plug-in. 이 플러그인을 사용하는 프로젝트가 더 이상 해당 플러그인을 인식하지 못하게 됩니다. The CompanyID and PluginID are persisted with each plug-in instance, and are used to recreate an instance of the right plug-in when the file is loaded. If two or more PluginIDs are identical for the same CompanyID, Wwise will display an error message on startup. 이 경우, 새로운 플러그인의 ID를 변경하세요. If you base your plug-in on a sample plug-in provided by Audiokinetic (예제 플러그인), don't forget to change the CompanyID and PluginIDs to appropriate values. 공식 CompanyID를 부여 받은 경우 그것을 사용하고, 그렇지 않은 경우 64에서 255 사이 숫자를 사용하면 됩니다. PluginID에 사용됐던 숫자가 CompanyID에 중복되지 않도록 주의하세요.

For more details on IDs, refer to Wwise Plug-in ID.

PluginInfo Element

PluginInfo/PlatformSupport 섹션에서 자신의 플러그인이 지원하는 플랫폼을 정의합니다. 여기에는 하나 이상의 Platform 구성 요소가 들어있으며, 이 각각의 구성 요소는 각 플랫폼에서 플러그인이 지원하는 다양한 기능을 명시하고 있습니다. 다음과 같은 기능이 명시됩니다.

• CanBeInsertOnBusses 는 효과가 버스 제어에 적용될 수 있는지를 결정합니다. 대부분의 경우 효과가 서라운드 오디오 환경 설정을 지원해야 합니다.
• CanBeInsertOnAuxBusses determines whether the effect can be applied to control and master auxiliary busses. 대부분의 경우 효과가 서라운드 오디오 환경 설정을 지원해야 합니다. Note that if CanBeInsertOnBusses is already set, the effect is already available on Aux busses.
• CanBeInsertOnAudioObjects 는 효과가 SFX에 삽입으로 적용될 수 있는지를 결정합니다 (모노와 스테레오 처리 둘 다 지원해야 함).
• CanBeRendered 는 효과가 오프라인 렌더링에 사용될 수 있는지를 결정합니다.
• CanSendMonitorData determines whether the effect can send monitoring data. Refer to AK::Wwise::Plugin::Notifications::Monitor::NotifyMonitorData for more information.
• CanBeSourceOnSound determines whether source plug-in can be a source for a sound.
• CanBeInsertEndOfPipeline 은 효과가 오디오 파이프라인의 마지막, 즉 상위 레벨 Audio Bus의 마지막 효과가 있는 자리에만 추가될 수 있는지를 결정합니다 (Audiokinetic 전용).

자신의 플러그인은 Wwise 안에서 지정된 플랫폼에 대해서만 사용 가능합니다.

모든 지원 플랫폼을 나열하는 대신 "Any (모든)" 플랫폼을 추가할 수도 있습니다. 단, 이 플러그인은 Wwise 안에서 모든 플랫폼에서 사용 가능한 것으로 소개된다는 점을 기억하세요. 또한, 일치하는 런타임 라이브러리가 플러그인에 없는 경우 사용자는 해당 플랫폼으로 가져올 때에야 이 사실을 알게 되다는 점에 유의하세요.

Metadata PluginInfo Element

For a metadata plug-in, it is important to set the MenuPath="Metadata" attribute to the PluginInfo node as such:

Properties Element

Each audio plug-in can define properties and references. 속성과 레퍼런스에 대한 더 자세한 정보는 Properties XML Description 을(를) 참고하세요.

Inner Objects

InnerTypes 섹션은 자신의 플러그인 안에서 인스턴스화하고 사용할 수 있는 Inner Object Types를 정의합니다. InnerTypes 섹션 안에 여러 개의 InnerType 을 정의할 수 있습니다. 각 InnerType 은 고유의 이름과 플러그인 ID를 갖고있어야 합니다. InnerType 섹션에는 Properties 섹션이 포함돼있으며, 여기에서 플러그인 속성을 정의하는 방식과 동일하게 속성을 정의할 수 있습니다.

Inner Types 는 플러그인에 여러 오브젝트 인스턴스가 필요할 때 매우 유용합니다. 예를 들어, 가변수의 EQ 밴드가 있을 경우, EQ 플러그인의 Inner Type Band 를 정의할 수 있습니다. 각 밴드에는, 각 밴드의 서로 다른 값과 함께 동일한 속성 정의가 있습니다.

참고: Inner Types의 속성은 RTPC를 지원하지 않습니다. 따라서 SupportRTPCType 속성과 AudioEnginePropertyID 구성 요소를 사용할 수 없습니다.

참고: InnerTypes are only supported inside audio plug-ins.

To manipulate the Inner Type instances (Inner Objects) in your plug-in code, you need to request the service by deriving AK::Wwise::Plugin::RequestObjectStore in your plug-in class and using the AK::Wwise::Plugin::ObjectStore m_objectStore member. The AK::Wwise::Plugin::ObjectStore interface provides functions for creating and deleting inner objects (AK::Wwise::Plugin::ObjectStore::CreatePropertySet and AK::Wwise::Plugin::ObjectStore::DeletePropertySet). Inner Objects' properties are manipulated using the PropertySet interface (see Property Set).

When objects are created, they must be stored in a named list using the insertion (AK::Wwise::Plugin::ObjectStore::InsertPropertySet) and removal (AK::Wwise::Plugin::ObjectStore::RemovePropertySet) functions. 예를 들어, 다음과 같이 Band 타입의 Inner Object를 생성하고, 이를 BandList 에 저장할 수 있습니다.

참고: An inner object can only be stored in a single list at any one time.

The persistence in the project Work Units is automatically handled by Wwise. However, you must implement the serialization of the inner objects in the SoundBanks and for the Sound Engine data. You must serialize the inner objects inside AK::Wwise::Plugin::CustomData::GetPluginData and AK::Wwise::Plugin::AudioPlugin::GetBankParameters.

오브젝트 저장소에 Inner Object를 추가할 때, 연관 Undo 체계가 Wwise에 자동으로 생성됩니다. 실행 취소 시스템을 별도로 구현할 필요가 없습니다. However, to support undo events correctly, you need to update your user interface only at the reception of notifications from the framework.

Inner Objects Notifications

The interface AK::Wwise::Plugin::NotificationsObjectStore provides handlers to override that allow to act on notification events related to inner objects. These are primarily meant to update custom GUI elements on model changes that could be triggered by a user interaction, an undo event or even a WAAPI call.

For example, after calling AK::Wwise::Plugin::ObjectStore::InsertPropertySet, do not update the UI right-away. Wait for the notification AK::Wwise::Plugin::NotificationsObjectStore::NotifyInnerObjectAddedRemoved to be called on your plug-in. 이 알림은, 오브젝트가 목록에 추가 또는 삭제되었다고 알려줍니다.

Similarly, you can react on AK::Wwise::Plugin::NotificationsObjectStore::NotifyInnerObjectPropertyChanged, which is called when the value of a property changes in an inner object.

문제 해결

문제가 발생할 경우 Wwise 음원 플러그인 및 효과 플러그인 문제 해결 안내 을 참고하세요.