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 aos delegados necessários (OnProgress e OnResult)
3. Importar áudio de um arquivo ou buffer
4. Reproduzir o sound wave importado obtido do delegado OnResult (mais informações estão aqui)

Nota importante

Certifique-se de que tanto a instância do Runtime Audio Importer quanto a do Sound Wave não sejam coletadas prematuramente pelo garbage collector, 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 evite 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 detecção automática de formato baseada na extensão do arquivo ou no conteúdo.

Importações de áudio em 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 mesmo buffer do sound wave, 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. Certifique-se de que ele seja tratado como uma referência forte pelo 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 ao Delegate 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. Vincule ao Delegate OnResult

Para ser notificado quando o processo de importação de dados de áudio estiver concluído e acessar a referência da onda sonora resultante, você deve vincular ao delegate 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 onda sonora 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 compactados e não compactados.

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 Utilitárias

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 completo de implementação para importar áudio:

Blueprint

C++

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

O exemplo utiliza 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.

Observação: Mantive "Blueprint", "C++", nomes de funções, classes e módulos em inglês conforme solicitado, assim como o formato markdown e estrutura original. Corrigi "arquivo" que estava escrito como "arquivo" no texto traduzido para manter a consistência.

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