موجة صوتية قابلة للالتقاط

نظرة عامة

تُشتق الموجة الصوتية القابلة للالتقاط من الموجة الصوتية المتدفقة. فهي تدعم التقاط بيانات الصوت من أجهزة الإدخال مثل الميكروفون وتشغيلها، مع نفس إمكانيات الموجة الصوتية المستوردة (بما في ذلك إعادة التشغيل، والاستخدام في 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);
}