Overview - perturbed-koala.co.uk Ref - WSRM - Languag… · Web viewFor example, you could type “555 ... textInDocument built in rule refers to a word or a set of ordered words

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


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


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


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


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


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)


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.



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)


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]}?


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:


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.


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.


The following example minimizes Notepad if opened:

Minimize my favorite application

The executor is used to maximize a specified application.


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.


The following example maximizes an instance of Notepad:

Maximize my favorite application

The executor is used to restore a specified application.


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.


The following example restores Notepad if opened:

Restore my favorite application

The executor is used to close a specified application.


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.


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)


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:


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:



John

Kris

Travis

Let us examine the above script:


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


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


Title

BSTR


Timeout

FLOAT

0.0


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


Title

BSTR


Timeout

FLOAT

0.0


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


initialValue

BSTR

0

Default text in the edit control

Title

BSTR


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


MinimizeAppByTitleThe MinimizeAppByTitle method minimizes the specified application window.

Parameter Name

Type

Default Value

Description

Title

BSTR

no default value


ExactMatch

BOOL

FALSE



MaximizeAppByTitleThe MaximizeAppByTitle method maximizes the specified application window.

Parameter Name

Type

Default Value

Description

Title

BSTR

no default value


ExactMatch

BOOL

FALSE



RestoreAppByTitleThe RestoreAppByTitle method restores the specified application window.

Parameter Name

Type

Default Value

Description

Title

BSTR

no default value


ExactMatch

BOOL

FALSE



CloseAppByTitleThe CloseAppByTitle method closes the specified application window.

Parameter Name

Type

Default Value

Description

Title

BSTR

no default value


ExactMatch

BOOL

FALSE



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


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


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


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


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.


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