オーディオのインポート

概要

ランタイムでオーディオをインポートするプロセスは、以下のステップに分解できます:

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	Ogg コンテナに Vorbis オーディオ
OGG OPUS	Ogg コンテナに Opus オーディオ
BINK	Bink Audio
RAW (PCM)	非圧縮 Pulse-Code Modulation オーディオデータ (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に追加し、プロジェクトの.uproject**ファイルにも追加する必要があります。

```cpp title="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);
}