nanowakeword 2.1.2

A lightweight, wake word detection engine. Train custom, high-accuracy models with minimal effort.

Nanowakeword is a next-generation, adaptive framework designed to build high-performance, custom wake word models. More than just a tool, it’s an intelligent engine that train custom models, deploy them anywhere, and integrate them into any project with minimal code. From a Raspberry Pi Zero to a cloud server, from a single device to a distributed edge/cloud system, it handles the full lifecycle.

Quick Access

• Features
• Installation
• Train Model
• Using model & Server
• Performance
• NOTIS
• Support
• FAQ

Choose Your Architecture, Build Your Pro Model

NanoWakeWord is a versatile framework offering a rich library of neural network architectures. Each is optimized for different scenarios, allowing you to build the perfect model for your specific needs. This Colab notebook lets you experiment with any of them.

Architecture	Recommended Use Case	Performance Profile	Start Training
DNN	General use on resource-constrained devices (e.g., MCUs).	Fastest Training, Low Memory	▶️ Launch
RNN	Baseline experiments or educational purposes.	Better than DNN	▶️ Launch
CNN	Short, sharp, and explosive wake words.	Efficient Feature Extraction	▶️ Launch
LSTM	Noisy environments or complex, multi-syllable phrases.	Best-in-Class Noise Robustness	▶️ Launch
GRU	A faster, lighter alternative to LSTM with similar high performance.	Balanced: Speed & Robustness	▶️ Launch
CRNN	Challenging audio requiring both feature and context analysis.	Hybrid Power: CNN + RNN	▶️ Launch
TCN	Modern, high-speed sequential processing.	Faster than RNN (Parallel)	▶️ Launch
BcResNet	Broadcasting-residual network	Accuracy Potential	▶️ Launch
QuartzNet	Top accuracy with a small footprint on edge devices.	Parameter-Efficient & Accurate	▶️ Launch
Transformer	Deep Contextual Understanding via Self-Attention mechanism.	SOTA Performance & Flexibility	▶️ Launch
Conformer	State-of-the-art hybrid for ultimate real-world performance.	SOTA: Global + Local Features	▶️ Launch
E-Branchformer	Bleeding-edge research for potentially the highest accuracy.	Accuracy Potential	▶️ Launch

---

NOTE: Nanowakeword is under active development. For important updates, version-specific notes, and the latest stability status of all features, please refer to our official status document.

➡️ View Latest Release Notes & Project Status

State-of-the-Art Features and Architecture

Nanowakeword is not merely a tool; it's a holistic, end-to-end ecosystem engineered to democratize the creation of state-of-the-art, custom wake word models. It moves beyond simple scripting by integrating a series of automated, production-grade systems that orchestrate the entire lifecycle-from data analysis and feature engineering to advanced training and deployment-optimized inference.

1. Builds a tiny student Model

Built-in knowledge distillation - automatically generates a lightweight gate model from any trained model.

2. The Production-Grade Data Pipeline: From Raw Audio to Optimized Features

Recognizing that data is the bedrock of any great model, Nanowakeword automates the entire data engineering lifecycle with a pipeline designed for scale and quality:

• Phonetic Adversarial Negative Generation: This is a key differentiator. The system moves beyond generic noise and random words by performing a phonetic analysis of your wake word. It then synthesizes acoustically confusing counter-examples—phrases that sound similar but are semantically different. This forces the model to learn fine-grained phonetic boundaries, dramatically reducing the false positive rate in real-world use.

• Dynamic On-the-Fly Augmentation: During training, a powerful augmentation engine injects a rich tapestry of real-world acoustic scenarios in real-time. This includes applying background noise at varying SNR levels, convolving clips with room impulse responses (RIR) for realistic reverberation, and applying a suite of other transformations like pitch shifting and filtering.

• Seamless Large-Scale Data Handling (mmap): The framework shatters the memory ceiling of conventional training scripts. By utilizing memory-mapped files, it streams features directly from disk, enabling seamless training on datasets that can be hundreds of gigabytes or even terabytes in size, all on standard consumer hardware.

3. A Modern Training Paradigm: State-of-the-Art Optimization Techniques

The training process itself is infused with cutting-edge techniques to ensure the final model is not just accurate, but exceptionally robust and reliable:

• Hybrid Loss Architecture: The model's learning is guided by a sophisticated, dual-objective loss function.

• Checkpoint Ensembling / Stochastic Weight Averaging (SWA): Instead of relying on a single "best" checkpoint, the framework identifies and averages the weights of the most stable and high-performing models from the training run. This powerful ensembling technique finds a flatter, more robust minimum in the loss landscape, leading to a final model with provably better generalization to unseen data.

• Resilient, Fault-Tolerant Workflow: Long training sessions are protected. The framework automatically saves the entire training state—model weights, optimizer progress, scheduler state, and even the precise position of the data generator. This allows you to resume an interrupted session from the exact point you left off, ensuring zero progress is lost.

• Transparent Live Dashboard: A clean, dynamic terminal table provides a real-time, transparent view of all effective training parameters as they are being used, offering complete insight into the automated process.

4. The Deployment-Optimized Inference Engine: High Performance on the Edge

A model's true value is in its deployment. Nanowakeword's inference engine is designed from the ground up for efficiency, low latency, and the challenges of real-world deployment:

• Stateful Streaming Architecture: It processes continuous audio streams incrementally, maintaining temporal context via hidden states for recurrent models (like LSTMs/GRUs). This is essential for delivering instant, low-latency predictions in real-time applications.

• Universal Export: The final trained model is exported to the industry-standard ONNX & Pytorch format. This guarantees maximum hardware acceleration and platform-agnostic deployment across a vast range of environments, from powerful servers to resource-constrained edge devices.

• Integrated On-Device Post-Processing Stack: The engine is a complete, production-ready solution. It incorporates an on-device stack that includes optional Voice Activity Detection (VAD) to conserve power, Noise Reduction to enhance clarity, and intelligent Debouncing/Patience Filters. This stack transforms the raw model output into a reliable, robust trigger, ready for integration out of the box.

A Stable & Dependency-Free Workflow

The framework is architected to eliminate the common dependency conflicts that often disrupt machine learning workflows. All required packages are carefully version-managed to guarantee a stable environment from initial setup through to the final training execution.

This design ensures that users can proceed from installation to model generation without encountering environment-related errors, allowing them to focus entirely on building their wake word model.

Getting Started

Prerequisites

• Python 3.9 or higher

Installation

Install the latest stable version from PyPI for inference:

pip install nanowakeword

To train your own models, install the full package with all training dependencies:

pip install "nanowakeword[train]"

Pro-Tip: Bleeding-Edge Updates
While the PyPI package offers the latest stable release, you can install the most up-to-the-minute version directly from GitHub to get access to new features and fixes before they are officially released:

pip install git+https://github.com/arcosoph/nanowakeword.git

Train Model

The primary method for controlling the NanoWakeWord framework is through a .yaml file. This file acts as the central hub for your entire project, defining data paths and controlling which pipeline stages are active.

Simple Example Workflow

1. Prepare Your Data Structure: Organize your raw audio files (.wav, flac etc.) into their respective subfolders or you can generate synthetic data.

   training_data/
   ├── positive/         # Your wake word samples ("hey_nano.wav")
   │   ├── sample.wav
   │   └── user_01.aiff
   ├── negative/         # Speech/sounds that are NOT the wake word
   │   ├── adversarial_word.pcm
   │   └── random_speech.wav
   ├── noise/            # Background noises (fan, traffic, crowd)
   │   ├── cafe.wav
   │   └── office_noise.flac
   └── rir/              # Room Impulse Response files
       ├── small_room.wav
       └── hall.wav
   

2. Define Your Configuration: Create a .yaml file to manage your training pipeline. This approach ensures your experiments are repeatable and well-documented.

   # In your config.yaml
   # Essential Paths (Required)
   model_type: dnn # Or other architectures such as `LSTM`, `GRU`, `RNN`, `Transformer` etc..
   model_name: "my_wakeword_v1"
   output_dir: "./trained_models"
   positive_data_path: "./training_data/positive"
   negative_data_path: "./training_data/negative"
   background_paths:
   - "./training_data/noise"
   rir_paths:
   - "./training_data/rir"
   
   # Enable the stages for a full run
   generate_clips: true
   transform_clips: true
   train_model: true
   
   # Add more setting (Optional)
   # For example, to apply a specific set of parameters:
   n_blocks: 3
   # ...
   steps: 20000
   # ...
   checkpointing:
     enabled: true
     interval_steps: 500
     limit: 3
   # Other...
   

For a full explanation & all parameters, please see the training_config or CONFIGURATION_GUIDE.

3. Execute the Pipeline: Launch the trainer by pointing it to your configuration file. The stages enabled in your config will run automatically.

   nanowakeword -c ./path/to/config.yaml
   

Command-Line Arguments (Overrides)

For on-the-fly experiments or to temporarily modify your pipeline without editing your configuration file, you can use the following command-line arguments. Any flag used will take precedence over the corresponding setting in your config.yaml file.

Argument	Shorthand	Description
--config	-c	Required. Path to the base .yaml configuration file.
--generate_clips	-G	Activates the 'Generation' stage.
--transform_clips	-t	Activates the preparatory 'transform' stage (augmentation and feature extraction).
--train	-T	Activates the final 'Training' stage to build the model.
--distill	-d	Generate a lightweight lite model via knowledge distillation.
--resume	✗	Resumes training from the latest checkpoint in the specified project directory.
--overwrite	✗	Forces regeneration of feature files. Use with caution as this deletes existing data.

Performance and Evaluation

Nanowakeword is engineered to produce state-of-the-art, highly accurate models with exceptional real-world performance. The new dual-loss training architecture, combined with our powerful Intelligent Configuration Engine, ensures models achieve a very low stable loss while maintaining a clear separation between positive and negative predictions. This makes them extremely reliable for always-on, resource-constrained applications.

Below is a typical training performance graph for a model trained on a standard dataset. This entire process, from hyperparameter selection to training duration, is managed automatically by Nanowakeword's core engine.

📈 Training Performance Graph

Key Performance Insights:

• Stable and Efficient Learning: The "Training Loss (Stable/EMA)" curve demonstrates the model's rapid and stable convergence. The loss consistently decreases and flattens, indicating that the model has effectively learned the underlying patterns of the wake word without overfitting. The raw loss (light blue) shows the natural variance between batches, while the stable loss (dark blue) confirms a solid and reliable learning trend.

• Exceptional Confidence and Separation: The final report card is a testament to the model's quality. With an Average Stable Loss of just 0.0086, the model is highly accurate. More importantly, the high margin between the positive and negative confidence scores highlights its decision-making power:

  • Avg. Positive Confidence (Logit): 5.447 (Extremely confident when the wake word is spoken)
  • Avg. Negative Confidence (Logit): -5.721 (Equally confident in rejecting incorrect words and noise) This large separation is crucial for minimizing false activations and ensuring the model responds only when it should.

• Extremely Low False Positive Rate: While real-world performance depends on the environment, our new training methodology, which heavily penalizes misclassifications, produces models with an exceptionally low rate of false activations. A well-trained model often achieves less than one false positive every 16-28 hours on average, making it ideal for a seamless user experience.

Using Your Trained Model (Inference)

Your trained .onnx model is ready for action! The easiest and most powerful way to run inference is with our lightweight NanoInterpreter. It's designed for high performance and requires minimal code to get started.

Here’s a practical example of how to use it:

import pyaudio
import numpy as np
import os
import sys
# Import the interpreter from the library
from nanowakeword import NanoInterpreter  
#                Simple Configuration 
MODEL_PATH = r"model/path/your.onnx"
THRESHOLD = 0.9  # A simple threshold for detection | ⚠️ This may need to be changed (eg, 0.999, 0.80)
# If you want, you can use more advanced methods like VAD or PATIENCE_FRAMES.

# Initialization 
try:
    print(" Initializing NanoInterpreter (Simple Mode)...")
    
    # Load the model with NO advanced features.
    interpreter = NanoInterpreter.load_model(MODEL_PATH)
    
    key = list(interpreter.models.keys())[0]
    print(f" Interpreter ready. Listening for '{key}'...")

    pa = pyaudio.PyAudio()
    stream = pa.open(format=pyaudio.paInt16, channels=1, rate=16000, input=True, frames_per_buffer=1280)

    # Main Loop 
    while True:
        audio_chunk = np.frombuffer(stream.read(1280, exception_on_overflow=False), dtype=np.int16)
        
        # Call predict with NO advanced parameters.
        score = interpreter.predict(audio_chunk).get(key, 0.0)

        # The detection logic is simple and external.
        if score > THRESHOLD:
            print(f"Detected '{key}'! (Score: {score:.2f})")
            interpreter.reset()
        else:
            print(f"Score: {score:.3f}", end='\r', flush=True)

except KeyboardInterrupt:
    print("")

Deployment modes at a glance

Mode	Edge runs	Server runs	Best for
Fully local	mel + embedding + model	✗	Common use
Local cascade	mel + embedding + gate + verifier	✗	Any device with a lite model
Gate + remote verifier	mel + embedding + gate	verifier only	Medium-power edge
Gate + remote full pipeline	gate only	mel + embedding + verifier	Low-power edge (Pi Zero, MCU)
Fully remote	✗	mel + embedding + verifier	Ultra-minimal edge

Server Command-Line Arguments

Available command-line options for configuring, securing, and running the Nanowakeword server.

Argument	Shorthand	Description
--model	✗	Start RemoteVerifier server
--pipeline	✗	verifier_only or full
--port	✗	Server port (default 8765)
--info	✗	Inspect a .onnx model file
--api-key	✗	API keys for client authentication (repeat for multiple keys)
--enable-tokens	✗	Allow clients to exchange API keys for short-lived tokens
--token-ttl	✗	Token lifetime in seconds (default: 3600)
--rate-limit	✗	Max requests per IP per window (0 = disabled)
--rate-window	✗	Rate limit window in seconds (default: 60)
--ip-allowlist	✗	Allow only specific IPs/CIDR ranges
--ssl-certfile / --ssl-keyfile	✗	WSS/TLS certificate files
--ssl-ca-certs	✗	CA bundle for mutual TLS
--max-connections	✗	Maximum simultaneous clients
--ban-duration	✗	Ban time after rate limit breach (default: 300)

༼ つ ◕_◕ ༽つ Learn more about running models, NanoInterpreter, and Server here

🎙️ Pre-trained Models

To help you get started quickly, nanowakeword comes with a rich collection of pre-trained models. These pre-trained models are ready to use and support a wide variety of wake words, eliminating the need to spend time training your own model from scratch.

Because our library of models is constantly evolving with new additions and improvements, we maintain a live, up-to-date list directly on our GitHub project page. This ensures you always have access to the latest information.

For a comprehensive list of all available models and their descriptions, please visit the official model registry:

View the Official List of Pre-trained Models (✿◕‿◕✿)

⚖️ Our Philosophy

In a world of complex machine learning tools, Nanowakeword is built on a simple philosophy:

1. Simplicity First: You shouldn't need a Ph.D. in machine learning to train a high-quality wake word model. We believe in abstracting away the complexity.
2. Intelligence over Manual Labor: The best hyperparameters are data-driven. Our goal is to replace hours of manual tuning with intelligent, automated analysis.
3. Performance on the Edge: Wake word detection should be fast, efficient, and run anywhere. We focus on creating models that are small and optimized for devices like the Raspberry Pi.
4. Empowerment Through Open Source: Everyone should have access to powerful voice technology. By being fully open-source, we empower developers and hobbyists to build the next generation of voice-enabled applications.

FAQ

1. Which Python version should I use?

You can use Python 3.8 to 3.13. This setup has been tested and is fully supported.

2. What kind of hardware do I need for training?

Training can be performed on any modern device, including standard CPUs, without requiring specialized hardware. While a dedicated GPU can accelerate the process, it is not necessary. The training pipeline is optimized to run efficiently even on low-end systems.

3. How much data do I need to train a good model?

For a good starting point, we recommend at least 10000+ clean data of your wake words from a few different voices. The total duration of negative audio should be at least 3 times longer than positive audio. You can also create synthetic words using Nanowakeword. The more data you have, the better your model will be. Our intelligent engine is designed to work well even with small datasets.

4. Can I train a model for a language other than English?

Yes! Nanowakeword is language-agnostic. As long as you can provide audio samples for your wake words, you can train a model for any language.

5. What platforms are supported for running the trained model?

Inference (running the model) is extremely lightweight and can run smoothly on almost any device, including a Raspberry Pi 3/4, Linux systems, Android devices, and Apple platforms.

6. Is there an official C# port for nanowakeword?

There are no official ports for C#

Community & Support

Assistance for any issue—from data preparation to troubleshooting a stalled training process or an unexpected error—is readily available. The project prioritizes swift and effective solutions to ensure a smooth user experience.

For support, users can get help through the most convenient channel:

• GitHub Issues: For reporting bugs, technical issues, and making feature requests.
• Discord Server: Ideal for general questions, configuration help, and community discussion.
• Official Website: Provides documentation and includes a contact interface for direct communication.

All inquiries are reviewed and addressed as promptly as possible.

Roadmap

Nanowakeword is an actively developed project. Here are some of the features and improvements we are planning for the future:

• E2E: End to End model
• Model Quantization: Tools to automatically quantize the final .onnx model for even better performance on edge devices.
• Model Zoo Expansion: Adding more pre-trained models for different languages and phrases.

Contributing

Contributions are the lifeblood of open source. We welcome contributions of all forms, from bug reports and documentation improvements to new features.

To get started, please see our Contribution Guide, which includes information on setting up a development environment, running trsts, and our code of conduct.

Visit our website

License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.

💙 If you find this helpful, please support us at A r c o s o p h or give our repository a ⭐