ISpeechRecoGrammar SetWordSequenceData Method (SAPI 5.3)
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 )
- Specifies the text.
- Specifies the length of the text.
- An SpTextSelectionInformation object which specifies the text selection range.
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