SpeechRecognizer

public class SpeechRecognizer
extends Object

java.lang.Object
   ↳ 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 Manifest.permission.RECORD_AUDIO permission to use this class.

Summary

Constants

String CONFIDENCE_SCORES

Key used to retrieve a float array from the Bundle passed to the RecognitionListener#onResults(Bundle) and RecognitionListener#onPartialResults(Bundle) methods.

String DETECTED_LANGUAGE

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.

int ERROR_AUDIO

Audio recording error.

int ERROR_CANNOT_CHECK_SUPPORT

The service does not allow to check for support.

int ERROR_CANNOT_LISTEN_TO_DOWNLOAD_EVENTS

The service does not support listening to model downloads events.

int ERROR_CLIENT

Other client side errors.

int ERROR_INSUFFICIENT_PERMISSIONS

Insufficient permissions

int ERROR_LANGUAGE_NOT_SUPPORTED

Requested language is not available to be used with the current recognizer.

int ERROR_LANGUAGE_UNAVAILABLE

Requested language is supported, but not available currently (e.g. not downloaded yet).

int ERROR_NETWORK

Other network related errors.

int ERROR_NETWORK_TIMEOUT

Network operation timed out.

int ERROR_NO_MATCH

No recognition result matched.

int ERROR_RECOGNIZER_BUSY

RecognitionService busy.

int ERROR_SERVER

Server sends error status.

int ERROR_SERVER_DISCONNECTED

Server has been disconnected, e.g. because the app has crashed.

int ERROR_SPEECH_TIMEOUT

No speech input

int ERROR_TOO_MANY_REQUESTS

Too many requests from the same client.

String LANGUAGE_DETECTION_CONFIDENCE_LEVEL

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_.

int LANGUAGE_DETECTION_CONFIDENCE_LEVEL_CONFIDENT

int LANGUAGE_DETECTION_CONFIDENCE_LEVEL_HIGHLY_CONFIDENT

int LANGUAGE_DETECTION_CONFIDENCE_LEVEL_NOT_CONFIDENT

int LANGUAGE_DETECTION_CONFIDENCE_LEVEL_UNKNOWN

String LANGUAGE_SWITCH_RESULT

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_.

int LANGUAGE_SWITCH_RESULT_FAILED

Switch attempted and failed.

int LANGUAGE_SWITCH_RESULT_NOT_ATTEMPTED

Switch not attempted.

int LANGUAGE_SWITCH_RESULT_SKIPPED_NO_MODEL

Switch skipped because the language model is missing or the language is not allowlisted for auto switch.

int LANGUAGE_SWITCH_RESULT_SUCCEEDED

Switch attempted and succeeded.

String RECOGNITION_PARTS

Key used to receive an ArrayList<RecognitionPart> object from the Bundle passed to the RecognitionListener#onResults(Bundle) and RecognitionListener#onSegmentResults(Bundle) methods.

String RESULTS_ALTERNATIVES

Key used to retrieve an ArrayList<AlternativeSpans> from the Bundle passed to the RecognitionListener#onResults(Bundle) and RecognitionListener#onPartialResults(Bundle) methods.

String RESULTS_RECOGNITION

Key used to retrieve an ArrayList<String> from the Bundle passed to the RecognitionListener#onResults(Bundle) and RecognitionListener#onPartialResults(Bundle) methods.

String TOP_LOCALE_ALTERNATIVES

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.

Public methods

void cancel()

Cancels the speech recognition.

void checkRecognitionSupport(Intent recognizerIntent, Executor executor, RecognitionSupportCallback supportListener)

Checks whether recognizerIntent is supported by SpeechRecognizer#startListening(Intent).

static SpeechRecognizer createOnDeviceSpeechRecognizer(Context context)

Factory method to create a new SpeechRecognizer.

static SpeechRecognizer createSpeechRecognizer(Context context)

Factory method to create a new SpeechRecognizer.

static SpeechRecognizer createSpeechRecognizer(Context context, ComponentName serviceComponent)

Factory method to create a new SpeechRecognizer.

void destroy()

Destroys the SpeechRecognizer object.

static boolean isOnDeviceRecognitionAvailable(Context context)

Checks whether an on-device speech recognition service is available on the system.

static boolean isRecognitionAvailable(Context context)

Checks whether a speech recognition service is available on the system.

void setRecognitionListener(RecognitionListener listener)

Sets the listener that will receive all the callbacks.

void startListening(Intent recognizerIntent)

Starts listening for speech.

void stopListening()

Stops listening for speech.

void triggerModelDownload(Intent recognizerIntent)

Attempts to download the support for the given recognizerIntent.

void triggerModelDownload(Intent recognizerIntent, Executor executor, ModelDownloadListener listener)

Attempts to download the support for the given recognizerIntent.

Inherited methods

Constants

CONFIDENCE_SCORES

Added in API level 14
public static final String CONFIDENCE_SCORES

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.

Constant Value: "confidence_scores"

DETECTED_LANGUAGE

Added in API level 34
public static final String DETECTED_LANGUAGE

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.

Constant Value: "detected_language"

ERROR_AUDIO

Added in API level 8
public static final int ERROR_AUDIO

Audio recording error.

Constant Value: 3 (0x00000003)

ERROR_CANNOT_CHECK_SUPPORT

Added in API level 33
public static final int ERROR_CANNOT_CHECK_SUPPORT

The service does not allow to check for support.

Constant Value: 14 (0x0000000e)

ERROR_CANNOT_LISTEN_TO_DOWNLOAD_EVENTS

Added in API level 34
public static final int ERROR_CANNOT_LISTEN_TO_DOWNLOAD_EVENTS

The service does not support listening to model downloads events.

Constant Value: 15 (0x0000000f)

ERROR_CLIENT

Added in API level 8
public static final int ERROR_CLIENT

Other client side errors.

Constant Value: 5 (0x00000005)

ERROR_INSUFFICIENT_PERMISSIONS

Added in API level 8
public static final int ERROR_INSUFFICIENT_PERMISSIONS

Insufficient permissions

Constant Value: 9 (0x00000009)

ERROR_LANGUAGE_NOT_SUPPORTED

Added in API level 31
public static final int ERROR_LANGUAGE_NOT_SUPPORTED

Requested language is not available to be used with the current recognizer.

Constant Value: 12 (0x0000000c)

ERROR_LANGUAGE_UNAVAILABLE

Added in API level 31
public static final int ERROR_LANGUAGE_UNAVAILABLE

Requested language is supported, but not available currently (e.g. not downloaded yet).

Constant Value: 13 (0x0000000d)

ERROR_NETWORK

Added in API level 8
public static final int ERROR_NETWORK

Other network related errors.

Constant Value: 2 (0x00000002)

ERROR_NETWORK_TIMEOUT

Added in API level 8
public static final int ERROR_NETWORK_TIMEOUT

Network operation timed out.

Constant Value: 1 (0x00000001)

ERROR_NO_MATCH

Added in API level 8
public static final int ERROR_NO_MATCH

No recognition result matched.

Constant Value: 7 (0x00000007)

ERROR_RECOGNIZER_BUSY

Added in API level 8
public static final int ERROR_RECOGNIZER_BUSY

RecognitionService busy.

Constant Value: 8 (0x00000008)

ERROR_SERVER

Added in API level 8
public static final int ERROR_SERVER

Server sends error status.

Constant Value: 4 (0x00000004)

ERROR_SERVER_DISCONNECTED

Added in API level 31
public static final int ERROR_SERVER_DISCONNECTED

Server has been disconnected, e.g. because the app has crashed.

Constant Value: 11 (0x0000000b)

ERROR_SPEECH_TIMEOUT

Added in API level 8
public static final int ERROR_SPEECH_TIMEOUT

No speech input

Constant Value: 6 (0x00000006)

ERROR_TOO_MANY_REQUESTS

Added in API level 31
public static final int ERROR_TOO_MANY_REQUESTS

Too many requests from the same client.

Constant Value: 10 (0x0000000a)

LANGUAGE_DETECTION_CONFIDENCE_LEVEL

Added in API level 34
public static final String LANGUAGE_DETECTION_CONFIDENCE_LEVEL

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.

Constant Value: "language_detection_confidence_level"

LANGUAGE_DETECTION_CONFIDENCE_LEVEL_CONFIDENT

Added in API level 34
public static final int LANGUAGE_DETECTION_CONFIDENCE_LEVEL_CONFIDENT

Constant Value: 2 (0x00000002)

LANGUAGE_DETECTION_CONFIDENCE_LEVEL_HIGHLY_CONFIDENT

Added in API level 34
public static final int LANGUAGE_DETECTION_CONFIDENCE_LEVEL_HIGHLY_CONFIDENT

Constant Value: 3 (0x00000003)

LANGUAGE_DETECTION_CONFIDENCE_LEVEL_NOT_CONFIDENT

Added in API level 34
public static final int LANGUAGE_DETECTION_CONFIDENCE_LEVEL_NOT_CONFIDENT

Constant Value: 1 (0x00000001)

LANGUAGE_DETECTION_CONFIDENCE_LEVEL_UNKNOWN

Added in API level 34
public static final int LANGUAGE_DETECTION_CONFIDENCE_LEVEL_UNKNOWN

Constant Value: 0 (0x00000000)

LANGUAGE_SWITCH_RESULT

Added in API level 34
public static final String LANGUAGE_SWITCH_RESULT

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.

Constant Value: "language_switch_result"

LANGUAGE_SWITCH_RESULT_FAILED

Added in API level 34
public static final int LANGUAGE_SWITCH_RESULT_FAILED

Switch attempted and failed.

Constant Value: 2 (0x00000002)

LANGUAGE_SWITCH_RESULT_NOT_ATTEMPTED

Added in API level 34
public static final int LANGUAGE_SWITCH_RESULT_NOT_ATTEMPTED

Switch not attempted.

Constant Value: 0 (0x00000000)

LANGUAGE_SWITCH_RESULT_SKIPPED_NO_MODEL

Added in API level 34
public static final int LANGUAGE_SWITCH_RESULT_SKIPPED_NO_MODEL

Switch skipped because the language model is missing or the language is not allowlisted for auto switch.

Constant Value: 3 (0x00000003)

LANGUAGE_SWITCH_RESULT_SUCCEEDED

Added in API level 34
public static final int LANGUAGE_SWITCH_RESULT_SUCCEEDED

Switch attempted and succeeded.

Constant Value: 1 (0x00000001)

RECOGNITION_PARTS

Added in API level 34
public static final String RECOGNITION_PARTS

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.

Constant Value: "recognition_parts"

RESULTS_ALTERNATIVES

Added in API level 34
public static final String RESULTS_ALTERNATIVES

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.

Constant Value: "results_alternatives"

RESULTS_RECOGNITION

Added in API level 8
public static final String RESULTS_RECOGNITION

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.

Constant Value: "results_recognition"

TOP_LOCALE_ALTERNATIVES

Added in API level 34
public static final String TOP_LOCALE_ALTERNATIVES

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.

Constant Value: "top_locale_alternatives"

Public methods

cancel

Added in API level 8
public void cancel ()

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

Added in API level 33
public void checkRecognitionSupport (Intent recognizerIntent, 
                Executor executor, 
                RecognitionSupportCallback supportListener)

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.

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.

supportListener RecognitionSupportCallback: the listener on which to receive the support query results. This value cannot be null.

createOnDeviceSpeechRecognizer

Added in API level 31
public static SpeechRecognizer createOnDeviceSpeechRecognizer (Context context)

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.

Returns
SpeechRecognizer a new on-device SpeechRecognizer. This value cannot be null.

Throws
UnsupportedOperationException iff isOnDeviceRecognitionAvailable(android.content.Context) is false

createSpeechRecognizer

Added in API level 8
public static SpeechRecognizer createSpeechRecognizer (Context context)

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:

<queries>
   <intent>
     <action
        android:name="android.speech.RecognitionService" />
   </intent>
 </queries>
 

This method must be called from the main thread of your app.

Parameters
context Context: in which to create SpeechRecognizer

Returns
SpeechRecognizer a new SpeechRecognizer

createSpeechRecognizer

Added in API level 8
public static SpeechRecognizer createSpeechRecognizer (Context context, 
                ComponentName serviceComponent)

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

<queries>
   <intent>
     <action
        android:name="android.speech.RecognitionService" />
   </intent>
 </queries>
 

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

Returns
SpeechRecognizer a new SpeechRecognizer

destroy

Added in API level 8
public void destroy ()

Destroys the SpeechRecognizer object.

isOnDeviceRecognitionAvailable

Added in API level 31
public static boolean isOnDeviceRecognitionAvailable (Context context)

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.

Returns
boolean true if on-device recognition is available, false otherwise

isRecognitionAvailable

Added in API level 8
public static boolean isRecognitionAvailable (Context context)

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.

Returns
boolean true if recognition is available, false otherwise

setRecognitionListener

Added in API level 8
public void setRecognitionListener (RecognitionListener listener)

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

Added in API level 8
public void startListening (Intent recognizerIntent)

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

Added in API level 8
public void stopListening ()

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

Added in API level 33
public void triggerModelDownload (Intent recognizerIntent)

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

Added in API level 34
public void triggerModelDownload (Intent recognizerIntent, 
                Executor executor, 
                ModelDownloadListener listener)

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:

  • If the model is already available, ModelDownloadListener#onSuccess() will be called directly. The model can be safely used afterwards.
  • If the 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.
  • If the 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.
  • If the request fails at any time due to a network or scheduling error, 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.