1/* 2 * Copyright 2016 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@2.0; 18 19import android.hardware.audio.common@2.0; 20 21import ISoundTriggerHwCallback; 22 23interface ISoundTriggerHw { 24 25 /** 26 * Sound trigger implementation descriptor read by the framework via 27 * getProperties(). Used by SoundTrigger service to report to applications 28 * and manage concurrency and policy. 29 */ 30 struct Properties { 31 /** Implementor name */ 32 string implementor; 33 /** Implementation description */ 34 string description; 35 /** Implementation version */ 36 uint32_t version; 37 /** 38 * Unique implementation ID. The UUID must change with each version of 39 the engine implementation */ 40 Uuid uuid; 41 /** Maximum number of concurrent sound models loaded */ 42 uint32_t maxSoundModels; 43 /** Maximum number of key phrases */ 44 uint32_t maxKeyPhrases; 45 /** Maximum number of concurrent users detected */ 46 uint32_t maxUsers; 47 /** All supported modes. e.g RecognitionMode.VOICE_TRIGGER */ 48 uint32_t recognitionModes; 49 /** Supports seamless transition from detection to capture */ 50 bool captureTransition; 51 /** Maximum buffering capacity in ms if captureTransition is true */ 52 uint32_t maxBufferMs; 53 /** Supports capture by other use cases while detection is active */ 54 bool concurrentCapture; 55 /** Returns the trigger capture in event */ 56 bool triggerInEvent; 57 /** 58 * Rated power consumption when detection is active with TDB 59 * silence/sound/speech ratio */ 60 uint32_t powerConsumptionMw; 61 }; 62 63 64 /** 65 * Base sound model descriptor. This struct is the header of a larger block 66 * passed to loadSoundModel() and contains the binary data of the 67 * sound model. 68 */ 69 struct SoundModel { 70 /** Model type. e.g. SoundModelType.KEYPHRASE */ 71 SoundModelType type; 72 /** Unique sound model ID. */ 73 Uuid uuid; 74 /** 75 * Unique vendor ID. Identifies the engine the sound model 76 * was build for */ 77 Uuid vendorUuid; 78 /** Opaque data transparent to Android framework */ 79 vec<uint8_t> data; 80 }; 81 82 /** Key phrase descriptor */ 83 struct Phrase { 84 /** Unique keyphrase ID assigned at enrollment time */ 85 uint32_t id; 86 /** Recognition modes supported by this key phrase */ 87 uint32_t recognitionModes; 88 /** List of users IDs associated with this key phrase */ 89 vec<uint32_t> users; 90 /** Locale - Java Locale style (e.g. en_US) */ 91 string locale; 92 /** Phrase text in UTF-8 format. */ 93 string text; 94 }; 95 96 /** 97 * Specialized sound model for key phrase detection. 98 * Proprietary representation of key phrases in binary data must match 99 * information indicated by phrases field 100 */ 101 struct PhraseSoundModel { 102 /** Common part of sound model descriptor */ 103 SoundModel common; 104 /** List of descriptors for key phrases supported by this sound model */ 105 vec<Phrase> phrases; 106 }; 107 108 /** 109 * Configuration for sound trigger capture session passed to 110 * startRecognition() method 111 */ 112 struct RecognitionConfig { 113 /** 114 * IO handle that will be used for capture. N/A if captureRequested 115 * is false */ 116 AudioIoHandle captureHandle; 117 /** Input device requested for detection capture */ 118 AudioDevice captureDevice; 119 /** Capture and buffer audio for this recognition instance */ 120 bool captureRequested; 121 /** Configuration for each key phrase */ 122 vec<PhraseRecognitionExtra> phrases; 123 /** Opaque capture configuration data transparent to the framework */ 124 vec<uint8_t> data; 125 }; 126 127 128 /** 129 * Retrieve implementation properties. 130 * @return retval Operation completion status: 0 in case of success, 131 * -ENODEV in case of initialization error. 132 * @return properties A Properties structure containing implementation 133 * description and capabilities. 134 */ 135 getProperties() generates (int32_t retval, Properties properties); 136 137 /** 138 * Load a sound model. Once loaded, recognition of this model can be 139 * started and stopped. Only one active recognition per model at a time. 140 * The SoundTrigger service must handle concurrent recognition requests by 141 * different users/applications on the same model. 142 * The implementation returns a unique handle used by other functions 143 * (unloadSoundModel(), startRecognition(), etc... 144 * @param soundModel A SoundModel structure describing the sound model to 145 * load. 146 * @param callback The callback interface on which the soundmodelCallback() 147 * method will be called upon completion. 148 * @param cookie The value of the cookie argument passed to the completion 149 * callback. This unique context information is assigned and 150 * used only by the framework. 151 * @return retval Operation completion status: 0 in case of success, 152 * -EINVAL in case of invalid sound model (e.g 0 data size), 153 * -ENOSYS in case of invalid operation (e.g max number of 154 * models exceeded), 155 * -ENOMEM in case of memory allocation failure, 156 * -ENODEV in case of initialization error. 157 * @return modelHandle A unique handle assigned by the HAL for use by the 158 * framework when controlling activity for this sound model. 159 */ 160 loadSoundModel(SoundModel soundModel, 161 ISoundTriggerHwCallback callback, 162 CallbackCookie cookie) 163 generates (int32_t retval, SoundModelHandle modelHandle); 164 165 /** 166 * Load a key phrase sound model. Once loaded, recognition of this model can 167 * be started and stopped. Only one active recognition per model at a time. 168 * The SoundTrigger service must handle concurrent recognition requests by 169 * different users/applications on the same model. 170 * The implementation returns a unique handle used by other functions 171 * (unloadSoundModel(), startRecognition(), etc... 172 * @param soundModel A PhraseSoundModel structure describing the sound model 173 * to load. 174 * @param callback The callback interface on which the soundmodelCallback() 175 * method will be called upon completion. 176 * @param cookie The value of the cookie argument passed to the completion 177 * callback. This unique context information is assigned and 178 * used only by the framework. 179 * @return retval Operation completion status: 0 in case of success, 180 * -EINVAL in case of invalid sound model (e.g 0 data size), 181 * -ENOSYS in case of invalid operation (e.g max number of 182 * models exceeded), 183 * -ENOMEM in case of memory allocation failure, 184 * -ENODEV in case of initialization error. 185 * @return modelHandle A unique handle assigned by the HAL for use by the 186 * framework when controlling activity for this sound model. 187 */ 188 loadPhraseSoundModel(PhraseSoundModel soundModel, 189 ISoundTriggerHwCallback callback, 190 CallbackCookie cookie) 191 generates (int32_t retval, SoundModelHandle modelHandle); 192 193 /** 194 * Unload a sound model. A sound model may be unloaded to make room for a 195 * new one to overcome implementation limitations. 196 * @param modelHandle the handle of the sound model to unload 197 * @return retval Operation completion status: 0 in case of success, 198 * -ENOSYS if the model is not loaded, 199 * -ENODEV in case of initialization error. 200 */ 201 unloadSoundModel(SoundModelHandle modelHandle) 202 generates (int32_t retval); 203 204 /** 205 * Start recognition on a given model. Only one recognition active 206 * at a time per model. Once recognition succeeds of fails, the callback 207 * is called. 208 * @param modelHandle the handle of the sound model to use for recognition 209 * @param config A RecognitionConfig structure containing attributes of the 210 * recognition to perform 211 * @param callback The callback interface on which the recognitionCallback() 212 * method must be called upon recognition. 213 * @param cookie The value of the cookie argument passed to the recognition 214 * callback. This unique context information is assigned and 215 * used only by the framework. 216 * @return retval Operation completion status: 0 in case of success, 217 * -EINVAL in case of invalid recognition attributes, 218 * -ENOSYS in case of invalid model handle, 219 * -ENOMEM in case of memory allocation failure, 220 * -ENODEV in case of initialization error. 221 */ 222 startRecognition(SoundModelHandle modelHandle, 223 RecognitionConfig config, 224 ISoundTriggerHwCallback callback, 225 CallbackCookie cookie) 226 generates (int32_t retval); 227 228 /** 229 * Stop recognition on a given model. 230 * The implementation must not call the recognition callback when stopped 231 * via this method. 232 * @param modelHandle The handle of the sound model to use for recognition 233 * @return retval Operation completion status: 0 in case of success, 234 * -ENOSYS in case of invalid model handle, 235 * -ENODEV in case of initialization error. 236 */ 237 stopRecognition(SoundModelHandle modelHandle) 238 generates (int32_t retval); 239 240 /** 241 * Stop recognition on all models. 242 * @return retval Operation completion status: 0 in case of success, 243 * -ENODEV in case of initialization error. 244 */ 245 stopAllRecognitions() 246 generates (int32_t retval); 247}; 248