soundtrigger/2.0/ISoundTriggerHw.hal - platform/hardware/interfaces - Git at Google

 /*
  * 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<uint8_t>   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<uint32_t> 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<Phrase> 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<PhraseRecognitionExtra> phrases;
         /** Opaque capture configuration data transparent to the framework */
         vec<uint8_t>    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);
 };
	/*
	* 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<uint8_t> 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<uint32_t> 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<Phrase> 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<PhraseRecognitionExtra> phrases;
	/** Opaque capture configuration data transparent to the framework */
	vec<uint8_t> 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);
	};