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 * Must be aligned to transmit as raw memory through Binder. 141 */ 142 struct __attribute__((aligned(8))) sound_trigger_recognition_event { 143 int status; /* recognition status e.g. 144 RECOGNITION_STATUS_SUCCESS */ 145 sound_trigger_sound_model_type_t type; /* event type, same as sound model type. 146 e.g. SOUND_MODEL_TYPE_KEYPHRASE */ 147 sound_model_handle_t model; /* loaded sound model that triggered the 148 event */ 149 bool capture_available; /* it is possible to capture audio from this 150 utterance buffered by the 151 implementation */ 152 int capture_session; /* audio session ID. framework use */ 153 int capture_delay_ms; /* delay in ms between end of model 154 detection and start of audio available 155 for capture. A negative value is possible 156 (e.g. if key phrase is also available for 157 capture */ 158 int capture_preamble_ms; /* duration in ms of audio captured 159 before the start of the trigger. 160 0 if none. */ 161 bool trigger_in_data; /* the opaque data is the capture of 162 the trigger sound */ 163 audio_config_t audio_config; /* audio format of either the trigger in 164 event data or to use for capture of the 165 rest of the utterance */ 166 unsigned int data_size; /* size of opaque event data */ 167 unsigned int data_offset; /* offset of opaque data start from start of 168 this struct (e.g sizeof struct 169 sound_trigger_phrase_recognition_event) */ 170 }; 171 172 /* 173 * Confidence level for each user in struct sound_trigger_phrase_recognition_extra 174 */ 175 struct sound_trigger_confidence_level { 176 unsigned int user_id; /* user ID */ 177 unsigned int level; /* confidence level in percent (0 - 100). 178 - min level for recognition configuration 179 - detected level for recognition event */ 180 }; 181 182 /* 183 * Specialized recognition event for key phrase detection 184 */ 185 struct sound_trigger_phrase_recognition_extra { 186 unsigned int id; /* keyphrase ID */ 187 unsigned int recognition_modes; /* recognition modes used for this keyphrase */ 188 unsigned int confidence_level; /* confidence level for mode RECOGNITION_MODE_VOICE_TRIGGER */ 189 unsigned int num_levels; /* number of user confidence levels */ 190 struct sound_trigger_confidence_level levels[SOUND_TRIGGER_MAX_USERS]; 191 }; 192 193 struct sound_trigger_phrase_recognition_event { 194 struct sound_trigger_recognition_event common; 195 unsigned int num_phrases; 196 struct sound_trigger_phrase_recognition_extra phrase_extras[SOUND_TRIGGER_MAX_PHRASES]; 197 }; 198 199 struct sound_trigger_generic_recognition_event { 200 struct sound_trigger_recognition_event common; 201 }; 202 203 /* 204 * configuration for sound trigger capture session passed to start_recognition() 205 */ 206 struct sound_trigger_recognition_config { 207 audio_io_handle_t capture_handle; /* IO handle that will be used for capture. 208 N/A if capture_requested is false */ 209 audio_devices_t capture_device; /* input device requested for detection capture */ 210 bool capture_requested; /* capture and buffer audio for this recognition 211 instance */ 212 unsigned int num_phrases; /* number of key phrases recognition extras */ 213 struct sound_trigger_phrase_recognition_extra phrases[SOUND_TRIGGER_MAX_PHRASES]; 214 /* configuration for each key phrase */ 215 unsigned int data_size; /* size of opaque capture configuration data */ 216 unsigned int data_offset; /* offset of opaque data start from start of this struct 217 (e.g sizeof struct sound_trigger_recognition_config) */ 218 }; 219 220 /* 221 * Event sent via load sound model callback 222 */ 223 struct sound_trigger_model_event { 224 int status; /* sound model status e.g. SOUND_MODEL_STATUS_UPDATED */ 225 sound_model_handle_t model; /* loaded sound model that triggered the event */ 226 unsigned int data_size; /* size of event data if any. Size of updated sound model if 227 status is SOUND_MODEL_STATUS_UPDATED */ 228 unsigned int data_offset; /* offset of data start from start of this struct 229 (e.g sizeof struct sound_trigger_model_event) */ 230 }; 231 232 233 #endif // ANDROID_SOUND_TRIGGER_H 234
