ISpRecoContext::SetAudioOptions

ISpRecoContext::SetAudioOptions sets the audio options for result objects from this recognition context. This method also enables or disables the retention of audio with result objects and can change the retained audio format.

HRESULT SetAudioOptions(
   SPAUDIOOPTIONS        Options,
   const GUID           *pAudioFormatId,
   const WAVEFORMATEX   *pWaveFormatEx
);

Parameters

Options

[in] Flag of type SPAUDIOOPTIONS indicating the option. It must be one of the following:

Value
SPAO_NONE	Do not retain audio for results.
SPAO_RETAIN_AUDIO	Retain audio for all future results.

pAudioFormatId

[in] The audio stream format id [of type GUID]. Usually this value is SPDFID_WaveFormatEx. If this value is NULL, the retained audio format will not be changed. Reset the retained audio format to the SR engine's recognition format by setting this value to GUID_NULL and pWaveFormatEx to NULL. 

pWaveFormatEx

[in] The audio stream wave format [of type WAVEFORMATEX]. This is only valid if *pAudioFormatId == SPFID_WaveFormatEx.

Return values

Remarks

If a WAVEFORMATEX-based retained audio format is specified, but the SR engine and the audio input stream agree on a non-WAVEFORMATEX-based audio input format (e.g., custom audio object/format), ISpRecoContext::SetAudioOptions will return successfully, but will not retain the audio.

By default, SAPI does not retain recognition audio.

By default, when an audio format is not specified, the audio will be retained in the same format that the SR engine used to perform the recognition.

Example

The following code snippet illustrates the use of ISpRecoContext::SetAudioOptions.

    HRESULT hr = S_OK;

    // activate retained audio settings with default format (i.e. SR engine recognition format)
    hr = cpRecoContext->SetAudioOptions(SPAO_RETAIN_AUDIO, &GUID;_NULL, NULL);
    // Check hr

    // deactivate retained audio settings
    hr = cpRecoContext->SetAudioOptions(SPAO_NONE, NULL, NULL);
    // Check hr

    // change the retained audio format to 11 kHz, 16-bit Stereo

    // use the stream format helper to fill in the WAVEFORMATEX structure
    CSpStreamFormat sfRetained(SPSF_24kHz16BitStereo, &hr);
    // Check hr

    // change the settings to the selected stream format
    hr = cpRecoContext->SetAudioOptions(SPAO_RETAIN_AUDIO, &sfRetained.FormatId(), sfRetained.WaveFormatExPtr());
    // Check hr

Development Helpers