SpeechRecognizer GetPropertyNumber method

Microsoft Speech SDK

Intelligent Interface Technologies Home Page Microsoft Speech SDK

Speech Automation 5.1

Interface: ISpeechRecognizer
Type: Hidden

GetPropertyNumber Method


The GetPropertyNumber method returns a numeric value specified by the named key.

The speech recognition (SR) engine maintains several changeable values for setting the characteristics of the SR process. These controls, or properties, are listed in pairs with the control name and an associated value. For example, the SAPI 5 SR engine defines a property allocating CPU usage for the SR engine. This property is named ResourceUsage, and has a range of 0 to 100 percent. The default value is 50. This number is the percentage of the CPU time allocated for SR processing. This value may be changed to increase or decrease the processing time for SR features.

To get the current value, call ISpeechRecognizer.GetPropertyNumber. To set a new value, call ISpeechRecognizer.SetPropertyNumber. In addition, a PropertyNumberChange event is sent after the change is made. This event is broadcast to all applications set to receive it. Since multiple applications, or even recognition contexts within the same application can use the same SR engine, the applications may need to react to the new settings appropriately. Applications should restrict making changes unless there is a compelling reason. Changes to the engine properties will take effect at the next synchronization point. The changes persist in the engine until properties are changed again.

Persisting the changes on a permanent basis is an engine design issue. There is no requirement to do so and each engine manufacturer may implement changing characteristics differently. See the manufacturer's engine documentation for specific details. The SAPI 5 engine changes are not permanent beyond the life span of the recognizer object. That is, when all the applications using the same recognizer object (essentially an SR engine) quit, the values will return to the default state.

If properties need to be changed in a SAPI 5 engine, use Speech properties in Control Panel. For instance, the AdaptationOn property controlling background and continuous adaptation of speech recognition is the same property as Background Adaptation in Settings for the Recognition Profile on the Speech Recognition tab.

Properties are not required of SR engines and each manufacturer's engine may be different. Consult the manufacturer's documentation for specific information.


SpeechRecognizer.GetPropertyNumber(
     Name As String,
     Value As Long
) As Boolean

Parameters

Name
Specifies the string name of the property.
Value
Specifies the value associated with the property Name. This value is passed back upon successful completion of the call. If the return value is False, Value will not be updated.

Return Value

A Boolean variable of True if the property is supported, or False if not supported.


Remarks

For a complete list of SAPI 5 supported properties, see the SAPI 5 SR Properties White Paper.

Example

The following Visual Basic form code demonstrates the use of the SetPropertyNumber, GetPropertyNumber, and PropertyNumberChange event. The application displays the current value of the property, in this case ResourceUsage in a label. The first button displays the current value. The second button increments the value by one. The new value displays as a result of the PropertyNumberChange event. The original or starting value will be the same as the Accuracy vs. Recognition Response Time slider in the Recognition Profile Settings. This is set on the SR tab of Speech properties in Control Panel.

To run this code, create a form with the following controls:

  • Two command buttons called Command1 and Command2
  • Two labels called Label1 and Label2
  • Paste this code into the Declarations section of the form.

    The Form_Load procedure creates and activates a dictation grammar.

    Public WithEvents RC As SpSharedRecoContext
    Public myGrammar As ISpeechRecoGrammar
    Const THE_PROPERTY = "ResourceUsage"
    
    Private Sub Command1_Click()
        Dim lActualValue As Long
        Dim fSupported As Boolean
        
        Label2.Caption = ""
        fSupported = RC.Recognizer.GetPropertyNumber(THE_PROPERTY, lActualValue)
        Label1.Caption = lActualValue
    End Sub
    
    Private Sub Command2_Click()
        Dim lActualValue As Long
        Dim fSupported As Boolean
        
        Label1.Caption = ""
        fSupported = RC.Recognizer.GetPropertyNumber(THE_PROPERTY, lActualValue)
        fSupported = RC.Recognizer.SetPropertyNumber(THE_PROPERTY, lActualValue + 1)
    End Sub
    
    Private Sub Form_Load()
        Set RC = New SpSharedRecoContext
        
        Set myGrammar = RC.CreateGrammar
        myGrammar.DictationSetState SGDSActive
    End Sub
    
    Private Sub RC_PropertyNumberChange(ByVal StreamNumber As Long, ByVal StreamPosition As Variant, ByVal PropertyName As String, ByVal NewNumberValue As Long)
        Label2.Caption = NewNumberValue
    End Sub