tiny-kws

tiny-kws — DS-CNN keyword spotter (12-class Speech Commands v2)

A 119,372-parameter (~0.48 MB fp32) depthwise-separable CNN for spoken command recognition, trained from scratch in PyTorch. Input: 1-second 16 kHz audio → 64×101 log-mel spectrogram. Output: one of 12 classes — the keywords yes, no, up, down, left, right, on, off, stop, go, plus unknown and silence.

• Architecture: DS-CNN (Zhang et al. 2017, arXiv:1711.07128): 10×4 conv stem (stride 2) → 4 depthwise-separable blocks (160 ch, one stride-2) → global average pooling → dropout 0.2 → linear.
• Dataset: Google Speech Commands v0.02 (Warden 2018, arXiv:1804.03209, CC-BY-4.0): 105,829 one-second utterances, 35 words. Official validation/testing lists (speaker-disjoint); "unknown" = seeded 10% sample of the 25 non-keyword words; "silence" = background-noise crops.
• Training: 30 epochs on a free Colab T4 (GPU), AdamW lr 3e-3 (cosine-annealed), batch 128, label smoothing 0.1, fp32. Best validation accuracy 96.15% at epoch 30. Augmentation: ±100 ms time-shift + background-noise mixing (p=0.8, vol U(0,0.1)).
• Features: log-mel, 64 mels, 25 ms window / 10 ms hop, normalized by train-set global mean/std (stored inside the checkpoint).

Evaluation — official Speech Commands v2 test set (4,890 clips)

<!-- METRICS_TABLE: produced by evaluate.py, never hand-written -->

Per-class F1 ranges from 0.921 ("unknown", the hardest class) to 0.998 ("silence"); all 10 keywords score ≥0.94. Full per-class table and the confusion matrix: see metrics.json and confusion_matrix.png in this repo. Evaluating this checkpoint on the Colab T4 and on an Apple M2 produced bit-for-bit identical metrics (reproducible across devices).

Usage

import torch
from huggingface_hub import hf_hub_download

# model.py + common.py from https://github.com/priyadeepjaiswal9c/tiny-kws
from model import DSCNN
from common import LogMel, normalize

ckpt = torch.load(hf_hub_download("priyadeepjaiswal9c/tiny-kws", "best.pt"),
                  map_location="cpu", weights_only=True)
model = DSCNN(**ckpt["model_config"]); model.load_state_dict(ckpt["model_state"]); model.eval()

wav = torch.zeros(16000)          # your 1 s, 16 kHz, mono float32 waveform
feats = normalize(LogMel()(wav), ckpt["stats"])
probs = model(feats).softmax(1)[0]
print(dict(zip(ckpt["labels"], probs.tolist())))

Intended use & limitations

Demo/educational model for isolated 1-second command words in quiet-to-mild noise. Not a streaming/wake-word system (no sliding-window detection), not robust to far-field audio or heavy noise, English only, and trained on crowdsourced speech that skews toward certain accents — expect degraded accuracy outside that distribution.

Live demo: https://huggingface.co/spaces/priyadeepjaiswal9c/tiny-kws · Code: https://github.com/priyadeepjaiswal9c/tiny-kws