مؤشر الإدخال الصوتي في Jetpack Compose Glimmer

أجهزة XR المشمولة
تساعدك هذه الإرشادات في إنشاء تجارب لهذه الأنواع من أجهزة XR.
نظارات بشاشة عرض

‫VoiceInputIndicator هو مكوّن Jetpack Compose Glimmer يعرض النشاط الصوتي للمستخدم. يمكنك استخدام هذا المكوّن لقبول الإدخال الصوتي أو أي صوت آخر وتقديم ملاحظات مرئية لإظهار أنّ تطبيقك يلتقط الصوت.

هذا المكوّن هو عنصر مرئي فقط. ولا يسجّل الصوت أو يعالج بيانات الميكروفون من تلقاء نفسه. بدلاً من ذلك، يستجيب التطبيق لملف صوتي level يوفّره تطبيقك، والذي يعرض تمثيلاً مرئيًا لشدة الصوت.

الشكل 1. مثال على VoiceInputIndicator.

طلب الأذونات المُسقَطة

لتسجيل البيانات الصوتية من أجل تشغيل المؤشر، يحتاج تطبيقك إلى إذن Manifest.permission.RECORD_AUDIO.

عند إنشاء تجارب الواقع المعزّز للنظارات بشاشة عرض، تأكَّد من طلب الأذونات بشكل صحيح على كل من الجهاز والنظارات. استخدِم ProjectedActivityCompat.requestPermissions لطلب الإجراء من المستخدم.

لمزيد من المعلومات حول طلب الأذونات في البيئات المعروضة، يُرجى الاطّلاع على طلب أذونات الأجهزة.

تسجيل الصوت وتعديله

يتطلّب VoiceInputIndicator استخدام Float بين 0.0f و1.0f ليعكس مستوى الصوت بشكل مرئي. بما أنّ المؤشر يعمل فقط كمكوّن مرئي ولا يسجّل الصوت، يجب أن يراقب تطبيقك الميكروفون باستمرار وينقل مستوى الصوت إلى المَعلمة level الخاصة بالمؤشر.

هناك طرق متعددة لتسجيل البيانات الصوتية، ومن بينها استخدام واجهة برمجة التطبيقات SpeechRecognizer. عند استخدام SpeechRecognizer، يمكنك الحصول على تعديلات في الوقت الفعلي لمستوى الصوت باستخدام دالة الاستدعاء RecognitionListener.onRmsChanged التي توفّر مستوى الصوت بالديسيبل، rmsdB.

بما أنّ هذه القيمة الأولية تقع عادةً بين 0 و10، يجب تسوية الناتج إلى النطاق المطلوب من 0.0f إلى 1.0f. يمكنك الاحتفاظ بهذا المستوى الذي تم تسويته في متغيّر حالة لتحديث المؤشر باستمرار.

في ما يلي مثال على استخدام RecognitionListener لتعديل متغيّر الحالة:

// Example state variable to hold the normalized level (0.0 to 1.0)
// that the VoiceInputIndicator component expects.
val audioLevel = MutableStateFlow(0f)

// Initialize the Android SpeechRecognizer
val speechRecognizer = SpeechRecognizer.createSpeechRecognizer(context)

// Listener to capture speech events and audio level changes
val listener = object : RecognitionListener {
    override fun onRmsChanged(rmsdB: Float) {
        // Normalize raw dB level to a 0.0-1.0 range.
        // Android SpeechRecognizer's rmsdB typically ranges from 0 to ~10.
        audioLevel.value = ((rmsdB - 1f) / 9f).coerceIn(0f, 1f)
    }

    // ... Implement other required RecognitionListener methods ...
    override fun onReadyForSpeech(params: Bundle?) {}
    override fun onBeginningOfSpeech() {}
    override fun onEndOfSpeech() {}
    override fun onError(error: Int) {}
    override fun onResults(results: Bundle?) {}
    override fun onPartialResults(partialResults: Bundle?) {}
    override fun onEvent(eventType: Int, params: Bundle?) {}
    override fun onBufferReceived(buffer: ByteArray?) {}
}

// Attach the listener to the recognizer
speechRecognizer.setRecognitionListener(listener)

// Create an intent to specify the recognition model and behavior
val intent = Intent(RecognizerIntent.ACTION_RECOGNIZE_SPEECH).apply {
    putExtra(RecognizerIntent.EXTRA_LANGUAGE_MODEL, RecognizerIntent.LANGUAGE_MODEL_FREE_FORM)
}
// Begin listening for audio input
speechRecognizer.startListening(intent)

دمج مؤشر الإدخال الصوتي

بعد تسوية البث الصوتي بشكل صحيح وعرضه كحالة، يمكنك تمريره مباشرةً إلى VoiceInputIndicator.

@Composable
fun VoiceInputExample(modifier: Modifier) {
    // Collect the flow as Compose State so the UI reacts to changes in real-time.
    val currentLevel by audioLevel.collectAsState()

    VoiceInputIndicator(
        // The VoiceInputIndicator component provides a visual "pulse" or indicator
        // that changes based on the 'level' lambda, which returns a Float between 0.0 and 1.0.
        level = { currentLevel },
        modifier = modifier
    )
}

مَعلمات التخصيص

توفّر VoiceInputIndicator بعض المَعلمات لتخصيص سلوكها ومظهرها:

  • ‫level: دالة تعرض Float يمثّل مستوى الإدخال الصوتي، ويتراوح من 0.0 للصمت إلى 1.0 لأعلى صوت.
  • ‫indicatorColor: لون أشرطة المؤشر يستخدم هذا الإعداد تلقائيًا اللون الأساسي من مظهر Glimmer. يمكنك الاطّلاع على GlimmerTheme.colors.primary.
  • modifier: يمثّل هذا الحقل عنصر Compose العادي modifier الذي سيتم تطبيقه على المؤشر.

إذا كانت واجهة المستخدم تتطلّب وضع المؤشر داخل حاوية خلفية مرئية، استخدِم ContainedVoiceInputIndicator. يضمن هذا البديل أن تكون أشرطة المؤشر شفافة، مما يسمح بظهور حاوية الخلفية من خلالها.