1 /* 2 * Copyright (C) 2019 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 17 package android.media.soundtrigger_middleware; 18 19 import android.media.soundtrigger.ModelParameter; 20 import android.media.soundtrigger.ModelParameterRange; 21 import android.media.soundtrigger.SoundModel; 22 import android.media.soundtrigger.PhraseSoundModel; 23 import android.media.soundtrigger.RecognitionConfig; 24 25 /** 26 * A sound-trigger module. 27 * 28 * This interface allows a client to operate a sound-trigger device, intended for low-power 29 * detection of various sound patterns, represented by a "sound model". 30 * 31 * Basic operation is to load a sound model (either a generic one or a "phrase" model), then 32 * initiate recognition on this model. A trigger will be delivered asynchronously via a callback 33 * provided by the caller earlier, when attaching to this interface. 34 * 35 * In additon to recognition events, this module will also produce abort events in cases where 36 * recognition has been externally preempted. 37 * 38 * {@hide} 39 */ 40 interface ISoundTriggerModule { 41 /** 42 * Load a sound model. Will return a handle to the model on success or will throw a 43 * ServiceSpecificException with one of the {@link Status} error codes upon a recoverable error 44 * (for example, lack of resources of loading a model at the time of call. 45 * Model must eventually be unloaded using {@link #unloadModel(int)} prior to detaching. 46 * 47 * May throw a ServiceSpecificException with an RESOURCE_CONTENTION status to indicate that 48 * resources required for loading the model are currently consumed by other clients. 49 */ loadModel(in SoundModel model)50 int loadModel(in SoundModel model); 51 52 /** 53 * Load a phrase sound model. Will return a handle to the model on success or will throw a 54 * ServiceSpecificException with one of the {@link Status} error codes upon a recoverable error 55 * (for example, lack of resources of loading a model at the time of call. 56 * Model must eventually be unloaded using unloadModel prior to detaching. 57 * 58 * May throw a ServiceSpecificException with an RESOURCE_CONTENTION status to indicate that 59 * resources required for loading the model are currently consumed by other clients. 60 */ loadPhraseModel(in PhraseSoundModel model)61 int loadPhraseModel(in PhraseSoundModel model); 62 63 /** 64 * Unload a model, previously loaded with loadModel or loadPhraseModel. After unloading, model 65 * can no longer be used for recognition and the resources occupied by it are released. 66 * Model must not be active at the time of unloading. Cient may call stopRecognition to ensure 67 * that. 68 */ unloadModel(int modelHandle)69 void unloadModel(int modelHandle); 70 71 /** 72 * Initiate recognition on a previously loaded model. 73 * Recognition event would eventually be delivered via the client-provided callback, typically 74 * supplied during attachment to this interface. 75 * 76 * Once a recognition event is passed to the client, the recognition automatically become 77 * inactive, unless the event is of the RecognitionStatus.FORCED kind. Client can also shut down 78 * the recognition explicitly, via stopRecognition. 79 * 80 * May throw a ServiceSpecificException with an RESOURCE_CONTENTION status to indicate that 81 * resources required for starting the model are currently consumed by other clients. 82 * @return - A token delivered along with future recognition events. 83 */ startRecognition(int modelHandle, in RecognitionConfig config)84 IBinder startRecognition(int modelHandle, in RecognitionConfig config); 85 86 /** 87 * Stop a recognition of a previously active recognition. Will NOT generate a recognition event. 88 * This call is idempotent - calling it on an inactive model has no effect. However, it must 89 * only be used with a loaded model handle. 90 */ stopRecognition(int modelHandle)91 void stopRecognition(int modelHandle); 92 93 /** 94 * Force generation of a recognition event. Handle must be that of a loaded model. If 95 * recognition is inactive, will do nothing. If recognition is active, will asynchronously 96 * deliever an event with RecognitionStatus.FORCED status and leave recognition in active state. 97 * To avoid any race conditions, once an event signalling the automatic stopping of recognition 98 * is sent, no more forced events will get sent (even if previously requested) until recognition 99 * is explicitly started again. 100 * 101 * Since not all module implementations support this feature, may throw a 102 * ServiceSpecificException with an OPERATION_NOT_SUPPORTED status. 103 */ forceRecognitionEvent(int modelHandle)104 void forceRecognitionEvent(int modelHandle); 105 106 /** 107 * Set a model specific parameter with the given value. This parameter 108 * will keep its value for the duration the model is loaded regardless of starting and stopping 109 * recognition. Once the model is unloaded, the value will be lost. 110 * It is expected to check if the handle supports the parameter via the 111 * queryModelParameterSupport API prior to calling this method. 112 * 113 * @param modelHandle The sound model handle indicating which model to modify parameters 114 * @param modelParam Parameter to set which will be validated against the 115 * ModelParameter type. 116 * @param value The value to set for the given model parameter 117 */ setModelParameter(int modelHandle, ModelParameter modelParam, int value)118 void setModelParameter(int modelHandle, ModelParameter modelParam, int value); 119 120 /** 121 * Get a model specific parameter. This parameter will keep its value 122 * for the duration the model is loaded regardless of starting and stopping recognition. 123 * Once the model is unloaded, the value will be lost. If the value is not set, a default 124 * value is returned. See ModelParameter for parameter default values. 125 * It is expected to check if the handle supports the parameter via the 126 * queryModelParameterSupport API prior to calling this method. 127 * 128 * @param modelHandle The sound model associated with given modelParam 129 * @param modelParam Parameter to set which will be validated against the 130 * ModelParameter type. 131 * @return Value set to the requested parameter. 132 */ getModelParameter(int modelHandle, ModelParameter modelParam)133 int getModelParameter(int modelHandle, ModelParameter modelParam); 134 135 /** 136 * Determine if parameter control is supported for the given model handle, and its valid value 137 * range if it is. 138 * 139 * @param modelHandle The sound model handle indicating which model to query 140 * @param modelParam Parameter to set which will be validated against the 141 * ModelParameter type. 142 * @return If parameter is supported, the return value is its valid range, otherwise null. 143 */ queryModelParameterSupport(int modelHandle, ModelParameter modelParam)144 @nullable ModelParameterRange queryModelParameterSupport(int modelHandle, 145 ModelParameter modelParam); 146 147 /** 148 * Detach from the module, releasing any active resources. 149 * This will ensure the client callback is no longer called after this call returns. 150 * All models must have been unloaded prior to calling this method. 151 */ detach()152 void detach(); 153 } 154