1 /*---------------------------------------------------------------------------* 2 * SR_AcousticState.h * 3 * * 4 * Copyright 2007, 2008 Nuance Communciations, Inc. * 5 * * 6 * Licensed under the Apache License, Version 2.0 (the 'License'); * 7 * you may not use this file except in compliance with the License. * 8 * * 9 * You may obtain a copy of the License at * 10 * http://www.apache.org/licenses/LICENSE-2.0 * 11 * * 12 * Unless required by applicable law or agreed to in writing, software * 13 * distributed under the License is distributed on an 'AS IS' BASIS, * 14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * 15 * See the License for the specific language governing permissions and * 16 * limitations under the License. * 17 * * 18 *---------------------------------------------------------------------------*/ 19 20 #ifndef __SR_ACOUSTICSTATE_H 21 #define __SR_ACOUSTICSTATE_H 22 23 24 25 #include <stddef.h> 26 #include <stdlib.h> 27 #include "SR_AcousticModels.h" 28 #include "SR_AcousticStatePrefix.h" 29 #include "SR_Recognizer.h" 30 #include "pstdio.h" 31 #include "ESR_ReturnCode.h" 32 33 34 /** 35 * @addtogroup SR_AcousticStateModule SR_AcousticState API functions 36 * Contains Acoustic state information. 37 * 38 * @{ 39 */ 40 41 /** 42 * Contains Acoustic state information. 43 */ 44 typedef struct SR_AcousticState_t 45 { 46 /** 47 * Resets the acoustic state object. 48 * The recognizer adapts to the acoustic state of the caller and calling environment 49 * during a call in order to improve recognition accuracy. The platform must reset 50 * the AcousticState either at the beginning of a new call or at the end of a call in 51 * order to reset acoustic state information for a new caller. 52 * 53 * @param recognizer SR_Recognizer handle 54 * @return ESR_INVALID_ARGUMENT if recognizer is null 55 */ 56 ESR_ReturnCode(*reset)(SR_Recognizer* recognizer); 57 /** 58 * Loads an AcousticState from file. 59 * 60 * @param recognizer SR_Recognizer handle 61 * @param file File to read from 62 * @return ESR_INVALID_ARGUMENT if recognizer is null 63 */ 64 ESR_ReturnCode(*load)(SR_Recognizer* recognizer, const LCHAR* filename); 65 /** 66 * Saves an AcousticState to a file. 67 * 68 * @param recognizer SR_Recognizer handle 69 * @param file File to write into 70 * @return ESR_INVALID_ARGUMENT if recognizer is null 71 */ 72 ESR_ReturnCode(*save)(SR_Recognizer* recognizer, const LCHAR* filename); 73 /** 74 * Gets an AcousticState into a string. 75 * 76 * @param recognizer SR_Recognizer handle 77 * @param param_string contains data from the recognizer 78 * @return ESR_INVALID_ARGUMENT if recognizer is null 79 */ 80 ESR_ReturnCode(*get)(SR_Recognizer* recognizer, LCHAR *param_string, size_t* len ); 81 /** 82 * Sets an AcousticState from a string. 83 * 84 * @param recognizer SR_Recognizer handle 85 * @param param_string contains data to set 86 * @return ESR_INVALID_ARGUMENT if recognizer is null 87 */ 88 ESR_ReturnCode(*set)(SR_Recognizer* recognizer, const LCHAR *param_string ); 89 /** 90 * Destrroys the acoustic state of a recognizer 91 * 92 * @param recognizer SR_Recognizer handle 93 * @return ESR_INVALID_ARGUMENT if recognizer is null 94 */ 95 ESR_ReturnCode(*destroy)(SR_Recognizer* recognizer); 96 } 97 SR_AcousticState; 98 99 /** 100 * @name AcousticState 101 * 102 * An AcousticState is a container for the configurations of several items used in recognition: 103 * 104 * - What models are in use (where there is more than one available). E.g. M/F or adapted models. 105 * - Properties of the channels (microphone, environment, speaker). These properties are updated 106 * during recognition. E.g. There may be more than one microphone in use, offering zone-based 107 * input. Each zone may require the maintenance of its own channel settings. 108 * 109 * AcousticState must offer persistence to reflect optimal settings and preferred use on start-up. 110 * 111 * @{ 112 */ 113 114 /** 115 * Loads an AcousticState from file. 116 * 117 * @param recognizer SR_Recognizer handle 118 * @param filename File to read from 119 * @return ESR_INVALID_ARGUMENT if recognizer is null 120 */ 121 SREC_ACOUSTICSTATE_API ESR_ReturnCode SR_AcousticStateLoad(SR_Recognizer* recognizer, const LCHAR* filename); 122 /** 123 * Saves an AcousticState to a file. 124 * 125 * @param recognizer SR_Recognizer handle 126 * @param filename File to write into 127 * @return ESR_NOT_IMPLEMENTED 128 */ 129 SREC_ACOUSTICSTATE_API ESR_ReturnCode SR_AcousticStateSave(SR_Recognizer* recognizer, const LCHAR* filename); 130 /** 131 * @} 132 * 133 * @name Possible AcousticState <-> Model operations 134 * 135 * @{ 136 */ 137 138 /** 139 * Resets the acoustic state object. 140 * The recognizer adapts to the acoustic state of the caller and calling environment 141 * during a call in order to improve recognition accuracy. The platform must reset 142 * the AcousticState either at the beginning of a new call or at the end of a call in 143 * order to reset acoustic state information for a new caller. 144 * 145 * @param recognizer SR_Recognizer handle 146 * @return ESR_INVALID_ARGUMENT if recognizer is null 147 */ 148 SREC_ACOUSTICSTATE_API ESR_ReturnCode SR_AcousticStateReset(SR_Recognizer* recognizer); 149 SREC_ACOUSTICSTATE_API ESR_ReturnCode SR_AcousticStateSet ( SR_Recognizer* recognizer, const LCHAR *param_string ); 150 SREC_ACOUSTICSTATE_API ESR_ReturnCode SR_AcousticStateGet ( SR_Recognizer* recognizer, LCHAR *param_string, size_t* len ); 151 /** 152 * @} 153 */ 154 155 /** 156 * @} 157 */ 158 159 #endif /* __SR_ACOUSTICSTATE_H */ 160
