GenAI Speech Recognition API

Bu API, alfa sürümünde sunulur ve herhangi bir HDS'ye (Hizmet Düzeyi Sözleşmesi) veya kullanımdan kaldırma politikasına tabi değildir. Bu API'de geriye dönük uyumluluğu bozan değişiklikler yapılabilir.

ML Kit'in GenAI Speech Recognition API'si ile ses içeriklerini metne dönüştürebilirsiniz. Bu API aşağıdaki modları destekler:

• Gelişmiş: Speech Recognition API, daha geniş dil kapsamı ve daha iyi genel kalite sağlayan üretken yapay zeka modelini kullanır. Her dil için ayrı bir dil paketi indirmeniz gerekmez. Bu sayede depolama alanından tasarruf edersiniz.
• Temel: Speech Recognition API, SpeechRecognizer API'ye benzer şekilde geleneksel cihaz üzerinde konuşma tanıma modelini kullanır.

Speech Recognition API, ses içeriğini aynı dilde metne dönüştürür. Sesi farklı bir dilde metne dönüştürmek için Speech Translation API'yi kullanın.

Temel özellikler

• Mikrofondan veya ses dosyasından akış girişini yakalar.
• AudioSource.fromFile() veya AudioSource.fromUri() yöntemleriyle önceden kaydedilmiş bir dosyanın tamamını metne dönüştürür. Ayrıntılar için Ses girişi koşulları başlıklı makaleye bakın.
• Akış girişleri için, kullanıcı arayüzü animasyonlarını senkronize etmenize, altyazı oluşturmanıza veya kelimeleri konuşulurken vurgulamanıza yardımcı olmak amacıyla tanınan her kelimenin tam başlangıç zamanını sağlar. Tanınan her kelimenin başlangıç zamanı (milisaniye cinsinden), etkinliğin başlangıcından (0 zaman damgası) itibaren bir ofsettir.
• Metne dönüştürülen metin, sürekli bir akış olarak sağlanır. Bu akış, nihai olarak tanınan metin haline gelmeden önce kısmi olabilir (ve değişebilir).

Örnek sonuçlar

Ses	Mod	Yerel ayar	Çeviri yazı
audio_2	Gelişmiş	es-ES	"Este es un mensaje corto."
audio_1	Temel	en-US	"Bu kısa bir mesajdır"

Platformun Speech Recognition API'si ile karşılaştırma

ML Kit Speech Recognition API, Basic modunu kullanırken platform SpeechRecognizer API'sinin temel işlevlerini kapsar. ML Kit'in önemli bir avantajı, belirli bir platform sürümüne bağlı olmamasıdır.

Ayrıca ML Kit Speech Recognition API, gelişmiş modu kullanırken cihaz üzerinde Gemini modelini kullanarak konuşma tanımayı destekler ve daha geniş bir dil kapsamı sunar.

Not: Gelişmiş mod, belirli cihazlarda kullanılabilir. Ayrıntılar için Desteklenen cihazlar bölümüne göz atın.

Başlayın

Not: SDK için minSdkVersion 26 veya sonraki sürümler gerekir. Her modun çalışma zamanı gereksinimleri için Desteklenen cihazlar bölümüne bakın.

ML Kit Speech Recognition API'yi build.gradle yapılandırmanıza bağımlılık olarak ekleyin:

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

Speech Recognition API'yi uygulamanıza entegre etmek için bir SpeechRecognizer istemcisi oluşturun. Gerekli cihaz üzerinde model özelliklerinin durumunu kontrol edin ve cihazda yoksa modeli indirin. Ses girişinizi SpeechRecognizerRequest içinde hazırladıktan sonra, Kotlin akışından çıkış almak için istemciyi kullanarak çıkarım yapın. Son olarak, kaynakları serbest bırakmak için istemciyi kapatmayı unutmayın.

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

Ses girişi şartları

GenAI Speech Recognition API, mikrofondan veya dosya tanımlayıcı aracılığıyla özel bir kaynaktan girişi destekler.

AudioSource.fromPfd(parcelFileDescriptor) kullanıyorsanız giriş sesinin aşağıdaki katı koşulları karşılaması gerekir:

• Biçim: Ham, başlıksız 16 bit PCM.
• Kanallar: Mono (tek kanal).
• Örnek hızı: 16 kHz.

Çoğu kullanım alanında, bu kısıtlamaları otomatik olarak işlediği için AudioSource.fromMic() önerilir.

Desteklenen ses girişi biçimleri

Speech Recognition API, aşağıdaki ses girişi biçimlerini destekler:

• MP3, WAV, FLAC, M4A ve OGG dosyalarının kodu cihazda otomatik olarak çözülür.
• Ham, başlıksız ses (.raw veya .pcm) 16 bit PCM, 16 kHz, mono biçiminde olmalıdır.

Biçim geçersiz veya desteklenmiyorsa tanıma işlemi başladığında ErrorResponse değeri döndürülür.

Speech Recognition API'yi uygulama

Speech Recognition API'yi kullanarak sesi metne dönüştürme ve kelime zamanlamasını kullanma hakkında bilgi edinin.

Sesi metne dönüştürme

Speech Recognition API, cihaz mikrofonundan, önceden kaydedilmiş dosyalardan veya ParcelFileDescriptor nesnesi kullanan özel ardışık düzenlerden ses girişini destekler.

Ses verilerinizi hazırlamak için aşağıdaki tabloda listelenen fabrika yöntemlerinden birini kullanarak bir AudioSource nesnesi oluşturun:

Yöntem	Ses modu	Önerilen kullanım alanı
AudioSource.fromMic()	STREAMING	Kullanıcıdan canlı ses girişi alın. RECORD_AUDIO izni gerekir.
AudioSource.fromFile(file) AudioSource.fromUri(context, uri)	ONE_SHOT	Önceden kaydedilmiş ses dosyalarını metne dönüştürme Standart dosya biçimlerinin kodunu doğrudan cihazda otomatik olarak çözer.
AudioSource.fromPfd(pfd, mode) AudioSource.fromPfd(pfd, mode, audioFormat)	STREAMING veya ONE_SHOT	Özel ses ardışık düzenleri (ör. uygulamanızın başka bir yerinde işlenen ses verileri).

AudioSource.Mode sabiti, API'nin gelen sesi nasıl işleyeceğini kontrol eder:

• AudioSource.Mode.STREAMING sabiti, tanıyıcıyı ses verileri geldikçe kısmi ve nihai transkript sonuçlarını sürekli olarak döndürecek şekilde yapılandırır. Özel bir ParcelFileDescriptor nesnesi sağladığınızda, verileri akışa gerçek zamanlı bir hızda yazmanız gerekir (standart 16 kHz, 16 bit, mono PCM ses için saniyede yaklaşık 32.000 bayt). Verilerin çok hızlı yazılması, arabelleğin taşmasına neden olabilir.
• AudioSource.Mode.ONE_SHOT sabiti, çıkarım yapmadan ve nihai transkripti sunmadan önce tüm ses kaynağının aktarılmasını bekleyecek şekilde tanıma aracını yapılandırır. Ses verilerini mümkün olduğunca hızlı yazabilirsiniz ancak dosya sonunu belirtmek için dosya tanımlayıcınızın yazma ucunu kapatmanız gerekir. Bu dosya sonu sinyali alınana kadar nihai transkripsiyon sonucu teslim edilmez.

Not: AudioSource nesnesi, temel ParcelFileDescriptor nesnesinin sahipliğini alır. Tanıma işlemi tamamlandığında AudioSource.close() yöntemini çağırmayı unutmayın.

Aşağıdaki örnekte, önceden kaydedilmiş bir ses dosyasının transkripti oluşturulmaktadır:

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

Kelime zamanlamasını kullanma

İsteğinizin recognitionOptions yapılandırma bloğunda enableWordTiming parametresini true olarak ayarlayarak tanınan her kelimenin başlangıç zamanını isteyebilirsiniz.

Kelime zamanlaması etkinleştirildiğinde her SpeechRecognizerResponse.FinalTextResponse nesnesi, SpeechRecognizerResponse.WordTiming nesnelerinin listesini içeren bir wordTimings özelliği içerir. Her nesne, konuşma tanıma oturumunun başından itibaren tanınan kelime dizesini (text) ve milisaniye cinsinden ofsetini (timestampMs) sağlar. Kelime zamanlaması devre dışı bırakıldığında (varsayılan ayar) wordTimings listesi boş döndürülür.

Aşağıdaki kod örneğinde, kelime zamanlamasının nasıl yapılandırılacağı ve etkinleştirileceği gösterilmektedir:

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

Not: Kelime zamanlaması özelliği yalnızca akış ses kaynakları kullanılırken desteklenir. Örneğin, AudioSource.Mode.STREAMING sabitiyle AudioSource.fromMic() yönteminden canlı giriş veya AudioSource.fromPfd() yönteminden özel akış ardışık düzenleri. AudioSource.fromFile() veya AudioSource.fromUri() yöntemleri tarafından döndürülenler gibi statik bir ONE_SHOT ses kaynağında kelime zamanlaması etkinleştirilmiş olarak startRecognition() yöntemini çağırmak, bir IllegalArgumentException nesnesi oluşturur.

Desteklenen diller

Mod	Yerel ayarlar
Gelişmiş	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)
Temel	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)

Not: Beta sürümündeki dillerde kelime hata oranı biraz daha yüksek olabilir. Ek yerel ayarlar mevcuttur. Performanslarını kendi kullanım alanınıza göre değerlendirin.

Desteklenen cihazlar

Mod	Desteklenen cihazlar
Temel	API düzeyi 31 ve sonraki sürümleri kullanan Android cihazlar.
Gelişmiş	Pixel 10 ve Pixel 11 serisi ile aşağıdaki yonga setlerinde Gemini Nano bulunan cihazlar (Samsung Galaxy S26, Z Flip8 ve Z Fold8 serisi dahil): Qualcomm Snapdragon: SM8750, SM8845, SM8850, SM8950, SM8975 MediaTek Dimensity: MT6991, MT6993, MT6995 Samsung Exynos: Exynos 2600

Sık karşılaşılan kurulum sorunları

Not: Bu API, bootloader'ın kilidi açılmış cihazlarda desteklenmez.

ML Kit GenAI API'leri, Gemini Nano'ya erişmek için Android AICore uygulamasını kullanır. Bir cihaz yeni kurulduğunda (sıfırlama dahil) veya AICore uygulaması yeni sıfırlandığında (ör. veriler temizlendiğinde, kaldırılıp yeniden yüklendiğinde) AICore uygulamasının başlatma işlemini (sunucudan en son yapılandırmaları indirme dahil) tamamlamak için yeterli zamanı olmayabilir. Bu nedenle, ML Kit GenAI API'leri beklendiği gibi çalışmayabilir. Karşılaşabileceğiniz yaygın kurulum hata mesajları ve bunları nasıl ele alacağınız aşağıda açıklanmıştır:

Örnek hata mesajı	İtirazı yanıtlama
AICore, 4-CONNECTION_ERROR hata türü ve 601-BINDING_FAILURE hata koduyla başarısız oldu: AICore hizmeti bağlanamadı.	Bu durum, cihaz kurulumundan hemen sonra ML Kit GenAI API'lerini kullanarak uygulamayı yüklediğinizde veya uygulamanız yüklendikten sonra AICore kaldırıldığında ortaya çıkabilir. AICore uygulamasını güncelleyip uygulamanızı yeniden yüklediğinizde sorun çözülecektir.
AICore, 3-PREPARATION_ERROR hata türü ve 606-FEATURE_NOT_FOUND hata koduyla başarısız oldu: ... özelliği kullanılamıyor.	Bu durum, AICore en son yapılandırmaları indirmeyi tamamlamadığında gerçekleşebilir. Cihaz internete bağlıyken güncelleme işlemi genellikle birkaç dakika ile birkaç saat arasında sürer. Cihazı yeniden başlatmak güncellemeyi hızlandırabilir. Cihazın bootloader'ının kilidi açıksa da bu hatayı görürsünüz. Bu API, bootloader'ının kilidi açık olan cihazları desteklemez.
AICore, 1-DOWNLOAD_ERROR hata türü ve 0-UNKNOWN hata koduyla başarısız oldu: ... özelliği, 0 hata durumu ve esz: UNAVAILABLE: ... ana makinesi çözümlenemiyor hatasıyla başarısız oldu.	Ağ bağlantısını koruyun, birkaç dakika bekleyin ve tekrar deneyin.

Not: Çeşitli sıfırlama işlemleri geliştiriciler için yaygın olsa da kullanıcılar için çok daha az sıklıkta gerçekleşir. Ayrıca, tüm bu kurulum hatası durumları checkFeatureStatus() veya checkStatus() API'leri tarafından yakalanabilir. İlgili kullanıcı arayüzünü göstermeden önce checkFeatureStatus() veya checkStatus() yöntemini çağırdığınızdan emin olun. Böylece uygulama kullanıcılarınız bu hataları hiçbir durumda görmez.

Örnek kod

• GitHub'da ML Kit Speech Recognition API kod örneğini inceleyin.