Skip to content

Commit

Permalink
Amend recently added documentation on new engines
Browse files Browse the repository at this point in the history
Re: #139, #376, #383.

I've added a section on new engines back into the CONTRIBUTING.rst
file and given criteria for new engine implementations.
  • Loading branch information
drmfinlay committed May 4, 2024
1 parent d0d4e44 commit b08fa83
Show file tree
Hide file tree
Showing 2 changed files with 59 additions and 29 deletions.
52 changes: 52 additions & 0 deletions CONTRIBUTING.rst
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
.. _RefContributing:

Contributing
============

Expand Down Expand Up @@ -76,6 +78,56 @@ Other languages such as German and Dutch only have mappings for using
``IntegerRef`` (and similar) elements.


.. _RefContributingNewEngines:

Contributing New Speech Recognition Engines
-------------------------------------------

Introduction and Criteria
~~~~~~~~~~~~~~~~~~~~~~~~~

Contribution of new Dragonfly speech recognition engine implementations is
welcome, provided certain criteria are met. New implementations must:

* be as functional as the current engines
* have some significant advantage over the current engines, perhaps in
terms of accuracy, speed, CPU/memory requirements and/or platform support
* have a willing maintainer or require little maintenance

Before setting out to implement a new Dragonfly engine, please know that
it is difficult to achieve the first criterion on functionality.
Dragonfly's feature set requires a very specific type of speech recognition
engine. Namely, it must be one which supports each of the following
features:

1. definition of voice commands in a grammar format
2. efficient and dynamic activation and deactivation of (parts of) grammars
at the beginning of an utterance
3. in-speech transition between dictated prose (dictation mode), loaded
voice commands (command mode) and vice versa

Each Dragonfly engine supports features one and two. All engines support
feature three except the CMU Pocket Sphinx engine. However, Sphinx is
only limited in that dictated prose must be spoken in separate utterances.

These three requirements have effectively ruled out Dragonfly support for
most speech recognition engines that users have asked about in the past.
This is not meant to discourage those wishing to contribute new
implementations, it is simply a fact.

As for the second and third criteria listed above, they are fairly
self-explanatory. There is no sense in contributing a new engine that
brings nothing new to the table and this library's maintainer does not wish
to substantially increase the effort needed to keep things working.

.. _RefContributingNewEngineGuide:

New SR Engine Guide
~~~~~~~~~~~~~~~~~~~

TODO


.. Links.
.. _Read the docs: https://readthedocs.org/
.. _Sphinx documentation engine: https://www.sphinx-doc.org/en/master/
Expand Down
36 changes: 7 additions & 29 deletions documentation/faq.txt
Original file line number Diff line number Diff line change
Expand Up @@ -165,31 +165,10 @@ the following resources from might be of use:
Will Dragonfly add support for speech recognition engine X?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

We are not considering the addition of new Dragonfly engine implementations.
The main reason for this is that Dragonfly requires a very specific type of
speech recognition engine to work. It must be one which supports each of
the following features:

1. definition of voice commands in a grammar format
2. efficient and dynamic activation and deactivation of (parts of) grammars
at the beginning of an utterance
3. in-speech transition between dictated prose (dictation mode), loaded
voice commands (command mode) and vice versa

Each Dragonfly engine supports features one and two. All engines support
feature three except the CMU Pocket Sphinx engine. However, Sphinx is
only limited in that dictated prose must be spoken in separate utterances.

These three requirements have effectively ruled out Dragonfly support for
most speech recognition engines that users have asked about in the past.

Even if a new speech recognition engine comes along that supports the above
features, we will probably not accept an engine implementation for it
because Dragonfly already has very good engine implementations.

We may make an exception for new implementations meant to replace current,
deprecated ones. However, none of Dragonfly's current engines really need
replacing.
The answer is 'it depends.' No new engine implementations are currently
under development. Contribution of new implementations is welcome, provided
certain criteria are met. Please see :ref:`RefContributingNewEngines` for
more information.


API Questions
Expand Down Expand Up @@ -373,12 +352,11 @@ prints the name of the current engine if one has been initialized:
print("No engine has been initialized.")


Can I implement my own custom Dragonfly engine?
Can I implement my own custom Dragonfly engine externally?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Yes, this is possible. Although Dragonfly is :ref:`not accepting new engine
implementations <RefFAQSupportEngineX>`, you can write one externally,
register it and use it like any of the in-package engines.
Yes, you can write a Dragonfly engine implementation externally and use it
like any of the in-package engines.

Implementing a custom Dragonfly engine is a complex task. It is
recommended that you start with a copy of the text-input engine source code
Expand Down

0 comments on commit b08fa83

Please sign in to comment.