Importar Áudio

Visão Geral

O processo de importar áudio em tempo de execução pode ser dividido em várias etapas:

1. Criar um Runtime Audio Importer
2. Vincular-se aos delegados necessários (OnProgress e OnResult)
3. Importar áudio de um arquivo ou buffer
4. Reproduzir a onda sonora importada obtida do delegado OnResult (mais informações estão aqui)

Nota Importante

Certifique-se de que as instâncias de Runtime Audio Importer e Sound Wave não sejam coletadas prematuramente pelo coletor de lixo, mantendo uma referência forte a elas. Isso pode ser feito atribuindo-as a variáveis separadas usando UPROPERTY(), TStrongObjectPtr ou qualquer outro método que impeça a destruição do objeto.

Formatos de Áudio Suportados

O Runtime Audio Importer suporta a importação dos seguintes formatos de áudio:

Formato	Descrição
MP3	MPEG-1/2/2.5 Audio Layer I/II/III
WAV	Waveform Audio File Format
FLAC	Free Lossless Audio Codec
OGG VORBIS	Contêiner Ogg com áudio Vorbis
OGG OPUS	Contêiner Ogg com áudio Opus
BINK	Bink Audio
RAW (PCM)	Dados de áudio Pulse-Code Modulation não comprimidos (Int8, UInt8, Int16, UInt16, Int32, UInt32, Float32)

dica

Ao importar áudio, você pode especificar o formato explicitamente ou usar a detecção automática de formato baseada na extensão do arquivo ou no seu conteúdo.

Importações de Áudio por Streaming

Para cenários de streaming onde os dados de áudio são recebidos incrementalmente (por exemplo, de um servidor, captura em tempo real ou fluxos de rede), considere usar Streaming Sound Waves.

Este método fornece uma maneira contínua de anexar dados de áudio ao buffer da mesma onda sonora, tornando-o adequado para transmissões ao vivo ou arquivos grandes processados em partes. Consulte a documentação do Streaming Sound Wave para obter mais detalhes.

Etapas Básicas de Implementação

1. Criar Runtime Audio Importer

Primeiro, você precisa criar um objeto Runtime Audio Importer. Você deve garantir que ele seja tratado como uma referência forte pelo coletor de lixo.

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 ao Delegado OnProgress

Para acompanhar o progresso da importação de dados de áudio, você pode vincular ao 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);
});

dica

Isso permitirá que você monitore o progresso e, por exemplo, implemente uma tela de carregamento.

3. Vincular ao Delegado OnResult

Para ser notificado quando o processo de importação de dados de áudio estiver completo e para acessar a referência da onda sonora resultante, você deve vincular-se ao 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));
});

atenção

Certifique-se de que a forma de onda de áudio importada seja tratada como uma referência forte pelo coletor de lixo para evitar coleta prematura indesejada. Isso pode ser feito colocando-a como uma variável separada em Blueprints.

4. Iniciar Importação de Áudio

Inicie o processo de importação de áudio chamando a função relevante, que pode lidar com formatos de dados de áudio comprimidos e não 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);

Funções de Utilidade

Localizando Arquivos de Áudio

Você pode escanear um diretório em busca de arquivos de áudio suportados:

Blueprint

C++

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

Exemplo Completo

Aqui está um exemplo de implementação completa para importar áudio:

Blueprint

C++

Este é um exemplo de código básico para importar áudio de um arquivo.

O exemplo usa a função ImportAudioExample localizada na classe UImportAudioClassExample dentro do módulo EXAMPLEMODULE.

nota

Para executar o exemplo com sucesso, certifique-se de adicionar o módulo RuntimeAudioImporter a PublicDependencyModuleNames ou PrivateDependencyModuleNames no arquivo .Build.cs, bem como ao arquivo .uproject do seu projeto.

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