/* * 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; import ISoundTriggerHwCallback; interface ISoundTriggerHw { /** * Sound trigger implementation descriptor read by the framework via * getProperties(). Used by SoundTrigger service to report to applications * and manage concurrency and policy. */ struct Properties { /** Implementor name */ string implementor; /** Implementation description */ string description; /** Implementation version */ uint32_t version; /** * Unique implementation ID. The UUID must change with each version of the engine implementation */ Uuid uuid; /** Maximum number of concurrent sound models loaded */ uint32_t maxSoundModels; /** Maximum number of key phrases */ uint32_t maxKeyPhrases; /** Maximum number of concurrent users detected */ uint32_t maxUsers; /** All supported modes. e.g RecognitionMode.VOICE_TRIGGER */ uint32_t recognitionModes; /** Supports seamless transition from detection to capture */ bool captureTransition; /** Maximum buffering capacity in ms if captureTransition is true */ uint32_t maxBufferMs; /** Supports capture by other use cases while detection is active */ bool concurrentCapture; /** Returns the trigger capture in event */ bool triggerInEvent; /** * Rated power consumption when detection is active with TDB * silence/sound/speech ratio */ uint32_t powerConsumptionMw; }; /** * Base sound model descriptor. This struct is the header of a larger block * passed to loadSoundModel() and contains the binary data of the * sound model. */ struct SoundModel { /** Model type. e.g. SoundModelType.KEYPHRASE */ SoundModelType type; /** Unique sound model ID. */ Uuid uuid; /** * Unique vendor ID. Identifies the engine the sound model * was build for */ Uuid vendorUuid; /** Opaque data transparent to Android framework */ vec data; }; /** Key phrase descriptor */ struct Phrase { /** Unique keyphrase ID assigned at enrollment time */ uint32_t id; /** Recognition modes supported by this key phrase */ uint32_t recognitionModes; /** List of users IDs associated with this key phrase */ vec users; /** Locale - Java Locale style (e.g. en_US) */ string locale; /** Phrase text in UTF-8 format. */ string text; }; /** * Specialized sound model for key phrase detection. * Proprietary representation of key phrases in binary data must match * information indicated by phrases field */ struct PhraseSoundModel { /** Common part of sound model descriptor */ SoundModel common; /** List of descriptors for key phrases supported by this sound model */ vec phrases; }; /** * Configuration for sound trigger capture session passed to * startRecognition() method */ struct RecognitionConfig { /** * IO handle that will be used for capture. N/A if captureRequested * is false */ AudioIoHandle captureHandle; /** Input device requested for detection capture */ AudioDevice captureDevice; /** Capture and buffer audio for this recognition instance */ bool captureRequested; /** Configuration for each key phrase */ vec phrases; /** Opaque capture configuration data transparent to the framework */ vec data; }; /** * Retrieve implementation properties. * @return retval Operation completion status: 0 in case of success, * -ENODEV in case of initialization error. * @return properties A Properties structure containing implementation * description and capabilities. */ getProperties() generates (int32_t retval, Properties properties); /** * Load a sound model. Once loaded, recognition of this model can be * started and stopped. Only one active recognition per model at a time. * The SoundTrigger service must handle concurrent recognition requests by * different users/applications on the same model. * The implementation returns a unique handle used by other functions * (unloadSoundModel(), startRecognition(), etc... * @param soundModel A SoundModel structure describing the sound model to * load. * @param callback The callback interface on which the soundmodelCallback() * method will be called upon completion. * @param cookie The value of the cookie argument passed to the completion * callback. This unique context information is assigned and * used only by the framework. * @return retval Operation completion status: 0 in case of success, * -EINVAL in case of invalid sound model (e.g 0 data size), * -ENOSYS in case of invalid operation (e.g max number of * models exceeded), * -ENOMEM in case of memory allocation failure, * -ENODEV in case of initialization error. * @return modelHandle A unique handle assigned by the HAL for use by the * framework when controlling activity for this sound model. */ loadSoundModel(SoundModel soundModel, ISoundTriggerHwCallback callback, CallbackCookie cookie) generates (int32_t retval, SoundModelHandle modelHandle); /** * Load a key phrase sound model. Once loaded, recognition of this model can * be started and stopped. Only one active recognition per model at a time. * The SoundTrigger service must handle concurrent recognition requests by * different users/applications on the same model. * The implementation returns a unique handle used by other functions * (unloadSoundModel(), startRecognition(), etc... * @param soundModel A PhraseSoundModel structure describing the sound model * to load. * @param callback The callback interface on which the soundmodelCallback() * method will be called upon completion. * @param cookie The value of the cookie argument passed to the completion * callback. This unique context information is assigned and * used only by the framework. * @return retval Operation completion status: 0 in case of success, * -EINVAL in case of invalid sound model (e.g 0 data size), * -ENOSYS in case of invalid operation (e.g max number of * models exceeded), * -ENOMEM in case of memory allocation failure, * -ENODEV in case of initialization error. * @return modelHandle A unique handle assigned by the HAL for use by the * framework when controlling activity for this sound model. */ loadPhraseSoundModel(PhraseSoundModel soundModel, ISoundTriggerHwCallback callback, CallbackCookie cookie) generates (int32_t retval, SoundModelHandle modelHandle); /** * Unload a sound model. A sound model may be unloaded to make room for a * new one to overcome implementation limitations. * @param modelHandle the handle of the sound model to unload * @return retval Operation completion status: 0 in case of success, * -ENOSYS if the model is not loaded, * -ENODEV in case of initialization error. */ unloadSoundModel(SoundModelHandle modelHandle) generates (int32_t retval); /** * Start recognition on a given model. Only one recognition active * at a time per model. Once recognition succeeds of fails, the callback * is called. * @param modelHandle the handle of the sound model to use for recognition * @param config A RecognitionConfig structure containing attributes of the * recognition to perform * @param callback The callback interface on which the recognitionCallback() * method must be called upon recognition. * @param cookie The value of the cookie argument passed to the recognition * callback. This unique context information is assigned and * used only by the framework. * @return retval Operation completion status: 0 in case of success, * -EINVAL in case of invalid recognition attributes, * -ENOSYS in case of invalid model handle, * -ENOMEM in case of memory allocation failure, * -ENODEV in case of initialization error. */ startRecognition(SoundModelHandle modelHandle, RecognitionConfig config, ISoundTriggerHwCallback callback, CallbackCookie cookie) generates (int32_t retval); /** * Stop recognition on a given model. * The implementation must not call the recognition callback when stopped * via this method. * @param modelHandle The handle of the sound model to use for recognition * @return retval Operation completion status: 0 in case of success, * -ENOSYS in case of invalid model handle, * -ENODEV in case of initialization error. */ stopRecognition(SoundModelHandle modelHandle) generates (int32_t retval); /** * Stop recognition on all models. * @return retval Operation completion status: 0 in case of success, * -ENODEV in case of initialization error. */ stopAllRecognitions() generates (int32_t retval); };