GenAI Speech Recognition API

Этот API предлагается в альфа-версии, и на него не распространяются никакие соглашения об уровне обслуживания или правила прекращения поддержки. В API могут вноситься изменения, нарушающие обратную совместимость.

API распознавания речи на основе генеративного ИИ в ML Kit позволяет преобразовывать аудиоконтент в текст. Этот API поддерживает следующие режимы:

• Расширенный. Speech Recognition API использует модель GenAI, которая обеспечивает более широкий охват языков и более высокое качество. Вам не нужно скачивать отдельный языковой пакет для каждого языка, что экономит место в хранилище.
• Базовый. Speech Recognition API использует традиционную модель распознавания речи на устройстве, аналогичную SpeechRecognizer API.

Speech Recognition API преобразует аудиоконтент в текст на том же языке. Чтобы преобразовать аудио в текст на другом языке, используйте Speech Translation API.

Основные возможности

• Записывает потоковые входные данные с микрофона или аудиофайла.
• Расшифровывает весь предварительно записанный файл с помощью методов AudioSource.fromFile() или AudioSource.fromUri(). Подробнее о требованиях к аудиовходу…
• Для потоковых входных данных предоставляет точное время начала каждого распознанного слова, чтобы помочь вам синхронизировать анимацию пользовательского интерфейса, генерировать субтитры или выделять слова по мере их произнесения. Время начала (в миллисекундах) каждого распознанного слова – это смещение от начала события, которое является временной меткой 0.
• Расшифрованный текст предоставляется в виде непрерывного потока, который изначально может быть частичным (и может быть изменен), прежде чем станет окончательным распознанным текстом.

Пример результатов

Аудио	Режим	Региональные настройки	Расшифровка
audio_2	Расширенные	es-ES	"Este es un mensaje corto."
audio_1	Основные	en-US	"Это короткое сообщение"

Сравнение с Speech Recognition API

API распознавания речи ML Kit охватывает основные функции API платформы SpeechRecognizer при использовании базового режима. Ключевое преимущество ML Kit в том, что он не привязан к конкретной версии платформы.

Кроме того, Speech Recognition API в ML Kit поддерживает распознавание речи с помощью модели Gemini на устройстве в расширенном режиме, что позволяет расширить языковой охват.

Примечание. Расширенный режим доступен только на некоторых устройствах. Подробнее о поддерживаемых устройствах…

Начать

Примечание. Для работы SDK требуется minSdkVersion версии 26 или выше. Требования к среде выполнения для каждого режима приведены в разделе Поддерживаемые устройства.

Добавьте ML Kit 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), входной аудиофайл должен соответствовать следующим строгим требованиям:

• Формат: необработанный 16-битный PCM без заголовка.
• Каналы: моно (один канал).
• Частота дискретизации: 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.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, то должны записывать данные в поток в реальном времени (примерно 32 000 байт в секунду для стандартного монофонического PCM-аудио с частотой дискретизации 16 кГц и разрядностью 16 бит). Слишком быстрая запись данных может переполнить буфер.
• Константа 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()
    }
}

Использовать временные метки слов

Чтобы получить время начала каждого распознанного слова, задайте для параметра 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
            }
        }
    }
}

Примечание. Функция временных меток для слов поддерживается только при использовании потоковых источников аудио, таких как входные данные в реальном времени из метода AudioSource.fromMic() или пользовательские конвейеры потоковой передачи из метода AudioSource.fromPfd() с константой AudioSource.Mode.STREAMING. Вызов метода startRecognition() с включенным таймингом слов для статического источника аудио ONE_SHOT, например возвращенного методами AudioSource.fromFile() или AudioSource.fromUri(), приводит к созданию объекта IllegalArgumentException.

Поддерживаемые языки

Режим	Региональные настройки
Расширенные	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 (бета), cmn-Hant-TW (бета), de-DE (бета), en-US, es-ES (бета), fr-FR (бета), hi-IN (бета), it-IT (бета), ja-JP (бета), ko-KR (бета), pl-PL (бета), pt-BR (бета), ru-RU (бета), tr-TR (бета), vi-VN (бета)

Примечание. При использовании языков, находящихся на этапе бета-тестирования, может быть немного больше ошибок в словах. Доступны дополнительные региональные настройки. Оцените их эффективность в зависимости от вашего конкретного случая использования.

Поддерживаемые устройства

Режим	Поддерживаемые устройства
Основные	Устройства Android с API уровня 31 и выше.
Расширенные	Устройства серий 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 не поддерживается на устройствах с разблокированным загрузчиком операционной системы.

Для доступа к Gemini Nano API ML Kit GenAI используют приложение Android AICore. Если устройство только что настроено (в том числе после сброса) или приложение AICore только что сброшено (например, очищены данные, приложение удалено и установлено заново), у AICore может не хватить времени на завершение инициализации (включая скачивание последних конфигураций с сервера). В результате API GenAI в ML Kit могут работать неправильно. Ниже приведены распространенные сообщения об ошибках настройки и способы их устранения.

Пример сообщения об ошибке	Как устранить проблему
Ошибка 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 failed with error type 1-DOWNLOAD_ERROR and error code 0-UNKNOWN: Feature ... failed with failure status 0 and error esz: UNAVAILABLE: Unable to resolve host ...	Сохраните сетевое подключение, подождите несколько минут и повторите попытку.

Примечание. Разработчики часто сбрасывают настройки, но пользователи делают это редко. Кроме того, все эти ошибки настройки можно отследить с помощью API checkFeatureStatus() или checkStatus(). Чтобы пользователи не видели эти ошибки, перед показом интерфейса вызывайте checkFeatureStatus() или checkStatus().

Образец кода

• Изучите пример кода Speech Recognition API в ML Kit на GitHub.