1 /* 2 * Copyright (C) 2010 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of 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, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 package android.speech; 17 18 import android.annotation.NonNull; 19 import android.content.Intent; 20 import android.os.Bundle; 21 22 /** 23 * Used for receiving notifications from the SpeechRecognizer when the 24 * recognition related events occur. All the callbacks are executed on the 25 * Application main thread. 26 */ 27 public interface RecognitionListener { 28 29 /** 30 * Called when the endpointer is ready for the user to start speaking. 31 * 32 * @param params parameters set by the recognition service. Reserved for future use. 33 */ onReadyForSpeech(Bundle params)34 void onReadyForSpeech(Bundle params); 35 36 /** 37 * The user has started to speak. 38 */ onBeginningOfSpeech()39 void onBeginningOfSpeech(); 40 41 /** 42 * The sound level in the audio stream has changed. There is no guarantee that this method will 43 * be called. 44 * 45 * @param rmsdB the new RMS dB value 46 */ onRmsChanged(float rmsdB)47 void onRmsChanged(float rmsdB); 48 49 /** 50 * More sound has been received. The purpose of this function is to allow giving feedback to the 51 * user regarding the captured audio. There is no guarantee that this method will be called. 52 * 53 * @param buffer a buffer containing a sequence of big-endian 16-bit integers representing a 54 * single channel audio stream. The sample rate is implementation dependent. 55 */ onBufferReceived(byte[] buffer)56 void onBufferReceived(byte[] buffer); 57 58 /** 59 * Called after the user stops speaking. 60 */ onEndOfSpeech()61 void onEndOfSpeech(); 62 63 /** 64 * A network or recognition error occurred. 65 * 66 * @param error code is defined in {@link SpeechRecognizer}. Implementations need to handle any 67 * integer error constant to be passed here beyond constants prefixed with ERROR_. 68 */ onError(@peechRecognizer.RecognitionError int error)69 void onError(@SpeechRecognizer.RecognitionError int error); 70 71 /** 72 * Called when recognition results are ready. 73 * 74 * <p> 75 * Called with the results for the full speech since {@link #onReadyForSpeech(Bundle)}. 76 * To get recognition results in segments rather than for the full session see 77 * {@link RecognizerIntent#EXTRA_SEGMENTED_SESSION}. 78 * </p> 79 * 80 * @param results the recognition results. To retrieve the results in {@code 81 * ArrayList<String>} format use {@link Bundle#getStringArrayList(String)} with 82 * {@link SpeechRecognizer#RESULTS_RECOGNITION} as a parameter. A float array of 83 * confidence values might also be given in {@link SpeechRecognizer#CONFIDENCE_SCORES}. 84 */ onResults(Bundle results)85 void onResults(Bundle results); 86 87 /** 88 * Called when partial recognition results are available. The callback might be called at any 89 * time between {@link #onBeginningOfSpeech()} and {@link #onResults(Bundle)} when partial 90 * results are ready. This method may be called zero, one or multiple times for each call to 91 * {@link SpeechRecognizer#startListening(Intent)}, depending on the speech recognition 92 * service implementation. To request partial results, use 93 * {@link RecognizerIntent#EXTRA_PARTIAL_RESULTS} 94 * 95 * @param partialResults the returned results. To retrieve the results in 96 * ArrayList<String> format use {@link Bundle#getStringArrayList(String)} with 97 * {@link SpeechRecognizer#RESULTS_RECOGNITION} as a parameter 98 */ onPartialResults(Bundle partialResults)99 void onPartialResults(Bundle partialResults); 100 101 /** 102 * Called for each ready segment of a recognition request. To request segmented speech results 103 * use {@link RecognizerIntent#EXTRA_SEGMENTED_SESSION}. The callback might be called 104 * any number of times between {@link #onReadyForSpeech(Bundle)} and 105 * {@link #onEndOfSegmentedSession()}. 106 * 107 * @param segmentResults the returned results. To retrieve the results in 108 * ArrayList<String> format use {@link Bundle#getStringArrayList(String)} with 109 * {@link SpeechRecognizer#RESULTS_RECOGNITION} as a parameter 110 */ onSegmentResults(@onNull Bundle segmentResults)111 default void onSegmentResults(@NonNull Bundle segmentResults) {} 112 113 /** 114 * Called at the end of a segmented recognition request. To request segmented speech results 115 * use {@link RecognizerIntent#EXTRA_SEGMENTED_SESSION}. 116 */ onEndOfSegmentedSession()117 default void onEndOfSegmentedSession() {} 118 119 /** 120 * Called when the language detection (and switching) results are available. This callback 121 * can be invoked on any number of occasions at any time between {@link #onBeginningOfSpeech()} 122 * and {@link #onEndOfSpeech()}, depending on the speech recognition service implementation. 123 * 124 * <p> To request language detection, 125 * use {@link RecognizerIntent#EXTRA_ENABLE_LANGUAGE_DETECTION}. 126 * <p> To request automatic language switching, 127 * use {@link RecognizerIntent#EXTRA_ENABLE_LANGUAGE_SWITCH}. 128 * 129 * @param results the returned language detection (and switching) results. 130 * <p> To retrieve the most confidently detected language IETF tag 131 * (as defined by BCP 47, e.g., "en-US", "de-DE"), 132 * use {@link Bundle#getString(String)} 133 * with {@link SpeechRecognizer#DETECTED_LANGUAGE} as the parameter. 134 * <p> To retrieve the language detection confidence level represented by a value 135 * prefixed by {@code LANGUAGE_DETECTION_CONFIDENCE_LEVEL_} and 136 * defined in {@link SpeechRecognizer}, use {@link Bundle#getInt(String)} 137 * with {@link SpeechRecognizer#LANGUAGE_DETECTION_CONFIDENCE_LEVEL} as the parameter. 138 * <p> To retrieve the alternative locales for the same language 139 * retrieved by the key {@link SpeechRecognizer#DETECTED_LANGUAGE}, 140 * use {@link Bundle#getStringArrayList(String)} 141 * with {@link SpeechRecognizer#TOP_LOCALE_ALTERNATIVES} as the parameter. 142 * <p> To retrieve the language switching results represented by a value 143 * prefixed by {@code LANGUAGE_SWITCH_RESULT_} and defined in {@link SpeechRecognizer}, 144 * use {@link Bundle#getInt(String)} 145 * with {@link SpeechRecognizer#LANGUAGE_SWITCH_RESULT} as the parameter. 146 */ onLanguageDetection(@onNull Bundle results)147 default void onLanguageDetection(@NonNull Bundle results) {} 148 149 /** 150 * Reserved for adding future events. 151 * 152 * @param eventType the type of the occurred event 153 * @param params a Bundle containing the passed parameters 154 */ onEvent(int eventType, Bundle params)155 void onEvent(int eventType, Bundle params); 156 } 157