Capturable Sound Wave

نظرة عامة

موجة الصوت القابلة للالتقاط مشتقة من موجة الصوت المتدفقة. وهي تدعم التقاط بيانات الصوت من أجهزة الإدخال مثل الميكروفون وتشغيلها، مع نفس القدرات الموجودة في موجة الصوت المستوردة (بما في ذلك إعادة التشغيل، والاستخدام في SoundCues، وما إلى ذلك). يمكنك حتى التقاط الصوت وتشغيله في وقت واحد دون أي قيود.

تلميح

للحصول على كشف نشاط الصوت (VAD)، راجع هذه الصفحة.

ملاحظة

تطلب موجة الصوت القابلة للالتقاط أذونات الميكروفون تلقائيًا على iOS وAndroid بمجرد بدء الالتقاط.

الاستخدام الأساسي

إنشاء موجة صوت قابلة للالتقاط

يجب عليك أولاً إنشاء موجة صوت قابلة للالتقاط.

Blueprint

C++

UCapturableSoundWave* CapturableSoundWave = UCapturableSoundWave::CreateCapturableSoundWave();

warning

يجب أن تعامل موجة الصوت القابلة للتسجيل كمرجع قوي لمنع تدميرها قبل الأوان (على سبيل المثال، عن طريق تعيينها لمتغير منفصل في Blueprints أو استخدام UPROPERTY() في ++C).

الحصول على أجهزة الإدخال المتاحة

لاستخدام هذه الميزة، تحتاج أولاً إلى الحصول على جميع أجهزة إدخال الصوت المتاحة التي يمكن استخدامها للتسجيل.

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 هو فهرس الجهاز في مصفوفة الأجهزة المتاحة التي تم الحصول عليها من الخطوة السابقة. لاستخدام جهاز إدخال الصوت الافتراضي، قم بتمرير -1 في Blueprints أو Audio::DefaultDeviceIndex في C++ (والذي يساوي 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++

هذا مثال أساسي للكود لالتقاط بيانات الصوت من جهاز إدخال (ميكروفون) باستخدام موجة صوت قابلة للالتقاط.

يستخدم المثال الدالة CaptureAudioExample الموجودة في الفئة UCaptureAudioClassExample داخل الوحدة EXAMPLEMODULE.

ملاحظة

لتشغيل المثال بنجاح، تأكد من إضافة وحدة RuntimeAudioImporter إما إلى PublicDependencyModuleNames أو PrivateDependencyModuleNames في ملف .Build.cs، وكذلك إلى ملف .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);
}