オーディオのインポート

概要

ランタイムでのオーディオインポートのプロセスは、いくつかのステップに分けることができます：

1. Runtime Audio Importer を作成する
2. 必要なデリゲート (OnProgress と OnResult) にバインドする
3. ファイルまたはバッファからオーディオをインポートする
4. OnResult デリゲートから取得したインポート済みサウンドウェーブを再生する (詳細はこちら)

重要な注意点

Runtime Audio Importer と Sound Wave の両方のインスタンスが、ガベージコレクションによって早期に破棄されないようにするためには、それらへの強参照を維持する必要があります。これは、UPROPERTY()、TStrongObjectPtr、またはオブジェクトが破棄されないようにする他の方法を使用して、別々の変数に割り当てることで行うことができます。

サポートされているオーディオフォーマット

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	Vorbis オーディオを含む Ogg コンテナ
OGG OPUS	Opus オーディオを含む Ogg コンテナ
BINK	Bink Audio
RAW (PCM)	非圧縮パルス符号変調オーディオデータ (Int8, UInt8, Int16, UInt16, Int32, UInt32, Float32)

ヒント

オーディオをインポートする際、フォーマットを明示的に指定するか、ファイル拡張子またはコンテンツに基づいた自動フォーマット検出を使用することができます。

ストリーミングオーディオインポート

オーディオデータが段階的に受信されるストリーミングシナリオ（例：サーバーからの受信、リアルタイムキャプチャ、ネットワークストリーム）では、Streaming Sound Waves の使用を検討してください。

この方法は、同じサウンドウェーブのバッファにオーディオデータを継続的に追加する方法を提供し、ライブストリームやチャンク単位で処理される大きなファイルに適しています。詳細については、Streaming Sound Wave ドキュメントを参照してください。

基本的な実装手順

1. Runtime Audio Importer を作成する

まず、Runtime Audio Importer オブジェクトを作成する必要があります。ガベージコレクタによって強参照として扱われるようにする必要があります。

Blueprint

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();

2. OnProgress デリゲートへのバインド

オーディオデータのインポート進捗状況を追跡するには、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);
});

ヒント

これにより、進行状況を監視し、例えばローディング画面を実装することができます。

3. OnResult デリゲートにバインドする

オーディオデータのインポート処理が完了し、結果のサウンドウェーブの参照にアクセスするための通知を受け取るには、OnResult (Blueprints) / OnResultNative (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->OnResultNative.AddWeakLambda(this, [](URuntimeAudioImporterLibrary* Importer, UImportedSoundWave* ImportedSoundWave, ERuntimeImportStatus Status)
{
	UE_LOG(LogTemp, Log, TEXT("Import result: %s"), *UEnum::GetValueAsString(Status));
});

警告

インポートしたサウンドウェーブがガベージコレクションによって不要な早期回収を防ぐため、強参照として扱われるようにしてください。これは、ブループリントで別の変数として配置することで実現できます。

4. オーディオインポートを開始する

関連する関数を呼び出すことでオーディオインポートプロセスを開始します。この関数は、圧縮および非圧縮のオーディオデータ形式の両方を処理できます。

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);

ユーティリティ関数

オーディオファイルの検索

サポートされているオーディオファイルをディレクトリ内でスキャンできます：

Blueprint

C++

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

完全な例

オーディオをインポートするための完全な実装例を以下に示します：

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);
}