Audio importieren

Übersicht

Der Prozess des Audio-Imports zur Laufzeit kann in mehrere Schritte unterteilt werden:

1. Einen Runtime Audio Importer erstellen
2. An die benötigten Delegates binden (OnProgress und OnResult)
3. Audio aus einer Datei oder einem Buffer importieren
4. Die importierte Sound Wave aus dem OnResult-Delegate abspielen (weitere Informationen finden Sie hier)

Wichtiger Hinweis

Stellen Sie sicher, dass sowohl Runtime Audio Importer als auch Sound Wave-Instanzen nicht vorzeitig vom Garbage Collector bereinigt werden, indem Sie eine starke Referenz auf sie halten. Dies kann durch Zuweisung zu separaten Variablen mittels UPROPERTY(), TStrongObjectPtr oder einer anderen Methode, die das Objekt vor der Zerstörung schützt, 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 Import von Audio können Sie entweder das Format explizit angeben oder die automatische Formaterkennung basierend auf Dateierweiterung oder Inhalt verwenden.

Streaming-Audio-Imports

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

Diese Methode bietet eine kontinuierliche Möglichkeit, Audiodaten an den gleichen Sound-Wave-Buffer anzuhängen, was sie für Live-Streams oder große Dateien, die in Chunks verarbeitet werden, 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 als starke Referenz vom Garbage Collector 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-Delegate binden

Um den Fortschritt beim Importieren von Audiodaten zu verfolgen, können Sie an den OnProgress (Blueprints) / OnProgressNative (C++) Delegate 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 verfolgen und beispielsweise einen Ladebildschirm zu implementieren.

3. An OnResult Delegate binden

Um benachrichtigt zu werden, wenn der Audio-Daten-Importprozess abgeschlossen ist und auf die Referenz der resultierenden Sound-Wave zugreifen zu können, müssen Sie an den OnResult (Blueprints) / OnResultNative (C++) Delegate 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 Soundwelle vom Garbage Collector als starke Referenz behandelt wird, um 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 durch Aufruf der relevanten Funktion, 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);

Utility-Funktionen

Audiodateien finden

Sie können ein Verzeichnis nach unterstützten Audiodateien 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 eine vollständige Implementierungsbeispiel für den Audio-Import:

Blueprint

C++

Dies ist ein grundlegendes Codebeispiel für den Import von Audio 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 in der .uproject-Datei Ihres Projekts hinzufügen.

Key points maintained:

1. Exact same markdown structure and tabs
2. Preserved line breaks and whitespace
3. Technical terms kept in English (Blueprint, C++, RuntimeAudioImporter, etc.)
4. Code blocks and class/function names untouched
5. Image path remains identical
6. Note formatting preserved with :::note syntax
7. File extensions (.Build.cs, .uproject) unchanged

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