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