RecognitionService

public abstract class RecognitionService
extends Service

java.lang.Object
   ↳ android.content.Context
     ↳ android.content.ContextWrapper
       ↳ android.app.Service
         ↳ android.speech.RecognitionService


This class provides a base class for recognition service implementations. This class should be extended only in case you wish to implement a new speech recognizer. Please note that the implementation of this service is stateless.

Summary

Nested classes

class RecognitionService.Callback

This class receives callbacks from the speech recognition service and forwards them to the user. 

class RecognitionService.SupportCallback

This class receives callbacks from the speech recognition service and forwards them to the user. 

Constants

String SERVICE_INTERFACE

The Intent that must be declared as handled by the service.

String SERVICE_META_DATA

Name under which a RecognitionService component publishes information about itself.

Inherited constants

Public constructors

RecognitionService()

Public methods

Context createContext(ContextParams contextParams)

Creates a context with specific properties and behaviors.

int getMaxConcurrentSessionsCount()

Returns the maximal number of recognition sessions ongoing at the same time.

final IBinder onBind(Intent intent)

Return the communication channel to the service.

void onCheckRecognitionSupport(Intent recognizerIntent, RecognitionService.SupportCallback supportCallback)

Queries the service on whether it would support a onStartListening(android.content.Intent, android.speech.RecognitionService.Callback) for the same recognizerIntent.

void onCheckRecognitionSupport(Intent recognizerIntent, AttributionSource attributionSource, RecognitionService.SupportCallback supportCallback)

Queries the service on whether it would support a onStartListening(android.content.Intent, android.speech.RecognitionService.Callback) for the same recognizerIntent.

void onDestroy()

Called by the system to notify a Service that it is no longer used and is being removed.

void onTriggerModelDownload(Intent recognizerIntent, AttributionSource attributionSource, ModelDownloadListener listener)

Requests the download of the recognizer support for recognizerIntent.

void onTriggerModelDownload(Intent recognizerIntent, AttributionSource attributionSource)

Requests the download of the recognizer support for recognizerIntent.

void onTriggerModelDownload(Intent recognizerIntent)

Requests the download of the recognizer support for recognizerIntent.

Protected methods

abstract void onCancel(RecognitionService.Callback listener)

Notifies the service that it should cancel the speech recognition.

abstract void onStartListening(Intent recognizerIntent, RecognitionService.Callback listener)

Notifies the service that it should start listening for speech.

abstract void onStopListening(RecognitionService.Callback listener)

Notifies the service that it should stop listening for speech.

Inherited methods

Constants

SERVICE_INTERFACE

Added in API level 8
public static final String SERVICE_INTERFACE

The Intent that must be declared as handled by the service.

Constant Value: "android.speech.RecognitionService"

SERVICE_META_DATA

Added in API level 8
public static final String SERVICE_META_DATA

Name under which a RecognitionService component publishes information about itself. This meta-data should reference an XML resource containing a <recognition-service> or <on-device-recognition-service > tag.

Constant Value: "android.speech"

Public constructors

RecognitionService

public RecognitionService ()

Public methods

createContext

Added in API level 31
public Context createContext (ContextParams contextParams)

Creates a context with specific properties and behaviors.

Parameters
contextParams ContextParams: This value cannot be null.

Returns
Context This value cannot be null.

getMaxConcurrentSessionsCount

Added in API level 34
public int getMaxConcurrentSessionsCount ()

Returns the maximal number of recognition sessions ongoing at the same time.

The default value is 1, meaning concurrency should be enabled by overriding this method.

Returns
int

onBind

Added in API level 8
public final IBinder onBind (Intent intent)

Return the communication channel to the service. May return null if clients can not bind to the service. The returned IBinder is usually for a complex interface that has been described using aidl.

Note that unlike other application components, calls on to the IBinder interface returned here may not happen on the main thread of the process. More information about the main thread can be found in Processes and Threads.

Parameters
intent Intent: The Intent that was used to bind to this service, as given to Context.bindService. Note that any extras that were included with the Intent at that point will not be seen here.

Returns
IBinder Return an IBinder through which clients can call on to the service.

onCheckRecognitionSupport

Added in API level 33
public void onCheckRecognitionSupport (Intent recognizerIntent, 
                RecognitionService.SupportCallback supportCallback)

Queries the service on whether it would support a onStartListening(android.content.Intent, android.speech.RecognitionService.Callback) for the same recognizerIntent.

The service will notify the caller about the level of support or error via SupportCallback.

If the service does not offer the support check it will notify the caller with SpeechRecognizer#ERROR_CANNOT_CHECK_SUPPORT.

Parameters
recognizerIntent Intent: This value cannot be null.

supportCallback RecognitionService.SupportCallback: This value cannot be null.

onCheckRecognitionSupport

Added in API level 34
public void onCheckRecognitionSupport (Intent recognizerIntent, 
                AttributionSource attributionSource, 
                RecognitionService.SupportCallback supportCallback)

Queries the service on whether it would support a onStartListening(android.content.Intent, android.speech.RecognitionService.Callback) for the same recognizerIntent.

The service will notify the caller about the level of support or error via SupportCallback.

If the service does not offer the support check it will notify the caller with SpeechRecognizer#ERROR_CANNOT_CHECK_SUPPORT.

Provides the calling AttributionSource to the service implementation so that permissions and bandwidth could be correctly blamed.

Parameters
recognizerIntent Intent: This value cannot be null.

attributionSource AttributionSource: This value cannot be null.

supportCallback RecognitionService.SupportCallback: This value cannot be null.

onDestroy

Added in API level 8
public void onDestroy ()

Called by the system to notify a Service that it is no longer used and is being removed. The service should clean up any resources it holds (threads, registered receivers, etc) at this point. Upon return, there will be no more calls in to this Service object and it is effectively dead. Do not call this method directly.

onTriggerModelDownload

Added in API level 34
public void onTriggerModelDownload (Intent recognizerIntent, 
                AttributionSource attributionSource, 
                ModelDownloadListener listener)

Requests the download of the recognizer support for recognizerIntent.

Provides the calling AttributionSource to the service implementation so that permissions and bandwidth could be correctly blamed.

Client will receive the progress updates 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.

    attributionSource AttributionSource: the attribution source of the caller. This value cannot be null.

    listener ModelDownloadListener: on which to receive updates about the model download request. This value cannot be null.

  • onTriggerModelDownload

    Added in API level 34
    public void onTriggerModelDownload (Intent recognizerIntent, 
                    AttributionSource attributionSource)

    Requests the download of the recognizer support for recognizerIntent.

    Provides the calling AttributionSource to the service implementation so that permissions and bandwidth could be correctly blamed.

    Parameters
    recognizerIntent Intent: This value cannot be null.

    attributionSource AttributionSource: This value cannot be null.

    onTriggerModelDownload

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

    Requests the download of the recognizer support for recognizerIntent.

    Parameters
    recognizerIntent Intent: This value cannot be null.

    Protected methods

    onCancel

    Added in API level 8
    protected abstract void onCancel (RecognitionService.Callback listener)

    Notifies the service that it should cancel the speech recognition.

    Parameters
    listener RecognitionService.Callback

    onStartListening

    Added in API level 8
    protected abstract void onStartListening (Intent recognizerIntent, 
                    RecognitionService.Callback listener)

    Notifies the service that it should start listening for speech.

    If you are recognizing speech from the microphone, in this callback you should create an attribution context for the caller such that when you access the mic the caller would be properly blamed (and their permission checked in the process) for accessing the microphone and that you served as a proxy for this sensitive data (and your permissions would be checked in the process). You should also open the mic in this callback via the attribution context and close the mic before returning the recognized result. If you don't do that then the caller would be blamed and you as being a proxy as well as you would get one more blame on yourself when you open the microphone.

     Context attributionContext = context.createContext(new ContextParams.Builder()
         .setNextAttributionSource(callback.getCallingAttributionSource())
         .build());
    
     AudioRecord recorder = AudioRecord.Builder()
         .setContext(attributionContext);
         . . .
        .build();
    
     recorder.startRecording()
     

    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 should be used by the recognizer.

    listener RecognitionService.Callback: that will receive the service's callbacks

    onStopListening

    Added in API level 8
    protected abstract void onStopListening (RecognitionService.Callback listener)

    Notifies the service that it should stop listening for speech. Speech captured so far should be recognized as if the user had stopped speaking at this point. This method is only called if the application calls it explicitly.

    Parameters
    listener RecognitionService.Callback