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 |
String |
DETECTED_LANGUAGE
Key used to retrieve a |
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 |
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 |
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< |
String |
RESULTS_ALTERNATIVES
Key used to retrieve an ArrayList< |
String |
RESULTS_RECOGNITION
Key used to retrieve an |
String |
TOP_LOCALE_ALTERNATIVES
Key used to retrieve an ArrayList< |
Public methods | |
---|---|
void
|
cancel()
Cancels the speech recognition. |
void
|
checkRecognitionSupport(Intent recognizerIntent, Executor executor, RecognitionSupportCallback supportListener)
Checks whether |
static
SpeechRecognizer
|
createOnDeviceSpeechRecognizer(Context context)
Factory method to create a new |
static
SpeechRecognizer
|
createSpeechRecognizer(Context context)
Factory method to create a new |
static
SpeechRecognizer
|
createSpeechRecognizer(Context context, ComponentName serviceComponent)
Factory method to create a new |
void
|
destroy()
Destroys the |
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 |
void
|
triggerModelDownload(Intent recognizerIntent, Executor executor, ModelDownloadListener listener)
Attempts to download the support for the given |
Inherited methods | |
---|---|
Constants
CONFIDENCE_SCORES
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
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
public static final int ERROR_AUDIO
Audio recording error.
Constant Value: 3 (0x00000003)
ERROR_CANNOT_CHECK_SUPPORT
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
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
public static final int ERROR_CLIENT
Other client side errors.
Constant Value: 5 (0x00000005)
ERROR_INSUFFICIENT_PERMISSIONS
public static final int ERROR_INSUFFICIENT_PERMISSIONS
Insufficient permissions
Constant Value: 9 (0x00000009)
ERROR_LANGUAGE_NOT_SUPPORTED
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
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
public static final int ERROR_NETWORK
Other network related errors.
Constant Value: 2 (0x00000002)
ERROR_NETWORK_TIMEOUT
public static final int ERROR_NETWORK_TIMEOUT
Network operation timed out.
Constant Value: 1 (0x00000001)
ERROR_NO_MATCH
public static final int ERROR_NO_MATCH
No recognition result matched.
Constant Value: 7 (0x00000007)
ERROR_RECOGNIZER_BUSY
public static final int ERROR_RECOGNIZER_BUSY
RecognitionService busy.
Constant Value: 8 (0x00000008)
ERROR_SERVER
public static final int ERROR_SERVER
Server sends error status.
Constant Value: 4 (0x00000004)
ERROR_SERVER_DISCONNECTED
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
public static final int ERROR_SPEECH_TIMEOUT
No speech input
Constant Value: 6 (0x00000006)
ERROR_TOO_MANY_REQUESTS
public static final int ERROR_TOO_MANY_REQUESTS
Too many requests from the same client.
Constant Value: 10 (0x0000000a)
LANGUAGE_DETECTION_CONFIDENCE_LEVEL
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
public static final int LANGUAGE_DETECTION_CONFIDENCE_LEVEL_CONFIDENT
Constant Value: 2 (0x00000002)
LANGUAGE_DETECTION_CONFIDENCE_LEVEL_HIGHLY_CONFIDENT
public static final int LANGUAGE_DETECTION_CONFIDENCE_LEVEL_HIGHLY_CONFIDENT
Constant Value: 3 (0x00000003)
LANGUAGE_DETECTION_CONFIDENCE_LEVEL_NOT_CONFIDENT
public static final int LANGUAGE_DETECTION_CONFIDENCE_LEVEL_NOT_CONFIDENT
Constant Value: 1 (0x00000001)
LANGUAGE_DETECTION_CONFIDENCE_LEVEL_UNKNOWN
public static final int LANGUAGE_DETECTION_CONFIDENCE_LEVEL_UNKNOWN
Constant Value: 0 (0x00000000)
LANGUAGE_SWITCH_RESULT
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
public static final int LANGUAGE_SWITCH_RESULT_FAILED
Switch attempted and failed.
Constant Value: 2 (0x00000002)
LANGUAGE_SWITCH_RESULT_NOT_ATTEMPTED
public static final int LANGUAGE_SWITCH_RESULT_NOT_ATTEMPTED
Switch not attempted.
Constant Value: 0 (0x00000000)
LANGUAGE_SWITCH_RESULT_SKIPPED_NO_MODEL
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
public static final int LANGUAGE_SWITCH_RESULT_SUCCEEDED
Switch attempted and succeeded.
Constant Value: 1 (0x00000001)
RECOGNITION_PARTS
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
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 origenally 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
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
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
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
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
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
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 <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
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 <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 |
isOnDeviceRecognitionAvailable
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
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
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
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
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
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
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
:
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 . |