PyPI - ovos-ww-plugin-wakeforge - Versions diffs - 0.0.1a2__tar.gz - Mend

ovos-ww-plugin-wakeforge 0.0.1a2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (15) hide show

ovos_ww_plugin_wakeforge-0.0.1a2/LICENSE ADDED Viewed

@@ -0,0 +1,203 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+   1. Definitions.
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+   END OF TERMS AND CONDITIONS
+   APPENDIX: How to apply the Apache License to your work.
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+   Copyright 2025 Casimiro Ferreira
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+       http://www.apache.org/licenses/LICENSE-2.0
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

ovos_ww_plugin_wakeforge-0.0.1a2/PKG-INFO ADDED Viewed

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: ovos-ww-plugin-wakeforge
+Version: 0.0.1a2
+Summary: OVOS wake word plugin for models trained with wakeforge
+Author-email: JarbasAi <jarbasai@mailfence.com>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/OpenVoiceOS/ovos-ww-plugin-wakeforge
+Project-URL: Repository, https://github.com/OpenVoiceOS/ovos-ww-plugin-wakeforge
+Keywords: mycroft,ovos,plugin,wake,word,wakeforge
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: onnxruntime>=1.20
+Requires-Dist: numpy
+Requires-Dist: requests
+Requires-Dist: ovos-plugin-manager<3.0.0,>=2.1.0
+Requires-Dist: ovos-utils<1.0.0,>=0.0.14
+Provides-Extra: test
+Requires-Dist: pytest<9; extra == "test"
+Requires-Dist: onnx; extra == "test"
+Requires-Dist: ovoscope<1.0.0,>=0.19.0a1; extra == "test"
+Dynamic: license-file
+# ovos-ww-plugin-wakeforge
+An OVOS wake-word plugin for custom models trained with
+[wakeforge](https://github.com/TigreGotico/wakeforge).
+Wakeforge trains a wake-word detector from a single phrase and exports a two-file
+ONNX pipeline: a feature extractor and a classifier head. This plugin loads that
+pipeline and runs it as an always-on hotword engine. The runtime uses
+`onnxruntime` and `numpy` only. It does not need PyTorch.
+## Install
+```bash
+pip install ovos-ww-plugin-wakeforge
+```
+## Train a model
+```bash
+pip install wakeforge
+wakeforge-quickstart "hey jarvis" ./hey_jarvis
+# → ./hey_jarvis/best_f1_featurizer.onnx  +  ./hey_jarvis/best_f1.onnx
+```
+## Configure
+In `mycroft.conf`, point a hotword at the two ONNX files. Use local paths or URLs.
+```json
+{
+  "listener": {
+    "wake_word": "hey_jarvis"
+  },
+  "hotwords": {
+    "hey_jarvis": {
+      "module": "ovos-ww-plugin-wakeforge",
+      "listen": true,
+      "featurizer": "~/hey_jarvis/best_f1_featurizer.onnx",
+      "model": "~/hey_jarvis/best_f1.onnx",
+      "threshold": 0.5
+    }
+  }
+}
+```
+### Config keys
+| key | default | description |
+|-----|---------|-------------|
+| `featurizer` | — (required) | feature-extractor ONNX (path or URL) |
+| `model` | — (required) | classifier-head ONNX (path or URL) |
+| `vad` | none | optional VAD ONNX for an extra channel |
+| `threshold` | `0.5` | detection threshold |
+| `smoothing` | `ema` | `ema` \| `mean` \| `max` |
+| `patience` | `3` | consecutive above-threshold frames to fire |
+| `debounce_sec` | `1.0` | minimum seconds between triggers |
+| `window_size` | `5` | smoother rolling window (mean/max) |
+| `ema_alpha` | `0.3` | EMA responsiveness |
+| `streaming` | `false` | use the stateful streaming (GRU) head |
+| `gru_window` | `100` | window the streaming head was exported with |
+| `hidden_dim` | `128` | GRU hidden size of the streaming head |
+URL models are cached under `${XDG_DATA_HOME}/wakeforge/`.
+## Related projects
+- [TigreGotico/wakeforge](https://github.com/TigreGotico/wakeforge) trains the ONNX models this plugin loads.
+- [OpenVoiceOS/ovos-plugin-manager](https://github.com/OpenVoiceOS/ovos-plugin-manager) loads and manages this plugin alongside other STT, TTS, and wake-word plugins.
+- [OpenVoiceOS/ovos-ww-plugin-precise-onnx](https://github.com/OpenVoiceOS/ovos-ww-plugin-precise-onnx) is a sibling wake-word plugin that runs Precise models through ONNX.
+## Credits
+Developed by [TigreGótico](https://tigregotico.pt) for
+[OpenVoiceOS](https://openvoiceos.org).
+[![NGI0 Commons Fund](./ngi.png)](https://nlnet.nl/project/OpenVoiceOS)
+This project was funded through the [NGI0 Commons Fund](https://nlnet.nl/commonsfund),
+a fund established by [NLnet](https://nlnet.nl) with financial support from the
+European Commission's [Next Generation Internet](https://ngi.eu) programme, under
+the aegis of [DG Communications Networks, Content and Technology](https://commission.europa.eu/about-european-commission/departments-and-executive-agencies/communications-networks-content-and-technology_en)
+under grant agreement No [101135429](https://cordis.europa.eu/project/id/101135429).
+---
+## License
+Apache-2.0

ovos_ww_plugin_wakeforge-0.0.1a2/README.md ADDED Viewed

@@ -0,0 +1,88 @@
+# ovos-ww-plugin-wakeforge
+An OVOS wake-word plugin for custom models trained with
+[wakeforge](https://github.com/TigreGotico/wakeforge).
+Wakeforge trains a wake-word detector from a single phrase and exports a two-file
+ONNX pipeline: a feature extractor and a classifier head. This plugin loads that
+pipeline and runs it as an always-on hotword engine. The runtime uses
+`onnxruntime` and `numpy` only. It does not need PyTorch.
+## Install
+```bash
+pip install ovos-ww-plugin-wakeforge
+```
+## Train a model
+```bash
+pip install wakeforge
+wakeforge-quickstart "hey jarvis" ./hey_jarvis
+# → ./hey_jarvis/best_f1_featurizer.onnx  +  ./hey_jarvis/best_f1.onnx
+```
+## Configure
+In `mycroft.conf`, point a hotword at the two ONNX files. Use local paths or URLs.
+```json
+{
+  "listener": {
+    "wake_word": "hey_jarvis"
+  },
+  "hotwords": {
+    "hey_jarvis": {
+      "module": "ovos-ww-plugin-wakeforge",
+      "listen": true,
+      "featurizer": "~/hey_jarvis/best_f1_featurizer.onnx",
+      "model": "~/hey_jarvis/best_f1.onnx",
+      "threshold": 0.5
+    }
+  }
+}
+```
+### Config keys
+| key | default | description |
+|-----|---------|-------------|
+| `featurizer` | — (required) | feature-extractor ONNX (path or URL) |
+| `model` | — (required) | classifier-head ONNX (path or URL) |
+| `vad` | none | optional VAD ONNX for an extra channel |
+| `threshold` | `0.5` | detection threshold |
+| `smoothing` | `ema` | `ema` \| `mean` \| `max` |
+| `patience` | `3` | consecutive above-threshold frames to fire |
+| `debounce_sec` | `1.0` | minimum seconds between triggers |
+| `window_size` | `5` | smoother rolling window (mean/max) |
+| `ema_alpha` | `0.3` | EMA responsiveness |
+| `streaming` | `false` | use the stateful streaming (GRU) head |
+| `gru_window` | `100` | window the streaming head was exported with |
+| `hidden_dim` | `128` | GRU hidden size of the streaming head |
+URL models are cached under `${XDG_DATA_HOME}/wakeforge/`.
+## Related projects
+- [TigreGotico/wakeforge](https://github.com/TigreGotico/wakeforge) trains the ONNX models this plugin loads.
+- [OpenVoiceOS/ovos-plugin-manager](https://github.com/OpenVoiceOS/ovos-plugin-manager) loads and manages this plugin alongside other STT, TTS, and wake-word plugins.
+- [OpenVoiceOS/ovos-ww-plugin-precise-onnx](https://github.com/OpenVoiceOS/ovos-ww-plugin-precise-onnx) is a sibling wake-word plugin that runs Precise models through ONNX.
+## Credits
+Developed by [TigreGótico](https://tigregotico.pt) for
+[OpenVoiceOS](https://openvoiceos.org).
+[![NGI0 Commons Fund](./ngi.png)](https://nlnet.nl/project/OpenVoiceOS)
+This project was funded through the [NGI0 Commons Fund](https://nlnet.nl/commonsfund),
+a fund established by [NLnet](https://nlnet.nl) with financial support from the
+European Commission's [Next Generation Internet](https://ngi.eu) programme, under
+the aegis of [DG Communications Networks, Content and Technology](https://commission.europa.eu/about-european-commission/departments-and-executive-agencies/communications-networks-content-and-technology_en)
+under grant agreement No [101135429](https://cordis.europa.eu/project/id/101135429).
+---
+## License
+Apache-2.0

ovos_ww_plugin_wakeforge-0.0.1a2/ovos_ww_plugin_wakeforge/__init__.py ADDED Viewed

@@ -0,0 +1,146 @@
+"""OVOS wake-word plugin for models trained with wakeforge.
+Loads a wakeforge two-file ONNX pipeline (featurizer + classifier head) and runs
+it as an always-on hotword detector. Pure runtime: numpy + onnxruntime, no torch.
+"""
+from os import makedirs
+from os.path import isfile, join, expanduser
+import numpy as np
+import requests
+from ovos_plugin_manager.templates.hotwords import HotWordEngine
+from ovos_utils.log import LOG
+from ovos_utils.xdg_utils import xdg_data_home
+from ovos_ww_plugin_wakeforge.inference import (
+    OnnxStreamingWakeWord,
+    OnnxWakeWordInferencer,
+    PredictionSmoother,
+)
+class WakeForgeHotwordPlugin(HotWordEngine):
+    """Detect a wake word using a model trained with wakeforge.
+    wakeforge exports a two-file ONNX pipeline — a feature extractor and a
+    classifier head. Point this plugin at both (local paths or HTTP URLs) via the
+    ``hotwords.<phrase>`` section of ``mycroft.conf``::
+        "hotwords": {
+            "hey_jarvis": {
+                "module": "ovos-ww-plugin-wakeforge",
+                "featurizer": "/path/to/best_f1_featurizer.onnx",
+                "model": "/path/to/best_f1.onnx",
+                "threshold": 0.5
+            }
+        }
+    Recognised config keys:
+        featurizer (str): path/URL to the feature-extractor ONNX (required).
+        model (str): path/URL to the classifier-head ONNX (required).
+        vad (str): optional path/URL to a VAD ONNX (extra channel).
+        threshold (float): detection threshold, default 0.5.
+        smoothing (str): ``"ema"`` | ``"mean"`` | ``"max"``, default ``"ema"``.
+        patience (int): consecutive above-threshold frames to fire, default 3.
+        debounce_sec (float): minimum seconds between triggers, default 1.0.
+        window_size (int): smoother rolling-window size (mean/max), default 5.
+        ema_alpha (float): EMA responsiveness, default 0.3.
+        streaming (bool): use the stateful streaming head (GRU), default False.
+        gru_window (int): window the streaming head was exported with, default 100.
+        hidden_dim (int): GRU hidden size for the streaming head, default 128.
+    """
+    def __init__(self, key_phrase="hey jarvis", config=None):
+        super().__init__(key_phrase, config)
+        self.trigger_flag = False
+        self.threshold = float(self.config.get("threshold", 0.5))
+        self.streaming = bool(self.config.get("streaming", False))
+        featurizer = self.config.get("featurizer")
+        model = self.config.get("model")
+        if not featurizer or not model:
+            raise ValueError(
+                "wakeforge plugin needs both 'featurizer' and 'model' ONNX paths "
+                "in the hotword config (train one with `wakeforge-quickstart`)."
+            )
+        featurizer = self._resolve(featurizer)
+        model = self._resolve(model)
+        vad = self.config.get("vad")
+        vad = self._resolve(vad) if vad else None
+        self.smoother = PredictionSmoother(
+            method=self.config.get("smoothing", "ema"),
+            window_size=int(self.config.get("window_size", 5)),
+            threshold=self.threshold,
+            patience=int(self.config.get("patience", 3)),
+            debounce_sec=float(self.config.get("debounce_sec", 1.0)),
+            ema_alpha=float(self.config.get("ema_alpha", 0.3)),
+        )
+        if self.streaming:
+            self.engine = OnnxStreamingWakeWord(
+                featurizer, model,
+                window=int(self.config.get("gru_window", 100)),
+                hidden_dim=int(self.config.get("hidden_dim", 128)),
+            )
+        else:
+            self.engine = OnnxWakeWordInferencer(featurizer, model, vad_path=vad,
+                                                 device="cpu")
+        self._cache = None
+        LOG.info(f"wakeforge wake word '{self.key_phrase}' loaded "
+                 f"(streaming={self.streaming}, threshold={self.threshold})")
+    def _resolve(self, model):
+        """Resolve a model reference to a local file path, downloading URLs."""
+        if model.startswith("http"):
+            return self.download_model(model)
+        path = expanduser(model)
+        if not isfile(path):
+            raise ValueError(f"Model not found: {path}")
+        return path
+    @staticmethod
+    def download_model(url):
+        """Download an ONNX model to the XDG data dir (cached) and return its path."""
+        name = url.split("/")[-1]
+        folder = join(xdg_data_home(), "wakeforge")
+        model_path = join(folder, name)
+        if not isfile(model_path):
+            LOG.info(f"Downloading wakeforge ONNX model: {url}")
+            response = requests.get(url)
+            response.raise_for_status()
+            makedirs(folder, exist_ok=True)
+            with open(model_path, "wb") as f:
+                f.write(response.content)
+            LOG.info(f"Model downloaded to {model_path}")
+        return model_path
+    def update(self, chunk):
+        """Process a raw 16-bit PCM chunk and update the trigger flag."""
+        audio = np.frombuffer(chunk, dtype=np.int16).astype(np.float32) / 32768.0
+        if audio.size == 0:
+            return
+        if self.streaming:
+            prob = self.engine.push(audio)
+            self.smoother.update(prob)
+        else:
+            _, self._cache = self.engine.infer_streaming(
+                audio, self._cache, smoother=self.smoother)
+        if self.smoother.is_triggered():
+            self.trigger_flag = True
+    def found_wake_word(self):
+        """Return True (once) if the wake word fired since the last call."""
+        if self.trigger_flag:
+            self.trigger_flag = False
+            self.reset()
+            return True
+        return False
+    def reset(self):
+        """Clear streaming/smoothing state between detections."""
+        self.smoother.reset()
+        self._cache = None
+        if self.streaming:
+            self.engine.reset()

ovos_ww_plugin_wakeforge-0.0.1a2/ovos_ww_plugin_wakeforge/inference.py ADDED Viewed

@@ -0,0 +1,446 @@
+# Vendored from wakeforge/inference.py (https://github.com/TigreGotico/wakeforge).
+# wakeforge is the source of truth — keep this copy in sync on runtime changes.
+# Pure runtime: numpy + onnxruntime only, no torch.
+"""ONNX-only wake word inference — no PyTorch dependency at runtime."""
+from __future__ import annotations
+import math
+from collections import deque
+from typing import Optional
+import numpy as np
+import onnxruntime as ort
+class PredictionSmoother:
+    """Smooths raw per-frame predictions for robust wake word detection.
+    Inspired by openWakeWord's prediction buffer + patience mechanism
+    and EfficientWord-Net's relaxation time.
+    Supports three smoothing methods:
+    - ``"ema"``: Exponential moving average (fast response, smooth decay).
+    - ``"mean"``: Rolling window mean (stable, uniform weighting).
+    - ``"max"``: Rolling window max (aggressive, catches peaks).
+    Args:
+        method: Smoothing method — ``"ema"``, ``"mean"``, or ``"max"``.
+        window_size: Number of frames in the rolling buffer (for mean/max).
+        threshold: Detection threshold for ``is_triggered()``.
+        patience: Number of consecutive above-threshold frames required.
+        debounce_sec: Minimum seconds between consecutive triggers.
+        frame_rate_hz: Approximate frame rate for debounce timing.
+        ema_alpha: Smoothing factor for EMA (default 0.3). Higher = more responsive.
+    """
+    def __init__(
+        self,
+        method: str = "ema",
+        window_size: int = 5,
+        threshold: float = 0.5,
+        patience: int = 3,
+        debounce_sec: float = 1.0,
+        frame_rate_hz: float = 10.0,
+        ema_alpha: float = 0.3,
+    ) -> None:
+        if method not in ("ema", "mean", "max"):
+            raise ValueError(f"Unknown smoothing method: {method!r}. Use 'ema', 'mean', or 'max'.")
+        self.method = method
+        self.window_size = window_size
+        self.threshold = threshold
+        self.patience = patience
+        self.debounce_frames = int(debounce_sec * frame_rate_hz)
+        self.ema_alpha = ema_alpha
+        self._buffer: deque = deque(maxlen=window_size)
+        self._ema_value: float = 0.0
+        self._consecutive_above: int = 0
+        self._frames_since_trigger: int = self.debounce_frames  # allow first trigger
+        self._smoothed: float = 0.0
+    def update(self, raw_prob: float) -> float:
+        """Feed a new raw prediction and return the smoothed value.
+        Args:
+            raw_prob: Raw sigmoid probability from model.
+        Returns:
+            Smoothed probability.
+        """
+        self._frames_since_trigger += 1
+        if self.method == "ema":
+            self._ema_value = self.ema_alpha * raw_prob + (1.0 - self.ema_alpha) * self._ema_value
+            self._smoothed = self._ema_value
+        elif self.method == "mean":
+            self._buffer.append(raw_prob)
+            self._smoothed = sum(self._buffer) / len(self._buffer)
+        elif self.method == "max":
+            self._buffer.append(raw_prob)
+            self._smoothed = max(self._buffer)
+        if self._smoothed >= self.threshold:
+            self._consecutive_above += 1
+        else:
+            self._consecutive_above = 0
+        return self._smoothed
+    def is_triggered(self) -> bool:
+        """Check if a detection should fire.
+        Returns True when smoothed probability exceeds threshold for
+        ``patience`` consecutive frames AND debounce window has elapsed.
+        Returns:
+            True if wake word detected.
+        """
+        if (self._consecutive_above >= self.patience
+                and self._frames_since_trigger >= self.debounce_frames):
+            self._frames_since_trigger = 0
+            self._consecutive_above = 0
+            return True
+        return False
+    def reset(self) -> None:
+        """Reset smoother state."""
+        self._buffer.clear()
+        self._ema_value = 0.0
+        self._consecutive_above = 0
+        self._frames_since_trigger = self.debounce_frames
+        self._smoothed = 0.0
+class OnnxWakeWordInferencer:
+    """Run wake word detection using multiple ONNX sessions.
+    This class has no dependency on PyTorch. Only numpy and onnxruntime are required.
+    A text featurizer ONNX can optionally be supplied alongside the audio featurizer.
+    When present, :meth:`infer` accepts ``text_token_ids`` and appends the resulting
+    text embedding as extra feature channels before running the classifier head —
+    exactly the same pattern used for the optional VAD channel.
+    Args:
+        extractor_path: Path to the audio feature extractor ONNX file.
+        head_path: Path to the classifier head ONNX file.
+        vad_path: Optional path to a VAD ONNX file (e.g. Silero VAD).
+        text_extractor_path: Optional path to a text-encoder ONNX file.
+            The ONNX must accept ``[1, seq_len]`` int64 token IDs and return
+            ``[1, 1, D]`` or ``[1, D]`` float32 embeddings.
+        text_emb_dim: Output embedding dimension of the text featurizer (``D``).
+        sample_rate: Expected audio sample rate in Hz (default 16000).
+        device: ``"cpu"``, ``"cuda"``, or ``"auto"`` (selects CUDA if available).
+    """
+    def __init__(self, extractor_path: str, head_path: str,
+                 vad_path: Optional[str] = None,
+                 text_extractor_path: Optional[str] = None,
+                 text_emb_dim: int = 128,
+                 sample_rate: int = 16000, device: str = "auto") -> None:
+        if device == "auto":
+            available = ort.get_available_providers()
+            device = "cuda" if "CUDAExecutionProvider" in available else "cpu"
+        providers = (["CUDAExecutionProvider", "CPUExecutionProvider"]
+                     if device == "cuda" else ["CPUExecutionProvider"])
+        self.extractor = ort.InferenceSession(extractor_path, providers=providers)
+        self.head = ort.InferenceSession(head_path, providers=providers)
+        self.vad = ort.InferenceSession(vad_path, providers=providers) if vad_path else None
+        self.text_ext = (
+            ort.InferenceSession(text_extractor_path, providers=providers)
+            if text_extractor_path else None
+        )
+        self._text_emb_dim = text_emb_dim
+        self.sample_rate = sample_rate
+        self._ext_input = self.extractor.get_inputs()[0].name
+        self._ext_output = self.extractor.get_outputs()[0].name
+        self._head_input = self.head.get_inputs()[0].name
+        self._head_output = self.head.get_outputs()[0].name
+        if self.vad:
+            self._vad_input = self.vad.get_inputs()[0].name
+            self._vad_output = self.vad.get_outputs()[0].name
+        if self.text_ext:
+            self._text_input = self.text_ext.get_inputs()[0].name
+            self._text_output = self.text_ext.get_outputs()[0].name
+    def _run_text(self, token_ids: "list[int]", target_t: int) -> np.ndarray:
+        """Encode token IDs and expand to ``[1, target_t, D]``."""
+        ids = np.array([token_ids], dtype=np.int64)  # [1, seq_len]
+        out = self.text_ext.run([self._text_output], {self._text_input: ids})[0]
+        # out may be [1, 1, D] or [1, D]
+        if out.ndim == 2:
+            out = out[:, np.newaxis, :]   # [1, 1, D]
+        return np.repeat(out, target_t, axis=1)  # [1, target_t, D]
+    def _run_vad(self, wav: np.ndarray, target_t: int) -> np.ndarray:
+        """Run VAD and interpolate to match target time dimension."""
+        # Silero VAD (v4+) specific: expects 512 sample chunks
+        chunk_size = 512
+        B, L = wav.shape
+        # Pad to multiple of chunk_size
+        pad_len = (chunk_size - (L % chunk_size)) % chunk_size
+        if pad_len > 0:
+            wav = np.pad(wav, ((0, 0), (0, pad_len)))
+        L_padded = wav.shape[1]
+        T_chunks = L_padded // chunk_size
+        # Reshape to batch of chunks
+        chunks = wav.reshape(B * T_chunks, chunk_size)
+        # Run VAD
+        # Note: some Silero versions expect [B, L] or [B, T, 512].
+        # We assume [B_total, 512] for consistency with the feats.py wrapper.
+        vad_out = self.vad.run([self._vad_output], {self._vad_input: chunks})[0]
+        # [B * T_chunks, 1]
+        vad_probs = vad_out.reshape(B, T_chunks, 1)
+        if T_chunks == target_t:
+            return vad_probs
+        # Linear interpolation to match base feature length
+        # [B, T_chunks, 1] -> [B, target_t, 1]
+        x = np.linspace(0, 1, T_chunks)
+        x_new = np.linspace(0, 1, target_t)
+        aligned = np.zeros((B, target_t, 1), dtype=np.float32)
+        for b in range(B):
+            # numpy.interp expects 1D arrays
+            aligned[b, :, 0] = np.interp(x_new, x, vad_probs[b, :, 0])
+        return aligned
+    def infer(self, audio: np.ndarray,
+              text_token_ids: "Optional[list[int]]" = None) -> float:
+        """Infer wake word probability for a single audio waveform.
+        Args:
+            audio: 1-D float32 numpy array at ``self.sample_rate``.
+            text_token_ids: Optional list of integer token IDs for the keyword.
+                Required when ``text_extractor_path`` was supplied at init.
+                The token scheme must match whatever the text-encoder ONNX expects.
+        Returns:
+            Sigmoid probability in [0, 1].
+        """
+        if audio.ndim != 1:
+            raise ValueError("audio must be a 1-D numpy array")
+        wav = audio[np.newaxis, :].astype(np.float32)  # [1, T]
+        feats = self.extractor.run(
+            [self._ext_output], {self._ext_input: wav}
+        )[0]  # [1, T, F]
+        if self.vad:
+            vad_probs = self._run_vad(wav, feats.shape[1])
+            feats = np.concatenate([feats, vad_probs], axis=-1)
+        if self.text_ext is not None and text_token_ids is not None:
+            text_feats = self._run_text(text_token_ids, feats.shape[1])
+            feats = np.concatenate([feats, text_feats], axis=-1)  # [1, T, F+D]
+        logit = self.head.run(
+            [self._head_output], {self._head_input: feats}
+        )[0]  # [1] or scalar
+        logit_val = float(np.asarray(logit).ravel()[0])
+        return float(1.0 / (1.0 + np.exp(-logit_val)))
+    def infer_batch(self, audio_batch: np.ndarray,
+                    text_token_ids: "Optional[list[int]]" = None) -> np.ndarray:
+        """Infer for a batch of equal-length waveforms.
+        Args:
+            audio_batch: float32 array of shape ``[B, T]``.
+            text_token_ids: Optional token IDs shared across the batch.
+        Returns:
+            Sigmoid probabilities array of shape ``[B]``.
+        """
+        if audio_batch.ndim != 2:
+            raise ValueError("audio_batch must be a 2-D numpy array [B, T]")
+        wav = audio_batch.astype(np.float32)
+        feats = self.extractor.run([self._ext_output], {self._ext_input: wav})[0]
+        if self.vad:
+            vad_probs = self._run_vad(wav, feats.shape[1])
+            feats = np.concatenate([feats, vad_probs], axis=-1)
+        if self.text_ext is not None and text_token_ids is not None:
+            B = feats.shape[0]
+            text_feats = self._run_text(text_token_ids, feats.shape[1])  # [1, T, D]
+            text_feats = np.repeat(text_feats, B, axis=0)               # [B, T, D]
+            feats = np.concatenate([feats, text_feats], axis=-1)
+        logits = self.head.run([self._head_output], {self._head_input: feats})[0]
+        logits = np.asarray(logits).ravel()
+        return (1.0 / (1.0 + np.exp(-logits))).astype(np.float32)
+    def infer_streaming(self, audio_chunk: np.ndarray,
+                        cache: np.ndarray | None,
+                        smoother: Optional[PredictionSmoother] = None,
+                        ) -> tuple[float, np.ndarray]:
+        """Process one audio chunk with a rolling feature cache.
+        Args:
+            audio_chunk: 1-D float32 array (one chunk of audio).
+            cache: Previous feature cache [T_cached, F] or None for first call.
+            smoother: Optional PredictionSmoother for temporal smoothing.
+        Returns:
+            (probability, updated_cache) — probability is smoothed if
+            smoother is provided, raw otherwise.
+        """
+        wav = audio_chunk[np.newaxis, :].astype(np.float32)  # [1, T_chunk]
+        new_feats = self.extractor.run(
+            [self._ext_output], {self._ext_input: wav}
+        )[0]  # [1, T_new, F]
+        if self.vad:
+            vad_probs = self._run_vad(wav, new_feats.shape[1])
+            new_feats = np.concatenate([new_feats, vad_probs], axis=-1)
+        new_feats = new_feats.squeeze(0) # [T_new, F_total]
+        if cache is None:
+            cache = new_feats
+        else:
+            cache = np.concatenate([cache, new_feats], axis=0)
+        # Keep last 50 frames (matching SlidingFeatureCacheTensor default)
+        window = 50
+        if cache.shape[0] > window:
+            cache = cache[-window:]
+        feats_input = cache[np.newaxis, :, :]  # [1, T_cached, F]
+        logit = self.head.run(
+            [self._head_output], {self._head_input: feats_input}
+        )[0]
+        logit_val = float(np.asarray(logit).ravel()[0])
+        prob = float(1.0 / (1.0 + np.exp(-logit_val)))
+        if smoother is not None:
+            prob = smoother.update(prob)
+        return prob, cache
+class OnnxStreamingWakeWord:
+    """Stateful streaming wake-word inference — ONNX only, O(chunk) per step.
+    Pairs a featurizer ONNX with a *streaming* head ONNX exported via
+    :meth:`wakeforge.model.GruClassifierHead.export_streaming_onnx`. Unlike
+    :meth:`OnnxWakeWordInferencer.infer_streaming` (which re-runs the head over a
+    cached feature window each call), this carries the GRU hidden state and a
+    sliding window of GRU outputs as model state, so the head never recomputes
+    history — the always-on / MCU pattern. No PyTorch at runtime.
+    Usage::
+        sw = OnnxStreamingWakeWord("feat.onnx", "head_streaming.onnx")
+        for chunk in audio_chunks:          # e.g. 0.1 s of 16 kHz audio
+            prob = sw.push(chunk)
+    Args:
+        featurizer_path: Feature extractor ONNX.
+        streaming_head_path: Streaming head ONNX (state I/O).
+        window: GRU-output window length the head was exported with.
+        hidden_dim: GRU hidden size of the head.
+    """
+    def __init__(self, featurizer_path: str, streaming_head_path: str,
+                 window: int = 100, hidden_dim: int = 128,
+                 hop_samples: int = 160, context_samples: int = 640) -> None:
+        providers = ["CPUExecutionProvider"]
+        self.ext = ort.InferenceSession(featurizer_path, providers=providers)
+        self.head = ort.InferenceSession(streaming_head_path, providers=providers)
+        self._ext_in = self.ext.get_inputs()[0].name
+        self._ext_out = self.ext.get_outputs()[0].name
+        self.window = window
+        self.hidden_dim = hidden_dim
+        self.hop = hop_samples            # featurizer hop (for frame accounting)
+        self.context = context_samples    # left-context carried for clean MFCC
+        self.reset()
+    def reset(self) -> None:
+        """Clear the carried GRU state and audio context (call between utterances)."""
+        self._h = np.zeros((1, 1, self.hidden_dim), dtype=np.float32)
+        self._ow = np.zeros((1, self.window, self.hidden_dim), dtype=np.float32)
+        self._ctx = np.zeros(0, dtype=np.float32)
+    def push(self, audio_chunk: np.ndarray) -> float:
+        """Feed one audio chunk, advance state frame-by-frame, return the score.
+        The chunk is featurized *with* a left-context tail from the previous
+        call so MFCC frames are computed with proper context (avoiding chunk-edge
+        artifacts); only the frames belonging to the new audio are streamed
+        through the stateful head (O(1) per frame). Returns the sigmoid
+        probability after the last new frame.
+        """
+        chunk = audio_chunk.astype(np.float32)
+        buf = np.concatenate([self._ctx, chunk])
+        wav = buf[np.newaxis, :]
+        feats = self.ext.run([self._ext_out], {self._ext_in: wav})[0]  # [1, T, F]
+        # Frames attributable to the new chunk (the rest came from context).
+        n_new = max(1, int(round(len(chunk) / self.hop)))
+        n_new = min(n_new, feats.shape[1])
+        self._ctx = buf[-self.context:] if self.context else np.zeros(0, dtype=np.float32)
+        logit_val = 0.0
+        for t in range(feats.shape[1] - n_new, feats.shape[1]):
+            frame = feats[:, t:t + 1, :].astype(np.float32)
+            logit, self._h, self._ow = self.head.run(
+                None, {"feat_frame": frame, "h_in": self._h, "out_window": self._ow})
+            logit_val = float(np.asarray(logit).ravel()[0])
+        return float(1.0 / (1.0 + np.exp(-logit_val)))
+def cli_main() -> None:
+    """CLI entry point for ``wakeforge-infer``.
+    Run a trained ONNX wake-word model on an audio file and print the
+    confidence score.
+    """
+    import argparse
+    import logging
+    import sys
+    import numpy as np
+    logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
+    parser = argparse.ArgumentParser(
+        prog="wakeforge-infer",
+        description="Score an audio file with a trained ONNX wake-word model.",
+    )
+    parser.add_argument("--featurizer", required=True, help="Path to featurizer ONNX file.")
+    parser.add_argument("--model", required=True, help="Path to head ONNX file.")
+    parser.add_argument("--audio", required=True, help="Path to WAV file (16 kHz mono float32).")
+    parser.add_argument("--threshold", type=float, default=0.5, help="Detection threshold (default 0.5).")
+    parser.add_argument("--device", default="auto", choices=["auto", "cpu", "cuda"])
+    args = parser.parse_args()
+    try:
+        import soundfile as sf
+    except ImportError:
+        try:
+            import torchaudio
+            wav, sr = torchaudio.load(args.audio)
+            if sr != 16000:
+                import torchaudio.functional as F_ta
+                wav = F_ta.resample(wav, sr, 16000)
+            audio = wav.squeeze().numpy().astype(np.float32)
+        except ImportError:
+            print("Install soundfile or torchaudio to load audio files.", file=sys.stderr)
+            sys.exit(1)
+    else:
+        audio, sr = sf.read(args.audio, dtype="float32", always_2d=False)
+        if sr != 16000:
+            print(f"Warning: sample rate is {sr} Hz, expected 16000.", file=sys.stderr)
+    model = OnnxWakeWordInferencer(args.featurizer, args.model, device=args.device)
+    score = model.infer(audio)
+    detected = score >= args.threshold
+    print(f"score={score:.4f}  threshold={args.threshold}  detected={detected}")
+    sys.exit(0 if detected else 1)
+if __name__ == "__main__":
+    cli_main()

ovos_ww_plugin_wakeforge-0.0.1a2/ovos_ww_plugin_wakeforge/version.py ADDED Viewed

@@ -0,0 +1,7 @@
+# START_VERSION_BLOCK
+VERSION_MAJOR = 0
+VERSION_MINOR = 0
+VERSION_BUILD = 1
+VERSION_ALPHA = 2
+# END_VERSION_BLOCK
+__version__ = f"{VERSION_MAJOR}.{VERSION_MINOR}.{VERSION_BUILD}a{VERSION_ALPHA}" if VERSION_ALPHA else f"{VERSION_MAJOR}.{VERSION_MINOR}.{VERSION_BUILD}"

ovos_ww_plugin_wakeforge-0.0.1a2/ovos_ww_plugin_wakeforge.egg-info/PKG-INFO ADDED Viewed

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: ovos-ww-plugin-wakeforge
+Version: 0.0.1a2
+Summary: OVOS wake word plugin for models trained with wakeforge
+Author-email: JarbasAi <jarbasai@mailfence.com>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/OpenVoiceOS/ovos-ww-plugin-wakeforge
+Project-URL: Repository, https://github.com/OpenVoiceOS/ovos-ww-plugin-wakeforge
+Keywords: mycroft,ovos,plugin,wake,word,wakeforge
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: onnxruntime>=1.20
+Requires-Dist: numpy
+Requires-Dist: requests
+Requires-Dist: ovos-plugin-manager<3.0.0,>=2.1.0
+Requires-Dist: ovos-utils<1.0.0,>=0.0.14
+Provides-Extra: test
+Requires-Dist: pytest<9; extra == "test"
+Requires-Dist: onnx; extra == "test"
+Requires-Dist: ovoscope<1.0.0,>=0.19.0a1; extra == "test"
+Dynamic: license-file
+# ovos-ww-plugin-wakeforge
+An OVOS wake-word plugin for custom models trained with
+[wakeforge](https://github.com/TigreGotico/wakeforge).
+Wakeforge trains a wake-word detector from a single phrase and exports a two-file
+ONNX pipeline: a feature extractor and a classifier head. This plugin loads that
+pipeline and runs it as an always-on hotword engine. The runtime uses
+`onnxruntime` and `numpy` only. It does not need PyTorch.
+## Install
+```bash
+pip install ovos-ww-plugin-wakeforge
+```
+## Train a model
+```bash
+pip install wakeforge
+wakeforge-quickstart "hey jarvis" ./hey_jarvis
+# → ./hey_jarvis/best_f1_featurizer.onnx  +  ./hey_jarvis/best_f1.onnx
+```
+## Configure
+In `mycroft.conf`, point a hotword at the two ONNX files. Use local paths or URLs.
+```json
+{
+  "listener": {
+    "wake_word": "hey_jarvis"
+  },
+  "hotwords": {
+    "hey_jarvis": {
+      "module": "ovos-ww-plugin-wakeforge",
+      "listen": true,
+      "featurizer": "~/hey_jarvis/best_f1_featurizer.onnx",
+      "model": "~/hey_jarvis/best_f1.onnx",
+      "threshold": 0.5
+    }
+  }
+}
+```
+### Config keys
+| key | default | description |
+|-----|---------|-------------|
+| `featurizer` | — (required) | feature-extractor ONNX (path or URL) |
+| `model` | — (required) | classifier-head ONNX (path or URL) |
+| `vad` | none | optional VAD ONNX for an extra channel |
+| `threshold` | `0.5` | detection threshold |
+| `smoothing` | `ema` | `ema` \| `mean` \| `max` |
+| `patience` | `3` | consecutive above-threshold frames to fire |
+| `debounce_sec` | `1.0` | minimum seconds between triggers |
+| `window_size` | `5` | smoother rolling window (mean/max) |
+| `ema_alpha` | `0.3` | EMA responsiveness |
+| `streaming` | `false` | use the stateful streaming (GRU) head |
+| `gru_window` | `100` | window the streaming head was exported with |
+| `hidden_dim` | `128` | GRU hidden size of the streaming head |
+URL models are cached under `${XDG_DATA_HOME}/wakeforge/`.
+## Related projects
+- [TigreGotico/wakeforge](https://github.com/TigreGotico/wakeforge) trains the ONNX models this plugin loads.
+- [OpenVoiceOS/ovos-plugin-manager](https://github.com/OpenVoiceOS/ovos-plugin-manager) loads and manages this plugin alongside other STT, TTS, and wake-word plugins.
+- [OpenVoiceOS/ovos-ww-plugin-precise-onnx](https://github.com/OpenVoiceOS/ovos-ww-plugin-precise-onnx) is a sibling wake-word plugin that runs Precise models through ONNX.
+## Credits
+Developed by [TigreGótico](https://tigregotico.pt) for
+[OpenVoiceOS](https://openvoiceos.org).
+[![NGI0 Commons Fund](./ngi.png)](https://nlnet.nl/project/OpenVoiceOS)
+This project was funded through the [NGI0 Commons Fund](https://nlnet.nl/commonsfund),
+a fund established by [NLnet](https://nlnet.nl) with financial support from the
+European Commission's [Next Generation Internet](https://ngi.eu) programme, under
+the aegis of [DG Communications Networks, Content and Technology](https://commission.europa.eu/about-european-commission/departments-and-executive-agencies/communications-networks-content-and-technology_en)
+under grant agreement No [101135429](https://cordis.europa.eu/project/id/101135429).
+---
+## License
+Apache-2.0

ovos_ww_plugin_wakeforge-0.0.1a2/ovos_ww_plugin_wakeforge.egg-info/SOURCES.txt ADDED Viewed

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+ovos_ww_plugin_wakeforge/__init__.py
+ovos_ww_plugin_wakeforge/inference.py
+ovos_ww_plugin_wakeforge/version.py
+ovos_ww_plugin_wakeforge.egg-info/PKG-INFO
+ovos_ww_plugin_wakeforge.egg-info/SOURCES.txt
+ovos_ww_plugin_wakeforge.egg-info/dependency_links.txt
+ovos_ww_plugin_wakeforge.egg-info/entry_points.txt
+ovos_ww_plugin_wakeforge.egg-info/requires.txt
+ovos_ww_plugin_wakeforge.egg-info/top_level.txt
+test/test_wakeforge.py

ovos_ww_plugin_wakeforge-0.0.1a2/ovos_ww_plugin_wakeforge.egg-info/dependency_links.txt ADDED Viewed

	@@ -0,0 +1 @@
1	+

ovos_ww_plugin_wakeforge-0.0.1a2/ovos_ww_plugin_wakeforge.egg-info/entry_points.txt ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ [opm.wake_word]
2	+ ovos-ww-plugin-wakeforge = ovos_ww_plugin_wakeforge:WakeForgeHotwordPlugin

ovos_ww_plugin_wakeforge-0.0.1a2/ovos_ww_plugin_wakeforge.egg-info/requires.txt ADDED Viewed

@@ -0,0 +1,10 @@
+onnxruntime>=1.20
+numpy
+requests
+ovos-plugin-manager<3.0.0,>=2.1.0
+ovos-utils<1.0.0,>=0.0.14
+[test]
+pytest<9
+onnx
+ovoscope<1.0.0,>=0.19.0a1

ovos_ww_plugin_wakeforge-0.0.1a2/ovos_ww_plugin_wakeforge.egg-info/top_level.txt ADDED Viewed

	@@ -0,0 +1 @@
1	+ ovos_ww_plugin_wakeforge

ovos_ww_plugin_wakeforge-0.0.1a2/pyproject.toml ADDED Viewed

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+[project]
+name = "ovos-ww-plugin-wakeforge"
+dynamic = ["version"]
+description = "OVOS wake word plugin for models trained with wakeforge"
+readme = "README.md"
+license = "Apache-2.0"
+authors = [{name = "JarbasAi", email = "jarbasai@mailfence.com"}]
+requires-python = ">=3.10"
+keywords = [
+    "mycroft",
+    "ovos",
+    "plugin",
+    "wake",
+    "word",
+    "wakeforge",
+]
+dependencies = [
+    "onnxruntime>=1.20",
+    "numpy",
+    "requests",
+    "ovos-plugin-manager>=2.1.0,<3.0.0",
+    "ovos-utils>=0.0.14,<1.0.0",
+]
+[project.optional-dependencies]
+test = [
+    "pytest<9",
+    "onnx",
+    "ovoscope>=0.19.0a1,<1.0.0",
+]
+[project.urls]
+Homepage = "https://github.com/OpenVoiceOS/ovos-ww-plugin-wakeforge"
+Repository = "https://github.com/OpenVoiceOS/ovos-ww-plugin-wakeforge"
+[project.entry-points."opm.wake_word"]
+ovos-ww-plugin-wakeforge = "ovos_ww_plugin_wakeforge:WakeForgeHotwordPlugin"
+[tool.setuptools]
+include-package-data = true
+[tool.setuptools.packages.find]
+include = ["ovos_ww_plugin_wakeforge*"]
+[tool.setuptools.dynamic]
+version = {attr = "ovos_ww_plugin_wakeforge.version.__version__"}

ovos_ww_plugin_wakeforge-0.0.1a2/setup.cfg ADDED Viewed

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build =
+tag_date = 0

ovos_ww_plugin_wakeforge-0.0.1a2/test/test_wakeforge.py ADDED Viewed

@@ -0,0 +1,117 @@
+"""Functional tests for ovos-ww-plugin-wakeforge.
+A real trained wakeforge model is large and language/phrase specific, so these
+tests synthesise a tiny two-file ONNX pipeline (featurizer + energy head) and
+drive the plugin through the real onnxruntime sessions. This exercises the full
+plumbing — PCM decode, feature cache, smoothing, trigger/reset — without torch
+or a downloaded model.
+The synthetic head fires on high-energy audio and stays quiet on silence, so the
+detection assertions are deterministic.
+"""
+import numpy as np
+import onnx
+import pytest
+from onnx import TensorProto, helper, numpy_helper
+from ovos_ww_plugin_wakeforge import WakeForgeHotwordPlugin
+def _build_featurizer(path):
+    """audio [1, T] float32 -> feats [1, T, 1] float32 (Unsqueeze on axis 2)."""
+    axes = numpy_helper.from_array(np.array([2], dtype=np.int64), name="axes")
+    node = helper.make_node("Unsqueeze", ["audio", "axes"], ["feats"])
+    graph = helper.make_graph(
+        [node], "featurizer",
+        inputs=[helper.make_tensor_value_info("audio", TensorProto.FLOAT, [1, "T"])],
+        outputs=[helper.make_tensor_value_info("feats", TensorProto.FLOAT, [1, "T", 1])],
+        initializer=[axes],
+    )
+    model = helper.make_model(graph, opset_imports=[helper.make_opsetid("", 13)])
+    onnx.save(model, path)
+def _build_head(path):
+    """feats [1, T, 1] -> logit [1] = mean(|feats|) * 40 - 4 (energy detector)."""
+    scale = numpy_helper.from_array(np.array(40.0, dtype=np.float32), name="scale")
+    bias = numpy_helper.from_array(np.array(4.0, dtype=np.float32), name="bias")
+    nodes = [
+        helper.make_node("Abs", ["feats"], ["a"]),
+        helper.make_node("ReduceMean", ["a"], ["m"], axes=[1, 2], keepdims=0),
+        helper.make_node("Mul", ["m", "scale"], ["s"]),
+        helper.make_node("Sub", ["s", "bias"], ["logit"]),
+    ]
+    graph = helper.make_graph(
+        nodes, "head",
+        inputs=[helper.make_tensor_value_info("feats", TensorProto.FLOAT, [1, "T", 1])],
+        outputs=[helper.make_tensor_value_info("logit", TensorProto.FLOAT, [1])],
+        initializer=[scale, bias],
+    )
+    model = helper.make_model(graph, opset_imports=[helper.make_opsetid("", 13)])
+    onnx.save(model, path)
+@pytest.fixture(scope="module")
+def models(tmp_path_factory):
+    d = tmp_path_factory.mktemp("wakeforge_models")
+    feat, head = str(d / "feat.onnx"), str(d / "head.onnx")
+    _build_featurizer(feat)
+    _build_head(head)
+    return feat, head
+def _engine(models, **cfg):
+    feat, head = models
+    config = {"featurizer": feat, "model": head}
+    config.update(cfg)
+    return WakeForgeHotwordPlugin(key_phrase="hey jarvis", config=config)
+def _pcm(value, n=1600):
+    """n int16 samples all set to `value`, as raw little-endian bytes."""
+    return (np.full(n, value, dtype=np.int16)).tobytes()
+def test_missing_config_raises(models):
+    with pytest.raises(ValueError):
+        WakeForgeHotwordPlugin(key_phrase="x", config={})
+def test_loads(models):
+    eng = _engine(models)
+    assert eng.engine is not None
+    assert not eng.found_wake_word()
+def test_silence_does_not_trigger(models):
+    eng = _engine(models)
+    for _ in range(10):
+        eng.update(_pcm(0))
+        assert not eng.found_wake_word()
+def test_loud_audio_triggers(models):
+    eng = _engine(models, patience=3)
+    detected = False
+    for _ in range(8):
+        eng.update(_pcm(16384))  # ~0.5 full-scale -> high energy
+        if eng.found_wake_word():
+            detected = True
+            break
+    assert detected, "high-energy audio should fire the synthetic detector"
+def test_found_wake_word_resets(models):
+    eng = _engine(models, patience=3)
+    for _ in range(8):
+        eng.update(_pcm(16384))
+        if eng.found_wake_word():
+            break
+    # consumed once; immediately polling again must be False
+    assert not eng.found_wake_word()
+def test_opm_discovery():
+    """Plugin is discoverable through the ovos-plugin-manager entry point."""
+    from ovos_plugin_manager.wakewords import find_wake_word_plugins
+    assert "ovos-ww-plugin-wakeforge" in find_wake_word_plugins()