Home | History | Annotate | Download | only in include
      1 /*---------------------------------------------------------------------------*
      2  *  frontapi.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 
     21 
     22 #ifndef _h_frontapi_
     23 #define _h_frontapi_
     24 
     25 #include "creccons.h"   /* CREC Public Constants    */
     26 
     27 #include "front.h"
     28 #include "sample.h"
     29 #include "utteranc.h"
     30 #include "caexcept.h"
     31 
     32 #ifdef __cplusplus
     33 extern "C"
     34 {
     35 #endif
     36 
     37   /**
     38    ************************************************************************
     39    * SwigImageBegin       <- DO NOT MOVE THIS LINE !
     40    *
     41    * This is a CADOC Keyword section.
     42    *
     43    * If CADOC is instructed to create a SWIG I-File and this is one of the
     44    * files in the input list, everything between the 'SwigImage Begin' and
     45    * 'SwigImage End' keywords comment blocks will be copied 'as-is' to the
     46    * SWIG I-File specified on the CADOC command line.
     47    *
     48    ************************************************************************
     49    */
     50 #include "mutualob.h"
     51 
     52 #ifndef SWIGBUILD
     53 
     54   typedef struct
     55   {
     56     int                 ca_rtti;
     57     booldata            is_configured;
     58     booldata            is_configuredForAgc;
     59     booldata            is_configuredForVoicing;
     60     booldata            is_attached;
     61     wave_info           data;
     62     voicing_info        voice;
     63   }
     64   CA_Wave;
     65 
     66   typedef struct
     67   {
     68     int                 ca_rtti;
     69     booldata            is_configured;
     70     booldata            is_filter_loaded;
     71     int                 status;
     72     int                 samplerate;
     73     float               src_scale;
     74     float               sink_scale;
     75     int                 offset;
     76     front_config        *config;
     77   }
     78   CA_Frontend;
     79 
     80 #endif
     81 
     82   /**
     83    ************************************************************************
     84    * SwigImageEnd         <- DO NOT MOVE THIS LINE !
     85    ************************************************************************
     86    */
     87 
     88   /*
     89   **  Frontend
     90   */
     91 
     92   CA_Frontend* CA_AllocateFrontend(float srcscale,
     93                                    int offset,
     94                                    float sinkscale);
     95   /**
     96    *
     97    * Params       srcscale    Gain applied to incoming wave data
     98    *              offset      DC offset applied to incoming wave data
     99    *              sinkscale   Gain applied to any wave data sinks
    100    *
    101    * Returns      Handle to new Front End object
    102    *
    103    * See          CA_FreeFrontend
    104    *
    105    ************************************************************************
    106    * Allocates a front-end object
    107    ************************************************************************
    108    */
    109 
    110 
    111   void CA_FreeFrontend(CA_Frontend* hFrontend);
    112   /**
    113    *
    114    * Params       hFrontend   Handle to valid front-end object
    115    *
    116    * Returns      void
    117    *
    118    * See          CA_AllocateFrontend
    119    *
    120    ************************************************************************
    121    * Deletes a front-end object
    122    ************************************************************************
    123    */
    124 
    125 
    126   void CA_ConfigureFrontend(CA_Frontend *hFrontend,
    127                             CA_FrontendInputParams *hFrontArgs);
    128   /**
    129    *
    130    * Params       hFrontend   Handle to valid front-end object
    131    *              hFrontpars  Handle to valid front-end input parameters object
    132    *
    133    * Returns      void
    134    *
    135    * See          CA_UnconfigureFrontend
    136    *
    137    ************************************************************************
    138    * Set up the front end using the paramteters. This function
    139    * configures the member Wave, Freq and Cep objects, by calling their
    140    * create and setup functions.
    141    ************************************************************************
    142    */
    143 
    144 
    145   void CA_SetWarpScale(CA_Frontend *hFrontend, float wscale);
    146   /**
    147    *
    148    * Params       hFrontend   Handle to valid front-end object
    149    *              wscale      warp scale
    150    *
    151    * Returns      void
    152    *
    153    * See          CA_SetFrontendParameter
    154    *
    155    ************************************************************************
    156    ************************************************************************
    157    */
    158 
    159   void CA_UnconfigureFrontend(CA_Frontend *hFrontend);
    160   /**
    161    *
    162    * Params       hFrontend   Handle to valid front-end object
    163    *
    164    * Returns      void
    165    *
    166    * See          CA_ConfigureFrontend
    167    *
    168    ************************************************************************
    169    * Undo all of the front end configurations
    170    ************************************************************************
    171    */
    172 
    173 
    174   int  CA_MakeFrame(CA_Frontend* hFrontend,
    175                     CA_Utterance* hUtt,
    176                     CA_Wave* hWave);
    177   /**
    178    *
    179    * Params       hFrontend   Handle to valid front-end object
    180    *              hUtt        Handle to valid utterance object
    181    *              hWave       Handle to valid wave object
    182    *
    183    * Returns      non-zero if a frame was constructed
    184    *
    185    ************************************************************************
    186    * Constructs a single frame from audio in the wave object.  The output
    187    * frame is inserted into the utterance.
    188    *
    189    * Frames may not be built. An initial start-up condition prevents
    190    * the first few frames of audio from being used for frames, in this case
    191    * this method returns zero to the caller.
    192    ************************************************************************
    193    */
    194 
    195 
    196   int  CA_GetFrontendFramesPerValidFrame(CA_Frontend *hFrontend);
    197   int  CA_GetFrontendSampleRate(CA_Frontend *hFrontend);
    198   /**
    199    *
    200    * Params       hFrontend   Handle to valid front-end object
    201    *
    202    * Returns       Current sample rate (Hz)
    203    *
    204    * See          CA_ConfigureFrontend
    205    *
    206    ************************************************************************
    207    * Gets the sample rate from the front end object
    208    ************************************************************************
    209    */
    210 
    211 
    212   int  CA_GetFrontendUtteranceDimension(CA_Frontend *hFrontend);
    213   /**
    214    *
    215    * Params       hFrontend   Handle to valid front-end object
    216    *
    217    * Returns      The dimension of utterance that the front end will build
    218    *
    219    * See          CA_InitUtteranceForFile
    220    *              CA_InitUtteranceForFrontend
    221    *              CA_LoadUtteranceFrame
    222    *
    223    ************************************************************************
    224    * Returns the number of items in an utterance.
    225    ************************************************************************
    226    */
    227 
    228 
    229   int  CA_GetRecognitionHoldoff(CA_FrontendInputParams *hFrontPar);
    230   /**
    231    *
    232    * Params       hFrontpar  Handle to valid front-end input parameters object
    233    *
    234    * Returns      The minimum recognition holdoff period, i.e. the minimum
    235    *              gap between the frontend and recognizer.
    236    *
    237    ************************************************************************
    238    * Computes the Recognition Holdoff Parameter value.  Setting the par in
    239    * a par file is unnecessary if this function is used.
    240    ************************************************************************
    241    */
    242 
    243 
    244   /*
    245   **  Channel normalization
    246   */
    247 ESR_ReturnCode CA_GetCMSParameters ( CA_Wave *hWave, LCHAR *param_string, size_t* len );
    248 ESR_ReturnCode CA_SetCMSParameters ( CA_Wave *hWave, const LCHAR *param_string );
    249 
    250 
    251   void CA_ReLoadCMSParameters(CA_Wave *hWave,
    252                               const char *basename);
    253 
    254   void CA_LoadCMSParameters(CA_Wave *hWave,
    255                             const char *basename,
    256                             CA_FrontendInputParams
    257                             *hFrontArgs);
    258   /**
    259    *
    260    * Params       hWave       Handle to valid wave object
    261    *              basename    Forename of .cmn and .tmn files that store the parameters
    262    *              hFrontPar       Handle to a valid CRhFrontendInputParams
    263    *
    264    * Returns      Nothing
    265    *
    266    * See          CA_ConfigureCMSparameters
    267    *              CA_SaveCMSParameters
    268    *              CA_AttachCMStoUtterance
    269    *
    270    ************************************************************************
    271    * Loads CMS parameters from file.  Sets up the CMS calculations
    272    * The .cmn and .tmn files must obviously have the same basename.
    273    ************************************************************************
    274    */
    275 
    276 
    277   void CA_SaveCMSParameters(CA_Wave *hWave,
    278                             const char *basename);
    279   /**
    280    *
    281    * Params       hWave       Handle to valid wave object
    282    *              basename    Forename of .cmn and .tmn files that are
    283    *                          to store the parameters
    284    *
    285    * Returns      Nothing
    286    *
    287    * See          CA_LoadCMSParameters
    288    *              CA_ClearCMSParameters
    289    *
    290    ************************************************************************
    291    * This method writes out .CMN and .TMN files.
    292    *
    293    * The .CMN file may differ from the one used during a call to
    294    * CA_LoadCMSParameters() due to channel adaptation.
    295    *
    296    * The .cmn and .tmn files will obviously have the same basename.
    297    ************************************************************************
    298    */
    299 
    300 
    301   void CA_ClearCMSParameters(CA_Wave *hWave);
    302   /**
    303    *
    304    * Params       hWave       Handle to valid wave object
    305    *
    306    * Returns      Nothing
    307    *
    308    * See          CA_LoadCMSParameters
    309    *              CA_SaveCMSParameters
    310    *              CA_DetachCMSfromUtterance
    311    *
    312    ************************************************************************
    313    * This method clears any CMS information.  Must call
    314    * CA_DetachCMSfromUtterance on the Wave first, if CA_AttachCMStoUtterance
    315    * has been called.
    316    ************************************************************************
    317    */
    318 
    319   void CA_AttachCMStoUtterance(CA_Wave *hWave,
    320                                CA_Utterance *hUtt);
    321   /**
    322    *
    323    * Params       hWave   Handle to valid Wave structure
    324    *              hUtt    Handle to an utterance object to clear
    325    *
    326    * Returns      Nothing.
    327    *
    328    * See          CA_LoadCMSParameters
    329    *              CA_DetachCMStoUtterance
    330    *
    331    ************************************************************************
    332    *  The CMS data items are inherited from the CA_Wave object to the
    333    *  CA_Utterance.  All calculations carried out with this utterance
    334    *  object will now result in new statistics being inherited by the
    335    *  CA_Wave object.
    336    ************************************************************************
    337    */
    338 
    339   /**
    340    * Returns true if CMS is attached to utterance.
    341    *
    342    * @param hWave wave handle
    343    * @param isAttached [out] True if attached
    344    */
    345   ESR_ReturnCode CA_IsCMSAttachedtoUtterance(CA_Wave* hWave, ESR_BOOL* isAttached);
    346 
    347   /**
    348    * Returns true if CA_Wave is configured for Agc.
    349    *
    350    * @param hWave wave handle
    351    * @param isAttached [out] True if attached
    352    */
    353   ESR_ReturnCode CA_IsConfiguredForAgc(CA_Wave* hWave, ESR_BOOL* isConfigured);
    354 
    355   void CA_DetachCMSfromUtterance(CA_Wave *hWave,
    356                                  CA_Utterance *hUtt);
    357   /**
    358    *
    359    * Params       hWave   Handle to valid Wave structure
    360    *              hUtt    Handle to an utterance object to clear
    361    *
    362    * Returns      Nothing.
    363    *
    364    * See          CA_LoadCMSParameters
    365    *              CA_AttachCMStoUtterance
    366    *              CA_ClearCMSParameters
    367    *
    368    ************************************************************************
    369    *  The CMS data items are now dis-inherited by the CA_Utterance object.
    370    *  Calculations carried out with this utterance
    371    *  object will no longer result in new statistics being inherited by the
    372    *  CA_Wave object.
    373    ************************************************************************
    374    */
    375 
    376 
    377   void CA_CalculateCMSParameters(CA_Wave *hWave);
    378   /**
    379    *
    380    * Params       hWave       Handle to valid wave object
    381    *
    382    * Returns
    383    *
    384    * See          CA_LoadCMSParameters
    385    *              CA_AttachCMStoUtterance
    386    *              CA_DiscardCMSAccumulates
    387    *
    388    ************************************************************************
    389    * This routine updates the values used for cepstrum mean subtraction
    390    * using a running estimation algorithm.
    391    * A call must first have been made to CA_LoadCMSparameters and
    392    * subsequently to a CA_AttachCMStoUtterance.
    393    ************************************************************************
    394    */
    395 
    396 
    397   void CA_DiscardCMSAccumulates(CA_Wave *hWave);
    398   /**
    399    *
    400    * Params       hWave       Handle to valid wave object
    401    *
    402    * Returns
    403    *
    404    * See          CA_LoadCMSParameters
    405    *              CA_AttachCMStoUtterance
    406    *              CA_CalculateCMSParameters
    407    *
    408    ************************************************************************
    409    * This routine clears the updates used for the running estimation of
    410    * cepstrum mean subtraction.
    411    * CMS parameters must have been loaded and attached to the wave.
    412    ************************************************************************
    413    */
    414 
    415 
    416 
    417   /*
    418   **  Wave
    419   */
    420   /**
    421    ************************************************************************
    422    * CA_Wave methods
    423    *
    424    * The wave-input object that represents a file or a device.
    425    * It maintains sample buffers and data associated with that input stream
    426    * such as agc, talk-over etc.
    427    *
    428    * However the process of getting samples into the CA_Wave object from
    429    * a physical device is external to CREC-API.
    430    ************************************************************************
    431    */
    432 
    433   CA_Wave* CA_AllocateWave(char typ);
    434   /**
    435    *
    436    * Params       typ     A waveform type charcater
    437    *
    438    * Returns      Handle to a new Wave structure
    439    *
    440    * See          CA_FreeWave
    441    *              CA_ConfigureWave
    442    *
    443    ************************************************************************
    444    * Creates a Wave structure.
    445    *
    446    * There are several options for the 'typ' character, each is listed below:
    447    *  'M' mu-Law
    448    *  'P' PCM  (i.e. 8k or 11kHz PCM Files)
    449    *  'R' RIFF
    450    *  'N' NIST
    451    *
    452    * Once allocated, the returned object should be configured with a call
    453    * to CA_ConfigureWave().
    454    ************************************************************************
    455    */
    456 
    457 
    458   void CA_ConfigureWave(CA_Wave *hWave,
    459                         CA_Frontend *hFrontend);
    460   /**
    461    *
    462    * Params       hWave   Handle to a previously created Wave structure
    463    *              hFrontend   Handle to valid front-end object
    464    *
    465    * Returns      void
    466    *
    467    * See          CA_UnconfigureWave
    468    *
    469    ************************************************************************
    470    * Initializes a Wave structure.
    471    *
    472    * This should be called before any other Wave methods.
    473    ************************************************************************
    474    */
    475 
    476 
    477   void CA_ConfigureVoicingAnalysis(CA_Wave *hWave,
    478                                    CA_FrontendInputParams *hFrontPar);
    479   /**
    480    *
    481    * Params       hWave           Handle to a previously created Wave structure
    482    *              hFrontPar       Handle to a valid CRhFrontendInputParams
    483    *
    484    * Returns      void
    485    *
    486    ************************************************************************
    487    * Initializes a Wave's voicin analysis module.
    488    ************************************************************************
    489    */
    490 
    491 
    492   void CA_ResetWave(CA_Wave *hWave);
    493   /**
    494    *
    495    * Params       hWave   Handle to a previously created Wave structure
    496    *
    497    * Returns      Nothing
    498    *
    499    ************************************************************************
    500    * This prepares the wave object for re-use.  The voicing information
    501    * is cleared. It is *essential* to call this function if the Wave object
    502    * is used for streaming live data, or multiple-utterance wave files.
    503    *
    504    ************************************************************************
    505    */
    506 
    507 
    508   void CA_UnconfigureWave(CA_Wave *hWave);
    509   /**
    510    *
    511    * Params       hWave   Handle to a previously created Wave structure
    512    *
    513    * Returns      void
    514    *
    515    * See          CA_ConfigureWave
    516    *
    517    ************************************************************************
    518    * Uninitializes a Wave structure.
    519    ************************************************************************
    520    */
    521 
    522 
    523   void CA_FreeWave(CA_Wave *hWave);
    524   /**
    525    *
    526    * Params       hWave   Handle to a previously created Wave structure
    527    *
    528    * Returns      Nothing, the Wave object is no longer valid
    529    *
    530    * See          CA_AllocateWave
    531    *
    532    ************************************************************************
    533    * Removes a previously allocated Wave structure
    534    ************************************************************************
    535    */
    536 
    537 
    538   int  CA_OpenWaveFromFile(CA_Wave *hWave,
    539                            char* filename,
    540                            char typ,
    541                            int endian,
    542                            int do_write,
    543                            int samplerate);
    544   /**
    545    *
    546    * Params       hWave       Handle to valid Wave structure
    547    *              filename    ASCII, null-terminated filename string
    548    *              typ         File attribute character
    549    *              endian      Binary storage, use 'LITTLE' or 'BIG'
    550    *              do_write    Adds a RIFF header if non-ZERO
    551    *              samplerate  File's sample rate (Hz)
    552    *
    553    * Returns      non-ZERO if successful
    554    *
    555    * See          CA_CloseFile
    556    *
    557    ************************************************************************
    558    * Initializes the Wave structure for use with a known filename.
    559    *
    560    * There are several options for the 'typ' character, each is listed below:
    561    *  'M' mu-Law Files
    562    *  'P' PCM Files (i.e. 8k or 11kHz PCM Files)
    563    *  'R' RIFF
    564    *  'N' NIST
    565    *
    566    * It is an error to call this function without first configuring hWave
    567    ************************************************************************
    568    */
    569 
    570 
    571   void CA_CloseFile(CA_Wave *hWave);
    572   /**
    573    *
    574    * Params       hWave   Handle to valid Wave structure
    575    *
    576    * Returns      Nothing, the opened file is closed
    577    *
    578    * See          CA_OpenWaveFromFile
    579    *
    580    ************************************************************************
    581    * It is an error to call this function without first configuring hWave
    582    ************************************************************************
    583    */
    584 
    585 
    586   int  CA_OpenWaveFromDevice(CA_Wave *hWave,
    587                              int wave_type,
    588                              int samplerate,
    589                              int device_id,
    590                              int device_type);
    591   /**
    592    *
    593    * Params       hWave       Handle to valid Wave structure
    594    *              wave_type   Audio format
    595    *              samplerate  Device sample rate (Hz)
    596    *              device_id   The Physical device number of the
    597    *                          waveform hardware (normally starting at 0)
    598    *              device_type The type of device
    599    *
    600    * Returns      non-ZERO if successful
    601    *
    602    * See          CA_CloseDevice
    603    *
    604    ************************************************************************
    605    * Initializes the Wave structure for use with a known filename.
    606    *
    607    * 'wave_type' should be either DEVICE_MULAW or DEVICE_RAW_PCM.  This
    608    * enables correct internal interpretation of the audio samples.  If the
    609    * device is an output device 'wave_type' should be 0 (ZERO).
    610    *
    611    * It is an error to call this function without first configuring hWave
    612    *
    613    * 'device_type' should be one of WAVE_DEVICE_MSWAVE (for real devices)
    614    * or WAVE_DEVICE_RAW (if using the raw interface - CA_LoadSamples)
    615    ************************************************************************
    616    */
    617 
    618 
    619   void CA_CloseDevice(CA_Wave *hWave);
    620   /**
    621    *
    622    * Params       hWave   Handle to valid Wave structure
    623    *
    624    * Returns      Nothing, the opened device is closed
    625    *
    626    * See          CA_OpenWaveFromDevice
    627    *
    628    ************************************************************************
    629    * It is an error to call this function without first configuring hWave
    630    ************************************************************************
    631    */
    632 
    633 
    634   void CA_SetWaveBoostValue(CA_Wave *hWave,
    635                             int waveBoost);
    636   /**
    637    *
    638    * Params       hWave       Handle to valid Wave structure
    639    *              waveBoost   The input sample scaling value (in %)
    640    *
    641    * Returns      void
    642    *
    643    ************************************************************************
    644    * The 'offset' and 'gain' parameters are applied to the current
    645    * waveform buffer and the resultant samples clamped to a 16-bit
    646    * audio range.
    647    *
    648    * It is an error to call this function without first configuring hWave
    649    ************************************************************************
    650    */
    651 
    652 
    653   int  CA_GetWaveBoostValue(CA_Wave *hWave);
    654   /**
    655    *
    656    * Params       hWave   Handle to valid Wave structure
    657    *
    658    * Returns      The input sample scaling value (in %)
    659    *
    660    ************************************************************************
    661    * It is an error to call this function without first configuring hWave
    662    ************************************************************************
    663    */
    664 
    665 
    666   int  CA_GetSampleRate(CA_Wave *hWave);
    667   /**
    668    *
    669    * Params       hWave       Handle to valid Wave structure
    670    *
    671    * Returns      Sample rate used by the wave device
    672    *
    673    * See          CA_LoadSamples
    674    *              CA_ConfigureWave
    675    *
    676    ************************************************************************
    677    * It is an error to call this function without first configuring hWave
    678    ************************************************************************
    679    */
    680 
    681 
    682   void CA_CopyWaveSegment(CA_Wave *source,
    683                           CA_Wave *sink,
    684                           unsigned long offset,
    685                           unsigned long length);
    686   /**
    687    *
    688    * Params       source  Handle to valid Wave structure for source
    689    *              sink    Handle to valid Wave structure for destination
    690    *              offset  Sample number starting the segment (first sample == 0)
    691    *              length  Number of samples in the segment
    692    *
    693    * Returns      Nothing, the wave segment in 'source' is copied to 'sink'
    694    *
    695    ************************************************************************
    696    * This is useful when copying selected sections of a waveform.  It is
    697    * employed within the SDXCollect_SinkWaveSegment() method.
    698    *
    699    * 'source' and 'sinks' must be different objects.
    700    *
    701    * It is an error to call this function without first configuring
    702    * the 'source' and 'sink' wave objects.
    703    ************************************************************************
    704    */
    705 
    706 
    707   int  CA_GetBufferSize(CA_Wave *hWave);
    708   /**
    709    *
    710    * Params       hWave       Handle to valid Wave structure
    711    *
    712    * Returns      Buffer size (in bytes) used by the wave device for
    713    *              the construction of a single frame.
    714    *
    715    * See          CA_LoadSamples
    716    *              CA_ConfigureWave
    717    *
    718    ************************************************************************
    719    * This function is supplied for use in conjunction with CA_LoadSamples.
    720    * The application should call CA_CetBufferSIze on the current input Wave
    721    * object and use the result to create the wave sample buffer that it will
    722    * supply to CA_LoadSamples.
    723    *
    724    * It is an error to call this function without first configuring hWave
    725    ************************************************************************
    726    */
    727 
    728 
    729 #ifndef SWIGBUILD
    730   int  CA_LoadSamples(CA_Wave *hWave,
    731                       samdata *pPCMData,
    732                       int sampleCount);
    733 #else
    734   int  CA_LoadSamples(CA_Wave *hWave,
    735                       short *pPCMData,
    736                       int sampleCount);
    737 #endif
    738   /**
    739    *
    740    * Params       hWave       Handle to valid Wave structure
    741    *              pPCMData    Pointer to a buffer created by the application.
    742    *              sampleCount The number of samples in the supplied buffer.
    743    *
    744    * Returns      Buffer size (in bytes) used by the wave device for
    745    *              the construction of a single frame.
    746    *
    747    * See          CA_GetBufferSize
    748    *              CA_ConfigureWave
    749    *
    750    ************************************************************************
    751    * The buffer contains exactly enough wave data to make one frame of an
    752    * utterance. The required buffer size can be got by calling CA_GetBufferSize.
    753    * The application is responsible for ensuring that the supplied sample
    754    * data is in the correct format. The sample rate should match that of the
    755    * recognizer, and the sample size should be of size 16 bits. CA_LoadSamples
    756    * will check the sample count, and report an error if it does not match
    757    * the front end's required buffer size.
    758    *
    759    * It is an error to call this function without first configuring hWave
    760    ************************************************************************
    761    */
    762 
    763 
    764   int  CA_ReadSamplesForFrame(CA_Wave *hWave);
    765   /**
    766    *
    767    * Params       hWave   Handle to valid Wave structure
    768    *
    769    * Returns      The number of samples read; <0 on failure.
    770    *
    771    * See          CA_SaveSamplesForFrame
    772    *
    773    ************************************************************************
    774    * It is an error to call this function without first configuring hWave
    775    ************************************************************************
    776    */
    777 
    778 
    779   int  CA_SaveSamplesForFrame(CA_Wave *hWave);
    780   /**
    781    *
    782    * Params       hWave   Handle to valid Wave structure
    783    *
    784    * Returns      The number of samples read; <0 on failure.
    785    *
    786    * See          CA_ReadSamplesForFrame
    787    *
    788    ************************************************************************
    789    * It is an error to call this function without first configuring hWave
    790    ************************************************************************
    791    */
    792 
    793 
    794   void CA_ConditionSamples(CA_Wave *hWave);
    795   /**
    796    *
    797    * Params       hWave   Handle to valid Wave structure
    798    *
    799    * Returns      Nothing. The incoming audio buffer is 'conditioned'.
    800    *
    801    ************************************************************************
    802    * The 'offset' and 'gain' parameters are applied to the current
    803    * waveform buffer and the resultant samples clamped to a 16-bit
    804    * audio range.
    805    *
    806    * It is an error to call this function without first configuring hWave
    807    ************************************************************************
    808    */
    809 
    810 
    811   void CA_CopyWaveSamples(CA_Wave *hWaveIn,
    812                           CA_Wave *hWaveOut);
    813   /**
    814    *
    815    * Params       hWaveIn     Handle to valid Wave object
    816    *              hWaveOut    Handle to valid Wave object
    817    *
    818    * Returns      The audio samples in the In channel are
    819    *              copied to the Out channel
    820    *
    821    ************************************************************************
    822    * This method is provided to permit incoming audio sample to be copied
    823    * to the sink for file storage.  The wave objects should have been
    824    * created as appropriate sources or sinks.
    825    *
    826    * 'hWaveIn' and 'hWaveOut' must be different objects.
    827    *
    828    * It is an error to call this function without first configuring
    829    * the 'hWaveIn' and 'hWaveOut' wave objects.
    830    ************************************************************************
    831    */
    832 
    833 
    834   int  CA_WaveIsOutput(CA_Wave *hWave);
    835   /**
    836    *
    837    * Params       hWave   Handle to valid Wave structure
    838    *
    839    * Returns      Boolean.
    840    *
    841    ************************************************************************
    842    * Returns true if the Wave is setup as a sink of data
    843    *
    844    * It is an error to call this function without first configuring hWave
    845    * and setting it up as a device or a file
    846    ************************************************************************
    847    */
    848 
    849 
    850   int  CA_WaveIsInput(CA_Wave *hWave);
    851   /**
    852    *
    853    * Params       hWave   Handle to valid Wave structure
    854    *
    855    * Returns      Boolean.
    856    *
    857    ************************************************************************
    858    * Returns true if the Wave is setup as a source of data
    859    *
    860    * It is an error to call this function without first configuring hWave
    861    * and setting it up as a device or a file
    862    ************************************************************************
    863    */
    864 
    865 
    866   int  CA_WaveIsADevice(CA_Wave *hWave);
    867   /**
    868    *
    869    * Params       hWave   Handle to valid Wave structure
    870    *
    871    * Returns      Boolean.
    872    *
    873    ************************************************************************
    874    * Returns true if the Wave is setup as a device
    875    *
    876    * It is an error to call this function without first configuring hWave
    877    * and setting it up as a device or a file
    878    ************************************************************************
    879    */
    880 
    881 
    882   int  CA_WaveIsAFile(CA_Wave *hWave);
    883   /**
    884    *
    885    * Params       hWave   Handle to valid Wave structure
    886    *
    887    * Returns      Boolean.
    888    *
    889    ************************************************************************
    890    * Returns true if the Wave is setup as a file of data
    891    *
    892    * It is an error to call this function without first configuring hWave
    893    * and setting it up as a device or a file
    894    ************************************************************************
    895    */
    896 
    897   void CA_StartSigCheck(CA_Wave *hWave);
    898   void CA_StopSigCheck(CA_Wave *hWave);
    899   void CA_ResetSigCheck(CA_Wave *hWave);
    900   void CA_GetSigStats(CA_Wave *hWave, int *nsam, int *pclowclip, int *pchighclip,
    901                       int *dc_offset, int *amp, int *pc5, int *pc95,
    902                       int *overflow);
    903   ESR_BOOL CA_DoSignalCheck(CA_Wave *hWave, ESR_BOOL *clipping, ESR_BOOL *dcoffset,
    904                         ESR_BOOL *highnoise, ESR_BOOL *quietspeech, ESR_BOOL *too_few_samples,
    905                         ESR_BOOL *too_many_samples);
    906 
    907 
    908 
    909   /*  Frontend parameter API
    910   */
    911   /**
    912    ************************************************************************
    913    * CA_FrontendInputParams methods
    914    *
    915    * To load the front-end parameters from a par file
    916    *
    917    * This object holds input parameters (objtained from an ASCII
    918    * parameter file) for the Front-End object.
    919    *
    920    * Apart from allocating and freeing the object it also has a method
    921    * used to read a given parameter file.
    922    ************************************************************************
    923    */
    924 
    925 
    926 
    927   CA_FrontendInputParams* CA_AllocateFrontendParameters(void);
    928   /**
    929    *
    930    * Params       void
    931    *
    932    * Returns      Handle to new front-end input object
    933    *
    934    * See          CA_FreeFrontendParameters
    935    *              CA_ConfigureFrontend
    936    *
    937    ************************************************************************
    938    * Creates a new front-end input paramater onject
    939    ************************************************************************
    940    */
    941 
    942 
    943   void CA_LoadFrontendParameters(CA_FrontendInputParams* hFrontpar,
    944                                  const char* parfile);
    945   /**
    946    *
    947    * Params       hFrontpar   valid front-end input object handle
    948    *              parfile     par file
    949    *
    950    * Returns      void
    951    *
    952    * See          CA_SaveFrontendParameters
    953    *              CA_ConfigureFrontend
    954    *
    955    ************************************************************************
    956    * Loads known front-end parameters from the given .PAR file.
    957    * The file is a .par file
    958    ************************************************************************
    959    */
    960 
    961 
    962   void CA_FreeFrontendParameters(CA_FrontendInputParams* hFrontpar);
    963   /**
    964    *
    965    * Params       hFrontpar   valid front-end input object handle
    966    *
    967    * Returns      void        front-end object is no longer valid
    968    *
    969    * See          CA_AllocateFrontendParameters
    970    *
    971    ************************************************************************
    972    * Removes a previously allocated parameter object
    973    ************************************************************************
    974    */
    975 
    976 
    977   void CA_SaveFrontendParameters(CA_FrontendInputParams* hFrontpar,
    978                                  const char* parfile);
    979   /**
    980    *
    981    * Params       hFrontpar   valid front-end input object handle
    982    *              parfile     parameter (.par) file to read
    983    *
    984    * Returns      void
    985    *
    986    * See          CA_LoadFrontendParameters
    987    *              CA_ConfigureFrontend
    988    *
    989    ************************************************************************
    990    * Saves a previously loaded (modified) parameter file
    991    *
    992    * It is an error to call this function without first loading
    993    * front-end input parameters.
    994    ************************************************************************
    995    */
    996 
    997 
    998   int  CA_SetFrontendParameter(CA_FrontendInputParams *hFrontpar,
    999                                char *key,
   1000                                char *value);
   1001   /**
   1002    *
   1003    * Params       hFrontpar   valid Front End Parameter handle
   1004    *              key         parameter key (text label)
   1005    *              value       new parameter value (text)
   1006    *
   1007    * Returns      Zero on error
   1008    *
   1009    * See          CA_GetFrontendStringParameter
   1010    *              CA_GetFrontendIntParameter
   1011    *              CA_GetFrontendFloatParameter
   1012    *              CA_LoadFrontendParameters
   1013    *
   1014    ************************************************************************
   1015    * Sets/Modifies a known Front End Input parameter.
   1016    *
   1017    * It is an error to call this function without first loading
   1018    * front-end input parameters.
   1019    ************************************************************************
   1020    */
   1021 
   1022 
   1023   int  CA_GetFrontendParameter(CA_FrontendInputParams *hFrontpar,
   1024                                char *key,
   1025                                void *value);
   1026   /**
   1027    *
   1028    * Params       hFrontpar   valid Front End Parameter handle
   1029    *              key         parameter key (text label)
   1030    *              value       pointer to store parameter value (text)
   1031    *              valueLen    size of value buffer
   1032    *
   1033    * Returns      False on error
   1034    *
   1035    * See          CA_SetFrontendParameter
   1036    *              CA_LoadFrontendParameters
   1037    *
   1038    ************************************************************************
   1039    * Reads a known Front End Parameter.
   1040    *
   1041    * It is an error to call this function without first loading
   1042    * front-end input parameters.
   1043    ************************************************************************
   1044    */
   1045 
   1046   int  CA_GetFrontendStringParameter(CA_FrontendInputParams *hFrontpar,
   1047                                      char *key,
   1048                                      char *value,
   1049                                      int valueLen,
   1050                                      int *bytes_required);
   1051   /**
   1052    *
   1053    * Params       hFrontpar   valid Front End Parameter handle
   1054    *              key         parameter key (text label)
   1055    *              value       pointer to store parameter value
   1056    *  value_len   number of bytes pointed to by value
   1057    *  bytes_required holds the number of bytes neededf to store the data
   1058    *
   1059    * Returns      False on error
   1060    *
   1061    * See          CA_SetFrontendParameter
   1062    *              CA_LoadFrontendParameters
   1063    *
   1064    ************************************************************************
   1065    * Reads a known Front End Parameter.
   1066    *
   1067    * It is an error to call this function without first loading
   1068    * front-end input parameters.
   1069    ************************************************************************
   1070    */
   1071 
   1072   int CA_LoadSpectrumFilter(CA_Frontend *hFrontend, char *basename);
   1073   /**
   1074    *
   1075    * Params       hFrontend   valid Frontend handle
   1076    *              basename    basename of filter file (a text file)
   1077    *              hFrontArs   valid Frontend parameters handle
   1078    *
   1079    * Returns      False on error
   1080    *
   1081    * See          CA_SetFrontendParameter
   1082    *              CA_LoadFrontendParameters
   1083    *
   1084    ************************************************************************
   1085    * Loads a spectrum filter from a file.
   1086    *
   1087    * It is an error to call this function without first loading
   1088    * front-end input parameters.
   1089    ************************************************************************
   1090    */
   1091 
   1092   void CA_ClearSpectrumFilter(CA_Frontend *hFrontend);
   1093   /**
   1094    *
   1095    * Params       hFrontend   valid Frontend handle
   1096    *
   1097    * Returns      void
   1098    *
   1099    * See          CA_LoadSpectrumFilter
   1100    *
   1101    ************************************************************************
   1102    * Clears a front end spectrum filter.
   1103    *
   1104    * It is an error to call this function without first loading
   1105    * front-end input parameters.
   1106    ************************************************************************
   1107    */
   1108 
   1109   int CA_IsSpectrumFilterLoaded(CA_Frontend *hFrontend);
   1110   /**
   1111    *
   1112    * Params       hFrontend   valid Frontend handle
   1113    *
   1114    * Returns      True if front end is loaded with a spectrum filter.
   1115    *
   1116    * See          CA_LoadSpectrumFilter
   1117    *
   1118    ************************************************************************
   1119    *
   1120    ************************************************************************
   1121    */
   1122 
   1123   void CA_EnableNonlinearFilter(CA_Frontend *hFrontend);
   1124   void CA_DisableNonlinearFilter(CA_Frontend *hFrontend);
   1125   void CA_EnableSpectrumFilter(CA_Frontend *hFrontend);
   1126   void CA_DisableSpectrumFilter(CA_Frontend *hFrontend);
   1127 
   1128 #ifdef __cplusplus
   1129 }
   1130 #endif
   1131 
   1132 
   1133 #endif
   1134