Package: dragonfly2
ContentsIntroductionDocumentation and FAQCompoundRule Usage exampleMappingRule usage exampleInstallationSR engine back-endsExisting command modulesIntroductionDragonfly is a speech recognition framework for Python that makes it
convenient to create custom commands to use with speech recognition
software. It was written to make it very easy for Python macros, scripts,
and applications to interface with speech recognition engines. Its design
allows speech commands and grammar objects to be treated as first-class
Python objects.Dragonfly can be used for general programming by voice. It is flexible
enough to allow programming in any language, not just Python. It can also be
used for speech-enabling applications, automating computer activities
and dictating prose.Dragonfly contains its own powerful framework for defining and executing
actions. It includes actions for text input and key-stroke simulation. This
framework is cross-platform, working on Windows, macOS and Linux (X11 only).
See theactions sub-package documentationfor more information, including code examples.This project is a fork of the originalt4ngo/dragonflyproject.Dragonfly currently supports the following speech recognition engines:Dragon, a product ofNuance. All versions up to 15 (the latest)
should be supported.Home,Professional Individualand previous
similar editions ofDragonare supported. Other editions may work tooWindows Speech Recognition(WSR), included with Microsoft Windows
Vista, Windows 7+, and freely available for Windows XPKaldi, open source (AGPL) and multi-platform.CMU Pocket Sphinx, open source and multi-platform.Documentation and FAQDragonfly’s documentation is available online atRead the
Docs. The changes in
each release are listed in the project’schangelog.
Dragonfly’s FAQ is available in the documentationhere.
There are also a number of Dragonfly-related questions onStackoverflow, although
many of them are related to issues resolved in the latest version of
Dragonfly.CompoundRule Usage exampleA very simple example of Dragonfly usage is to create a static voice
command with a callback that will be called when the command is spoken.
This is done as follows:fromdragonflyimportGrammar,CompoundRule# Voice command rule combining spoken form and recognition processing.classExampleRule(CompoundRule):spec="do something computer"# Spoken form of command.def_process_recognition(self,node,extras):# Callback when command is spoken.print("Voice command spoken.")# Create a grammar which contains and loads the command rule.grammar=Grammar("example grammar")# Create a grammar to contain the command rule.grammar.add_rule(ExampleRule())# Add the command rule to the grammar.grammar.load()# Load the grammar.To use this example, save it in a command module in your module loader
directory or Natlink user directory, load it and then saydo something
computer. If the speech recognition engine recognized the command, thenVoice command spoken.will be printed in the Natlink messages window.
If you’re not using Dragon, then it will be printed into the console window.MappingRule usage exampleA more common use of Dragonfly is theMappingRuleclass, which allows
defining multiple voice commands. The following example is a simple grammar
to be used when Notepad is the foreground window:fromdragonflyimport(Grammar,AppContext,MappingRule,Dictation,Key,Text)# Voice command rule combining spoken forms and action execution.classNotepadRule(MappingRule):# Define the commands and the actions they execute.mapping={"save [file]":Key("c-s"),"save [file] as":Key("a-f, a/20"),"save [file] as <text>":Key("a-f, a/20")+Text("%(text)s"),"find <text>":Key("c-f/20")+Text("%(text)s\n"),}# Define the extras list of Dragonfly elements which are available# to be used in mapping specs and actions.extras=[Dictation("text")]# Create the grammar and the context under which it'll be active.context=AppContext(executable="notepad")grammar=Grammar("Notepad example",context=context)# Add the command rule to the grammar and load it.grammar.add_rule(NotepadRule())grammar.load()To use this example, save it in a command module in your module loader
directory or Natlink user directory, load it, open a Notepad window and then
say one of mapping commands. For example, sayingsaveorsave filewill
cause the control and S keys to be pressed.The example aboves don’t show any of Dragonfly’s exciting features, such as
dynamic speech elements. To learn more about these, please take a look atDragonfly’s online docs.InstallationDragonfly is a Python package. It can be installed asdragonfly2using
pip:pipinstalldragonfly2The distribution name has been changed todragonfly2in order to
upload releases to PyPI.org, but everything can still be imported usingdragonfly. If you use any grammar modules that include something likepkg_resources.require("dragonfly >= 0.6.5"), you will need to either
replacedragonflywithdragonfly2or remove lines like this
altogether.If you are installing this on Linux, you will also need to install thewmctrl,xdotoolandxselprograms. You may
also need to manually set theXDG_SESSION_TYPEenvironment variable tox11.Please note that Dragonfly is only fully functional in an X11 session on
Linux. Input action classes, application contexts and theWindowclass
willnotbe functional under Wayland. It is recommended that Wayland
users switch to X11.If you have dragonfly installed under the originaldragonflydistribution name, you’ll need to remove the old version using:pipuninstalldragonflyDragonfly can also be installed by cloning this repository or
downloading it fromthe releases
pageand
running the following (or similar) command in the project’s root
directory:pythonsetup.pyinstallIf pip fails to installdragonfly2or any of its required or extra
dependencies, then you may need to upgrade pip with the following command:pipinstall--upgradepipSR engine back-endsEach Dragonfly speech recognition engine back-end and its requirements are
documented separately:Natlink and DNS engineSAPI 5 and WSR engineKaldi engineCMU Pocket Sphinx engineText-input engineExisting command modulesThe related resources page of Dragonfly’s documentation has a section oncommand
moduleswhich lists various sources.