Chapter 7

CoffeeS5

Introduction

The concepts of resource management were introduced in CoffeeS4. There, the sources of information that SAPI needed (such as voices and recognizers) were stored as tokens waiting to be used. When needed, the tokens were read and used as parameters to create objects. In turn, the objects were the actual implementation of those resources in working form. As objects, they have methods, validated data and communication paths to other parts of the speech system.

CoffeeS4 displayed the names of the available voices. It could even speak something in the current voice. However, as far as managing employees, there was little else it could do. CoffeeS5 addresses managing employees a little bit further. In addition to displaying voice names, you can pick a different voice for each employee. You can also choose the type of voice you want displayed and spoken. You can choose feminine, masculine, or all voices.

The following topic will be discussed

·         Dynamic Grammars

Dynamic Grammars

Up until now Coffee has only worked with static grammars. That is, for command and control issues, the word list has been both explicit and static. Explicit in that a list of exact words has been defined and therefore no words outside of this list are recognized. For instance, the grammar rule VID_DrinkType lists five types of drinks. Latte is included and may be ordered, but cola is not included and therefore cannot be ordered. Any order including cola would not be recognized. Static means this list is defined ahead of time and is not subject to change. Although the .xml file may be edited independently of the application, it may not be changed during execution.

As the name implies, a dynamic grammar is the opposite of a static one. First, words may be added and deleted during run time and the list does not need to be predetermined. This gives applications much greater latitude. CoffeeS5 demonstrates this by dynamically adding voices. Because the list of available voices may change not only from one computer to another, but also by user profile, there is no way to predetermine the available voices. CoffeeS4 started the process by polling the system for voice tokens-- the definitive list of available voices. CoffeeS5 expands now to construct and use a grammar.

The logic to initializing the grammar is straightforward although there are a few subtleties. First, the rule is retrieved or created. CoffeeS5 creates a new rule but other applications could modify existing ones. Second, unwanted words are removed. Since CoffeeS5 adds all the words itself, for simplicity, the entire existing rule is erased. Again, another application could examine each word first before removing it. Regardless, SAPI needs to know explicitly to make the changes. As a last step, the new commands are added and the changes committed.

The magic happens in the ManageEmployeesPaneProc() WM_InitPane case. Specifically, because of the ::GetRule call.

SPSTATEHANDLE  hDynamicRuleHandle;

hr = g_cpCmdGrammar->GetRule(NULL, DYN_TTSVOICERULE, SPRAF_TopLevel | SPRAF_Active | SPRAF_Dynamic, TRUE, &hDynamicRuleHandle);

Words may be added and deleted freely now. That is, up to the point of removing all words from a grammar. Conversely, and in this case, a completely empty grammar may be used and words added in; there is nothing wrong with an empty grammar. As an example, CoffeeS5 can actually add a cola drink to the order list or remove latte if the milk runs out. However, CoffeeS5 starts the rule from scratch. ::GetRule not only retrieves existing rules but also creates new ones. The fCreateIfNotExist member (TRUE in this case) creates the rule.

The first two parameters are often mutually exclusive. The first one, requests a rule by name and the second one searches by ID. In practice, knowing either the name or the ID is enough and you can leave the unneeded one NULL or zero respectively. Since you are creating a new rule, it will not have an ID to search for (hence the NULL value) and you must specify the name (DYN_TTSVOICERULE). The attributes may also be set here. Some attributes may (and will be) set later. This includes activating and deactivating grammars. Other attributes must be set at the time of creation. The rule is being made to be top-level, dynamic and active. The values may be strung together with logical operators to get the exact nuance you want. And last, a handle  (hDynamicRuleHandle) is passed back.

It is possible that there was already a rule existing for DYN_TTSVOICERULE. It might not have been properly destroyed before or you just forgot to remove it. ::ClearRule removes the state information for the rule. In essence, all the words are removed and it effectively guarantees a clean start.

// Clear the rule first
hr = g_cpCmdGrammar->ClearRule( hDynamicRuleHandle );

// Commit the changes
hr = g_cpCmdGrammar->Commit(0);

After making any changes to the grammar, SAPI must be notified explicitly. ::Commit submits the changes to SAPI and thereafter the grammar is considered in the new state, with the new words. The parameter must be set to zero or it returns an error. In the example above, CoffeeS5 simply clears out the words and commits the changes. The grammar is now in a pristine state.

Words are added to the grammar using ::AddWordTransition.