Examples for configuring hotwords

docs/ht_ww.md

@@ -1,9 +1,53 @@
 # OVOS Listener - WakeWords / HotWords
-OVOS uses "wakewords" to activate the system.  This is what "hey Google" or "Alexa" is on proprietary devices.  By default, OVOS uses the WakeWord "hey Mycroft".
+OVOS uses "wakewords" to activate the system. This is what "hey Google" or "Alexa" is on proprietary devices. By default, OVOS uses the WakeWord "hey Mycroft".
+
+OVOS "hotwords" is the configuration section in `mycroft.conf` config  to specify what the WakeWord do.  Multiple "hotwords" can be used to do a variety of things from putting OVOS into active listening mode, a WakeWord like "hey Mycroft", to issuing a command such as "stop" or "wake up"
+
+Each hotword can do one or more of the following (with example configs):
+* trigger listening, also called a wake_word (default option)
+  * `“Listen” : “True”`
+
+* play a sound (only or with other action), you can set a specific sound per hotword.
+  * `"sound": "snd/start_listening.wav"`
+
+* emit a utterance to open a skill directly (instead of listen), useful to open skills from others.
+  * `“utterance” : “What’s the time”` 
+  * `“listen” : “false”`
+
+  This example will start the date & time skill with the given utterance and not listen for a command.
+
+* emit a bus event directly to the messagebus, to for instance open a skill you developed yourself  (instead of listen / utterance), emit a message directly (microphone mute/unmute"
+  *	`“bus_event” : “custom message that you use in your own skill”`
+
+     or
+
+  *	`“bus_event” : “mycroft.mic.mute"`
+
+* Use a hotkey; allows you to assign a keyboard shortcut (e.g., "ctrl+alt+h") for triggering the hotword manually. The ovos_ww_hotkeys module is         required forusing a hotkey.
+  *	`“Hotkey”: “Control+shift+h”`
+
+* assign a language for STT per wake word
+  * `Example?`
+
+* be a wakeup word (out of sleep mode); take ovos-core out of sleep mode, also called a wakeup_word or standup_word
+  * Example:
+```
+  "listener": {
+    // Default wake_word and stand_up_word will be automatically set to active
+    // unless explicitly disabled under "hotwords" section with "active": false. This is usually not
+       desired unless you are looking to completely disable wake word usage
+    "wake_word": "hey mycroft",
+    "stand_up_word": "wake up"
+}
+```
+   See: [skill-ovos-naptime](https://github.com/OpenVoiceOS/skill-ovos-naptime)
+
+
+* Take ovos-core out of recording mode, also called a `stop_word`
+   * A stop word is used when using a record skill like
+    [skill-audio-recordinge](https://github.com/NeonGeckoCom/skill-audio-recording)
 
-OVOS "hotwords" is the configuration section to specify what the WakeWord do.  Multiple "hotwords" can be used to do a variety of things from putting OVOS into active listening mode, a WakeWord like "hey Mycroft", to issuing a command such as "stop" or "wake up"
 
-As with everything else, this too can be changed, and several plugins are available.  Some work better than others.
 
 ## List of OVOS WakeWord Plugins
 | Plugin                                 | Type     | Description                           |
@@ -58,4 +102,23 @@ If enabling a wakeword, be sure to also set `"listen": true`.
 
 Multiple hotwords can be configured at the same time, even the same word with different plugins.  This allows for more accurate ones to be used before the less accurate, but only if the plugin is installed.
 
+
+### Example hotword config (keyboard wakeword)
+In the following example an extra hotword is added, that uses the `ovos_ww_hotkeys` [wake word plugin](https://github.com/OpenVoiceOS/ovos-ww-plugin-hotkeys) to listen for keyboard press and start a skill based on an utterance (in this example to tell the time by just pressing space bar).  
+Install the `ovos_ww_hotkeys` plug-in and add the following to your `~/.config/mycroft/mycroft.conf` file
+
+```
+ "hotwords": {
+    "hotkey": {
+        "module": "ovos_ww_hotkeys",
+        "listen": false,
+        "active": true,
+        "hotkey": "space",
+        "utterance": "what time is it?"
+      }
+  }
+```
+
+
+
 [Advanced WakeWords/HotWords](https://openvoiceos.github.io/ovos-technical-manual/ww_plugins/)