Capturable Sound Wave

概述

可捕获音波派生自流式音波。它支持从麦克风等输入设备捕获音频数据并进行播放，具备与导入音波相同的功能（包括倒带、在SoundCue中使用等）。你甚至可以同时捕获和播放音频，没有任何限制。

提示

关于语音活动检测 (VAD)，请参阅此页面。

备注

在 iOS 和 Android 上，可捕获音波会在开始捕获时自动请求麦克风权限。

基本用法

创建可捕获音波

首先，你应该创建一个可捕获音波。

Blueprint

C++

UCapturableSoundWave* CapturableSoundWave = UCapturableSoundWave::CreateCapturableSoundWave();

注意

您应将可捕获的声波视为强引用，以防止其过早销毁（例如，在蓝图中将其分配给单独的变量，或在 C++ 中使用 UPROPERTY()）。

获取可用的输入设备

要使用此功能，您需要首先获取所有可用于捕获的可用音频输入设备。

Blueprint

C++

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

启动和停止捕获

获取可用设备后，您可以开始从输入设备捕获音频数据，并在需要时停止。

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

信息

DeviceId 是设备在从上一步获取的可用设备数组中的索引。要使用默认音频输入设备，请在 Blueprints 中传递 -1，或在 C++ 中传递 Audio::DefaultDeviceIndex（其值等于 INDEX_NONE），因为有时零索引并非默认设备。

检查捕获状态

您可以检查声音波是否正在捕获音频：

Blueprint

C++

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

高级功能

静音与取消静音捕获

您可以选择静音或取消静音声音捕获，以防止音频数据累积，同时不中断捕获过程。

Blueprint

C++

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

引擎版本差异

UE 5.3 及更新版本： 启动和停止捕获不再导致卡顿，因此 ToggleMute 与 StartCapture/StopCapture 效果相同。出于性能优化考虑，您可能完全不需要使用 ToggleMute。

UE 5.2 及更早版本： 通过 StartCapture 启动捕获可能会导致轻微卡顿。在这些版本中，建议使用 ToggleMute 来频繁切换捕获的开关。您应首先在不太关键的时间（例如加载屏幕期间）启动捕获本身，然后使用静音/取消静音来控制何时实际累积音频数据。

针对早期引擎版本的性能优化

如果您使用的是 UE 5.2 或更早版本，并希望消除轻微的卡顿，可以考虑在卡顿影响可忽略不计的时候启动捕获。例如，您可以在游戏加载屏幕期间启动捕获，随后立即将可捕获音波静音，然后在需要捕获音频数据时取消静音，从而实现无卡顿的音频数据捕获。

完整示例

以下是使用可捕获音波的完整实现示例：

Blueprint

C++

这是一个使用可捕获音波从输入设备（麦克风）捕获音频数据的基本代码示例。

该示例使用了位于 EXAMPLEMODULE 模块内 UCaptureAudioClassExample 类中的 CaptureAudioExample 函数。

备注

要成功运行此示例，请确保将 RuntimeAudioImporter 模块添加到 .Build.cs 文件中的 PublicDependencyModuleNames 或 PrivateDependencyModuleNames，同时也添加到您项目的 .uproject 文件中。

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