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 17 #ifndef ANDROID_SOUND_TRIGGER_H 18 #define ANDROID_SOUND_TRIGGER_H 19 20 #include <stdbool.h> 21 #include <system/audio.h> 22 23 #define SOUND_TRIGGER_MAX_STRING_LEN 64 /* max length of strings in properties or 24 descriptor structs */ 25 #define SOUND_TRIGGER_MAX_LOCALE_LEN 6 /* max length of locale string. e.g en_US */ 26 #define SOUND_TRIGGER_MAX_USERS 10 /* max number of concurrent users */ 27 #define SOUND_TRIGGER_MAX_PHRASES 10 /* max number of concurrent phrases */ 28 29 typedef enum { 30 SOUND_TRIGGER_STATE_NO_INIT = -1, /* The sound trigger service is not initialized */ 31 SOUND_TRIGGER_STATE_ENABLED = 0, /* The sound trigger service is enabled */ 32 SOUND_TRIGGER_STATE_DISABLED = 1 /* The sound trigger service is disabled */ 33 } sound_trigger_service_state_t; 34 35 #define RECOGNITION_MODE_VOICE_TRIGGER 0x1 /* simple voice trigger */ 36 #define RECOGNITION_MODE_USER_IDENTIFICATION 0x2 /* trigger only if one user in model identified */ 37 #define RECOGNITION_MODE_USER_AUTHENTICATION 0x4 /* trigger only if one user in mode 38 authenticated */ 39 #define RECOGNITION_MODE_GENERIC_TRIGGER 0x8 /* generic sound trigger */ 40 41 #define RECOGNITION_STATUS_SUCCESS 0 42 #define RECOGNITION_STATUS_ABORT 1 43 #define RECOGNITION_STATUS_FAILURE 2 44 45 #define SOUND_MODEL_STATUS_UPDATED 0 46 47 typedef enum { 48 SOUND_MODEL_TYPE_UNKNOWN = -1, /* use for unspecified sound model type */ 49 SOUND_MODEL_TYPE_KEYPHRASE = 0, /* use for key phrase sound models */ 50 SOUND_MODEL_TYPE_GENERIC = 1 /* use for all models other than keyphrase */ 51 } sound_trigger_sound_model_type_t; 52 53 typedef audio_uuid_t sound_trigger_uuid_t; 54 55 /* 56 * sound trigger implementation descriptor read by the framework via get_properties(). 57 * Used by SoundTrigger service to report to applications and manage concurrency and policy. 58 */ 59 struct sound_trigger_properties { 60 char implementor[SOUND_TRIGGER_MAX_STRING_LEN]; /* implementor name */ 61 char description[SOUND_TRIGGER_MAX_STRING_LEN]; /* implementation description */ 62 unsigned int version; /* implementation version */ 63 sound_trigger_uuid_t uuid; /* unique implementation ID. 64 Must change with version each version */ 65 unsigned int max_sound_models; /* maximum number of concurrent sound models 66 loaded */ 67 unsigned int max_key_phrases; /* maximum number of key phrases */ 68 unsigned int max_users; /* maximum number of concurrent users detected */ 69 unsigned int recognition_modes; /* all supported modes. 70 e.g RECOGNITION_MODE_VOICE_TRIGGER */ 71 bool capture_transition; /* supports seamless transition from detection 72 to capture */ 73 unsigned int max_buffer_ms; /* maximum buffering capacity in ms if 74 capture_transition is true*/ 75 bool concurrent_capture; /* supports capture by other use cases while 76 detection is active */ 77 bool trigger_in_event; /* returns the trigger capture in event */ 78 unsigned int power_consumption_mw; /* Rated power consumption when detection is active 79 with TDB silence/sound/speech ratio */ 80 }; 81 82 typedef int sound_trigger_module_handle_t; 83 84 struct sound_trigger_module_descriptor { 85 sound_trigger_module_handle_t handle; 86 struct sound_trigger_properties properties; 87 }; 88 89 typedef int sound_model_handle_t; 90 91 /* 92 * Base sound model descriptor. This struct is the header of a larger block passed to 93 * load_sound_model() and containing the binary data of the sound model. 94 * Proprietary representation of users in binary data must match information indicated 95 * by users field 96 */ 97 struct sound_trigger_sound_model { 98 sound_trigger_sound_model_type_t type; /* model type. e.g. SOUND_MODEL_TYPE_KEYPHRASE */ 99 sound_trigger_uuid_t uuid; /* unique sound model ID. */ 100 sound_trigger_uuid_t vendor_uuid; /* unique vendor ID. Identifies the engine the 101 sound model was build for */ 102 unsigned int data_size; /* size of opaque model data */ 103 unsigned int data_offset; /* offset of opaque data start from head of struct 104 (e.g sizeof struct sound_trigger_sound_model) */ 105 }; 106 107 /* key phrase descriptor */ 108 struct sound_trigger_phrase { 109 unsigned int id; /* keyphrase ID */ 110 unsigned int recognition_mode; /* recognition modes supported by this key phrase */ 111 unsigned int num_users; /* number of users in the key phrase */ 112 unsigned int users[SOUND_TRIGGER_MAX_USERS]; /* users ids: (not uid_t but sound trigger 113 specific IDs */ 114 char locale[SOUND_TRIGGER_MAX_LOCALE_LEN]; /* locale - JAVA Locale style (e.g. en_US) */ 115 char text[SOUND_TRIGGER_MAX_STRING_LEN]; /* phrase text in UTF-8 format. */ 116 }; 117 118 /* 119 * Specialized sound model for key phrase detection. 120 * Proprietary representation of key phrases in binary data must match information indicated 121 * by phrases field 122 */ 123 struct sound_trigger_phrase_sound_model { 124 struct sound_trigger_sound_model common; 125 unsigned int num_phrases; /* number of key phrases in model */ 126 struct sound_trigger_phrase phrases[SOUND_TRIGGER_MAX_PHRASES]; 127 }; 128 129 130 /* 131 * Generic sound model, used for all cases except key phrase detection. 132 */ 133 struct sound_trigger_generic_sound_model { 134 struct sound_trigger_sound_model common; 135 }; 136 137 138 /* 139 * Generic recognition event sent via recognition callback 140 */ 141 struct sound_trigger_recognition_event { 142 int status; /* recognition status e.g. 143 RECOGNITION_STATUS_SUCCESS */ 144 sound_trigger_sound_model_type_t type; /* event type, same as sound model type. 145 e.g. SOUND_MODEL_TYPE_KEYPHRASE */ 146 sound_model_handle_t model; /* loaded sound model that triggered the 147 event */ 148 bool capture_available; /* it is possible to capture audio from this 149 utterance buffered by the 150 implementation */ 151 int capture_session; /* audio session ID. framework use */ 152 int capture_delay_ms; /* delay in ms between end of model 153 detection and start of audio available 154 for capture. A negative value is possible 155 (e.g. if key phrase is also available for 156 capture */ 157 int capture_preamble_ms; /* duration in ms of audio captured 158 before the start of the trigger. 159 0 if none. */ 160 bool trigger_in_data; /* the opaque data is the capture of 161 the trigger sound */ 162 audio_config_t audio_config; /* audio format of either the trigger in 163 event data or to use for capture of the 164 rest of the utterance */ 165 unsigned int data_size; /* size of opaque event data */ 166 unsigned int data_offset; /* offset of opaque data start from start of 167 this struct (e.g sizeof struct 168 sound_trigger_phrase_recognition_event) */ 169 }; 170 171 /* 172 * Confidence level for each user in struct sound_trigger_phrase_recognition_extra 173 */ 174 struct sound_trigger_confidence_level { 175 unsigned int user_id; /* user ID */ 176 unsigned int level; /* confidence level in percent (0 - 100). 177 - min level for recognition configuration 178 - detected level for recognition event */ 179 }; 180 181 /* 182 * Specialized recognition event for key phrase detection 183 */ 184 struct sound_trigger_phrase_recognition_extra { 185 unsigned int id; /* keyphrase ID */ 186 unsigned int recognition_modes; /* recognition modes used for this keyphrase */ 187 unsigned int confidence_level; /* confidence level for mode RECOGNITION_MODE_VOICE_TRIGGER */ 188 unsigned int num_levels; /* number of user confidence levels */ 189 struct sound_trigger_confidence_level levels[SOUND_TRIGGER_MAX_USERS]; 190 }; 191 192 struct sound_trigger_phrase_recognition_event { 193 struct sound_trigger_recognition_event common; 194 unsigned int num_phrases; 195 struct sound_trigger_phrase_recognition_extra phrase_extras[SOUND_TRIGGER_MAX_PHRASES]; 196 }; 197 198 struct sound_trigger_generic_recognition_event { 199 struct sound_trigger_recognition_event common; 200 }; 201 202 /* 203 * configuration for sound trigger capture session passed to start_recognition() 204 */ 205 struct sound_trigger_recognition_config { 206 audio_io_handle_t capture_handle; /* IO handle that will be used for capture. 207 N/A if capture_requested is false */ 208 audio_devices_t capture_device; /* input device requested for detection capture */ 209 bool capture_requested; /* capture and buffer audio for this recognition 210 instance */ 211 unsigned int num_phrases; /* number of key phrases recognition extras */ 212 struct sound_trigger_phrase_recognition_extra phrases[SOUND_TRIGGER_MAX_PHRASES]; 213 /* configuration for each key phrase */ 214 unsigned int data_size; /* size of opaque capture configuration data */ 215 unsigned int data_offset; /* offset of opaque data start from start of this struct 216 (e.g sizeof struct sound_trigger_recognition_config) */ 217 }; 218 219 /* 220 * Event sent via load sound model callback 221 */ 222 struct sound_trigger_model_event { 223 int status; /* sound model status e.g. SOUND_MODEL_STATUS_UPDATED */ 224 sound_model_handle_t model; /* loaded sound model that triggered the event */ 225 unsigned int data_size; /* size of event data if any. Size of updated sound model if 226 status is SOUND_MODEL_STATUS_UPDATED */ 227 unsigned int data_offset; /* offset of data start from start of this struct 228 (e.g sizeof struct sound_trigger_model_event) */ 229 }; 230 231 232 #endif // ANDROID_SOUND_TRIGGER_H 233
