Microsoft Speech Platform

Use Speech Recognition Events

The Microsoft Speech Platform includes events that provide notifications and return information about the status of speech recognition. Most speech recognition events are raised by the speech recognition engine while it is performing recognition. An application can register to receive notification of the events that it wants to process. In addition to subscribing to events, applications should use either a window message, callback function, or Win32 event to signal when speech events are available.

Note that both variations of callback functions as well as the window message notification require a window message pump to run on the thread that initialized the notification source. A callback function will only be called as the result of window message processing, and will always be called on the same thread that initialized the notify source. However, using Win32 events for SAPI event notification does not require a window message pump.

Example

The following code excerpt subscribes to events that are raised when speech recognition begins and when the input stream ends, and establishes a Win32 event. `

// Subscribe to the speech recognition event and end stream event.
if (SUCCEEDED(hr))
{
ULONGLONG ullEventInterest = SPFEI(SPEI_RECOGNITION) | SPFEI(SPEI_END_SR_STREAM);
hr = cpContext->SetInterest(ullEventInterest, ullEventInterest);
}

// Establish a Win32 event to signal when speech events are available.
HANDLE hSpeechNotifyEvent = INVALID_HANDLE_VALUE;
if (SUCCEEDED(hr))
{
hr = cpContext->SetNotifyWin32Event();
}
if (SUCCEEDED(hr))
{
hSpeechNotifyEvent = cpContext->GetNotifyEventHandle();
if (INVALID_HANDLE_VALUE == hSpeechNotifyEvent)
{
// Notification handle unsupported.
hr = E_NOINTERFACE;
}
}

See the end of this topic for an example of a complete console application that subscribes to events, recognizes speech input, and processes events raised during speech recognition.

Speech recognition events in the Speech Platform

The following table lists and describes the events raised in the Speech Platform to support speech recognition.

Complete speech recognition example

The following is an example of a complete console application that subscribes to events, recognizes speech, and processes events raised during speech recognition. The example loads a speech recognition grammar that recognizes phrases such as "Find restaurants near Madrid". See the end of the code example for the contents of the grammar.

`

int _tmain(int argc, _TCHAR* argv[])
{
CoInitialize(NULL);
{
HRESULT hr = S_OK;

    // Find the best matching installed en-us recognizer.
    CComPtr<ISpObjectToken> cpRecognizerToken;

    if (SUCCEEDED(hr))
    {
        hr = SpFindBestToken(SPCAT_RECOGNIZERS, L"language=409", NULL, &cpRecognizerToken;);
    }

    // Create a recognizer and immediately set its state to inactive.
    CComPtr<ISpRecognizer> cpRecognizer;

    if (SUCCEEDED(hr))
    {
        hr = cpRecognizer.CoCreateInstance(CLSID_SpInprocRecognizer);
    }

    if (SUCCEEDED(hr))
    {
        hr = cpRecognizer->SetRecognizer(cpRecognizerToken);
    }

    if (SUCCEEDED(hr))
    {
        hr = cpRecognizer->SetRecoState(SPRST_INACTIVE);
    }

    // Create a new recognition context from the recognizer.
    CComPtr<ISpRecoContext> cpContext;

    if (SUCCEEDED(hr))
    {
        hr = cpRecognizer->CreateRecoContext(&cpContext;);
    }

    // Subscribe to the speech recognition event and end stream event.
    if (SUCCEEDED(hr))
    {
        ULONGLONG ullEventInterest = SPFEI(SPEI_RECOGNITION) | SPFEI(SPEI_END_SR_STREAM);
        hr = cpContext->SetInterest(ullEventInterest, ullEventInterest);
    }

    // Establish a Win32 event to signal when speech events are available.
    HANDLE hSpeechNotifyEvent = INVALID_HANDLE_VALUE;

    if (SUCCEEDED(hr))
    {
        hr = cpContext->SetNotifyWin32Event();
    }

    if (SUCCEEDED(hr))
    {
        hSpeechNotifyEvent = cpContext->GetNotifyEventHandle();

        if (INVALID_HANDLE_VALUE == hSpeechNotifyEvent)
        {
            // Notification handle unsupported.
            hr = E_NOINTERFACE;
        }
    }

    // Initialize an audio object to use the default audio input of the system and set the recognizer to use it.
    CComPtr<ISpAudio> cpAudioIn;

    if (SUCCEEDED(hr))
    {
        hr = cpAudioIn.CoCreateInstance(CLSID_SpMMAudioIn);
    }

    // This will typically use the microphone input. 
    // Speak a phrase such as "Find restaurants near Madrid".  
    if (SUCCEEDED(hr))
    {
        hr = cpRecognizer->SetInput(cpAudioIn, TRUE);
    }

    // Populate a WAVEFORMATEX struct with our desired output audio format information.
    WAVEFORMATEX* pWfexCoMemRetainedAudioFormat = NULL;
    GUID guidRetainedAudioFormat = GUID_NULL;

    if (SUCCEEDED(hr))
    {
        hr = SpConvertStreamFormatEnum(SPSF_16kHz16BitMono, &guidRetainedAudioFormat;, &pWfexCoMemRetainedAudioFormat;);
    }

    // Create a new grammar and load an SRGS grammar from file.
    CComPtr<ISpRecoGrammar> cpGrammar;

    if (SUCCEEDED(hr))
    {
        hr = cpContext->CreateGrammar(0, &cpGrammar;);
    }

    if (SUCCEEDED(hr))
    {
        hr = cpGrammar->LoadCmdFromFile(L"C:\\Test\\FindServices.grxml", SPLO_STATIC);
    }

    // Set all top-level rules in the new grammar to the active state.
    if (SUCCEEDED(hr))
    {
        hr = cpGrammar->SetRuleState(NULL, NULL, SPRS_ACTIVE);
    }

    // Set the recognizer state to active to begin recognition.
    if (SUCCEEDED(hr))
    {
        hr = cpRecognizer->SetRecoState(SPRST_ACTIVE_ALWAYS);
    }    

    // Establish a separate win32 event to signal event loop exit.
    HANDLE hExitEvent = CreateEvent(NULL, FALSE, FALSE, NULL);

    // Collect the events listened for to pump the speech event loop.
    HANDLE rghEvents[] = { hSpeechNotifyEvent, hExitEvent };

    // Speech recognition event loop.
    BOOL fContinue = TRUE;

    while (fContinue && SUCCEEDED(hr))
    {
        // Wait for either a speech event or an exit event.
        DWORD dwMessage = WaitForMultipleObjects(sp_countof(rghEvents), rghEvents, FALSE, INFINITE);

        switch (dwMessage)
        {
            // With the WaitForMultipleObjects call above, WAIT_OBJECT_0 is a speech event from hSpeechNotifyEvent.
            case WAIT_OBJECT_0: 
            {
                // Sequentially grab the available speech events from the speech event queue.
                CSpEvent spevent;

                while (S_OK == spevent.GetFrom(cpContext))
                {
                    switch (spevent.eEventId)
                    {
                        case SPEI_RECOGNITION:
                        {
                            // Retrieve the recognition result and output the text of that result.
                            ISpRecoResult* pResult = spevent.RecoResult();

                            LPWSTR pszCoMemResultText = NULL;
                            hr = pResult->GetText(SP_GETWHOLEPHRASE, SP_GETWHOLEPHRASE, TRUE, &pszCoMemResultText;, NULL);

                            if (SUCCEEDED(hr))
                            {
                                wprintf(L"Recognition event received, text=\"%s\"\r\n", pszCoMemResultText);
                            }

                            if (NULL != pszCoMemResultText)
                            {
                                CoTaskMemFree(pszCoMemResultText);
                            }

                            break;
                        }
                        case SPEI_END_SR_STREAM:
                        {
                            // The stream has ended; signal the exit event if it hasn't been signaled already.
                            wprintf(L"End stream event received\r\n");
                            SetEvent(hExitEvent);
                            break;
                        }
                    }
                }

                break;
            }
            case WAIT_OBJECT_0 + 1:
            {
                // Exit event; discontinue the speech loop.
                fContinue = FALSE;
                break;
            }
        }
    }

    // Pause to prevent application exit.
    wprintf(L"Press any key to exit!\r\n");
    getchar();
}
CoUninitialize();

return 0;

}

The following are the contents of the grammar file (FindServices.grxml) used in the preceding example. See Grammar Authoring Overview for more information about authoring grammars.

`

<?xml version="1.0" encoding="utf-8"?>
<grammar version="1.0" xml:lang="en-US" mode="voice" root="findServices"
xmlns="http://www.w3.org/2001/06/grammar" tag-format="semantics/1.0">

<rule id="findServices">
<item> Find </item>
<ruleref uri="#services"/>
<item> near </item>
<ruleref uri="#city"/>
</rule>
<rule id="services">
<one-of>
<item> restaurants </item>
<item> gas stations </item>
<item> coffee </item>
</one-of>
</rule>
<rule id="city">
<one-of>
<item> Seattle </item>
<item> Madrid </item>
<item> London </item>
</one-of>
</rule>
</grammar>