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