Clarify `Playback` documentation

[LexiconCode]

When you give dictation with the proper noun like Buffalo Bills that's capitalized by DNS in free dictation not as a command it causes playback to fail.

In Caster we have a command called again do

It retrieves raw recognition history from from dragonfly import RecognitionHistory

• raw history [('hello', 'how', 'are', 'you', 'Buffalo Bills')]

It does postprocessing to ensure that each word is an element in a list and subtracts again do from the recognition index.

• postprocessed ['hello', 'how', 'are', 'you', 'Buffalo', 'Bills'].

  I could lower case the output but I don't see anything of the docs to suggest that it must be lowercase.

[drmfinlay]

Thanks for reporting this. I'll look into it. What stands out to me is Buffalo Bills being one "word" in the recognition history and two words after processing. I don't know if that's related.

[LexiconCode]

That's a good point about it being two words and that DNS might expect that. That should be easy enough for me to test and let you know

[LexiconCode]

Well a couple of notes here

• Spec identical to words defined in action playback.

        'buffalo bills':
            R(Playback([(["buffalo", "bills"], 0.0)])), 

Traceback (most recent call last):
  File "C:\Python2\lib\site-packages\dragonfly\engines\backend_natlink\engine.py", line 411, in results_callback
    func, words=tuple(map_word(w) for w in results.getWords(0)),
  File "C:\Python2\lib\site-packages\dragonfly\engines\backend_natlink\engine.py", line 411, in <genexpr>
    func, words=tuple(map_word(w) for w in results.getWords(0)),
  File "C:\Python2\lib\site-packages\dragonfly\engines\backend_natlink\engine.py", line 60, in map_word
    if isinstance(word, text_type):

Recursion error can be caused by the following. The command repeats itself 71 times before trace back is produced. Not directly related to the issue but interesting to note.

• Lowercase separate words

  'buffalo bills hello':
          R(Playback([(["buffalo", "bills"], 0.0)])),

  The following text is produced Buffalo bills Notice the capital B. I believe that's because it's the beginning of a sentence.

• Uppercase separate words

  'buffalo bills hello':
          R(Playback([(["Buffalo", "Bills"], 0.0)])),

  ERROR:action.exec:Execution failed: Playback failed: No matching rule found for words ['Buffalo', 'Bills'].

• Uppercase single utterance Works as expected producing Buffalo Bills

 'buffalo bills hello':
            R(Playback([(["Buffalo Bills"], 0.0)])),  

• Testing out Dragon's built-in commands that have formatting like new line Works as expected producing the new line of DNS is built in command.

      'buffalo bills hello':
          R(Playback([(["\\new-line\\new line"], 0.0)])),   

• Testing Playback with nonsense phrase that should not exist as a command or in the general dictionary.

      'buffalo bills hello':
          R(Playback([(["sdfdf"], 0.0)])),   

  ERROR:action.exec:Execution failed: Playback failed: No matching rule found for words ['sdfdf'].

• Conclusions

These issues came about due to incorrect assumptions about the playback.

• Playback is not limited to one element per word as seen with proper nouns from DNS. Example Buffalo Bills
• Playback can handle by the extra formatting by DNS built-in commands.
• Playback is case sensitive.

I suppose one of my unconscious assumptions about Playback is if it failed has a command it would print out as free dictation with DNS. Clearly by the tests above this is not the case. I believe this internal assumption came about the playback command didn't find a command and the playback was defined by lowercase words it would simply print out as free dictation.

I will look into Casters postprocessing function could be fixed to just remove the again do without disturbing the engines expected format from history. The assumption being the history reported is always valid for dragonfly playback per back-end.

You might want to update the title to what you feel best reflects the issue at hand. if you feel more in depth testing is needed I could view the these tests through debugging.

[drmfinlay]

Sorry for the late response. I don't understand why DNS is picky with capitals like this. I'm happy to update the documentation.

The recursion error is expected in the case where you recognise "buffalo bills" and then mimic it again. An exception caught and displayed by Natlink is certainly better than it looping forever. 😉

[drmfinlay]

I think these things should be documented in a new page for the Natlink engine back-end. The documentation for Playback and Mimic can then reference that page.

Some of the other engine back-ends also have quirky mimic behaviour, e.g. SAPI 5 sometimes fails to mimic commands for no discernible reason. The SAPI 5 engine back-end's mimic() method can actually crash Python in certain situations. I'll put together a new page for that engine as well.