SpeechRecognizer
open class SpeechRecognizer
kotlin.Any | |
↳ | android.speech.SpeechRecognizer |
This class provides access to the speech recognition service. This service allows access to the speech recognizer. Do not instantiate this class directly, instead, call SpeechRecognizer#createSpeechRecognizer(Context)
, or SpeechRecognizer#createOnDeviceSpeechRecognizer(Context)
. This class's methods must be invoked only from the main application thread.
Important: the caller MUST invoke destroy()
on a SpeechRecognizer object when it is no longer needed.
The implementation of this API is likely to stream audio to remote servers to perform speech recognition. As such this API is not intended to be used for continuous recognition, which would consume a significant amount of battery and bandwidth.
Please note that the application must have android.Manifest.permission#RECORD_AUDIO
permission to use this class.
Summary
Constants | |
---|---|
static String |
Key used to retrieve a float array from the |
static String |
Key used to retrieve a |
static Int |
Audio recording error. |
static Int |
The service does not allow to check for support. |
static Int |
The service does not support listening to model downloads events. |
static Int |
Other client side errors. |
static Int |
Insufficient permissions |
static Int |
Requested language is not available to be used with the current recognizer. |
static Int |
Requested language is supported, but not available currently (e.g. not downloaded yet). |
static Int |
Other network related errors. |
static Int |
Network operation timed out. |
static Int |
No recognition result matched. |
static Int |
RecognitionService busy. |
static Int |
Server sends error status. |
static Int |
Server has been disconnected, e. |
static Int |
No speech input |
static Int |
Too many requests from the same client. |
static String |
Key used to retrieve the level of confidence of the detected language of the most recent audio chunk, represented by an |
static Int | |
static Int | |
static Int | |
static Int | |
static String |
Key used to retrieve the result of the language switch of the most recent audio chunk, represented by an |
static Int |
Switch attempted and failed. |
static Int |
Switch not attempted. |
static Int |
Switch skipped because the language model is missing or the language is not allowlisted for auto switch. |
static Int |
Switch attempted and succeeded. |
static String |
Key used to receive an ArrayList< |
static String |
Key used to retrieve an ArrayList< |
static String |
Key used to retrieve an |
static String |
Key used to retrieve an ArrayList< |
Public methods | |
---|---|
open Unit |
cancel() Cancels the speech recognition. |
open Unit |
checkRecognitionSupport(recognizerIntent: Intent, executor: Executor, supportListener: RecognitionSupportCallback) Checks whether |
open static SpeechRecognizer |
createOnDeviceSpeechRecognizer(context: Context) Factory method to create a new |
open static SpeechRecognizer! |
createSpeechRecognizer(context: Context!) Factory method to create a new |
open static SpeechRecognizer! |
createSpeechRecognizer(context: Context!, serviceComponent: ComponentName!) Factory method to create a new |
open Unit |
destroy() Destroys the |
open static Boolean |
isOnDeviceRecognitionAvailable(context: Context) Checks whether an on-device speech recognition service is available on the system. |
open static Boolean |
isRecognitionAvailable(context: Context) Checks whether a speech recognition service is available on the system. |
open Unit |
setRecognitionListener(listener: RecognitionListener!) Sets the listener that will receive all the callbacks. |
open Unit |
startListening(recognizerIntent: Intent!) Starts listening for speech. |
open Unit |
Stops listening for speech. |
open Unit |
triggerModelDownload(recognizerIntent: Intent) Attempts to download the support for the given |
open Unit |
triggerModelDownload(recognizerIntent: Intent, executor: Executor, listener: ModelDownloadListener) Attempts to download the support for the given |
Constants
CONFIDENCE_SCORES
static val CONFIDENCE_SCORES: String
Key used to retrieve a float array from the Bundle
passed to the RecognitionListener#onResults(Bundle)
and RecognitionListener#onPartialResults(Bundle)
methods. The array should be the same size as the ArrayList provided in RESULTS_RECOGNITION
, and should contain values ranging from 0.0 to 1.0, or -1 to represent an unavailable confidence score.
Confidence values close to 1.0 indicate high confidence (the speech recognizer is confident that the recognition result is correct), while values close to 0.0 indicate low confidence.
This value is optional and might not be provided.
Value: "confidence_scores"
DETECTED_LANGUAGE
static val DETECTED_LANGUAGE: String
Key used to retrieve a String
representation of the IETF language tag (as defined by BCP 47, e.g., "en-US", "de-DE") of the detected language of the most recent audio chunk.
This info is returned to the client in the Bundle
passed to RecognitionListener#onLanguageDetection(Bundle)
only if RecognizerIntent#EXTRA_ENABLE_LANGUAGE_DETECTION
is set. Additionally, if RecognizerIntent#EXTRA_LANGUAGE_DETECTION_ALLOWED_LANGUAGES
are listed, the detected language is constrained to be one from the list.
Value: "detected_language"
ERROR_CANNOT_CHECK_SUPPORT
static val ERROR_CANNOT_CHECK_SUPPORT: Int
The service does not allow to check for support.
Value: 14
ERROR_CANNOT_LISTEN_TO_DOWNLOAD_EVENTS
static val ERROR_CANNOT_LISTEN_TO_DOWNLOAD_EVENTS: Int
The service does not support listening to model downloads events.
Value: 15
ERROR_INSUFFICIENT_PERMISSIONS
static val ERROR_INSUFFICIENT_PERMISSIONS: Int
Insufficient permissions
Value: 9
ERROR_LANGUAGE_NOT_SUPPORTED
static val ERROR_LANGUAGE_NOT_SUPPORTED: Int
Requested language is not available to be used with the current recognizer.
Value: 12
ERROR_LANGUAGE_UNAVAILABLE
static val ERROR_LANGUAGE_UNAVAILABLE: Int
Requested language is supported, but not available currently (e.g. not downloaded yet).
Value: 13
ERROR_NETWORK
static val ERROR_NETWORK: Int
Other network related errors.
Value: 2
ERROR_NETWORK_TIMEOUT
static val ERROR_NETWORK_TIMEOUT: Int
Network operation timed out.
Value: 1
ERROR_NO_MATCH
static val ERROR_NO_MATCH: Int
No recognition result matched.
Value: 7
ERROR_RECOGNIZER_BUSY
static val ERROR_RECOGNIZER_BUSY: Int
RecognitionService busy.
Value: 8
ERROR_SERVER_DISCONNECTED
static val ERROR_SERVER_DISCONNECTED: Int
Server has been disconnected, e.g. because the app has crashed.
Value: 11
ERROR_SPEECH_TIMEOUT
static val ERROR_SPEECH_TIMEOUT: Int
No speech input
Value: 6
ERROR_TOO_MANY_REQUESTS
static val ERROR_TOO_MANY_REQUESTS: Int
Too many requests from the same client.
Value: 10
LANGUAGE_DETECTION_CONFIDENCE_LEVEL
static val LANGUAGE_DETECTION_CONFIDENCE_LEVEL: String
Key used to retrieve the level of confidence of the detected language of the most recent audio chunk, represented by an int
value prefixed by LANGUAGE_DETECTION_CONFIDENCE_LEVEL_
.
This info is returned to the client in the Bundle
passed to RecognitionListener#onLanguageDetection(Bundle)
only if RecognizerIntent#EXTRA_ENABLE_LANGUAGE_DETECTION
is set.
Value: "language_detection_confidence_level"
LANGUAGE_DETECTION_CONFIDENCE_LEVEL_CONFIDENT
static val LANGUAGE_DETECTION_CONFIDENCE_LEVEL_CONFIDENT: Int
Value: 2
LANGUAGE_DETECTION_CONFIDENCE_LEVEL_HIGHLY_CONFIDENT
static val LANGUAGE_DETECTION_CONFIDENCE_LEVEL_HIGHLY_CONFIDENT: Int
Value: 3
LANGUAGE_DETECTION_CONFIDENCE_LEVEL_NOT_CONFIDENT
static val LANGUAGE_DETECTION_CONFIDENCE_LEVEL_NOT_CONFIDENT: Int
Value: 1
LANGUAGE_DETECTION_CONFIDENCE_LEVEL_UNKNOWN
static val LANGUAGE_DETECTION_CONFIDENCE_LEVEL_UNKNOWN: Int
Value: 0
LANGUAGE_SWITCH_RESULT
static val LANGUAGE_SWITCH_RESULT: String
Key used to retrieve the result of the language switch of the most recent audio chunk, represented by an int
value prefixed by LANGUAGE_SWITCH_
.
This info is returned to the client in the Bundle
passed to the RecognitionListener#onLanguageDetection(Bundle)
only if RecognizerIntent#EXTRA_ENABLE_LANGUAGE_SWITCH
is set.
Value: "language_switch_result"
LANGUAGE_SWITCH_RESULT_FAILED
static val LANGUAGE_SWITCH_RESULT_FAILED: Int
Switch attempted and failed.
Value: 2
LANGUAGE_SWITCH_RESULT_NOT_ATTEMPTED
static val LANGUAGE_SWITCH_RESULT_NOT_ATTEMPTED: Int
Switch not attempted.
Value: 0
LANGUAGE_SWITCH_RESULT_SKIPPED_NO_MODEL
static val LANGUAGE_SWITCH_RESULT_SKIPPED_NO_MODEL: Int
Switch skipped because the language model is missing or the language is not allowlisted for auto switch.
Value: 3
LANGUAGE_SWITCH_RESULT_SUCCEEDED
static val LANGUAGE_SWITCH_RESULT_SUCCEEDED: Int
Switch attempted and succeeded.
Value: 1
RECOGNITION_PARTS
static val RECOGNITION_PARTS: String
Key used to receive an ArrayList<RecognitionPart
> object from the Bundle
passed to the RecognitionListener#onResults(Bundle)
and RecognitionListener#onSegmentResults(Bundle)
methods.
A single SpeechRecognizer
result is represented as a String
. Each word of the resulting String, as well as any potential adjacent punctuation, is represented by a RecognitionPart
item from the ArrayList retrieved by this key.
Value: "recognition_parts"
RESULTS_ALTERNATIVES
static val RESULTS_ALTERNATIVES: String
Key used to retrieve an ArrayList<AlternativeSpans
> from the Bundle
passed to the RecognitionListener#onResults(Bundle)
and RecognitionListener#onPartialResults(Bundle)
methods. The list should be the same size as the ArrayList provided in RESULTS_RECOGNITION
.
A single SpeechRecognizer
result is represented as a String
. For a specific span (substring) of the originally recognized result string the recognizer provides a list of alternative hypotheses in the form of an AlternativeSpan
object. Alternatives for different spans of a result string are listed in an AlternativeSpans
object. Each item from the ArrayList retrieved by this key corresponds to a single result string provided in RESULTS_RECOGNITION
.
This value is optional and might not be provided.
Value: "results_alternatives"
RESULTS_RECOGNITION
static val RESULTS_RECOGNITION: String
Key used to retrieve an ArrayList<String>
from the Bundle
passed to the RecognitionListener#onResults(Bundle)
and RecognitionListener#onPartialResults(Bundle)
methods. These strings are the possible recognition results, where the first element is the most likely candidate.
Value: "results_recognition"
TOP_LOCALE_ALTERNATIVES
static val TOP_LOCALE_ALTERNATIVES: String
Key used to retrieve an ArrayList<String
> containing representations of the IETF language tags (as defined by BCP 47, e.g., "en-US", "en-UK") denoting the alternative locales for the same language retrieved by the key DETECTED_LANGUAGE
. This info is returned to the client in the Bundle
passed to RecognitionListener#onLanguageDetection(Bundle)
only if RecognizerIntent#EXTRA_ENABLE_LANGUAGE_DETECTION
is set.
Value: "top_locale_alternatives"
Public methods
cancel
open fun cancel(): Unit
Cancels the speech recognition. Please note that setRecognitionListener(android.speech.RecognitionListener)
should be called beforehand, otherwise no notifications will be received.
This method must be called from the main thread of your app.
checkRecognitionSupport
open fun checkRecognitionSupport(
recognizerIntent: Intent,
executor: Executor,
supportListener: RecognitionSupportCallback
): Unit
Checks whether recognizerIntent
is supported by SpeechRecognizer#startListening(Intent)
.
Parameters | |
---|---|
recognizerIntent |
Intent: contains parameters for the recognition to be performed. The intent may also contain optional extras. See RecognizerIntent for the list of supported extras, any unlisted extra might be ignored. This value cannot be null . |
supportListener |
RecognitionSupportCallback: the listener on which to receive the support query results. This value cannot be null . |
executor |
Executor: This value cannot be null . Callback and listener events are dispatched through this Executor , providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor() . Otherwise, provide an Executor that dispatches to an appropriate thread. |
createOnDeviceSpeechRecognizer
open static fun createOnDeviceSpeechRecognizer(context: Context): SpeechRecognizer
Factory method to create a new SpeechRecognizer
.
Please note that setRecognitionListener(android.speech.RecognitionListener)
should be called before dispatching any command to the created SpeechRecognizer
, otherwise no notifications will be received.
Important: the caller MUST invoke destroy()
on a SpeechRecognizer object when it is no longer needed.
This method must be called from the main thread of your app.
Parameters | |
---|---|
context |
Context: in which to create SpeechRecognizer This value cannot be null . |
Return | |
---|---|
SpeechRecognizer |
a new on-device SpeechRecognizer . This value cannot be null . |
Exceptions | |
---|---|
java.lang.UnsupportedOperationException |
iff isOnDeviceRecognitionAvailable(android.content.Context) is false |
createSpeechRecognizer
open static fun createSpeechRecognizer(context: Context!): SpeechRecognizer!
Factory method to create a new SpeechRecognizer
. Please note that setRecognitionListener(android.speech.RecognitionListener)
should be called before dispatching any command to the created SpeechRecognizer
, otherwise no notifications will be received.
Important: the caller MUST invoke destroy()
on a SpeechRecognizer object when it is no longer needed.
For apps targeting Android 11 (API level 30) interaction with a speech recognition service requires element to be added to the manifest file:
<code><queries> <intent> <action android:name="android.speech.RecognitionService" /> </intent> </queries> </code>
This method must be called from the main thread of your app.
Parameters | |
---|---|
context |
Context!: in which to create SpeechRecognizer |
Return | |
---|---|
SpeechRecognizer! |
a new SpeechRecognizer |
createSpeechRecognizer
open static fun createSpeechRecognizer(
context: Context!,
serviceComponent: ComponentName!
): SpeechRecognizer!
Factory method to create a new SpeechRecognizer
. Please note that setRecognitionListener(android.speech.RecognitionListener)
should be called before dispatching any command to the created SpeechRecognizer
, otherwise no notifications will be received. Use this version of the method to specify a specific service to direct this SpeechRecognizer
to.
Important: the caller MUST invoke destroy()
on a SpeechRecognizer object when it is no longer needed.
Important: before calling this method, please check via android.content.pm.PackageManager#queryIntentServices(Intent, int)
that serviceComponent
actually exists and provides RecognitionService#SERVICE_INTERFACE
. Normally you would not use this; call createSpeechRecognizer(android.content.Context)
to use the system default recognition service instead or createOnDeviceSpeechRecognizer(android.content.Context)
to use on-device recognition.
For apps targeting Android 11 (API level 30) interaction with a speech recognition service requires element to be added to the manifest file:
<code><queries> <intent> <action android:name="android.speech.RecognitionService" /> </intent> </queries> </code>
This method must be called from the main thread of your app.
Parameters | |
---|---|
context |
Context!: in which to create SpeechRecognizer |
serviceComponent |
ComponentName!: the ComponentName of a specific service to direct this SpeechRecognizer to |
Return | |
---|---|
SpeechRecognizer! |
a new SpeechRecognizer |
isOnDeviceRecognitionAvailable
open static fun isOnDeviceRecognitionAvailable(context: Context): Boolean
Checks whether an on-device speech recognition service is available on the system. If this method returns false
, SpeechRecognizer#createOnDeviceSpeechRecognizer(Context)
will fail.
Parameters | |
---|---|
context |
Context: with which on-device SpeechRecognizer will be created This value cannot be null . |
Return | |
---|---|
Boolean |
true if on-device recognition is available, false otherwise |
isRecognitionAvailable
open static fun isRecognitionAvailable(context: Context): Boolean
Checks whether a speech recognition service is available on the system. If this method returns false
, SpeechRecognizer#createSpeechRecognizer(Context)
will fail.
Parameters | |
---|---|
context |
Context: with which SpeechRecognizer will be created This value cannot be null . |
Return | |
---|---|
Boolean |
true if recognition is available, false otherwise |
setRecognitionListener
open fun setRecognitionListener(listener: RecognitionListener!): Unit
Sets the listener that will receive all the callbacks. The previous unfinished commands will be executed with the old listener, while any following command will be executed with the new listener.
This method must be called from the main thread of your app.
Parameters | |
---|---|
listener |
RecognitionListener!: listener that will receive all the callbacks from the created SpeechRecognizer , this must not be null. |
startListening
open fun startListening(recognizerIntent: Intent!): Unit
Starts listening for speech. Please note that setRecognitionListener(android.speech.RecognitionListener)
should be called beforehand, otherwise no notifications will be received.
This method must be called from the main thread of your app.
Parameters | |
---|---|
recognizerIntent |
Intent!: contains parameters for the recognition to be performed. The intent may also contain optional extras, see RecognizerIntent . If these values are not set explicitly, default values will be used by the recognizer. |
stopListening
open fun stopListening(): Unit
Stops listening for speech. Speech captured so far will be recognized as if the user had stopped speaking at this point.
Note that in the default case, this does not need to be called, as the speech endpointer will automatically stop the recognizer listening when it determines speech has completed. However, you can manipulate endpointer parameters directly using the intent extras defined in RecognizerIntent
, in which case you may sometimes want to manually call this method to stop listening sooner.
Upon invocation clients must wait until RecognitionListener#onResults
or RecognitionListener#onError
are invoked before calling SpeechRecognizer#startListening
again. Otherwise such an attempt would be rejected by recognition service.
Please note that setRecognitionListener(android.speech.RecognitionListener)
should be called beforehand, otherwise no notifications will be received.
This method must be called from the main thread of your app.
triggerModelDownload
open fun triggerModelDownload(recognizerIntent: Intent): Unit
Attempts to download the support for the given recognizerIntent
. This might trigger user interaction to approve the download. Callers can verify the status of the request via checkRecognitionSupport(android.content.Intent,java.util.concurrent.Executor,android.speech.RecognitionSupportCallback)
.
Parameters | |
---|---|
recognizerIntent |
Intent: contains parameters for the recognition to be performed. The intent may also contain optional extras, see RecognizerIntent . This value cannot be null . |
triggerModelDownload
open fun triggerModelDownload(
recognizerIntent: Intent,
executor: Executor,
listener: ModelDownloadListener
): Unit
Attempts to download the support for the given recognizerIntent
. This might trigger user interaction to approve the download. Callers can verify the status of the request via checkRecognitionSupport(android.content.Intent,java.util.concurrent.Executor,android.speech.RecognitionSupportCallback)
.
The updates about the model download request are received via the given ModelDownloadListener
:
ModelDownloadListener#onSuccess()
will be called directly. The model can be safely used afterwards. RecognitionService
has started the download, ModelDownloadListener#onProgress(int)
will be called an unspecified (zero or more) number of times until the download is complete. When the download finishes, ModelDownloadListener#onSuccess()
will be called. The model can be safely used afterwards. RecognitionService
has only scheduled the download, but won't satisfy it immediately, ModelDownloadListener#onScheduled()
will be called. There will be no further updates on this listener. ModelDownloadListener#onError(int)
will be called.Parameters | |
---|---|
recognizerIntent |
Intent: contains parameters for the recognition to be performed. The intent may also contain optional extras, see RecognizerIntent . This value cannot be null . |
executor |
Executor: for dispatching listener callbacks This value cannot be null . Callback and listener events are dispatched through this Executor , providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor() . Otherwise, provide an Executor that dispatches to an appropriate thread. |
listener |
ModelDownloadListener: on which to receive updates about the model download request. This value cannot be null . |