Importer de l'audio

Aperçu

Le processus d'importation d'audio au runtime peut être décomposé en plusieurs étapes :

1. Créer un Runtime Audio Importer
2. Se lier aux délégués nécessaires (OnProgress et OnResult)
3. Importer l'audio depuis un fichier ou un buffer
4. Jouer le sound wave importé obtenu depuis le délégué OnResult (plus d'informations sont disponibles ici)

Note importante

Assurez-vous que les instances Runtime Audio Importer et Sound Wave ne soient pas prématurément collectées par le garbage collector en maintenant une référence forte vers elles. Cela peut être fait en les assignant à des variables séparées en utilisant UPROPERTY(), TStrongObjectPtr, ou toute autre méthode empêchant la destruction de l'objet.

Formats audio pris en charge

Runtime Audio Importer prend en charge l'importation des formats audio suivants :

Format	Description
MP3	MPEG-1/2/2.5 Audio Layer I/II/III
WAV	Waveform Audio File Format
FLAC	Free Lossless Audio Codec
OGG VORBIS	Conteneur Ogg avec audio Vorbis
OGG OPUS	Conteneur Ogg avec audio Opus
BINK	Bink Audio
RAW (PCM)	Données audio Pulse-Code Modulation non compressées (Int8, UInt8, Int16, UInt16, Int32, UInt32, Float32)

astuce

Lors de l'importation d'audio, vous pouvez soit spécifier le format explicitement, soit utiliser la détection automatique de format basée sur l'extension du fichier ou son contenu.

Importations audio en streaming

Pour les scénarios de streaming où les données audio sont reçues de manière incrémentielle (par exemple, depuis un serveur, une capture en temps réel ou des flux réseau), envisagez d'utiliser Streaming Sound Waves.

Cette méthode permet d'ajouter continuellement des données audio au même buffer d'un sound wave, ce qui la rend adaptée aux flux en direct ou aux fichiers volumineux traités par morceaux. Consultez la documentation Streaming Sound Wave pour plus de détails.

Étapes de base de mise en œuvre

1. Créer un Runtime Audio Importer

Tout d'abord, vous devez créer un objet Runtime Audio Importer. Vous devez vous assurer qu'il est traité comme une référence forte par le 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. Lier au délégué OnProgress

Pour suivre la progression de l'importation des données audio, vous pouvez lier au délégué 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);
});

astuce

Cela vous permettra de surveiller la progression et, par exemple, d'implémenter un écran de chargement.

3. Lier au délégué OnResult

Pour être notifié lorsque le processus d'importation des données audio est terminé et accéder à la référence de l'onde sonore résultante, vous devez lier le délégué 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));
});

attention

Assurez-vous que l'onde sonore importée est traitée comme une référence forte par le garbage collector pour éviter une collecte prématurée non désirée. Ceci peut être fait en la plaçant comme une variable séparée dans les Blueprints.

4. Démarrer l'Import Audio

Commencez le processus d'import audio en appelant la fonction pertinente, qui peut gérer à la fois les formats de données audio compressées et non compressées.

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

Fonctions utilitaires

Recherche de fichiers audio

Vous pouvez scanner un répertoire pour trouver des fichiers audio pris en charge :

Blueprint

C++

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

Exemple Complet

Voici une implémentation complète pour l'importation audio :

Blueprint

C++

Ceci est un exemple de code basique pour importer un fichier audio.

L'exemple utilise la fonction ImportAudioExample située dans la classe UImportAudioClassExample du module EXAMPLEMODULE.

remarque

Pour exécuter cet exemple avec succès, assurez-vous d'ajouter le module RuntimeAudioImporter soit à PublicDependencyModuleNames ou PrivateDependencyModuleNames dans le fichier .Build.cs, ainsi qu'au fichier .uproject de votre projet.

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