1 /* 2 * Copyright (C) 2010 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); you may not 5 * use this file except in compliance with the License. You may obtain a copy of 6 * the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 12 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 13 * License for the specific language governing permissions and limitations under 14 * the License. 15 */ 16 17 package android.speech; 18 19 import android.annotation.SdkConstant; 20 import android.annotation.SdkConstant.SdkConstantType; 21 import android.app.Service; 22 import android.content.Intent; 23 import android.content.pm.PackageManager; 24 import android.os.Bundle; 25 import android.os.Handler; 26 import android.os.IBinder; 27 import android.os.Message; 28 import android.os.RemoteException; 29 import android.util.Log; 30 31 import java.lang.ref.WeakReference; 32 33 /** 34 * This class provides a base class for recognition service implementations. This class should be 35 * extended only in case you wish to implement a new speech recognizer. Please note that the 36 * implementation of this service is stateless. 37 */ 38 public abstract class RecognitionService extends Service { 39 /** 40 * The {@link Intent} that must be declared as handled by the service. 41 */ 42 @SdkConstant(SdkConstantType.SERVICE_ACTION) 43 public static final String SERVICE_INTERFACE = "android.speech.RecognitionService"; 44 45 /** 46 * Name under which a RecognitionService component publishes information about itself. 47 * This meta-data should reference an XML resource containing a 48 * <code><{@link android.R.styleable#RecognitionService recognition-service}></code> tag. 49 */ 50 public static final String SERVICE_META_DATA = "android.speech"; 51 52 /** Log messages identifier */ 53 private static final String TAG = "RecognitionService"; 54 55 /** Debugging flag */ 56 private static final boolean DBG = false; 57 58 /** Binder of the recognition service */ 59 private RecognitionServiceBinder mBinder = new RecognitionServiceBinder(this); 60 61 /** 62 * The current callback of an application that invoked the 63 * {@link RecognitionService#onStartListening(Intent, Callback)} method 64 */ 65 private Callback mCurrentCallback = null; 66 67 private static final int MSG_START_LISTENING = 1; 68 69 private static final int MSG_STOP_LISTENING = 2; 70 71 private static final int MSG_CANCEL = 3; 72 73 private static final int MSG_RESET = 4; 74 75 private final Handler mHandler = new Handler() { 76 @Override 77 public void handleMessage(Message msg) { 78 switch (msg.what) { 79 case MSG_START_LISTENING: 80 StartListeningArgs args = (StartListeningArgs) msg.obj; 81 dispatchStartListening(args.mIntent, args.mListener); 82 break; 83 case MSG_STOP_LISTENING: 84 dispatchStopListening((IRecognitionListener) msg.obj); 85 break; 86 case MSG_CANCEL: 87 dispatchCancel((IRecognitionListener) msg.obj); 88 break; 89 case MSG_RESET: 90 dispatchClearCallback(); 91 break; 92 } 93 } 94 }; 95 96 private void dispatchStartListening(Intent intent, final IRecognitionListener listener) { 97 if (mCurrentCallback == null) { 98 if (DBG) Log.d(TAG, "created new mCurrentCallback, listener = " + listener.asBinder()); 99 try { 100 listener.asBinder().linkToDeath(new IBinder.DeathRecipient() { 101 @Override 102 public void binderDied() { 103 mHandler.sendMessage(mHandler.obtainMessage(MSG_CANCEL, listener)); 104 } 105 }, 0); 106 } catch (RemoteException re) { 107 Log.e(TAG, "dead listener on startListening"); 108 return; 109 } 110 mCurrentCallback = new Callback(listener); 111 RecognitionService.this.onStartListening(intent, mCurrentCallback); 112 } else { 113 try { 114 listener.onError(SpeechRecognizer.ERROR_RECOGNIZER_BUSY); 115 } catch (RemoteException e) { 116 Log.d(TAG, "onError call from startListening failed"); 117 } 118 Log.i(TAG, "concurrent startListening received - ignoring this call"); 119 } 120 } 121 122 private void dispatchStopListening(IRecognitionListener listener) { 123 try { 124 if (mCurrentCallback == null) { 125 listener.onError(SpeechRecognizer.ERROR_CLIENT); 126 Log.w(TAG, "stopListening called with no preceding startListening - ignoring"); 127 } else if (mCurrentCallback.mListener.asBinder() != listener.asBinder()) { 128 listener.onError(SpeechRecognizer.ERROR_RECOGNIZER_BUSY); 129 Log.w(TAG, "stopListening called by other caller than startListening - ignoring"); 130 } else { // the correct state 131 RecognitionService.this.onStopListening(mCurrentCallback); 132 } 133 } catch (RemoteException e) { // occurs if onError fails 134 Log.d(TAG, "onError call from stopListening failed"); 135 } 136 } 137 138 private void dispatchCancel(IRecognitionListener listener) { 139 if (mCurrentCallback == null) { 140 if (DBG) Log.d(TAG, "cancel called with no preceding startListening - ignoring"); 141 } else if (mCurrentCallback.mListener.asBinder() != listener.asBinder()) { 142 Log.w(TAG, "cancel called by client who did not call startListening - ignoring"); 143 } else { // the correct state 144 RecognitionService.this.onCancel(mCurrentCallback); 145 mCurrentCallback = null; 146 if (DBG) Log.d(TAG, "canceling - setting mCurrentCallback to null"); 147 } 148 } 149 150 private void dispatchClearCallback() { 151 mCurrentCallback = null; 152 } 153 154 private class StartListeningArgs { 155 public final Intent mIntent; 156 157 public final IRecognitionListener mListener; 158 159 public StartListeningArgs(Intent intent, IRecognitionListener listener) { 160 this.mIntent = intent; 161 this.mListener = listener; 162 } 163 } 164 165 /** 166 * Checks whether the caller has sufficient permissions 167 * 168 * @param listener to send the error message to in case of error 169 * @return {@code true} if the caller has enough permissions, {@code false} otherwise 170 */ 171 private boolean checkPermissions(IRecognitionListener listener) { 172 if (DBG) Log.d(TAG, "checkPermissions"); 173 if (RecognitionService.this.checkCallingOrSelfPermission(android.Manifest.permission. 174 RECORD_AUDIO) == PackageManager.PERMISSION_GRANTED) { 175 return true; 176 } 177 try { 178 Log.e(TAG, "call for recognition service without RECORD_AUDIO permissions"); 179 listener.onError(SpeechRecognizer.ERROR_INSUFFICIENT_PERMISSIONS); 180 } catch (RemoteException re) { 181 Log.e(TAG, "sending ERROR_INSUFFICIENT_PERMISSIONS message failed", re); 182 } 183 return false; 184 } 185 186 /** 187 * Notifies the service that it should start listening for speech. 188 * 189 * @param recognizerIntent contains parameters for the recognition to be performed. The intent 190 * may also contain optional extras, see {@link RecognizerIntent}. If these values are 191 * not set explicitly, default values should be used by the recognizer. 192 * @param listener that will receive the service's callbacks 193 */ 194 protected abstract void onStartListening(Intent recognizerIntent, Callback listener); 195 196 /** 197 * Notifies the service that it should cancel the speech recognition. 198 */ 199 protected abstract void onCancel(Callback listener); 200 201 /** 202 * Notifies the service that it should stop listening for speech. Speech captured so far should 203 * be recognized as if the user had stopped speaking at this point. This method is only called 204 * if the application calls it explicitly. 205 */ 206 protected abstract void onStopListening(Callback listener); 207 208 @Override 209 public final IBinder onBind(final Intent intent) { 210 if (DBG) Log.d(TAG, "onBind, intent=" + intent); 211 return mBinder; 212 } 213 214 @Override 215 public void onDestroy() { 216 if (DBG) Log.d(TAG, "onDestroy"); 217 mCurrentCallback = null; 218 mBinder.clearReference(); 219 super.onDestroy(); 220 } 221 222 /** 223 * This class receives callbacks from the speech recognition service and forwards them to the 224 * user. An instance of this class is passed to the 225 * {@link RecognitionService#onStartListening(Intent, Callback)} method. Recognizers may call 226 * these methods on any thread. 227 */ 228 public class Callback { 229 private final IRecognitionListener mListener; 230 231 private Callback(IRecognitionListener listener) { 232 mListener = listener; 233 } 234 235 /** 236 * The service should call this method when the user has started to speak. 237 */ 238 public void beginningOfSpeech() throws RemoteException { 239 if (DBG) Log.d(TAG, "beginningOfSpeech"); 240 mListener.onBeginningOfSpeech(); 241 } 242 243 /** 244 * The service should call this method when sound has been received. The purpose of this 245 * function is to allow giving feedback to the user regarding the captured audio. 246 * 247 * @param buffer a buffer containing a sequence of big-endian 16-bit integers representing a 248 * single channel audio stream. The sample rate is implementation dependent. 249 */ 250 public void bufferReceived(byte[] buffer) throws RemoteException { 251 mListener.onBufferReceived(buffer); 252 } 253 254 /** 255 * The service should call this method after the user stops speaking. 256 */ 257 public void endOfSpeech() throws RemoteException { 258 mListener.onEndOfSpeech(); 259 } 260 261 /** 262 * The service should call this method when a network or recognition error occurred. 263 * 264 * @param error code is defined in {@link SpeechRecognizer} 265 */ 266 public void error(int error) throws RemoteException { 267 Message.obtain(mHandler, MSG_RESET).sendToTarget(); 268 mListener.onError(error); 269 } 270 271 /** 272 * The service should call this method when partial recognition results are available. This 273 * method can be called at any time between {@link #beginningOfSpeech()} and 274 * {@link #results(Bundle)} when partial results are ready. This method may be called zero, 275 * one or multiple times for each call to {@link SpeechRecognizer#startListening(Intent)}, 276 * depending on the speech recognition service implementation. 277 * 278 * @param partialResults the returned results. To retrieve the results in 279 * ArrayList<String> format use {@link Bundle#getStringArrayList(String)} with 280 * {@link SpeechRecognizer#RESULTS_RECOGNITION} as a parameter 281 */ 282 public void partialResults(Bundle partialResults) throws RemoteException { 283 mListener.onPartialResults(partialResults); 284 } 285 286 /** 287 * The service should call this method when the endpointer is ready for the user to start 288 * speaking. 289 * 290 * @param params parameters set by the recognition service. Reserved for future use. 291 */ 292 public void readyForSpeech(Bundle params) throws RemoteException { 293 mListener.onReadyForSpeech(params); 294 } 295 296 /** 297 * The service should call this method when recognition results are ready. 298 * 299 * @param results the recognition results. To retrieve the results in {@code 300 * ArrayList<String>} format use {@link Bundle#getStringArrayList(String)} with 301 * {@link SpeechRecognizer#RESULTS_RECOGNITION} as a parameter 302 */ 303 public void results(Bundle results) throws RemoteException { 304 Message.obtain(mHandler, MSG_RESET).sendToTarget(); 305 mListener.onResults(results); 306 } 307 308 /** 309 * The service should call this method when the sound level in the audio stream has changed. 310 * There is no guarantee that this method will be called. 311 * 312 * @param rmsdB the new RMS dB value 313 */ 314 public void rmsChanged(float rmsdB) throws RemoteException { 315 mListener.onRmsChanged(rmsdB); 316 } 317 } 318 319 /** Binder of the recognition service */ 320 private static final class RecognitionServiceBinder extends IRecognitionService.Stub { 321 private final WeakReference<RecognitionService> mServiceRef; 322 323 public RecognitionServiceBinder(RecognitionService service) { 324 mServiceRef = new WeakReference<RecognitionService>(service); 325 } 326 327 @Override 328 public void startListening(Intent recognizerIntent, IRecognitionListener listener) { 329 if (DBG) Log.d(TAG, "startListening called by:" + listener.asBinder()); 330 final RecognitionService service = mServiceRef.get(); 331 if (service != null && service.checkPermissions(listener)) { 332 service.mHandler.sendMessage(Message.obtain(service.mHandler, 333 MSG_START_LISTENING, service.new StartListeningArgs( 334 recognizerIntent, listener))); 335 } 336 } 337 338 @Override 339 public void stopListening(IRecognitionListener listener) { 340 if (DBG) Log.d(TAG, "stopListening called by:" + listener.asBinder()); 341 final RecognitionService service = mServiceRef.get(); 342 if (service != null && service.checkPermissions(listener)) { 343 service.mHandler.sendMessage(Message.obtain(service.mHandler, 344 MSG_STOP_LISTENING, listener)); 345 } 346 } 347 348 @Override 349 public void cancel(IRecognitionListener listener) { 350 if (DBG) Log.d(TAG, "cancel called by:" + listener.asBinder()); 351 final RecognitionService service = mServiceRef.get(); 352 if (service != null && service.checkPermissions(listener)) { 353 service.mHandler.sendMessage(Message.obtain(service.mHandler, 354 MSG_CANCEL, listener)); 355 } 356 } 357 358 public void clearReference() { 359 mServiceRef.clear(); 360 } 361 } 362 } 363
