GenAI Speech Recognition API

البدء

أضِف واجهة Speech Recognition API في حزمة تعلّم الآلة كعنصر تابع في إعدادات build.gradle:

implementation("com.google.mlkit:genai-speech-recognition:1.0.0-alpha1")

لدمج واجهة برمجة التطبيقات Speech Recognition API في تطبيقك، أنشئ عميل SpeechRecognizer. التحقّق من حالة ميزات النموذج اللازمة على الجهاز وتنزيل النموذج إذا لم يكن متوفّرًا على الجهاز بعد إعداد الإدخال الصوتي في SpeechRecognizerRequest، يمكنك تشغيل الاستنتاج باستخدام العميل لتلقّي مخرجات البث من Kotlin flow. أخيرًا، تذكَّر إغلاق العميل لإخلاء الموارد.

// 1. Create a SpeechRecognizer with desired options.
val options: SpeechRecognizerOptions =
    speechRecognizerOptions {
        locale = Locale.US
        preferredMode = SpeechRecognizerOptions.Mode.MODE_ADVANCED
    }
val speechRecognizer: SpeechRecognizer = SpeechRecognition.getClient(options)

// 2. Check if the recognition model is available or needs downloading.
launch {
    val status: Int = speechRecognizer.checkStatus()
    if (status == FeatureStatus.DOWNLOADABLE) {
        // 3. If needed, download the model and monitor progress.
        speechRecognizer.download.collect { downloadStatus ->
            when (downloadStatus) {
                is DownloadStatus.DownloadCompleted -> {
                    // Model is ready, start recognition.
                    startMyRecognition(speechRecognizer)
                }
                is DownloadStatus.DownloadFailed -> {
                    // Handle download failure (e.g., inform the user).
                }
                is DownloadStatus.DownloadProgress -> {
                    // Handle download progress (e.g., update a progress bar).
                }
            }
        }
    } else if (status == FeatureStatus.AVAILABLE) {
        // Model is already ready, start recognition immediately.
        startMyRecognition(speechRecognizer)
    } else {
        // Handle other statuses (e.g., DOWNLOADING, UNAVAILABLE).
    }
}

// 4. Define your recognition logic using a suspend function.
suspend fun startMyRecognition(recognizer: SpeechRecognizer) {
    // Create a request (e.g., specifying audio source).
    val request: SpeechRecognizerRequest
        = speechRecognizerRequest { audioSource = AudioSource.fromMic() }
    // Start recognition and process the continuous stream of responses.
    recognizer.startRecognition(request).collect {
        // Process the SpeechRecognitionResponse data here.
    }
}

// 5. Stop recognition and clean up resources when the session is complete.
launch {
    recognizer.stopRecognition()
    recognizer.close()
}

متطلبات إدخال الصوت

تتيح واجهة GenAI Speech Recognition API إدخال الصوت من الميكروفون أو من مصدر مخصّص عبر واصِف الملف.

إذا كنت تستخدم AudioSource.fromPfd(parcelFileDescriptor)، يجب أن يستوفي الصوت المُدخَل المتطلبات الصارمة التالية:

• التنسيق: ملف PCM خام بدون عنوان بمعدّل 16 بت.
• القنوات: أحادي (قناة واحدة)
• معدّل البيانات في الملف الصوتي: 16 كيلوهرتز

في معظم حالات الاستخدام، ننصح باستخدام AudioSource.fromMic() لأنّه يتعامل مع هذه القيود تلقائيًا.

تنسيقات الإدخال الصوتي المتوافقة

تتيح واجهة Speech Recognition API استخدام تنسيقات الإدخال الصوتي التالية:

• يتم تلقائيًا فك ترميز ملفات MP3 وWAV وFLAC وM4A وOGG على الجهاز.
• يجب أن يكون الصوت الأولي بدون عنوان (.raw أو .pcm) بتنسيق PCM‏ 16 بت و16 كيلوهرتز وأحادي.

إذا كان التنسيق غير صالح أو غير متوافق، يتم عرض قيمة ErrorResponse عند بدء التعرّف على الصوت.

تنفيذ واجهة برمجة التطبيقات Speech Recognition API

في ما يلي كيفية استخدام واجهة Speech Recognition API لتحويل الصوت إلى نص واستخدام توقيت الكلمات.

تحويل الصوت إلى نص

تتيح واجهة Speech Recognition API إدخال الصوت من ميكروفون الجهاز أو الملفات المسجّلة مسبقًا أو المسارات المخصّصة باستخدام عنصر ParcelFileDescriptor.

لإعداد بياناتك الصوتية، أنشئ كائن AudioSource باستخدام إحدى طرق المصنع المدرَجة في الجدول التالي:

يتحكّم الثابت AudioSource.Mode في كيفية معالجة واجهة برمجة التطبيقات للصوت الوارد:

• يضبط الثابت AudioSource.Mode.STREAMING أداة التعرّف على الكلام لعرض نتائج تحويل الصوت إلى نص جزئية ونهائية بشكل مستمر عند وصول البيانات الصوتية. عند تقديم عنصر ParcelFileDescriptor مخصّص، يجب كتابة البيانات في البث في الوقت الفعلي (حوالي 32,000 بايت في الثانية للصوت العادي بتنسيق PCM أحادي القناة بتردد 16 كيلوهرتز و16 بت). يمكن أن تؤدي كتابة البيانات بسرعة كبيرة إلى تجاوز سعة المخزن المؤقت.
• يضبط الثابت AudioSource.Mode.ONE_SHOT أداة التعرّف على الكلام للانتظار حتى يتم نقل مصدر الصوت بالكامل قبل إجراء الاستنتاج وتقديم النص النهائي. يمكنك كتابة البيانات الصوتية بأسرع ما يمكن، ولكن يجب إغلاق نهاية الكتابة لواصف الملف للإشارة إلى نهاية الملف. ولا يتم تسليم نتيجة تحويل الصوت إلى نص النهائية إلا بعد تلقّي إشارة نهاية الملف هذه.

يحوّل المثال التالي ملفًا صوتيًا مسجَّلاً مسبقًا إلى نص:

suspend fun recognizeFromFile(recognizer: SpeechRecognizer, audioFile: File) {
    val audioSource = AudioSource.fromFile(audioFile)
    val request = speechRecognizerRequest { this.audioSource = audioSource }
    try {
        recognizer.startRecognition(request).collect { response ->
            when (response) {
                is SpeechRecognizerResponse.FinalTextResponse -> {
                    // Process the transcription of the whole file.
                }
                is SpeechRecognizerResponse.ErrorResponse -> {
                    // Handle the error, for example an unsupported audio format.
                }
                else -> {}
            }
        }
    } finally {
        audioSource.close()
    }
}

استخدام توقيت الكلمات

يمكنك طلب وقت البدء لكل كلمة يتم التعرّف عليها من خلال ضبط المَعلمة enableWordTiming على true في مجموعة إعدادات recognitionOptions لطلبك.

عند تفعيل ميزة توقيت الكلمات، يتضمّن كل عنصر SpeechRecognizerResponse.FinalTextResponse السمة wordTimings التي تحتوي على قائمة بعناصر SpeechRecognizerResponse.WordTiming. يوفّر كل عنصر سلسلة الكلمات التي تم التعرّف عليها (text) والإزاحة بالملي ثانية (timestampMs) بدءًا من بداية جلسة التعرّف على الكلام. عند إيقاف توقيت الكلمات (الإعداد التلقائي)، يتم عرض قائمة wordTimings فارغة.

يوضّح مثال الرمز البرمجي التالي كيفية ضبط توقيت الكلمات وتفعيله:

suspend fun recognizeWithWordTiming(recognizer: SpeechRecognizer) {
    val request = speechRecognizerRequest {
        audioSource = AudioSource.fromMic()
        recognitionOptions { enableWordTiming = true }
    }
    recognizer.startRecognition(request).collect { response ->
        if (response is SpeechRecognizerResponse.FinalTextResponse) {
            for (wordTiming in response.wordTimings) {
                val word: String = wordTiming.text
                val timestamp: Long = wordTiming.timestampMs
            }
        }
    }
}

اللغات المتاحة

الأجهزة المعتمدة

المشاكل الشائعة في الإعداد

تعتمد واجهات برمجة التطبيقات للذكاء الاصطناعي التوليدي في "حزمة تعلّم الآلة" على تطبيق Android AICore للوصول إلى Gemini Nano. عند إعداد جهاز للتو (بما في ذلك إعادة الضبط)، أو إعادة ضبط تطبيق AICore للتو (مثل محو البيانات وإلغاء التثبيت ثم إعادة التثبيت)، قد لا يتوفّر لتطبيق AICore الوقت الكافي لإنهاء عملية الإعداد (بما في ذلك تنزيل أحدث الإعدادات من الخادم). نتيجةً لذلك، قد لا تعمل واجهات برمجة التطبيقات GenAI في حزمة تعلّم الآلة على النحو المتوقّع. في ما يلي رسائل الخطأ الشائعة في الإعداد التي قد تظهر لك وكيفية التعامل معها:

نموذج الرموز البرمجية

• استكشِف نموذج الرمز البرمجي لواجهة Speech Recognition API في "حزمة تعلّم الآلة" على GitHub