ISpRecoContext::SetAudioOptions
Other versions of this page are also available for the following:
.gif "A hyphen indicates that the information in this topic is not relevant for this platform, or that the platform does not support the API that is listed.")
.gif "A checkmark indicates that the information in this topic is relevant for this platform, and that any API listed is also supported on this platform.")
8/28/2008
This method 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.
By default, SAPI does not retain recognition audio. When an audio format is not specified, the audio will be retained in the same format as the SR engine used to perform the recognition.
This method returns successfully, but does not retain the audio, if the application specifies a WAVEFORMATEX-based retained audio format but the SR engine and the audio input stream agree on a non-WAVEFORMATEX-based audio input format (for example, custom audio object/format).
Syntax
HRESULT SetAudioOptions(
SPAUDIOOPTIONS Options,
const GUID* pAudioFormatId,
const WAVEFORMATEX* pWaveFormatEx
);
Parameters
- Options
[in] The audio option to set. Possible values are defined for the SPAUDIOOPTIONS enumeration.
- pAudioFormatId
[in] Pointer to the audio stream format identifier (type GUID). Usually this value is SPDFID_WaveFormatEx. If this value is NULL, the retained audio format will not be changed. The application can reset the retained audio format to the SR engine recognition format by setting this value to GUID_NULL and pWaveFormatEx to NULL.
- pWaveFormatEx
[in] Pointer to a WAVEFORMATEX structure defining the audio stream wave format. This value is only valid if pAudioFormatId is set to SPFID_WaveFormatEx.
Return Value
The following table shows the possible return values.
| Value | Description |
|---|---|
S_OK |
Function completed successfully. |
E_INVALIDARG |
Options is not one of the correct types, or the specified audio format is not valid. |
FAILED(hr) |
Appropriate error message. |
Remarks
A related enumeration is SPSTREAMFORMAT, which defines SAPI-supported stream formats. A related class is CspStreamFormat, which manages SAPI-supported stream formats and WAVEFORMATEX structures.
Example
The following code snippet illustrates the use of this method.
HRESULT hr = S_OK;
// start retained audio settings with default format (such as SR engine
recognition format)
hr = cpRecoContext->SetAudioOptions(SPAO_RETAIN_AUDIO, 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 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
Requirements
| Header | sapi.h, sapi.idl |
| Library | sapilib.lib |
| Windows Embedded CE | Windows CE .NET 4.1 and later |