GenAI Speech Recognition API

API ini ditawarkan dalam versi alfa, dan tidak tunduk pada kebijakan penghentian layanan atau SLA apa pun. Perubahan mungkin dilakukan pada API ini yang dapat merusak kompatibilitas mundur.

Dalam API Pengenalan Ucapan GenAI ML Kit, Anda dapat mentranskripsikan konten audio menjadi teks. API ini mendukung mode berikut:

• Advanced: Speech Recognition API menggunakan model GenAI, yang menghasilkan cakupan bahasa yang lebih luas dan kualitas keseluruhan yang lebih baik. Anda tidak perlu mendownload paket bahasa terpisah untuk setiap bahasa, sehingga menghemat penyimpanan.
• Dasar: Speech Recognition API menggunakan model pengenalan ucapan tradisional di perangkat, mirip dengan SpeechRecognizer API.

Speech Recognition API mentranskripsikan konten audio menjadi teks dalam bahasa yang sama. Untuk mentranskripsikan audio ke teks dalam bahasa lain, gunakan Speech Translation API.

Kemampuan utama

• Merekam input streaming dari mikrofon atau file audio.
• Mentranskripsikan seluruh file yang telah direkam sebelumnya dengan metode AudioSource.fromFile() atau AudioSource.fromUri(). Untuk mengetahui detailnya, lihat Persyaratan input audio.
• Untuk input streaming, memberikan waktu mulai yang tepat dari setiap kata yang dikenali untuk membantu Anda menyinkronkan animasi UI, membuat teks, atau menandai kata saat diucapkan. Waktu mulai (dalam milidetik) setiap kata yang dikenali adalah offset dari awal peristiwa, yaitu stempel waktu 0.
• Teks yang ditranskripsikan disediakan sebagai streaming berkelanjutan, yang awalnya mungkin bersifat parsial (dan dapat berubah) sebelum menjadi teks akhir yang dikenali.

Hasil contoh

Audio	Mode	Lokal	Transkripsi
audio_2	Lanjutan	es-ES	"Este es un mensaje corto."
audio_1	Dasar	en-US	"Ini adalah pesan singkat"

Perbandingan dengan Speech Recognition API platform

ML Kit Speech Recognition API mencakup fungsi dasar API SpeechRecognizer platform saat menggunakan mode Basic. Keunggulan utama ML Kit adalah tidak terikat dengan versi platform tertentu.

Selain itu, Speech Recognition API ML Kit mendukung pengenalan ucapan menggunakan model Gemini di perangkat saat menggunakan mode Lanjutan, sehingga memberikan cakupan bahasa yang lebih luas.

Catatan: Mode lanjutan tersedia di perangkat tertentu. Lihat Perangkat yang didukung untuk mengetahui detailnya.

Mulai

Catatan: SDK memerlukan minSdkVersion 26 atau yang lebih tinggi. Lihat Perangkat yang didukung untuk mengetahui persyaratan runtime untuk setiap mode.

Tambahkan Speech Recognition API ML Kit sebagai dependensi dalam konfigurasi build.gradle Anda:

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

Untuk mengintegrasikan Speech Recognition API ke dalam aplikasi Anda, buat klien SpeechRecognizer. Periksa status fitur model di perangkat yang diperlukan dan download model jika belum ada di perangkat. Setelah menyiapkan input audio dalam SpeechRecognizerRequest, jalankan inferensi menggunakan klien untuk menerima output streaming dari Kotlin flow. Terakhir, ingatlah untuk menutup klien guna melepaskan resource.

// 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()
}

Persyaratan input audio

GenAI Speech Recognition API mendukung input dari mikrofon atau sumber kustom melalui deskriptor file.

Jika Anda menggunakan AudioSource.fromPfd(parcelFileDescriptor), audio input harus memenuhi persyaratan ketat berikut:

• Format: PCM 16-bit mentah tanpa header.
• Saluran: Mono (saluran tunggal).
• Frekuensi Sampel: 16 kHz.

Untuk sebagian besar kasus penggunaan, AudioSource.fromMic() direkomendasikan karena menangani batasan ini secara otomatis.

Format input audio yang didukung

Speech Recognition API mendukung format input audio berikut:

• File MP3, WAV, FLAC, M4A, dan OGG didekode secara otomatis di perangkat.
• Audio mentah tanpa header (.raw atau .pcm) harus dalam format PCM 16-bit, 16 kHz, mono.

Jika format tidak valid atau tidak didukung, nilai ErrorResponse akan ditampilkan saat pengenalan dimulai.

Mengimplementasikan Speech Recognition API

Berikut cara menggunakan Speech Recognition API untuk mentranskripsikan audio dan menggunakan pengaturan waktu kata.

Mentranskripsikan audio

Speech Recognition API mendukung input audio dari mikrofon perangkat, file yang direkam sebelumnya, atau pipeline kustom menggunakan objek ParcelFileDescriptor.

Untuk menyiapkan data audio, buat objek AudioSource menggunakan salah satu metode factory yang tercantum dalam tabel berikut:

Metode	Mode audio	Kasus penggunaan yang direkomendasikan
AudioSource.fromMic()	STREAMING	Merekam input suara langsung dari pengguna. Memerlukan izin RECORD_AUDIO.
AudioSource.fromFile(file) AudioSource.fromUri(context, uri)	ONE_SHOT	Mentranskripsikan file audio yang telah direkam sebelumnya. Otomatis mendekode format file standar langsung di perangkat.
AudioSource.fromPfd(pfd, mode) AudioSource.fromPfd(pfd, mode, audioFormat)	STREAMING atau ONE_SHOT	Pipeline audio kustom (seperti data audio yang diproses di tempat lain dalam aplikasi Anda).

Konstanta AudioSource.Mode mengontrol cara API memproses audio yang masuk:

• Konstanta AudioSource.Mode.STREAMING mengonfigurasi pengenal untuk menampilkan hasil transkripsi parsial dan final secara terus-menerus saat data audio masuk. Saat menyediakan objek ParcelFileDescriptor kustom, Anda harus menulis data ke aliran data secara real-time (sekitar 32.000 byte per detik untuk audio PCM mono 16 kHz, 16-bit standar). Menulis data terlalu cepat dapat menyebabkan buffer penuh.
• Konstanta AudioSource.Mode.ONE_SHOT mengonfigurasi pengenal untuk menunggu seluruh sumber audio ditransfer sebelum melakukan inferensi dan memberikan transkripsi akhir. Anda dapat menulis data audio secepat mungkin, tetapi Anda harus menutup ujung tulis deskriptor file untuk menandakan akhir file. Hasil transkripsi akhir tidak akan dikirimkan hingga sinyal akhir file ini diterima.

Catatan: Objek AudioSource mengambil kepemilikan objek ParcelFileDescriptor yang mendasarinya. Ingatlah untuk memanggil metode AudioSource.close() setelah pengenalan selesai.

Contoh berikut mentranskripsikan file audio yang telah direkam sebelumnya:

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()
    }
}

Menggunakan pengaturan waktu kata

Anda dapat meminta waktu mulai setiap kata yang dikenali dengan menetapkan parameter enableWordTiming ke true di blok konfigurasi recognitionOptions permintaan Anda.

Jika pengaturan waktu kata diaktifkan, setiap objek SpeechRecognizerResponse.FinalTextResponse akan menyertakan properti wordTimings yang berisi daftar objek SpeechRecognizerResponse.WordTiming. Setiap objek menyediakan string kata yang dikenali (text) dan offset milidetiknya (timestampMs) mulai dari awal sesi pengenalan ucapan. Jika pengaturan waktu kata dinonaktifkan (setelan default), daftar wordTimings akan ditampilkan kosong.

Contoh kode berikut menunjukkan cara mengonfigurasi dan mengaktifkan pengaturan waktu kata:

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
            }
        }
    }
}

Catatan: Fitur pengaturan waktu kata hanya didukung saat menggunakan sumber audio streaming, seperti input live dari metode AudioSource.fromMic() atau pipeline streaming kustom dari metode AudioSource.fromPfd() dengan konstanta AudioSource.Mode.STREAMING. Memanggil metode startRecognition() dengan pengaturan waktu kata diaktifkan pada sumber audio ONE_SHOT statis, seperti yang ditampilkan oleh metode AudioSource.fromFile() atau AudioSource.fromUri(), akan menampilkan objek IllegalArgumentException.

Bahasa yang didukung

Mode	Locales
Lanjutan	ar-SA (beta), cmn-Hans-CN, cmn-Hant-TW, da-DK (beta), de-DE, en-US, es-ES, fr-FR, hi-IN (beta), id-ID (beta), it-IT, ja-JP, ko-KR, nl-NL (beta), pl-PL (beta), pt-PT, ru-RU, sv-SE (beta), th-TH, tr-TR (beta), vi-VN (beta)
Dasar	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)

Catatan: Bahasa dalam versi Beta mungkin memiliki tingkat kesalahan kata yang sedikit lebih tinggi. Lokalitas tambahan tersedia. Evaluasi performanya berdasarkan kasus penggunaan spesifik Anda.

Perangkat yang didukung

Mode	Perangkat yang Didukung
Dasar	Perangkat Android yang menggunakan level API 31 dan yang lebih tinggi.
Lanjutan	Seri Pixel 10 dan Pixel 11, serta perangkat dengan Gemini Nano pada chipset berikut (termasuk seri Samsung Galaxy S26, Z Flip8, dan Z Fold8, di antaranya): Qualcomm Snapdragon: SM8750, SM8845, SM8850, SM8950, SM8975 MediaTek Dimensity: MT6991, MT6993, MT6995 Samsung Exynos: Exynos 2600

Masalah penyiapan umum

Catatan: API ini tidak didukung di perangkat dengan bootloader yang tidak terkunci.

API GenAI ML Kit mengandalkan aplikasi Android AICore untuk mengakses Gemini Nano. Saat perangkat baru disiapkan (termasuk direset), atau aplikasi AICore baru direset (misalnya, hapus data, di-uninstal, lalu diinstal ulang), aplikasi AICore mungkin tidak memiliki cukup waktu untuk menyelesaikan inisialisasi (termasuk mendownload konfigurasi terbaru dari server). Akibatnya, API GenAI ML Kit mungkin tidak berfungsi seperti yang diharapkan. Berikut adalah pesan error penyiapan umum yang mungkin Anda lihat dan cara menanganinya:

Contoh pesan error	Cara menangani
AICore gagal dengan jenis error 4-CONNECTION_ERROR dan kode error 601-BINDING_FAILURE: Layanan AICore gagal mengikat.	Hal ini dapat terjadi saat Anda menginstal aplikasi menggunakan ML Kit GenAI API segera setelah penyiapan perangkat atau saat AICore di-uninstal setelah aplikasi Anda diinstal. Mengupdate aplikasi AICore, lalu menginstal ulang aplikasi Anda akan memperbaiki masalah ini.
AICore gagal dengan jenis error 3-PREPARATION_ERROR dan kode error 606-FEATURE_NOT_FOUND: Fitur ... tidak tersedia.	Hal ini dapat terjadi jika AICore belum selesai mendownload konfigurasi terbaru. Saat perangkat terhubung ke internet, biasanya perlu waktu beberapa menit hingga beberapa jam untuk mengupdate. Memulai ulang perangkat dapat mempercepat update. Perhatikan bahwa jika bootloader perangkat tidak terkunci, Anda juga akan melihat error ini—API ini tidak mendukung perangkat dengan bootloader yang tidak terkunci.
AICore gagal dengan jenis error 1-DOWNLOAD_ERROR dan kode error 0-UNKNOWN: Fitur ... gagal dengan status kegagalan 0 dan error esz: UNAVAILABLE: Tidak dapat me-resolve host ...	Pertahankan koneksi jaringan, tunggu beberapa menit, lalu coba lagi.

Catatan: Meskipun berbagai reset umum dilakukan oleh developer, hal ini jauh lebih jarang dilakukan oleh pengguna. Selain itu, semua kasus kegagalan penyiapan ini dapat diketahui oleh API checkFeatureStatus() atau checkStatus(). Pastikan untuk memanggil checkFeatureStatus() atau checkStatus() terlebih dahulu sebelum menampilkan UI terkait, sehingga pengguna aplikasi Anda tidak akan melihat error ini dalam kasus apa pun.

Kode contoh

• Pelajari contoh kode Speech Recognition API ML Kit di GitHub