Importar Audio

Descripción General

El proceso de importar audio en tiempo de ejecución se puede desglosar en varios pasos:

1. Crear un Runtime Audio Importer
2. Vincularse a los delegados necesarios (OnProgress y OnResult)
3. Importar audio desde un archivo o búfer
4. Reproducir la onda sonora importada obtenida del delegado OnResult (más información aquí)

Nota Importante

Asegúrate de que tanto las instancias de Runtime Audio Importer como de Sound Wave no sean recolectadas prematuramente por el recolector de basura manteniendo una referencia fuerte a ellas, lo cual se puede hacer asignándolas a variables separadas usando UPROPERTY(), TStrongObjectPtr, o cualquier otro método que evite que el objeto sea destruido.

Formatos de Audio Soportados

Runtime Audio Importer soporta importar los siguientes formatos de audio:

Formato	Descripción
MP3	MPEG-1/2/2.5 Audio Layer I/II/III
WAV	Waveform Audio File Format
FLAC	Free Lossless Audio Codec
OGG VORBIS	Contenedor Ogg con audio Vorbis
OGG OPUS	Contenedor Ogg con audio Opus
BINK	Bink Audio
RAW (PCM)	Datos de audio sin comprimir Pulse-Code Modulation (Int8, UInt8, Int16, UInt16, Int32, UInt32, Float32)

tip

Al importar audio, puedes especificar el formato explícitamente o usar la detección automática de formato basada en la extensión del archivo o su contenido.

Importaciones de Audio en Streaming

Para escenarios de streaming donde los datos de audio se reciben de forma incremental (por ejemplo, desde un servidor, captura en tiempo real o transmisiones de red), considera usar Streaming Sound Waves.

Este método proporciona una forma continua de añadir datos de audio al mismo búfer de la onda sonora, haciéndolo adecuado para transmisiones en vivo o archivos grandes procesados en fragmentos. Consulta la documentación de Streaming Sound Wave para más detalles.

Pasos Básicos de Implementación

1. Crear Runtime Audio Importer

Primero, necesitas crear un objeto Runtime Audio Importer. Debes asegurarte de que sea tratado como una referencia fuerte por el recolector de basura.

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. Vincular al Delegado OnProgress

Para rastrear el progreso de la importación de datos de audio, puedes vincular al delegado 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);
});

tip

Esto te permitirá monitorear el progreso y, por ejemplo, implementar una pantalla de carga.

3. Vincular al Delegado OnResult

Para ser notificado cuando el proceso de importación de datos de audio esté completo y para acceder a la referencia de la onda de sonido resultante, debes vincular al delegado 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));
});

aviso

Asegúrate de que la onda de sonido importada sea tratada como una referencia fuerte por el recolector de basura para evitar una recolección prematura no deseada. Esto se puede hacer colocándola como una variable separada en Blueprints.

4. Iniciar Importación de Audio

Comienza el proceso de importación de audio llamando a la función relevante, que puede manejar tanto formatos de datos de audio comprimidos como sin comprimir.

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

Funciones de Utilidad

Encontrar Archivos de Audio

Puedes escanear un directorio en busca de archivos de audio compatibles:

Blueprint

C++

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

Ejemplo Completo

Aquí hay un ejemplo de implementación completo para importar audio:

Blueprint

C++

Este es un ejemplo de código básico para importar audio desde un archivo.

El ejemplo utiliza la función ImportAudioExample ubicada en la clase UImportAudioClassExample dentro del módulo EXAMPLEMODULE.

nota

Para ejecutar el ejemplo con éxito, asegúrate de agregar el módulo RuntimeAudioImporter a PublicDependencyModuleNames o PrivateDependencyModuleNames en el archivo .Build.cs, así como al archivo .uproject de tu proyecto.

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