Using in applications (wrapper grammars)

To use SSMs and confidence files, you must specify them inside a SRGS grammar that is extended with a Nuance namespace.

The namespace provides several grammar elements:

Element

Description

<semantic_interpretation>

Contains semantic components, and optionally indicates their precedence. Described below.

<component>

Groups an SSM and (optionally) a confidence engine model. Optionally, it specifies a local confidence threshold for the SSM. Described below.

<interpreter>

Specifies a URI to a semantic interpreter (a SRGS grammar or a trained SSM). See also Training an SSM.

<confidence_engine>

Specifies a URI to a .conf file (a confidence engine model). See Confidence engine models.

A grammar used for this purpose is known as a wrapper grammar. You can specify one SSM, more than one SSM (activated in parallel), or multiple grammars specified in order of priority (override grammars).

This example activates a single SSM:

<?xml version="1.0" encoding="UTF-8"?>
<grammar xml:lang="en-US" version="1.0"
        xmlns="http://www.w3.org/2001/06/grammar"
        mode="voice" root="dummy">
    <meta name="swirec_fsm_parser" content="NULL"/>
    <meta name="swirec_fsm_grammar" content="myapp.fsm"/>
    <meta name="swirec_fsm_wordlist" content="myapp.wordlist"/>
    <semantic_interpretation
            xmlns="http://www.nuance.com/semantics" priority="1">
        <component confidence_threshold="0.00">
        <interpreter uri="trained.ssm"
            type="application/x-vnd.nuance.ssm"/>
        <confidence_engine uri="trained.conf"
            type="application/x-vnd.nuance.confengine"/>
        </component>
    </semantic_interpretation>
    <rule id="dummy">
        dummy
    </rule>
</grammar>

The example illustrates several aspects of wrapper grammars:

  • The namespace attribute (xmlns) is required.
  • The <component> element contains the SSM interpreter and (optional) confidence engine model.
  • The optional confidence_threshold parameter is local to the SSM; semantic values below the threshold do not appear in results. This parameter allows you to distinguish between SSMs that are highly accurate (with strong correlation between words and meanings) or less accurate (where the correlation is more vague). If you omit this parameter for any SSM, the default threshold for that SSM is determined by the swissm_confidence_threshold parameter (set via the Recognizer).
  • The type attribute is required for <interpreter> and <confidence_engine>.

You can specify more than one <semantic_intepretation> element; this lets you activate parallel SSMs simultaneously during recognition. (For an overview, see Parallel SSMs.)

This example activates two parallel SSMs. They fill different slots in one result:

<!-- insert header here -->
<semantic_interpretation xmlns="http://www.nuance.com/semantics">
   <component confidence_threshold="0.33">
     <interpreter uri="color.ssm" type="myapp/x-vnd.nuance.ssm"/>
    <confidence_engine 
        uri="general.conf" type="myapp/x-vnd.nuance.confengine"/>
    </component>
    <component confidence_threshold="0.27">
   <interpreter uri="command.ssm" type="myapp/x-vnd.nuance.ssm"/>
    <confidence_engine 
        uri="general.conf" type="myapp/x-vnd.nuance.confengine"/>
    </component>
</semantic_interpretation>
</grammar>

Note: If a single slot is set by more than one parallel grammar, precedence is determined by the document order in the wrapper file. In the example above, the value set by color.ssm would be returned.

You can activate SRGS grammars in parallel with SSMs. This is useful for implementing override grammars. At runtime, Recognizer interprets higher-priority grammars first, and only applies a lower-priority grammar if the first one failed. In other words, Recognizer activates grammar components in sequence and not in parallel (see Override grammars).

The example below shows the most typical scenario: an SRGS grammar is interpreted first, and an SSM second. One or the other will provide a semantic result, but not both.

<?xml version="1.0" encoding="UTF-8"?>
<grammar xml:lang="en-US" version="1.0"
        xmlns="http://www.w3.org/2001/06/grammar"
        mode="voice" root="commands">
    <!-- <meta name="swirec_fsm_parser" content="NULL"/> -->
    <meta name="swirec_fsm_grammar" content="sample.fsm"/>
    <meta name="swirec_fsm_wordlist" content="sample.wordlist"/>
    <semantic_interpretation
        xmlns="http://www.nuance.com/semantics" priority="1">
        <component>
          <interpreter uri="#commands" type="application/srgs+xml"/>
        </component>
    </semantic_interpretation>
    <semantic_interpretation
        xmlns="http://www.nuance.com/semantics" priority="2">
        <component confidence_threshold="0.33">
           <interpreter uri="S2.ssm"
              type="application/x-vnd.nuance.ssm"/>
           <confidence_engine uri="conf.out"
              type="application/x-vnd.nuance.confengine"/> 
        </component>
    </semantic_interpretation>
    <semantic_interpretation
        xmlns="http://www.nuance.com/semantics" priority="3">
        <component confidence_threshold="0.01">
           <interpreter uri="S1.ssm"
              type="application/x-vnd.nuance.ssm"/>
           <confidence_engine uri="conf.out"
              type="application/x-vnd.nuance.confengine"/>
        </component>
    </semantic_interpretation>
    <rule id="commands">
      help
      <tag> command="help" </tag>
    </rule>
</grammar>

This wrapper grammar not only has an override SRGS (root rule); it also has two levels of priority on two SSMs.

  • The first semantic_interpretation block is listed as priority 1. In this example it references the SRGS grammar rule at the bottom of the grammar, which only matches the command “help”. If the grammar rule successfully parses the utterance, this is the result returned, and nothing further is processed; otherwise, the semantic processing moves on to the priority 2 block.
  • The second semantic_interpretation block is listed as priority 2, and it references an SSM and specifies a confidence threshold. If this SSM returns with a confidence over 0.33, then the result is used; otherwise, the semantic processing moves along to the priority 3 block.
  • The third semantic_interpretation block is listed as priority 3, and also references a single SSM (with accompanying confidence engine model), this time with a confidence threshold of 0.01. This is basically a fall-back that catches pretty much any result that isn't complete garbage. This block fires only if the first two SSM interpreters fail to assign a meaning.

If both SSMs had the same priority (such as priority="2"), they would be treated as parallel grammars and could produce multiple interpretations. Both SSMs are processed, regardless of whether either one returns a valid result, but only those results that are above the threshold are included in the "merged" semantic result. That is, if either of the parallel SSMs returns with a confidence over its default threshold, then the result is used.

You can define any sequence of prioritized grammars, but there can only be one SRGS grammar pointing to the root rule in the wrapper grammar—and that SRGS grammar must be in a <semantic_interpretation> element by itself. SSMs can run in parallel when they have the same priority; however, an SRGS grammar never runs in parallel with the SSMs, even if it has the same priority. We recommend that you assign the SRGS grammar a unique priority, in order to avoid confusion.