Importa Audio

Panoramica

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

1. Crea un Runtime Audio Importer
2. Collega ai delegati necessari (OnProgress e OnResult)
3. Importa audio da un file o buffer
4. Riproduci la sound wave importata ottenuta dal delegato OnResult (maggiori informazioni qui)

Nota Importante

Assicurati che sia le istanze di Runtime Audio Importer che di Sound Wave non vengano garbage collected prematuramente mantenendo un riferimento forte ad esse, il che può essere fatto assegnandole a variabili separate usando UPROPERTY(), TStrongObjectPtr, o qualsiasi altro metodo che prevenga 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

Quando importi audio, puoi specificare il formato esplicitamente o usare 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, acquisizione in tempo reale, o flussi di rete), considera l'uso di Streaming Sound Waves.

Questo metodo fornisce un modo continuo per aggiungere dati audio allo stesso buffer della sound wave, rendendolo adatto per flussi live o file grandi elaborati in blocchi. Vedi la documentazione di Streaming Sound Wave per maggiori dettagli.

Passaggi Base di Implementazione

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. Associa al Delegato OnProgress

Per tracciare lo stato di avanzamento dell'importazione dei dati audio, puoi associarti 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

Questo ti permetterà di monitorare l'avanzamento e, ad esempio, implementare una schermata di caricamento.

3. Collegati al Delegato OnResult

Per essere notificato quando il processo di importazione dei dati audio è completo e per accedere al riferimento dell'onda sonora risultante, devi collegarti al delegato 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 prematura. Questo può essere fatto posizionandola come una variabile separata nei Blueprints.

4. Avvia 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 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 nel 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);
}