Importowanie audio

Przegląd

Proces importowania audio w czasie działania można podzielić na kilka kroków:

1. Utwórz Runtime Audio Importer
2. Podłącz się do potrzebnych delegatów (OnProgress i OnResult)
3. Zaimportuj 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 zostaną przedwcześnie zebrane przez odśmiecacz, utrzymując do nich twarde referencje. Można to zrobić przypisując je do oddzielnych zmiennych za pomocą UPROPERTY(), TStrongObjectPtr lub dowolnej innej metody, która zapobiega zniszczeniu obiektu.

Obsługiwane formaty 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 jego zawartości.

Importowanie audio strumieniowego

W scenariuszach strumieniowych, gdzie 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 fragmentach. Więcej szczegółów znajdziesz w dokumentacji Streaming Sound Wave.

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 odśmiecacz.

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 otrzymać powiadomienie o zakończeniu procesu importu danych audio 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));
});

ostrzeżenie

Upewnij się, że zaimportowana fala dźwiękowa jest traktowana przez odśmiecacz pamięci (garbage collector) jako silne odniesienie, aby zapobiec niepożądanemu przedwczesnemu odśmiecaniu. Można to zrobić, umieszczając ją jako oddzielną zmienną w Blueprints.

4. Rozpocznij import audio

Rozpocznij proces importowania 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 dźwięku:

Blueprint

C++

To jest podstawowy przykład kodu do importowania dźwięku z pliku.

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

notatka

Aby przykład działał poprawnie, 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);
}