오디오 가져오기

런타임에서 오디오를 가져오는 과정은 여러 단계로 나뉩니다:

1. Runtime Audio Importer를 생성합니다.
2. 필요한 델리게이트(OnProgress 및 OnResult)에 바인딩합니다.
3. 파일 또는 버퍼에서 오디오를 가져옵니다.
4. OnResult 델리게이트에서 반환된 가져온 사운드 웨이브를 재생합니다 (자세한 내용은 여기에서 확인하세요).

Runtime Audio Importer와 Sound Wave 인스턴스가 조기에 가비지 컬렉션되지 않도록 강한 참조를 유지해야 합니다. 이를 위해 UPROPERTY(), TStrongObjectPtr 또는 객체가 제거되지 않도록 방지하는 다른 방법을 사용하여 별도의 변수에 할당할 수 있습니다.

스트리밍 오디오 가져오기

서버, 실시간 캡처 또는 네트워크 스트림과 같이 오디오 데이터를 점진적으로 수신하는 스트리밍 시나리오의 경우, Streaming Sound Waves를 사용하는 것이 좋습니다. 이 방법은 동일한 사운드 웨이브의 버퍼에 지속적으로 오디오 데이터를 추가할 수 있어, 라이브 스트리밍이나 청크 단위로 처리되는 대용량 파일에 적합합니다. 자세한 내용은 Streaming Sound Wave 문서를 참조하세요.

지원되는 오디오 형식

Runtime Audio Importer는 다음 오디오 형식의 가져오기를 지원합니다:

• MP3 - MPEG-1/2/2.5 Audio Layer I/II/III
• WAV - Waveform Audio File Format
• FLAC - Free Lossless Audio Codec
• OGG VORBIS - Ogg 컨테이너 내 Vorbis 오디오
• OGG OPUS - Ogg 컨테이너 내 Opus 오디오
• BINK - Bink Audio
• RAW (PCM) - 비압축 Pulse-Code Modulation 오디오 데이터 (Int8, UInt8, Int16, UInt16, Int32, UInt32, Float32)

오디오를 가져올 때 파일 확장자 또는 콘텐츠를 기반으로 자동 형식 감지 기능을 사용하거나, 형식을 명시적으로 지정할 수 있습니다.

오디오 파일 찾기

지원되는 오디오 파일을 찾기 위해 디렉터리를 스캔할 수 있습니다:

블루프린트

C++

URuntimeAudioUtilities::ScanDirectoryForAudioFiles(TEXT("C:/Folder/"), true,
	FOnScanDirectoryForAudioFilesResultNative::CreateWeakLambda(this, [this](bool bSucceeded, const TArray<FString>& AudioFilePaths)
	{
		// Handle the result
	}));

예제

먼저, Runtime Audio Importer 객체를 생성해야 합니다. 이 객체가 가비지 컬렉터에 의해 강한 참조로 처리되도록 해야 하며, 이를 위해 블루프린트에서 별도의 변수로 지정하는 것이 좋습니다. 이렇게 하면 객체가 조기에 소멸되는 것을 방지할 수 있습니다.

블루프린트

C++

Header, in the UCLASS declaration (.h)

// UPROPERTY() is used here to prevent the object from being prematurely garbage collected
UPROPERTY()
class URuntimeAudioImporterLibrary* Importer;

Source file, in the function where you want to create the importer (.cpp)

Importer = URuntimeAudioImporterLibrary::CreateRuntimeAudioImporter();

---

오디오 데이터를 가져오는 진행 상황을 추적하려면 OnProgress (Blueprints) / OnProgressNative (C++) 델리게이트에 바인딩할 수 있습니다. 이를 통해 진행 상황을 모니터링하고, 예를 들어 로딩 화면을 구현할 수 있습니다. 이 델리게이트에 바인딩하려면 바인드 이벤트 노드에서 이벤트 핀을 가져오면 됩니다.

Blueprint

C++

// Assuming Importer is a UE reference to a URuntimeAudioImporterLibrary object
// AddWeakLambda is used just as an example. You can use any other method to bind the delegate, such as AddUObject, AddUFunction, etc.
Importer->OnProgressNative.AddWeakLambda(this, [](int32 Percentage)
{
	UE_LOG(LogTemp, Log, TEXT("Import progress: %d"), Percentage);
});

---

오디오 데이터 가져오기 프로세스가 완료되었음을 알리고, 결과로 생성된 사운드 웨이브의 참조에 접근하려면 OnResult (Blueprints) / OnResultNative (C++) 델리게이트를 바인딩해야 합니다. 또한, 가져온 사운드 웨이브가 가비지 컬렉터에 의해 강한 참조(strong reference)로 처리되도록 보장하여, 원치 않는 조기 가비지 컬렉션을 방지해야 합니다. 이를 위해 Blueprints에서 별도의 변수로 설정하면 됩니다.

Blueprint

C++

// Assuming Importer is a UE reference to a URuntimeAudioImporterLibrary object
// AddWeakLambda is used just as an example. You can use any other method to bind the delegate, such as AddUObject, AddUFunction, etc.
Importer->OnResultNative.AddWeakLambda(this, [](URuntimeAudioImporterLibrary* Importer, UImportedSoundWave* ImportedSoundWave, ERuntimeImportStatus Status)
{
	UE_LOG(LogTemp, Log, TEXT("Import result: %s"), *UEnum::GetValueAsString(Status));
});

---

오디오 가져오기 프로세스를 시작하려면 관련 함수를 호출하세요. 이 함수는 압축 및 비압축 오디오 데이터 형식을 모두 처리할 수 있습니다.

Blueprint

C++

// Assuming Importer is a UE reference to a URuntimeAudioImporterLibrary object

// Import audio from a file
Importer->ImportAudioFromFile(TEXT("C:/Folder/AudioFile.mp3"), ERuntimeAudioFormat::Auto);

// Import audio from a buffer
TArray<uint8> AudioData = ...; // Fill the array with your audio data
Importer->ImportAudioFromBuffer(MoveTemp(AudioData), ERuntimeAudioFormat::OggVorbis);

// Import audio from a RAW file
Importer->ImportAudioFromRAWFile(TEXT("C:/Folder/AudioFile.raw"), ERuntimeRAWAudioFormat::Int8, 44100, 2);

// Import audio from a RAW buffer
TArray<uint8> RAWBuffer = ...; // Fill the array with your PCM int 16-bit audio data
Importer->ImportAudioFromRAWBuffer(MoveTemp(RAWBuffer), ERuntimeRAWAudioFormat::Int16, 44100, 2);

---

가져오기 프로세스가 완료되면, 결과로 가져온 사운드 웨이브를 OnResult 델리게이트를 통해 얻을 수 있습니다.

전체 예제

Blueprint

C++

이것은 파일에서 오디오를 가져오는 기본 코드 예제입니다.

이 예제에서는 EXAMPLEMODULE 모듈 내 UImportAudioClassExample 클래스에 위치한 ImportAudioExample 함수를 사용합니다.

참고: 예제를 성공적으로 실행하려면 .Build.cs 파일의 PublicDependencyModuleNames 또는 PrivateDependencyModuleNames에 RuntimeAudioImporter 모듈을 추가하고, 프로젝트의 .uproject 파일에도 모듈을 추가해야 합니다.

Header file (.h)

#pragma once

#include "CoreMinimal.h"
#include "UObject/Object.h"
#include "ImportAudioClassExample.generated.h"

UCLASS(BlueprintType)
class EXAMPLEMODULE_API UImportAudioClassExample : public UObject
{
	GENERATED_BODY()

public:
	UFUNCTION(BlueprintCallable)
	void ImportAudioExample();

private:
	// Please pay attention to making the RuntimeAudioImporter a hard reference, such as using UPROPERTY(), to prevent it from being prematurely garbage collected
	UPROPERTY()
	class URuntimeAudioImporterLibrary* RuntimeAudioImporter;
};

Source file (.cpp)

#include "ImportAudioClassExample.h"
#include "RuntimeAudioImporterLibrary.h"

void UImportAudioClassExample::ImportAudioExample()
{
	RuntimeAudioImporter = URuntimeAudioImporterLibrary::CreateRuntimeAudioImporter();

	if (!IsValid(RuntimeAudioImporter))
	{
		UE_LOG(LogTemp, Error, TEXT("Failed to create audio importer"));
		return;
	}

	RuntimeAudioImporter->OnProgressNative.AddWeakLambda(this, [](int32 Percentage)
	{
		UE_LOG(LogTemp, Log, TEXT("Audio importing percentage: %d"), Percentage);
	});

	RuntimeAudioImporter->OnResultNative.AddWeakLambda(this, [this](URuntimeAudioImporterLibrary* Importer, UImportedSoundWave* ImportedSoundWave, ERuntimeImportStatus Status)
	{
		if (Status == ERuntimeImportStatus::SuccessfulImport)
		{
			UE_LOG(LogTemp, Warning, TEXT("Successfully imported audio with sound wave %s"), *ImportedSoundWave->GetName());
			// Here you can handle ImportedSoundWave playback, like "UGameplayStatics::PlaySound2D(GetWorld(), ImportedSoundWave);"
		}
		else
		{
			UE_LOG(LogTemp, Error, TEXT("Failed to import audio"));
		}

		RuntimeAudioImporter = nullptr;
	});

	RuntimeAudioImporter->ImportAudioFromFile(TEXT("C:/Folder/Example.mp3"), ERuntimeAudioFormat::Auto);
}