Importuj Audio

Przegląd

Proces importowania audio w czasie rzeczywistym można podzielić na kilka kroków:

1. Utwórz Runtime Audio Importer
2. Powiąż z wymaganymi delegatami (OnProgress i OnResult)
3. Importuj audio z pliku lub bufora
4. Odtwórz zaimportowaną falę dźwiękową uzyskaną z delegata OnResult (więcej informacji jest tutaj)

Ważna Uwaga

Upewnij się, że zarówno instancje Runtime Audio Importer, jak i Sound Wave nie są przedwcześnie usuwane przez garbage collector, utrzymując do nich twarde referencje. Można to zrobić przypisując je do oddzielnych zmiennych za pomocą UPROPERTY(), TStrongObjectPtr lub jakiejkolwiek innej metody, która zapobiega zniszczeniu obiektu.

Obsługiwane Format Audio

Runtime Audio Importer obsługuje importowanie następujących formatów audio:

Format	Opis
MP3	MPEG-1/2/2.5 Audio Layer I/II/III
WAV	Waveform Audio File Format
FLAC	Free Lossless Audio Codec
OGG VORBIS	Kontener Ogg z audio Vorbis
OGG OPUS	Kontener Ogg z audio Opus
BINK	Bink Audio
RAW (PCM)	Nieskompresowane dane audio Pulse-Code Modulation (Int8, UInt8, Int16, UInt16, Int32, UInt32, Float32)

wskazówka

Podczas importowania audio możesz albo jawnie określić format, albo użyć automatycznego wykrywania formatu na podstawie rozszerzenia pliku lub zawartości.

Importowanie Audio w Strumieniu

Dla scenariuszy strumieniowych, w których dane audio są odbierane przyrostowo (np. z serwera, przechwytywania w czasie rzeczywistym lub strumieni sieciowych), rozważ użycie Streaming Sound Waves.

Ta metoda zapewnia ciągły sposób dołączania danych audio do bufora tej samej fali dźwiękowej, co czyni ją odpowiednią dla transmisji na żywo lub dużych plików przetwarzanych w porcjach. Zobacz dokumentację Streaming Sound Wave po więcej szczegółów.

Podstawowe Kroki Implementacji

1. Utwórz Runtime Audio Importer

Najpierw musisz utworzyć obiekt Runtime Audio Importer. Należy upewnić się, że jest on traktowany jako silna referencja przez garbage collector.

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. Powiąż z delegatem OnProgress

Aby śledzić postęp importowania danych audio, możesz powiązać się z delegatem 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);
});

wskazówka

Pozwoli to monitorować postęp i, na przykład, zaimplementować ekran ładowania.

3. Powiąż z delegatem OnResult

Aby otrzymywać powiadomienia, gdy proces importowania danych audio jest zakończony i uzyskać dostęp do referencji wynikowej fali dźwiękowej, musisz powiązać się z delegatem 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));
});

warning

Upewnij się, że zaimportowana fala dźwiękowa jest traktowana jako silne odwołanie przez garbage collector, aby zapobiec niechcianemu przedwczesnemu usuwaniu z pamięci. Można to zrobić, umieszczając ją jako oddzielną zmienną w Blueprints.

4. Rozpocznij import audio

Rozpocznij proces importu audio, wywołując odpowiednią funkcję, która może obsłużyć zarówno skompresowane, jak i nieskompresowane formaty danych audio.

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

Funkcje narzędziowe

Wyszukiwanie plików audio

Możesz przeskanować katalog w poszukiwaniu obsługiwanych plików audio:

Blueprint

C++

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

Kompletny przykład

Oto pełny przykład implementacji importowania audio:

Blueprint

C++

To jest podstawowy przykład kodu do importowania audio z pliku.

Przykład używa funkcji ImportAudioExample znajdującej się w klasie UImportAudioClassExample w module EXAMPLEMODULE.

notatka

Aby pomyślnie uruchomić przykład, upewnij się, że dodałeś moduł RuntimeAudioImporter do PublicDependencyModuleNames lub PrivateDependencyModuleNames w pliku .Build.cs, a także do pliku .uproject twojego projektu.

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