Introduction

Introduction to VocolaVocola is a voice command language--a language for defining commands to control a computer by voice. It was developed for use with Dragon NaturallySpeaking and implemented using Joel Gould's NatLink package. Vocola (pronounced "vo-CO-luh") builds on the strengths of both these systems, using the keystroke syntax and built-in functions from the Dragon Macro Language and a grammar syntax similar to NatLink. 

(I wish to acknowledge and appreciate Joel Gould for his time and care in designing, building, and "productizing" NatLink, which enabled and inspired Vocola.)

Examples

Vocola's main benefits are conciseness and ease of use. For example, here are four voice commands defined in Vocola:

 Copy That = {Ctrl+c};

 Copy to NatSpeak = {Ctrl+a}{Ctrl+c} AppBringUp(NatSpeak);

 1..40 (Left | Right | Up | Down) = "{$2 $1}";

 Sort by (Date=e | Sender=r | Subject=s) = {Alt+v}o $1;


The first is a simple keystroke command -- saying "Copy That" sends the keystroke Control-C, which copies the current selection to the clipboard. The great majority of commands needed for controlling a computer by voice are simple keystroke commands like this. 

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 unfortunately 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 600 Vocola commands.

The Dragon Macro Language (used in NatSpeak through version 5) and the newer VisualBasic-based language (introduced in version 6) both provide the necessary ingredients for writing voice commands. But, both are cumbersome to use. Simple commands consume multiple lines, and it is hard to write them quickly, keep them organized, and keep track of what you have defined.  Joel Gould's NatLink system is a great improvement. Commands are more flexible, easier to organize, and are reloaded instantly. And the Python base language brings the power to program rich behaviors. But the trade-off is that a simple command still consumes four lines instead of one, is split in two locations, and shares the command file with the Python plumbing which makes it work.

In Vocola most commands consume one line. Besides easy creation, this also makes it easy to see what commands you have defined. And because Vocola commands are translated into NatLink they benefit from the quick reloading and careful engineering of that system, and can coexist with existing NatLink commands.

Main Features

Here's a summary of important Vocola features:

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

Using Vocola

How to Create and Load Voice Commands

The easiest way to create Vocola commands is by voice. You can use Vocola's built-in commands to open the right files for defining commands which control the current application or all applications.

What you say
What happens How it works
"Edit Voice Commands"
or
"Edit Commands"
Opens the Vocola file defining commands for the currently running application (using your favorite editor). If app.exe is the currently running application, opens the file app.vcl (using the application associated with the ".vcl" extension).
"Edit Global Voice Commands"
or
"Edit Global Commands"
Opens the Vocola file defining commands for all applications (using your favorite editor). Opens the file _vocola.vcl (using the application associated with the ".vcl" extension).

After editing a command file you can load it using this built-in Vocola command:
 
What you say
What happens How it works
"Load Voice Commands"
or
"Load Commands"
Activates all commands in the Vocola command files you have created. (Displays any errors using your favorite editor.) Converts each Vocola file (.vcl) in the NatLink/Vocola/Commands directory to a NatLink Python file (.py) in the NatLink/MacroSystem directory (by running vcl2py.pl). If errors are encountered, the error log file (vcl2py_log.txt) is opened (using the application associated with the ".txt" extension).

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:

What you say
What happens How it works
"Edit Machine Voice Commands"
or
"Edit Machine Commands"
Opens the Vocola file defining commands for the currently running application on the current computer (using your favorite editor). If app.exe is the currently running application and machine is the current computer name, opens the file app@machine.vcl (using the application associated with the ".vcl" extension).
"Edit Global Machine Voice Commands"
or
"Edit Global Machine Commands"
Opens the Vocola file defining commands for all applications on the current computer (using your favorite editor). If machine is the current computer name, opens the file _vocola@machine.vcl (using the application associated with the ".vcl" extension).

File Organization and Naming

If you don't want to use the built-in commands, or if you want to understand the underlying organization they depend on, here are the relevant conventions:

Language Tutorial

Vocola Tutorial The following sections present the Vocola language in detail, with examples:

Keystroke Commands

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":
 
 Vocola: Hello World = Greetings; 
 Say: Hello World Sent: Greetings 

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:
 
 Vocola: Copy That = {Ctrl+c}; 
 Say: Copy That Sent: {Ctrl+c}

The Vocola syntax for specifying modifier key sequences such as {Ctrl+c} is borrowed from the Dragon Macro Language, which describes the syntax.
 
Each Vocola command contains a series of terms (indicating what is said) and a series of actions (indicating what is done), separated by "=" and terminated by ";". In this section the terms are words and the actions are keystrokes; later sections introduce other possibilities.

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 mail program to use its HTML editor (rather than the plain text editor) for composing messages:
 
 Vocola: HTML Editor = "{Alt+e}e{Shift+Tab}{Down 8}{Tab}{Up}{Enter}"; 
 Say: HTML Editor Sent: {Alt+e}e{Shift+Tab}{Down 8}{Tab}{Up}{Enter}

Here's how it works:
 
 {Alt+e}Open the "Edit" menu

eChoose the "Preferences..." menu item, raising the Preferences panel

{Shift+Tab} Move back one field in the panel, to the "Category" list

{Down 8}Move down 8 lines, to the "Formatting" category

{Tab}Move forward one field in the panel, to "Message formatting"

uChoose the top radio button ("Use the HTML editor to compose messages")

{Enter}Hit the "OK" button

Quotation Marks and Whitespace

Quotation marks are optional around keystroke sequences. For example, the following commands are equivalent, specifying one action (the keystroke sequence {Ctrl+a}{Ctrl+c}):
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.

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

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

Using Alternatives

Alternatives And References Sometimes you will want to create a group of similar commands. Instead of creating a separate command for each, you can often write a single command which works for the whole group.

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 keystrokes "{Left}" are 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".

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

Defining Variable Terms If you want to re-use an alternative set in several different commands, you can assign it to a variable. For example, we can create a variable called <direction> to hold the alternatives "Left | Right | Up | Down", and use it in a command:
 
 Vocola: <direction> := Left | Right | Up | Down; 
         Move <direction> = {$1}; 
 Say: Move Left  Sent: {Left} 
 Say: Move Down   Sent: {Down} 

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

Substitutions So far the spoken words in our alternative sets have been substituted directly into our keystroke sequences. Actually it is more commonly useful to substitute a different set of keystrokes than the spoken words.

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.


Function Calls

Function Calls Not everything can be accomplished with keystroke sequences -- Vocola commands can also include calls to system functions. When writing commands for Dragon NaturallySpeaking, all system functions defined for the Dragon Macro Language are available.

Here are two simple examples:
 
 Vocola: Die Die = GoToSleep(); 
         Hit Down = ButtonClick(1,1); 

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:
 
 Vocola: Kill Word = HeardWord(Delete,Next,Word); 

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):
 
 Vocola: Paste Here = ButtonClick(1,1) {Ctrl+v}; 

Finally, 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":
 
 Vocola: Copy to (NatSpeak|Emacs) = {Ctrl+a}{Ctrl+c} AppBringUp($1); 

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


Optional Words

Optional Words Sometimes you want to create a command with optional words. For example, you might want to be able to say either "Hit Start Menu" or just "Hit Start" to bring up the Windows Start Menu:
 
 Vocola: Hit Start [Menu] = SendSystemKeys({Ctrl+Esc}); 
 Say: Hit Start Menu  Sent: {Ctrl+Esc}
 Say: Hit Start       Sent: {Ctrl+Esc}

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.


Comments

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

Comments in Vocola are specified by the "#" character. Anything on a line following a "#" character is ignored by the command parser. Here is an example:

 # Extract a file pathname from a Netscape 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




Contextual Commands

Vocola Tutorial: Enable by Context

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"): 

 Microsoft Outlook:
   New Message = {Ctrl+n};
   Reply to Message = {Ctrl+r};
   Reply to All = {Ctrl+Shift+r};
   Forward Message = {Ctrl+f};

 Message (Plain Text):
   Send That = {Alt+s};
   Reply Here = "{Home}{Shift+End}{Del}{Enter 3}{Left 2}";

 Calendar:
   View Month = {Alt+m};
   View Work Week = {Alt+r};

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 Control Key = {Ctrl+;
   Insert Alt Key = {Alt+;
   Save and Load = {Ctrl+x}{Ctrl+s} HeardWord(Load, Voice, Commands);

 ### Editing Perl files
 .pl:
   Insert Hash Reference = ->{}{Ctrl+b};
   New Statement = {Ctrl+e}{Ctrl+j};
   New Statement Above = {Ctrl+a}{Ctrl+b}{Ctrl+j};
   Statement (Start="" | Down={Ctrl+n} | Up={Ctrl+p}) = $1 {Ctrl+a}{Ctrl+i};

So for example when the Emacs window title contains ".vcl", saying "Save and Load" will save the current file and invoke the "Load Voice Commands" command. (This allows quick loading of commands you have created).

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

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

 Open:
   Go Up = ..{Enter};
   Folder List = "{Shift+Tab 2}{Down}{PgUp}";

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.


Example File

Example File Here's a longer example of a Vocola command file, taken from my "netscape.vcl" file for controlling the various Netscape applications.

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+=}");


 
 


Download Vocola

Download And Install 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 1.1 -- May 11, 2002 (Vocola-1-1.zip)

Install Vocola

Install Vocola Follow these instructions to install Vocola:
  1. Install Dragon NaturallySpeaking, version 3.5 or later, any edition.

  2.  
  3. Install Python and NatLink. Follow Joel Gould's instructions. NatLink version 007 or greater is recommended, though Vocola has worked since version 004. Note: make sure to install Python version 2.0 (or 1.5). NatLink does not work with later versions.

    If you are already a NatLink user, be aware that Vocola creates command files in the NatLink\MacroSystem folder. If for example you already have a NatLink file called notepad.py, you should rename it to something like notepad_natlink.py before creating Vocola commands for Notepad.


  4. Download the Vocola zip file.


  5. Unpack the Vocola zip file into the NatLink directory. For example, if you installed NatLink in C:\NatLink, you should install Vocola in C:\NatLink\Vocola. After unpacking you should see subfolders Commands, Doc, Exec, and Samples.

  6.  
  7. Copy Vocola\Exec\_vocola_main.py to the NatLink\MacroSystem folder. This activates Vocola's built-in voice commands.

  8.  
  9. 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 do this is shift-right-click on any .vcl file (such as Vocola\Samples\notepad.vcl), select "Open With", and pick your favorite text editor (for example, Notepad).
  10. 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.)

  11. Test Vocola. 

Converting DVC Files

Converting DVC Files If you have created voice commands using the Dragon macro language you may want to jumpstart your repertoire of Vocola commands using the utility Perl script dvc2vcl.pl, found in the folder Vocola\Exec. Note: this utility is  provided "as is". You are welcome to make improvements.

This utility converts many commands correctly, handling keystroke sequences, function calls, word arguments, lists, and lists with substitution. Most of my 200+ macros converted fine, with some manual cleanup required for the rest. If the utility cannot handle a particular command construct it is replaced with "[]" and the resulting command is commented out.

The utility takes two arguments -- an input folder containing Dragon voice command files (*.dvc), and an output folder to contain Vocola files (*.vcl). For example, the script might be invoked as follows (assuming Vocola is installed in C:\NatLink\Vocola and NatSpeak is installed in C:\NatSpeak):

cd C:\NatLink\Vocola
perl Exec\dvc2vcl.pl C:\NatSpeak\Users\Rick\current Commands

Each .dvc file in the input folder C:\NatSpeak\Users\Rick\current is converted to one or more .vcl files, which are written to the output folder C:\NatLink\Vocola\Commands. Global commands are written to the file _vocola.vcl, and application-specific commands for an application named foo.exe are written to foo.vcl.

If you have added commands to the default Dragon command file global.dvc, you may want to make a copy of the file and delete the Dragon-supplied commands so that you only convert your own commands. There's no particular value in converting the Dragon-supplied commands to Vocola.


Troubleshooting

Troubleshooting Writing Vocola commands is straightforward with a little practice. Problems can however arise at several levels, since your Vocola command is translated by a Perl program into a Python program, which uses the NatLink system to interface with Dragon NaturallySpeaking. This page summarizes some potential problems, and how to solve them.

My command doesn't work

You've written a Vocola command but nothing happens when you speak the command. Here are some possible causes:
  1. You didn't save the .vcl file.

  2.  
  3. You didn't run the Vocola translator by saying "Load Voice Commands".

  4.  
  5. Your command had a syntax error.
  6. You've hit one of the known bugs.
  7. You're speaking the command in a different context than you defined it for.
  8. NatLink didn't load the translated Python file.
  9. NatLink doesn't like Vocola's translation of your command.
  10. NatLink can't tell what application you're running.

"Vocola cannot determine application"

Due to a bug in NatSpeak version 4 (and some version 5's), especially under Windows 2000, you can sometimes get into a state where no application-specific commands are recognized. In this state, the "Messages from Python Macros" window contains the persistent message "Vocola cannot determine application, app-specific commands disabled". This bug was fixed in NatSpeak version 6.

After long observation of this problem I have these suggestions:

My command doesn't work right

Your command gets executed, but doesn't work correctly. Here are some possible causes:

Support

Support I will do my best to fix Vocola problems, but as usual with free software supported in spare time I make no guarantees. Before e-mailing, please consult the Language Tutorial, the section on Troubleshooting, and the list of known bugs below. I wrote this documentation with you in mind, so please read it and try to solve your problem before contacting me.

Known Bugs or Limitations

The following problems are known to exist in Vocola 1.1:

Email

Send bug reports and other feedback by clicking on the button below. Please indicate what version of Windows, NatSpeak, and Vocola you are running.

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.attbi.com/~vocola) rather than this e-mail address.


Wish List

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

My RSI Story

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. I may yet recover, but at this writing (February 2002) I still cannot do any significant typing or play much violin. My diagnosis is tendinitis, and my prescription is "With constant vigilance you can get a little better every year." 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, myotherapy, and voice recognition.

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.

Rick Mohr, Watertown, Massachusetts, USA, February 2002