SoundTrigger.java revision e48188ce35f613f64b513e5d8ce24fada1212d8e
1/* 2 * Copyright (C) 2014 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 17package android.hardware.soundtrigger; 18 19import android.content.Context; 20import android.content.Intent; 21import android.os.Handler; 22 23import java.util.ArrayList; 24import java.util.UUID; 25 26/** 27 * The SoundTrigger class provides access via JNI to the native service managing 28 * the sound trigger HAL. 29 * 30 * @hide 31 */ 32public class SoundTrigger { 33 34 public static final int STATUS_OK = 0; 35 public static final int STATUS_ERROR = Integer.MIN_VALUE; 36 public static final int STATUS_PERMISSION_DENIED = -1; 37 public static final int STATUS_NO_INIT = -19; 38 public static final int STATUS_BAD_VALUE = -22; 39 public static final int STATUS_DEAD_OBJECT = -32; 40 public static final int STATUS_INVALID_OPERATION = -38; 41 42 /***************************************************************************** 43 * A ModuleProperties describes a given sound trigger hardware module 44 * managed by the native sound trigger service. Each module has a unique 45 * ID used to target any API call to this paricular module. Module 46 * properties are returned by listModules() method. 47 ****************************************************************************/ 48 public static class ModuleProperties { 49 /** Unique module ID provided by the native service */ 50 public final int id; 51 52 /** human readable voice detection engine implementor */ 53 public final String implementor; 54 55 /** human readable voice detection engine description */ 56 public final String description; 57 58 /** Unique voice engine Id (changes with each version) */ 59 public final UUID uuid; 60 61 /** Voice detection engine version */ 62 public final int version; 63 64 /** Maximum number of active sound models */ 65 public final int maxSoundModels; 66 67 /** Maximum number of key phrases */ 68 public final int maxKeyPhrases; 69 70 /** Maximum number of users per key phrase */ 71 public final int maxUsers; 72 73 /** Supported recognition modes (bit field, RECOGNITION_MODE_VOICE_TRIGGER ...) */ 74 public final int recognitionModes; 75 76 /** Supports seamless transition to capture mode after recognition */ 77 public final boolean supportsCaptureTransition; 78 79 /** Maximum buffering capacity in ms if supportsCaptureTransition() is true */ 80 public final int maxBufferMs; 81 82 /** Supports capture by other use cases while detection is active */ 83 public final boolean supportsConcurrentCapture; 84 85 /** Rated power consumption when detection is active with TDB silence/sound/speech ratio */ 86 public final int powerConsumptionMw; 87 88 ModuleProperties(int id, String implementor, String description, 89 String uuid, int version, int maxSoundModels, int maxKeyPhrases, 90 int maxUsers, int recognitionModes, boolean supportsCaptureTransition, 91 int maxBufferMs, boolean supportsConcurrentCapture, 92 int powerConsumptionMw) { 93 this.id = id; 94 this.implementor = implementor; 95 this.description = description; 96 this.uuid = UUID.fromString(uuid); 97 this.version = version; 98 this.maxSoundModels = maxSoundModels; 99 this.maxKeyPhrases = maxKeyPhrases; 100 this.maxUsers = maxUsers; 101 this.recognitionModes = recognitionModes; 102 this.supportsCaptureTransition = supportsCaptureTransition; 103 this.maxBufferMs = maxBufferMs; 104 this.supportsConcurrentCapture = supportsConcurrentCapture; 105 this.powerConsumptionMw = powerConsumptionMw; 106 } 107 } 108 109 /***************************************************************************** 110 * A SoundModel describes the attributes and contains the binary data used by the hardware 111 * implementation to detect a particular sound pattern. 112 * A specialized version {@link KeyPhraseSoundModel} is defined for key phrase 113 * sound models. 114 ****************************************************************************/ 115 public static class SoundModel { 116 /** Undefined sound model type */ 117 public static final int TYPE_UNKNOWN = -1; 118 119 /** Keyphrase sound model */ 120 public static final int TYPE_KEYPHRASE = 0; 121 122 /** Sound model type (e.g. TYPE_KEYPHRASE); */ 123 public final int type; 124 125 /** Opaque data. For use by vendor implementation and enrollment application */ 126 public final byte[] data; 127 128 public SoundModel(int type, byte[] data) { 129 this.type = type; 130 this.data = data; 131 } 132 } 133 134 /***************************************************************************** 135 * A KeyPhrase describes a key phrase that can be detected by a 136 * {@link KeyPhraseSoundModel} 137 ****************************************************************************/ 138 public static class KeyPhrase { 139 /** Recognition modes supported for this key phrase in the model */ 140 public final int recognitionModes; 141 142 /** Locale of the keyphrase. JAVA Locale string e.g en_US */ 143 public final String locale; 144 145 /** Key phrase text */ 146 public final String text; 147 148 /** Number of users this key phrase has been trained for */ 149 public final int numUsers; 150 151 public KeyPhrase(int recognitionModes, String locale, String text, int numUsers) { 152 this.recognitionModes = recognitionModes; 153 this.locale = locale; 154 this.text = text; 155 this.numUsers = numUsers; 156 } 157 } 158 159 /***************************************************************************** 160 * A KeyPhraseSoundModel is a specialized {@link SoundModel} for key phrases. 161 * It contains data needed by the hardware to detect a certain number of key phrases 162 * and the list of corresponding {@link KeyPhrase} descriptors. 163 ****************************************************************************/ 164 public static class KeyPhraseSoundModel extends SoundModel { 165 /** Key phrases in this sound model */ 166 public final KeyPhrase[] keyPhrases; // keyword phrases in model 167 168 public KeyPhraseSoundModel(byte[] data, KeyPhrase[] keyPhrases) { 169 super(TYPE_KEYPHRASE, data); 170 this.keyPhrases = keyPhrases; 171 } 172 } 173 174 /** 175 * Modes for key phrase recognition 176 */ 177 /** Simple recognition of the key phrase */ 178 public static final int RECOGNITION_MODE_VOICE_TRIGGER = 0x1; 179 /** Trigger only if one user is identified */ 180 public static final int RECOGNITION_MODE_USER_IDENTIFICATION = 0x2; 181 /** Trigger only if one user is authenticated */ 182 public static final int RECOGNITION_MODE_USER_AUTHENTICATION = 0x4; 183 184 /** 185 * Status codes for {@link RecognitionEvent} 186 */ 187 /** Recognition success */ 188 public static final int RECOGNITION_STATUS_SUCCESS = 0; 189 /** Recognition aborted (e.g. capture preempted by anotehr use case */ 190 public static final int RECOGNITION_STATUS_ABORT = 1; 191 /** Recognition failure */ 192 public static final int RECOGNITION_STATUS_FAILURE = 2; 193 194 /** 195 * A RecognitionEvent is provided by the 196 * {@link StatusListener#onRecognition(RecognitionEvent)} 197 * callback upon recognition success or failure. 198 */ 199 public static class RecognitionEvent { 200 /** Recognition status e.g {@link #RECOGNITION_STATUS_SUCCESS} */ 201 public final int status; 202 /** Sound Model corresponding to this event callback */ 203 public final int soundModelHandle; 204 /** True if it is possible to capture audio from this utterance buffered by the hardware */ 205 public final boolean captureAvailable; 206 /** Audio session ID to be used when capturing the utterance with an AudioRecord 207 * if captureAvailable() is true. */ 208 public final int captureSession; 209 /** Delay in ms between end of model detection and start of audio available for capture. 210 * A negative value is possible (e.g. if keyphrase is also available for capture) */ 211 public final int captureDelayMs; 212 /** Opaque data for use by system applications who know about voice engine internals, 213 * typically during enrollment. */ 214 public final byte[] data; 215 216 RecognitionEvent(int status, int soundModelHandle, boolean captureAvailable, 217 int captureSession, int captureDelayMs, byte[] data) { 218 this.status = status; 219 this.soundModelHandle = soundModelHandle; 220 this.captureAvailable = captureAvailable; 221 this.captureSession = captureSession; 222 this.captureDelayMs = captureDelayMs; 223 this.data = data; 224 } 225 } 226 227 /** 228 * Additional data conveyed by a {@link KeyPhraseRecognitionEvent} 229 * for a key phrase detection. 230 */ 231 public static class KeyPhraseRecognitionExtra { 232 /** Confidence level for each user defined in the key phrase in the same order as 233 * users in the key phrase. The confidence level is expressed in percentage (0% -100%) */ 234 public final int[] confidenceLevels; 235 236 /** Recognition modes matched for this event */ 237 public final int recognitionModes; 238 239 KeyPhraseRecognitionExtra(int[] confidenceLevels, int recognitionModes) { 240 this.confidenceLevels = confidenceLevels; 241 this.recognitionModes = recognitionModes; 242 } 243 } 244 245 /** 246 * Specialized {@link RecognitionEvent} for a key phrase detection. 247 */ 248 public static class KeyPhraseRecognitionEvent extends RecognitionEvent { 249 /** Indicates if the key phrase is present in the buffered audio available for capture */ 250 public final KeyPhraseRecognitionExtra[] keyPhraseExtras; 251 252 /** Additional data available for each recognized key phrases in the model */ 253 public final boolean keyPhraseInCapture; 254 255 KeyPhraseRecognitionEvent(int status, int soundModelHandle, boolean captureAvailable, 256 int captureSession, int captureDelayMs, byte[] data, 257 boolean keyPhraseInCapture, KeyPhraseRecognitionExtra[] keyPhraseExtras) { 258 super(status, soundModelHandle, captureAvailable, captureSession, captureDelayMs, data); 259 this.keyPhraseInCapture = keyPhraseInCapture; 260 this.keyPhraseExtras = keyPhraseExtras; 261 } 262 } 263 264 /** 265 * Returns a list of descriptors for all harware modules loaded. 266 * @param modules A ModuleProperties array where the list will be returned. 267 * @return - {@link #STATUS_OK} in case of success 268 * - {@link #STATUS_ERROR} in case of unspecified error 269 * - {@link #STATUS_PERMISSION_DENIED} if the caller does not have system permission 270 * - {@link #STATUS_NO_INIT} if the native service cannot be reached 271 * - {@link #STATUS_BAD_VALUE} if modules is null 272 * - {@link #STATUS_DEAD_OBJECT} if the binder transaction to the native service fails 273 */ 274 public static native int listModules(ArrayList <ModuleProperties> modules); 275 276 /** 277 * Get an interface on a hardware module to control sound models and recognition on 278 * this module. 279 * @param moduleId Sound module system identifier {@link ModuleProperties#id}. mandatory. 280 * @param listener {@link StatusListener} interface. Mandatory. 281 * @param handler the Handler that will receive the callabcks. Can be null if default handler 282 * is OK. 283 * @return a valid sound module in case of success or null in case of error. 284 */ 285 public static SoundTriggerModule attachModule(int moduleId, 286 StatusListener listener, 287 Handler handler) { 288 if (listener == null) { 289 return null; 290 } 291 SoundTriggerModule module = new SoundTriggerModule(moduleId, listener, handler); 292 return module; 293 } 294 295 /** 296 * Interface provided by the client application when attaching to a {@link SoundTriggerModule} 297 * to received recognition and error notifications. 298 */ 299 public static interface StatusListener { 300 /** 301 * Called when recognition succeeds of fails 302 */ 303 public abstract void onRecognition(RecognitionEvent event); 304 305 /** 306 * Called when the sound trigger native service dies 307 */ 308 public abstract void onServiceDied(); 309 } 310} 311