.. _RefNatlinkEngine:

Natlink and DNS engine back-end
============================================================================

Dragonfly uses Natlink to communicate with Dragon.  The latest versions of
Natlink are available from `SourceForge
<https://sourceforge.net/projects/natlink/files/natlink/natlink4.2/>`__.
All versions in the 4.X range should work with Dragonfly.  Please see the
`Natlink install instructions
<https://qh.antenna.nl/unimacro/installation/index.html>`__ on
*qh.antenna.nl* for how to install Natlink on your machine and configure it.

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

Python version 2.7 (32-bit) is required to use this engine back-end.  This
is because, at the time of writing (September '22), Natlink does not have
stable support for Python version 3.  Dragonfly will continue to retain
support for Python version 2.7 regardless, since it is not difficult.

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 **or** from the
optional user directory.  Common locations are:

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

At least one of these, or the custom user directory, should be present
after installing and configuring Natlink.  That is the place where you
should put Dragonfly command-modules so that Natlink will load them.
Command-modules should be Python source files starting with an underscore,
e.g. *_notepad_example.py*.

Don't forget to turn the microphone off and on again after placing new
command-modules in the Natlink directory, because otherwise Natlink does
not immediately see the new file.


Engine Configuration
----------------------------------------------------------------------------

This engine can be configured by passing (optional) keyword arguments to
the ``get_engine()`` function, which passes them to the engine constructor
(documented below). For example:

.. code:: Python

   engine = get_engine("natlink",
     retain_dir="natlink_recordings",
   )

The engine can also be configured via the :ref:`command-line interface
<RefCLI>`:

.. code:: shell

   # Initialize the Natlink engine back-end with custom arguments, then load
   # command modules and recognize speech.
   python -m dragonfly load _*.py --engine natlink --engine-options \
       retain_dir="natlink_recordings"


Engine API
----------------------------------------------------------------------------

.. autoclass:: dragonfly.engines.backend_natlink.engine.NatlinkEngine
   :members:

.. automodule:: dragonfly.engines.backend_natlink.dictation
   :members:

.. automodule:: dragonfly.engines.backend_natlink.timer
   :members:
