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