Importer de l'audio

Aperçu

Le processus d'importation de l'audio à l'exécution peut être décomposé en plusieurs étapes :

1. Créer un Runtime Audio Importer
2. Lier aux délégués nécessaires (OnProgress et OnResult)
3. Importer l'audio depuis un fichier ou un tampon
4. Lire l'onde sonore importée obtenue depuis le délégué OnResult (plus d'informations sont ici)

Note importante

Assurez-vous que les instances de Runtime Audio Importer et de Sound Wave ne soient pas prématurément collectées par le ramasse-miettes 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 qui empêche 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 de l'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 fournit un moyen continu d'ajouter des données audio au même tampon de l'onde sonore, 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 mise en œuvre de base

1. Créer 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 ramasse-miettes.

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 pour 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 ramasse-miettes pour éviter une collecte prématurée non désirée. Cela peut être fait en la plaçant comme une variable séparée dans les Blueprints.

4. Démarrer l'Import Audio

Démarrez le processus d'import audio en appelant la fonction appropriée, 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 parcourir un répertoire pour trouver les 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 un exemple d'implémentation complet pour l'importation audio :

Blueprint

C++

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

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

remarque

Pour exécuter l'exemple avec succès, assurez-vous d'ajouter le module RuntimeAudioImporter soit à PublicDependencyModuleNames, soit à 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);
}