API de reconnaissance vocale GenAI

Cette API est proposée en version alpha et n'est soumise à aucun contrat de niveau de service ni aucun règlement relatif aux abandons. Des modifications susceptibles d'interrompre la rétrocompatibilité peuvent être apportées à cette API.

L'API GenAI Speech Recognition de ML Kit vous permet de transcrire du contenu audio en texte. Cette API est compatible avec les modes suivants :

• Avancé : l'API Speech Recognition utilise le modèle GenAI, qui offre une couverture linguistique plus large et une meilleure qualité globale. Vous n'avez pas besoin de télécharger un module linguistique distinct pour chaque langue, ce qui vous permet d'économiser de l'espace de stockage.
• Basic : l'API Speech Recognition utilise le modèle de reconnaissance vocale traditionnel sur l'appareil, semblable à l'API SpeechRecognizer.

L'API Speech Recognition transcrit du contenu audio en texte dans la même langue. Pour transcrire du contenu audio en texte dans une autre langue, utilisez l'API Speech Translation.

Capacités clés

• Capture l'entrée en streaming depuis le micro ou un fichier audio.
• Transcrire un fichier préenregistré entier avec les méthodes AudioSource.fromFile() ou AudioSource.fromUri(). Pour en savoir plus, consultez Exigences concernant les entrées audio.
• Pour les entrées en streaming, fournit l'heure de début exacte de chaque mot reconnu pour vous aider à synchroniser les animations de l'interface utilisateur, à générer des sous-titres ou à mettre en surbrillance les mots au fur et à mesure qu'ils sont prononcés. L'heure de début (en millisecondes) de chaque mot reconnu est un décalage par rapport au début de l'événement, qui correspond au code temporel 0.
• Le texte transcrit est fourni sous la forme d'un flux continu, qui peut être initialement partiel (et sujet à modification) avant de devenir le texte reconnu final.

Exemples de résultats

Audio	Mode	Paramètres régionaux	Transcription
audio_2	Avancé	es-ES	"Este es un mensaje corto."
audio_1	De base	en-US	"Ceci est un message court"

Comparaison avec l'API de reconnaissance vocale de la plate-forme

L'API ML Kit Speech Recognition couvre les fonctionnalités de base de l'API SpeechRecognizer de la plate-forme en mode Basic. L'un des principaux avantages de ML Kit est qu'il n'est pas lié à une version de plate-forme spécifique.

De plus, l'API ML Kit Speech Recognition est compatible avec la reconnaissance vocale à l'aide du modèle Gemini sur l'appareil en mode avancé, ce qui permet de couvrir un plus grand nombre de langues.

Remarque : Le mode avancé est disponible sur certains appareils. Pour en savoir plus, consultez Appareils compatibles.

Commencer

Remarque : Le SDK nécessite minSdkVersion 26 ou version ultérieure. Consultez Appareils compatibles pour connaître les exigences d'exécution de chaque mode.

Ajoutez l'API ML Kit Speech Recognition en tant que dépendance dans votre configuration build.gradle :

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

Pour intégrer l'API Speech Recognition à votre application, créez un client SpeechRecognizer. Vérifiez l'état des fonctionnalités nécessaires du modèle sur l'appareil et téléchargez le modèle s'il n'est pas déjà présent sur l'appareil. Après avoir préparé votre entrée audio dans un SpeechRecognizerRequest, exécutez l'inférence à l'aide du client pour recevoir la sortie en streaming du flux Kotlin. Enfin, n'oubliez pas de fermer le client pour libérer les ressources.

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

Exigences concernant l'entrée audio

L'API GenAI Speech Recognition accepte les entrées provenant du micro ou d'une source personnalisée via un descripteur de fichier.

Si vous utilisez AudioSource.fromPfd(parcelFileDescriptor), l'audio d'entrée doit répondre aux exigences strictes suivantes :

• Format : PCM 16 bits brut sans en-tête.
• Canaux : mono (canal unique).
• Taux d'échantillonnage : 16 kHz.

Pour la plupart des cas d'utilisation, AudioSource.fromMic() est recommandé, car il gère automatiquement ces contraintes.

Formats d'entrée audio compatibles

L'API Speech Recognition est compatible avec les formats d'entrée audio suivants :

• Les fichiers MP3, WAV, FLAC, M4A et OGG sont décodés automatiquement sur l'appareil.
• Les fichiers audio bruts sans en-tête (.raw ou .pcm) doivent être au format PCM 16 bits, 16 kHz, mono.

Si le format n'est pas valide ou n'est pas accepté, une valeur ErrorResponse est renvoyée au début de la reconnaissance.

Implémenter l'API Speech Recognition

Voici comment utiliser l'API Speech Recognition pour transcrire des contenus audio et utiliser le code temporel des mots.

Transcrire du contenu audio

L'API Speech Recognition accepte les entrées audio provenant du micro de l'appareil, de fichiers préenregistrés ou de pipelines personnalisés à l'aide d'un objet ParcelFileDescriptor.

Pour préparer vos données audio, créez un objet AudioSource à l'aide de l'une des méthodes de fabrique listées dans le tableau suivant :

Méthode	Mode audio	Cas d'utilisation recommandé
AudioSource.fromMic()	STREAMING	Capturer l'entrée vocale en direct de l'utilisateur. Nécessite l'autorisation RECORD_AUDIO.
AudioSource.fromFile(file) AudioSource.fromUri(context, uri)	ONE_SHOT	Transcrire des fichiers audio préenregistrés Décode automatiquement les formats de fichiers standards directement sur l'appareil.
AudioSource.fromPfd(pfd, mode) AudioSource.fromPfd(pfd, mode, audioFormat)	STREAMING ou ONE_SHOT	Pipelines audio personnalisés (par exemple, données audio traitées ailleurs dans votre application)

La constante AudioSource.Mode contrôle la manière dont l'API traite l'audio entrant :

• La constante AudioSource.Mode.STREAMING configure l'outil de reconnaissance pour qu'il renvoie des résultats de transcription partiels et finaux en continu à mesure que les données audio arrivent. Lorsque vous fournissez un objet ParcelFileDescriptor personnalisé, vous devez écrire les données dans le flux en temps réel (environ 32 000 octets par seconde pour un son PCM mono standard de 16 kHz, 16 bits). L'écriture de données trop rapide peut entraîner un dépassement de la mémoire tampon.
• La constante AudioSource.Mode.ONE_SHOT configure l'outil de reconnaissance pour qu'il attende le transfert de l'intégralité de la source audio avant d'effectuer l'inférence et de fournir la transcription finale. Vous pouvez écrire les données audio aussi rapidement que possible, mais vous devez fermer l'extrémité d'écriture de votre descripteur de fichier pour signaler la fin du fichier. Le résultat final de la transcription n'est pas fourni tant que ce signal de fin de fichier n'est pas reçu.

Remarque : L'objet AudioSource s'approprie l'objet ParcelFileDescriptor sous-jacent. N'oubliez pas d'appeler la méthode AudioSource.close() une fois la reconnaissance terminée.

L'exemple suivant transcrit un fichier audio préenregistré :

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

Utiliser le code temporel au niveau du mot

Vous pouvez demander l'heure de début de chaque mot reconnu en définissant le paramètre enableWordTiming sur true dans le bloc de configuration recognitionOptions de votre requête.

Lorsque la synchronisation des mots est activée, chaque objet SpeechRecognizerResponse.FinalTextResponse inclut une propriété wordTimings contenant une liste d'objets SpeechRecognizerResponse.WordTiming. Chaque objet fournit la chaîne de mots reconnue (text) et son décalage en millisecondes (timestampMs) à partir du début de la session de reconnaissance vocale. Lorsque le temps de chargement du mot est désactivé (paramètre par défaut), la liste wordTimings est renvoyée vide.

L'exemple de code suivant montre comment configurer et activer la synchronisation des mots :

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

Remarque : La fonctionnalité de minutage des mots n'est compatible qu'avec les sources audio en streaming, telles que l'entrée en direct de la méthode AudioSource.fromMic() ou les pipelines de streaming personnalisés de la méthode AudioSource.fromPfd() avec la constante AudioSource.Mode.STREAMING. L'appel de la méthode startRecognition() avec la synchronisation des mots activée sur une source audio ONE_SHOT statique, telle que celles renvoyées par les méthodes AudioSource.fromFile() ou AudioSource.fromUri(), génère un objet IllegalArgumentException.

Langues disponibles

Mode	Locales
Avancé	ar-SA (bêta), cmn-Hans-CN, cmn-Hant-TW, da-DK (bêta), de-DE, en-US, es-ES, fr-FR, hi-IN (bêta), id-ID (bêta), it-IT, ja-JP, ko-KR, nl-NL (bêta), pl-PL (bêta), pt-PT, ru-RU, sv-SE (bêta), th-TH, tr-TR (bêta), vi-VN (bêta)
De base	cmn-Hans-CN (bêta), cmn-Hant-TW (bêta), de-DE (bêta), en-US, es-ES (bêta), fr-FR (bêta), hi-IN (bêta), it-IT (bêta), ja-JP (bêta), ko-KR (bêta), pl-PL (bêta), pt-BR (bêta), ru-RU (bêta), tr-TR (bêta), vi-VN (bêta)

Remarque : Les langues en version bêta peuvent présenter un taux d'erreur de mots légèrement plus élevé. D'autres paramètres régionaux sont disponibles. Évaluez leurs performances en fonction de votre cas d'utilisation spécifique.

Appareils compatibles

Mode	Appareils compatibles
De base	Appareils Android utilisant le niveau d'API 31 ou supérieur.
Avancé	Séries Pixel 10 et Pixel 11, ainsi que les appareils équipés de Gemini Nano sur les chipsets suivants (y compris les séries Samsung Galaxy S26, Z Flip8 et Z Fold8, entre autres) : Qualcomm Snapdragon : SM8750, SM8845, SM8850, SM8950, SM8975 MediaTek Dimensity : MT6991, MT6993, MT6995 Samsung Exynos : Exynos 2600

Problèmes de configuration courants

Remarque : Cette API n'est pas compatible avec les appareils dotés d'un bootloader déverrouillé.

Les API d'IA générative ML Kit s'appuient sur l'application Android AICore pour accéder à Gemini Nano. Lorsqu'un appareil vient d'être configuré (y compris réinitialisé) ou que l'application AICore vient d'être réinitialisée (par exemple, effacement des données, désinstallation puis réinstallation), l'application AICore peut ne pas avoir assez de temps pour terminer l'initialisation (y compris le téléchargement des dernières configurations depuis le serveur). Par conséquent, les API GenAI de ML Kit risquent de ne pas fonctionner comme prévu. Voici les messages d'erreur de configuration courants que vous pouvez rencontrer et comment les résoudre :

Exemple de message d'erreur	Comment répondre à une telle objection
Échec d'AICore avec le type d'erreur 4-CONNECTION_ERROR et le code d'erreur 601-BINDING_FAILURE : échec de la liaison du service AICore.	Cela peut se produire lorsque vous installez l'application à l'aide des API GenAI de ML Kit immédiatement après la configuration de l'appareil ou lorsque AICore est désinstallé après l'installation de votre application. Mettre à jour l'application AICore, puis réinstaller votre application devrait résoudre le problème.
AICore a échoué avec le type d'erreur 3-PREPARATION_ERROR et le code d'erreur 606-FEATURE_NOT_FOUND : la fonctionnalité ... n'est pas disponible.	Cela peut se produire lorsque AICore n'a pas fini de télécharger les dernières configurations. Lorsque l'appareil est connecté à Internet, la mise à jour prend généralement de quelques minutes à quelques heures. Redémarrer l'appareil peut accélérer la mise à jour. Notez que si le bootloader de l'appareil est déverrouillé, vous verrez également cette erreur. Cette API n'est pas compatible avec les appareils dont le bootloader est déverrouillé.
AICore a échoué avec le type d'erreur 1-DOWNLOAD_ERROR et le code d'erreur 0-UNKNOWN : la fonctionnalité ... a échoué avec l'état d'échec 0 et l'erreur esz : UNAVAILABLE : Impossible de résoudre l'hôte ...	Maintenez la connexion réseau, patientez quelques minutes, puis réessayez.

Remarque : Bien que les développeurs effectuent souvent des réinitialisations, les utilisateurs le font beaucoup moins fréquemment. De plus, tous ces cas d'échec de configuration peuvent être détectés par les API checkFeatureStatus() ou checkStatus(). Veillez à appeler checkFeatureStatus() ou checkStatus() avant d'afficher une UI associée, afin que les utilisateurs de votre application ne voient jamais ces erreurs.

Exemple de code

• Explorez l'exemple de code de l'API ML Kit Speech Recognition sur GitHub.