Dragonfly
============================================================================

Dragonfly 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 the :ref:`actions sub-package documentation <RefActions>` for more
information, including code examples.

This project is a fork of the original
`t4ngo/dragonfly <https://github.com/t4ngo/dragonfly>`__ project.

Dragonfly currently supports the following speech recognition engines:

 - :ref:`Dragon <RefNatlinkEngine>`, a product of *Nuance*. All versions up
   to 15 (the latest) are supported. *Home*, *Professional Individual* and
   previous similar editions of *Dragon* are supported. Other editions may
   work too
 - :ref:`Windows Speech Recognition <RefSapi5Engine>` (WSR), included with
   Microsoft Windows Vista, Windows 7+, and freely available for Windows XP
 - :ref:`Kaldi <RefKaldiEngine>`, open source and multi-platform.
 - :ref:`CMU Pocket Sphinx <RefSphinxEngine>`, open source and multi-
   platform.

Dragonfly's documentation is available online at
`Read the Docs <http://dragonfly2.readthedocs.org/en/latest/>`_.
Dragonfly's FAQ is available in the documentation :ref:`here <RefFAQ>`.
There are also a number of Dragonfly-related questions on `Stackoverflow
<http://stackoverflow.com/questions/tagged/python-dragonfly>`_, although
many of them are related to issues resolved in the latest version of
Dragonfly.

Dragonfly's mailing list/discussion group is available at
`Google Groups
<https://groups.google.com/forum/#!forum/dragonflyspeech>`_.


CompoundRule usage example
----------------------------------------------------------------------------

A 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:

..  code-block:: python

    from dragonfly import Grammar, CompoundRule

    # Voice command rule combining spoken form and recognition processing.
    class ExampleRule(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 say *do something
computer*. If the speech recognition engine recognized the command, then
``Voice 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 example
----------------------------------------------------------------------------

A more common use of Dragonfly is the ``MappingRule`` class, which allows
defining multiple voice commands. The following example is a simple grammar
to be used when Notepad is the foreground window:

..  code-block:: python

    from dragonfly import (Grammar, AppContext, MappingRule, Dictation,
                           Key, Text)

    # Voice command rule combining spoken forms and action execution.
    class NotepadRule(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, saying *save* or *save file* will
cause the control and S keys to be pressed.

Documentation
----------------------------------------------------------------------------

Besides this page, the following documentation is also available:

.. toctree::
    :titlesonly:
    :maxdepth: 2

    introduction
    faq
    object_model
    engines
    actions
    language
    windows
    accessibility
    cli
    logging
    rpc
    config
    ccr
    project
    tests
    changelog

Direct links within this documentation to help you get started:

 - :ref:`features_and_target_audience`
 - :ref:`installation`

Indices and tables
----------------------------------------------------------------------------

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
