Audio importieren

Übersicht

Der Prozess des Audioimports zur Laufzeit kann in mehrere Schritte unterteilt werden:

1. Einen Runtime Audio Importer erstellen
2. An die benötigten Delegaten binden (OnProgress und OnResult)
3. Audio aus einer Datei oder einem Puffer importieren
4. Die importierte Sound Wave abspielen, die vom OnResult-Delegaten erhalten wurde (weitere Informationen hier)

Wichtiger Hinweis

Stellen Sie sicher, dass sowohl Runtime Audio Importer- als auch Sound Wave-Instanzen nicht vorzeitig vom Garbage Collector erfasst werden, indem Sie eine feste Referenz auf sie halten. Dies kann durch Zuweisung zu separaten Variablen mit UPROPERTY(), TStrongObjectPtr oder einer anderen Methode, die das Objekt vor der Zerstörung bewahrt, erfolgen.

Unterstützte Audioformate

Runtime Audio Importer unterstützt den Import der folgenden Audioformate:

Format	Beschreibung
MP3	MPEG-1/2/2.5 Audio Layer I/II/III
WAV	Waveform Audio File Format
FLAC	Free Lossless Audio Codec
OGG VORBIS	Ogg-Container mit Vorbis-Audio
OGG OPUS	Ogg-Container mit Opus-Audio
BINK	Bink Audio
RAW (PCM)	Unkomprimierte Pulse-Code-Modulation-Audiodaten (Int8, UInt8, Int16, UInt16, Int32, UInt32, Float32)

tipp

Beim Audioimport können Sie das Format entweder explizit angeben oder die automatische Format-Erkennung basierend auf Dateiendung oder Inhalt verwenden.

Streaming-Audioimporte

Für Streaming-Szenarien, bei denen Audiodaten inkrementell empfangen werden (z. B. von einem Server, Echtzeit-Aufnahme oder Netzwerk-Streams), sollten Sie Streaming Sound Waves in Betracht ziehen.

Diese Methode bietet eine kontinuierliche Möglichkeit, Audiodaten an den gleichen Puffer der Sound Wave anzuhängen, was sie für Live-Streams oder große, in Blöcken verarbeitete Dateien geeignet macht. Weitere Details finden Sie in der Streaming Sound Wave-Dokumentation.

Grundlegende Implementierungsschritte

1. Runtime Audio Importer erstellen

Zuerst müssen Sie ein Runtime Audio Importer-Objekt erstellen. Sie sollten sicherstellen, dass es vom Garbage Collector als starke Referenz behandelt wird.

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. An OnProgress-Delegat binden

Um den Fortschritt beim Importieren von Audiodaten zu verfolgen, können Sie an den OnProgress (Blueprints) / OnProgressNative (C++) Delegaten binden.

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

tipp

Dies ermöglicht es Ihnen, den Fortschritt zu überwachen und beispielsweise einen Ladebildschirm zu implementieren.

3. An den OnResult-Delegaten binden

Um benachrichtigt zu werden, wenn der Audio-Datenimportprozess abgeschlossen ist und um auf die Referenz der resultierenden Soundwelle zuzugreifen, müssen Sie sich an den OnResult (Blueprints) / OnResultNative (C++) Delegaten binden.

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

warnung

Stellen Sie sicher, dass die importierte Schallwelle vom Garbage Collector als starke Referenz behandelt wird, um eine unerwünschte vorzeitige Garbage Collection zu verhindern. Dies kann erreicht werden, indem sie als separate Variable in Blueprints platziert wird.

4. Audioimport starten

Starten Sie den Audioimport-Prozess, indem Sie die relevante Funktion aufrufen, die sowohl komprimierte als auch unkomprimierte Audiodatenformate verarbeiten kann.

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

Hilfsfunktionen

Audio-Dateien finden

Sie können ein Verzeichnis nach unterstützten Audio-Dateien durchsuchen:

Blueprint

C++

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

Vollständiges Beispiel

Hier ist ein vollständiges Implementierungsbeispiel für den Audio-Import:

Blueprint

C++

Dies ist ein einfaches Codebeispiel für den Audio-Import aus einer Datei.

Das Beispiel verwendet die Funktion ImportAudioExample, die sich in der Klasse UImportAudioClassExample innerhalb des Moduls EXAMPLEMODULE befindet.

hinweis

Um das Beispiel erfolgreich auszuführen, stellen Sie sicher, dass Sie das RuntimeAudioImporter-Modul entweder zu PublicDependencyModuleNames oder PrivateDependencyModuleNames in der .Build.cs-Datei sowie zu Ihrer Projektdatei .uproject hinzufügen.

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