オーディオのインポート

概要

ランタイムでのオーディオインポートプロセスは、以下のいくつかのステップに分解できます：

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

警告

ガベージコレクターによって不要な早期のガベージコレクションを防ぐため、インポートされた音声波形が強参照として扱われるようにしてください。これは、Blueprints 内で別の変数として配置することで行えます。

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 関数を使用しています。

注記

この例を正常に実行するには、RuntimeAudioImporter.Build.cs ファイルの PublicDependencyModuleNames または PrivateDependencyModuleNames に RuntimeAudioImporter モジュールを追加し、さらに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);
}