Base engine classes

EngineBase class

The dragonfly.engines.engine_base.EngineBase class forms the base class for this specific speech recognition engine classes. It defines the stubs required and performs some of the logic necessary for Dragonfly to be able to interact with a speech recognition engine.

class EngineBase[source]

Base class for engine-specific back-ends.


Connect to back-end SR engine.


Context manager for a connection to the back-end SR engine.

create_timer(callback, interval, repeating=True)[source]

Create and return a timer using the specified callback and repeat interval.


Disconnect from back-end SR engine.

do_recognition(begin_callback=None, recognition_callback=None, failure_callback=None, end_callback=None, post_recognition_callback=None, *args, **kwargs)[source]

Recognize speech in a loop until interrupted or disconnect() is called.

Recognition callback functions can optionally be registered.

Extra positional and key word arguments are passed to _do_recognition().

  • begin_callback (callable | None) – optional function to be called when speech starts.
  • recognition_callback (callable | None) – optional function to be called on recognition success.
  • failure_callback (callable | None) – optional function to be called on recognition failure.
  • end_callback (callable | None) – optional function to be called when speech ends, either successfully (after calling the recognition callback) or in failure (after calling the failure callback).
  • post_recognition_callback (callable | None) – optional function to be called after all rule processing has completed.

Grammars loaded into this engine.


Current user language of the SR engine. (Read-only)

Return type:str

Mimic a recognition of the given words.


The human-readable name of this engine.


Enable/disable grammars & rules based on their current contexts.

This must be done preemptively for some SR engine back-ends, such as WSR, that don’t apply context changes upon/after the utterance start has been detected. The WSR engine should call this automatically whenever the foreground application (or its title) changes. The user may want to call this manually to update when custom contexts.

The window parameter is optional window information, which can be passed in as an optimization if it has already been gathered.


Whether this engine can compile and recognize quoted words.

Return type:bool
recognise_forever(begin_callback=None, recognition_callback=None, failure_callback=None, end_callback=None, post_recognition_callback=None, *args, **kwargs)

Alias of do_recognition() left in for backwards-compatibility

recognize_forever(begin_callback=None, recognition_callback=None, failure_callback=None, end_callback=None, post_recognition_callback=None, *args, **kwargs)

Alias of do_recognition() left in for backwards-compatibility

set_exclusive(grammar, exclusive)[source]

Alias of set_exclusiveness().

set_exclusiveness(grammar, exclusive)[source]

Set the exclusiveness of a grammar.


Speak the given text using text-to-speech.

Dictation container classes

Dictation container base class

This class is used to store the recognized results of dictation elements within voice-commands. It offers access to both the raw spoken-form words and be formatted written-form text.

The object can be expected to behave like a string, responding as you would expect to string methods like replace(). The formatted text can be retrieved using format() or simply by calling str(...) on a dictation container object. By default, formatting returns the words joined with spaces, but custom formatting can be applied by calling string methods on the Dictation object. A tuple of the raw spoken words can be retrieved using words.

String Formatting Examples

The following examples demonstrate dictation input can be formatted by calling string methods on Dictation elements.

Python example:

mapping = {
    # Define commands for writing Python methods, functions and classes.
    "method [<under>] <snaketext>":
        Text("def %(under)s%(snaketext)s(self):") + Key("left:2"),
    "function <snaketext>":
        Text("def %(snaketext)s():") + Key("left:2"),
    "classy [<classtext>]":
        Text("class %(classtext)s:") + Key("left"),

    # Define a command for accessing object members.
    "selfie [<under>] [<snaketext>]":

extras = [
    # Define a Dictation element that produces snake case text,
    # e.g. hello_world.
    Dictation("snaketext", default="").lower().replace(" ", "_"),

    # Define a Dictation element that produces text matching Python's
    # class casing, e.g. DictationContainer.
    Dictation("classtext", default="").title().replace(" ", ""),

    # Allow adding underscores before cased text.
    Choice("under", {"under": "_"}, default=""),

rule = MappingRule(name="PythonExample", mapping=mapping, extras=extras)

Markdown example:

mapping = {
    # Define a command for typing Markdown headings 1 to 7 with optional
    # capitalized text.
    "heading [<num>] [<capitalised_text>]":
        Text("#")*Repeat("num") + Text(" %(capitalised_text)s"),

extras = [
    Dictation("capitalised_text", default="").capitalize(),
    IntegerRef("num", 1, 7, 1),

rule = MappingRule(name="MdExample", mapping=mapping, extras=extras)

Camel-case example using the Dictation.camel() method:

mapping = {
    # Define a command for typing camel-case text, e.g. helloWorld.
    "camel <camel_text>": Text(" %(camel_text)s"),

extras = [
    Dictation("camel_text", default="").camel(),

rule = MappingRule(name="CamelExample", mapping=mapping, extras=extras)

Example using the Dictation.apply() method for random casing:

from random import random

def random_text(text):
    # Randomize the case of each character.
    result = ""
    for c in text:
        r = random()
        if r < 0.5:
            result += c.lower()
            result += c.upper()
    return result

mapping = {
    "random <random_text>": Text("%(random_text)s"),

extras = [
    Dictation("random_text", default="").apply(random_text),

rule = MappingRule(name="RandomExample", mapping=mapping, extras=extras)

Class reference

class DictationContainerBase(words, methods=None)[source]

Container class for dictated words as recognized by the Dictation element.

This base class implements the general functionality of dictation container classes. Each supported engine should have a derived dictation container class which performs the actual engine- specific formatting of dictated text.

A dictation container is created by passing it a sequence of words as recognized by the backend SR engine. Each word must be a Unicode string.

  • words (sequence-of-unicode) – A sequence of Unicode strings.
  • methods (list-of-triples) – Tuples describing string methods to call on the output.

Apply any string methods called on the Dictation object to a given string.

Called during format().


Format and return this dictation as a Unicode object.


Sequence of the words forming this dictation.

Engine timer classes

Multiplexing interface to a timer

class Timer(function, interval, manager, repeating=True)[source]

Timer class for calling a function every N seconds.

Constructor arguments:

  • function (callable) – the function to call every N seconds. Must have no required arguments.
  • interval (float) – number of seconds between calls to the function. Note that this is on a best-effort basis only.
  • manager (TimerManagerBase) – engine timer manager instance.
  • repeating (bool) – whether to call the function every N seconds or just once (default: True).

Instances of this class are normally initialised from engine.create_timer().


Call the timer’s function.

This method is normally called by the timer manager.


Start calling the timer’s function on an interval.

This method is called on initialisation.


Stop calling the timer’s function on an interval.

class TimerManagerBase(interval, engine)[source]

Base timer manager class.

_activate_main_callback(callback, msec)[source]

Virtual method to implement to start calling main_callback() on an interval.


Virtual method to implement to stop calling main_callback() on an interval.


Add a timer and activate the main callback if required.


Method to disable execution of the main timer callback.

This method is used for testing timer-related functionality without race conditions.


Method to re-enable the main timer callback.

The main timer callback is enabled by default. This method is only useful if disable() is called.


Method to call each timer’s function when required.


Remove a timer and deactivate the main callback if required.

class ThreadedTimerManager(interval, engine)[source]

Timer manager class using a daemon thread.

This class is used by the “text” engine. It is only suitable for engine backends with no recognition loop to execute timer functions on.


The timer interface is not thread-safe. Use the enable() and disable() methods if you need finer control over timer function execution.

class DelegateTimerManager(interval, engine)[source]

Timer manager class that calls main_callback() through an engine-specific callback function.

Engines using this class should implement the methods in DelegateManagerInterface.

This class is used by the SAPI 5 engine.

class DelegateTimerManagerInterface[source]

DelegateTimerManager interface.

set_timer_callback(callback, sec)[source]

Method to set the timer manager’s callback.

  • callback (callable | None) – function to call every N seconds
  • sec (float | int) – number of seconds between calls to the callback function