1 /*---------------------------------------------------------------------------* 2 * audioin.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 __AUDIOIN_H__ 21 #define __AUDIOIN_H__ 22 /* -------------------------------------------------------------------------+ 23 | ScanSoft Inc. | 24 + -------------------------------------------------------------------------*/ 25 26 27 28 /* -------------------------------------------------------------------------+ 29 | Project : ScanSoft AudioIn component 30 | Module : AUDIOIN 31 | File name : audioin.h 32 | Description : Interface definition for AUDIOIN 33 | Reference(s) : wavein, audioin.chm, audioin.doc, audioin.hlp 34 | SltGl00001_audioin_gl1.doc 35 | Status : Version 1.2 36 + -------------------------------------------------------------------------*/ 37 /* Oct/8/2002: Fixes for Windows 2000, and memory leaks. Version 1.1 */ 38 /* PVP Jan/8/2004: Default audio format changed to 16kHz. Version 2.0 */ 39 /*--------------------------------------------------------------------------*/ 40 41 /* @doc AUDIOININTERFACE */ 42 43 44 #include "audioinerr.h" 45 46 #if defined( __cplusplus ) 47 extern "C" 48 { 49 #endif 50 51 /* -------------------------------------------------------------------------+ 52 | MACROS | 53 + -------------------------------------------------------------------------*/ 54 55 /* none */ 56 57 /* -------------------------------------------------------------------------+ 58 | TYPE DEFINITIONS | 59 + -------------------------------------------------------------------------*/ 60 61 typedef short audioinSample; 62 63 64 /* Type Definitions for SCANSOFT-TYPES (re-definition)*/ 65 66 /* @type AUDIOIN_H | Handle to an audio-in component. 67 * @comm Type is declared as a void *. The actual implementation is 68 * done by the implementation engineer. */ 69 typedef void * AUDIOIN_H; 70 #define WAVE_MAPPER 0 71 /* @enum AUDIOIN_STATUSINFO | Enumerator for the Status Information of the AudioIn component. 72 * @comm The information contained in this definition concerns not only to the status of 73 * the FIFO but also the general status of the audio component. 74 * 75 * @xref <f lh_audioinGetSamples>(), AudioIn Diagram State */ 76 typedef enum _AUDIOIN_STATUSINFO { 77 AUDIOIN_NORMAL, /* @emem Normal state of the audio buffer. No problems detected while retrieving 78 samples.*/ 79 AUDIOIN_TIMEOUT, /* @emem The audio-in component timed out after no audio was received from the 80 audio device. The MMSystem is not providing any more samples, or the 81 lh_audioinGetSamples function may be called much faster than the actual 82 thread filling the buffer (Probable issue with the audio device). This could 83 be fixed by decreasing the number of samples that you want to retrieve or by 84 waiting till samples are available. A time out period is set internally on 85 the audioin implementation. Default of: 86 <nlpar>const DWORD GETSAMPLESTIMEOUT_PERIOD = 10000; (time in milliseconds)*/ 87 AUDIOIN_HIGHWATERMARK,/* @emem The buffer has been filled out with 75% or more. A high watermark on 88 the audio buffer has been detected and the buffer could be close to an OVERRUN 89 state.*/ 90 AUDIOIN_FIFOOVERRUN, /* @emem The buffer has been overfilled with audio samples. You can still retrieve 91 samples from the FIFO with the lhs_audioinGetSamples function, but the audio-in 92 component will not buffer any new audio into the FIFO. AudioinStop must be 93 called to reset the audio-in component.*/ 94 AUDIOIN_FLUSHED, /* @emem The buffer has been overfilled with audio samples. You can no longer retrieve 95 samples from the FIFO, since you already emptied it with lhs_audioinGetSamples. 96 The audio-in component will not buffer any new audio into the FIFO. 97 lhs_audioinStop must be called in the audio-in component since 98 lhs_audioinGetSamples will not longer work.*/ 99 AUDIOIN_HWOVERRUN, /* @emem The buffer has been overfilled with audio samples inside the device component 100 (audio device). lhs_audioinStop should be called to reset the contents of the 101 FIFO and the codec. This state is caused by an error in the MMSystem. It is 102 recommended to initialize the audio-in component before retrieving samples 103 again.*/ 104 } AUDIOIN_STATUSINFO; 105 106 107 /* @struct AUDIOIN_INFO | Structure for the AudioIn Information 108 * @comm The AUDIOIN_INFO contains information about several parts of the audio-in component. 109 * It gives information about the FIFO buffering audio and at the same time about the audio 110 * component. 111 * 112 * @xref <f lh_audioinGetSamples>(), AudioIn Diagram State */ 113 typedef struct _AUDIOIN_INFO{ 114 AUDIOIN_STATUSINFO eStatusInfo; /* @field The state in which the audio Buffer of the audio-in component 115 is. This is detailed in AUDIOIN_STATUSINFO. */ 116 unsigned long u32SamplesAvailable; /* @field The number of Samples still available in the audio Buffer after 117 lhs_audioinGetSamples is called. This value can help you to 118 detect over-runs in the audio buffer.*/ 119 } AUDIOIN_INFO; 120 121 #ifdef AUDIOIN_SUPPORT_CALLBACK 122 typedef enum _AUDIOIN_MSG { 123 AUDIOIN_MSG_OPEN, // audio device was opened 124 AUDIOIN_MSG_START, // start audio acquisition 125 AUDIOIN_MSG_DATA, // audio samples are available 126 AUDIOIN_MSG_STOP, // stop audio acquisition 127 AUDIOIN_MSG_CLOSE, // audio device was closed 128 AUDIOIN_MSG_INVALID, // bogus 129 } AUDIOIN_MSG; 130 131 /* callback function for "samples ready" notification */ 132 typedef void (*pCallbackFunc)(AUDIOIN_H hAudioIn, AUDIOIN_MSG uMsg, void* dwInstance, void* dwParam1, void* dwParam2); 133 134 /* data structure passed to callback function; loosely based on Windows' WAVEHDR */ 135 typedef struct { 136 void *pData; 137 unsigned long nBufferLength; 138 unsigned long nBytesRecorded; 139 AUDIOIN_STATUSINFO status; 140 } AUDIOIN_WAVEHDR; 141 #endif 142 143 /* -------------------------------------------------------------------------+ 144 | EXTERNAL DATA (+ meaning) | 145 + -------------------------------------------------------------------------*/ 146 147 /* none */ 148 149 /* -------------------------------------------------------------------------+ 150 | GLOBAL FUNCTION PROTOTYPES | 151 + -------------------------------------------------------------------------*/ 152 #if 0 153 LHS_AUDIOIN_ERROR lhs_audioinOpenEx ( 154 unsigned long u32AudioInID, /*@parm [in] Audio-in device ID (ranges from 0 to a number of available 155 devices on the system). You can also use the following flag 156 instead of a device identifier. 157 <nl><nl><bold WAVE_MAPPER> = The function selects a 158 waveform-audio input device capable of recording in the 159 specified format. <bold Header:> Declared in Mmsystem.h from 160 the Windows Multimedia: Platform SDK.*/ 161 unsigned long u32Frequency, /*@parm [in] Frequency of the recognition engine in Hz. */ 162 unsigned long u32NbrOfFrames, /*@parm [in] (not used) Number of frames buffered internally */ 163 unsigned long u32SamplesPerFrame, /*@parm [in] Size, in samples, of each individual frame. */ 164 AUDIOIN_H * phAudioIn /*@parm [out] Handle to the audio-in device */ 165 ); 166 #endif 167 168 LHS_AUDIOIN_ERROR lhs_audioinOpen( 169 unsigned long u32AudioInID, /* [in] audio-in device ID (ranges from 0 to a number of available devices on the 170 system). You can also use the following flag instead of a device identifier. 171 <nl><nl><bold WAVE_MAPPER> = The function selects a waveform-audio input 172 device capable of recording in the specified format. <bold Header:> 173 Declared in Mmsystem.h from the Windows Multimedia: Platform SDK.*/ 174 unsigned long u32Frequency, /* [in] Frequency of the recognition engine in Hz. */ 175 AUDIOIN_H * phAudioIn /* [out] Handle to the audio-in device */ 176 ); 177 178 #ifdef AUDIOIN_SUPPORT_CALLBACK 179 LHS_AUDIOIN_ERROR lhs_audioinOpenCallback( 180 unsigned long u32AudioInID, /* [in] audio-in device ID (ranges from 0 to a number of available devices on the 181 system). You can also use the following flag instead of a device identifier. 182 <nl><nl><bold WAVE_MAPPER> = The function selects a waveform-audio input 183 device capable of recording in the specified format. <bold Header:> 184 Declared in Mmsystem.h from the Windows Multimedia: Platform SDK.*/ 185 unsigned long u32Frequency, /* [in] Frequency of the recognition engine in Hz. */ 186 unsigned long u32NbrOfSamples, /*[in] <nl><bold Input:> Number of samples requested per callback */ 187 188 pCallbackFunc pCallback, /* [in] callback function */ 189 void *pCallbackInstance, /* [in] callback instance */ 190 AUDIOIN_H * phAudioIn /* [out] Handle to the audio-in device */ 191 ); 192 #endif 193 194 LHS_AUDIOIN_ERROR lhs_audioinClose( 195 AUDIOIN_H * phAudioIn /*[in] Pointer to the handle of the audio-in device to be closed.*/ 196 ); 197 198 LHS_AUDIOIN_ERROR lhs_audioinStart( 199 AUDIOIN_H hAudioIn /*[in] Handle of the audio-in device */ 200 ); 201 202 LHS_AUDIOIN_ERROR lhs_audioinStop( 203 AUDIOIN_H hAudioIn /*[in] Handle of the audio-in device*/ 204 ); 205 206 LHS_AUDIOIN_ERROR lhs_audioinGetSamples ( 207 AUDIOIN_H hAudioIn, /*[in] Handle of the audio-in device */ 208 unsigned long * u32NbrOfSamples, /*[in/out] <nl><bold Input:> The requested number of samples to be filled in 209 the pAudioBuffer. Note that the memory used for pBuffer should be large enough 210 to contain the requested number of samples, also note how the u32NbrOfSamples 211 is different than the Buffer size, since each frame has an specific size depending 212 on the audio format. 213 <nl><bold Output:> The actual number of recorded audio samples written in pBuffer. 214 If you pass 0 to this parameter then you may still retrieve the AUDIOIN_STATUSINFO 215 on the audio component. */ 216 void * pAudioBuffer, /*[out] Buffer that contains the recorded samples. The memory used for this 217 buffer is allocated by the client. So, it is the responsibility of the client to 218 make sure that this memory can contain the requested number of samples. The memory 219 for this buffer needs also to be freed by the client. */ 220 AUDIOIN_INFO * pAudioInInfo /*[out] Information about the audio internal buffer described in 221 AUDIOIN_INFO.*/ 222 ); 223 224 225 LHS_AUDIOIN_ERROR lhs_audioinGetVersion( 226 unsigned long * pu32Version /*[out] The version number of the API implementation. */ 227 ); 228 229 230 LHS_AUDIOIN_ERROR lhs_audioinGetVolume( 231 AUDIOIN_H hAudioIn, /*[in] Handle of the audio-in device.*/ 232 unsigned long * pu32Volume /*[out] Pointer to a variable that will be filled with the current volume 233 (normally range of 0 - 65535). Depending on the platform the volume 234 value may be set to in sizes of 16, 32 or other size, the range also 235 depends on the platform (Implementations of this interface may 236 change because of the compatibility of the internal function).*/ 237 ); 238 239 LHS_AUDIOIN_ERROR lhs_audioinSetVolume( 240 AUDIOIN_H hAudioIn, /*[in] Handle of the audio-in device.*/ 241 unsigned long u32Volume /*[in] The volume to be set (normal range 0-65535). Depending on the 242 platform the volume value may be set to in sizes of 16, 32 or other size, 243 the range also depends on the platform. (Implementations of this interface 244 may change because of the compatibility of the internal function)*/ 245 ); 246 247 248 const TCHAR * lhs_audioinErrorGetString( 249 const LHS_AUDIOIN_ERROR Error /*[in] The Error code.*/ 250 ); 251 252 253 /* -------------------------------------------------------------------------+ 254 | END | 255 + -------------------------------------------------------------------------*/ 256 257 #if defined( __cplusplus ) 258 } 259 #endif 260 261 262 #endif /* #ifndef __AUDIOIN_H__ */ 263