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