SpeechRecognizer GetPropertyNumber method (SAPI 5.3)
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
- Specifies the string name of the property.
- 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.
A Boolean variable of True if the property is supported, or False if not supported.
For a complete list of SAPI 5 supported properties, see the SAPI 5 SR Properties White Paper.
The following Visual Basic form code demonstrates the use of the SetPropertyNumber method, GetPropertyNumber method, and PropertyNumberChange event.
To run this code, create a form with the following controls:
- Two command buttons called Command1 and Command2
Paste this code into the Declarations section of the form.
Clicking Command1 displays the current value of the property. The second button increments the value by one and the new value is displayed 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 in the Speech properties of Control Panel.
Option Explicit Const THE_PROPERTY = "ResourceUsage" Public WithEvents RC As SpSharedRecoContext Public myGrammar As ISpeechRecoGrammar Private Sub Command1_Click() On Error GoTo EH Dim lActualValue As Long Dim fSupported As Boolean Dim T As String fSupported = RC.Recognizer.GetPropertyNumber(THE_PROPERTY, lActualValue) T = "Property's current value: " & lActualValue MsgBox T, vbInformation EH: If Err.Number Then ShowErrMsg End Sub Private Sub Command2_Click() On Error GoTo EH Dim lActualValue As Long Dim fSupported As Boolean With RC.Recognizer fSupported = .GetPropertyNumber(THE_PROPERTY, lActualValue) fSupported = .SetPropertyNumber(THE_PROPERTY, lActualValue + 1) End With EH: If Err.Number Then ShowErrMsg End Sub Private Sub Form_Load() On Error GoTo EH Set RC = New SpSharedRecoContext Set myGrammar = RC.CreateGrammar myGrammar.DictationSetState SGDSActive EH: If Err.Number Then ShowErrMsg End Sub Private Sub RC_PropertyNumberChange _ (ByVal StreamNumber As Long, _ ByVal StreamPosition As Variant, _ ByVal PropertyName As String, _ ByVal NewNumberValue As Long) On Error GoTo EH MsgBox "Property's value has been incremented by 1.", vbInformation EH: If Err.Number Then ShowErrMsg End Sub Private Sub ShowErrMsg() ' Declare identifiers: Dim T As String T = "Desc: " & Err.Description & vbNewLine T = T & "Err #: " & Err.Number MsgBox T, vbExclamation, "Run-Time Error" End End Sub