From d4616741209f4b2868fe578b210059170eaf3336 Mon Sep 17 00:00:00 2001 From: timonvanhasselt Date: Sun, 10 Sep 2023 22:26:01 +0200 Subject: [PATCH 1/3] Update ht_ww.md A first try to add some extra useful info I got from the OVOS forum (Matrix), that helped me using hotwords. --- docs/ht_ww.md | 53 ++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 50 insertions(+), 3 deletions(-) diff --git a/docs/ht_ww.md b/docs/ht_ww.md index 87096707..d8e11e45 100644 --- a/docs/ht_ww.md +++ b/docs/ht_ww.md @@ -1,9 +1,37 @@ # 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) + * `“bus_event” : “custom message that you use in your own skill”` + +* 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?` + +* take ovos-core out of recording mode, also called a stop_word + * `Example?` -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 +86,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/) From 6fc51b4b8d82a253b3531d5f48bf2be55bbd1277 Mon Sep 17 00:00:00 2001 From: timonvanhasselt Date: Mon, 11 Sep 2023 09:07:11 +0200 Subject: [PATCH 2/3] Update ht_ww.md --- docs/ht_ww.md | 26 +++++++++++++++++++++----- 1 file changed, 21 insertions(+), 5 deletions(-) diff --git a/docs/ht_ww.md b/docs/ht_ww.md index d8e11e45..89aa7e60 100644 --- a/docs/ht_ww.md +++ b/docs/ht_ww.md @@ -16,8 +16,12 @@ Each hotword can do one or more of the following (with example configs): 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) - * `“bus_event” : “custom message that you use in your own skill”` +* 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”` @@ -26,10 +30,22 @@ Each hotword can do one or more of the following (with example configs): * `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?` + * 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 - * `Example?` +* 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) From de774a7fb0dfcb2c66754ac66aeeae62736797bd Mon Sep 17 00:00:00 2001 From: timonvanhasselt Date: Tue, 12 Sep 2023 17:05:53 +0200 Subject: [PATCH 3/3] Update ht_ww.md Changes after review --- docs/ht_ww.md | 37 +++++++++++++++++++------------------ 1 file changed, 19 insertions(+), 18 deletions(-) diff --git a/docs/ht_ww.md b/docs/ht_ww.md index 89aa7e60..f7282c60 100644 --- a/docs/ht_ww.md +++ b/docs/ht_ww.md @@ -1,33 +1,34 @@ # 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" +In OVOS, a WakeWord is configured in the hotwords section of the user's mycroft.conf configuration (defaults to `~/.config/mycroft/mycroft.conf`). Multiple "hotwords" can be configured at one time. They can trigger a variety of tasks, ranging from putting OVOS into active listening mode (the default for "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”` + * `"listen" : true` -* play a sound (only or with other action), you can set a specific sound per hotword. +* play a sound. 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”` + +* emit an 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”` + * `"bus_event" : "custom.message.that.you.use.in.your.own.skill"` or - * `“bus_event” : “mycroft.mic.mute"` + * `"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”` +* Use a hotkey. This allows you to assign a keyboard shortcut (e.g., "ctrl+alt+h") for triggering the hotword manually. The [ovos-ww-plugin-hotkeys](https://github.com/OpenVoiceOS/ovos-ww-plugin-hotkeys) is required for using a hotkey. + * `"hotkey": "control+shift+h"` * assign a language for STT per wake word - * `Example?` + * `"stt_lang": "pt-pt"` (at Speech To Text stage the language code, for example `pt-pt`, will be requested instead of the global language. * be a wakeup word (out of sleep mode); take ovos-core out of sleep mode, also called a wakeup_word or standup_word * Example: @@ -94,18 +95,18 @@ The most important section is `"wake_word": "hey_ziggy"` in the `"listener"` sec This tells OVOS what the default wakeword should be. -In the `"hotwords"` section, `"active": true`, is only used if multiple wakewords are being used. By default, what ever `wake_word` is set in the `listener` section is automatically set to `true`. +In the `"hotwords"` section, `"active": true`, is only used if multiple wakewords are being used. By default, what ever `wake_word` is set in the `listener` section is automatically set to `true`. If you want to disable a wakeword, you can set this to `false`. 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. +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 +## Example hotword config (keyboard wakeword) +In the following example an extra hotword is added, that uses the [ovos-ww-plugin-hotkeys](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-plugin-hotkeys](https://github.com/OpenVoiceOS/ovos-ww-plugin-hotkeys) and add the following to your `~/.config/mycroft/mycroft.conf` file ``` "hotwords": { @@ -119,6 +120,6 @@ Install the `ovos_ww_hotkeys` plug-in and add the following to your `~/.config/m } ``` - +## Read more about WakeWords/HotWords [Advanced WakeWords/HotWords](https://openvoiceos.github.io/ovos-technical-manual/ww_plugins/)