Skip to content
This repository has been archived by the owner on Jun 9, 2023. It is now read-only.

Latest commit

 

History

History
112 lines (95 loc) · 12 KB

hs.speech.listener.md

File metadata and controls

112 lines (95 loc) · 12 KB
Raw

docs » hs.speech.listener

This module provides access to the Speech Recognizer component of OS X.

The speech recognizer functions and methods provide a way to add commands which may be issued to Hammerspoon through spoken words and phrases to trigger a callback.

API Overview

API Documentation

Constructors

new

Signature hs.speech.listener.new([title]) -> recognizerObject
Type Constructor
Description Creates a new speech recognizer object for use by Hammerspoon.
Parameters
  • title - an optional parameter specifying the title under which commands assigned to this speech recognizer will be listed in the Dictation Commands display when it is visible. Defaults to "Hammerspoon".
Returns
  • a speech recognizer object or nil, if the system was unable to create a new recognizer.
Notes
  • You can change the title later with the hs.speech.listener:title method.

Methods

blocksOtherRecognizers

| Signature | hs.speech.listener:blocksOtherRecognizers([flag]) -> recognizerObject | current value | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set whether or not the speech recognizer should block other recognizers when it is active. | | Parameters |

  • flag - an optional boolean indicating whether or not the speech recognizer should block other speech recognizers when it is active. Defaults to false.
| | Returns |
  • If no parameter is provided, returns the current value; otherwise returns the recognizer object.
|

commands

| Signature | hs.speech.listener:commands([commandsArray]) -> recognizerObject | current value | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set the commands this speech recognizer will listen for. | | Parameters |

  • commandsArray - an optional array of strings which specify the commands the recognizer will listen for.
| | Returns |
  • If no parameter is provided, returns the current value; otherwise returns the recognizer object.
| | Notes |
  • The list of commands will appear in the Dictation Commands window, if it is visible, under the title of this speech recognizer. The text of each command is a possible value which may be sent as the second argument to a callback function for this speech recognizer, if one is defined.
  • Setting this to an empty list does not disable the speech recognizer, but it does make it of limited use, other than to provide a title in the Dictation Commands window. To disable the recognizer, use the hs.speech.listener:stop or hs.speech.listener:delete methods.
|

delete

Signature hs.speech.listener:delete() -> recognizerObject
Type Method
Description Disables the speech recognizer and removes it from the possible available speech recognizers.
Parameters
  • None.
Returns
  • None
Notes
  • this disables the speech recognizer and removes it from the list in the Dictation Commands window. The object is effectively destroyed, so you will need to create a new one with hs.speech.listener.new if you want to bring it back.
  • if this was the only speech recognizer currently available, the Dictation Commands window and feedback display will be removed from the users display.
  • this method is automatically called during a reload or restart of Hammerspoon.

foregroundOnly

| Signature | hs.speech.listener:foregroundOnly([flag]) -> recognizerObject | current value | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set whether or not the speech recognizer is active only when the Hammerspoon application is active. | | Parameters |

  • flag - an optional boolean indicating whether or not the speech recognizer should respond to commands only when Hammerspoon is the active application or not. Defaults to true.
| | Returns |
  • If no parameter is provided, returns the current value; otherwise returns the recognizer object.
|

isListening

Signature hs.speech.listener:isListening() -> boolean
Type Method
Description Returns a boolean value indicating whether or not the recognizer is currently enabled (started).
Parameters
  • None
Returns
  • true if the listener is listening (has been started) or false if it is not.

setCallback

Signature hs.speech.listener:setCallback(fn) -> recognizerObject
Type Method
Description Sets or removes a callback function for the speech recognizer.
Parameters
  • fn - a function to set as the callback for this speech synthesizer. If the value provided is nil, any currently existing callback function is removed. The callback function should accept two arguments and return none. The arguments will be the speech recognizer object itself and the string of the command which was spoken.
Returns
  • the recognizer object
Notes
  • Possible string values for the command spoken are set with the hs.speech.listener:commands method.
  • Removing the callback does not disable the speech recognizer, but it does make it of limited use, other than to provide a list in the Dictation Commands window. To disable the recognizer, use the hs.speech.listener:stop or hs.speech.listener:delete methods.

start

Signature hs.speech.listener:start() -> recognizerObject
Type Method
Description Make the speech recognizer active.
Parameters
  • None.
Returns
  • returns the recognizer object.

stop

Signature hs.speech.listener:stop() -> recognizerObject
Type Method
Description Disables the speech recognizer.
Parameters
  • None.
Returns
  • returns the recognizer object.
Notes
  • this only disables the speech recognizer. To completely remove it from the list in the Dictation Commands window, use hs.speech.listener:delete.

title

| Signature | hs.speech.listener:title([title]) -> recognizerObject | current value | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set the title for a speech recognizer. | | Parameters |

  • title - an optional parameter specifying the title under which commands assigned to this speech recognizer will be listed in the Dictation Commands display when it is visible. If you provide an explicit nil, it will reset to the default of "Hammerspoon".
| | Returns |
  • If no parameter is provided, returns the current value; otherwise returns the recognizer object.
|