overview - perturbed-koala.co.uk ref - wsrm - languag… · web viewfor example, you could type...
TRANSCRIPT
Table of Contents
Overview3System Requirements3Getting Started with WSR Macros4Installation and Running WSR Macros4Creating a Speech Macro4Feedback and More Information5
Speech Macros Command Set666
Conditions789101112
Rule Generators131416171819202122
Executors2324262627282930313233343536373838393940414243Semantic Properties44A single semantic property44Multiple Semantic Properties45Using the Same Rule and the Same Property name multiple times.46Using different Rules and different Property names.47Script Object Model49Application object50Properties54ChooseFromList object55Command object56
Windows Speech Recognition MacrosVersion 1 Release Notes
January 2009
Overview
The Windows Speech Recognition Macros tool or WSR Macros for short extends the usefulness of the speech recognition capabilities in Windows Vista. Users can create powerful macros that are triggered by spoken commands. These macros can perform a variety of tasks ranging from simply inserting your mailing address to having full speech-control over your windows media player library.
For documentation, tutorials, sample macros, or more information please visit the WSR Macros Code Gallery and Wiki:http://code.msdn.microsoft.com/wsrmacros
System Requirements
Windows Speech Recognition Macros requires the following:
1. A computer running a genuine copy of Windows Vista (x86 or x64)
0. Currently, only English-language editions of Windows are supported.
1. A microphone.
We recommend the following in addition:
1. A minimum of 1GB of memory is recommended.
1. Completing the Microphone Wizard and the Windows Speech Recognition tutorial before using WSR Macros. This will ensure that your microphone is properly set-up and help the speech engine become adapted to your voice.
1. Speakers or headset for sound and voice output.
1. Speech recognition works best when the computer can hear you clearly. We recommend high-quality microphones for best results.
The use of Bluetooth microphones is not recommended since they do not support high enough quality audio for speech recognition to work optimally.
Getting Started with WSR MacrosInstallation and Running WSR Macros
1. Install WSR Macros from the setup file.
1. After installation, WSR Macros can be invoked by clicking Start Menu -> All Programs -> Windows Speech Recognition Macros.
1. When loaded, the WSR Macros icon is placed in the taskbar notification area, close to where the time and system alerts are shown.
When you load WSR Macros, the Windows Speech Recognition application also loads. If you have not used Windows Speech Recognition before, you will be prompted to complete the Microphone Setup Wizard, the Speech Tutorial and a few other questions regarding the configuration of Windows Speech Recognition.
If you are unfamiliar with Windows Speech Recognition, please refer to the following resources:
Help and Support
Start Help and Support from the Start menu and type Speech Recognition into the search box and press Enter.
Step-by-Step guide
http://msdn2.microsoft.com/en-us/library/bb530325.aspx
Demonstration Video
http://www.microsoft.com/enable/demos/windowsvista/speechdemo.aspx
Creating a Speech Macro
For this example, we will create a simple yet useful macro that will insert your mailing address into the current application whenever you say my mailing address.
1. Double-click on the WSR Macros icon to display the menu and choose New Speech Macro
1. The Speech Macro Wizard will appear with four choices. Choose the first one Insert Text
1. Type or speak my mailing address
1. Press the Tab key or say Tab to move to the next field
1. Type or speak the text you would like to appear. For example, you could type 555 Main St., Buffalo, NY 98052, pressing Enter to separate the lines as you choose
1. When finished, press or say Next
1. The wizard will confirm your choices and prompt for a filename to save the speech macro.
Note that in order for WSR Macros to load the macro, the macro must be saved in the Speech Macros folder, under the current user's Documents folder
1. Press or say Create to complete the wizard and save the new macro file.
By default, the wizard will apply a digital signature to the newly created macro file. A digital signature ensures that the file cannot be changed or tampered with, without the user applying a new signature. You will be prompted to create a new default signing certificate if one has not yet been created. Creating a signing certificate requires administrative access and you may be prompted to provide credentials as part of the process.
Feedback and More Information
For sample macros, documentation, and community support for WSR Macros, please visit our Code Gallery and Wiki site:
http://code.msdn.microsoft.com/wsrmacros
In addition, the following web sites can offer more information about WSR Macros:
Microsoft Speech http://www.microsoft.com/speech/Speech @ Microsoft Bloghttp://blogs.msdn.com/speech/Rob's Rhapsodyhttp://blogs.msdn.com/robch/Speech API Bloghttp://blogs.msdn.com/chuckop/
Please send questions and feedback regarding WSR Macros to [email protected].
Speech Macros Command Set
The Speech Macros Command Set is an XML set that defines Speech Macros files.
The element is the outermost XML element and it initializes a Speech Macro file.
The following example shows how to initialize a Speech Macro using the element:
My Address
One Microsoft Way Redmond WA
The element is the container that holds conditions, rule generators and executors.
One or more elements
The element must contain one or more elements.
The following example contains two tags:
My Work Address
One Microsoft Way Redmond WA
My Home Address
Seattle WA
Conditions
Conditions specify when a particular rule should be recognized. When a condition is true then the computer should listen for the command phrases specified by the rule generators. When a condition is false then the computer should disable the command phrases specified by rule generators.
Zero Conditions
If there are zero conditions the command is enabled at all times.
One Condition
If a command has one condition, that condition must be satisfied for the command to be enabled.
More than one Condition
If a command has more than one conditions, all of the conditions must be satisfied for the command to be enabled.
Global Conditions
Conditions are normally contained inside . However if the same condition will be used in different commands set, the condition can be a child of and is then considered a global condition.
List of Conditions
appIsInForeground appIsRunning stateIsSet condition scriptCondition
The condition checks if a specific application is the foreground window.If the application is the foreground window the condition holds true otherwise the condition is false.
Attributes:Note: processName, WindowTitle or WindowTitleContains are optional attributes of . However at least one must be specified.
processName. (optional)The pocessName attribute of the condition specifies the process name of the application that is being checked.
The following example checks if NOTEPAD.EXE is the foreground window:
windowTitleContains. (optional)The windowTitleContains attribute of the condition specifies a substring of text in the window title of the application that is being checked.
The following example checks if the window title of the foreground application contains the substring "Notepad":
windowTitle. (optional)The windowTitle attribute of the condition specifies the exact text of the window title of the application that is being checked.
The following example checks if "NOTEPAD.EXE" is the foreground window and that it has a dialog box with the exact title "Font":
The condition checks if a specific application is running.If the application is running the condition holds true, otherwise the condition is false.
Attributes:Note: processName, WindowTitle or WindowTitleContains are optional attributes of . However at least one must be specified.
processName. (optional)The pocessName attribute of the condition specifies the process' name of the application that is being checked.
The following example checks if NOTEPAD.EXE is running:
windowTitleContains. (optional)The windowTitleContains attribute of the condition specifies a substring of text in the window title of the application that is being checked.
The following example checks if the title of an application running contains the substring Notepad:
windowTitle. (optional)The windowTitle attribute of the condition specifies the exact text of the window title of the application that is being checked.
The following example checks if a Notepad window with the title "test - Notepad" is running:
The condition checks if there is a state with a specific name. It also checks for the value of the state (optional). If there is a state with the specific name and no value was specified in the condition, the condition holds true otherwise the condition is false.If there is a state with the specific name and the state value specified matches the states value the condition holds true otherwise the condition is false.
Attributes:
name (required)The name attribute of the condition specifies the name of the state that is being checked for existence or for a matching value.
value (optional)The value attribute of the condition specifies the value of the state that is being checked.
The following example demonstrates the condition:
Good morning computer
Good morning
Good night computer
Good night
what are you drinking
a glass of milk
what are you eating
rice and beans
The first listens for "good morning computer", once it is recognized the engine speaks back "Good Morning". It then names a state "aConversation" with the value of "morning". After that it waits for five seconds and removes the named state. The second does something similar, it listens for "good night computer" and once it is recognized the engine speaks back "Good Night". It then names a state "aConversation" with the value of "night". After that it waits for five second and removes the named state. The third checks if the named state "aConversation" has the value of "morning". If true then and only then will it listen to "what are you drinking".The fourth checks if the named state "aConversation" has the value of "night". If true then and only then will it listen to "what are you eating". The third and fourth elements will never execute unless condition becomes true.
The condition groups other conditions into logical expressions using the logical operators AND, OR, and NOT.
Attributes:name (optional)The name attribute of the condition names the condition so it can be referenced from other scripts/commands.
operator (required) The operator attribute of the condition specifies the logical operator that will be applied to the contained conditions. Values:ANDAll of the conditions contained must be true.
The following example utilizes the AND operator for the condition. Both Notepad and Wordpad need to be running for the condition to be true:
Can I write
Yes
ORAt least one of the conditions contained must be true.
The following example utilizes an OR operator for the condition. If either Notepad or Wordpad is running the condition holds true:
Can I write
Yes
NOTAll of the conditions contained must be false for the overall condition to be true.
The following example utilizes the NOT operator for the condition. If both Notepad and Wordpad are not running the condition holds true:
Open a text editor
open Notepad
The condition allows scripts to programmatically determine if the condition is met or not. The script is provided with the condition object model which the script can use to indicate wheter the condition is met or not.
Attributes:
name (optional)The name attribute of the condition names the condition so it can be referenced from other scripts/commnads.
language (required)The language attribute of the condition indicates in what language the script is written in.Values: "VBScript", "JScript"
Object Models available for : ConditionNamedStatesApplicationDebug (link them latter to their respective page)
The following example demonstrates how the is used to make a rule active only on Monday:
Condition.Satisfied = ((new Date()).getDay() == 1);
Open email
Ok, opening email on monday
Open Microsoft Outlook
Rule Generators
A rule generator defines what the computer should listen for to execute speech macros commands.
Zero Rule Generators
There must be at least one rule generator inside each command. The entire command set will be rejected if any command contains no rule generators.
One Rule Generator
There must be at least one rule generator inside each command.
More than one Rule Generator
If there is more than one rule generator inside each command, the computer will listen for any of the phrase specified by the rule generators.
In the following example the computer would listen for "I want to draw" or "I want to paint" to run Microsoft paint:
listenForI want to draw
listenForI want to paint
Global Rule Generators
Rule Generators can be children of the node. These are Global Rule Generators and can be referenced by other rule generators from the command set.
In the following example two commands reference a global rule generator that has a list of names:
listenForSay hello to [person]
Hello {[person]}
listenForSay goodbye to [person]
Goodbye {[person]}
Rob
Alex
Ana
Travis
Laura
Rule generators can have names (optional)
Rule generators can have names. Every Rule Generator name must be unique among all other Rule Generator and Command names.
List of Rule Generators
listenFor listenForList rule numbers fontNames fileNames ruleScript wmpMediaItems
The rule generator creates a phrase for the speech recognizer to listen for.
In the following example the rule generator creates the phrase "Play solitaire":
Play solitaire
Attributes:
name (optional)
The name attribute of the rule generator specifies the name of the rule generator.
Text between the tags:- If the text between the tags is plain text it will be converted to a SAPI 5 based rule.- If the text between the tags is within brackets ("[" and "]") it is used as a rule reference.
Rule References:
For more information about rule references visit the semantic properties section by clicking here .
- When the Rule name is equal to the Semantic Property name:If the name contained within brackets ("[" and "]") does not contain a period (".") the rule name and the semantic property name will be the same. For example if the text within the brackets is "[number]" both the rule reference name and the semantic property name will be number.
- When the Rule name is part of the Semantic Property name: If the name contained within brackets ("[" and "]") does contain a period (".") the rule name will be the value after the period and the semantic property name will be the entire value. For example if the text within the brackets is "[add.number]" the rule reference name will be number and the semantic property name will be add.number.
Built-in Rules In Windows Vista, the Speech User Experience keeps a set of rules to enhance command and control as well as text services. These rules are exported and available to the Speech Macro runtime on Windows Vista
textInDocument built-in rule The textInDocument built in rule refers to a word or a set of ordered words that exist in an active text document window.
In the following example if Notepad is the foreground application any text contained in the document is exported as a rule so you can chose any string of ordered words and add quotes around them:
Put [textInDocument] in quotes
Select {[textInDocument]}
^x"^v"
startableApplicationNames built-in ruleThe startableApplicationNames built-in rule refers to the names of the applications that can be started via the Start menu or desktop.
The following example shows how to redefine a phrase ("How about bringing up [application]) to start an application:
How about bringing up [startableApplicationNames]
Start {[startableApplicationNames]}
itemOnScreen built-in rule The itemOnScreen built-in rule contains a list of all the named controls in the current application. If, for example, Notepad is the foreground application itemOnScreen would contain all of the "Menu Headings" (File, Edit, Format, etc) as well as "Close", "Minimize",etc
The following example allows you to choose any control, for example if you have Notepad open you can say "Choose Format":
choose [itemOnScreen]
click {[itemOnScreen]}
runningApplicationNames built-in ruleThe runningApplicationNames built-in rule contains a list of all of the applications currently running on the system.
The following example copies selected text into an instance of Notepad already running on the system.
Copy that into [runningApplicationNames]
^c
switch to {[runningApplicationNames]}
^v
The rule generator generates a list of phrases for the speech recognizer to listen for.
Attributes:
name
The name attribute of the rule generator specifies the name of the rule. This attribute is optional when the rule generator is contained within a command. This attribute is required when the is a global rule generator.
propname
The propname attribute of the rule generator specifies the property that will be generated from the contained items. This attribute is optional if no contained tags specify a property value. This attribute is required if any contained tags specify a property value.
useSubset
The useSubset attribute of the rule generator indicates that an ordered subset of a phrase may be used to trigger the rule. Not all of the words in the phrase need to be spoken, but the words must be in the same order as they appear in the rule item.
In the following example speaking "I want to draw in Paint", "I want to draw", "draw in paint" open the paint application (note, these words must be in the same order as they appear in the rule, "paint draw" would not open the application)
I want to draw in Paint
Ok
open paint
Contained tags
The rule generator contains tags and these define individual phrases that the recognizer should listen for. The propval attribute specifies the value of the semantic property that will be generated for this item if its recognized.
The following example shows you how to use to send email to a specific person's email address using a global rule generator:
Send email to [person]
Sending email to {[person]}
John
Travis
Kris
The rule generator is used to wrap a SAPI 5 XML rule as defined by the SAPI SDK.
Attributes:
name
The name attribute of the rule generator specifies the name of the rule. This attribute is optional when the rule generator is contained within a command. This attribute is required when the is a global rule generator.
The following example shows how to send an email using the rule generator:
Send email to [Contact]
Lou
Oliver
Laura
The rule generator is used to generate phrases for a sequence of numbers.
Attributes:
name
The name attribute of the rule generator specifies the name of the rule. This attribute is optional when the rule generator is contained within a command. This attribute is required when the is a global rule generator.
propname
The propname attribute of the rule generator specifies the name of the property that will be generated for the spoken number. If propname is not specified it defaults to "number".
start
The start attribute of the rule generator specifies the number to start with. If this attribute is not specified it defaults to 0 (zero).
stop
The stop attribute of the rule generator specifies the number to stop with. If this attribute is not specified it defaults to 100 (one hundred).
Note: Please choose a sensible range between the start and stop attribute values. Having a very large range may significantly slow down WSRMacros.
The following example shows how to scroll down on a browser by saying "Look down [ a number between 1 - 20 ] times":
Look down [times] times
scroll down {[times]}
The rule generator is used to generate a set of phrases for all the fonts installed on the system.
Attributes:
name
The name attribute of the rule generator specifies the name of the rule. This attribute is optional when the rule generator is contained within a command. This attribute is required when the is a global rule generator.
In the following example the global rule generator generates a list of all the installed fonts so they can be easily changed in Notepad:
Change the font to [fontName]
%o
f
%f
{[fontName]}
{ENTER}
The rule generator is used to generate a set of phrases for all the files in a specified directory. (Hidden and/or system files will not be included)
Attributes:
name
The name attribute of the rule generator specifies the name of the rule. This attribute is optional when the rule generator is contained within a command. This attribute is required when the is a global rule generator.
propname (optional)
The propname attribute of the rule generator specifies the fully qualified name for the file.
directory (required)
The directory attribute of the rule generator specifies the name of the directory that should be inspected for filenames. If the directory does not exist the rule generator will not generate any phrases. Note: Ensure that the directory specified in this attribute is present in your computer. If the directory specified by this attribute does not exist in your computer, the Speech Macro will fail to load.
includeSubdirectories (optional)
The includeSubdirectories attribute of the rule generator specifies wheter or not subdirectories should be inspected.
useSubset (optional)
The useSubset attribute of the rule generator indicates that an ordered subset of a phrase may be used to trigger the rule. Not all of the words in the phrase need to be spoken, but the words must be in the same order as they appear in the rule item.
The following example allows the user to open any document in the folder "C:\publicFiles" by saying "Open" followed by the name of any file inside the folder:
Open [publicFiles]
Opening {[publicFiles.fileName]}
Note: Make sure that the directory attribute specifies a folder that exists in your computer. If publicFiles is not present in your computer, this example will fail to load.
The rule generator allows to generate a rule from a scripting environment.
Attributes:
name
The name attribute of the rule generator specifies the name of the rule. This attribute is optional when the rule generator is contained within a command. This attribute is required when the is a global rule generator.
language (required)
The language attribute of the rule generator specifies the scripting language in which the script is written. This can be "VBScript" or "JScript"
propname
The propname attribute of the rule generator specifies the property that will be generated from the contained items. This attribute is optional when the rule generator is contained within a command. This attribute is required when the is a global rule generator.
Object Models:
The rule generator is provided with the following object models: - Rule - CommandSet - NamedStates - Application- Debug
The following example uses to generate email contacts using Jscript:
Send email to [Contact]
Rule.Items.AddItem("Alex","[email protected]",true);
Rule.Items.AddItem("Paco","[email protected]",true);
Rule.Items.AddItem("Maria","[email protected]",true);
Rule.Commit();
]]>
The rule generator generates a rule containing musical items from the Windows Media Player's Library.
Attributes:
name
The name attribute of the rule generator specifies the name of the rule. This attribute is optional when the rule generator is contained within a command. This attribute is required when the is a global rule generator.
propname
The propname attribute of the rule generator specifies the name of the property that will be generated from the contained items.
propvalue
The propvalue attribute of the rule generator contain any valid WMP attribute value enclosed in brackets. Valid values are defined in the WMP SDK attribute reference
attrname
The attrname attribute of the rule generator specifies the attribute name that will be used to play music in Windows Media Player. Valid values are defined in the WMP SDK attribute reference
attrvalue (optional)
The attrvalue attribute of the rule generator specifies the attribute value that will be used t o filter the set of music items in the Windows Media Player by their attrname.
listenFor (optional)
The listenFor attribute of the rule generator specifies what should be listened for; it defaults to name.
useSubset (optional)
The useSubset attribute of the rule generator indicates that an ordered subset of a phrase may be used to trigger the rule. Not all of the words in the phrase need to be spoken, but the words must be in the same order as they appear in the rule item.
In the following example rule generator is used to generate a rule containing all the known artists in the Windows Media Player Library:
Play ?the ?artist [Artists]
Executors
An executor specifies the action a computer should take once a spoken phrase matches a rule generator.
Zero Executors
It is not valid for a to have zero executors.
One Executor
There must be at least one executor inside a . Once a spoken command matches a phrase from a rule generator the executor executes.
More than One Executor
If multiple executors are within a they will execute in order, synchronously, once a spoken command matches a phrase from a rule generator.
List of Executors
sendKeys insertText run emulateRecognition waitFor speak alert confirm setTextFeedback script wmpMediaPlay wmpMediaControl sendMessages setState switchToApp minimizeApp maximizeApp restoreApp closeApp prompt mouse disambiguate
The executor sends keyboard keys to the application running in the foreground. The following example allows you to copy a string of text "CTRL+C" and pastes it "CTRL+V" into WordPad:
Copy that into wordpad
^c
^v
Attributes:
times (optional)
The times attribute of the executor specifies the number of times the keys should be sent to the application. It defaults to 1 and maximum is 20.
Text between executor:
The text contained within executor specify the keys to send to the foreground application. Click http://msdn.microsoft.com/en-us/library/system.windows.forms.sendkeys.aspx for a list of the standard definition of keys per the Windows Platform. New Keys for WSR Macros:
Key text
Key definition
{WIN}
Windows Key
{LWIN}
Left Windows Key
{RWIN}
Right Windows Key
{MENU}
Menu Key
{CTRL}
Control Key
{LCTRL}
Left Control Key
{RCTRL}
Right Control Key
{CAPSLOCK+}
Puts CAPSLOCK in the "ON" state
{CAPSLOCK-}
Puts CAPSLOCK in the "OFF" state
{NUMLOCK+}
Puts NUMLOCK in the "ON" state
{NUMLOCK-}
Puts NUMLOCK in the "OFF" state
{SCROLLLOCK+}
Puts SCROLLLOCK in the "ON" state
{SCROLLLOCK-}
Puts SCROLLLOCK in the "OFF" state
{NUM0} - {NUM9}
Number pad 0 - Number pad 9
{NUM*}
Number pad *
{NUM/}
Number pad /
{NUM+}
Number pad +
{NUM-}
Number pad -
{NUM~}
Number pad ENTER
{n WAIT}
Wait for n milliseconds before sending next key
Modifiers
In addition to the standard modifiers "+" (Shift) "%" (ALT) and "^" (Control) any key can be used as a modifier key by enclosing it in curly {} braces. For example: {LALT}g - hold and releases Left ALT then hold and release the "g" key. LALTg - presses and holds Left ALT, presses "g" then it releases Left ALT and "g" keys.
Any key may be used this way. {a} presses and releases the "a" key.
Virtual Keys
To send a virtual key use {VK n} where the n is the scancode in decimal of the key to send. To use a hex value prefix t he number with a "#" sign.For example: To send VK_BROWSER_HOME - {VK 172} or {VK #AC}
Unicode Characters
To send a Unicode character use {U+nnnn} where nnnn is a four digit hex number identifying the Unicode character to send. For example: (theta) - {U+03F4}
Invalid Key Combinations
The following list include the keys or key combinations that are not allowed due to the limitations of the API: - WIN+L - Log off Windows. - PRTSCR - Print Screen. Note: To use Print Screen you can emulate the phrase "Print Screen". Please refer to the executor. - CTRL+WIN+F- Find Computer. Note: In WSR Macros any combination that includes CTRL+WIN results in turning the Speech Recognition off.-CTRL+WIN+TAB-Move focus from Start, to the Quick Launch toolbar, to the System tray. Note: In WSR Macros any combination that includes CTRL+WIN results in turning the Speech Recognition off.
IMPORTANT: The keys between double braces -{{key}}- are important and are called modifiers. As a rule, they will always be higher in precedence than all the other keys. The keys enclosed in single braces -{key}- are called non-modifiers. The rest of the keys are considered normal keys (letters or numbers) and don't need braces.
The keys that are mainly used for double or single braces are Ctrl, Alt, Shift, F1 to F9 , TAB, ESC etc. Normal keys such as a letters or numbers, won't have any set of braces and they will be last in the sequence. A modifier is a key that is pressed, awaits for another key to be pressed and then they are both released. This is used when using combinations such as {{CTRL}} C (copy), {{CTRL}} V (paste), {{CTRL}}{{SHIFT}}{ESC}. The keys that are enclosed in single braces are those that aren't apart of simple numbers and letters and are also not pressed and kept pressed awaiting for another key.
It is important to keep the braces precedence to have a macro working properly. The order is {{all modifiers}} {all non-modifiers} normal keys . To better understand this, it is correct to use {{CTRL}}{{SHIFT}}{ESC} (notice that there is no modifier after the non-modifier), but incorrect to use {ESC}{{CTRL}}{{SHIFT}} or {{CTRL}}{ESC}{{SHIFT}}. The modifiers -{{keys}}- must always be put first.
When creating this type of macros be careful to the numbers of braces used for modifiers and non-modifiers keys and the order in which you write them. If there is one little mistake, the macros won't function correctly and you will get an error message similar to the one below.
The executor inserts text into the foreground application.
Text between executor:The text contained within the executor specifies what text to send to the foreground application. The following example inserts the address "One Microsoft Way Redmond Washignton":
Insert my address
One Microsoft Way Redmond Washington
The executor starts a new application.
Attributes:
command (required)
The command attribute specifies what program to run.
params (optional)
The params attribute specifies the command line parameters to pass to the application.
directory (optional)
The directory attribute specifies what the current directory should be when running the application.
In the following example the executor is used to open an internet explorer window with www.live.com as its default page:
Search the Internet
The executor simulates speech recognition.
Attributes:
waitForDisambiguation (optional)
The waitForDisambiguation attribute specifies the amount of time to wait for the speech recognition command to be disambiguated. Default value is 0 where the recognizer wont wait for disambiguation.
If a value is specified, the executor will ensure that if disambiguation is necessary, the user will be given an amount of time to respond to the disambiguation prompt as specified in this attribute.
Text between executor:The text contained within the executor specifies the text of voice command to be emulated by the speech recognition engine.
Note: Emulate recognition does not validate the correction of the text between the tags therefore invalid characterers, extra white spaces and mispelled words may corrupt its execution and it may fail silently.
In the following example allows to copy the screen into paint:
Copy the screen into paint
Press print screen
^v
The executor waits for a specified amount of time.
Attributes:
seconds (required)
The seconds attribute specifies how long in seconds the executor should wait before continuing. (The value can be specified as a floating point value)
anyStateNameIsSet (optional not allowed in conjuntion with allStateNamesAreSet)
The anyStateNameIsSet attribute specifies to wait until any of the named states are set to a value. The list of state names is separated by the vertical bar character "|". Example:
allStateNamesAreSet (optional not allowed in conjunction with anyStateNameIsSet)
The allStateNamesAreSet attribute specifies to wait until all of the named states are set to a value. The list of state names is separated by the vertical bar character "|". Example:
The following example uses the executor to wait for WordPad to load:
Open my text editor with font menu
%o
f
The executor uses a TTS (Text To Speech) voice to speak back to the user.
Attributes:
speakFlags (optional)
The speakFlags attribute of the executor allows to specify the SPEAKFLAGS value passed to the TTS engine. It defaults to SPF_IS_NOT_XML(16).For more information about SPEAKFLAGS go to http://msdn.microsoft.com/en-us/library/ms717252(VS.85).aspx
The following example the computer greets back at the user:
Hello computer
Hello user
The executor is used to inform the user using a dialog box. This dialog box only contains an OK button.
Attributes:
title(optional)
The title attribute of the executor specifies the title of the dialog box.
timeout(optional)
The timeout attribute of the executor specifies how long in seconds will the dialog box be displayed. Defaults to INFINITE.
Text between executorThe text between the tags specifies the message that will be displayes in the dialog box.
Send email to [person]
Sending email to {[person]}
What's [person] email address
{[person]}'s email address is: {[person.email]}
John
Kris
Travis
The executor provides the user with a dialog box to decide if execution should continue. The dialog box will contain "Yes" and "No" buttons.
Attributes:
title(optional)
The title attribute of the executor specifies the title of the dialog box.
timeout(optional)
The timeout attribute of the executor specifies how long in seconds will the dialog box be displayed. Defaults to INFINITE.
Text between executor:The text between the tags specifies the message that will be displayed in the dialog box.
Send an email to [person]
Are you sure you want to send an email to {[person]}?
Sending email to {[person]}
John
Kris
Travis
The executor is used to set text on the feedback pane in the Speech UI.
Attributes:
style(optional)
The style attribute of the executor specifies if the text on the feedback pane should be displayed normally or as a warning. Valid values are "normal" and "warning". It defaults to "normal".
speak(optional)
The speak attribute of the executor specifies if the text on the feedback pane should also be spoken in addition to be displayed. Valid values are "true" and "false". It defaults to "false".
Search the internet
Opening Internet Explorer and Live.com
The executor is used to execute script code in the macro framework.
Attributes:
language (required)
The language attribute of the executor specifies the scripting language of the script. Valid values are "VBScript" or "JScript".
The following example shows you how to use VBScript to perform actions using the executor:
Can you count to ten
Application.Speak("Yes I can")
For count = 1 to 10
Application.Speak(count)
Next
The executor is used to play music in Windows Media Player.
Attributes:
attrname (required)
The attrname attribute of the specifies the attribute name that will be used to play music in Windows Media Player.
Common values for the attrname attribute are: NameArtistWM/AlbumArtistTitleWM/AlbumTitleGenreWM/GenreWM/TrackNumber
attrvalue
The attrvalue attribute of the specifies the attribute value that will be used to play music in Windows Media Player.
The following example allows you to play music in Windows Media Player by artist name:
Play ?the ?artist [Artists]
The executor is used to control Windows Media Player in a variety of ways, play, pause, stop, etc.
Attributes:
command (required)
The command attribute of the executor specifies the command to execute on Windows Media Player. Valid values are: playpausestopnextpreviousloop_onloop_offloop_toggleshuffle_onshuffle_offshuffle_toggle
times (optional)
The times attribute of the executor specifies the number of times the command will be sent to Windows Media Player. Default is 1.
The following example allows you to play the next track in your Windows Media Player list by saying "next track":
Next track
Playing the next track
The executor provides limited means to send Windows messages to applications.
Attributes:
windowName (required)
The windowName attribute of the specifies the name of the target window.
className (required)
The className attribute of the executor specifies the class name of the target window.
message (required)
The message attribute of the executor specifies the message number to send to the target window.
wParam (optional)
The wParam attribute of the executor specifies the wParam argument of the message sent.
lParam (optional)
The lParam attribute of the executor specifies the lParam argument of the message sent.
Text between executor:The text within tags only works in conjunction with a WM_COPYDATA message. It specifies a block of text to be sent as the lpData part of the COPYDATASTRUCT structure associated with this message.
Turn speech recognition off
The executor is used to set a named state to a specific value.
Attributes:
name (required)
The name attribute of the executor specifies the state's name that will be set.
value (optional)
The value attribute of the executor specifies the value the state will be set to.
An example that demonstrates how to set several states using setState (for a complete explanation on this macro go to Condition):
Good morning computer
Good morning
Good night computer
Good night
what are you drinking
a glass of milk
what are you eating
rice and beans
The executor is used to switch to a specified application.
Note. Currently this executor does not disambiguate if more than one application matches the search.
Attributes:
windowTitle
The windowTitle attribute of the executor specifies the exact title of the window to switch to.
windowTitleContains
The windowTitleContains attribute of the executor specifies a subset of the title of the window to switch to.
Only one of these attributes must be specified. They cannot be used in conjunction.
The following example shifts focus to Notepad:
Switch to my favorite application
The executor is used to minimize a specified application.
Note. Currently this executor does not disambiguate if more than one application matches the search.
Attributes:
windowTitle
The windowTitle attribute of the executor specifies the exact title of the window to minimize.
windowTitleContains
The windowTitleContains attribute of the executor specifies a subset of the title of the window to minimize.
Only one of these attributes must be specified. They cannot be used in conjunction.
The following example minimizes Notepad if opened:
Minimize my favorite application
The executor is used to maximize a specified application.
Note. Currently this executor does not disambiguate if more than one application matches the search.
Attributes:
windowTitle
The windowTitle attribute of the executor specifies the exact title of the window to maximize.
windowTitleContains
The windowTitleContains attribute of the executor specifies a subset of the title of the window to maximize.
Only one of these attributes must be specified. They cannot be used in conjunction.
The following example maximizes an instance of Notepad:
Maximize my favorite application
The executor is used to restore a specified application.
Note. Currently this executor does not disambiguate if more than one application matches the search.
Attributes:
windowTitle
The windowTitle attribute of the executor specifies the exact title of the window to restore.
windowTitleContains
The windowTitleContains attribute of the executor specifies a subset of the title of the window to restore.
Only one of these attributes must be specified. They cannot be used in conjunction.
The following example restores Notepad if opened:
Restore my favorite application
The executor is used to close a specified application.
Note. Currently this executor does not disambiguate if more than one application matches the search.
Attributes:
windowTitle
The windowTitle attribute of the executor specifies the exact title of the window to close.
windowTitleContains
The windowTitleContains attribute of the executor specifies a subset of the title of the window to close.
Only one of these attributes must be specified. They cannot be used in conjunction.
The following examples closes Notepad if opened:
Close my favorite application
The executor prompts the user with a dialog box that contains manipulable text.
Attributes:
title (optional)
The title attribute of the executor specifies the title of the dialog box.
timeout (optional)
The timeout attribute of the executor specifies how long in seconds will the dialog box appear for. If the user do not respond to the timeout the command is canceled. The default value is INFINITE.
defaultValue (optional)
The defaultValue attribute of the executor specifies what the default value of the edit control should be. It defaults to an empty string.
resultState (required)
The resultState attribute of the executor specifies what state should be modified to contain the new value of the dialog box upon successful completion of the dialog.
Text between executor:The text within tags specifies the text prompted to the user in the dialog box.
The following example allows you to generate the subject line of a thank you email using the executor:
Send thank you email to [person]
Thank you greeting:
John
Kris
Travis
The executor manipulates the mouse pointer.
Attributes:
button (optional)
The button attribute of the executor specifies which button to press. Available values are "left","right", and "middle"; it defaults to "left".
command(required)
The command attribute of the executor specifies what action the mouse should perform. Values are "click", "dblclick" and "scroll".
modifierKeys(optional)
The modifierKeys attribute of the executor allows for using CTRL (^), ALT (%), and SHIFT (+) keys while manipulating the mouse pointer.
position (optional)
The position attribute of the executor indicates horizontal (x) and vertical (y) coordinates of where to locate the mouse cursor.
positionStyle (optional)
The positionStyle of the executor indicates the position style of the mouse pointer. If assigned to "absolute" the x and y coordinates are mapped to the computer's screen resolution. If assigned to "virtual" the coordinates are mapped to the "virtual" system in which the top left corner coordinates are 0,0; the middle of the screen coordinates are 32768,32768 and bottom right corner coordinates are 65536,65536. It defaults to "absolute".
The following example moves the mouse cursor to the bottom right corner and double clicks on the date:
scrollAmount (optional)
The scrollAmount of the executor indicates the scroll increment.
scrollDirection (optional)
The scrollDirection of the executor indicates the scrolling direction. Values are "up" or "down".
Click on today's date
The executor is used to disambiguate potentially ambigous properties or text from a recognition result. If the item is ambigous a dialog box will be displayed to the user allowing him/her to choose the specific item from the list.
Attributes:
propname (required)
The propname attribute of the executor specifies the name of the property that will be disambiguated.
!!!!!!timeout (optional)The timeout attribute of the executor specifies how long, in seconds, should the executor wait for an answer. If the user do not respond in the given timeout the command is canceled. The default is INFINITE.
!!!!!!title (optional) The title attribute of the executor specifies the title of the dialog box.
!!!!!!prompt The prompt attribute of the executor specifies the text prompted to the user in the dialog box.
The following example allows plays music by artist name and allows for disambiguation of similar artists names:
Play ?the ?artist [Artists]
Playing Artist {[Artist]}
Semantic Properties
Semantic properties allows you to use executors in a generic form.
To understand semantic properties let us consider the following example: Suppose you wanted to create a command that could send email to a set of people by saying things like "send email to John" or "send email to Kris". It would be nice to be able to specify the email address of each person.
The email address would be considered as a semantic property: It is not something the user said but it is something associated to what the user said.
A single semantic property
The following script enables sending an email to a single person:
Send email to [person]
Sending email to {[person]}
John
Kris
Travis
Let us examine the above script:
Send email to [person]
Inside the text area of the executor, "person" is both a rule name and a semantic property name. A rule name reference means that the list of people will be defined inside this command set using a rule generator named "person". A semantic property means that if any executor asks for a semantic property by name, and the name is "person", it should return the text that was spoken. For example if the user said "send email to John" the semantic property named "person" would have the value "John".
Sending email to {[person]}
Inside the text area of the executor, "person" is referenced again and this time it is inside "{[ ]}" brackets. These double brackets tell the executor to look for the value of the semantic property named "person". Since the semantic value of "person" is "John" the Speech Recognition UI will display "Sending email to John".
You can also associate other values with the phrases recognized. In this line of code "person.email" inside "{[ ]}" brackets tell the executor to look up the semantic property named "person.email" and substitute that value inside the executor. This value is contained in the rule generator named "person":
John
Kris
Travis
This rule named "person" contains the semantic property "email". For "John" the semantic property "person.email" returns the value "[email protected]". Thus, the semantic property person.email inside the executor will be substituted with "mailto:[email protected]".
Multiple Semantic Properties
Lets change the above script so we can CC the email to another person:
Send email to [to.person] and CC [cc.person]
Sending email to {[to.person]} and CCing {[cc.person]}
John
Kris
Travis
The key difference in this example is that it shows you how to change the name of the semantic property being used from being the same as the rule name
Send email to [to.person] and CC [cc.person]
Here the semantic property "to.person" will contain the value the user said ("John","Kris",etc) and the rule name "person".
Sending email to {[to.person]} and CCing {[cc.person]}
Similarly, the { } brackets tell the executor to substitute the semantic property value. Therefore if the user said "Send email to John and CC Kris" the Speech Recognition UI will display "Sending email to John and CCing Kris".
Since to.person also contains the rule named "person", the semantic value of "to.person.email" will be extracted from the rule named "person". For this example the executor will be replaced with "mailto:[email protected][email protected]".
Using the Same Rule and the Same Property name multiple times.
A more complicated example involves multiple semantic properties with the same property name for example person1[,person2[,person3]]. Let's edit the email script so it allows the user to send an email for up to three different people:
Send email to
and
Sending email to {[foreach:{[person]};]}
John
Kris
Travis
The three major changes are: - We are using the rule generator instead of the rule generator. - We changed the executor. - We changed the executor.
Let's take a look at each change:
Send email to
and
The first
tag of the rule generator tells the computer to listen for the phrase "Send email to". The second
tag states that the tag must be used at least one (min="1") and at most three times (max="3"). The tag tells the computer to reference the rule named "person" and to use a semantic property of the same name. The last tag says that "and" is optional after a person's name. This rule generator allows the user to say "Send email to John", "Send email to John and Travis", "Send email to John, Travis and Kris", and "Send email to John and Travis and Kris".
Sending email to {[foreach:{[person]};]}
For the executor we have concatenated each semantic property by using the foreach statement. The Speech Recognition UI will display each name separated by a semicolon; so if we said "Send email to John, Travis and Kris" the UI will display "Sending email to John; Travis; Kris;".
Similarly to , the executor will replace each vaule of person.email using the foreach statment with the proper semantic value. So for "Send email to John, Travis and Kris" the "mailto" command will contain "[email protected];[email protected];[email protected];"
Using different Rules and different Property names.
You can also use different rules that have different semantic properties. Lets edit the email script so we can send an email with a priority property:
Send [priority] email to [person]
Sending {[priority]} email to {[person]}
{[priority.keysToSend]}
John
Kris
Travis
high priority
low priority
normal priority
Let us examin these new changes:
Send [priority] email to [person]
In this script we have added a new rule reference named "priority".
{[priority.keysToSend]}
We have added two new executors the executor will wait for one second after executing the executor. The will replace the value in "priority.keysToSend" with its respective semantic value.
high priority
low priority
normal priority
The new rule generator defines a new rule named "priority" and it generates a semantic property named "keysToSend".
With this scrip the user is allow to say "Send email to John" and everything works as before however the user can add a priority to the email message. For example if the user says "send high priority email to John" the executor will contain "mailto:[email protected]" then the script will wait for one second and set the importance to High in Outlook by sending the keys "ALT-P" followed by an "H" and "Enter" which is defined by %ph{enter} (for more information about the executor visit the executors section of the Windows Speech Recognition Macros wiki).
Note. Priority Shortcuts may not be the same for every email client.
Note. For a more thorough description of semantic properties, see the Speech API programming Reference http://msdn.microsoft.com/en-us/library/ms723630(VS.85).aspx
Script Object Model
The following object models are provided to:
- condition- rule generator - executor
Objects List
These objects can be called from scripts called from the WSR
Application:Methods that parallel executors available to WSRM (run, speak, wait,
switch/minimise application etc).
ClipboardData:Methods to set/get text to clipboard. ChooseFromList:Opens dialogue window for use to select option. Command:Methods to get a WSRM property, and to exit script. CommandSet:Gets conditions and rule generators from WSRM. Debug:Methods to debug script code, assertion alert box, start debugger. NamedStates:Gets / sets WSRM named states. RuleItem:Creates a rule item available to WSRM. RuleItemCollection:Creates a collection of rules item available to WSRM. Rule: Condition:
Application object
The Application object contains methods that parallel the Executors available to the Command Set. This allow executors to perform the same functionality as any other executor.
Methods
SetTextFeedbackThe SetTextFeedback method is used to set the text in the Speech Recognition UI.
Parameter Name
Type
Default Value
Description
Text
BSTR
no default value
Text to be displayed in the Speech Recognition Feedback Window
Warning
BOOL
FALSE
Show the message as a warning
Speak
BOOL
FALSE
Speak the text in addition to displaying it
Return Value: None.
AlertThe Alert method brings a dialog box with a message.
Parameter Name
Type
Default Value
Description
Prompt
BSTR
no default value
Text to be displayed in the dialog box
Title
BSTR
Text to be displayed in the dialog box title
Timeout
FLOAT
0.0
Time in seconds before the window atuomatically closes. 0 indicates that it never timeout
Return Value: None.
ConfirmThe Confirm method brings up a dialog box with a message and "Yes" and "No" buttons.
Parameter Name
Type
Default Value
Description
Prompt
BSTR
no default value
Text to be displayed in the dialog box
Title
BSTR
Text to be displayed in the dialog box title
Timeout
FLOAT
0.0
Time in seconds before the window atuomatically closes. 0 indicates that it never timeout
Return Value: Integer of the Button "6" for IDYES, "7" for IDNO or -1 if dialog times out.
MsgBoxThe MsgBox method brings up a dialog box with user specified content
Parameter Name
Type
Default Value
Description
Prompt
BSTR
no default value
Text to be displayed in the dialog box
Title
BSTR
Text to be displayed in the dialog box title
Timeout
FLOAT
0.0
Time in seconds before the window atuomatically closes. 0 indicates that it never timeout
Buttons
Int
0
Button arguments for VBscript MsgBox
Return Value: None.
(for more info on the Buttons parameter read the VBscript documentation here http://msdn.microsoft.com/en-us/library/sfw6660x.aspx)
PromptThe Prompt method brings a dialog box with an edit control allowing the user to enter text
Parameter Name
Type
Default Value
Description
Prompt
BSTR
no default value
Text to be displayed in the dialog box
initialValue
BSTR
0
Default text in the edit control
Title
BSTR
Text to be displayed in the dialog box title
Timeout
FLOAT
0.0
Time in seconds before the window atuomatically closes. O indicates that it never timeout
Return value: BSTR containing the text entered by the user. If the user cancels the dialog box or it times out, the returned value is an empty string.
RunThe Run method launches an application or URL
Parameter Name
Type
Default Value
Description
Command
BSTR
no default value
URL or executable file name to run
Params
BSTR
Command line arguments
startInDirectory
BSTR
Working directory for the application
Return value: None. If the URL or application fails to launch an exception will be thrown.
SwitchToAppByTitleThe SwitchToAppByTitle method brings the specified application window to the foreground.
Parameter Name
Type
Default Value
Description
Title
BSTR
no default value
Window Title of the application
ExactMatch
BOOL
FALSE
Specifies if the window title should match the Title argument exactly. FALSE allows for partial match
Return value: None. If the URL or application fails to launch an exception will be thrown.
MinimizeAppByTitleThe MinimizeAppByTitle method minimizes the specified application window.
Parameter Name
Type
Default Value
Description
Title
BSTR
no default value
Window Title of the application
ExactMatch
BOOL
FALSE
Specifies if the window title should match the Title argument exactly. FALSE allows for partial match
Return value: None. If the URL or application fails to launch an exception will be thrown.
MaximizeAppByTitleThe MaximizeAppByTitle method maximizes the specified application window.
Parameter Name
Type
Default Value
Description
Title
BSTR
no default value
Window Title of the application
ExactMatch
BOOL
FALSE
Specifies if the window title should match the Title argument exactly. FALSE allows for partial match
Return value: None. If the URL or application fails to launch an exception will be thrown.
RestoreAppByTitleThe RestoreAppByTitle method restores the specified application window.
Parameter Name
Type
Default Value
Description
Title
BSTR
no default value
Window Title of the application
ExactMatch
BOOL
FALSE
Specifies if the window title should match the Title argument exactly. FALSE allows for partial match
Return value: None. If the URL or application fails to launch an exception will be thrown.
CloseAppByTitleThe CloseAppByTitle method closes the specified application window.
Parameter Name
Type
Default Value
Description
Title
BSTR
no default value
Window Title of the application
ExactMatch
BOOL
FALSE
Specifies if the window title should match the Title argument exactly. FALSE allows for partial match
Return value: None. If the URL or application fails to launch an exception will be thrown.
SendMessageThe SendMessage method provides limited means to send window messages to a window.
Parameter Name
Type
Default Value
Description
className
BSTR
no default value
Name of the window class of the target window
windowName
BSTR
no default value
Title of the target window
Msg
UINT
no default value
Window message number
wParam
UINT
no default value
wParam value of message
lParam
UINT
no default value
lParam value of message
Return Value: UINT result of SendMessage. This value is application specific.
SendKeysThe SendKeys method sends keystrokes to the foreground window.
Parameter Name
Type
Default Value
Description
Keys
BSTR
no default value
Keys to send to the foreground window
Return Value: None. An exception will be thrown if an error ocurred. Note: Visit the executor documentation for details regarding the string format for Keys.
InsertTextThe InsertText method inserts the specified text into t he foreground window.
Parameter Name
Type
Default Value
Description
text
BSTR
no default value
Text to send to the foreground window
Return Value: None. An exception will be thrown if an error occurred.
EmulateRecognitionThe EmulateRecognition method sends a string of Windows Speech Recognition commands to the recognizer.
Parameter Name
Type
Default Value
Description
textToEmulate
BSTR
no default value
Text that represents WSR commands to be sent to the recognizer
disambiguationTimeout
FLOAT
0.0
Time to wait for native disambiguation to occur. 0.0 indicates that disambiguation is not expected
Return Value: None. An exception will be thrown if an error occurred.
SpeakThe Speak method causes the TTS engine to speak the text provided.
Parameter Name
Type
Default Value
Description
Text
BSTR
no default value
Text to be spoken
Flags
ULONG
16 (SPF_IS_NOT_XML)
SPEAKFLAGS passed to the TTS engine
Return Value: None. An exception will be thrown if an error occurred. Note: For more information about SPEAKFLAGS go to http://msdn.microsoft.com/en-us/library/ms717252(VS.85).aspx
WaitThe Wait method pauses execution for a specified time period.
Parameter Name
Type
Default Value
Description
Seconds
FLOAT
1.0
Time in seconds to stop execution
Return Value: None. An exception will be thrown if an error occurred.
Properties
clipboardDataThe clipboardData property is a read-only property that returns the clipboardData object.
clipboardData Object
The clipboardData object can be used to manipulate text data in the system clipboard.
Methods
getDataThe getData method of the clipboardData object returns the text currently contained in the systems clipboard.
Parameter Name
Type
Default Value
Description
Format
BSTR
no default value
Clipboard format string (only text is supported)
Return Value: VARIANT - The text currently in the clipboard, or an empty string if no clipboard text exists.
setDataThe setData method of the clipboardData object places the specified text into the system clipboard.
Parameter Name
Type
Default Value
Description
Format
BSTR
no default value
Clipboard format string (only text is supported)
Data
VARIANT
no default value
Text to place into the system clipboard
Return Value: None. An exception will be thrown if an error occurs.
clearDataThe clearData method of the clipboardData object clears any text from the systems clipboard.
Parameter Name
Type
Default Value
Description
Format
BSTR
no default value
Clipboard format string (only text is supported)
Return Value: None. An exception will be thrown if an error occurs.
ChooseFromList Object
Methods
ChooseThe Choose method of the ChooseFromList object launches a dialog window with a list that allows the user to choose from the selection.
Parameter Name
Type
Default Value
Description
Prompt
BSTR
Text that prompts the user. This will be displayed at the top of the dialog box
Title
BSTR
Title of the dialog window
Timeout
FLOAT
0.0
Time to wait (in seconds) before automatically canceling the dialog window. 0.0 indicates that it never times out
Return Value: int - The zero-based index of the item selected by the user. If user cancels or dialog timesout -1 is returned.Note: The Items property of the ChooseFromList must be initialized to contain the itemos to be presented in a list to the user.
Properties
Items (read-only)The Items property of the ChooseFromList object is a RuleItemCollection object containing the choices to be presented in a list to the user. This property may be set using an external RuleItemCollection (from a rule generator, for example) or it may be directly modified.
Command Object
Methods
ResolvePropertiesThe ResolveProperties method of the Command object provides a means to get the value of a named property. This property can be any property that would normally be resolved using the {[property]} syntax.
Parameter Name
Type
Default Value
Description
PropertyString
BSTR
no default value
Property to be resolved
Return Value: The resolved property string. If a property specified in the string does not exists it is replaced with an empty string.
ExitThe Exit method causes the script to terminate. This can be useful for early termination for a script, and also to halt the list of executors in a command.
Parameter Name
Type
Default Value
Description
ExitCode
DWORD
no default value
A non-zero value in this field causes the current executor to stop execution. Zero allows the executor to continue execution.
Return Value: None. An exception will be thrown if an error occurred.
Properties
Result (read-only)The Result object is the ISpRecoResult returned from the recognizer for the recognition event that triggered this executor. Click the following link for more information: http://msdn.microsoft.com/en-us/library/ms718929(VS.85).aspx
CommandSet Object
The CommandSet object contains methods used to access Conditions or Rule Generators within the Command Set.
Methods
Conditions
Parameter Name
Type
Default Value
Description
ConditionName
BSTR
no default value
Name of the Condition
Return Value: The Condition method returns an object dependent on the type of the condition targeted. Different conditions support different methods and properties. All Conditions support the Attributes property which is an IXMLDOMNamedNodeMap representing the XML attribute of the XML node representing the condition.
RuleGenerators
Parameter Name
Type
Default Value
Description
RuleName
BSTR
no default value
Name of the Rule Generator
Return Value: The RuleGenerator methods returns an object dependent on the type of the Rule Generator targeted. Different rule generators support different methods and properties, The table below illustrates which properties are available for each Rule Generator:
Attributes: IXMLDOMNamedNodeMap containing the XML attributes of the Rule Generator. Rule: Rule object of the rule. Script: only: Collection of objects and functions within a script. Text: only. Text of the element.
Rule Generator
Attribute
Rule
Script
Text
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
Debug Object
The Debug object is made available to aid in debugging scripts within Command Sets.
Methods
Assert
Parameter Name
Type
Default Value
Description
Test
BOOL
no default value
If FALSE a dialog box pops with the Prompt text. If TRUE execution runs normally
Prompt
BSTR
no default value
Text displayed in dialog box if Test evaluates to FALSE
Return Value: None.
DebugBreakThe DebugBreak method is used to halt execution of a script in the debugger. If a debugger is not running, the user will be prompted to choose a debugger to attach to the process. Parameters: None. Return Value: None.
TraceThe Trace method is used to output a message to a debugger window.
Parameter Name
Type
Default Value
Description
Text
BSTR
no default value
Text to be sent to the debugger output window
Return Value: None.
NamedStates Object
The NamedStates object is used to interact with Named States in the system. These can be set either through this methods of this object or by the executor.
Methods
IsNamedStateSetThe IsNamedStateSet method checks the value of a Named State. If a value exists and is not empty, this methods returns true.
Parameter Name
Type
Default Value
Description
StateName
BSTR
no default value
Name of the state to check
Return Value: TRUE if the specified state is non empty. FALSE otherwise.
IsNamedStateSetToValueThe IsNamedStateSetToValue method checks the value of a Named State against a specified value. If the values are identical the method returns TRUE.
Parameter Name
Type
Default Value
Description
StateName
BSTR
no default value
Name of the state to check
StateValue
BSTR
no default value
Value used for comparision
Return Value: TRUE if the value of the state equals the specified value. FALSE otherwise.
SetNamedStateValueThe SetNamedStateValue method sets the value of the specified state.
Parameter Name
Type
Default Value
Description
StateName
BSTR
no default value
Name of the state to set
StateValue
BSTR
no default value
Value assigned to state
Return Value: None.
GetNamedStateValueThe GetNamedStateValue method retrieves the value of the specified state.
Parameter Name
Type
Default Value
Description
StateName
BSTR
no default value
Name of the state to be retrieved
Return Value: BSTR The value of the specified Named State. If the state is not set an empty string will be returned.
ClearNamedStateValueThe ClearNamedStateValue method clears the value of the specified state.
Parameter Name
Type
Default Value
Description
StateName
BSTR
no default value
Name of the state to clear
Return Value: None.
WaitForAllNamedStatesToBeSetThe WaitForAllNamedStatesToBeSet method pauses execution of the script until all the specified states are set (non-empty) or the specified timeout expires.
Parameter Name
Type
Default Value
Description
StateList
BSTR
no default value
List of states to wait for. States are separated by the vertical bar "
" symbol
Timeout
FLOAT
no default value
Time in seconds to wait for the specified states to be set
Return Value: BOOL - TRUE if all states were set FALSE if timeout expires.
WaitForAnyNamedStateToBeSetThe WaitForAllNamedStateToBeSet method pauses execution of the script until one or more of the specified states are set (non-empty) or the specified timeout expires.
Parameter Name
Type
Default Value
Description
StateList
BSTR
no default value
List of states to wait for. States are separated by the vertical bar "
" symbol
Timeout
FLOAT
no default value
Time in seconds to wait for the specified states to be set
Return Value: BOOL - TRUE if any states were set FALSE if timeout expires.
RuleItem Object
The RuleItem object represents a spoken phrase and their property value within a rule.
Methods
CloneThe Clone method creates a copy of the RuleItem object. Parameters:None. Return Value:A RuleItem object that is a copy of the original.
Properties
Phrase (read/write)Type: BSTRThe Phrase property of a RuleItem object is a string that contains the text the recognizer should listen for. Example: myRuleItem.Phrase = "John Smith";In this example, the recognizer listens for "John Smith".
Property (read/write)Type:BSTRThe Property property of the RuleItem object is the semantic property associated with the item. Example: myRuleItem.Phrase = "John Smith";myRuleItem.Property = "[email protected]";In this example, the recognizer listens for "John Smith" and sets the semantic property of the rule to "[email protected]".
UseSubsets (read/write)Type:BOOLThe UseSubsets property of the RuleItem object indicates if the recognizer should accept an ordered subset of the words contained in the Phrase property rather than the entire set of words. Example: myRuleItem.Phrase = "John Austin Smith Junior";myRuleItem.Property = "[email protected]";myRuleItem.UseSubsets = true;In this example, setting UseSubsets to true allows the recognizer to listen for "John Austin", "Austin Junior", "John Smith" to match this rule item. If UseSubsets property were set to false only "John Austin Smith Junior" would be recognized to match the RuleItem.
RuleItemCollection Object
The RuleItemCollection object is a container class used to hold a collection of RuleItem objects.
Methods
NewEnumThe NewEnum method is used to allow VBScript enumerations internally, and is not normally called from within script. Parameters: None. Return Value: IEnumVariant - A new enumerator which can be used to iterate through the items of the collection. Visit the following website for more information http://msdn.microsoft.com/en-us/library/ms221053.aspx
FindTextMatchesThe FindTextMatches method returns a new RuleItemCollection containing items from the original collection that contain the ordered subset specified in the Filter parameter.
Parameter Name
Type
Default Value
Description
Filter
BSTR
Ordered subset used to filter matches. If this value is an empty string a complete copy of the RuleItemCollection will be returned.
Return Value: RuleItemCollection - a new collection containing the matching RuleItems. Example: _ var flavoredPops = popsCollection.FindTextMatches("flavored pop");_ In this example the flavoredPops collection would contain items from the popsCollection whose phrases contain the words "flavored" and "pop" in that order. This could include items such as: "orange flavored pop" "cola flavored pop"
AddItemThe AddItem method adds a new RuleItem to the collection.
Parameter Name
Type
Default Value
Description
Phrase
BSTR
no default value
Phrase property of the new RuleItem
PropertyValue
BSTR
Property property of the new RuleItem
UseSubsets
BOOL
FALSE
UseSubsets property of the new RuleItem
Return Value: None.
AddItemsThe AddItems method adds a RuleItemCollection to the collection.
Parameter Name
Type
Default Value
Description
Collection
RuleItemCollection
no default value
RuleItemCollection to be added
Return Value: None.
RemoveItemThe RemoveItem method removes items from the collection.
Parameter Name
Type
Default Value
Description
Phrase
BSTR
no default value
Phrase property of the RuleItem to be removed
PropertyValue
BSTR
Property property of the RuleItem to be removed
UseSubsets
BOOL
FALSE
UseSubsets property of the RuleItem to be removed
Return Value: None.
RemoveItemsThe RemoveItem method removes a collection of items from the collection.
Parameter Name
Type
Default Value
Description
Collection
RuleItemCollection
no default value
Collection of Items to be removed
Return Value: None.
RemoveAllThe RemoveAll method removes all items from the collection. Parameters: None. Return Value: None.
SortThe Sort method sorts the items in the collection. Sorting is performed alphabetically based on the Phrase property of each RuleItem.
Parameter Name
Type
Default Value
Description
Ascending
BOOL
TRUE
If TRUE the collection is order in ascending order, if FALSE the collection is ordered in descending order
Return Value: None.
Properties
Item (read-only)The Item property returns the RuleItem at the specified location.
Parameter Name
Type
Default Value
Description
Index
VARIANT
No default value
Zero based index of the item to be retrieved
Return Value:The RuleItem found at the specified index.
Count (read-only)The Count property returns the number of items in the collection. Parameters: None. Return Value: LONG - the number of items in the collection.
Rule object
The Rule object creates or modifies rules within a Rule Generator. Most commonly this object is used by scripts to generate rules on the fly.
Methods
CommitThe Commit method causes the rule to be generated and inserted into the recognizer. The call to Commit() is optional within a script. Commit can be called again after the rule has been generated to cause the rule to be reloaded in the Command Set. Parameters: None Return Value: None
Properties
Items (read/write)The Items property of the Rule object represents the RuleItemCollection of RuleItems that compose the rule. This property may be set or retrieved. Parameters: None Return Value: The RuleItemCollection returned by the Rule.
InnerXML (read/write)The InnerXML property can be used to set or retrieve the SAPI XML that is sent to the recognizer. This property may be set to allow the Rule object to contain a SAPI rule. Setting the XML directly using this property causes the Items of the Rule object to be emptied, and no manipulation of the rule can be done through the Items object. If the InnerXML property has not been explicitly set, this property returns the SAPI XML generated by the Items collection as it is sent to the recognizer. Parameters: None.Return Value: BSTR - The SAPI XML representing this Rule object.
RuleName (read only)The RuleName property returns the name of the Rule. This is a read-only property. The RuleName for Rule Generators is determined by the "name=" attribute of the tag.Parameters: None Return Value: BSTR-The name of the rule.
PropName (read only)The PropName property returns the name of the semantic property associated with items of the Rule object. The PropName for Rule Generators is determined by the "propname=" attribute of the tag. Parameters: None Return Value: BSTR-The name of the semantic properties associated with this rule.
Condition object
The Condition object is exposed to conditions. It contains methods and properties used to aid in condition evaluation.
Methods
setTimeoutThe setTimeout method allows the script author to execute a scriptlet after a specified period of time has expired. Unlike setInterval, setTimeout willonly execute the scriptlet once.
Parameter Name
Type
Default Value
Description
Seconds
FLOAT
no default value
Time in seconds before running the scriptlet
Scriptlet
BSTR
no default value
Scriptlet code to run
Return Value: ULONG - Timer ID. This ID can be passed to the clearTimeout method to cancel the timer.
setIntervalThe setInterval method allows the script author to execute a scriptlet after a specified period of time has expired. Unlike setTimeout, setInterval executes the scriptlet code every interval until clearInterval is called.
Parameter Name
Type
Default Value
Description
Seconds
FLOAT
no default value
Time in seconds before running the scriptlet
Scriptlet
BSTR
no default value
Scriptlet code to run
Return Value: ULONG - Timer ID. This ID can be passed to the clearInterval method to cancel the timer.
Properties
Satisfied (read/write) The Satisfied property determines if the condition has been met. Set this property to TRUE to cause the condition to pass. Set toFALSE to cause the condition to fail. Parameters: None. Return Value: BOOL - The current state of the condition.
WSR Macros Security
WSR Macros is a facility that enhances Windows Speech Recognition. It allows for greater control over your computer via speech. As it is designed to interact with applications, malicious software may generate macro files that could harm your computer.
To prevent unwanted files to load, WSR Macros provides you with signing certificates and security levels that gives you full control of which Speech Macros files to load.
Please take a moment to read this section as its content is valuable for the security of your computer.
Creating a Signing Certificate
Your signing certificate serves to identify yourself in the WSR Macros application. You can think of a signing certificate as a digital stamp of approval: if you trust the quality, validation, and source of a Speech Macro file then you stamp it with your signing certificate as a sign of approval. Only those WSR Macros files that contain your signing certificate will be loaded into the Macro application.
To create your signing certificate for the WSR Macros application: 1. Click on the WSR Macros icon and select Security->Create Signing Certificate... 2. User Account Control will prompt for your permission to continue running WSR Macros, click on Continue3. The following Creating a new RSA signature key window will pop up
- From this Window you can either select OK or change the security Level of your Signing Certificate by clicking Set Security Level....
If you select Set Security Level... a window will prompt you to select the level of security of your signing certificate. If you choose High, you will input a password for your signing certificate, by this everytime you choose to sign a Speech Macro file with this certificate you will be prompted for the signing certificate password. If you select Medium you will not need to provide a password for the signing certificate.
4. A final dialog window will display the message "A new certificate "username" was created" click Ok to close the window.
Congratulations! You have now created your personal signing certificate for the WSR Macros application. To set a signing certificate as the default certificate click on the WSR Macros icon and select Security->Set Default Signing Certificate.... Choose the certificate you just created and click Ok.
To use a signing certificate please refer to the section Signing a Speech Macro file below.
Note. Signing certificates contain expiration dates. WSR Macros signing certificates expire after one year. After a signing certificate expires you must create a new signing certificate and re-sign your Speech Files with the new signing certificate.
For more information about signing certificates please visit the link http://www.microsoft.com/technet/security/guidance/cryptographyetc/cryptpki.mspx
Setting the Security Level
The Security Level of WSR Macros determines how restrictive the application must be. The level of restrictiveness is determined by which Speech Macros files must be loaded into the application. WSR Macros provide three levels of security: High, Medium and Low. - WSR Macros defaults to High. In this level only those Speech Macros files with signing certificates will be loaded into the application.
Note: We strongly recommend that you always run the WSR Macros application in 'High' security
- In Medium, similar to High, only those Speech Macros files with a signing certificate will be loaded but you will be prompted to sign those files that do not contain a digital signature.
Note: Do not sign Speech files that are unfamiliar to you, only sign those speech files that you entrust. If a Speech Files seems suspicious delete it immediately
- Low security loads every Speech Macros file stored in the Speech Macros folder.
Note:We do not recommend running the WSR Macros application in Low security
To access the Security Levels on the WSR Macros application: 1. Click on the WSR Macros systray icon 2. Select Security->Set Security Level...3. The following "Speech Macros Security Level" dialog box pops up
4. From this dialog box you can select your security level
Signing a Speech Macro file
By signing a speech Macro file you validate its functionality and trust its source. Your signing certificate signs the Speech Macros files. If you create a Speech Macro file using the WSR Macros wizard, the Summary page provides a way of signing the macro
Check the box to sign the WSR Macro file.
To sign a Speech Macro from the context menu 1. Click on the WSR Macros systray icon2. Select Security->Sign Speech Macros3. A Select the macros you would like to sign window pops up4. From this window select a file (or a group of files) and click the