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:
- Simple, concise command syntax
- Most commands are one-liners
- Easy to see what commands you have defined
- Expressive
- Easy to specify different actions based on variable words
- Inline word lists and substitutions
- Support for number ranges and optional words
- Familiar syntax
- Uses keystroke syntax and built-in functions from Dragon Macro
Language
- Similar grammar syntax to NatLink
- Easy to use
- Open command files by voice control
- New commands usable in 1-2 seconds
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:
- 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.
Language Tutorial
Vocola Tutorial
The following sections present the Vocola language in detail, with examples:
- Keystroke Commands: When I say this, send these keystrokes.
- 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.
- Function Calls: Call built-in functions.
- Optional Words: Option to omit words when invoking a command.
- Contextual Commands: Create commands active only for particular
windows.
- Comments: Put comments in your Vocola command files.
- Example File: A longer example of a Vocola command file.
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 |
| e | Choose 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" |
| u | Choose 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)
- First public release.
- 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.
Install Vocola
Install Vocola
Follow these instructions to install Vocola:
- Install Dragon NaturallySpeaking, version 3.5 or later, any edition.
- 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.
- Download
the Vocola zip file.
- 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.
- Copy Vocola\Exec\_vocola_main.py to the NatLink\MacroSystem folder. This activates Vocola's built-in voice
commands.
- 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).
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.)
- Test Vocola.
- Launch NaturallySpeaking if it is not already running.
- Copy the sample command file for Notepad (Vocola\Samples\notepad.vcl) to the Vocola\Commands folder.
- Say "Load Voice Commands". (This should create the file NatLink\MacroSystem\notepad.py as well as the log file Vocola\Commands\vcl2py_log.txt)
- Exit NaturallySpeaking and restart. (NatLink requires this only when you have created a new command file.)
- 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 7.
- Change the "Test Simple Command" command to type "It really works!"
-
Save the file, say "Load Voice Commands", say "Switch to Notepad", and say
"Test Simple Command". "It really works!" should appear.
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:
- You didn't save the .vcl file.
- You didn't run the Vocola translator by saying "Load Voice Commands".
- Your command had a syntax error.
- Vocola reports errors in the file NatLink\Vocola\vcl2py_log.txt, which
should be opened automatically if errors are present.
- You've hit one of the known bugs.
- 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.
- 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. NatLink does not notice
these.
- NatLink or NatSpeak is in a bad state.
- In either case, you need to exit and restart NatSpeak. (If NatSpeak
loads quickly, you didn't succeed in exiting. Make sure you have closed Microsoft
Word. And sometimes you have to kill the natspeak.exe process explicitly using
Task Manager.)
- NatLink doesn't like Vocola's translation of your command.
- Check the window titled "Messages from Python Macros" for messages
which may help you figure out the problem.
- NatLink can't tell what application you're running.
- If the "Messages from Python Macros" window contains the persistent
message "Vocola cannot determine application, app-specific commands disabled",
read on.
"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:
- If your computer is always on and you run automatic nightly virus scans
or disk defragmentation, either disable them or exit NatSpeak every evening.
For me this prevented the most serious version of the problem, where only
a reboot gets you back on track.
- Wait for 10 seconds. Strange but true. If you keep saying your command
nothing improves, but if you say and do nothing for 10 seconds and then repeat
your command, it usually works. Now and then I have to try again and wait
for 15 seconds. It can seem excruciating to do nothing for an entire 10 seconds,
but hey, it's a great time to do some wrist stretches...
- Restart NatSpeak (as described in #4 above).
My command doesn't work right
Your command gets executed, but doesn't work correctly. Here are some possible
causes:
- Another command is being executed instead.
- You may have defined a command with the same words using the Dragon
Macro 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.
- You need to use quotation marks in your Vocola command. Quotation
mark delimiters are always optional in Vocola, but are required in some cases:
- when whitespace is significant, e.g. "{Left 2}"
- when a word contains an apostrophe, e.g. "Don't"
- when keystrokes to enter contain special characters
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:
- Function calls with numeric arguments can fail.
Note that while
most Dragon functions (like SetMousePosition) expect numbers to be
passed without quotation marks, the HeardWord function requires numbers
to be passed with quotation marks. Vocola has no way to express
this distinction. Currently, numeric arguments are passed unquoted (so
SetMousePosition(6,7) works but HeardWord(Delete,3,Words)
fails) and references are passed quoted (so
HeardWord(Delete,$1,Words) works but SetMousePosition($1,$2)
fails) This works fairly well for most real world macros, but may fail for
some.
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.
- User-defined functions, so you can reuse all or part of a command without
using HeardWord
- Allow default values in alternative sets
- Allow variables in alternative sets (e.g. <direction> |
foo | bar)
- Share variable definitions between Vocola files (e.g. list of interesting
folders)
- Context statement can be a regular expression
- A way to repeat actions a certain number of times
- Repeatable terms (e.g. Press <modifier_key>+ <key>
= ...)
- Function argument can combine a reference and explicit keystrokes
- Use the return value of a function as a keystroke sequence (e.g.
Mid$($1,0,1))
- Commands which include arbitrary dictation (e.g. "Line Number 135")
- User-specific command files
- Load changed .vcl files automatically (like NatLink), rather than
by saying "Load Voice Commands"
- Only process changed .vcl files, rather than all files
- Improve quality/efficiency of generated Python code
- Ship Vocola translator as an executable, so installing Perl is not
required
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