Importar Audio

Resumen

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

1. Crear un Runtime Audio Importer
2. Vincular a los delegados necesarios (OnProgress y OnResult)
3. Importar audio desde un archivo o buffer
4. Reproducir el sound wave importado obtenido del delegado OnResult (más información aquí)

Nota Importante

Asegúrate de que tanto Runtime Audio Importer como las instancias de Sound Wave no sean recolectadas prematuramente por el garbage collector 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 en formato Pulse-Code Modulation (Int8, UInt8, Int16, UInt16, Int32, UInt32, Float32)

tip

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

Importación de Audio en Streaming

Para escenarios de streaming donde los datos de audio se reciben incrementalmente (ej. desde un servidor, captura en tiempo real o streams de red), considera usar Streaming Sound Waves.

Este método proporciona una forma continua de añadir datos de audio al mismo buffer del sound wave, 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 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. 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 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 lograr 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 audio comprimidos como no comprimidos.

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

Búsqueda de 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 una implementación completa de ejemplo para importar audio:

Blueprint

C++

Este es un ejemplo básico de código 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 correctamente, asegúrate de añadir el módulo RuntimeAudioImporter ya sea a PublicDependencyModuleNames o PrivateDependencyModuleNames en el archivo .Build.cs, así como al archivo .uproject de tu proyecto.

Manteniendo:

1. Estructura exacta de Tabs y TabItems
2. Formato de markdown (:::note)
3. Términos técnicos en inglés (RuntimeAudioImporter, .Build.cs, .uproject)
4. Nombres de funciones/clases sin modificar (ImportAudioExample, UImportAudioClassExample)
5. Espaciado y saltos de línea idénticos al original

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