.. _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** -- available from the `Python dowloads page
   <https://www.python.org/downloads/>`_.
   **Version 2.7 (32-bit) is required if using Natlink**.
 * **Win32 extensions for Python** *(only for Windows users)* --
   available from the `pywin32 releases page
   <https://github.com/mhammond/pywin32/releases>`_.
 * **Natlink** *(only for Dragon users)* -- latest
   versions available from `SourceForge
   <https://sourceforge.net/projects/natlink/files/natlink/natlinktest4.1/>`_.
 * `wmctrl <https://www.freedesktop.org/wiki/Software/wmctrl/>`__, `xdotool
   <https://www.semicomplete.com/projects/xdotool/>`__ and `xsel
   <http://www.vergenet.net/~conrad/software/xsel/>`__ programs *(only
   for Linux/X11 users)* -- usually available from your system's package
   manager.

**Note on Python 2**: Python version 2.7 (32-bit) is required if using the
Natlink SR engine, at least for the moment.  With the exception of the Kaldi
engine, Python 2 support has been retained for the whole library.  Other
than the fact that this support is currently required for the Natlink
engine, this has been done because the library has always supported this
version of Python and because retaining said support is, at present, neither
difficult nor detrimental to the library's support for Python version 3.

**Note for Linux users**: Dragonfly is only fully functional in an X11
session.  You may also need to manually set the ``DISPLAY`` environment
variable.  Input action classes, application contexts and the ``Window``
class will **not** be functional under Wayland.  It is therefore recommended
that the Wayland user switch to X11.


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

Dragonfly is a Python package. It can be installed as *dragonfly* using
pip:

.. code:: shell

    pip install dragonfly2

If you wish to install the latest release candidate for version 1.0.0,
please run the following command instead:

.. code:: shell

    pip install dragonfly2==1.0.0-rc2

These versions are more up-to-date and have fewer requirements.  The
documentation for them is available at `Read the Docs (latest)
<http://dragonfly2.readthedocs.org/en/latest/>`_.

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 *dragonfly* 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


Installation for specific SR engine back-ends
----------------------------------------------------------------------------

Each Dragonfly speech recognition engine back-end and its requirements are
documented separately:

* :ref:`RefNatlinkEngine`
* :ref:`RefSapi5Engine`
* :ref:`RefKaldiEngine`
* :ref:`RefSphinxEngine`
* :ref:`RefTextEngine`

Installation for optional features
----------------------------------------------------------------------------

Some features of Dragonfly are optional and have requirements which must be
installed separately.  Included in this category are the following:

* :ref:`RefAccessibility`