Introduction

Vocola is a voice command language -- a language for defining commands to control a computer by voice -- developed for use with Dragon NaturallySpeaking and implemented using NatLink. While these systems do the heavy lifting, Vocola (pronounced "vo-CO-luh") concentrates on features and ease of use. In particular, Vocola offers the following:

• Easy to use
  • Simple, concise command syntax -- most commands are one-liners
  • Easy to view and modify commands
  • Changed commands are loaded automatically
  • Free, and works with any version of NatSpeak
• Features
  • Create commands which capture any dictated words
  • Use concise number ranges, optional words, and inline word lists
  • Specify different actions for variable words
  • Speak a continuous sequence of commands
  • Re-use work with include files and user-defined functions
• Familiar syntax
  • Keystroke syntax and built-in functions from Dragon Macro Language
  • Grammar syntax similar to NatLink

Examples

Here are four voice commands defined in Vocola:

The second command, invoked by saying "Copy to NatSpeak", copies a window of text (Control-A selects all text and Control-C copies it) and brings up the NaturallySpeaking editor (using the built-in function AppBringUp ).

The third command allows controlling the cursor, by saying for example "3 Left" to move left three characters, or "6 Down" to move down six lines. Spoken words match variable terms on the left and are substituted into the keystroke sequence on the right. For example, when saying "3 Left" the spoken "3" matches the numeric range "1..40" and the spoken "Left" matches the alternative set "(Left | Right | Up | Down) ". The keystroke sequence "{Left 3}" is constructed and sent, and the cursor moves left three characters.

The fourth command allows sorting messages in the Netscape Mailer, by saying "Sort by Date", "Sort by Sender", or "Sort by Subject". The matched word "Date", "Sender", or "Subject", causes the appropriate keystroke "e", "r", or "s" to be inserted into the keystroke sequence.

These and other features are discussed in greater detail in the Vocola Tutorial.

Why a New Voice Command Language?

Existing voice command languages are grafted onto existing programming languages. This means you can program any behavior you want, but you're stuck with the syntactic overhead of the base language. In contrast, Vocola is designed specifically as a voice command language, not as a general-purpose programming language. This means you can write quickly and concisely the great majority of voice commands you need, and use another language in the few cases where you need more power. When I switched to Vocola I was able to convert all but two of my 200+ Dragon macros, and at this writing use something over 900 Vocola commands.

Alternatives to Vocola include NatSpeak Pro's VisualBasic-based language (introduced in version 6), the older Dragon Macro Language (used through version 5 and still functional), and NatLink. Each of these languages has advantages, but (in my humble and not unbiased opinion) none offers Vocola's features and ease of use.

Acknowledgments

Joel Gould for his time and care in designing, building, and "productizing" NatLink, which enabled and inspired Vocola. The authors and voice community members listed in Voice Resources. Scott Weinstein for building and maintaining his NatLink + Vocola installer.

This Web Site

This web site was created using a Python program developed and shared by Joel Gould, in another admirable display of community-mindedness. His description and sources are here.

A single-page version of the site is available here.

Using Vocola

The easiest way to create and manage Vocola commands is by voice, using Vocola's built-in commands. Beginning and intermediate users should only need to learn the two commands described in the first subsection. The remaining subsections discuss commands for advanced features.

In the command descriptions below, words in square brackets are optional. For example, "Edit [Voice] Commands" means you can say either "Edit Voice Commands" or "Edit Commands".

How to Create and Load Voice Commands

With Vocola you can define commands for a specific application program, or define global commands which are active for all applications. You can use the following built-in commands to open the right command files:

After creating or modifying commands and saving the file, your commands will be loaded automatically and usable immediately. Any errors will be displayed in a pop-up window titled "Messages from Python Macros".

Machine-Specific Commands

If you need to control more than one computer by voice (for example at work and at home) you can define commands which will only be enabled on a particular computer:

Machine-specific command files are also reloaded automatically.

Direct Loading

Sometimes it's useful to reload your command files explicitly. For example, if you modify an include file, Vocola doesn't know enough to reload all command files which use that include file. You can do it yourself using the following commands:

File Organization and Naming

• Put all Vocola source files in the folder NatLink/Vocola/Commands.
• Put global commands in the file _vocola.vcl.
• Put application-specific commands in the .vcl file matching the executable name -- for example, commands specific to Netscape.exe go in netscape.vcl.
• You can create additional files for a category of commands by extending the filename.  For example, an additional global command file could be called _vocola_text.vcl; or, an additional Netscape command file could be called netscape_addresses.vcl.
• If you want commands to be active only on a certain computer, put them in a file containing @ followed by the computer name.  For example, commands in the file natspeak@venus.vcl would be valid only on the computer named "venus" with natspeak.exe running.
• Vocola files are translated into Python files and loaded by NatLink. For example, the Vocola command file NatLink/Vocola/Commands/Netscape.vcl would be translated to the Python file NatLink/MacroSystem/Netscape_vcl.py.

Language Tutorial

• Keystroke Commands: When I say this, send these keystrokes.
• Quotes and Whitespace: Understand Vocola syntax.
• Using Alternatives: Create commands with alternative words or number ranges.
• Defining Variables: Name a set of alternative words for use in several commands.
• Substituting Actions: Specify different actions for each alternative word.
• Capturing Dictation: Create commands incorporating arbitrary dictation.
• Optional Words: Option to omit words when speaking a command.
• Function Calls: Create commands which call built-in functions.
• Built-in Functions: Descriptions of available functions.
• Defining Functions: Name an action sequence for use in several commands.
• Contextual Commands: Create commands active only for particular windows.
• Include Statements: Share commands and definitions across several Vocola files.
• Comments: Put comments in your Vocola command files.
• Example File: A longer example of a Vocola command file.

Keystroke Commands

Most of the everyday commands you will need are simple -- "When I say this, send these keystrokes." For example, the following command types the word "Greetings" when you say "Hello World": 

In most cases the keystrokes you want to send will use modifier key sequences to control a particular application. For example, most Windows applications perform a "Copy" operation when you hold down the "Control" key and type the letter "c". The next command uses the phrase "Copy That" to invoke such a "Copy" operation:

The Vocola syntax for specifying modifier key sequences such as {Ctrl+c} is borrowed from the Dragon Macro Language, which describes the syntax. (See the discussion on pp. 13-14 and the table on pp. 116-117, or just absorb it from the Vocola examples.)

Because Windows applications allow keyboard control of almost everything, you can usually write a keystroke command to do what you want. The next example tells the Netscape 4 mail program to use its HTML editor (rather than the plain text editor) for composing messages:

Here's how it works:

Quotes And Whitespace

Copy All = {Ctrl+a}{Ctrl+c};
Copy All = "{Ctrl+a}{Ctrl+c}";
Copy All = '{Ctrl+a}{Ctrl+c}';

Whitespace (any sequence of blank, tab, and newline characters) is used to separate actions. The following commands are also equivalent, specifying two actions (the keystroke sequence {Ctrl+a} followed by the keystroke sequence {Ctrl+c}):

Copy All = {Ctrl+a} {Ctrl+c};
Copy All = {Ctrl+a}
           {Ctrl+c};

In general it does no harm to separate keystroke sequences into multiple actions, so you can add whitespace wherever it is useful in formatting your commands. However, watch out for keystroke sequences containing space characters, such as the "HTML Editor" command above. That command specifies one action:

HTML Editor = "{Alt+e}e{Shift+Tab}{Down 8}{Tab}{Up}{Enter}";

Because this command contains a space character, omitting the quotation marks would unintentionally specify two actions, "{Alt+e}e{Shift+Tab}{Down" followed by "8}{Tab}{Up}{Enter}". This command would not behave as intended.

An alternative to quotation marks in this example is using the syntax "{Down_8}" instead of "{Down 8}":

HTML Editor = {Alt+e}e{Shift+Tab}{Down_8}{Tab}{Up}{Enter};

This is a Vocola extension to the Dragon Macro Language keystroke syntax -- within braces, underscore may be used instead of space to separate the keystroke name from the repetition count.

Some characters must be quoted

In addition to whitespace characters, the following characters must appear within quotes when used in a keystroke sequence:

( ) [ ] = | , " '

All other characters may appear without quotes. For example, pathnames do not need to be quoted, as in this command to open a temporary file:

Open Temp = {Ctrl+o}C:\Temp\temp.txt{Enter};

The examples in this tutorial use quotation marks only where necessary; you might prefer to use them more consistently. 

Using Alternatives

For example, you might want to be able to say either "Switch View" or "Next View" to switch between views in an application:
 

Vocola: (Switch | Next) View = {Ctrl+Tab};   Say: Switch View  Sent: {Ctrl+Tab}  Say: Next View    Sent: {Ctrl+Tab}

Here the alternative term (Switch | Next) allows you to say either.

In many cases you want the actions invoked by a command to depend on which alternative was spoken. For example, you might want to move the cursor in one of four directions by saying "Move Left", "Move Down", etc.:
 

Vocola: Move (Left | Right | Up | Down) = {$1};   Say: Move Left  Sent: {Left}   Say: Move Down  Sent: {Down}

Here the reference "$1" specifies that the first variable term should be substituted. So, when you say "Move Left" the value of the first variable term is "Left" and the keystroke"{Left}" is sent.
 

References may appear anywhere in a sequence of actions (i.e. on the right hand side of an "="), even inside quoted strings. If you want to insert the literal text "$1", use the escape sequence "\$1".

Number Ranges

Often you will want to specify a range of numbers as alternatives in a command.  This can be specified concisely in Vocola, as in the following example:
 

Vocola: Move Down 1..10 = {Down_$1};   Say: Move Down 1  Sent: {Down 1}  Say: Move Down 6  Sent: {Down 6}

Here the syntax "1..10" is shorthand for "(1|2|3|4|5|6|7|8|9|10) ". On the right hand side we substitute the spoken number (e.g. "6 ") to construct the syntax for a repeated keystroke ("{Down 6}") and we have a command which moves the cursor down a specified number of lines.

In real life it's very useful to control the arrow keys by saying simply "1 Down", "3 Left", "6 Up", etc. Here's how to write it in Vocola:
 

Vocola: 1..40 (Left | Right | Up | Down) = {$2_$1};   Say: 3 Left   Sent: {Left 3}  Say: 12 Down  Sent: {Down 12}

This command has two variable terms. On the right-hand side the second term (which direction to move) is substituted first and the first term (how many times) is substituted second, to create the necessary keystroke syntax.
 

Defining Variables

This command is equivalent to the second command in the previous section, allowing you to move the cursor in one of four directions.

The following command defines the variable <number>, and is equivalent to the third command in the previous section:
 

Vocola: <number> := 1..40;           Move Down <number> = {Down_$1};   Say: Move Down 1   Sent: {Down 1}  Say: Move Down 12  Sent: {Down 12}

This moves the cursor down a given number of lines.

Finally, we can write our general-purpose arrow-key command (move a given number of steps in any direction) using both the <direction> and <number> variables:
 

Vocola: <number> <direction> = {$2_$1};   Say: 3 Left   Sent: {Left 3}  Say: 10 Down  Sent: {Down 12}

 

Note that a variable reference may appear earlier in a Vocola command file then the definition of that variable.

Substituting Actions

For example, suppose we want "Move Back" to move the cursor left and "Move Forward" to move the cursor right. We can specify that this way:
 

Vocola: Move (Back=Left | Forward=Right) = {$1};   Say: Move Back      Sent: {Left}  Say: Move Forward   Sent: {Right}

The alternative set "(Back=Left | Forward=Right)" means you can say either "Back" or "Forward", but the value substituted on the right hand side will be "Left" or "Right".

Here's another example. The Netscape Mailer has several options for sorting messages. This command allows you to change the sort by saying "Sort by Date", "Sort by Sender", or "Sort by Subject":
 

Vocola: Sort by (Date=e | Sender=r | Subject=s) = {Alt+v}o $1;   Say: Sort by Date     Sent: {Alt+v}oe   Say: Sort by Sender   Sent: {Alt+v}or

This alternative set allows you to say "Date", "Sender", or "Subject", and substitutes "e", "r", or "s" into the keystroke sequence.

Another common use of alternative sets with substitution is when you want to pick from a long list of specific items such as files, folders, or email addresses. For example, we can define the variable <EmailAddress> to contain a list of email addresses and shorthands to invoke them:
 

Vocola: <EmailAddress> := ( Bill = bsmith@mediaone.net                             | Dragon = info@dragonsys.com                             | Voice Coder = VoiceCoder@yahoogroups.com                             );           Address <EmailAddress> = $1 {Enter};  Say: Address Bill         Sent: bsmith@mediaone.net{Enter}  Say: Address Voice Coder  Sent: VoiceCoder@yahoogroups.com{Enter}

The command "Address <EmailAddress>" allows you to say, for example, "Address Bill" or "Address Voice Coder" to insert the desired email address. The list can be modified over time to add new addresses.
 

An alternative and its substitution (e.g. Dragon = info@dragonsys.com )  is actually a mini-command -- "when I say this, send these keystrokes". As with a command, the left-hand side may be an alternative set and the right-hand side may contain a sequence of actions. However, the left-hand side may not contain variables or ranges, and the right-hand side may not contain references.

Capturing Dictation

Sometimes you want a command which recognizes any words you might say rather than recognizing a particular set of alternatives. For example, searching for text is a common operation in Microsoft Word. It would be nice to be able to speak a single command to search for the text you want rather than needing to speak a command to open the "Find" dialog box, pausing, and then speaking the text you want to search for.

You can use the special variable <_anything> in a command to match any spoken words:
 

Vocola: Find Text <_anything> = {Ctrl+f} $1 {Enter};  Say: Find Text will do  Sent: {Ctrl+f}will do{Enter}

With this command you could search for the text "will do" by saying "Find Text will do", which opens the "Find" dialog box, enters the text "will do", and launches the search. (Note: if using this macro for Internet Explorer you need to call wait after the {Ctrl+f})

Note that <_anything> matches anything you say, including saying nothing. So in the above example saying "Find Text" would bring up the "Find" dialog box to search for nothing. Since this may be unexpected it's a good idea to use at least two keywords in these commands (i.e. Find Text <_anything> instead of Find <_anything>) to reduce unwanted recognitions.

<_anything> may appear anywhere a regular variable term appears, and may even appear more than once in a command.

Optional Words

Enclosing the optional word "Menu" in square brackets does the trick.

Note that optional words are not considered variable terms. Consider this example:
 

Vocola: [Move] Down 1..10 = {Down_$1};   Say: Move Down 1  Sent: {Down 1}  Say: Down 6       Sent: {Down 6}

Because the optional word "[Move]" is not considered variable, the range "1..10" is the first variable term and is referenced using "$1".
 

Note that a command must have at least one non-optional term.

Function Calls

Here are two simple examples:

The first example puts NaturallySpeaking in sleep mode when you say "Die Die". The second example clicks the mouse when you say "Hit Down".

The function HeardWord is useful for writing a command which invokes another command. Any command recognized by NaturallySpeaking may be invoked this way, whether it was defined in Vocola, NatLink, or the Dragon Macro Language.

For example, maybe you'd like to say "Kill Word" to delete a word rather than using the built-in NaturallySpeaking command "Delete Next Word", but you don't want to take the time to figure out the exact keystroke sequence. This command does the trick:

A command's actions can be a mix of keystroke sequences and function calls. For example, this command performs a "paste" at the current mouse location (saving you a mouse click):

Function arguments aren't always constant -- you can use a reference to a variable term as an argument to a function call. For example, this command allows you to copy a window's contents to either NaturallySpeaking or Emacs, by saying "Copy to NatSpeak" or "Copy to Emacs":

Here the result of the first variable term "(NatSpeak|Emacs)" is passed to the function AppBringUp to bring up the desired application.

Finally, a function argument can be built by concatenating more than one action. For example, the "Back" and "Forward" buttons in a Web browser use by convention the keystrokes Alt+Left and Alt+Right. In Lotus Notes these keystrokes only work when passed via the SendSystemKeys function:

When you say "Go Back", the function argument "{Alt+Left}" is constructed by combining the characters "{Alt+", the reference $1, and the character "}"

Built-in Functions

Vocola supports all scripting commands defined for the Dragon Macro Language, as well as adding some built-in functions. Here are the most useful functions in the combined set:

Here is the complete list:

The Dragon Macro Language documentation describes most of these functions (see pp. 74-115.) For those not so described, and for Vocola's built-in functions, see the descriptions below.

Eval

Repeat

SetNaturalText

ShiftKey

Defining Functions

Vocola supports user-defined functions as well as built-in functions. If you find yourself copying an action sequence for use in several commands, defining a function can make the commands more concise and understandable. (This is also possible using the built-in function HeardWord, but creating your own function makes for clearer code and faster execution.)

For example, in the Netscape/Mozilla mailer it's useful to define commands to move around in the "summary" window (which shows a one-line summary of each e-mail message). Here we define the function goToSummary to make sure the summary window has the focus:

goToSummary() := 
    SetMousePosition(4, 7)        # Window's bottom left edge
    SetMousePosition(2, 15, -45)  # Bottom left of folder list
    ButtonClick()                 # Folder list now has focus
    {Tab_3};                      # Summary pane now has focus

The left side of the definition specifies the function's name (goToSummary) and arguments (none in this case). The right side of the definition is a standard Vocola action sequence. Here we position the mouse over the bottom left corner of the mailer window, move up and to the right slightly to be over the folder list panel, click the mouse so the folder list has focus, and finally press the tab key three times so the summary window has focus.

Now we can define 3 commands using this function. Saying "Final Message" moves to the last message in the summary. Saying "First Unread" moves to the first unread message. And saying for example "Summary 3 Up" moves to the summary window and up three messages:

Final Message = goToSummary() {End};
First Unread  = goToSummary() {End}n;
Summary 1..20 (Up|Down) = goToSummary() {$2_$1};

Each of these commands uses our function goToSummary, making them shorter and clearer than if each had to include that function's actions explicitly.

Defining Functions with Arguments

You can also specify arguments when defining a function. For example, here's a function which switches to the nth application on the Windows taskbar:

switchToTaskBar(number) := SendSystemKeys( {Ctrl+Esc} )
                           {Tab_2}{Right_$number}{Left} " ";

This function, switchToTaskBar, is defined to take the single argument number (indicating which taskbar slot to switch to). {Ctrl+Esc} opens the start menu (just to get focus on the taskbar), and {Tab_2} moves to the first application. Then $number (referring to the function argument) is used to move right the specified number of slots. Finally, sending a "space" keystroke makes the selected application active. (Note that this function works in Windows XP -- a slightly different version is needed for Windows 2000.)

Now we can use this function in several commands. Let's say that Microsoft Word is the third application from the left on the taskbar. Saying "Switch to 3" makes Word the active application. Saying "Close 3" closes Word. And saying "Copy to 3" copies everything from the current application and switches to Word:

<n> := 1..20;
Switch to <n> = switchToTaskBar($1);
Close     <n> = switchToTaskBar($1) {Alt+F4};
Copy to   <n> = {Ctrl+a}{Ctrl+c} switchToTaskBar($1);

Each of these commands uses the variable <n> to specify a number between 1 and 20, which is then passed to the switchToTaskBar function to specify the target application.

Multiple Arguments and Nested Function Calls

Here's another example, defining two functions which each take 2 arguments. First is the function moveBy, which moves the mouse a distance (x,y) from the current position. Note that it uses the built-in Vocola function Eval to multiply each coordinate by 15, providing more convenient units than pixels. (I have rulers taped to my screen in these units, thanks to Kim Patch's idea. With this approach you can place the mouse anywhere on a large screen by speaking only 2-digit numbers, which are recognized much more reliably than 3-digit numbers. See the file _vocola.vcl in the shipping Vocola samples for more examples.)

moveBy is used twice by the next function, moveWindowBy, which moves the current window a specified distance (x,y) in these same 15-pixel units.

moveBy(x,y) := SetMousePosition(2, Eval(15*$x), Eval(15*$y));

moveWindowBy(x,y) :=
    SetMousePosition(4,1)  # Top window edge, center
    moveBy(0,1)            # Down into title bar
    RememberPoint()        # Store initial drag point
    moveBy($x,$y)          # Move by given amount
    DragToPoint();         # Do the drag

Note again that a function's arguments may be referenced in its action sequence using "$". That's $x and $y in these functions.

Now here are two commands using moveWindowBy, allowing you to say for example "Window 10 Up"or "Window 20 Right" to move the current window:

<n> := 0..99;
Window <n> (  Up='-' |  Down='+') = moveWindowBy(0, $2$1);
Window <n> (Left='-' | Right='+') = moveWindowBy($2$1, 0);

Note here how a function argument can be built from two variables. When you say "Window 10 Up", the first variable term <n> has the value "10" and the second variable term has the value "-". These are concatenated by the double reference $2$1 to form the final function call moveWindowBy(0, -10).

Contextual Commands

We've discussed how to create "global" commands (which are always enabled) as well as application-specific commands (which are enabled only when a particular application is active). In addition, you can create contextual commands, which are enabled only when a particular window has the focus.

By specifying all or part of the window title in a context statement you can create commands specific to that window. For example, here are three groups of commands for Microsoft Outlook (from the application-specific command file "outlook.vcl"): 

The context statement "Microsoft Outlook:" specifies that subsequent commands should be active only when "Microsoft Outlook" is part of the title of the active window. When reading mail using Outlook the main window title is "Inbox - Microsoft Outlook", so the first group of commands above (to create, reply to, or forward a message) will be enabled.

Similarly, when editing a mail message the window title is "Message (Plain Text)", so the second group of commands above will be enabled. Finally, the third group of commands above will be enabled when the Outlook calendar is displayed.

Here is another example. The text editor application Emacs can be customized so that the window title includes the name of the currently-edited file. For example, when editing iexplore.vcl (the file of Vocola commands for Internet Explorer) the Emacs window title is "Emacs - iexplore.vcl - 01.05.02". This allows defining a set of contextual commands for editing Vocola files. The application-specific command file "emacs.vcl" would include:

 ### Editing Vocola files
 .vcl:
   Insert             <key> = {$1       Wait(0) }; 
   Insert       <mod> <key> = {$1+$2    Wait(0) }; 
   Insert <mod> <mod> <key> = {$1+$2+$3 Wait(0) }; 
 
 ### Editing Perl files
 .pl:
   New Statement = {Ctrl+e}{Ctrl+j};
   New Statement Above = {Ctrl+a}{Ctrl+b}{Ctrl+j}; 
   Insert Hash Reference = ->{}{Ctrl+b};

So for example when the Emacs window title contains ".vcl", saying "Insert Shift Tab" inserts the text "{Shift+Tab}" into the file. These commands allow speaking keystroke sequences when writing Vocola code. (The variable definitions for <mod> and <key> are omitted here, but available with the Vocola distribution.)

Similarly, the second group of commands above is active only when editing Perl files.

Global Contextual Commands and Multiple Context Choices

Contextual commands don't need to be application-specific. You can also create global contextual commands, as in this example from the global command file "_vocola.vcl":

This defines two commands for use in a "File Open" dialog box, regardless of the current application. Whenever the window title includes the word "Open", you can say "Go Up" to move to the parent folder or "Folder List" to open the folder hierarchy drop down at the top of the dialog.

As it happens, "File Chooser" dialog boxes appear with a wide range of titles, such as "Open File", "Save As", "Browse for Folder", etc. Ideally we want the same set of context-specific commands to be available for all such dialogs. Vocola supports this by allowing the "|" character in context statements. Here is the full set of context titles and commands I use:

Include Statements

For example, many applications need to navigate the file system to find specific files or folders. But speaking pathnames can be difficult, as can navigating through folder hierarchies by voice. What you'd really like to do is define a single list of shortcuts to interesting folders, and have that list available in any program which needs to navigate the file system.

I've created a file called "folders.vch" ("vch" stands for "Vocola header") to contain my personal list of interesting folders, defined as a Vocola variable:

<folder> := 
 ( Home       = C:\Rick
 | Temp       = C:\Temp
 | Downloads  = C:\Programs\Downloads
 | Start Menu ="C:\Documents and Settings\Rick Mohr\Start Menu"
 | Vocola     = C:\Programs\NatLink\Vocola
 | NatLink    = C:\Programs\NatLink\MacroSystem
 );

With the Vocola "include" statement this list can be used in several Vocola command files. Here's part of my command file for Windows Explorer:

So for example, saying "Folder NatLink" to Windows Explorer switches to the folder "C:\Programs\NatLink\MacroSystem".

The folder list is also useful in a Command Prompt (DOS box), where saying for example "Folder Temp" performs the command "cd C:\Temp":

Last and perhaps most useful is the following global command to move quickly to a specific folder in a "File Open" dialog box:

This global contextual command is active when the window title of any application contains one of the words shown. For example, when saving an attachment in Microsoft Outlook the window title is "Save Attachment", so saying "Folder Temp" switches the dialog's current folder to "C:\Temp".

Include using a variable filename

The "include" statement's filename can be varied using references to environment variables. For example, you might have a different set of interesting folders at home than at work, and so want to include a different file depending on which machine you are currently using. Since the environment variable "COMPUTERNAME" contains the name of your machine, you could say:

include folders_$COMPUTERNAME.vch;

If your work machine were called "Venus" and your home machine were called "family", you would define your list of interesting folders in two separate files, "folders_Venus.vch" and "folders_family.vch".

Comments

Using comments in your Vocola command files can help you or somebody else understand the sometimes-cryptic keystroke sequences.

Example File

It contains commands for reading email, composing email messages, and editing HTML files, activated contextually by the window title. It contains simple one-line keystroke commands, some longer keystroke commands, several "alternative set" commands with substitutions, a variable definition, and a few function calls mixed in.
 

# Voice commands for Netscape 4   ### Reading email  Netscape Folder:    New Message      = {Ctrl+m};    Reply to Message = {Ctrl+r};    Reply to All     = {Ctrl+Shift+r};    Forward Message  = {Ctrl+l};    Print Message = {Ctrl+p}{Tab_6}1{Enter};    Search Messages = {Ctrl+Shift+F};    Sort by (Date=e | Sender=r | Subject=s) = {Alt+v}o $1;    # Choose HTML editor or plain text editor    Use (HTML={Up} | Plain Text={Down}) =         "{Alt+e}e{Shift+Tab}{Down 8}{Tab}$1{Enter}";    # Extract a file pathname from a mail message    Get File Name =         {Ctrl+l} Wait(500)           # Open a "forward" window        {Enter_2}                    # Move to message body        {Ctrl+f}:\{Enter}{Esc}       # Search for ":\"        {Left_3}{Shift+End}{Ctrl+c}  # Copy entire pathname        {Alt+F4};                    # Close the window  ### Composing email messages  Composition:    <EmailAddress> := ( David = dsmith@netscape.com                      | Emily = egreene@aol.com                      | Mike  = mike@orangerooster.com                      | Sue   = suenew@brown.net                      );    Address <EmailAddress> = $1 {Enter};    Cc <EmailAddress> = "{Shift+Tab} {Down 2}{Enter}$1{Enter}";     Send That = {Ctrl+Enter};    I Meant Reply All =        {Ctrl+Home}{Ctrl+Shift+End}{Ctrl+c}  # Copy message        {Alt+F4}n                            # Close window        {Ctrl+Shift+r};                      # Reply to All  ### Editing HTML documents  Netscape Composer:    Save (File|That) = {Ctrl+s};    Save and Close   = {Ctrl+s}{Alt+F4};    Show Preview     = {Ctrl+s} AppBringUp(iexplore) {F5};    Fixed    Width [Font] = {Alt+o}{Right}{Down}{Enter};      Variable Width [Font] = {Alt+o}{Right}{Enter};      Style Normal         = {Alt+o}p{Enter};    [Style] Heading 1..6 = {Alt+o}h $1;    Promote That = {Ctrl+-};    Demote That  = SendSystemKeys("{Ctrl+=}");

 
 

Command Sequences

You can configure Vocola to allow speaking several commands in a row without pausing. For example, assume your commands allow you to say:

"3 Words Right"		to move the cursor 3 words to the right,
"2 Right"		to move the cursor 2 characters to the right, and
"Kill Char"		to delete 1 character.

If you wanted to speak these three commands in succession you would normally have to pause between commands, saying

"3 Words Right" (pause) "2 Right" (pause) "Kill Char".

"3 Words Right 2 Right Kill Char".

Once you get used to speaking command sequences, text editing by voice becomes faster and less frustrating.

Warning: A bug introduced in Dragon NaturallySpeaking 7.0 and worsened in 8.0 can cause unacceptable performance if command sequences are enabled. With 7.0 switching to or from an application becomes slow if a large number of commands are defined for the application. With 8.0 users have reported that command recognition is very slow even when only a few commands are defined.

Because of these NaturallySpeaking bugs (which ScanSoft has essentially refused to fix), Vocola command sequences are disabled by default and not recommended with version 8.0. Personally I find them so productive that I've stayed with NaturallySpeaking 6.0.

How to Enable and Disable Command Sequences

To enable command sequences (in Vocola 2.5 or later), open the file:

NatLink\Vocola\Exec\vocola.ini

and modify it to contain the line:

Use Command Sequences=1

Then say "Load All Commands".

To disable command sequences, proceed as above but with the line:

Use Command Sequences=0

Caveats

Note that only commands defined in the same file can be spoken in sequence. For me this causes occasional mistakes but is not a major limitation. And using include files can help. For example, if you find you want to sequence some of your global commands with commands local to Microsoft Word, you could put the global commands in a separate .vch file and include that file in both word.vcl and _vocola.vcl.

You might think command sequences would lead to mistakes when an unexpected combination of commands is recognized, but in practice I have not found this to be the case. It's a good idea to avoid single-word commands, but that's a good idea anyway.

Install Vocola

Use the following instructions for your first installation of Vocola.
Or, see below to upgrade from an earlier version of Vocola.

Installing Vocola for the first time

1. Install Dragon NaturallySpeaking, version 3.5 or later, any edition.

 
2. Install Python. Version 2.3 is recommended, with 2.0 and 2.2 also supported. Earlier versions are not supported.
    
3. Install NatLink and Vocola.
• If you have Python 2.3, use Scott Weinstein's installer to install NatLink and Vocola simultaneously.
• Otherwise, download NatLink for Python 2.2 or NatLink for Python 2.0, and follow Joel Gould's instructions (don't bother with the self-tests, which often fail). Then install Vocola.
   
4. Associate the .vcl file extension (used for Vocola command files) with your favorite text editor. This allows you to open your Vocola files using built-in voice commands. An easy way to set up this association is to right-click on any .vcl file (such as Vocola\Samples\notepad.vcl), select "Open With" or "Open", and pick your favorite text editor (for example, Notepad).
   
   Note that Scott's installer associates the .vcl file extension with the free editor Notepad2, which it also installs.
   
   Emacs users should install gnuserv and associate the .vcl file extension with gnuclientw.exe. (Make sure the directory containing gnuclientw.exe is included in your PATH environment variable.)
    
5. Test Vocola. 
• Copy the sample command file for Notepad (Vocola\Samples\notepad.vcl) to the Vocola\Commands folder. 
• Say "Start Notepad" to launch Notepad.
• Say "Test Simple Command". The phrase "It works!" should appear.
• Say "Edit Voice Commands". Vocola\Commands\notepad.vcl should be opened using the editor you picked in step 4.
• Change the "Test Simple Command" command to type "It really works!"
• Save the file, say "Switch to Notepad", and say "Test Simple Command". "It really works!" should appear.

Upgrading from an Earlier Version of Vocola

If you originally installed NatLink + Vocola using Scott Weinstein's installer, you must upgrade using the latest version of that installer. The installer will detect if there is an older version, and upgrade correctly. (You can't change any installed files manually because the current version of the installer automatically changes them back when you start NatSpeak.)

If you originally installed Vocola directly you can either switch to the installer or follow these steps:

1. Rename your existing Vocola folder (it's in your NatLink folder)
2. Install Vocola as described below.
3. Copy all files from your old Vocola/Commands folder to your new Vocola/Commands folder
4. Restart NatSpeak

Installing Vocola Directly 

1. Download the Vocola zip file.
    
2. Extract the Vocola zip file into the NatLink directory. For example, if you installed NatLink in C:\NatLink, you should choose C:\NatLink as the folder to extract to. After unpacking you should see folder C:\NatLink\Vocola, with subfolders Commands, Doc, Exec, Samples, and Simpscrp.
    
3. From the Vocola\Exec folder, copy the files _vocola_main.py and VocolaUtils.py to the NatLink\MacroSystem folder. This activates Vocola's built-in voice commands.

Vocola Versions

This page lists the released versions of Vocola and the changes they included, with the most recent version first. To download Vocola, click on the link next to the version you want.

Version 2.5 -- January 10, 2005 (Vocola-2-5.zip)

• Commands can incorporate arbitrary dictation. See Capturing Dictation.
• Allow disabling/enabling the command sequences feature (and disable it by default), to avoid performance problems caused by bugs in NaturallySpeaking 7.0 and 8.0

Version 2.4 -- September 28, 2003 (Vocola-2-4.zip)

• Fixed problem with some installations where vcl2py.exe failed to run, and perpetually raised a blank message window.
• Fixed problem where "Edit Voice Commands" (with some editors) did not allow editing commands by voice.

Version 2.0 -- June 7, 2003

• Speak continuous command sequences
• Automatic loading of changed files, with error messages to NatLink window
• User-defined functions
• include statement
• Eval built-in function
• Repeat built-in function
• Context statements can contain '|'
• Function arguments can be built from several actions
• Numeric arguments now work correctly in all built-in functions
• Improved generated Python code (using VocolaUtils.py)
• Case insensitive window title comparisons
• Obscure name for generated python file ("outlook_vcl.py") to avoid clobbering existing NatLink files

Version 1.1 -- May 11, 2002 (Vocola-1-1.zip)

• First public release.
• Installing Perl is no longer required.
• Commands containing backslash sequences like  \;  or  \"  or  \'   are now parsed correctly.
• Application-specific commands are now recognized for applications whose name contains an underscore character.

Converting DVC Files

Troubleshooting

My command doesn't work

1. You didn't save the .vcl file.

 
2. Your command had a syntax error.
• Vocola reports errors in the NatLink output window, a small window titled "Messages from Python Macros".
• Read the error message, correct the problem, save the file, close the NatLink window, and try your command again.
 
3. You're speaking the command in a different context than you defined it for.
• Make sure you put the command in the .vcl file for the application you're running.
• If your command appears within a context statement, make sure the context string matches the title of the current window.

 
4. You changed an include file (.vch) and didn't run the Vocola translator by saying "Load Voice Commands".
    
5. NatLink didn't load the translated Python file.
   • Look in the NatLink\MacroSystem directory. There should be both a .py file and a .pyc with the same name as your .vcl file.
   • If the .pyc file is older than the .py file, and you really have talked at the correct application, then NatLink has not noticed the .py file. There are two possible reasons:
   • You have created a new global command file (one beginning with underscore, "_"). NatLink does not notice these.
   • NatLink or NatSpeak is in a bad state.
   • In either case, you need to exit and restart NatSpeak.

My command doesn't work right

1. Another command is being executed instead.
• You may have defined a command with the same words using another voice command language. It's a good idea to delete these.
• You may have defined a global command and an application-specific command with the same words. Usually the application-specific command will be recognized, but occasionally the global command is recognized instead. Usually if you repeat the command the application-specific version will be recognized.
  


2. You need to use quotation marks in your Vocola command. Quotation mark delimiters are usually optional in Vocola, but are required in some cases:
• when whitespace is significant, e.g. "{Left 2}"
• when keystrokes to enter contain special characters

Support

Known Bugs

• A bug introduced in Dragon NaturallySpeaking 7.0 and worsened in 8.0 can cause unacceptable performance if command sequences are enabled. ScanSoft has thus far refused to address the problem, so if you're experiencing a slowdown your options are to disable command sequences or use an earlier NatSpeak version such as 6.0.

Email

I'm hoping to keep this address away from junk e-mailers, so if for some reason you are posting information about Vocola please use the web page address (http://home.comcast.net/~vocola) rather than this e-mail address.

Wish List

Here is a list of potential Vocola enhancements. Let me know if any of these are particularly important to you.

New built-in functions:

• ExecutePreviousCommands(howManyCommands, howManyTimes)
• WaitForWindow(titleContains, timeout), which waits until the main window has a particular title
• Functions to save and restore the current mouse position
• Function like ShellExecute(), but which doesn't return until the command has completed

Language improvements:

• Keystroke sequences using "Windows" modifier key (e.g. {Win+e} to start Windows Explorer)
• Context statement ":" clears any existing context
• Allow variables in alternative sets (e.g. <direction> | foo | bar)
• Allow default values in alternative sets
• Repeatable terms (e.g. Press <modifier_key>+ <key> = ...)

Other:

• Option to store command files in user-specified folder(s)

My RSI Story

In March 1998 I worked an entire weekend to meet a major deadline with important revenue consequences for my employer. By Sunday night my wrists and hands were tingling and sensitive, and the next day I had significant wrist pain. In previous years I had had minor symptoms, but they had always gone away.

I knew to treat my injury seriously since I have friends with debilitating RSI problems. But, I was starting at square zero in terms of knowledge and treatment, and still in the middle of a high-pressure work situation. As I began to realize my injury was serious I started searching for solutions. Everyone I talked to had different ideas, and every idea seemed to involve 30-90 minutes a day of work on my part. I could handle the regimen of one or two of these, but in the absence of real progress it was hard to have confidence. In the subsequent months I tried doctors, occupational therapy, anti-inflammatories, massage, a new chair, acupuncture, rolfing, special keyboards, physical therapy, drinking lots of water, chiropractic, vitamins, myotherapy, and glucosamine sulfate. Nothing seemed to make a reliable difference.

Meanwhile my company was supportive and willing to provide what I asked. But while it was easy to ask for new equipment and small schedule accommodations, I couldn't bring myself to ask for major time commitments from other people or major project slippage. I adjusted all my habits to require as little typing is possible, but continued to type when necessary (occasionally a considerable amount).

Unfortunately it took a year of this before I began using voice recognition and started truly resting my hands. I can't know for sure, but I believe that had I started using voice recognition right away I would have recovered. During several periods I've made significant recovery, but despite vigilance in most every activity I have always slipped up. Once it was snow shoveling, once un-careful fiddling, and once not-wimpy-enough weightlifting in a strengthening program. Of all the things I have tried, the only ones that have reliably helped are avoiding irritating activities and voice recognition. Of some help have been stretching, posture improvement, myotherapy, and massage.

Since resting my hands seemed so important I tried for hands-free computer use as much as possible. The Dragon Macro Language made this possible but was excruciatingly cumbersome, so I was very excited when Joel Gould released NatLink. Shortly thereafter (at NEFFA) Patricia Hawkins and I were comparing notes about NatLink. Her comment "yeah, but you still have to change two places" got me thinking about Vocola.

Designing, implementing, and using Vocola has been a rewarding bright spot among otherwise unsuccessful attempts at recovery. And thankfully, with Dragon NaturallySpeaking, NatLink, and Vocola I've continued to be effective at my job.

The main lesson I take away is to stand up for my own needs when they conflict with the needs and desires of others. That Monday deadline seemed very important at the time, but everybody would have survived just fine if I had delivered a week later. The customer was adamant about the deadline, but as it happens they ultimately canceled the project! And even after my initial injury, if I had been brave enough during the first year to ask for difficult adjustments at work I might have been able to recover quickly.

One doctor I saw said "With constant vigilance you can get a little better every year" and at this writing (December 2004) things are looking up somewhat, I'm starting to type a little and play some careful fiddle.

Rick Mohr, Watertown, Massachusetts, USA, December 2004

Voice Resources

Web Sites

• ScanSoft Dragon NaturallySpeaking - The official purchase and support site for NatSpeak.
• NaturallySpeaking Unofficial Information Pages - Joel Gould was the lead architect of NatSpeak and the developer of NatLink. This is his site, including pages on NatLink and useful information about NatSpeak. No longer being updated, but still useful.
• NatLink-related utilities developed by NatLink users - A collection of useful NatLink voice commands coordinated by Jonathan Epstein. Vocola coexists happily with these.
• Kim Patch's Macros - A large set of macros for NatSpeak Pro 5 (free) or 6 ($24). Full of good voice command ideas, many of which are reflected in the sample Vocola commands.
• Speech.squidnet.com - Scott Weinstein's Speech Recognition WIKI, including a NatLink + Vocola installer.
• SpeechUtilities.com - David Austin's site, with help for getting the most out of the NatSpeak macro languages. If you decide to stick with these, get here the superior command browser "SayWhat".
• Ruth Rose's NatSpeak Site - Useful suggestions for getting the most out of NatSpeak
• Computing Out Loud - Susan Fulton's general-purpose voice recognition site with information and links.
• Windows Keyboard Shortcuts - Microsoft site with thorough description of keyboard shortcuts by Windows version or product.
• Typing Injury FAQ - Resources for injured typists.

Mailing Lists

• VoiceGroup - General discussion of voice recognition issues, mostly NatSpeak related. Lots of traffic.
• VoiceCoder - Good quality list for programmers using voice recognition.
• NatPython - NatLink discussion, low-volume with some Vocola traffic.
• NatPro Macro Writers - Discussion of NatSpeak macros, particularly advanced scripting commands.
• ScanSoft Public Forum - Public NatSpeak discussion list at ScanSoft.