Framework
dictation-toolbox/dragonfly avatar
dictation-toolbox/dragonfly

Dragonfly: Python voice commands for Dragon, WSR, Kaldi and Pocket Sphinx

Speech recognition framework allowing powerful Python-based scripting and extension of Dragon NaturallySpeaking (DNS), Windows Speech Recognition (WSR), Kaldi and CMU Pocket Sphinx

418 stars81 forksPythonLGPL-3.0

At a glance

What is it?
Dragonfly is a Python framework for building custom voice commands on top of existing speech recognition engines. It is a library for people who want to script their own commands, not a dictation app, and its engine support is uneven across platforms.
Who is it for?
Adopt Dragonfly if you already run a supported recognition engine and want your own commands as Python objects, or if you are speech-enabling an application. Do not adopt it expecting a ready-made dictation client or a cross-platform engine: the README states that on Linux Dragonfly is only fully functional with Kaldi, and the Dragon and WSR engines are Windows-only.
Can I use it commercially?
Yes, with conditions. LGPL-3.0 is a weak copyleft licence: you can use it inside commercial and closed-source software, but if you distribute changes to its own files, you must publish those changes under the same licence.
Is it still maintained?
Yes. The repository last received commits 100 days ago.
What is it written in?
Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • dictation-toolbox/dragonfly418 ★ · +0
Star history
Repository2026-09-212026-11-15
dictation-toolbox/dragonfly418418

0 Stars in the last 55 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

What Dragonfly is for, and what it is not

Dragonfly is a library that sits between a speech recognition engine and your own Python code. The README describes it as a framework that makes it convenient to create custom commands for speech recognition software, with commands and grammar objects treated as first-class Python objects. The intended audience is narrow and specific: people who already have a recognition engine running and want to attach behaviour to what it hears. That includes programmers who work by voice, people automating desktop activities, and developers adding a voice layer to an existing application.

It is not a recogniser. Dragonfly does not transcribe audio on its own. It supports Dragon (Nuance), Windows Speech Recognition, Kaldi and CMU Pocket Sphinx, and it delegates the actual listening to whichever of those is installed. The README states that Dragonfly can be used for general programming by voice and is flexible enough to allow programming in any language, not just Python. That last claim is about the commands you define, not the framework itself: the rules, actions and grammar objects are Python code, so you still need a Python environment to run them.

Grammar objects, rules and actions: the mechanism

The core design decision is that a voice command is an object. You define a rule, give it a spoken specification, attach a callback or an action, put it in a Grammar, and load the grammar. The engine then knows about that grammar and routes recognised speech to it.

The README's first example uses CompoundRule, where a single spec string such as "do something computer" maps to one _process_recognition callback. The more common pattern is MappingRule, which the README presents as a way to define multiple voice commands at once. A mapping dictionary pairs spoken forms with actions, and an extras list declares the dynamic elements available inside those specs. In the README's Notepad example the extras list holds Dictation("text"), which lets a spec like "find <text>" capture whatever was dictated and feed it into the action through the %(text)s substitution.

Actions are their own sub-package. The README says Dragonfly includes actions for text input and key-stroke simulation, and that this framework is cross-platform, working on Windows, macOS and Linux (X11 only). The Notepad example shows the composition style: Key("a-f, a/20") plus Text("%(text)s") for a save-as command, where the slash suffix expresses a pause between keystrokes. Context is the other half of the routing. AppContext(executable="notepad") restricts a grammar to a foreground window, so the same spoken phrase can do different things in different applications.

Installing Dragonfly and loading a first command

Dragonfly ships as a Python package. The README gives the package name as dragonfly2 on PyPI, even though the project is called Dragonfly; the fork is known as dragonfly2 there for functional purposes.

bash
pip install dragonfly2

The README also documents a release candidate for version 1.0.0, installed as follows, and notes that these versions are more up to date and have fewer requirements.

bash
pip install dragonfly2==1.0.0-rc2

On Linux the installation is not complete with pip alone. The README states that you also need the wmctrl, xdotool and xsel programs, which the actions sub-package uses for window and clipboard work.

bash
sudo apt install wmctrl xdotool xsel

With the package installed, the smallest useful module is the CompoundRule example from the README. Save it in a command module in your module loader directory or Natlink user directory, then load it.

python
from dragonfly import Grammar, CompoundRule

class ExampleRule(CompoundRule):
    spec = "do something computer"
    def _process_recognition(self, node, extras):
        print("Voice command spoken.")

grammar = Grammar("example grammar")
grammar.add_rule(ExampleRule())
grammar.load()

The README says that after loading it you say do something computer, and if the engine recognised the command, Voice command spoken. appears in the Natlink messages window when using Dragon; with any other engine it appears in the console window. That difference in where output lands is a useful first check that your engine binding is working at all.

Engine support is uneven, and Linux is the weak spot

The list of supported engines reads as four equal options, but they are not equal in practice. Dragon is a commercial product from Nuance, and the README says all versions up to 16 should be supported, along with Home, Professional Individual and previous similar editions, with other editions possibly working. Windows Speech Recognition ships with Windows Vista and Windows 7+, and was freely available for Windows XP. Both of those engines are Windows-only, which means a large part of Dragonfly's user base is on Windows by necessity rather than preference.

Kaldi is described as open source under AGPL and multi-platform, and CMU Pocket Sphinx as open source and multi-platform. Those are the engines a Linux user would reach for. The README's installation section then states that on Linux Dragonfly is only fully functional with one of them, and the sentence is cut off in the text before naming which. That truncation is itself a signal: the platform matrix is the part of the project most likely to bite a new user, and the README does not resolve it in the installation section. If you are choosing an engine, do that before writing rules, because the extras and dictation behaviour you can rely on depend on the engine underneath. This is a framework whose portability comes from the action layer, not from the recognition layer.

Where a different tool fits better

If what you want is dictation rather than command scripting, Dragonfly is the wrong layer. It has no editor, no correction workflow, no profile management and no user interface; those belong to the engine or to a separate dictation client. A person who wants to talk into a document should install a dictation application, not a Python framework.

A more direct comparison is with writing against the engine's own API. Natlink exposes Dragon's grammar interface to Python, and the README places Dragonfly in the same neighbourhood: it tells you to save command modules in your Natlink user directory and to watch the Natlink messages window for output. The difference in approach is abstraction. Natlink gives you Dragon's grammar model directly, with its own concepts and its own vocabulary, and it only exists for Dragon. Dragonfly wraps that model, plus WSR, Kaldi and Pocket Sphinx, behind one set of Python classes such as Grammar, MappingRule and AppContext, and adds its own action framework for keystrokes, text and context matching. You trade direct access to engine-specific behaviour for code that can move between engines and for actions you would otherwise write yourself. If you only ever intend to use Dragon and you need a feature Dragon exposes but Dragonfly does not, going straight to Natlink is the shorter path.

Licence and the cost of keeping up

Dragonfly is licensed under the LGPL, version 3 or later. The setup.py header carries the standard notice: the library is free software distributed under the GNU Lesser General Public License, with no warranty, and the full text is expected to accompany it. The practical shape of the LGPL is that you can use the library from your own code, including code under other terms, but modifications to the library itself carry obligations. That is a general description of the licence family, not legal advice for your situation; if you are shipping a product that links against Dragonfly, read LICENSE.txt and get proper advice rather than relying on a summary.

On upgrade cost, the repository has no published GitHub releases, so there is no release cadence to measure. The README points to a changelog file in the repository for the changes in each release, and to a separate documentation set for the 1.0.0 release candidates, described as more up to date with fewer requirements. That is the migration story you get: read CHANGELOG.rst before upgrading, and be aware that the documentation has two versions. The last push to the repository was on 2026-08-07, so the codebase is not dormant, but the README does not document a rollback path if an upgrade breaks your command modules. Keep your modules in version control and pin the dragonfly2 version you install.

Editorial conclusion

Adopt Dragonfly if you already run a supported recognition engine and want your own commands as Python objects, or if you are speech-enabling an application. Do not adopt it expecting a ready-made dictation client or a cross-platform engine: the README states that on Linux Dragonfly is only fully functional with Kaldi, and the Dragon and WSR engines are Windows-only. Before writing rules, verify which engine you can actually run on your machine, and on Linux install wmctrl, xdotool and xsel, since the README lists them as required. Then copy the CompoundRule example into your module loader directory and confirm that the callback fires.

Frequently asked questions

How do you use Dragonfly to define a voice command?

Define a rule class such as CompoundRule or MappingRule, attach a callback or an action, add the rule to a Grammar object, and call grammar.load(). The README's first example uses a spec string and a _process_recognition method that prints when the command is spoken.

How do you install the Dragonfly speech recognition framework?

Install it as the dragonfly2 package with pip install dragonfly2. The README also documents pip install dragonfly2==1.0.0-rc2 for the latest release candidate, which it describes as more up to date with fewer requirements.

Which speech recognition engines does Dragonfly support?

The README lists Dragon (Nuance), Windows Speech Recognition, Kaldi and CMU Pocket Sphinx. Dragon versions up to 16 should be supported, and Kaldi and Pocket Sphinx are the open source, multi-platform options.

What else do you need to install for Dragonfly on Linux?

The README states that on Linux you also need the wmctrl, xdotool and xsel programs. It further notes that on Linux Dragonfly is only fully functional with one engine, and that sentence is cut off in the README text.

Where does Dragonfly print output when a command is recognised?

With Dragon it appears in the Natlink messages window. The README says that if you are not using Dragon, it will be printed into the console window instead.

Official sources

  1. dictation-toolbox/dragonfly on GitHub
  2. Issues
  3. License: LGPL-3.0
  4. README
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/dictation-toolbox-dragonfly.svg)](https://hysenlabs.com/projects/dictation-toolbox-dragonfly)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/dictation-toolbox-dragonfly.svg)](https://hysenlabs.com/projects/dictation-toolbox-dragonfly)

Was this useful?