xref: /external/srec/audio/AudioIn/UNIX/include/audioin.h

/*---------------------------------------------------------------------------*
 *  audioin.h  *
 *                                                                           *
 *  Copyright 2007, 2008 Nuance Communciations, Inc.                               *
 *                                                                           *
 *  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.                                           *
 *                                                                           *
 *---------------------------------------------------------------------------*/

#ifndef __AUDIOIN_H__
#define __AUDIOIN_H__
/* -------------------------------------------------------------------------+
 |                               ScanSoft Inc.                              |
 + -------------------------------------------------------------------------*/



/* -------------------------------------------------------------------------+
 | Project       : ScanSoft AudioIn component
 | Module        : AUDIOIN
 | File name     : audioin.h
 | Description   : Interface definition for AUDIOIN
 | Reference(s)  : wavein, audioin.chm, audioin.doc, audioin.hlp
 |                 SltGl00001_audioin_gl1.doc
 | Status        : Version 1.2
 + -------------------------------------------------------------------------*/
/*     Oct/8/2002: Fixes for Windows 2000, and memory leaks. Version 1.1    */
/*  PVP   Jan/8/2004: Default audio format changed to 16kHz. Version 2.0       */
/*--------------------------------------------------------------------------*/

/* @doc AUDIOININTERFACE */


#include "audioinerr.h"

#if defined( __cplusplus )
extern "C"
{
#endif

/* -------------------------------------------------------------------------+
 |   MACROS                                                                 |
 + -------------------------------------------------------------------------*/

/* none */

/* -------------------------------------------------------------------------+
 |   TYPE DEFINITIONS                                                       |
 + -------------------------------------------------------------------------*/

typedef short audioinSample;


/* Type Definitions for SCANSOFT-TYPES (re-definition)*/

/* @type AUDIOIN_H | Handle to an audio-in component.
 * @comm Type is declared as a void *. The actual implementation is
 *       done by the implementation engineer. */
typedef void *  AUDIOIN_H;
#define WAVE_MAPPER 0
/* @enum AUDIOIN_STATUSINFO | Enumerator for the Status Information of the AudioIn component.
 * @comm The information contained in this definition concerns not only to the status of
 *       the FIFO but also the general status of the audio component.
 *
 * @xref <f lh_audioinGetSamples>(), AudioIn Diagram State */
typedef enum _AUDIOIN_STATUSINFO {
  AUDIOIN_NORMAL,       /* @emem Normal state of the audio buffer. No problems detected while retrieving
                                 samples.*/
  AUDIOIN_TIMEOUT,      /* @emem The audio-in component timed out after no audio was received from the
                                 audio device. The MMSystem is not providing any more samples, or the
                                 lh_audioinGetSamples function may be called much faster than the actual
                                 thread filling the buffer (Probable issue with the audio device). This could
                                 be fixed by decreasing the number of samples that you want to retrieve or by
                                 waiting till samples are available. A time out period is set internally on
                                 the audioin implementation. Default of:
                                 <nlpar>const DWORD GETSAMPLESTIMEOUT_PERIOD = 10000; (time in milliseconds)*/
  AUDIOIN_HIGHWATERMARK,/* @emem The buffer has been filled out with 75% or more. A high watermark on
                                 the audio buffer has been detected and the buffer could be close to an OVERRUN
                                 state.*/
  AUDIOIN_FIFOOVERRUN,  /* @emem The buffer has been overfilled with audio samples. You can still retrieve
                                 samples from the FIFO with the lhs_audioinGetSamples function, but the audio-in
                                 component will not buffer any new audio into the FIFO. AudioinStop must be
                                 called to reset the audio-in component.*/
  AUDIOIN_FLUSHED,      /* @emem The buffer has been overfilled with audio samples. You can no longer retrieve
                                 samples from the FIFO, since you already emptied it with lhs_audioinGetSamples.
                                 The audio-in component will not buffer any new audio into the FIFO.
                                 lhs_audioinStop must be called in the audio-in component since
                                 lhs_audioinGetSamples will not longer work.*/
  AUDIOIN_HWOVERRUN,    /* @emem The buffer has been overfilled with audio samples inside the device component
                                 (audio device). lhs_audioinStop should be called to reset the contents of the
                                 FIFO and the codec. This state is caused by an error in the MMSystem. It is
                                 recommended to initialize the audio-in component before retrieving samples
                                 again.*/
} AUDIOIN_STATUSINFO;


/* @struct AUDIOIN_INFO | Structure for the AudioIn Information
 * @comm The AUDIOIN_INFO contains information about several parts of the audio-in component.
 *       It gives information about the FIFO buffering audio and at the same time about the audio
 *       component.
 *
 * @xref <f lh_audioinGetSamples>(), AudioIn Diagram State */
typedef struct _AUDIOIN_INFO{
  AUDIOIN_STATUSINFO eStatusInfo;    /* @field The state in which the audio Buffer of the audio-in component
                                               is. This is detailed in AUDIOIN_STATUSINFO. */
  unsigned long u32SamplesAvailable; /* @field The number of Samples still available in the audio Buffer after
                                               lhs_audioinGetSamples is called. This value can help you to
                                               detect over-runs in the audio buffer.*/
} AUDIOIN_INFO;

#ifdef AUDIOIN_SUPPORT_CALLBACK
typedef enum _AUDIOIN_MSG {
  AUDIOIN_MSG_OPEN,           // audio device was opened
  AUDIOIN_MSG_START,          // start audio acquisition
  AUDIOIN_MSG_DATA,           // audio samples are available
  AUDIOIN_MSG_STOP,           // stop audio acquisition
  AUDIOIN_MSG_CLOSE,          // audio device was closed
  AUDIOIN_MSG_INVALID,        // bogus
} AUDIOIN_MSG;

/* callback function for "samples ready" notification */
typedef void (*pCallbackFunc)(AUDIOIN_H hAudioIn, AUDIOIN_MSG uMsg, void* dwInstance, void* dwParam1, void* dwParam2);

/* data structure passed to callback function; loosely based on Windows' WAVEHDR */
typedef struct {
    void               *pData;
    unsigned long       nBufferLength;
    unsigned long       nBytesRecorded;
    AUDIOIN_STATUSINFO  status;
} AUDIOIN_WAVEHDR;
#endif

/* -------------------------------------------------------------------------+
|   EXTERNAL DATA (+ meaning)                                              |
+ -------------------------------------------------------------------------*/

/* none */

/* -------------------------------------------------------------------------+
|   GLOBAL FUNCTION PROTOTYPES                                             |
+ -------------------------------------------------------------------------*/
#if 0
 LHS_AUDIOIN_ERROR  lhs_audioinOpenEx (
  unsigned long u32AudioInID,         /*@parm [in]  Audio-in device ID (ranges from 0 to a number of available
                                                    devices on the system). You can also use the following flag
                                                    instead of a device identifier.
                                                    <nl><nl><bold WAVE_MAPPER> = The function selects a
                                                    waveform-audio input device capable of recording in the
                                                    specified format. <bold Header:> Declared in Mmsystem.h from
                                                    the Windows Multimedia: Platform SDK.*/
  unsigned long u32Frequency,         /*@parm [in]  Frequency of the recognition engine in Hz. */
  unsigned long u32NbrOfFrames,       /*@parm [in]  (not used) Number of frames buffered internally */
  unsigned long u32SamplesPerFrame,   /*@parm [in]  Size, in samples, of each individual frame. */
  AUDIOIN_H * phAudioIn               /*@parm [out] Handle to the audio-in device */
 );
#endif

LHS_AUDIOIN_ERROR  lhs_audioinOpen(
  unsigned long u32AudioInID, /* [in] audio-in device ID (ranges from 0 to a number of available devices on the
                                      system). You can also use the following flag instead of a device identifier.
                                      <nl><nl><bold WAVE_MAPPER> = The function selects a waveform-audio input
                                      device capable of recording in the specified format. <bold Header:>
                                      Declared in Mmsystem.h from the Windows Multimedia: Platform SDK.*/
  unsigned long u32Frequency, /* [in] Frequency of the recognition engine in Hz. */
  AUDIOIN_H * phAudioIn       /* [out] Handle to the audio-in device */
);

#ifdef AUDIOIN_SUPPORT_CALLBACK
LHS_AUDIOIN_ERROR  lhs_audioinOpenCallback(
  unsigned long u32AudioInID,      /* [in] audio-in device ID (ranges from 0 to a number of available devices on the
                                      system). You can also use the following flag instead of a device identifier.
                                      <nl><nl><bold WAVE_MAPPER> = The function selects a waveform-audio input
                                      device capable of recording in the specified format. <bold Header:>
                                      Declared in Mmsystem.h from the Windows Multimedia: Platform SDK.*/
  unsigned long u32Frequency,      /* [in] Frequency of the recognition engine in Hz. */
  unsigned long u32NbrOfSamples,   /*[in] <nl><bold Input:> Number of samples requested per callback */

  pCallbackFunc pCallback,         /* [in] callback function */
  void         *pCallbackInstance, /* [in] callback instance */
  AUDIOIN_H * phAudioIn            /* [out] Handle to the audio-in device */
);
#endif

LHS_AUDIOIN_ERROR lhs_audioinClose(
  AUDIOIN_H * phAudioIn /*[in] Pointer to the handle of the audio-in device to be closed.*/
);

LHS_AUDIOIN_ERROR lhs_audioinStart(
  AUDIOIN_H hAudioIn    /*[in] Handle of the audio-in device */
);

LHS_AUDIOIN_ERROR lhs_audioinStop(
  AUDIOIN_H hAudioIn    /*[in] Handle of the audio-in device*/
);

LHS_AUDIOIN_ERROR lhs_audioinGetSamples (
  AUDIOIN_H hAudioIn,              /*[in] Handle of the audio-in device */
  unsigned long * u32NbrOfSamples, /*[in/out] <nl><bold Input:> The requested number of samples to be filled in
                                              the pAudioBuffer. Note that the memory used for pBuffer should be large enough
                                              to contain the requested number of samples, also note how the u32NbrOfSamples
                                              is different than the Buffer size, since each frame has an specific size depending
                                              on the audio format.
                                              <nl><bold Output:> The actual number of recorded audio samples written in pBuffer.
                                              If you pass 0 to this parameter then you may still retrieve the AUDIOIN_STATUSINFO
                                              on the audio component. */
  void * pAudioBuffer,              /*[out] Buffer that contains the recorded samples. The memory used for this
                                            buffer is allocated by the client. So, it is the responsibility of the client to
                                            make sure that this memory can contain the requested number of samples. The memory
                                            for this buffer needs also to be freed by the client. */
  AUDIOIN_INFO * pAudioInInfo       /*[out] Information about the audio internal buffer described in
                                            AUDIOIN_INFO.*/
);


LHS_AUDIOIN_ERROR lhs_audioinGetVersion(
  unsigned long * pu32Version       /*[out] The version number of the API implementation. */
);


LHS_AUDIOIN_ERROR lhs_audioinGetVolume(
  AUDIOIN_H hAudioIn,             /*[in] Handle of the audio-in device.*/
  unsigned long * pu32Volume      /*[out] Pointer to a variable that will be filled with the current volume
                                          (normally range of  0 - 65535). Depending on the platform the volume
                                          value may be set to in sizes of 16, 32 or other size, the range also
                                          depends on the platform (Implementations of this interface may
                                          change because of the compatibility of the internal function).*/
);

LHS_AUDIOIN_ERROR lhs_audioinSetVolume(
  AUDIOIN_H hAudioIn,         /*[in] Handle of the audio-in device.*/
  unsigned long u32Volume     /*[in] The volume to be set (normal range 0-65535). Depending on the
                                     platform the volume value may be set to in sizes of 16, 32 or other size,
                                     the range also depends on the platform. (Implementations of this interface
                                     may change because of the compatibility of the internal function)*/
);


const TCHAR * lhs_audioinErrorGetString(
  const LHS_AUDIOIN_ERROR Error    /*[in] The Error code.*/
);


/* -------------------------------------------------------------------------+
 |   END                                                                    |
 + -------------------------------------------------------------------------*/

#if defined( __cplusplus )
}
#endif


#endif /* #ifndef __AUDIOIN_H__ */