Model card: standalone use without OpenVoiceOS

README.md

@@ -79,6 +79,61 @@ pip install --pre ovos-ww-plugin-wakeforge
 A model file from this repository also loads by path: set `model` to the local `.onnx` file. The plugin reads
 the featurizer and the default threshold from the model's metadata.
 
+## Use in your own code
+
+The models need only `numpy`, `onnxruntime` and `huggingface_hub`; nothing from OpenVoiceOS. Each model is a small classifier that reads WakeHuBERT-tiny features, so you run two ONNX files: the featurizer, then the wake-word model.
+
+```python
+import numpy as np
+import onnxruntime as ort
+from huggingface_hub import hf_hub_download
+
+word = "jarvis"
+head = ort.InferenceSession(hf_hub_download("OpenVoiceOS/wakehubert-wakewords", f"models/wakehubert_{word}.onnx"))
+meta = head.get_modelmeta().custom_metadata_map
+featurizer_file = "wakehubert_int8.onnx" if meta["pretrained_featurizer"] == "wakehubert-int8" else "wakehubert.onnx"
+feat = ort.InferenceSession(hf_hub_download("TigreGotico/wakehubert-tiny", featurizer_file))
+threshold = float(meta["default_threshold"])
+
+WINDOW = 24000          # 1.5 s of 16 kHz audio: the window the models were trained on (75 feature frames)
+BLOCK = 1280            # score every 80 ms
+DEBOUNCE_BLOCKS = 25    # ignore 2 s after a detection
+
+
+class WakeWordDetector:
+    def __init__(self):
+        self.buf = np.zeros(WINDOW, np.float32)
+        self.cooldown = 0
+
+    def push(self, chunk):
+        """chunk: 1280 float32 samples at 16 kHz in -1..1. Returns (score, detected)."""
+        self.buf = np.concatenate([self.buf, chunk.astype(np.float32)])[-WINDOW:]
+        features = feat.run(None, {"waveform": self.buf[None]})[0]       # [1, 75, 128]
+        logit = head.run(None, {"features": features})[0][0]
+        score = float(1.0 / (1.0 + np.exp(-logit)))
+        self.cooldown = max(0, self.cooldown - 1)
+        detected = score >= threshold and self.cooldown == 0
+        if detected:
+            self.cooldown = DEBOUNCE_BLOCKS
+        return score, detected
+```
+
+From a microphone, for example with `sounddevice`:
+
+```python
+import sounddevice as sd
+
+detector = WakeWordDetector()
+with sd.InputStream(samplerate=16000, channels=1, dtype="float32", blocksize=BLOCK) as stream:
+    while True:
+        chunk, _ = stream.read(BLOCK)
+        score, detected = detector.push(chunk[:, 0])
+        if detected:
+            print(f"{word} detected (score {score:.2f})")
+```
+
+Each block featurizes the last 1.5 s on its own, exactly as the models were trained and scored. The featurizer is causal, the per-block cost is about 1–2 ms on one CPU core for the int8 featurizer, and one featurizer run can feed any number of wake-word models: run `feat` once per block and pass the same `features` to each model. Replace `threshold` to change sensitivity (see below). Checked against the plugin on real recordings: the snippet fires on the same clips.
+
 ## Choosing a threshold
 
 Set `"threshold"` in the hotword config to trade missed wake words against false activations. A lower value