Importa Audio

Panoramica

Il processo di importazione dell'audio in runtime può essere suddiviso in diversi passaggi:

1. Crea un Runtime Audio Importer
2. Collega i delegati necessari (OnProgress e OnResult)
3. Importa audio da un file o da un buffer
4. Riproduci l'onda sonora importata ottenuta dal delegato OnResult (maggiori informazioni qui)

Nota Importante

Assicurati che le istanze di Runtime Audio Importer e Sound Wave non vengano raccolte prematuramente dal garbage collector mantenendo un riferimento forte ad esse. Questo può essere fatto assegnandole a variabili separate utilizzando UPROPERTY(), TStrongObjectPtr, o qualsiasi altro metodo che impedisca la distruzione dell'oggetto.

Formati Audio Supportati

Runtime Audio Importer supporta l'importazione dei seguenti formati audio:

Formato	Descrizione
MP3	MPEG-1/2/2.5 Audio Layer I/II/III
WAV	Waveform Audio File Format
FLAC	Free Lossless Audio Codec
OGG VORBIS	Contenitore Ogg con audio Vorbis
OGG OPUS	Contenitore Ogg con audio Opus
BINK	Bink Audio
RAW (PCM)	Dati audio Pulse-Code Modulation non compressi (Int8, UInt8, Int16, UInt16, Int32, UInt32, Float32)

suggerimento

Durante l'importazione dell'audio, puoi specificare esplicitamente il formato o utilizzare il rilevamento automatico del formato basato sull'estensione del file o sul contenuto.

Importazioni Audio in Streaming

Per scenari di streaming in cui i dati audio vengono ricevuti in modo incrementale (ad esempio, da un server, da una cattura in tempo reale o da flussi di rete), considera l'uso di Streaming Sound Waves.

Questo metodo fornisce un modo continuo per aggiungere dati audio allo stesso buffer dell'onda sonora, rendendolo adatto per flussi live o file di grandi dimensioni elaborati in blocchi. Consulta la documentazione di Streaming Sound Wave per maggiori dettagli.

Passaggi di Implementazione di Base

1. Crea Runtime Audio Importer

Per prima cosa, devi creare un oggetto Runtime Audio Importer. Dovresti assicurarti che venga trattato come un riferimento forte dal 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. Bind to OnProgress Delegate

Per tracciare lo stato di avanzamento dell'importazione dei dati audio, puoi collegarti al delegato 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);
});

suggerimento

Cela vous permettra de surveiller la progression et, par exemple, d'implémenter un écran de chargement.

3. Lier au Délégué OnResult

Pour être notifié lorsque le processus d'importation des données audio est terminé et pour accéder à la référence de l'onde sonore résultante, vous devez lier le délégué 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

Assicurati che l'onda sonora importata sia trattata come un riferimento forte dal garbage collector per prevenire una raccolta indesiderata e prematura. Questo può essere fatto posizionandola come una variabile separata nei Blueprints.

4. Inizia l'Importazione Audio

Inizia il processo di importazione audio chiamando la funzione rilevante, che può gestire sia formati di dati audio compressi che non compressi.

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

Funzioni Utilità

Trovare File Audio

Puoi scansionare una directory per file audio supportati:

Blueprint

C++

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

Esempio Completo

Ecco un esempio di implementazione completa per importare audio:

Blueprint

C++

Questo è un esempio di codice di base per importare audio da un file.

L'esempio utilizza la funzione ImportAudioExample situata nella classe UImportAudioClassExample all'interno del modulo EXAMPLEMODULE.

note

Per eseguire correttamente l'esempio, assicurati di aggiungere il modulo RuntimeAudioImporter a PublicDependencyModuleNames o PrivateDependencyModuleNames nel file .Build.cs, così come al file .uproject del tuo progetto.

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