Base engine classes

EngineBase class

The dragonfly.engines.base.EngineBase class forms the base class for the 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

Base class for engine-specific back-ends.

DictationContainer

alias of DictationContainerBase

connect()

Connect to back-end SR engine.

connection()

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

create_timer(callback, interval, repeating=True)

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

disconnect()

Disconnect from back-end SR engine.

dispatch_recognition_failure(results)

Dispatch results data to all grammars with a process_recognition_failure method.

dispatch_recognition_other(grammar, words, results)

Dispatch recognition data for a grammar to all other grammars with a process_recognition_other method.

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

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

Parameters:

• 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).

property grammars

Grammars loaded into this engine.

property language

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

Return type:

str

mimic(words)

Mimic a recognition of the given words.

property name

The human-readable name of this engine.

process_grammars_context(window=None)

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 calls this automatically whenever the foreground application (or its title) changes.

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

The user may wish to call this method to update if custom contexts are used.

Note

This method does not trigger the on_begin() methods of recognition observers.

property quoted_words_support

Whether this engine can compile and recognize quoted words.

Return type:

bool

set_exclusive(grammar, exclusive)

Alias of set_exclusiveness().

set_exclusiveness(grammar, exclusive)

Set the exclusiveness of a grammar.

speak(text)

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>]":
        Text("self.%(under)s%(snaketext)s"),
}

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

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.

Parameters:

• words (sequence-of-unicode) – A sequence of Unicode strings.

• methods (list-of-triples) – Tuples describing string methods to call on the output.

apply_methods(joined_words)

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

Called during format().

format(spoken_form=False)

Format and return this dictation as a string.

Arguments:

• spoken_form (bool, default: False) – whether to use the spoken form of dictated words in the result instead of the written form. Only has an effect if using the Natlink/DNS engine back-end

property words

Sequence of the words forming this dictation.

Engine timer classes

Multiplexing interface to a timer

class DelegateTimerManager(interval, engine)

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

Engines using this class should implement the methods in DelegateManagerInterface.

class DelegateTimerManagerInterface

DelegateTimerManager interface.

set_timer_callback(callback, sec)

Method to set the timer manager’s callback.

Parameters:

• callback (callable | None) – function to call every N seconds

• sec (float | int) – number of seconds between calls to the callback function

class ThreadedTimerManager(interval, engine)

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.

Warning

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

class Timer(function, interval, manager, repeating=True)

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

Call the timer’s function.

This method is normally called by the timer manager.

start()

Start calling the timer’s function on an interval.

This method is called on initialisation.

stop()

Stop calling the timer’s function on an interval.

class TimerManagerBase(interval, engine)

Base timer manager class.

_activate_main_callback(callback, msec)

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

_deactivate_main_callback()

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

add_timer(timer)

Add a timer and activate the main callback if required.

disable()

Method to disable execution of the main timer callback.

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

enable()

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.

main_callback()

Method to call each timer’s function when required.

remove_timer(timer)

Remove a timer and deactivate the main callback if required.