GenAI Speech Recognition API

Ten interfejs API jest oferowany w wersji alfa i nie podlega żadnej gwarancji jakości usług ani żadnym zasadom wycofywania. W tym interfejsie API mogą zostać wprowadzone zmiany, które uniemożliwią zgodność wsteczną.

W interfejsie GenAI Speech Recognition API w ML Kit możesz transkrybować treści audio na tekst. Ten interfejs API obsługuje te tryby:

• Zaawansowany: interfejs Speech Recognition API korzysta z modelu generatywnej AI, który zapewnia szerszą obsługę języków i lepszą ogólną jakość. Nie musisz pobierać osobnego pakietu językowego dla każdego języka, co pozwala zaoszczędzić miejsce na dane.
• Podstawowy: interfejs Speech Recognition API używa tradycyjnego modelu rozpoznawania mowy na urządzeniu, podobnie jak interfejs SpeechRecognizer API.

Interfejs Speech Recognition API transkrybuje treści audio na tekst w tym samym języku. Aby transkrybować dźwięk na tekst w innym języku, użyj interfejsu Speech Translation API.

Najważniejsze funkcje

• Przechwytuje dane wejściowe przesyłane strumieniowo z mikrofonu lub pliku audio.
• Transkrybuje cały nagrany wcześniej plik za pomocą metod AudioSource.fromFile() lub AudioSource.fromUri(). Więcej informacji znajdziesz w artykule Wymagania dotyczące wejścia audio.
• W przypadku danych wejściowych przesyłanych strumieniowo podaje dokładny czas rozpoczęcia każdego rozpoznanego słowa, aby pomóc Ci zsynchronizować animacje interfejsu, wygenerować napisy lub wyróżnić słowa w trakcie ich wypowiadania. Czas rozpoczęcia (w milisekundach) każdego rozpoznanego słowa jest przesunięciem względem początku zdarzenia, czyli sygnatury czasowej 0.
• Transkrybowany tekst jest dostarczany jako ciągły strumień, który początkowo może być częściowy (i może ulec zmianie), zanim stanie się ostatecznym rozpoznanym tekstem.

Przykładowe wyniki

Audio	Tryb	Język	Transkrypcja
audio_2	Zaawansowane	es-ES	"Este es un mensaje corto."
audio_1	Podstawowe	en-US	„To jest krótka wiadomość”

Porównanie z interfejsem Speech Recognition API platformy

Interfejs ML Kit Speech Recognition API obejmuje podstawowe funkcje interfejsu SpeechRecognizer API w trybie podstawowym. Główną zaletą ML Kit jest to, że nie jest on powiązany z konkretną wersją platformy.

Ponadto interfejs API rozpoznawania mowy ML Kit obsługuje rozpoznawanie mowy za pomocą modelu Gemini na urządzeniu w trybie zaawansowanym, co zapewnia obsługę większej liczby języków.

Uwaga: tryb zaawansowany jest dostępny na wybranych urządzeniach. Więcej informacji znajdziesz w sekcji Obsługiwane urządzenia.

Rozpocznij

Uwaga: pakiet SDK wymaga minSdkVersion w wersji 26 lub nowszej. Wymagania dotyczące środowiska wykonawczego w poszczególnych trybach znajdziesz w sekcji Obsługiwane urządzenia.

Dodaj interfejs ML Kit Speech Recognition API jako zależność w konfiguracji build.gradle:

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

Aby zintegrować interfejs Speech Recognition API z aplikacją, utwórz klienta SpeechRecognizer. Sprawdź stan niezbędnych funkcji modelu na urządzeniu i pobierz model, jeśli nie ma go jeszcze na urządzeniu. Po przygotowaniu danych wejściowych audio w SpeechRecognizerRequest uruchom wnioskowanie za pomocą klienta, aby otrzymywać dane wyjściowe strumieniowo z przepływu Kotlin. Na koniec pamiętaj o zamknięciu klienta, aby zwolnić zasoby.

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

Wymagania dotyczące wejścia audio

Interfejs GenAI Speech Recognition API obsługuje dane wejściowe z mikrofonu lub niestandardowego źródła za pomocą deskryptora pliku.

Jeśli używasz AudioSource.fromPfd(parcelFileDescriptor), wejściowy plik audio musi spełniać te rygorystyczne wymagania:

• Format: nieprzetworzony, 16-bitowy PCM bez nagłówka.
• Kanały: mono (1 kanał).
• Częstotliwość próbkowania: 16 kHz.

W większości przypadków zalecamy używanie AudioSource.fromMic(), ponieważ automatycznie obsługuje te ograniczenia.

Obsługiwane formaty wejściowe audio

Interfejs Speech Recognition API obsługuje te formaty wejściowe audio:

• Pliki MP3, WAV, FLAC, M4A i OGG są automatycznie dekodowane na urządzeniu.
• Nieprzetworzony dźwięk bez nagłówka (.raw lub .pcm) musi być w formacie 16-bitowym PCM, 16 kHz, mono.

Jeśli format jest nieprawidłowy lub nieobsługiwany, po rozpoczęciu rozpoznawania zwracana jest wartość ErrorResponse.

Implementowanie interfejsu Speech Recognition API

Oto jak używać interfejsu Speech Recognition API do transkrypcji dźwięku i korzystania z sygnatur czasowych słów.

Transkrypcja dźwięku

Interfejs Speech Recognition API obsługuje dane wejściowe audio z mikrofonu urządzenia, nagranych wcześniej plików lub niestandardowych potoków za pomocą obiektu ParcelFileDescriptor.

Aby przygotować dane audio, utwórz obiekt AudioSource, korzystając z jednej z metod fabrycznych wymienionych w tej tabeli:

Metoda	Tryb „tylko dźwięk”	Zalecane zastosowanie
AudioSource.fromMic()	STREAMING	Przechwytywanie danych głosowych od użytkownika na żywo. Wymaga uprawnienia RECORD_AUDIO.
AudioSource.fromFile(file) AudioSource.fromUri(context, uri)	ONE_SHOT	transkrypcja nagranych wcześniej plików audio, Automatycznie dekoduje standardowe formaty plików bezpośrednio na urządzeniu.
AudioSource.fromPfd(pfd, mode) AudioSource.fromPfd(pfd, mode, audioFormat)	STREAMING lub ONE_SHOT	niestandardowe potoki audio (np. dane audio przetwarzane w innym miejscu w aplikacji).

Stała AudioSource.Mode określa, jak interfejs API przetwarza przychodzący dźwięk:

• Stała AudioSource.Mode.STREAMING konfiguruje rozpoznawanie, aby zwracało częściowe i końcowe wyniki transkrypcji w sposób ciągły w miarę napływania danych audio. Jeśli podasz niestandardowy obiekt ParcelFileDescriptor, musisz zapisywać dane w strumieniu w czasie rzeczywistym (około 32 000 bajtów na sekundę w przypadku standardowego dźwięku PCM 16 kHz, 16-bitowego, mono). Zbyt szybkie zapisywanie danych może spowodować przepełnienie bufora.
• Stała AudioSource.Mode.ONE_SHOT dotyczy nagranego wcześniej dźwięku. Możesz zapisywać dane audio tak szybko, jak to możliwe, a rozpoznawanie mowy będzie je transkrybować szybciej niż w czasie rzeczywistym. Podobnie jak w trybie strumieniowym, dostarcza on ostateczny wynik dla każdego segmentu mowy, gdy tylko zostanie on rozpoznany, a nie pojedynczą transkrypcję na końcu. Aby zasygnalizować koniec pliku, musisz zamknąć koniec zapisu deskryptora pliku: do tego momentu nie zostanie dostarczony wynik ostatniego segmentu, a po nim ukończona odpowiedź.

Uwaga: obiekt AudioSource przejmuje własność obiektu ParcelFileDescriptor. Pamiętaj, aby po zakończeniu rozpoznawania wywołać metodę AudioSource.close().

W tym przykładzie transkrybowany jest nagrany wcześniej plik audio:

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

Używanie synchronizacji słów

Możesz poprosić o czas rozpoczęcia każdego rozpoznanego słowa, ustawiając parametr enableWordTiming na true w bloku konfiguracji recognitionOptions żądania.

Gdy włączone jest określanie czasu słów, każdy obiekt SpeechRecognizerResponse.FinalTextResponse zawiera właściwość wordTimings z listą obiektów SpeechRecognizerResponse.WordTiming. Każdy obiekt zawiera rozpoznany ciąg słów (text) i jego przesunięcie w milisekundach (timestampMs) od początku sesji rozpoznawania mowy. Gdy synchronizacja słów jest wyłączona (ustawienie domyślne), lista wordTimings jest zwracana jako pusta.

Poniższy przykładowy kod pokazuje, jak skonfigurować i włączyć synchronizację słów:

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

Uwaga: funkcja synchronizacji słów jest obsługiwana tylko wtedy, gdy używasz strumieniowych źródeł dźwięku, takich jak dane wejściowe na żywo z metody AudioSource.fromMic() lub niestandardowe potoki strumieniowe z metody AudioSource.fromPfd() ze stałą AudioSource.Mode.STREAMING. Wywołanie metody startRecognition() z włączonymi znacznikami czasu słów na statycznym źródle dźwięku ONE_SHOT, takim jak zwracane przez metody AudioSource.fromFile() lub AudioSource.fromUri(), powoduje zgłoszenie obiektu IllegalArgumentException.

Obsługiwane języki

Tryb	Język
Zaawansowane	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)
Podstawowe	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)

Uwaga: języki w wersji beta mogą mieć nieco wyższy współczynnik błędów słownych. Dostępne są dodatkowe języki. Oceń ich skuteczność na podstawie konkretnego przypadku użycia.

Obsługiwane urządzenia

Tryb	Obsługiwane urządzenia
Podstawowe	urządzenia z Androidem z interfejsem API na poziomie 31 lub wyższym;
Zaawansowane	Urządzenia z serii Pixel 10 i Pixel 11 oraz urządzenia z Gemini Nano z tymi chipsetami (m.in. Samsung Galaxy S26, Z Flip8 i Z Fold8): Qualcomm Snapdragon: SM8750, SM8845, SM8850, SM8950, SM8975 MediaTek Dimensity: MT6991, MT6993, MT6995 Samsung Exynos: Exynos 2600

Typowe problemy z konfiguracją

Uwaga: ten interfejs API nie jest obsługiwany na urządzeniach z odblokowanym programem rozruchowym.

Interfejsy ML Kit GenAI API korzystają z aplikacji Android AICore, aby uzyskać dostęp do Gemini Nano. Gdy urządzenie jest dopiero konfigurowane (w tym resetowane) lub aplikacja AICore jest dopiero resetowana (np. wyczyszczone dane, odinstalowana i ponownie zainstalowana), aplikacja AICore może nie mieć wystarczająco dużo czasu na zakończenie inicjowania (w tym pobranie najnowszych konfiguracji z serwera). W związku z tym interfejsy API ML Kit GenAI mogą nie działać zgodnie z oczekiwaniami. Oto typowe komunikaty o błędach konfiguracji, które mogą się pojawić, oraz sposoby ich rozwiązywania:

Przykładowy komunikat o błędzie	Jak odpowiedzieć
Wystąpił błąd AICore typu 4-CONNECTION_ERROR i kod błędu 601-BINDING_FAILURE: nie udało się powiązać usługi AICore.	Może się tak zdarzyć, gdy zainstalujesz aplikację za pomocą interfejsów API ML Kit GenAI natychmiast po skonfigurowaniu urządzenia lub gdy AICore zostanie odinstalowany po zainstalowaniu aplikacji. Problem powinien zostać rozwiązany po zaktualizowaniu aplikacji AICore i ponownym zainstalowaniu aplikacji.
AICore: błąd typu 3-PREPARATION_ERROR i kod błędu 606-FEATURE_NOT_FOUND: funkcja … jest niedostępna.	Może się tak zdarzyć, gdy AICore nie zakończy pobierania najnowszych konfiguracji. Gdy urządzenie jest połączone z internetem, aktualizacja trwa zwykle od kilku minut do kilku godzin. Ponowne uruchomienie urządzenia może przyspieszyć aktualizację. Pamiętaj, że jeśli program rozruchowy urządzenia jest odblokowany, również zobaczysz ten błąd – ten interfejs API nie obsługuje urządzeń z odblokowanymi programami rozruchowymi.
AICore: błąd typu 1-DOWNLOAD_ERROR i kod błędu 0-UNKNOWN: funkcja … nie powiodła się ze stanem błędu 0 i błędem esz: UNAVAILABLE: nie można rozpoznać hosta …	Utrzymaj połączenie sieciowe, poczekaj kilka minut i spróbuj ponownie.

Uwaga: deweloperzy często resetują różne ustawienia, ale użytkownicy robią to znacznie rzadziej. Wszystkie te przypadki niepowodzenia konfiguracji można też wykryć za pomocą interfejsów API checkFeatureStatus() lub checkStatus(). Zanim wyświetlisz powiązany interfejs, wywołaj checkFeatureStatus() lub checkStatus(), aby użytkownicy aplikacji nie widzieli tych błędów.

Przykładowy kod

• Przykładowy kod interfejsu ML Kit Speech Recognition API znajdziesz na GitHub.