GenAI Speech Recognition API

這個 API 處於 Alpha 版階段，不受任何服務水準協議或廢止政策規範。這項 API 可能會有所變更，導致回溯相容性中斷。

在 ML Kit 的 GenAI Speech Recognition API 中，您可以將音訊內容轉錄為文字。這個 API 支援下列模式：

• 進階：Speech Recognition API 使用生成式 AI 模型，可支援更多語言，整體品質也更佳。您不必為每種語言下載個別語言套件，因此可節省儲存空間。
• 基本：Speech Recognition API 使用傳統的裝置端語音辨識模型，類似於 SpeechRecognizer API。

Speech Recognition API 會將音訊內容轉錄為相同語言的文字。如要將音訊轉錄為其他語言的文字，請使用 Speech Translation API。

主要功能

• 擷取麥克風或音訊檔案的串流輸入內容。
• 使用 AudioSource.fromFile() 或 AudioSource.fromUri() 方法轉錄整個預錄檔案。詳情請參閱「音訊輸入需求」。
• 如果是串流輸入，系統會提供每個辨識字詞的確切開始時間，協助您同步處理 UI 動畫、生成字幕，或在說出字詞時醒目顯示。每個辨識出的字詞開始時間 (以毫秒為單位) 是從事件開始時間 (時間戳記 0) 算起的偏移量。
• 轉錄文字會以連續串流的形式提供，一開始可能只是部分內容 (且可能變更)，之後才會成為最終辨識文字。

搜尋結果範例

音訊	模式	語言代碼	語音轉錄
audio_2	進階	es-ES	"Este es un mensaje corto."
audio_1	基本	en-US	「這是一則簡短訊息」

與平台 Speech Recognition API 比較

使用基本模式時，ML Kit 語音辨識 API 涵蓋平台 SpeechRecognizer API 的基本功能。ML Kit 的主要優點是不受特定平台版本限制。

此外，在進階模式下，ML Kit Speech Recognition API 支援使用裝置端 Gemini 模型進行語音辨識，提供更廣泛的語言支援。

注意： 進階模式僅適用於特定裝置。詳情請參閱「支援的裝置」。

開始使用

注意： SDK 需要 minSdkVersion 26 以上版本。如要瞭解各模式的執行階段需求，請參閱「支援的裝置」一節。

在 build.gradle 設定中，將 ML Kit 語音辨識 API 新增為依附元件：

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)，輸入音訊必須符合下列嚴格規定：

• 格式：原始、無標頭的 16 位元 PCM。
• 聲道：單聲道 (單一聲道)。
• 取樣率：16 kHz。

在大多數用途中，建議使用 AudioSource.fromMic()，因為它會自動處理這些限制。

支援的音訊輸入格式

Speech Recognition API 支援下列音訊輸入格式：

• MP3、WAV、FLAC、M4A 和 OGG 檔案會在裝置上自動解碼。
• 原始、無標頭的音訊 (.raw 或 .pcm) 必須採用 16 位元 PCM、16 kHz、單聲道格式。

如果格式無效或不受支援，辨識作業開始時會傳回 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 物件時，您必須以即時速度將資料寫入串流 (標準 16 kHz、16 位元、單聲道 PCM 音訊約為每秒 32,000 位元組)。如果寫入資料的速度過快，緩衝區可能會溢位。
• AudioSource.Mode.ONE_SHOT 常數會設定辨識器，等待整個音訊來源傳輸完畢，再執行推論並提供最終轉錄稿。您可以盡快寫入音訊資料，但必須關閉檔案描述元的寫入端，表示檔案結尾。系統收到這個檔案結尾信號後，才會提供最終語音轉錄結果。

注意： AudioSource 物件會取得基礎 ParcelFileDescriptor 物件的擁有權。辨識完成後，請務必呼叫 AudioSource.close() 方法。

以下範例會轉錄預錄的音訊檔案：

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

使用字詞時間

在要求的 recognitionOptions 設定區塊中，將 enableWordTiming 參數設為 true，即可要求每個辨識字詞的開始時間。

啟用字詞時間戳記後，每個 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
            }
        }
    }
}

注意： 只有使用串流音訊來源時，才支援字詞時間功能，例如 AudioSource.fromMic() 方法的即時輸入，或 AudioSource.fromPfd() 方法與 AudioSource.Mode.STREAMING 常數的自訂串流管道。在靜態 ONE_SHOT 音訊來源 (例如 AudioSource.fromFile() 或 AudioSource.fromUri() 方法傳回的來源) 上啟用字詞時間戳記，並呼叫 startRecognition() 方法，會擲回 IllegalArgumentException 物件。

支援的語言

眾數	語言代碼
進階	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 版)
基本	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 版)

注意： Beta 版語言的字詞錯誤率可能略高。我們也提供其他語言版本。請根據您的特定用途評估成效。

支援的裝置

眾數	支援的裝置
基本	使用 API 級別 31 以上版本的 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

常見設定問題

注意： 如果裝置的系統啟動載入程式已解鎖，則不支援這個 API。

ML Kit GenAI API 仰賴 Android AICore 應用程式存取 Gemini Nano。裝置剛設定完成 (包括重設)，或 AICore 應用程式剛重設 (例如清除資料、解除安裝後重新安裝)，AICore 應用程式可能沒有足夠時間完成初始化 (包括從伺服器下載最新設定)。因此，ML Kit GenAI API 可能無法正常運作。以下是常見的設定錯誤訊息和處理方式：

錯誤訊息範例	應對方式
AICore 失敗，錯誤類型為 4-CONNECTION_ERROR，錯誤代碼為 601-BINDING_FAILURE：AICore 服務繫結失敗。	舉例來說，在裝置設定完成後，立即安裝使用 ML Kit GenAI API 的應用程式，或是在安裝應用程式後解除安裝 AICore，都可能發生這種情況。更新 AICore 應用程式，然後重新安裝應用程式，應該就能解決問題。
AICore 失敗，錯誤類型為 3-PREPARATION_ERROR，錯誤代碼為 606-FEATURE_NOT_FOUND：無法使用「...」功能。	如果 AICore 尚未下載完最新設定，就可能發生這種情況。裝置連上網際網路後，通常需要幾分鐘到幾小時才能完成更新。重新啟動裝置可加快更新速度。 請注意，如果裝置的系統啟動載入程式已解鎖，您也會看到這則錯誤訊息，因為這個 API 不支援系統啟動載入程式已解鎖的裝置。
AICore 失敗，錯誤類型 1-DOWNLOAD_ERROR，錯誤代碼 0-UNKNOWN：功能 ... 失敗，失敗狀態 0，錯誤 esz：UNAVAILABLE：無法解析主機 ...	請保持網路連線，稍候幾分鐘再重試。

注意： 雖然開發人員經常重設各種設定，但使用者很少這麼做。此外，checkFeatureStatus() 或 checkStatus() API 可擷取所有這些設定失敗案例。請務必先呼叫 checkFeatureStatus() 或 checkStatus()，再顯示任何相關 UI，這樣應用程式使用者就不會看到這些錯誤。

程式碼範例

• 在 GitHub 探索 ML Kit 語音辨識 API 程式碼範例