Example application of ISpGrammarBuilder (SAPI 5.3)

Article
04/17/2012
Microsoft Speech API 5.3
Example application of ISpGrammarBuilder

The code example below illustrates an implementation of a travel grammar, using the ISpGrammarBuilder interface.
An approximation of the XML form is included for each of the following three grammar authoring approaches.
  
// Declare local identifiers:
HRESULT                       hr = S_OK;
CComPtr<ISpGrammarBuilder>    cpGrammarBuilder;
SPSTATEHANDLE                 hStateTravel;
SPSTATEHANDLE                 hStateTravel_Second;
SPSTATEHANDLE                 hStateMethod;
SPSTATEHANDLE                 hStateDest;

// Create (if rule does not already exist)
// top-level Rule, defaulting to Active.
hr = cpGrammarBuilder->GetRule(L"Travel", 0, SPRAF_TopLevel | SPRAF_Active, TRUE, &hStateTravel;);

// Approach 1: list all possible phrases--
// This is the most intuitive approach, and it does not sacrifice efficiency
// because the grammar builder will merge shared sub-phrases when possible.
// Internally, SAPI may break the transitions into separate transitions if
// there are common roots (e.g. "fly to Seattle" and "fly to New York").
// There is only one root state, hStateTravel, and the terminal NULL state,
// and there are 6 unique transitions between root state and NULL state.

/* XML Approximation:
   <RULE NAME="Travel" TOPLEVEL="ACTIVE">
      <PHRASE>fly to Seattle</PHRASE>
      <PHRASE>fly to New York</PHRASE>
      <PHRASE>fly to Washington DC</PHRASE>
      <PHRASE>drive to Seattle</PHRASE>
      <PHRASE>drive to New York</PHRASE>
      <PHRASE>drive to Washington DC</PHRASE>
   </RULE>
*/

// Create set of peer phrases, each containing complete phrase.
// Note: the word delimiter is set as " ", so that the text we
// attach to the transition can be multiple words (for example,
// "fly to Seattle" is implicitly "fly" + "to" + "Seattle"):
if (SUCCEEDED(hr))
{
   hr = cpGrammarBuilder->AddWordTransition(hStateTravel, NULL, L"fly to Seattle", L" ", SPWT_LEXICAL, 1, NULL);
}
if (SUCCEEDED(hr))
{
   hr = cpGrammarBuilder->AddWordTransition(hStateTravel, NULL, L"fly to New York", L" ", SPWT_LEXICAL, 1, NULL);
}
if (SUCCEEDED(hr))
{
   hr = cpGrammarBuilder->AddWordTransition(hStateTravel, NULL, L"fly to Washington DC", L" ", SPWT_LEXICAL, 1, NULL);
}
if (SUCCEEDED(hr))
{
   hr = cpGrammarBuilder->AddWordTransition(hStateTravel, NULL, L"drive to Seattle", L" ", SPWT_LEXICAL, 1, NULL);
}
if (SUCCEEDED(hr))
{
   hr = cpGrammarBuilder->AddWordTransition(hStateTravel, NULL, L"drive to New York", L" ", SPWT_LEXICAL, 1, NULL);
}
if (SUCCEEDED(hr))
{
   hr = cpGrammarBuilder->AddWordTransition(hStateTravel, NULL, L"drive to Washington DC", L" ", SPWT_LEXICAL, 1, NULL);
}

// Approach 2: construct the directed-graph using intermediate states--
// This approach gives you more control of the grammar layout, and may be
// easier to implement when you have some combinations.
// Using this approach, there is one root state (hStateTravel), one interim state
// (hStateTravel_Second), and the final terminal NULL state. There are three
// unique transitions between the root state and the interim state. And there are
// three more unique transitions between the interim state, and the final NULL state.
// Note that graph includes only 2-transition paths. The user is not capable of saying
// only the first transition or the second transition (e.g. "fly to" is an invalid
// phrase as is "Seattle", but "fly to Seattle" is valid.)

/* XML Approximation:
   <RULE NAME="Travel" TOPLEVEL="ACTIVE">
      <LIST>
         <PHRASE>fly to</PHRASE>
         <PHRASE>drive to</PHRASE>
         <PHRASE>take train to</PHRASE>
      </LIST>
      <LIST>
         <PHRASE>Seattle</PHRASE>
         <PHRASE>New York</PHRASE>
         <PHRASE>Washington DC</PHRASE>
      </LIST>
   </RULE>
*/

// Create a new transition which starts at
// the root state and ends at a second state.
if (SUCCEEDED(hr))
{
   hr = cpGrammarBuilder->CreateNewState(hStateTravel, &hStateTravel;_Second);
}

// Attach the first part of the phrase to to first transition:
if (SUCCEEDED(hr))
{
   hr = cpGrammarBuilder->AddWordTransition(hStateTravel, hStateTravel_Second, L"fly to", L" ", SPWT_LEXICAL, 1, NULL);
}
if (SUCCEEDED(hr))
{
   hr = cpGrammarBuilder->AddWordTransition(hStateTravel, hStateTravel_Second, L"drive to", L" ", SPWT_LEXICAL, 1, NULL);
}
if (SUCCEEDED(hr))
{
   hr = cpGrammarBuilder->AddWordTransition(hStateTravel, hStateTravel_Second, L"take train to", L" ", SPWT_LEXICAL, 1, NULL);
}

// Attach the second and final part of the phrase to
// the last transition (ending with the NULL state):
if (SUCCEEDED(hr))
{
   hr = cpGrammarBuilder->AddWordTransition(hStateTravel_Second, NULL, L"Seattle", L" ", SPWT_LEXICAL, 1, NULL);
}
if (SUCCEEDED(hr))
{
   hr = cpGrammarBuilder->AddWordTransition(hStateTravel_Second, NULL, L"New York", L" ", SPWT_LEXICAL, 1, NULL);
}
if (SUCCEEDED(hr))
{
   hr = cpGrammarBuilder->AddWordTransition(hStateTravel_Second, NULL, L"Washington DC", L" ", SPWT_LEXICAL, 1, NULL);
}

// Approach 3: Using sub rules--
// This approach let you structure the grammars and is useful when building large grammars,
// since it allows for reusable component rules (see also the XML Grammar tag, RULEREF).
// Note that forward-declarations are allowed, since the grammar validation is not performed
// until the XML is compiled or the GrammarBuilder instance is 'Commit'ted.
// The main difference between Approach 2 and Approach 3 is the use of component rules, which
// are combined into one top-level rule. This facilitates the reuse of the component rules
// in other rules (e.g. create a second rule called "Geography" which combines the phrase
// "where is" with the "Dest" rule, allowing the user to say "where is New York", without
// requiring the grammar author/designer to place the same phrase text in multiple places
// of the grammar leading to grammar maintenance problems.

/* XML Approximation:
   <RULE NAME="Travel" TOPLEVEL="ACTIVE">
      <RULEREF NAME="Method"/>
      <RULEREF NAME="Dest"/>
   </RULE>
   <RULE NAME="Method">
      <LIST>
         <PHRASE>fly to</PHRASE>
         <PHRASE>drive to</PHRASE>
         <PHRASE>take train to</PHRASE>
      </LIST>
   </RULE>
   <RULE NAME="Dest" DYNAMIC="TRUE">
      <LIST>
         <PHRASE>Seattle</PHRASE>
         <PHRASE>New York</PHRASE>
         <PHRASE>Washington DC</PHRASE>
      </LIST>
   </RULE>
*/

if (SUCCEEDED(hr))
{
   // Note the two new rules ("Method" & "Dest") are NOT marked Top-level, since they are
   // reused by other top-level rules, and are not by themselves recognizable phrases:
   hr = cpGrammarBuilder->GetRule(L"Method", 0, 0, TRUE, &hStateMethod;);
}
if (SUCCEEDED(hr))
{
   // Marking the "Dest" rules as Dynamic allows the programmatic grammar author to
   // update only the "Dest" rule after the initial ::Commit (e.g. to add more travel
   // destinations depending on user history, preferences, or geographic data):
   hr = cpGrammarBuilder->GetRule(L"Dest", 0, SPRAF_Dynamic, TRUE, &hStateDest;);
}

if (SUCCEEDED(hr))
{
   // Create an interim state (same as Approach 2).
   hr = cpGrammarBuilder->CreateNewState(hStateTravel, &hStateTravel;_Second);
}

// Then attach rules to the transitions from Root->Interim and Interim->NULL state:
if (SUCCEEDED(hr))
{
   hr = cpGrammarBuilder->AddRuleTransition(hStateTravel, hStateTravel_Second, hStateMethod, 1, NULL);
}
if (SUCCEEDED(hr))
{
   hr = cpGrammarBuilder->AddRuleTransition(hStateTravel_Second, NULL, hStateDest, 1, NULL);
}

// Add the set of sibling transitions for travel "method":
if (SUCCEEDED(hr))
{
   hr = cpGrammarBuilder->AddWordTransition(hStateMethod, NULL, L"fly to", L" ", SPWT_LEXICAL, 1, NULL);
}
if (SUCCEEDED(hr))
{
   hr = cpGrammarBuilder->AddWordTransition(hStateMethod, NULL, L"drive to", L" ", SPWT_LEXICAL, 1, NULL);
}
if (SUCCEEDED(hr))
{
   hr = cpGrammarBuilder->AddWordTransition(hStateMethod, NULL, L"take train to", L" ", SPWT_LEXICAL, 1, NULL);
}

// Add the set of sibling transitions for travel "destinations":
if (SUCCEEDED(hr))
{
   hr = cpGrammarBuilder->AddWordTransition(hStateDest, NULL, L"Seattle", L" ", SPWT_LEXICAL, 1, NULL);
}
if (SUCCEEDED(hr))
{
   hr = cpGrammarBuilder->AddWordTransition(hStateDest, NULL, L"New York", L" ", SPWT_LEXICAL, 1, NULL);
}
if (SUCCEEDED(hr))
{
   hr = cpGrammarBuilder->AddWordTransition(hStateDest, NULL, L"Washington DC", L" ", SPWT_LEXICAL, 1, NULL);
}

// Must Commit before the grammar changes before using the grammar.
// NOTE: grammar changes are only given to the engine at synchronize
// points (see ISpSREngineSite::Synchronize).
if (SUCCEEDED(hr))
{
   hr = cpGrammarBuilder->Commit(0);
}

if (SUCCEEDED(hr))
{
   // Do some more stuff here.
}
Share via

Example application of ISpGrammarBuilder (SAPI 5.3)

Example application of ISpGrammarBuilder

Additional resources
