keywordtensor-edge 1.0.0__tar.gz

keywordtensor_edge-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fabian Kondela
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

keywordtensor_edge-1.0.0/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: keywordtensor-edge
+Version: 1.0.0
+Summary: A lightweight inference library for training custom keyword spotting models and running real-time voice command detection.
+License: MIT
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: sounddevice
+Requires-Dist: onnxruntime
+Requires-Dist: torch
+Requires-Dist: torchaudio
+Requires-Dist: torch-audiomentations
+Requires-Dist: torchcodec
+Requires-Dist: onnx
+Dynamic: license-file

keywordtensor_edge-1.0.0/README.md

@@ -0,0 +1,141 @@
+<div align="center">
+  <img src="assets/logo.png" width="300" alt="KeywordTensor Logo">
+  <br>
+  <p><strong>A Python library for training custom keyword spotting models and running real-time voice command detection.</strong></p>
+
+  [![PyPI - Version](https://img.shields.io/pypi/v/keywordtensor?style=flat-square&color=blue)](https://pypi.org/project/keywordtensor/)
+  [![Python](https://img.shields.io/badge/python-3.8+-blue.svg?style=flat-square&logo=python&logoColor=white)](https://www.python.org)
+  [![License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](LICENSE)
+</div>
+
+---
+
+## ⚡ About KeywordTensor
+KeywordTensor is built for developers who want to integrate voice commands into their Python projects without requiring deep knowledge of audio processing. 
+
+- **Bring your own `.wav` files**: Just put your audio files into folders (e.g., `dataset/hello/`, `dataset/stop/`).
+- **Trigger custom Python actions**: Easily map recognized words directly to your own Python functions. No Speech-to-Text required—KeywordTensor detects predefined commands and directly triggers Python callbacks.
+- **Automated Export & Config**: Training automatically generates your optimized model and its configuration file. This allows you to launch live inference with a single command later. No manual saving required!
+- **Built-in Audio Augmentation**: We automatically mutate your `.wav` files during training (PitchShift, Gain & Polarity Inversion, Colored Noise) to improve robustness in noisy environments.
+- **SpecAugment Pipeline**: Raw audio is converted to Mel-spectrograms with Time and Frequency Masking applied. The model learns to recognize commands even if the microphone crackles or the audio drops out.
+- **Continuous Listening**: A rolling buffer averages predictions over time to prevent sudden false positive clicks.
+- **Full Control**: We hide the complexity by default, but give you full access to all deep learning training and listening parameters (training configuration, validation settings, and inference thresholds).
+
+---
+
+## 📦 Pre-trained Models
+Don't have time to record your own dataset? You can use our ready-to-go models.
+
+- **`prawda_falsz`**
+  [![Live Demo](https://img.shields.io/badge/Live_Demo-Coming_Soon!-4CAF50?style=flat-square&logo=googlechrome&logoColor=white)](#)
+  
+  A highly robust model trained specifically to handle high-pitched children's voices and extremely noisy environments. This model was successfully deployed in a live public demonstration during the *"Noc Naukowców"* (Researchers' Night) event.
+- **More models coming soon!**
+
+---
+
+## 💻 Quick Start & API
+
+### 1. Installation (Choose your variant)
+The library is available in two variants on PyPI depending on your needs:
+
+- **`pip install keywordtensor`**
+  Installs the full training environment. Use this on your PC or Server to train your models.
+
+- **`pip install keywordtensor-edge`**
+  A lightweight runtime variant. It strips out heavy training dependencies (like `fastai`), providing only what is needed for real-time inference (`listen()`). Perfect for Raspberry Pi or IoT devices.
+
+---
+
+### 2. Training your model
+The `.train()` method takes your audio files and trains a neural network using PyTorch and FastAI under the hood. 
+
+```python
+import keywordtensor
+
+model = keywordtensor.Engine()
+
+# The engine automatically applies audio & spectrogram augmentations during training
+model.train(
+    dataset_path="path/to/audio/dataset",
+    model_name="my_custom_model",
+    epochs=30,
+    batch_size=32
+)
+```
+
+**Training parameters:**
+You have total control over the pipeline. Available parameters in `.train()`:
+- `dataset_path` *(required)*: Path to your dataset folder. Any number of folders (classes) is supported.
+- `model_name` *(default: 'myownmodel')*: Name of the final exported model.
+- `epochs` *(default: 30)*: Number of training cycles over your dataset.
+- `batch_size` *(default: 32)*: Number of audio samples processed simultaneously.
+- `learning_rate` *(Automatic)*: The engine dynamically searches for the optimal learning rate for your specific dataset and automatically applies the One-Cycle Policy.
+- `wd` *(default: 0.01)*: Weight decay (L2 penalty) to prevent overfitting.
+- `eps` *(default: 0.01)*: Label smoothing epsilon to improve generalization.
+- `valid_pct` *(default: 0.1)*: Percentage of data reserved for validation.
+- `duration` *(default: 3.0)*: The exact duration of your audio clips in seconds. If an audio clip is shorter, it will be automatically padded with zeros (silence). If it is longer, it will be accurately truncated to match this length.
+- `sr` *(default: 16000)*: Sample rate of your audio files.
+
+---
+
+### 3. Live Inference & Custom Actions
+Once trained (or using a pre-trained model like `prawda_falsz`), you can run real-time inference using your microphone.
+
+```python
+import keywordtensor as kt
+
+model = kt.Engine()
+
+# Define your custom actions
+def on_hello():
+    print("Action triggered: 'Hello' detected!")
+
+def on_stop():
+    print("Action triggered: Stopping the robot!")
+
+# Map keywords to your Python functions with per-keyword cooldowns
+model.listen(
+    model_name="my_custom_model",
+    actions={
+        "hello": {"funkcja": on_hello, "cooldown": 2.0},
+        "stop": {"funkcja": on_stop, "cooldown": 3.0}
+    },
+    min_confidence=0.6,
+    n_averages=3
+)
+```
+
+**Listen parameters:**
+The `.listen()` method itself accepts the following runtime arguments:
+- `model_name` *(required)*: The name of the model to load. You can provide the path to your own trained model, or use the built-in `"prawda_falsz"` model which is highly robust to noise and pitched voices.
+- `actions` *(default: None)*: Optional dictionary mapping detected keywords to Python callbacks. You can pass just a function (defaults to 0.0s cooldown), or a dictionary for precise control: `{"funkcja": your_function, "cooldown": 2.0}`. Cooldowns are tracked individually per keyword!
+- `min_confidence` *(default: 0.6)*: The probability threshold (0.0 to 1.0) required to trigger the action.
+- `n_averages` *(default: 3)*: Temporal smoothing. Averages the last *N* predictions to prevent false positive clicks.
+
+**Config file parameters:**
+The rest of the underlying parameters are loaded automatically from the `<model_name>_config.json` file! 
+When you run `.train()`, this file is automatically generated for you. It looks like this:
+
+```json
+{
+    "labels": ["hello", "stop"],
+    "mean": -40.15,
+    "std": 17.35,
+    "duration": 3.0,
+    "sr": 16000
+}
+```
+
+This file dictates the rules for the inference engine:
+- `labels`: The list of keywords the model was trained on.
+- `duration`: The size of the rolling audio buffer in seconds.
+- `sr`: The microphone sample rate.
+- `mean` / `std`: Normalization statistics for the Mel-spectrogram.
+
+> 💡 **Total Flexibility:** 
+> Want to adjust the microphone sample rate or buffer duration without retraining? Just open the JSON file and edit it! 
+> 
+> **Bringing your own model?** No problem! If you trained an ONNX model entirely outside of KeywordTensor, simply drop it into your folder, create a matching `your_model_config.json` file next to it with the parameters above, and the `.listen()` method will load and run your external model.
+
+

keywordtensor_edge-1.0.0/keywordtensor/__init__.py

@@ -0,0 +1 @@
+from .core import Engine

keywordtensor_edge-1.0.0/keywordtensor/core.py

@@ -0,0 +1,260 @@
+import json
+import torch
+import torchaudio
+import torchaudio.transforms as T
+import onnxruntime as ort
+from pathlib import Path
+import os
+import time
+from collections import deque
+import numpy as np
+import sounddevice as sd
+#klasy niezbedne do transformacji danych audio i spektrogramów
+
+try:
+    from fastai.vision.all import *
+    from fastcore.foundation import L
+    import itertools
+    if not hasattr(L, 'starmap'):
+        L.starmap = lambda self, f: L(itertools.starmap(f, self))
+    from torch_audiomentations import Compose, Shift, Gain, PolarityInversion, AddColoredNoise, PitchShift, HighPassFilter, LowPassFilter
+    HAS_FASTAI = True
+except ImportError:
+    HAS_FASTAI = False
+    class Transform:
+        pass
+    class TensorImage:
+        def __new__(cls, x, *args, **kwargs): 
+            return x
+    def show_image(*args, **kwargs): 
+        pass
+
+
+#zamiana pliku na falę dźwiękową
+class LoadAudio(Transform):
+    def __init__(self, duration=3.0):
+        self.duration = duration
+
+    def encodes(self, file: Path):
+        waveform, sr = torchaudio.load(file)
+        target_length = int(self.duration * sr)
+        if waveform.shape[1] > target_length:
+            waveform = waveform[:, :target_length]
+        elif waveform.shape[1] < target_length:
+            pad_amount = target_length - waveform.shape[1]
+            waveform = torch.nn.functional.pad(waveform, (0, pad_amount))
+        return waveform
+
+#definicja wyświetlenia spektrogramu
+class AudioSpectrogram(TensorImage):
+    def show(self, ctx=None, **kwargs):
+        return show_image(self, ctx=ctx, cmap='magma', **kwargs)
+
+#definicja zamiany fali dźwiękowej na spektrogram
+class WaveformToSpectrogram(Transform):
+    def __init__(self, sr=16000):
+        self.melspec = T.MelSpectrogram(sample_rate=sr, n_mels=128, n_fft=1024, hop_length=128)
+        self.todb    = T.AmplitudeToDB(top_db=80.0)
+        
+    def encodes(self, waveform):
+        spec = self.todb(self.melspec(waveform))
+        return AudioSpectrogram(spec)
+    
+#definicja augmentacji audio
+class AudioAugment(Transform):
+    split_idx = 0 
+    
+    def __init__(self, sr=16000):
+        self.sr = sr
+        
+        self.audio_augcompose = Compose([
+            Shift(min_shift=-0.1, max_shift=0.1, sample_rate=self.sr, p=0.4, rollover=False, output_type="dict"),
+            Gain(min_gain_in_db=-15.0, max_gain_in_db=15.0, p=0.6, output_type="dict"),
+            PolarityInversion(p=0.5, output_type="dict"),
+            AddColoredNoise(min_snr_in_db=20.0, max_snr_in_db=35.0, p=0.6, output_type="dict"),
+            PitchShift(min_transpose_semitones=-8, max_transpose_semitones=8, sample_rate=self.sr, p=0.6, output_type="dict"),
+            HighPassFilter(min_cutoff_freq=50, max_cutoff_freq=300, sample_rate=self.sr, p=0.3, output_type="dict"),
+            LowPassFilter(min_cutoff_freq=5000, max_cutoff_freq=7000, sample_rate=self.sr, p=0.3, output_type="dict"),
+        ], output_type="dict")
+
+    def encodes(self, waveform):
+        audio_input = waveform.unsqueeze(0)
+        augment_dict = self.audio_augcompose(audio_input, sample_rate=self.sr)
+        audio_output = augment_dict.samples
+        return audio_output.squeeze(0)
+    
+#defdinicja augmentacji spektrogramu
+class SpecAugment(Transform):
+    split_idx = 0
+    def __init__(self):
+        self.tmask = T.TimeMasking(time_mask_param=4)
+        self.fmask = T.FrequencyMasking(freq_mask_param=4)
+        
+    def encodes(self, spec: AudioSpectrogram):
+        return self.fmask(self.tmask(spec))
+
+#definicja normalizacji spektrogramu
+class NormalizeSpec(Transform):
+    def __init__(self, mean=0.0, std=1.0):
+        self.mean = mean
+        self.std = std
+
+    def setups(self, items):
+        sum_x, sum_x2, n = 0.0, 0.0, 0
+        for x in items:
+            sum_x += x.sum().item()
+            sum_x2 += (x**2).sum().item()
+            n += x.numel()
+        self.mean = sum_x / n
+        self.std = (sum_x2 / n - self.mean**2)**0.5
+
+    def encodes(self, spec: AudioSpectrogram):
+        normalized = (spec - self.mean) / self.std
+        return AudioSpectrogram(normalized)
+
+    #def decodes(self, spec: AudioSpectrogram):
+        #denormalized = (spec * self.std) + self.mean
+        #return AudioSpectrogram(denormalized)
+        
+
+#klasa gdy ktos chce trenowac swoj wlasny model, a nie korzystac z wbudowanych wytrenowanych przykladow 
+class Engine:
+    def __init__(self):
+        self.model_name = None
+
+    def train(self, dataset_path, epochs=30, batch_size=32, wd=0.01, eps=0.01, valid_pct=0.1, model_name='myownmodel', duration=3.0, sr=16000):
+        if not HAS_FASTAI:
+            raise RuntimeError("Training requires fastai. Install the full package: pip install keywordtensor")
+        
+        self.model_name = model_name
+        
+        get_audio_files = partial(get_files, extensions=['.wav'])
+        files = get_audio_files(Path(dataset_path))
+        splits = RandomSplitter(valid_pct=valid_pct, seed=42)(files)
+        
+        norm_spec = NormalizeSpec()
+        
+        tfms = [
+                [LoadAudio(duration=duration), AudioAugment(sr=sr), WaveformToSpectrogram(sr=sr), norm_spec, SpecAugment()],
+                [parent_label, Categorize()]
+                ]
+        dsets = Datasets(files, tfms, splits=splits)
+        dls = dsets.dataloaders(bs=batch_size)
+
+        model = xresnet18(c_in=1, n_out=len(dls.vocab), pretrained=False)
+        learn = Learner(dls, model, wd=wd, metrics=accuracy, loss_func=LabelSmoothingCrossEntropy(eps=eps))
+        
+        res = learn.lr_find()
+        base_lr = res.valley
+        learn.fit_one_cycle(epochs, lr_max=slice(base_lr/10, base_lr))
+
+        config = {
+            "labels": list(dls.vocab),
+            "mean": float(norm_spec.mean),
+            "std": float(norm_spec.std),
+            "duration": float(duration),
+            "sr": int(sr)
+        }
+        with open(f"{model_name}_config.json", "w", encoding="utf-8") as f:
+            json.dump(config, f, ensure_ascii=False, indent=4)
+
+        x, y = learn.dls.one_batch()
+        dummy_input = x[0].unsqueeze(0).cpu()
+
+        model = learn.model.cpu()
+        model.eval()
+
+        torch.onnx.export(
+            model, 
+            dummy_input, 
+            f"{model_name}.onnx",
+            input_names=['input'],
+            output_names=['output'],
+            opset_version=12,
+            dynamo=False
+            )
+
+
+    def listen(self, model_name, actions=None, min_confidence=0.6, n_averages=3):
+        if actions is None:
+            actions = {}
+            
+        user_model_path = Path(f"{model_name}.onnx")
+        user_config_path = Path(f"{model_name}_config.json")
+        
+        library_dir = os.path.dirname(os.path.abspath(__file__))
+        builtin_base_path = os.path.join(library_dir, "pretrained", model_name)
+        builtin_model_path = Path(f"{builtin_base_path}.onnx")
+        builtin_config_path = Path(f"{builtin_base_path}_config.json")
+
+        if user_model_path.exists() and user_config_path.exists():
+            resolved_path = model_name
+        elif builtin_model_path.exists() and builtin_config_path.exists():
+            resolved_path = builtin_base_path
+            
+        with open(f"{resolved_path}_config.json", "r", encoding="utf-8") as f:
+            cfg = json.load(f)
+            
+        labels = cfg["labels"]
+        sr = cfg["sr"]
+        duration = cfg["duration"]
+        
+        wav_to_spec = WaveformToSpectrogram(sr=sr)
+        normalize_spec = NormalizeSpec(mean=cfg["mean"], std=cfg["std"])
+        
+        sess = ort.InferenceSession(f"{resolved_path}.onnx")
+        inp_name = sess.get_inputs()[0].name
+        
+        buf_len = int(sr * duration)
+        audio_buffer = deque([0.0] * buf_len, maxlen=buf_len)
+        prediction_history = deque(maxlen=n_averages)
+        
+
+        def _audio_callback(indata, frames, time_info, status): 
+            audio_buffer.extend(indata[:, 0])
+
+        last_trigger_times = {}
+
+        with sd.InputStream(samplerate=sr, channels=1, blocksize=int(sr * 0.1), callback=_audio_callback):
+            time.sleep(duration)
+            while True:
+
+                wav_tensor = torch.tensor(list(audio_buffer), dtype=torch.float32)
+
+                spectrogram = wav_to_spec.encodes(wav_tensor)
+                spectrogram = normalize_spec.encodes(spectrogram)
+                
+                onnx_data = spectrogram.unsqueeze(0).unsqueeze(0).numpy()
+                
+                logits = sess.run(None, {inp_name: onnx_data})[0][0]
+                
+                exp_res = np.exp(logits - np.max(logits))
+                probs = exp_res / exp_res.sum()
+                
+                prediction_history.append(probs)
+                
+                if len(prediction_history) == n_averages:
+                    mean_probs = np.mean(prediction_history, axis=0)
+                    idx = np.argmax(mean_probs)
+                    confidence = mean_probs[idx]
+                    predicted_class = labels[idx]
+
+                    if confidence > min_confidence:
+                        if predicted_class in actions:
+                            action_val = actions[predicted_class]
+                            
+                            if callable(action_val):
+                                func = action_val
+                                cooldown = 0.0
+                            else:
+                                func = action_val.get("funkcja")
+                                cooldown = action_val.get("cooldown", 0.0)
+                                
+                            last_time = last_trigger_times.get(predicted_class, 0.0)
+                            
+                            if func and (time.time() - last_time >= cooldown):
+                                func()
+                                prediction_history.clear()
+                                last_trigger_times[predicted_class] = time.time()
+                
+                time.sleep(0.05)

keywordtensor_edge-1.0.0/keywordtensor/pretrained/prawda_falsz_config.json

@@ -0,0 +1,11 @@
+{
+    "labels": [
+        "falsz",
+        "other",
+        "prawda"
+    ],
+    "mean": -40.1587,
+    "std": 17.3580,
+    "duration": 3.0,
+    "sr": 16000
+}

keywordtensor_edge-1.0.0/keywordtensor_edge.egg-info/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: keywordtensor-edge
+Version: 1.0.0
+Summary: A lightweight inference library for training custom keyword spotting models and running real-time voice command detection.
+License: MIT
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: sounddevice
+Requires-Dist: onnxruntime
+Requires-Dist: torch
+Requires-Dist: torchaudio
+Requires-Dist: torch-audiomentations
+Requires-Dist: torchcodec
+Requires-Dist: onnx
+Dynamic: license-file

keywordtensor_edge-1.0.0/keywordtensor_edge.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+keywordtensor/__init__.py
+keywordtensor/core.py
+keywordtensor/pretrained/__init__.py
+keywordtensor/pretrained/prawda_falsz.onnx
+keywordtensor/pretrained/prawda_falsz_config.json
+keywordtensor_edge.egg-info/PKG-INFO
+keywordtensor_edge.egg-info/SOURCES.txt
+keywordtensor_edge.egg-info/dependency_links.txt
+keywordtensor_edge.egg-info/requires.txt
+keywordtensor_edge.egg-info/top_level.txt

keywordtensor_edge-1.0.0/keywordtensor_edge.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

keywordtensor_edge-1.0.0/keywordtensor_edge.egg-info/requires.txt

@@ -0,0 +1,8 @@
+numpy
+sounddevice
+onnxruntime
+torch
+torchaudio
+torch-audiomentations
+torchcodec
+onnx

keywordtensor_edge-1.0.0/keywordtensor_edge.egg-info/top_level.txt

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

keywordtensor_edge-1.0.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "keywordtensor-edge"
+version = "1.0.0"
+description = "A lightweight inference library for training custom keyword spotting models and running real-time voice command detection."
+license = {text = "MIT"}
+dependencies = [
+    "numpy",
+    "sounddevice",
+    "onnxruntime",
+    "torch",
+    "torchaudio",
+    "torch-audiomentations",
+    "torchcodec",
+    "onnx"
+]
+
+[tool.setuptools]
+packages = ["keywordtensor", "keywordtensor.pretrained"]
+
+[tool.setuptools.package-data]
+"keywordtensor.pretrained" = ["*.onnx", "*.json"]

keywordtensor_edge-1.0.0/setup.cfg

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