Using the Interpretation Object

#include <LV_SRE_Semantic.h>

When the speech port executes your semantic interpretation tags, the output is an ECMAScript (JavaScript) object. LumenVox provides a C and C++ API for examining this object. When the speech port has finished its decode, and processed the resulting parse tree and tags, you may request an interpretation object. The interpretation object contains information about the decode -- confidence score, matching grammar, etc. -- plus a single semantic data object.

C API

  1. H_SI interpretation = LV_SRE_CreateInterpretation (hport,voicechannel,index);
  2.  
  3. // the name of the active grammar that matched this interpretation
  4. const char* grammar = LVInterpretation_GetGrammarLabel (interpretation);
  5.  
  6. // the Speech Engine's confidence in this interpretation
  7. int confidence = LVInterpretation_GetScore (interpretation);
  8.  
  9. // the sentence that the Speech Engine decoded
  10. const char* sentence = LVInterpretation_GetInputSentence (interpretation);
  11.  
  12. // the object returned by the semantic interpretation process
  13. H_SI_DATA result_data = LVInterpretation_GetResultData (interpretation);

C++ API

  1. LVInterpretation interpretation = port.GetInterpretation (voicechannel, index);
  2.  
  3. const char* grammar = interpretation.GrammarLabel( );
  4.  
  5. int confidence = interpretation.Score( );
  6.  
  7. const char* sentence = interpretation.InputSentence ( );
  8.  
  9. LVSemanticData result_data = interpretation.ResultData ( );

Semantic Data Examples

In the following examples, the grammar will be:

#ABNF 1.0;
language en-US;
mode voice;
tag-format <lumenvox/1.0>; //This line tells the engine how to interpret the grammar's tags.

root $small_number_and_text;

$base = (one:"1"|two:"2"|three:"3"|four:"4"|five:"5"|six:"6"|seven:"7"| eight:"8"|nine:"9"){ $ = parseInt($) };

$teen = ten:"10"|eleven:"11"|twelve:"12"|thirteen:"13"|fourteen:"14"|fifteen:"15" |
sixteen:"16"|seventeen:"17"|eighteen:"18"|nineteen:"19"
{ $ = parseInt($) };

$twenty_to_ninetynine = (twenty:"20"|thirty:"30"|forty:"40"|fifty:"50"|sixty:"60"|
seventy:"70"|eighty:"80"|ninety:"90"){ $ = parseInt($) }
[$base { $ += $base }];

$tens = ($base|$teen|$twenty_to_ninetynine) { $ = $$ };

$hundred = ([a] hundred {$ = 100} | $base hundred {$ = 100 * $base});

$small_number = $hundred {$ = $$} [[and] $tens {$ += $$}] | $tens { $ = $$ };

$small_number_and_text = $small_number { $.number = $$; $.text = $$$.text };

And the input sentence will be "four hundred and six." If you do not understand how SRGS grammars are written, or how the semantic interpretation process works, please read the SRGS Grammar and/or Semantic Interpretation tutorials now.

The result of the semantic interpretation process on the input sentence is an ECMAScript object that looks like this:

small_number_and_text : // return value of type SI_TYPE_OBJECT
{
number: 406, // property of type SI_TYPE_INT
text: "four hundred and six" // property of type SI_TYPE_STRING
}

Example 1: Access Data Directly

If we knew that our application would always be receiving an object containing an integer property named "number", and a string property named "text", we could write code to retrieve the data as follows:

C Code

  1. H_SI_DATA result  = LVInterpretation_GetResultData(interpretation);
  2.  
  3. H_SI_DATA number_container = LVSemanticObject_GetPropertyValue(result,"number");
  4. int number = LVSemanticData_GetInt(number_container);
  5.  
  6. H_SI_DATA text_container = LVSemanticObject_GetPropertyValue(result,"text");
  7. const char* text = LVSemanticData_GetString(text_container);

C++ Code

  1. LVSemanticObject result_obj = interpretation.ResultData().GetSemanticObject( );
  2.  
  3. int number = result_obj["number"].GetInt( );
  4.  
  5. const char* text = result_obj["text"].GetString( );

Example 2: Traverse a Semantic Data Structure

You can get the interpretation data as an XML string using GetInterpretationString.:

C Code

  1. if (LV_SRE_GetNumberOfInterpretations(port_handle, voice_channel) > 0)
  2. {
  3. printf("%s\n",LV_SRE_GetInterpretationString(hport, voice_channel, index));
  4. }

C+ Code

  1. if (port.GetNumberOfInterpretations(voicechannel) > 0)
  2. {
  3. printf("%s\n",port.GetInterpretationString(voicechannel, index)
  4. }

Note that you will need to parse this string in your client application.

The following code prints a generic interpretation object as an XML fragment:

C Code

  1. void PrintXML(H_SI hsi)
  2. {
  3. const char* result_name = LVInterpretation_GetResultName(hsi);
  4.  
  5. printf("<%s>\n",result_name);
  6. PrintDataXML(LVInterpretation_GetResultData(hsi));
  7. printf("</%s>\n",result_name);
  8. }
  9.  
  10. void PrintDataXML(H_SI_DATA hsi)
  11. {
  12. int i;
  13. int n;
  14. const char* property_name;
  15.         H_SI_DATA data;
  16.  
  17. switch(LVSemanticData_GetType(hsi))
  18. {
  19. case SI_TYPE_BOOL:
  20. LVSemanticData_GetBool(hsi) ? printf("true\n") : printf("false\n");
  21. break;
  22.  
  23. case SI_TYPE_INT:
  24. printf("%d\n", LVSemanticData_GetInt(hsi));
  25.                 break;
  26.  
  27. case SI_TYPE_DOUBLE:
  28. printf("%f\n", LVSemanticData_GetDouble(hsi));
  29. break;
  30.  
  31. case SI_TYPE_STRING:
  32. printf("%s\n", LVSemanticData_GetString(hsi));
  33. break;
  34.  
  35. case SI_TYPE_OBJECT:
  36. n = LVSemanticObject_GetNumberOfProperties(hsi);
  37.  
  38. for (i = 0; i < n; i++)
  39. {
  40. property_name = LVSemanticObject_GetPropertyName(hsi, i)
  41. data = LVSemanticObject_GetPropertyValue(hsi,property_name);
  42.  
  43. printf("<%s>\n", property_name);
  44.  
  45. PrintDataXML(data);
  46.  
  47. printf("</%s>\n", property_name);
  48. }
  49. break;
  50.  
  51. case SI_TYPE_ARRAY:
  52. n = LVSemanticArray_GetSize(hsi);
  53.  
  54. for (i = 0; i < n; i++)
  55. {
  56. data = LVSemanticArray_GetElement(hsi,i);
  57.  
  58. printf("<item>\n");
  59. PrintDataXML(data);
  60. printf("</item>\n");
  61. }
  62. break;
  63. }
  64. }

Result

<small_number_and_text>
<number>406</number>
<text>four hundred and six</text> </small_number_and_text>

Once you have examined the results and no longer need to perform decodes on a port, you should unload all your local grammars and close that speech port.

See Also

© 2012 LumenVox LLC. All rights reserved.