API GenAI Speech Recognition

Questa API è offerta in versione alpha e non è soggetta a SLA (accordo sul livello del servizio) o norme sul ritiro. A questa API potrebbero essere apportate modifiche che interrompono la compatibilità con le versioni precedenti.

Con l'API GenAI Speech Recognition di ML Kit, puoi trascrivere i contenuti audio in testo. Questa API supporta le seguenti modalità:

• Avanzato: l'API Speech Recognition utilizza il modello di AI generativa, che produce una copertura linguistica più ampia e una qualità complessiva migliore. Non è necessario scaricare un language pack separato per ogni lingua, il che consente di risparmiare spazio di archiviazione.
• Base: l'API Speech Recognition utilizza il modello di riconoscimento vocale on-device tradizionale, simile all'API SpeechRecognizer.

L'API Speech Recognition trascrive i contenuti audio in testo nella stessa lingua. Per trascrivere l'audio in testo in un'altra lingua, utilizza l'API Speech Translation.

Funzionalità chiave

• Acquisisce l'input in streaming dal microfono o da un file audio.
• Trascrive un intero file preregistrato con i metodi AudioSource.fromFile() o AudioSource.fromUri(). Per maggiori dettagli, consulta i requisiti per l'input audio.
• Per gli input in streaming, fornisce l'ora di inizio esatta di ogni parola riconosciuta per aiutarti a sincronizzare le animazioni della UI, generare sottotitoli o evidenziare le parole mentre vengono pronunciate. L'ora di inizio (in millisecondi) di ogni parola riconosciuta è un offset dall'inizio dell'evento, ovvero il timestamp 0.
• Il testo trascritto viene fornito come un flusso continuo, che inizialmente potrebbe essere parziale (e soggetto a modifiche) prima di diventare il testo riconosciuto finale.

Risultati di esempio

Audio	Modalità	Impostazioni internazionali	Trascrizione
audio_2	Avanzate	es-ES	"Este es un mensaje corto."
audio_1	Base	en-US	"Questo è un breve messaggio"

Confronto con l'API Speech Recognition della piattaforma

L'API Speech Recognition di ML Kit copre le funzionalità di base dell'API SpeechRecognizer della piattaforma quando utilizzi la modalità Basic. Un vantaggio fondamentale di ML Kit è che non è vincolato a una versione specifica della piattaforma.

Inoltre, l'API ML Kit Speech Recognition supporta il riconoscimento vocale utilizzando il modello Gemini on-device quando si utilizza la modalità avanzata, offrendo una copertura linguistica estesa.

Nota: la modalità avanzata è disponibile su alcuni dispositivi. Per maggiori dettagli, vedi Dispositivi supportati.

Inizia

Nota: l'SDK richiede minSdkVersion 26 o versioni successive. Consulta Dispositivi supportati per i requisiti di runtime per ogni modalità.

Aggiungi l'API ML Kit Speech Recognition come dipendenza nella configurazione build.gradle:

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

Per integrare l'API Speech Recognition nella tua app, crea un client SpeechRecognizer. Controlla lo stato delle funzionalità del modello on-device necessarie e scarica il modello se non è già presente sul dispositivo. Dopo aver preparato l'input audio in un SpeechRecognizerRequest, esegui l'inferenza utilizzando il client per ricevere l'output in streaming dal flusso Kotlin. Infine, ricordati di chiudere il client per rilasciare le risorse.

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

Requisiti per l'input audio

L'API GenAI Speech Recognition supporta l'input dal microfono o da un'origine personalizzata tramite un descrittore del file.

Se utilizzi AudioSource.fromPfd(parcelFileDescriptor), l'audio di input deve soddisfare i seguenti requisiti rigorosi:

• Formato: PCM a 16 bit non elaborato, senza intestazione.
• Canali: mono (canale singolo).
• Frequenza di campionamento: 16 kHz.

Per la maggior parte dei casi d'uso, è consigliato AudioSource.fromMic() perché gestisce questi vincoli automaticamente.

Formati di input audio supportati

L'API Speech Recognition supporta i seguenti formati di input audio:

• I file MP3, WAV, FLAC, M4A e OGG vengono decodificati automaticamente sul dispositivo.
• L'audio non elaborato e senza intestazione (.raw o .pcm) deve essere in formato PCM a 16 bit, 16 kHz, mono.

Se il formato non è valido o non è supportato, viene restituito un valore ErrorResponse all'avvio del riconoscimento.

Implementa l'API Speech Recognition

Ecco come utilizzare l'API Speech Recognition per trascrivere l'audio e utilizzare la sincronizzazione delle parole.

Trascrivi audio

L'API Speech Recognition supporta l'input audio dal microfono del dispositivo, da file preregistrati o da pipeline personalizzate utilizzando un oggetto ParcelFileDescriptor.

Per preparare i dati audio, crea un oggetto AudioSource utilizzando uno dei metodi factory elencati nella tabella seguente:

Metodo	Modalità audio	Caso d'uso consigliato
AudioSource.fromMic()	STREAMING	Acquisire l'input vocale in tempo reale dell'utente. Richiede l'autorizzazione RECORD_AUDIO.
AudioSource.fromFile(file) AudioSource.fromUri(context, uri)	ONE_SHOT	Trascrivi file audio preregistrati. Decodifica automaticamente i formati file standard direttamente sul dispositivo.
AudioSource.fromPfd(pfd, mode) AudioSource.fromPfd(pfd, mode, audioFormat)	STREAMING o ONE_SHOT	Pipeline audio personalizzate (ad esempio dati audio elaborati altrove nella tua app).

La costante AudioSource.Mode controlla il modo in cui l'API elabora l'audio in entrata:

• La costante AudioSource.Mode.STREAMING configura il riconoscimento in modo che restituisca continuamente i risultati di trascrizione parziali e finali man mano che arrivano i dati audio. Quando fornisci un oggetto ParcelFileDescriptor personalizzato, devi scrivere i dati nello stream in tempo reale (circa 32.000 byte al secondo per l'audio PCM mono standard a 16 kHz e 16 bit). La scrittura dei dati troppo rapida può causare l'overflow del buffer.
• La costante AudioSource.Mode.ONE_SHOT configura il riconoscimento in modo che attenda il trasferimento dell'intera sorgente audio prima di eseguire l'inferenza e fornire la trascrizione finale. Puoi scrivere i dati audio il più velocemente possibile, ma devi chiudere l'estremità di scrittura del descrittore del file per segnalare la fine del file. Il risultato finale della trascrizione non viene fornito finché non viene ricevuto questo segnale di fine file.

Nota: l'oggetto AudioSource assume la proprietà dell'oggetto ParcelFileDescriptor sottostante. Ricordati di chiamare il metodo AudioSource.close() al termine del riconoscimento.

L'esempio seguente trascrive un file audio preregistrato:

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

Utilizza la sincronizzazione delle parole

Puoi richiedere l'ora di inizio di ogni parola riconosciuta impostando il parametro enableWordTiming su true nel blocco di configurazione recognitionOptions della richiesta.

Quando la sincronizzazione delle parole è abilitata, ogni oggetto SpeechRecognizerResponse.FinalTextResponse include una proprietà wordTimings contenente un elenco di oggetti SpeechRecognizerResponse.WordTiming. Ogni oggetto fornisce la stringa di parole riconosciuta (text) e il relativo offset in millisecondi (timestampMs) a partire dall'inizio della sessione di riconoscimento vocale. Quando la sincronizzazione delle parole è disattivata (impostazione predefinita), l'elenco wordTimings viene restituito vuoto.

L'esempio di codice seguente mostra come configurare e attivare la sincronizzazione delle parole:

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

Nota: la funzionalità di sincronizzazione delle parole è supportata solo quando si utilizzano origini audio in streaming, come l'input in tempo reale dal metodo AudioSource.fromMic() o pipeline di streaming personalizzate dal metodo AudioSource.fromPfd() con la costante AudioSource.Mode.STREAMING. La chiamata del metodo startRecognition() con la sincronizzazione delle parole attivata su una sorgente audio ONE_SHOT statica, come quelle restituite dai metodi AudioSource.fromFile() o AudioSource.fromUri(), genera un oggetto IllegalArgumentException.

Lingue supportate

Modalità	Locales
Avanzate	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)
Base	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)

Nota: le lingue in versione beta potrebbero avere un tasso di errore delle parole leggermente più elevato. Sono disponibili altre impostazioni internazionali. Valuta le loro prestazioni in base al tuo caso d'uso specifico.

Dispositivi supportati

Modalità	Dispositivi supportati
Base	Dispositivi Android che utilizzano il livello API 31 e versioni successive.
Avanzate	Pixel serie 10 e 11, oltre ai dispositivi con Gemini Nano sui seguenti chipset (tra cui Samsung Galaxy serie S26, Z Flip8 e Z Fold8): Qualcomm Snapdragon: SM8750, SM8845, SM8850, SM8950, SM8975 MediaTek Dimensity: MT6991, MT6993, MT6995 Samsung Exynos: Exynos 2600

Problemi di configurazione comuni

Nota: questa API non è supportata sui dispositivi con un bootloader sbloccato.

Le API GenAI di ML Kit si basano sull'app Android AICore per accedere a Gemini Nano. Quando un dispositivo viene appena configurato (incluso il reset) o l'app AICore viene appena resettata (ad es. cancellazione dei dati, disinstallazione e reinstallazione), l'app AICore potrebbe non avere abbastanza tempo per completare l'inizializzazione (incluso il download delle configurazioni più recenti dal server). Di conseguenza, le API GenAI di ML Kit potrebbero non funzionare come previsto. Di seguito sono riportati i messaggi di errore di configurazione comuni che potresti visualizzare e come gestirli:

Esempio di messaggio di errore	Come gestirla
AICore non è riuscito con il tipo di errore 4-CONNECTION_ERROR e il codice di errore 601-BINDING_FAILURE: impossibile associare il servizio AICore.	Ciò potrebbe accadere quando installi l'app utilizzando le API GenAI di ML Kit immediatamente dopo la configurazione del dispositivo o quando AICore viene disinstallato dopo l'installazione dell'app. Il problema dovrebbe risolversi aggiornando l'app AICore e reinstallando la tua app.
AICore non è riuscito con il tipo di errore 3-PREPARATION_ERROR e il codice di errore 606-FEATURE_NOT_FOUND: la funzionalità … non è disponibile.	Ciò potrebbe accadere quando AICore non ha terminato il download delle configurazioni più recenti. Quando il dispositivo è connesso a internet, l'aggiornamento richiede in genere da alcuni minuti ad alcune ore. Il riavvio del dispositivo può velocizzare l'aggiornamento. Tieni presente che se il bootloader del dispositivo è sbloccato, vedrai anche questo errore: questa API non supporta i dispositivi con bootloader sbloccati.
AICore non è riuscito con il tipo di errore 1-DOWNLOAD_ERROR e il codice di errore 0-UNKNOWN: la funzionalità … non è riuscita con lo stato di errore 0 e l'errore esz: UNAVAILABLE: impossibile risolvere l'host …	Mantieni la connessione di rete, attendi qualche minuto e riprova.

Nota: sebbene i vari reset siano comuni per gli sviluppatori, sono molto meno frequenti per gli utenti. Inoltre, tutti questi casi di errore di configurazione possono essere rilevati dalle API checkFeatureStatus() o checkStatus(). Assicurati di chiamare prima checkFeatureStatus() o checkStatus() prima di mostrare qualsiasi UI correlata, in modo che gli utenti della tua app non vedano questi errori in nessun caso.

Codice campione

• Esplora l'esempio di codice dell'API ML Kit Speech Recognition su GitHub