
.. _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.7 or later* -- available from the `Python dowloads page
   <https://www.python.org/downloads/>`_.
 * **Win32 extensions for Python** *(only for Windows users)* --
   available from the `pywin32 releases page
   <https://github.com/mhammond/pywin32/releases>`_.
 * **Natlink** *(only for Dragon NaturallySpeaking users)* -- latest
   versions available from `SourceForge
   <https://sourceforge.net/projects/natlink/files/natlink/natlinktest4.1/>`_.


Installation of Dragonfly
----------------------------------------------------------------------------
Dragonfly is a Python package. It can be installed as *dragonfly2* using
pip:

.. code:: shell

    pip install dragonfly2

The distribution name has been changed to *dragonfly2* in order to
upload releases to PyPI.org, but everything can still be imported using
*dragonfly*. If you use any grammar modules that include something like
:code:`pkg_resources.require("dragonfly >= 0.6.5")`, you will need to either
replace :code:`dragonfly` with :code:`dragonfly2` or remove lines like this
altogether.

If you are installing this on Linux, you will also need to install the
`xdotool <https://www.semicomplete.com/projects/xdotool/>`__ program for the
``Key`` and ``Text`` actions to work. Please note that Dragonfly is only
fully functional in an X11 session. Input action classes, application
contexts and the ``Window`` class will **not** be functional under Wayland.
It is recommended that Wayland users switch to X11.

If you have dragonfly installed under the original *dragonfly*
distribution name, you'll need to remove the old version using:

.. code:: shell

    pip uninstall dragonfly

Dragonfly can also be installed by cloning this repository or
downloading it from `the releases
page <https://github.com/dictation-toolbox/dragonfly/releases>`__ and running
the following (or similar) command in the project's root directory:

.. code:: shell

    python setup.py install

If pip fails to install *dragonfly2* or any of its required or extra
dependencies, then you may need to upgrade pip with the following command:

.. code:: shell

    pip install --upgrade pip

.. _RefDNSInstall:

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

Dragonfly uses Natlink to communicate with DNS.  The latest versions of
Natlink are available from `SourceForge
<https://sourceforge.net/projects/natlink/files/natlink/natlinktest4.1/>`__.

Dragonfly and Natlink support DNS versions up to 15 (latest). The DNS
*Individual* editions are recommended, although other editions like *Home*
will also work.

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.

.. _RefWSRInstall:

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/dfly-loader-wsr.py`` file.  When run, it 
will scan the directory it's in for files beginning with ``_`` and ending
with ``.py``, then try to load them as command-modules.

A *more full-featured loader* is available in the 
``dragonfly/examples/wsr_module_loader_plus.py`` file. It includes a
basic sleep/wake grammar to control recognition (simply say "start
listening" or "halt listening"), along with a rudimentary user interface
via sound effects and console text (easily modified in the file). It
otherwise operates like the above loader.

You can download Dragonfly's module loaders and other example files in
``dragonfly/examples`` from `the source code repository
<https://github.com/dictation-toolbox/dragonfly/tree/master/dragonfly/examples>`__.


Installation for CMU Pocket Sphinx
----------------------------------------------------------------------------

Please see the :ref:`Pocket Sphinx engine page <RefSphinxEngine>` for
installation and usage information. There is a *loader* program for
the Sphinx engine available in the
``dragonfly/examples/sphinx_module_loader.py.py`` file.
