xref: /hardware/interfaces/soundtrigger/2.0/ISoundTriggerHwCallback.hal

/*
 * Copyright 2016 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package android.hardware.soundtrigger@2.0;

import android.hardware.audio.common@2.0;

interface ISoundTriggerHwCallback {
    enum RecognitionStatus : uint32_t {
        SUCCESS  = 0,
        ABORT    = 1,
        FAILURE  = 2,
    };

    enum SoundModelStatus : uint32_t {
        UPDATED  = 0,
    };

    /**
     * Generic recognition event sent via recognition callback
     */
    struct RecognitionEvent {
        /** Recognition status e.g. SUCCESS */
        RecognitionStatus status;
        /** Sound model type for this event. e.g SoundModelType.TYPE_KEYPHRASE */
        SoundModelType    type;
        /** Handle of loaded sound model which triggered the event */
        SoundModelHandle  model;
        /** It is possible to capture audio from this */
        /** utterance buffered by the implementation */
        bool              captureAvailable;
        /** Audio session ID. framework use */
        int32_t           captureSession;
        /**
         * Delay in ms between end of model detection and start of audio
        /**
         * available for capture. A negative value is possible
         * (e.g. if key phrase is also available for capture */
        int32_t           captureDelayMs;
        /**
         * Duration in ms of audio captured before the start of the trigger.
         * 0 if none. */
        int32_t           capturePreambleMs;
        /** The opaque data is the capture of the trigger sound */
        bool              triggerInData;
        /**
         * Audio format of either the trigger in event data or to use for
         * capture of the rest of the utterance */
        AudioConfig       audioConfig;
        /** Opaque event data */
        vec<uint8_t>      data;
    };

    /**
     * Specialized recognition event for key phrase recognitions
     */
    struct PhraseRecognitionEvent {
        /** Common part of the recognition event */
        RecognitionEvent common;
        /** List of descriptors for each recognized key phrase */
        vec<PhraseRecognitionExtra> phraseExtras;
    };

    /**
     * Event sent via load sound model callback
     */
    struct ModelEvent {
         /** Sound model status e.g. SoundModelStatus.UPDATED */
        SoundModelStatus status;
        /** Loaded sound model that triggered the event */
        SoundModelHandle model;
        /** Opaque event data, passed transparently by the framework */
        vec<uint8_t>     data;
    };

    typedef int32_t CallbackCookie;

    /**
     * Callback method called by the HAL when the sound recognition triggers
     * @param event A RecognitionEvent structure containing detailed results
     *              of the recognition triggered
     * @param cookie The cookie passed by the framework when recognition was
     *               started (see ISoundtriggerHw.startRecognition()
     */
    recognitionCallback(RecognitionEvent event, CallbackCookie cookie);

    /**
     * Callback method called by the HAL when the sound recognition triggers
     * for a key phrase sound model.
     * @param event A RecognitionEvent structure containing detailed results
     *              of the recognition triggered
     * @param cookie The cookie passed by the framework when recognition was
     *               started (see ISoundtriggerHw.startRecognition()
     */
    phraseRecognitionCallback(PhraseRecognitionEvent event,
                              CallbackCookie cookie);
    /**
     * Callback method called by the HAL when the sound model loading completes
     * @param event A ModelEvent structure containing detailed results of the
     *              model loading operation
     * @param cookie The cookie passed by the framework when loading was
     *               initiated (see ISoundtriggerHw.loadSoundModel()
     */
    soundModelCallback(ModelEvent event, CallbackCookie cookie);
};