導入音頻

概述

在運行時導入音頻的過程可以分解為以下幾個步驟：

1. 創建一個運行時音頻導入器
2. 綁定所需的委託（OnProgress 和 OnResult）
3. 從文件或緩衝區導入音頻
4. 播放從 OnResult 委託獲得的導入音波（更多信息請參見此處）

重要提示

請確保 Runtime Audio Importer 和 Sound Wave 實例不會被過早地進行垃圾回收，方法是通過使用 UPROPERTY()、TStrongObjectPtr 或任何其他防止對象被銷毀的方式，將它們分配給單獨的變量來保持對它們的強引用。

支持的音頻格式

Runtime Audio Importer 支持導入以下音頻格式：

格式	描述
MP3	MPEG-1/2/2.5 音頻層 I/II/III
WAV	波形音頻文件格式
FLAC	免費無損音頻編解碼器
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 對象。您應確保它被垃圾回收器視為強引用。

藍圖

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 (藍圖) / OnProgressNative (C++) 委派。

藍圖

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（藍圖）/ OnResultNative（C++）委派。

藍圖

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. 開始音頻導入

通過調用相關函數開始音頻導入過程，該函數可以處理壓縮和未壓縮的音頻數據格式。

藍圖

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 檔案中。

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