ISpeechRecoGrammar SetWordSequenceData Method (SAPI 5.3)

Microsoft Speech API 5.3

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