File size: 3,226 Bytes
7e30c36 37aae04 7e30c36 37aae04 7e30c36 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 | ---
license: mit
language: en
tags:
- audio-classification
- keyword-spotting
- tinyml
- pytorch
datasets:
- speech_commands
metrics:
- accuracy
- f1
---
# 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 -->
| metric | value |
|---|---|
| accuracy | 96.65% |
| macro-F1 | 96.64% |
| CPU latency (batch=1, 1 thread, Apple M2) | 1.90 ms mean / 2.08 ms p95 |
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
```python
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
|