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)

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, and retain.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()

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()

Connect to natlink with Python threading support enabled.

disconnect()

Disconnect from natlink.

mimic(words)

Mimic a recognition of the given words.

Note

This method has a few quirks to be aware of:

1. 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.
2. Mimic can handle by the extra formatting by DNS built-in commands.
3. Mimic is case sensitive.

set_exclusiveness(grammar, exclusive)

Set the exclusiveness of a grammar.

set_retain_directory(retain_dir)

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

speak(text)

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.

class NatlinkDictationContainer(words, methods)

Container class for dictated words as recognized by the Dictation element for the Natlink and DNS engine.

format()

Format and return this dictation.

Multiplexing interface to the Natlink timer

class NatlinkTimerManager(interval, engine)

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!