Capturable Sound Wave

Aperçu

Une onde sonore capturable est dérivée de l'onde sonore en streaming. Elle prend en charge la capture de données audio à partir de périphériques d'entrée comme un microphone et leur lecture, avec les mêmes capacités qu'une onde sonore importée (y compris le rembobinage, l'utilisation dans les SoundCues, etc). Vous pouvez même capturer et lire l'audio simultanément sans aucune limitation.

astuce

Pour la détection d'activité vocale (VAD), consultez cette page.

remarque

L'onde sonore capturable demande automatiquement les autorisations du microphone sur iOS et Android une fois la capture démarrée.

Utilisation de base

Création d'une onde sonore capturable

Vous devez d'abord créer une onde sonore capturable.

Blueprint

C++

UCapturableSoundWave* CapturableSoundWave = UCapturableSoundWave::CreateCapturableSoundWave();

attention

Vous devez traiter l'onde sonore capturable comme une référence forte pour éviter une destruction prématurée (par exemple en l'assignant à une variable séparée dans Blueprints ou en utilisant UPROPERTY() en C++).

Obtenir les périphériques d'entrée disponibles

Pour utiliser cette fonctionnalité, vous devez d'abord obtenir tous les périphériques d'entrée audio disponibles qui peuvent être utilisés pour la capture.

Blueprint

C++

UCapturableSoundWave::GetAvailableAudioInputDevices(FOnGetAvailableAudioInputDevicesResultNative::CreateWeakLambda(this, [](const TArray<FRuntimeAudioInputDeviceInfo>& AvailableDevices)
{
	// Handle the result
}));

Démarrage et arrêt de la capture

Après avoir obtenu les périphériques disponibles, vous pouvez commencer à capturer les données audio du périphérique d'entrée et l'arrêter lorsque nécessaire.

Blueprint

C++

// Assuming CapturableSoundWave is a UE reference to a UCapturableSoundWave object (or its derived type)

// Start capturing audio data from the input device with the specified device ID (0 in this case)
CapturableSoundWave->StartCapture(0);

// Stop capturing audio data
CapturableSoundWave->StopCapture();

info

DeviceId est l'index du périphérique dans le tableau des périphériques disponibles obtenu à l'étape précédente. Pour utiliser le périphérique d'entrée audio par défaut, passez -1 dans Blueprints ou Audio::DefaultDeviceIndex en C++ (ce qui équivaut à INDEX_NONE), car parfois l'index zéro n'est pas le périphérique par défaut.

Vérification de l'état de capture

Vous pouvez vérifier si la sound wave capture actuellement l'audio :

Blueprint

C++

// Assuming CapturableSoundWave is a reference to a UCapturableSoundWave object
bool bIsCapturing = CapturableSoundWave->IsCapturing();

Fonctionnalités avancées

Activation et désactivation de la capture audio

Vous pouvez choisir de couper ou de rétablir la capture audio pour empêcher l'accumulation de données audio sans interrompre le processus de capture.

Blueprint

C++

// Assuming CapturableSoundWave is a UE reference to a UCapturableSoundWave object (or its derived type)
CapturableSoundWave->ToggleMute(true);

Différences de version du moteur

UE 5.3 et plus récent : Le démarrage et l'arrêt de la capture ne causent plus de saccades, donc ToggleMute a le même effet que StartCapture/StopCapture. Il se peut que vous n'ayez pas besoin d'utiliser ToggleMute du tout pour l'optimisation des performances.

UE 5.2 et antérieur : Le démarrage de la capture via StartCapture peut causer de légères saccades. Dans ces versions, il est recommandé d'utiliser ToggleMute pour activer et désactiver fréquemment la capture. Vous devez d'abord démarrer la capture elle-même pendant un moment moins critique (comme un écran de chargement), puis utiliser mute/unmute pour contrôler quand les données audio sont réellement accumulées.

Optimisation des performances pour les versions antérieures du moteur

Si vous utilisez UE 5.2 ou antérieur et que vous souhaitez éliminer les légers gels, envisagez de démarrer la capture pendant un moment où ce gel pourrait être négligeable. Par exemple, vous pourriez démarrer la capture pendant l'écran de chargement de votre jeu, mettre en sourdine la sound wave capturable juste après, puis désactiver la sourdine de la sound wave capturable lorsque nécessaire pour capturer des données audio sans aucune saccade.

Exemple complet

Voici un exemple d'implémentation complet d'utilisation d'une sound wave capturable :

Blueprint

C++

Ceci est un exemple de code basique pour capturer des données audio à partir d'un périphérique d'entrée (microphone) en utilisant une sound wave capturable.

L'exemple utilise la fonction CaptureAudioExample située dans la classe UCaptureAudioClassExample 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 "CaptureAudioClassExample.generated.h"

UCLASS(BlueprintType)
class EXAMPLEMODULE_API UCaptureAudioClassExample : public UObject
{
	GENERATED_BODY()

public:
	UFUNCTION(BlueprintCallable)
	void CaptureAudioExample();

private:
	// Please pay attention to making the StreamingSoundWave a hard reference, such as using UPROPERTY(), to prevent it from being prematurely garbage collected
	UPROPERTY()
	class UCapturableSoundWave* CapturableSoundWave;
};

Source file (.cpp)

#include "CaptureAudioClassExample.h"
#include "Sound/StreamingSoundWave.h"
#include "AudioCaptureDeviceInterface.h"

void UCaptureAudioClassExample::CaptureAudioExample()
{
	// Create a capturable sound wave
	CapturableSoundWave = UCapturableSoundWave::CreateCapturableSoundWave();

	// Capture audio data from the default input device
	CapturableSoundWave->StartCapture(Audio::DefaultDeviceIndex);

	// Delay for 5 seconds, just for demonstration purposes
	FTimerHandle TimerHandle;
	GetWorld()->GetTimerManager().SetTimer(TimerHandle, [this]()
	{
		// Stop capturing audio data
		CapturableSoundWave->StopCapture();

		// Play the sound wave
		UGameplayStatics::PlaySound2D(GetWorld(), CapturableSoundWave);
	}, 5, false);
}