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, at least for the moment. Support for this version is not maintained for the other engine back-ends and will be dropped completely in the first MAJOR release following stable Natlink support for Python 3.
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 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.
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:
engine = get_engine("natlink",
retain_dir="natlink_recordings",
)
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 \
retain_dir="natlink_recordings"
Engine API¶
-
class
NatlinkEngine
(retain_dir=None)[source]¶ Speech recognition engine back-end for Natlink and DNS.
Parameters: retain_dir (str|None) – directory to save audio data: A
.wav
file for each utterance, andretain.tsv
file with each row listing (wav filename, wav length in seconds, grammar name, rule name, recognized text) as tab separated values.If this parameter is used in a module loaded by
natlinkmain
, then the directory will be relative to the Natlink user directory (e.g.MacroSystem
).-
DictationContainer
¶ alias of
dragonfly.engines.backend_natlink.dictation.NatlinkDictationContainer
-
apply_threading_fix
()[source]¶ 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.
-
mimic
(words)[source]¶ Mimic a recognition of the given words.
Note
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 commands.
- Mimic is case sensitive.
-
set_retain_directory
(retain_dir)[source]¶ 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.
MacroSystem
).Parameters: retain_dir (string|None) – retain directory path
-
Dictation container class for Natlink¶
This class is derived from DictationContainerBase
and implements
dictation formatting for the Natlink and Dragon NaturallySpeaking engine.
Multiplexing interface to the Natlink timer¶
-
class
NatlinkTimerManager
(interval, engine)[source]¶ 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 status.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 manager.Note: long-running timers will block dragonfly from processing what was said, so be careful with how you use them!