.. _installation:

Installation
============================================================================

This section describes how to install Dragonfly.  The 
installation procedure of Dragonfly itself is straightforward. 
Its dependencies, however, differ depending on which speech 
recognition engine is used.


Prerequisites
----------------------------------------------------------------------------

To be able to use the dragonfly, you will need the following:

 * **Python**, *v2.5 or later* -- for example available from
   `ActiveState
   <http://www.activestate.com/Products/activepython/index.mhtml>`_.
 * **Win32 extensions for Python** -- already included in
   ActiveState's Python distribution or available from
   `Mark Hammond's page
   <http://python.net/crew/mhammond/win32/Downloads.html>`_.
 * **Natlink** *(only for Dragon NaturallySpeaking users)* --
   for example available from `Daniel Rocco
   <http://www.westga.edu/~drocco/voice/NatLink/>`_.


Installation of Dragonfly
----------------------------------------------------------------------------

Dragonfly is a Python package.  A simple installer of the
*next, next, finish* type is available from the project's
`download page
<http://code.google.com/p/dragonfly/downloads/list>`_.
This installer was created with Python's standard distutils and 
has been tested on Microsoft Windows XP and Vista.

Dragonfly's installer will install the library in your Python's 
local site-packages directory under the ``dragonfly`` 
subdirectory.


Installation for Dragon NaturallySpeaking
----------------------------------------------------------------------------

Dragonfly uses Natlink to communicate with DNS.  Natlink is 
available in various forms, including Daniel Rocco's efficient 
and tidy pure-Python package.  It is available `here 
<http://www.westga.edu/~drocco/voice/NatLink/>`_.

Once Natlink is up and running, Dragonfly command-modules can be 
treated as any other Natlink macro files.  Natlink automatically 
loads macro files from a predefined directory.  Common locations 
are:

 * ``C:\Program Files\NatLink\MacroSystem``
 * ``My Documents\Natlink``

At least one of these should be present after installing 
Natlink.  That is the place where you should put Dragonfly 
command-modules so that Natlink will load them.  Don't forget to 
turn the microphone off and on again after placing a new 
command-modules in the Natlink directory, because otherwise 
Natlink does not immediately see the new file.


Installation for Windows Speech Recognition
----------------------------------------------------------------------------

If WSR is available, then no extra installation needs to be 
done.  Dragonfly can find and communicate with WSR using 
standard COM communication channels.

If you would like to use Dragonfly command-modules with WSR, 
then you must run a *loader* program which will load and manage 
the command-modules.  A simple *loader* is available in the 
``dragonfly/examples/dragonfly-main.py`` file.  When run, it 
will scan the directory it's in for other ``*.py`` files and try 
to load them as command-modules.