Natlink and DNS engine back-end
Dragonfly uses Natlink to communicate with Dragon. The latest versions of
Natlink are available from SourceForge.
All versions in the 4.X range should work with Dragonfly. Please see the
Natlink install instructions 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:
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,
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.
This engine can be configured by passing (optional) keyword arguments to
get_engine() function, which passes them to the engine constructor
(documented below). For example:
engine = get_engine("natlink",
The engine can also be configured via the command-line interface:
# 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 \
Speech recognition engine back-end for Natlink and DNS.
|Parameters:||retain_dir (str|None) –
directory to save audio data:
.wav file for each utterance, and
with each row listing (wav filename, wav length in seconds,
grammar name, rule name, recognized text) as tab separated
If this parameter is used in a module loaded by
natlinkmain, then the directory will be relative to the
Natlink user directory (e.g.
Start a thread and engine timer internally to allow Python threads
to work properly while connected to natlink. The fix is only applied
once, successive calls have no effect.
This method is called automatically when
connect() is called
or when a grammar is loaded for the first time.
Connect to natlink with Python threading support enabled.
Disconnect from natlink.
Mimic a recognition of the given words.
This method has a few quirks to be aware of:
- Mimic is not limited to one element per word as seen with
proper nouns from DNS. For example, “Buffalo Bills” can be
passed as one word.
- Mimic can handle by the extra formatting by DNS built-in
- Mimic is case sensitive.
Set the exclusiveness of a grammar.
Set the directory where audio data is saved.
Retaining audio data may be useful for acoustic model training. This
is disabled by default.
If a relative path is used and the code is running via natspeak.exe,
then the path will be made relative to the Natlink user directory or
base directory (e.g.
|Parameters:||retain_dir (string|None) – retain directory path
Speak the given text using text-to-speech.
Dictation container class for Natlink
This class is derived from
DictationContainerBase and implements
dictation formatting for the Natlink and Dragon NaturallySpeaking engine.
Container class for dictated words as recognized by the
Dictation element for the Natlink and DNS engine.
Format and return this dictation.
Multiplexing interface to the Natlink timer
Timer manager for the Natlink engine.
This class utilises
natlink.setTimerCallback() to ensure that
timer functions are called on-time regardless of Dragon’s current
Python code run outside of timer functions will be blocked when
natlink functions are executing. This is a
limitation with Python threads.
engine.connect() must be called before using timers with this
Note: long-running timers will block dragonfly from processing
what was said, so be careful with how you use them!