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

Dragonfly is a speech recognition framework. It is a Python 
package which offers a high-level object model and allows its 
users to easily write scripts, macros, and programs which use 
speech recognition. This is a fork of the original
`t4ngo/dragonfly <https://github.com/t4ngo/dragonfly>`__ project.

It currently supports the following speech recognition engines:

 - *Dragon NaturallySpeaking* (DNS), a product of *Nuance*
 - *Windows Speech Recognition* (WSR), included with Microsoft 
   Windows Vista, Windows 7, and freely available for Windows XP
 - *Kaldi* (under development)
 - *CMU Pocket Sphinx* (with caveats)

Dragonfly's documentation is available online at
`Read the Docs <http://dragonfly2.readthedocs.org/en/latest/>`_.
Dragonfly's FAQ is available at `Stackoverflow
<http://stackoverflow.com/questions/tagged/python-dragonfly>`_.
Dragonfly's mailing list/discussion group is available at
`Google Groups
<https://groups.google.com/forum/#!forum/dragonflyspeech>`_.


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

Besides this page, the following documentation is also available:

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

    introduction
    object_model
    engines
    actions
    language
    miscellaneous
    project
    tests
    changelog

Direct links within this documentation to help you get started:

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


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

   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.

The example above is very basic and doesn't show any of 
Dragonfly's exciting features, such as dynamic speech elements.


Rationale behind Dragonfly
----------------------------------------------------------------------------

Dragonfly offers a powerful and unified interface to developers 
who want to use speech recognition in their software. It is used 
for both speech-enabling applications and for automating 
computer activities.

In the field of scripting and automation, there are other 
alternatives available that add speech-commands to increase 
efficiency. Dragonfly differs from them in that it is a powerful 
development platform. The open source alternatives currently 
available for use with DNS are compared to Dragonfly as follows:

 - Vocola uses its own easy-to-use scripting language, 
   whereas Dragonfly uses Python and gives the macro-writer all 
   the power available.

 - Unimacro offers a set of macros for common activities, 
   whereas Dragonfly is a platform on which macro-writers can 
   easily build new commands. 


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

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