Joel Gould NaturallySpeaking Unofficial Information Pages
The Insider's Guide to Dragon NaturallySpeaking by Joel Gould
 Introduction
 Latest Product News
 Guide To Products
 Product Features
 Frequently Asked Questions
 Getting Best Performance
 Python Macro System
    Intro To Python
    Intro To NatSpeak
    NatLink Copyright
    NatLink Installation
    NatLink Versions
->     NatLink Contents
    Writing Python Macros
    Controlling NatSpeak
    Speech Enabled Python
    NatLink Support
 

NatLink Contents

Last Modified: October 14, 2000

The NatLink.zip archive should contain the following directories and files. I have only listed the most important files, not every file included in the NatLink release has been described below.

MacroSystem

This subdirectory is where all the NatLink executables and scripts are stored. When you create your own macros for Dragon NaturallySpeaking, you have to put them in this directory.

  • MacroSystem\natlinkmain.py

    This Python file is loaded automatically when NatLink is used as a compatibility module (to enable Python macros in Dragon NaturallySpeaking). This file contains the code which looks and loads other macro files.

  • MacroSystem\natlinkutils.py

    This Python file contains a number of utility functions, definitions and classes which make it easier to use the NatLink system. This file is normally included in every Python script with the line:

            from natlinkutils import *
    
  • MacroSystem\gramparser.py

    This Python file contains the code which compiles grammars, converting text into SAPI-compatible binary format. Users of NatLink do not normally have to explicitly import this file since it is imported and used as part of natlinkutils.

  • MacroSystem\natlink.dll

    This is the NatLink Python extension module. This DLL contains the code which links Python to Dragon NaturallySpeaking and Dragon NaturallySpeaking to Python. It is both a Python extension module and a Dragon NaturallySpeaking compatibility module (i.e. it is a COM server). To use NatLink from Python, you need to include this line in every Python script:

            import natlink
    

    Natlink.dll can be rebuild from the source files in the NatlinkSource subdirectory. The version included with the NatLink distribution was compiled using Microsoft Visual C++ 5.0 SP3.

  • MacroSystem\EnableNL.exe

    This executable is used to enable or disable NatLink as a macro subsystem for Dragon NaturallySpeaking. As a side effect, EnableNL also creates the necessary registry entries to use NatLink from Python. EnableNL.exe can be rebuild from the source files in the EnableNL subdirectory. The version included with the NatLink distribution was compiled using Microsoft Visual C++ 5.0 SP3.

  • MacroSystem\mobiletools.dll

    This is another Python extension module. This module contains the code necessary to decode SRI files, the compressed files which are created by the Dragon NaturallyMobile recorder. Because this DLL uses 3rd file library files which I do not have the rights to distribute, I have not included the source code for this module.

    Mobiletool.dll requires the decompression software which is part of the Voice It Link software. Voice It link is installed as part of Dragon NaturallySpeaking Mobile. Therefore, if you do not have Dragon NaturallySpeaking Mobile, you will not be able to use mobiletools.dll.

SampleMacros

This subdirectory contains sample Python scripts which define voice commands (macros) for Dragon NaturallySpeaking. These files do nothing when they are in the SampleMacros directory. In order to use one or more of these files, you should copy the file(s) into the MacroSystem directory before starting Dragon NaturallySpeaking. These files are provided mostly as an example of how to write macros using NatLink.

All of the files with "sample" in their name (like _sample1.py and excel_sample7.py) were created for the presentation I have to the Boston Voice Users group and are described in the PowerPoint slides NatLinkTalk.ppt.

  • SampleMacros\_globals.py

    This is a very simple global grammar for use with NatLink. It defines some simple commands which implement the commands "Python microphone off" and "Python go to sleep" which work exactly as the normal versions. It also includes the commands "Python stop listening" and "Python start listening" which demonstrate how to switch to an exclusive recognition state. (Note: the initial word Python in the commands was included to distinguish these commands from the build-in commands. Normally, you do not need to include the word Python at the beginning of your command grammars.)

  • SampleMacros\_sleeping.py

    This file does not define any grammars. Instead, if you copy this sample file into the MacroSystem subdirectory then when Dragon NaturallySpeaking starts, it will start with the microphone turned on and asleep.

  • SampleMacros\_mouse.py

    This file is a more complex global grammar. If you copy this file to the MacroSystem subdirectory than this file enables a mouse and arrow key grammar similar to DragonDictate for Windows. For example, you will be able to say "mouse left" to start the mouse moving left, followed by "faster", "slower", "stop" or a new direction. Continuous arrow movement is also defined.

  • SampleMacros\wordpad.py

    This file is an application specific grammar. When you copy this file into the MacroSystem subdirectory and run Wordpad, then whenever Wordpad is active, this file defines some new formatting grammars like "make that bold", and "set font Arial 16".

    Files with global grammars all begin with an underscore. They are loaded automatically when Dragon NaturallySpeaking starts. Application specific grammar files have the same name as the module for which they apply. Because this file is named "wordpad.py", it will be loaded automatically when the modules named "wordpad" is active.

  • SampleMacros\_repeatthat.py

    When copied to the MacroSystem subdirectory, this file implements the command "repeat that". The command "repeat that" will re-execute the last thing you said to Dragon NaturallySpeaking, command or dictation. You can say "repeat that" multiple times.

MiscScripts

This directory contains Python scripts which demonstrate how to control Dragon NaturallySpeaking using Python. These scripts are not meant to be loaded by Dragon NaturallySpeaking as part of the macro system. Instead, they can be run from this directory whether or not NatLink has been enabled as a macro system for NatSpeak.

  • MiscScripts\testnatlink.py

    This is the beginning of a complete test suite for NatLink. I unfortunately started this test script after I had written NatLink so it is currently incomplete. But is does test enough of the NatLink basic functions to determine whether NatLink is installed properly.

    You can read more about using testnatlink under NatLinkInstallation.

  • MiscScripts\transcribe.py

    This is a sample Python script which can be used to transcribe a set of recordings made using the Dragon NaturallyMobile recorder. This is the script I used to transcribe my journal from my Grand Canyon trip.

    To use this script, first download a set of recordings from the Dragon NaturallyMobile record into a directory in compressed (SRI) form. Them modify the line transcribe.py which points to your SRI files. Start Dragon NaturallySpeaking, then run transcribe.py from the Python command window.

    This script will decompress each SRI file and transcribe them using Dragon NaturallySpeaking. However, unlike using the Voice It link software t do the transcription, this script automatically prepends each file's transcript with the date and time the recording was made.

  • MiscScripts\trainuser.py

    This is a very complex script which allows you to create a new user and perform enrollment on that user completely from Python. This script assumes that you have a made set of recordings (probably with the SaveWave program) and that you have corrected the transcriptions of those recordings. I do not currently expect users to experiment with transcribe.py since I have not supplied an editor program for recordings. However, it does provide an example of different way to use NatLink to control Dragon NaturallySpeaking.

  • MiscScripts\winspch.py

    This is a simple program which display a speech-enabled dialog box implemented in Python. This script requires that you install the PythonWin (win32) extensions. It demonstrates how you can speech enable a Python program using NatLink.

    Although I was successful in getting a PythonWin-based Python program to work using NatLink. I did not get a Tkinter-based program to work properly. Perhaps someone else can debug the problems with using Tkinter and NatLink together.

NatlinkSource

This directory contains the source code for natlink.dll. With the files in this directory, and Visual C++ 5.0, you can completely rebuild natlink.dll. There is no reason to have to rebuild natlink.dll, but the source code is included to help people understand what NatLink is doing. I have not listed every file included in this directory, only the most interesting files.

  • NatlinkSource\natlink.txt

    This is main documentation file for natlink.dll. In this file, I document every function and class which the natlink module exposes to Python. Please refer to this file when writing Python code which uses NatLink.

  • NatlinkSource\natlink.dsw

    This is a Visual C++ 6.0 project file. If you want to rebuild natlink.dll, you should load this file into the VC++ developer studio. The project settings reference include files and libraries which are part of the standard Python distribution. If you have installed Python in a place other than c:\Python you may have to fix the project settings to get natlink.dll to compile.

  • NatlinkSource\speech.h

    This is the Microsoft SAPI 4.0 header file. Dragon NaturallySpeaking implements much of Microsoft SAPI 4.0 so many of the native Dragon NaturallySpeaking functions are declared in this file. You can learn more about Microsoft SAPI by downloading SAPI from the Microsoft web site and studying the documentation. (http://www.microsoft.com/IIT)

  • NatlinkSource\dspeech.h

    In addition to the core SAPI interfaces, Dragon NaturallySpeaking exposes a number of additional COM interfaces which extend the basic functionally of Microsoft SAPI. This is the header file which declares those additional interfaces and constants.

    There is no documentation for these interfaces. In addition, these interfaces are not exposes or defined by the Dragon NaturallySpeaking tool kit. When writing NatLink, I made the decision to code directly to the Dragon NaturallySpeaking internal interfaces, which are richer than any shipping NatSpeak tool kit. However, these interfaces are not documented and NOT SUPPORTED by Dragon Systems. The interfaces I use in NatLink work with version 3.x and they should also work with version 4.0 when it becomes available, but after that there are no guarantees.

    Also since there is no documentation, you will not be able to successfully use the interfaces in dspeech.h to access Dragon NaturallySpeaking except by following the examples in the NatLink source code.

EnableNL

This directory contains the source code for EnableNL.exe. With the files in this directory, and Visual C++ 5.0, you can completely rebuild EnableNL.exe. There is no reason to have to rebuild EnableNL.exe, but the source code is included to help people understand what EnableNL is doing. I have not listed every file included in this directory, only the most interesting files.

  • EnableNL\EnableNL.dsw

    This is a Visual C++ 6.0 project file. If you want to rebuild EnableNL.exe, you should load this file into the VC++ developer studio.

MobileTools

At present I have decided not to include the source code to mobiletools.dll because I am unsure about the distribution writes to the libraries and header files which interface with the decompression software. However, I have included the documentation file.

  • MobileTools\mobiletools.txt

    This is main documentation file for mobiletools.dll. In this file, I document every function and class which the mobiletools module exposes to Python. Please refer to this file when writing Python code which uses mobiletools.

This web page (http://www.synapseadaptive.com/joel/NatLinkContents.html) was last modified on October 14, 2000. The contents of this page are (c) Copyright 1998-1999 by Joel Gould. All Rights Reserved. See Copyright Information for more details.

Web page hosting graciously provided by
Synapse, a provider of speech recognition solutions.