Recognition observers

This section describes classes and functions for observing Dragonfly’s recognition state events:

• on_begin() – called when speech start is detected.
• on_recognition() – called when speech successfully decoded to a grammar rule or to dictation. This is called before grammar rule processing (i.e. Rule.process_recognition()).
• on_failure() – called when speech failed to decode to a grammar rule or to dictation.
• on_end() – called when speech ends, either with a successful recognition or in failure.
• on_post_recognition() – called after all rule processing has completed after a successful recognition.

Recognition observer classes

class PlaybackHistory(length=10)

Storage class for playing back recent recognitions via the Playback action.

Instances of this class monitor recognitions and store them internally. This class derives from the built in list type and can be accessed as if it were a normal list containing Playback actions for recent recognitions. Note that an instance’s contents are updated automatically as recognitions are received.

class RecognitionHistory(length=10)

Storage class for recent recognitions.

Instances of this class monitor recognitions and store them internally. This class derives from the built in list type and can be accessed as if it were a normal list containing recent recognitions. Note that an instance’s contents are updated automatically as recognitions are received.

complete

False if phrase-start detected but no recognition yet.

class RecognitionObserver

Recognition observer base class.

Sub-classes should override one or more of the event methods.

on_begin()

Method called when the observer is registered and speech start is detected.

on_end(results)

Method called when speech ends, either with a successful recognition (after on_recognition) or in failure (after on_failure).

Parameters:results (engine-specific type) – optional engine recognition results object

on_failure(results)

Method called when speech failed to decode to a grammar rule or to dictation.

Parameters:results (engine-specific type) – optional engine recognition results object

on_post_recognition(words, rule, node, results)

Method called when speech successfully decoded to a grammar rule or to dictation.

This is called after grammar rule processing (i.e. Rule.process_recognition()).

Parameters:

• words (tuple) – recognized words
• rule (Rule) – optional recognized rule
• node (Node) – optional parse tree node
• results (engine-specific type) – optional engine recognition results object

on_recognition(words, rule, node, results)

Method called when speech successfully decoded to a grammar rule or to dictation.

This is called before grammar rule processing (i.e. Rule.process_recognition()).

Parameters:

• words (tuple) – recognized words
• rule (Rule) – optional recognized rule
• node (Node) – optional parse tree node
• results (engine-specific type) – optional engine recognition results object

register()

Register the observer for recognition state events.

unregister()

Unregister the observer for recognition state events.

Recognition state change callbacks

class CallbackRecognitionObserver(event, function)

Observer class for calling recognition state change callbacks.

This class is used by the register_*_callback functions and is registered with the current engine on initialization.

Constructor arguments:

• event (str) – the name of the recognition event to register for (e.g. "on_begin").
• function (callable) – function to call on the specified recognition event.

register_beginning_callback(function)

Register a callback function to be called when speech starts.

The CallbackRecognitionObserver object returned from this function can be used to unregister the callback function.

Parameters:function (callable) – callback function Returns:recognition observer Return type:CallbackRecognitionObserver

register_ending_callback(function)

Register a callback function to be called when speech ends, either successfully (after calling the recognition callback) or in failure (after calling the failure callback).

The CallbackRecognitionObserver object returned from this function can be used to unregister the callback function.

Parameters:function (callable) – callback function Returns:recognition observer Return type:CallbackRecognitionObserver

register_failure_callback(function)

Register a callback function to be called on recognition failures.

The CallbackRecognitionObserver object returned from this function can be used to unregister the callback function.

Parameters:function (callable) – callback function Returns:recognition observer Return type:CallbackRecognitionObserver

register_post_recognition_callback(function)

Register a callback function to be called after all rule processing has completed after recognition success.

The CallbackRecognitionObserver object returned from this function can be used to unregister the callback function.

Parameters:function (callable) – callback function Returns:recognition observer Return type:CallbackRecognitionObserver

register_recognition_callback(function)

Register a callback function to be called on recognition success.

The CallbackRecognitionObserver object returned from this function can be used to unregister the callback function.

Parameters:function (callable) – callback function Returns:recognition observer Return type:CallbackRecognitionObserver

Doctest usage examples

See Dragonfly’s doctests for recognition observers for some usage examples.