SpeechRecoContext CmdMaxAlternates Property (SAPI 5.3)

Microsoft Speech API 5.3

Interface: ISpeechRecoContext

CmdMaxAlternates Property

The CmdMaxAlternates property specifies the maximum number of alternates that will be generated for command and control grammars.

By default, the maximum alternates value is zero, so an application must call this method before attempting to retrieve or depend on alternates for command and control. Not all speech recognition engines support command and control or proprietary grammar alternates. If the particular engine does not support alternates, this method will indicate it has succeeded but the number of alternates returned will always be zero.

CmdMaxAlternates has no effect on dictation alternates. See ISpeechRecoResult.Alternates for information regarding dictation alternates.

Syntax

Parts

• SpeechRecoContext
  The owning object.
• Long
  Set: A Long variable setting the maximum number of alternates.
  Get: A Long variable retrieving the maximum number of alternates.

Remarks

Versions of the Microsoft speech recognition engine up to 5.1 did not support command and control alternates, but versions 6.0 and above do. Other manufacturers' engines may also support alternates.

Example

The following Visual Basic form code demonstrates how to retrieve the current number of alternates. However, because not all engines support the alternates feature, SAPI may throw an SPERR_NOT_FOUND exception (that is, -2147200966) if the attribute does not exist. If the attribute does exist, no error will occur and cfgAttribute will be valid, even if only as Empty.

To run this code, paste it into the Declarations section of a form that contains no controls. This code also needs a reference set to simpleaudio 1.0 Type Library to run correctly.

  
Option Explicit

Const AUDIOFORMAT = SAFT8kHz16BitMono

' Text-to-Speech variables:
Dim WithEvents Voice As SpVoice
Dim EndofStream As Boolean
Dim AudioPlugOut As SpAudioPlug

' Speech Recognition variables:
Dim WithEvents RecoContext As SpInProcRecoContext
Dim Grammar As ISpeechRecoGrammar
Dim Recognizer As SpInprocRecognizer
Dim AudioPlugIn As SpAudioPlug

Private Sub Form_Load()

    Const Text = "One of the world's seven wonders"
    Dim Output As Variant

    On Error GoTo EH

    Set Voice = New SpVoice

    ' Set up output audio:
    Set AudioPlugOut = New SpAudioPlug
    AudioPlugOut.Init True, AUDIOFORMAT
    Set Voice.AudioOutputStream = AudioPlugOut

    ' Set up input audio:
    Set AudioPlugIn = New SpAudioPlug
    AudioPlugIn.Init False, AUDIOFORMAT
    Set Recognizer = New SpInprocRecognizer
    Set Recognizer.AudioInputStream = AudioPlugIn

    ' Set up speech recognition and explicitly set
    ' flag to retain audio portion of recognition
    ' (default behavior is not to retain):
    Set RecoContext = Recognizer.CreateRecoContext
    RecoContext.RetainedAudio = SRAORetainAudio
    Set Grammar = RecoContext.CreateGrammar(1)
    Grammar.DictationLoad
    Grammar.DictationSetState SGDSActive

    ' Speak some text to be recognized.
    Voice.Speak Text, SVSFlagsAsync

    Do While EndofStream = False
        DoEvents

        ' Get audio data from audio object.
        Output = AudioPlugOut.GetData

        ' Output audio data to input audio object--
        If (Len(Output) * 2 <> 0) Then
            AudioPlugIn.SetData (Output)
        End If

    Loop

    Grammar.DictationSetState SGDSInactive

EH:
    If Err.Number Then ShowErrMsg
End Sub

Private Sub RecoContext_Recognition _
   (ByVal StreamNumber As Long, _
    ByVal StreamPosition As Variant, _
    ByVal RecognitionType As SpeechLib.SpeechRecognitionType, _
    ByVal Result As SpeechLib.ISpeechRecoResult)

    Dim cfgAttribute As String
    Dim numAlternates As Long
    Dim objToken As Object

    On Error GoTo EH

    Set objToken = Result.RecoContext.Recognizer.Recognizer
    cfgAttribute = objToken.GetAttribute("CGFAlternates")
    numAlternates = Result.RecoContext.CmdMaxAlternates
    MsgBox "# of alternates", vbInformation

EH:
    If Err.Number Then ShowErrMsg
End Sub

Private Sub Voice_EndStream _
   (ByVal StreamNumber As Long, _
    ByVal StreamPosition As Variant)

    EndofStream = True

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