Metadata-Version: 2.4
Name: ovos-ww-plugin-vosk
Version: 0.1.13a1
Summary: Kaldi/Vosk wake word plugin for OpenVoiceOS
Author-email: JarbasAi <jarbasai@mailfence.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/OpenVoiceOS/ovos-ww-plugin-vosk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: vosk
Requires-Dist: ovos-plugin-manager<3.0.0,>=2.1.1
Requires-Dist: ovos-bus-client>=0.0.6
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: ovoscope; extra == "test"
Requires-Dist: vosk; extra == "test"
Dynamic: license-file

## Description

Vosk wake word plugin for [OpenVoiceOS](https://github.com/OpenVoiceOS). It uses the
[Vosk](https://alphacephei.com/vosk/) speech recognizer to transcribe short audio
chunks and check the transcript against one or more wake word samples.

## Install

`pip install ovos-ww-plugin-vosk`

## Configuration

### Quick start

Add the following to the `hotwords` section in `mycroft.conf`.

```json
  "listener": {
    "wake_word": "hey_computer"
  },
  "hotwords": {
    "hey_computer": {
        "module": "ovos-ww-plugin-vosk",
        "listen": true
    }
  }
```

Replace `hey_computer` with your wake word. A model downloads automatically for the
configured language.

### Single keyword

Some wake words are hard to trigger, usually because the language model does not
include them. For example, `hey mycroft` is often transcribed as `hey microsoft`. By
default, this plugin checks for the wake word name, but you can configure the keyword
in a number of ways.

- `model_folder` - full path to a Vosk model. Optional; the plugin downloads one automatically.
- `lang` - language code for the model. Optional; uses the global value if not set. Only affects which model downloads.
- `debug` - if true, prints extra info, like the transcript contents.
- `rule` - how to compare the transcript against the samples. See the rules below.
- `time_between_checks` - the length in seconds between inferences. Must be between 0.2 and 3.
- `window_seconds` - the length in seconds of the most recent audio each inference transcribes. Maximum 3. The default is the plugin's `DEFAULT_WINDOW_SECONDS`.
- `full_vocab` - use the full model vocabulary for transcription. If false (default), Vosk runs in keyword mode.
- `samples` - list of samples to match the rules against. Optional; defaults to the keyword name.

```json
  "listener": {
    "wake_word": "hey_computer"
  },
  "hotwords": {
    "hey_computer": {
        "module": "ovos-ww-plugin-vosk",
        "listen": true,
        "full_vocab": true,
        "rule": "equals",
        "debug": true,
        "samples": ["hey computer", "a computer", "hey computed"],
        "model_folder": "/home/user/Downloads/vosk-model-small-en-us-0.4",
        "time_between_checks": 0.6
    }
  }
```

#### Keyword rules

You can define different rules to trigger a wake word.

- `contains` - the transcript contains any of the samples.
- `equals` - the transcript exactly matches any of the samples.
- `starts` - the transcript starts with any of the samples.
- `ends` - the transcript ends with any of the samples.
- `fuzzy` - fuzzy match the transcript against the samples.

Enable the `debug` flag and check the logs to see what the plugin transcribes. Use
this to tune the rule and samples.

Each wake word must fit in 3 seconds, the longest `window_seconds` allowed.

The plugin keeps the last `window_seconds` of audio. After every `time_between_checks`
seconds of new audio, it transcribes that whole window, so a check boundary does not
split a wake word. The check interval counts audio received,
whatever the chunk size. Lower `time_between_checks` values run more checks and use
more CPU. Higher values check less often and may miss short wake words. The default is
1.0. A longer `window_seconds` costs more CPU per check, and a `window_seconds` smaller than `time_between_checks` is raised to it. A window longer than `time_between_checks` catches more phrases but gives more false wake-ups on conversation than a window equal to it, which checks each stretch of audio once. After a detection the window
is cleared, so one utterance triggers once.

Set `full_vocab` to transcribe all known words before applying the detection rules. By
default this is false, and the plugin only looks for the wake word samples. Depending
on the wake word, this may raise or lower accuracy.

### Multiple keywords

A single model per language can check for multiple keywords at once. For example, to
replace the default wake words:

```json
  "hotwords": {
    "hey mycroft": {"active": false},
    "wake up": {"active": false},
    "hey xxx": {
        "module": "ovos-ww-plugin-vosk-multi",
        "listen": true,
        "wakeup": true,
        "keywords": {
           "hey mycroft": {"samples": ["hey mycroft", "hey microsoft", "hey minecraft"], "rule": "fuzzy"},
           "wake up": {"wakeup": true}
        }
    }
```

You can load any number of languages side by side.

```json
  "hotwords": {
    "hey_xxx": {
        "module": "ovos-ww-plugin-vosk-multi",
        "listen": true,
        "full_vocab": false,
        "keywords": {
           "hey mycroft": {"samples": ["hey mycroft", "hey microsoft", "hey minecraft"], "rule": "fuzzy"},
           "hey neon": {},
           "hey computer": {},
           "hey jarvis": {},
           "computador": {"lang": "pt"},
           "jarbas": {"lang": "pt"}
        }
    }
```

## Related projects

- [OpenVoiceOS/ovos-plugin-manager](https://github.com/OpenVoiceOS/ovos-plugin-manager) - loads and manages OVOS plugins, including wake word engines like this one.
- [OpenVoiceOS/ovos-dinkum-listener](https://github.com/OpenVoiceOS/ovos-dinkum-listener) - the OVOS listener service that runs wake word plugins against microphone audio.

## License

Apache-2.0
