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
21interface ISoundTriggerHwCallback {
22    enum RecognitionStatus : uint32_t {
23        SUCCESS  = 0,
24        ABORT    = 1,
25        FAILURE  = 2,
26    };
27
28    enum SoundModelStatus : uint32_t {
29        UPDATED  = 0,
30    };
31
32    /**
33     * Generic recognition event sent via recognition callback
34     */
35    struct RecognitionEvent {
36        /** Recognition status e.g. SUCCESS */
37        RecognitionStatus status;
38        /** Sound model type for this event. e.g SoundModelType.TYPE_KEYPHRASE */
39        SoundModelType    type;
40        /** Handle of loaded sound model which triggered the event */
41        SoundModelHandle  model;
42        /** It is possible to capture audio from this */
43        /** utterance buffered by the implementation */
44        bool              captureAvailable;
45        /** Audio session ID. framework use */
46        int32_t           captureSession;
47        /**
48         * Delay in ms between end of model detection and start of audio
49         * available for capture. A negative value is possible
50         * (e.g. if key phrase is also available for capture */
51        int32_t           captureDelayMs;
52        /**
53         * Duration in ms of audio captured before the start of the trigger.
54         * 0 if none. */
55        int32_t           capturePreambleMs;
56        /** The opaque data is the capture of the trigger sound */
57        bool              triggerInData;
58        /**
59         * Audio format of either the trigger in event data or to use for
60         * capture of the rest of the utterance */
61        AudioConfig       audioConfig;
62        /** Opaque event data */
63        vec<uint8_t>      data;
64    };
65
66    /**
67     * Specialized recognition event for key phrase recognitions
68     */
69    struct PhraseRecognitionEvent {
70        /** Common part of the recognition event */
71        RecognitionEvent common;
72        /** List of descriptors for each recognized key phrase */
73        vec<PhraseRecognitionExtra> phraseExtras;
74    };
75
76    /**
77     * Event sent via load sound model callback
78     */
79    struct ModelEvent {
80         /** Sound model status e.g. SoundModelStatus.UPDATED */
81        SoundModelStatus status;
82        /** Loaded sound model that triggered the event */
83        SoundModelHandle model;
84        /** Opaque event data, passed transparently by the framework */
85        vec<uint8_t>     data;
86    };
87
88    typedef int32_t CallbackCookie;
89
90    /**
91     * Callback method called by the HAL when the sound recognition triggers
92     * @param event A RecognitionEvent structure containing detailed results
93     *              of the recognition triggered
94     * @param cookie The cookie passed by the framework when recognition was
95     *               started (see ISoundtriggerHw.startRecognition()
96     */
97    recognitionCallback(RecognitionEvent event, CallbackCookie cookie);
98
99    /**
100     * Callback method called by the HAL when the sound recognition triggers
101     * for a key phrase sound model.
102     * @param event A RecognitionEvent structure containing detailed results
103     *              of the recognition triggered
104     * @param cookie The cookie passed by the framework when recognition was
105     *               started (see ISoundtriggerHw.startRecognition()
106     */
107    phraseRecognitionCallback(PhraseRecognitionEvent event,
108                              CallbackCookie cookie);
109    /**
110     * Callback method called by the HAL when the sound model loading completes
111     * @param event A ModelEvent structure containing detailed results of the
112     *              model loading operation
113     * @param cookie The cookie passed by the framework when loading was
114     *               initiated (see ISoundtriggerHw.loadSoundModel()
115     */
116    soundModelCallback(ModelEvent event, CallbackCookie cookie);
117};
118