This documentation is archived and is not being maintained.

SemanticValue Class

Represents the semantic organization of a recognized phrase.

Namespace: Microsoft.Speech.Recognition
Assembly: Microsoft.Speech (in microsoft.speech.dll)

The SemanticValue is a primary object implementing the Speech platform semantic technology. Semantic interpretation allows grammars to define, and recognition engines to correctly interpret, audio input but organized into more easily processable information, not just as words and sequences of words.

For example, the recognition engine output "Change background to red" would have to be parsed and interpreted by an application before it could be acted upon.

However, a Grammar object can specify an semantic interpretation to make processing clearer.

In the case of the phrase "Change background to red", the Grammar could specify that the phrase has two semantic substructures, one for selecting background or foreground (represented by the text "background"), the other for selecting color (represented by the text "red").

This semantic interpretation by the recognition engine is expressed in a tree of SemanticValue objects.

SemanticValue implements System.Collection.Generic.IDictionary, System.Collections.Generic.ICollection and System.Collections.Generic.IEnumerable interfaces.

Under Speech platform, the semantics of a recognition operation are represented in a tree of SemanticValue objects.

Each SemanticValue instance has

  • A System.Object type, accessed using the Value property, used to key the instance of the SemanticValue.

  • A measure of accuracy returned by the Confidence property

  • A collection name value pairs (System.Collections.Generic.KeyValuePair) of child objects, which are also SemanticValue instances. Child nodes are accessible through the SemanticValue implementation of System.Collection.Generic.IDictionary using with a string lookup key and a SemanticValue instance, for example:

    foreach (KeyValuePair<String, SemanticValue> child in semantics) {
       Utils.CreateSemanticsTreeNodes(semanticsNode.Nodes, child.Value, child.Key);

All Speech platform-based recognition engines output provide valid instances of SemanticValue for all recognized output, even phrases with no explicit semantic structure.

The SemanticValue instance for a phrase is obtained using the Semantics property on the RecognizedPhrase object (or objects which inherit from it, such as RecognitionResult).

SemanticValue objects obtained for recognized phrases without semantic structure are characterized by:

  • Having no children (Count is 0)

  • The Value property is null.

  • An artificial confidence level of 1.0 (returned by Confidence)

Typically, applications create instance of SemanticValue indirectly, adding them to Grammar objects by using SemanticResultValue, and SemanticResultKey instances in conjunction with, Choices and GrammarBuilder objects.

Direct construction of an SemanticValue is useful during the creation of strongly typed grammars.


The example below shows a handler for a SpeechRecognized event designed to handle commands to change foreground and background color.

Cases where phrases are recognized, but have no semantic structure, are identified by the handler by having Count of zero and a Value of null. This recognition output is then processed directly from the parsing the raw text.

In other cases, the handler obtains specific information about whether the command is to set the foreground or background color, and the RGB of official name of a color setting based on keys, or indicates that no valid key was found.

newGrammar.SpeechRecognized +=
    delegate(object sender, SpeechRecognizedEventArgs eventArgs) {
        // Retrieve the value of the semantic property.
        bool changeBackGround = true;
        string errorString = "";
        SemanticValue semantics = eventArgs.Result.Semantics;

        Color newColor = Color.Empty;

        try {
            if (semantics.Count == 0 && semantics.Value==null){
                //This signature of recognition by grammar with no semantic
                ////We have to parse the string. hope last word is color, search for background or forground in input
                if (eventArgs.Result.Text.Contains("foreground")) {
                    changeBackGround = false;
                string cName = eventArgs.Result.Words[eventArgs.Result.Words.Count - 1].Text;
                newColor = Color.FromName(cName);
            }else if (semantics.ContainsKey("colorStringList") ^ semantics.ContainsKey("colorRGBValueList")) {
                //Check background vs foreground

                if (semantics.ContainsKey("applyChgToBackground")) {
                    changeBackGround = semantics["applyChgToBackground"].Value is bool;

                //Get color value
                if (semantics.ContainsKey("colorStringList")) {
                    newColor = Color.FromName((string)semantics["colorStringList"].Value);
                if (semantics.ContainsKey("colorRGBValueList")) {
                    newColor = System.Drawing.Color.FromArgb((int)semantics["colorRGBValueList"].Value);
            } else {
                //we have a semantics that does not contain the keys we support, throw an exception.
                throw(new Exception("Unsupported semantics keys found."));

        } catch (Exception exp) {
            MessageBox.Show(String.Format("Unable to process color semantics.:\n{0}\n", exp.Message));
        //Change colors, either foreground or background.
        if (changeBackGround) {
            BackColor = newColor;
            float Bright = BackColor.GetBrightness();
            float Hue = BackColor.GetHue();
            float Sat = BackColor.GetSaturation();
            //Make sure the text is readable regardless of background.
            if (BackColor.GetBrightness() <= .50) {
                ForeColor = Color.White;
            } else {
                ForeColor = Color.Black;
        } else {
            ForeColor = newColor;
            float Bright = ForeColor.GetBrightness();
            float Hue = ForeColor.GetHue();
            float Sat = ForeColor.GetSaturation();
            //Make sure the text is readable regardless of Foreground.
            if (ForeColor.GetBrightness() <= .50) {
                BackColor = Color.White;
            } else {
                BackColor = Color.Black;

All public static (Shared in Visual Basic) members of this type are thread-safe. Instance members are not guaranteed to be thread-safe.

Development Platforms

Windows XP Professional with Service Pack 2 (SP2), Windows Server 2003, Windows Vista Ultimate Edition, Windows Vista Business Edition, Windows Vista Enterprise Edition

Target Platforms