SpeechRecoContext Bookmark Method (SAPI 5.3)

Article
04/17/2012

Microsoft Speech API 5.3

Bookmark Method

The Bookmark method sets a bookmark within the current recognition stream.

A bookmark relates an audio stream position with an occurrence significant to the application. The speech recognition (SR) engine has a latency period between the speech and the recognition. This latency may be caused by a long speech period (the engine must have all the phrase before processing it) or other events may already be queued and the engine must finishing process those first. However, during that latent period, the user or application may continue operations (such as moving the mouse or speaking). As a result, the condition of the application may be different when the recognition comes back than it was when recognition was initiated. A bookmark allows the application to mark or record a condition of the application to a particular recognition attempt.

Bookmark is a convenient alternative to polling the engine for stream position (see ISpeechRecognizer.Status). A Bookmark event is returned when the bookmark has been processed by the engine. See ISpeechRecoContext.Bookmark for further information.

  
    SpeechRecoContext.Bookmark(
     Options As SpeechBookmarkOptions,
     StreamPos As Variant,
     BookmarkId As Variant
)

Parameters

Options
Specifies whether the recognition context will pause when encountering bookmarks. This must be value of type SpeechBookmarkOptions.
StreamPos
Specifies the stream position. This value may be anywhere in the stream and will send a Bookmark event when that position is reached. Additionally it may be any one of two special values: Speech_StreamPos_Asap or Speech_StreamPos_RealTime.
BookmarkId
Specifies the BookmarkId. BookmarkId is additional information provided by the application and is unique to the application. As a Variant data type, it may be numeric, String, or any other format and is used to pass information within the method or event. If BookmarkId is a String, the value must be able to convert to a numeric value. This information is returned back using the Bookmark event.

Return Value

None.

Remarks

An application that wants to display a recognition progress meter, for example could use ISpeechRecoContext.Bookmark and update the UI when each bookmark is received.

Example

The following Visual Basic form code demonstrates the use of the Bookmark method and its associated event. Each Bookmark event can be identified by the setting of the BookmarkId paramater and that value may be used inside the event for additional processing. Additional events may be raised by adding new Bookmarks. This example assumes that the grammar file is located at C:\sol.xml.

To run this code, paste it into the Declarations section of a form without any controls.

  
Option Explicit

Dim WithEvents RecoContext As SpInProcRecoContext

Private Sub Form_Load()
    On Error GoTo EH

    Const Text = "One of the world's seven wonders"
    Dim Grammar As ISpeechRecoGrammar
    Dim Recognizer As SpInprocRecognizer
    Dim Voice As SpVoice

    Set Voice = New SpVoice
    Set Recognizer = New SpInprocRecognizer

    ' Set up speech recognition and grammar (assumes
    ' grammar file is at "C:\sol.xml"):
    Set RecoContext = Recognizer.CreateRecoContext
    Set Grammar = RecoContext.CreateGrammar(1)
    Grammar.CmdLoadFromFile "C:\sol.xml"

    ' Set first bookmark before recognition.
    RecoContext.Bookmark SBONone, 0, "5"

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

    ' Set second bookmark after recognition.
    RecoContext.Bookmark SBONone, 0, "10"

EH:
    If Err.Number Then ShowErrMsg
End Sub

Private Sub RecoContext_Bookmark _
   (ByVal StreamNumber As Long, _
    ByVal StreamPosition As Variant, _
    ByVal BookmarkId As Variant, _
    ByVal Options As SpeechLib.SpeechBookmarkOptions)

    If BookmarkId = 5 Then
        MsgBox "Bookmark 5 event raised", vbInformation
    ElseIf BookmarkId = 10 Then
        MsgBox "Bookmark 10 event raised", vbInformation
    End If

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

Share via