xmanii/hey-nimruz-wakeword

Hey Nimruz wake-word model

hey-nimruz-wakeword is a compact research model for detecting the spoken phrase “Hey Nimruz”, with Nimruz pronounced like the Persian نیمروز. The synthetic speech prompt was written as hey nimrooz so the TTS system would produce the intended pronunciation.

The release contains a 214,273-parameter convolution-and-attention classifier trained on top of the frozen mel-spectrogram and 96-dimensional speech embedding pipeline provided by LiveKit WakeWord. The exported ONNX classifier is 931 KiB.

This is an experimental wake-word model, not a safety-critical voice-control system. It has worked well in an informal real-microphone test with a Persian accent, but it has not yet been evaluated across a controlled population of speakers, microphones, rooms, dialects, or long recordings of natural Persian conversation.

Files

File	Purpose
hey_nimruz.onnx	Inference classifier; input shape (batch, 16, 96)
hey_nimruz.pt	PyTorch checkpoint backup
hey_nimruz_metrics.json	Metrics recorded during the three-phase training loop
training_config.yaml	Exact production training configuration
test_gui.py	Local microphone tester with a browser-based confidence display

The ONNX file is the classifier head. It does not accept PCM audio by itself. livekit-wakeword supplies the frozen audio frontend and embedding model that convert a rolling two-second, 16 kHz audio window into the 16 × 96 classifier input.

Training summary

The model was trained with livekit-wakeword==0.2.1 on an NVIDIA L40S through Modal. Synthetic speech used the Piper VITS backend.

• Target phrase: hey nimrooz
• Classifier: medium Conv1D + self-attention head
• Trainable parameters: 214,273
• Positive speech: 25,000 training and 5,000 validation clips before augmentation
• Adversarial negative speech: 25,000 training and 5,000 validation clips
• Background-only clips: 2,000 training and 500 validation clips
• Augmentation: three rounds using room impulse responses, background mixing, parametric EQ, distortion, timing jitter, and compounded transformations
• Effective augmented positive set: 75,000 training and 15,000 validation clips
• General negative speech: ACAV100M 2,000-hour precomputed feature corpus
• Hard negatives included variations such as nimrooz, nimruz, hey nimrod, hey nimbus, and hey numerous
• Optimizer: AdamW with focal loss, embedding-space mixup, label smoothing, negative-class reweighting, warmup, and cosine decay
• Phase 1: 100,000 main-training steps
• Phase 2: 10,000 refinement steps at one-tenth learning rate
• Phase 3: 10,000 fine-tuning steps at one-hundredth learning rate
• Classifier training time: approximately 31.6 minutes on one L40S, excluding speech synthesis, augmentation, and feature extraction

The MUSAN background download was partially complete when its host rate-limited the setup job. The available MUSAN files were still used alongside the room impulse responses and generated background clips.

Validation results

These figures come from the trainer's held-out validation pass. The validation mixture contained 15,000 augmented positive clips and 46,584 negative clips, including adversarial speech, background audio, and general negative speech features.

Operating point	Recall	Accuracy	Estimated FPPH
Threshold 0.50	82.32%	91.14%	0.696
Selected threshold 0.73	75.33%	87.66%	0.077

FPPH means estimated false positives per hour. These numbers should not be treated as a substitute for long-form testing on real Persian speech. The standalone DET-report command was not completed because of a NumPy API-version mismatch after the model had already been trained, validated, saved, and exported. The raw training-loop metrics are included for inspection.

Microphone test

Python 3.12 is recommended. PortAudio is required by PyAudio; on macOS it can be installed with brew install portaudio.

pip install "livekit-wakeword[listener]==0.2.1" huggingface_hub
huggingface-cli download xmanii/hey-nimruz-wakeword \
  hey_nimruz.onnx hey_nimruz_metrics.json test_gui.py \
  --local-dir hey-nimruz
cd hey-nimruz
python test_gui.py \
  --model hey_nimruz.onnx \
  --metrics hey_nimruz_metrics.json

Open http://127.0.0.1:8765, press Start listening, and say “Hey Nimruz.” The tester uses the selected threshold of 0.73, displays live confidence and microphone level, and lets you adjust the threshold interactively.

For direct integration:

import asyncio
from huggingface_hub import hf_hub_download
from livekit.wakeword import WakeWordListener, WakeWordModel


async def main():
    model_path = hf_hub_download(
        repo_id="xmanii/hey-nimruz-wakeword",
        filename="hey_nimruz.onnx",
    )
    model = WakeWordModel(models=[model_path])

    async with WakeWordListener(model, threshold=0.73, debounce=2.0) as listener:
        while True:
            detection = await listener.wait_for_detection()
            print(detection.name, detection.confidence)


asyncio.run(main())

Intended use

This model is intended for research, prototypes, local assistants, and experiments involving the “Hey Nimruz” activation phrase. It should be tested and thresholded again for the target microphone, acoustic environment, and speaker population before deployment.

Do not use it as the only control for consequential or safety-sensitive actions. A false activation or missed activation must be expected in real conditions.

Suggested evaluation work

• Record positive examples from multiple Persian speakers across genders, ages, dialects, distances, and speaking rates.
• Measure false activations over many hours of natural Persian conversation, television, music, and environmental audio.
• Include close phonetic negatives and sentences containing Nimruz without the complete wake phrase.
• Report recall by speaker and environment rather than only an aggregate score.

Attribution and license

The training and inference pipeline is based on LiveKit WakeWord, Copyright 2026 LiveKit, Inc. LiveKit WakeWord and this model release are distributed under the Apache License 2.0. The synthetic dataset itself is not included in this repository.