API GenAI Speech Recognition

Esta API é oferecida na versão Alfa e não está sujeita a nenhum SLA ou política de descontinuação. É possível que sejam feitas alterações nessa API que interrompam a compatibilidade com versões anteriores.

Com a API GenAI Speech Recognition do Kit de ML, é possível transcrever conteúdo de áudio em texto. Esta API é compatível com os seguintes modos:

• Avançado: a API Speech Recognition usa o modelo de IA generativa, que produz uma cobertura de idioma mais ampla e uma qualidade geral melhor. Não é necessário fazer o download de um pacote de idioma separado para cada idioma, o que economiza armazenamento.
• Básico: a API Speech Recognition usa o modelo tradicional de reconhecimento de fala no dispositivo, semelhante à API SpeechRecognizer.

A API Speech Recognition transcreve conteúdo de áudio em texto no mesmo idioma. Para transcrever áudio em texto em outro idioma, use a API Speech Translation.

Principais recursos

• Captura a entrada de streaming do microfone ou de um arquivo de áudio.
• Transcreve um arquivo pré-gravado inteiro com os métodos AudioSource.fromFile() ou AudioSource.fromUri(). Para mais detalhes, consulte Requisitos de entrada de áudio.
• Para entradas de streaming, fornece o horário de início exato de cada palavra reconhecida para ajudar você a sincronizar animações de interface, gerar legendas ou destacar palavras enquanto são faladas. O horário de início (em milissegundos) de cada palavra reconhecida é um deslocamento do início do evento, que é o carimbo de data/hora 0.
• O texto transcrito é fornecido como um fluxo contínuo, que pode ser inicialmente parcial (e sujeito a alterações) antes de se tornar o texto reconhecido final.

Resultados de exemplo

Áudio	Modo	Localidade	Transcrição
audio_2	Avançado	es-ES	"Este es un mensaje corto."
audio_1	Básico	en-US	"Esta é uma mensagem curta"

Comparação com a API Speech Recognition da plataforma

A API Speech Recognition do Kit de ML abrange a funcionalidade básica da API SpeechRecognizer da plataforma ao usar o modo básico. Uma das principais vantagens do Kit de ML é que ele não está vinculado a uma versão específica da plataforma.

Além disso, a API Speech Recognition do Kit de ML oferece suporte ao reconhecimento de fala usando o modelo do Gemini no dispositivo no modo avançado, oferecendo uma cobertura de idioma estendida.

Observação: o modo avançado está disponível em alguns dispositivos. Consulte Dispositivos compatíveis para mais detalhes.

Primeiros passos

Observação: o SDK requer o minSdkVersion 26 ou mais recente. Confira os requisitos de ambiente de execução para cada modo em Dispositivos compatíveis.

Adicione a API Speech Recognition do Kit de ML como uma dependência na configuração build.gradle:

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

Para integrar a API Speech Recognition ao seu app, crie um cliente SpeechRecognizer. Verifique o status dos recursos necessários do modelo no dispositivo e faça o download do modelo, se ele ainda não estiver no dispositivo. Depois de preparar a entrada de áudio em um SpeechRecognizerRequest, execute a inferência usando o cliente para receber a saída de streaming do fluxo do Kotlin. Por fim, lembre-se de fechar o cliente para liberar recursos.

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

Requisitos de entrada de áudio

A API GenAI Speech Recognition aceita entrada do microfone ou de uma fonte personalizada por um descritor do arquivo.

Se você usar AudioSource.fromPfd(parcelFileDescriptor), o áudio de entrada precisará atender aos seguintes requisitos rigorosos:

• Formato: PCM bruto de 16 bits sem cabeçalho.
• Canais: mono (canal único).
• Taxa de amostragem: 16 kHz.

Para a maioria dos casos de uso, recomendamos o AudioSource.fromMic(), porque ele lida com essas restrições automaticamente.

Formatos de entrada de áudio compatíveis

A API Speech Recognition é compatível com os seguintes formatos de entrada de áudio:

• Os arquivos MP3, WAV, FLAC, M4A e OGG são decodificados automaticamente no dispositivo.
• O áudio bruto sem cabeçalho (.raw ou .pcm) precisa estar no formato PCM de 16 bits, 16 kHz, mono.

Se o formato for inválido ou incompatível, um valor ErrorResponse será retornado quando o reconhecimento começar.

Implementar a API Speech Recognition

Veja como usar a API Speech Recognition para transcrever áudio e usar o tempo de palavras.

Transcrever áudio

A API Speech Recognition aceita entrada de áudio do microfone do dispositivo, arquivos pré-gravados ou pipelines personalizados usando um objeto ParcelFileDescriptor.

Para preparar os dados de áudio, crie um objeto AudioSource usando um dos métodos de fábrica listados na tabela a seguir:

Método	Modo de áudio	Caso de uso recomendado
AudioSource.fromMic()	STREAMING	Capturar a entrada de voz ao vivo do usuário. Requer a permissão RECORD_AUDIO.
AudioSource.fromFile(file) AudioSource.fromUri(context, uri)	ONE_SHOT	Transcrever arquivos de áudio pré-gravados. Decodifica automaticamente formatos de arquivo padrão diretamente no dispositivo.
AudioSource.fromPfd(pfd, mode) AudioSource.fromPfd(pfd, mode, audioFormat)	STREAMING ou ONE_SHOT	Pipelines de áudio personalizados (como tratamento de dados de áudio processados em outro lugar no app).

A constante AudioSource.Mode controla como a API processa o áudio recebido:

• A constante AudioSource.Mode.STREAMING configura o reconhecedor para retornar resultados de transcrição parciais e finais continuamente à medida que os dados de áudio chegam. Ao fornecer um objeto ParcelFileDescriptor personalizado, é necessário gravar dados no stream em tempo real (aproximadamente 32.000 bytes por segundo para áudio PCM mono padrão de 16 kHz e 16 bits). Gravar dados muito rapidamente pode sobrecarregar o buffer.
• A constante AudioSource.Mode.ONE_SHOT configura o reconhecedor para aguardar a transferência de toda a fonte de áudio antes de realizar a inferência e entregar a transcrição final. É possível gravar os dados de áudio o mais rápido possível, mas é necessário fechar a extremidade de gravação do descritor do arquivo para sinalizar o fim do arquivo. O resultado final da transcrição não é entregue até que esse sinal de fim de arquivo seja recebido.

Observação: o objeto AudioSource assume a propriedade do objeto ParcelFileDescriptor subjacente. Não se esqueça de chamar o método AudioSource.close() quando o reconhecimento for concluído.

O exemplo a seguir transcreve um arquivo de áudio pré-gravado:

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

Usar o tempo das palavras

É possível solicitar o horário de início de cada palavra reconhecida definindo o parâmetro enableWordTiming como true no bloco de configuração recognitionOptions da solicitação.

Quando o tempo de palavras está ativado, cada objeto SpeechRecognizerResponse.FinalTextResponse inclui uma propriedade wordTimings que contém uma lista de objetos SpeechRecognizerResponse.WordTiming. Cada objeto fornece a string de palavras reconhecida (text) e o deslocamento em milissegundos (timestampMs) a partir do início da sessão de reconhecimento de fala. Quando o tempo de palavras está desativado (a configuração padrão), a lista wordTimings é retornada vazia.

O exemplo de código a seguir demonstra como configurar e ativar o tempo de palavras:

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

Observação: o recurso de marcação de tempo de palavras só é compatível com fontes de áudio de streaming, como entrada ao vivo do método AudioSource.fromMic() ou pipelines de streaming personalizados do método AudioSource.fromPfd() com a constante AudioSource.Mode.STREAMING. Chamar o método startRecognition() com o tempo de palavras ativado em uma fonte de áudio ONE_SHOT estática, como as retornadas pelos métodos AudioSource.fromFile() ou AudioSource.fromUri(), gera um objeto IllegalArgumentException.

Idiomas compatíveis

Moda	Localidades
Avançado	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)
Básico	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)

Observação: os idiomas na versão Beta podem ter uma taxa de erro de palavras um pouco maior. Outras localidades estão disponíveis. Avalie o desempenho deles com base no seu caso de uso específico.

Dispositivos compatíveis

Moda	Dispositivos compatíveis
Básico	Dispositivos Android que usam o nível 31 da API e versões mais recentes.
Avançado	Séries Pixel 10 e Pixel 11, além de dispositivos com o Gemini Nano nos seguintes chipsets (incluindo as séries Samsung Galaxy S26, Z Flip8 e Z Fold8, entre outras): Qualcomm Snapdragon: SM8750, SM8845, SM8850, SM8950, SM8975 MediaTek Dimensity: MT6991, MT6993, MT6995 Samsung Exynos: Exynos 2600

Problemas comuns de configuração

Observação: essa API não é compatível com dispositivos que têm um bootloader desbloqueado.

As APIs GenAI do Kit de ML dependem do app Android AICore para acessar o Gemini Nano. Quando um dispositivo é configurado (incluindo redefinição) ou o app AICore é redefinido (por exemplo, dados limpos, desinstalados e reinstalados), o app AICore pode não ter tempo suficiente para concluir a inicialização (incluindo o download das configurações mais recentes do servidor). Por isso, as APIs GenAI do Kit de ML podem não funcionar como esperado. Confira as mensagens de erro de configuração comuns que podem aparecer e como lidar com elas:

Exemplo de mensagem de erro	Como proceder
O AICore falhou com o tipo de erro 4-CONNECTION_ERROR e o código do erro 601-BINDING_FAILURE: falha ao vincular o serviço do AICore.	Isso pode acontecer quando você instala o app usando as APIs GenAI do Kit de ML imediatamente após a configuração do dispositivo ou quando o AICore é desinstalado depois que o app é instalado. Atualize o app AICore e reinstale o seu app para corrigir o problema.
O AICore falhou com o tipo de erro 3-PREPARATION_ERROR e o código do erro 606-FEATURE_NOT_FOUND: o recurso ... não está disponível.	Isso pode acontecer quando o AICore não terminou de baixar as configurações mais recentes. Quando o dispositivo está conectado à Internet, geralmente leva de alguns minutos a algumas horas para atualizar. Reiniciar o dispositivo pode acelerar a atualização. Se o carregador de inicialização do dispositivo estiver desbloqueado, você também vai receber esse erro. Essa API não é compatível com dispositivos que têm carregadores de inicialização desbloqueados.
O AICore falhou com o tipo de erro 1-DOWNLOAD_ERROR e o código do erro 0-UNKNOWN: o recurso ... falhou com o status de falha 0 e o erro esz: UNAVAILABLE: não foi possível resolver o host ...	Mantenha a conexão de rede, aguarde alguns minutos e tente de novo.

Observação: embora as redefinições sejam comuns para desenvolvedores, elas são muito menos frequentes para os usuários. Além disso, todos esses casos de falha de configuração podem ser detectados pelas APIs checkFeatureStatus() ou checkStatus(). Chame checkFeatureStatus() ou checkStatus() antes de mostrar qualquer interface relacionada para que os usuários do app não vejam esses erros em nenhum caso.

Exemplo de código

• Confira o exemplo de código da API Speech Recognition do Kit de ML no GitHub.