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 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