Interface: ISpeechRecoGrammar

SetWordSequenceData Method

The SetWordSequenceData method defines a word sequence buffer for use by the speech recognition (SR) engine.

Some recognition grammars specify every word and phrase that they are capable of recognizing. The Solitaire grammar is one of these; it contains only a small amount of data, and all its data elements were known to the grammar designer. But it would be impractical to create such a grammar for a speech-enabled order-entry system handling several hundred thousand inventory items.

In order to eliminate the need to specify every recognizable word in a grammar, yet still maintain the high quality of rule-based recognition, SAPI provides applications with a means to link the grammar to application-specific and user-specific data. An order-entry application could display the text for several inventory items on a user's monitor, and send this text to the engine for recognition. When a user spoke a part number, the engine would more easily recognize it from the few words on the user's screen than from thousands of part numbers specified in a grammar.

To accomplish this, the SR engine maintains a text buffer which is associated with the XML grammar tag <TEXTBUFFER>. When the recognition process arrives at a <TEXTBUFFER> tag, it expects that the application has placed text in this buffer, and that the user's speech represents one word or phrase out of the words and phrases in the buffer. If recognition is successful, the words or phrases selected from the buffer are recognized as if they had been specified in the grammar rule literally.

The SetWordSequenceData method sends this text to the engine's buffer. It is associated with the SetTextSelection method, which describes the range of text the user has selected with the mouse. The SetWordSequenceData method always sends selection data with the text data, because changing the text in the buffer invalidates the previous selection data. The SetTextSelection method sends selection data only.

ISpeechRecoGrammar.SetWordSequenceData(
     Text As String,
     TextLength As Long,
     Info As SpTextSelectionInformation
)

Parameters

Text

Specifies the text.

TextLength

Specifies the length of the text.

Info

An SpTextSelectionInformation object which specifies the text selection range.

Return Value

None.

Example

The following Visual Basic form code demonstrates the use of the SetWordSequenceData and SetTextSelection methods. To run this code, create a form with the following controls:

• A text box called Text1
• A list box called List1
• A command button called Command1

Paste this code into the Declarations section of the form.

Because selecting data in the text box is an important visual part of this example, the HideSelection property of the text box should be set to False.

The Form_Load procedure creates a recognizer, a recognition context, and a grammar object. It fills the text box with the names of several types of animals. It writes an XML grammar file which contains a grammar rule using a text tag. The rule expects a sentence like "Send me a *," where "*" is a type of animal listed in the text box.

Double-click on an animal type in the text box to select it, and then click Command1. The Command1 procedure gets the selected animal type and builds a sentence such as, "Send me a hamster," or "Send me a chinchilla." If no animal type is selected in the text box, the sample uses the first animal listed. The procedure then speaks the sentence into a wave file and sends the file to the recognition context for recognition.

The Recognition event procedure displays some of the recognition data in the list box. It first determines if the recognition result satisfied a grammar rule; if so, it displays the name of the rule. In this case, PETS is the only rule that can be satisfied. The procedure then displays the individual phrase elements of the sentence.

Option Explicit

Const WAVEFILENAME = "C:\SetWordSequenceData.wav"
Const XMLFILENAME = "C:\texttag.xml"

Dim MyRecognizer As SpeechLib.SpInprocRecognizer
Dim MyGrammar As SpeechLib.ISpeechRecoGrammar
Dim MyFileStream As SpeechLib.SPFileStream
Dim PhraseElem As SpeechLib.ISpeechPhraseElement
Dim Voice1 As SpeechLib.SpVoice
Dim Voice2 As SpeechLib.SpVoice     'Plays the wave file back
Dim TextSelectInfo As SpeechLib.SpTextSelectionInformation

Dim WithEvents RecoContext As SpeechLib.SpInProcRecoContext

Private Sub Form_Load()
    On Error GoTo EH

    ' Create Recognizer, RecoContext, Grammar, and Voices:
    Set MyRecognizer = New SpInprocRecognizer
    Set RecoContext = MyRecognizer.CreateRecoContext
    Set MyGrammar = RecoContext.CreateGrammar()
    Set Voice1 = New SpVoice
    Set Voice1.Voice = Voice1.GetVoices("gender=male").Item(0)
    Set Voice2 = New SpVoice
    Set TextSelectInfo = New SpeechLib.SpTextSelectionInformation

    ' Write a grammar with a transition and then use it:
    Call WriteGrammar(XMLFILENAME)
    MyGrammar.CmdLoadFromFile XMLFILENAME, SLOStatic

    ' Set command-and-control grammar and dictation active:
    MyGrammar.CmdSetRuleIdState 0, SGDSActive
    MyGrammar.DictationSetState SGDSActive

    Text1.HideSelection = False
    Text1.Text = "pony dog cat mouse rabbit hamster chinchilla parrot turtle"

EH:
    If Err.Number Then ShowErrMsg
End Sub

Private Sub WriteGrammar(strFName)

    On Error GoTo EH
	
    Open strFName For Output As #1
    Print #1, "<GRAMMAR>"
    Print #1, " <RULE NAME=""PETS"" TOPLEVEL=""ACTIVE"">"
    Print #1, "   <O>please</O>"
    Print #1, "   <P>send me a</P>"
    Print #1, "   <TEXTBUFFER/>"    '<-- Calls for WordSequenceData
    Print #1, " </RULE>"
    Print #1, "</GRAMMAR>"
    Close #1
	
EH:
    If Err.Number Then ShowErrMsg
End Sub

Private Sub SetTextSelection(T As Control)
    On Error GoTo EH

    TextSelectInfo.ActiveOffset = 0                    'Start of text
    TextSelectInfo.ActiveLength = Len(T.Text)          'Length of text
    TextSelectInfo.SelectionOffset = T.SelStart + 1    'Start of selected text
    TextSelectInfo.SelectionOffset = T.SelLength       'Length of selected text
    MyGrammar.SetTextSelection TextSelectInfo        'Send text-selection data to SR engine

EH:
    If Err.Number Then ShowErrMsg
End Sub

Private Sub SetWordSequenceData(T As Control)
    On Error GoTo EH

    Call SetTextSelection(T)                        'Set up text-selection data
    MyGrammar.SetWordSequenceData T.Text, Len(T.Text), TextSelectInfo  'Send the text itself to engine

EH:
    If Err.Number Then ShowErrMsg
End Sub

Private Sub Command1_Click()
    Dim W As String

    On Error GoTo EH

    'Get selected word for voice to speak
    If Text1.SelLength Then
        W = Mid(Text1.Text, Text1.SelStart + 1, Text1.SelLength)
    Else
        W = "pony"
    End If
    W = "send me a " & W    'Voice speaks this string

    'Send buffer text and selection data to engine
    Call SetWordSequenceData(Text1)

    List1.Clear
    Set MyFileStream = MakeWAVFileFromText(W, WAVEFILENAME)
    MyFileStream.Open WAVEFILENAME
    Set MyRecognizer.AudioInputStream = MyFileStream

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 X As String
    Dim ii As Integer

    On Error GoTo EH

    If Not Result.PhraseInfo.Rule.Name = "" Then
        List1.AddItem "   Result matches rule """ & Result.PhraseInfo.Rule.Name & """"
    End If

    ii = 0
    For Each PhraseElem In Result.PhraseInfo.Elements
        X = "element " & Format(ii, "00") & ": " & PhraseElem.DisplayText
        List1.AddItem X
        ii = ii + 1
    Next

EH:
    If Err.Number Then ShowErrMsg
End Sub

Private Sub RecoContext_EndStream _
   (ByVal StreamNumber As Long, _
    ByVal StreamPosition As Variant, _
    ByVal StreamReleased As Boolean)

    On Error GoTo EH
    MyFileStream.Close
    DoEvents
    MyFileStream.Open WAVEFILENAME
    Voice2.SpeakStream MyFileStream
    MyFileStream.Close

EH:
    If Err.Number Then ShowErrMsg
End Sub

Private Function MakeWAVFileFromText _
   (ByVal strText As String, _
    ByVal strFName As String) _
    As SPFileStream

    On Error GoTo EH

    ' Declare identifiers:
    Dim FileStream As SPFileStream
    Dim Voice As SpVoice

    ' Instantiate Voice and FileStream objects:
    Set Voice = New SpVoice
    Set FileStream = New SPFileStream

    ' Open specified .wav file, set voice output
    ' to file, and speak synchronously:
    FileStream.Open strFName, SSFMCreateForWrite, True
    Set Voice.AudioOutputStream = FileStream
    Voice.Speak strText, SVSFIsXML

    ' Close file and return reference to FileStream object:
    FileStream.Close
    Set MakeWAVFileFromText = FileStream

EH:
    If Err.Number Then ShowErrMsg
End Function

Private Sub ShowErrMsg()

    ' Declare identifier:
    Dim T As String

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

End Sub