Package: android.hardware.soundtrigger@2.0

ISoundTriggerHw

interface ISoundTriggerHw

Properties

Properties

struct Properties {string implementor; string description; uint32_t version; Uuid uuid; uint32_t maxSoundModels; uint32_t maxKeyPhrases; uint32_t maxUsers; uint32_t recognitionModes; bool captureTransition; uint32_t maxBufferMs; bool concurrentCapture; bool triggerInEvent; uint32_t powerConsumptionMw}

Sound trigger implementation descriptor read by the framework via getProperties().Used by SoundTrigger service to report to applications and manage concurrency and policy.

Details
Members
implementor
Implementor name
description
Implementation description
version
Implementation version
uuid
Unique implementation ID.The UUID must change with each version of the engine implementation
maxSoundModels
Maximum number of concurrent sound models loaded
maxKeyPhrases
Maximum number of key phrases
maxUsers
Maximum number of concurrent users detected
recognitionModes
All supported modes.e.g RecognitionMode.VOICE_TRIGGER
captureTransition
Supports seamless transition from detection to capture
maxBufferMs
Maximum buffering capacity in ms if captureTransition is true
concurrentCapture
Supports capture by other use cases while detection is active
triggerInEvent
Returns the trigger capture in event
powerConsumptionMw
Rated power consumption when detection is active with TDB silence/sound/speech ratio

SoundModel

struct SoundModel {SoundModelType type; Uuid uuid; Uuid vendorUuid; vec data}

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.

Details
Members
type
Model type.e.g.SoundModelType.KEYPHRASE
uuid
Unique sound model ID.
vendorUuid
Unique vendor ID.Identifies the engine the sound model was build for
data
Opaque data transparent to Android framework

Phrase

struct Phrase {uint32_t id; uint32_t recognitionModes; vec users; string locale; string text}

Key phrase descriptor

Details
Members
id
Unique keyphrase ID assigned at enrollment time
recognitionModes
Recognition modes supported by this key phrase
users
List of users IDs associated with this key phrase
locale
Locale - Java Locale style(e.g.en_US )
text
Phrase text in UTF-8 format.

PhraseSoundModel

struct PhraseSoundModel {SoundModel common; vec phrases}

Specialized sound model for key phrase detection.Proprietary representation of key phrases in binary data must match information indicated by phrases field

Details
Members
common
Common part of sound model descriptor
phrases
List of descriptors for key phrases supported by this sound model

RecognitionConfig

struct RecognitionConfig {AudioIoHandle captureHandle; AudioDevice captureDevice; bool captureRequested; vec phrases; vec data}

Configuration for sound trigger capture session passed to startRecognition() method

Details
Members
captureHandle
IO handle that will be used for capture.N/A if captureRequested is false
captureDevice
Input device requested for detection capture
captureRequested
Capture and buffer audio for this recognition instance
phrases
Configuration for each key phrase
data
Opaque capture configuration data transparent to the framework

Methods

getProperties

getProperties ()
generates (int32_t retval, Properties properties)

Retrieve implementation properties.

Details
Generates
retval
Operation completion status:0 in case of success, -ENODEV in case of initialization error.
properties
A Properties structure containing implementation description and capabilities.

loadSoundModel

loadSoundModel (SoundModel soundModel, ISoundTriggerHwCallback callback, CallbackCookie cookie)
generates (int32_t retval, SoundModelHandle modelHandle)

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...

Details
Parameters
soundModel
A SoundModel structure describing the sound model to load.
callback
The callback interface on which the soundmodelCallback() method will be called upon completion.
cookie
The value of the cookie argument passed to the completion callback.This unique context information is assigned and used only by the framework.
Generates
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.
modelHandle
A unique handle assigned by the HAL for use by the framework when controlling activity for this sound model.

loadPhraseSoundModel

loadPhraseSoundModel (PhraseSoundModel 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...

Details
Parameters
soundModel
A PhraseSoundModel structure describing the sound model to load.
callback
The callback interface on which the soundmodelCallback() method will be called upon completion.
cookie
The value of the cookie argument passed to the completion callback.This unique context information is assigned and used only by the framework.
Generates
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.
modelHandle
A unique handle assigned by the HAL for use by the framework when controlling activity for this sound model.

unloadSoundModel

unloadSoundModel (SoundModelHandle modelHandle)
generates (int32_t retval)

Unload a sound model.A sound model may be unloaded to make room for a new one to overcome implementation limitations.

Details
Parameters
modelHandle
the handle of the sound model to unload
Generates
retval
Operation completion status:0 in case of success, -ENOSYS if the model is not loaded, -ENODEV in case of initialization error.

startRecognition

startRecognition (SoundModelHandle modelHandle, RecognitionConfig config, ISoundTriggerHwCallback callback, CallbackCookie cookie)
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.

Details
Parameters
modelHandle
the handle of the sound model to use for recognition
config
A RecognitionConfig structure containing attributes of the recognition to perform
callback
The callback interface on which the recognitionCallback() method must be called upon recognition.
cookie
The value of the cookie argument passed to the recognition callback.This unique context information is assigned and used only by the framework.
Generates
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.

stopRecognition

stopRecognition (SoundModelHandle modelHandle)
generates (int32_t retval)

Stop recognition on a given model.The implementation must not call the recognition callback when stopped via this method.

Details
Parameters
modelHandle
The handle of the sound model to use for recognition
Generates
retval
Operation completion status:0 in case of success, -ENOSYS in case of invalid model handle, -ENODEV in case of initialization error.

stopAllRecognitions

stopAllRecognitions ()
generates (int32_t retval)

Stop recognition on all models.

Details
Generates
retval
Operation completion status:0 in case of success, -ENODEV in case of initialization error.