GenAI Speech Recognition API

در میانای برنامه‌سازی کاربردی تشخیص گفتار هوش مصنوعی زایا در ML Kit، می‌توانید محتوای صوتی را به نوشتار آوانویسی کنید. این میانای برنامه‌سازی کاربردی از حالت‌های زیر پشتیبانی می‌کند:

  • پیشرفته: Speech Recognition API از مدل GenAI استفاده می‌کند که پوشش زبانی گسترده‌تر و کیفیت کلی بهتری ارائه می‌دهد. لازم نیست برای هر زبان بسته زبان جداگانه‌ای بارگیری کنید، که این امر باعث صرفه‌جویی در فضای ذخیره‌سازی می‌شود.
  • پایه: Speech Recognition API از مدل سنتی تشخیص گفتار در دستگاه استفاده می‌کند، مشابه SpeechRecognizer API.

Speech Recognition API محتوای صوتی را به نوشتار به همان زبان ترانویسی می‌کند. برای ترانویسی صدا به نوشتار به زبانی دیگر، از Speech Translation API استفاده کنید.

قابلیت‌های کلیدی

  • ورودی جاری‌سازی را از میکروفون یا فایل صوتی ضبط می‌کند.
  • کل فایل ازپیش ضبط‌شده را با روش‌های AudioSource.fromFile() یا AudioSource.fromUri() ترانویسی می‌کند. برای جزئیات، الزامات ورودی صوتی را ببینید.
  • برای ورودی‌های جاری‌سازی، زمان شروع دقیق هر کلمه تشخیص‌داده‌شده را ارائه می‌دهد تا به شما در همگام‌سازی پویانمایی‌های واسط کاربر، تولید زیرنویس ناشنوایان، یا برجسته کردن کلمات هنگام بیان شدن کمک کند. زمان شروع (به میلی‌ثانیه) هر کلمه تشخیص‌داده‌شده انحرافی از شروع رویداد است که مُهر زمان ۰ است.
  • نوشتار ترانویسی‌شده به‌صورت جریانی پیوسته ارائه می‌شود که ممکن است در ابتدا ناقص باشد (و تغییر کند) تا اینکه درنهایت به نوشتار تشخیص‌داده‌شده نهایی تبدیل شود.

نتایج نمونه

صوتی حالت منطقه زبانی ترانویسی
audio_2 پیشرفته es-ES "Este es un mensaje corto."
audio_1 اولیه en-US «این یک پیام کوتاه است»

مقایسه با Speech Recognition API پلاتفرم

‫ML Kit Speech Recognition API عملکرد اصلی پلاتفرم SpeechRecognizer API را هنگام استفاده از حالت «پایه» پوشش می‌دهد. مزیت کلیدی ML Kit این است که به نسخه پلاتفرم خاصی محدود نیست.

همچنین، ML Kit Speech Recognition API از تشخیص گفتار بااستفاده از مدل Gemini درون‌دستگاهی هنگام استفاده از حالت «پیشرفته» پشتیبانی می‌کند و پوشش زبانی گسترده‌ای ارائه می‌دهد.

شروع کنید

‫ML Kit Speech Recognition API را به‌عنوان وابستگی در پیکربندی build.gradle اضافه کنید:

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

برای ادغام کردن Speech Recognition API در برنامه‌تان، یک SpeechRecognizer کارخواه ایجاد کنید. وضعیت ویژگی‌های مدل درون‌دستگاهی لازم را بررسی کنید و اگر مدل ازقبل در دستگاه وجود ندارد، آن را بارگیری کنید. پس‌از آماده‌سازی ورودی صوتی در SpeechRecognizerRequest، استنتاج را بااستفاده از کارخواه اجرا کنید تا خروجی جاری‌سازی را از جریان Kotlin دریافت کنید. درنهایت، فراموش نکنید که کارخواه را ببندید تا منابع آزاد شوند.

// 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‏ ۱۶ بیتی خام بدون سرصفحه.
  • کانال‌ها: مونو (تک کانال).
  • نرخ نمونه‌برداری: ۱۶ کیلوهرتز.

برای اکثر موارد استفاده، AudioSource.fromMic() توصیه می‌شود زیرا این محدودیت‌ها را به‌طور خودکار مدیریت می‌کند.

قالب‌های ورودی صوتی پشتیبانی‌شده

‫Speech Recognition API از قالب‌های ورودی صوتی زیر پشتیبانی می‌کند:

  • فایل‌های MP3،‏ WAV،‏ FLAC،‏ M4A، و OGG به‌طور خودکار در دستگاه رمزگشایی می‌شوند.
  • صدای خام بدون سرصفحه (.raw یا .pcm) باید در قالب PCM‏ ۱۶ بیتی، ۱۶ کیلوهرتز، تک‌کاناله باشد.

اگر قالب نامعتبر باشد یا پشتیبانی نشود، هنگام شروع تشخیص، مقدار ErrorResponse برگردانده می‌شود.

پیاده‌سازی Speech Recognition API

در اینجا نحوه استفاده از Speech Recognition API برای ترانویسی صدا و استفاده از زمان‌بندی کلمه آورده شده است.

آوانویسی کردن صدا

Speech Recognition API از ورودی صوتی از میکروفون دستگاه، فایل‌های ازپیش ضبط‌شده، یا خطوط لوله سفارشی بااستفاده از شیء ParcelFileDescriptor پشتیبانی می‌کند.

برای آماده کردن داده‌های صوتی، بااستفاده از یکی از روش‌های کارخانه‌ای فهرست‌شده در جدول زیر، شیء AudioSource بسازید:

روش حالت صوتی مورد استفاده توصیه‌شده
AudioSource.fromMic() STREAMING ورودی گفتاری زنده را از کاربر ضبط کنید.

به اجازه RECORD_AUDIO نیاز دارد.
AudioSource.fromFile(file)

AudioSource.fromUri(context, uri) 		ONE_SHOT فایل‌های صوتی ازپیش ضبط‌شده را ترانویسی کنید. قالب‌های فایل استاندارد را به‌طور خودکار مستقیماً در دستگاه رمزگشایی می‌کند.
AudioSource.fromPfd(pfd, mode)

AudioSource.fromPfd(pfd, mode, audioFormat) 		‫STREAMING یا ONE_SHOT خطوط لوله صوتی سفارشی (مانند داده‌های صوتی پردازش‌شده در جای دیگری از برنامه شما).

ثابت AudioSource.Mode نحوه پردازش صدای ورودی توسط API را کنترل می‌کند:

  • ثابت AudioSource.Mode.STREAMING تشخیص‌دهنده را پیکربندی می‌کند تا نتایج آوانویسی نهایی و جزئی را به‌طور مداوم با رسیدن داده‌های صوتی برگرداند. وقتی شیء ParcelFileDescriptor سفارشی ارائه می‌دهید، باید داده‌ها را با سرعت هم‌زمان در جاری‌سازی بنویسید (تقریباً ۳۲٬۰۰۰ بایت در ثانیه برای صدای PCM تک‌کاناله ۱۶ بیتی ۱۶ کیلوهرتز استاندارد). نوشتن داده‌ها با سرعت زیاد می‌تواند باعث سرریز شدن میان‌گیر شود.
  • ثابت 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
            }
        }
    }
}

زبان‌های پشتیبانی‌شده

حالت مکان‌ها
پیشرفته ar-SA (بتا)، cmn-Hans-CN،‏ cmn-Hant-TW،‏ da-DK (بتا)، de-DE،‏ en-US،‏ es-ES،‏ fr-FR،‏ hi-IN (بتا)، id-ID (بتا)، it-IT،‏ ja-JP،‏ ko-KR،‏ nl-NL (بتا)، pl-PL (بتا)، pt-PT،‏ ru-RU،‏ sv-SE (بتا)، th-TH،‏ tr-TR (بتا)، vi-VN (بتا)
اولیه cmn-Hans-CN (beta), cmn-Hant-TW (beta), de-DE (beta), en-US, es-ES (beta), fr-FR (beta), hi-IN (beta), it-IT (beta), ja-JP (beta), ko-KR (beta), pl-PL (beta), pt-BR (beta), ru-RU (beta), tr-TR (beta), vi-VN (beta)

دستگاه‌های پشتیبانی‌شده

حالت دستگاه‌های پشتیبانی‌شده
اولیه دستگاه‌های Android که از سطح میانای برنامه‌سازی کاربردی ۳۱ و بالاتر استفاده می‌کنند.
پیشرفته

سری Pixel 10 و Pixel 11، به‌علاوه دستگاه‌های دارای Gemini Nano در مجموعه تراشه‌های زیر (ازجمله سری Samsung Galaxy S26،‏ Z Flip8، و Z Fold8، و غیره):

  • Qualcomm Snapdragon: SM8750, SM8845, SM8850, SM8950, SM8975
  • MediaTek Dimensity: MT6991, MT6993, MT6995
  • Samsung Exynos: Exynos 2600

مشکلات رایج راه‌اندازی

میاناهای برنامه‌سازی کاربردی ML Kit GenAI برای دسترسی به Gemini Nano به برنامه Android AICore متکی هستند. وقتی دستگاه به‌تازگی راه‌اندازی شده است (ازجمله بازنشانی)، یا برنامه AICore به‌تازگی بازنشانی شده است (برای مثال، پاک کردن داده‌ها، حذف نصب و سپس نصب مجدد)، ممکن است برنامه AICore زمان کافی برای تکمیل مقداردهی اولیه (ازجمله بارگیری جدیدترین پیکربندی‌ها از سرور) نداشته باشد. درنتیجه، میاناهای برنامه‌سازی کاربردی GenAI در ML Kit ممکن است عملکرد موردانتظار را نداشته باشند. در اینجا پیام‌های خطای رایج راه‌اندازی که ممکن است ببینید و نحوه رسیدگی به آن‌ها آورده شده است:

نمونه پیام خطا نحوه رسیدگی
‫AICore با نوع خطای 4-CONNECTION_ERROR و کد خطای 601-BINDING_FAILURE ناموفق بود: سرویس AICore متصل نشد. این اتفاق ممکن است زمانی رخ دهد که برنامه را بااستفاده از ML Kit GenAI APIs بلافاصله پس‌از راه‌اندازی دستگاه نصب کنید یا زمانی که AICore پس‌از نصب برنامه شما حذف نصب شود. به‌روزرسانی برنامه AICore و سپس بازنصب کردن برنامه شما باید مشکل را برطرف کند.
‫AICore با نوع خطای 3-PREPARATION_ERROR و کد خطای 606-FEATURE_NOT_FOUND ناموفق بود: ویژگی ... دردسترس نیست. این اتفاق زمانی می‌افتد که AICore بارگیری جدیدترین پیکربندی‌ها را تکمیل نکرده باشد. وقتی دستگاه به اینترنت متصل باشد، معمولاً چند دقیقه تا چند ساعت طول می‌کشد تا به‌روز شود. بازراه‌اندازی دستگاه می‌تواند به‌روزرسانی را تسریع کند.

توجه داشته باشید که اگر قفل bootloader دستگاه باز باشد، این خطا را نیز خواهید دید—این API از دستگاه‌هایی که قفل bootloader آن‌ها باز است پشتیبانی نمی‌کند.
‫AICore با نوع خطای 1-DOWNLOAD_ERROR و کد خطای 0-UNKNOWN ناموفق بود: ویژگی ... با وضعیت ناموفق 0 و خطای esz: UNAVAILABLE: Unable to resolve host ... ناموفق بود اتصال شبکه را حفظ کنید، چند دقیقه صبر کنید و دوباره امتحان کنید.

کدگذاری نمونه

  • نمونه کد ML Kit Speech Recognition API را در GitHub کاوش کنید