SpVoice AllowAudioOutputFormatChangesOnNextSet property (SAPI 5.3)

Microsoft Speech API 5.3

Object: SpVoice
Type: Hidden

AllowAudioOutputFormatChangesOnNextSet Property

The AllowOutputFormatChangesOnNextSet property gets and sets the flag that specifies whether SAPI will adjust the format of a voice object's new audio output device automatically.

By default, when an application sets a voice object's AudioOutput property to an audio device, SAPI will change the format of that device to match the engine's preferred format. In cases where a specific audio format is required, such as telephony applications, the AllowOutputFormatChangesOnNextSet property can be used to prevent this format change.

When this property is true, SAPI adjusts the format of the audio output object to the engine's preferred format. When it is false, SAPI uses the audio output object's format. If the output is set to a stream object, SAPI will convert the output to the format of the stream.

Syntax

Parts

• SpVoice
  The owning object.
• Boolean
  Set: A Boolean variable that sets the property value.
  Get: A Boolean variable that gets the property value.

Remarks

Using the same audio format for input and output source is useful for sound cards that do not support full-duplex audio (i.e., input format must match output format). If the input format quality is lower than the output format quality, the output format quality will be reduced to equal the input quality.

Example

The following Visual Basic form code demonstrates the use of the AllowAudioOutputFormatChangesOnNextSet property. To run this code, create a form with the following controls:

• Two command buttons called Command1 and Command2.

Paste this code into the Declarations section of the form.

The Form_Load procedure creates a voice object, an audio output object, and a SpeechAudioFormatType variable. Both command button procedures set the format of the audio output object to SAFT22kHz8BitMono, then set the AudioOutputStream of the voice to the audio output object, and then test if the voice's audio format has been changed.

In the Command1 procedure, the AllowAudioOutputFormatChangesOnNextSet is set to True, and the voice's format is changed. In the Command2 procedure, this property is set to False, and the voice's format is not changed.

  
Option Explicit

Dim V As SpeechLib.SpVoice
Dim O As SpMMAudioOut
Dim S As ISpeechBaseStream

Dim f As SpeechLib.SpeechAudioFormatType    'This is an Enum

Private Sub Form_Load()
    On Error GoTo EH

    Set V = New SpVoice
    Set O = New SpMMAudioOut
    f = SAFT22kHz8BitMono       'The test audio output format

EH:
    If Err.Number Then ShowErrMsg
End Sub

Private Sub Command1_Click()
    On Error GoTo EH

    V.AllowAudioOutputFormatChangesOnNextSet = True

    O.Format.Type = f               'AudioOut obj gets SAFT22kHz8BitMono format
    Set V.AudioOutputStream = O     'The "Next Set"
    V.Speak "Adjust my format"      'Speak
    Set S = V.AudioOutputStream     'Stream object gets voice's format

    If S.Format.Type = f Then
        MsgBox "format not adjusted"
    Else
        MsgBox "format adjusted"
    End If

EH:
    If Err.Number Then ShowErrMsg
End Sub

Private Sub Command2_Click()
    On Error GoTo EH

    V.AllowAudioOutputFormatChangesOnNextSet = False

    O.Format.Type = f               'AudioOut obj gets SAFT22kHz8BitMono format
    Set V.AudioOutputStream = O     'The "Next Set"
    V.Speak "Leave my format alone" 'Speak
    Set S = V.AudioOutputStream     'Stream object gets voice's format

    If S.Format.Type = f Then
        MsgBox "format not adjusted"
    Else
        MsgBox "format adjusted"
    End If

EH:
    If Err.Number Then ShowErrMsg
End Sub

Private Sub ShowErrMsg()

    ' Declare identifiers:
    Dim T As String

    T = "Desc: " & Err.Description & vbNewLine
    T = T & "Err #: " & Err.Number
    MsgBox T, vbExclamation, "Run-Time Error"
    End

End Sub