External Sources are a type of source that developers can associate with Wwise sound objects to provide sound data at runtime. You can use External Sources to load media dynamically, especially if there are many different media files associated with an Event, such as multiple lines of dialogue.

You can use the External Source Manager to implement your own system that determines which media to load, as well as when and how to load it. The External Source Manager provides a highly extensible base class that contains a basic implementation to track states of External Sources and their media, but you must extend it to define the actual loading behavior.

In the Wwise Unreal Integration, the External Source system consists of three parts:

• The External Source Manager, which contains interfaces necessary for calling operations.
• The External Source Manager Implementation, which provides low-level media management operations that respond to PostEvent calls. These operations identify which media to load, and indicate when to unload and load media.
• The Simple External Source Manager, a sample extension that supports basic External Source management and acts as a reference for developers. It provides the data that the implementation layer uses. For more information, see Wwise Simple External Source Manager 사용하기.

Setting up External Sources in Wwise Authoring

To use External Sources, you must first set the generation path in Wwise Authoring, in the External Sources tab in the Project Settings dialog. See Specifying the Input/Output Locations for External Sources for more information.

External Source 이해하기

External Source는 빈 컨테이너라고 할 수 있습니다. The game has to fill it in and inform the sound engine about its contents.

An External Source uses a Cookie as an identifier, similar to a ShortId. Cookie를 얻으려면 음원의 Contents Editor에서 External Source 플러그인에 지정된 이름을 해시(hash)하세요. See Contents Editor: Wwise External Source for more information.

When an Event that uses External Sources is posted to the sound engine, an array of AkExternalSourceInfo structures that identify the media to use for each Cookie must be passed with it. This media can be in memory or streamed, and the game must ensure that these resources are ready when the Event is posted.

For more information about External Sources, see the following topics:

• Wwise External Source 개요
• Contents Editor: Wwise External Source
• AkExternalSourceInfo 구조체 참조
• Integrating External Sources

Wwise External Source Manager 이해하기

External Source에는 주목할 만한 몇 가지 특징이 있습니다.

• 여러 Event가 동일한 External Source를 사용할 수 있습니다.
• Multiple External Sources can use the same media.
• External Source가 사용하는 미디어는 SoundBank에서 정의되지 않으며 게임 로직에 의해 언제든지 변경될 수 있습니다.

To manage the relationship between Events, External Sources, and media, the External Source Manager:

• tracks the state of External Sources used by loaded Events.
• provides AkExternalSourceInfo structures for calls to PostEvent.
• tracks the state of loaded media used by External Sources.
• tracks the mapping between loaded External Sources and media.
• triggers the loading and unloading of media used by External Sources.
• packages the media files used by External Sources in the game.

Wwise External Source Manager 구현하기

The default implementation of the Wwise External Source Manager attempts to answer PostEvent calls (PrepareExternalSourceInfos, BindPlayingIdToExternalSources, and OnEndOfEvent) as quickly as possible. It requests PrepareExternalSourceInfos in order to "use" the specified media until OnEndOfEvent indicates that the playing media is no longer needed. The Simple External Source Manager provides the cookies that identify the media to load. You can override the default implementation if desired.

To implement a custom Wwise External Source Manager, you must first create an Unreal module. 모듈에는 최소한 두 개의 클래스가 포함되어야 합니다.

• 이전 섹션에서 나열된 책임들을 처리하는 FWwiseExternalSourceManager를 상속하는 클래스.
  • FWwiseExternalSourceManager에는 External Source를 정의하는 데 필요한 순수 가상 인터페이스(pure virtual interface)가 있습니다. 특별한 경우, 프로젝트는 이를 상속 지점으로 정의하고 External Source 파이프라인을 완전히 제어할 수 있습니다.
  • FWwiseExternalSourceManagerImpl에는 런타임이 External Source에서 사용하는 미디어를 로드/언로드하는 데 필요한 모든 함수가 있습니다. 이 클래스에는 External Source 쿠키에서 미디어 ID로의 매핑이 담겨 있으며, I/O 작업을 처리하고 미디어 수명을 추적합니다. 이 클래스를 상속하면 사용자 지정 추적 작업과 패키징 구현이 간소화됩니다. FWwiseExternalSourceManagerImpl 클래스는 복잡한 I/O 세부 정보를 자체적으로 처리합니다.
  • FWwiseSimpleExtSrcModule은 확장 가능하기 때문에 상위 클래스로 사용할 수도 있습니다.
• 첫 번째 클래스의 인스턴스를 반환하기 위해 InstantiateExternalSourceManager를 오버라이드하는 FWwiseFileHandlerModule을 구현하는 클래스입니다.

그리고 DefaultEngine.ini 파일의 [Audio] 섹션에 있는 새로운 모듈의 이름으로 WwiseFileHandlerModuleName을 설정하면 해당 모듈을 활성화할 수 있습니다. 자세한 내용은 Simple External Source Manager 활성화하기 를 참고해 주세요.

Wwise External Source Manager는 WwiseFileHandler 모듈의 인터페이스입니다. When Wwise Event assets that use External Sources are loaded, the WwiseResourceLoader module passes the External Source information in the Event's CookedData (see Wwise Unreal 애셋) to the WwiseFileHandler, which then delegates resource loading to the Wwise External Source Manager Implementation. Subsequent behavior depends on the implementation.

Tracking External Source states

기본 구현에서 External Source Manager는 External Source를 추적하는 FWwiseExternalSourceState 구조체를 생성합니다. 구현의 특이성 및 사용 가능한 정보에 따라 미디어가 로드되거나 스트리밍을 위해 준비됩니다. 마찬가지로 Event 애셋이 언로드되면 External Source Manager가 이 내용을 전달받고 이에 따라 External Source의 상태를 업데이트합니다. External Source Manager의 첫 번째 책임(External Source 상태 추적하기)을 수행하는 이 작동 방식은 다음 함수에서 구현됩니다.

• PrepareExternalSourceInfos: 요청된 External Source에 따라 재생할 미디어 목록을 선택/가져오고 External Source 재생에 필요한 AkExternalSourceInfo를 준비하는 공용 메소드입니다.
• LoadExternalSource: 관리자의 실행 대기열에서 LoadExternalSourceImpl로의 호출을 준비하는 공용 메소드입니다.
• UnloadExternalSource: 관리자의 실행 대기열에서 UnloadExternalSourceImpl로의 호출을 준비하는 공용 메소드입니다.
• LoadExternalSourceImpl: (가상) 추적된 External Source State의 생성 또는 업데이트를 처리합니다. 그런 다음 LoadExternalSourceMedia를 호출합니다.
• UnloadExternalSourceImpl: (가상) 추적된 External Source State의 제거 또는 업데이트를 처리합니다. If the External Source State must be removed, UnloadExternalSourceMedia is called.

The default implementation answers PostEvent calls (Prepare, Bind) as quickly as possible.

Providing information to PostEvent calls

두 번째 책임(AkExternalSourceInfo 구조체 채우기)은 PostEvent External Source 매개 변수를 반환하는 PrepareExternalSourceInfos에 의해 처리됩니다. CookieToMedia에서 데이터를 검색하고 해당 정보를 사용하여 다양한 파일 상태를 정의하고 이벤트 게시에 필요한 AkExternalSourceInfo 구조체를 제공합니다. 이를 오버라이드해서 보다 복잡한 선택 알고리즘을 사용할 수도 있습니다.

Wwise Simple External Source Manager 확장에서 고정 MediaInfo DataTable은 프로젝트의 모든 External Source 미디어와 관련 메타데이터를 식별합니다. 더 고급한 시스템은 미디어의 목록을 동적으로 업데이트할 수 있습니다. 이러한 시스템을 구현하는 방법은 다양하기 때문에 모든 작업은 가상화됩니다. PostEvent마다 변경되는 임의의 컨테이너나 언어 변경과 같은 외부 상태에 따라 변경되는 구조로 코드를 생성할 수 있습니다.

Loading and unloading media

The FWwiseExternalSourceManagerImpl class tracks known External Source media and the information necessary to load them. 이러한 상태 추적은 ExternalSourceStatesById 맵을 통해 내부적으로 수행됩니다.

위에서 언급한 시스템 및 구조를 구현한 후에 다음 가상 기능을 구현하는 것을 권장합니다.

• LoadExternalSourceMedia: External Source가 사용하는 미디어를 찾아 로드하거나 스트리밍을 준비합니다. FWwiseFileHandlerBase에서 상속된 메소드를 사용하여 미디어 로드 상태를 추적하고 FWwiseExternalSourceFileState 구조를 사용하여 미디어 리소스를 관리하는 것이 좋습니다.
• UnloadExternalSourceMedia: External Source가 사용하는 미디어를 찾아서 리소스를 언로드합니다.
• SetExternalSourceMediaById: 이름으로 식별되는 External Source의 미디어 ID를 설정합니다.
• SetExternalSourceMediaByName: 이름으로 식별되는 External Source의 미디어 이름을 설정합니다.
• SetExternalSourceMediaWithIds: Cookie로 식별되는 External Source의 미디어 ID를 설정합니다.

SetExternalSourceMedia 함수는 각 External Source 미디어에 고유한 ID가 있고 SetExternalSourceMediaByName의 경우 이름을 통해 미디어 ID를 알아낼 수 있다고 가정합니다. 이러한 기능에 대한 참조로 Simple Wwise External Source Manager를 사용하는 것이 좋습니다. External Source에서 미디어로의 매핑을 저장, 업데이트 및 가져오는 방법의 구현에 차이가 있을 수 있기 때문입니다. External Source와 미디어 파일 사이의 매핑이 동적으로 변경되면 리소스가 로드 및 언로드될 수 있습니다.

The current implementation treats these as blocking functions, which potentially run through the game thread. 그러나 이것은 필수 요구 사항은 아닙니다.

After you implement the desired functions, the most complex part of External Source manager development is complete. 모든 것이 제대로 작동하는 경우 EventAsset을 로드하면 (또는 시스템에서External Source 준비를 구현하하는 방식대로 실행하면) 메모리의 해당 External Source에서 사용하는 미디어가 로드되거나 스트리밍을 위해 준비됩니다.

Packaging External Source media

마지막으로 External Source 미디어를 패키징해야 합니다. 간단한 방법은 Unreal 프로젝트 내에서 항상 쿠킹되도록 설정된 폴더에 External Source 미디어를 생성하는 것입니다. To implement more complex packaging logic, override the External Source Manager's Cook method, which the Wwise Resource Cooker calls for each External Source contained in cooked Wwise Assets.

The following functions, which you can override, are also available:

• BindPlayingIdToExternalSources: External Source를 사용하는 Event가 게시될 때 관리자의 내부 상태를 업데이트하려면 이 함수를 오버라이드하세요.
• OnEndOfEvent: External Source를 사용하는 Event가 재생을 중지할 때 관리자의 내부 상태를 업데이트하려면 이 함수를 오버라이드하세요.
• SetGranularity: 스트리밍 미디어 프리페치 청크의 세분성(읽을 최소 바이트 수)을 설정합니다.

Wwise External Source Manager Blueprint

기본적으로 세 가지 Blueprint 함수가 WwiseExternalSourceStatics에 노출됩니다.

• SetExternalSourceMediaById
• SetExternalSourceMediaByName
• SetExternalSourceMediaWithIds

These functions call the corresponding functions defined in the Simple External Source Manager extension. 자세한 내용은 External Source Manager Blueprint 함수 를 참고해 주세요.

External Source Manager가 사용하는 State 구조체

FWwiseExternalSourceState

로드된 External Source의 숫자를 참조하기 위해 WwiseExternalSourceManagerImpl에서 기본적으로 사용되는 구조체입니다.

FWwiseExternalSourceFileState

미디어 리소스를 처리하기 위해 Wwise Simple External Source Manager가 사용하는 State 구조체입니다. 이 상태(state)는 현재 미디어가 재생되고 있는지 여부와 참조 횟수를 추적합니다. Unloading External Source media while it is playing causes the sound engine to crash. 메모리에 저장되거나 스트리밍되는 미디어를 처리하기 위해서는 다음 두 개의 하위 클래스를 사용할 수 있습니다.

• FWwiseInMemoryExternalSourceFileState
  • Media Data는 메모리에 로드되어 SoundEngine에 전달할 AkExternalSourceInfo 구조체를 만드는 데 사용할 수 있습니다.
• FWwiseStreamedExternalSourceFileState
  • FileState는 External Source Manager의 FWwiseFileHandlerBase 기본 클래스에 자신을 등록합니다. 스트림 미디어에 대한 요청이 External Source Manager에게 전달되면, 등록된 FileState를 검색하고, 다음 I/O 요청을 처리합니다.